{"id":32388673,"url":"https://github.com/thecodealchemy/chess_eval_llm_script","last_synced_at":"2025-10-25T03:54:51.767Z","repository":{"id":314582189,"uuid":"1044488921","full_name":"thecodealchemy/Chess_Eval_LLM_Script","owner":"thecodealchemy","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-13T10:07:53.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-13T12:45:49.557Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thecodealchemy.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-25T19:01:18.000Z","updated_at":"2025-09-13T10:07:56.000Z","dependencies_parsed_at":"2025-09-14T00:45:26.310Z","dependency_job_id":null,"html_url":"https://github.com/thecodealchemy/Chess_Eval_LLM_Script","commit_stats":null,"previous_names":["thecodealchemy/chess_eval_llm_script"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thecodealchemy/Chess_Eval_LLM_Script","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodealchemy%2FChess_Eval_LLM_Script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodealchemy%2FChess_Eval_LLM_Script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodealchemy%2FChess_Eval_LLM_Script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodealchemy%2FChess_Eval_LLM_Script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thecodealchemy","download_url":"https://codeload.github.com/thecodealchemy/Chess_Eval_LLM_Script/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodealchemy%2FChess_Eval_LLM_Script/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280901444,"owners_count":26410586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-25T03:54:50.606Z","updated_at":"2025-10-25T03:54:51.758Z","avatar_url":"https://github.com/thecodealchemy.png","language":"Python","readme":"# Chess Game Analysis App\n\nA full-stack application for analyzing chess games with engine evaluations and optional AI explanations. Upload PGN files, get move-by-move analysis, and browse your game history with an interactive chess board interface.\n\n## Features\n\n- **PGN Upload**: Upload chess games in PGN format via drag-and-drop or file selection\n- **Engine Analysis**: Get position evaluations using Lichess Cloud Evaluation API\n- **Interactive Chess Board**: View games with a responsive chessboard component\n- **Move Navigation**: Step through games move by move with analysis\n- **Game Management**: Browse, analyze, and delete uploaded games\n- **AI Explanations**: Optional integration with LLM APIs for human-readable move explanations\n- **Responsive Design**: Works on desktop and mobile devices\n\n## Technology Stack\n\n### Backend\n\n- **FastAPI**: Modern Python web framework\n- **MongoDB**: Document database for storing games and analysis\n- **Python Chess**: Chess game processing and PGN parsing\n- **Motor**: Async MongoDB driver\n- **Lichess API**: Cloud-based chess engine evaluation\n\n### Frontend\n\n- **React 18**: Modern React with hooks\n- **Vite**: Fast build tool and development server\n- **React Router**: Client-side routing\n- **TanStack Query**: Data fetching and caching\n- **React Chessboard**: Interactive chess board component\n- **Chess.js**: Chess game logic and validation\n- **Axios**: HTTP client for API calls\n\n### Infrastructure\n\n- **Docker**: Containerized deployment\n- **Docker Compose**: Multi-service orchestration\n\n## Project Structure\n\n```\n├── client/                 # React frontend\n│   ├── src/\n│   │   ├── components/     # Reusable UI components\n│   │   ├── pages/          # Page components\n│   │   ├── utils/          # API utilities\n│   │   ├── App.jsx         # Main App component\n│   │   └── main.jsx        # Entry point\n│   ├── public/             # Static assets\n│   ├── package.json        # Frontend dependencies\n│   ├── vite.config.js      # Vite configuration\n│   └── Dockerfile          # Frontend container\n├── server/                 # FastAPI backend\n│   ├── app/\n│   │   ├── main.py         # FastAPI application\n│   │   ├── routes.py       # API endpoints\n│   │   ├── models.py       # Pydantic models\n│   │   ├── database.py     # MongoDB connection\n│   │   └── chess_analyzer.py # Chess analysis logic\n│   ├── requirements.txt    # Python dependencies\n│   ├── .env.example        # Environment variables template\n│   └── Dockerfile          # Backend container\n├── docker-compose.yml      # Multi-service setup\n└── README.md              # This file\n```\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n1. **Clone the repository**\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd chess-analysis-app\n   ```\n\n2. **Start all services**\n\n   ```bash\n   docker-compose up -d\n   ```\n\n3. **Access the application**\n   - Frontend: http://localhost:3000\n   - Backend API: http://localhost:8000\n   - API Documentation: http://localhost:8000/docs\n\n### Manual Setup\n\n#### Prerequisites\n\n- Python 3.9+\n- Node.js 18+\n- MongoDB (local or cloud instance)\n\n#### Backend Setup\n\n1. **Navigate to server directory**\n\n   ```bash\n   cd server\n   ```\n\n2. **Create virtual environment**\n\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Set up environment variables**\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your MongoDB connection string\n   ```\n\n5. **Start the backend**\n   ```bash\n   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n   ```\n\n#### Frontend Setup\n\n1. **Navigate to client directory**\n\n   ```bash\n   cd client\n   ```\n\n2. **Install dependencies**\n\n   ```bash\n   npm install\n   ```\n\n3. **Start development server**\n   ```bash\n   npm run dev\n   ```\n\n#### MongoDB Setup\n\n**Option 1: Local MongoDB**\n\n- Install MongoDB locally\n- Start MongoDB service\n- Use connection string: `mongodb://localhost:27017`\n\n**Option 2: MongoDB Atlas (Cloud)**\n\n- Create free cluster at mongodb.com\n- Get connection string from Atlas dashboard\n- Update `MONGODB_URL` in `.env` file\n\n**Option 3: Docker**\n\n```bash\ndocker run -d -p 27017:27017 --name chess-mongo \\\n  -e MONGO_INITDB_ROOT_USERNAME=admin \\\n  -e MONGO_INITDB_ROOT_PASSWORD=password \\\n  mongo:7.0\n```\n\n## API Endpoints\n\n### Games\n\n- `POST /api/v1/games/upload` - Upload a new PGN game\n- `POST /api/v1/upload_pgn` - Upload PGN string and get parsed game data\n- `POST /api/v1/analyse_move` - Analyze a specific move with AI explanation\n- `GET /api/v1/games` - Get list of games\n- `GET /api/v1/games/{game_id}` - Get specific game details\n- `DELETE /api/v1/games/{game_id}` - Delete a game\n\n### Analysis\n\n- `POST /api/v1/games/{game_id}/analyze` - Analyze a game\n- `GET /api/v1/games/{game_id}/analysis` - Get game analysis results\n\n### System\n\n- `GET /` - API information\n- `GET /health` - Health check\n- `GET /docs` - Interactive API documentation\n\n## Usage\n\n### 1. Upload a Game\n\n- Navigate to the Upload page\n- Enter a title for your game\n- Either drag and drop a PGN file or paste PGN content directly\n- Click \"Upload Game\"\n\n### 2. Analyze a Game\n\n- Go to the game detail page\n- Click \"Analyze Game\" for engine evaluation\n- Click \"Analyze with AI\" for additional explanations (requires API key)\n\n### 3. Review Analysis\n\n- Use the chess board to visualize positions\n- Navigate through moves using the control buttons\n- View evaluations, best moves, and explanations in the analysis panel\n\n### 4. Manage Games\n\n- Browse all games in the Games list\n- Delete games you no longer need\n- Filter and search through your game history\n\n### 5. Using the /upload_pgn API Endpoint\n\nThe `/upload_pgn` endpoint allows you to upload PGN strings directly and get parsed game data:\n\n**Request:**\n\n```json\n{\n  \"pgn\": \"[Event \\\"Test Game\\\"]\\n[White \\\"Alice\\\"]\\n[Black \\\"Bob\\\"]\\n[Result \\\"1-0\\\"]\\n\\n1. e4 e5 2. Nf3 1-0\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"game_id\": \"507f1f77bcf86cd799439011\",\n  \"metadata\": {\n    \"white_player\": \"Alice\",\n    \"black_player\": \"Bob\",\n    \"event\": \"Test Game\",\n    \"result\": \"1-0\",\n    \"date\": null,\n    \"site\": null,\n    \"round\": null,\n    \"eco\": null\n  },\n  \"moves\": [\n    {\n      \"move_number\": 0,\n      \"san\": \"Starting position\",\n      \"fen\": \"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1\"\n    },\n    {\n      \"move_number\": 1,\n      \"san\": \"e4\",\n      \"fen\": \"rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1\"\n    },\n    {\n      \"move_number\": 2,\n      \"san\": \"e5\",\n      \"fen\": \"rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6 0 2\"\n    },\n    {\n      \"move_number\": 3,\n      \"san\": \"Nf3\",\n      \"fen\": \"rnbqkbnr/pppp1ppp/8/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 2\"\n    }\n  ]\n}\n```\n\n### 6. Using the /analyse_move API Endpoint\n\nThe `/analyse_move` endpoint provides detailed analysis for specific moves using Lichess Cloud Eval and Groq LLM:\n\n**Request:**\n\n```json\n{\n  \"game_id\": \"507f1f77bcf86cd799439011\",\n  \"move_index\": 5\n}\n```\n\n**Response:**\n\n```json\n{\n  \"eval\": 0.75,\n  \"explanation\": \"White gains a slight advantage with this central pawn advance, controlling key squares and preparing piece development.\",\n  \"variations\": [\"d4 exd4 Nxd4 Nc6 Nxc6\"]\n}\n```\n\n**Features:**\n\n- **Lichess Cloud Evaluation**: Professional-grade position analysis\n- **AI Explanations**: Human-readable move explanations via Groq LLM\n- **MongoDB Caching**: Results are cached to avoid repeated API calls\n- **Move Navigation**: Analyze any position in a game by move index\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the server directory:\n\n```env\n# Required: MongoDB connection\nMONGODB_URL=mongodb://localhost:27017\n\n# Optional: LLM API keys for explanations\nGROQ_API_KEY=your_groq_api_key_here\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\n### Frontend Configuration\n\nThe frontend is configured via `vite.config.js` to proxy API requests to the backend during development.\n\n## Development\n\n### Running Tests\n\n**Backend Tests**\n\n```bash\ncd server\npytest tests/\n```\n\n**Frontend Tests**\n\n```bash\ncd client\nnpm test\n```\n\n### Code Style\n\n**Backend**\n\n- Follow PEP 8 guidelines\n- Use type hints where appropriate\n- Document functions and classes\n\n**Frontend**\n\n- Use ESLint configuration\n- Follow React best practices\n- Use functional components with hooks\n\n### Adding Features\n\n1. **Backend**: Add new endpoints in `routes.py`, models in `models.py`\n2. **Frontend**: Create components in `components/`, pages in `pages/`\n3. **Database**: Add new collections or fields as needed\n\n## Deployment\n\n### Production Deployment\n\n1. **Update environment variables**\n\n   - Set production MongoDB URL\n   - Add API keys for LLM services\n   - Configure CORS origins\n\n2. **Build and deploy with Docker**\n\n   ```bash\n   docker-compose -f docker-compose.prod.yml up -d\n   ```\n\n3. **Or deploy separately**\n   - Backend: Deploy to services like Railway, Heroku, or AWS\n   - Frontend: Deploy to Vercel, Netlify, or similar\n   - Database: Use MongoDB Atlas or managed database service\n\n### Environment-Specific Configurations\n\nCreate different Docker Compose files or environment configurations for:\n\n- Development (`docker-compose.yml`)\n- Production (`docker-compose.prod.yml`)\n- Testing (`docker-compose.test.yml`)\n\n## Troubleshooting\n\n### Common Issues\n\n**Connection Errors**\n\n- Check MongoDB connection string\n- Ensure MongoDB service is running\n- Verify network connectivity between services\n\n**API Errors**\n\n- Check backend logs: `docker-compose logs backend`\n- Verify environment variables are set\n- Test API endpoints directly at `/docs`\n\n**Frontend Issues**\n\n- Clear browser cache and local storage\n- Check console for JavaScript errors\n- Verify API proxy configuration in Vite\n\n**Analysis Not Working**\n\n- Check internet connection (Lichess API access required)\n- Verify PGN format is valid\n- Review backend logs for analysis errors\n\n### Debugging\n\n**Enable Debug Mode**\n\n```bash\n# Backend\nuvicorn app.main:app --reload --log-level debug\n\n# Frontend\nnpm run dev -- --debug\n```\n\n**View Logs**\n\n```bash\n# Docker logs\ndocker-compose logs -f backend\ndocker-compose logs -f frontend\n\n# Database logs\ndocker-compose logs -f mongodb\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- [Lichess](https://lichess.org) for providing free cloud evaluation API\n- [Chess.js](https://github.com/jhlywa/chess.js) for chess game logic\n- [React Chessboard](https://github.com/Clariity/react-chessboard) for the interactive board component\n- [FastAPI](https://fastapi.tiangolo.com/) for the excellent Python web framework\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodealchemy%2Fchess_eval_llm_script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecodealchemy%2Fchess_eval_llm_script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodealchemy%2Fchess_eval_llm_script/lists"}