npm package: @sf-ai/sdk
Description: Type-safe SDK for the San Francisco database with GraphQL codegen
Author: City of San Francisco
Latest version: 0.2.1

<p align="center" width="100%">
  <img height="250" src="https://github.com/city-of-san-francisco/.github/blob/main/assets/logo.svg" />
</p>

<p align="center" width="100%">
   <a href="https://github.com/city-of-san-francisco/license"><img height="20" src="https://img.shields.io/badge/license-SF-blue.svg"/></a>
   <a href="https://github.com/city-of-san-francisco/sf-rag-utils/actions/workflows/ci.yml"><img height="20" src="https://github.com/city-of-san-francisco/sf-rag-utils/actions/workflows/ci.yml/badge.svg" /></a>
   <a href="https://www.npmjs.com/package/@sf-ai/sdk"><img height="20" src="https://img.shields.io/github/package-json/v/city-of-san-francisco/sf-rag-utils?filename=packages%2Fsf-sdk%2Fpackage.json"/></a>
</p>

<p align="center" width="100%">
  <a href="https://github.com/city-of-san-francisco/sf-rag-utils">A pgpm workspace for building agentic, database-driven AI applications for the City of San Francisco.</a>
</p>

# @sf-ai/sdk

Type-safe SDK for the San Francisco database with GraphQL codegen.

## Overview

This package provides a type-safe SDK generated from the San Francisco RAG database schema using `@constructive-io/graphql-codegen`. It generates both React Query hooks and a Prisma-like ORM client from the PGPM modules.

## Installation

```bash
pnpm add @sf-ai/sdk
```

## Usage

### ORM Client

```typescript
import { createClient } from '@sf-ai/sdk';

const db = createClient({
  endpoint: process.env.GRAPHQL_ENDPOINT,
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
  },
});

// Query documents
const documents = await db.document.findMany({
  select: { id: true, title: true, content: true },
  first: 10,
}).execute().unwrap();

// Query chunks with embeddings
const chunks = await db.chunk.findMany({
  select: {
    id: true,
    content: true,
    document: { select: { id: true, title: true } },
  },
}).execute().unwrap();
```

### React Query Hooks

```typescript
import { useDocumentsQuery, useChunksQuery } from '@sf-ai/sdk';

function DocumentList() {
  const { data, isLoading } = useDocumentsQuery({ first: 10 });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {data?.documents.nodes.map((doc) => (
        <li key={doc.id}>{doc.title}</li>
      ))}
    </ul>
  );
}
```

## Regenerating the SDK

The SDK is generated from the PGPM modules in this repository. To regenerate:

### Locally

Requires a running PostgreSQL database with the schema deployed:

```bash
cd packages/sf-sdk
pnpm run codegen:all
```

### Via GitHub Actions

Use the "Generate SDK" workflow which:

1. Spins up an ephemeral PostgreSQL database
2. Deploys the PGPM modules
3. Generates the SDK types
4. Optionally commits the changes

Run the workflow from the Actions tab with the "commit_changes" option enabled to automatically commit regenerated types.

## Configuration

The codegen configuration is in `graphql-codegen.config.ts`:

```typescript
import { defineConfig } from '@constructive-io/graphql-codegen';

export default defineConfig({
  targets: {
    default: {
      db: {
        pgpm: {
          modulePath: '../rag-core',
        },
        schemas: ['rag'],
      },
      output: './src/generated',
      // ... other options
    },
  },
});
```

## Schema

The SDK is generated from the `rag` schema which includes:

- `embedding_model` - Embedding model configurations
- `collection` - Document collections
- `collection_model` - Collection-model associations
- `document` - Full documents
- `chunk` - Document chunks for RAG
- `embedding` - Vector embeddings

## License

[SF License](https://github.com/city-of-san-francisco/license)