Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(ai): Add Assistant code guide (#51785)

Raúl Barroso78348a767a89
diff --git a/apps/studio/AGENTS.md b/apps/studio/AGENTS.md
index 19fb5459f2d..8e57c792e99 100644
--- a/apps/studio/AGENTS.md
+++ b/apps/studio/AGENTS.md
@@ -32,6 +32,7 @@ Studio is migrating from the Next.js pages router (`pages/**`) to TanStack Start
## Orientation
+- **Supabase Assistant** — before working on Assistant chat, prompts, tools, or access handling, read the [Assistant code guide](lib/ai/README.md) for entry points, request flow, and validation references. Update the guide when moving entry points or changing the request/tool lifecycle.
- **Data layer** — all platform API calls go through `data/fetchers.ts` (`openapi-fetch`, typed by the generated `api-types` package) with `handleError`; never raw `fetch`. One folder per resource in `data/`, most with a `keys.ts` query-key factory.
- **State** — valtio for global state (`state/`), nuqs for URL state, react-hook-form + zod for forms.
- **Platform vs self-hosted** — `IS_PLATFORM` gates platform-only behavior; `withAuth` is a no-op when self-hosted.
diff --git a/apps/studio/README.md b/apps/studio/README.md
index f6e3a4131a7..c65b0490bcb 100644
--- a/apps/studio/README.md
+++ b/apps/studio/README.md
@@ -23,6 +23,8 @@ Project settings are managed outside of the Dashboard. If you use docker compose
## How to contribute?
+For Assistant work, start with the [Supabase Assistant code guide](lib/ai/README.md) for the architecture, file map, tools, and validation workflow.
+
- Branch from `master` and name your branches with the following structure
- `{type}/{branch_name}`
- Type: `chore | fix | feature`
diff --git a/apps/studio/lib/ai/README.md b/apps/studio/lib/ai/README.md
new file mode 100644
index 00000000000..c99154b22d0
--- /dev/null
+++ b/apps/studio/lib/ai/README.md
@@ -0,0 +1,128 @@
+# Supabase Assistant code guide
+
+Start here when working on the Assistant in Studio. This guide maps the implementation for contributors and coding agents. Follow [Studio's agent instructions](../../AGENTS.md) and load the skills that apply to your change.
+
+## Request flow
+
+```mermaid
+flowchart TD
+ UI[AssistantChat] --> State[ai-assistant-state: chat transport]
+ State --> API[POST /api/ai/sql/generate-v4]
+ API --> Access[Resolve organization access and model]
+ Access --> Tools[getTools]
+ Tools --> Response[generateAssistantResponse]
+ Response --> Stream[Stream messages and tool calls to the UI]
+ Stream --> Parts[Message.Parts: render text and tool cards]
+ Parts --> Approval[User approves a tool when required]
+ Approval --> State
+```
+
+The [sidebar provider](../../components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider.tsx) mounts [AIAssistant](../../components/ui/AIAssistantPanel/AIAssistant.tsx). [AssistantChat](../../components/ui/AIAssistantPanel/AssistantChat.tsx) manages the active conversation UI and supplies project and organization context to [ai-assistant-state](../../state/ai-assistant-state.tsx).
+
+The state module owns the AI SDK chat instances, request transport, chat persistence, and approval continuation. Its transport sends messages to [generate-v4](../../pages/api/ai/sql/generate-v4.ts), which validates and authenticates the request, resolves access and the model, builds tools, and streams the response. The [TanStack route](../../routes/api/ai/sql/generate-v4.ts) adapts this same handler. Keep both runtimes in mind; see the [migration guide](../../TANSTACK_MIGRATION.md).
+
+[generateAssistantResponse](./generate-assistant-response.ts) combines prompts, context, prepared conversation history, and tools for the model. [Message.Parts](../../components/ui/AIAssistantPanel/Message.Parts.tsx) dispatches streamed message parts to their UI renderers. Approval responses travel back through the chat transport so the server can continue tool execution.
+
+## Rules to keep
+
+- **Enforce access in code.** Resolve organization/project access on the server and keep the restrictive fallback for an unverified pairing. Prompts and UI visibility are not authorization checks.
+- **Keep execution approval separate from data sharing.** Full data opt-in does not approve AI-generated SQL execution. Promote untrusted SQL only after explicit user approval.
+- **Protect results on every model path.** Apply output filtering to both live tool results and replayed history. Raising opt-in must not expose SQL results collected under a lower level.
+- **Keep the tool allowlist.** Register tools explicitly and declare their minimum opt-in level. Remote MCP tools must pass the filter; the remote server's read-only setting does not replace it.
+- **Keep request context out of the shared system prompt.** Put project, chat, clock, and logs context in `assistant-context.ts` to preserve provider caching.
+- **Keep tool contracts safe to import in the browser.** Shared contracts contain schemas and pure output transformations; database calls and other server execution belong in the server implementation.
+- **Preserve both runtimes.** Keep the TanStack adapter and Next.js handler aligned. The chat route currently delegates to the shared handler; do not remove that handler while the adapter uses it.
+
+## Where to make changes
+
+### Chat and rendering
+
+| Change | Start here |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Panel layout, chat selection, and header | [AIAssistant.tsx](../../components/ui/AIAssistantPanel/AIAssistant.tsx), [AIAssistantHeader.tsx](../../components/ui/AIAssistantPanel/AIAssistantHeader.tsx) |
+| Composer, attachments, and sending messages | [AssistantChat.tsx](../../components/ui/AIAssistantPanel/AssistantChat.tsx), [AssistantChatForm.tsx](../../components/ui/AIAssistantPanel/AssistantChatForm.tsx) |
+| Chat state, persistence, transport, and selected model | [ai-assistant-state.tsx](../../state/ai-assistant-state.tsx) |
+| Message rendering and tool-specific cards | [Message.Parts.tsx](../../components/ui/AIAssistantPanel/Message.Parts.tsx), [Message.Parts.utils.ts](../../components/ui/AIAssistantPanel/Message.Parts.utils.ts) |
+| SQL results and charts | [AssistantQueryCell.tsx](../../components/ui/AIAssistantPanel/AssistantQueryCell.tsx), [AssistantQueryCell.utils.ts](../../components/ui/AIAssistantPanel/AssistantQueryCell.utils.ts) |
+| Approval UI | [Confirm.tsx](../../components/ui/AIAssistantPanel/Confirm.tsx), [Confirm.utils.ts](../../components/ui/AIAssistantPanel/Confirm.utils.ts) |
+
+### Model requests and context
+
+| Change | Start here |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Chat endpoint and request validation | [generate-v4.ts](../../pages/api/ai/sql/generate-v4.ts) |
+| Model streaming and response orchestration | [generate-assistant-response.ts](./generate-assistant-response.ts) |
+| System instructions and topic knowledge | [prompts.ts](./prompts.ts); `load_knowledge` in [studio-tools.ts](./tools/studio-tools.ts) |
+| Project, chat, clock, and logs context | [assistant-context.ts](./assistant-context.ts), [assistant-message-metadata.ts](./assistant-message-metadata.ts) |
+| History preparation and output sanitization | [generate-assistant-response.utils.ts](./generate-assistant-response.utils.ts), [tool-sanitizer.ts](./tools/tool-sanitizer.ts) |
+| Model catalog, defaults, and provider configuration | [model.utils.ts](./model.utils.ts), [model.ts](./model.ts), [bedrock.ts](./bedrock.ts); entitlement and throttling decisions in [generate-v4.ts](../../pages/api/ai/sql/generate-v4.ts) |
+| Tracing and feedback | [braintrust-logger.ts](./braintrust-logger.ts), [feedback API](../../pages/api/ai/feedback/), [rate-message-mutation.ts](../../data/ai/rate-message-mutation.ts) |
+
+Keep per-request context in `assistant-context.ts`. The shared system prompt is deliberately static for provider caching.
+
+### Tools
+
+| Change | Start here |
+| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool assembly and platform/self-hosted selection | [tools/index.ts](./tools/index.ts) |
+| Allowlist, minimum opt-in levels, and blocked-tool responses | [tool-filter.ts](./tool-filter.ts) |
+| SQL execution, Edge Function deployment, chat renaming, knowledge, and opt-in requests | [studio-tools.ts](./tools/studio-tools.ts) |
+| Remote MCP connection and tool selection | [supabase-mcp.ts](./supabase-mcp.ts), [mcp-tools.ts](./tools/mcp-tools.ts) |
+| Schema and policy tools | [schema-tools.ts](./tools/schema-tools.ts) |
+| Reports, notebooks, incidents, and support | [report-tools.ts](./tools/report-tools.ts), [notebook-tools.ts](./tools/notebook-tools.ts), [incident-tools.ts](./tools/incident-tools.ts), [support-tools.ts](./tools/support-tools.ts) |
+| Self-hosted tools | [fallback-tools.ts](./tools/fallback-tools.ts) |
+| Shared tool contracts | [types.ts](./tools/types.ts), [registry.ts](./tools/registry.ts), [tool-from-contract.ts](./tools/tool-from-contract.ts) |
+
+Some tools use shared contracts; others declare their schemas and output handling directly. [update-notebook.ts](./tools/update-notebook.ts) and [update-notebook.server.ts](./tools/update-notebook.server.ts) show the contract/server split. Contracts define input/output schemas, minimum opt-in level, approval requirements, and what the model may see. The registry also applies contract output handling when replaying history.
+
+For a new or changed tool:
+
+1. Implement it in the appropriate tool module and include it in `getTools`.
+2. Update the allowlist/validation in `tool-filter.ts`. Declare minimum access in its contract or the existing category map, as applicable.
+3. Decide whether execution needs user approval and what output may reach the model, including on history replay. Read the [SQL safety skill](../../../../.agents/skills/safe-sql-execution/SKILL.md) before changing SQL execution.
+4. Update `Message.Parts.tsx` and its helpers if the tool needs a UI renderer.
+5. Update relevant tests, mock tools, and evaluation cases. See [local development and validation](#local-development-and-validation).
+
+## Access and data sharing
+
+These checks have different responsibilities:
+
+| Responsibility | Implementation |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Resolve the saved organization opt-in tags for the UI | [useOrgOptedIntoAi.ts](../../hooks/misc/useOrgOptedIntoAi.ts) |
+| Resolve server-side access for an organization/project pair | [ai-details.ts](./ai-details.ts) |
+| Check permission to change organization settings | [useCheckPermissions.ts](../../hooks/misc/useCheckPermissions.ts), used by [OptInRequest.tsx](../../components/ui/AIAssistantPanel/OptInRequest.tsx) and [AIOptInModal.tsx](../../components/ui/AIAssistantPanel/AIOptInModal.tsx) |
+| Save organization opt-in settings | [useAIOptInForm.ts](../../hooks/forms/useAIOptInForm.ts), [DataPrivacyForm.tsx](../../components/interfaces/Organization/GeneralSettings/DataPrivacyForm.tsx) |
+| Gate tool availability by opt-in level | [tool-filter.ts](./tool-filter.ts) |
+| Approve SQL execution and call the database | `execute_sql` in [studio-tools.ts](./tools/studio-tools.ts), using [execute-sql-mutation.ts](../../data/sql/execute-sql-mutation.ts) |
+| Control which SQL results reach the model | `toModelOutput` in [studio-tools.ts](./tools/studio-tools.ts) and history sanitization in [tool-sanitizer.ts](./tools/tool-sanitizer.ts) |
+
+The opt-in levels are `disabled`, `schema`, `schema_and_log`, and `schema_and_log_and_data`. `execute_sql` is available at every level and requires user approval; sharing its result rows with the model requires `schema_and_log_and_data`. History sanitization also considers the level stamped on the original SQL output. Permission to change opt-in settings, user approval to run SQL, and the database's authorization checks are separate from result sharing.
+
+The model can call `update_opt_in_level` with `requiredLevel` to request higher access, or without `requiredLevel` when the user asks to review or change the setting. Every call requires approval through the opt-in request card, even when the organization already has the requested level. If the requested level is already satisfied, the input transform removes `requiredLevel` and treats the call as a review request; `levelWhenAsked` records the organization's level when the call was made.
+
+On platform, the endpoint resolves organization access and `getTools` includes platform tools when an access token is available. It also registers the opt-in request tool. Self-hosted requests use the `schema` level and fallback tools instead of the platform tool set. Check [getTools](./tools/index.ts) and [generate-v4](../../pages/api/ai/sql/generate-v4.ts) when changing either environment.
+
+## Related AI features
+
+The chat Assistant shares code with other Studio AI features, but those have separate endpoints:
+
+- [pages/api/ai/sql/](../../pages/api/ai/sql/) contains policy generation, SQL title, filter, and cron helpers alongside the chat endpoint.
+- [pages/api/ai/code/complete.ts](../../pages/api/ai/code/complete.ts) handles code completions.
+- [pages/api/ai/onboarding/design.ts](../../pages/api/ai/onboarding/design.ts) handles onboarding design.
+- [data/ai/](../../data/ai/) contains client queries and mutations for AI helpers and feedback. The chat transport itself lives in `ai-assistant-state.tsx`.
+- [routes/api/ai/](../../routes/api/ai/) contains the corresponding TanStack API adapters.
+
+## Local development and validation
+
+Use the [Studio setup instructions](../../README.md#developer-quickstart) for the application and backend configuration. From the repository root, `pnpm dev:studio` starts Studio on port 8082 by default. The chat endpoint currently selects the OpenAI provider, which requires a server-side `OPENAI_API_KEY`; see [model.ts](./model.ts). A self-hosted session exercises the fallback tool set, so use a platform development environment when working on platform-only tools or organization settings.
+
+Tests are colocated with the implementation under `lib/ai/`, `components/ui/AIAssistantPanel/`, and `state/`. For example, from `apps/studio`:
+
+```bash
+pnpm exec vitest run lib/ai/tool-filter.test.ts lib/ai/tools/studio-tools.test.ts
+```
+
+Use the [Assistant evaluation guide](../../evals/README.md) for behavioral datasets, local evaluation commands, CI labels, and scoring. [dataset.ts](../../evals/dataset.ts) contains scenarios and [mock-tools.ts](./tools/mock-tools.ts) supplies tool behavior for evaluations. The browser test is [assistant.spec.ts](../../../../e2e/studio/features/assistant.spec.ts); read the [E2E setup guide](../../../../e2e/studio/README.md) before running it.
+
+Update this map when moving entry points or changing the request/tool lifecycle.