AI features
PLACEHOLDER Cloud uses an LLM you configure — OpenAI, Anthropic, Ollama, or any OpenAI-compatible endpoint — for three things: proposing rules, explaining anomalies, and (planned) translating natural-language descriptions into custom SQL expectations.
The LLM is configured per organisation via LLMConfig rows; the org's default config is used unless overridden. API keys for hosted LLMs are AES-256-GCM-encrypted at rest.
Configuring a provider
Settings → AI opens with one-click setup cards for Anthropic, OpenAI, Azure OpenAI, and a local Ollama install. Each card lists that provider's supported models, links out to where you get an API key (or, for Ollama, the download page), and shows a Connected check once at least one saved config uses that provider. Clicking Configure opens the add-config form pre-selected to that provider. Any other OpenAI-compatible endpoint is reachable through the form's provider selector (provider = "custom" — see Self-hosted / private LLMs).
Until a provider is configured, the AI surfaces are inert but never dead ends: the rule-suite editor's Ask AI control is disabled with an inline link to Settings → AI, and the Suggestions page shows an empty state that explains AI suggestions require a provider and links you to the setup cards.
What the LLM is asked to do
Rule suggestions
After every profile run, the worker enqueues an AISuggestion of kind = "rule_generation". The prompt includes the asset's column list, types, and sample stats; the LLM returns a list of proposed rules with rationales and confidence scores.
You see these in the Suggestions route. Each row has accept / dismiss buttons; accept appends the rule to a chosen rule suite.
Status: partial (PARITY-8) — single-row accept / dismiss UI is in flight. Bulk accept / dismiss (FEATURE-39) is shipped: select multiple rows on the Suggestions page and accept them onto one rule suite (or dismiss with an optional reason) in a single call.
Anomaly explanations
When you tap an anomaly, the Explain panel asks the LLM to summarise the deviation in plain language ("the row count dropped from a 14-day baseline of 412k to 89k — a 78 % drop classified as critical"). The explanation is cached on the AnomalyEvent after the first generation; a Regenerate button forces a fresh call.
Status: partial (PARITY-9) — UI is in flight; backend hooks are in place.
Root cause analysis narrative
On a failed validation result, the Root cause analysis panel ranks likely causes deterministically (no LLM needed). If a provider is configured, a Generate AI summary button asks the LLM to narrate the ranked causes in plain English and suggest a next step. It is opt-in (off by default to bound spend) and degrades gracefully to a Settings → AI link when no provider is set. Shipped in FEATURE-410 (first cut).
Custom SQL generation
You describe the rule you want in English; the LLM produces a parameterised SQL query that returns rows where the rule is broken. Shipped in FEATURE-23. The Custom SQL editor in the rule-suite form exposes a Generate from description button — provide a one-line goal ("orders that were shipped before they were paid for"), pick the target asset, and the LLM returns a {batch}-templated SELECT plus a description string the same validator that fronts hand-written queries will accept. Audit each generation: the LLM doesn't know your schema beyond the column-name list the prompt carries, and the safety allowlist on the resulting SQL is the same one described in Rule suites → Custom SQL → Safety model.
Data model
LLMConfig (public schema):
| Column | What it stores |
|---|---|
org_id | Which org this config belongs to. |
name | A label. |
provider | openai / anthropic / ollama / azure_openai / custom. |
model | The model identifier per provider (claude-3-5-sonnet, gpt-4o-mini, etc.). |
api_key_encrypted | Encrypted bearer credential. |
base_url | Override for self-hosted or Azure endpoints. |
is_default | If true, used when nothing else is specified. |
AISuggestion (per-tenant) carries the request and the response — see Anomalies and Rule suites for the consumer side.
Cost controls
Per-org LLM cost budgets are tracked in HARDEN-25. When that lands, an org owner can set a monthly budget; PLACEHOLDER Cloud refuses further LLM calls once the budget is consumed.
Self-hosted / private LLMs
You can point PLACEHOLDER Cloud at any OpenAI-compatible endpoint by setting provider = "custom" and a base_url. The most common pattern is Ollama running on a private host (base_url = http://ollama.internal:11434/v1). The traffic stays inside your network; PLACEHOLDER Cloud never proxies LLM calls through itself.