> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Configuration
> Configure AI analyzer parameters for your organization.
## Overview
AI Configuration lets administrators tune the behavior of each AI analyzer and configure the LLM provider across the platform. Settings are saved per tenant (organization), so each organization can customize analysis thresholds, caps, algorithms, and AI provider independently.
Navigate to **Settings > AI Configuration** in the KaireonAI sidebar.
### LLM Provider Configuration
The platform supports 6 LLM providers. Configuration is resolved in priority order:
1. **Database** -- Per-tenant settings stored in `Settings > Integrations > AI / LLM Provider`
2. **Environment variables** -- **AI\_PROVIDER**, **AI\_MODEL**, **AI\_API\_KEY**, **AI\_BASE\_URL**
3. **Defaults** -- Google Gemini 2.5 Flash
| Provider | Key | Default Model | Base URL | Auth |
| -------------- | ----------- | ------------------ | -------------------------- | ------------------------------------------ |
| Google | `google` | `gemini-2.5-flash` | Auto | API key |
| Anthropic | `anthropic` | Claude models | Auto | API key |
| OpenAI | `openai` | GPT-4o models | Auto | API key |
| Amazon Bedrock | `bedrock` | Configurable | Auto | IAM role, access key, or inference profile |
| Ollama | `ollama` | Any local model | `http://localhost:11434` | None |
| LM Studio | `lm_studio` | Any local model | `http://localhost:1234/v1` | None (uses `lm-studio` placeholder key) |
For Bedrock, additional configuration is available: region, auth mode (`access_key` or `iam_role`), role ARN, access key ID, secret access key, and inference profile.
### Analyzer Settings
Analyzer settings are managed via the `GET /api/v1/ai/analyzer-settings` and `PUT /api/v1/ai/analyzer-settings` endpoints. The GET endpoint is accessible to viewers, editors, and admins. The PUT endpoint requires the **admin** role. Both endpoints now include a `ranking` section alongside segmentation, policy, content, and ruleBuilder.
## Setup
In the sidebar, expand **Settings** and click **AI Configuration**.
The page shows collapsible cards for each analyzer: **Segmentation**, **Policy**, **Content Intelligence**, **Rule Building**, and **Ranking**. Each card lists the tunable parameters with their current values.
Change any value by editing the input field. Each parameter shows a plain-language description. Click **Technical detail** to see the underlying implementation detail.
Click **Save Configuration** to persist your changes. Use **Reset Section** on an individual card or **Reset All to Defaults** to restore factory defaults.
Settings are loaded once on page load and edited locally until you save. Multiple admins editing at the same time will overwrite each other — the last save wins.
## AI Autonomy
The **AI Autonomy** card controls how far the [Decisioning Autopilot](/ai-ml/autopilot) and [Decision Sentinel](/ai-ml/sentinel) may act on their own. Stored on `tenant_settings.aiAutopilot`; editable here or via `PUT /api/v1/tenant-settings`:
| Setting | Values | Effect |
| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Mode | `suggest` (default) | Autopilot proposals wait in the Recommendation Inbox |
| | `auto_gated` | Proposals also open Approval Requests for four-eyes review |
| | `auto` | Proposals are applied immediately and audit-logged |
| Sentinel auto-pause | off (default) / on | On hard decision-stream breaches (suppression ≥ 95% or empty-decision rate ≥ 50%), the Sentinel may pause active flows |
## Segmentation Parameters
| Parameter | Type | Min | Max | Default | Description | Technical Detail |
| ----------------- | ----------------- | --- | --- | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
| Min Clusters | integer | 2 | 20 | 2 | Fewest groups to split customers into | K-Means `n_clusters` lower bound. Fewer clusters = broader segments. |
| Max Clusters | integer | 2 | 50 | 8 | Most groups customers can be split into | K-Means `n_clusters` upper bound. More clusters = finer-grained segments. |
| Algorithm | enum | — | — | `kmeans` | Method used to find natural groupings | `kmeans` (centroid-based, fast) or `dbscan` (density-based, handles outliers). |
| Included Features | string\[] or null | — | — | null (all) | Which attributes to consider when grouping | Feature allowlist for clustering input matrix. Null = all numeric features. |
## Policy Parameters
| Parameter | Type | Min | Max | Default | Description | Technical Detail |
| --------------- | ------- | --- | ------ | ------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| Daily Cap | integer | 1 | 100 | 3 | Max messages a customer receives per day | Hard cap on contact frequency per customer per calendar day. |
| Weekly Cap | integer | 1 | 500 | 10 | Max messages a customer receives per week | Hard cap per customer per rolling 7-day window. |
| Monthly Cap | integer | 1 | 2,000 | 30 | Max messages a customer receives per month | Hard cap per customer per rolling 30-day window. |
| Lookback Days | integer | 7 | 730 | 90 | How far back to analyze interaction history | Interaction history window (days) for policy violation detection. |
| Min Sample Size | integer | 10 | 10,000 | 100 | Minimum interactions before analysis is meaningful | Statistical minimum sample size for reliable policy analysis. |
## Content Intelligence Parameters
| Parameter | Type | Min | Max | Default | Description | Technical Detail |
| ------------------------ | ------- | --- | ------- | ------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
| Min Impressions | integer | 1 | 100,000 | 100 | Times content must be shown before judging performance | Minimum impression count before metrics are statistically valid. |
| Metric Weights (CTR) | number | 0 | 1 | 0.33 | Weight given to click-through rate | Weighted blend coefficient for CTR in content scoring. |
| Metric Weights (CVR) | number | 0 | 1 | 0.34 | Weight given to conversion rate | Weighted blend coefficient for CVR in content scoring. |
| Metric Weights (Revenue) | number | 0 | 1 | 0.33 | Weight given to revenue per impression | Weighted blend coefficient for revenue-per-impression. |
| Confidence Level | number | 0.5 | 0.99 | 0.95 | How sure we need to be before recommending a change | Statistical confidence threshold (1 - alpha) for hypothesis tests. |
## Rule Building Parameters
| Parameter | Type | Min | Max | Default | Description | Technical Detail |
| ---------------------- | ----------------- | --- | --- | ---------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
| Max Conditions | integer | 1 | 20 | 5 | Maximum conditions allowed in a single rule | Upper bound on rule clause count to prevent overly complex rules. |
| Allowed Operators | string\[] | — | — | `equals`, `gt`, `lt`, `gte`, `lte`, `contains`, `in` | Comparison types available when building rules | Operator allowlist for AI-generated rule conditions. |
| Field Type Constraints | string\[] or null | — | — | null (all) | Which field types can be used in rules | Field type allowlist for rule condition targets. Null = no restrictions. |
## Ranking Flags
The `ranking` section gates five realtime features that run inside the `/recommend` hot path. All flags default to `false`. Change them via the **Ranking** card in **Settings > AI Configuration**, or directly via `PUT /api/v1/ai/analyzer-settings` with a `ranking` object.
| Flag | Default | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lagrangianEnabled` | `false` | Enable the realtime Lagrangian shadow-price solver. When on, the rank node applies a continuous penalty to offers whose `budget.dailyCapCents` is approaching exhaustion, naturally rotating traffic toward less-saturated offers without hard-dropping them. When no offer has budget or inventory configured, the solver detects a no-constraint state and returns base scores untouched — the overhead is skipped entirely. |
| `crossOfferEnabled` | `false` | Enable cross-offer constraint loading so the Lagrangian solver can cap total selections across groups of related offers (channel quota, portfolio budget, category cap). Requires `lagrangianEnabled: true` to have effect. The cross-offer CRUD API is not yet public; this flag is reserved for tenants with direct database access to constraint rows. |
| `exp3IxEnabled` | `false` | Enable the EXP3-IX online bandit that continuously re-weights ranking arms based on customer response feedback. Requires operator-configured `banditArms` in the ranking state. Without configured arms the flag is a structured no-op — no bandit arm is sampled and `banditArmIndex` is absent from the `/recommend` response. See [EXP3-IX Ranking](/decisioning/ranking-exp3ix) for arm configuration. |
| `budgetPacingEnabled` | `false` | Enable budget pacing so daily offer spend is spread evenly across the day rather than exhausted early. Requires per-offer pacing config (`plan` + `delivered` history). Without that config the wire reports `awaitingConfig` and leaves scores untouched. Full operator configuration is forthcoming. |
| `goalSeekEnabled` | `false` | Enable goal-seek adjustment that fine-tunes ranking weights to hit a configured period target (e.g. a target conversion rate for the day). Requires `periodTarget`, `currentActual`, and `elapsedFraction` in the ranking state. Without those values the wire is a no-op. Full operator configuration is forthcoming. |
`budgetPacingEnabled` and `goalSeekEnabled` are available to enable but their full operator-facing configuration UI is forthcoming. Turning them on without the corresponding state configured results in a safe no-op at runtime — scores are returned untouched and a structured `awaitingConfig` diagnostic is logged.
## Validation
All parameters are validated server-side using Zod schemas. If any value is outside its allowed range, the API returns a `400 Bad Request` with details about which parameter failed validation. Each sub-schema (segmentation, policy, content, ruleBuilder) is parsed independently — a bad value in one analyzer does not reset valid overrides in other analyzers.
## Per-Run Overrides
Each AI analyzer (Segmentation, Policy Recommender, Content Intelligence, Rule Building) supports per-run parameter overrides in its **Advanced Parameters** panel.
Per-run overrides:
* Take effect for that run only and do not change the saved tenant configuration
* Default to the current tenant-level values from AI Configuration
* Include a **Reset to Defaults** button to restore tenant-level values
This lets analysts experiment with different settings without affecting the organization-wide defaults.
## Large Dataset Warning Flow
When a dataset contains **more than 5,000 rows** (the **ML\_ROW\_THRESHOLD** constant, `5000`, in `domain/ai.ts`; a dataset of exactly 5,000 rows still routes straight to the LLM), the platform displays a confirmation dialog before proceeding with analysis. The dialog provides three pieces of information:
1. **Accuracy** — The ML Worker uses K-Means clustering, logistic regression, and TF-IDF, which are more accurate than LLM pattern matching for large datasets.
2. **Cost estimate** — Proceeding with the LLM shows the estimated token count and cost. The estimate is calculated as `rows x fields x 15 + 500` tokens.
3. **Speed** — The ML Worker processes data locally in seconds vs. LLM round-trip latency.
The dialog offers two choices:
* **Use ML Worker** — Routes the analysis to the ML Worker for full-dataset processing (only available if the ML Worker is connected and healthy).
* **Proceed with LLM** — Continues with LLM-based analysis using sampled data. Useful when the ML Worker is unavailable.
For datasets over 5,000 rows, LLM-based analysis samples the data rather than processing it all. This reduces cost but may miss patterns present in the full dataset. Deploy the [ML Worker](/self-host/deploy/ml-worker) for the most accurate results on large datasets.
If the ML Worker is not connected, the dialog still appears but explains that the ML Worker is not available and suggests enabling it in **Settings > Integrations**.
## Next Steps
Configure segmentation analysis.
Optimize contact frequency policies.
Analyze creative performance.