# 🌿 Farm Intelligence Platform (Pune AgriAI) - User Guide

Welcome to the **Pune AgriAI Farm Intelligence Platform**, a state-of-the-art AI-driven ecosystem designed to transform traditional farming into high-precision, data-backed agriculture. This guide provides comprehensive instructions for deploying and utilizing the platform's advanced features.

---

## 🚀 Quick Start Guide

### 1. Prerequisites
- **Python**: 3.9 or 3.10 (3.11+ may require minor dependency adjustments)
- **Database**: MongoDB (Local or Atlas)
- **API Keys**: Required for AI reasoning and market data.

### 2. Installation
Clone the repository and install the required packages:
```bash
pip install -r requirements.txt
```

### 3. Environment Configuration
Create/Update your `.env` file in the root directory:
```env
MONGO_CONNECTION_URL="your_mongodb_url"
GEMINI_API_KEY="your_google_gemini_key"
NVIDIA_API_KEY="your_nvidia_ai_key"
GROQ_API_KEY="your_groq_key"
```

### 4. Running the Application
Start the Flask server:
```bash
python app.py
```
Access the dashboard at: `http://127.0.0.1:5000`

---

## 🛠️ The Intelligence Modules

### 📋 1. Strategic Planner (The Brain)
The Strategic Planner generates a comprehensive **12-month Agricultural Roadmap**. It doesn't just suggest crops; it builds an entire business plan for your land.

- **How to Initiate**: Navigate to the "Plan" section and click **"Run AI Agent"**.
- **Calculations**: It processes land size, capital, and soil data to determine:
    - **Crop Roster**: Optimal main and inter-cropping sequences.
    - **Cashflow Projections**: Predicted monthly revenue vs. expenses (CapEx).
    - **Strategic Timing**: Precise sowing and harvest windows to catch high market prices.
- **AI Logic**: Primarily uses NVIDIA/Groq for rapid reasoning, with an auto-switch to **Gemini 1.5 Flash** if endpoints are busy.

### 🌱 2. Real-Time Growth Monitor
This dashboard provides a "Command Center" view of your farm's health.

- **Glassmorphic Interface**: Visualizes soil pH, Nitrogen, and Moisture via real-time (or simulated IoT) sensors.
- **Dynamic Insights**: AI analyzes current sensor data and weather forecasts to provide immediate recommendations.
- **Health Indicators**: Categorizes farm state (Optimal, Good, Needs Care) using ML thresholds.

### 🐛 3. Pest & Disease Intelligence
A predictive engine that forecasts biological risks before they manifest.

- **Predictive Modeling**: Analyzes humidity, temperature, and crop stage to predict bug outbreaks.
- **Actionable Alerts**: If a "High Risk" is detected, the system provides a specific protection protocol (spraying schedule, biological controls).

### 🍎 4. Market & Harvest Intelligence
Maximizes profit by connecting your farm to real-world market trends (via **Data.gov.in**).

- **Mandi Insights**: Live tracking of modal prices across Maharashtra districts (Pune, Nashik, Nagpur).
- **Selling Strategy**: High-level AI advice on whether to sell immediately or store harvest based on price trends.
- **Geo-Restricted Search**: Prioritizes local markets (Pune/MH) first, then suggests high-value national hubs.

### 💰 5. Financial Flow & ROI
Track your farm's performance like a modern enterprise.

- **Net Yield Tracker**: Real-time calculation of revenue minus expenses.
- **ROI Analysis**: Visualizes Return on Investment for each crop cycle.
- **Monthly Fiscal Bar Charts**: Identifies months of high surplus or potential deficit to help with financial planning.

---

## 🔍 System Architecture & Troubleshooting

### Bulletproof AI Pipeline
The platform uses a **Multi-Model Intelligence Layer**:
- **Layer 1 (Performance)**: Groq/NVIDIA Llama-3.1-405B for strategy.
- **Layer 2 (Reliability)**: Gemini 1.5 Flash acts as a fallback to ensure the system never crashes during API outages.

### Common Issues
> **Note**: **"AI Pipeline Initializing"**: This occurs during the first strategic run as the reasoning agent warms up. Please wait 10-15 seconds.
>
> **MongoDB Errors**: Ensure your IP address is whitelisted in MongoDB Atlas or your local service is running.

---

## 🎓 For Developers & Researchers

- **Logic Engines**: Explore `modules/pest_logic.py`, `soil_logic.py`, and `irrigation_logic.py` for the core agricultural intelligence.
- **Agentic Pipeline**: See the `agentic/` directory for the complex reasoning chains that power the 12-month planner.
- **UI Design**: The frontend is built with high-fidelity glassmorphism, using custom CSS variables (Emerald/Dark Mode) located in `index2.html` and `templates/`.

---

> **Tip**: Use the **"Refresh Report"** button in the dashboard to force-sync the latest market data and sensor readings.

*Developed for the Pune AgriAI Precision Agriculture Initiative 2026*