AI features for editors

In addition to the chat agent, every database has two producer-facing AI features available to editors. They live under the database’s AI tab in the console and as /api/namespaces/:slug/databases/:dbSlug/ai/* on the REST surface.

NL → SQL playground

POST /ai/sql

Body:

{
  "question": "How many orders shipped last week?",
  "execute": true,
  "allowedTables": ["orders"]
}

The endpoint introspects the schema (with optional allowedTables filter), prompts the model, and returns the generated SQL plus an explanation. With execute: true the SQL is run after a read-only check; results come back as columns / rows. Without execute, nothing runs — the UI shows the SQL for review first.

assertReadOnly rejects any statement that contains INSERT/UPDATE/DELETE/CREATE/DROP/ALTER/REPLACE/PRAGMA keywords outside of strings, so the playground can never mutate data.

Auto-docs

POST /ai/describe

Body (all fields optional):

{ "tables": ["orders", "customers"] }

For each listed table (or every table when omitted), the endpoint:

1. Pulls column metadata via PRAGMA table_info.
2. Samples up to 5 rows from the table.
3. Asks the model for a one-line table description and a one-line description for each column.
4. Persists results to database_doc / table_doc / column_doc.

The response includes the new docs bundle and a failures list for tables that errored out. Docs are editable by hand:

• GET /ai/docs — read current docs for the database.

• PUT /ai/docs — overwrite descriptions:

  {
    "databaseDescription": "Orders ledger for ACME",
    "tables": [
      {
        "table": "orders",
        "description": "One row per shipped order",
        "columns": [
          { "column": "status", "description": "fulfillment state" }
        ]
      }
    ]
  }

Docs flow into:

• The agent’s read_docs tool, used as grounding for ask.
• The OpenAPI / .well-known/endpoints.json description fields for endpoints, so external agents see the same context.