docs/TEST_GUIDE.md

Complete Step-by-Step Testing Guide

Part 1: Check Available Models

Step 1: List all MLflow runs

Open a terminal and run:

python -c "
import mlflow
runs = mlflow.search_runs()
if runs:
    for i, run in enumerate(runs):
        print(f'{i+1}. Run ID: {run.info.run_id}')
        print(f'   Status: {run.info.status}')
        artifacts = mlflow.artifacts.list_artifacts(run_id=run.info.run_id)
        print(f'   Has artifacts: {len(artifacts) > 0}')
        print()
else:
    print('No runs found!')
"

What to look for:

• Copy a run ID that has status: FINISHED
• Check if it has artifacts (models)

If you see run IDs: Go to Step 3
If you see "No runs found!": Go to Step 2

---

Part 2: Train a New Model (If Needed)

Step 2: Train the model

python ml/train.py

What to expect:

• Takes 2-5 minutes
• Prints: Training complete! Run ID: ...
• Copy that Run ID

---

Part 3: Update Configuration

Step 3: Update .env with the correct Run ID

Edit .env and replace the run ID:

KRONECTOR_MODEL_RUN_ID=<paste-the-run-id-here>

Example:

KRONECTOR_MODEL_RUN_ID=563634279953604033

Save the file!

Step 4: Restart the API

If the API is running, stop it (Ctrl+C in the terminal).

Then restart:

python -m uvicorn api.main:app --reload

Wait for: Uvicorn running on http://127.0.0.1:8000

---

Part 4: Test the API

Step 5: Check Health Status

Open a new terminal and run:

curl http://localhost:8000/health

Expected output:

{
  "status": "healthy",
  "model_loaded": true,
  "data_available": true,
  "version": "1.0.0"
}

If model_loaded is still false: The run ID is wrong. Go back to Step 1 and copy the correct ID.

Step 6: List Available Drivers

curl "http://localhost:8000/drivers?season=2023"

Expected output:

[
  {"driver_id": "VER", "driver_name": "Max Verstappen", "team": "Red Bull"},
  {"driver_id": "SAI", "driver_name": "Carlos Sainz", "team": "Ferrari"},
  ...
]

Step 7: List Races

curl http://localhost:8000/races/2023

Expected output:

[
  {"season": 2023, "round": 1, "name": "Bahrain Grand Prix"},
  {"season": 2023, "round": 2, "name": "Saudi Arabian Grand Prix"},
  ...
]

---

Part 5: Test the Main Prediction

Step 8: Natural Language Query (THE MAIN TEST)

curl -X POST http://localhost:8000/predict/f1 `
  -H "Content-Type: application/json" `
  -d '{"query": "What is Verstappens win probability at Monaco 2023?"}'

Expected output:

{
  "win_probability": 0.87,
  "metadata": {
    "season": 2023,
    "round": 6,
    "driver_id": "VER",
    "driver_name": "Max Verstappen",
    "team": "Red Bull",
    "grid_position": 1
  },
  "shap_values": {
    "grid_position": 0.45,
    "previous_race_points": 0.23,
    ...
  }
}

If it works: ✅ SUCCESS! The system is working!

---

Part 6: Visual Testing (Easiest!)

Step 9: Use the Interactive API Docs

Open your browser and visit:

http://localhost:8000/docs

You'll see all 5 endpoints with:

• Try it out buttons
• Example inputs
• Full responses

Test order:

1. Click /health → Execute (check model_loaded)
2. Click /drivers → Execute (see drivers)
3. Click /races/{season} → Enter "2023" → Execute
4. Click /predict/f1 → Enter {"query": "Verstappen Monaco 2023"} → Execute

---

Troubleshooting

Problem: model_loaded: false

Solution:

1. Check you have the right run ID in .env
2. Verify the run exists: python ml/train.py to create a new one
3. Restart the API

Problem: Query returns error 503

Solution:

• Model not loaded yet (see above)
• Check the API logs in the terminal for details

Problem: "query": "must be at least 3 characters"

Solution:

• Make sure your query is longer than 3 characters
• Example: "What is VER's win probability at Monaco?" ✅

Problem: Race not found

Solution:

• Check valid seasons: 2023 races are available
• Try: "Verstappen Bahrain 2023" instead

---

Quick Test Commands (Copy & Paste)

# 1. Check health
curl http://localhost:8000/health

# 2. List drivers
curl "http://localhost:8000/drivers?season=2023"

# 3. List races
curl http://localhost:8000/races/2023

# 4. Make prediction
curl -X POST http://localhost:8000/predict/f1 `
  -H "Content-Type: application/json" `
  -d '{"query": "Verstappen Monaco 2023 win probability?"}'

# 5. Open interactive docs
start http://localhost:8000/docs

---

Expected Results

Test	Status	Output
Health check	✅	model_loaded: true
List drivers	✅	Array of drivers
List races	✅	Array of races
Prediction	✅	Win probability (0-1) + SHAP values

---

Success!

If all 4 tests pass, your system is fully functional! 🎉

The API is ready to:

• Accept natural language F1 queries
• Return accurate win probabilities
• Explain predictions with SHAP values