How spidey13/stratsim works
Project Type and Purpose
• This is a full‐stack, multi‐agent simulation platform for F1 race strategy analysis.
• It integrates a data pipeline (ingest, process, validate historical race data), machine learning model training/serving, a orchestrator that runs the simulation loop via specialized agents, an interactive Streamlit web UI (and optional FastAPI endpoints), plus experiment tracking (MLflow) and containerized deployment (Docker).
Main Components
a. External Data Sources
• FastF1 API (historical race, telemetry, weather)
• OpenWeather API (optional live weather)
b. Data Pipeline Layer (src/data_pipeline)
• Collector (fastf1_collector, weather_collector)
• Processor / Preprocessor / Validator modules
• Data storage: raw cache, processed CSVs, validation reports
c. Model Training & Experiment Tracking
• Training scripts (notebooks & scripts/model_training)
• CatBoost / ML models stored under models/ and catboost_info/
• MLflow server (mlruns/ or via docker‐compose)
d. Core Simulation Orchestrator
• RaceSimulator (src/orchestrator/simulation_loop.py)
• Multi-agent subsystem (src/agents):
• BaseAgent, TireManagerAgent (and sub-agents), StrategyAgent,
LapTimeAgent, WeatherAgent, VehicleDynamicsAgent, GapEffectsAgent
e. API Layer (src/api/endpoints.py)
• Exposes simulation control or data retrieval (if deployed beyond Streamlit)
f. Web Interface (web/)
• Streamlit app (web/streamlit_app.py) – user configuration, live visualization
• Optional FastAPI app (web/app.py) for REST endpoints
g. Infrastructure & Deployment
• Dockerfile, docker-compose.yml (app, MLflow)
• .devcontainer for VSCode containerized dev
h. Configuration & Utilities
• src/config (settings, simulation_config)
• src/utils helpers, run_mlflow_ui
Relationships and Data Flow
• External Data → Data Pipeline Collector → Processor → Validated / Enhanced Data → Stored in data/processed.
• Processed Data → Model Training (scripts + notebooks) → Trained Models → models/
• Trained Models & Configs → Agents (loaded at runtime by orchestrator).
• Orchestrator (RaceSimulator) invokes each agent in sequence per lap, consuming model outputs and simulation state → Produces race history/results.
• Results → Web UI (Streamlit) via direct function calls or REST API.
• MLflow tracks training runs—accessible via separate UI container.
• Docker Compose wires together the Streamlit app container + MLflow server (and potentially a backend API).
Architectural Patterns and Principles
• Layered Architecture:
• Ingestion/ETL (data_pipeline)
• Business Logic / Simulation (orchestrator + agents)
• Presentation / API (web/ + src/api)
• Modular, Plug-in Agents (Strategy, Tire, Weather, etc.) adhering to BaseAgent interface → supports extensibility.
• Separation of Concerns: Data, Models, Simulation, UI, Config isolated in dedicated directories.
• Containerized Deployment for consistency across environments.