Skip to main content
View as Markdown

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
Eco routing Frugal-by-default provider precedence — prefer a local model, fall back to cloud. AI Eco Routing
AI fields Computed table columns that summarize, categorize, extract, translate, etc. using an LLM. AI Fields
AI chat A conversational interface over your data — query, mutate, and trigger automations in natural language. AI Chat
AI agents Autonomous virtual users with scoped tools, approval gates, schedules, and operational limits. AI Agents
RAG knowledge Ground answers in your tables and documents via vector embeddings and semantic search. AI RAG
Agent memory Conversation history, RAG-backed knowledge, and persistent learned facts per agent. AI Memory
MCP integration Expose Sovrium as an MCP server, and let agents consume external MCP tools. MCP Integration

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.

# Minimal enablement: a local Ollama model (no API key, no cloud).
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
# 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.