<div align="center">

🦅 TerraHawk

AI-Powered Smart Farm Management System

A multi-agent agentic system for precision agriculture — orchestrating 3 specialized AI crews for crop analysis, strategic decision-making, and EU AI Act compliance, powered by AWS Bedrock and real-time edge computer vision.

Architecture · Crews · Edge CV · Getting Started

</div>

---

✨ Key Features

• Multi-Crew Agentic Architecture — SmartFarmFlow orchestrator with 3 specialized crews via CrewAI Flows
• Human-in-the-Loop — @human_feedback gate before report submission, with approve/deny control
• AWS Bedrock (Claude 3.5 Sonnet) — Enterprise-grade LLM backbone for all agent reasoning
• Edge Computer Vision — YOLO26 + RF-DETR on Raspberry Pi 5 via WebRTC real-time stream
• EU AI Act Compliance — Dedicated LegalCrew with risk classification, transparency obligations, and action items
• Prompt Versioning — Registry-based prompt management with versioned .txt files and index.json manifest
• Token Usage & Cost Tracking — Per-crew token accounting with model-specific cost estimation
• ChromaDB RAG — Retrieval-augmented compliance knowledge base for legal assessments
• AWS Integration — S3 for report storage/retrieval, DynamoDB for sensor data and vision detections
• Structured Outputs — Pydantic models for every crew output (weather, sensors, compliance, master report)

---

🏗 Architecture

                         ┌──────────────────────────────────────────────┐
                         │         SmartFarmFlow (CrewAI Flow)          │
                         └──────────────────────────────────────────────┘

  Edge (RPi 5)                    AWS Cloud                         Output
  ──────────┐              ┌─────────────────┐              ┌──────────────
            ▼              ▼                 ▼              ▼
  ┌──────────────┐   ┌──────────────────────────────┐   ┌──────────────┐
  │  WebRTC      │   │         CropCrew             │   │   S3 Bucket  │
  │  Stream      │──▶│  ┌────────┐ ┌────────┐      │   │   Reports    │
  │              │   │  │Weather │ │Sensor  │      │   └──────────────┘
  │  YOLO26 +    │   │  │Analyst │ │Analyst │      │          ▲
  │  RF-DETR     │   │  └───┬────┘ └───┬────┘      │          │
  └──────────────┘   │      │          │            │          │
                     │  ┌───▼──────────▼────┐       │          │
                     │  │  Vision Analyst   │       │          │
  ┌──────────────┐   │  └───────┬───────────┘       │          │
  │  DynamoDB    │◀──│          │ Aggregation        │          │
  │  Sensor Data │──▶│  ┌───────▼───────────┐       │          │
  └──────────────┘   │  │  CropCrew Output  │       │          │
                     │  └───────┬───────────┘       │          │
                     └──────────┼───────────────────┘          │
                                ▼                              │
                     ┌──────────────────────────────┐          │
                     │        LegalCrew             │          │
                     │  ┌─────────────┐ ┌────────┐  │          │
                     │  │ Compliance  │ │EU AI   │  │          │
                     │  │ Analyst     │ │Act     │  │          │
                     │  └──────┬──────┘ └───┬────┘  │          │
                     │         └─────┬──────┘       │          │
                     │         ┌─────▼──────┐       │          │
                     │         │ Aggregator │       │          │
                     │         └─────┬──────┘       │          │
                     └───────────────┼──────────────┘          │
                                     ▼                         │
                     ┌───────────────────────────┐             │
                     │  🧑 Human Feedback Gate   │             │
                     │  "Submit reports?" [y/n]  │             │
                     └───────────┬───────────────┘             │
                                 ▼                             │
                     ┌──────────────────────────────┐          │
                     │     Master Chief Agent       │          │
                     │  (Claude 3.5 Sonnet)         │──────────┘
                     │  Cross-functional synthesis  │
                     │  + historical trend analysis │
                     └──────────────────────────────┘

---

🤖 Crew Architecture

CropCrew — Field Intelligence

Analyzes real-time farm conditions from three data streams:

| Agent | Tools | Output | |-------|-------|--------| | Weather Analyst | WeatherAPITool | Temperature, humidity, wind, air quality, agricultural assessment | | Sensor Analyst | SensorDataRetriever (DynamoDB) | Soil moisture, pH, nutrients, irrigation status | | Vision Analyst | DynamoDBVisionRetriever | Crop health from edge CV detections (YOLO26/RF-DETR) | | Aggregator | — | Combined JSON with all three analyses |

LegalCrew — Compliance & Regulation

Evaluates operations against regulatory frameworks:

| Agent | Tools | Output | |-------|-------|--------| | Compliance Analyst | ComplianceRAGTool (ChromaDB) | Regulatory classification, nitrogen emissions, operational impact | | EU AI Act Assessor | ComplianceRAGTool (ChromaDB) | Risk level, transparency obligations, compliance gaps, action items | | Aggregator | — | Combined compliance + EU AI Act assessment (7-day cache) |

Master Chief Agent — Strategic Synthesis

A direct Claude 3.5 Sonnet agent (outside crew) that:

• Reads all crew outputs + historical S3 reports via S3ReportReader
• Identifies cross-functional patterns and historical trends
• Produces a 9-section Master Operations Report with farm status rating

---

📡 Edge Computer Vision

Real-time crop monitoring on Raspberry Pi 5:

• YOLO26 — Object detection for crop health anomalies
• RF-DETR — High-accuracy detection/segmentation
• WebRTC — Low-latency video stream to cloud
• Detections stored in DynamoDB for agent retrieval

---

📝 Prompt Versioning

All agent prompts are externalized and versioned:

prompts/
├── index.json                                    # Manifest: task → file mapping
├── crop_crew__weather_task_v1.0.0.txt
├── crop_crew__crop_sensor_task_v1.0.0.txt
├── crop_crew__vision_analyzer_task_v1.0.0.txt
├── crop_crew__aggregation_task_v1.0.0.txt
├── legal_crew__compliance_task_v1.0.0.txt
├── legal_crew__eu_ai_act_task_v1.0.0.txt
├── legal_crew__compliance_aggregation_task_v1.0.0.txt
└── core_crew__master_chief_task_v1.0.0.txt

Loaded via prompt_registry.py — enables A/B testing and version rollback without code changes.

---

💰 Token Usage & Cost Tracking

Every crew run tracks token consumption with per-model cost estimation:

══════════════════════════════════════════════════════════════════════
Token Usage & Cost Summary:
══════════════════════════════════════════════════════════════════════
  crop_crew:              12,450 tokens (prompt: 8,200, completion: 4,250) — ~$0.0882
  compliance_crew:         8,320 tokens (prompt: 5,100, completion: 3,220) — ~$0.0636
  master_chief (direct):  15,800 tokens (prompt: 11,200, completion: 4,600) — ~$0.1026
  ──────────────────────────────────────────────────────────────
  TOTAL: 36,570 tokens — ~$0.2544 USD
  💰 EU AI Act assessment served from cache (saved ~1 agent run)
══════════════════════════════════════════════════════════════════════

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• AWS account with Bedrock, S3, and DynamoDB access
• Raspberry Pi 5 (for edge CV — optional for cloud-only testing)

Installation

git clone https://github.com/james-t98/terra_hawk_crewai.git
cd terra_hawk_crewai
pip install -e .

Environment Variables

export AWS_REGION_NAME=eu-west-1
export S3_BUCKET=your-bucket-name
export FARM_ID=FARM-001
export LOCATION="Your Farm Location"

Run

crewai flow kickoff

The flow will execute CropCrew → LegalCrew → Human Feedback Gate → Master Chief → S3 Report Submission.

---

🛠 Tech Stack

| Layer | Technology | |-------|------------| | Orchestration | CrewAI Flows, Human-in-the-Loop | | LLM | AWS Bedrock (Claude 3.5 Sonnet), GPT-4o-mini (feedback) | | RAG | ChromaDB, sentence-transformers | | Edge CV | YOLO26, RF-DETR, WebRTC, Raspberry Pi 5 | | Cloud Storage | AWS S3 (reports), DynamoDB (sensors + detections) | | Data Validation | Pydantic v2 structured outputs | | Prompt Management | Versioned prompt registry |

---

📁 Project Structure

terra_hawk_crewai/
├── src/terra_hawk_crewai/
│   ├── main.py                     # SmartFarmFlow orchestrator
│   ├── crews/
│   │   ├── crop_crew/              # Weather + Sensor + Vision analysis
│   │   ├── core_crew/              # Master Chief agent definitions
│   │   └── legal_crew/             # Compliance + EU AI Act assessment
│   ├── tools/
│   │   ├── weather_api_tool.py     # Weather data retrieval
│   │   ├── sensor_data_retriever.py # DynamoDB sensor queries
│   │   ├── dynamodb_vision_retriever.py # Edge CV detection retrieval
│   │   ├── compliance_rag_tool.py  # ChromaDB legal knowledge RAG
│   │   ├── s3_report_writer.py     # Report persistence to S3
│   │   ├── s3_report_reader.py     # Historical report retrieval
│   │   ├── s3_image_retriever.py   # Image retrieval from S3
│   │   └── retry_utils.py          # Exponential backoff utilities
│   └── prompts/                    # Versioned prompt templates
├── pyproject.toml
└── README.md

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

<div align="center">

Built with 🦅 for precision agriculture · TerraHawk

</div>