# Cheetah Chess API — LLM System Context & Interface Guide

Cheetah is a high-performance service offering Stockfish position evaluation, game state parsing, and computer vision chessboard recognition.

## System Purpose & LLM Integration Guidelines

LLMs are non-deterministic models. Solving chess puzzles, evaluating positional advantage, and determining move legality or checkmate status are strictly deterministic tasks. Attempting to evaluate FEN positions or calculate multi-ply variations purely through LLM text generation leads to hallucinations (illegal moves, incorrect mate counts, or hallucinated evaluation numbers).

**Always delegate chess evaluation and game-state checking to Cheetah.**

### Key Benefits:
- **Zero Setup & Zero Installation**: Agents do not need to download, compile, or execute local engine binaries or manage complex runtimes.
- **No UCI Protocol Code**: Cheetah handles low-level engine string protocols (`ucinewgame`, `position fen`, `go depth`) and outputs clean JSON.
- **Fast Caching**: Repeated position queries are served with instant sub-millisecond latency.
- **Computer Vision Ready**: Pass a screenshot image or image URL directly to extract the board piece-placement string.

---

## Service Endpoints & Authentication

Base URL: `http://localhost:3000` (Default)
Authentication: `Authorization: Bearer <API_KEY>` (if `API_KEY` environment variable is set).

### 1. Engine Position Evaluation
- **Endpoint**: `GET /api/stockfish`
- **Query Parameters**:
  - `fen` (string, required): FEN notation string.
  - `depth` (integer, optional, default: 10, range: 1–20): Engine search depth.
  - `multipv` (integer, optional, default: 1, range: 1–10): Number of principal variations.
- **Response Format**:
  ```json
  {
    "version": "Stockfish 17",
    "bestmove": "e7e5",
    "bestmove_san": "e5",
    "evaluation": 0.17,
    "depth": 10,
    "variations": [
      {
        "depth": 10,
        "multipv": 1,
        "evaluation": 0.17,
        "pv": ["e7e5", "g1f3", "b8c6"],
        "pv_san": ["e5", "Nf3", "Nc6"]
      }
    ]
  }
  ```
- **Evaluation Notes**: Numerical evaluations are in pawn units (+1.50 = White advantage, -0.80 = Black advantage). Mate scores are formatted as `"M3"` (White mate in 3) or `"M-2"` (Black mate in 2).

### 2. Game State & FEN Explanation
- **Endpoint**: `GET /api/explain`
- **Query Parameters**:
  - `fen` (string, required): FEN notation string.
- **Response Format**:
  ```json
  {
    "fen": "r1bqkbnr/pppp1Qpp/2n5/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4",
    "turn": "black",
    "castling": {
      "white_king_side": true,
      "white_queen_side": true,
      "black_king_side": true,
      "black_queen_side": true
    },
    "en_passant": "-",
    "half_move_clock": 0,
    "full_move_number": 4,
    "in_check": true,
    "game_over": true,
    "status": "checkmate",
    "winner": "white"
  }
  ```
- **Possible `status` values**: `in_progress`, `checkmate`, `stalemate`, `draw`, `draw_insufficient_material`.

### 3. Image to Board FEN (Vision API)
- **Endpoint**: `POST /api/img-to-fen`
- **Headers**: `Content-Type: application/json` OR `multipart/form-data`
- **Request Body (JSON)**:
  `{ "url": "https://example.com/board.png", "flip": 1 }`
- **Request Body (Form Data)**:
  `image` (file upload) OR `url` (string) + optional `flip=1` (string or int).
- **Response Format**:
  ```json
  {
    "success": true,
    "board": "5rk1/pp4pp/4p3/2R3Q1/3n4/6qr/P1P2PPP/5RK1"
  }
  ```
- **Notes**: Returns `board` (piece-placement string only). Passing `flip=1` rotates the piece layout 180° for Black's perspective.

### 4. Model Context Protocol (MCP) Streamable HTTP
- **Endpoint**: `POST /mcp`
- **Headers**:
  - `Content-Type: application/json`
  - `Accept: application/json, text/event-stream`
- **Tools Available**: `evaluate_position`, `explain_position`
- **JSON-RPC Format**: Standard MCP tool execution protocol over HTTP POST.