# Clutch-IQ Inference API Interface Guide

## Overview
The Inference Service (`src/inference/app.py`) supports **two types of payloads** to accommodate different use cases: Real-time Game Integration and Strategy Simulation (Dashboard).

## 1. Raw Game State Payload (Game Integration)
Used when receiving data directly from the CS2 Game State Integration (GSI) or Parser. The server performs Feature Engineering.

**Use Case:** Real-time match prediction.

**Payload Structure:**
```json
{
  "game_time": 60.0,
  "is_bomb_planted": 0,
  "site": 0,
  "players": [
    {
      "team_num": 2, // 2=T, 3=CT
      "is_alive": true,
      "health": 100,
      "X": -1200, "Y": 500, "Z": 128,
      "active_weapon_name": "ak47",
      "balance": 4500,
      "equip_value": 2700
    },
    ...
  ]
}
```

**Processing Logic:**
- `process_payload` extracts `players` list.
- Calculates `t_alive`, `health_diff`, `t_spread`, `pincer_index`, etc.
- Returns feature vector.

---

## 2. Pre-calculated Feature Payload (Dashboard/Simulation)
Used when the client (e.g., Streamlit Dashboard) manually sets the tactical situation. The server skips feature engineering and uses provided values.

**Use Case:** "What-if" analysis, Strategy Dashboard.

**Payload Structure:**
```json
{
  "t_alive": 2,
  "ct_alive": 3,
  "t_health": 180,
  "ct_health": 290,
  "t_equip_value": 8500,
  "ct_equip_value": 14000,
  "t_total_cash": 1200,
  "ct_total_cash": 3500,
  "team_distance": 1500.5,
  "t_spread": 400.2,
  "ct_spread": 800.1,
  "t_area": 40000.0,
  "ct_area": 64000.0,
  "t_pincer_index": 0.45,
  "ct_pincer_index": 0.22,
  "is_bomb_planted": 0,
  "site": 0,
  "game_time": 60.0
}
```

**Processing Logic:**
- `process_payload` detects presence of `t_alive` / `ct_alive`.
- Uses values directly.
- Auto-calculates derived fields like `health_diff` (`ct - t`) if missing.

## Error Handling
If you receive `Error: {"error":"Not supported type for data.<class 'NoneType'>"}`:
- **Cause:** You sent a payload that matches neither format (e.g., missing `players` list AND missing direct features).
- **Fix:** Ensure your JSON body matches one of the structures above.