ai-commands

LLM-backed commands used by Studio and the docs site. Each command is a self-contained function that can be unit-tested in isolation.

Purpose

Centralizes prompt templates and command logic for AI features (RLS policy generation, SQL generation, embeddings/search, error explanation, etc.) so they can be evolved and regression-tested without touching app code.

Directory layout

packages/ai-commands/
├── index.ts        # Server-only entry
├── edge.ts         # Edge-runtime entry (streaming functions)
├── src/
│   ├── docs.ts     # Embedding-based docs search command
│   ├── errors.ts
│   ├── tokenizer.ts
│   ├── types.ts
│   └── sql/        # SQL-related commands (RLS, schema, etc.)
├── test/
├── package.json
├── vitest.config.ts
└── vitest.setup.ts

How to import

There are two entry points:

// Server (Node) usage
import 'ai-commands'; /* ... */
// Edge runtime — streaming versions only
import { chatRlsPolicy } from 'ai-commands/edge';

The streaming functions only run on Edge runtimes (Vercel Edge / Deno Edge Runtime), per packages/ai-commands/README.md.

How it works

Commands wrap calls to OpenAI or Amazon Bedrock with prompt construction and post-processing. Studio's data layer calls them through the AI SDK (ai, @ai-sdk/openai, @ai-sdk/amazon-bedrock, @ai-sdk/react). Streamed responses go via the edge entry; non-streaming responses go via index.ts.

tokenizer.ts provides token counting against the relevant model's tokenizer for budgeting and truncation.

Tests

pnpm --filter ai-commands test

CI: ai-tests.yml.

Evals

Studio runs Braintrust evals against these commands from apps/studio/evals/. See how-to-contribute/testing.md for commands.

Integration points

• Consumed by apps/studio (Assistant, SQL Editor inline AI, RLS policy generator, advisors).
• Consumed by apps/docs (search and "ask the docs" features).

Entry points for modification

• Tweak a prompt → edit the relevant file in src/. Run the corresponding test in test/ and re-run Braintrust evals if behavior is observable.
• Add a new command → create src/<area>/<command>.ts with a unit test in test/. Export from both index.ts (and edge.ts if streaming).
• Migrate a command to a new model provider → add the provider to the imports and parameterize the model selection.