This service transforms enriched telemetry data from HPC simulations into actionable F1 race strategies using advanced AI. It sits between the HPC enrichment module and race engineers, providing real-time strategic recommendations.

🎯 System Overview

The AI Intelligence Layer uses a two-step LLM process powered by Google Gemini:

Strategy Generation (Brainstorming): Generate 20 diverse strategy options based on telemetry trends
Strategy Analysis & Selection: Analyze all options and select top 3 with detailed execution plans

🏗️ Architecture Integration

┌─────────────────────┐
│  HPC Enrichment     │
│  (localhost:8000)   │
│                     │
│  Enriched Telemetry │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  AI Intelligence    │  ◄── You are here
│  (localhost:9000)   │
│                     │
│  Strategy AI        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Race Engineers     │
│  Frontend/Display   │
└─────────────────────┘

Upstream Service (HPC Enrichment)

URL: http://localhost:8000
Provides: Enriched telemetry data (lap-by-lap metrics)
Integration: Pull (fetch) or Push (webhook)

This Service (AI Intelligence Layer)

URL: http://localhost:9000
Provides: Strategic race recommendations with detailed analysis

🚀 Quick Start

1. Prerequisites

Python 3.11+
Google Gemini API key (Get one here)
HPC enrichment service running on port 8000

2. Installation

cd ai_intelligence_layer

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configuration

# Copy example env file
cp .env.example .env

# Edit .env and add your Gemini API key
nano .env

Required environment variables:

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-1.5-pro
AI_SERVICE_PORT=9000
ENRICHMENT_SERVICE_URL=http://localhost:8000

4. Run the Service

# Start the server
python main.py

# Or with uvicorn directly
uvicorn main:app --host 0.0.0.0 --port 9000 --reload

The service will be available at http://localhost:9000

📡 API Endpoints

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "service": "AI Intelligence Layer",
  "version": "1.0.0",
  "demo_mode": false,
  "enrichment_service_url": "http://localhost:8000"
}

Webhook Receiver (for enrichment service)

POST /api/ingest/enriched
Content-Type: application/json

{
  "lap": 27,
  "aero_efficiency": 0.83,
  "tire_degradation_index": 0.65,
  "ers_charge": 0.72,
  "fuel_optimization_score": 0.91,
  "driver_consistency": 0.89,
  "weather_impact": "medium"
}

Response:

{
  "status": "received",
  "lap": 27,
  "buffer_size": 10
}

Strategy Brainstorming

POST /api/strategy/brainstorm
Content-Type: application/json

{
  "enriched_telemetry": [...],  # Optional, will fetch from enrichment service if omitted
  "race_context": {
    "race_info": {
      "track_name": "Monaco",
      "total_laps": 58,
      "current_lap": 27,
      "weather_condition": "Dry",
      "track_temp_celsius": 42
    },
    "driver_state": {
      "driver_name": "Hamilton",
      "current_position": 4,
      "current_tire_compound": "medium",
      "tire_age_laps": 14,
      "fuel_remaining_percent": 47
    },
    "competitors": [...]
  }
}

Response:

{
  "strategies": [
    {
      "strategy_id": 1,
      "strategy_name": "Conservative 1-Stop",
      "stop_count": 1,
      "pit_laps": [32],
      "tire_sequence": ["medium", "hard"],
      "brief_description": "Extend mediums to lap 32, safe finish on hards",
      "risk_level": "low",
      "key_assumption": "Tire degradation stays below 0.85 until lap 32"
    }
    // ... 19 more strategies
  ]
}

Strategy Analysis

POST /api/strategy/analyze
Content-Type: application/json

{
  "enriched_telemetry": [...],
  "race_context": {...},
  "strategies": [...]  # Array of 20 strategies from brainstorm
}

Response:

{
  "top_strategies": [
    {
      "rank": 1,
      "strategy_id": 7,
      "strategy_name": "Aggressive Undercut",
      "classification": "RECOMMENDED",
      "predicted_outcome": {
        "finish_position_most_likely": 3,
        "p1_probability": 8,
        "p2_probability": 22,
        "p3_probability": 45,
        "p4_or_worse_probability": 25,
        "confidence_score": 78
      },
      "risk_assessment": {
        "risk_level": "medium",
        "key_risks": ["Requires pit stop under 2.5s"],
        "success_factors": ["Tire degradation trending favorably"]
      },
      "telemetry_insights": {
        "tire_wear_projection": "Current 0.65, will hit 0.85 cliff by lap 35",
        "aero_status": "0.83 - car performing well",
        "fuel_margin": "0.91 - excellent, no saving needed",
        "driver_form": "0.89 - high confidence"
      },
      "engineer_brief": {
        "title": "Recommended: Aggressive Undercut Lap 18",
        "summary": "67% chance P3 or better",
        "key_points": ["Tire degradation accelerating", "Undercut window open"],
        "execution_steps": ["Lap 18: Box for softs", "Lap 19-26: Push hard"]
      },
      "driver_audio_script": "Box this lap. Softs going on. Push mode for 8 laps.",
      "ecu_commands": {
        "fuel_mode": "RICH",
        "ers_strategy": "AGGRESSIVE_DEPLOY",
        "engine_mode": "PUSH",
        "brake_balance_adjustment": 0,
        "differential_setting": "BALANCED"
      }
    }
    // ... 2 more strategies (rank 2, 3)
  ],
  "situational_context": {
    "critical_decision_point": "Next 3 laps crucial",
    "telemetry_alert": "Aero efficiency stable",
    "key_assumption": "No safety car deployment",
    "time_sensitivity": "Decision needed within 2 laps"
  }
}

🧪 Testing

Using the Test Script

cd ai_intelligence_layer
chmod +x test_api.sh
./test_api.sh

Manual Testing with curl

# 1. Health check
curl http://localhost:9000/api/health

# 2. Brainstorm (with sample data)
curl -X POST http://localhost:9000/api/strategy/brainstorm \
  -H "Content-Type: application/json" \
  -d @- << EOF
{
  "enriched_telemetry": $(cat sample_data/sample_enriched_telemetry.json),
  "race_context": $(cat sample_data/sample_race_context.json)
}
EOF

# 3. Full workflow test
./test_api.sh

🔗 Integration with Enrichment Service

Option 1: Pull Model (Service Fetches)

The AI service automatically fetches telemetry when none is provided:

# Configure enrichment service URL in .env
ENRICHMENT_SERVICE_URL=http://localhost:8000

# Call brainstorm without telemetry data
curl -X POST http://localhost:9000/api/strategy/brainstorm \
  -H "Content-Type: application/json" \
  -d '{"race_context": {...}}'

Option 2: Push Model (Webhook) [RECOMMENDED]

Configure the enrichment service to push data:

# In enrichment service .env:
NEXT_STAGE_CALLBACK_URL=http://localhost:9000/api/ingest/enriched

# Start enrichment service - it will automatically push to AI layer
# AI layer buffers the data for strategy generation

📊 Understanding Enriched Telemetry

The AI layer interprets enriched metrics from HPC analysis:

Metric	Range	Interpretation	Strategy Impact
`aero_efficiency`	0-1 (higher better)	Aerodynamic performance	<0.6 = problem, prioritize early stop
`tire_degradation_index`	0-1 (higher worse)	Tire wear	>0.7 = aggressive stop, >0.85 = cliff imminent
`ers_charge`	0-1	Energy system charge	>0.7 = can attack, <0.3 = depleted
`fuel_optimization_score`	0-1 (higher better)	Fuel efficiency	<0.7 = must save fuel
`driver_consistency`	0-1 (higher better)	Lap-to-lap variance	<0.75 = risky, prefer conservative
`weather_impact`	low/medium/high	Weather effect severity	high = favor flexible strategies

🎓 How It Works

Step 1: Strategy Brainstorming

The AI generates 20 diverse strategies by:

Analyzing telemetry trends (tire deg rate, aero efficiency, ERS patterns)
Considering race constraints (current lap, competitors, track)
Generating diverse options: conservative, standard, aggressive, reactive, contingency
Using high temperature (0.9) for creative diversity

Diversity categories:

Conservative: 1-stop, minimal risk
Standard: Balanced 1-stop or 2-stop
Aggressive: Early undercut, overcut plays
Reactive: Respond to competitor moves
Contingency: Safety car, rain scenarios

Step 2: Strategy Analysis

The AI analyzes all 20 strategies and selects top 3 by:

Tire Degradation Projection: Rate of change, cliff prediction
Aero Efficiency Impact: Lap time degradation assessment
Fuel Management: Fuel-saving mode necessity
Driver Consistency: Risk tolerance based on form
Weather & Track Position: Safety car probability, overtaking difficulty
Competitor Analysis: Undercut/overcut opportunities

Selection criteria:

Rank 1 (RECOMMENDED): Highest podium probability, balanced risk
Rank 2 (ALTERNATIVE): Different approach, viable if conditions change
Rank 3 (CONSERVATIVE): Safest option, minimize finishing outside points

Uses low temperature (0.3) for analytical consistency.

🛠️ Development

Project Structure

ai_intelligence_layer/
├── main.py                 # FastAPI application
├── config.py               # Settings management
├── requirements.txt        # Dependencies
├── .env.example            # Environment template
├── models/
│   ├── input_models.py     # Request schemas
│   ├── output_models.py    # Response schemas
│   └── internal_models.py  # Internal data structures
├── services/
│   ├── gemini_client.py    # Gemini API wrapper
│   ├── telemetry_client.py # Enrichment API client
│   ├── strategy_generator.py  # Brainstorm logic
│   └── strategy_analyzer.py   # Analysis logic
├── prompts/
│   ├── brainstorm_prompt.py   # Step 1 prompt template
│   └── analyze_prompt.py      # Step 2 prompt template
├── utils/
│   ├── validators.py       # Strategy validation
│   └── telemetry_buffer.py # In-memory storage
└── sample_data/
    ├── sample_enriched_telemetry.json
    └── sample_race_context.json

Adding New Features

Custom Strategy Types: Edit prompts/brainstorm_prompt.py
Analysis Criteria: Edit prompts/analyze_prompt.py
Telemetry Metrics: Add to models/input_models.py and update validators
Validation Rules: Edit utils/validators.py

⚙️ Configuration Options

Demo Mode

Enable consistent responses for demos:

DEMO_MODE=true

Features:

Caches Gemini responses for identical inputs
Lower temperature for repeatability
Artificial "thinking" delays (optional)

Performance Tuning

BRAINSTORM_TIMEOUT=30    # Seconds for brainstorm generation
ANALYZE_TIMEOUT=60       # Seconds for analysis
GEMINI_MAX_RETRIES=3     # Retry attempts on failure

Gemini Model Selection

GEMINI_MODEL=gemini-1.5-pro        # Recommended
# GEMINI_MODEL=gemini-1.5-flash    # Faster, less detailed

🐛 Troubleshooting

"Enrichment service unreachable"

Check enrichment service is running: curl http://localhost:8000/health
Verify ENRICHMENT_SERVICE_URL in .env
Use absolute telemetry in request as fallback

"Gemini API error"

Verify GEMINI_API_KEY in .env
Check API quota: https://makersuite.google.com/app/apikey
Review rate limits (increase GEMINI_MAX_RETRIES)

"Invalid JSON from Gemini"

Service automatically retries with stricter prompt
Check Gemini model supports JSON mode
Review logs for parsing errors

"Strategies validation failed"

Check race context constraints (current lap, total laps)
Ensure at least 2 tire compounds available
Review strategy validator logs

📈 Performance

Target response times:

Brainstorm: <5 seconds (20 strategies)
Analyze: <10 seconds (top 3 selection)
Health check: <100ms
Webhook ingest: <50ms

Optimization tips:

Use webhook push model for real-time data
Enable demo mode for consistent demo performance
Adjust timeouts based on network conditions

🔒 Security Notes

Store GEMINI_API_KEY securely (never commit to git)
Use environment variables for all secrets
Consider API key rotation for production
Implement rate limiting for public deployments

📝 License

Part of HPCSimSite hackathon project.

🤝 Contributing

This is a hackathon project. For improvements:

Test changes with sample data
Validate against race constraints
Ensure backward compatibility with enrichment service

📞 Support

For integration issues:

Check enrichment service compatibility
Review API endpoint documentation
Test with provided sample data
Enable debug logging: LOG_LEVEL=DEBUG

Built for the HPC + AI Race Strategy Hackathon 🏎️💨