---
title: Example App Hackathon Gustave Eiffel 2026
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.1
python_version: '3.11'
app_file: app.py
pinned: false
license: apache-2.0
---

# 🗼 RAG Chat API — Gustave Eiffel Hackathon 2026

A complete **Retrieval-Augmented Generation (RAG)** system deployed as a Hugging Face Space, with a `/query` API endpoint designed for the RAG evaluation system.

---

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Setup & Deployment](#setup--deployment)
4. [Adding Binary Files to the HF Space](#adding-binary-files-to-the-hf-space)
5. [Configuration](#configuration)
6. [How It Works (Detailed)](#how-it-works-detailed)

---

## Overview

This application demonstrates how to build a production-ready RAG system within the Hugging Face ecosystem. It covers:

| Requirement | Solution |
|---|---|
| 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) |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Hugging Face Space                         │
│                                                              │
│  ┌──────────┐     ┌──────────────┐     ┌───────────────┐   │
│  │  Gradio  │     │   FastAPI    │     │   ChromaDB    │   │
│  │   UI     │────▶│  /query      │────▶│  Vector Store │   │
│  │          │     │  /ingest     │     │  (persistent) │   │
│  └──────────┘     └──────┬───────┘     └───────────────┘   │
│                          │                      ▲            │
│                          ▼                      │            │
│               ┌──────────────────┐    ┌─────────────────┐   │
│               │  Azure OpenAI    │    │  Azure OpenAI   │   │
│               │  GPT-5 (LLM)    │    │  text-embedding │   │
│               │                  │    │  -3-small       │   │
│               └──────────────────┘    └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---


## Setup & Deployment

### Prerequisites

- Python 3.11+
- A Hugging Face account with an API token

### Local Development

```bash
# Clone the repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/Example-App-Hackathon-Gustave-Eiffel-2026
cd Example-App-Hackathon-Gustave-Eiffel-2026
```

#### Set Up a Python Virtual Environment

Using a virtual environment isolates project dependencies from your global Python installation.

```bash
# Create the virtual environment (Python 3.11+ required)
python -m venv ~/.venv/hackathon-eiffel

# Activate it
# macOS / Linux
source ~/.venv/hackathon-eiffel/bin/activate
# Windows (PowerShell)
~\.venv\hackathon-eiffel\Scripts\Activate.ps1
# Windows (Command Prompt)
~\.venv\hackathon-eiffel\Scripts\activate.bat

```

Once your virtual environment is active, install dependencies and run the app:

```bash
# Install dependencies
pip install -r requirements.txt

# Set your Azure API key
# macOS / Linux
export AZURE_API_KEY="your_azure_api_key_here"
# Windows (PowerShell)
$env:AZURE_API_KEY = "your_azure_api_key_here"

# Run the application
python app.py
# Server starts at http://localhost:7860

# To make it work, you first need to create embeddings , you can learn about it from README_RAG.md
```

> **Tip:** To deactivate the virtual environment when you are done, run `deactivate` (venv) or `conda deactivate` (conda).



### Testing the API

```bash
# Health check
curl http://localhost:7860/health

# Query the RAG system
curl -X POST http://localhost:7860/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the Eiffel Tower?", "top_k": 3}'

# Ingest a new document
curl -X POST http://localhost:7860/ingest \
  -H "Content-Type: application/json" \
  -d '{"text": "Your document text here...", "source": "new_doc.txt"}'
```

---

## 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. 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
# Install the hf CLI (requires uv)
uv tool install "huggingface_hub[cli]"

# Authenticate (needs Write access to the bucket)
export HF_TOKEN="hf_your_token_here"
# or interactively:
hf auth login
```

### Step 1 — Attach the Storage Bucket to Your Space

1. Open your Space on huggingface.co
2. Go to **Settings → Persistent Storage**
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 — Sync Your Local `./data` with the Space Bucket

Place all persistent files under a local `./data` folder. The expected structure is:

```
./data/
├── chroma_db/          # Binary files and ChromaDB vector store
│   └── chroma.sqlite3
./train_data/           # Training/test datasets (PDFs, CSVs, etc.)
    ├── Automobile - Train/
    ├── Climatique-Train/
    └── ...
```

**Upload (local → bucket):**
```bash
# 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

# Sync only specific file types
hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage \
  --include "*.pdf" --include "*.sqlite3"
```

> **`--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

To pull the latest bucket contents back to a local `./data` folder (e.g., on a new dev machine):

```bash
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.

The application resolves the data root automatically via a single `DATA_DIR` constant in `app.py`:

```python
from pathlib import Path

# /data when running in HF Spaces (bucket mount), ./data for local dev
DATA_DIR = Path("/data") if Path("/data").is_dir() else Path("./data")

CHROMA_PERSIST_DIR = str(DATA_DIR / "chroma_db")
SAMPLE_DOCS_DIR = DATA_DIR / "sample_documents"
```

All persistent data — the vector store, sample documents, datasets — lives under `DATA_DIR` so a single `hf sync ./data ...` covers everything.

### Useful `hf sync` Flags

| Flag | Description |
|---|---|
| `--include "*.pdf"` | Only sync files matching the pattern |
| `--exclude "*.tmp"` | Skip files matching the pattern |
| `--delete` | Remove files in the destination that no longer exist in the source |
| `--dry-run` | Preview what would be transferred without actually doing it |

```bash
# Preview before committing
hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage --dry-run
```

---

## Configuration

The application loads model configuration with the following priority:

1. **`./data/config.json`** — the live runtime config (read at startup)
2. **`./config.json`** (project root) — example/template file used as fallback when no runtime config exists; **never put real credentials here**

### Step 1 — Create `data/config.json`

Copy the root template to `./data/` and fill in your Azure OpenAI resource details:

```bash
cp config.json data/config.json
```

Then edit `data/config.json`:

```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_completion_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`).

### Step 3 — Push `data/config.json` to the HF Bucket

`data/config.json` lives under `./data` so a normal bucket sync includes it automatically:

```bash
hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage --delete
```

The Space container will then find it at `/data/config.json` on next restart.

> **Do not commit `data/config.json` to Git** — it contains endpoint URLs tied to your Azure resource. Add `data/config.json` to `.gitignore`. The root `config.json` is safe to commit as it only contains placeholder values.

### Tunable Parameters

The following constants in `app.py` can also be adjusted directly:

| Variable | Default | Description |
|---|---|---|
| `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 |
| `CHUNK_SIZE` | `512` | Text chunk size in characters |
| `CHUNK_OVERLAP` | `50` | Overlap between chunks |
| `TOP_K_RESULTS` | `3` | Number of context chunks to retrieve |

---

## How It Works (Detailed)

### Why RAG?

Large Language Models have a knowledge cutoff and can hallucinate. RAG solves this by:
- **Grounding** responses in actual documents
- **Updating** knowledge without retraining
- **Providing** source attribution for answers

### Why ChromaDB in HF Spaces?

ChromaDB is ideal for Hugging Face Spaces because:
- Runs **in-process** (no external database needed)
- Supports **persistent storage** (survives Space restarts)
- Uses **HNSW index** for fast approximate nearest neighbor search
- Zero configuration required

### Why Azure OpenAI Embeddings?

- **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

The `/query` endpoint is designed to be called by external RAG evaluation frameworks. It returns:
- The generated `answer` for correctness evaluation
- Source `documents` for faithfulness/groundedness checks
- Similarity `scores` for retrieval quality assessment

---

## Troubleshooting

### ChromaDB Telemetry Error

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 / Embedding API Errors

If the `/query` endpoint logs a `503 Service Unavailable` or `401 Unauthorized`:

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

If you see an error like the one below when running `python app.py`, your machine is most likely behind a **corporate proxy that performs SSL inspection** and has its own root CA that Python does not trust by default.

```
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify
failed: unable to get local issuer certificate
```

**Fix — point `requests` to your corporate CA bundle:**

```bash
# macOS / Linux — use the system bundle (adjust path for your distro)
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt   # Debian/Ubuntu
export REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt     # RHEL/CentOS

# Or point to a specific corporate certificate file
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.crt

# Windows (PowerShell)
$env:REQUESTS_CA_BUNDLE = "C:\path\to\corporate-ca.crt"
```

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.

### `hf sync` 401 Unauthorized Error

If `hf sync` fails with:

```
Error: Client error '401 Unauthorized' for url
'https://huggingface.co/api/buckets/.../tree?recursive=true'
Invalid username or password.
```

the `hf` CLI has not been authenticated. Log in with your Hugging Face token:

```bash
hf auth login
# Paste your token when prompted (needs read + write access to the bucket)
```

Or set the token as an environment variable so the CLI picks it up automatically without an interactive prompt:

```bash
export HF_TOKEN="hf_your_token_here"
hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage
```

> **Generate a token:** Go to huggingface.co → Settings → Access Tokens → New token. Select **Write** role so the CLI can both read and upload to the bucket.

> **Check current login state:**
> ```bash
> hf auth whoami
> ```

---

### `hf sync` SSL Certificate Verification Error

The `hf` CLI (installed via `uv tool install huggingface_hub`) uses `httpx` internally instead of `requests`, so it ignores `REQUESTS_CA_BUNDLE`. If `hf sync` fails with:

```
httpcore.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
unable to get local issuer certificate
```

you must set the certificate bundle through the variables that `httpx` (and the underlying `ssl` module) respects:

```bash
# Option A — point to your corporate CA bundle file (recommended)
export SSL_CERT_FILE=/path/to/corporate-ca.crt
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.crt   # keep this too for other tools

hf sync ./data hf://buckets/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026-storage

# Option B — append your CA cert to the system bundle and point there
cat /path/to/corporate-ca.crt >> /etc/ssl/certs/ca-certificates.crt
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
```

`SSL_CERT_FILE` overrides the default CA store for Python's `ssl` module, which `httpx` / `httpcore` uses directly.

**If you need to set these variables permanently** (e.g., in a shared dev environment), add them to your shell profile:

```bash
# ~/.bashrc or ~/.zshrc
export SSL_CERT_FILE=/path/to/corporate-ca.crt
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.crt
```

> **Finding your corporate CA cert on Linux:**
> ```bash
> # List all trusted CAs and look for your company's entry
> awk -v cmd='openssl x509 -noout -subject' '/BEGIN CERT/{close(cmd)}; {print | cmd}' \
>   /etc/ssl/certs/ca-certificates.crt | grep -i "your-company-name"
>
> # Or export the cert directly from the proxy
> echo | openssl s_client -connect huggingface.co:443 -showcerts 2>/dev/null \
>   | openssl x509 -outform PEM > /tmp/hf-chain.pem
> export SSL_CERT_FILE=/tmp/hf-chain.pem
> ```

---

## License

Apache 2.0