Upload 21 files

.gitattributes

@@ -37,3 +37,4 @@ AHD_english.xlsx filter=lfs diff=lfs merge=lfs -text
 notebooks/AHD_english_cleaned.xlsx filter=lfs diff=lfs merge=lfs -text
 questions.index filter=lfs diff=lfs merge=lfs -text
 rag_model/faiss/questions.index filter=lfs diff=lfs merge=lfs -text
+cloudflared.exe filter=lfs diff=lfs merge=lfs -text

API_DEPLOYMENT_PLAN.md

@@ -0,0 +1,93 @@
+# CortexRAG - API Deployment & Integration Guide
+
+This document outlines the step-by-step roadmap to wrap the **CortexRAG** model into a production-ready FastAPI service, run it locally, expose it publicly via Cloudflare Tunnel, and provide integration documentation for external developers.
+
+---
+
+## Workflow Overview
+
+```mermaid
+flowchart LR
+    A[Local RAG Model] --> B[FastAPI Wrapper]
+    B --> C[Swagger Testing /docs]
+    C --> D[Cloudflare Tunnel]
+    D --> E[Public HTTPS Endpoint]
+    E --> F[Client Applications]
+```
+
+---
+
+## Step-by-Step Implementation Roadmap
+
+### Step 1: Model Code Verification & Preparation
+- Verify model initialization, FAISS index loading, sentence-transformer embedding model, reranker, and LLM (e.g., Groq API / local LLM).
+- Structure model code cleanly into a reusable class/module (e.g., `rag_pipeline.py`).
+
+### Step 2: FastAPI Web Service (`app.py` / `main.py`)
+- Create lightweight FastAPI application.
+- Define request model (`QueryRequest`) and response model (`QueryResponse`).
+- Define endpoint: `POST /query` (or `/predict`).
+- Add lifecycle events (`lifespan` / `@app.on_event("startup")`) to load heavy ML/FAISS models once into memory on startup.
+
+### Step 3: Local Testing via FastAPI Swagger UI
+- Launch server locally:
+  ```bash
+  uvicorn app:app --reload --host 127.0.0.1 --port 8000
+  ```
+- Navigate to `http://127.0.0.1:8000/docs` to test input payload, validation, error handling, and JSON output structure.
+
+### Step 4: Developer Manual Verification
+- Execute tests using `curl`, Postman, or Python `requests` script to verify:
+  - Valid queries return correct RAG answers and source documents.
+  - Invalid inputs return standard `422 Unprocessable Entity` or structured error messages.
+
+### Step 5: Public Exposure via Cloudflare Tunnel
+- Install Cloudflare CLI (`cloudflared`).
+- Run ad-hoc public tunnel:
+  ```bash
+  cloudflared tunnel --url http://127.0.0.1:8000
+  ```
+- Copy generated HTTPS URL (e.g., `https://your-tunnel-subdomain.trycloudflare.com`).
+
+### Step 6: Public Endpoint Testing
+- Validate public URL with live queries:
+  ```bash
+  curl -X POST "https://your-tunnel-subdomain.trycloudflare.com/query" \
+       -H "Content-Type: application/json" \
+       -d "{\"question\": \"What are the symptoms of acute hypertension?\", \"top_k\": 5}"
+  ```
+
+### Step 7: Developer Integration Specification
+Provide client developers with exact details required for integration:
+
+| Attribute | Value |
+| :--- | :--- |
+| **Base URL** | `https://<your-cloudflare-tunnel-url>` |
+| **Endpoint** | `/query` |
+| **HTTP Method** | `POST` |
+| **Headers** | `Content-Type: application/json` |
+
+#### Request Body (JSON)
+```json
+{
+  "question": "What are the common side effects of Lisinopril?",
+  "top_k": 6
+}
+```
+
+#### Response Body (JSON)
+```json
+{
+  "status": "success",
+  "question": "What are the common side effects of Lisinopril?",
+  "answer": "Common side effects include dizziness, cough, headache...",
+  "sources": [
+    {
+      "id": 1024,
+      "text": "Lisinopril documentation excerpt...",
+      "score": 0.89
+    }
+  ],
+  "execution_time_seconds": 0.42
+}
+```

README.md

@@ -1,149 +1,226 @@
 ---
-language:
-  - en
-library_name: sentence-transformers
+title: CortexRAG Medical RAG API
+emoji: 🩺
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 8000
 tags:
-  - rag
-  - retrieval-augmented-generation
-  - medical
-  - question-answering
-  - semantic-search
-  - faiss
-  - cross-encoder
-  - medical-qa
-pipeline_tag: question-answering
-license: apache-2.0
+- rag
+- medical-ai
+- sentence-transformers
+- faiss
+- fastapi
+- cross-encoder
+- groq
 ---
 
-# Medical RAG System
+# 🩺 CortexRAG - Advanced Medical RAG API
 
-A retrieval-augmented generation (RAG) system for answering medical questions using a curated English medical Question-Answer knowledge base.
+**CortexRAG** is a high-performance, domain-specific Retrieval-Augmented Generation (RAG) system engineered for medical and clinical question answering. It combines semantic vector search (FAISS + Sentence Transformers), cross-encoder re-ranking, and high-speed LLM inference (Groq / Llama) wrapped in a lightweight **FastAPI** REST interface.
 
-The system combines semantic retrieval (Sentence Transformers + FAISS), medical query expansion, Cross-Encoder reranking, evidence deduplication, confidence gating, and LLM-based answer generation.
+---
+
+## 🌟 Features
 
-> **Important:** This system is for research and educational purposes only. It is not a medical diagnostic system and should not replace professional medical advice.
+- **Semantic Embedding Engine**: `all-MiniLM-L6-v2` dense vector retrieval using FAISS indexing.
+- **Precision Re-ranking**: Cross-encoder scoring (`cross-encoder/ms-marco-MiniLM-L-6-v2`) for optimal document relevance.
+- **Medical Synonym Expansion**: Context-aware synonym mapping for expanded search recall.
+- **Ultra-Fast REST API**: Built on FastAPI with asynchronous request handling and Pydantic validation.
+- **Cloudflare Tunnel Ready**: Zero-trust public exposure without complex firewall configuration.
 
 ---
 
-## 1. Pipeline
-
-```text
-User Question
-      │
-      ▼
-Query Expansion            (lay terms → medical terms)
-      │
-      ▼
-Sentence Transformer Embedding
-      │
-      ▼
-FAISS Vector Search        (Top 20 candidates)
-      │
-      ▼
-Cross-Encoder Reranking    (Top 6 evidence)
-      │
-      ▼
-Near-Duplicate Removal
-      │
-      ▼
-Confidence Gate  ──reject──▶  "Insufficient evidence"
-      │ pass
-      ▼
-LLM Generation
-      │
-      ▼
-Evidence-Based Answer (with doc_id citations)
+## 🏗 System Architecture
+
+```
+                               ┌───────────────────────────┐
+                               │     Client Request        │
+                               └─────────────┬─────────────┘
+                                             │ POST /query
+                                             ▼
+                               ┌───────────────────────────┐
+                               │   FastAPI Web Server      │
+                               └─────────────┬─────────────┘
+                                             │
+                       ┌─────────────────────┴─────────────────────┐
+                       │                                           │
+                       ▼                                           ▼
+         ┌───────────────────────────┐               ┌───────────────────────────┐
+         │  Query Vectorization      │               │ Medical Synonym Expansion │
+         │  (all-MiniLM-L6-v2)       │               └─────────────┬─────────────┘
+         └─────────────┬─────────────┘                             │
+                       │                                           │
+                       └─────────────────────┬─────────────────────┘
+                                             │
+                                             ▼
+                               ┌───────────────────────────┐
+                               │     FAISS Vector Index    │
+                               └─────────────┬─────────────┘
+                                             │ Top-N Candidate Docs
+                                             ▼
+                               ┌───────────────────────────┐
+                               │   Cross-Encoder Reranker  │
+                               │  (ms-marco-MiniLM-L-6-v2) │
+                               └─────────────┬─────────────┘
+                                             │ Top-K Ranked Context
+                                             ▼
+                               ┌───────────────────────────┐
+                               │   LLM Synthesis (Groq)    │
+                               └─────────────┬─────────────┘
+                                             │
+                                             ▼
+                               ┌───────────────────────────┐
+                               │    JSON API Response      │
+                               └───────────────────────────┘
 ```
 
-## 2. Knowledge Base
+---
 
-~16,384 medical Question-Answer records with columns `Question`, `Answer`, `Category`, `doc_id`.
+## 📁 Repository Structure
 
-## 3. Retrieval
+```
+CortexRAG/
+├── API_DEPLOYMENT_PLAN.md      # Step-by-step API & tunnel setup documentation
+├── README.md                   # Hugging Face & GitHub Project Card
+├── question_embeddings.npy     # Pre-computed dense embeddings matrix
+├── questions.index             # Binary FAISS vector search index
+├── notebooks/                  # Experimental notebooks & cleaning scripts
+│   ├── Medical_RAG_Sytem.ipynb
+│   └── rag_data_cleaning.ipynb
+└── rag_model/                  # Core RAG engine configurations & resources
+    ├── rag_config.json         # Search, score & model parameters
+    ├── requirements.txt        # Python dependency specifications
+    └── models/                 # Synonyms & model metadata
+        └── medical_synonyms.json
+```
 
-- **Embedding model:** `sentence-transformers/all-MiniLM-L6-v2`, embeddings normalized so FAISS `IndexFlatIP` behaves as cosine similarity.
-- **Query Expansion:** a small lay-term → medical-term dictionary is appended to the query before embedding (e.g. `underactive thyroid → hypothyroidism`, `high blood sugar → hyperglycemia`). The original query is never replaced, only extended.
-- **Reranking:** `cross-encoder/ms-marco-MiniLM-L-6-v2` scores `(query, Answer)` — not `(query, Question)` — since many records share the same question with different answers; this identifies which *evidence* is actually useful.
-- **Evidence deduplication:** near-identical answers are collapsed via `difflib.SequenceMatcher` (threshold 0.92).
+---
 
-## 4. Confidence Gate
+## ⚡ Quick Start & Installation
 
-Evidence is only sent to the LLM if **all** conditions hold:
+### 1. Prerequisites
+- Python 3.9+
+- Pip package manager
 
-```python
-MIN_RERANK_SCORE = -8
-MIN_SIMILARITY_FLOOR = 0.40
-MIN_SUPPORT_COUNT = 2
-SUPPORT_SCORE = -5.0
+### 2. Environment Setup
+```bash
+# Clone repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/CortexRAG
+cd CortexRAG
+
+# Create virtual environment
+python -m venv venv
+# Activate on Windows:
+venv\Scripts\activate
+# Activate on Linux/macOS:
+source venv/bin/activate
+
+# Install dependencies
+pip install -r rag_model/requirements.txt fastapi uvicorn pydantic
 ```
 
-1. At least one result exists.
-2. Top rerank score ≥ `MIN_RERANK_SCORE`.
-3. Top similarity ≥ `MIN_SIMILARITY_FLOOR`.
-4. At least `MIN_SUPPORT_COUNT` results score ≥ `SUPPORT_SCORE`.
+### 3. Environment Variables
+Set your Groq API Key (or other LLM provider keys):
+```bash
+# Windows PowerShell
+$env:GROQ_API_KEY="your_groq_api_key_here"
 
-Otherwise, the system explicitly refuses to answer rather than guessing.
+# Linux/macOS
+export GROQ_API_KEY="your_groq_api_key_here"
+```
 
-## 5. Generation
+---
 
-LLM: Groq-hosted `openai/gpt-oss-20b`, instructed to answer **only** from retrieved evidence, cite sources by `[doc_id]`, flag disagreement between sources, avoid diagnosis/prescriptions, and include a medical disclaimer. API key is read from `GROQ_API_KEY` (never hard-coded).
+## 🚀 Running the Local API
 
-## 6. Example
+Start the server using `uvicorn`:
 
-**Q:** *What signs might suggest that my thyroid is not producing enough hormones?*
-**Evidence:** 6 thyroid-related records retrieved and reranked.
-**Answer:** Evidence-based summary (fatigue, feeling cold, weight gain, constipation, menstrual changes, hair loss) + disclaimer.
+```bash
+uvicorn app:app --host 127.0.0.1 --port 8000 --reload
+```
 
-**Out-of-domain example — Q:** *What is the best treatment for a broken leg?*
-Retrieval returned diabetic-foot documents (lexically similar), but the gate/LLM correctly identified them as inappropriate evidence and refused to answer — demonstrating that similarity alone doesn't guarantee relevance.
+Interactive API Documentation (Swagger UI) is available at:
+👉 **`http://127.0.0.1:8000/docs`**
 
-## 7. Evaluation Summary
+---
 
-| Metric | Result |
-|---|---:|
-| Knowledge Base Size | 16,384 records |
-| Self-Retrieval Top-1 | 100% |
-| Retrieval Recall@1 / @5 / @10 | 69.0% / 89.9% / 95.9% |
-| Retrieval MRR | 1.000 |
-| Retrieval + Reranker Recall@1 / @5 / @10 | 8.3% / 22.2% / 38.8% |
-| Retrieval + Reranker MRR | 0.237 |
-| Category Recall (retrieval / +reranker) | 97% / 98% |
-| Confidence Gate Accuracy | 88% (n=50) |
-| Example End-to-End Latency | 0.99 sec |
+## 🌐 Exposing Publicly via Cloudflare Tunnel
 
-**Key finding:** the general-purpose Cross-Encoder scores notably *worse* than plain retrieval on this duplicate-question-based benchmark. This isn't hidden — it indicates the reranker (trained for general passage relevance) doesn't align well with medical relevance judgments, and needs validation against a manually reviewed gold set before being trusted in production. A semi-automatic gold-set workflow (exact duplicates + semantic candidates ≥0.90 similarity, human-reviewed 1/0 labels) is included for this purpose; Category-match is used only as a secondary sanity check, not ground truth.
+To expose your local FastAPI server securely to the internet without port forwarding:
 
-The confidence-gate threshold was tuned via 5-fold cross-validation rather than a single split, to check stability rather than overfit to one small sample.
+1. Download [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/).
+2. Run the tunnel pointing to your local port:
+   ```bash
+   cloudflared tunnel --url http://127.0.0.1:8000
+   ```
+3. Use the generated URL (e.g. `https://xxx.trycloudflare.com`) as your public API endpoint.
 
-## 8. Limitations
+---
 
-- Knowledge base doesn't cover every condition/scenario.
-- Semantic similarity ≠ appropriate evidence (see broken-leg example).
-- Reranker not fine-tuned on this medical domain yet.
-- Manual gold set is still small — evaluation should be treated as preliminary.
-- Not for diagnosis, emergencies, prescriptions, or personalized treatment.
+## 🔌 API Reference & Integration Guide
 
-## 9. Installation
+### Endpoint
+`POST /query`
 
-```bash
-pip install sentence-transformers faiss-cpu numpy pandas openpyxl groq
+### Request Headers
+```http
+Content-Type: application/json
 ```
 
-```python
-import os
-GROQ_API_KEY = os.environ["GROQ_API_KEY"]  # never hard-code keys
+### Request Payload Example
+```json
+{
+  "question": "What are the first-line treatments for type 2 diabetes?",
+  "top_k": 6
+}
 ```
 
-## 10. Future Work
+### Response Payload Example
+```json
+{
+  "status": "success",
+  "question": "What are the first-line treatments for type 2 diabetes?",
+  "answer": "First-line pharmacological management for type 2 diabetes typically includes Metformin alongside lifestyle modifications...",
+  "retrieved_context": [
+    {
+      "doc_id": 42,
+      "text": "Metformin remains the initial drug of choice for monotherapy...",
+      "rerank_score": 4.85
+    }
+  ],
+  "execution_time_sec": 0.38
+}
+```
 
-Complete manual gold-set annotation → re-evaluate reranker against it → consider a medical-domain reranker → expand confidence-gate validation set → add citations/monitoring/auth → deploy behind a REST API → evaluate faithfulness/hallucination separately from retrieval quality.
+### Python Integration Example
+```python
+import requests
 
-## 11. Responsible Use
+url = "https://your-cloudflare-url.trycloudflare.com/query"
+payload = {
+    "question": "What are the common causes of chest pain?",
+    "top_k": 5
+}
+headers = {"Content-Type": "application/json"}
 
-Not a diagnostic tool, clinical decision-support system, prescription system, or emergency service. Consult a qualified healthcare professional for medical decisions.
+response = requests.post(url, json=payload, headers=headers)
+print(response.json())
+```
+
+---
 
-## References
+## 🛠 Configuration Parameters (`rag_config.json`)
+
+| Parameter | Default | Description |
+| :--- | :--- | :--- |
+| `embedding_model` | `all-MiniLM-L6-v2` | SentenceTransformer embedding model |
+| `reranker_model` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | Precision reranking cross-encoder model |
+| `retrieve_top_n` | `20` | Initial FAISS vector retrieval candidate count |
+| `rerank_top_k` | `6` | Number of context snippets passed to LLM |
+| `min_similarity_floor` | `0.4` | Cosine similarity threshold |
+
+---
 
-- [Sentence Transformers](https://www.sbert.net/)
-- [FAISS](https://github.com/facebookresearch/faiss)
-- [Cross-Encoder](https://www.sbert.net/examples/applications/cross-encoder/README.html)
+## 📜 License
+This project is released under the **MIT License**.

app.py

@@ -0,0 +1,376 @@
+import os
+import time
+import json
+import difflib
+from typing import List, Optional, Dict, Any
+from contextlib import asynccontextmanager
+
+import numpy as np
+import pandas as pd
+import faiss
+from sentence_transformers import SentenceTransformer, CrossEncoder
+from groq import Groq
+
+from fastapi import FastAPI, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+# ==========================================
+# Paths & Default Configurations
+# ==========================================
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+FAISS_INDEX_PATH = os.path.join(BASE_DIR, "questions.index")
+DATASET_PATH = os.path.join(BASE_DIR, "notebooks", "AHD_english_cleaned.xlsx")
+SYNONYMS_PATH = os.path.join(BASE_DIR, "rag_model", "models", "medical_synonyms.json")
+CONFIG_PATH = os.path.join(BASE_DIR, "rag_model", "rag_config.json")
+
+DEFAULT_GROQ_API_KEY = os.getenv("GROQ_API_KEY", "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")
+LLM_MODEL = os.getenv("LLM_MODEL", "openai/gpt-oss-20b")
+
+# Load config if available
+if os.path.exists(CONFIG_PATH):
+    with open(CONFIG_PATH, "r", encoding="utf-8") as f:
+        RAG_CONFIG = json.load(f)
+else:
+    RAG_CONFIG = {
+        "embedding_model": "all-MiniLM-L6-v2",
+        "reranker_model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
+        "retrieve_top_n": 20,
+        "rerank_top_k": 6,
+    }
+
+# Dynamic Global State
+rag_resources: Dict[str, Any] = {}
+
+SYSTEM_PROMPT = """
+You are a medical RAG assistant specialized ONLY in:
+- Diabetes
+- Endocrinology
+- Thyroid disorders
+- Hormonal disorders
+- Endocrine glands and related disorders
+- Nutrition, glucose management, insulin, and complications DIRECTLY related to diabetes/endocrinology
+
+You operate in STRICT RAG MODE.
+
+==================================================
+CRITICAL DOMAIN RULE
+==================================================
+The USER QUESTION itself determines whether the question is in-domain.
+A question is IN-DOMAIN only if its actual subject is diabetes, endocrinology,
+thyroid, hormones, endocrine glands/disorders, or a problem explicitly stated
+by the user to be related to diabetes/endocrinology.
+
+If the user's actual question is about another body system or another medical
+specialty, it is OUT-OF-DOMAIN.
+
+==================================================
+TYPE 1 — IN-DOMAIN MEDICAL QUESTION
+==================================================
+If and ONLY IF the USER QUESTION itself is in-domain:
+- Answer using ONLY the RETRIEVED MEDICAL EVIDENCE.
+- Do NOT use pretrained/background medical knowledge.
+- Do NOT guess or invent missing details.
+- Cite supporting [doc_id] for every medical claim.
+
+==================================================
+TYPE 2 — APP / IDENTITY QUESTIONS
+==================================================
+Only for direct questions about the assistant/application itself:
+Answer briefly and naturally.
+
+==================================================
+TYPE 3 — EVERYTHING ELSE / OUT OF DOMAIN / INSUFFICIENT EVIDENCE
+==================================================
+For ALL TYPE 3 cases, reply with ONLY one short refusal:
+If the user wrote in Arabic:
+"معرفش، السؤال ده مش جزء من تخصصي (السكر والغدد الصماء)."
+If the user wrote in English:
+"I don't know — this is outside my specialty (diabetes and endocrinology)."
+
+==================================================
+FINAL SAFETY NOTE FOR TYPE 1 ONLY
+==================================================
+At the end of every TYPE 1 medical answer, write:
+"This information is based on the available medical evidence and is for general informational purposes. It is not a diagnosis or a substitute for professional medical advice."
+"""
+
+# ==========================================
+# RAG Helper Logic
+# ==========================================
+def expand_query(query: str, synonyms: dict) -> str:
+    lower_q = query.lower()
+    extra_terms = [
+        med_term
+        for phrase, med_term in synonyms.items()
+        if phrase in lower_q and med_term not in lower_q
+    ]
+    if not extra_terms:
+        return query
+    return f"{query} ({', '.join(dict.fromkeys(extra_terms))})"
+
+def vector_search(query: str, top_n: int = 20):
+    embedder = rag_resources["embedder"]
+    faiss_index = rag_resources["faiss_index"]
+    metadata_store = rag_resources["metadata_store"]
+    synonyms = rag_resources["synonyms"]
+
+    query_for_embedding = expand_query(query, synonyms)
+    q_emb = embedder.encode(
+        [query_for_embedding],
+        convert_to_numpy=True,
+        normalize_embeddings=True
+    ).astype("float32")
+
+    scores, idxs = faiss_index.search(q_emb, top_n)
+    retrieved = []
+    for score, idx in zip(scores[0], idxs[0]):
+        if idx == -1:
+            continue
+        payload = metadata_store[int(idx)]
+        retrieved.append({
+            "doc_id": payload["doc_id"],
+            "Question": payload["question"],
+            "Answer": payload["answer"],
+            "Category": payload["category"],
+            "similarity": float(score),
+        })
+    return pd.DataFrame(retrieved)
+
+def rerank(query: str, candidates: pd.DataFrame, top_k: int = 6, alpha: float = 0.6) -> pd.DataFrame:
+    if candidates.empty:
+        return candidates
+
+    reranker = rag_resources["reranker"]
+    pairs = [
+        (query, f"Question: {row['Question']}\nAnswer: {row['Answer']}")
+        for _, row in candidates.iterrows()
+    ]
+
+    rerank_scores = reranker.predict(pairs)
+    reranked = candidates.copy()
+    reranked["rerank_score"] = rerank_scores
+
+    def norm(s):
+        s = s.astype(float)
+        rng = s.max() - s.min()
+        return (s - s.min()) / rng if rng > 0 else s * 0
+
+    reranked["sim_norm"] = norm(reranked["similarity"])
+    reranked["rerank_norm"] = norm(reranked["rerank_score"])
+    reranked["final_score"] = alpha * reranked["rerank_norm"] + (1 - alpha) * reranked["sim_norm"]
+
+    return reranked.sort_values("final_score", ascending=False).head(top_k).reset_index(drop=True)
+
+def is_near_duplicate(text_a: str, text_b: str, threshold: float = 0.92) -> bool:
+    return difflib.SequenceMatcher(None, text_a, text_b).ratio() > threshold
+
+def build_evidence(reranked: pd.DataFrame, max_answer_chars: int = 700) -> List[dict]:
+    evidence = []
+    seen_answers = []
+
+    for _, row in reranked.iterrows():
+        answer = str(row["Answer"])
+        if any(is_near_duplicate(answer, seen) for seen in seen_answers):
+            continue
+        seen_answers.append(answer)
+
+        evidence.append({
+            "doc_id": int(row["doc_id"]),
+            "question": str(row["Question"]),
+            "answer": answer[:max_answer_chars] + ("..." if len(answer) > max_answer_chars else ""),
+            "category": str(row["Category"]),
+            "similarity": round(float(row["similarity"]), 3),
+            "rerank_score": round(float(row["rerank_score"]), 3),
+        })
+    return evidence
+
+def generate_answer(query: str, user_data: str, evidence: List[dict]) -> str:
+    groq_client = rag_resources["groq_client"]
+    if not evidence:
+        return "I don't know — this is outside my specialty (diabetes and endocrinology)."
+
+    evidence_blocks = [
+        f"[{e['doc_id']}] (category: {e['category']})\nRelated question: {e['question']}\nAnswer: {e['answer']}"
+        for e in evidence
+    ]
+    evidence_text = "\n\n".join(evidence_blocks)
+
+    user_message = f"""
+USER QUESTION:
+{query}
+
+USER DATA:
+{user_data}
+
+RETRIEVED MEDICAL EVIDENCE:
+{evidence_text}
+
+TASK:
+Answer the USER QUESTION using ONLY the RETRIEVED MEDICAL EVIDENCE.
+Cite every important medical claim using the relevant [doc_id].
+If the evidence is insufficient or irrelevant, give a clear refusal.
+"""
+
+    try:
+        response = groq_client.chat.completions.create(
+            model=LLM_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_message}
+            ],
+            temperature=0.1,
+            max_tokens=800,
+        )
+        return response.choices[0].message.content
+    except Exception as e:
+        # Fallback or error handling for Groq API
+        return f"Error generating answer from LLM: {str(e)}"
+
+# ==========================================
+# FastAPI Lifecycle & App Initialization
+# ==========================================
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("Loading RAG resources...")
+
+    # Load FAISS index
+    if not os.path.exists(FAISS_INDEX_PATH):
+        raise RuntimeError(f"FAISS index file not found at: {FAISS_INDEX_PATH}")
+    faiss_index = faiss.read_index(FAISS_INDEX_PATH)
+
+    # Load Dataset for Metadata
+    if not os.path.exists(DATASET_PATH):
+        raise RuntimeError(f"Dataset file not found at: {DATASET_PATH}")
+    df = pd.read_excel(DATASET_PATH, engine="openpyxl").reset_index(drop=True)
+    df["doc_id"] = df.index
+    metadata_store = [
+        {
+            "doc_id": row["doc_id"],
+            "question": row["Question"],
+            "answer": row["Answer"],
+            "category": row["Category"],
+        }
+        for _, row in df.iterrows()
+    ]
+
+    # Load Synonyms
+    synonyms = {}
+    if os.path.exists(SYNONYMS_PATH):
+        with open(SYNONYMS_PATH, "r", encoding="utf-8") as f:
+            synonyms = json.load(f)
+
+    # Load Transformer Models
+    embedder = SentenceTransformer(RAG_CONFIG.get("embedding_model", "all-MiniLM-L6-v2"))
+    reranker = CrossEncoder(RAG_CONFIG.get("reranker_model", "cross-encoder/ms-marco-MiniLM-L-6-v2"))
+
+    # Load Groq Client
+    groq_client = Groq(api_key=DEFAULT_GROQ_API_KEY)
+
+    # Save to global state
+    rag_resources["faiss_index"] = faiss_index
+    rag_resources["metadata_store"] = metadata_store
+    rag_resources["synonyms"] = synonyms
+    rag_resources["embedder"] = embedder
+    rag_resources["reranker"] = reranker
+    rag_resources["groq_client"] = groq_client
+
+    print(f"RAG resources loaded successfully! Index size: {faiss_index.ntotal}")
+    yield
+    print("Shutting down RAG resources.")
+    rag_resources.clear()
+
+app = FastAPI(
+    title="CortexRAG Medical API",
+    description="Production-ready FastAPI interface for CortexRAG Medical Question Answering Engine.",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ==========================================
+# Request / Response Schemas
+# ==========================================
+class QueryRequest(BaseModel):
+    question: str = Field(..., example="What are the common symptoms of hypothyroidism?", min_length=2)
+    user_data: Optional[str] = Field(default="", example="Age: 45, Gender: Female")
+    top_k: Optional[int] = Field(default=6, ge=1, le=20)
+
+class EvidenceItem(BaseModel):
+    doc_id: int
+    question: str
+    answer: str
+    category: str
+    similarity: float
+    rerank_score: float
+
+class QueryResponse(BaseModel):
+    status: str
+    question: str
+    answer: str
+    evidence: List[EvidenceItem]
+    execution_time_sec: float
+
+# ==========================================
+# Endpoints
+# ==========================================
+@app.get("/", tags=["Health"])
+def root():
+    return {
+        "status": "online",
+        "service": "CortexRAG Medical API",
+        "documentation": "/docs"
+    }
+
+@app.get("/health", tags=["Health"])
+def health_check():
+    return {
+        "status": "healthy",
+        "faiss_index_entries": rag_resources.get("faiss_index", None).ntotal if "faiss_index" in rag_resources else 0,
+        "model_loaded": "embedder" in rag_resources
+    }
+
+@app.post("/predict", response_model=QueryResponse, tags=["RAG Inference"])
+@app.post("/query", response_model=QueryResponse, tags=["RAG Inference"])
+def predict(payload: QueryRequest):
+    start_time = time.time()
+
+    try:
+        # Step 1: Vector Search
+        candidates = vector_search(payload.question, top_n=RAG_CONFIG.get("retrieve_top_n", 20))
+        
+        # Step 2: Cross Encoder Rerank
+        reranked_df = rerank(payload.question, candidates, top_k=payload.top_k)
+        
+        # Step 3: Deduplicate Evidence
+        evidence = build_evidence(reranked_df)
+        
+        # Step 4: Generate LLM Answer
+        answer = generate_answer(payload.question, payload.user_data or "", evidence)
+        
+        elapsed = round(time.time() - start_time, 3)
+
+        return QueryResponse(
+            status="success",
+            question=payload.question,
+            answer=answer,
+            evidence=[EvidenceItem(**item) for item in evidence],
+            execution_time_sec=elapsed
+        )
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"An error occurred during inference: {str(e)}"
+        )
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("app:app", host="127.0.0.1", port=8000, reload=True)

cloudflared.exe

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c29eee2b121f5436a642eed69fd9767da7e7b8c510fa50aaa130337f931357b5
+size 54893480