A realistic, modular, AI-driven sheep herding simulation built in Python with Pygame. Watch advanced flocking behaviors, strategic shepherding AI, and online learning come together in one interactive demo!

• Modular architecture -- tweak everything in one config file (config.py)\
• Advanced flocking rules -- separation, alignment, cohesion plus a fear-response system for emergent collective movement\
• Smart Shepherd Dog 🤖
  -- Limited perception via configurable vision radius
  -- k-Nearest Neighbors to focus on the most influential sheep
  -- Multi-criteria scoring: distance, alignment, local density, boundary proximity
  -- Online learning (gradient descent) to adapt feature weights in real time
  -- Strategic positioning behind the furthest sheep relative to your target\
• Interactive debug overlays -- toggle vision radius, connection lines, AI decision scores\
• Live console output -- see feature weights update as the dog's strategy evolves

1. Clone the repo:
   git clone https://github.com/cipherpodliq1/sheep-herding-simulation.git
   cd sheep-herding-simulation

2. (Optional) Create + activate virtual environment:\

   • macOS/Linux:
     python3 -m venv venv
     source venv/bin/activate\
   • Windows:
     python3 -m venv venv
     venv\Scripts\activate

3. Install dependencies:
   pip install -r requirements.txt

All parameters live in config.py for easy tweaking!
VISION_RADIUS -- Dog's view range (default 150)
K_NEIGHBORS -- Number of sheep to consider (default 5)
SHEEP_COUNT -- Total flock size (default 50)
COHESION_WEIGHT -- Cohesion rule weight (default 1.0)
DOG_LEARNING_RATE -- Online learning rate (default 0.01)

Run the sim:
python main.py
Watch as the AI dog learns, adapts, and refines its herding strategy over time!

• SPACE -- Pause / Resume\
• D -- Toggle debug info (AI scoring per sheep)\
• V -- Toggle vision radius overlay\
• C -- Toggle connection lines to neighbors\
• Left Click -- Move the target point\
• R -- Reset simulation

config.py -- Centralized parameters & constants
vector_utils.py -- 2D vector math helpers
sheep.py -- Flocking & fear-response logic
dog.py -- AI decision pipelines & online learning
environment.py -- Simulation manager (state & rendering)
main.py -- Entry point (Pygame loop)
requirements.txt -- Dependencies (pygame, numpy, sklearn)

Inline docstrings and comments explain every module!\

• dog.py -- Dive into decision-making, scoring, and learning\
• sheep.py -- See how flocking and fear responses produce lifelike movement

🙌 WANT TO CONTRIBUTE? 🙌
We welcome your ideas, enhancements, and optimizations!

1. Fork the repo

2. Create a feature branch

3. Submit a pull request

Let's build the ultimate sheep herding AI together!

🔗 CONNECT WITH ME 🔗
LinkedIn: https://www.linkedin.com/in/kristiyan-radev/

Happy herding! 🐕✨