Metadata-Version: 2.4
Name: noprune
Version: 0.1.2
Summary: Python client for noprune chess bot platform - easily create custom chess systems
Project-URL: Homepage, https://noprune.org
Project-URL: Documentation, https://github.com/noprune/noprune/tree/main/clients/python
Project-URL: Repository, https://github.com/noprune/noprune
Project-URL: Issues, https://github.com/noprune/noprune/issues
Author-email: noprune <contact@noprune.org>
License: MIT
License-File: LICENSE
Keywords: ai,bot,chess,engine,game,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: python-chess>=1.10.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# noprune

**Build your own chess system in Python with just a few lines of code.**

noprune is the official Python client for the [noprune.org](https://noprune.org) chess bot platform — where AI chess systems compete against each other in a fair, transparent rating system.

## Vision

**noprune** is a platform where anyone can create, deploy, and compete with their own chess AI.

- **No pruning, pure skill** — Every system plays every position. No shortcuts.
- **Fair matchmaking** — Systems are matched by skill level (Turing rating)
- **Open competition** — Your bot competes 24/7 against others worldwide
- **Learn by doing** — Start with random moves, evolve to neural networks

Whether you're a beginner learning minimax or a researcher testing cutting-edge models, noprune provides the arena.

## Installation

```bash
pip install noprune
```

## Quick Start

Create a chess bot in 10 lines:

```python
from noprune import Bot
import random

@Bot(system_id="your-id", secret="your-secret")
def my_bot(board):
    # board is a python-chess Board object
    moves = list(board.legal_moves)
    return random.choice(moves).uci()

my_bot.run()  # Connect and start playing!
```

That's it. Your bot will connect to noprune.org, join the matchmaking queue, and start playing games automatically.

## Getting Your Credentials

1. Sign up at [noprune.org](https://noprune.org)
2. Create a new "System" (your bot)
3. Copy your `system_id` and `secret`

## Examples

### Random Bot (Simplest)

```python
from noprune import Bot
import random

@Bot(system_id="...", secret="...")
def random_bot(board):
    return random.choice(list(board.legal_moves)).uci()

random_bot.run()
```

### Stockfish Bot (Strong)

```python
from noprune import Bot
import chess.engine

@Bot(system_id="...", secret="...")
def stockfish_bot(board):
    with chess.engine.SimpleEngine.popen_uci("/usr/games/stockfish") as engine:
        result = engine.play(board, chess.engine.Limit(time=0.1))
        return result.move.uci()

stockfish_bot.run()
```

### With Game Events (Advanced)

```python
from noprune import Bot, GameState, Action

class MyBot(Bot):
    def on_game_start(self, game: GameState):
        print(f"Game started vs {game.opponent}!")
        print(f"I'm playing as {game.color}")

    def on_game_end(self, game: GameState, result: str, reason: str):
        print(f"Game over: {result} ({reason})")

    def think(self, board) -> str:
        # Your engine logic here
        return "e2e4"

bot = MyBot(system_id="...", secret="...")
bot.run()
```

### Resign & Draw Offers

```python
from noprune import Bot, Action

@Bot(system_id="...", secret="...")
def smart_bot(board):
    # Resign if losing badly
    if is_losing(board):
        return Action.RESIGN

    # Offer draw in equal endgame
    if is_drawn_endgame(board):
        return Action.OFFER_DRAW

    return calculate_best_move(board)
```

## API Reference

### Bot

The main class for creating chess bots.

```python
# Decorator style
@Bot(system_id="...", secret="...", server_url="wss://noprune.org/ws")
def my_bot(board):
    return "e2e4"

# Class style
class MyBot(Bot):
    def think(self, board):
        return "e2e4"
```

**Methods to override:**
- `think(board) -> str | Action` — Calculate your move (required)
- `on_game_start(game: GameState)` — Called when game begins
- `on_game_end(game, result, reason)` — Called when game ends
- `on_move(game, move, is_my_move)` — Called after each move
- `on_draw_offer(game) -> bool` — Return True to accept draw

### GameState

```python
@dataclass
class GameState:
    game_id: str           # Unique game identifier
    board: chess.Board     # Current position (python-chess)
    color: str             # "white" or "black"
    opponent: str          # Opponent's name
    moves: list[str]       # Move history in UCI format
    my_time_ms: int        # Your remaining time (ms)
    opponent_time_ms: int  # Opponent's remaining time (ms)
```

### Action

```python
Action.RESIGN       # Give up
Action.OFFER_DRAW   # Propose a draw
Action.move("e2e4") # Make a move (same as returning "e2e4")
```

## Environment Variables

```bash
export SYSTEM_ID="your-system-id"
export SYSTEM_SECRET="your-secret"
export SERVER_URL="wss://noprune.org/ws"  # or ws://localhost:8086/ws for local

python my_bot.py
```

## Why "noprune"?

In chess programming, "pruning" means skipping moves that seem bad. Top systems like Stockfish prune aggressively — they don't even consider most legal moves.

**noprune** is different. It's a place where any approach is welcome:
- Brute-force minimax? Great.
- Neural network evaluation? Awesome.
- Random moves? Sure, let's see how it does.

The name reminds us: there's no "wrong" way to build a chess system. Every approach teaches us something.

## Links

- **Website**: [noprune.org](https://noprune.org)
- **GitHub**: [github.com/noprune/noprune](https://github.com/noprune/noprune)
- **PyPI**: [pypi.org/project/noprune](https://pypi.org/project/noprune)

## License

MIT
