clutch/docs/API_INTERFACE_GUIDE.md

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:

{
  "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:

{
  "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.