Latin for "I feel" — a chess engine that reads your emotions and adapts in real time.
Sentio is a full-stack chess application where you play against a Stockfish AI engine whose difficulty adapts based on your detected emotional state via webcam. It also features an LLM-powered coaching chat for position analysis and encouragement.
- 🎮 Play chess against Stockfish — click-to-move interface with full legal move validation
- 😊 Emotion-aware engine — webcam reads your expressions (calm, focused, frustrated, etc.) and adjusts ELO (1320–3190), depth, and skill level on the fly
- 🤖 LLM coach — ask for advice on any position; get natural-language analysis with clickable "Play [move]" buttons
- 💬 Bot trash talk — the engine taunts or supports you based on your detected emotion
- 🎛️ Manual override — switch to manual emotion selection at any time
| Technology | Purpose |
|---|---|
 |
React framework (App Router) |
 |
UI library |
 |
Type safety |
 |
Styling (v4) |
 |
Game logic & move validation |
 |
Interactive chessboard UI |
 |
Browser-based facial expression recognition |
| Technology | Purpose |
|---|---|
 |
Backend language |
 |
REST API framework |
 |
ASGI server |
 |
Chess engine |
| Technology | Purpose |
|---|---|
 |
Local LLM inference for coaching |
 |
Lightweight face detection & expression analysis |
┌────────────────────────────────────────────────┐
│ Browser │
│ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Chessboard │ │ Coach Chat Panel │ │
│ │ (react-chess │ │ (LLM conversation) │ │
│ │ board) │ │ │ │
│ └──────┬───────┘ └──────────┬─────────────┘ │
│ │ │ │
│ ┌──────┴───────┐ ┌──────────┴─────────────┐ │
│ │ chess.js │ │ /api/coach (Route │ │
│ │ (validation)│ │ Handler) │ │
│ └──────┬───────┘ └──────────┬─────────────┘ │
│ │ │ │
│ ┌──────┴─────────────────────┴─────────────┐ │
│ │ Next.js App (Server Layer) │ │
│ │ Route: /api/bot-move (proxies to │ │
│ │ Python backend) │ │
│ └──────────────────┬──────────────────────┘ │
└─────────────────────┼─────────────────────────┘
│ HTTP
┌─────────────────────┴─────────────────────────┐
│ Python Backend (FastAPI) │
│ ┌──────────────────────────────────────────┐ │
│ │ POST /api/bot-move │ │
│ │ { fen, emotion } → { botMove, profile }│ │
│ └──────────────────┬───────────────────────┘ │
│ │ │
│ ┌──────────────────┴───────────────────────┐ │
│ │ Stockfish Engine │ │
│ │ (per-request isolated instance) │ │
│ └──────────────────────────────────────────┘ │
└────────────────────────────────────────────────┘
- Node.js ≥ 18
- Python ≥ 3.10
- Stockfish engine binary (included at
backend/stockfishfor macOS)
npm installcd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtcp .env.example .env.localEdit .env.local if needed:
| Variable | Default | Description |
|---|---|---|
BOT_MOVE_API_URL |
http://127.0.0.1:8000/api/bot-move |
Python backend endpoint |
COACH_LLM_ENABLED |
true |
Enable/disable LLM coach |
COACH_LLM_BASE_URL |
http://127.0.0.1:1234/v1 |
LM Studio API base URL |
COACH_LLM_MODEL |
qwen/qwen3.5-9b |
Model name in LM Studio |
cd backend
python -m uvicorn main:app --host 0.0.0.0 --port 8000npm run devOpen http://localhost:3000 in your browser.
Note: If you see
ERR_CONNECTION_REFUSED, make sure the Python backend is running on port8000.
| Emotion | Depth | Skill | ELO |
|---|---|---|---|
| 😰 Stressed | 1 | 1 | 1320 |
| 😤 Frustrated | 2 | 3 | 1320 |
| 😌 Calm | 4 | 6 | 1600 |
| 😐 Neutral | 6 | 10 | 2000 |
| 🎯 Focused | 8 | 15 | 2600 |
| 😎 Confident | 10 | 20 | 3190 |
The webcam captures frames every 2.2 seconds, runs TinyFaceDetector + FaceExpressionNet, buffers the last 3 readings, and sets the majority emotion automatically.
chess-agent/
├── app/
│ ├── api/
│ │ ├── bot-move/route.ts # Proxies moves to Python backend
│ │ └── coach/route.ts # LLM coach route handler
│ ├── layout.tsx # Root layout (fonts, metadata, theme)
│ └── page.tsx # SPA — all game UI and logic
├── backend/
│ ├── main.py # FastAPI app — Stockfish bridge
│ ├── requirements.txt # Python dependencies
│ ├── stockfish # Precompiled macOS binary
│ └── venv/ # Python virtual environment
├── public/
│ └── models/ # face-api.js model weights
├── .env.example # Environment variable template
├── package.json
├── tsconfig.json
└── next.config.ts