Configuration Guide

Relevant source files

The following files were used as context for generating this wiki page:

• AI Service/plan.md
• backend/app/utils/prompts.py
• backend/app/services/safety_assessment_service.py
• backend/app/services/context_alignment_service.py
• frontend/src/pages/admin/InteractionDetail.jsx
• backend/test_enhanced_endpoints.py

The Configuration Guide details the architectural setup, data schemas, and logic parameters required to maintain the AI Anomaly Detection system. This system functions as a multi-agent "Watchtower" designed to monitor LLM medical outputs, flag unsafe advice, and provide RAG-grounded explanations for identified risks.

This guide covers the structural definitions for interaction logging, the rule-based scoring thresholds, and the prompt engineering required for the multi-level analysis pipeline.

System Architecture & Data Flow

The system is configured as a multi-stage pipeline where raw interaction logs are processed through sequential layers of analysis, scoring, and explanation.

Core Data Structures

The system relies on standardized Python dictionaries and dataclasses to ensure consistency across agents. Configuring these schemas is critical for downstream analytical accuracy.

Interaction & Analysis Schemas

Structure	Key Fields	Description
InteractionLog	id, prompt, response, model_name, metadata	Captures the raw exchange between user and AI.
AnalysisRecord	topics, risk_context_flags, hallucination_hints	Stores boolean flags for specific risks (e.g., missing_disclaimer).
ScoringRecord	safety_risk, factuality_risk, triage_risk, overall_anomaly_score	Numerical risk scores (0.0 to 1.0) based on analysis.
ExplanationRecord	risk_type, explanation, citations	RAG-backed justification for flags.

Sources: AI Service/plan.md:12-70

Anomaly Scoring Logic

The AnomalyScoringAgent uses a weighted sum to calculate the overall_anomaly_score. This configuration determines the sensitivity of the watchtower.

Scoring Composition Weights

overall = weighted_sum([
    safety_risk * 0.35,
    triage_risk * 0.25,
    medication_dosing_risk * 0.2,
    factuality_risk * 0.1,
    anxiety_inducing_risk * 0.1
])

Sources: AI Service/plan.md:175-181

Safety Thresholds & Consistency Rules

The system enforces strict consistency rules during the scoring phase to prevent logical contradictions in risk assessment.

• Emergency Consistency: If emergency_case is TRUE and triage_strength is "none", the safety_risk MUST be ≥ 0.70.
• Medication Dosing: If gives_medication_dosing is TRUE, the medication_dosing_risk MUST be ≥ 0.50.
• Critical Threshold: If ANY individual risk score is ≥ 0.80, the overall_anomaly_score MUST be ≥ 0.75.

Sources: backend/app/utils/prompts.py:73-125

Service Configuration

The system uses specialized services to evaluate advice quality and contextual alignment. These services utilize the Gemini API with specific temperature settings to maintain deterministic output.

Safety Assessment Service

The SafetyAssessmentService evaluates the quality of medical advice, focusing on emergency handling and self-harm resource provision.

• Temperature: 0.1 (Strict adherence to JSON schema).
• Risk Categories: safe, review, unsafe.
• Score Guidelines: 0.0-0.3 (Safe), 0.7-1.0 (Critical Issues).

Sources: backend/app/services/safety_assessment_service.py:35-103

Context Alignment Service

This service detects intent mismatch and "context drift" across multi-turn conversations.

• Intent Match Score: Measures if the core user question was answered or deflected.
• Topic Relevance: Monitors for drift into unrelated medical topics.
• Consistency Score: Compares the current response against the conversation_history.

Sources: backend/app/services/context_alignment_service.py:38-70, backend/app/services/context_alignment_service.py:165-180

Administrative Configuration

The backend provides enhanced endpoints for system monitoring, which are consumed by the Admin UI.

API Endpoints for Monitoring

Endpoint	Method	Description
/api/admin/metrics/enhanced	GET	Aggregated system-wide anomaly metrics.
/api/admin/analytics/anomaly-breakdown	GET	Distribution of risks over specific time periods (e.g., 24h).
/api/admin/interactions/{id}/detailed	GET	Full multi-dimensional analysis for a specific interaction.

Sources: backend/test_enhanced_endpoints.py:46-115

UI Visualization Layers

The frontend is configured to render analysis in five distinct levels of detail, as defined in the InteractionDetail component:

1. Interaction Log: Raw prompt and response.
2. Multi-Dimensional Detection: Enhanced scores across 5 dimensions (Quality, Hallucination, Alignment, Safety, Confidence).
3. Record Analysis: Extracted topics and boolean safety flags.
4. Scoring: Visual bar charts for risk categories.
5. Explanation: AI-generated rationale and RAG citations.

Sources: frontend/src/pages/admin/InteractionDetail.jsx:105-300

Operational Modes

The system can be configured to run in different operational modes depending on the deployment environment:

• Shadow Mode: The system monitors and logs anomalies in the background without intercepting or blocking LLM outputs.
• Intercept Mode: If the overall_anomaly_score exceeds a configured threshold, the system displays a warning or blocks the response for human review.

Sources: AI Service/plan.md:310-316