drwjkirkpatrick-web/poultry-guardian

AI-powered autonomous poultry monitoring system for smallholder African farmers. Raspberry Pi 4/5, under USD150/coop, 2G GSM connectivity. # HERMES Poultry Guardian **AI-Powered Autonomous Poultry Monitoring System for Smallholder African Farmers** | | | |---|---| | **Hardware** | Raspberry Pi 4 / 5 (4 GB ARM64) | | **AI Model** | MiniMax 2.7 (via Ollama Cloud) | | **Language** | Python 3.10+ | | **Cost** | Under USD150 per coop | | **Connectivity** | 2G GSM OK (no broadband required) | --- ## What It Does HERMES Poultry Guardian monitors temperature, humidity, ammonia (NH₃), water level, feed level, and chick behavior via USB webcam — then automatically controls fans, heaters, and window actuators to keep poultry safe. It sends SMS/WhatsApp alerts via Twilio with SIM800L GSM fallback for remote areas. **Five AI agents:** - **Vision Agent** — YOLOv8n chick behavior detection (clustering, heat stress, inactivity, mortality) - **Prediction Agent** — Open-Meteo weather forecasting + temperature trend spike detection - **Supervisor Agent** — Priority-based decision orchestration with 5-tier graduated heating/cooling and ammonia-compensated ventilation - **Cleaning Agent** — Coop hygiene tracking with NH₃ alert gating (6-hour post-cleaning grace, recontamination detection) - **Learning Agent** — Adaptive fan speed via exponential moving averages (EMA) per speed tier --- ## Quick Start ```bash # Clone git clone github.com cd poultry-guardian # Install dependencies python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt # Configure cp config/.env.example config/.env # Edit config/.env with your Twilio credentials and phone numbers # Simulate (no hardware needed) POULTRY_SIMULATE=true python3 src/main.py --test-agents # Deploy for real python3 src/main.py ``` --- ## Architecture ``` src/ ├── main.py # Orchestrator — loop, agent coordination, shutdown ├── agents/ │ ├── supervisor_agent.py # Priority decision tree + graduated control │ ├── vision_agent.py # OpenCV + YOLOv8 behavior detection │ ├── …