feat: production upgrade — agentic RAG, OpenSearch, Redis, Langfuse, Docker, Gradio, Telegram

Phase 1: Project structure & dev tooling
- pyproject.toml with Ruff/MyPy/pytest config and optional deps
- Makefile with dev/test/docker/lint targets
- Multi-stage Dockerfile + docker-compose.yml (12 services)
- .env.example, .pre-commit-config.yaml

Phase 2: Core infrastructure
- src/settings.py: hierarchical Pydantic Settings (env-driven)
- src/exceptions.py: domain exception hierarchy (15+ classes)
- src/database.py: SQLAlchemy engine/session factory
- src/models/analysis.py: ORM models (PatientAnalysis, MedicalDocument, SOPVersion)
- src/repositories/: data access layer

Phase 3: Production services
- OpenSearch client with BM25, KNN vector, and hybrid RRF search
- Medical synonym analyzer + KNN index mapping (1024d, HNSW)
- Multi-provider embedding service (Jina/Google/HuggingFace) with fallback
- Redis cache with graceful degradation (NullCache)
- Langfuse v3 observability tracer (NullSpan for no-ops)
- Ollama REST client with streaming + LangChain integration
- Medical-aware text chunker with biomarker/condition detection
- Indexing pipeline (chunk → embed → OpenSearch)

Phase 4: Agentic RAG pipeline (LangGraph)
- Guardrail node: medical domain validation (0-100 scoring)
- Retrieve node: hybrid search with cache
- Grade documents node: LLM relevance grading
- Rewrite query node: query improvement loop
- Generate answer node: RAG with citations + safety disclaimers
- Out-of-scope node: polite rejection
- AgenticRAGService orchestrator with compiled StateGraph

Phase 5: Production FastAPI application
- src/main.py: app factory with lifespan (all services init/teardown)
- Routers: /health, /health/ready, /analyze/*, /ask, /search
- src/schemas/schemas.py: full Pydantic v2 request/response models
- src/dependencies.py: DI factories

Phase 6: Additional services
- Biomarker validation service (wraps existing validator)
- PDF parser service (Docling → PyPDF fallback)
- Telegram bot (proxies to /ask endpoint)
- Gradio web UI (ask/analyze/search tabs)

Phase 7: Orchestration
- Airflow DAGs: PDF ingestion + SOP evolution

Tests: 94 passed (11 new test files, 60+ new test cases)

.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=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
+LLM__GROQ_MODEL=llama-3.3-70b-versatile
+LLM__GEMINI_API_KEY=AIzaSyBbWG-vy44GXuZL-PgNjtvKLXrhdINCgwg
+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

.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]

Dockerfile

@@ -0,0 +1,66 @@
+# ===========================================================================
+# MediGuard AI — Multi-stage Dockerfile
+# ===========================================================================
+# Build stages:
+#   base        — Python + system deps
+#   production  — slim runtime image
+# ===========================================================================
+
+# ---------------------------------------------------------------------------
+# Stage 1: base
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY pyproject.toml ./
+RUN pip install --upgrade pip && \
+    pip install ".[all]"
+
+# ---------------------------------------------------------------------------
+# Stage 2: production
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim AS production
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Copy installed packages from base
+COPY --from=base /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=base /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY . .
+
+# Runtime dependencies only
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN groupadd -r mediguard && \
+    useradd -r -g mediguard -d /app -s /sbin/nologin mediguard && \
+    chown -R mediguard:mediguard /app
+
+USER mediguard
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -sf http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

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

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,
+    )

docker-compose.yml

@@ -0,0 +1,166 @@
+# ===========================================================================
+# 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.19.0
+    container_name: mediguard-opensearch
+    environment:
+      - discovery.type=single-node
+      - DISABLE_SECURITY_PLUGIN=true
+      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
+      - 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: 20
+    restart: unless-stopped
+
+  opensearch-dashboards:
+    image: opensearchproject/opensearch-dashboards:2.19.0
+    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:

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"]

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/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}

src/services/agents/nodes/rewrite_query_node.py

@@ -0,0 +1,40 @@
+"""
+MediGuard AI — Rewrite Query Node
+
+Reformulates the user query to improve retrieval recall.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from src.services.agents.prompts import REWRITE_SYSTEM
+
+logger = logging.getLogger(__name__)
+
+
+def rewrite_query_node(state: dict, *, context: Any) -> dict:
+    """Rewrite the original query for better retrieval."""
+    original = state.get("query", "")
+    patient_context = state.get("patient_context", "")
+
+    user_msg = f"Original query: {original}"
+    if patient_context:
+        user_msg += f"\n\nPatient context: {patient_context}"
+
+    try:
+        response = context.llm.invoke(
+            [
+                {"role": "system", "content": REWRITE_SYSTEM},
+                {"role": "user", "content": user_msg},
+            ]
+        )
+        rewritten = response.content.strip()
+        if not rewritten:
+            rewritten = original
+    except Exception as exc:
+        logger.warning("Rewrite LLM failed: %s — keeping original query", exc)
+        rewritten = original
+
+    return {"rewritten_query": rewritten}

src/services/agents/prompts.py

@@ -0,0 +1,72 @@
+"""
+MediGuard AI — Agentic RAG Prompts
+
+Medical-domain prompts for guardrail, grading, rewriting, and generation.
+"""
+
+# ── Guardrail prompt ─────────────────────────────────────────────────────────
+
+GUARDRAIL_SYSTEM = """\
+You are a medical-domain classifier.  Determine whether the user query is
+about health, biomarkers, medical conditions, clinical guidelines, or
+wellness — topics that MediGuard AI can help with.
+
+Score the query from 0 to 100:
+  90-100  Clearly medical (biomarker values, disease questions, symptoms)
+  60-89   Health-adjacent (nutrition, fitness, wellness)
+  30-59   Loosely related (general biology, anatomy trivia)
+   0-29   Not medical at all (weather, coding, sports)
+
+Respond ONLY with JSON:
+{{"score": <int>, "reason": "<one-sentence explanation>"}}
+"""
+
+# ── Document grading prompt ──────────────────────────────────────────────────
+
+GRADING_SYSTEM = """\
+You are a medical-relevance grader.  Given a user question and a retrieved
+document chunk, decide whether the document is relevant to answering the
+medical question.
+
+Respond ONLY with JSON:
+{{"relevant": true/false, "reason": "<one sentence>"}}
+"""
+
+# ── Query rewriting prompt ───────────────────────────────────────────────────
+
+REWRITE_SYSTEM = """\
+You are a medical-query optimiser.  The original user query did not
+retrieve relevant medical documents.  Rewrite it to improve retrieval from
+a medical knowledge base.
+
+Guidelines:
+- Use standard medical terminology
+- Add synonyms for biomarker names
+- Make the intent clearer
+
+Respond with ONLY the rewritten query (no explanation, no quotes).
+"""
+
+# ── RAG generation prompt ────────────────────────────────────────────────────
+
+RAG_GENERATION_SYSTEM = """\
+You are MediGuard AI, a clinical-information assistant.
+Answer the user's medical question using ONLY the provided context documents.
+If the context is insufficient, say so honestly.
+
+Rules:
+1. Cite specific documents with [Source: filename, Page X].
+2. Use patient-friendly language.
+3. Never provide a definitive diagnosis — use "may indicate", "suggests".
+4. Always end with: "Please consult a healthcare professional for diagnosis."
+5. If biomarker values are critical, highlight them as safety alerts.
+"""
+
+# ── Out-of-scope response ───────────────────────────────────────────────────
+
+OUT_OF_SCOPE_RESPONSE = (
+    "I'm MediGuard AI — I specialise in medical biomarker analysis and "
+    "health-related questions. Your query doesn't appear to be about a "
+    "medical or health topic I can help with. Please try asking about "
+    "biomarker values, disease information, or clinical guidelines."
+)

src/services/agents/state.py

@@ -0,0 +1,47 @@
+"""
+MediGuard AI — Agentic RAG State
+
+Enhanced LangGraph state for the guardrail → retrieve → grade → generate
+pipeline that wraps the existing 6-agent clinical workflow.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Annotated
+from typing_extensions import TypedDict
+import operator
+
+
+class AgenticRAGState(TypedDict):
+    """State flowing through the agentic RAG graph."""
+
+    # ── Input ────────────────────────────────────────────────────────────
+    query: str
+    biomarkers: Optional[Dict[str, float]]
+    patient_context: Optional[Dict[str, Any]]
+
+    # ── Guardrail ────────────────────────────────────────────────────────
+    guardrail_score: float            # 0-100 medical-relevance score
+    is_in_scope: bool                 # passed guardrail?
+
+    # ── Retrieval ────────────────────────────────────────────────────────
+    retrieved_documents: List[Dict[str, Any]]
+    retrieval_attempts: int
+    max_retrieval_attempts: int
+
+    # ── Grading ──────────────────────────────────────────────────────────
+    grading_results: List[Dict[str, Any]]
+    relevant_documents: List[Dict[str, Any]]
+    needs_rewrite: bool
+
+    # ── Rewriting ────────────────────────────────────────────────────────
+    rewritten_query: Optional[str]
+
+    # ── Generation / routing ─────────────────────────────────────────────
+    routing_decision: str             # "analyze" | "rag_answer" | "out_of_scope"
+    final_answer: Optional[str]
+    analysis_result: Optional[Dict[str, Any]]
+
+    # ── Metadata ─────────────────────────────────────────────────────────
+    trace_id: Optional[str]
+    errors: Annotated[List[str], operator.add]

src/services/biomarker/__init__.py

@@ -0,0 +1 @@
+"""MediGuard AI — Biomarker validation service."""

src/services/biomarker/service.py

@@ -0,0 +1,110 @@
+"""
+MediGuard AI — Biomarker Validation Service
+
+Wraps the existing BiomarkerValidator as a production service with caching,
+observability, and Pydantic-typed outputs.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Dict, List, Optional
+
+from src.biomarker_validator import BiomarkerValidator
+from src.biomarker_normalization import normalize_biomarker_name
+from src.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class BiomarkerResult:
+    """Validated result for a single biomarker."""
+
+    name: str
+    value: float
+    unit: str
+    status: str  # NORMAL | HIGH | LOW | CRITICAL_HIGH | CRITICAL_LOW
+    reference_range: str
+    warning: Optional[str] = None
+
+
+@dataclass
+class ValidationReport:
+    """Complete biomarker validation report."""
+
+    results: List[BiomarkerResult] = field(default_factory=list)
+    safety_alerts: List[Dict[str, Any]] = field(default_factory=list)
+    recognized_count: int = 0
+    unrecognized: List[str] = field(default_factory=list)
+
+
+class BiomarkerService:
+    """Production biomarker validation service."""
+
+    def __init__(self) -> None:
+        self._validator = BiomarkerValidator()
+
+    # --------------------------------------------------------------------- #
+    # Public API
+    # --------------------------------------------------------------------- #
+
+    def validate(
+        self,
+        biomarkers: Dict[str, float],
+        gender: Optional[str] = None,
+    ) -> ValidationReport:
+        """Validate a dict of biomarker name → value and return a report."""
+        report = ValidationReport()
+
+        for raw_name, value in biomarkers.items():
+            normalized = normalize_biomarker_name(raw_name)
+            flag = self._validator.validate_biomarker(normalized, value, gender=gender)
+            if flag is None:
+                report.unrecognized.append(raw_name)
+                continue
+            if flag.status == "UNKNOWN":
+                report.unrecognized.append(raw_name)
+                continue
+            report.recognized_count += 1
+            report.results.append(
+                BiomarkerResult(
+                    name=flag.name,
+                    value=flag.value,
+                    unit=flag.unit,
+                    status=flag.status,
+                    reference_range=flag.reference_range,
+                    warning=flag.warning,
+                )
+            )
+            if flag.status.startswith("CRITICAL"):
+                report.safety_alerts.append(
+                    {
+                        "severity": "CRITICAL",
+                        "biomarker": normalized,
+                        "message": flag.warning or f"{normalized} is critically out of range",
+                        "action": "Seek immediate medical attention",
+                    }
+                )
+
+        return report
+
+    def list_supported(self) -> List[Dict[str, Any]]:
+        """Return metadata for all supported biomarkers."""
+        result = []
+        for name, ref in self._validator.references.items():
+            result.append({
+                "name": name,
+                "unit": ref.get("unit", ""),
+                "normal_range": ref.get("normal_range", {}),
+                "critical_low": ref.get("critical_low"),
+                "critical_high": ref.get("critical_high"),
+            })
+        return result
+
+
+@lru_cache(maxsize=1)
+def make_biomarker_service() -> BiomarkerService:
+    return BiomarkerService()

src/services/cache/__init__.py

@@ -0,0 +1,4 @@
+"""MediGuard AI — Redis cache service package."""
+from src.services.cache.redis_cache import RedisCache, make_redis_cache
+
+__all__ = ["RedisCache", "make_redis_cache"]

src/services/cache/redis_cache.py

@@ -0,0 +1,123 @@
+"""
+MediGuard AI — Redis Cache
+
+Exact-match caching with SHA-256 keys for RAG and analysis responses.
+Gracefully degrades when Redis is unavailable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from functools import lru_cache
+from typing import Any, Dict, Optional
+
+from src.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+try:
+    import redis as _redis
+except ImportError:  # pragma: no cover
+    _redis = None  # type: ignore[assignment]
+
+
+class RedisCache:
+    """Thin Redis wrapper with SHA-256 key generation and JSON ser/de."""
+
+    def __init__(self, client: Any, default_ttl: int = 21600):
+        self._client = client
+        self._default_ttl = default_ttl
+        self._enabled = client is not None
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    def ping(self) -> bool:
+        if not self._enabled:
+            return False
+        try:
+            return self._client.ping()
+        except Exception:
+            return False
+
+    @staticmethod
+    def _make_key(*parts: str) -> str:
+        raw = "|".join(parts)
+        return f"mediguard:{hashlib.sha256(raw.encode()).hexdigest()}"
+
+    def get(self, *key_parts: str) -> Optional[Dict[str, Any]]:
+        if not self._enabled:
+            return None
+        key = self._make_key(*key_parts)
+        try:
+            value = self._client.get(key)
+            if value is None:
+                return None
+            return json.loads(value)
+        except Exception as exc:
+            logger.warning("Cache GET failed: %s", exc)
+            return None
+
+    def set(self, value: Dict[str, Any], *key_parts: str, ttl: Optional[int] = None) -> bool:
+        if not self._enabled:
+            return False
+        key = self._make_key(*key_parts)
+        try:
+            self._client.setex(key, ttl or self._default_ttl, json.dumps(value, default=str))
+            return True
+        except Exception as exc:
+            logger.warning("Cache SET failed: %s", exc)
+            return False
+
+    def delete(self, *key_parts: str) -> bool:
+        if not self._enabled:
+            return False
+        key = self._make_key(*key_parts)
+        try:
+            self._client.delete(key)
+            return True
+        except Exception as exc:
+            logger.warning("Cache DELETE failed: %s", exc)
+            return False
+
+    def flush(self) -> bool:
+        if not self._enabled:
+            return False
+        try:
+            self._client.flushdb()
+            return True
+        except Exception:
+            return False
+
+
+class _NullCache(RedisCache):
+    """No-op cache returned when Redis is disabled or unavailable."""
+
+    def __init__(self):
+        super().__init__(client=None)
+
+
+@lru_cache(maxsize=1)
+def make_redis_cache() -> RedisCache:
+    """Factory — returns a live cache or a silent null-cache."""
+    settings = get_settings()
+    if not settings.redis.enabled or _redis is None:
+        logger.info("Redis caching disabled")
+        return _NullCache()
+    try:
+        client = _redis.Redis(
+            host=settings.redis.host,
+            port=settings.redis.port,
+            db=settings.redis.db,
+            decode_responses=True,
+            socket_connect_timeout=3,
+        )
+        client.ping()
+        logger.info("Redis connected (%s:%d)", settings.redis.host, settings.redis.port)
+        return RedisCache(client, settings.redis.ttl_seconds)
+    except Exception as exc:
+        logger.warning("Redis unavailable (%s), running without cache", exc)
+        return _NullCache()

src/services/embeddings/__init__.py

@@ -0,0 +1,4 @@
+"""MediGuard AI — Embeddings service package."""
+from src.services.embeddings.service import EmbeddingService, make_embedding_service
+
+__all__ = ["EmbeddingService", "make_embedding_service"]

src/services/embeddings/service.py

@@ -0,0 +1,147 @@
+"""
+MediGuard AI — Embedding Service
+
+Supports Jina AI, Google, HuggingFace, and Ollama embeddings with
+automatic fallback chain: Jina → Google → HuggingFace.
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import List
+
+from src.exceptions import EmbeddingError, EmbeddingProviderError
+from src.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class EmbeddingService:
+    """Unified embedding interface — delegates to the configured provider."""
+
+    def __init__(self, model, provider_name: str, dimension: int):
+        self._model = model
+        self.provider_name = provider_name
+        self.dimension = dimension
+
+    def embed_query(self, text: str) -> List[float]:
+        """Embed a single query text."""
+        try:
+            return self._model.embed_query(text)
+        except Exception as exc:
+            raise EmbeddingProviderError(f"{self.provider_name} embed_query failed: {exc}")
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Batch-embed a list of texts."""
+        try:
+            return self._model.embed_documents(texts)
+        except Exception as exc:
+            raise EmbeddingProviderError(f"{self.provider_name} embed_documents failed: {exc}")
+
+
+def _make_google_embeddings():
+    settings = get_settings()
+    api_key = settings.embedding.google_api_key or settings.llm.google_api_key
+    if not api_key:
+        raise EmbeddingError("GOOGLE_API_KEY not set for Google embeddings")
+    from langchain_google_genai import GoogleGenerativeAIEmbeddings
+
+    model = GoogleGenerativeAIEmbeddings(
+        model="models/text-embedding-004",
+        google_api_key=api_key,
+    )
+    return EmbeddingService(model, "google", 768)
+
+
+def _make_huggingface_embeddings():
+    settings = get_settings()
+    try:
+        from langchain_huggingface import HuggingFaceEmbeddings
+    except ImportError:
+        from langchain_community.embeddings import HuggingFaceEmbeddings
+
+    model = HuggingFaceEmbeddings(model_name=settings.embedding.huggingface_model)
+    return EmbeddingService(model, "huggingface", 384)
+
+
+def _make_ollama_embeddings():
+    settings = get_settings()
+    try:
+        from langchain_ollama import OllamaEmbeddings
+    except ImportError:
+        from langchain_community.embeddings import OllamaEmbeddings
+
+    model = OllamaEmbeddings(
+        model=settings.ollama.embedding_model,
+        base_url=settings.ollama.host,
+    )
+    return EmbeddingService(model, "ollama", 768)
+
+
+def _make_jina_embeddings():
+    settings = get_settings()
+    api_key = settings.embedding.jina_api_key
+    if not api_key:
+        raise EmbeddingError("JINA_API_KEY not set for Jina embeddings")
+    # Jina v3 via httpx (lightweight, no extra SDK)
+    import httpx
+
+    class _JinaModel:
+        """Minimal Jina AI embedding adapter."""
+
+        def __init__(self, api_key: str, model: str):
+            self._api_key = api_key
+            self._model = model
+            self._url = "https://api.jina.ai/v1/embeddings"
+
+        def _call(self, texts: list[str], task: str = "retrieval.passage") -> list[list[float]]:
+            headers = {"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"}
+            payload = {"model": self._model, "input": texts, "task": task}
+            resp = httpx.post(self._url, json=payload, headers=headers, timeout=60)
+            resp.raise_for_status()
+            data = resp.json()["data"]
+            return [item["embedding"] for item in sorted(data, key=lambda x: x["index"])]
+
+        def embed_query(self, text: str) -> list[float]:
+            return self._call([text], task="retrieval.query")[0]
+
+        def embed_documents(self, texts: list[str]) -> list[list[float]]:
+            return self._call(texts, task="retrieval.passage")
+
+    model = _JinaModel(api_key, settings.embedding.jina_model)
+    return EmbeddingService(model, "jina", settings.embedding.dimension)
+
+
+# ── Fallback chain factory ───────────────────────────────────────────────────
+
+_PROVIDERS = {
+    "jina": _make_jina_embeddings,
+    "google": _make_google_embeddings,
+    "huggingface": _make_huggingface_embeddings,
+    "ollama": _make_ollama_embeddings,
+}
+
+FALLBACK_ORDER = ["jina", "google", "huggingface"]
+
+
+@lru_cache(maxsize=1)
+def make_embedding_service() -> EmbeddingService:
+    """Create an embedding service with automatic fallback."""
+    settings = get_settings()
+    preferred = settings.embedding.provider
+
+    # Try preferred first, then fallbacks
+    order = [preferred] + [p for p in FALLBACK_ORDER if p != preferred]
+    for provider in order:
+        factory = _PROVIDERS.get(provider)
+        if factory is None:
+            continue
+        try:
+            svc = factory()
+            logger.info("Embedding provider: %s (dim=%d)", svc.provider_name, svc.dimension)
+            return svc
+        except Exception as exc:
+            logger.warning("Embedding provider '%s' failed: %s — trying next", provider, exc)
+
+    raise EmbeddingError("All embedding providers failed. Check your API keys and configuration.")

src/services/indexing/__init__.py

@@ -0,0 +1,5 @@
+"""MediGuard AI — Indexing (chunking + embedding + OpenSearch) package."""
+from src.services.indexing.text_chunker import MedicalTextChunker
+from src.services.indexing.service import IndexingService
+
+__all__ = ["MedicalTextChunker", "IndexingService"]

src/services/indexing/service.py

@@ -0,0 +1,84 @@
+"""
+MediGuard AI — Indexing Service
+
+Orchestrates: PDF parse → chunk → embed → index into OpenSearch.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from src.services.indexing.text_chunker import MedicalChunk, MedicalTextChunker
+
+logger = logging.getLogger(__name__)
+
+
+class IndexingService:
+    """Coordinates chunking → embedding → OpenSearch indexing."""
+
+    def __init__(self, chunker, embedding_service, opensearch_client):
+        self.chunker = chunker
+        self.embedding_service = embedding_service
+        self.opensearch_client = opensearch_client
+
+    def index_text(
+        self,
+        text: str,
+        *,
+        document_id: str = "",
+        title: str = "",
+        source_file: str = "",
+    ) -> int:
+        """Chunk, embed, and index a single document's text. Returns count of indexed chunks."""
+        if not document_id:
+            document_id = str(uuid.uuid4())
+
+        chunks = self.chunker.chunk_text(
+            text,
+            document_id=document_id,
+            title=title,
+            source_file=source_file,
+        )
+        if not chunks:
+            logger.warning("No chunks generated for document '%s'", title)
+            return 0
+
+        # Embed all chunks
+        texts = [c.text for c in chunks]
+        embeddings = self.embedding_service.embed_documents(texts)
+
+        # Prepare OpenSearch documents
+        now = datetime.now(timezone.utc).isoformat()
+        docs: List[Dict] = []
+        for chunk, emb in zip(chunks, embeddings):
+            doc = chunk.to_dict()
+            doc["_id"] = f"{document_id}_{chunk.chunk_index}"
+            doc["embedding"] = emb
+            doc["indexed_at"] = now
+            docs.append(doc)
+
+        indexed = self.opensearch_client.bulk_index(docs)
+        logger.info(
+            "Indexed %d chunks for '%s' (document_id=%s)",
+            indexed, title, document_id,
+        )
+        return indexed
+
+    def index_chunks(self, chunks: List[MedicalChunk]) -> int:
+        """Embed and index pre-built chunks."""
+        if not chunks:
+            return 0
+        texts = [c.text for c in chunks]
+        embeddings = self.embedding_service.embed_documents(texts)
+        now = datetime.now(timezone.utc).isoformat()
+        docs: List[Dict] = []
+        for chunk, emb in zip(chunks, embeddings):
+            doc = chunk.to_dict()
+            doc["_id"] = f"{chunk.document_id}_{chunk.chunk_index}"
+            doc["embedding"] = emb
+            doc["indexed_at"] = now
+            docs.append(doc)
+        return self.opensearch_client.bulk_index(docs)

src/services/indexing/text_chunker.py

@@ -0,0 +1,178 @@
+"""
+MediGuard AI — Medical-Aware Text Chunker
+
+Section-aware chunking with biomarker / condition metadata extraction.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+# Biomarker names to detect in chunk text
+_BIOMARKER_NAMES: Set[str] = {
+    "Glucose", "Cholesterol", "Triglycerides", "HbA1c", "LDL", "HDL",
+    "Insulin", "BMI", "Hemoglobin", "Platelets", "WBC", "RBC",
+    "Hematocrit", "MCV", "MCH", "MCHC", "Heart Rate", "Systolic",
+    "Diastolic", "Troponin", "CRP", "C-reactive Protein", "ALT", "AST",
+    "Creatinine", "TSH", "T3", "T4", "Sodium", "Potassium", "Calcium",
+}
+
+_CONDITION_KEYWORDS: Dict[str, str] = {
+    "diabetes": "diabetes",
+    "diabetic": "diabetes",
+    "hyperglycemia": "diabetes",
+    "insulin resistance": "diabetes",
+    "anemia": "anemia",
+    "anaemia": "anemia",
+    "iron deficiency": "anemia",
+    "thalassemia": "thalassemia",
+    "thalassaemia": "thalassemia",
+    "thrombocytopenia": "thrombocytopenia",
+    "heart disease": "heart_disease",
+    "cardiovascular": "heart_disease",
+    "coronary": "heart_disease",
+    "hypertension": "heart_disease",
+    "atherosclerosis": "heart_disease",
+    "hyperlipidemia": "heart_disease",
+}
+
+_SECTION_RE = re.compile(
+    r"^(?:#+\s*)?("
+    r"abstract|introduction|background|methods?|methodology|materials?"
+    r"|results?|findings|discussion|conclusion|summary"
+    r"|guidelines?|recommendations?|references?|bibliography"
+    r"|clinical\s*presentation|pathophysiology|diagnosis|treatment|prognosis"
+    r")\b",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+@dataclass
+class MedicalChunk:
+    """A single chunk with medical metadata."""
+    text: str
+    chunk_index: int
+    document_id: str = ""
+    title: str = ""
+    source_file: str = ""
+    page_number: Optional[int] = None
+    section_title: str = ""
+    biomarkers_mentioned: List[str] = field(default_factory=list)
+    condition_tags: List[str] = field(default_factory=list)
+    word_count: int = 0
+
+    def to_dict(self) -> Dict:
+        return {
+            "chunk_text": self.text,
+            "chunk_index": self.chunk_index,
+            "document_id": self.document_id,
+            "title": self.title,
+            "source_file": self.source_file,
+            "page_number": self.page_number,
+            "section_title": self.section_title,
+            "biomarkers_mentioned": self.biomarkers_mentioned,
+            "condition_tags": self.condition_tags,
+        }
+
+
+class MedicalTextChunker:
+    """Section-aware text chunker optimised for medical documents."""
+
+    def __init__(
+        self,
+        target_words: int = 600,
+        overlap_words: int = 100,
+        min_words: int = 50,
+    ):
+        self.target_words = target_words
+        self.overlap_words = overlap_words
+        self.min_words = min_words
+
+    def chunk_text(
+        self,
+        text: str,
+        *,
+        document_id: str = "",
+        title: str = "",
+        source_file: str = "",
+    ) -> List[MedicalChunk]:
+        """Split text into enriched medical chunks."""
+        sections = self._split_sections(text)
+        chunks: List[MedicalChunk] = []
+        idx = 0
+        for section_title, section_text in sections:
+            words = section_text.split()
+            if not words:
+                continue
+            start = 0
+            while start < len(words):
+                end = min(start + self.target_words, len(words))
+                chunk_words = words[start:end]
+                if len(chunk_words) < self.min_words and chunks:
+                    # merge tiny tail into previous chunk
+                    chunks[-1].text += " " + " ".join(chunk_words)
+                    chunks[-1].word_count = len(chunks[-1].text.split())
+                    break
+
+                chunk_text = " ".join(chunk_words)
+                biomarkers = self._detect_biomarkers(chunk_text)
+                conditions = self._detect_conditions(chunk_text)
+
+                chunks.append(
+                    MedicalChunk(
+                        text=chunk_text,
+                        chunk_index=idx,
+                        document_id=document_id,
+                        title=title,
+                        source_file=source_file,
+                        section_title=section_title,
+                        biomarkers_mentioned=biomarkers,
+                        condition_tags=conditions,
+                        word_count=len(chunk_words),
+                    )
+                )
+                idx += 1
+                start = end - self.overlap_words if end < len(words) else len(words)
+        return chunks
+
+    # ── internal helpers ─────────────────────────────────────────────────
+
+    @staticmethod
+    def _split_sections(text: str) -> List[tuple[str, str]]:
+        """Split text by detected section headers."""
+        matches = list(_SECTION_RE.finditer(text))
+        if not matches:
+            return [("", text)]
+        sections: List[tuple[str, str]] = []
+        # text before first section header
+        if matches[0].start() > 0:
+            preamble = text[: matches[0].start()].strip()
+            if preamble:
+                sections.append(("", preamble))
+        for i, match in enumerate(matches):
+            header = match.group(1).strip().title()
+            start = match.end()
+            end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+            body = text[start:end].strip()
+            # Skip reference/bibliography sections
+            if header.lower() in ("references", "bibliography"):
+                continue
+            if body:
+                sections.append((header, body))
+        return sections or [("", text)]
+
+    @staticmethod
+    def _detect_biomarkers(text: str) -> List[str]:
+        text_lower = text.lower()
+        return sorted(
+            {name for name in _BIOMARKER_NAMES if name.lower() in text_lower}
+        )
+
+    @staticmethod
+    def _detect_conditions(text: str) -> List[str]:
+        text_lower = text.lower()
+        return sorted(
+            {tag for kw, tag in _CONDITION_KEYWORDS.items() if kw in text_lower}
+        )

src/services/langfuse/__init__.py

@@ -0,0 +1,4 @@
+"""MediGuard AI — Langfuse observability package."""
+from src.services.langfuse.tracer import LangfuseTracer, make_langfuse_tracer
+
+__all__ = ["LangfuseTracer", "make_langfuse_tracer"]

src/services/langfuse/tracer.py

@@ -0,0 +1,97 @@
+"""
+MediGuard AI — Langfuse Observability Tracer
+
+Wraps Langfuse v3 SDK for end-to-end tracing of the RAG pipeline.
+Silently no-ops when Langfuse is disabled or unreachable.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from functools import lru_cache
+from typing import Any, Dict, Optional
+
+from src.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+try:
+    from langfuse import Langfuse as _Langfuse
+except ImportError:
+    _Langfuse = None  # type: ignore[assignment,misc]
+
+
+class LangfuseTracer:
+    """Thin wrapper around Langfuse for MediGuard pipeline tracing."""
+
+    def __init__(self, client: Any | None):
+        self._client = client
+        self._enabled = client is not None
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    def trace(self, name: str, **kwargs: Any):
+        """Create a new trace (top-level span)."""
+        if not self._enabled:
+            return _NullSpan()
+        return self._client.trace(name=name, **kwargs)
+
+    @contextmanager
+    def span(self, trace, name: str, **kwargs):
+        """Context manager for creating a span within a trace."""
+        if not self._enabled or trace is None:
+            yield _NullSpan()
+            return
+        s = trace.span(name=name, **kwargs)
+        try:
+            yield s
+        finally:
+            s.end()
+
+    def score(self, trace_id: str, name: str, value: float, comment: str = ""):
+        """Attach a score to a trace (for evaluation feedback)."""
+        if not self._enabled:
+            return
+        try:
+            self._client.score(trace_id=trace_id, name=name, value=value, comment=comment)
+        except Exception as exc:
+            logger.warning("Langfuse score failed: %s", exc)
+
+    def flush(self):
+        if self._enabled:
+            try:
+                self._client.flush()
+            except Exception:
+                pass
+
+
+class _NullSpan:
+    """Dummy span object that silently swallows calls."""
+
+    def __getattr__(self, name: str):
+        return lambda *a, **kw: _NullSpan()
+
+    def end(self):
+        pass
+
+
+@lru_cache(maxsize=1)
+def make_langfuse_tracer() -> LangfuseTracer:
+    settings = get_settings()
+    if not settings.langfuse.enabled or _Langfuse is None:
+        logger.info("Langfuse tracing disabled")
+        return LangfuseTracer(None)
+    try:
+        client = _Langfuse(
+            public_key=settings.langfuse.public_key,
+            secret_key=settings.langfuse.secret_key,
+            host=settings.langfuse.host,
+        )
+        logger.info("Langfuse connected (%s)", settings.langfuse.host)
+        return LangfuseTracer(client)
+    except Exception as exc:
+        logger.warning("Langfuse unavailable: %s", exc)
+        return LangfuseTracer(None)

src/services/ollama/__init__.py

@@ -0,0 +1,4 @@
+"""MediGuard AI — Ollama client package."""
+from src.services.ollama.client import OllamaClient, make_ollama_client
+
+__all__ = ["OllamaClient", "make_ollama_client"]

src/services/ollama/client.py

@@ -0,0 +1,160 @@
+"""
+MediGuard AI — Ollama Client
+
+Production-grade wrapper for the Ollama API with health checks,
+streaming, and LangChain integration.
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Dict, Iterator, List, Optional
+
+import httpx
+
+from src.exceptions import OllamaConnectionError, OllamaModelNotFoundError
+from src.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class OllamaClient:
+    """Wrapper around the Ollama REST API."""
+
+    def __init__(self, base_url: str, *, timeout: int = 120):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    # ── Health ───────────────────────────────────────────────────────────
+
+    def ping(self) -> bool:
+        try:
+            resp = self._http.get("/api/version")
+            return resp.status_code == 200
+        except Exception:
+            return False
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            resp = self._http.get("/api/version")
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as exc:
+            raise OllamaConnectionError(f"Cannot reach Ollama: {exc}")
+
+    def list_models(self) -> List[str]:
+        try:
+            resp = self._http.get("/api/tags")
+            resp.raise_for_status()
+            return [m["name"] for m in resp.json().get("models", [])]
+        except Exception as exc:
+            logger.warning("Failed to list Ollama models: %s", exc)
+            return []
+
+    # ── Generation ───────────────────────────────────────────────────────
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        system: str = "",
+        temperature: float = 0.0,
+        num_ctx: int = 8192,
+    ) -> Dict[str, Any]:
+        """Synchronous generation — returns the full response dict."""
+        model = model or get_settings().ollama.model
+        payload: Dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {"temperature": temperature, "num_ctx": num_ctx},
+        }
+        if system:
+            payload["system"] = system
+        try:
+            resp = self._http.post("/api/generate", json=payload)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 404:
+                raise OllamaModelNotFoundError(f"Model '{model}' not found on Ollama server")
+            raise OllamaConnectionError(str(exc))
+        except Exception as exc:
+            raise OllamaConnectionError(str(exc))
+
+    def generate_stream(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        system: str = "",
+        temperature: float = 0.0,
+        num_ctx: int = 8192,
+    ) -> Iterator[str]:
+        """Streaming generation — yields text tokens."""
+        model = model or get_settings().ollama.model
+        payload: Dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+            "stream": True,
+            "options": {"temperature": temperature, "num_ctx": num_ctx},
+        }
+        if system:
+            payload["system"] = system
+        try:
+            with self._http.stream("POST", "/api/generate", json=payload) as resp:
+                resp.raise_for_status()
+                import json
+                for line in resp.iter_lines():
+                    if line:
+                        data = json.loads(line)
+                        token = data.get("response", "")
+                        if token:
+                            yield token
+                        if data.get("done", False):
+                            break
+        except Exception as exc:
+            raise OllamaConnectionError(str(exc))
+
+    # ── LangChain integration ────────────────────────────────────────────
+
+    def get_langchain_model(
+        self,
+        *,
+        model: Optional[str] = None,
+        temperature: float = 0.0,
+        json_mode: bool = False,
+    ):
+        """Return a LangChain ChatOllama instance."""
+        model = model or get_settings().ollama.model
+        try:
+            from langchain_ollama import ChatOllama
+        except ImportError:
+            from langchain_community.chat_models import ChatOllama
+
+        return ChatOllama(
+            model=model,
+            temperature=temperature,
+            base_url=self.base_url,
+            format="json" if json_mode else None,
+        )
+
+    def close(self):
+        self._http.close()
+
+
+@lru_cache(maxsize=1)
+def make_ollama_client() -> OllamaClient:
+    settings = get_settings()
+    client = OllamaClient(
+        base_url=settings.ollama.host,
+        timeout=settings.ollama.timeout,
+    )
+    if client.ping():
+        logger.info("Ollama connected at %s", settings.ollama.host)
+    else:
+        logger.warning("Ollama not reachable at %s", settings.ollama.host)
+    return client

src/services/opensearch/__init__.py

@@ -0,0 +1,5 @@
+"""MediGuard AI — OpenSearch service package."""
+from src.services.opensearch.client import OpenSearchClient, make_opensearch_client
+from src.services.opensearch.index_config import MEDICAL_CHUNKS_MAPPING
+
+__all__ = ["OpenSearchClient", "make_opensearch_client", "MEDICAL_CHUNKS_MAPPING"]