Skip to main content

​
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
ProviderKeyDefault ModelBase URLAuth
Googlegooglegemini-2.5-flashAutoAPI key
AnthropicanthropicClaude modelsAutoAPI key
OpenAIopenaiGPT-4o modelsAutoAPI key
Amazon BedrockbedrockConfigurableAutoIAM role, access key, or inference profile
OllamaollamaAny local modelhttp://localhost:11434None
LM Studiolm_studioAny local modelhttp://localhost:1234/v1None (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

1

Open AI Configuration

In the sidebar, expand Settings and click AI Configuration.
2

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.
3

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.
4

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.

​
Segmentation Parameters

ParameterTypeMinMaxDefaultDescriptionTechnical Detail
Min Clustersinteger2202Fewest groups to split customers intoK-Means n_clusters lower bound. Fewer clusters = broader segments.
Max Clustersinteger2508Most groups customers can be split intoK-Means n_clusters upper bound. More clusters = finer-grained segments.
Algorithmenum——kmeansMethod used to find natural groupingskmeans (centroid-based, fast) or dbscan (density-based, handles outliers).
Included Featuresstring[] or null——null (all)Which attributes to consider when groupingFeature allowlist for clustering input matrix. Null = all numeric features.

​
Policy Parameters

ParameterTypeMinMaxDefaultDescriptionTechnical Detail
Daily Capinteger11003Max messages a customer receives per dayHard cap on contact frequency per customer per calendar day.
Weekly Capinteger150010Max messages a customer receives per weekHard cap per customer per rolling 7-day window.
Monthly Capinteger12,00030Max messages a customer receives per monthHard cap per customer per rolling 30-day window.
Lookback Daysinteger773090How far back to analyze interaction historyInteraction history window (days) for policy violation detection.
Min Sample Sizeinteger1010,000100Minimum interactions before analysis is meaningfulStatistical minimum sample size for reliable policy analysis.

​
Content Intelligence Parameters

ParameterTypeMinMaxDefaultDescriptionTechnical Detail
Min Impressionsinteger1100,000100Times content must be shown before judging performanceMinimum impression count before metrics are statistically valid.
Metric Weights (CTR)number010.33Weight given to click-through rateWeighted blend coefficient for CTR in content scoring.
Metric Weights (CVR)number010.34Weight given to conversion rateWeighted blend coefficient for CVR in content scoring.
Metric Weights (Revenue)number010.33Weight given to revenue per impressionWeighted blend coefficient for revenue-per-impression.
Confidence Levelnumber0.50.990.95How sure we need to be before recommending a changeStatistical confidence threshold (1 - alpha) for hypothesis tests.

​
Rule Building Parameters

ParameterTypeMinMaxDefaultDescriptionTechnical Detail
Max Conditionsinteger1205Maximum conditions allowed in a single ruleUpper bound on rule clause count to prevent overly complex rules.
Allowed Operatorsstring[]——equals, gt, lt, gte, lte, contains, inComparison types available when building rulesOperator allowlist for AI-generated rule conditions.
Field Type Constraintsstring[] or null——null (all)Which field types can be used in rulesField 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.
FlagDefaultDescription
lagrangianEnabledfalseEnable 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.
crossOfferEnabledfalseEnable 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.
exp3IxEnabledfalseEnable 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.
budgetPacingEnabledfalseEnable 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.
goalSeekEnabledfalseEnable 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 5,000 or more rows (the ML_ROW_THRESHOLD constant from domain/ai.ts:101), 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 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.