feat: Initial commit of Clutch-IQ project

docs/API_INTERFACE_GUIDE.md

@@ -0,0 +1,76 @@
+# 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.