purefn 0.0.0.dev0

Pure, stateless game operations: deterministic, replay-able game state management

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.

# 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 | Cards Specification

---

Chess

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

# 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 | Chess Specification

---

Protocol

Cryptographic rule inference game for testing AI procedural learning.

# 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 | Protocol Specification

---

Installation

# 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:

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

Response:

{
  "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:

# Run all demos
./demos/run_all.sh

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

Testing

# 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