backend-agent

<h1 align="center">Intelligent Irrigation Agent</h1>

<p align="center">
  <img src="docs/images/plantita_pixel_art.gif" alt="Plant Animation" width="200">
</p>

<p align="center">
Multi‑agent irrigation backend using Google Gemini ADK. Adds proactive monitoring, explainable decisions and API endpoints over an IoT irrigation setup (sensors + pumps).
</p>

---

## Table of Contents
- Project Overview
- Quick Start
- Architecture
- Installation
- Configuration
- API Endpoints
- Audio (TTS/STT)
- Agriculture (USDA Quick Stats)
- Deployment (Cloud Run)
- Development

---

## Project Overview

This service turns a traditional automated irrigation system into an intelligent assistant. It analyzes sensor history, weather, and crop context to recommend or trigger actions with clear reasons.

Key benefits
- Proactive: predicts issues 12–48 hours ahead
- Efficient: 15–25% water savings via optimization
- Explainable: every decision includes reasoning
- Context‑aware: integrates weather, soil and plant data
- Smart alerts: priority‑based notifications

---

## Quick Start

Prerequisites
- Python 3.10+
- pip

Setup
```bash
pip install -r requirements.txt
# Create .env and fill keys (see Configuration)

# Run locally
uvicorn main:app --reload --port 8080

# Health check
curl http://localhost:8080/health
```

---

## Architecture

### System Architecture Diagram

<p align="center">
  <img src="docs/images/arch-gcp.svg" alt="GCP Architecture" width="800">
</p>

### Components Overview

**API Layer** (FastAPI)
- REST endpoints organized by domain (plants, gardens, agriculture, audio)
- WebSocket server for real-time notifications
- Background monitoring task (30-60s intervals)

**Agent Layer** (Google Gemini ADK)
- Multi-agent orchestration with 4 specialized sub-agents
- Sensor monitor, nutrient analyzer, alert manager, optimization agent
- Explainable AI decisions with reasoning

**Tools Layer** (Modular)
- Sensors: moisture, tank level, history
- Control: irrigation triggers
- A