🎮 Bulls & Cows Game

Welcome to Bulls & Cows, a fun and strategic number guessing game! Test your logic skills against an AI opponent and compete in real-time gameplay.

🌐 Live Demo

Try the deployed app here: Live Demo — bulls-cows.streamlit.app

🎯 What's the Game?

Bulls & Cows is a classic code-breaking game where:

• Someone picks a secret 4-digit number
• The other person makes guesses to figure it out
• After each guess, you get feedback:
  • 🎯 Bulls = Correct digit in the correct position
  • 🐄 Cows = Correct digit in the wrong position

✨ Features

• Classic Mode: You guess the AI's secret number
• Smart Suggestions: Get hints for your next guess
• Entropy Visualization: See how much information you gain with each guess

🚀 Get Started

Requirements

You'll need:

• Python 3.11 or higher
• Poetry (package manager)

Setup Instructions

1️⃣ Create a Virtual Environment

On Mac/Linux:

python3 -m venv .venv && source .venv/bin/activate

On Windows:

python -m venv .venv
.venv\Scripts\Activate.ps1

2️⃣ Install Dependencies

First, install Poetry:

pip install poetry

Then install project dependencies:

poetry install

3️⃣ Set Up Gemini API (Optional - for Competitive Mode)

Want to play against AI? Here's how:

1. Go to Google AI Studio
2. Create a free API key
3. Create a .env file in the project root:

   GEMINI_API_KEY=your_api_key_here
   

4️⃣ Run the Game

poetry run app

That's it! Open the game in your browser and start playing! 🎉

📖 How to Play

Classic Mode 🤖

• AI picks a secret 4-digit number (0-9, no repeating digits)
• You try to guess it
• After each guess, see Bulls & Cows feedback
• Use logic and our smart suggestions to solve it faster!

Competitive Mode ⚡

• AI and you both guess the same secret number
• First one to crack it wins the round
• Watch the AI's strategy in action
• See how your intuition compares to information theory!

📝 License

This project is licensed under MIT. See LICENSE for details.