# SwiftQuery AI Documentation

## Overview
The AI module in SwiftQuery powers intelligent features such as Retrieval-Augmented Generation (RAG) for patient data, similar case search, and clinical note enhancement. It leverages **Google Gemini** for generation, **CyborgDB** for vector storage, and **SentenceTransformers** for embeddings.

## Key Components

### 1. Patient RAG Pipeline (`ai_agents/patient_rag.py`)
**Class**: `SimilarPatientRAGPipeline`

This pipeline manages the context for AI interactions.

- **Session Management**:
  - `start_patient_session(patient_id)`: Initializes an *ephemeral, in-memory* vector store for a specific patient. It extracts data (History, Consultations, Tests, Chats) from MongoDB, chunks it, and ingests it into CyborgDB.
  - `end_patient_session(patient_id)`: Cleans up the in-memory store to free resources.

- **RAG Query**:
  - `rag_query(query, patient_id)`: Retrieves relevant chunks from the patient's active session store and uses Google Gemini to generate a context-aware answer.

- **Similar Patient Search**:
  - `similar_patient_search(query)`: Builds/uses a *global anonymized* vector store containing clinical data from all patients. It finds cases with similar symptoms or conditions to aid diagnosis.

### 2. Clinical Note Enhancer (`ai_agents/clinical_summarizer.py`)
**Class**: `ClinicalNoteEnhancer`

This tool improves the quality of raw clinical text entered by assistants.

- **Function**: `enhance_text(text)`
  - Uses Gemini to rephrase medical text for clarity, grammar, and professionalism without altering facts.
- **Batch Processing**: `enhance_patient_records(patient_id)`
  - Iterates through a patient's entire record (History, Consultations, Reports) and enhances all text fields. Supports a `dry_run` mode to preview changes.

### 3. Chat Interface (`utils/blueprints/chat.py`)
- **Route**: `/api/chat`
- **Logic**:
  - Receives user message.
  - If the message starts with `/similar`, it triggers `rag_pipeline.similar_patient_search`.
  - Otherwise, it triggers `rag_pipeline.rag_query`.
  - Logs the interaction to `chatsession` and `chatmessage` collections.

## Dependency Configuration
- **Embeddings**: `all-MiniLM-L6-v2` (via SentenceTransformers).
- **LLM**: `gemini-flash-latest` (via Google Generative AI).
- **Vector DB**: `CyborgDB` (in-memory execution).

## Error Handling
- All AI failures (e.g., API limits, network issues) are caught and logged.
- The UI receives graceful error messages instead of server crashes.
- Sessions attempt auto-recovery if a context is not found in memory (e.g., due to worker restarts).