Skip to main content
View as Markdown

AI Chat

AI Chat is a conversational interface over your application data. Users ask questions and issue commands in natural language; the platform translates them into permitted queries, mutations, and automation triggers, then returns a structured reply. It is available both as a REST endpoint (POST /api/ai/chat) and as an embeddable page component (type: ai-chat).

Chat is native once AI_PROVIDER is configured — the platform auto-detects every table and field, so no per-table YAML is needed for query support. All actions taken through chat are governed by the requesting user's RBAC and field-level permissions and are written to the activity log for full auditability.

What Chat Can and Cannot Do

Chat can Chat cannot
Query records across tables via natural language Modify table schemas (add/remove fields, change types)
Create, update, and delete records (destructive ops confirmed) Create or modify automations
Trigger manual-trigger automations the user may run Access records outside the user's RBAC permissions
Maintain conversation context within a session Bypass field-level permissions

Architecture

User Message
    │
    ▼
POST /api/ai/chat ──▶ Resolve Agent (or default AI) ──▶ Inject Context
    │                                                        │
    │   ┌────────────────────────────────────────────────────┘
    ▼   ▼
AI Provider ──▶ Tool Calls (query, mutate, trigger) ──▶ RBAC check ──▶ Activity Log
    │
    ▼
Structured Response (reply text + actions taken)

Chat resolves an agent (when one is named) or falls back to the default AI provider. The model interacts with data exclusively through tool calls — structured operations Sovrium executes after an RBAC check — rather than fabricating data in free text.

Using Chat as a Page Component

The ai-chat component embeds a chat panel into any page.

pages:
  - name: dashboard
    path: /dashboard
    components:
      - type: ai-chat
        agent: support-agent # optional — falls back to default AI provider
        placeholder: Ask about your tickets...
        chatHeight: 600
        showHistory: true
        allowAttachments: false
Property Description
agent Agent name from app.agents[]. Omit to use the default AI provider.
placeholder Placeholder text for the chat input field.
chatHeight Chat container height in pixels (must be > 0).
showHistory Whether to show previous conversation history on load.
allowAttachments Whether to allow file attachments in the chat.

Using the REST API

POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "message": "How many open tickets are there?",
  "context": { "table": "tickets" },
  "sessionId": "sess_abc123"
}
{
  "reply": "There are 42 open tickets — 5 critical, 12 high, 18 medium, 7 low.",
  "actions": [
    {
      "type": "query",
      "table": "tickets",
      "description": "Counted tickets where status = 'open', grouped by priority"
    }
  ],
  "sessionId": "sess_abc123"
}

Record Queries

When AI_PROVIDER is set, the chat API natively translates natural-language questions into SQL/API queries against the user's permitted tables, executes them, and formats the result into the conversation. No configuration is required — the platform introspects the schema automatically. Queries never reach tables or fields the requesting role cannot read.

Record Mutations

Chat can create, update, and delete records on the user's behalf. Mutations honor field-level permissions (a role that cannot write a field cannot set it through chat), and destructive operations require confirmation before they execute. Every mutation is recorded in the activity log alongside the user who initiated it.

Triggering Automations

Chat can invoke manual-trigger automations the user is permitted to run, then report the result back in the conversation. Chat cannot run automations of other trigger types, nor create or edit automation definitions.

Tool Calling

Chat is built on function/tool calling. Sovrium presents the model a set of tool definitions (query, mutate, trigger); the model returns a tool_call; Sovrium executes it after an RBAC check and feeds the result back to the model, which then composes the final reply. Structured tool calling — rather than free-text data generation — is what keeps chat grounded and auditable.

User Message → AI Provider (with tool definitions)
                    │
                    ▼
              AI returns tool_call
                    │
                    ▼
         Sovrium executes tool (RBAC checked)
                    │
                    ▼
         Tool result sent back to AI
                    │
                    ▼
              AI returns final text response

Streaming Responses

Chat supports Server-Sent Events (SSE) streaming so users see progressive text generation instead of waiting for the full response.

Behavior Detail
Chunk delivery Partial message content arrives as SSE chunks, forwarded in real time as the provider emits them.
Completion marker The final SSE event carries a [DONE] marker; the complete message is assembled from all chunks.
Persistence Streamed messages are persisted to conversation history once complete.
Permissions Streaming enforces the same RBAC as non-streaming chat.
Time-to-first-chunk A 504 is returned when the provider sends no first chunk before AI_CHAT_STREAM_TIMEOUT.
Connection drop Handled gracefully — a partial response is discarded if the connection drops before completion.

Rate Limiting

Per-user rate limits protect the AI provider from being overwhelmed and cap cost. Limits are configured via environment variables, not the app schema.

Variable Description Default
AI_CHAT_RATE_LIMIT Messages allowed per window, per user. 60
AI_CHAT_RATE_WINDOW Rate-limit window length. 1 minute
AI_CHAT_STREAM_TIMEOUT Deadline for time-to-first-chunk on streaming requests. —

A rate-limited request returns 429 with a Retry-After header and remaining-quota information. Each user has an independent counter, and the window resets after it expires. Agent API calls respect the same limits as user chat.

Error Handling

When the AI provider fails, chat returns a user-friendly error rather than leaking raw provider internals. When AI_PROVIDER is unset, the chat endpoint responds with a disabled state instead of erroring — consistent with the platform's "AI dormant until configured" contract.