SNAKESTRAL

Watch Mistral AI play Snake in real-time.

A demonstration of spatial reasoning and planning in large language models, visualised through the classic Snake game.

Quick Start

# 1. Create .env file with your Mistral API key
cp .env.example .env
# Edit .env and add your MISTRAL_API_KEY

# 2. Run the start script
./run.sh

This starts:

• Backend: http://localhost:8000 (FastAPI)
• Frontend: http://localhost:3000 (Next.js)

Manual Setup

Backend

# Create virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Set API key
export MISTRAL_API_KEY=your_key_here

# Run server
uvicorn backend.main:app --reload --port 8000

Frontend

cd frontend

# Install dependencies
bun install

# Run dev server
bun run dev

Why This Project?

Most LLM demos are chatbots. Playing Snake requires:

• Spatial reasoning: Understanding a 2D grid from text
• Planning ahead: Not trapping yourself in corners
• Consistent decisions: Every move matters

Architecture

• Frontend: Next.js app with game board, controls, and AI reasoning display
• Backend: FastAPI server with game engine, Mistral agent, REST + WebSocket APIs
• AI: Mistral API (text and vision models)

Features

• Real-time AI reasoning: Watch the model think through each move
• Text & Vision modes: Toggle between text representation and vision model
• Auto-play: Let the AI run continuously at configurable speed
• Confidence tracking: See how certain the AI is about each decision
• Token counting: Monitor API usage per decision

API Endpoints

Endpoint	Method	Description
/games	POST	Create new game
/games/{id}	GET	Get current state
/games/{id}/ai-step	POST	AI makes one move
/games/{id}/reset	POST	Reset game
/games/{id}/stats	GET	Get statistics
/games/{id}	DELETE	Delete game
/games/{id}/ws	WebSocket	Real-time updates

Game State Format

The AI receives structured text with coordinates:

=== SNAKE GAME STATE ===
Board size: 12x12
Score: 2
Moves taken: 15
Snake length: 5

Snake head position: (8, 7)
Current direction: UP
Apple position: (3, 10)

Apple is 5 cells left, 3 cells up from head

Valid moves (won't immediately die): ['UP', 'LEFT', 'RIGHT']

Board visualisation (H=head, o=body, *=apple, .=empty):

11 . . . . . . . . . . . .
10 . . . * . . . . . . . .
 9 . . . . . . . . . . . .
 8 . . . . . . . . . . . .
 7 . . . . . . . . H . . .
 6 . . . . . . . . o . . .
 5 . . . . . . . . o . . .
 4 . . . . . . . . o . . .
 3 . . . . . . . . o . . .
 2 . . . . . . . . . . . .
 1 . . . . . . . . . . . .
 0 . . . . . . . . . . . .
   0 1 2 3 4 5 6 7 8 9 10 11

Coordinate system: (0,0) is bottom-left, x increases right, y increases up

AI Response Format

{
  "reasoning": "The apple is to the left and down. Moving LEFT brings us closer while keeping escape routes open.",
  "move": "LEFT",
  "confidence": "high"
}

Configuration

Variable	Default	Description
MISTRAL_API_KEY	-	Required API key
Board size	12x12	Configurable via API
Model	mistral-small-latest	small/medium/large

Available Models

Model	ID	Best For
Mistral Small	mistral-small-latest	Fast, cost-effective
Mistral Medium	mistral-medium-latest	Balanced
Mistral Large	mistral-large-latest	Best reasoning
Ministral 3B	ministral-3b-latest	Cheapest, fastest
Ministral 8B	ministral-8b-latest	Small but capable
Codestral	codestral-latest	Code/logic specialist
Pixtral	pixtral-12b-2409	Vision (auto in vision mode)
Pixtral Large	pixtral-large-latest	Best vision model

Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, CSS Modules
• Backend: FastAPI, httpx, Pillow
• AI: Mistral API (text + vision models)

License

MIT