AI Insights Dashboard

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.

​

Overview

The AI Insights Dashboard (/ai/insights) is your central hub for proactive platform intelligence. It automatically runs three 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: 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:

​

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:

​

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

AI recommendations generated by the analyzers (policy, segmentation, content, rule building) follow a four-state lifecycle: Status transitions are managed via PATCH /api/v1/ai/recommendations/:id.

​

Applying Recommendations

When you click Apply on a recommendation:

1. KaireonAI creates a draft entity in the appropriate module (Contact Policy, Qualification Rule, Customer Segment, or Creative)
2. You are redirected to the relevant editor to review and finalize the draft
3. The recommendation status updates to Applied with a link to the created entity via the appliedEntityId field

Draft entities are never auto-activated. You always review and explicitly activate them.

​

ML Worker Status Indicator

The dashboard shows the ML Worker connection status (fetched from GET /api/v1/ai/ml-worker/status): 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.

​

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

​

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: 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’s anomaly feed, which renders candidates directly on load.
• The Alert Rules evaluator, which converts anomaly-shaped metric moves into notifications.

To fire alerts on these anomalies, configure Alert Rules with the same metrics and a notification destination. 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 helper functions in platform/src/lib/ai/intelligence/decision-explainer.ts build human-readable narratives on top of the endpoints above:

• explainOfferUnderperformance({tenantId, offerId, days, segmentId?}) — names the offer, states its selection rate, and identifies the top competitor when relevant.
• explainSegmentCoverage({tenantId, segmentId, days}) — lists the top offers delivered to a segment and the active offers that never reached it.
• explainAnomaly({tenantId, metric, dimension, dimensionKey, days}) — produces root-cause hypotheses for an anomaly tuple (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.

​

Next Steps