Upload README.md

README.md

@@ -1,13 +1,111 @@
----
-title: Chat Bot Sentinel
-emoji: 📉
-colorFrom: indigo
-colorTo: blue
-sdk: gradio
-sdk_version: 6.15.1
-python_version: '3.13'
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Market Performance Sentinel (Demo)
+emoji: 🧬
+colorFrom: indigo
+colorTo: purple
+sdk: streamlit
+sdk_version: 1.39.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: Multi-agent LangGraph chatbot for market analytics.
+---
+
+# Market Performance Sentinel — Demo
+
+A multi-agent **LangGraph** chatbot that answers natural-language questions about pharma market
+performance — built around a *supervisor + specialised agents* architecture.
+
+> **This Space runs on 100% fictional data.**
+> All company names, product names, and metric values are **synthetic** and were generated
+> procedurally for demonstration purposes. The fictional company in the demo is **NovaPharma**
+> and its products (NOVACOR, NOVAGLU, etc.) do **not** exist.
+
+## What this demo showcases
+
+The chatbot answers questions like:
+
+- *"What's the market share of the top 3 products in France for the Growth Hormone market?"*
+- *"In LATAM, which country has the biggest QTR-QoQ value change in the Hypothyroid market in 25Q3?"*
+- *"Which cluster is leading the change in APAC for the Anti-EGFR market?"*
+- *"What are the clusters for the Injectable Platform in APAC?"*
+
+It is **not** a Retrieval-Augmented-Generation chatbot — it is a **multi-agent system** where
+each agent has a specific responsibility:
+
+```text
+              ┌────────────────┐
+              │ query_analyzer │   ← LLM classifies intent
+              └───────┬────────┘
+        ┌─────────────┼───────────────┐
+   data_retrieval  parameter_info  out_of_scope
+        │             │                │
+        ▼             ▼                │
+┌────────────────┐ ┌──────────────────┐│
+│ data_extraction│ │  data_knowledge  ││  ← LLM-assisted filter parsing,
+│   (SQL query)  │ │  (param tables)  ││    fuzzy parameter lookup
+└────────┬───────┘ └────────┬─────────┘│
+         │  (optional)      │          │
+         ▼                  │          │
+┌────────────────┐          │          │
+│ leading_country│          │          │  ← deterministic country
+│  (delta calc)  │          │          │    delta calculation
+└────────┬───────┘          │          │
+         │                  │          │
+         ▼                  ▼          ▼
+         ┌──────────────────────────────┐
+         │      generate_response       │  ← LLM synthesises final
+         │  (LLM synthesis + fallback)  │    business-friendly answer
+         └──────────────────────────────┘
+```
+
+| Node | Role |
+|------|------|
+| `query_analyzer` | LLM classifies user intent: `data_retrieval`, `parameter_info`, `both`, or `out_of_scope`. |
+| `data_extraction` | LLM parses filters (region, period, product, market, …) from the user query, then issues a **targeted SQL** query — no full-table scan. |
+| `data_knowledge` | Keyword-scored lookup into the parameter tables (clusters, markets, country-region mapping). |
+| `leading_country` | Deterministic, no-LLM calculation that reconstructs prior-period deltas and ranks countries by contribution. |
+| `generate_response` | LLM synthesises a natural-language answer from extracted data + filters + conversation history; falls back to a deterministic CSV-formatted answer if the LLM is unavailable. |
+
+## Tech stack
+
+- **Streamlit** for the UI
+- **LangGraph** for the agent graph
+- **Hugging Face Inference Providers** (`InferenceClient`) for the LLM calls — free serverless tier
+- **SQLite** (single-file `demo.sqlite`) as the metrics store — pre-seeded with synthetic data
+- **Python 3.10+**
+
+## Configuration
+
+The Space needs **one secret**:
+
+| Secret | Where to set it | Notes |
+|---|---|---|
+| `HF_TOKEN` | Space → Settings → Variables and secrets | A free Hugging Face read token works fine. |
+
+Optional environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `HF_MODEL` | `meta-llama/Llama-3.3-70B-Instruct` | Model used for all LLM calls. Any OpenAI-compatible chat model on HF Inference Providers will work. |
+| `HF_PROVIDER` | `auto` | HF inference provider routing (`auto`, `hf-inference`, `together`, …). |
+
+## Running locally
+
+```bash
+pip install -r requirements.txt
+python seed_data.py            # creates demo.sqlite (one-off; idempotent)
+export HF_TOKEN=hf_xxx          # Linux/macOS
+# $env:HF_TOKEN = "hf_xxx"      # Windows PowerShell
+streamlit run app.py
+```
+
+## Disclaimer
+
+This is a **demonstration project**. The data, products, and company branding are entirely
+fictional. Numbers were generated procedurally and have no relationship to any real-world
+pharmaceutical market.
+
+## License
+
+MIT