Metadata-Version: 2.4
Name: chessplaza
Version: 0.1.1
Summary: A virtual chess plaza: AI chess hustlers with distinct personalities, played by Claude agents over any UCI engine, in your terminal.
Author-email: Alex Myodov <amyodov@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/AnglerfishChess/chessplaza
Project-URL: Repository, https://github.com/AnglerfishChess/chessplaza
Project-URL: Issues, https://github.com/AnglerfishChess/chessplaza/issues
Keywords: chess,AI,LLM,Claude,agents,chess hustler,game,anthropic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claude-agent-sdk>=0.2.152
Requires-Dist: click<9.0.0,>=8.1.8
Requires-Dist: esca~=0.4.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.6.0; extra == "gui"
Provides-Extra: voice
Requires-Dist: edge-tts>=7.0.0; extra == "voice"
Requires-Dist: google-genai>=1.0.0; extra == "voice"
Requires-Dist: miniaudio>=1.60; extra == "voice"
Dynamic: license-file

# chessplaza

[![PyPI](https://img.shields.io/pypi/v/chessplaza)](https://pypi.org/project/chessplaza/)
[![Python](https://img.shields.io/pypi/pyversions/chessplaza)](https://pypi.org/project/chessplaza/)
[![CI](https://github.com/AnglerfishChess/chessplaza/actions/workflows/ci.yml/badge.svg)](https://github.com/AnglerfishChess/chessplaza/actions/workflows/ci.yml)
[![Publish](https://github.com/AnglerfishChess/chessplaza/actions/workflows/publish.yml/badge.svg)](https://github.com/AnglerfishChess/chessplaza/actions/workflows/publish.yml)
[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

*A park, a few benches, a pond, and some deep-sea creature that has learned chess from listening to trash talk.*

A virtual chess plaza: AI chess hustlers with distinct personalities, played by Claude agents over any UCI engine, in your terminal.

Think of Washington Square Park in NYC, or Dupont Circle in DC (but not any specific, exact place!) – places where chess hustlers gather to play, banter, and challenge passersby. This project brings that experience to your terminal, powered by LLMs.

## Roadmap

**Phase 1: Claude Agents epoch** (shipped in 0.1.0)
- Chess hustler personas powered by Claude Agents SDK;
- Integration with UCI chess engines via [chess-uci-mcp](https://github.com/AnglerfishChess/chess-uci-mcp);
- Different hustler personalities: the trash-talker, the philosopher, the speed demon, the old master...
- Game/chat loop using Claude Agents SDK.

**Phase 2: Experimentation epoch**
- Basic voice output (Edge-TTS), complementing the text UI;
- Voice input (Whisper) to call out your moves (and words) instead of keyboard input;
- Switchable UI: command-line vs PySide-based (with proper chess board).

**Phase 3: LangGraph/Gemini epoch**
- Switching to Gemini, for LLM but specifically for advanced text-to-speech (each with distinct voice characteristics, intonations, etc);
- (Because of Gemini switch) Migrating from Claude Agents SDK to `GenAI` SDK (TTS, one-shot queries) and LangGraph (game/chat loop).

## Prerequisites

- **Claude Code** authenticated ([install](https://docs.anthropic.com/en/docs/claude-code/getting-started)), or `ANTHROPIC_API_KEY` environment variable;
- **uv** package manager ([install](https://docs.astral.sh/uv/getting-started/installation/));
- **Stockfish** or another UCI chess engine ([download](https://stockfishchess.org/download/)).

## Usage

```bash
# Via uvx (PyPI release)
uvx "chessplaza[voice]" /usr/local/bin/stockfish

# Via uvx (latest from GitHub)
uvx --from "git+https://github.com/AnglerfishChess/chessplaza[voice]" chessplaza /usr/local/bin/stockfish

# From source
git clone https://github.com/AnglerfishChess/chessplaza.git
cd chessplaza
uv run chessplaza /usr/local/bin/stockfish
```

Options (work with any launch method):
- `--voice` / `-v` - enable text-to-speech
- `--language <lang>` / `-l <lang>` - play in a different language (e.g., Spanish, Russian)
- `--use-github-deps` - use bleeding-edge GitHub versions of dependencies (unstable, for development)

### Development setup

```bash
git clone https://github.com/AnglerfishChess/chessplaza.git
cd chessplaza
uv sync --extra voice
uv run chessplaza /usr/local/bin/stockfish
```

### Building Redistributables

PyInstaller is included in dev dependencies for building standalone apps. Full build instructions coming soon.

## Troubleshooting

### macOS: Microphone not working (voice input)

If voice input records silence or doesn't work, your terminal app likely lacks microphone permissions.

**Fix:**
1. Open **System Settings → Privacy & Security → Microphone**
2. Find your terminal app (Terminal, iTerm2, VS Code, etc.) and enable it
3. If not listed, the app hasn't requested access yet – try restarting the app

**Verify via command line:**
```bash
# Check which apps have microphone access
tccutil list Microphone
```

**Still not working?** Reset permissions to trigger a fresh prompt:
```bash
# For Terminal.app
tccutil reset Microphone com.apple.Terminal

# For iTerm2
tccutil reset Microphone com.googlecode.iterm2
```

## Related Projects

- [chess-uci-mcp](https://github.com/AnglerfishChess/chess-uci-mcp) - MCP bridge to UCI chess engines
- [esca](https://github.com/AnglerfishChess/esca) - the MIT-licensed Rust/Python chess library: rules, position facts, PGN, opening books and names
