ML-RosterOptimiser/api_contract.txt at main · Player1205/ML-RosterOptimiser · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
Apex Zero Roster Optimizer API Contract
======================================

This document defines the API response formats used by the Apex Zero AI-Driven Roster & Contract Optimizer.
It ensures consistency between backend and frontend development and prevents integration errors.

All salary values are represented in LAKHS.
All player performance predictions are numeric scores generated by the ML model.


------------------------------------------------------------
1. UPLOAD API
------------------------------------------------------------
Endpoint:
POST /upload

Description:
Uploads the dataset CSV file and triggers preprocessing.

Response:
{
  "status": "ok",
  "rows": 182
}

Fields:
status → upload success indicator
rows → number of records processed


------------------------------------------------------------
2. PREDICT API
------------------------------------------------------------
Endpoint:
POST /predict

Description:
Runs ML inference on uploaded dataset and returns predicted player performance and value index.

Response:
{
  "status": "ok",
  "count": 182,
  "players": [
    {
      "Player": "Virat Kohli",
      "TEAM": "RCB",
      "Paying_Role": "Batsman",
      "AGE": 35,
      "salary_lakhs": 1500,
      "predicted_performance": 34.2,
      "value_index": 0.022
    }
  ]
}

Fields:
Player → player name
TEAM → IPL team
Paying_Role → Batsman | Bowler | Allrounder | Wicketkeeper
AGE → player age
salary_lakhs → salary in lakhs
predicted_performance → ML predicted performance score
value_index → predicted_performance / (salary_lakhs + 1)


------------------------------------------------------------
3. OPTIMIZE API
------------------------------------------------------------
Endpoint:
POST /optimize

Description:
Runs salary-cap roster optimization using knapsack optimization.

Request Body:
{
  "salary_cap": 9000,
  "roster_size": 11
}

Response:
{
  "status": "ok",
  "salary_cap": 9000,
  "roster_size": 11,
  "selected_players": [
    {
      "Player": "Virat Kohli",
      "TEAM": "RCB",
      "Paying_Role": "Batsman",
      "salary_lakhs": 1500,
      "predicted_performance": 34.2,
      "value_index": 0.022
    }
  ],
  "total_salary": 8900,
  "total_predicted_score": 310.5,
  "cap_remaining": 100
}

Fields:
selected_players → optimized roster
total_salary → total salary used
total_predicted_score → sum of predicted performance
cap_remaining → unused cap


------------------------------------------------------------
4. DASHBOARD API
------------------------------------------------------------
Endpoint:
GET /dashboard

Description:
Returns aggregated analytics insights.

Response:
{
  "top_undervalued": [
    {
      "Player": "Player A",
      "value_index": 3.4
    }
  ],
  "top_overpaid": [
    {
      "Player": "Player B",
      "value_index": 0.2
    }
  ],
  "avg_value_by_role": {
    "Batsman": 1.8,
    "Bowler": 1.2,
    "Allrounder": 2.2,
    "Wicketkeeper": 1.5
  },
  "total_players": 182
}

Fields:
top_undervalued → highest value index players
top_overpaid → lowest value index players
avg_value_by_role → role-wise average value index
total_players → dataset size


------------------------------------------------------------
5. UI DATA MAPPING (IMPORTANT FOR FRONTEND)
------------------------------------------------------------

Scatter Plot:
x-axis → salary_lakhs
y-axis → predicted_performance
color → Paying_Role

Bar Chart:
value_index (sorted descending)

Roster Table:
selected_players array

Trade Suggestions:
players with lowest value_index

Contract Recommendations:
young players with high value_index


------------------------------------------------------------
6. ASSUMPTIONS
------------------------------------------------------------
- Dataset uploaded as CSV
- Model stored at backend/models/model.pkl
- Predictions stored at data/players_with_predictions.csv
- Salary values in lakhs
- Role values restricted to:
  Batsman
  Bowler
  Allrounder
  Wicketkeeper


------------------------------------------------------------
END OF API CONTRACT
------------------------------------------------------------