Spaces:

anandu467
/

maia3-chess-api

Sleeping

App Files Files Community

maia3-chess-api / api-spec.md

anandu467

Add tactical vision and game review endpoints

fa5dd4c 3 months ago

preview code

Raw

History Blame Contribute Delete

18.5 kB

	# Maia3 Chess API Specification

	Base URL: `https://<your-space>.hf.space`

	Authentication: All endpoints (except `/api/health` and `GET /api/tactical-vision`) require an `x-api-key` header.

	```
	x-api-key: sk-maia3-2026
	```

	---

	## Endpoints

	\| Method \| Path \| Description \|
	\|--------\|------\|-------------\|
	\| `GET` \| `/api/health` \| Health check \|
	\| `POST` \| `/api/bestmove` \| Best move prediction \|
	\| `POST` \| `/api/analyze-move` \| Analyze a specific move \|
	\| `POST` \| `/api/generate-puzzle` \| Generate a tactical puzzle \|
	\| `GET` \| `/api/categories` \| List puzzle categories \|
	\| `POST` \| `/api/tactical-vision` \| Full tactical vision (model) \|
	\| `GET` \| `/api/tactical-vision` \| Lightweight overlay (no model) \|
	\| `POST` \| `/api/game-review` \| Post-game analysis \|

	---

	## `POST /api/tactical-vision`

	Real-time board overlay during a live game. Helps the human player see move probabilities, tactical threats, and danger assessment.

	### Request

	```json
	{
	"fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1",
	"elo_self": 1500,
	"elo_oppo": 1500,
	"top_n": 10,
	"player_color": "black",
	"bot_last_move": "e2e4",
	"compare_elos": true
	}
	```

	\| Field \| Type \| Required \| Default \| Description \|
	\|-------\|------\|----------\|---------\|-------------\|
	\| `fen` \| string \| yes \| — \| FEN string of the current position \|
	\| `elo_self` \| int \| no \| 1500 \| Player's Elo rating (0–5000) \|
	\| `elo_oppo` \| int \| no \| 1500 \| Opponent's Elo rating (0–5000) \|
	\| `top_n` \| int \| no \| 10 \| Number of top moves to return (1–20) \|
	\| `player_color` \| string \| no \| `"white"` \| Player's side: `"white"` or `"black"` \|
	\| `bot_last_move` \| string \| no \| null \| UCI of opponent's last move to analyze. Use the FEN from before the opponent's move for accurate analysis. \|
	\| `compare_elos` \| bool \| no \| false \| Include Elo comparison across 1200/1500/1800/2100/2400 \|

	### Response

	```json
	{
	"fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1",
	"elo_self": 1500,
	"elo_oppo": 1500,
	"player_side": "black",

	"position": {
	"win_probability": 0.4437,
	"eval_cp": -39,
	"confidence": "confusing",
	"entropy": 3.142,
	"max_probability": 0.425,
	"legal_move_count": 20,
	"danger_level": "low",
	"danger_detail": "Position is relatively straightforward."
	},

	"top_moves": [
	{
	"uci": "e7e5",
	"san": "e5",
	"probability": 0.4247,
	"rank": 1,
	"classification": "good",
	"result_eval_cp": 5,
	"result_win_probability": 0.5063,
	"eval_delta_cp": 44,
	"is_capture": false,
	"is_check": false,
	"is_mate": false,
	"is_tempting_blunder": false,
	"tactical_tags": []
	},
	{
	"uci": "e7e6",
	"san": "e6",
	"probability": 0.1220,
	"rank": 2,
	"classification": "mistake",
	"result_eval_cp": 1,
	"result_win_probability": 0.5013,
	"eval_delta_cp": 40,
	"is_capture": false,
	"is_check": false,
	"is_mate": false,
	"is_tempting_blunder": false,
	"tactical_tags": []
	}
	],

	"threats": {
	"hanging_pieces": [],
	"attacked_pieces": [],
	"underdefended_squares": [],
	"king_safety_concern": false,
	"king_safety_detail": ""
	},

	"tactical_alerts": [
	{
	"type": "hanging_piece",
	"square": "e4",
	"piece": "pawn",
	"description": "Undefended white pawn on e4"
	}
	],

	"bot_last_move": {
	"uci": "e2e4",
	"san": "e4",
	"probability": 0.5200,
	"rank": 1,
	"classification": "excellent"
	},

	"elo_comparison": {
	"1200": {
	"best_move": "e7e5",
	"best_probability": 0.4985,
	"top_moves": [
	{ "uci": "e7e5", "san": "e5", "probability": 0.4985 },
	{ "uci": "e7e6", "san": "e6", "probability": 0.1320 }
	]
	},
	"1500": {
	"best_move": "e7e5",
	"best_probability": 0.4247,
	"top_moves": [
	{ "uci": "e7e5", "san": "e5", "probability": 0.4247 }
	]
	},
	"1800": {
	"best_move": "e7e5",
	"best_probability": 0.3875,
	"top_moves": [
	{ "uci": "e7e5", "san": "e5", "probability": 0.3875 }
	]
	},
	"2100": {
	"best_move": "e7e5",
	"best_probability": 0.3039,
	"top_moves": [
	{ "uci": "e7e5", "san": "e5", "probability": 0.3039 }
	]
	},
	"2400": {
	"best_move": "e7e5",
	"best_probability": 0.2654,
	"top_moves": [
	{ "uci": "e7e5", "san": "e5", "probability": 0.2654 }
	]
	}
	}
	}
	```

	### Field Reference

	#### `position`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `win_probability` \| float \| Maia3's predicted win probability for the side to move (0–1) \|
	\| `eval_cp` \| int \| Centipawn evaluation derived from win probability \|
	\| `confidence` \| string \| `"clear"` (one move dominates), `"complex"` (top move 50–85%), `"confusing"` (no clear favorite), `"terminal"` (game over) \|
	\| `entropy` \| float \| Shannon entropy of the policy distribution over legal moves \|
	\| `max_probability` \| float \| Probability of the top move \|
	\| `legal_move_count` \| int \| Number of legal moves \|
	\| `danger_level` \| string \| `"low"`, `"moderate"`, or `"high"` — how treacherous the position is \|
	\| `danger_detail` \| string \| Human-readable explanation of the danger level \|

	#### `top_moves[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `uci` \| string \| Move in UCI format \|
	\| `san` \| string \| Move in Standard Algebraic Notation \|
	\| `probability` \| float \| Maia3's predicted probability a human at this Elo plays this move \|
	\| `rank` \| int \| Rank among all legal moves (1 = most likely) \|
	\| `classification` \| string \| `"excellent"` (≥60%), `"good"` (≥30%), `"inaccuracy"` (≥15%), `"mistake"` (≥5%), `"blunder"` (<5%) \|
	\| `result_eval_cp` \| int \| Evaluation after playing this move (centipawns) \|
	\| `result_win_probability` \| float \| Win probability after playing this move \|
	\| `eval_delta_cp` \| int \| Change in evaluation: positive = improves position, negative = worsens \|
	\| `is_capture` \| bool \| Whether the move is a capture \|
	\| `is_check` \| bool \| Whether the move gives check \|
	\| `is_mate` \| bool \| Whether the move delivers checkmate \|
	\| `is_tempting_blunder` \| bool \| High probability (≥15%) but leads to a significantly worse position (eval_delta < -100cp) \|
	\| `tactical_tags` \| string[] \| Tactical motifs detected: `"fork"`, `"pin"`, `"skewer"`, `"discovered_attack"`, `"hanging_piece"`, `"trapped_piece"`, `"sacrifice"`, `"zwischenzug"`, `"king_safety"` \|

	#### `threats`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `hanging_pieces` \| string[] \| Squares of opponent's undefended pieces \|
	\| `attacked_pieces` \| string[] \| Squares of your attacked but undefended pieces \|
	\| `underdefended_squares` \| string[] \| Squares where attacker value exceeds defender value \|
	\| `king_safety_concern` \| bool \| Whether there's a king safety issue \|
	\| `king_safety_detail` \| string \| Description of the king safety concern \|

	#### `tactical_alerts[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `type` \| string \| `"hanging_piece"`, `"attacked_piece"`, `"in_check"`, `"fork_opportunity"` \|
	\| `square` \| string \| Square name (e.g., `"e4"`) \|
	\| `piece` \| string \| Piece type (e.g., `"pawn"`, `"knight"`) \|
	\| `description` \| string \| Human-readable description \|

	#### `bot_last_move`

	Only present when `bot_last_move` is provided in the request.

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `uci` \| string \| The move in UCI format \|
	\| `san` \| string \| The move in SAN \|
	\| `probability` \| float \| How likely Maia3 thought a human at this Elo would play this move \|
	\| `rank` \| int \| Rank among all legal moves \|
	\| `classification` \| string \| Move quality classification \|

	#### `elo_comparison`

	Only present when `compare_elos: true`. Keys are Elo levels (1200, 1500, 1800, 2100, 2400).

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `best_move` \| string \| Top move at this Elo \|
	\| `best_probability` \| float \| Probability of the top move \|
	\| `top_moves` \| array \| Top 5 moves at this Elo \|

	---

	## `GET /api/tactical-vision`

	Lightweight chess-only overlay — no model inference. Use for fast board overlays showing threats and tactical alerts.

	### Parameters

	\| Parameter \| Type \| Required \| Default \| Description \|
	\|-----------\|------\|----------\|---------\|-------------\|
	\| `fen` \| string \| yes \| — \| FEN string \|
	\| `player_color` \| string \| no \| `"white"` \| Player's side \|

	### Response

	```json
	{
	"fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1",
	"player_side": "black",
	"threats": {
	"hanging_pieces": ["e4"],
	"attacked_pieces": [],
	"underdefended_squares": [],
	"king_safety_concern": false,
	"king_safety_detail": ""
	},
	"tactical_alerts": [
	{
	"type": "hanging_piece",
	"square": "e4",
	"piece": "pawn",
	"description": "Undefended white pawn on e4"
	}
	],
	"board_info": {
	"turn": "black",
	"fullmove": 1,
	"halfmove_clock": 0,
	"is_check": false,
	"is_game_over": false,
	"piece_count": 31
	}
	}
	```

	---

	## `POST /api/game-review`

	Post-game analysis. Reviews every move in a completed game, calculates consistency, identifies blunder patterns, and provides recommendations.

	### Request

	Provide either `pgn` or `moves`:

	Option A: PGN
	```json
	{
	"pgn": "[Event \"Casual\"]\n[White \"Player1\"]\n[Black \"Player2\"]\n[Result \"1-0\"]\n[WhiteElo \"1500\"]\n[BlackElo \"1480\"]\n\n1. e4 e5 2. Bc4 Nc6 3. Qh5 Nf6 4. Qxf7# 1-0",
	"elo_white": 1500,
	"elo_black": 1480
	}
	```

	Option B: Move list
	```json
	{
	"moves": ["e2e4", "e7e5", "f1c4", "b8c6", "d1h5", "g8f6", "h5f7"],
	"starting_fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
	"elo_white": 1500,
	"elo_black": 1500
	}
	```

	\| Field \| Type \| Required \| Default \| Description \|
	\|-------\|------\|----------\|---------\|-------------\|
	\| `pgn` \| string \| one of pgn/moves \| null \| PGN string of the game \|
	\| `moves` \| string[] \| one of pgn/moves \| null \| List of UCI moves \|
	\| `starting_fen` \| string \| no \| starting position \| Starting FEN \|
	\| `elo_white` \| int \| no \| 1500 \| White player's Elo \|
	\| `elo_black` \| int \| no \| 1500 \| Black player's Elo \|

	### Response

	```json
	{
	"game_info": {
	"white": "Player1",
	"black": "Player2",
	"result": "1-0",
	"elo_white": 1500,
	"elo_black": 1480,
	"total_moves": 7,
	"opening": ""
	},

	"summary": {
	"consistency_score": 0.34,
	"consistency_label": "Below your usual level",
	"average_move_probability": 0.34,
	"blunder_count": 1,
	"mistake_count": 1,
	"inaccuracy_count": 2,
	"good_count": 1,
	"excellent_count": 2,
	"missed_opportunities": 0
	},

	"phase_breakdown": {
	"opening": {
	"moves": 7,
	"consistency_score": 0.34,
	"average_probability": 0.34,
	"blunders": 1,
	"mistakes": 1,
	"inaccuracies": 2,
	"good": 1,
	"excellent": 2,
	"label": "Opening technique needs work"
	},
	"middlegame": {
	"moves": 0,
	"consistency_score": 0.0,
	"average_probability": 0.0,
	"blunders": 0,
	"mistakes": 0,
	"inaccuracies": 0,
	"good": 0,
	"excellent": 0,
	"label": ""
	},
	"endgame": {
	"moves": 0,
	"consistency_score": 0.0,
	"average_probability": 0.0,
	"blunders": 0,
	"mistakes": 0,
	"inaccuracies": 0,
	"good": 0,
	"excellent": 0,
	"label": ""
	}
	},

	"moves": [
	{
	"move_number": 1,
	"side": "white",
	"uci": "e2e4",
	"san": "e4",
	"fen_before": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
	"fen_after": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1",
	"probability": 0.6400,
	"rank": 1,
	"classification": "excellent",
	"eval_before": 0,
	"eval_after": -18,
	"eval_delta": -18,
	"best_move": "e2e4",
	"best_move_probability": 0.6400,
	"is_capture": false,
	"is_check": false,
	"tactical_tags": [],
	"phase": "opening"
	}
	],

	"blunder_genealogy": [
	{
	"blunder_move": 4,
	"root_cause_move": 2,
	"explanation": "The blunder at move 4 was likely caused by difficulties that started around move 2. The position became complex after Bc4."
	}
	],

	"missed_opportunities": [
	{
	"move_number": 3,
	"side": "white",
	"played_move": "Qh5",
	"best_move": "Nf3",
	"eval_delta_missed": 150,
	"explanation": "Nf3 would have been much stronger, improving the position by 150 centipawns."
	}
	],

	"danger_positions": [
	{
	"move_number": 3,
	"side": "black",
	"fen": "r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/8/PPPP1PPP/RNBQK1NR b KQkq - 1 3",
	"danger_level": "moderate",
	"danger_detail": "Position was complex with low probability for the played move.",
	"player_response": "Nf6 (inaccuracy)",
	"correct_response": "Qe7"
	}
	],

	"eval_trajectory": [
	{ "move": 1, "side": "white", "eval": -18 },
	{ "move": 1, "side": "black", "eval": -5 },
	{ "move": 2, "side": "white", "eval": -38 },
	{ "move": 2, "side": "black", "eval": 52 },
	{ "move": 3, "side": "white", "eval": -22 },
	{ "move": 3, "side": "black", "eval": 493 },
	{ "move": 4, "side": "white", "eval": 1000 }
	],

	"tactical_patterns": {
	"missed_forks": 1,
	"missed_pins": 0,
	"missed_skewers": 0,
	"missed_discovered_attacks": 0,
	"hung_pieces": 0,
	"walked_into_tactics": 0,
	"most_common_mistake": "fork (1 occurrences)"
	},

	"recommendations": [
	"Focus on opening technique — your consistency drops significantly in openings",
	"Work on fork recognition — you missed opportunities to fork pieces",
	"Review your opening repertoire — low consistency suggests unfamiliar positions"
	]
	}
	```

	### Field Reference

	#### `summary`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `consistency_score` \| float \| Average move probability across all moves (0–1) \|
	\| `consistency_label` \| string \| Human-readable label: `"Excellent performance"`, `"Playing to your rating"`, `"Below your usual level"`, `"Significantly underperforming"` \|
	\| `average_move_probability` \| float \| Same as consistency_score \|
	\| `blunder_count` \| int \| Number of blunders (<5% probability) \|
	\| `mistake_count` \| int \| Number of mistakes (5–15%) \|
	\| `inaccuracy_count` \| int \| Number of inaccuracies (15–30%) \|
	\| `good_count` \| int \| Number of good moves (30–60%) \|
	\| `excellent_count` \| int \| Number of excellent moves (≥60%) \|
	\| `missed_opportunities` \| int \| Positions where eval dropped >100cp and a better move existed \|

	#### `phase_breakdown`

	Keys: `"opening"` (moves 1–10), `"middlegame"` (moves 11–30), `"endgame"` (move 31+ or ≤8 pieces).

	Each phase has the same fields as `summary` plus a `label` describing performance.

	#### `moves[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `move_number` \| int \| Full move number \|
	\| `side` \| string \| `"white"` or `"black"` \|
	\| `uci` \| string \| Move in UCI format \|
	\| `san` \| string \| Move in SAN \|
	\| `fen_before` \| string \| FEN before the move \|
	\| `fen_after` \| string \| FEN after the move \|
	\| `probability` \| float \| Maia3's predicted probability \|
	\| `rank` \| int \| Rank among legal moves \|
	\| `classification` \| string \| Move quality \|
	\| `eval_before` \| int \| Evaluation before the move (centipawns) \|
	\| `eval_after` \| int \| Evaluation after the move (centipawns) \|
	\| `eval_delta` \| int \| Change in evaluation \|
	\| `best_move` \| string \| Maia3's top predicted move \|
	\| `best_move_probability` \| float \| Probability of the best move \|
	\| `is_capture` \| bool \| Whether the move is a capture \|
	\| `is_check` \| bool \| Whether the move gives check \|
	\| `tactical_tags` \| string[] \| Tactical motifs detected \|
	\| `phase` \| string \| Game phase: `"opening"`, `"middlegame"`, `"endgame"` \|

	#### `blunder_genealogy[]`

	Traces each blunder back to its root cause.

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `blunder_move` \| int \| Move number of the blunder \|
	\| `root_cause_move` \| int \| Move number where difficulties began \|
	\| `explanation` \| string \| Human-readable explanation \|

	#### `missed_opportunities[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `move_number` \| int \| Move number \|
	\| `side` \| string \| `"white"` or `"black"` \|
	\| `played_move` \| string \| SAN of the played move \|
	\| `best_move` \| string \| UCI of the better move \|
	\| `eval_delta_missed` \| int \| Centipawns lost by not playing the best move \|
	\| `explanation` \| string \| Human-readable explanation \|

	#### `danger_positions[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `move_number` \| int \| Move number \|
	\| `side` \| string \| `"white"` or `"black"` \|
	\| `fen` \| string \| FEN of the dangerous position \|
	\| `danger_level` \| string \| `"high"` or `"moderate"` \|
	\| `danger_detail` \| string \| Description of the danger \|
	\| `player_response` \| string \| What the player played (with classification) \|
	\| `correct_response` \| string \| The better move \|

	#### `eval_trajectory[]`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `move` \| int \| Move number \|
	\| `side` \| string \| `"white"` or `"black"` \|
	\| `eval` \| int \| Evaluation in centipawns after the move \|

	#### `tactical_patterns`

	\| Field \| Type \| Description \|
	\|-------\|------\|-------------\|
	\| `missed_forks` \| int \| Number of missed fork opportunities \|
	\| `missed_pins` \| int \| Number of missed pins \|
	\| `missed_skewers` \| int \| Number of missed skewers \|
	\| `missed_discovered_attacks` \| int \| Number of missed discovered attacks \|
	\| `hung_pieces` \| int \| Number of times a piece was hung \|
	\| `walked_into_tactics` \| int \| Number of times the player walked into a tactic \|
	\| `most_common_mistake` \| string \| Description of the most frequent mistake type \|

	#### `recommendations`

	Array of strings with actionable improvement suggestions based on the analysis.

	---

	## Error Responses

	All endpoints return errors in this format:

	```json
	{
	"error": "Description of the error"
	}
	```

	\| Status Code \| Meaning \|
	\|-------------\|---------\|
	\| 400 \| Bad request (invalid FEN, missing fields, invalid move) \|
	\| 401 \| Unauthorized (missing or invalid API key) \|
	\| 405 \| Method not allowed \|
	\| 500 \| Internal server error \|
	\| 503 \| Model unavailable (still loading or failed) \|