AI Configuration

The data platform integrates with AI providers for these features:

Schema generation — upload a file to POST /api/v1/pipeline/generate and receive a complete pipeline configuration with inferred field names and types
Data quality rules — describe validation logic in plain English using aiRule instead of writing code
Transformations — describe data transformations in plain English using aiTransformation
Data profiling — upload a file and get summary statistics, quality issues, and suggested validation rules
Header validation — AI-powered fuzzy matching for CSV/delimited file headers against the pipeline schema
Error explanation — AI analyzes job failures and explains the root cause in plain English
Vector search & embeddings — required when pushing data to vector destinations (Qdrant, Weaviate, Milvus, Chroma, pgvector) or running semantic search

Independent Secrets

AI configuration is split into independent, self-describing Vault secrets, each pointing at its own endpoint/model/key. Each is a separate slot in application.yaml:

ai:
  enabled: "true"
  aiPrimary:
    secretName: "oss/ai-primary"
  codegen:
    secretName: "oss/codegen"
  embedding:
    secretName: "oss/embedding"
  webSearch:
    secretName: "oss/web-search"

Slot	Purpose	Used by
`aiPrimary`	General AI tasks	Schema generation, error explanation, brainstorm chat, profiling, header validation, CRON generation, AI Q&A
`codegen`	Code-generation tasks	Tap scripts, `aiRule`, `aiTransformation`, JSON Schema / XSD generation, natural-language → SQL
`embedding`	Vector embeddings	Vector destinations (Qdrant, Weaviate, Milvus, Chroma, pgvector), semantic search
`webSearch`	Live web lookup (optional)	Tap script generation and tap diagnosis when the model needs current API documentation

Each Vault secret carries its full configuration inline:

Field	Required	Notes
`provider`	Yes	`anthropic`, `openai`, `azure`, or `ollama`
`endpoint`	Yes	API endpoint URL. Azure has no default — use your resource URL, e.g. `https://YOUR-RESOURCE.openai.azure.com/openai/v1/chat/completions`
`model`	Yes	Model identifier. For Azure this is your deployment name
`apiKey`	No (not used by ollama)	Inline provider API key. The shared API key store is checked first and takes precedence when set
`version`	Optional	API version (Anthropic uses `2023-06-01`)

The resolver reads each secret at the configured path and uses whatever it finds inside — there is no path derivation from a YAML provider field. This means the three slots can independently use different providers (e.g. Anthropic for aiPrimary, Ollama for codegen, OpenAI for embedding). All three slots support Ollama — you can run the entire platform on local models with no API keys. The Configuration UI offers Ollama as a provider choice for every section, with a free-text model input since Ollama supports hundreds of community models.

Shared API Key Store

Provider API keys live in a shared per-provider secret, {env}/ai-keys (oss/ai-keys in single-tenant deployments), with one field per provider: anthropicApiKey, openaiApiKey, and azureApiKey. When a slot needs a key, resolution order is:

Shared key store ({env}/ai-keys) — checked first; takes precedence over any inline key
Inline apiKey on the slot secret — legacy deployments that stored the key on the slot itself
ANTHROPIC_API_KEY / OPENAI_API_KEY / AZURE_OPENAI_API_KEY container env vars — single-tenant only

Keys are stored once per provider rather than once per slot, so switching a slot between providers never loses the other provider’s key. This is the store behind the Configuration UI’s shared API Keys panel — entering a key there writes it to {env}/ai-keys for all slots to use.

Quick Start with `.env`

On first boot, docker/vault-init.sh seeds all three Vault secrets automatically based on which API key you put in .env (see How Configuration Persists — after the first boot, the Configuration tab is the source of truth). Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or the AZURE_OPENAI_* trio:

# .env
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=

OpenAI path

When OPENAI_API_KEY is set, all three slots are seeded against OpenAI:

Slot	Provider	Endpoint	Model
`oss/ai-primary`	openai	`https://api.openai.com/v1/chat/completions`	`gpt-5.5`
`oss/codegen`	openai	`https://api.openai.com/v1/chat/completions`	`gpt-5.5`
`oss/embedding`	openai	`https://api.openai.com/v1/embeddings`	`text-embedding-3-small`

Azure OpenAI path

Use your Azure OpenAI resource instead of api.openai.com. All three values are required together — Azure endpoints embed your resource name and models are addressed by deployment name, so there are no universal defaults:

# .env
AI_PROVIDER=azure
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://YOUR-RESOURCE.openai.azure.com
AZURE_OPENAI_MODEL=gpt-5-2          # your chat deployment's name

Slot	Provider	Endpoint	Model
`oss/ai-primary`	azure	`{AZURE_OPENAI_ENDPOINT}/openai/v1/chat/completions`	your deployment name
`oss/codegen`	azure	`{AZURE_OPENAI_ENDPOINT}/openai/v1/chat/completions`	`CODEGEN_MODEL` or same deployment
`oss/embedding`	tei	`http://tei:80/v1/embeddings`	`BAAI/bge-m3`

Embeddings default to the bundled service; set EMBEDDING_PROVIDER=azure to use an embedding deployment on your resource instead (see mix-and-match).

Name deployments after their model (e.g. gpt-5-2, o4-mini — the Azure portal’s default). The platform detects model-specific behavior, like omitting sampling parameters that reasoning models reject, from the model name — which for Azure is the deployment name.

Datris targets Azure’s v1 API (/openai/v1/...), which needs no api-version parameter. Legacy deployment-scoped URLs also work — put the full URL including ?api-version=... in the section’s Endpoint field in the Configuration UI.

Anthropic path (with bundled embedding service)

When ANTHROPIC_API_KEY is set, aiPrimary and codegen use Claude. Anthropic has no embeddings API, so embedding falls back to a bundled embedding service running bge-m3 (a strong open-source 1024-dimension embedding model). No OpenAI key required, vector destinations work out of the box.

Slot	Provider	Endpoint	Model
`oss/ai-primary`	anthropic	`https://api.anthropic.com/v1/messages`	`claude-opus-5`
`oss/codegen`	anthropic	`https://api.anthropic.com/v1/messages`	`claude-opus-5`
`oss/embedding`	tei	`http://tei:80/v1/embeddings`	`BAAI/bge-m3`

The tei service (HuggingFace Text Embeddings Inference) is part of docker-compose.yml. On first start it downloads bge-m3 (~2.2 GB ONNX weights) into a persistent volume; subsequent restarts use the cached model.

Fully local with Ollama

You can run all three slots on a local Ollama instance — no cloud API keys needed. Ollama is opt-in: uncomment the optional ollama service block in docker-compose.yml (and the ollama-data volume), then docker compose up -d ollama and pull the models you want (e.g. docker exec ollama ollama pull qwen3:14b). Alternatively, point at an Ollama instance on your host machine using host.docker.internal:

Slot	Provider	Endpoint	Model (example)
`oss/ai-primary`	ollama	`http://ollama:11434/v1/chat/completions` (bundled) or `http://host.docker.internal:11434/v1/chat/completions` (host)	`qwen3:14b`
`oss/codegen`	ollama	same as above	`qwen2.5-coder:7b-instruct`
`oss/embedding`	ollama	same as above	`bge-m3`

If you only need local chat but want to keep the bundled embedding service (TEI), leave oss/embedding pointed at http://tei:80/v1/embeddings with model="BAAI/bge-m3" and only switch the AI Primary and CodeGen slots to Ollama. The Configuration UI makes this easy — select Ollama (if optional service enabled) as the provider, type your model name, and the endpoint defaults to ollama:11434. No API key is required.

Optional model overrides

Override the seeded models by setting these in .env:

ANTHROPIC_MODEL=claude-opus-5
OPENAI_MODEL=gpt-5.5
CODEGEN_MODEL=claude-opus-5   # or gpt-5.5 if using OpenAI

Mix-and-match: Anthropic chat + OpenAI embeddings

The embedding slot is decoupled from the chat slots — set EMBEDDING_PROVIDER in .env to override what vault-init.sh seeds for oss/embedding, regardless of AI_PROVIDER. This is the recommended path when you want Claude for chat/codegen but don’t want to run the bundled TEI sidecar (for example on a small host where TEI gets OOM-killed).

# .env — Anthropic for chat/codegen, OpenAI for embeddings
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
EMBEDDING_PROVIDER=openai

Valid values for EMBEDDING_PROVIDER:

Value	Endpoint	Default model	Requirements
`openai`	`https://api.openai.com/v1/embeddings`	`text-embedding-3-small` (1536-dim)	`OPENAI_API_KEY` set
`azure`	`{AZURE_OPENAI_ENDPOINT}/openai/v1/embeddings`	`text-embedding-3-small` (deployment name)	`AZURE_OPENAI_API_KEY` set, embedding deployment created on your resource
`tei`	`http://tei:80/v1/embeddings`	`BAAI/bge-m3` (1024-dim)	bundled TEI sidecar running
`ollama`	`http://ollama:11434/v1/embeddings`	`bge-m3` (1024-dim)	optional Ollama service enabled, model pulled

EMBEDDING_MODEL overrides the default model for the chosen provider (e.g. text-embedding-3-large for higher quality at 3072-dim). EMBEDDING_ENDPOINT overrides the URL for the tei or ollama providers — useful when running TEI or Ollama on a separate host and pointing at it from inside Docker. When EMBEDDING_PROVIDER is unset, embedding follows AI_PROVIDER: anthropic seeds the bundled TEI; openai seeds OpenAI embeddings.

Switching providers changes vector dimensions. bge-m3 is 1024-dim, text-embedding-3-small is 1536-dim, text-embedding-3-large is 3072-dim. Existing pgvector / Qdrant / Weaviate / Milvus / Chroma collections built on the previous embedder will fail-fast on the next run with a dimension-mismatch message — drop the destination table or collection and re-ingest.

Hot Reload

When you save AI configuration from the Configuration UI, the server reloads the ai-primary and codegen configs from Vault immediately — no restart required. The next AI call uses the updated provider, model, and endpoint. The embedding config is read from Vault on each request and also requires no restart.

How Configuration Persists

Vault stores its data on a durable Docker volume (vault-data), so secrets, AI provider and model choices, and other Configuration-tab changes survive restarts and rebuilds — docker compose up --build, down && up, and host reboots all keep your settings. .env is a first-boot seed only. The first time Vault initializes, vault-init.sh seeds the secrets from .env. After that, Vault persists on disk and the Configuration tab is the source of truth — editing a value in .env later has no effect. To change AI configuration after the first boot, use the Configuration tab (saves go to Vault and stick). This applies to everything stored in Vault (AI config and connection secrets). Deployment-level settings like JAVA_OPTS and USE_USER_AUTH work the opposite way — they’re plain container env vars read on every boot, so .env edits do take effect on a container recreate. See Changing Settings After Install for the full two-bucket breakdown.

Upgrading from an older release — one-time step. Earlier versions kept Vault data in memory only, so any secret you had set only in the UI — including tap connection secrets — is not carried into the new on-disk store and must be re-entered once after upgrading. Secrets supplied through .env are re-seeded automatically. After this one-time step, everything persists across future rebuilds.

Re-seeding from `.env`

To discard the persisted Vault data and seed fresh from .env again (a clean reset), remove the volume:

docker compose down
docker volume rm datris-platform-oss_vault-data   # the project-name prefix may differ
docker compose up -d

The next boot re-initializes Vault and seeds from .env.

Setting Secrets Manually

To write a secret directly to Vault (note: manual Vault writes do not trigger hot reload — restart the server or re-save from the UI):

docker compose exec -e VAULT_ADDR=http://vault:8200 -e VAULT_TOKEN=root-token vault \
  vault kv put secret/oss/ai-primary \
  provider="anthropic" \
  endpoint="https://api.anthropic.com/v1/messages" \
  model="claude-opus-5" \
  apiKey="sk-ant-..." \
  version="2023-06-01"

Same shape for oss/codegen and oss/embedding. Verify with:

docker compose exec -e VAULT_ADDR=http://vault:8200 -e VAULT_TOKEN=root-token vault \
  vault kv get secret/oss/ai-primary

Embedding Provider Notes

The embedding endpoint must speak the OpenAI embeddings API (POST /v1/embeddings with {model, input} body returning {data: [{embedding: [...]}]}). That contract is implemented by:

OpenAI — https://api.openai.com/v1/embeddings
Azure OpenAI — https://YOUR-RESOURCE.openai.azure.com/openai/v1/embeddings (model = your embedding deployment’s name)
TEI (bundled) — http://tei:80/v1/embeddings (the bundled HuggingFace Text Embeddings Inference sidecar serves BAAI/bge-m3 out of the box)
Ollama — http://ollama:11434/v1/embeddings (only when the optional Ollama service is enabled and bge-m3 has been pulled there)
Ollama (external) — http://host.docker.internal:11434/v1/embeddings (your own Ollama with any embedding model)
Self-hosted vLLM, LM Studio, etc. — anything implementing the same contract

Anthropic has no embeddings API, so provider: "anthropic" is not valid for the embedding slot.

Chat Provider Notes

The aiPrimary and codegen slots support Anthropic, OpenAI, Azure OpenAI, and Ollama. Ollama must expose the OpenAI chat completions API (POST /v1/chat/completions), which it does by default. When running Ollama on your host machine, the endpoint from inside Docker is http://host.docker.internal:11434/v1/chat/completions. Azure OpenAI always speaks chat/completions against your configured endpoint (never the OpenAI Responses API, whose Azure availability varies by region and model). Web search is not available on the Azure provider — pair Azure chat with Anthropic or OpenAI web search if you need it.

Web Search (Optional)

When enabled, four surfaces can consult the live web — official API documentation, deprecation notices, current package names — instead of relying only on the model’s training data. Off by default; flip it on from the Configuration → AI Providers tab. Web search is its own independent service — same model as Embedding. Pick a provider regardless of which provider runs the main AI work. The platform attaches the tool natively to the main AI call when the providers match (one round trip, the model decides when to search) or makes a separate out-of-band search call and injects the results as context (when providers differ — e.g. AI Primary=Anthropic, Web Search=OpenAI). Either way the model sees the current information.

Field	Required	Notes
`enabled`	Yes	`true` or `false`
`provider`	Yes	`anthropic` or `openai` (Ollama has no native web search)
`endpoint`	Yes	Provider endpoint — Anthropic Messages or OpenAI Responses
`model`	Yes	Model that runs the search call
`apiKey`	Yes	Own key, copied from the right-hand panel based on the chosen provider (mirrors Embedding)
`version`	Optional	API version (Anthropic uses `2023-06-01`)
`maxUses`	Optional	Maximum searches per AI call (default 3)

Surface	Web search opt-in
Tap brainstorm (chat)	Yes — verifies recommended data sources still exist and surfaces current free-tier / auth state
Tap diagnosis (analyzes run logs after a failed test)	Yes — looks up unfamiliar exception messages, library deprecation notices
Tap fix path (Auto-Fix after a tap fails)	Yes — looks up current PyPI install names, current method signatures (replaces the legacy PyPI scraper when on)
First-pass tap script generation	No — happy path, model uses training data so generation stays fast
NL → SQL, schema gen, profiling, DQ rule gen, etc.	No — self-contained, they don’t need the web

OpenAI web search requires the Responses API. When the configured endpoint is /v1/chat/completions, the call is automatically routed to /v1/responses. Ollama has no native web search; selecting it as your AI Primary doesn’t prevent you from using Anthropic or OpenAI for web search.

Stronger Model for Code Generation

Highly recommended: Anthropic with the latest coding model for CodeGen. Tap script generation, AI data quality rules, AI transformations, and NL→SQL all depend heavily on the model’s coding ability — Claude produces dramatically better results than smaller or cheaper models. The same recommendation appears in the Configuration UI’s CodeGen section and in .env.example.

CodeGen tasks (tap scripts, aiRule, aiTransformation, JSON Schema / XSD generation, natural-language → SQL) have their own slot so they can run a different model than the general default. On a fresh install both slots seed the strongest available model — gpt-5.5 with OpenAI, claude-opus-5 with Anthropic — so code generation is at full quality out of the box. The separate slot is your cost-tuning lever: point aiPrimary at a cheaper model (e.g. claude-sonnet-4-6) for the chatty paths and keep the stronger model only on the calls that benefit from it.

Feature	Uses codegen slot?
Tap script generation, auto-fix	Yes
`aiRule` data quality rules	Yes
`aiTransformation`	Yes
CSV / JSON Schema / XSD generation	Yes
Natural language → SQL (`/query/ai`)	Yes
Error explanation, brainstorm chat, CRON generation	No (general slot)
Data profiling, AI Q&A	No (general slot)
AI header validation	No (general slot)

To use the same model for codegen as for everything else, point oss/codegen at the same secret values as oss/ai-primary.

Multi-Tenant: Per-Tenant Overrides

In multi-tenant deployments (multiTenant: "true" in application.yaml) each tenant can override any of the three slots independently. The resolver checks per-request:

Slot	Per-tenant Vault path	Falls back to
AI Primary	`{env}/ai-primary`	`oss/ai-primary`
CodeGen	`{env}/codegen`	`oss/codegen`
Embedding	`{env}/embedding`	`oss/embedding`
Web Search	`{env}/web-search`	`oss/web-search`

({env} is the tenant’s environment name, e.g. trial-acme.) A per-tenant secret takes effect on the next AI call — no restart needed. The override is independent for each slot: a tenant can override just AI Primary, just CodeGen, just Embedding, or any combination.

Setting your key from the UI

Trial users (and any multi-tenant tenant) can manage all three slots from the platform UI. The Configuration page is organized into sub-tabs:

AI Providers — AI Primary, CodeGen, and Embedding provider + model selectors, plus a shared API Keys panel on the right (backed by the {env}/ai-keys secret — see Shared API Key Store). This is where you enter your Anthropic / OpenAI key and pick models.
Secrets — operator-facing platform credentials (Vault-backed). Admin-only when user-auth is on.
Users — user accounts and roles. Visible when USE_USER_AUTH=true.
API-Keys — issue and revoke scoped credentials for the CLI, MCP agents, and other programmatic clients. Visible when USE_API_KEYS=true. See API Keys.
Environment — tenant name, version, trial/hosted flags, and a status block showing which AI slots are using Datris-managed defaults vs your own keys.

Some sub-tabs are role- and flag-gated — see the API Keys matrix for the full visibility rules. To set your AI keys:

Open the Configuration tab, then the AI Providers sub-tab.
Each section (AI Provider, CodeGen Provider, Embedding Provider) has its own provider and model selector. Providers include Anthropic, OpenAI, Azure OpenAI, and Ollama (local).
For Anthropic/OpenAI/Azure, enter your API key in the right-hand panel and pick a model from the dropdown. For Azure, also enter your resource endpoint and type your deployment name as the model. For Ollama, type the model name directly — no API key needed.
Click Save Configuration. Changes take effect immediately — no restart required.

To revert to defaults, click Reset to Datris-managed. This deletes all three per-tenant secrets and falls the tenant back to the global defaults.

Setting tenant secrets directly in Vault

For operators provisioning tenants programmatically:

docker compose exec -e VAULT_ADDR=http://vault:8200 -e VAULT_TOKEN=root-token vault \
  vault kv put secret/trial-acme/ai-primary \
  provider="anthropic" \
  endpoint="https://api.anthropic.com/v1/messages" \
  model="claude-opus-5" \
  apiKey="sk-ant-..." \
  version="2023-06-01"

Same shape for {env}/codegen and {env}/embedding.

Misconfiguration

The platform fails fast at startup if any required slot is missing or malformed. There is no silent fallback. The aiPrimary slot is always required when ai.enabled: true; codegen and embedding are required if you use features that depend on them (which is most features for codegen, and only vector destinations for embedding).

Getting Started

Assistant

Catalog

Taps

Ingestion

Destinations

Data Quality

Transformation

AI Features

Configuration

Integrations

Examples

AI Configuration

Independent Secrets

Shared API Key Store

Quick Start with `.env`

OpenAI path

Azure OpenAI path

Anthropic path (with bundled embedding service)

Fully local with Ollama

Optional model overrides

Mix-and-match: Anthropic chat + OpenAI embeddings

Hot Reload

How Configuration Persists

Re-seeding from `.env`

Setting Secrets Manually

Embedding Provider Notes

Chat Provider Notes

Web Search (Optional)

Stronger Model for Code Generation

Multi-Tenant: Per-Tenant Overrides

Setting your key from the UI

Setting tenant secrets directly in Vault

Misconfiguration

​Independent Secrets

​Shared API Key Store

​Quick Start with .env

​OpenAI path

​Azure OpenAI path

​Anthropic path (with bundled embedding service)

​Fully local with Ollama

​Optional model overrides

​Mix-and-match: Anthropic chat + OpenAI embeddings

​Hot Reload

​How Configuration Persists

​Re-seeding from .env

​Setting Secrets Manually

​Embedding Provider Notes

​Chat Provider Notes

​Web Search (Optional)

​Stronger Model for Code Generation

​Multi-Tenant: Per-Tenant Overrides

​Setting your key from the UI

​Setting tenant secrets directly in Vault

​Misconfiguration

Independent Secrets

Shared API Key Store

Quick Start with `.env`

OpenAI path

Azure OpenAI path

Anthropic path (with bundled embedding service)

Fully local with Ollama

Optional model overrides

Mix-and-match: Anthropic chat + OpenAI embeddings

Hot Reload

How Configuration Persists

Re-seeding from `.env`

Setting Secrets Manually

Embedding Provider Notes

Chat Provider Notes

Web Search (Optional)

Stronger Model for Code Generation

Multi-Tenant: Per-Tenant Overrides

Setting your key from the UI

Setting tenant secrets directly in Vault

Misconfiguration