Merge feature/production-upgrade: HF Spaces deployment with modern UI

.env.example

@@ -0,0 +1,61 @@
+# ===========================================================================
+# MediGuard AI — Environment Variables
+# ===========================================================================
+# Copy this file to .env and fill in your values.
+# ===========================================================================
+
+# --- API ---
+API__HOST=0.0.0.0
+API__PORT=8000
+API__DEBUG=true
+CORS_ALLOWED_ORIGINS=*
+
+# --- PostgreSQL ---
+POSTGRES__HOST=localhost
+POSTGRES__PORT=5432
+POSTGRES__DATABASE=mediguard
+POSTGRES__USER=mediguard
+POSTGRES__PASSWORD=mediguard_secret
+
+# --- OpenSearch ---
+OPENSEARCH__HOST=localhost
+OPENSEARCH__PORT=9200
+
+# --- Redis ---
+REDIS__HOST=localhost
+REDIS__PORT=6379
+REDIS__ENABLED=true
+
+# --- Ollama ---
+OLLAMA__BASE_URL=http://localhost:11434
+OLLAMA__MODEL=llama3.2
+
+# --- LLM (Groq / Gemini — existing providers) ---
+LLM__PRIMARY_PROVIDER=groq
+LLM__GROQ_API_KEY=
+LLM__GROQ_MODEL=llama-3.3-70b-versatile
+LLM__GEMINI_API_KEY=
+LLM__GEMINI_MODEL=gemini-2.0-flash
+
+# --- Embeddings ---
+EMBEDDING__PROVIDER=jina
+EMBEDDING__JINA_API_KEY=
+EMBEDDING__MODEL_NAME=jina-embeddings-v3
+EMBEDDING__DIMENSION=1024
+
+# --- Langfuse ---
+LANGFUSE__ENABLED=true
+LANGFUSE__PUBLIC_KEY=
+LANGFUSE__SECRET_KEY=
+LANGFUSE__HOST=http://localhost:3000
+
+# --- Chunking ---
+CHUNKING__CHUNK_SIZE=1024
+CHUNKING__CHUNK_OVERLAP=128
+
+# --- Telegram Bot (optional) ---
+TELEGRAM__BOT_TOKEN=
+TELEGRAM__API_BASE_URL=http://localhost:8000
+
+# --- Medical PDFs ---
+MEDICAL_PDFS__DIRECTORY=data/medical_pdfs

.gitattributes

@@ -0,0 +1,2 @@
+*.faiss filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -221,10 +221,13 @@ $RECYCLE.BIN/
 # Project Specific
 # ==============================================================================
 # Vector stores (large files, regenerate locally)
+# BUT allow medical_knowledge for HuggingFace deployment
 data/vector_stores/*.faiss
 data/vector_stores/*.pkl
-*.faiss
-*.pkl
+!data/vector_stores/medical_knowledge.faiss
+!data/vector_stores/medical_knowledge.pkl
+# *.faiss  # Commented out to allow medical_knowledge
+# *.pkl    # Commented out to allow medical_knowledge
 
 # Medical PDFs (proprietary/large)
 data/medical_pdfs/*.pdf

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# MediGuard AI — Pre-commit hooks
+# Install: pre-commit install
+# Run all: pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.12.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.0]
+        args: [--ignore-missing-imports]

DEPLOY_HUGGINGFACE.md

@@ -0,0 +1,203 @@
+# 🚀 Deploy MediGuard AI to Hugging Face Spaces
+
+This guide walks you through deploying MediGuard AI to Hugging Face Spaces using Docker.
+
+## Prerequisites
+
+1. **Hugging Face Account** — [Sign up free](https://huggingface.co/join)
+2. **Git** — Installed on your machine
+3. **API Key** — Either:
+   - **Groq** (recommended) — [Get free key](https://console.groq.com/keys)
+   - **Google Gemini** — [Get free key](https://aistudio.google.com/app/apikey)
+
+## Step 1: Create a New Space
+
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Fill in:
+   - **Space name**: `mediguard-ai` (or your choice)
+   - **License**: MIT
+   - **SDK**: Select **Docker**
+   - **Hardware**: **CPU Basic** (free tier works!)
+3. Click **Create Space**
+
+## Step 2: Clone Your Space
+
+```bash
+# Clone the empty space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai
+cd mediguard-ai
+```
+
+## Step 3: Copy Project Files
+
+Copy all files from this repository to your space folder:
+
+```bash
+# Option A: If you have the RagBot repo locally
+cp -r /path/to/RagBot/* .
+
+# Option B: Clone fresh
+git clone https://github.com/yourusername/ragbot temp
+cp -r temp/* .
+rm -rf temp
+```
+
+## Step 4: Set Up Dockerfile for Spaces
+
+Hugging Face Spaces expects the Dockerfile in the root. Copy the HF-optimized Dockerfile:
+
+```bash
+# Copy the HF Spaces Dockerfile to root
+cp huggingface/Dockerfile ./Dockerfile
+```
+
+**Or** update your root `Dockerfile` to match the HF Spaces version.
+
+## Step 5: Set Up README (Important!)
+
+The README.md must have the HF Spaces metadata header. Copy the HF README:
+
+```bash
+# Backup original README
+mv README.md README_original.md
+
+# Use HF Spaces README
+cp huggingface/README.md ./README.md
+```
+
+## Step 6: Add Your API Key (Secret)
+
+1. Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai`
+2. Click **Settings** tab
+3. Scroll to **Repository Secrets**
+4. Add a new secret:
+   - **Name**: `GROQ_API_KEY` (or `GOOGLE_API_KEY`)
+   - **Value**: Your API key
+5. Click **Add**
+
+## Step 7: Push to Deploy
+
+```bash
+# Add all files
+git add .
+
+# Commit
+git commit -m "Deploy MediGuard AI"
+
+# Push to Hugging Face
+git push
+```
+
+## Step 8: Monitor Deployment
+
+1. Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai`
+2. Click the **Logs** tab to watch the build
+3. Build takes ~5-10 minutes (first time)
+4. Once "Running", your app is live! 🎉
+
+## 🔧 Troubleshooting
+
+### "No LLM API key configured"
+
+- Make sure you added `GROQ_API_KEY` or `GOOGLE_API_KEY` in Space Settings → Secrets
+- Secret names are case-sensitive
+
+### Build fails with "No space disk"
+
+- Hugging Face free tier has limited disk space
+- The FAISS vector store might be too large
+- Solution: Upgrade to a paid tier or reduce vector store size
+
+### "ModuleNotFoundError"
+
+- Check that all dependencies are in `huggingface/requirements.txt`
+- The Dockerfile should install from this file
+
+### App crashes on startup
+
+- Check Logs for the actual error
+- Common issue: Missing environment variables
+- Increase Space hardware if OOM error
+
+## 📁 File Structure for Deployment
+
+Your Space should have this structure:
+
+```
+your-space/
+├── Dockerfile              # HF Spaces Dockerfile (from huggingface/)
+├── README.md               # HF Spaces README with metadata
+├── huggingface/
+│   ├── app.py              # Standalone Gradio app
+│   ├── requirements.txt    # Minimal deps for HF
+│   └── README.md           # Original HF README
+├── src/                    # Core application code
+│   ├── workflow.py
+│   ├── state.py
+│   ├── llm_config.py
+│   ├── pdf_processor.py
+│   ├── agents/
+│   └── ...
+├── data/
+│   └── vector_stores/
+│       ├── medical_knowledge.faiss
+│       └── medical_knowledge.pkl
+└── config/
+    └── biomarker_references.json
+```
+
+## 🔄 Updating Your Space
+
+To update after making changes:
+
+```bash
+git add .
+git commit -m "Update: description of changes"
+git push
+```
+
+Hugging Face will automatically rebuild and redeploy.
+
+## 💰 Hardware Options
+
+| Tier | RAM | vCPU | Cost | Best For |
+|------|-----|------|------|----------|
+| CPU Basic | 2GB | 2 | Free | Demo/Testing |
+| CPU Upgrade | 8GB | 4 | ~$0.03/hr | Production |
+| T4 Small | 16GB | 4 | ~$0.06/hr | Heavy usage |
+
+The free tier works for demos. Upgrade if you experience timeouts.
+
+## 🎉 Your Space is Live!
+
+Once deployed, share your Space URL:
+
+```
+https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai
+```
+
+Anyone can now use MediGuard AI without any setup!
+
+---
+
+## Quick Commands Reference
+
+```bash
+# Clone your space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai
+
+# Set up remote (if needed)
+git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai
+
+# Push changes
+git push origin main
+
+# Force rebuild (if stuck)
+# Go to Settings → Factory Reset
+```
+
+## Need Help?
+
+- [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces)
+- [Docker on Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Spaces Secrets](https://huggingface.co/docs/hub/spaces-secrets)

Dockerfile

@@ -0,0 +1,66 @@
+# ===========================================================================
+# MediGuard AI — Hugging Face Spaces Dockerfile
+# ===========================================================================
+# Optimized single-container deployment for Hugging Face Spaces.
+# Uses FAISS vector store + Cloud LLMs (Groq/Gemini) - no external services.
+# ===========================================================================
+
+FROM python:3.11-slim
+
+# Non-interactive apt
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Python settings
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# HuggingFace Spaces runs on port 7860
+ENV GRADIO_SERVER_NAME="0.0.0.0" \
+    GRADIO_SERVER_PORT=7860
+
+# Default to HuggingFace embeddings (local, no API key needed)
+ENV EMBEDDING_PROVIDER=huggingface
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        git \
+        && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (cache layer)
+COPY huggingface/requirements.txt ./requirements.txt
+RUN pip install --upgrade pip && \
+    pip install -r requirements.txt
+
+# Copy the entire project
+COPY . .
+
+# Create necessary directories and ensure vector store exists
+RUN mkdir -p data/medical_pdfs data/vector_stores data/chat_reports
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+
+# Make app writable by user
+RUN chown -R user:user /app
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD curl -sf http://localhost:7860/ || exit 1
+
+# Launch Gradio app
+CMD ["python", "huggingface/app.py"]

Makefile

@@ -0,0 +1,137 @@
+# ===========================================================================
+# MediGuard AI — Makefile
+# ===========================================================================
+# Usage:
+#   make help         — show all targets
+#   make setup        — install deps + pre-commit hooks
+#   make dev          — run API in dev mode with reload
+#   make test         — run full test suite
+#   make lint         — ruff check + mypy
+#   make docker-up    — spin up all Docker services
+#   make docker-down  — tear down Docker services
+# ===========================================================================
+
+.DEFAULT_GOAL := help
+SHELL := /bin/bash
+
+# Python / UV
+PYTHON ?= python
+UV     ?= uv
+PIP    ?= pip
+
+# Docker
+COMPOSE := docker compose
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+.PHONY: help
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# ---------------------------------------------------------------------------
+# Setup
+# ---------------------------------------------------------------------------
+.PHONY: setup
+setup: ## Install all deps (pip) + pre-commit hooks
+	$(PIP) install -e ".[all]"
+	pre-commit install
+
+.PHONY: setup-uv
+setup-uv: ## Install all deps with UV
+	$(UV) pip install -e ".[all]"
+	pre-commit install
+
+# ---------------------------------------------------------------------------
+# Development
+# ---------------------------------------------------------------------------
+.PHONY: dev
+dev: ## Run API in dev mode (auto-reload)
+	uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
+
+.PHONY: gradio
+gradio: ## Launch Gradio web UI
+	$(PYTHON) -m src.gradio_app
+
+.PHONY: telegram
+telegram: ## Start Telegram bot
+	$(PYTHON) -c "from src.services.telegram.bot import MediGuardTelegramBot; MediGuardTelegramBot().run()"
+
+# ---------------------------------------------------------------------------
+# Quality
+# ---------------------------------------------------------------------------
+.PHONY: lint
+lint: ## Ruff check + MyPy
+	ruff check src/ tests/
+	mypy src/ --ignore-missing-imports
+
+.PHONY: format
+format: ## Ruff format
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+.PHONY: test
+test: ## Run pytest with coverage
+	pytest tests/ -v --tb=short --cov=src --cov-report=term-missing
+
+.PHONY: test-quick
+test-quick: ## Run only fast unit tests
+	pytest tests/ -v --tb=short -m "not slow"
+
+# ---------------------------------------------------------------------------
+# Docker
+# ---------------------------------------------------------------------------
+.PHONY: docker-up
+docker-up: ## Start all Docker services (detached)
+	$(COMPOSE) up -d
+
+.PHONY: docker-down
+docker-down: ## Stop and remove Docker services
+	$(COMPOSE) down -v
+
+.PHONY: docker-build
+docker-build: ## Build Docker images
+	$(COMPOSE) build
+
+.PHONY: docker-logs
+docker-logs: ## Tail Docker logs
+	$(COMPOSE) logs -f
+
+# ---------------------------------------------------------------------------
+# Database
+# ---------------------------------------------------------------------------
+.PHONY: db-upgrade
+db-upgrade: ## Run Alembic migrations
+	alembic upgrade head
+
+.PHONY: db-revision
+db-revision: ## Create a new Alembic migration
+	alembic revision --autogenerate -m "$(msg)"
+
+# ---------------------------------------------------------------------------
+# Indexing
+# ---------------------------------------------------------------------------
+.PHONY: index-pdfs
+index-pdfs: ## Parse and index all medical PDFs
+	$(PYTHON) -c "\
+from pathlib import Path; \
+from src.services.pdf_parser.service import make_pdf_parser_service; \
+from src.services.indexing.service import IndexingService; \
+from src.services.embeddings.service import make_embedding_service; \
+from src.services.opensearch.client import make_opensearch_client; \
+parser = make_pdf_parser_service(); \
+idx = IndexingService(make_embedding_service(), make_opensearch_client()); \
+docs = parser.parse_directory(Path('data/medical_pdfs')); \
+[idx.index_text(d.full_text, {'title': d.filename}) for d in docs if d.full_text]; \
+print(f'Indexed {len(docs)} documents')"
+
+# ---------------------------------------------------------------------------
+# Clean
+# ---------------------------------------------------------------------------
+.PHONY: clean
+clean: ## Remove build artifacts and caches
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+	rm -rf dist/ build/ *.egg-info

README.md

@@ -1,3 +1,22 @@
+---
+title: Agentic RagBot
+emoji: 🏥
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: true
+license: mit
+app_port: 7860
+tags:
+  - medical
+  - biomarker
+  - rag
+  - healthcare
+  - langgraph
+  - agents
+short_description: Multi-Agent RAG System for Medical Biomarker Analysis
+---
+
 # RagBot: Multi-Agent RAG System for Medical Biomarker Analysis
 
 A production-ready biomarker analysis system combining 6 specialized AI agents with medical knowledge retrieval to provide evidence-based insights on blood test results in **15-25 seconds**.

airflow/dags/ingest_pdfs.py

@@ -0,0 +1,64 @@
+"""
+MediGuard AI — Airflow DAG: Ingest Medical PDFs
+
+Periodically scans the medical_pdfs directory, parses new PDFs,
+chunks them, generates embeddings, and indexes into OpenSearch.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from airflow import DAG
+from airflow.operators.python import PythonOperator
+
+default_args = {
+    "owner": "mediguard",
+    "retries": 2,
+    "retry_delay": timedelta(minutes=5),
+    "email_on_failure": False,
+}
+
+
+def _ingest_pdfs(**kwargs):
+    """Parse all PDFs and index into OpenSearch."""
+    from pathlib import Path
+
+    from src.services.embeddings.service import make_embedding_service
+    from src.services.indexing.service import IndexingService
+    from src.services.opensearch.client import make_opensearch_client
+    from src.services.pdf_parser.service import make_pdf_parser_service
+    from src.settings import get_settings
+
+    settings = get_settings()
+    pdf_dir = Path(settings.medical_pdfs.directory)
+
+    parser = make_pdf_parser_service()
+    embedding_svc = make_embedding_service()
+    os_client = make_opensearch_client()
+    indexing_svc = IndexingService(embedding_svc, os_client)
+
+    docs = parser.parse_directory(pdf_dir)
+    indexed = 0
+    for doc in docs:
+        if doc.full_text and not doc.error:
+            indexing_svc.index_text(doc.full_text, {"title": doc.filename})
+            indexed += 1
+
+    print(f"Ingested {indexed}/{len(docs)} documents")
+    return {"total": len(docs), "indexed": indexed}
+
+
+with DAG(
+    dag_id="mediguard_ingest_pdfs",
+    default_args=default_args,
+    description="Parse and index medical PDFs into OpenSearch",
+    schedule="@daily",
+    start_date=datetime(2025, 1, 1),
+    catchup=False,
+    tags=["mediguard", "indexing"],
+) as dag:
+    ingest = PythonOperator(
+        task_id="ingest_medical_pdfs",
+        python_callable=_ingest_pdfs,
+    )

airflow/dags/sop_evolution.py

@@ -0,0 +1,43 @@
+"""
+MediGuard AI — Airflow DAG: SOP Evolution Cycle
+
+Runs the evolutionary SOP optimisation loop periodically.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from airflow import DAG
+from airflow.operators.python import PythonOperator
+
+default_args = {
+    "owner": "mediguard",
+    "retries": 1,
+    "retry_delay": timedelta(minutes=10),
+    "email_on_failure": False,
+}
+
+
+def _run_evolution(**kwargs):
+    """Execute one SOP evolution cycle."""
+    from src.evolution.director import run_evolution_cycle
+
+    result = run_evolution_cycle()
+    print(f"Evolution cycle complete: {result}")
+    return result
+
+
+with DAG(
+    dag_id="mediguard_sop_evolution",
+    default_args=default_args,
+    description="Run SOP evolutionary optimisation",
+    schedule="@weekly",
+    start_date=datetime(2025, 1, 1),
+    catchup=False,
+    tags=["mediguard", "evolution"],
+) as dag:
+    evolve = PythonOperator(
+        task_id="run_sop_evolution",
+        python_callable=_run_evolution,
+    )

alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

alembic/env.py

@@ -0,0 +1,95 @@
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool, create_engine
+
+from alembic import context
+
+# ---------------------------------------------------------------------------
+# MediGuard AI — Alembic env.py
+# Pull DB URL from settings so we never hard-code credentials.
+# ---------------------------------------------------------------------------
+import sys
+import os
+
+# Make sure the project root is on sys.path
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from src.settings import get_settings  # noqa: E402
+from src.database import Base  # noqa: E402
+
+# Import all models so Alembic's autogenerate can see them
+import src.models.analysis  # noqa: F401, E402
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Override sqlalchemy.url from our Pydantic Settings
+_settings = get_settings()
+config.set_main_option("sqlalchemy.url", _settings.postgres.database_url)
+
+# Metadata used for autogenerate
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

data/vector_stores/medical_knowledge.faiss

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

data/vector_stores/medical_knowledge.pkl

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

docker-compose.yml

@@ -0,0 +1,168 @@
+# ===========================================================================
+# MediGuard AI — Docker Compose (development / CI)
+# ===========================================================================
+# Usage:
+#   docker compose up -d          — start all services
+#   docker compose down -v        — stop and remove volumes
+#   docker compose logs -f api    — follow API logs
+# ===========================================================================
+
+services:
+  # -----------------------------------------------------------------------
+  # Application
+  # -----------------------------------------------------------------------
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    container_name: mediguard-api
+    ports:
+      - "${API_PORT:-8000}:8000"
+    env_file: .env
+    environment:
+      - POSTGRES__HOST=postgres
+      - OPENSEARCH__HOST=opensearch
+      - OPENSEARCH__PORT=9200
+      - REDIS__HOST=redis
+      - REDIS__PORT=6379
+      - OLLAMA__BASE_URL=http://ollama:11434
+      - LANGFUSE__HOST=http://langfuse:3000
+    depends_on:
+      postgres:
+        condition: service_healthy
+      opensearch:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      - ./data/medical_pdfs:/app/data/medical_pdfs:ro
+    restart: unless-stopped
+
+  gradio:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    container_name: mediguard-gradio
+    command: python -m src.gradio_app
+    ports:
+      - "${GRADIO_PORT:-7860}:7860"
+    environment:
+      - MEDIGUARD_API_URL=http://api:8000
+    depends_on:
+      - api
+    restart: unless-stopped
+
+  # -----------------------------------------------------------------------
+  # Backing services
+  # -----------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    container_name: mediguard-postgres
+    environment:
+      POSTGRES_DB: ${POSTGRES__DATABASE:-mediguard}
+      POSTGRES_USER: ${POSTGRES__USER:-mediguard}
+      POSTGRES_PASSWORD: ${POSTGRES__PASSWORD:-mediguard_secret}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U mediguard"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    restart: unless-stopped
+
+  opensearch:
+    image: opensearchproject/opensearch:2.11.1
+    container_name: mediguard-opensearch
+    environment:
+      - discovery.type=single-node
+      - DISABLE_SECURITY_PLUGIN=true
+      - plugins.security.disabled=true
+      - "OPENSEARCH_JAVA_OPTS=-Xms256m -Xmx256m"
+      - bootstrap.memory_lock=true
+    ulimits:
+      memlock: { soft: -1, hard: -1 }
+      nofile: { soft: 65536, hard: 65536 }
+    ports:
+      - "${OPENSEARCH_PORT:-9200}:9200"
+    volumes:
+      - os_data:/usr/share/opensearch/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 24
+    restart: unless-stopped
+
+  # opensearch-dashboards: disabled by default — uncomment if you need the UI
+  # opensearch-dashboards:
+  #   image: opensearchproject/opensearch-dashboards:2.11.1
+  #   container_name: mediguard-os-dashboards
+  #   environment:
+  #     - OPENSEARCH_HOSTS=["http://opensearch:9200"]
+  #     - DISABLE_SECURITY_DASHBOARDS_PLUGIN=true
+  #   ports:
+  #     - "${OS_DASHBOARDS_PORT:-5601}:5601"
+  #   depends_on:
+  #     opensearch:
+  #       condition: service_healthy
+  #   restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    container_name: mediguard-redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    container_name: mediguard-ollama
+    ports:
+      - "${OLLAMA_PORT:-11434}:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+    # Uncomment for GPU support:
+    # deploy:
+    #   resources:
+    #     reservations:
+    #       devices:
+    #         - driver: nvidia
+    #           count: 1
+    #           capabilities: [gpu]
+
+  # -----------------------------------------------------------------------
+  # Observability
+  # -----------------------------------------------------------------------
+  langfuse:
+    image: langfuse/langfuse:2
+    container_name: mediguard-langfuse
+    environment:
+      - DATABASE_URL=postgresql://mediguard:mediguard_secret@postgres:5432/langfuse
+      - NEXTAUTH_URL=http://localhost:3000
+      - NEXTAUTH_SECRET=mediguard-langfuse-secret-change-me
+      - SALT=mediguard-langfuse-salt-change-me
+    ports:
+      - "${LANGFUSE_PORT:-3000}:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  pg_data:
+  os_data:
+  redis_data:
+  ollama_data:

huggingface/.env.example

@@ -0,0 +1,21 @@
+# ===========================================================================
+# MediGuard AI — HuggingFace Spaces Environment Variables
+# ===========================================================================
+# MINIMAL config for HuggingFace Spaces deployment.
+# Only the LLM API key is required — everything else has sensible defaults.
+# ===========================================================================
+
+# --- LLM Provider (choose ONE) ---
+# Option 1: Groq (RECOMMENDED - fast, free)
+GROQ_API_KEY=your_groq_api_key_here
+
+# Option 2: Google Gemini (alternative free option)
+# GOOGLE_API_KEY=your_google_api_key_here
+
+# --- Provider Selection (auto-detected from keys) ---
+LLM_PROVIDER=groq
+
+# --- Embedding Provider (must match vector store) ---
+# The bundled vector store uses HuggingFace embeddings (384 dim)
+# DO NOT CHANGE THIS unless you rebuild the vector store!
+EMBEDDING_PROVIDER=huggingface

huggingface/Dockerfile

@@ -0,0 +1,66 @@
+# ===========================================================================
+# MediGuard AI — Hugging Face Spaces Dockerfile
+# ===========================================================================
+# Optimized single-container deployment for Hugging Face Spaces.
+# Uses FAISS vector store + Cloud LLMs (Groq/Gemini) - no external services.
+# ===========================================================================
+
+FROM python:3.11-slim
+
+# Non-interactive apt
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Python settings
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# HuggingFace Spaces runs on port 7860
+ENV GRADIO_SERVER_NAME="0.0.0.0" \
+    GRADIO_SERVER_PORT=7860
+
+# Default to HuggingFace embeddings (local, no API key needed)
+ENV EMBEDDING_PROVIDER=huggingface
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        git \
+        && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (cache layer)
+COPY huggingface/requirements.txt ./requirements.txt
+RUN pip install --upgrade pip && \
+    pip install -r requirements.txt
+
+# Copy the entire project
+COPY . .
+
+# Create necessary directories and ensure vector store exists
+RUN mkdir -p data/medical_pdfs data/vector_stores data/chat_reports
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+
+# Make app writable by user
+RUN chown -R user:user /app
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD curl -sf http://localhost:7860/ || exit 1
+
+# Launch Gradio app
+CMD ["python", "huggingface/app.py"]

huggingface/README.md

@@ -0,0 +1,109 @@
+---
+title: Agentic RagBot
+emoji: 🏥
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: true
+license: mit
+app_port: 7860
+tags:
+  - medical
+  - biomarker
+  - rag
+  - healthcare
+  - langgraph
+  - agents
+short_description: Multi-Agent RAG System for Medical Biomarker Analysis
+---
+
+# 🏥 MediGuard AI — Medical Biomarker Analysis
+
+A production-ready **Multi-Agent RAG System** that analyzes blood test biomarkers using 6 specialized AI agents with medical knowledge retrieval.
+
+## ✨ Features
+
+- **6 Specialist AI Agents** — Biomarker validation, disease prediction, RAG-powered analysis, confidence assessment
+- **Medical Knowledge Base** — 750+ pages of clinical guidelines (FAISS vector store)
+- **Evidence-Based** — All recommendations backed by retrieved medical literature
+- **Free Cloud LLMs** — Uses Groq (LLaMA 3.3-70B) or Google Gemini
+
+## 🚀 Quick Start
+
+1. **Enter your biomarkers** in any format:
+   - `Glucose: 140, HbA1c: 7.5`
+   - `My glucose is 140 and HbA1c is 7.5`
+   - `{"Glucose": 140, "HbA1c": 7.5}`
+
+2. **Click Analyze** and get:
+   - Primary diagnosis with confidence score
+   - Critical alerts and safety flags
+   - Biomarker analysis with normal ranges
+   - Evidence-based recommendations
+   - Disease pathophysiology explanation
+
+## 🔧 Configuration
+
+This Space requires an LLM API key. Add one of these secrets in Space Settings:
+
+| Secret | Provider | Get Free Key |
+|--------|----------|--------------|
+| `GROQ_API_KEY` | Groq (recommended) | [console.groq.com/keys](https://console.groq.com/keys) |
+| `GOOGLE_API_KEY` | Google Gemini | [aistudio.google.com](https://aistudio.google.com/app/apikey) |
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Clinical Insight Guild                 │
+├─────────────────────────────────────────────────────────┤
+│  ┌───────────────────────────────────────────────────┐  │
+│  │           1. Biomarker Analyzer                    │  │
+│  │     Validates values, flags abnormalities          │  │
+│  └───────────────────┬───────────────────────────────┘  │
+│                      │                                   │
+│         ┌────────────┼────────────┐                     │
+│         ▼            ▼            ▼                     │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐                │
+│  │ Disease  │ │Biomarker │ │ Clinical │                │
+│  │Explainer │ │ Linker   │ │Guidelines│                │
+│  │  (RAG)   │ │          │ │  (RAG)   │                │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘                │
+│       │            │            │                       │
+│       └────────────┼────────────┘                       │
+│                    ▼                                    │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │          4. Confidence Assessor                    │  │
+│  │     Evaluates reliability, assigns scores          │  │
+│  └───────────────────┬───────────────────────────────┘  │
+│                      ▼                                   │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │          5. Response Synthesizer                   │  │
+│  │     Compiles patient-friendly summary              │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 📊 Supported Biomarkers
+
+| Category | Biomarkers |
+|----------|------------|
+| **Diabetes** | Glucose, HbA1c, Fasting Glucose, Insulin |
+| **Lipids** | Cholesterol, LDL, HDL, Triglycerides |
+| **Kidney** | Creatinine, BUN, eGFR |
+| **Liver** | ALT, AST, Bilirubin, Albumin |
+| **Thyroid** | TSH, T3, T4, Free T4 |
+| **Blood** | Hemoglobin, WBC, RBC, Platelets |
+| **Cardiac** | Troponin, BNP, CRP |
+
+## ⚠️ Medical Disclaimer
+
+This tool is for **informational purposes only** and does not replace professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare provider with questions regarding a medical condition.
+
+## 📄 License
+
+MIT License — See [GitHub Repository](https://github.com/yourusername/ragbot) for details.
+
+## 🙏 Acknowledgments
+
+Built with [LangGraph](https://langchain-ai.github.io/langgraph/), [FAISS](https://faiss.ai/), [Gradio](https://gradio.app/), and [Groq](https://groq.com/).

huggingface/app.py

@@ -0,0 +1,1025 @@
+"""
+MediGuard AI — Hugging Face Spaces Gradio App
+
+Standalone deployment that uses:
+- FAISS vector store (local)
+- Cloud LLMs (Groq or Gemini - FREE tiers)
+- No external services required
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Optional
+
+# Ensure project root is in path
+_project_root = str(Path(__file__).parent.parent)
+if _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
+os.chdir(_project_root)
+
+import gradio as gr
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(name)-20s | %(levelname)-7s | %(message)s",
+)
+logger = logging.getLogger("mediguard.huggingface")
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+def get_api_keys():
+    """Get API keys dynamically (HuggingFace injects secrets after module load)."""
+    groq_key = os.getenv("GROQ_API_KEY", "")
+    google_key = os.getenv("GOOGLE_API_KEY", "")
+    return groq_key, google_key
+
+
+def setup_llm_provider():
+    """Set LLM provider based on available keys."""
+    groq_key, google_key = get_api_keys()
+    
+    if groq_key:
+        os.environ["LLM_PROVIDER"] = "groq"
+        os.environ["GROQ_API_KEY"] = groq_key  # Ensure it's set
+        return "groq"
+    elif google_key:
+        os.environ["LLM_PROVIDER"] = "gemini"
+        os.environ["GOOGLE_API_KEY"] = google_key
+        return "gemini"
+    return None
+
+
+# Log status at startup (keys may not be available yet)
+_groq, _google = get_api_keys()
+if not _groq and not _google:
+    logger.warning(
+        "No LLM API key found at startup. Will check again when analyzing."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Guild Initialization (lazy)
+# ---------------------------------------------------------------------------
+
+_guild = None
+_guild_error = None
+_guild_provider = None  # Track which provider was used
+
+
+def reset_guild():
+    """Reset guild to force re-initialization (e.g., when API key changes)."""
+    global _guild, _guild_error, _guild_provider
+    _guild = None
+    _guild_error = None
+    _guild_provider = None
+
+
+def get_guild():
+    """Lazy initialization of the Clinical Insight Guild."""
+    global _guild, _guild_error, _guild_provider
+    
+    # Check if we need to reinitialize (provider changed)
+    current_provider = os.getenv("LLM_PROVIDER")
+    if _guild_provider and _guild_provider != current_provider:
+        logger.info(f"Provider changed from {_guild_provider} to {current_provider}, reinitializing...")
+        reset_guild()
+    
+    if _guild is not None:
+        return _guild
+    
+    if _guild_error is not None:
+        # Don't cache errors forever - allow retry
+        logger.warning("Previous initialization failed, retrying...")
+        _guild_error = None
+    
+    try:
+        logger.info("Initializing Clinical Insight Guild...")
+        logger.info(f"LLM_PROVIDER={os.getenv('LLM_PROVIDER')}")
+        logger.info(f"GROQ_API_KEY={'set' if os.getenv('GROQ_API_KEY') else 'NOT SET'}")
+        logger.info(f"GOOGLE_API_KEY={'set' if os.getenv('GOOGLE_API_KEY') else 'NOT SET'}")
+        
+        start = time.time()
+        
+        from src.workflow import create_guild
+        _guild = create_guild()
+        _guild_provider = current_provider
+        
+        elapsed = time.time() - start
+        logger.info(f"Guild initialized in {elapsed:.1f}s")
+        return _guild
+        
+    except Exception as exc:
+        logger.error(f"Failed to initialize guild: {exc}")
+        _guild_error = exc
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Analysis Functions
+# ---------------------------------------------------------------------------
+
+def parse_biomarkers(text: str) -> dict[str, float]:
+    """
+    Parse biomarkers from natural language text.
+    
+    Supports formats like:
+    - "Glucose: 140, HbA1c: 7.5"
+    - "glucose 140 hba1c 7.5"
+    - {"Glucose": 140, "HbA1c": 7.5}
+    """
+    text = text.strip()
+    
+    # Try JSON first
+    if text.startswith("{"):
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            pass
+    
+    # Parse natural language
+    import re
+    
+    # Common biomarker patterns
+    patterns = [
+        # "Glucose: 140" or "Glucose = 140"
+        r"([A-Za-z0-9_]+)\s*[:=]\s*([\d.]+)",
+        # "Glucose 140 mg/dL"
+        r"([A-Za-z0-9_]+)\s+([\d.]+)\s*(?:mg/dL|mmol/L|%|g/dL|U/L|mIU/L)?",
+    ]
+    
+    biomarkers = {}
+    
+    for pattern in patterns:
+        matches = re.findall(pattern, text, re.IGNORECASE)
+        for name, value in matches:
+            try:
+                biomarkers[name.strip()] = float(value)
+            except ValueError:
+                continue
+    
+    return biomarkers
+
+
+def analyze_biomarkers(input_text: str, progress=gr.Progress()) -> tuple[str, str, str]:
+    """
+    Analyze biomarkers using the Clinical Insight Guild.
+    
+    Returns: (summary, details_json, status)
+    """
+    if not input_text.strip():
+        return "", "", """
+<div style="background: linear-gradient(135deg, #f0f4f8 0%, #e2e8f0 100%); border: 1px solid #cbd5e1; border-radius: 10px; padding: 16px; text-align: center;">
+    <span style="font-size: 2em;">✍️</span>
+    <p style="margin: 8px 0 0 0; color: #64748b;">Please enter biomarkers to analyze.</p>
+</div>
+        """
+    
+    # Check API key dynamically (HF injects secrets after startup)
+    groq_key, google_key = get_api_keys()
+    
+    if not groq_key and not google_key:
+        return "", "", """
+<div style="background: linear-gradient(135deg, #fee2e2 0%, #fecaca 100%); border: 1px solid #ef4444; border-radius: 10px; padding: 16px;">
+    <strong style="color: #dc2626;">❌ No API Key Configured</strong>
+    <p style="margin: 12px 0 8px 0; color: #991b1b;">Please add your API key in Space Settings → Secrets:</p>
+    <ul style="margin: 0; color: #7f1d1d;">
+        <li><code>GROQ_API_KEY</code> - <a href="https://console.groq.com/keys" target="_blank" style="color: #2563eb;">Get free key →</a></li>
+        <li><code>GOOGLE_API_KEY</code> - <a href="https://aistudio.google.com/app/apikey" target="_blank" style="color: #2563eb;">Get free key →</a></li>
+    </ul>
+</div>
+        """
+    
+    # Setup provider based on available key
+    provider = setup_llm_provider()
+    logger.info(f"Using LLM provider: {provider}")
+    
+    try:
+        progress(0.1, desc="📝 Parsing biomarkers...")
+        biomarkers = parse_biomarkers(input_text)
+        
+        if not biomarkers:
+            return "", "", """
+<div style="background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%); border: 1px solid #fbbf24; border-radius: 10px; padding: 16px;">
+    <strong>⚠️ Could not parse biomarkers</strong>
+    <p style="margin: 8px 0 0 0; color: #92400e;">Try formats like:</p>
+    <ul style="margin: 8px 0 0 0; color: #92400e;">
+        <li><code>Glucose: 140, HbA1c: 7.5</code></li>
+        <li><code>{"Glucose": 140, "HbA1c": 7.5}</code></li>
+    </ul>
+</div>
+            """
+        
+        progress(0.2, desc="🔧 Initializing AI agents...")
+        
+        # Initialize guild
+        guild = get_guild()
+        
+        # Prepare input
+        from src.state import PatientInput
+        
+        # Auto-generate prediction based on common patterns
+        prediction = auto_predict(biomarkers)
+        
+        patient_input = PatientInput(
+            biomarkers=biomarkers,
+            model_prediction=prediction,
+            patient_context={"patient_id": "HF_User", "source": "huggingface_spaces"}
+        )
+        
+        progress(0.4, desc="🤖 Running Clinical Insight Guild...")
+        
+        # Run analysis
+        start = time.time()
+        result = guild.run(patient_input)
+        elapsed = time.time() - start
+        
+        progress(0.9, desc="✨ Formatting results...")
+        
+        # Extract response
+        final_response = result.get("final_response", {})
+        
+        # Format summary
+        summary = format_summary(final_response, elapsed)
+        
+        # Format details
+        details = json.dumps(final_response, indent=2, default=str)
+        
+        status = f"""
+<div style="background: linear-gradient(135deg, #d1fae5 0%, #a7f3d0 100%); border: 1px solid #10b981; border-radius: 10px; padding: 12px; display: flex; align-items: center; gap: 10px;">
+    <span style="font-size: 1.5em;">✅</span>
+    <div>
+        <strong style="color: #047857;">Analysis Complete</strong>
+        <span style="color: #065f46; margin-left: 8px;">({elapsed:.1f}s)</span>
+    </div>
+</div>
+        """
+        
+        return summary, details, status
+        
+    except Exception as exc:
+        logger.error(f"Analysis error: {exc}", exc_info=True)
+        error_msg = f"""
+<div style="background: linear-gradient(135deg, #fee2e2 0%, #fecaca 100%); border: 1px solid #ef4444; border-radius: 10px; padding: 16px;">
+    <strong style="color: #dc2626;">❌ Analysis Error</strong>
+    <p style="margin: 8px 0 0 0; color: #991b1b;">{exc}</p>
+    <details style="margin-top: 12px;">
+        <summary style="cursor: pointer; color: #7f1d1d;">Show details</summary>
+        <pre style="margin-top: 8px; padding: 12px; background: #fef2f2; border-radius: 6px; overflow-x: auto; font-size: 0.8em;">{traceback.format_exc()}</pre>
+    </details>
+</div>
+        """
+        return "", "", error_msg
+
+
+def auto_predict(biomarkers: dict[str, float]) -> dict[str, Any]:
+    """
+    Auto-generate a disease prediction based on biomarkers.
+    This simulates what an ML model would provide.
+    """
+    # Normalize biomarker names for matching
+    normalized = {k.lower().replace(" ", ""): v for k, v in biomarkers.items()}
+    
+    # Check for diabetes indicators
+    glucose = normalized.get("glucose", normalized.get("fastingglucose", 0))
+    hba1c = normalized.get("hba1c", normalized.get("hemoglobina1c", 0))
+    
+    if hba1c >= 6.5 or glucose >= 126:
+        return {
+            "disease": "Diabetes",
+            "confidence": min(0.95, 0.7 + (hba1c - 6.5) * 0.1) if hba1c else 0.85,
+            "severity": "high" if hba1c >= 8 or glucose >= 200 else "moderate"
+        }
+    
+    # Check for lipid disorders
+    cholesterol = normalized.get("cholesterol", normalized.get("totalcholesterol", 0))
+    ldl = normalized.get("ldl", normalized.get("ldlcholesterol", 0))
+    triglycerides = normalized.get("triglycerides", 0)
+    
+    if cholesterol >= 240 or ldl >= 160 or triglycerides >= 200:
+        return {
+            "disease": "Dyslipidemia",
+            "confidence": 0.85,
+            "severity": "moderate"
+        }
+    
+    # Check for anemia
+    hemoglobin = normalized.get("hemoglobin", normalized.get("hgb", normalized.get("hb", 0)))
+    
+    if hemoglobin and hemoglobin < 12:
+        return {
+            "disease": "Anemia",
+            "confidence": 0.80,
+            "severity": "moderate"
+        }
+    
+    # Check for thyroid issues
+    tsh = normalized.get("tsh", 0)
+    
+    if tsh > 4.5:
+        return {
+            "disease": "Hypothyroidism",
+            "confidence": 0.75,
+            "severity": "moderate"
+        }
+    elif tsh and tsh < 0.4:
+        return {
+            "disease": "Hyperthyroidism",
+            "confidence": 0.75,
+            "severity": "moderate"
+        }
+    
+    # Default - general health screening
+    return {
+        "disease": "General Health Screening",
+        "confidence": 0.70,
+        "severity": "low"
+    }
+
+
+def format_summary(response: dict, elapsed: float) -> str:
+    """Format the analysis response as beautiful HTML/markdown."""
+    if not response:
+        return """
+<div style="text-align: center; padding: 40px; color: #94a3b8;">
+    <div style="font-size: 3em;">❌</div>
+    <p>No analysis results available.</p>
+</div>
+        """
+    
+    parts = []
+    
+    # Header with primary finding and confidence
+    primary = response.get("primary_finding", "Analysis Complete")
+    confidence = response.get("confidence", {})
+    conf_score = confidence.get("overall_score", 0) if isinstance(confidence, dict) else 0
+    
+    # Determine severity color
+    severity = response.get("severity", "low")
+    severity_colors = {
+        "critical": ("#dc2626", "#fef2f2", "🔴"),
+        "high": ("#ea580c", "#fff7ed", "🟠"),
+        "moderate": ("#ca8a04", "#fefce8", "🟡"),
+        "low": ("#16a34a", "#f0fdf4", "🟢")
+    }
+    color, bg_color, emoji = severity_colors.get(severity, severity_colors["low"])
+    
+    # Confidence badge
+    conf_badge = ""
+    if conf_score:
+        conf_pct = int(conf_score * 100)
+        conf_color = "#16a34a" if conf_pct >= 80 else "#ca8a04" if conf_pct >= 60 else "#dc2626"
+        conf_badge = f'<span style="background: {conf_color}; color: white; padding: 4px 12px; border-radius: 20px; font-size: 0.85em; margin-left: 12px;">{conf_pct}% confidence</span>'
+    
+    parts.append(f"""
+<div style="background: linear-gradient(135deg, {bg_color} 0%, white 100%); border-left: 4px solid {color}; border-radius: 12px; padding: 20px; margin-bottom: 20px;">
+    <div style="display: flex; align-items: center; flex-wrap: wrap;">
+        <span style="font-size: 1.5em; margin-right: 12px;">{emoji}</span>
+        <h2 style="margin: 0; color: {color}; font-size: 1.4em;">{primary}</h2>
+        {conf_badge}
+    </div>
+</div>
+    """)
+    
+    # Critical Alerts
+    alerts = response.get("safety_alerts", [])
+    if alerts:
+        alert_items = ""
+        for alert in alerts[:5]:
+            if isinstance(alert, dict):
+                alert_items += f'<li><strong>{alert.get("alert_type", "Alert")}:</strong> {alert.get("message", "")}</li>'
+            else:
+                alert_items += f'<li>{alert}</li>'
+        
+        parts.append(f"""
+<div style="background: linear-gradient(135deg, #fef2f2 0%, #fee2e2 100%); border: 1px solid #fecaca; border-radius: 12px; padding: 16px; margin-bottom: 16px;">
+    <h4 style="margin: 0 0 12px 0; color: #dc2626; display: flex; align-items: center; gap: 8px;">
+        ⚠️ Critical Alerts
+    </h4>
+    <ul style="margin: 0; padding-left: 20px; color: #991b1b;">{alert_items}</ul>
+</div>
+        """)
+    
+    # Key Findings
+    findings = response.get("key_findings", [])
+    if findings:
+        finding_items = "".join([f'<li style="margin-bottom: 8px;">{f}</li>' for f in findings[:5]])
+        parts.append(f"""
+<div style="background: #f8fafc; border-radius: 12px; padding: 16px; margin-bottom: 16px;">
+    <h4 style="margin: 0 0 12px 0; color: #1e3a5f;">🔍 Key Findings</h4>
+    <ul style="margin: 0; padding-left: 20px; color: #475569;">{finding_items}</ul>
+</div>
+        """)
+    
+    # Biomarker Flags - as a visual grid
+    flags = response.get("biomarker_flags", [])
+    if flags:
+        flag_cards = ""
+        for flag in flags[:8]:
+            if isinstance(flag, dict):
+                name = flag.get("biomarker", "Unknown")
+                status = flag.get("status", "normal")
+                value = flag.get("value", "N/A")
+                
+                status_styles = {
+                    "critical": ("🔴", "#dc2626", "#fef2f2"),
+                    "abnormal": ("🟡", "#ca8a04", "#fefce8"),
+                    "normal": ("🟢", "#16a34a", "#f0fdf4")
+                }
+                s_emoji, s_color, s_bg = status_styles.get(status, status_styles["normal"])
+                
+                flag_cards += f"""
+<div style="background: {s_bg}; border: 1px solid {s_color}33; border-radius: 8px; padding: 12px; text-align: center;">
+    <div style="font-size: 1.2em;">{s_emoji}</div>
+    <div style="font-weight: 600; color: #1e3a5f; margin: 4px 0;">{name}</div>
+    <div style="font-size: 1.1em; color: {s_color};">{value}</div>
+    <div style="font-size: 0.8em; color: #64748b; text-transform: uppercase;">{status}</div>
+</div>
+                """
+        
+        parts.append(f"""
+<div style="margin-bottom: 16px;">
+    <h4 style="margin: 0 0 12px 0; color: #1e3a5f;">📊 Biomarker Analysis</h4>
+    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(100px, 1fr)); gap: 12px;">
+        {flag_cards}
+    </div>
+</div>
+        """)
+    
+    # Recommendations - organized sections
+    recs = response.get("recommendations", {})
+    if recs:
+        rec_sections = ""
+        
+        immediate = recs.get("immediate_actions", [])
+        if immediate:
+            items = "".join([f'<li style="margin-bottom: 6px;">{a}</li>' for a in immediate[:3]])
+            rec_sections += f"""
+<div style="margin-bottom: 12px;">
+    <h5 style="margin: 0 0 8px 0; color: #dc2626;">🚨 Immediate Actions</h5>
+    <ul style="margin: 0; padding-left: 20px; color: #475569;">{items}</ul>
+</div>
+            """
+        
+        lifestyle = recs.get("lifestyle_modifications", [])
+        if lifestyle:
+            items = "".join([f'<li style="margin-bottom: 6px;">{m}</li>' for m in lifestyle[:3]])
+            rec_sections += f"""
+<div style="margin-bottom: 12px;">
+    <h5 style="margin: 0 0 8px 0; color: #16a34a;">🌿 Lifestyle Modifications</h5>
+    <ul style="margin: 0; padding-left: 20px; color: #475569;">{items}</ul>
+</div>
+            """
+        
+        followup = recs.get("follow_up", [])
+        if followup:
+            items = "".join([f'<li style="margin-bottom: 6px;">{f}</li>' for f in followup[:3]])
+            rec_sections += f"""
+<div>
+    <h5 style="margin: 0 0 8px 0; color: #2563eb;">📅 Follow-up</h5>
+    <ul style="margin: 0; padding-left: 20px; color: #475569;">{items}</ul>
+</div>
+            """
+        
+        if rec_sections:
+            parts.append(f"""
+<div style="background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%); border-radius: 12px; padding: 16px; margin-bottom: 16px;">
+    <h4 style="margin: 0 0 16px 0; color: #1e3a5f;">💡 Recommendations</h4>
+    {rec_sections}
+</div>
+            """)
+    
+    # Disease Explanation
+    explanation = response.get("disease_explanation", {})
+    if explanation and isinstance(explanation, dict):
+        pathophys = explanation.get("pathophysiology", "")
+        if pathophys:
+            parts.append(f"""
+<div style="background: #f8fafc; border-radius: 12px; padding: 16px; margin-bottom: 16px;">
+    <h4 style="margin: 0 0 12px 0; color: #1e3a5f;">📖 Understanding Your Results</h4>
+    <p style="margin: 0; color: #475569; line-height: 1.6;">{pathophys[:600]}{'...' if len(pathophys) > 600 else ''}</p>
+</div>
+            """)
+    
+    # Conversational Summary
+    conv_summary = response.get("conversational_summary", "")
+    if conv_summary:
+        parts.append(f"""
+<div style="background: linear-gradient(135deg, #faf5ff 0%, #f3e8ff 100%); border-radius: 12px; padding: 16px; margin-bottom: 16px;">
+    <h4 style="margin: 0 0 12px 0; color: #7c3aed;">📝 Summary</h4>
+    <p style="margin: 0; color: #475569; line-height: 1.6;">{conv_summary[:1000]}</p>
+</div>
+        """)
+    
+    # Footer
+    parts.append(f"""
+<div style="border-top: 1px solid #e2e8f0; padding-top: 16px; margin-top: 8px; text-align: center;">
+    <p style="margin: 0 0 8px 0; color: #94a3b8; font-size: 0.9em;">
+        ✨ Analysis completed in <strong>{elapsed:.1f}s</strong> using Agentic RagBot
+    </p>
+    <p style="margin: 0; color: #f59e0b; font-size: 0.85em;">
+        ⚠️ <em>This is for informational purposes only. Consult a healthcare professional for medical advice.</em>
+    </p>
+</div>
+    """)
+    
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Gradio Interface
+# ---------------------------------------------------------------------------
+
+# Custom CSS for modern medical UI
+CUSTOM_CSS = """
+/* Global Styles */
+.gradio-container {
+    max-width: 1400px !important;
+    margin: auto !important;
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif !important;
+}
+
+/* Hide footer */
+footer { display: none !important; }
+
+/* Header styling */
+.header-container {
+    background: linear-gradient(135deg, #1e3a5f 0%, #2d5a87 50%, #3d7ab5 100%);
+    border-radius: 16px;
+    padding: 32px;
+    margin-bottom: 24px;
+    color: white;
+    text-align: center;
+    box-shadow: 0 8px 32px rgba(30, 58, 95, 0.3);
+}
+
+.header-container h1 {
+    margin: 0 0 12px 0;
+    font-size: 2.5em;
+    font-weight: 700;
+    text-shadow: 0 2px 4px rgba(0,0,0,0.2);
+}
+
+.header-container p {
+    margin: 0;
+    opacity: 0.95;
+    font-size: 1.1em;
+}
+
+/* Input panel */
+.input-panel {
+    background: linear-gradient(180deg, #f8fafc 0%, #f1f5f9 100%);
+    border-radius: 16px;
+    padding: 24px;
+    border: 1px solid #e2e8f0;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+}
+
+/* Output panel */
+.output-panel {
+    background: white;
+    border-radius: 16px;
+    padding: 24px;
+    border: 1px solid #e2e8f0;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+    min-height: 500px;
+}
+
+/* Status badges */
+.status-success {
+    background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    color: white;
+    padding: 12px 20px;
+    border-radius: 10px;
+    font-weight: 600;
+    display: inline-block;
+}
+
+.status-error {
+    background: linear-gradient(135deg, #ef4444 0%, #dc2626 100%);
+    color: white;
+    padding: 12px 20px;
+    border-radius: 10px;
+    font-weight: 600;
+}
+
+.status-warning {
+    background: linear-gradient(135deg, #f59e0b 0%, #d97706 100%);
+    color: white;
+    padding: 12px 20px;
+    border-radius: 10px;
+    font-weight: 600;
+}
+
+/* Info banner */
+.info-banner {
+    background: linear-gradient(135deg, #dbeafe 0%, #bfdbfe 100%);
+    border: 1px solid #93c5fd;
+    border-radius: 12px;
+    padding: 16px 20px;
+    margin: 16px 0;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+.info-banner-icon {
+    font-size: 1.5em;
+}
+
+/* Agent cards */
+.agent-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 16px;
+    margin: 20px 0;
+}
+
+.agent-card {
+    background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
+    border: 1px solid #e2e8f0;
+    border-radius: 12px;
+    padding: 20px;
+    transition: all 0.3s ease;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
+}
+
+.agent-card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+    border-color: #3b82f6;
+}
+
+.agent-card h4 {
+    margin: 0 0 8px 0;
+    color: #1e3a5f;
+    font-size: 1em;
+}
+
+.agent-card p {
+    margin: 0;
+    color: #64748b;
+    font-size: 0.9em;
+}
+
+/* Example buttons */
+.example-btn {
+    background: #f1f5f9;
+    border: 1px solid #cbd5e1;
+    border-radius: 8px;
+    padding: 10px 14px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    text-align: left;
+    font-size: 0.85em;
+}
+
+.example-btn:hover {
+    background: #e2e8f0;
+    border-color: #94a3b8;
+}
+
+/* Buttons */
+.primary-btn {
+    background: linear-gradient(135deg, #3b82f6 0%, #2563eb 100%) !important;
+    border: none !important;
+    border-radius: 12px !important;
+    padding: 14px 28px !important;
+    font-weight: 600 !important;
+    font-size: 1.1em !important;
+    box-shadow: 0 4px 14px rgba(59, 130, 246, 0.4) !important;
+    transition: all 0.3s ease !important;
+}
+
+.primary-btn:hover {
+    transform: translateY(-2px) !important;
+    box-shadow: 0 6px 20px rgba(59, 130, 246, 0.5) !important;
+}
+
+.secondary-btn {
+    background: #f1f5f9 !important;
+    border: 1px solid #cbd5e1 !important;
+    border-radius: 12px !important;
+    padding: 14px 28px !important;
+    font-weight: 500 !important;
+    transition: all 0.2s ease !important;
+}
+
+.secondary-btn:hover {
+    background: #e2e8f0 !important;
+}
+
+/* Results tabs */
+.results-tabs {
+    border-radius: 12px;
+    overflow: hidden;
+}
+
+/* Disclaimer */
+.disclaimer {
+    background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);
+    border: 1px solid #fbbf24;
+    border-radius: 12px;
+    padding: 16px 20px;
+    margin-top: 24px;
+    font-size: 0.9em;
+}
+
+/* Feature badges */
+.feature-badge {
+    display: inline-block;
+    background: linear-gradient(135deg, #e0e7ff 0%, #c7d2fe 100%);
+    color: #4338ca;
+    padding: 6px 12px;
+    border-radius: 20px;
+    font-size: 0.8em;
+    font-weight: 600;
+    margin: 4px;
+}
+
+/* Section titles */
+.section-title {
+    font-size: 1.25em;
+    font-weight: 600;
+    color: #1e3a5f;
+    margin-bottom: 16px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+
+/* Animations */
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.7; }
+}
+
+.analyzing {
+    animation: pulse 1.5s ease-in-out infinite;
+}
+"""
+
+
+def create_demo() -> gr.Blocks:
+    """Create the Gradio Blocks interface with modern medical UI."""
+    
+    with gr.Blocks(
+        title="Agentic RagBot - Medical Biomarker Analysis",
+        theme=gr.themes.Soft(
+            primary_hue=gr.themes.colors.blue,
+            secondary_hue=gr.themes.colors.slate,
+            neutral_hue=gr.themes.colors.slate,
+            font=gr.themes.GoogleFont("Inter"),
+            font_mono=gr.themes.GoogleFont("JetBrains Mono"),
+        ).set(
+            body_background_fill="linear-gradient(135deg, #f0f4f8 0%, #e2e8f0 100%)",
+            block_background_fill="white",
+            block_border_width="0px",
+            block_shadow="0 4px 16px rgba(0, 0, 0, 0.08)",
+            block_radius="16px",
+            button_primary_background_fill="linear-gradient(135deg, #3b82f6 0%, #2563eb 100%)",
+            button_primary_background_fill_hover="linear-gradient(135deg, #2563eb 0%, #1d4ed8 100%)",
+            button_primary_text_color="white",
+            button_primary_shadow="0 4px 14px rgba(59, 130, 246, 0.4)",
+            input_background_fill="#f8fafc",
+            input_border_width="1px",
+            input_border_color="#e2e8f0",
+            input_radius="12px",
+        ),
+        css=CUSTOM_CSS,
+    ) as demo:
+        
+        # ===== HEADER =====
+        gr.HTML("""
+        <div class="header-container">
+            <h1>🏥 Agentic RagBot</h1>
+            <p>Multi-Agent RAG System for Medical Biomarker Analysis</p>
+            <div style="margin-top: 16px;">
+                <span class="feature-badge">🤖 6 AI Agents</span>
+                <span class="feature-badge">📚 RAG-Powered</span>
+                <span class="feature-badge">⚡ Real-time Analysis</span>
+                <span class="feature-badge">🔬 Evidence-Based</span>
+            </div>
+        </div>
+        """)
+        
+        # ===== API KEY INFO =====
+        gr.HTML("""
+        <div class="info-banner">
+            <span class="info-banner-icon">🔑</span>
+            <div>
+                <strong>Setup Required:</strong> Add your <code>GROQ_API_KEY</code> or 
+                <code>GOOGLE_API_KEY</code> in Space Settings → Secrets to enable analysis.
+                <a href="https://console.groq.com/keys" target="_blank" style="color: #2563eb;">Get free Groq key →</a>
+            </div>
+        </div>
+        """)
+        
+        # ===== MAIN CONTENT =====
+        with gr.Row(equal_height=False):
+            
+            # ----- LEFT PANEL: INPUT -----
+            with gr.Column(scale=2, min_width=400):
+                gr.HTML('<div class="section-title">📝 Enter Your Biomarkers</div>')
+                
+                with gr.Group():
+                    input_text = gr.Textbox(
+                        label="",
+                        placeholder="Enter biomarkers in any format:\n\n• Glucose: 140, HbA1c: 7.5, Cholesterol: 210\n• My glucose is 140 and HbA1c is 7.5\n• {\"Glucose\": 140, \"HbA1c\": 7.5}",
+                        lines=6,
+                        max_lines=12,
+                        show_label=False,
+                    )
+                    
+                    with gr.Row():
+                        analyze_btn = gr.Button(
+                            "🔬 Analyze Biomarkers", 
+                            variant="primary", 
+                            size="lg",
+                            scale=3,
+                        )
+                        clear_btn = gr.Button(
+                            "🗑️ Clear", 
+                            variant="secondary",
+                            size="lg",
+                            scale=1,
+                        )
+                
+                # Status display
+                status_output = gr.Markdown(
+                    value="",
+                    elem_classes="status-box"
+                )
+                
+                # Quick Examples
+                gr.HTML('<div class="section-title" style="margin-top: 24px;">⚡ Quick Examples</div>')
+                gr.HTML('<p style="color: #64748b; font-size: 0.9em; margin-bottom: 12px;">Click any example to load it instantly</p>')
+                
+                examples = gr.Examples(
+                    examples=[
+                        ["Glucose: 185, HbA1c: 8.2, Cholesterol: 245, LDL: 165"],
+                        ["Glucose: 95, HbA1c: 5.4, Cholesterol: 180, HDL: 55, LDL: 100"],
+                        ["Hemoglobin: 9.5, Iron: 40, Ferritin: 15"],
+                        ["TSH: 8.5, T4: 4.0, T3: 80"],
+                        ["Creatinine: 2.5, BUN: 45, eGFR: 35"],
+                    ],
+                    inputs=input_text,
+                    label="",
+                )
+                
+                # Supported Biomarkers
+                with gr.Accordion("📊 Supported Biomarkers", open=False):
+                    gr.HTML("""
+                    <div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; padding: 12px;">
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">🩸 Diabetes</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">Glucose, HbA1c, Fasting Glucose, Insulin</p>
+                        </div>
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">❤️ Cardiovascular</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">Cholesterol, LDL, HDL, Triglycerides</p>
+                        </div>
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">🫘 Kidney</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">Creatinine, BUN, eGFR, Uric Acid</p>
+                        </div>
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">🦴 Liver</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">ALT, AST, Bilirubin, Albumin</p>
+                        </div>
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">🦋 Thyroid</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">TSH, T3, T4, Free T4</p>
+                        </div>
+                        <div>
+                            <h4 style="color: #1e3a5f; margin: 0 0 8px 0;">💉 Blood</h4>
+                            <p style="color: #64748b; font-size: 0.85em; margin: 0;">Hemoglobin, WBC, RBC, Platelets</p>
+                        </div>
+                    </div>
+                    """)
+            
+            # ----- RIGHT PANEL: RESULTS -----
+            with gr.Column(scale=3, min_width=500):
+                gr.HTML('<div class="section-title">📊 Analysis Results</div>')
+                
+                with gr.Tabs() as result_tabs:
+                    with gr.Tab("📋 Summary", id="summary"):
+                        summary_output = gr.Markdown(
+                            value="""
+<div style="text-align: center; padding: 60px 20px; color: #94a3b8;">
+    <div style="font-size: 4em; margin-bottom: 16px;">🔬</div>
+    <h3 style="color: #64748b; font-weight: 500;">Ready to Analyze</h3>
+    <p>Enter your biomarkers on the left and click <strong>Analyze</strong> to get your personalized health insights.</p>
+</div>
+                            """,
+                            elem_classes="summary-output"
+                        )
+                    
+                    with gr.Tab("🔍 Detailed JSON", id="json"):
+                        details_output = gr.Code(
+                            label="",
+                            language="json",
+                            lines=30,
+                            show_label=False,
+                        )
+        
+        # ===== HOW IT WORKS =====
+        gr.HTML('<div class="section-title" style="margin-top: 32px;">🤖 How It Works</div>')
+        
+        gr.HTML("""
+        <div class="agent-grid">
+            <div class="agent-card">
+                <h4>🔬 Biomarker Analyzer</h4>
+                <p>Validates your biomarker values against clinical reference ranges and flags any abnormalities.</p>
+            </div>
+            <div class="agent-card">
+                <h4>📚 Disease Explainer</h4>
+                <p>Uses RAG to retrieve relevant medical literature and explain potential conditions.</p>
+            </div>
+            <div class="agent-card">
+                <h4>🔗 Biomarker Linker</h4>
+                <p>Connects your specific biomarker patterns to disease predictions with clinical evidence.</p>
+            </div>
+            <div class="agent-card">
+                <h4>📋 Clinical Guidelines</h4>
+                <p>Retrieves evidence-based recommendations from 750+ pages of medical guidelines.</p>
+            </div>
+            <div class="agent-card">
+                <h4>✅ Confidence Assessor</h4>
+                <p>Evaluates the reliability of findings based on data quality and evidence strength.</p>
+            </div>
+            <div class="agent-card">
+                <h4>📝 Response Synthesizer</h4>
+                <p>Compiles all insights into a comprehensive, easy-to-understand patient report.</p>
+            </div>
+        </div>
+        """)
+        
+        # ===== DISCLAIMER =====
+        gr.HTML("""
+        <div class="disclaimer">
+            <strong>⚠️ Medical Disclaimer:</strong> This tool is for <strong>informational purposes only</strong> 
+            and does not replace professional medical advice, diagnosis, or treatment. Always consult a qualified 
+            healthcare provider with questions regarding a medical condition. The AI analysis is based on general 
+            clinical guidelines and may not account for your specific medical history.
+        </div>
+        """)
+        
+        # ===== FOOTER =====
+        gr.HTML("""
+        <div style="text-align: center; padding: 24px; color: #94a3b8; font-size: 0.85em; margin-top: 24px;">
+            <p>Built with ❤️ using 
+                <a href="https://langchain-ai.github.io/langgraph/" target="_blank" style="color: #3b82f6;">LangGraph</a>, 
+                <a href="https://faiss.ai/" target="_blank" style="color: #3b82f6;">FAISS</a>, and 
+                <a href="https://gradio.app/" target="_blank" style="color: #3b82f6;">Gradio</a>
+            </p>
+            <p style="margin-top: 8px;">Powered by <strong>Groq</strong> (LLaMA 3.3-70B) • Open Source on GitHub</p>
+        </div>
+        """)
+        
+        # ===== EVENT HANDLERS =====
+        analyze_btn.click(
+            fn=analyze_biomarkers,
+            inputs=[input_text],
+            outputs=[summary_output, details_output, status_output],
+            show_progress="full",
+        )
+        
+        clear_btn.click(
+            fn=lambda: ("", """
+<div style="text-align: center; padding: 60px 20px; color: #94a3b8;">
+    <div style="font-size: 4em; margin-bottom: 16px;">🔬</div>
+    <h3 style="color: #64748b; font-weight: 500;">Ready to Analyze</h3>
+    <p>Enter your biomarkers on the left and click <strong>Analyze</strong> to get your personalized health insights.</p>
+</div>
+            """, "", ""),
+            outputs=[input_text, summary_output, details_output, status_output],
+        )
+    
+    return demo
+
+
+# ---------------------------------------------------------------------------
+# Main Entry Point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    logger.info("Starting MediGuard AI Gradio App...")
+    
+    demo = create_demo()
+    
+    # Launch with HF Spaces compatible settings
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+        # share=False on HF Spaces
+    )

huggingface/requirements.txt

@@ -0,0 +1,42 @@
+# ===========================================================================
+# MediGuard AI — Hugging Face Spaces Dependencies
+# ===========================================================================
+# Minimal dependencies for standalone Gradio deployment.
+# No postgres, redis, opensearch, ollama required.
+# ===========================================================================
+
+# --- Gradio UI ---
+gradio>=5.0.0
+
+# --- LangChain Core ---
+langchain>=0.3.0
+langchain-community>=0.3.0
+langchain-core>=0.3.0
+langchain-text-splitters>=0.3.0
+langgraph>=0.2.0
+
+# --- Cloud LLM Providers (FREE tiers) ---
+langchain-groq>=0.2.0
+langchain-google-genai>=2.0.0
+
+# --- Vector Store ---
+faiss-cpu>=1.8.0
+
+# --- Embeddings (local - no API key needed) ---
+sentence-transformers>=3.0.0
+langchain-huggingface>=0.1.0
+
+# --- Document Processing ---
+pypdf>=4.0.0
+
+# --- Pydantic ---
+pydantic>=2.9.0
+pydantic-settings>=2.5.0
+
+# --- HTTP Client ---
+httpx>=0.27.0
+
+# --- Utilities ---
+python-dotenv>=1.0.0
+tenacity>=8.0.0
+numpy<2.0.0

pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mediguard-ai"
+version = "2.0.0"
+description = "Production medical biomarker analysis — agentic RAG + multi-agent workflow"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "MediGuard AI Team" }]
+
+dependencies = [
+    # --- Core ---
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.5.0",
+    # --- LLM / LangChain ---
+    "langchain>=0.3.0",
+    "langchain-community>=0.3.0",
+    "langgraph>=0.2.0",
+    # --- Vector / Search ---
+    "opensearch-py>=2.7.0",
+    "faiss-cpu>=1.8.0",
+    # --- Embeddings ---
+    "httpx>=0.27.0",
+    # --- Database ---
+    "sqlalchemy>=2.0.0",
+    "psycopg2-binary>=2.9.0",
+    "alembic>=1.13.0",
+    # --- Cache ---
+    "redis>=5.0.0",
+    # --- PDF ---
+    "pypdf>=4.0.0",
+    # --- Observability ---
+    "langfuse>=2.0.0",
+    # --- Utilities ---
+    "python-dotenv>=1.0.0",
+    "tenacity>=8.0.0",
+]
+
+[project.optional-dependencies]
+docling = ["docling>=2.0.0"]
+telegram = ["python-telegram-bot>=21.0", "httpx>=0.27.0"]
+gradio = ["gradio>=5.0.0", "httpx>=0.27.0"]
+airflow = ["apache-airflow>=2.9.0"]
+google = ["langchain-google-genai>=2.0.0"]
+groq = ["langchain-groq>=0.2.0"]
+huggingface = ["sentence-transformers>=3.0.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.7.0",
+    "mypy>=1.12.0",
+    "pre-commit>=3.8.0",
+    "httpx>=0.27.0",
+]
+all = [
+    "mediguard-ai[docling,telegram,gradio,google,groq,huggingface,dev]",
+]
+
+[project.scripts]
+mediguard = "src.main:app"
+mediguard-telegram = "src.services.telegram.bot:MediGuardTelegramBot"
+mediguard-gradio = "src.gradio_app:launch_gradio"
+
+# --------------------------------------------------------------------------
+# Ruff
+# --------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",   # line too long — handled by formatter
+    "B008",   # do not perform function calls in argument defaults (Depends)
+    "SIM108", # ternary operator
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+# --------------------------------------------------------------------------
+# MyPy
+# --------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false  # gradually enable
+ignore_missing_imports = true
+
+# --------------------------------------------------------------------------
+# Pytest
+# --------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short -q"
+filterwarnings = ["ignore::DeprecationWarning"]

scripts/deploy_huggingface.ps1

@@ -0,0 +1,139 @@
+<#
+.SYNOPSIS
+    Deploy MediGuard AI to Hugging Face Spaces
+.DESCRIPTION
+    This script automates the deployment of MediGuard AI to Hugging Face Spaces.
+    It handles copying files, setting up the Dockerfile, and pushing to the Space.
+.PARAMETER SpaceName
+    Name of your Hugging Face Space (e.g., "mediguard-ai")
+.PARAMETER Username
+    Your Hugging Face username
+.PARAMETER SkipClone
+    Skip cloning if you've already cloned the Space
+.EXAMPLE
+    .\deploy_huggingface.ps1 -Username "your-username" -SpaceName "mediguard-ai"
+#>
+
+param(
+    [Parameter(Mandatory=$true)]
+    [string]$Username,
+    
+    [Parameter(Mandatory=$false)]
+    [string]$SpaceName = "mediguard-ai",
+    
+    [switch]$SkipClone
+)
+
+$ErrorActionPreference = "Stop"
+
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host " MediGuard AI - Hugging Face Deployment" -ForegroundColor Cyan
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Configuration
+$ProjectRoot = Split-Path -Parent $PSScriptRoot
+$DeployDir = Join-Path $ProjectRoot "hf-deploy"
+$SpaceUrl = "https://huggingface.co/spaces/$Username/$SpaceName"
+
+Write-Host "Project Root: $ProjectRoot" -ForegroundColor Gray
+Write-Host "Deploy Dir: $DeployDir" -ForegroundColor Gray
+Write-Host "Space URL: $SpaceUrl" -ForegroundColor Gray
+Write-Host ""
+
+# Step 1: Clone or use existing Space
+if (-not $SkipClone) {
+    Write-Host "[1/6] Cloning Hugging Face Space..." -ForegroundColor Yellow
+    
+    if (Test-Path $DeployDir) {
+        Write-Host "  Removing existing deploy directory..." -ForegroundColor Gray
+        Remove-Item -Recurse -Force $DeployDir
+    }
+    
+    git clone "https://huggingface.co/spaces/$Username/$SpaceName" $DeployDir
+    
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "ERROR: Failed to clone Space. Make sure it exists!" -ForegroundColor Red
+        Write-Host "Create it at: https://huggingface.co/new-space" -ForegroundColor Yellow
+        exit 1
+    }
+} else {
+    Write-Host "[1/6] Using existing deploy directory..." -ForegroundColor Yellow
+}
+
+# Step 2: Copy project files
+Write-Host "[2/6] Copying project files..." -ForegroundColor Yellow
+
+# Core directories
+$CoreDirs = @("src", "config", "data", "huggingface")
+foreach ($dir in $CoreDirs) {
+    $source = Join-Path $ProjectRoot $dir
+    $dest = Join-Path $DeployDir $dir
+    if (Test-Path $source) {
+        Write-Host "  Copying $dir..." -ForegroundColor Gray
+        Copy-Item -Path $source -Destination $dest -Recurse -Force
+    }
+}
+
+# Copy specific files
+$CoreFiles = @("pyproject.toml", ".dockerignore")
+foreach ($file in $CoreFiles) {
+    $source = Join-Path $ProjectRoot $file
+    if (Test-Path $source) {
+        Write-Host "  Copying $file..." -ForegroundColor Gray
+        Copy-Item -Path $source -Destination (Join-Path $DeployDir $file) -Force
+    }
+}
+
+# Step 3: Set up Dockerfile (HF Spaces expects it in root)
+Write-Host "[3/6] Setting up Dockerfile..." -ForegroundColor Yellow
+$HfDockerfile = Join-Path $DeployDir "huggingface/Dockerfile"
+$RootDockerfile = Join-Path $DeployDir "Dockerfile"
+Copy-Item -Path $HfDockerfile -Destination $RootDockerfile -Force
+Write-Host "  Copied huggingface/Dockerfile to Dockerfile" -ForegroundColor Gray
+
+# Step 4: Set up README with HF metadata
+Write-Host "[4/6] Setting up README.md..." -ForegroundColor Yellow
+$HfReadme = Join-Path $DeployDir "huggingface/README.md"
+$RootReadme = Join-Path $DeployDir "README.md"
+Copy-Item -Path $HfReadme -Destination $RootReadme -Force
+Write-Host "  Copied huggingface/README.md to README.md" -ForegroundColor Gray
+
+# Step 5: Verify vector store exists
+Write-Host "[5/6] Verifying vector store..." -ForegroundColor Yellow
+$VectorStore = Join-Path $DeployDir "data/vector_stores/medical_knowledge.faiss"
+if (Test-Path $VectorStore) {
+    $size = (Get-Item $VectorStore).Length / 1MB
+    Write-Host "  Vector store found: $([math]::Round($size, 2)) MB" -ForegroundColor Green
+} else {
+    Write-Host "  WARNING: Vector store not found!" -ForegroundColor Red
+    Write-Host "  Run 'python scripts/setup_embeddings.py' first to create it." -ForegroundColor Yellow
+}
+
+# Step 6: Commit and push
+Write-Host "[6/6] Committing and pushing to Hugging Face..." -ForegroundColor Yellow
+
+Push-Location $DeployDir
+
+git add .
+git commit -m "Deploy MediGuard AI - $(Get-Date -Format 'yyyy-MM-dd HH:mm')"
+
+Write-Host ""
+Write-Host "Ready to push! Run the following command:" -ForegroundColor Green
+Write-Host ""
+Write-Host "  cd $DeployDir" -ForegroundColor Cyan
+Write-Host "  git push" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "After pushing, add your API key as a Secret in Space Settings:" -ForegroundColor Yellow
+Write-Host "  Name: GROQ_API_KEY  (or GOOGLE_API_KEY)" -ForegroundColor Gray
+Write-Host "  Value: your-api-key" -ForegroundColor Gray
+Write-Host ""
+Write-Host "Your Space will be live at:" -ForegroundColor Green
+Write-Host "  $SpaceUrl" -ForegroundColor Cyan
+
+Pop-Location
+
+Write-Host ""
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host " Deployment prepared successfully!" -ForegroundColor Green
+Write-Host "========================================" -ForegroundColor Cyan

src/database.py

@@ -0,0 +1,50 @@
+"""
+MediGuard AI — Database layer
+
+Provides SQLAlchemy engine/session factories and the declarative Base.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker, DeclarativeBase
+
+from src.settings import get_settings
+
+
+class Base(DeclarativeBase):
+    """Shared declarative base for all ORM models."""
+    pass
+
+
+@lru_cache(maxsize=1)
+def _engine():
+    settings = get_settings()
+    return create_engine(
+        settings.postgres.database_url,
+        pool_pre_ping=True,
+        pool_size=5,
+        max_overflow=10,
+        echo=settings.debug,
+    )
+
+
+@lru_cache(maxsize=1)
+def _session_factory() -> sessionmaker[Session]:
+    return sessionmaker(bind=_engine(), autocommit=False, autoflush=False)
+
+
+def get_db() -> Generator[Session, None, None]:
+    """FastAPI dependency — yields a DB session and commits/rolls back."""
+    session = _session_factory()()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

src/dependencies.py

@@ -0,0 +1,36 @@
+"""
+MediGuard AI — FastAPI Dependency Injection
+
+Provides factory functions and ``Depends()`` for services used across routers.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from src.settings import Settings, get_settings
+from src.services.cache.redis_cache import RedisCache, make_redis_cache
+from src.services.embeddings.service import EmbeddingService, make_embedding_service
+from src.services.langfuse.tracer import LangfuseTracer, make_langfuse_tracer
+from src.services.ollama.client import OllamaClient, make_ollama_client
+from src.services.opensearch.client import OpenSearchClient, make_opensearch_client
+
+
+def get_opensearch_client() -> OpenSearchClient:
+    return make_opensearch_client()
+
+
+def get_embedding_service() -> EmbeddingService:
+    return make_embedding_service()
+
+
+def get_redis_cache() -> RedisCache:
+    return make_redis_cache()
+
+
+def get_ollama_client() -> OllamaClient:
+    return make_ollama_client()
+
+
+def get_langfuse_tracer() -> LangfuseTracer:
+    return make_langfuse_tracer()

src/exceptions.py

@@ -0,0 +1,149 @@
+"""
+MediGuard AI — Domain Exception Hierarchy
+
+Production-grade exception classes for the medical RAG system.
+Each service layer raises its own exception type so callers can handle
+failures precisely without leaking implementation details.
+"""
+
+from typing import Any, Dict, Optional
+
+
+# ── Base ──────────────────────────────────────────────────────────────────────
+
+class MediGuardError(Exception):
+    """Root exception for the entire MediGuard AI application."""
+
+    def __init__(self, message: str = "", *, details: Optional[Dict[str, Any]] = None):
+        self.details = details or {}
+        super().__init__(message)
+
+
+# ── Configuration / startup ──────────────────────────────────────────────────
+
+class ConfigurationError(MediGuardError):
+    """Raised when a required setting is missing or invalid."""
+
+
+class ServiceInitError(MediGuardError):
+    """Raised when a service fails to initialise during app startup."""
+
+
+# ── Database ─────────────────────────────────────────────────────────────────
+
+class DatabaseError(MediGuardError):
+    """Base class for all database-related errors."""
+
+
+class ConnectionError(DatabaseError):
+    """Could not connect to PostgreSQL."""
+
+
+class RecordNotFoundError(DatabaseError):
+    """Expected record does not exist."""
+
+
+# ── Search engine ────────────────────────────────────────────────────────────
+
+class SearchError(MediGuardError):
+    """Base class for search-engine (OpenSearch) errors."""
+
+
+class IndexNotFoundError(SearchError):
+    """The requested OpenSearch index does not exist."""
+
+
+class SearchQueryError(SearchError):
+    """The search query was malformed or returned an error."""
+
+
+# ── Embeddings ───────────────────────────────────────────────────────────────
+
+class EmbeddingError(MediGuardError):
+    """Failed to generate embeddings."""
+
+
+class EmbeddingProviderError(EmbeddingError):
+    """The upstream embedding provider returned an error."""
+
+
+# ── PDF / document parsing ───────────────────────────────────────────────────
+
+class PDFParsingError(MediGuardError):
+    """Base class for PDF-processing errors."""
+
+
+class PDFExtractionError(PDFParsingError):
+    """Could not extract text from a PDF document."""
+
+
+class PDFValidationError(PDFParsingError):
+    """Uploaded PDF failed validation (size, format, etc.)."""
+
+
+# ── LLM / Ollama ─────────────────────────────────────────────────────────────
+
+class LLMError(MediGuardError):
+    """Base class for LLM-related errors."""
+
+
+class OllamaConnectionError(LLMError):
+    """Could not reach the Ollama server."""
+
+
+class OllamaModelNotFoundError(LLMError):
+    """The requested Ollama model is not pulled/available."""
+
+
+class LLMResponseError(LLMError):
+    """The LLM returned an unparseable or empty response."""
+
+
+# ── Biomarker domain ─────────────────────────────────────────────────────────
+
+class BiomarkerError(MediGuardError):
+    """Base class for biomarker-related errors."""
+
+
+class BiomarkerValidationError(BiomarkerError):
+    """A biomarker value is physiologically implausible."""
+
+
+class BiomarkerNotFoundError(BiomarkerError):
+    """The biomarker name is unknown to the system."""
+
+
+# ── Medical analysis / workflow ──────────────────────────────────────────────
+
+class AnalysisError(MediGuardError):
+    """The clinical-analysis workflow encountered an error."""
+
+
+class GuardrailError(MediGuardError):
+    """A safety guardrail was triggered (input or output)."""
+
+
+class OutOfScopeError(GuardrailError):
+    """The user query falls outside the medical domain."""
+
+
+# ── Cache ────────────────────────────────────────────────────────────────────
+
+class CacheError(MediGuardError):
+    """Base class for cache (Redis) errors."""
+
+
+class CacheConnectionError(CacheError):
+    """Could not connect to Redis."""
+
+
+# ── Observability ────────────────────────────────────────────────────────────
+
+class ObservabilityError(MediGuardError):
+    """Langfuse or metrics reporting failed (non-fatal)."""
+
+
+# ── Telegram bot ─────────────────────────────────────────────────────────────
+
+class TelegramError(MediGuardError):
+    """Error from the Telegram bot integration."""

src/gradio_app.py

@@ -0,0 +1,121 @@
+"""
+MediGuard AI — Gradio Web UI
+
+Provides a simple chat interface and biomarker analysis panel.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+API_BASE = os.getenv("MEDIGUARD_API_URL", "http://localhost:8000")
+
+
+def _call_ask(question: str) -> str:
+    """Call the /ask endpoint."""
+    try:
+        with httpx.Client(timeout=60.0) as client:
+            resp = client.post(f"{API_BASE}/ask", json={"question": question})
+            resp.raise_for_status()
+            return resp.json().get("answer", "No answer returned.")
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def _call_analyze(biomarkers_json: str) -> str:
+    """Call the /analyze/structured endpoint."""
+    try:
+        biomarkers = json.loads(biomarkers_json)
+        with httpx.Client(timeout=60.0) as client:
+            resp = client.post(
+                f"{API_BASE}/analyze/structured",
+                json={"biomarkers": biomarkers},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            summary = data.get("conversational_summary") or json.dumps(data, indent=2)
+            return summary
+    except json.JSONDecodeError:
+        return "Invalid JSON. Please enter biomarkers as: {\"Glucose\": 185, \"HbA1c\": 8.2}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def launch_gradio(share: bool = False) -> None:
+    """Launch the Gradio interface."""
+    try:
+        import gradio as gr
+    except ImportError:
+        raise ImportError("gradio is required. Install: pip install gradio")
+
+    with gr.Blocks(title="MediGuard AI", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("# 🏥 MediGuard AI — Medical Analysis")
+        gr.Markdown(
+            "**Disclaimer**: This tool is for informational purposes only and does not "
+            "replace professional medical advice."
+        )
+
+        with gr.Tab("Ask a Question"):
+            question_input = gr.Textbox(
+                label="Medical Question",
+                placeholder="e.g., What does a high HbA1c level indicate?",
+                lines=3,
+            )
+            ask_btn = gr.Button("Ask", variant="primary")
+            answer_output = gr.Textbox(label="Answer", lines=15, interactive=False)
+            ask_btn.click(fn=_call_ask, inputs=question_input, outputs=answer_output)
+
+        with gr.Tab("Analyze Biomarkers"):
+            bio_input = gr.Textbox(
+                label="Biomarkers (JSON)",
+                placeholder='{"Glucose": 185, "HbA1c": 8.2, "Cholesterol": 210}',
+                lines=5,
+            )
+            analyze_btn = gr.Button("Analyze", variant="primary")
+            analysis_output = gr.Textbox(label="Analysis", lines=20, interactive=False)
+            analyze_btn.click(fn=_call_analyze, inputs=bio_input, outputs=analysis_output)
+
+        with gr.Tab("Search Knowledge Base"):
+            search_input = gr.Textbox(
+                label="Search Query",
+                placeholder="e.g., diabetes management guidelines",
+                lines=2,
+            )
+            search_btn = gr.Button("Search", variant="primary")
+            search_output = gr.Textbox(label="Results", lines=15, interactive=False)
+
+            def _call_search(query: str) -> str:
+                try:
+                    with httpx.Client(timeout=30.0) as client:
+                        resp = client.post(
+                            f"{API_BASE}/search",
+                            json={"query": query, "top_k": 5, "mode": "hybrid"},
+                        )
+                        resp.raise_for_status()
+                        data = resp.json()
+                        results = data.get("results", [])
+                        if not results:
+                            return "No results found."
+                        parts = []
+                        for i, r in enumerate(results, 1):
+                            parts.append(
+                                f"**[{i}] {r.get('title', 'Untitled')}** (score: {r.get('score', 0):.3f})\n"
+                                f"{r.get('text', '')}\n"
+                            )
+                        return "\n---\n".join(parts)
+                except Exception as exc:
+                    return f"Error: {exc}"
+
+            search_btn.click(fn=_call_search, inputs=search_input, outputs=search_output)
+
+    demo.launch(server_name="0.0.0.0", server_port=7860, share=share)
+
+
+if __name__ == "__main__":
+    launch_gradio()

src/llm_config.py

@@ -19,8 +19,14 @@ load_dotenv()
 # Configure LangSmith tracing
 os.environ["LANGCHAIN_PROJECT"] = os.getenv("LANGCHAIN_PROJECT", "MediGuard_AI_RAG_Helper")
 
-# Default provider (can be overridden via env)
-DEFAULT_LLM_PROVIDER = os.getenv("LLM_PROVIDER", "groq")
+
+def get_default_llm_provider() -> str:
+    """Get default LLM provider dynamically from environment."""
+    return os.getenv("LLM_PROVIDER", "groq")
+
+
+# For backward compatibility (but prefer using get_default_llm_provider())
+DEFAULT_LLM_PROVIDER = get_default_llm_provider()
 
 
 def get_chat_model(
@@ -41,7 +47,8 @@ def get_chat_model(
     Returns:
         LangChain chat model instance
     """
-    provider = provider or DEFAULT_LLM_PROVIDER
+    # Use dynamic lookup to get current provider from environment
+    provider = provider or get_default_llm_provider()
     
     if provider == "groq":
         from langchain_groq import ChatGroq
@@ -164,9 +171,11 @@ class LLMConfig:
             provider: LLM provider - "groq" (free), "gemini" (free), or "ollama" (local)
             lazy: If True, defer model initialization until first use (avoids API key errors at import)
         """
-        self.provider = provider or DEFAULT_LLM_PROVIDER
+        # Store explicit provider or None to use dynamic lookup later
+        self._explicit_provider = provider
         self._lazy = lazy
         self._initialized = False
+        self._initialized_provider = None  # Track which provider was initialized
         self._lock = threading.Lock()
         
         # Lazy-initialized model instances
@@ -181,8 +190,28 @@ class LLMConfig:
         if not lazy:
             self._initialize_models()
     
+    @property
+    def provider(self) -> str:
+        """Get current provider (dynamic lookup if not explicitly set)."""
+        return self._explicit_provider or get_default_llm_provider()
+    
+    def _check_provider_change(self):
+        """Check if provider changed and reinitialize if needed."""
+        current = self.provider
+        if self._initialized and self._initialized_provider != current:
+            print(f"Provider changed from {self._initialized_provider} to {current}, reinitializing...")
+            self._initialized = False
+            self._planner = None
+            self._analyzer = None
+            self._explainer = None
+            self._synthesizer_7b = None
+            self._synthesizer_8b = None
+            self._director = None
+    
     def _initialize_models(self):
         """Initialize all model clients (called on first use if lazy)"""
+        self._check_provider_change()
+        
         if self._initialized:
             return
         
@@ -234,6 +263,7 @@ class LLMConfig:
         self._embedding_model = get_embedding_model()
         
         self._initialized = True
+        self._initialized_provider = self.provider
     
     @property
     def planner(self):

src/main.py

@@ -0,0 +1,220 @@
+"""
+MediGuard AI — Production FastAPI Application
+
+Central app factory with lifespan that initialises all production services
+(OpenSearch, Redis, Ollama, Langfuse, RAG pipeline) and gracefully shuts
+them down.  The existing ``api/`` package is kept as-is — this new module
+becomes the primary production entry-point.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from src.settings import get_settings
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(name)-30s | %(levelname)-7s | %(message)s",
+)
+logger = logging.getLogger("mediguard")
+
+# ---------------------------------------------------------------------------
+# Lifespan
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialise production services on startup, tear them down on shutdown."""
+    settings = get_settings()
+    app.state.start_time = time.time()
+    app.state.version = "2.0.0"
+
+    logger.info("=" * 70)
+    logger.info("MediGuard AI — starting production server v%s", app.state.version)
+    logger.info("=" * 70)
+
+    # --- OpenSearch ---
+    try:
+        from src.services.opensearch.client import make_opensearch_client
+        app.state.opensearch_client = make_opensearch_client()
+        logger.info("OpenSearch client ready")
+    except Exception as exc:
+        logger.warning("OpenSearch unavailable: %s", exc)
+        app.state.opensearch_client = None
+
+    # --- Embedding service ---
+    try:
+        from src.services.embeddings.service import make_embedding_service
+        app.state.embedding_service = make_embedding_service()
+        logger.info("Embedding service ready (provider=%s)", app.state.embedding_service._provider)
+    except Exception as exc:
+        logger.warning("Embedding service unavailable: %s", exc)
+        app.state.embedding_service = None
+
+    # --- Redis cache ---
+    try:
+        from src.services.cache.redis_cache import make_redis_cache
+        app.state.cache = make_redis_cache()
+        logger.info("Redis cache ready")
+    except Exception as exc:
+        logger.warning("Redis cache unavailable: %s", exc)
+        app.state.cache = None
+
+    # --- Ollama LLM ---
+    try:
+        from src.services.ollama.client import make_ollama_client
+        app.state.ollama_client = make_ollama_client()
+        logger.info("Ollama client ready")
+    except Exception as exc:
+        logger.warning("Ollama client unavailable: %s", exc)
+        app.state.ollama_client = None
+
+    # --- Langfuse tracer ---
+    try:
+        from src.services.langfuse.tracer import make_langfuse_tracer
+        app.state.tracer = make_langfuse_tracer()
+        logger.info("Langfuse tracer ready")
+    except Exception as exc:
+        logger.warning("Langfuse tracer unavailable: %s", exc)
+        app.state.tracer = None
+
+    # --- Agentic RAG service ---
+    try:
+        from src.services.agents.agentic_rag import AgenticRAGService
+        from src.services.agents.context import AgenticContext
+
+        if app.state.ollama_client and app.state.opensearch_client and app.state.embedding_service:
+            llm = app.state.ollama_client.get_langchain_model()
+            ctx = AgenticContext(
+                llm=llm,
+                embedding_service=app.state.embedding_service,
+                opensearch_client=app.state.opensearch_client,
+                cache=app.state.cache,
+                tracer=app.state.tracer,
+            )
+            app.state.rag_service = AgenticRAGService(ctx)
+            logger.info("Agentic RAG service ready")
+        else:
+            app.state.rag_service = None
+            logger.warning("Agentic RAG service skipped — missing backing services")
+    except Exception as exc:
+        logger.warning("Agentic RAG service failed: %s", exc)
+        app.state.rag_service = None
+
+    # --- Legacy RagBot service (backward-compatible /analyze) ---
+    try:
+        from api.app.services.ragbot import get_ragbot_service
+        ragbot = get_ragbot_service()
+        ragbot.initialize()
+        app.state.ragbot_service = ragbot
+        logger.info("Legacy RagBot service ready")
+    except Exception as exc:
+        logger.warning("Legacy RagBot service unavailable: %s", exc)
+        app.state.ragbot_service = None
+
+    logger.info("All services initialised — ready to serve")
+    logger.info("=" * 70)
+
+    yield  # ---- server running ----
+
+    logger.info("Shutting down MediGuard AI …")
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+def create_app() -> FastAPI:
+    """Build and return the configured FastAPI application."""
+    settings = get_settings()
+
+    app = FastAPI(
+        title="MediGuard AI",
+        description="Production medical biomarker analysis — agentic RAG + multi-agent workflow",
+        version="2.0.0",
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+    )
+
+    # --- CORS ---
+    origins = os.getenv("CORS_ALLOWED_ORIGINS", "*").split(",")
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=origins != ["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # --- Exception handlers ---
+    @app.exception_handler(RequestValidationError)
+    async def validation_error(request: Request, exc: RequestValidationError):
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={
+                "status": "error",
+                "error_code": "VALIDATION_ERROR",
+                "message": "Request validation failed",
+                "details": exc.errors(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
+    @app.exception_handler(Exception)
+    async def catch_all(request: Request, exc: Exception):
+        logger.error("Unhandled exception: %s", exc, exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "status": "error",
+                "error_code": "INTERNAL_SERVER_ERROR",
+                "message": "An unexpected error occurred. Please try again later.",
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
+    # --- Routers ---
+    from src.routers import health, analyze, ask, search
+
+    app.include_router(health.router)
+    app.include_router(analyze.router)
+    app.include_router(ask.router)
+    app.include_router(search.router)
+
+    @app.get("/")
+    async def root():
+        return {
+            "name": "MediGuard AI",
+            "version": "2.0.0",
+            "status": "online",
+            "endpoints": {
+                "health": "/health",
+                "health_ready": "/health/ready",
+                "analyze_natural": "/analyze/natural",
+                "analyze_structured": "/analyze/structured",
+                "ask": "/ask",
+                "search": "/search",
+                "docs": "/docs",
+            },
+        }
+
+    return app
+
+
+# Module-level app for ``uvicorn src.main:app``
+app = create_app()

src/repositories/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Repositories package."""

src/repositories/analysis.py

@@ -0,0 +1,41 @@
+"""
+MediGuard AI — Analysis repository (data-access layer).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from sqlalchemy.orm import Session
+
+from src.models.analysis import PatientAnalysis
+
+
+class AnalysisRepository:
+    """CRUD operations for patient analyses."""
+
+    def __init__(self, db: Session):
+        self.db = db
+
+    def create(self, analysis: PatientAnalysis) -> PatientAnalysis:
+        self.db.add(analysis)
+        self.db.flush()
+        return analysis
+
+    def get_by_request_id(self, request_id: str) -> Optional[PatientAnalysis]:
+        return (
+            self.db.query(PatientAnalysis)
+            .filter(PatientAnalysis.request_id == request_id)
+            .first()
+        )
+
+    def list_recent(self, limit: int = 20) -> List[PatientAnalysis]:
+        return (
+            self.db.query(PatientAnalysis)
+            .order_by(PatientAnalysis.created_at.desc())
+            .limit(limit)
+            .all()
+        )
+
+    def count(self) -> int:
+        return self.db.query(PatientAnalysis).count()

src/repositories/document.py

@@ -0,0 +1,48 @@
+"""
+MediGuard AI — Document repository.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from sqlalchemy.orm import Session
+
+from src.models.analysis import MedicalDocument
+
+
+class DocumentRepository:
+    """CRUD for ingested medical documents."""
+
+    def __init__(self, db: Session):
+        self.db = db
+
+    def upsert(self, doc: MedicalDocument) -> MedicalDocument:
+        existing = (
+            self.db.query(MedicalDocument)
+            .filter(MedicalDocument.content_hash == doc.content_hash)
+            .first()
+        )
+        if existing:
+            existing.parse_status = doc.parse_status
+            existing.chunk_count = doc.chunk_count
+            existing.indexed_at = doc.indexed_at
+            self.db.flush()
+            return existing
+        self.db.add(doc)
+        self.db.flush()
+        return doc
+
+    def get_by_id(self, doc_id: str) -> Optional[MedicalDocument]:
+        return self.db.query(MedicalDocument).filter(MedicalDocument.id == doc_id).first()
+
+    def list_all(self, limit: int = 100) -> List[MedicalDocument]:
+        return (
+            self.db.query(MedicalDocument)
+            .order_by(MedicalDocument.created_at.desc())
+            .limit(limit)
+            .all()
+        )
+
+    def count(self) -> int:
+        return self.db.query(MedicalDocument).count()

src/routers/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Production API routers."""

src/routers/analyze.py

@@ -0,0 +1,88 @@
+"""
+MediGuard AI — Analyze Router
+
+Backward-compatible /analyze/natural and /analyze/structured endpoints
+that delegate to the existing ClinicalInsightGuild workflow.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+from fastapi import APIRouter, HTTPException, Request
+
+from src.schemas.schemas import (
+    AnalysisResponse,
+    ErrorResponse,
+    NaturalAnalysisRequest,
+    StructuredAnalysisRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/analyze", tags=["analysis"])
+
+
+async def _run_guild_analysis(
+    request: Request,
+    biomarkers: Dict[str, float],
+    patient_ctx: Dict[str, Any],
+    extracted_biomarkers: Dict[str, float] | None = None,
+) -> AnalysisResponse:
+    """Execute the ClinicalInsightGuild and build the response envelope."""
+    request_id = f"req_{uuid.uuid4().hex[:12]}"
+    t0 = time.time()
+
+    ragbot = getattr(request.app.state, "ragbot_service", None)
+    if ragbot is None:
+        raise HTTPException(status_code=503, detail="Analysis service unavailable")
+
+    try:
+        result = await ragbot.analyze(biomarkers, patient_ctx)
+    except Exception as exc:
+        logger.exception("Guild analysis failed: %s", exc)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Analysis pipeline error: {exc}",
+        )
+
+    elapsed = (time.time() - t0) * 1000
+
+    # The guild returns a dict shaped like AnalysisResponse — pass through
+    return AnalysisResponse(
+        status="success",
+        request_id=request_id,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        extracted_biomarkers=extracted_biomarkers,
+        input_biomarkers=biomarkers,
+        patient_context=patient_ctx,
+        processing_time_ms=round(elapsed, 1),
+        **{k: v for k, v in result.items() if k not in ("status", "request_id", "timestamp", "extracted_biomarkers", "input_biomarkers", "patient_context", "processing_time_ms")},
+    )
+
+
+@router.post("/natural", response_model=AnalysisResponse)
+async def analyze_natural(body: NaturalAnalysisRequest, request: Request):
+    """Extract biomarkers from natural language and run full analysis."""
+    extraction_svc = getattr(request.app.state, "extraction_service", None)
+    if extraction_svc is None:
+        raise HTTPException(status_code=503, detail="Extraction service unavailable")
+
+    try:
+        extracted = await extraction_svc.extract_biomarkers(body.message)
+    except Exception as exc:
+        logger.exception("Biomarker extraction failed: %s", exc)
+        raise HTTPException(status_code=422, detail=f"Could not extract biomarkers: {exc}")
+
+    patient_ctx = body.patient_context.model_dump(exclude_none=True) if body.patient_context else {}
+    return await _run_guild_analysis(request, extracted, patient_ctx, extracted_biomarkers=extracted)
+
+
+@router.post("/structured", response_model=AnalysisResponse)
+async def analyze_structured(body: StructuredAnalysisRequest, request: Request):
+    """Run full analysis on pre-structured biomarker data."""
+    patient_ctx = body.patient_context.model_dump(exclude_none=True) if body.patient_context else {}
+    return await _run_guild_analysis(request, body.biomarkers, patient_ctx)

src/routers/ask.py

@@ -0,0 +1,53 @@
+"""
+MediGuard AI — Ask Router
+
+Free-form medical Q&A powered by the agentic RAG pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, HTTPException, Request
+
+from src.schemas.schemas import AskRequest, AskResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["ask"])
+
+
+@router.post("/ask", response_model=AskResponse)
+async def ask_medical_question(body: AskRequest, request: Request):
+    """Answer a free-form medical question via agentic RAG."""
+    rag_service = getattr(request.app.state, "rag_service", None)
+    if rag_service is None:
+        raise HTTPException(status_code=503, detail="RAG service unavailable")
+
+    request_id = f"req_{uuid.uuid4().hex[:12]}"
+    t0 = time.time()
+
+    try:
+        result = rag_service.ask(
+            query=body.question,
+            biomarkers=body.biomarkers,
+            patient_context=body.patient_context or "",
+        )
+    except Exception as exc:
+        logger.exception("Agentic RAG failed: %s", exc)
+        raise HTTPException(status_code=500, detail=f"RAG pipeline error: {exc}")
+
+    elapsed = (time.time() - t0) * 1000
+
+    return AskResponse(
+        status="success",
+        request_id=request_id,
+        question=body.question,
+        answer=result.get("final_answer", ""),
+        guardrail_score=result.get("guardrail_score"),
+        documents_retrieved=len(result.get("retrieved_documents", [])),
+        documents_relevant=len(result.get("relevant_documents", [])),
+        processing_time_ms=round(elapsed, 1),
+    )

src/routers/health.py

@@ -0,0 +1,101 @@
+"""
+MediGuard AI — Health Router
+
+Provides /health and /health/ready with per-service checks.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Request
+
+from src.schemas.schemas import HealthResponse, ServiceHealth
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check(request: Request) -> HealthResponse:
+    """Shallow liveness probe."""
+    app_state = request.app.state
+    uptime = time.time() - getattr(app_state, "start_time", time.time())
+    return HealthResponse(
+        status="healthy",
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        version=getattr(app_state, "version", "2.0.0"),
+        uptime_seconds=round(uptime, 2),
+    )
+
+
+@router.get("/health/ready", response_model=HealthResponse)
+async def readiness_check(request: Request) -> HealthResponse:
+    """Deep readiness probe — checks all backing services."""
+    app_state = request.app.state
+    uptime = time.time() - getattr(app_state, "start_time", time.time())
+    services: list[ServiceHealth] = []
+    overall = "healthy"
+
+    # --- OpenSearch ---
+    try:
+        os_client = getattr(app_state, "opensearch_client", None)
+        if os_client is not None:
+            t0 = time.time()
+            info = os_client.health()
+            latency = (time.time() - t0) * 1000
+            os_status = info.get("status", "unknown")
+            services.append(ServiceHealth(name="opensearch", status="ok" if os_status in ("green", "yellow") else "degraded", latency_ms=round(latency, 1)))
+        else:
+            services.append(ServiceHealth(name="opensearch", status="unavailable"))
+    except Exception as exc:
+        services.append(ServiceHealth(name="opensearch", status="unavailable", detail=str(exc)))
+        overall = "degraded"
+
+    # --- Redis ---
+    try:
+        cache = getattr(app_state, "cache", None)
+        if cache is not None:
+            t0 = time.time()
+            cache.set("__health__", "ok", ttl=10)
+            latency = (time.time() - t0) * 1000
+            services.append(ServiceHealth(name="redis", status="ok", latency_ms=round(latency, 1)))
+        else:
+            services.append(ServiceHealth(name="redis", status="unavailable"))
+    except Exception as exc:
+        services.append(ServiceHealth(name="redis", status="unavailable", detail=str(exc)))
+
+    # --- Ollama ---
+    try:
+        ollama = getattr(app_state, "ollama_client", None)
+        if ollama is not None:
+            t0 = time.time()
+            healthy = ollama.health()
+            latency = (time.time() - t0) * 1000
+            services.append(ServiceHealth(name="ollama", status="ok" if healthy else "degraded", latency_ms=round(latency, 1)))
+        else:
+            services.append(ServiceHealth(name="ollama", status="unavailable"))
+    except Exception as exc:
+        services.append(ServiceHealth(name="ollama", status="unavailable", detail=str(exc)))
+        overall = "degraded"
+
+    # --- Langfuse ---
+    try:
+        tracer = getattr(app_state, "tracer", None)
+        if tracer is not None:
+            services.append(ServiceHealth(name="langfuse", status="ok"))
+        else:
+            services.append(ServiceHealth(name="langfuse", status="unavailable"))
+    except Exception as exc:
+        services.append(ServiceHealth(name="langfuse", status="unavailable", detail=str(exc)))
+
+    if any(s.status == "unavailable" for s in services if s.name in ("opensearch", "ollama")):
+        overall = "unhealthy"
+
+    return HealthResponse(
+        status=overall,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        version=getattr(app_state, "version", "2.0.0"),
+        uptime_seconds=round(uptime, 2),
+        services=services,
+    )

src/routers/search.py

@@ -0,0 +1,72 @@
+"""
+MediGuard AI — Search Router
+
+Direct hybrid search endpoint (no LLM generation).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from fastapi import APIRouter, HTTPException, Request
+
+from src.schemas.schemas import SearchRequest, SearchResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["search"])
+
+
+@router.post("/search", response_model=SearchResponse)
+async def hybrid_search(body: SearchRequest, request: Request):
+    """Execute a direct hybrid search against the OpenSearch index."""
+    os_client = getattr(request.app.state, "opensearch_client", None)
+    embedding_service = getattr(request.app.state, "embedding_service", None)
+
+    if os_client is None:
+        raise HTTPException(status_code=503, detail="Search service unavailable")
+
+    t0 = time.time()
+
+    try:
+        if body.mode == "bm25":
+            results = os_client.search_bm25(query_text=body.query, top_k=body.top_k)
+        elif body.mode == "vector":
+            if embedding_service is None:
+                raise HTTPException(status_code=503, detail="Embedding service unavailable for vector search")
+            vec = embedding_service.embed_query(body.query)
+            results = os_client.search_vector(query_vector=vec, top_k=body.top_k)
+        else:
+            # hybrid
+            if embedding_service is None:
+                logger.warning("Embedding service unavailable — falling back to BM25")
+                results = os_client.search_bm25(query_text=body.query, top_k=body.top_k)
+            else:
+                vec = embedding_service.embed_query(body.query)
+                results = os_client.search_hybrid(query_text=body.query, query_vector=vec, top_k=body.top_k)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.exception("Search failed: %s", exc)
+        raise HTTPException(status_code=500, detail=f"Search error: {exc}")
+
+    elapsed = (time.time() - t0) * 1000
+
+    formatted = [
+        {
+            "id": hit.get("_id", ""),
+            "score": hit.get("_score", 0.0),
+            "title": hit.get("_source", {}).get("title", ""),
+            "section": hit.get("_source", {}).get("section_title", ""),
+            "text": hit.get("_source", {}).get("chunk_text", "")[:500],
+        }
+        for hit in results
+    ]
+
+    return SearchResponse(
+        query=body.query,
+        mode=body.mode,
+        total_hits=len(formatted),
+        results=formatted,
+        processing_time_ms=round(elapsed, 1),
+    )

src/schemas/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — API request/response schemas."""

src/schemas/schemas.py

@@ -0,0 +1,247 @@
+"""
+MediGuard AI — Production API Schemas
+
+Pydantic v2 request/response models for the new production API layer.
+Keeps backward compatibility with existing schemas where possible.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+# ============================================================================
+# REQUEST MODELS
+# ============================================================================
+
+
+class PatientContext(BaseModel):
+    """Patient demographic and context information."""
+
+    age: Optional[int] = Field(None, ge=0, le=120, description="Patient age in years")
+    gender: Optional[str] = Field(None, description="Patient gender (male/female)")
+    bmi: Optional[float] = Field(None, ge=10, le=60, description="Body Mass Index")
+    patient_id: Optional[str] = Field(None, description="Patient identifier")
+
+
+class NaturalAnalysisRequest(BaseModel):
+    """Natural language biomarker analysis request."""
+
+    message: str = Field(
+        ..., min_length=5, max_length=2000,
+        description="Natural language message with biomarker values",
+    )
+    patient_context: Optional[PatientContext] = Field(
+        default_factory=PatientContext,
+    )
+
+
+class StructuredAnalysisRequest(BaseModel):
+    """Structured biomarker analysis request."""
+
+    biomarkers: Dict[str, float] = Field(
+        ..., description="Dict of biomarker name → measured value",
+    )
+    patient_context: Optional[PatientContext] = Field(
+        default_factory=PatientContext,
+    )
+
+    @field_validator("biomarkers")
+    @classmethod
+    def biomarkers_not_empty(cls, v: Dict[str, float]) -> Dict[str, float]:
+        if not v:
+            raise ValueError("biomarkers must contain at least one entry")
+        return v
+
+
+class AskRequest(BaseModel):
+    """Free‑form medical question (agentic RAG pipeline)."""
+
+    question: str = Field(
+        ..., min_length=3, max_length=4000,
+        description="Medical question",
+    )
+    biomarkers: Optional[Dict[str, float]] = Field(
+        None, description="Optional biomarker context",
+    )
+    patient_context: Optional[str] = Field(
+        None, description="Free‑text patient context",
+    )
+
+
+class SearchRequest(BaseModel):
+    """Direct hybrid search (no LLM generation)."""
+
+    query: str = Field(..., min_length=2, max_length=1000)
+    top_k: int = Field(10, ge=1, le=100)
+    mode: str = Field("hybrid", description="Search mode: bm25 | vector | hybrid")
+
+
+# ============================================================================
+# RESPONSE BUILDING BLOCKS
+# ============================================================================
+
+
+class BiomarkerFlag(BaseModel):
+    name: str
+    value: float
+    unit: str
+    status: str
+    reference_range: str
+    warning: Optional[str] = None
+
+
+class SafetyAlert(BaseModel):
+    severity: str
+    biomarker: Optional[str] = None
+    message: str
+    action: str
+
+
+class KeyDriver(BaseModel):
+    biomarker: str
+    value: Any
+    contribution: Optional[str] = None
+    explanation: str
+    evidence: Optional[str] = None
+
+
+class Prediction(BaseModel):
+    disease: str
+    confidence: float = Field(ge=0, le=1)
+    probabilities: Dict[str, float]
+
+
+class DiseaseExplanation(BaseModel):
+    pathophysiology: str
+    citations: List[str] = Field(default_factory=list)
+    retrieved_chunks: Optional[List[Dict[str, Any]]] = None
+
+
+class Recommendations(BaseModel):
+    immediate_actions: List[str] = Field(default_factory=list)
+    lifestyle_changes: List[str] = Field(default_factory=list)
+    monitoring: List[str] = Field(default_factory=list)
+    follow_up: Optional[str] = None
+
+
+class ConfidenceAssessment(BaseModel):
+    prediction_reliability: str
+    evidence_strength: str
+    limitations: List[str] = Field(default_factory=list)
+    reasoning: Optional[str] = None
+
+
+class AgentOutput(BaseModel):
+    agent_name: str
+    findings: Any
+    metadata: Optional[Dict[str, Any]] = None
+    execution_time_ms: Optional[float] = None
+
+
+class Analysis(BaseModel):
+    biomarker_flags: List[BiomarkerFlag]
+    safety_alerts: List[SafetyAlert]
+    key_drivers: List[KeyDriver]
+    disease_explanation: DiseaseExplanation
+    recommendations: Recommendations
+    confidence_assessment: ConfidenceAssessment
+    alternative_diagnoses: Optional[List[Dict[str, Any]]] = None
+
+
+# ============================================================================
+# TOP‑LEVEL RESPONSES
+# ============================================================================
+
+
+class AnalysisResponse(BaseModel):
+    """Full clinical analysis response (backward‑compatible)."""
+
+    status: str
+    request_id: str
+    timestamp: str
+    extracted_biomarkers: Optional[Dict[str, float]] = None
+    input_biomarkers: Dict[str, float]
+    patient_context: Dict[str, Any]
+    prediction: Prediction
+    analysis: Analysis
+    agent_outputs: List[AgentOutput]
+    workflow_metadata: Dict[str, Any]
+    conversational_summary: Optional[str] = None
+    processing_time_ms: float
+    sop_version: Optional[str] = None
+
+
+class AskResponse(BaseModel):
+    """Response from the agentic RAG /ask endpoint."""
+
+    status: str = "success"
+    request_id: str
+    question: str
+    answer: str
+    guardrail_score: Optional[float] = None
+    documents_retrieved: int = 0
+    documents_relevant: int = 0
+    processing_time_ms: float = 0.0
+
+
+class SearchResponse(BaseModel):
+    """Direct hybrid search response."""
+
+    status: str = "success"
+    query: str
+    mode: str
+    total_hits: int
+    results: List[Dict[str, Any]]
+    processing_time_ms: float = 0.0
+
+
+class ErrorResponse(BaseModel):
+    """Error envelope."""
+
+    status: str = "error"
+    error_code: str
+    message: str
+    details: Optional[Dict[str, Any]] = None
+    timestamp: str
+    request_id: Optional[str] = None
+
+
+# ============================================================================
+# HEALTH / INFO
+# ============================================================================
+
+
+class ServiceHealth(BaseModel):
+    name: str
+    status: str  # ok | degraded | unavailable
+    latency_ms: Optional[float] = None
+    detail: Optional[str] = None
+
+
+class HealthResponse(BaseModel):
+    """Production health check."""
+
+    status: str  # healthy | degraded | unhealthy
+    timestamp: str
+    version: str
+    uptime_seconds: float
+    services: List[ServiceHealth] = Field(default_factory=list)
+
+
+class BiomarkerReferenceRange(BaseModel):
+    min: Optional[float] = None
+    max: Optional[float] = None
+    male: Optional[Dict[str, float]] = None
+    female: Optional[Dict[str, float]] = None
+
+
+class BiomarkerInfo(BaseModel):
+    name: str
+    unit: str
+    normal_range: BiomarkerReferenceRange
+    critical_low: Optional[float] = None
+    critical_high: Optional[float] = None

src/services/agents/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Agentic RAG agents package."""

src/services/agents/agentic_rag.py

@@ -0,0 +1,158 @@
+"""
+MediGuard AI — Agentic RAG Orchestrator
+
+LangGraph StateGraph that wires all nodes into the guardrail → retrieve → grade → generate pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache, partial
+from typing import Any
+
+from langgraph.graph import END, StateGraph
+
+from src.services.agents.context import AgenticContext
+from src.services.agents.nodes.generate_answer_node import generate_answer_node
+from src.services.agents.nodes.grade_documents_node import grade_documents_node
+from src.services.agents.nodes.guardrail_node import guardrail_node
+from src.services.agents.nodes.out_of_scope_node import out_of_scope_node
+from src.services.agents.nodes.retrieve_node import retrieve_node
+from src.services.agents.nodes.rewrite_query_node import rewrite_query_node
+from src.services.agents.state import AgenticRAGState
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Edge routing helpers
+# ---------------------------------------------------------------------------
+
+
+def _route_after_guardrail(state: dict) -> str:
+    """Decide path after guardrail evaluation."""
+    if state.get("routing_decision") == "analyze":
+        # Biomarker analysis pathway — goes straight to retrieve
+        return "retrieve"
+    if state.get("is_in_scope"):
+        return "retrieve"
+    return "out_of_scope"
+
+
+def _route_after_grading(state: dict) -> str:
+    """Decide whether to rewrite query or proceed to generation."""
+    if state.get("needs_rewrite"):
+        return "rewrite_query"
+    if not state.get("relevant_documents"):
+        return "generate_answer"  # will produce a "no evidence found" answer
+    return "generate_answer"
+
+
+# ---------------------------------------------------------------------------
+# Graph builder
+# ---------------------------------------------------------------------------
+
+
+def build_agentic_rag_graph(context: AgenticContext) -> Any:
+    """Construct the compiled LangGraph for the agentic RAG pipeline.
+
+    Parameters
+    ----------
+    context:
+        Runtime dependencies (LLM, OpenSearch, embeddings, cache, tracer).
+
+    Returns
+    -------
+    Compiled LangGraph graph ready for ``.invoke()`` / ``.stream()``.
+    """
+    workflow = StateGraph(AgenticRAGState)
+
+    # Bind context to every node via functools.partial
+    workflow.add_node("guardrail", partial(guardrail_node, context=context))
+    workflow.add_node("retrieve", partial(retrieve_node, context=context))
+    workflow.add_node("grade_documents", partial(grade_documents_node, context=context))
+    workflow.add_node("rewrite_query", partial(rewrite_query_node, context=context))
+    workflow.add_node("generate_answer", partial(generate_answer_node, context=context))
+    workflow.add_node("out_of_scope", partial(out_of_scope_node, context=context))
+
+    # Entry point
+    workflow.set_entry_point("guardrail")
+
+    # Conditional edges
+    workflow.add_conditional_edges(
+        "guardrail",
+        _route_after_guardrail,
+        {
+            "retrieve": "retrieve",
+            "out_of_scope": "out_of_scope",
+        },
+    )
+
+    workflow.add_edge("retrieve", "grade_documents")
+
+    workflow.add_conditional_edges(
+        "grade_documents",
+        _route_after_grading,
+        {
+            "rewrite_query": "rewrite_query",
+            "generate_answer": "generate_answer",
+        },
+    )
+
+    # After rewrite, loop back to retrieve
+    workflow.add_edge("rewrite_query", "retrieve")
+
+    # Terminal edges
+    workflow.add_edge("generate_answer", END)
+    workflow.add_edge("out_of_scope", END)
+
+    return workflow.compile()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+class AgenticRAGService:
+    """High-level wrapper around the compiled RAG graph."""
+
+    def __init__(self, context: AgenticContext) -> None:
+        self._context = context
+        self._graph = build_agentic_rag_graph(context)
+
+    def ask(
+        self,
+        query: str,
+        biomarkers: dict | None = None,
+        patient_context: str = "",
+    ) -> dict:
+        """Run the full agentic RAG pipeline and return the final state."""
+        initial_state: dict[str, Any] = {
+            "query": query,
+            "biomarkers": biomarkers,
+            "patient_context": patient_context,
+            "errors": [],
+        }
+
+        span = None
+        try:
+            if self._context.tracer:
+                span = self._context.tracer.start_span(
+                    name="agentic_rag_ask",
+                    metadata={"query": query},
+                )
+            result = self._graph.invoke(initial_state)
+            return result
+        except Exception as exc:
+            logger.error("Agentic RAG pipeline failed: %s", exc)
+            return {
+                **initial_state,
+                "final_answer": (
+                    "I apologize, but I'm temporarily unable to process your request. "
+                    "Please consult a healthcare professional."
+                ),
+                "errors": [str(exc)],
+            }
+        finally:
+            if span is not None:
+                self._context.tracer.end_span(span)

src/services/agents/context.py

@@ -0,0 +1,23 @@
+"""
+MediGuard AI — Agentic RAG Context
+
+Runtime dependency injection dataclass — passed to every LangGraph node
+so nodes can access services without globals.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass(frozen=True)
+class AgenticContext:
+    """Immutable runtime context for agentic RAG nodes."""
+
+    llm: Any                         # LangChain chat model
+    embedding_service: Any           # EmbeddingService
+    opensearch_client: Any           # OpenSearchClient
+    cache: Any                       # RedisCache
+    tracer: Any                      # LangfuseTracer
+    guild: Optional[Any] = None      # ClinicalInsightGuild (original workflow)

src/services/agents/medical/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Medical agents (original 6 agents, re-exported)."""

src/services/agents/nodes/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Agentic RAG nodes package."""

src/services/agents/nodes/generate_answer_node.py

@@ -0,0 +1,60 @@
+"""
+MediGuard AI — Generate Answer Node
+
+Produces a RAG-grounded medical answer with citations.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from src.services.agents.prompts import RAG_GENERATION_SYSTEM
+
+logger = logging.getLogger(__name__)
+
+
+def generate_answer_node(state: dict, *, context: Any) -> dict:
+    """Generate a cited medical answer from relevant documents."""
+    query = state.get("rewritten_query") or state.get("query", "")
+    documents = state.get("relevant_documents", [])
+    biomarkers = state.get("biomarkers")
+    patient_context = state.get("patient_context", "")
+
+    # Build evidence block
+    evidence_parts: list[str] = []
+    for i, doc in enumerate(documents, 1):
+        title = doc.get("title", "Unknown")
+        section = doc.get("section", "")
+        text = doc.get("text", "")[:2000]
+        header = f"[{i}] {title}"
+        if section:
+            header += f" — {section}"
+        evidence_parts.append(f"{header}\n{text}")
+    evidence_block = "\n\n---\n\n".join(evidence_parts) if evidence_parts else "(No evidence retrieved)"
+
+    # Build user message
+    user_msg = f"Question: {query}\n\n"
+    if biomarkers:
+        user_msg += f"Biomarkers: {biomarkers}\n\n"
+    if patient_context:
+        user_msg += f"Patient context: {patient_context}\n\n"
+    user_msg += f"Evidence:\n{evidence_block}"
+
+    try:
+        response = context.llm.invoke(
+            [
+                {"role": "system", "content": RAG_GENERATION_SYSTEM},
+                {"role": "user", "content": user_msg},
+            ]
+        )
+        answer = response.content.strip()
+    except Exception as exc:
+        logger.error("Generation LLM failed: %s", exc)
+        answer = (
+            "I apologize, but I'm temporarily unable to generate a response. "
+            "Please consult a healthcare professional for guidance."
+        )
+        return {"final_answer": answer, "errors": [str(exc)]}
+
+    return {"final_answer": answer}

src/services/agents/nodes/grade_documents_node.py

@@ -0,0 +1,64 @@
+"""
+MediGuard AI — Grade Documents Node
+
+Uses the LLM to judge whether each retrieved document is relevant to the query.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from src.services.agents.prompts import GRADING_SYSTEM
+
+logger = logging.getLogger(__name__)
+
+
+def grade_documents_node(state: dict, *, context: Any) -> dict:
+    """Grade each retrieved document for relevance."""
+    query = state.get("rewritten_query") or state.get("query", "")
+    documents = state.get("retrieved_documents", [])
+
+    if not documents:
+        return {
+            "grading_results": [],
+            "relevant_documents": [],
+            "needs_rewrite": True,
+        }
+
+    relevant: list[dict] = []
+    grading_results: list[dict] = []
+
+    for doc in documents:
+        text = doc.get("text", "")
+        user_msg = f"Query: {query}\n\nDocument:\n{text[:2000]}"
+        try:
+            response = context.llm.invoke(
+                [
+                    {"role": "system", "content": GRADING_SYSTEM},
+                    {"role": "user", "content": user_msg},
+                ]
+            )
+            content = response.content.strip()
+            if "```" in content:
+                content = content.split("```")[1].split("```")[0].strip()
+                if content.startswith("json"):
+                    content = content[4:].strip()
+            data = json.loads(content)
+            is_relevant = str(data.get("relevant", "false")).lower() == "true"
+        except Exception as exc:
+            logger.warning("Grading LLM failed for doc %s: %s — marking relevant", doc.get("id"), exc)
+            is_relevant = True  # benefit of the doubt
+
+        grading_results.append({"doc_id": doc.get("id"), "relevant": is_relevant})
+        if is_relevant:
+            relevant.append(doc)
+
+    needs_rewrite = len(relevant) < 2 and not state.get("rewritten_query")
+
+    return {
+        "grading_results": grading_results,
+        "relevant_documents": relevant,
+        "needs_rewrite": needs_rewrite,
+    }

src/services/agents/nodes/guardrail_node.py

@@ -0,0 +1,57 @@
+"""
+MediGuard AI — Guardrail Node
+
+Validates that the user query is within the medical domain (score 0-100).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from src.services.agents.prompts import GUARDRAIL_SYSTEM
+
+logger = logging.getLogger(__name__)
+
+
+def guardrail_node(state: dict, *, context: Any) -> dict:
+    """Score the query for medical relevance (0-100)."""
+    query = state.get("query", "")
+    biomarkers = state.get("biomarkers")
+
+    # Fast path: if biomarkers are provided, it's definitely medical
+    if biomarkers:
+        return {
+            "guardrail_score": 95.0,
+            "is_in_scope": True,
+            "routing_decision": "analyze",
+        }
+
+    try:
+        response = context.llm.invoke(
+            [
+                {"role": "system", "content": GUARDRAIL_SYSTEM},
+                {"role": "user", "content": query},
+            ]
+        )
+        content = response.content.strip()
+        # Parse JSON response
+        if "```" in content:
+            content = content.split("```")[1].split("```")[0].strip()
+            if content.startswith("json"):
+                content = content[4:].strip()
+        data = json.loads(content)
+        score = float(data.get("score", 0))
+    except Exception as exc:
+        logger.warning("Guardrail LLM failed: %s — defaulting to in-scope", exc)
+        score = 70.0  # benefit of the doubt
+
+    is_in_scope = score >= 40
+    routing = "rag_answer" if is_in_scope else "out_of_scope"
+
+    return {
+        "guardrail_score": score,
+        "is_in_scope": is_in_scope,
+        "routing_decision": routing,
+    }

src/services/agents/nodes/out_of_scope_node.py

@@ -0,0 +1,16 @@
+"""
+MediGuard AI — Out-of-Scope Node
+
+Returns a polite rejection for non-medical queries.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src.services.agents.prompts import OUT_OF_SCOPE_RESPONSE
+
+
+def out_of_scope_node(state: dict, *, context: Any) -> dict:
+    """Return polite out-of-scope message."""
+    return {"final_answer": OUT_OF_SCOPE_RESPONSE}

src/services/agents/nodes/retrieve_node.py

@@ -0,0 +1,68 @@
+"""
+MediGuard AI — Retrieve Node
+
+Performs hybrid search (BM25 + vector KNN) and merges results.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def retrieve_node(state: dict, *, context: Any) -> dict:
+    """Retrieve documents from OpenSearch via hybrid search."""
+    query = state.get("rewritten_query") or state.get("query", "")
+
+    # 1. Try cache first
+    cache_key = f"retrieve:{query}"
+    if context.cache:
+        cached = context.cache.get(cache_key)
+        if cached is not None:
+            logger.debug("Cache hit for retrieve query")
+            return {"retrieved_documents": cached}
+
+    # 2. Embed the query
+    try:
+        query_embedding = context.embedding_service.embed_query(query)
+    except Exception as exc:
+        logger.error("Embedding failed: %s", exc)
+        return {"retrieved_documents": [], "errors": [str(exc)]}
+
+    # 3. Hybrid search
+    try:
+        results = context.opensearch_client.search_hybrid(
+            query_text=query,
+            query_vector=query_embedding,
+            top_k=10,
+        )
+    except Exception as exc:
+        logger.error("OpenSearch hybrid search failed: %s — falling back to BM25", exc)
+        try:
+            results = context.opensearch_client.search_bm25(
+                query_text=query,
+                top_k=10,
+            )
+        except Exception as exc2:
+            logger.error("BM25 fallback also failed: %s", exc2)
+            return {"retrieved_documents": [], "errors": [str(exc), str(exc2)]}
+
+    documents = [
+        {
+            "id": hit.get("_id", ""),
+            "score": hit.get("_score", 0.0),
+            "text": hit.get("_source", {}).get("chunk_text", ""),
+            "title": hit.get("_source", {}).get("title", ""),
+            "section": hit.get("_source", {}).get("section_title", ""),
+            "metadata": hit.get("_source", {}),
+        }
+        for hit in results
+    ]
+
+    # 4. Store in cache (5 min TTL)
+    if context.cache:
+        context.cache.set(cache_key, documents, ttl=300)
+
+    return {"retrieved_documents": documents}