README.md

metadata

title: Chess Engine with Stockfish Integration
emoji: ♟️
colorFrom: green
colorTo: indigo
sdk: docker
sdk_version: latest
app_file: app.py
app_port: 8000
pinned: false

A Python chess engine with Stockfish integration, providing both a command-line interface and a REST API for playing chess against an AI opponent.

Features

• AI Integration: Play against Stockfish, one of the strongest chess engines available
• Multiple Interfaces:
  • Command-line interface for quick games
  • REST API for integration with web or desktop applications
  • Streamlit web interface for graphical gameplay
• Adjustable Difficulty: Six difficulty levels from beginner to master
• Position Analysis: Get detailed evaluation of board positions
• Move Hints: Receive suggestions and explanations for optimal moves
• Notation Support: Works with both UCI (e2e4) and SAN (e4) chess notations
• Game Management: Start, play, analyze, and save games
• Comprehensive Evaluation: Material balance, piece positioning, king safety, mobility, and pawn structure

Requirements

• Python 3.8+
• Stockfish chess engine (optional, but recommended for AI play)
• Dependencies listed in requirements.txt

API Documentation

For information please refer Dockerfile

Example API Usage

Start a new game:

curl -X POST "http://localhost:8000/game/new" \
  -H "Content-Type: application/json" \
  -d '{"player_color": "white", "difficulty": "medium"}'

Make a move:

curl -X POST "http://localhost:8000/game/move" \
  -H "Content-Type: application/json" \
  -d '{"move": "e2e4"}'

Get current game state:

curl -X GET "http://localhost:8000/game/state"

Testing

Run the test suite:

python test/run_tests.py

For more detailed output:

python test/run_tests.py -v

The test suite includes:

• Board representation and move validation tests
• Position evaluation tests
• Game controller tests
• REST API endpoint tests

License

Code

The code in this repository is licensed under the MIT License. See the LICENSE file for details.

Assets

The chess piece images and board square assets are licensed under the Creative Commons Attribution-ShareAlike (CC-BY-SA) license. See the LICENSE-ASSETS.md file for details on attribution and compliance requirements.

Note: If you redistribute this project or create derivative works, you must comply with both licenses - MIT for the code and CC-BY-SA for the assets.