# PUREFN

**Pure, stateless game engines: deterministic, replay-able game state management**

PUREFN is a collection of functional game engines where every operation is a pure function. No database, no side effects—just `token in → token out`.

## Core Principles

- **Stateless**: All game state lives in compact, portable tokens
- **Deterministic**: Same seed + same operations = same results, every time
- **Pure Functions**: No hidden state, no I/O in the core
- **JSON API**: CLI reads/writes JSON for seamless agent integration

## Games

PUREFN includes three game engines:

### Cards

Stateless 52-card deck with named players and deterministic shuffling.

```bash
# Create a deck
DECK=$(purefn cards deck poker-night | jq -r .deck)

# Deal to players
DECK=$(purefn cards deal $DECK alice 5 | jq -r .deck)
DECK=$(purefn cards deal $DECK bob 5 | jq -r .deck)

# View hands
purefn cards view all $DECK --human
```

**Operations:** `deck`, `deal`, `discard`, `trade`, `exchange`, `view`
**Token format:** `d.<base64-json>`

[Cards Documentation](docs/cards.md) | [Cards Specification](spec/cards/spec.md)

---

### Chess

Stateless board manipulation with no rule validation—maximum flexibility for analysis and variants.

```bash
# Create a board
BOARD=$(purefn chess new | jq -r .board)

# Make moves (no validation)
BOARD=$(purefn chess move $BOARD e2 e4 | jq -r .board)
BOARD=$(purefn chess move $BOARD e7 e5 | jq -r .board)

# View position
purefn chess view $BOARD --human
```

**Operations:** `new`, `move`, `place`, `remove`, `clear`, `import`, `export`, `view`
**Token format:** `c.<base64-fen>`

[Chess Documentation](docs/chess.md) | [Chess Specification](spec/chess/spec.md)

---

### Protocol

Cryptographic rule inference game for testing AI procedural learning.

```bash
# Initialize a game
export PROTOCOL_SECRET_KEY="your_secret_key"
purefn protocol init --seed 42 --team alpha,beta --profile DEV

# Scout actions
purefn protocol act --scout alpha look
purefn protocol act --scout alpha move HALL_S1_01
purefn protocol act --scout alpha probe 0x3F
```

**Operations:** `init`, `status`, `map`, `act` (move/look/probe/respond), `export`
**State:** File-based (`protocol_state.json`)

[Protocol Documentation](docs/protocol.md) | [Protocol Specification](spec/protocol/spec.md)

---

## Installation

```bash
# Clone and install
git clone https://github.com/botassembly/purefn.git
cd purefn
pip install -e .

# With dev dependencies
pip install -e ".[dev]"
```

## JSON Envelope API

For agent integration, use the envelope format via `purefn run`:

```bash
echo '{
  "game": "cards",
  "op": "deal",
  "global": "d.eyJzZWVk...",
  "args": {"player": "alice", "num_cards": 5}
}' | purefn run
```

Response:
```json
{
  "ok": true,
  "global": "d.eyJzZWVk...",
  "views": {"player": "alice", "hand": ["AS", "KH", "7D"]},
  "commit": "a3f2..."
}
```

## Demos

Run the included demos to see the engines in action:

```bash
# Run all demos
./demos/run_all.sh

# Run individual demos
./demos/cards/run.sh
./demos/chess/run.sh
./demos/protocol/run.sh
```

## Testing

```bash
# Run all tests
make test

# Run with coverage
make coverage

# Run linting and type checks
make check
```

## Project Structure

```
purefn/
├── src/purefn/           # Main package
│   ├── core/             # PRNG, codecs, registry, result types
│   ├── games/            # Game engines
│   │   ├── cards/        # Cards engine
│   │   ├── chess/        # Chess engine
│   │   └── protocol/     # Protocol engine
│   └── cli/              # CLI commands
├── docs/                 # User documentation
│   ├── cards.md
│   ├── chess.md
│   └── protocol.md
├── spec/                 # Technical specifications
│   ├── cards/
│   ├── chess/
│   └── protocol/
├── demos/                # Demo scripts
├── tests/                # Test suite
└── schemas/              # JSON schema validation
```

## Why PUREFN?

**For AI agents:**
- Deterministic environments for training and testing
- JSON in/out for seamless integration
- Stateless tokens are portable and cacheable

**For game simulations:**
- Fast, reproducible game state
- No database overhead
- Branch and explore game trees with tokens

**For testing:**
- Pure functions are trivially testable
- Property-based testing for invariants
- Replay any game from seed + operations

## License

MIT License - see LICENSE file

## Contributing

Contributions welcome! Please:
1. Follow the pure functional design principles
2. Add tests for new operations
3. Ensure determinism and batching invariance
4. Update docs and specs as needed
