Pull code from source repo

README.md

@@ -1,13 +1,290 @@
----
-title: Hackathon IA Team
-emoji: 🐢
-colorFrom: gray
-colorTo: yellow
+---
+title: Example App Hackathon Gustave Eiffel 2026
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+sdk_version: 4.44.1
+python_version: '3.11'
 app_file: app.py
 pinned: false
+license: apache-2.0
+---
+
+# RAG Chat API Sample Code for Gustave Eiffel Hackathon 2026
+
+This is a sample code of **Retrieval-Augmented Generation (RAG)** API deployed to Hugging Face Spaces for the Gustave Eiffel Hackathon 2026. The goal of this hackathon is to build an AI assistant for actuarial questions using a document corpus. The core challenge
+is to build an assistant that is:
+
+- ✅ Accurate (Juste) – correct answers, no hallucinations
+- 💲 Low cost (Pas cher) – minimize token usage
+- 🌱 Sustainable (Sobre) – reduce CO2 impact
+
+👉 Success = balance all three, not just performance!
+
+This sample code demonstrates how to build a RAG system with FastAPI and Gradio, and deploy it to Hugging Face Spaces. It also includes the necessary configuration and structure to meet the hackathon requirements. It includes:
+- `/query` API endpoint to interact with the user or the RAG evaluation system. Note that the output of this endpoint is designed for the RAG evaluation system, which will assess the correctness of the answer from your RAG. The response MUST have all the fields as follow (DO NOT change the response format, otherwise the evaluation framework will not be able to parse the response and evaluate the answer -- you will get 0 for the evaluation if the response is unparseable):
+  - answer (str): The generated answer from your RAG system
+  - sources (list): Source documents used for context in the answer generation, each source should have:
+    - source (str): File name of the source document
+    - score (float): Relevance score of the source document
+    - ref_text (str): The exact text span from the source document that is used in the answer generation (can be truncated if too long)
+  - explanation (str): Explanation of the retrieval and answer logic
+  - total_token (int): Total token count from the LLM call
+  - prompt_tokens (int): Prompt token count
+  - completion_tokens (int): Completion token count
+  - cached_tokens (int): Cached prompt tokens (when reported by model provider)
+  - co2_grams (float | None): Estimated CO2 emission in grams (via ecologits)
+  - energy_kwh (float | None): Estimated energy use in kWh (via ecologits)
+  - run_time_in_ms (float): Pipeline execution time in milliseconds 
+- `/health` API endpoint to check if the API is running or not. The return format should be `{"status": "healthy"}` when the API is healthy.
+- Gradio UI and configuration to be deployed to Hugging Face Spaces. The UI allows users to chat with the RAG system and ingest new documents.
+
+---
+
+## Overview
+
+This application demonstrates how to build a production-ready RAG system within the Hugging Face Spaces. It covers:
+
+| Requirement | Provided Solution |
+|---|---|
+| LLM API calls | Azure OpenAI (`gpt-5.1` via REST API) |
+| Text → Embeddings | Azure OpenAI (`text-embedding-3-small` via REST API) |
+| Prompt engineering | Custom prompts for RAG system in /prompts/rag_prompts.txt |
+| Vector Store | ChromaDB (persistent in /data folder, runs in-process) |
+
+Hackathon participants can use this code as a starting point and customize any solutions (the LLM calls, embeddings, prompts, and vector store) as they see fit to optimize for accuracy, cost, and sustainability. The provided code is modular and well-documented to facilitate easy modifications.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Hugging Face Space                        │
+│                                                              │
+│  ┌──────────┐     ┌──────────────┐     ┌────────────────┐    │
+│  │  Gradio  │     │   FastAPI    │     │   ChromaDB     │    │
+│  │   UI     │────▶│  /query     │────▶│  Vector Store  │    │
+│  │          │     │  /ingest     │     │ (persistent in │    │
+│  │          │     │  /health     │     │  /data folder) │    │
+│  └──────────┘     └──────┬───────┘     └────────────────┘    │
+│                          │                      ▲            │
+│                          ▼                      │            │
+│               ┌──────────────────┐    ┌─────────────────┐    │
+│               │  Azure OpenAI    │    │  Azure OpenAI   │    │
+│               │  GPT-5.1 (LLM)   │    │  text-embedding │    │
+│               │                  │    │  -3-small       │    │
+│               └──────────────────┘    └─────────────────┘    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+## Setup & Deployment
+
+### 1. Register for Hugging Face and Create a Space
+
+If you have not created a Hugging Face Space, follow the instructions in the [Hugging Face Quickstart](README_HF.md) to create an account and set up a new Space and clone the sample code to your local machine.
+
+### 2. Set Up a Python Virtual Environment
+
+Download and set up a Python virtual environment to manage package dependencies.
+
+To download Python, visit the [official Python website](https://www.python.org/downloads/) and follow the installation instructions for your operating system. Make sure to install Python 3.10 or 3.11. There is no need to install the latest Python version if it is above 3.11, as some dependencies may not be compatible with versions higher than 3.11.
+
+To create a virtual environment, run the following command in your terminal (you can replace `hackathon-eiffel` with any name you prefer for your virtual environment):
+
+```bash
+python -m venv ~/.venv/hackathon-eiffel
+
+# Activate the virtual environment
+# 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 activated, go to your project directory to install package dependencies and run the application:
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Set your Azure API key. Azure API key is a key to call the LLM APIs. The organizers will provide you one at the date of the hackathon.
+# 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 . If you can open http://localhost:7860/health on browser, it means the API is running successfully.
+
+# To make the RAG 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).
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+### 3. Install the Hugging Face CLI
+
+To manage binary files in the Hugging Face bucket (for storing large files like ChromaDB vector store, ingested documents, etc.), you need to install the Hugging Face CLI tool:
+
+```bash
+# Install the hf CLI (requires uv)
+uv tool install "huggingface_hub[cli]"
+
+# Try to login to Hugging Face with Hugging Face CLI (it needs Write access to the bucket)
+export HF_TOKEN="hf_your_token_here"
+# or interactively:
+hf auth login
+```
+
+### 4. Adding Binary Files to the HF Space
+
+Large or binary files (PDFs, pre-built ChromaDB databases, datasets, model weights) have to be 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.
+
+### 5. Persist files in the Shared Folder
+
+Each Hugging Face Space has a **persistent storage bucket** that is automatically mounted at `/data` to your project root inside the running container server. This folder is the single shared location where the application reads and writes all persistent files — the ChromaDB vector store, display images, even secrets and any binary assets.
+
+| Path in server | Purpose |
+|---|---|
+| `/data/chroma_db/` | ChromaDB vector store (survives Space restarts) |
+
+**Default bucket naming convention:** 
+A Hugging Face Space at  
+`https://huggingface.co/spaces/<org>/<space-name>`  
+gets a default /data storage bucket at  
+`https://huggingface.co/buckets/<org>/<space-name>-storage`
+
+Using this project as an example, the Space URL is:
+- 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`
+
+Note that by default, the bucket is empty and private when you create the Space. You need to upload files to it (via `hf sync`) before they appear in the Space server at `/data`.
+
+To attach the Hugging Face Storage Bucket to Your Space:
+
+1. Open your Space on huggingface.co
+2. Go to **"Organization" → Your organization name → "+New" → "Bucket"**
+3. Once the bucket is created. Go to your Hugging Face Space, click **"Settings"**. Scroll down to **"Storage Buckets" → "Mount a bucket"**, select the existing bucket **`<org>/<space-name>-storage`** to mount it to your Space of Month path `/data`.
+4. "Mount bucket" — Hugging Face will mount the bucket at `/data` inside the Space container
+
+To Sync Your Local `./data` with the Space Bucket
+
+Place all persistent files under the `./data` folder of your project. The expected structure may look like this:
+
+```
+./data/
+├── chroma_db/          # Binary files and ChromaDB vector store
+│   └── chroma.sqlite3
+./train_data/           # Hackathon train datasets (will be mounted at /train_data in the project with a bucket from the Hackathon organizer)
+    ├── Automobile - Train/
+    ├── Climatique - Train/
+    └── ...
+```
+
+**Push local file in ./data to Hugging Face bucket:**
+```bash
+# Mirror ./data to the bucket — removes remote files deleted locally
+hf sync ./data hf://buckets/<org>/<space-name>-storage --delete
+
+# Sync only a specific sub-folder (e.g., the vector store)
+hf sync ./data/chroma_db hf://buckets/<org>/<space-name>-storage/chroma_db
+
+# Sync only specific file types
+hf sync ./data hf://buckets/<org>/<space-name>-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.
+
+**Download the Bucket to another Machine's `./data` folder:**
+
+To pull the latest bucket contents back to a local `./data` folder (e.g., on another team member's machine):
+
+```bash
+hf sync hf://buckets/<org>/<space-name>-storage ./data
+```
+
+### 6. Get Hackathon Train Datasets from the Organizer's Bucket
+
+The train datasets for this hackathon are stored in a separate read-only bucket. Sync them to a local `./train_data` folder to save your Hugging Face bucket storage (the train datasets is about 1GB).
+
+```bash
+# Download all training data to local folder train_data/ from the organizer's bucket hf://buckets/millimanfrance/Hackathon2026TrainData
+hf sync hf://buckets/millimanfrance/Hackathon2026TrainData ./train_data
+```
+
+> **Note:** `Hackathon2026TrainData` is a shared read-only bucket. Do not attempt to push to it.
+
+### 7. 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`. Here is an example of how to access the ChromaDB vector store and the environment file in your code:
+
+```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")
+ENV_FILE = str(DATA_DIR / ".env")
+```
+
+All persistent data — the vector store, sample documents, datasets — lives under `DATA_DIR` so a single `hf sync ./data ...` covers everything.
+
+
+## Application Configuration
+
+The application loads model configuration from **`./config.json`** (project root) 
+
+**NEVER put real credentials in the config file.** Use environment variables instead. The config file is meant for non-sensitive configuration parameters like model names, API endpoints, and other settings.
+
+### Step 1 — Configure `./config.json`
+
+Edit `./config.json` to different LLM and embedding models, or to add additional configuration parameters. The provided sample config is designed for Azure OpenAI REST API calls, but you can modify the structure and fields as needed for your implementation. Just make sure to update the code in `app.py` accordingly to read the new config format. The organizers will provide you with the Azure API key at the date of the hackathon, and two LLM models (**gpt-5-mini** & **gpt-5.1**) and embedding models (**text-embedding-3-large** & **text-embedding-3-small**) are available.
+
+```json
+{
+    "embedding": {
+        "endpoint_url": "https://hackathon-eiffel-2026-apim.azure-api.net/ai/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-12-01-preview",
+        "model": "text-embedding-3-small"
+    },
+    "llm": {
+        "endpoint_url": "https://hackathon-eiffel-2026-apim.azure-api.net/ai/openai/deployments/gpt-5.1/chat/completions?api-version=2024-12-01-preview",
+        "model": "gpt-5.1",
+        "max_completion_tokens": 512,
+        "temperature": 0.7,
+        "top_p": 0.95
+    }
+
+}
+```
+> **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 **MUST NOT** be 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** (Go to your Hugging Face Space, click **Settings → Variables and secrets → New secret → name it `AZURE_API_KEY`**).

README_HF.md

@@ -0,0 +1,172 @@
+# How to Push Code to a New HuggingFace Space
+
+## Prerequisites
+
+- [Git](https://git-scm.com/) installed
+- A [HuggingFace account](https://huggingface.co/join)
+- A HuggingFace Access Token (create one at [Settings > Tokens](https://huggingface.co/settings/tokens) with **Write** permission)
+
+---
+
+## Steps
+
+### 1. Create a New Space on HuggingFace
+
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Choose a **Space name** (e.g., `My_App`)
+3. Select the **SDK** (Gradio, Streamlit, Docker, or Static)
+4. Choose visibility (Public or Private)
+5. Click **Create Space**
+
+Your Space URL will be: `https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>`
+
+---
+
+### 2. Clone the Empty Space Locally
+
+```bash
+git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>
+cd <SPACE_NAME>
+```
+
+When prompted for credentials:
+- **Username:** Your HuggingFace username
+- **Password:** Your HuggingFace Access Token (NOT your account password)
+
+---
+
+### 3. Register Your Team
+Create a `team.yml` file at the **root** of your Hugging Face Space folder with your team name and members. This is required for hackathon participation and helps organizers identify your team during evaluation.
+
+```yaml
+display_name: Your Team Name
+members:
+  - name: Alice Chen, email: "alice@example.com"
+  - name: Bob Martin, email: "bob@example.com"
+```
+
+Create a `README.md` file at the **root** of your Hugging Face Space folder with a brief description of your app. This is required for Hugging Face Spaces and helps organizers understand your app during evaluation. Replace [Your Team Name] with your actual team name. Also note that the `app_file` field should match the name of your main application file (e.g., `app.py`).
+
+```markdown
+title: [Your Team Name]'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
+```
+
+---
+
+### 4. Add Codes
+
+#### Pull the sample code Example-App-Hackathon-Gustave-Eiffel-2026 into the Space
+
+To have a quick start, you can pull the sameple code Example-App-Hackathon-Gustave-Eiffel-2026 into your Space. You can do this by adding this repo as a second remote source and merging it into your Space:
+
+```bash
+# Inside your cloned Space folder:
+cd <SPACE_NAME>
+
+# Add the source repo as a second remote
+git remote add source https://huggingface.co/spaces/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026
+# or from GitHub:
+# git remote add source https://github.com/<OWNER>/<REPO>.git
+
+# Fetch all branches from the source
+git fetch source
+
+# Merge the source's main branch into your Space
+git merge source/main --allow-unrelated-histories -m "Pull code from source repo"
+```
+
+#### Add your code into the Space
+
+If you are working in a team, your teammate can simply copy/paste your code or files into the cloned Space folder.
+
+---
+
+#### Add a `.gitignore` to exclude unnecessary files:
+
+Put the following content in a `.gitignore` file at the root of your Space to avoid pushing large or sensitive files:
+```
+.venv
+__pycache__/
+**/__pycache__/
+*.sqlite3
+chroma_db/
+.env
+```
+
+---
+
+### 5. Commit and Push
+
+```bash
+git add .
+git commit -m "Initial commit"
+git push origin main
+git remote remove source (if you have added the sample code Example-App-Hackathon-Gustave-Eiffel-2026 as a second remote)
+```
+---
+
+
+### 6. Deploy to Hugging Face Spaces
+
+1. Once you have pushed the code, (IF NOT) Push this code to the Space repository.
+2. Add `AZURE_API_KEY` as a Space Secret (Settings → Secrets). Azure API key is a key to call the LLM APIs. The organizers will provide you one at the date of the hackathon.
+3. The Space automatically installs dependencies and starts the app.
+4. The hackathon will be a competition on the RAG (Retrieval-Augmented Generation) application you built. You are encouraged to learn the basics of RAG.
+---
+
+## Troubleshooting reference
+
+### Binary File Rejection
+
+HuggingFace rejects pushes containing binary files (e.g., `.sqlite3`, `.pkl`, `.bin`).
+
+**Fix:**
+
+1. Add the binary files to `.gitignore`
+2. Remove them from git tracking:
+   ```bash
+   git rm -r --cached path/to/binary/file
+   ```
+3. Squash history to purge them completely:
+   ```bash
+   git add -A
+   git reset --soft $(git rev-list --max-parents=0 HEAD)
+   git commit -m "Clean initial commit"
+   git push hfspace main --force
+   ```
+
+### Authentication Failed
+
+- HuggingFace does **not** accept account passwords for git. Use an **Access Token**.
+- Make sure the token has **Write** permission.
+- You can embed the token in the remote URL:
+  ```bash
+  git remote set-url hfspace https://<USERNAME>:<TOKEN>@huggingface.co/spaces/<USERNAME>/<SPACE_NAME>
+  ```
+
+### Wrong Branch Name
+
+Some repos use `master` instead of `main`. Check with:
+
+```bash
+git branch
+```
+
+Push to whichever branch your Space expects (usually `main`).
+
+---
+
+## Security Reminder
+
+- **Never** commit your HF token or API keys to the repo.
+- If a token is accidentally exposed, revoke it immediately at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) and generate a new one.
+- Use environment variables or HuggingFace Space **Secrets** (Settings > Variables and secrets) for sensitive values.

app.py

@@ -0,0 +1,598 @@
+"""
+RAG Chat API - Gustave Eiffel Hackathon 2026
+=============================================
+
+This application demonstrates a complete Retrieval-Augmented Generation (RAG) system
+deployed as a Hugging Face Space. It includes:
+
+1. /query endpoint - Called by the RAG evaluation system
+2. LLM API integration via Hugging Face Inference API
+3. Document embedding using sentence-transformers
+4. ChromaDB as the vector store (runs locally within HF Spaces)
+5. End-to-end RAG pipeline: ingest → embed → retrieve → generate
+
+Architecture:
+    User Query → Embedding → Vector Search → Context Retrieval → LLM Generation → Response
+"""
+
+import os
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Optional
+
+# Must be set before chromadb is imported so the module never registers its
+# posthog telemetry hook (workaround for posthog v3 API incompatibility).
+os.environ.setdefault("ANONYMIZED_TELEMETRY", "False")
+
+import requests as http_requests
+import gradio as gr
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+import chromadb
+from chromadb.config import Settings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from pypdf import PdfReader
+
+from llm import call_llm as call_llm_with_metrics
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Suppress non-fatal chromadb telemetry errors (posthog v3 API incompatibility)
+logging.getLogger("chromadb.telemetry.product.posthog").setLevel(logging.CRITICAL)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+# Resolve the data directory: /data when running inside HF Spaces (bucket mount),
+# ./data for local development.
+DATA_DIR = Path("/data") if Path("/data").is_dir() else Path("./data")
+
+CHROMA_PERSIST_DIR = str(DATA_DIR / "chroma_db")
+TRAIN_DOCS_DIR = Path("./train_data")
+COLLECTION_NAME = "rag_documents"
+CHUNK_SIZE = 512
+CHUNK_OVERLAP = 50
+TOP_K_RESULTS = 3
+
+# Settings loaded from data/config.json (runtime config).
+# Falls back to the root config.json which serves as the example/template.
+_CONFIG_PATH = DATA_DIR / "config.json"
+if not _CONFIG_PATH.exists():
+    _CONFIG_PATH = Path(__file__).parent / "config.json"
+    logger.warning(
+        f"No config.json found in {DATA_DIR} — falling back to root config.json (example file). "
+        "Copy config.json to the data directory and fill in your values for production use."
+    )
+with open(_CONFIG_PATH, encoding="utf-8") as _f:
+    _config = json.load(_f)
+
+# Embedding model (Azure OpenAI)
+EMBEDDING_ENDPOINT_URL = _config["embedding"]["endpoint_url"]
+EMBEDDING_MODEL_NAME = _config["embedding"]["model"]
+
+# LLM (Azure OpenAI)
+LLM_ENDPOINT_URL = _config["llm"]["endpoint_url"]
+LLM_MODEL_NAME = _config["llm"]["model"]
+LLM_MAX_TOKENS = _config["llm"].get("max_completion_tokens", 512)
+LLM_TEMPERATURE = _config["llm"].get("temperature", 0.7)
+LLM_TOP_P = _config["llm"].get("top_p", 0.95)
+
+# Azure API key from environment variable (shared by both LLM and embedding endpoints)
+AZURE_API_KEY = os.environ.get("AZURE_API_KEY")
+if not AZURE_API_KEY:
+    logger.warning("AZURE_API_KEY is not set — LLM and embedding calls will fail.")
+
+# Prompt template loaded from file so it can be edited without touching application code
+_PROMPT_TEMPLATE_PATH = Path(__file__).parent / "prompts" / "rag_prompt.txt"
+RAG_PROMPT_TEMPLATE = _PROMPT_TEMPLATE_PATH.read_text(encoding="utf-8")
+
+# ---------------------------------------------------------------------------
+# Step 1: Embedding via Azure OpenAI
+# ---------------------------------------------------------------------------
+# Embeddings are generated by calling the Azure OpenAI /embeddings endpoint.
+# No local model is loaded — the API handles all inference.
+
+logger.info(f"Embedding model configured: {EMBEDDING_MODEL_NAME} via Azure OpenAI")
+
+# ---------------------------------------------------------------------------
+# Step 2: Initialize the Vector Store (ChromaDB)
+# ---------------------------------------------------------------------------
+# ChromaDB runs in-process with persistent storage. This is ideal for HF Spaces
+# because it requires no external database service.
+
+logger.info(f"Initializing ChromaDB at: {CHROMA_PERSIST_DIR}")
+chroma_client = chromadb.PersistentClient(
+    path=CHROMA_PERSIST_DIR,
+    settings=Settings(anonymized_telemetry=False),
+)
+collection = chroma_client.get_or_create_collection(
+    name=COLLECTION_NAME,
+    metadata={"hnsw:space": "cosine"},
+)
+logger.info(f"ChromaDB collection '{COLLECTION_NAME}' ready. Documents: {collection.count()}")
+
+# ---------------------------------------------------------------------------
+# Step 3: LLM Configuration (Azure Foundry GPT-5)
+# ---------------------------------------------------------------------------
+# We call the Azure OpenAI-compatible endpoint directly via requests.
+# Endpoint URL and model are configured in config.json.
+
+logger.info(f"LLM configured: {LLM_MODEL_NAME} via {LLM_ENDPOINT_URL}")
+
+
+# ---------------------------------------------------------------------------
+# Helper Functions
+# ---------------------------------------------------------------------------
+
+def extract_text_from_pdf(pdf_path: Path) -> str:
+    """
+    Extract text content from a PDF file using pypdf.
+
+    This demonstrates how to convert PDF documents into plain text
+    for downstream embedding. Each page is extracted sequentially
+    and concatenated with page separators for traceability.
+    """
+    reader = PdfReader(str(pdf_path))
+    pages_text = []
+
+    for page_num, page in enumerate(reader.pages, start=1):
+        text = page.extract_text()
+        if text and text.strip():
+            pages_text.append(f"[Page {page_num}]\n{text.strip()}")
+
+    full_text = "\n\n".join(pages_text)
+    logger.info(f"Extracted {len(reader.pages)} pages from PDF: {pdf_path.name} ({len(full_text)} chars)")
+    return full_text
+
+
+def chunk_text(text: str, source: str = "unknown") -> list[dict]:
+    """
+    Split a document into smaller chunks for embedding.
+
+    We use LangChain's RecursiveCharacterTextSplitter which intelligently
+    splits on paragraph/sentence boundaries to preserve semantic meaning.
+    """
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ". ", " ", ""],
+    )
+    chunks = splitter.split_text(text)
+    return [{"text": chunk, "source": source, "chunk_index": i} for i, chunk in enumerate(chunks)]
+
+
+def generate_embeddings(texts: list[str]) -> list[list[float]]:
+    """
+    Generate vector embeddings via the Azure OpenAI /embeddings endpoint.
+
+    The endpoint, model name, and API key are loaded from config.json
+    and the AZURE_API_KEY environment variable.
+    """
+    headers = {
+        "api-key": AZURE_API_KEY,
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "input": texts,
+        "model": EMBEDDING_MODEL_NAME,
+    }
+    try:
+        resp = http_requests.post(
+            EMBEDDING_ENDPOINT_URL, headers=headers, json=payload, timeout=120,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return [item["embedding"] for item in data["data"]]
+    except http_requests.exceptions.HTTPError as e:
+        logger.error(f"Embedding API call failed: {e} — {resp.text}")
+        raise HTTPException(status_code=503, detail=f"Embedding service unavailable: {str(e)}")
+    except (http_requests.exceptions.JSONDecodeError, ValueError) as e:
+        logger.error(f"Embedding API returned non-JSON response (status {resp.status_code}): {repr(resp.text)}")
+        raise HTTPException(status_code=502, detail="Embedding service returned an invalid response")
+    except (KeyError, IndexError) as e:
+        logger.error(f"Unexpected embedding response format: {e} — body: {resp.text}")
+        raise HTTPException(status_code=502, detail="Unexpected response from embedding service")
+
+
+def add_documents_to_vectorstore(documents: list[dict]) -> int:
+    """
+    Save document embeddings to the ChromaDB vector store.
+
+    This demonstrates Step 2c: How to persist embeddings for retrieval.
+    Each document gets a unique ID, its embedding vector, the raw text,
+    and metadata (source file, chunk index).
+    """
+    if not documents:
+        return 0
+
+    texts = [doc["text"] for doc in documents]
+    embeddings = generate_embeddings(texts)
+
+    existing_count = collection.count()
+    ids = [f"doc_{existing_count + i}" for i in range(len(documents))]
+    metadatas = [{"source": doc["source"], "chunk_index": doc["chunk_index"]} for doc in documents]
+
+    collection.add(
+        ids=ids,
+        embeddings=embeddings,
+        documents=texts,
+        metadatas=metadatas,
+    )
+
+    logger.info(f"Added {len(documents)} chunks to vector store. Total: {collection.count()}")
+    return len(documents)
+
+
+def retrieve_relevant_context(query: str, top_k: int = TOP_K_RESULTS) -> list[dict]:
+    """
+    Retrieve the most relevant document chunks for a given query.
+
+    This is the "Retrieval" step in RAG:
+    1. Embed the user's query using the same embedding model
+    2. Search the vector store for the nearest neighbors
+    3. Return the top-k most similar chunks as context
+    """
+    if collection.count() == 0:
+        return []
+
+    query_embedding = generate_embeddings([query])[0]
+
+    results = collection.query(
+        query_embeddings=[query_embedding],
+        n_results=min(top_k, collection.count()),
+        include=["documents", "metadatas", "distances"],
+    )
+
+    contexts = []
+    for i in range(len(results["documents"][0])):
+        contexts.append({
+            "text": results["documents"][0][i],
+            "source": results["metadatas"][0][i]["source"],
+            "similarity_score": 1 - results["distances"][0][i],
+        })
+
+    return contexts
+
+
+def build_rag_prompt(query: str, contexts: list[dict]) -> str:
+    """
+    Construct the RAG prompt by combining retrieved context with the user question.
+
+    The prompt template instructs the LLM to:
+    - Answer based ONLY on the provided context
+    - Acknowledge when information is insufficient
+    - Cite sources when possible
+    """
+    context_text = "\n\n".join(
+        f"[Source: {ctx['source']}]\n{ctx['text']}" for ctx in contexts
+    )
+
+    prompt = RAG_PROMPT_TEMPLATE.format(context=context_text, question=query)
+    return prompt
+
+
+def rag_query(query: str, top_k: int = TOP_K_RESULTS) -> dict:
+    """
+    End-to-end RAG pipeline: Query → Retrieve → Generate.
+
+    This demonstrates Step 2d: How to make a RAG system end-to-end.
+
+    Pipeline steps:
+    1. Receive user query
+    2. Retrieve relevant context from vector store
+    3. Build augmented prompt with context
+    4. Call LLM to generate answer
+    5. Return answer with source metadata, explanation, token count, and timing
+    """
+    start_time = time.perf_counter()
+
+    # Step 1: Retrieve relevant document chunks
+    contexts = retrieve_relevant_context(query, top_k=top_k)
+
+    if not contexts:
+        elapsed_ms = round((time.perf_counter() - start_time) * 1000, 2)
+        return {
+            "answer": "No documents have been ingested yet. Please upload documents first.",
+            "sources": [],
+            "explanation": "No documents found in the vector store to retrieve context from.",
+            "total_token": 0,
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "cached_tokens": 0,
+            "co2_grams": None,
+            "energy_kwh": None,
+            "run_time_in_ms": elapsed_ms,
+        }
+
+    # Step 2: Build the augmented prompt
+    prompt = build_rag_prompt(query, contexts)
+
+    # Step 3: Generate answer from LLM (with token + CO2 metrics)
+    llm_result = call_llm_with_metrics(
+        prompt,
+        endpoint_url=LLM_ENDPOINT_URL,
+        api_key=AZURE_API_KEY,
+        model=LLM_MODEL_NAME,
+        max_completion_tokens=LLM_MAX_TOKENS,
+        temperature=LLM_TEMPERATURE,
+        top_p=LLM_TOP_P,
+    )
+    raw_content = llm_result["content"]
+    tokens = llm_result["tokens"]
+    total_token = tokens["total"]
+
+    # Parse structured JSON response from LLM (handle markdown code fences)
+    json_str = raw_content.strip()
+    if json_str.startswith("```"):
+        json_str = json_str.split("\n", 1)[-1]
+        json_str = json_str.rsplit("```", 1)[0].strip()
+
+    try:
+        parsed = json.loads(json_str)
+        answer = parsed["answer"]
+        explanation = parsed["explanation"]
+    except (json.JSONDecodeError, KeyError):
+        answer = raw_content
+        explanation = "LLM did not return a structured explanation."
+
+    elapsed_ms = round((time.perf_counter() - start_time) * 1000, 2)
+
+    # Step 4: Return structured response
+    return {
+        "answer": answer,
+        "sources": [{"source": ctx["source"], "score": ctx["similarity_score"], "ref_text": ctx["text"]} for ctx in contexts],
+        "explanation": explanation,
+        "total_token": total_token,
+        "prompt_tokens": tokens["prompt"],
+        "completion_tokens": tokens["completion"],
+        "cached_tokens": tokens["cached"],
+        "co2_grams": llm_result["co2_grams"],
+        "energy_kwh": llm_result["energy_kwh"],
+        "run_time_in_ms": elapsed_ms,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Step 4: Ingest Train Documents (on-demand)
+# ---------------------------------------------------------------------------
+
+
+def ingest_train_documents():
+    """Load and embed training documents into the vector store."""
+    if collection.count() > 0:
+        logger.info("Vector store already has documents, skipping ingestion.")
+        return
+
+    if not TRAIN_DOCS_DIR.exists():
+        logger.warning(f"No train_data directory found at: {TRAIN_DOCS_DIR}")
+        return
+
+    # Ingest plain text files (recursively in subdirectories)
+    for file_path in TRAIN_DOCS_DIR.rglob("*.txt"):
+        logger.info(f"Ingesting text file: {file_path.name}")
+        text = file_path.read_text(encoding="utf-8")
+        chunks = chunk_text(text, source=file_path.name)
+        add_documents_to_vectorstore(chunks)
+
+    # Ingest PDF files (recursively in subdirectories)
+    for file_path in TRAIN_DOCS_DIR.rglob("*.pdf"):
+        logger.info(f"Ingesting PDF file: {file_path.name}")
+        text = extract_text_from_pdf(file_path)
+        if text.strip():
+            chunks = chunk_text(text, source=file_path.name)
+            add_documents_to_vectorstore(chunks)
+        else:
+            logger.warning(f"No extractable text found in: {file_path.name}")
+
+    logger.info(f"Train document ingestion complete. Total chunks: {collection.count()}")
+
+
+# ---------------------------------------------------------------------------
+# Step 5: FastAPI Application with /query Endpoint
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="RAG Chat API - Gustave Eiffel Hackathon 2026",
+    description="A RAG system with /query endpoint for evaluation",
+    version="1.0.0",
+)
+
+
+class QueryRequest(BaseModel):
+    """Request schema for the /query endpoint."""
+    query: str
+    top_k: Optional[int] = TOP_K_RESULTS
+
+
+class IngestRequest(BaseModel):
+    """Request schema for the /ingest endpoint."""
+    text: str
+    source: str = "user_upload"
+
+
+@app.post("/query")
+async def query_endpoint(request: QueryRequest):
+    """
+    RAG Query Endpoint - Called by the evaluation system.
+
+    Accepts a user query, retrieves relevant context from the vector store,
+    and generates an answer using the LLM.
+
+    Request body:
+        - query (str): The user's question
+        - top_k (int, optional): Number of context chunks to retrieve (default: 3)
+
+    Returns:
+        - answer (str): The generated answer
+        - sources (list): Source documents used for context
+        - explanation (str): Explanation of the retrieval and answer logic
+        - total_token (int): Total token count from the LLM call
+        - prompt_tokens (int): Prompt token count
+        - completion_tokens (int): Completion token count
+        - cached_tokens (int): Cached prompt tokens (when reported by provider)
+        - co2_grams (float | None): Estimated CO2 emission in grams (via ecologits)
+        - energy_kwh (float | None): Estimated energy use in kWh (via ecologits)
+        - run_time_in_ms (float): Pipeline execution time in milliseconds
+    """
+    logger.info(f"Query received: {request.query}")
+    result = rag_query(request.query, top_k=request.top_k)
+    return JSONResponse(content=result)
+
+
+@app.post("/ingest")
+async def ingest_endpoint(request: IngestRequest):
+    """
+    Document Ingestion Endpoint.
+
+    Accepts raw text, chunks it, generates embeddings, and stores in the vector store.
+
+    Request body:
+        - text (str): The document text to ingest
+        - source (str, optional): Source identifier for the document
+    """
+    chunks = chunk_text(request.text, source=request.source)
+    count = add_documents_to_vectorstore(chunks)
+    return JSONResponse(content={
+        "status": "success",
+        "chunks_added": count,
+        "total_chunks": collection.count(),
+    })
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint for monitoring."""
+    return {
+        "status": "healthy",
+        "documents_in_store": collection.count(),
+        "embedding_model": EMBEDDING_MODEL_NAME,
+        "llm_model": LLM_MODEL_NAME,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Step 6: Gradio UI for Interactive Demo
+# ---------------------------------------------------------------------------
+
+def gradio_query(question: str) -> tuple[str, str, str, str, str]:
+    """Handle queries from the Gradio chat interface."""
+    if not question.strip():
+        return "Please enter a question.", "", "", "", ""
+    result = rag_query(question)
+    sources_text = "\n".join(
+        f"  - {s['source']} (relevance: {s['score']:.2f})" for s in result["sources"]
+    )
+    answer = f"{result['answer']}\n\n📚 Sources:\n{sources_text}" if result["sources"] else result["answer"]
+    explanation = result.get("explanation", "")
+    token_info = str(result.get("total_token", 0))
+    co2_value = result.get("co2_grams")
+    co2_info = f"{co2_value:.4f} g" if isinstance(co2_value, (int, float)) else "N/A"
+    run_time = f"{result.get('run_time_in_ms', 0)} ms"
+    return answer, explanation, token_info, co2_info, run_time
+
+
+def gradio_ingest(text: str, source_name: str) -> str:
+    """Handle document ingestion from the Gradio UI."""
+    if not text.strip():
+        return "Please provide text to ingest."
+    chunks = chunk_text(text, source=source_name or "user_upload")
+    count = add_documents_to_vectorstore(chunks)
+    return f"✅ Ingested {count} chunks. Total documents in store: {collection.count()}"
+
+
+with gr.Blocks(title="RAG Chat API - Gustave Eiffel Hackathon") as demo:
+    gr.Markdown("""
+    # 🗼 RAG Chat API - Gustave Eiffel Hackathon 2026
+
+    This application demonstrates a complete **Retrieval-Augmented Generation (RAG)** system.
+
+    **API Endpoint:** Use `POST /query` with `{"query": "your question"}` for programmatic access.
+
+    ---
+    """)
+
+    with gr.Tab("💬 Chat"):
+        gr.Markdown("Ask questions about the ingested documents.")
+        with gr.Row():
+            query_input = gr.Textbox(
+                label="Your Question",
+                placeholder="e.g., What is the Eiffel Tower made of?",
+                lines=2,
+            )
+        query_button = gr.Button("Ask", variant="primary")
+        query_output = gr.Textbox(label="Answer", lines=8, interactive=False)
+        query_explanation = gr.Textbox(label="Explanation", lines=3, interactive=False)
+        with gr.Row():
+            query_tokens = gr.Textbox(label="Total Tokens", interactive=False)
+            query_co2 = gr.Textbox(label="CO2 Emission", interactive=False)
+            query_runtime = gr.Textbox(label="Run Time", interactive=False)
+        query_button.click(
+            fn=gradio_query,
+            inputs=query_input,
+            outputs=[query_output, query_explanation, query_tokens, query_co2, query_runtime],
+        )
+
+    with gr.Tab("📄 Ingest Documents"):
+        gr.Markdown("Add new documents to the knowledge base.")
+        doc_text = gr.Textbox(
+            label="Document Text",
+            placeholder="Paste your document text here...",
+            lines=10,
+        )
+        doc_source = gr.Textbox(
+            label="Source Name",
+            placeholder="e.g., my_document.txt",
+            value="user_upload",
+        )
+        ingest_button = gr.Button("Ingest Document", variant="primary")
+        ingest_output = gr.Textbox(label="Status", interactive=False)
+        ingest_button.click(fn=gradio_ingest, inputs=[doc_text, doc_source], outputs=ingest_output)
+
+    with gr.Tab("ℹ️ API Info"):
+        gr.Markdown("""
+        ## API Endpoints
+
+        ### POST /query
+        ```json
+        {
+            "query": "What is the Eiffel Tower?",
+            "top_k": 3
+        }
+        ```
+
+        **Response:**
+        ```json
+        {
+            "answer": "The Eiffel Tower is...",
+            "sources": [{"source": "eiffel_tower.txt", "score": 0.85}],
+            "query": "What is the Eiffel Tower?"
+        }
+        ```
+
+        ### POST /ingest
+        ```json
+        {
+            "text": "Your document text here...",
+            "source": "document_name.txt"
+        }
+        ```
+
+        ### GET /health
+        Returns system health and document count.
+        """)
+
+# Mount Gradio onto FastAPI so both the UI and API endpoints are served
+app = gr.mount_gradio_app(app, demo, path="/")
+
+# ---------------------------------------------------------------------------
+# Entry Point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

config.json

@@ -0,0 +1,14 @@
+{
+    "embedding": {
+        "endpoint_url": "https://hackathon-eiffel-2026-apim.azure-api.net/ai/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-12-01-preview",
+        "model": "text-embedding-3-small"
+    },
+    "llm": {
+        "endpoint_url": "https://hackathon-eiffel-2026-apim.azure-api.net/ai/openai/deployments/gpt-5.1/chat/completions?api-version=2024-12-01-preview",
+        "model": "gpt-5.1",
+        "max_completion_tokens": 512,
+        "temperature": 0.7,
+        "top_p": 0.95
+    }
+
+}

ingest_train_data.py

@@ -0,0 +1,197 @@
+"""
+Ingest Training Data Script
+============================
+
+Standalone script to convert all documents in ./train_data into embeddings
+and store them in the ChromaDB vector store.
+
+Usage:
+    python ingest_train_data.py
+
+Requires:
+    - AZURE_API_KEY environment variable set
+    - data/config.json (or root config.json as fallback) with endpoint URLs
+    - Documents (PDF/TXT) in ./train_data/<category>/
+"""
+
+import os
+import sys
+import json
+import logging
+import time
+from pathlib import Path
+
+os.environ.setdefault("ANONYMIZED_TELEMETRY", "False")
+
+import requests as http_requests
+import chromadb
+from chromadb.config import Settings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from pypdf import PdfReader
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+PROJECT_ROOT = Path(__file__).parent
+DATA_DIR = Path("/data") if Path("/data").is_dir() else PROJECT_ROOT / "data"
+TRAIN_DATA_DIR = Path("/train_data") if Path("/train_data").is_dir() else PROJECT_ROOT / "train_data"
+
+CHROMA_PERSIST_DIR = str(DATA_DIR / "chroma_db")
+COLLECTION_NAME = "rag_documents"
+CHUNK_SIZE = 512
+CHUNK_OVERLAP = 50
+EMBEDDING_BATCH_SIZE = 16
+
+_CONFIG_PATH = DATA_DIR / "config.json"
+if not _CONFIG_PATH.exists():
+    _CONFIG_PATH = PROJECT_ROOT / "config.json"
+    logger.warning(f"No config.json in {DATA_DIR} — using root config.json as fallback.")
+
+with open(_CONFIG_PATH, encoding="utf-8") as _f:
+    _config = json.load(_f)
+
+EMBEDDING_ENDPOINT_URL = _config["embedding"]["endpoint_url"]
+EMBEDDING_MODEL_NAME = _config["embedding"]["model"]
+
+AZURE_API_KEY = os.environ.get("AZURE_API_KEY")
+if not AZURE_API_KEY:
+    logger.error("AZURE_API_KEY is not set. Export it before running this script.")
+    sys.exit(1)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def extract_text_from_pdf(pdf_path: Path) -> str:
+    reader = PdfReader(str(pdf_path))
+    pages_text = []
+    for page_num, page in enumerate(reader.pages, start=1):
+        text = page.extract_text()
+        if text and text.strip():
+            pages_text.append(f"[Page {page_num}]\n{text.strip()}")
+    return "\n\n".join(pages_text)
+
+
+def chunk_text(text: str, source: str) -> list[dict]:
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ". ", " ", ""],
+    )
+    chunks = splitter.split_text(text)
+    return [{"text": chunk, "source": source, "chunk_index": i} for i, chunk in enumerate(chunks)]
+
+
+def generate_embeddings(texts: list[str]) -> list[list[float]]:
+    headers = {"api-key": AZURE_API_KEY, "Content-Type": "application/json"}
+    payload = {"input": texts, "model": EMBEDDING_MODEL_NAME}
+    resp = http_requests.post(EMBEDDING_ENDPOINT_URL, headers=headers, json=payload, timeout=120)
+    resp.raise_for_status()
+    data = resp.json()
+    return [item["embedding"] for item in data["data"]]
+
+
+def generate_embeddings_batched(texts: list[str]) -> list[list[float]]:
+    all_embeddings = []
+    for i in range(0, len(texts), EMBEDDING_BATCH_SIZE):
+        batch = texts[i:i + EMBEDDING_BATCH_SIZE]
+        logger.info(f"  Embedding batch {i // EMBEDDING_BATCH_SIZE + 1} ({len(batch)} chunks)...")
+        embeddings = generate_embeddings(batch)
+        all_embeddings.extend(embeddings)
+        time.sleep(0.5)  # Rate-limit courtesy
+    return all_embeddings
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main():
+    if not TRAIN_DATA_DIR.exists():
+        logger.error(f"Training data directory not found: {TRAIN_DATA_DIR}")
+        sys.exit(1)
+
+    logger.info(f"Training data directory: {TRAIN_DATA_DIR}")
+    logger.info(f"ChromaDB path: {CHROMA_PERSIST_DIR}")
+    logger.info(f"Embedding model: {EMBEDDING_MODEL_NAME}")
+
+    chroma_client = chromadb.PersistentClient(
+        path=CHROMA_PERSIST_DIR,
+        settings=Settings(anonymized_telemetry=False),
+    )
+    collection = chroma_client.get_or_create_collection(
+        name=COLLECTION_NAME,
+        metadata={"hnsw:space": "cosine"},
+    )
+    logger.info(f"ChromaDB collection '{COLLECTION_NAME}' — existing documents: {collection.count()}")
+
+    # Gather all PDF and TXT files recursively
+    files = sorted(
+        list(TRAIN_DATA_DIR.rglob("*.pdf")) + list(TRAIN_DATA_DIR.rglob("*.txt"))
+    )
+    logger.info(f"Found {len(files)} files to process.")
+
+    total_chunks_added = 0
+
+    for idx, file_path in enumerate(files, start=1):
+        relative = file_path.relative_to(TRAIN_DATA_DIR)
+        # Use category/filename as the source identifier
+        source = str(relative)
+        logger.info(f"[{idx}/{len(files)}] Processing: {source}")
+
+        try:
+            if file_path.suffix.lower() == ".pdf":
+                text = extract_text_from_pdf(file_path)
+            else:
+                text = file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logger.warning(f"  Skipped (read error): {e}")
+            continue
+
+        if not text.strip():
+            logger.warning(f"  Skipped (no extractable text)")
+            continue
+
+        chunks = chunk_text(text, source=source)
+        if not chunks:
+            logger.warning(f"  Skipped (no chunks produced)")
+            continue
+
+        logger.info(f"  {len(chunks)} chunks extracted")
+
+        texts = [c["text"] for c in chunks]
+        try:
+            embeddings = generate_embeddings_batched(texts)
+        except http_requests.exceptions.HTTPError as e:
+            logger.error(f"  Embedding failed: {e}")
+            continue
+        except Exception as e:
+            logger.error(f"  Unexpected embedding error: {e}")
+            continue
+
+        existing_count = collection.count()
+        ids = [f"doc_{existing_count + i}" for i in range(len(chunks))]
+        metadatas = [{"source": c["source"], "chunk_index": c["chunk_index"]} for c in chunks]
+
+        collection.add(
+            ids=ids,
+            embeddings=embeddings,
+            documents=texts,
+            metadatas=metadatas,
+        )
+        total_chunks_added += len(chunks)
+        logger.info(f"  Added {len(chunks)} chunks (total in store: {collection.count()})")
+
+    logger.info("=" * 60)
+    logger.info(f"Ingestion complete. Chunks added this run: {total_chunks_added}")
+    logger.info(f"Total documents in vector store: {collection.count()}")
+
+
+if __name__ == "__main__":
+    main()

llm.py

@@ -0,0 +1,152 @@
+"""
+LLM wrapper with token accounting and CO2 emission estimation.
+
+Wraps an Azure OpenAI-compatible chat/completions call and returns:
+- content: the generated text
+- tokens: prompt / completion / cached / total
+- energy_kwh, co2_grams: environmental impact for the call
+
+CO2 emissions are estimated with `ecologits`, which uses a model registry
+(parameter counts, hardware assumptions) plus output token count and request
+latency to compute global warming potential (kgCO2eq) and energy (kWh).
+We chose `ecologits` over `codecarbon` because the LLM runs on a remote
+endpoint — `codecarbon` measures local process energy and would only count
+the client overhead, not the inference itself.
+"""
+
+import logging
+import time
+from typing import Optional
+
+import requests
+from fastapi import HTTPException
+
+logger = logging.getLogger(__name__)
+
+try:
+    from ecologits.tracers.utils import llm_impacts
+    _ECOLOGITS_AVAILABLE = True
+except ImportError:
+    _ECOLOGITS_AVAILABLE = False
+    logger.warning("ecologits not installed — CO2 emission will be reported as None.")
+
+
+def _to_scalar(value) -> Optional[float]:
+    """
+    Normalize an ecologits impact value to a single float.
+
+    ecologits returns either a plain float or a RangeValue(min, max) depending
+    on the model registry entry. For RangeValue we return the midpoint so a
+    single representative number flows through the API/UI.
+    """
+    if value is None:
+        return None
+    if hasattr(value, "min") and hasattr(value, "max"):
+        return (float(value.min) + float(value.max)) / 2.0
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def call_llm(
+    prompt: str,
+    *,
+    endpoint_url: str,
+    api_key: str,
+    model: str,
+    max_completion_tokens: int = 512,
+    temperature: float = 0.7,
+    top_p: float = 0.95,
+    provider: str = "openai",
+    timeout: Optional[float] = None,
+) -> dict:
+    """
+    Call an Azure OpenAI-compatible chat/completions endpoint and return the
+    response together with token counts and CO2 emission estimate.
+
+    Returns a dict:
+        {
+            "content": str,
+            "tokens": {
+                "prompt": int,
+                "completion": int,
+                "cached": int,
+                "total": int,
+            },
+            "energy_kwh": float | None,
+            "co2_grams": float | None,
+            "latency_s": float,
+        }
+    """
+    headers = {
+        "api-key": api_key,
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "model": model,
+        "messages": [{"role": "user", "content": prompt}],
+        "max_completion_tokens": max_completion_tokens,
+        "temperature": temperature,
+        "top_p": top_p,
+    }
+
+    start = time.perf_counter()
+    try:
+        resp = requests.post(endpoint_url, headers=headers, json=payload, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+    except requests.exceptions.HTTPError as e:
+        logger.error(f"LLM API call failed: {e} — {resp.text}")
+        raise HTTPException(status_code=503, detail=f"LLM service unavailable: {str(e)}")
+    except (requests.exceptions.JSONDecodeError, ValueError):
+        logger.error(
+            f"LLM API returned non-JSON response (status {resp.status_code}): {repr(resp.text)}"
+        )
+        raise HTTPException(status_code=502, detail="LLM service returned an invalid response")
+    latency_s = time.perf_counter() - start
+
+    try:
+        content = data["choices"][0]["message"]["content"].strip()
+    except (KeyError, IndexError) as e:
+        logger.error(f"Unexpected LLM response format: {e} — body: {data!r}")
+        raise HTTPException(status_code=502, detail="Unexpected response from LLM service")
+
+    usage = data.get("usage") or {}
+    prompt_tokens = usage.get("prompt_tokens", 0)
+    completion_tokens = usage.get("completion_tokens", 0)
+    total_tokens = usage.get("total_tokens", prompt_tokens + completion_tokens)
+
+    prompt_details = usage.get("prompt_tokens_details") or {}
+    cached_tokens = prompt_details.get("cached_tokens", usage.get("cached_tokens", 0))
+
+    energy_kwh: Optional[float] = None
+    co2_grams: Optional[float] = None
+    if _ECOLOGITS_AVAILABLE:
+        try:
+            impacts = llm_impacts(
+                provider=provider,
+                model_name=model,
+                output_token_count=completion_tokens,
+                request_latency=latency_s,
+            )
+            if impacts is not None:
+                energy_kwh = _to_scalar(impacts.energy.value)
+                # ecologits returns gwp in kgCO2eq; convert to grams
+                gwp_kg = _to_scalar(impacts.gwp.value)
+                co2_grams = gwp_kg * 1000.0 if gwp_kg is not None else None
+        except Exception as e:
+            logger.warning(f"ecologits impact calc failed for model={model}: {e}")
+
+    return {
+        "content": content,
+        "tokens": {
+            "prompt": prompt_tokens,
+            "completion": completion_tokens,
+            "cached": cached_tokens,
+            "total": total_tokens,
+        },
+        "energy_kwh": energy_kwh,
+        "co2_grams": co2_grams,
+        "latency_s": latency_s,
+    }

prompts/rag_prompt.txt

@@ -0,0 +1,15 @@
+You are a helpful assistant. Answer the user's question based ONLY on the provided context.
+If the context does not contain enough information to answer, say "I don't have enough information to answer this question."
+Always be concise and factual.
+
+You MUST respond in valid JSON with exactly two fields:
+- "answer": your concise factual answer to the question
+- "explanation": a brief explanation of your reasoning, describing which parts of the context you used and why they led to your answer
+
+Do NOT include any text outside the JSON object.
+
+Context:
+{context}
+
+Question: {question}
+

requirements.txt

@@ -0,0 +1,15 @@
+fastapi==0.115.0
+uvicorn==0.30.0
+gradio==4.44.1
+chromadb==0.5.0
+huggingface-hub==0.25.0
+langchain==0.3.0
+langchain-community==0.3.0
+langchain-huggingface==0.1.0
+langchain-chroma==0.2.0
+langchain-text-splitters==0.3.0
+pypdf==4.3.0
+python-multipart==0.0.9
+pydantic==2.9.0
+requests>=2.31.0
+ecologits>=0.5.0

team.yml

@@ -0,0 +1,12 @@
+display_name: "Team Baseline"
+members:
+  - name: "Member One"
+    email: "quincy.hsieh@example.com"
+  - name: "Member Two"
+    email: "muhammad.umer@example.com"
+  - name: "Member Three"
+    email: "francois.hu@@example.com"
+  - name: "Member Four"
+    email: "chloe.rolland@@example.com"
+  - name: "Member Five"
+    email: "bertille.tierny@@example.com"