README.md

metadata

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

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

# 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

# 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

hf sync hf://buckets/<org>/<space-name>-storage ./data

Training Data Download

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

# 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

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:

{
    "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