README.md

---
title: Number_one's RAG App
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
short_description: hackathon space 06/2026
---

# Number_one — RAG App

RAG (Retrieval-Augmented Generation) application built for the Hackathon Gustave Eiffel 2026.

**Team:** Alves Enrique · Berry Lise · Bessiere Nicolas · Duong Davy · Coulibaly Fatoumata

---

# RAG Chat API Setup & Deployment Guide

## Key Instructions

### Virtual Environment Setup
```bash
python -m venv ~/.venv/hackathon-eiffel

# Activate (macOS / Linux)
source ~/.venv/hackathon-eiffel/bin/activate

# Activate (Windows PowerShell)
~\.venv\hackathon-eiffel\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Set Azure API key (macOS / Linux)
export AZURE_API_KEY="your_azure_api_key_here"

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

### Hugging Face CLI Installation
```bash
# Install the hf CLI (requires uv)
uv tool install "huggingface_hub[cli]"

# Login to Hugging Face
export HF_TOKEN="hf_your_token_here"
# or interactively:
hf auth login
```

## Persistent Storage (`/data`)

Each Hugging Face Space has a **persistent storage bucket** mounted at `/data` in the container. This stores:
- **ChromaDB vector store:** `/data/chroma_db/`
- Documents, datasets, and binary files

**Bucket naming convention:**
```
Space: https://huggingface.co/spaces/<org>/<space-name>
Bucket URI: hf://buckets/<org>/<space-name>-storage
```

### Syncing Local Data to Bucket

```bash
# Mirror ./data to bucket (removes remote files deleted locally)
hf sync ./data hf://buckets/<org>/<space-name>-storage --delete

# Sync specific subfolder
hf sync ./data/chroma_db hf://buckets/<org>/<space-name>-storage/chroma_db

# Sync specific file types
hf sync ./data hf://buckets/<org>/<space-name>-storage \
  --include "*.pdf" --include "*.sqlite3"
```

### Downloading Bucket to Another Machine
```bash
hf sync hf://buckets/<org>/<space-name>-storage ./data
```

## Training Data Download

The hackathon training datasets (~1GB) are in a shared read-only bucket:

```bash
# Download all training data to local ./train_data folder
hf sync hf://buckets/millimanfrance/Hackathon2026TrainData ./train_data
```

**Expected structure:**
```
./train_data/
├── Automobile - Train/
├── Climatique - Train/
└── ...
```

## Expected Data Directory Structure

```
./data/
├── chroma_db/          # ChromaDB vector store (binary)
│   └── chroma.sqlite3
./train_data/           # Training datasets (mounted from organizer bucket)
    ├── Automobile - Train/
    ├── Climatique - Train/
    └── ...
```

## Accessing Files in Application

```python
from pathlib import Path

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

CHROMA_PERSIST_DIR = str(DATA_DIR / "chroma_db")
ENV_FILE = str(DATA_DIR / ".env")
```

## API Response Format (Required)

The `/query` endpoint **MUST return** this exact format:
```json
{
    "answer": "str",
    "sources": [
        {
            "source": "filename",
            "score": 0.95,
            "ref_text": "text span from document"
        }
    ],
    "explanation": "str",
    "total_token": 100,
    "prompt_tokens": 50,
    "completion_tokens": 50,
    "cached_tokens": 0,
    "co2_grams": 0.5,
    "energy_kwh": 0.001,
    "run_time_in_ms": 250.5
}
```

## Configuration (`config.json`)

**NEVER put credentials in config.json** — use environment variables instead.

## Deploying to Hugging Face Spaces

1. Create/configure Space on huggingface.co
2. Go to **Settings → Storage Buckets → Mount a bucket** and select `<org>/<space-name>-storage`
3. Add `AZURE_API_KEY` as a **Space Secret** (Settings → Variables and secrets)
4. Push code to Space repository
5. Sync data: `hf sync ./data hf://buckets/<org>/<space-name>-storage`