Database Schema & Data Models

Relevant source files

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

• AI Service/plan.md
• backend/app/schemas/enhanced_detection.py
• backend/app/models/anomaly_score.py
• backend/app/models/safety_assessment.py
• backend/app/utils/prompts.py
• frontend/src/pages/admin/InteractionDetail.jsx

The Database Schema and Data Models for the AI Anomaly Detection system are designed to support a multi-stage, agentic pipeline that monitors and evaluates medical LLM outputs. The system prioritizes safety, medical accuracy, and explainability by persisting data across several layers of analysis, from raw interaction ingestion to high-dimensional anomaly scoring and RAG-backed explanations.

The architecture utilizes a primary SQLite store for portability and queryability, complemented by an append-only JSONL mirror for auditing. The schema follows a hierarchical structure where core interaction logs serve as the foundation for subsequent analysis, scoring, and human feedback records.
Sources: AI Service/plan.md:87-93, AI Service/plan.md:120-125

Core Data Architecture

The system's data flow is structured around the InteractionLog, which captures the raw exchange between a user and the AI model. Subsequent tables extend this data with multi-dimensional analysis results.

The diagram shows the central role of the Interaction Log and its one-to-one or one-to-zero relationship with various analysis and scoring modules.
Sources: AI Service/plan.md:15-84, backend/app/models/anomaly_score.py:30-51, backend/app/models/safety_assessment.py:19-38

Detailed Schema Definitions

1. Interaction Logs

The foundational table that stores the raw communication data and metadata.

Field	Type	Description
id	UUID	Primary key for the interaction.
prompt	String	The original user query.
response	String	The AI-generated response.
model_name	String	Name of the LLM used (e.g., test-model).
timestamp	ISO-8601	Time of ingestion.
metadata	JSON	Includes source (local_ui/api), language, and tags.
Sources: AI Service/plan.md:15-30, frontend/src/pages/admin/InteractionDetail.jsx:36-41

2. Anomaly Scoring & Classification

This model stores the final aggregated scores and specific category classifications for detected anomalies.

class AnomalyCategory(str, Enum):
    NONE = "NONE"
    UNSAFE_ADVICE = "UNSAFE_ADVICE"
    HALLUCINATION = "HALLUCINATION"
    CONTEXT_MISMATCH = "CONTEXT_MISMATCH"
    POOR_QUALITY = "POOR_QUALITY"
    CONFIDENCE_ISSUE = "CONFIDENCE_ISSUE"

Sources: backend/app/models/anomaly_score.py:17-25

Field	Type	Description
quality_anomaly_score	Float	Score for response quality (0.0 - 1.0).
hallucination_anomaly_score	Float	Probability of fabricated information.
alignment_anomaly_score	Float	Match between user intent and response.
safety_anomaly_score	Float	Physical harm or medical risk potential.
final_anomaly_score	Float	Weighted aggregate score.
is_anomaly	Boolean	Indexable flag for rapid filtering.
anomaly_category	String	Classification from the AnomalyCategory Enum.
Sources: backend/app/models/anomaly_score.py:35-48, backend/app/schemas/enhanced_detection.py:100-110

3. Safety Assessment

A dedicated model for deep-dive safety analysis, including specific risk issues and triage appropriateness.

• safety_issues: A JSON list containing dictionaries with type and description of detected hazards.
• risk_category: Categorizes the interaction as safe, review, or unsafe.
• appropriate_response_given: A boolean indicating if the AI correctly handled high-risk scenarios like emergencies.
  Sources: backend/app/models/safety_assessment.py:27-33, backend/app/schemas/enhanced_detection.py:78-83

Multi-Dimensional Detection Schemas

The system utilizes Pydantic schemas to validate and structure the data returned by various specialized agents in the pipeline.

Response Quality & Hallucination

The ResponseQualityResponse schema tracks metrics such as relevance_score, completeness_score, and coherence_score. It also maintains lists of specific quality_issues and strengths.
Sources: backend/app/schemas/enhanced_detection.py:14-26

The HallucinationDetectionResponse schema manages claim verification:

• extracted_claims: List of facts identified in the response.
• verified_claims: Claims confirmed against ground truth.
• unverified_claims: Potential hallucinations.
• hallucination_markers: Specific linguistic cues of fabrication.
  Sources: backend/app/schemas/enhanced_detection.py:33-47

Analysis Risk Flags

The system uses a wide array of boolean flags to identify specific medical risk contexts during the feature extraction stage.

"risk_context_flags": {
    "missing_disclaimer": "boolean",
    "gives_medication_dosing": "boolean",
    "pediatric_dosing_case": "boolean",
    "emergency_case": "boolean",
    "triage_strength": "none|weak|adequate|strong",
    "unwarranted_reassurance": "boolean",
    "overconfident_diagnosis": "boolean"
}

Sources: AI Service/plan.md:38-55, backend/app/utils/prompts.py:28-44

RAG Explanation & Feedback Models

For interactions flagged as anomalies, the system generates an ExplanationRecord using Retrieval-Augmented Generation (RAG).

• risk_type: Restricted to triage, dosing, disclaimer, self_harm, or other.
• explanation: A concise text explanation of why the interaction was flagged.
• citations: An array of objects linking to medical guidelines.
  • doc_id: Identifier for the source document (e.g., NHS_EMERGENCY_Triage).
  • chunk_id: Specific section or fragment used.
  • score: Relevance score of the citation.
    Sources: AI Service/plan.md:71-79, backend/app/utils/prompts.py:157-165

Human Feedback Record

To close the loop and enable future machine learning training, the FeedbackRecord stores expert reviews.

Field	Description
human_label	SAFE, UNSAFE, or BORDERLINE.
corrected_response	Optional text provided by the human reviewer.
comments	Expert notes on the AI's behavior.
reviewer_id	Identifier for the auditor.
Sources: AI Service/plan.md:81-85, frontend/src/pages/admin/InteractionDetail.jsx:54-58

Summary

The Database Schema and Data Models establish a robust framework for medical AI safety monitoring. By decomposing "anomalies" into specific dimensions (Quality, Hallucination, Alignment, Safety, and Confidence) and persisting these alongside raw logs and expert feedback, the system provides a comprehensive audit trail for medical LLM interactions.
Sources: backend/app/schemas/enhanced_detection.py:115-135, AI Service/plan.md:213-220