Update README for data sync

README.md

@@ -36,8 +36,8 @@ This application demonstrates how to build a production-ready RAG system within
 
 | Requirement | Solution |
 |---|---|
-| LLM API calls | Hugging Face Inference API (`InferenceClient`) |
-| Text → Embeddings | `sentence-transformers/all-MiniLM-L6-v2` (runs locally) |
+| LLM API calls | Azure OpenAI (`gpt-5` via REST) |
+| Text → Embeddings | Azure OpenAI (`text-embedding-3-small` via REST) |
 | Vector Store | ChromaDB (persistent, runs in-process) |
 | API Endpoint | FastAPI with `POST /query` |
 | UI | Gradio Blocks (chat + document ingestion) |
@@ -58,9 +58,9 @@ This application demonstrates how to build a production-ready RAG system within
 │                          │                      ▲            │
 │                          ▼                      │            │
 │               ┌──────────────────┐    ┌─────────────────┐   │
-│               │  HF Inference    │    │  Sentence       │   │
-│               │  API (LLM)       │    │  Transformers   │   │
-│               │  Qwen2.5-72B     │    │  (Embeddings)   │   │
+│               │  Azure OpenAI    │    │  Azure OpenAI   │   │
+│               │  GPT-5 (LLM)    │    │  text-embedding │   │
+│               │                  │    │  -3-small       │   │
 │               └──────────────────┘    └─────────────────┘   │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -89,15 +89,16 @@ chunks = splitter.split_text(document_text)
 
 Convert text chunks into dense vector representations that capture semantic meaning.
 
-1. **Load model** — We use `sentence-transformers/all-MiniLM-L6-v2`, a lightweight model that produces 384-dimensional vectors
+1. **Call Azure OpenAI** — We use the `text-embedding-3-small` model via the Azure OpenAI embeddings endpoint
 2. **Encode text** — Each chunk is transformed into a fixed-size vector where semantically similar texts are closer together in vector space
 
 ```python
-from sentence_transformers import SentenceTransformer
+import requests as http_requests
 
-model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
-embeddings = model.encode(["chunk 1 text", "chunk 2 text"])
-# Result: numpy array of shape (2, 384)
+headers = {"api-key": AZURE_API_KEY, "Content-Type": "application/json"}
+payload = {"input": ["chunk 1 text", "chunk 2 text"], "model": "text-embedding-3-small"}
+resp = http_requests.post(EMBEDDING_ENDPOINT_URL, headers=headers, json=payload)
+embeddings = [item["embedding"] for item in resp.json()["data"]]
 ```
 
 ### Step 3: Store in Vector Database (ChromaDB)
@@ -128,14 +129,14 @@ collection.add(
 
 When a user asks a question, find the most relevant context.
 
-1. **Embed the query** — Use the same embedding model to convert the question to a vector
+1. **Embed the query** — Use the same Azure OpenAI embedding model to convert the question to a vector
 2. **Similarity search** — Find the top-K nearest vectors in ChromaDB (cosine similarity)
 3. **Return context** — Extract the original text chunks for the closest matches
 
 ```python
-query_embedding = model.encode(["What is the Eiffel Tower?"])
+query_embedding = generate_embeddings(["What is the Eiffel Tower?"])[0]
 results = collection.query(
-    query_embeddings=query_embedding.tolist(),
+    query_embeddings=[query_embedding],
     n_results=3,
 )
 ```
@@ -145,7 +146,7 @@ results = collection.query(
 Combine retrieved context with the user's question and generate an answer.
 
 1. **Build prompt** — Load the template from [`prompts/rag_prompt.txt`](prompts/rag_prompt.txt), inject retrieved context and the user's question
-2. **Call LLM API** — Send the prompt to the Hugging Face Inference API (`chat_completion`, Qwen2.5-72B-Instruct)
+2. **Call Azure OpenAI** — Send the prompt to the Azure OpenAI chat/completions endpoint (`gpt-5`)
 3. **Return response** — The LLM generates an answer grounded in the provided context
 
 The prompt template (`prompts/rag_prompt.txt`):
@@ -168,11 +169,16 @@ RAG_PROMPT_TEMPLATE = Path("prompts/rag_prompt.txt").read_text(encoding="utf-8")
 
 # At query time:
 prompt = RAG_PROMPT_TEMPLATE.format(context=context_text, question=user_query)
-response = llm_client.chat_completion(
-    messages=[{"role": "user", "content": prompt}],
-    max_tokens=512,
-)
-answer = response.choices[0].message.content
+headers = {"api-key": AZURE_API_KEY, "Content-Type": "application/json"}
+payload = {
+    "model": "gpt-5",
+    "messages": [{"role": "user", "content": prompt}],
+    "max_tokens": 512,
+    "temperature": 0.7,
+    "top_p": 0.95,
+}
+resp = requests.post(LLM_ENDPOINT_URL, headers=headers, json=payload)
+answer = resp.json()["choices"][0]["message"]["content"]
 ```
 
 > **Tip:** Edit `prompts/rag_prompt.txt` to tune the model's behaviour (tone, language, output format) without touching application code.
@@ -250,8 +256,8 @@ System health check.
 {
     "status": "healthy",
     "documents_in_store": 42,
-    "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
-    "llm_model": "HuggingFaceH4/zephyr-7b-beta"
+    "embedding_model": "text-embedding-3-small",
+    "llm_model": "gpt-5"
 }
 ```
 
@@ -295,11 +301,11 @@ Once your virtual environment is active, install dependencies and run the app:
 # Install dependencies
 pip install -r requirements.txt
 
-# Set your HF token
+# Set your Azure API key
 # macOS / Linux
-export HF_TOKEN="hf_your_token_here"
+export AZURE_API_KEY="your_azure_api_key_here"
 # Windows (PowerShell)
-$env:HF_TOKEN = "hf_your_token_here"
+$env:AZURE_API_KEY = "your_azure_api_key_here"
 
 # Run the application
 python app.py
@@ -311,7 +317,7 @@ python app.py
 ### Deploy to Hugging Face Spaces
 
 1. Create a new Space on huggingface.co (select Gradio SDK)
-2. Add `HF_TOKEN` as a Space Secret (Settings → Secrets)
+2. Add `AZURE_API_KEY` as a Space Secret (Settings → Secrets)
 3. Push this code to the Space repository
 4. The Space automatically installs dependencies and starts the app
 
@@ -336,10 +342,32 @@ curl -X POST http://localhost:7860/ingest \
 
 ## Adding Binary Files to the HF Space
 
-Large or binary files (PDFs, pre-built ChromaDB databases, datasets, model weights) are stored in a **Hugging Face bucket** and mounted into the Space container at `/data`. The `hf sync` command keeps your local folder in sync with the bucket.
+Large or binary files (PDFs, pre-built ChromaDB databases, datasets, model weights) are stored in a **Hugging Face bucket** and mounted into the Space container. The `hf sync` command keeps your local folder in sync with the bucket.
 
 > **Note:** Git LFS is not supported for Hugging Face Spaces persistent storage. Use the bucket + `hf sync` workflow described here instead.
 
+### The `/data` Shared Folder
+
+Each Hugging Face Space has a **persistent storage bucket** that is automatically mounted at `/data` inside the running container. This folder is the single shared location where the application reads and writes all persistent files — the ChromaDB vector store, ingested documents, and any binary assets.
+
+| Path in container | Purpose |
+|---|---|
+| `/data/chroma_db/` | ChromaDB vector store (survives Space restarts) |
+| `/data/sample_documents/` | Text/PDF files auto-ingested on startup |
+| `/data/DataSet/` | Training and evaluation datasets |
+
+**Default bucket naming convention:** A Space at  
+`https://huggingface.co/spaces/<org>/<space-name>`  
+gets a default storage bucket at  
+`https://huggingface.co/buckets/<org>/<space-name>-storage`
+
+For this project:
+- Space: `https://huggingface.co/spaces/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026`
+- Bucket: `https://huggingface.co/buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage`
+
+The `hf://` URI for use with the CLI is:  
+`hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage`
+
 ### Prerequisites
 
 ```bash
@@ -359,28 +387,24 @@ hf auth login
 3. Under **"Attach storage"**, select the existing bucket **`millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage`** (or create a new one)
 4. Save — Hugging Face will mount the bucket at `/data` inside the Space container
 
-### Step 2 — Upload Files from Your Local Machine
+### Step 2 — Sync Your Local `./data` with the Space Bucket
 
 Place all persistent files under a local `./data` folder. The expected structure is:
 
 ```
 ./data/
-├── chroma_db/          # Pre-built ChromaDB vector store
+├── chroma_db/          # Binary files and ChromaDB vector store
 │   └── chroma.sqlite3
-├── sample_documents/   # Text/PDF files ingested on startup
-│   ├── eiffel_tower.txt
-│   └── gustave_eiffel.txt
-└── DataSet/            # Training/test datasets (PDFs, CSVs, etc.)
-    ├── Automobile/
-    ├── Climatique/
+./train_data/           # Training/test datasets (PDFs, CSVs, etc.)
+    ├── Automobile - Train/
+    ├── Climatique-Train/
     └── ...
 ```
 
-Then push:
-
+**Upload (local → bucket):**
 ```bash
-# Sync the entire ./data folder to the bucket
-hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage
+# Mirror ./data to the bucket — removes remote files deleted locally
+hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage --delete
 
 # Sync only a specific sub-folder (e.g., the vector store)
 hf sync ./data/chroma_db hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage/chroma_db
@@ -390,7 +414,9 @@ hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-
   --include "*.pdf" --include "*.sqlite3"
 ```
 
-`hf sync` is **incremental** — it computes checksums and only uploads files that have changed.
+> **`--delete` flag:** Without it, `hf sync` only uploads new/changed files and never removes anything from the remote. Add `--delete` to make the bucket an exact mirror of your local `./data`.
+
+`hf sync` is **incremental** — it computes checksums and only transfers files that have changed.
 
 ### Step 3 — Download the Bucket to Another Machine
 
@@ -400,11 +426,33 @@ To pull the latest bucket contents back to a local `./data` folder (e.g., on a n
 hf sync hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage ./data
 ```
 
+### Step 4 — Sync Hackathon Training Data
+
+The shared training dataset for this hackathon is stored in a separate read-only bucket. Sync it to a local `./train_data` folder (it will be mounted at `/train_data` inside the Space):
+
+```bash
+# Download all training data locally
+hf sync hf://buckets/millimanfrance/Hackathon2026TrainData ./train_data
+
+# Download only a specific category
+hf sync hf://buckets/millimanfrance/Hackathon2026TrainData/Automobile ./train_data/Automobile
+```
+
+> **Note:** `Hackathon2026TrainData` is a shared read-only bucket. Do not attempt to push to it.
+
+To make this data available inside your Space, push it to your Space's own bucket under a `train_data/` sub-folder:
+
+```bash
+hf sync ./train_data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage/train_data
+```
+
+It will then be accessible inside the container at `/data/train_data/`.
+
 ### Accessing Files in the Space Application
 
-Once the bucket is mounted, files appear under `/data` inside the Space container regardless of their path in the bucket.
+Once the bucket is mounted, files appear under `/data` inside the Space container.
 
-The application resolves this automatically via a single `DATA_DIR` constant in `app.py`:
+The application resolves the data root automatically via a single `DATA_DIR` constant in `app.py`:
 
 ```python
 from pathlib import Path
@@ -436,11 +484,61 @@ hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-
 
 ## Configuration
 
+### Step 1 — Edit `config.json`
+
+Open [`config.json`](config.json) at the project root and replace the placeholders with your Azure OpenAI resource details:
+
+```json
+{
+    "embedding": {
+        "endpoint_url": "https://<your-resource>.openai.azure.com/openai/deployments/<your-embedding-deployment>/embeddings?api-version=2024-12-01-preview",
+        "model": "text-embedding-3-small"
+    },
+    "llm": {
+        "endpoint_url": "https://<your-resource>.openai.azure.com/openai/deployments/<your-deployment>/chat/completions?api-version=2024-12-01-preview",
+        "model": "gpt-5",
+        "max_tokens": 512,
+        "temperature": 0.7,
+        "top_p": 0.95
+    }
+}
+```
+
+| Field | What to put |
+|---|---|
+| `<your-resource>` | Your Azure OpenAI resource name (from the Azure Portal) |
+| `<your-embedding-deployment>` | The deployment name for your embedding model |
+| `<your-deployment>` | The deployment name for your LLM |
+| `model` | Must match the model name used when creating the deployment |
+
+> **Note:** The `endpoint_url` for embeddings ends in `/embeddings` and the one for the LLM ends in `/chat/completions`. Keep those suffixes intact.
+
+### Step 2 — Set the API Key
+
+The API key is **not** stored in `config.json`. Set it as an environment variable:
+
+```bash
+# macOS / Linux
+export AZURE_API_KEY="your_azure_api_key_here"
+
+# Windows (PowerShell)
+$env:AZURE_API_KEY = "your_azure_api_key_here"
+```
+
+When deploying to Hugging Face Spaces, add it as a **Space Secret** (Settings → Secrets → New secret → name it `AZURE_API_KEY`).
+
+### Tunable Parameters
+
+The following constants in `app.py` can also be adjusted directly:
+
 | Variable | Default | Description |
 |---|---|---|
-| `HF_TOKEN` | (Space Secret) | Hugging Face API token for Inference API |
-| `EMBEDDING_MODEL_NAME` | `sentence-transformers/all-MiniLM-L6-v2` | Model for text embeddings |
-| `LLM_MODEL_NAME` | `Qwen/Qwen2.5-72B-Instruct` | LLM for answer generation |
+| `AZURE_API_KEY` | (env var / Space Secret) | Azure OpenAI API key (shared by LLM and embedding endpoints) |
+| `EMBEDDING_MODEL_NAME` | `text-embedding-3-small` | Azure OpenAI embedding model |
+| `LLM_MODEL_NAME` | `gpt-5` | Azure OpenAI LLM for answer generation |
+| `LLM_MAX_TOKENS` | `512` | Maximum tokens in the LLM response |
+| `LLM_TEMPERATURE` | `0.7` | Sampling temperature for the LLM |
+| `LLM_TOP_P` | `0.95` | Top-p (nucleus) sampling for the LLM |
 | `DATA_DIR` | `/data` (HF Spaces) or `./data` (local) | Root directory for all persistent data |
 | `CHROMA_PERSIST_DIR` | `DATA_DIR/chroma_db` | ChromaDB storage path |
 | `SAMPLE_DOCS_DIR` | `DATA_DIR/sample_documents` | Documents ingested on startup |
@@ -467,12 +565,12 @@ ChromaDB is ideal for Hugging Face Spaces because:
 - Uses **HNSW index** for fast approximate nearest neighbor search
 - Zero configuration required
 
-### Why Sentence Transformers?
+### Why Azure OpenAI Embeddings?
 
-- Runs **locally** within the Space (no API cost for embeddings)
-- `all-MiniLM-L6-v2` is small (~80MB) but effective
-- Produces **384-dimensional** vectors (good balance of quality vs. storage)
-- Trained on 1B+ sentence pairs for semantic similarity
+- **High-quality embeddings** — `text-embedding-3-small` produces state-of-the-art embeddings with excellent semantic understanding
+- **No local model loading** — Eliminates GPU/memory requirements on the Space
+- **Scalable** — Handles large batch embedding requests via the API
+- **Consistent** — Same model used across environments (dev, staging, production)
 
 ### Evaluation Integration
 
@@ -489,9 +587,14 @@ The `/query` endpoint is designed to be called by external RAG evaluation framew
 
 If you see `capture() takes 1 positional argument but 3 were given` in the logs, it is a version incompatibility between ChromaDB and the `posthog` library. Telemetry is disabled at startup (`anonymized_telemetry=False`) so this error should no longer appear. If it persists after updating dependencies, pin `posthog<3.0` in `requirements.txt`.
 
-### LLM 404 — Model Not Found
+### LLM / Embedding API Errors
+
+If the `/query` endpoint logs a `503 Service Unavailable` or `401 Unauthorized`:
 
-If the `/query` endpoint logs a `404 Not Found` for the Inference API URL, the configured model has been removed from the free serverless tier. Update `LLM_MODEL_NAME` in `app.py` to an available model. The app now uses `chat_completion` (`/v1/chat/completions`) rather than the legacy `text_generation` endpoint, so any model listed under **Inference Providers** on huggingface.co will work. The prompt in `prompts/rag_prompt.txt` is model-agnostic (no special tokens).
+1. Verify `AZURE_API_KEY` is set correctly as an environment variable or Space Secret
+2. Check that the endpoint URLs in `config.json` match your Azure OpenAI deployment
+3. Ensure your Azure OpenAI deployment is active and the model name matches the deployment name
+4. The app calls the Azure OpenAI-compatible `chat/completions` and `embeddings` endpoints directly via REST
 
 ### SSL Certificate Verification Error
 
@@ -516,7 +619,7 @@ export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.crt
 $env:REQUESTS_CA_BUNDLE = "C:\path\to\corporate-ca.crt"
 ```
 
-Set the variable **before** running `python app.py`. Both `huggingface_hub` and `sentence-transformers` use the `requests` library, which reads `REQUESTS_CA_BUNDLE` automatically — no code change is needed.
+Set the variable **before** running `python app.py`. The `requests` library (used for Azure OpenAI API calls) reads `REQUESTS_CA_BUNDLE` automatically — no code change is needed.
 
 > **How to export your corporate CA certificate:**
 > Open the failing URL (`https://huggingface.co`) in your browser, click the padlock icon → View Certificate → export the root CA as a `.crt` / `.pem` file, then point `REQUESTS_CA_BUNDLE` to that file.