AI Copilot

The AI Copilot provides contextual, proactive assistance throughout the MATIH platform. Unlike the reactive chat interface that responds to user questions, the copilot anticipates user needs, offers suggestions, explains data anomalies, and guides users through complex analytical workflows. It operates as a supplementary integration within the AI Service.

Copilot Capabilities

Capability	Description	Trigger
Query suggestions	Recommends next questions based on current context	After query results are displayed
Anomaly alerts	Highlights unusual data patterns in results	When statistical outliers are detected
Schema guidance	Suggests relevant tables and columns	During query composition
Workflow assistance	Guides multi-step analytical workflows	When complex questions are decomposed
Error recovery	Suggests fixes for failed queries	On SQL validation or execution error
Dashboard building	Recommends widgets based on query patterns	During dashboard creation

Copilot Modes

The copilot operates in three modes, configurable per user or tenant:

Mode	Behavior	Use Case
`passive`	Only responds when explicitly invoked	Power users who prefer control
`balanced`	Offers suggestions at key decision points	Default for most users
`proactive`	Continuously provides contextual assistance	New users and onboarding

Suggestion API

The copilot exposes endpoints for frontend consumption:

GET  /api/v1/copilot/suggestions?session_id=...&context=dashboard
POST /api/v1/copilot/explain
POST /api/v1/copilot/guide

Suggestion Response

{
  "suggestions": [
    {
      "type": "follow_up_query",
      "content": "Would you like to see this data broken down by month?",
      "confidence": 0.87,
      "action": {
        "type": "send_message",
        "payload": "Show monthly breakdown of revenue by region"
      }
    },
    {
      "type": "anomaly_alert",
      "content": "Revenue in APAC dropped 23% compared to last quarter",
      "confidence": 0.92,
      "severity": "warning"
    }
  ]
}

Context Sources

The copilot assembles context from multiple sources to generate relevant suggestions:

Source	Data	Weight
Current session	Recent messages and results	High
User profile	Personalization preferences	Medium
Schema metadata	Table relationships and descriptions	Medium
Organization patterns	Common queries by other users	Low
Historical anomalies	Previously detected data patterns	Low

Anomaly Detection

The copilot runs lightweight statistical checks on query results:

class AnomalyDetector:
    def detect(self, data: DataFrame, context: QueryContext) -> list[Anomaly]:
        anomalies = []
        # Check for significant deviations from historical averages
        for column in data.numeric_columns:
            if self._is_outlier(data[column], method="iqr"):
                anomalies.append(Anomaly(
                    column=column,
                    type="outlier",
                    description=f"{column} contains values outside expected range",
                ))
        return anomalies

Workflow Guidance

For complex multi-step analyses, the copilot provides a guided workflow:

Decomposition: Breaks the question into manageable steps
Navigation: Guides the user through each step with suggestions
Validation: Confirms intermediate results before proceeding
Synthesis: Combines results into a final summary

Configuration

Environment Variable	Default	Description
`COPILOT_ENABLED`	`true`	Enable copilot features
`COPILOT_DEFAULT_MODE`	`balanced`	Default copilot mode
`COPILOT_SUGGESTION_LIMIT`	`5`	Maximum suggestions per context
`COPILOT_ANOMALY_THRESHOLD`	`2.0`	Standard deviations for outlier detection
`COPILOT_MIN_CONFIDENCE`	`0.7`	Minimum confidence to surface a suggestion

Personalization Engine API Reference