p

2025-10-18 22:36:20 -05:00
parent 3c961efaff
commit a92ddf06bb
45 changed files with 5106 additions and 0 deletions
--- a/ai_intelligence_layer/QUICKSTART.md
+++ b/ai_intelligence_layer/QUICKSTART.md
@@ -0,0 +1,131 @@
+# 🚀 Quick Start Guide - AI Intelligence Layer
+
+## ⚡ 60-Second Setup
+
+### 1. Get Gemini API Key
+Visit: https://makersuite.google.com/app/apikey
+
+### 2. Configure
+```bash
+cd ai_intelligence_layer
+nano .env
+# Add your API key: GEMINI_API_KEY=your_key_here
+```
+
+### 3. Run
+```bash
+source myenv/bin/activate
+python main.py
+```
+
+Service starts on: http://localhost:9000
+
+---
+
+## 🧪 Quick Test
+
+### Health Check
+```bash
+curl http://localhost:9000/api/health
+```
+
+### Full Test
+```bash
+./test_api.sh
+```
+
+---
+
+## 📡 API Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/health` | GET | Health check |
+| `/api/ingest/enriched` | POST | Webhook receiver |
+| `/api/strategy/brainstorm` | POST | Generate 20 strategies |
+| `/api/strategy/analyze` | POST | Select top 3 |
+
+---
+
+## 🔗 Integration
+
+### With Enrichment Service (localhost:8000)
+
+**Option 1: Pull** (AI fetches)
+```bash
+# In enrichment service, AI will auto-fetch from:
+# http://localhost:8000/enriched?limit=10
+```
+
+**Option 2: Push** (Webhook - RECOMMENDED)
+```bash
+# In enrichment service .env:
+NEXT_STAGE_CALLBACK_URL=http://localhost:9000/api/ingest/enriched
+```
+
+---
+
+## 📦 What You Get
+
+### Input
+- Enriched telemetry (aero, tires, ERS, fuel, consistency)
+- Race context (track, position, competitors)
+
+### Output
+- **20 diverse strategies** (conservative → aggressive)
+- **Top 3 analyzed** with:
+  - Win probabilities
+  - Risk assessment
+  - Engineer briefs
+  - Driver radio scripts
+  - ECU commands
+
+---
+
+## 🎯 Example Usage
+
+### Brainstorm
+```bash
+curl -X POST http://localhost:9000/api/strategy/brainstorm \
+  -H "Content-Type: application/json" \
+  -d '{
+    "race_context": {
+      "race_info": {"track_name": "Monaco", "current_lap": 27, "total_laps": 58},
+      "driver_state": {"driver_name": "Hamilton", "current_position": 4}
+    }
+  }'
+```
+
+### Analyze
+```bash
+curl -X POST http://localhost:9000/api/strategy/analyze \
+  -H "Content-Type: application/json" \
+  -d '{
+    "race_context": {...},
+    "strategies": [...]
+  }'
+```
+
+---
+
+## 🐛 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| API key error | Add `GEMINI_API_KEY` to `.env` |
+| Enrichment unreachable | Start enrichment service or provide telemetry data |
+| Import errors | Activate venv: `source myenv/bin/activate` |
+
+---
+
+## 📚 Documentation
+
+- **Full docs**: `README.md`
+- **Implementation details**: `IMPLEMENTATION_SUMMARY.md`
+- **Sample data**: `sample_data/`
+
+---
+
+## ✅ Status
+
+All systems operational! Ready to generate race strategies! 🏎️💨