> ## 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 Insights Dashboard
> Proactive intelligence across your decisioning platform -- health checks, performance analysis, and policy conflict detection.
## Overview
The AI Insights Dashboard (`/ai/insights`) is your central hub for proactive platform intelligence. It automatically runs four intelligence tools in parallel and presents the findings as categorized insight cards sorted by severity.
Navigate to **AI > Insights** in the sidebar to open the dashboard.
## How It Works
On page load (and every 5 minutes thereafter), the dashboard calls four intelligence tools in parallel via `POST /api/v1/ai/intelligence`:
| Tool | Section | What It Checks |
| ------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `runHealthCheck` | Health | Model health, policy conflicts, budget burn, suppression rates, stale entities, experiment status. Results cached server-side for 5 minutes. |
| `analyzeOfferPerformance` | Performance | Offer impressions, conversions, conversion rates, revenue, and trends. Identifies top and bottom performers. |
| `analyzePolicyConflicts` | Policies | Cross-entity conflicts: contradictions, overlaps, gaps, and priority ties across offers, rules, policies, and experiments. |
| `analyzeCrossModule` | Correlations | **Cross-module analysis** -- connects dots across offers, policies, and models to surface insights that span module boundaries. |
Each tool call is independent -- if one fails, the others still display their results.
## Dashboard Layout
The Insights page is a **summary dashboard** that provides a unified view, with links to dedicated drill-down pages for each area.
### KPI Strip
Four top-level metrics at a glance:
| KPI | Description | Links To |
| --------------------- | -------------------------------------------------- | ---------------------- |
| **Health Score** | 0-100% based on critical/warning/info issue counts | -- |
| **Total Impressions** | Sum of all offer impressions in the current period | Content Intelligence |
| **Revenue** | Total revenue from offer conversions | Content Intelligence |
| **Policy Conflicts** | Number of active policy conflicts detected | Policy Recommendations |
### Health Progress Bar
Shows overall system health with a colored progress bar and breakdown of critical, warning, and info issue counts.
### Summary Cards
Three cards provide at-a-glance previews, each linking to the relevant drill-down page:
| Card | Shows | Links To |
| --------------- | ---------------------------------- | --------------------------- |
| **Health** | Top 3 critical issues | AI > Segments |
| **Performance** | Top and bottom performers by CVR | AI > Content Intelligence |
| **Policies** | Active conflicts with entity names | AI > Policy Recommendations |
### Cross-Module Correlations
This section is **unique to the Insights page** and provides the platform's most valuable intelligence -- insights that connect the dots across modules.
| Correlation Type | What It Detects | Example |
| -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Policy blocks top offer** | A contact policy is suppressing impressions for a high-CVR offer | "Category suppression may limit 'Win-Back Lapsed Policy' (9.8% CVR)" |
| **Low-AUC model in active flow** | A model with near-random AUC is available while a decision flow is published | "Model 'Cross-Sell GBM' has AUC 0.503 while 'Banking Main Flow' is live" |
| **Zero-CVR high spend** | An offer has many impressions but zero conversions (wasted opportunity cost) | "'Dental & Vision Rider' has 378 impressions but 0 conversions" |
Each correlation includes:
* **Impact statement** -- why it matters (e.g., "Potential revenue loss: 10-20%")
* **Action button** -- one-click action to resolve the issue
### One-Click Actions
Cross-module correlations and drill-down pages include action buttons that execute changes directly:
| Action | What It Does | API Call |
| ----------------- | ---------------------------------- | ---------------------------------- |
| **Review Policy** | Navigates to Contact Policies page | Navigation |
| **Pause Offer** | Sets offer status to `paused` | `PUT /api/v1/offers` |
| **Disable Model** | Sets model status to `paused` | `PUT /api/v1/algorithm-models/:id` |
After a successful action, the insight is removed from the list. All actions create audit log entries.
### Actionable Insights
Aggregated recommendations from the offer performance analyzer, with a link to see more in the Content Intelligence page.
## Recommendation Lifecycle
The **Recommendation Inbox** on this page shows open recommendations of every type in one place; the Segments, Policy Recommendations, and Content Intelligence pages show their own filtered views. Recommendations come from three producers:
| Source | Producer |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `llm` / `ml_worker` | The analyzers, when you run them from the sidebar pages (or an agent runs a governed playbook apply) |
| `autopilot` | The [Decisioning Autopilot](/ai-ml/autopilot) sweep (experiment promotions, drift retrains) |
| `sentinel` | Reserved for [Decision Sentinel](/ai-ml/sentinel) surfaced findings |
All recommendations follow a four-state lifecycle:
| Status | Meaning |
| ------------- | ------------------------------------------ |
| **New** | Freshly generated, awaiting review |
| **Reviewed** | Opened and read by a user |
| **Applied** | Accepted and converted into a draft entity |
| **Dismissed** | Rejected -- no further action |
Status transitions are managed via `PATCH /api/v1/ai/recommendations/:id`.
## Applying Recommendations
When you click **Apply** on a recommendation:
1. The Apply button arms on first click and asks **"Confirm apply?"** — the change only executes on the second click (`POST /api/v1/ai/recommendations/:id/apply`, admin only)
2. KaireonAI creates a **draft** entity in the appropriate module, or performs the scoped change for Autopilot types:
| Recommendation type | Apply effect |
| ------------------- | --------------------------------------------------------------------- |
| `policy` | Draft Contact Policy |
| `rule` | Draft Decisioning Gate |
| `segment` | Draft AI Customer Segment |
| `content` | Draft Content Item |
| `experiment` | Flips the experiment's champion to the winning challenger |
| `model` | Retrains (shared train path) or pauses the model per `payload.action` |
| `weights` | Updates a Ranking Profile's weights (version bumped) |
3. The recommendation status updates to **Applied** with the created/affected entity id in `appliedEntityId`
If entity creation fails, the API returns an error and the recommendation **stays open** — it is never marked applied without the change actually happening. Draft entities are never auto-activated.
## ML Worker Status Indicator
The dashboard shows the ML Worker connection status (fetched from `GET /api/v1/ai/ml-worker/status`):
| Status | Indicator | Meaning |
| ---------------- | --------- | ---------------------------------------------------------------------------- |
| **Connected** | Green | ML Worker is running and healthy at the configured URL |
| **LLM Only** | Amber | No ML Worker configured or disabled; AI features use LLM-based analysis only |
| **Disconnected** | Red | ML Worker is configured but not responding to health checks |
When the ML Worker is connected, analyzers that support dual-tier routing (segmentation, policy, content) automatically use the ML Worker for datasets exceeding 5,000 rows.
Configure the ML Worker connection in **Settings > Integrations > ML Worker**. The health check polls `/health` with a 30-second cache TTL and 3-second timeout.
## Sentinel Alerts
When the [Decision Sentinel](/ai-ml/sentinel) detects a decision-stream health breach (suppression spike or empty-decision spike), the alerts appear in a **Sentinel Alerts** card on this page (System Health alerts with source `sentinel`).
## Confirm-to-Act Buttons
Cross-module correlation actions that call an API (e.g., pausing an entity) require **two clicks**: the first arms the button ("Confirm: ...?"), the second executes. Navigation actions run on the first click.
## Auto-Refresh
The dashboard automatically refreshes every 5 minutes. The "Last updated" timestamp shows when the most recent refresh completed. You can also navigate away and return to trigger a fresh load.
## Analytics Foundation Endpoints
Beyond the dashboard tools above, KaireonAI exposes four analytical primitives that power deeper insight workflows. Each is a `type=` value on `GET /api/v1/dashboard-data` (full schemas in the [Dashboard Data API reference](/api-reference/dashboard-data)).
### Selection Frequency
`type=selection_frequency` aggregates decision traces to answer "how often was each offer eligible, scored, and selected — and at what rank?" For each offer in the window it returns `eligibleCount`, `scoredCount`, `selectedCount`, `selectionRate`, `avgRank`, and a 10-element `rankDistribution` histogram. Optional filters: `channelId`, `categoryId`, `decisionFlowId`, `segmentId`.
Use it to:
* Spot offers that are always eligible but rarely chosen — these are candidates for score inputs or strategy tuning.
* Compare rank distributions side-by-side to understand competitive pressure between offers.
* Slice by `segmentId` to compare how ranking differs for VIP vs. general customers.
### Anomaly Candidates
`type=anomaly_candidates` compares the current period (`days`) to a prior baseline (`baselineDays`) and surfaces metric moves large enough to warrant attention. Severity is classified from the larger of z-score magnitude and absolute percent change:
| Severity | Trigger | | | | |
| ---------- | ------- | - | ---------- | - | ---- |
| `info` | | z | ≥ 2 **or** | % | ≥ 15 |
| `warning` | | z | ≥ 3 **or** | % | ≥ 30 |
| `critical` | | z | ≥ 4 **or** | % | ≥ 50 |
Covered metrics: `acceptance_rate` (overall, per-offer, per-channel), `revenue` (per-offer), `degraded_scoring_rate` (overall). The endpoint is stateless — it returns candidates for a dashboard to display.
The anomaly surface feeds **two** downstream consumers:
* The [Executive Dashboard](../operations-reporting/executive-dashboard)'s anomaly feed, which renders candidates directly on load.
* The [Alert Rules](../operations-reporting/alert-rules) evaluator, which converts anomaly-shaped metric moves into notifications.
To **fire alerts on these anomalies**, configure [Alert Rules](../operations-reporting/alert-rules)
with the same metrics and a [notification destination](../operations-reporting/notifications).
Alert firing only happens when `/api/cron/tick` is invoked — by AWS
EventBridge when wired, or manually via `curl` in the meantime. During
pilot / initial deployment the cron is usually not wired, so the
anomaly-candidates endpoint still returns data (and drives the dashboard
panel) but configured alert rules sit dormant until a tick occurs. See
[EventBridge Setup](../self-host/deploy/eventbridge-setup) for the optional
automation path.
Rules evaluate on every cron tick and respect cooldown, so you can tune
threshold + window to match the anomaly severity bands above.
### Why-Not-Ranked Aggregate
`type=why_not_ranked` complements the per-customer Why-Not API by answering the question in aggregate: for a given target offer over the window, how often was it eligible but not selected, and why? The response breaks misses into `scoredTooLow`, `filteredByContactPolicy`, `filteredByQualification`, and `beatenBy` — the top five offers that won when this one was scored but passed over. `rankDistribution` surfaces where in the scored ranking this offer typically lands.
The trace sample is capped at 1,000 rows per call to keep latency predictable; the `sampleSize` and `sampleCap` fields in the response tell you when to narrow the window.
### Cross-Decision Narratives
Three explainer helpers build human-readable narratives on top of the endpoints above:
* **Offer underperformance explainer** — given a tenant, offer, window, and optional segment, names the offer, states its selection rate, and identifies the top competitor when relevant.
* **Segment coverage explainer** — given a tenant, segment, and window, lists the top offers delivered to that segment and the active offers that never reached it.
* **Anomaly explainer** — given a tenant, metric, dimension, dimension key, and window, produces root-cause hypotheses for the anomaly (policy pressure, scoring-rank pressure, model degradation).
Each returns `{narrative: string, support: {...}}`. The `narrative` string is safe to render directly in dashboards or executive emails; `support` carries structured evidence that the report narrator uses for richer output.
These helpers also back the **Explain** button on the Executive
Dashboard's anomaly feed. The feed today uses a deterministic fallback
drawn from the anomaly tuple's fields; wiring the helpers through a
dedicated `/api/v1/ai/explain` HTTP route is tracked in the
[roadmap](/roadmap).
## Next Steps
Where the LLM narrative + anomaly feed + segment × offer view live.
Convert anomaly-shaped metric moves into paged notifications.
Compose, narrate, and deliver scheduled reports built from these endpoints.
AI-powered contact policy optimization.
Create rules by describing them in plain English via the AI chat panel.
Discover customer segments from your data.