6 Developer - VforVitorio/F1_Strat_Manager GitHub Wiki
👨💻 Developer Guide
Development environment, utilities, and deployment instructions
# Data Processing Utilities
DeepWiki
VforVitorio/F1_Strat_Manager
Get free private DeepWikis with
Devin
Share
Last indexed: 13 June 2025 (0638ba)
Overview
System Architecture
Installation and Setup
Documentation Workflow
Streamlit Dashboard
Strategy Recommendations View
Gap Analysis View
Radio Analysis View
Time Predictions View
Strategy Chat Interface
Machine Learning Models
Lap Time Prediction
Tire Degradation Modeling
Vision-based Gap Calculation
NLP Pipeline
Radio Transcription
Sentiment and Intent Analysis
Named Entity Recognition
Integrated NLP Pipeline
Expert System
Facts and Data Transformation
Degradation Rules
Gap Analysis Rules
Radio Message Rules
Integrated Rule Engine
Developer Guide
Data Processing Utilities
Model Artifacts and Deployment
Development Environment
Data Processing Utilities Relevant source files
This document covers the core data processing utilities that transform raw F1 race data into structured formats suitable for machine learning models, expert system analysis, and dashboard visualization. These utilities serve as the central data transformation layer between external data sources and the application's analytical components.
For information about the specific ML models that consume this processed data, see Lap Time Prediction, Tire Degradation Modeling, and Vision-based Gap Calculation. For details about how the expert system uses the transformed data, see Facts and Data Transformation.
Core Processing Architecture
The data processing utilities are organized around a central processing.py module that orchestrates data loading, transformation, and preparation across multiple data sources and analytical pipelines.
Data Processing Flow
Visualization Preparation
ML Model Integration
Transformation Functions
Core Processing Functions
Raw Data Sources
race_data.csv
gap_data.csv
recommendation_data.csv
MP3 Audio Files
get_processed_race_data()
get_processed_gap_data()
get_processed_recommendations()
transcribe_audio()
add_race_lap_column()
calculate_fuel_adjusted_metrics()
calculate_degradation_rate()
calculate_gap_consistency()
calculate_strategic_windows()
predict_tire_degradation()
predict_lap_times()
analyze_radio_message()
prepare_visualization_data()
Structured Data Dictionary
Sources: scripts/app/utils/processing.py 1-475
Race Data Processing Pipeline
The race data processing pipeline transforms raw telemetry data into analysis-ready formats with calculated metrics for strategic decision-making.
Primary Processing Functions
Function Purpose Key Transformations get_processed_race_data() Main race data processing Adds lap numbers, fuel adjustment, degradation rates add_race_lap_column() Lap number calculation Converts tire age to actual race lap numbers add_lap_time_delta() Performance tracking Calculates lap-to-lap time differences calculate_fuel_adjusted_metrics() Fuel normalization Applies 0.055s/lap fuel adjustment calculate_degradation_rate() Tire analysis Computes tire degradation metrics Race Data Transformation Flow
Calculated Fields
Raw Race Data
add_race_lap_column()
calculate_fuel_adjusted_metrics()
calculate_degradation_rate()
add_lap_time_delta()
Processed Race Data
LapNumber
FuelAdjustedLapTime
DegradationRate
LapTime_Delta
Sources: scripts/app/utils/processing.py 69-130
Gap Analysis and Strategic Windows
The gap analysis system processes time intervals between cars to identify strategic opportunities for pit stops, undercuts, and defensive maneuvers.
Gap Processing Functions
The get_processed_gap_data() function loads gap data and applies consistency analysis, while calculate_gap_consistency() determines how long drivers maintain specific gap windows.
Strategic Opportunities
Consistency Metrics
Gap Window Classification
gap_data.csv
Load Gap Data
calculate_gap_consistency()
ahead_window classification
behind_window classification
undercut_window (< 2.0s)
overcut_window (2.0-3.5s)
defensive_window (< 2.0s)
consistent_gap_ahead_laps
consistent_gap_behind_laps
calculate_strategic_windows()
undercut_opportunity
overcut_opportunity
defensive_needed
Strategic Window Thresholds
Window Type Threshold Consistency Requirement Undercut Opportunity Gap < 2.0 seconds ≥3 consecutive laps Overcut Opportunity 2.0s ≤ Gap < 3.5s ≥3 consecutive laps Defensive Action Gap behind < 2.0s ≥3 consecutive laps
Sources: scripts/app/utils/processing.py 173-399
ML Model Integration Interface
The processing utilities provide standardized interfaces to integrate with machine learning models for predictions and analysis.
Model Integration Functions
Model Outputs
External ML Modules
ML Model Interfaces
Input Data
Processed Race Data
Gap Data
Audio Files
get_tire_degradation_predictions()
get_lap_time_predictions()
transcribe_audio() + analyze_radio_message()
predict_tire_degradation
predict_lap_times
Whisper Transcription
NLP Analysis Pipeline
Tire Degradation Predictions
Lap Time Predictions
Structured Radio Analysis
Import Error Handling
The module uses defensive imports with fallback handling for missing ML dependencies:
try: from ML_tyre_pred.ML_utils.N01_tire_prediction import ( calculate_fuel_adjusted_metrics, calculate_degradation_rate ) except ImportError: calculate_fuel_adjusted_metrics = None calculate_degradation_rate = None
Sources: scripts/app/utils/processing.py 32-65
scripts/app/components/radio_analysis_view.py 1-60
Visualization Data Preparation
The prepare_visualization_data() function orchestrates the loading and transformation of all data sources into a unified structure for dashboard consumption.
Data Preparation Orchestration
Data Type Source Function Purpose
Race Data get_processed_race_data() Core telemetry with calculated metrics
Recommendations get_processed_recommendations() Strategic recommendations from expert system
Tire Predictions get_tire_degradation_predictions() ML-based tire degradation forecasts
Lap Predictions get_lap_time_predictions() ML-based lap time forecasts
Gap Data get_gap_data_with_consistency() Strategic opportunity analysis
Output Data Structure
The function returns a dictionary with standardized keys for consumption by visualization components:
{ "race_data": race_data, "recommendations": recommendations, "tire_predictions": tire_preds, "lap_predictions": lap_preds, "gap_data": gap_data }
Sources: scripts/app/utils/processing.py 401-428
File Organization and Dependencies
Module Structure
The processing utilities follow a hierarchical import structure with path resolution for cross-module dependencies:
NLP Dependencies
Expert System Dependencies
ML Module Dependencies
Data Loading Dependencies
Core Module
scripts/app/utils/processing.py
app/utils/data_loader.py
load_race_data()
load_recommendation_data()
ML_tyre_pred/ML_utils/N01_tire_prediction.py
ML_tyre_pred/ML_utils/N02_model_tire_predictions.py
ML_tyre_pred/ML_utils/N00_model_lap_prediction.py
IS_agent/utils/N01_agent_setup.py
IS_agent/utils/N03_lap_time_rules.py
transform_gap_data_with_consistency()
app_modules/nlp_radio_processing/N06_model_merging.py
transcribe_audio()
analyze_radio_message()
Path Resolution Logic
The module implements dynamic path resolution to handle different deployment scenarios:
FILE_PATH = Path(file).resolve() PROJECT_ROOT = FILE_PATH.parents[2] PARENT_DIR = PROJECT_ROOT.parent if (PARENT_DIR / "outputs").exists(): BASE_DIR = PARENT_DIR else: BASE_DIR = PARENT_DIR
Sources: scripts/app/utils/processing.py 13-29
scripts/app/components/radio_analysis_view.py 7-9
# Development Environment
DeepWiki
VforVitorio/F1_Strat_Manager
Get free private DeepWikis with
Devin
Share
Last indexed: 13 June 2025 (0638ba)
Overview
System Architecture
Installation and Setup
Documentation Workflow
Streamlit Dashboard
Strategy Recommendations View
Gap Analysis View
Radio Analysis View
Time Predictions View
Strategy Chat Interface
Machine Learning Models
Lap Time Prediction
Tire Degradation Modeling
Vision-based Gap Calculation
NLP Pipeline
Radio Transcription
Sentiment and Intent Analysis
Named Entity Recognition
Integrated NLP Pipeline
Expert System
Facts and Data Transformation
Degradation Rules
Gap Analysis Rules
Radio Message Rules
Integrated Rule Engine
Developer Guide
Data Processing Utilities
Model Artifacts and Deployment
Development Environment
Development Environment Relevant source files
This document covers the local development environment setup for the F1 Strategy Manager, including VS Code configuration, editor associations, and LM Studio integration for AI-powered development assistance. This page focuses on the IDE setup and development workflow configuration.
For information about model artifacts and deployment considerations, see Model Artifacts and Deployment. For details about data processing utilities and core development tools, see Data Processing Utilities.
VS Code Configuration
The project includes a comprehensive VS Code configuration that optimizes the development experience for the multi-modal F1 Strategy Manager codebase. The configuration handles various file types used throughout the ML pipeline, data processing, and application development.
Editor Associations
The VS Code settings define specific editor associations for different file types encountered in the F1 strategy system:
File Type Association Purpose *.copilotmd vscode.markdown.preview.editor Markdown preview for documentation *.xls default Excel files for race data *.parquet jupyter-data-wrangler Telemetry data files Git-related files default Version control file handling
VS Code Settings Structure
.vscode/settings.json
workbench.editorAssociations
CodeGPT.apiKey
*.copilotmd → markdown.preview
*.xls → default
*.parquet → jupyter-data-wrangler
git files → default
LM Studio
Sources: .vscode/settings.json 1-9
LM Studio Integration
The development environment integrates with LM Studio for local AI assistance through the CodeGPT extension. This setup enables developers to access AI-powered code completion and analysis without relying on external services.
CodeGPT Configuration
The CodeGPT extension is configured to use LM Studio as the API provider, enabling local LLM integration for development assistance. This aligns with the project's Strategy Chat Interface component that also utilizes local LLM capabilities.
LM Studio Development Integration
Development Assistance
Developer
VS Code
CodeGPT Extension
CodeGPT.apiKey: LM Studio
LM Studio
Local LLM Models
Code Completion
Code Explanation
Refactoring Assistance
Sources: .vscode/settings.json 8
File Type Handling
The development environment is optimized for handling the diverse file types used throughout the F1 Strategy Manager system, from ML model artifacts to race data formats.
Data File Associations
The configuration specifically handles data-intensive file formats commonly used in the F1 analysis pipeline:
Parquet files: Associated with jupyter-data-wrangler for efficient telemetry data exploration
Excel files: Set to default handling for race data imports
Markdown files: Configured for enhanced preview capabilities
Version Control Integration
Git-related files are configured with default associations to ensure proper version control workflow integration across the various data science and application development components.
Development File Ecosystem
VS Code Handling
Documentation
Data Files
Code Files
*.py ML Models & Expert System
*.ipynb Data Processing
*.json Configuration
*.parquet Telemetry Data
*.xls Race Data
*.csv Processed Data
*.md Documentation
*.copilotmd AI-Generated Docs
jupyter-data-wrangler
default
markdown.preview.editor
Sources: .vscode/settings.json 2-7
Development Workflow
The development environment supports the complex workflow requirements of the F1 Strategy Manager, which spans data science, machine learning, expert systems, and web application development.
Multi-Modal Development Support
The VS Code configuration accommodates the diverse development activities within the project:
Data Analysis: Jupyter Data Wrangler integration for parquet file exploration
ML Development: Standard Python environment for model development
Documentation: Enhanced markdown preview for technical documentation
AI Assistance: Local LLM integration for development support Local Development Stack
The development environment emphasizes local-first development with offline capabilities:
Local LLM: LM Studio integration eliminates dependency on external AI services
Data Processing: Local handling of telemetry and race data files
Model Development: Local training and inference capabilities
Documentation: Local markdown rendering and preview
This setup aligns with the project's architecture that includes local model inference and expert system execution, ensuring developers can work effectively in offline environments while maintaining full system functionality.
Sources: .vscode/settings.json 1-9
# Developer Guide
DeepWiki
VforVitorio/F1_Strat_Manager
Get free private DeepWikis with
Devin
Share
Last indexed: 13 June 2025 (0638ba)
Overview
System Architecture
Installation and Setup
Documentation Workflow
Streamlit Dashboard
Strategy Recommendations View
Gap Analysis View
Radio Analysis View
Time Predictions View
Strategy Chat Interface
Machine Learning Models
Lap Time Prediction
Tire Degradation Modeling
Vision-based Gap Calculation
NLP Pipeline
Radio Transcription
Sentiment and Intent Analysis
Named Entity Recognition
Integrated NLP Pipeline
Expert System
Facts and Data Transformation
Degradation Rules
Gap Analysis Rules
Radio Message Rules
Integrated Rule Engine
Developer Guide
Data Processing Utilities
Model Artifacts and Deployment
Development Environment
Developer Guide Relevant source files
This document provides technical documentation for developers working on the F1 Strategy Manager codebase. It covers the core data processing utilities, component architecture, model integration patterns, and development environment setup required for extending and maintaining the system.
For information about the overall system architecture, see System Architecture. For details about specific ML models and their training, see Machine Learning Models. For expert system rule implementation, see Expert System.
Development Architecture Overview
The F1 Strategy Manager follows a modular architecture with clear separation between data processing, machine learning inference, expert system reasoning, and user interface components. The development workflow centers around utilities that transform raw race data into structured facts for the expert system and visualizations for the dashboard.
Expert System Integration
NLP Processing Modules
Streamlit Components
Core Processing Layer
processing.py get_processed_race_data()
data_loader.py load_race_data()
ML Model Transformers predict_tire_degradation() predict_lap_times()
radio_analysis_view.py render_radio_analysis_view()
competitive_analysis_view.py render_competitive_analysis_view()
time_predictions_view.py render_time_predictions_view()
report_export.py render_report_export_ui()
N04_radio_info.py transcribe_audio() analyze_radio_message()
N06_model_merging.py NLP Pipeline Integration
N01_agent_setup.py transform_gap_data_with_consistency()
Data → Facts Transformation
Core Data Processing Pipeline
The development workflow follows a consistent pattern where raw CSV data is loaded, processed through various transformation functions, enhanced with ML predictions, and finally converted into structured formats for both visualization and expert system reasoning.
Sources: scripts/app/utils/processing.py 1-475
scripts/app/components/radio_analysis_view.py 1-60
scripts/app/components/competitive_analysis_view.py 1-231
Data Processing Utilities
The processing.py module serves as the central hub for all data transformation operations, providing a standardized interface for loading, processing, and preparing race data for downstream analysis.
Core Processing Functions
Visualization Preparation
ML Model Integration
Primary Processing Functions
Raw Data Sources
race_data.csv
gap_data.csv
recommendations.csv
get_processed_race_data() Add lap numbers & fuel adjustment
get_processed_recommendations() Filter by driver
get_processed_gap_data() Add consistency metrics
get_tire_degradation_predictions() predict_tire_degradation()
get_lap_time_predictions() predict_lap_times()
prepare_visualization_data() Orchestrate all processing
The processing pipeline implements several key transformations:
Race Lap Calculation: The add_race_lap_column() function calculates real race lap numbers by tracking stint progression and tire age across drivers scripts/app/utils/processing.py 69-98
Gap Consistency Analysis: The calculate_gap_consistency() function computes how many consecutive laps a driver has maintained specific gap windows, essential for strategic opportunity detection scripts/app/utils/processing.py 273-344
Strategic Window Detection: The calculate_strategic_windows() function identifies undercut, overcut, and defensive opportunities based on gap thresholds and consistency metrics scripts/app/utils/processing.py 346-399
Model Integration Pattern
The processing utilities follow a consistent pattern for integrating ML models:
def get_tire_degradation_predictions(race_data, models_path, compound_start_laps=None): if predict_tire_degradation is None: raise ImportError("Could not import predict_tire_degradation") return predict_tire_degradation(race_data, models_path, compound_start_laps=compound_start_laps)
This pattern enables graceful degradation when models are unavailable while maintaining a consistent interface for all prediction functions scripts/app/utils/processing.py 142-160
Sources: scripts/app/utils/processing.py 1-475
scripts/app/utils/processing.py 69-98
scripts/app/utils/processing.py 273-344
Component Architecture
The Streamlit dashboard implements a modular component architecture where each analytical view is encapsulated in its own module with standardized rendering functions.
Component Interface Pattern
Specific Components
Component Interface Standard
render_*_view(data, selected_driver) Main rendering function
Data validation & preprocessing
Plotly figure generation
Streamlit UI elements
Export-ready figure return
render_radio_analysis_view() MP3 upload → transcription → NLP
render_competitive_analysis_view() Position evolution & opponent tracking
render_time_predictions_view() Real vs predicted lap times
Radio Analysis Component
The radio analysis component implements a complete audio processing pipeline within the Streamlit interface:
File Upload Handling: Temporary file management for MP3 uploads with automatic cleanup scripts/app/components/radio_analysis_view.py 24-29
Transcription Pipeline: Integration with Whisper-based transcription through the transcribe_audio() function scripts/app/components/radio_analysis_view.py 31-39
NLP Analysis Integration: Connection to the complete NLP pipeline via analyze_radio_message() for sentiment, intent, and entity extraction scripts/app/components/radio_analysis_view.py 41-54
Competitive Analysis Component
The competitive analysis component provides sophisticated position tracking and opponent strategy estimation:
Position Evolution Tracking: Multi-driver position comparison with customizable driver selection scripts/app/components/competitive_analysis_view.py 31-56
Stint Analysis: Extraction of tire compound changes and stint length estimation for pit window prediction scripts/app/components/competitive_analysis_view.py 58-92
Opponent Strategy Estimation: Real-time assessment of when rivals are likely to pit based on historical stint patterns scripts/app/components/competitive_analysis_view.py 134-174
Sources: scripts/app/components/radio_analysis_view.py 1-60
scripts/app/components/competitive_analysis_view.py 1-231
scripts/app/components/time_predictions_view.py 1-81
Model Artifacts and Integration
The system integrates multiple trained models through a standardized loading and inference pattern that supports graceful degradation and error handling.
Model Loading Architecture
Processing Integration
Import Pattern
Model Artifacts
xgb_sequential_model.pkl Lap Time Prediction
tire_degradation_models/ LSTM/TCN Models
model_anti_alpine.pt yolo11n.pt Car Detection
best_roberta_sentiment_model.pt best_bert_ner_model.pt best_deberta_intention_model.pt
try: from ML_module import predict_function except ImportError: predict_function = None
if predict_function is None: raise ImportError()
return predict_function(data, model_path)
get_*_predictions() Standardized wrapper functions
Graceful degradation when models unavailable
NLP Model Integration
The NLP pipeline demonstrates advanced model integration with multi-stage processing:
Intent Classification: DeBERTa-v3-large model for classifying radio messages into categories (INFORMATION, PROBLEM, ORDER, WARNING, QUESTION) with 76% accuracy scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 404-416
Sentiment Analysis: RoBERTa-based sentiment classification integrated into the complete NLP pipeline scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 380-401
Named Entity Recognition: Custom SpaCy model for F1-specific entity extraction including actions, situations, incidents, and technical issues scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 1019-1034
Model Performance Tracking
The system includes comprehensive model evaluation and comparison capabilities:
Training Metrics Storage: Structured tracking of validation accuracy, loss, and F1 scores across different model architectures scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 870-997
Confusion Matrix Analysis: Detailed class-level performance analysis with visualization support scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 853-867
Sources: scripts/app/utils/processing.py 32-66
scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 1-1096
Report Generation System
The report export system provides comprehensive document generation with LLM-enhanced narratives and multimodal content integration.
Report Architecture
HTML Export
Content Generation
Data Collection
collect_report_data() Gather all visualizations & data
get_driver_info() F1_2023_DRIVERS_BY_TEAM mapping
Race metadata & weather data
generate_llm_narrative() Multimodal LLM integration
image_to_base64() Plotly/Matplotlib conversion
stream_llm_response() Chunk-based streaming
build_html_report() Section-based assembly
User-configurable sections
Streamlit download integration
LLM Integration Pattern
The report system integrates local LLM capabilities through a sophisticated streaming interface:
Multimodal Message Construction: Support for both text and image content in LLM conversations scripts/app/components/report_export.py 139-157
Streaming Response Handling: Chunk-based response processing for real-time feedback during report generation scripts/app/components/report_export.py 158-163
Data Serialization: Intelligent summarization of DataFrames and large data structures for LLM consumption scripts/app/components/report_export.py 114-129
Export Configuration
The system provides flexible section-based report customization:
Section Management: Configurable inclusion/exclusion of report sections with default preferences scripts/app/components/report_export.py 422-453
Progress Tracking: Real-time progress indication during multi-section LLM narrative generation scripts/app/components/report_export.py 541-605
HTML Assembly: Structured HTML generation with embedded base64 images and markdown content processing scripts/app/components/report_export.py 249-396
Sources: scripts/app/components/report_export.py 1-617
scripts/app/components/report_export.py 103-164
scripts/app/components/report_export.py 171-247
Development Environment Setup
The development environment requires careful coordination between multiple ML frameworks, data processing libraries, and GPU-accelerated components.
Dependencies and Configuration
The system integrates several key technology stacks:
ML Framework Stack: PyTorch for deep learning models, XGBoost for gradient boosting, scikit-learn for preprocessing and evaluation metrics.
NLP Pipeline: Transformers library for BERT/RoBERTa models, SpaCy for custom NER, Whisper for audio transcription.
Visualization Stack: Plotly for interactive charts, Streamlit for dashboard interface, matplotlib for static plots.
Expert System: Experta framework for rule-based reasoning, pandas for data manipulation.
Model Training Environment
The development setup supports GPU-accelerated training across multiple model types:
CUDA Configuration: GPU preference detection for SpaCy and PyTorch training pipelines scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 1044-1048
Mixed Precision Training: Gradient scaling and automatic mixed precision support for memory efficiency scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 565-566
Model Checkpointing: Automatic best model saving based on validation metrics scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 744-750
Path Resolution and Module Loading
The system implements robust path resolution for cross-platform compatibility:
Project Structure Navigation: Dynamic path resolution from component files to project root and data directories scripts/app/utils/processing.py 13-28
Graceful Import Handling: Comprehensive try-catch blocks for optional dependencies and model modules scripts/app/utils/processing.py 32-66
Module Path Management: sys.path manipulation for proper module discovery across the project structure scripts/app/components/radio_analysis_view.py 7-9
Sources: scripts/app/utils/processing.py 13-28
scripts/app/app_modules/nlp_radio_processing/N04_radio_info.py 1044-1048
scripts/app/components/radio_analysis_view.py 7-9
📝 This documentation is automatically generated using browser automation.
🕒 Last updated: $(date '+%Y-%m-%d %H:%M:%S UTC')
📊 Auto-organized from 3 content files