guess-simulator 0.1.1

Probability-guided number guessing simulator

Probability-Guided Number Guessing Simulator

A production-grade CLI application for playing number guessing games with intelligent probability-based hints and comprehensive game tracking.

🎯 Features

• Probability-Guided Hints: Smart hints based on Bayesian probability analysis
• Multiple Difficulty Levels: Easy, Medium, Hard, and Expert profiles
• Durable Storage: Atomic file operations with JSON storage
• Import/Export: CSV support for data portability
• Comprehensive Logging: Detailed logs for debugging and tracking
• Strict Validation: Clear error messages for all inputs
• Statistics Tracking: Detailed game statistics and performance metrics
• Simple & Clean Code: Easy to understand for learning purposes

📦 Installation

Prerequisites

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

Install from Source

pip install -e .

After installation, the guess-sim command will be available globally.

🚀 Quick Start

# Play a game with default settings (medium difficulty)
python -m guess_simulator.cli play

# Or if installed:
guess-sim play

# Play with specific difficulty
guess-sim play -d hard

# Play with custom range
guess-sim play --min 1 --max 500 -a 15

# Play with verbose output
guess-sim play -v

📖 Usage

Commands

Play a Game

guess-sim play [OPTIONS]

Options:
  -d, --difficulty {easy,medium,hard,expert}  Difficulty level
  --min INTEGER                               Minimum number
  --max INTEGER                               Maximum number
  -a, --attempts INTEGER                      Maximum attempts
  -s, --save                                  Save game after completion
  -v, --verbose                               Verbose output with probability info

Example:

guess-sim play -d expert -s -v

View Statistics

guess-sim stats [OPTIONS]

Options:
  -v, --verbose    Show detailed statistics and recent games

Example:

guess-sim stats -v

Export Data

guess-sim export [OPTIONS]

Options:
  -o, --output PATH    Output CSV file path (default: game_export.csv)

Example:

guess-sim export -o my_games.csv

Import Data

guess-sim import -i INPUT_PATH

Options:
  -i, --input PATH    Input CSV file path (required)

Example:

guess-sim import -i my_games.csv

Manage Configuration

guess-sim config [OPTIONS]

Options:
  --list           List all available profiles
  --show PROFILE   Show specific profile settings

Example:

guess-sim config --list
guess-sim config --show hard

🎮 Gameplay

When you start a game, you'll see:

============================================================
🎮 PROBABILITY-GUIDED NUMBER GUESSING SIMULATOR
============================================================
Difficulty: MEDIUM
Range: 1 - 100
Maximum Attempts: 10
Game ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
============================================================

Enter your guess (1-100): 50
📉 Too high! Try a lower number.
📊 Attempts: 1/10

Enter your guess (1-100): 25
📈 Too low! Try a higher number.
💡 Hint: ♨️ Hot! The number is between 26 and 49.
📊 Attempts: 2/10

Hint System

The game provides intelligent hints based on:

1. Temperature Feedback:

   • 🔥 Very Hot (within 10% of range)
   • ♨️ Hot (within 25% of range)
   • 🌡️ Warm (within 50% of range)
   • ❄️ Cold (within 75% of range)
   • 🧊 Very Cold (beyond 75% of range)

2. Probability-Based Range Narrowing:

   • When possible numbers drop below threshold, shows exact range
   • Displays remaining possibilities in verbose mode

⚙️ Configuration

Configuration is hardcoded in config.py with the following profiles:

Difficulty Profiles

Profile	Range	Max Attempts	Hint Frequency
Easy	1-50	15	Every 2 guesses
Medium	1-100	10	Every 3 guesses
Hard	1-200	8	Every 4 guesses
Expert	1-500	12	Every 5 guesses

Storage Settings

• format: json (default for easy debugging)
• data_dir: Directory for storing game data (default: game_data)

📊 Game Statistics

The game tracks comprehensive statistics:

• Total games played
• Win/loss counts and percentages
• Average attempts per game
• Best and worst scores
• Guess history for each game

📂 Project Structure

guess_simulator/
├── __init__.py          # Package initialization
├── cli.py               # Command-line interface
├── config.py            # Configuration management
├── game.py              # Core game engine
├── logger.py            # Logging system
├── storage.py           # Data persistence
└── validator.py         # Input validation

tests/
├── __init__.py
├── test_game.py         # Game engine tests
├── test_storage.py      # Storage tests
├── test_validator.py    # Validation tests
└── test_integration.py  # Integration tests

🗂️ Data Storage

File Structure

game_data/
├── games.json          # All game records
└── statistics.json     # Aggregated statistics

game.log                # Application logs

Data Format

Games are stored in JSON format:

{
  "game_id": "uuid",
  "start_time": "2025-11-29T15:30:45",
  "end_time": "2025-11-29T15:32:10",
  "duration_seconds": 85.5,
  "min_number": 1,
  "max_number": 100,
  "target_number": 42,
  "max_attempts": 10,
  "attempts": 7,
  "guess_history": [50, 25, 37, 43, 40, 41, 42],
  "won": true,
  "finished": true
}

🧪 Testing

Run the test suite:

# Run all tests
python -m unittest discover tests

# Run specific test module
python -m unittest tests.test_game

# Run with verbose output
python -m unittest discover tests -v

Test Suite: 18 streamlined tests covering all core functionality

Test Coverage

• Unit Tests: Game logic, validation, storage
• Integration Tests: Complete workflows and system integration
• All tests run in ~0.1 seconds

Common Issues

Issue: Command not found after installation

# Solution: Use Python module syntax
python -m guess_simulator.cli play

Issue: Permission denied when saving

# Solution: Check directory permissions
chmod 755 game_data/

Issue: Corrupted data file

# Solution: Delete the corrupted file to start fresh
# Data files are located in game_data/ directory

📝 Design Trade-offs

Storage Format

• Choice: JSON for primary storage
• Rationale: Human-readable, easy debugging, excellent for learning
• Trade-off: Slightly larger file size vs binary formats
• Benefit: Students can open and inspect data files directly

Probability Algorithm

• Choice: Simple Bayesian range narrowing
• Rationale: Easy to understand for 1st-year students
• Trade-off: Not as sophisticated as ML models
• Benefit: Fast, deterministic, explainable

Testing Approach

• Choice: Focused test suite (18 tests)
• Rationale: Covers core functionality without overwhelming complexity
• Trade-off: Fewer edge cases tested
• Benefit: Easy to understand and maintain for beginners

🚨 Limits and Edge Cases

Input Limits

• Number Range: 1 to 2,147,483,647 (max int)
• Max Attempts: 1 to 1000
• String Length: 100 characters max

Edge Cases Handled

• ✅ Corrupted data files (graceful error handling)
• ✅ Concurrent access (atomic writes)
• ✅ Invalid user input (strict validation)
• ✅ Missing configuration (defaults provided)
• ✅ Disk full (graceful error handling)
• ✅ Large datasets (tested with 10,000+ games)

Known Limitations

• Windows: File rename not truly atomic (mitigated with temp files)
• Large ranges (>1M): Probability tracking uses significant memory
• Single-threaded: No async processing (keeps code simple)

📄 License

MIT License - Feel free to use for learning and projects!

👨‍💻 Author

Created as a 1st-year college project demonstrating:

• Production-grade Python development
• CLI application design
• Testing and documentation
• Software engineering best practices

🤝 Contributing

This is a learning project, but suggestions are welcome!

1. Test your changes thoroughly
2. Follow existing code style
3. Add tests for new features
4. Update documentation

📚 Learning Resources

This project demonstrates:

• argparse: CLI argument parsing
• logging: Professional logging practices
• json/csv: Data serialization
• pathlib: Modern file path handling
• unittest: Testing framework
• OOP principles: Classes, inheritance, encapsulation
• Design patterns: Singleton pattern in logger
• Input validation: Defensive programming

---

Happy Guessing! 🎯