> ## 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 Assistant
> Build and manage your decisioning platform using natural language
## Overview
KaireonAI includes a built-in AI assistant accessible from every page in the platform. Open it by clicking the AI icon in the top navigation bar, or press **Cmd+I** (macOS) / **Ctrl+I** (Windows/Linux).
The assistant can:
* **Query** any entity -- "Show me all active offers in the cross-sell category"
* **Analyze** your setup -- "Why didn't customer C-1234 receive the home loan offer?"
* **Build** new entities -- "Create a decisioning gate targeting customers with balance over \$10,000"
* **Build V2 pipelines** -- "Create a V2 decision flow with diversity ranking and formula scoring"
* **Simulate** changes -- "What would happen if I lowered the email frequency cap to 2 per week?"
* **Generate content** -- "Write email copy for the premium card offer in an urgent tone"
* **Diagnose models** -- "Analyze model health and detect drift for my propensity model"
* **Search documentation** -- "How do I set up a contact policy?"
## Architecture
The AI assistant is built on the [Vercel AI SDK](https://sdk.vercel.ai) and uses a three-layer architecture:
1. **Context Router** -- Inspects the current page route and selects the appropriate system prompt and tool subset. This keeps the LLM focused on the user's current task.
2. **Tool Layer** -- 85 tools organized across 11 categories that call internal API routes on behalf of the user. Every tool output is PII-sanitized before reaching the LLM. Tool calling has been verified with Google Gemini.
3. **Provider Layer** -- Supports 6 LLM providers (Google, Anthropic, OpenAI, Amazon Bedrock, Ollama, LM Studio) with per-tenant configuration stored in the database.
## 85 Tools
The assistant is powered by 85 tools organized across 11 tool categories:
| Category | Tools | Count |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| Data | listSchemas, getSchemaFields, addSchemaField, listPipelines, addPipelineNode, listTransformTypes, listConnectors, createSchema, createConnector, createPipeline | 10 |
| Studio | listDecisionFlows, listOffers, listChannels, listContactPolicies, createOffer, createDecisionFlow, createChannel, createTreatment, createCategory, createGuardrail, createContactPolicy, createTrigger, createOutcomeType, testConnector, createQualificationRule, createContactPolicyRule | 16 |
| V2 Pipeline | listV2NodeTypes, listScoringMethods, listRankMethods, listGroupAllocationStrategies, createV2DecisionFlow, getDecisionFlowConfig, addV2PipelineNode, removeV2PipelineNode, updateV2PipelineNodeConfig | 9 |
| Algorithms | listModels, trainModel, listExperiments, createExperiment, getModelDetails, addPredictor, removePredictor, updateModelConfig | 8 |
| Dashboards | queryMetric, listAlerts | 2 |
| Content Generation | generateCreativeCopy, generateSubjectLines | 2 |
| CMS | list\_content\_items, get\_content\_item, create\_content\_item, update\_content\_item, publish\_content\_item, generate\_content\_variants, list\_content\_sources, sync\_content\_source | 8 |
| Docs | searchDocs, getDocPage | 2 |
| Behavioral Metrics | listBehavioralMetrics, createBehavioralMetric, previewMetricValues, computeMetricNow, createMetricRule | 5 |
| Mutations | updateOffer, updateDecisionFlow, updateChannel, updateContactPolicy, updateQualificationRule, deleteEntity, publishDecisionFlow, confirmMutation | 8 |
| Intelligence | explainDecision, traceCustomerJourney, compareOfferEligibility, listCustomerSuppressions, analyzeQualificationFunnel, analyzeContactPolicySuppression, analyzePolicyConflicts, analyzeOfferPerformance, simulateRuleChange, simulateFrequencyCapChange, analyzeModelHealth, explainModelScoring, suggestModelImprovements, detectModelDrift, runHealthCheck | 15 |
### Read Tools (available everywhere)
These 18 tools are available in every context, giving the assistant cross-module visibility regardless of which page you are on:
`listSchemas`, `listPipelines`, `listConnectors`, `listTransformTypes`, `listDecisionFlows`, `listOffers`, `listChannels`, `listContactPolicies`, `listModels`, `listExperiments`, `queryMetric`, `listAlerts`, `searchDocs`, `listBehavioralMetrics`, `listV2NodeTypes`, `listScoringMethods`, `listRankMethods`, `listGroupAllocationStrategies`
### Write Tools (context-specific)
Creation and mutation tools are added based on the current page context. For example, when on the Decision Flows page, you get the full V2 pipeline toolset plus mutation tools. When on the Algorithms page, you get model management and training tools.
### Intelligence Tools
Deep analysis tools that provide explainability, diagnostics, and simulation:
| Tool | What It Does |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explainDecision` | Full decision funnel walkthrough: inventory, qualification, contact policy, scoring, ranking. Shows why a customer received or did not receive a specific offer. |
| `traceCustomerJourney` | Timeline of a customer's interactions: offers shown, channels used, outcomes recorded, journey enrollments, experiment assignments. |
| `compareOfferEligibility` | Side-by-side comparison of 2-5 offers for a customer: which rules pass/fail, which policies block, and the resulting scores. |
| `listCustomerSuppressions` | All active contact policy suppressions affecting a customer: which rules are blocking, on which channels, and expiration. |
| `analyzeQualificationFunnel` | Decision funnel analysis identifying the biggest bottleneck rule and suggesting improvements. |
| `analyzeContactPolicySuppression` | Suppression rate analysis by rule type and channel with recommendations for over-aggressive policies. |
| `analyzePolicyConflicts` | Cross-entity conflict detection: contradictions, overlaps, and misconfigurations across offers, rules, policies, and experiments. |
| `analyzeOfferPerformance` | Offer performance analysis: impressions, conversions, conversion rate, revenue, and trends. Identifies top/bottom performers. |
| `simulateRuleChange` | Before/after impact simulation for decisioning gate or contact policy changes. Shows reach estimates and impact direction. |
| `simulateFrequencyCapChange` | Frequency cap impact simulation: customers unlocked/suppressed, fatigue risk level. |
| `analyzeModelHealth` | ML model health check: AUC, precision, recall, performance trend, feature importance, data freshness, overall verdict. |
| `explainModelScoring` | Score explanation for a specific customer: raw score, estimated percentile, top contributing features with direction. |
| `suggestModelImprovements` | Model improvement recommendations: missing predictors, model type vs data volume, unused features, hyperparameter tuning. |
| `detectModelDrift` | Drift detection: compare recent scoring distribution against training-time metrics, check calibration, recommend action (retrain/monitor/no action). |
| `runHealthCheck` | Comprehensive tenant health check: model health, policy conflicts, budget burn, suppression rates, stale entities, experiment status. Results cached for 5 minutes. |
## Context-Aware Routing
The assistant adapts its system prompt and available tools based on which page you are on. This keeps the LLM focused on your current task while always providing read-only cross-module visibility.
| Page Route | Module | Additional Tools |
| ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/data/schemas` | Data | addSchemaField, getSchemaFields, createSchema |
| `/data/flow-pipelines` | Data | createFlowPipeline, updateFlowPipeline, getSchemaFields |
| `/data/*` | Data | createConnector, testConnector |
| `/studio/behavioral-metrics` | Studio | createBehavioralMetric, previewMetricValues, computeMetricNow, createMetricRule |
| `/studio/customer-viewer` | Studio | explainDecision, traceCustomerJourney, compareOfferEligibility, listCustomerSuppressions |
| `/studio/decision-flows` | Studio | Full creation + mutation + V2 pipeline + intelligence tools (30+ additional) |
| `/studio/treatments` | Studio | Creation tools + generateCreativeCopy, generateSubjectLines + all 8 CMS tools |
| `/studio/qualification-rules` | Studio | createQualificationRule, updateQualificationRule, deleteEntity, analyzeQualificationFunnel, simulateRuleChange |
| `/studio/contact-policies` | Studio | createContactPolicy, createContactPolicyRule, updateContactPolicy, deleteEntity, analyzeContactPolicySuppression, simulateFrequencyCapChange, analyzePolicyConflicts |
| `/studio/*` | Studio | Full creation + mutation + metrics + analyzeOfferPerformance |
| `/algorithms/*` | Algorithms | trainModel, createExperiment, getModelDetails, addPredictor, removePredictor, updateModelConfig, analyzeModelHealth, explainModelScoring, suggestModelImprovements, detectModelDrift |
| `/dashboards/*` | Dashboards | runHealthCheck, analyzeOfferPerformance, analyzePolicyConflicts |
| Any other page | General | All 85 tools |
### How Routing Works
The context router (`getContextForRoute`) inspects the pathname and returns:
1. **Module label** -- `data`, `studio`, `algorithms`, `dashboards`, or `general`
2. **System prompt** -- A module-specific prompt that tells the LLM what it can do, what terminology to use, and which V2 pipeline features are available
3. **Tool names** -- The 18 read-only tools plus context-specific write/intelligence tools
4. **Tool objects** -- The actual tool implementations, with `tenantId` automatically injected
The general fallback (any page not matching a specific route) provides access to all tools.
## V2 Composable Pipeline Support
The assistant fully supports the V2 composable pipeline with 16 node types in 3 phases:
**Phase 1 -- Narrow:** `inventory`, `match_creatives`, `enrich`, `qualify`, `contact_policy`, `filter`, `conditional`, `call_flow`
**Phase 2 -- Score & Rank:** `score` (3 built-in methods + external endpoints + channel overrides + champion/challenger), `optimize` (multi-objective portfolio optimization), `rank` (4 algorithms), `group` (Hungarian optimal allocation)
**Phase 3 -- Output:** `compute`, `set_properties`, `response`
**Cross-phase:** `call_flow`, `extension_point`
### Scoring Methods
* **priority\_weighted** -- Offer priority (0-100), no ML model needed
* **propensity** -- ML model propensity score
* **formula** -- Weighted composite: `propensity x 0.4 + context x 0.2 + value x 0.3 + lever x 0.1` (weights must sum to 1.0)
* **Channel overrides** -- Per-channel scoring method/model/formula
* **Champion/Challenger** -- A/B test scoring models with traffic split
### Ranking Methods
* **topN** -- Best offers by score
* **diversity** -- Category round-robin with backfill
* **round\_robin** -- Strict equal category representation
* **explore\_exploit** -- Epsilon-greedy (deterministic per customer via FNV-1a hashing)
### Group Allocation
* **optimal** -- Hungarian (Kuhn-Munkres) algorithm for globally optimal placement assignment, O(n^3)
* **greedy / priority\_fill** -- Fill placements sequentially with highest-scoring candidates
### Sub-Flow Invocation
The `call_flow` node invokes another decision flow on the current candidate set. Max depth: 2 levels. Circular reference guard prevents infinite loops. `optional=true` (default) means the parent flow continues if the sub-flow errors. `passContext=true` shares the parent's candidates. `mergeMode=replace` replaces parent candidates with sub-flow output.
## Guided Autonomy
Every tool that writes entities — creates, updates, deletes, publishes, model training, predictor changes, CMS writes — follows an **enforced preview -> approve -> execute** flow. This is gated at the tool layer, not by prompt instructions: calling a write tool never mutates anything; it stashes the executor and returns a preview card.
1. **Preview** -- The assistant shows exactly what it plans to create or change in a preview card
2. **Approve or Cancel** -- You review the details and click Approve or Cancel
3. **Execute** -- Clicking Approve calls `POST /api/v1/ai/mutations/confirm` (editor/admin, audit-logged as `ai_mutation`), which runs the stashed executor deterministically -- no LLM round-trip is involved in the approval itself
Pending mutations expire after 5 minutes if not confirmed. The `confirmMutation` chat tool provides the same execution path for MCP/agent callers.
Read operations and analysis run immediately -- no approval needed. Every write requires your explicit approval, including creates and model training.
### Deletable Entity Types
The `deleteEntity` tool supports: offer, decisionFlow, channel, contactPolicy, qualificationRule, experiment, guardrail, trigger.
## Conversation History
Your conversations are automatically saved and can be resumed later:
* Click the **History** icon in the AI panel header to see past conversations
* Click any conversation to resume it -- full message history is loaded from the database
* Start a **New conversation** to begin fresh
* Conversations are auto-titled from the first user message
* Up to 50 recent conversations are shown per tenant
* Conversations can be deleted via the trash icon or the `DELETE /api/v1/ai/conversations/:id` endpoint
## Documentation Search
The assistant includes a hybrid documentation search tool (`searchDocs`) that combines:
1. **Local knowledge base** -- Keyword-based search over embedded platform documentation covering all features, fields, workflows, and V2 pipeline details
2. **Mintlify MCP fallback** -- If the local match score is below threshold (score \< 4), the assistant queries the external Mintlify docs at `docs.kaireonai.com/mcp` for additional context
When you ask "how to" questions or need guidance on platform features, the assistant automatically searches docs before answering.
## Content Generation
The assistant can generate marketing content directly:
* **generateCreativeCopy** -- Generate copy for any channel (email, sms, push, in-app) with configurable tone (professional, friendly, urgent, casual) and max character length
* **generateSubjectLines** -- Generate 1-5 email subject line variants for an offer
* **generate\_content\_variants** -- Generate full content variants for A/B testing with channel-specific fields (subject line, headline, body, CTA) and configurable tone
## Example Prompts
### Building
* "Create a new email channel with batch delivery mode"
* "Set up a cross-sell offer for credit cards targeting premium customers"
* "Build a V2 Decision Flow that enriches from customer data, qualifies by credit score, scores with formula method, and ranks using diversity"
* "Create a contact policy with a frequency cap of 3 emails per week"
* "Generate 3 subject line variants for the home loan offer"
* "Add a call\_flow node to my pipeline that invokes the upsell-flow for secondary scoring"
* "Create a behavioral metric that counts impressions per offer in the last 30 days"
### V2 Pipeline
* "What scoring methods are available?"
* "What ranking algorithms can I use?"
* "Create a V2 flow with explore/exploit ranking at 20% exploration rate"
* "Update the score node to use propensity with a channel override for email using formula scoring"
* "Add an enrich node that loads loan\_amount and credit\_score from the applications schema"
* "Set up multi-placement with hero banner (1 slot) and sidebar (3 slots) using optimal allocation"
### Analyzing
* "Why didn't customer C-1234 receive the home loan offer?"
* "Which offers have declining conversion rates this week?"
* "Are there any conflicts in my contact policies?"
* "Explain how the propensity model scores customer C-5678"
* "Run a health check on the platform"
* "What are the suppression rates by channel this month?"
* "Is my propensity model drifting? Should I retrain?"
### Simulating
* "What happens if I change the minimum credit score from 700 to 650?"
* "How many more customers would I reach if I increase the SMS cap to 5 per week?"
* "Simulate removing the age decisioning gate from the auto loan offer"
### Content
* "Write email copy for the premium card offer in an urgent tone"
* "Generate 3 push notification variants for the savings offer"
* "List all content items in draft status"
## AI Configuration
Configure the LLM provider in **Settings > Integrations > AI / LLM Provider**:
| Provider | Models | Notes |
| -------------- | ------------------------------------------ | ------------------------------------------- |
| Google | Gemini 2.5 Flash (default), Gemini 2.5 Pro | Good balance of speed and quality |
| Anthropic | Claude Sonnet, Claude Haiku, Claude Opus | Strong reasoning, best for complex analysis |
| OpenAI | GPT-4o, GPT-4o-mini | Widely available |
| Amazon Bedrock | Any Bedrock-hosted model | Enterprise, uses IAM or role-based auth |
| Ollama | Any self-hosted model | Local at `localhost:11434`, no API costs |
| LM Studio | Any local model | Local at `localhost:1234/v1`, no API costs |
Configuration sources (in priority order):
1. **Database** -- Per-tenant settings via Settings > AI Configuration (supports all providers including Bedrock with region, role ARN, inference profiles)
2. **Environment variables** -- **AI\_PROVIDER**, **AI\_MODEL**, **AI\_API\_KEY**, **AI\_BASE\_URL**
3. **Defaults** -- Google Gemini 2.5 Flash
Additional environment variable names are reserved in the AI config (`AI_ENV`) but are **not currently read by the chat route**:
* **AI\_SIDEBAR\_ENABLED** -- Reserved for enabling/disabling the AI sidebar (not yet wired)
* **AI\_RATE\_LIMIT\_PER\_MINUTE** -- Reserved for overriding the rate limit; the chat route currently enforces a fixed 30 req/min
## Security
* **Prompt injection defense** -- User messages are scanned for 7 injection patterns (e.g., "ignore previous instructions", "you are now", "system:", "override instructions") and matching text is replaced with `[filtered]`. Messages are truncated to 10,000 characters.
* **PII redaction** -- All tool outputs are recursively sanitized before the LLM sees them. Patterns detected and redacted: email addresses, SSN, credit card numbers, phone numbers, bank account numbers, AWS ARNs, database connection strings, and long base64 strings. Field names like `password`, `secret`, `token`, `apiKey`, `ssn`, `creditCard`, `cvv`, `pin`, `privateKey` are always redacted.
* **RBAC enforcement** -- The chat endpoint requires admin, editor, or viewer role. Mutation tools inherit the user's role for downstream API calls.
* **Rate limiting** -- 30 requests per minute per user (configurable). Non-fail-open: requests beyond the limit return 429.
* **Tenant scoping** -- The `tenantId` is automatically injected into every tool call. The assistant cannot access data from other tenants.
* **Audit logging** -- Every chat interaction is logged with module, route, message count, and conversation ID.
* **Max tool steps** -- The LLM is limited to 5 sequential tool calls per message to prevent runaway execution.
* **Max duration** -- The streaming chat route sets `maxDuration = 300` (5 minutes). SSE responses return immediately and are not wrapped in the shared request-timeout helper; the LLM call itself is bounded by the provider/stream.
## Next Steps
Central hub for AI-generated recommendations.
Tune analyzer parameters for your organization.
Connect AI IDEs to KaireonAI via MCP.