Leonard
55cb932447
Build and publish Docker image to GHCR / build-and-push (push) Has been cancelled
- Merged stefan-kp/chess_tutor into chess-project with full feature set - Preserved Hermes agent files (agents/, .gitea/, AGENTS.md) - Added OpenRouter abstraction layer (src/lib/openrouter.ts) - Created ModelSelector dropdown component with 9 models - Updated API routes (chat + opening explanation) to use OpenRouter - Updated useTutorChat to route through OpenRouter API - Updated onboarding and API key input for OpenRouter - Created tasks.md with sprint 1 plan - Updated README with new architecture details
93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
# ♞ Chess Tutor
|
|
|
|
AI-powered chess tutor with Stockfish analysis. Play against customizable AI coach personalities. Supports multiple AI models via OpenRouter.
|
|
|
|
## Features
|
|
|
|
- **Play chess** against Stockfish with an AI coach giving you real-time feedback
|
|
- **AI personalities** — choose from Hype Streamer, Professional Coach, Russian Grandmaster, and more
|
|
- **Model selector** — switch between Gemini, Claude, GPT, Grok, DeepSeek, and Llama
|
|
- **Opening trainer** — practice specific openings with move validation
|
|
- **Tactical puzzles** — test your pattern recognition
|
|
- **Game analysis** — get AI feedback on your games
|
|
- **Multi-language** — English, German, French, Italian, Polish
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install
|
|
npm install
|
|
|
|
# Run
|
|
npm run dev
|
|
```
|
|
|
|
Open **http://localhost:3050** — the onboarding page will walk you through setup.
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend:** Next.js 16, React 19, TypeScript, Tailwind CSS 4
|
|
- **Chess:** chess.js, react-chessboard
|
|
- **Engine:** Stockfish (in-browser via stockfish.js WASM)
|
|
- **AI:** OpenRouter API (multi-provider: Gemini, Claude, GPT, Grok, DeepSeek, Llama)
|
|
- **Mobile:** Capacitor (iOS/Android)
|
|
|
|
## Environment
|
|
|
|
Copy `.env.example` to `.env.local`:
|
|
```
|
|
OPENROUTER_API_KEY=sk-or-...
|
|
NEXT_PUBLIC_DEFAULT_MODEL=google/gemini-2.5-flash
|
|
```
|
|
|
|
Or enter your API key through the UI on first launch.
|
|
|
|
## Hermes Agent Integration
|
|
|
|
This repo includes Hermes agent role files for multi-agent development:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `AGENTS.md` | High-level project guidance for Hermes agents |
|
|
| `tasks.md` | Sprint tasks with Now / Next / Backlog |
|
|
| `agents/HA_*.md` | Role-specific instructions (Architect, Coder, DevOps, etc.) |
|
|
| `.gitea/` | Issue and PR templates |
|
|
| `docs/WORKFLOW.md` | Collaboration workflow |
|
|
|
|
## Available AI Models
|
|
|
|
| Model | Provider |
|
|
|-------|----------|
|
|
| Gemini 2.5 Flash | Google |
|
|
| Gemini 2.5 Pro | Google |
|
|
| Claude Sonnet 4 | Anthropic |
|
|
| Claude 3.5 Haiku | Anthropic |
|
|
| GPT-4o | OpenAI |
|
|
| GPT-4o Mini | OpenAI |
|
|
| DeepSeek Chat | DeepSeek |
|
|
| Grok 3 | xAI |
|
|
| Llama 3.1 70B | Meta |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── app/ # Next.js pages and API routes
|
|
│ ├── api/v1/llm/ # OpenRouter-backed AI endpoints
|
|
│ ├── learning/ # Opening trainer and tactics
|
|
│ ├── onboarding/ # First-run setup flow
|
|
│ └── settings/ # Game settings
|
|
├── components/ # React components
|
|
│ ├── ChessGame.tsx # Main game component
|
|
│ ├── Tutor.tsx # AI tutor chat panel
|
|
│ ├── ModelSelector.tsx # Model dropdown (OpenRouter)
|
|
│ └── ...
|
|
└── lib/
|
|
├── openrouter.ts # OpenRouter abstraction layer
|
|
├── server/tutorPrompt.ts # Prompt templates
|
|
└── engine/ # Stockfish integration
|
|
```
|
|
|
|
## Credits
|
|
|
|
Based on [stefan-kp/chess_tutor](https://github.com/stefan-kp/chess_tutor) — licensed under GPL-3.0. |