Deploy to HuggingFace Spaces - Medical RAG with vector store

.env.example

@@ -32,9 +32,9 @@ OLLAMA__MODEL=llama3.2
 
 # --- LLM (Groq / Gemini — existing providers) ---
 LLM__PRIMARY_PROVIDER=groq
-LLM__GROQ_API_KEY=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
+LLM__GROQ_API_KEY=
 LLM__GROQ_MODEL=llama-3.3-70b-versatile
-LLM__GEMINI_API_KEY=AIzaSyBbWG-vy44GXuZL-PgNjtvKLXrhdINCgwg
+LLM__GEMINI_API_KEY=
 LLM__GEMINI_MODEL=gemini-2.0-flash
 
 # --- Embeddings ---

.gitattributes

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

.gitignore

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

DEPLOY_HUGGINGFACE.md

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

Dockerfile

@@ -1,19 +1,27 @@
 # ===========================================================================
-# MediGuard AI — Multi-stage Dockerfile
+# MediGuard AI — Hugging Face Spaces Dockerfile
 # ===========================================================================
-# Build stages:
-#   base        — Python + system deps
-#   production  — slim runtime image
+# Optimized single-container deployment for Hugging Face Spaces.
+# Uses FAISS vector store + Cloud LLMs (Groq/Gemini) - no external services.
 # ===========================================================================
 
-# ---------------------------------------------------------------------------
-# Stage 1: base
-# ---------------------------------------------------------------------------
-FROM python:3.11-slim AS base
+FROM python:3.11-slim
 
+# Non-interactive apt
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Python settings
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# HuggingFace Spaces runs on port 7860
+ENV GRADIO_SERVER_NAME="0.0.0.0" \
+    GRADIO_SERVER_PORT=7860
+
+# Default to HuggingFace embeddings (local, no API key needed)
+ENV EMBEDDING_PROVIDER=huggingface
 
 WORKDIR /app
 
@@ -22,45 +30,37 @@ RUN apt-get update && \
     apt-get install -y --no-install-recommends \
         build-essential \
         curl \
+        git \
         && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies
-COPY pyproject.toml ./
+# Copy requirements first (cache layer)
+COPY huggingface/requirements.txt ./requirements.txt
 RUN pip install --upgrade pip && \
-    pip install ".[all]"
-
-# ---------------------------------------------------------------------------
-# Stage 2: production
-# ---------------------------------------------------------------------------
-FROM python:3.11-slim AS production
-
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1
+    pip install -r requirements.txt
 
-WORKDIR /app
+# Copy the entire project
+COPY . .
 
-# 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
+# Create necessary directories and ensure vector store exists
+RUN mkdir -p data/medical_pdfs data/vector_stores data/chat_reports
 
-# Copy application code
-COPY . .
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
 
-# Runtime dependencies only
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends curl && \
-    rm -rf /var/lib/apt/lists/*
+# Make app writable by user
+RUN chown -R user:user /app
 
-# Create non-root user
-RUN groupadd -r mediguard && \
-    useradd -r -g mediguard -d /app -s /sbin/nologin mediguard && \
-    chown -R mediguard:mediguard /app
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
 
-USER mediguard
+WORKDIR /app
 
-EXPOSE 8000
+EXPOSE 7860
 
-HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
-    CMD curl -sf http://localhost:8000/health || exit 1
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD curl -sf http://localhost:7860/ || exit 1
 
-CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
+# Launch Gradio app
+CMD ["python", "huggingface/app.py"]

README.md

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

alembic.ini

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

alembic/README

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

alembic/env.py

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

alembic/script.py.mako

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

data/vector_stores/medical_knowledge.faiss

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

data/vector_stores/medical_knowledge.pkl

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

docker-compose.yml

@@ -76,12 +76,13 @@ services:
     restart: unless-stopped
 
   opensearch:
-    image: opensearchproject/opensearch:2.19.0
+    image: opensearchproject/opensearch:2.11.1
     container_name: mediguard-opensearch
     environment:
       - discovery.type=single-node
       - DISABLE_SECURITY_PLUGIN=true
-      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
+      - plugins.security.disabled=true
+      - "OPENSEARCH_JAVA_OPTS=-Xms256m -Xmx256m"
       - bootstrap.memory_lock=true
     ulimits:
       memlock: { soft: -1, hard: -1 }
@@ -94,21 +95,22 @@ services:
       test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health || exit 1"]
       interval: 10s
       timeout: 5s
-      retries: 20
+      retries: 24
     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
+  # opensearch-dashboards: disabled by default — uncomment if you need the UI
+  # opensearch-dashboards:
+  #   image: opensearchproject/opensearch-dashboards:2.11.1
+  #   container_name: mediguard-os-dashboards
+  #   environment:
+  #     - OPENSEARCH_HOSTS=["http://opensearch:9200"]
+  #     - DISABLE_SECURITY_DASHBOARDS_PLUGIN=true
+  #   ports:
+  #     - "${OS_DASHBOARDS_PORT:-5601}:5601"
+  #   depends_on:
+  #     opensearch:
+  #       condition: service_healthy
+  #   restart: unless-stopped
 
   redis:
     image: redis:7-alpine

huggingface/Dockerfile

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

huggingface/README.md

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

huggingface/app.py

@@ -0,0 +1,532 @@
+"""
+MediGuard AI — Hugging Face Spaces Gradio App
+
+Standalone deployment that uses:
+- FAISS vector store (local)
+- Cloud LLMs (Groq or Gemini - FREE tiers)
+- No external services required
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Optional
+
+# Ensure project root is in path
+_project_root = str(Path(__file__).parent.parent)
+if _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
+os.chdir(_project_root)
+
+import gradio as gr
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(name)-20s | %(levelname)-7s | %(message)s",
+)
+logger = logging.getLogger("mediguard.huggingface")
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+# Check for required API keys
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY", "")
+
+if not GROQ_API_KEY and not GOOGLE_API_KEY:
+    logger.warning(
+        "No LLM API key found. Set GROQ_API_KEY or GOOGLE_API_KEY environment variable."
+    )
+
+# Set default provider based on available keys
+if GROQ_API_KEY:
+    os.environ.setdefault("LLM_PROVIDER", "groq")
+elif GOOGLE_API_KEY:
+    os.environ.setdefault("LLM_PROVIDER", "gemini")
+
+
+# ---------------------------------------------------------------------------
+# Guild Initialization (lazy)
+# ---------------------------------------------------------------------------
+
+_guild = None
+_guild_error = None
+
+
+def get_guild():
+    """Lazy initialization of the Clinical Insight Guild."""
+    global _guild, _guild_error
+    
+    if _guild is not None:
+        return _guild
+    
+    if _guild_error is not None:
+        raise _guild_error
+    
+    try:
+        logger.info("Initializing Clinical Insight Guild...")
+        start = time.time()
+        
+        from src.workflow import create_guild
+        _guild = create_guild()
+        
+        elapsed = time.time() - start
+        logger.info(f"Guild initialized in {elapsed:.1f}s")
+        return _guild
+        
+    except Exception as exc:
+        logger.error(f"Failed to initialize guild: {exc}")
+        _guild_error = exc
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Analysis Functions
+# ---------------------------------------------------------------------------
+
+def parse_biomarkers(text: str) -> dict[str, float]:
+    """
+    Parse biomarkers from natural language text.
+    
+    Supports formats like:
+    - "Glucose: 140, HbA1c: 7.5"
+    - "glucose 140 hba1c 7.5"
+    - {"Glucose": 140, "HbA1c": 7.5}
+    """
+    text = text.strip()
+    
+    # Try JSON first
+    if text.startswith("{"):
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            pass
+    
+    # Parse natural language
+    import re
+    
+    # Common biomarker patterns
+    patterns = [
+        # "Glucose: 140" or "Glucose = 140"
+        r"([A-Za-z0-9_]+)\s*[:=]\s*([\d.]+)",
+        # "Glucose 140 mg/dL"
+        r"([A-Za-z0-9_]+)\s+([\d.]+)\s*(?:mg/dL|mmol/L|%|g/dL|U/L|mIU/L)?",
+    ]
+    
+    biomarkers = {}
+    
+    for pattern in patterns:
+        matches = re.findall(pattern, text, re.IGNORECASE)
+        for name, value in matches:
+            try:
+                biomarkers[name.strip()] = float(value)
+            except ValueError:
+                continue
+    
+    return biomarkers
+
+
+def analyze_biomarkers(input_text: str, progress=gr.Progress()) -> tuple[str, str, str]:
+    """
+    Analyze biomarkers using the Clinical Insight Guild.
+    
+    Returns: (summary, details_json, status)
+    """
+    if not input_text.strip():
+        return "", "", "⚠️ Please enter biomarkers to analyze."
+    
+    # Check API key
+    if not GROQ_API_KEY and not GOOGLE_API_KEY:
+        return "", "", (
+            "❌ **Error**: No LLM API key configured.\n\n"
+            "Please add your API key in Hugging Face Space Settings → Secrets:\n"
+            "- `GROQ_API_KEY` (get free at https://console.groq.com/keys)\n"
+            "- or `GOOGLE_API_KEY` (get free at https://aistudio.google.com/app/apikey)"
+        )
+    
+    try:
+        progress(0.1, desc="Parsing biomarkers...")
+        biomarkers = parse_biomarkers(input_text)
+        
+        if not biomarkers:
+            return "", "", (
+                "⚠️ Could not parse biomarkers. Try formats like:\n"
+                "• `Glucose: 140, HbA1c: 7.5`\n"
+                "• `{\"Glucose\": 140, \"HbA1c\": 7.5}`"
+            )
+        
+        progress(0.2, desc="Initializing analysis...")
+        
+        # Initialize guild
+        guild = get_guild()
+        
+        # Prepare input
+        from src.state import PatientInput
+        
+        # Auto-generate prediction based on common patterns
+        prediction = auto_predict(biomarkers)
+        
+        patient_input = PatientInput(
+            biomarkers=biomarkers,
+            model_prediction=prediction,
+            patient_context={"patient_id": "HF_User", "source": "huggingface_spaces"}
+        )
+        
+        progress(0.4, desc="Running Clinical Insight Guild...")
+        
+        # Run analysis
+        start = time.time()
+        result = guild.run(patient_input)
+        elapsed = time.time() - start
+        
+        progress(0.9, desc="Formatting results...")
+        
+        # Extract response
+        final_response = result.get("final_response", {})
+        
+        # Format summary
+        summary = format_summary(final_response, elapsed)
+        
+        # Format details
+        details = json.dumps(final_response, indent=2, default=str)
+        
+        status = f"✅ Analysis completed in {elapsed:.1f}s"
+        
+        return summary, details, status
+        
+    except Exception as exc:
+        logger.error(f"Analysis error: {exc}", exc_info=True)
+        return "", "", f"❌ **Error**: {exc}\n\n```\n{traceback.format_exc()}\n```"
+
+
+def auto_predict(biomarkers: dict[str, float]) -> dict[str, Any]:
+    """
+    Auto-generate a disease prediction based on biomarkers.
+    This simulates what an ML model would provide.
+    """
+    # Normalize biomarker names for matching
+    normalized = {k.lower().replace(" ", ""): v for k, v in biomarkers.items()}
+    
+    # Check for diabetes indicators
+    glucose = normalized.get("glucose", normalized.get("fastingglucose", 0))
+    hba1c = normalized.get("hba1c", normalized.get("hemoglobina1c", 0))
+    
+    if hba1c >= 6.5 or glucose >= 126:
+        return {
+            "disease": "Diabetes",
+            "confidence": min(0.95, 0.7 + (hba1c - 6.5) * 0.1) if hba1c else 0.85,
+            "severity": "high" if hba1c >= 8 or glucose >= 200 else "moderate"
+        }
+    
+    # Check for lipid disorders
+    cholesterol = normalized.get("cholesterol", normalized.get("totalcholesterol", 0))
+    ldl = normalized.get("ldl", normalized.get("ldlcholesterol", 0))
+    triglycerides = normalized.get("triglycerides", 0)
+    
+    if cholesterol >= 240 or ldl >= 160 or triglycerides >= 200:
+        return {
+            "disease": "Dyslipidemia",
+            "confidence": 0.85,
+            "severity": "moderate"
+        }
+    
+    # Check for anemia
+    hemoglobin = normalized.get("hemoglobin", normalized.get("hgb", normalized.get("hb", 0)))
+    
+    if hemoglobin and hemoglobin < 12:
+        return {
+            "disease": "Anemia",
+            "confidence": 0.80,
+            "severity": "moderate"
+        }
+    
+    # Check for thyroid issues
+    tsh = normalized.get("tsh", 0)
+    
+    if tsh > 4.5:
+        return {
+            "disease": "Hypothyroidism",
+            "confidence": 0.75,
+            "severity": "moderate"
+        }
+    elif tsh and tsh < 0.4:
+        return {
+            "disease": "Hyperthyroidism",
+            "confidence": 0.75,
+            "severity": "moderate"
+        }
+    
+    # Default - general health screening
+    return {
+        "disease": "General Health Screening",
+        "confidence": 0.70,
+        "severity": "low"
+    }
+
+
+def format_summary(response: dict, elapsed: float) -> str:
+    """Format the analysis response as readable markdown."""
+    if not response:
+        return "No analysis results available."
+    
+    parts = []
+    
+    # Header
+    primary = response.get("primary_finding", "Analysis")
+    confidence = response.get("confidence", {})
+    conf_score = confidence.get("overall_score", 0) if isinstance(confidence, dict) else 0
+    
+    parts.append(f"## 🏥 {primary}")
+    if conf_score:
+        parts.append(f"**Confidence**: {conf_score:.0%}")
+    parts.append("")
+    
+    # Critical Alerts
+    alerts = response.get("safety_alerts", [])
+    if alerts:
+        parts.append("### ⚠️ Critical Alerts")
+        for alert in alerts[:5]:
+            if isinstance(alert, dict):
+                parts.append(f"- **{alert.get('alert_type', 'Alert')}**: {alert.get('message', '')}")
+            else:
+                parts.append(f"- {alert}")
+        parts.append("")
+    
+    # Key Findings
+    findings = response.get("key_findings", [])
+    if findings:
+        parts.append("### 🔍 Key Findings")
+        for finding in findings[:5]:
+            parts.append(f"- {finding}")
+        parts.append("")
+    
+    # Biomarker Flags
+    flags = response.get("biomarker_flags", [])
+    if flags:
+        parts.append("### 📊 Biomarker Analysis")
+        for flag in flags[:8]:
+            if isinstance(flag, dict):
+                name = flag.get("biomarker", "Unknown")
+                status = flag.get("status", "normal")
+                value = flag.get("value", "N/A")
+                emoji = "🔴" if status == "critical" else "🟡" if status == "abnormal" else "🟢"
+                parts.append(f"- {emoji} **{name}**: {value} ({status})")
+            else:
+                parts.append(f"- {flag}")
+        parts.append("")
+    
+    # Recommendations
+    recs = response.get("recommendations", {})
+    if recs:
+        parts.append("### 💡 Recommendations")
+        
+        immediate = recs.get("immediate_actions", [])
+        if immediate:
+            parts.append("**Immediate Actions:**")
+            for action in immediate[:3]:
+                parts.append(f"- {action}")
+        
+        lifestyle = recs.get("lifestyle_modifications", [])
+        if lifestyle:
+            parts.append("\n**Lifestyle Modifications:**")
+            for mod in lifestyle[:3]:
+                parts.append(f"- {mod}")
+        
+        followup = recs.get("follow_up", [])
+        if followup:
+            parts.append("\n**Follow-up:**")
+            for item in followup[:3]:
+                parts.append(f"- {item}")
+        parts.append("")
+    
+    # Disease Explanation
+    explanation = response.get("disease_explanation", {})
+    if explanation and isinstance(explanation, dict):
+        parts.append("### 📖 Understanding Your Results")
+        
+        pathophys = explanation.get("pathophysiology", "")
+        if pathophys:
+            parts.append(f"{pathophys[:500]}...")
+        parts.append("")
+    
+    # Conversational Summary
+    conv_summary = response.get("conversational_summary", "")
+    if conv_summary:
+        parts.append("### 📝 Summary")
+        parts.append(conv_summary[:1000])
+        parts.append("")
+    
+    # Footer
+    parts.append("---")
+    parts.append(f"*Analysis completed in {elapsed:.1f}s using MediGuard AI*")
+    parts.append("")
+    parts.append("**⚠️ Disclaimer**: This is for informational purposes only. "
+                 "Consult a healthcare professional for medical advice.")
+    
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Gradio Interface
+# ---------------------------------------------------------------------------
+
+def create_demo() -> gr.Blocks:
+    """Create the Gradio Blocks interface."""
+    
+    with gr.Blocks(
+        title="MediGuard AI - Medical Biomarker Analysis",
+        theme=gr.themes.Soft(primary_hue="blue", secondary_hue="cyan"),
+        css="""
+        .gradio-container { max-width: 1200px !important; }
+        .status-box { font-size: 14px; }
+        footer { display: none !important; }
+        """
+    ) as demo:
+        
+        # Header
+        gr.Markdown("""
+        # 🏥 MediGuard AI — Medical Biomarker Analysis
+        
+        **Multi-Agent RAG System** powered by 6 specialized AI agents with medical knowledge retrieval.
+        
+        Enter your biomarkers below and get evidence-based insights in seconds.
+        """)
+        
+        # API Key warning (if needed)
+        if not GROQ_API_KEY and not GOOGLE_API_KEY:
+            gr.Markdown("""
+            <div style="background: #ffeeba; padding: 10px; border-radius: 5px; margin: 10px 0;">
+            ⚠️ <b>API Key Required</b>: Add <code>GROQ_API_KEY</code> or <code>GOOGLE_API_KEY</code> 
+            in Space Settings → Secrets to enable analysis.
+            </div>
+            """)
+        
+        with gr.Row():
+            # Input column
+            with gr.Column(scale=1):
+                gr.Markdown("### 📝 Enter Biomarkers")
+                
+                input_text = gr.Textbox(
+                    label="Biomarkers",
+                    placeholder=(
+                        "Enter biomarkers in any format:\n"
+                        "• Glucose: 140, HbA1c: 7.5, Cholesterol: 210\n"
+                        "• My glucose is 140 and HbA1c is 7.5\n"
+                        '• {"Glucose": 140, "HbA1c": 7.5}'
+                    ),
+                    lines=5,
+                    max_lines=10,
+                )
+                
+                with gr.Row():
+                    analyze_btn = gr.Button("🔬 Analyze", variant="primary", size="lg")
+                    clear_btn = gr.Button("🗑️ Clear", size="lg")
+                
+                status_output = gr.Markdown(
+                    label="Status",
+                    elem_classes="status-box"
+                )
+                
+                # Example inputs
+                gr.Markdown("### 📋 Example Inputs")
+                
+                examples = gr.Examples(
+                    examples=[
+                        ["Glucose: 185, HbA1c: 8.2, Cholesterol: 245, LDL: 165"],
+                        ["Glucose: 95, HbA1c: 5.4, Cholesterol: 180, HDL: 55, LDL: 100"],
+                        ["Hemoglobin: 9.5, Iron: 40, Ferritin: 15"],
+                        ["TSH: 8.5, T4: 4.0, T3: 80"],
+                        ['{"Glucose": 140, "HbA1c": 7.0, "Triglycerides": 250}'],
+                    ],
+                    inputs=input_text,
+                    label="Click an example to load it",
+                )
+            
+            # Output column
+            with gr.Column(scale=2):
+                gr.Markdown("### 📊 Analysis Results")
+                
+                with gr.Tabs():
+                    with gr.Tab("Summary"):
+                        summary_output = gr.Markdown(
+                            label="Analysis Summary",
+                            value="*Enter biomarkers and click Analyze to see results*"
+                        )
+                    
+                    with gr.Tab("Detailed JSON"):
+                        details_output = gr.Code(
+                            label="Full Response",
+                            language="json",
+                            lines=25,
+                        )
+        
+        # Event handlers
+        analyze_btn.click(
+            fn=analyze_biomarkers,
+            inputs=[input_text],
+            outputs=[summary_output, details_output, status_output],
+            show_progress="full",
+        )
+        
+        clear_btn.click(
+            fn=lambda: ("", "", "", ""),
+            outputs=[input_text, summary_output, details_output, status_output],
+        )
+        
+        # Footer
+        gr.Markdown("""
+        ---
+        
+        ### ℹ️ About MediGuard AI
+        
+        MediGuard AI uses a **Clinical Insight Guild** of 6 specialized AI agents:
+        
+        | Agent | Role |
+        |-------|------|
+        | 🔬 Biomarker Analyzer | Validates and flags abnormal values |
+        | 📚 Disease Explainer | RAG-powered pathophysiology explanations |
+        | 🔗 Biomarker Linker | Connects biomarkers to disease predictions |
+        | 📋 Clinical Guidelines | Evidence-based recommendations from medical literature |
+        | ✅ Confidence Assessor | Evaluates reliability of findings |
+        | 📝 Response Synthesizer | Compiles comprehensive patient-friendly output |
+        
+        **Data Sources**: 750+ pages of clinical guidelines (FAISS vector store)
+        
+        ---
+        
+        ⚠️ **Medical Disclaimer**: This tool is for **informational purposes only** and does not 
+        replace professional medical advice, diagnosis, or treatment. Always consult a qualified 
+        healthcare provider with questions regarding a medical condition.
+        
+        ---
+        
+        Built with ❤️ using [LangGraph](https://langchain-ai.github.io/langgraph/), 
+        [FAISS](https://faiss.ai/), and [Gradio](https://gradio.app/)
+        """)
+    
+    return demo
+
+
+# ---------------------------------------------------------------------------
+# Main Entry Point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    logger.info("Starting MediGuard AI Gradio App...")
+    
+    demo = create_demo()
+    
+    # Launch with HF Spaces compatible settings
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+        # share=False on HF Spaces
+    )

huggingface/requirements.txt

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

scripts/deploy_huggingface.ps1

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