# 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.

```yaml
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

```http
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"
}
```

```json
{
  "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.

## Related Pages

- [AI Overview](/en/docs/ai-overview) — the full AI ecosystem.
- [AI Providers](/en/docs/ai-providers) — configure the LLM backend.
- [AI Agents](/en/docs/ai-agents) — agents that power named chat panels.
- [AI Memory](/en/docs/ai-memory) — conversation history and learned facts.
- [Records Overview](/en/docs/records-overview) — the record CRUD model chat operates on.
- [Roles & RBAC](/en/docs/auth-roles-rbac) — the permissions chat always enforces.