docs/ML_MODELS.md

# SanjeevaniAI — Machine Learning & Biomedical NER Specification

## 1. Local Neural Architecture

SanjeevaniAI utilizes a dedicated local transformer model for biomedical token classification:

- **Base Architecture**: `roberta-large` (24 layers, 16 attention heads, 1024 hidden dimensions, 355 Million parameters).
- **Fine-Tuning Dataset**: BioCreative V Chemical Disease Relation dataset (BC5CDR).
- **Local Model Path**: `D:\SanjeevaniAI\models\bc5cdr-ner` (1.4 GB model weights).
- **Classification Head**: `RobertaForTokenClassification` with linear projection layer mapping hidden states to BIO label space.
- **Hardware Acceleration**: Automatically prioritizes `CUDA:0` when an NVIDIA GPU is present; gracefully falls back to multithreaded CPU inference.

---

## 2. Label Taxonomy & BIO Tag Normalization

The model is trained on standard IOB2 tagging for biomedical literature:

| Label ID | Raw Tag | Standard Entity Class | Description |
| :--- | :--- | :--- | :--- |
| 0 | `O` | Outside | Non-biomedical token |
| 1 | `B-Chemical` | `CHEMICAL` | Beginning of a chemical/drug entity |
| 2 | `B-Disease` | `DISEASE` | Beginning of a disease/condition entity |
| 3 | `I-Chemical` | `CHEMICAL` | Inside/continuation of a chemical entity |
| 4 | `I-Disease` | `DISEASE` | Inside/continuation of a disease entity |

### Sub-word Token Span Reconstruction
Because RoBERTa uses Byte-Pair Encoding (BPE), sub-word tokens starting with `Ġ` or raw fragments must be mapped back to original text character offsets:
1. Model generates predictions for all tokens.
2. `BC5CDRNERModel` aggregates sequential `B-` and `I-` tokens of matching entity types.
3. Whitespace and sub-word boundary artifacts are resolved using character index tracking `[start_offset, end_offset]`.
4. Extracted text is sliced from original input: `text[start_offset:end_offset]`.

---

## 3. Confidence Calibration & Post-Processing

- Softmax is applied to model output logits $z$:
  $$P(y_i = c) = \frac{e^{z_{i, c}}}{\sum_{j} e^{z_{i, j}}}$$
- Confidence for an entity span $E = (t_1, t_2, \dots, t_k)$ is calculated as the mean token probability:
  $$\text{Confidence}(E) = \frac{1}{k} \sum_{i=1}^k P(y_i = \hat{y}_i)$$
- **Default Confidence Filter**: $\tau = 0.85$. Entities below this threshold are discarded to prevent false positive hallucinations.

---

## 4. Inference Performance Benchmarks

| Hardware Platform | Average Latency (100-word text) | Peak Memory Usage |
| :--- | :--- | :--- |
| NVIDIA GeForce RTX 3050 Laptop GPU (CUDA) | **14.2 ms** | 1,480 MB VRAM |
| Intel Core i7-13700H (CPU Multithreading) | **82.4 ms** | 1,520 MB RAM |

---

## 5. Conversational LLM Architecture (Provider Abstraction)

SanjeevaniAI decouples reasoning from specific LLM vendors via `BaseLLMProvider`:

1. **`GeminiProvider`**: Calls Google Gemini 1.5 Pro / Flash via `google-genai` SDK with healthcare decision-support system prompts, structured JSON schema outputs, and safety settings blocking diagnostic assertions.
2. **`MockLLMProvider`**: High-availability offline fallback providing deterministic, evidence-grounded educational answers for diabetes, hypertension, cardiology, and pharmacology.
3. **Emergency Red-Flag Heuristic Triage**: Runs synchronously prior to LLM inference to identify acute life-threatening presentations (e.g., crushing chest pain, dyspnea, acute neurological deficits) and output emergency escalation notices.