F1 Telemetry & Analytics API Engine

Real-time F1 telemetry pipeline with integrated RAG engine — streams live vehicle and driver data via WebSockets, evaluates regulatory compliance using ChromaDB vector search, and injects live telemetry context alongside F1 technical regulation documents directly into an LLM prompt for real-time boundary analysis.

🚀 Key Features

• Live Ingestion Infrastructure: Integrates with the open-source OpenF1 API to capture vehicle dynamics sampled at ~3.7 Hz.
• Performance Caching Layer: Implements an in-memory caching mechanism with Time-To-Live (TTL) expiration to bypass upstream network bottlenecks and prevent API throttling.
• Real-Time WebSocket Broadcasting: Streams parsed telemetry state to connected clients via WebSockets, enabling live reactive frontend updates with sub-second latency.
• RAG Compliance Engine: Parses and chunks F1 technical regulation documents into a ChromaDB vector store. At query time, retrieves the most semantically relevant regulation excerpts and injects them alongside live telemetry buffer data directly into an LLM prompt context for real-time boundary evaluation (e.g. energy deployment limits, throttle shaping constraints).
• Self-Documenting REST API: Utilizes FastAPI and Pydantic for automated OpenAPI specification mapping and real-time parameter validation.

🛠️ System Architecture

OpenF1 API
    |
    v
Polling Loop (Go / Python)
    |
    v
Telemetry Processing Module
(slice, normalize, buffer)
    |
    +------------------+
    |                  |
    v                  v
In-Memory Cache    WebSocket Layer
(TTL, <2ms)        (live broadcast)
                       |
                       v
                  Frontend Dashboard
                  (Vue.js reactive UI)

ChromaDB Vector Store
(F1 regulation documents)
    |
    v
RAG Query Endpoint
(telemetry context + regulation chunks -> LLM prompt)
    |
    v
LLM Compliance Response

• FastAPI / Uvicorn: High-concurrency ASGI web framework handling asynchronous data routing.
• In-Memory Store: Tracks cache state and invalidation logic to reduce system response times to under 2ms.
• Telemetry Processing Module: Slices, reverses, and normalizes high-frequency raw arrays into optimized payloads.
• ChromaDB: Local vector database storing embedded chunks of F1 technical regulation documents for semantic retrieval.
• RAG Pipeline: Retrieval-Augmented Generation layer that fetches regulation context relevant to live telemetry readings and passes both to an LLM for compliance analysis.
• WebSocket Server: Pushes telemetry state to connected clients in real time, decoupling data ingestion from frontend rendering.

📦 Tech Stack

Layer	Technology
Language	Python 3.11+, Go
API Framework	FastAPI
Server	Uvicorn (ASGI)
Real-Time Transport	WebSockets
Vector Database	ChromaDB
Embeddings	HuggingFace Sentence Transformers
LLM Integration	OpenAI API / local LLM
Data Source	OpenF1 API
Frontend	Vue.js
Environment	Python venv

🔧 Installation & Local Setup

1. Prerequisites

• Python 3.11+
• pip
• Go 1.21+ (for the WebSocket/polling layer)
• Git

2. Initialize Environment & Install Dependencies

# Clone the repository
git clone https://github.com/sahasan95/f1-telemetry-api.git
cd f1-telemetry-api

# Create and activate virtual environment
python -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install locked dependencies
pip install -r requirements.txt

3. Run the API Server

uvicorn app.main:app --reload

The API will be available at http://localhost:8000

Interactive API docs at http://localhost:8000/docs

4. Run the RAG Engine

# Ingest regulation documents into ChromaDB
python app/rag/ingest.py

# Query the compliance endpoint
curl -X POST http://localhost:8000/rag/query \
  -H "Content-Type: application/json" \
  -d '{"question": "Is the current energy deployment within FIA limits?"}'

📡 API Endpoints

Method	Endpoint	Description
GET	/telemetry/live	Latest cached telemetry snapshot
GET	/telemetry/car/{driver}	Per-driver car data
WS	/ws/telemetry	WebSocket stream for live updates
POST	/rag/query	Submit telemetry-aware compliance query to LLM
GET	/health	Service health check

🧠 RAG Pipeline — How It Works

1. Ingestion: F1 technical regulation PDFs are parsed, chunked, and embedded using HuggingFace Sentence Transformers, then stored in a local ChromaDB collection.
2. Retrieval: On query, the most semantically relevant regulation chunks are retrieved via cosine similarity search against the query embedding.
3. Context Injection: The retrieved regulation text is combined with the current live telemetry buffer (throttle, ERS deployment, speed, gear, DRS state) into a structured LLM prompt.
4. Analysis: The LLM evaluates whether the live telemetry readings fall within the boundaries defined by the retrieved regulations and returns a compliance verdict with reasoning.

📊 Example Use Case

"Is the driver's current ERS deployment rate within the limits defined in Article 5.4 of the FIA Technical Regulations?"

The RAG endpoint retrieves the relevant Article 5.4 chunks, injects the current ERS telemetry readings, and returns an LLM-generated compliance analysis in real time.

🤝 Contributing

Pull requests are welcome. For significant changes, open an issue first to discuss what you would like to change.

📄 License

MIT