thompsonson/bayesian_game

🎲 Bayesian Game

A Bayesian Game implementation featuring a Belief-based Agent using domain-driven design. This interactive game demonstrates Bayesian inference in action as Player 2 attempts to deduce a hidden target die value based on evidence from dice rolls.

🎯 Game Overview

The Setup:

• —Judge and Player 1 can see the target die value (1-6)
• —Player 2 must deduce the target value using Bayesian inference
• —Each round: Player 1 rolls dice and reports "higher"/"lower"/"same" compared to target
• —Player 2 only receives the comparison result, NOT the actual dice roll value
• —Game runs for 10 rounds (configurable)
• —Judge ensures truth-telling

The Challenge: Player 2 starts with uniform beliefs about the target value and updates their beliefs after each piece of evidence using Bayes' rule. The key insight is that Player 2 must calculate the probability that ANY dice roll would produce the observed comparison result for each possible target value.

🏗️ Architecture

Built using Domain-Driven Design with clean separation of concerns:

1. Environment Domain (domains/environment/)

• —Pure evidence generation - no probability knowledge
• —EnvironmentEvidence: Dataclass for dice roll results
• —Environment: Generates target values and dice roll comparisons

2. Belief Domain (domains/belief/)

• —Pure Bayesian inference - receives only comparison results, no dice roll values
• —BeliefUpdate: Dataclass containing only comparison results
• —BayesianBeliefState: Calculates likelihood P(comparison_result | target) for each possible target

3. Game Coordination (domains/coordination/)

• —Thin orchestration layer - coordinates between domains
• —GameState: Tracks current game state
• —BayesianGame: Main game orchestration class

4. UI Layer (ui/)

• —Interactive Gradio web interface
• —Real-time belief visualization
• —Game controls and statistics display

🚀 Quick Start

Prerequisites

• —Python 3.10+
• —uv package manager (recommended) or pip

Installation

1. 1.Clone and navigate to the project:

git clone <repository-url>
cd bayesian_game

1. 1.Set up virtual environment:

# Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or using pip
python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

1. 1.Install dependencies:

# Using uv
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt

1. 1.Set up pre-commit hooks (optional for development):

pre-commit install

Running the Game

Launch the interactive web interface:

python app.py

The game will be available at http://localhost:7860

Run from command line (for development):

from domains.coordination.game_coordination import BayesianGame

# Create and start a game
game = BayesianGame(seed=42)
game.start_new_game(target_value=3)

# Play rounds
for round_num in range(5):
    state = game.play_round()
    evidence = state.evidence_history[-1]
    print(f"Round {round_num + 1}: Rolled {evidence.dice_roll} → {evidence.comparison_result}")
    print(f"Most likely target: {state.most_likely_target}")
    print(f"Belief entropy: {state.belief_entropy:.2f}")

🧪 Testing

Run the comprehensive test suite:

# Run all tests
python -m pytest tests/ -v

# Run specific domain tests
python -m pytest tests/test_environment_domain.py -v
python -m pytest tests/test_belief_domain.py -v
python -m pytest tests/test_game_coordination.py -v

# Run with coverage
python -m pytest tests/ --cov=domains --cov-report=html

Test Coverage:

• —56 comprehensive tests
• —All core functionality covered
• —Edge cases and error handling tested
• —Reproducibility and randomness testing

🎮 Game Interface

The Gradio interface provides:

• —Game Controls: Start new games, play rounds, reset settings
• —Real-time Visualization: Belief probability distribution chart
• —Game Statistics: Entropy, accuracy, round information
• —Evidence History: Complete log of dice rolls and comparisons
• —Customization: Adjustable dice sides and round count

Interface Features

• —📊 Belief Distribution Chart: Visual representation of Player 2's beliefs
• —🎯 Target Highlighting: True target and most likely guess highlighted
• —📝 Evidence Log: Complete history of all dice rolls and results
• —⚙️ Game Settings: Customize dice sides (2-20) and max rounds (1-50)
• —🔄 Reset & Replay: Easy game reset and replay functionality

📁 Project Structure

bayesian_game/
├── domains/                    # Core domain logic
│   ├── environment/           # Evidence generation
│   │   └── environment_domain.py
│   ├── belief/               # Bayesian inference
│   │   └── belief_domain.py
│   └── coordination/         # Game orchestration
│       └── game_coordination.py
├── ui/                       # User interface
│   └── gradio_interface.py
├── tests/                    # Comprehensive test suite
│   ├── test_environment_domain.py
│   ├── test_belief_domain.py
│   └── test_game_coordination.py
├── app.py                    # Main entry point
├── requirements.txt          # Dependencies
├── CLAUDE.md                 # Project specifications
└── README.md                 # This file

🔬 Key Features

Bayesian Inference Engine

• —Proper Bayesian Updates: Uses Bayes' rule for belief updates
• —Entropy Calculation: Measures uncertainty in beliefs
• —Evidence Integration: Combines multiple pieces of evidence
• —Impossible Evidence Handling: Gracefully handles contradictory evidence

Reproducible Experiments

• —Seeded Randomness: Reproducible results for testing
• —Deterministic Behavior: Same seed produces same game sequence
• —Statistical Analysis: Track accuracy and convergence

Clean Architecture

• —Domain Separation: Pure domains with no cross-dependencies
• —Testable Components: Each domain independently testable
• —Extensible Design: Easy to add new features or modify rules

🎓 Educational Value

This implementation demonstrates:

• —Bayesian Inference: Real-world application of Bayes' rule
• —Uncertainty Quantification: How beliefs evolve with evidence
• —Information Theory: Entropy as a measure of uncertainty
• —Domain-Driven Design: Clean software architecture patterns
• —Test-Driven Development: Comprehensive testing strategies

🛠️ Development

Key Dependencies

• —gradio: Web interface framework
• —numpy: Numerical computations for Bayesian inference
• —matplotlib: Belief distribution visualization
• —pytest: Testing framework
• —pre-commit: Code quality automation
• —ruff: Fast Python linter and formatter (replaces Black, isort, flake8)

Development Workflow

# Install pre-commit hooks
pre-commit install

# Run pre-commit manually
pre-commit run --all-files

# Run tests with coverage
python -m pytest tests/ --cov=domains --cov=ui --cov-report=html

# Code formatting and linting (automatic with pre-commit)
ruff check --fix .
ruff format .
mypy .

CI/CD Pipeline

• —GitHub Actions: Automated testing on Python 3.10, 3.11, 3.12
• —Pre-commit hooks: Code quality checks (Ruff, mypy, bandit)
• —Test coverage: Comprehensive coverage reporting
• —Security scanning: Trivy vulnerability scanner
• —Auto-deployment: Pushes to Hugging Face Spaces on main branch

Design Principles

1. 1.Pure Functions: Domains contain pure, testable functions
2. 2.Immutable Data: Evidence and belief updates are immutable
3. 3.Clear Interfaces: Well-defined boundaries between domains
4. 4.Comprehensive Testing: Every component thoroughly tested

Contributing

1. 1.Follow the existing domain-driven architecture
2. 2.Add tests for any new functionality
3. 3.Maintain clean separation between domains
4. 4.Update documentation for new features

📊 Example Game Flow

Round 1: Evidence "higher" (dice roll > target)
├─ P(roll>1)=5/6, P(roll>2)=4/6, ..., P(roll>6)=0/6
├─ Lower targets become more likely
└─ Entropy: 2.15 bits

Round 2: Evidence "lower" (dice roll < target)
├─ P(roll<1)=0/6, P(roll<2)=1/6, ..., P(roll<6)=5/6
├─ Higher targets become more likely
└─ Entropy: 1.97 bits

Round 3: Evidence "same" (dice roll = target)
├─ P(roll=target) = 1/6 for all targets
├─ Beliefs remain proportional to previous round
└─ Entropy: 1.97 bits (unchanged)

🚀 Deployment

Hugging Face Spaces (Automated)

The repository includes automated deployment to Hugging Face Spaces via GitHub Actions. To set this up:

1. 1.Create a Hugging Face Space: Go to hf.co/new-space and create a new Gradio space
2. 2.Get your HF Token: Visit hf.co/settings/tokens and create a token with write access
3. 3.Add GitHub Secret: In your GitHub repository, go to Settings > Secrets and variables > Actions, and add:
4. 4.Name: HF_TOKEN
5. 5.Value: Your Hugging Face token
6. 6.Update workflow: Edit .github/workflows/deploy.yml and replace:
7. 7.HF_USERNAME: Your Hugging Face username
8. 8.HF_SPACE_NAME: Your space name

The deployment will automatically trigger after successful CI runs on the main branch.

Other Deployment Options

• —Local Server: Built-in Gradio server (python app.py)
• —Cloud Platforms: Standard Python web app deployment

Built with ❤️ using Domain-Driven Design and Bayesian Inference