# AI Overview

Sovrium ships a complete, self-hostable AI layer. Every capability is opt-in and governed by the platform's existing RBAC and field-level permissions — AI never bypasses the security model. The AI layer is **disabled by default**: nothing AI-related runs until you set the `AI_PROVIDER` environment variable.

The design philosophy mirrors the rest of the platform: **operators control infrastructure via environment variables, schema authors declare intent in config.** Which provider answers a call, where embeddings live, and whether the MCP server mounts are operator concerns (`AI_PROVIDER`, `MCP_ENABLED`, …). Which tables an agent may touch and which entities are AI-eligible are schema-author concerns (`agents[]`, `aiAccess`).

## The AI Ecosystem

Eight building blocks compose into the full AI experience.

| Capability          | What it does                                                                                              | Docs                                        |
| ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **Providers**       | Pick the LLM and embedding backend (Anthropic, OpenAI, Mistral, Gemini, local Ollama, OpenAI-compatible). | [AI Providers](/en/docs/ai-providers)       |
| **Eco routing**     | Frugal-by-default provider precedence — prefer a local model, fall back to cloud.                         | [AI Eco Routing](/en/docs/ai-eco-routing)   |
| **AI fields**       | Computed table columns that summarize, categorize, extract, translate, etc. using an LLM.                 | [AI Fields](/en/docs/ai-fields)             |
| **AI chat**         | A conversational interface over your data — query, mutate, and trigger automations in natural language.   | [AI Chat](/en/docs/ai-chat)                 |
| **AI agents**       | Autonomous virtual users with scoped tools, approval gates, schedules, and operational limits.            | [AI Agents](/en/docs/ai-agents)             |
| **RAG knowledge**   | Ground answers in your tables and documents via vector embeddings and semantic search.                    | [AI RAG](/en/docs/ai-rag)                   |
| **Agent memory**    | Conversation history, RAG-backed knowledge, and persistent learned facts per agent.                       | [AI Memory](/en/docs/ai-memory)             |
| **MCP integration** | Expose Sovrium as an MCP server, and let agents consume external MCP tools.                               | [MCP Integration](/en/docs/mcp-integration) |

:::callout
**AI fields are documented under Tables.** The seven computed field types (`ai-summary`, `ai-categorize`, `ai-extract`, `ai-sentiment`, `ai-tag`, `ai-translate`, `ai-generate`) live on table records and are covered in [AI Fields](/en/docs/ai-fields). This section covers the conversational, agentic, and interoperability layers.
:::

## Configuration Philosophy

AI behaves like the database (`DATABASE_URL`), storage (`STORAGE_PROVIDER`), and auth (`AUTH_SECRET`) layers: **infrastructure is env-var config, intent is schema.**

| Concern                                   | Controlled by | Where                                            |
| ----------------------------------------- | ------------- | ------------------------------------------------ |
| Which provider/model/key to use           | Operator      | `AI_PROVIDER`, `AI_MODEL`, `AI_API_KEY` env vars |
| Provider routing precedence (eco)         | Operator      | `ECO_AI_PROVIDER_PRECEDENCE` env var             |
| Whether the MCP server mounts             | Operator      | `MCP_ENABLED`, `MCP_TRANSPORT`, … env vars       |
| Which entities are AI-eligible            | Schema author | `aiAccess` on tables / automations / actions     |
| Agent identity, tools, approval, schedule | Schema author | `app.agents[]`                                   |
| AI computed columns                       | Schema author | `type: ai-*` fields on a table                   |

The single master switch is `AI_PROVIDER`. When unset (or blanked), the entire AI layer is silently disabled — AI fields skip computation, the chat endpoint returns a disabled response, agents do not run, and RAG/embedding infrastructure is not provisioned. No errors are thrown at boot; AI simply stays dormant until configured.

```bash
# Minimal enablement: a local Ollama model (no API key, no cloud).
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# A cloud provider.
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-5
```

## How the Pieces Fit Together

```
                         AI_PROVIDER (master switch)
                                  │
        ┌─────────────────┬───────┴────────┬──────────────────┐
        ▼                 ▼                ▼                  ▼
   AI Fields          AI Chat          AI Agents          MCP Server
 (computed cols)   (conversation)   (virtual users)    (external clients)
        │                 │                │                  │
        │                 └──── tools ─────┤                  │
        │                                  │                  │
        ▼                                  ▼                  ▼
                          RBAC + field-level permissions (always enforced)
                                  │
                                  ▼
                    RAG knowledge + agent memory (pgvector / SQLite BLOB)
```

Every AI surface — fields, chat, agents, MCP — funnels through the same authorization layer. An agent inherits its role's permissions; a chat user can only see records their session permits; an MCP client is bounded by its token's role. There is no privileged AI bypass.

## Prerequisites

| Requirement       | Why                                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `AI_PROVIDER` set | Master switch. Without it the whole AI layer is dormant.                                                         |
| `app.auth` (most) | Agents are stored as auth users; chat and MCP RBAC require roles. AI fields work without auth.                   |
| pgvector / SQLite | RAG embeddings need PostgreSQL + pgvector **or** SQLite (Float32 BLOB + app-side cosine). No external vector DB. |

## Related Pages

- [AI Providers](/en/docs/ai-providers) — choose and configure the LLM backend.
- [AI Eco Routing](/en/docs/ai-eco-routing) — local-first provider precedence.
- [AI Fields](/en/docs/ai-fields) — computed columns powered by an LLM.
- [AI Chat](/en/docs/ai-chat) — conversational data interaction.
- [AI Agents](/en/docs/ai-agents) — autonomous virtual users.
- [AI RAG](/en/docs/ai-rag) — retrieval-augmented knowledge.
- [AI Memory](/en/docs/ai-memory) — agent conversation, knowledge, and facts.
- [MCP Integration](/en/docs/mcp-integration) — Sovrium as MCP server and client.
- [Environment Variables](/en/docs/env-vars) — full env-var reference.