AI Assistant

​

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

​

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:

​

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.

​

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.

​

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