Metadata-Version: 2.4
Name: chessplaza
Version: 0.1.0
Summary: Chess hustler plaza - AI chess hustlers with distinct personalities powered by Claude Agents SDK
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.3
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 virtual chess plaza with AI-powered chess hustlers, each with their own unique personality and playing style.

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
