AI Integration

:::info Source Sourced from services/analytics-service/AI_INTEGRATION.md in the documentation repo. :::

1. AI Capabilities (primarily M5+)

Capability	Prompt	Classification
Natural-language query	analytics.nl_query	Limited-risk (advisory)
Anomaly detection	analytics.anomaly.detect	Limited-risk
Forecasting (MRR, retention, completion)	analytics.forecast	Limited-risk
Cohort suggestion	analytics.cohort.suggest	Limited-risk
Auto-dashboard generation	analytics.dashboard.generate	Limited-risk
At-risk learner prediction	analytics.atrisk.predict	High-risk (EU AI Act) — affects learner

All via AIClient port.

2. High-Risk: At-Risk Prediction

• Produces predictions about learners likely to drop out / fail compliance.
• Mandatory human review before any action (enrollment intervention, manager alert).
• Explanation + feature attribution required.
• Disputable by learner.
• Quarterly bias eval (demographic parity, equalized odds).

3. Natural Language Query

• Admin asks: "Show me completion rate for course X in Q1 2026."
• AI generates SQL (restricted schema-aware), executes, summarizes.
• Generated SQL reviewed for safety (tenant filter auto-injected; no destructive ops).
• Reveal generated SQL for transparency.

4. Safety

• Pre-call: moderation; PII redaction on aggregated data.
• Post-call: schema validation; SQL must include tenant filter.
• Refusal UX on ambiguous queries.

5. Provenance

• Every insight: prompt version, model, SQL, confidence, evidence rows.

6. Cost

• Per-tenant AI budget.
• Caching: same question + time-range → 1h cache.
• Expensive queries (e.g., forecasts) rate-limited.

7. Local vs Cloud

• NL query: cloud (large LLM for SQL generation).
• Anomaly detection: hybrid — local model (ARIMA/Prophet) + LLM for explanation.
• Forecast: local (Prophet) + LLM narrative.

8. Data Privacy

• actor_id_hash only; no raw user IDs to AI.
• noTrain on providers.
• HIPAA tenants: on-premise models only.

9. Right to Explanation

• At-risk predictions: feature attribution (which signals triggered).
• Anomaly alerts: historical context + comparable periods.
• NL queries: generated SQL visible to admin.