Add HuggingFace Spaces deployment support

- Root app.py: HF Spaces entrypoint, auto-downloads data from KoopaK/OdinDB
on first cold start via snapshot_download, marks completion with .hf_downloaded
- src/agents/app.py: expose module-level demo + _figures_dir for import
- README.md: add HF Spaces YAML frontmatter (sdk: gradio, app_file: app.py)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -1,171 +1,183 @@
-# ODIN — Operational Drilling Intelligence Network
-
-> Multi-agent AI system for subsurface and drilling engineering analysis
-> Built on the public Equinor Volve Field dataset · SPE GCS 2026 ML Challenge
-
----
-
-## Overview
-
-ODIN is a CrewAI-powered multi-agent system that answers complex drilling engineering questions by reasoning over structured data (WITSML, EDM) and unstructured reports (Daily Drilling Reports). It combines real-time data retrieval, RAG over domain knowledge, and a Gradio chat interface with inline Plotly visualizations.
-
-**Key capabilities:**
-- Drill phase distribution & NPT breakdown analysis
-- ROP / WOB / RPM performance profiling
-- Cross-well KPI comparison
-- BHA configuration review and handover summaries
-- Stuck-pipe and wellbore stability root-cause analysis
-- Evidence-cited answers with confidence levels
-
----
-
-## Architecture
-
-```
-User Query
-    │
-    ▼
-Orchestrator (orchestrator.py)
-    │  Classifies query → lean or full crew
-    │
-    ├── LEAN (chart / compare queries, ~40s)
-    │     Analyst  ──► Lead (Odin)
-    │
-    └── FULL (deep analysis, ~80s)
-          Lead  ──► Analyst  ──► Historian  ──► Lead (Odin)
-```
-
-**Agents:**
-| Agent | Role |
-|---|---|
-| **Odin (Lead)** | Synthesizes findings, grounds in Volve KB |
-| **Data Analyst** | Runs DDR / WITSML / EDM queries & Python charts |
-| **Historian** | Searches operational history, validates stats |
-
-**Tools available to agents:**
-- `DDR_Query` — Daily Drilling Report search
-- `WITSML_Analyst` — Realtime drilling log analysis
-- `EDM_Technical_Query` — Casing, BHA, formation data
-- `CrossWell_Comparison` — Multi-well KPI comparison
-- `VolveHistory_SearchTool` — RAG over Volve campaign history
-- `python_interpreter` — Pandas + Plotly for custom charts
-
----
-
-## Tech Stack
-
-| Layer | Technology |
-|---|---|
-| LLM | Google Gemini 2.5 Flash (via `google-generativeai`) |
-| Agent framework | CrewAI 1.10 |
-| RAG / Vector store | ChromaDB + `sentence-transformers` |
-| Data processing | Pandas, NumPy, PDFPlumber |
-| Visualisation | Plotly (HTML) + Kaleido (PNG) |
-| UI | Gradio 6 |
-
----
-
-## Data
-
-This project uses the **Equinor Volve Field open dataset** (released under the Volve Data Sharing Agreement).
-
-> Download from: [https://www.equinor.com/energy/volve-data-sharing](https://www.equinor.com/energy/volve-data-sharing)
-
-After downloading, extract to `data/raw/` and run the ETL pipeline:
-
-```bash
-python src/data_pipeline/run_pipeline.py
-```
-
-Then build the knowledge base:
-
-```bash
-python src/rag/build_volve_db.py
-python src/rag/build_openviking_db.py
-```
-
----
-
-## Quickstart (judges)
-
-```bash
-# 1. Clone & install
-git clone <repo-url>
-cd odin
-python -m venv venv
-source venv/bin/activate      # Windows: venv\Scripts\activate
-pip install -r requirements.txt
-
-# 2. Download runtime data (~400 MB knowledge bases + processed CSVs)
-python scripts/download_data.py
-
-# 3. Add your Gemini API key
-cp .env.example .env
-# Edit .env: set GOOGLE_API_KEY=<your key>
-# Free key at: https://aistudio.google.com/app/apikey
-
-# 4. Run
-python src/agents/app.py
-```
-
-Open `http://localhost:7860` in your browser.
-
----
-
-## Project Structure
-
-```
-odin/
-├── src/
-│   ├── agents/           # Main application
-│   │   ├── app.py        # Gradio UI (entry point)
-│   │   ├── orchestrator.py  # Query routing & streaming
-│   │   ├── crew.py       # CrewAI agent definitions & tasks
-│   │   ├── tools.py      # DDR / WITSML / EDM / RAG tools
-│   │   └── data_tools.py # Python interpreter tool + data helpers
-│   │
-│   ├── data_pipeline/    # ETL: raw Volve data → processed CSV
-│   │   ├── run_pipeline.py
-│   │   ├── parse_witsml_logs.py
-│   │   ├── parse_ddr_xml.py
-│   │   └── parse_edm.py
-│   │
-│   └── rag/              # Knowledge base builders
-│       ├── build_volve_db.py
-│       └── build_openviking_db.py
-│
-├── tests/
-│   └── prompts/          # Agent prompt test cases
-│
-├── data/                 # ← NOT in git (download separately)
-│   ├── raw/              # Original Volve dataset
-│   ├── processed/        # ETL output (CSV / Parquet)
-│   └── knowledge_base/   # ChromaDB vector stores
-│
-├── outputs/              # ← NOT in git (generated at runtime)
-│   └── figures/          # Plotly charts (HTML + PNG)
-│
-├── requirements.txt
-├── .env.example
-└── promptfooconfig.yaml  # Evaluation harness (PromptFoo)
-```
-
----
-
-## Rate Limits
-
-The system is tuned for the Gemini free tier (15 RPM):
-
-| Crew mode | LLM calls | Target time |
-|---|---|---|
-| Lean (chart / compare) | ~6 calls | ~40s |
-| Full (deep analysis) | ~10 calls | ~80s |
-
-Automatic 429 retry with exponential back-off (10 → 20 → 40 → 60s) is built in.
-
----
-
-## License
-
-Source code: MIT
-Volve dataset: [Volve Data Sharing Agreement](https://www.equinor.com/energy/volve-data-sharing) (not included in this repo)
+---
+title: ODIN — Operational Drilling Intelligence Network
+emoji: 🛢️
+colorFrom: slate
+colorTo: green
+sdk: gradio
+sdk_version: 6.9.0
+app_file: app.py
+pinned: true
+license: mit
+---
+
+# ODIN — Operational Drilling Intelligence Network
+
+> Multi-agent AI system for subsurface and drilling engineering analysis
+> Built on the public Equinor Volve Field dataset · SPE GCS 2026 ML Challenge
+
+---
+
+## Overview
+
+ODIN is a CrewAI-powered multi-agent system that answers complex drilling engineering questions by reasoning over structured data (WITSML, EDM) and unstructured reports (Daily Drilling Reports). It combines real-time data retrieval, RAG over domain knowledge, and a Gradio chat interface with inline Plotly visualizations.
+
+**Key capabilities:**
+- Drill phase distribution & NPT breakdown analysis
+- ROP / WOB / RPM performance profiling
+- Cross-well KPI comparison
+- BHA configuration review and handover summaries
+- Stuck-pipe and wellbore stability root-cause analysis
+- Evidence-cited answers with confidence levels
+
+---
+
+## Architecture
+
+```
+User Query
+    │
+    ▼
+Orchestrator (orchestrator.py)
+    │  Classifies query → lean or full crew
+    │
+    ├── LEAN (chart / compare queries, ~40s)
+    │     Analyst  ──► Lead (Odin)
+    │
+    └── FULL (deep analysis, ~80s)
+          Lead  ──► Analyst  ──► Historian  ──► Lead (Odin)
+```
+
+**Agents:**
+| Agent | Role |
+|---|---|
+| **Odin (Lead)** | Synthesizes findings, grounds in Volve KB |
+| **Data Analyst** | Runs DDR / WITSML / EDM queries & Python charts |
+| **Historian** | Searches operational history, validates stats |
+
+**Tools available to agents:**
+- `DDR_Query` — Daily Drilling Report search
+- `WITSML_Analyst` — Realtime drilling log analysis
+- `EDM_Technical_Query` — Casing, BHA, formation data
+- `CrossWell_Comparison` — Multi-well KPI comparison
+- `VolveHistory_SearchTool` — RAG over Volve campaign history
+- `python_interpreter` — Pandas + Plotly for custom charts
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| LLM | Google Gemini 2.5 Flash (via `google-generativeai`) |
+| Agent framework | CrewAI 1.10 |
+| RAG / Vector store | ChromaDB + `sentence-transformers` |
+| Data processing | Pandas, NumPy, PDFPlumber |
+| Visualisation | Plotly (HTML) + Kaleido (PNG) |
+| UI | Gradio 6 |
+
+---
+
+## Data
+
+This project uses the **Equinor Volve Field open dataset** (released under the Volve Data Sharing Agreement).
+
+> Download from: [https://www.equinor.com/energy/volve-data-sharing](https://www.equinor.com/energy/volve-data-sharing)
+
+After downloading, extract to `data/raw/` and run the ETL pipeline:
+
+```bash
+python src/data_pipeline/run_pipeline.py
+```
+
+Then build the knowledge base:
+
+```bash
+python src/rag/build_volve_db.py
+python src/rag/build_openviking_db.py
+```
+
+---
+
+## Quickstart (judges)
+
+```bash
+# 1. Clone & install
+git clone <repo-url>
+cd odin
+python -m venv venv
+source venv/bin/activate      # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+
+# 2. Download runtime data (~400 MB knowledge bases + processed CSVs)
+python scripts/download_data.py
+
+# 3. Add your Gemini API key
+cp .env.example .env
+# Edit .env: set GOOGLE_API_KEY=<your key>
+# Free key at: https://aistudio.google.com/app/apikey
+
+# 4. Run
+python src/agents/app.py
+```
+
+Open `http://localhost:7860` in your browser.
+
+---
+
+## Project Structure
+
+```
+odin/
+├── src/
+│   ├── agents/           # Main application
+│   │   ├── app.py        # Gradio UI (entry point)
+│   │   ├── orchestrator.py  # Query routing & streaming
+│   │   ├── crew.py       # CrewAI agent definitions & tasks
+│   │   ├── tools.py      # DDR / WITSML / EDM / RAG tools
+│   │   └── data_tools.py # Python interpreter tool + data helpers
+│   │
+│   ├── data_pipeline/    # ETL: raw Volve data → processed CSV
+│   │   ├── run_pipeline.py
+│   │   ├── parse_witsml_logs.py
+│   │   ├── parse_ddr_xml.py
+│   │   └── parse_edm.py
+│   │
+│   └── rag/              # Knowledge base builders
+│       ├── build_volve_db.py
+│       └── build_openviking_db.py
+│
+├── tests/
+│   └── prompts/          # Agent prompt test cases
+│
+├── data/                 # ← NOT in git (download separately)
+│   ├── raw/              # Original Volve dataset
+│   ├── processed/        # ETL output (CSV / Parquet)
+│   └── knowledge_base/   # ChromaDB vector stores
+│
+├── outputs/              # ← NOT in git (generated at runtime)
+│   └── figures/          # Plotly charts (HTML + PNG)
+│
+├── requirements.txt
+├── .env.example
+└── promptfooconfig.yaml  # Evaluation harness (PromptFoo)
+```
+
+---
+
+## Rate Limits
+
+The system is tuned for the Gemini free tier (15 RPM):
+
+| Crew mode | LLM calls | Target time |
+|---|---|---|
+| Lean (chart / compare) | ~6 calls | ~40s |
+| Full (deep analysis) | ~10 calls | ~80s |
+
+Automatic 429 retry with exponential back-off (10 → 20 → 40 → 60s) is built in.
+
+---
+
+## License
+
+Source code: MIT
+Volve dataset: [Volve Data Sharing Agreement](https://www.equinor.com/energy/volve-data-sharing) (not included in this repo)

app.py

@@ -0,0 +1,40 @@
+"""
+HuggingFace Spaces entry point for ODIN.
+Downloads runtime data from KoopaK/OdinDB on first cold start, then launches the app.
+"""
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent
+sys.path.insert(0, str(ROOT))
+
+# ── Download data from HF Hub if not already present ──────────────────────────
+_data_dir = ROOT / "data"
+_marker   = _data_dir / "processed" / ".hf_downloaded"
+
+if not _marker.exists():
+    print("First run — downloading runtime data from KoopaK/OdinDB …")
+    try:
+        from huggingface_hub import snapshot_download
+        snapshot_download(
+            repo_id   = "KoopaK/OdinDB",
+            repo_type = "dataset",
+            local_dir = str(_data_dir),
+            ignore_patterns=["*.git*"],
+        )
+        _marker.parent.mkdir(parents=True, exist_ok=True)
+        _marker.touch()
+        print("Data download complete.")
+    except Exception as e:
+        print(f"Warning: data download failed — {e}")
+        print("App will start but data tools may return empty results.")
+
+# ── Launch ────────────────────────────────────────────────────────────────────
+from src.agents.app import demo, _figures_dir
+
+demo.launch(
+    server_name  = "0.0.0.0",
+    server_port  = 7860,
+    allowed_paths= [str(_figures_dir)],
+)

src/agents/app.py

@@ -1051,23 +1051,21 @@ def build_app():
 # ENTRY POINT
 # ─────────────────────────────────────────────────────────────────────────────
 
-if __name__ == "__main__":
+def _make_demo():
     base_proj_dir = Path(__file__).resolve().parents[2]
     figures_dir   = base_proj_dir / "outputs" / "figures"
     figures_dir.mkdir(parents=True, exist_ok=True)
+    return build_app(), figures_dir
 
-    theme = gr.themes.Soft(
-        primary_hue="emerald",
-        secondary_hue="slate",
-        neutral_hue="slate",
-        font=gr.themes.GoogleFont("Inter"),
-    )
-    app = build_app()
-    app.launch(
+
+# Module-level demo for HF Spaces (imported by root app.py)
+demo, _figures_dir = _make_demo()
+
+
+if __name__ == "__main__":
+    demo.launch(
         server_name="0.0.0.0",
         server_port=7860,
         share=False,
-        allowed_paths=[str(figures_dir)],
-        theme=theme,
-        css=CUSTOM_CSS,
+        allowed_paths=[str(_figures_dir)],
     )