AI Configuration

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:

Database — Per-tenant settings stored in Settings > Integrations > AI / LLM Provider
Environment variables — AI_PROVIDER, AI_MODEL, AI_API_KEY, AI_BASE_URL
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

Open AI Configuration

In the sidebar, expand Settings and click AI Configuration.

Review the five analyzer sections

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.

Adjust parameters

Change any value by editing the input field. Each parameter shows a plain-language description. Click Technical detail to see the underlying implementation detail.

Save or reset

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 and Decision 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 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:

Accuracy — The ML Worker uses K-Means clustering, logistic regression, and TF-IDF, which are more accurate than LLM pattern matching for large datasets.
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.
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 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

Auto-Segmentation

Configure segmentation analysis.

Policy Recommender

Optimize contact frequency policies.

Content Intelligence

Analyze creative performance.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Overview

LLM Provider Configuration

Analyzer Settings

Setup

AI Autonomy

Segmentation Parameters

Policy Parameters

Content Intelligence Parameters

Rule Building Parameters

Ranking Flags

Validation

Per-Run Overrides

Large Dataset Warning Flow

Next Steps

Auto-Segmentation

Policy Recommender

Content Intelligence

​Overview

​LLM Provider Configuration

​Analyzer Settings

​Setup

​AI Autonomy

​Segmentation Parameters

​Policy Parameters

​Content Intelligence Parameters

​Rule Building Parameters

​Ranking Flags

​Validation

​Per-Run Overrides

​Large Dataset Warning Flow

​Next Steps

Auto-Segmentation

Policy Recommender

Content Intelligence

Overview

LLM Provider Configuration

Analyzer Settings

Setup

AI Autonomy

Segmentation Parameters

Policy Parameters

Content Intelligence Parameters

Rule Building Parameters

Ranking Flags

Validation

Per-Run Overrides

Large Dataset Warning Flow

Next Steps