# Aglimate – Farmer-First Climate-Resilient Advisory Agent

## 1. Product Introduction

**Aglimate** is a multilingual, multimodal climate-resilient advisory agent designed specifically for Nigerian (and African) smallholder farmers. It provides farmer-first, locally grounded guidance using AI-powered assistance.

**Why Aglimate is important:**
- **Climate shocks are rising**: Irregular rains, floods, heat waves, and new pest patterns are already reducing yields for smallholder farmers.
- **Advisory gaps**: Most farmers still lack timely access to agronomists and extension officers in their own language.
- **Food security impact**: Smarter, climate-aware decisions at the farm level directly protect household income, nutrition, and national food security.

**Key Capabilities:**
- **Climate-smart Agricultural Q&A**: Answers questions about crops, livestock, soil, water, and weather in multiple languages.
- **Climate-Resilient Advisory**: Uses text + optional photo + GPS location to give context-aware, practical recommendations.
- **Live Agricultural Updates**: Delivers real-time weather information and agricultural news through RAG (Retrieval-Augmented Generation).

**Developer**: Oluchukwu Prosper
**Target Users**: Farmers, agronomists, agricultural extension officers, and agricultural support workers in Nigeria and similar contexts

---

## 2. Problem Statement

Nigerian smallholder farmers face significant challenges:

### 2.1 Limited Access to Agricultural Experts
- **Scarcity of agronomists and veterinarians** relative to the large farming population
- **Geographic barriers** preventing farmers from accessing expert advice
- **High consultation costs** that many smallholder farmers cannot afford
- **Long waiting times** for professional consultations, especially during critical periods (disease outbreaks, planting seasons)

### 2.2 Language Barriers
- Most agricultural information and resources are in **English**, while many farmers primarily speak **Hausa, Igbo, or Yoruba**
- **Technical terminology** is not easily accessible in local languages
- **Translation services** are often unavailable or unreliable

### 2.3 Fragmented Information Sources
- Weather data, soil reports, disease information, and market prices are scattered across different platforms
- **No unified system** to integrate and interpret multiple data sources
- **Information overload** without proper context or prioritization

### 2.4 Time-Sensitive Decision Making
- **Disease outbreaks** require immediate identification and treatment
- **Weather changes** affect planting, harvesting, and irrigation decisions
- **Pest attacks** can devastate crops if not addressed quickly
- **Delayed responses** lead to significant economic losses

### 2.5 Solution Approach
Aglimate addresses these challenges by providing:
- **Fast, AI-powered responses** available 24/7
- **Multilingual support** (English, Igbo, Hausa, Yoruba)
- **Integrated intelligence** combining expert models, RAG, and live data
- **Accessible interface** via text, voice, and image inputs
- **Professional consultation reminders** to ensure farmers seek expert confirmation when needed

---

## 3. System Architecture & Request Flows

### 3.1 General Agricultural Q&A – `POST /ask`

**Step-by-Step Process:**

1. **Input Reception**
   - User sends `query` (text) with optional `session_id` for conversation continuity

2. **Language Detection**
   - FastText model (`facebook/fasttext-language-identification`) detects input language
   - Supports: English, Igbo, Hausa, Yoruba

3. **Translation (if needed)**
   - If language ≠ English, translates to English using NLLB (`drrobot9/nllb-ig-yo-ha-finetuned`)
   - Preserves original language for back-translation

4. **Intent Detection**
   - Classifies query into categories:
     - **Weather question**: Requests weather information (with/without Nigerian state)
     - **Live update**: Requests current agricultural news or updates
     - **Normal question**: General agricultural Q&A
     - **Low confidence**: Falls back to RAG when intent is unclear

5. **Context Building**
   - **Weather intent**: Calls WeatherAPI for state-specific weather data, embeds summary into context
   - **Live update intent**: Queries live FAISS vectorstore index for latest agricultural documents
   - **Low confidence**: Falls back to static FAISS index for safer, more general responses

6. **Conversation Memory**
   - Loads per-session history from `MemoryStore` (TTL cache, 1-hour expiration)
   - Trims to `MAX_HISTORY_MESSAGES` (default: 30) to prevent context overflow

7. **Expert Model Generation**
   - Uses **Qwen/Qwen1.5-1.8B** (finetuned for Nigerian agriculture)
   - Loaded lazily via `model_manager` (CPU-optimized, first-use loading)
   - Builds chat messages: system prompt + conversation history + current user message + context
   - System prompt restricts responses to **agriculture/farming topics only**
   - Generates bounded-length answer (reduced token limit: 400 tokens for general, 256 for weather)
   - Cleans response to remove any "Human: / Assistant:" style example continuations

8. **Back-Translation**
   - If original language ≠ English, translates answer back to user's language using NLLB

9. **Response**
   - Returns JSON: `{ query, answer, session_id, detected_language }`

**Safety & Focus:**
- System prompt enforces agriculture-only topic handling
- Unrelated questions are redirected back to farming topics
- Response cleaning prevents off-topic example continuations

---

### 3.2 Climate-Resilient Multimodal Advisory – `POST /advise`

**Step-by-Step Process:**

1. **Input Reception**
   - `query`: Farmer question or situation description (required)
   - Optional fields: `latitude`, `longitude` (GPS), `photo` (field image), `session_id`

2. **Context Building**
   - Uses GPS (if provided) to query WeatherAPI for local weather snapshot
   - Uses shared conversation history (via `MemoryStore`) for continuity
   - Combines text, optional image, and weather/location context

3. **Multimodal Expert Model**
   - Uses **Qwen/Qwen2-VL-2B-Instruct** for vision-language reasoning
   - Generates concise, step-by-step climate-resilient advice:
     - Immediate actions
     - Short-term adjustments
     - Longer-term climate-smart practices

4. **Output**
   - JSON response: `{ answer, session_id, latitude, longitude, used_image, model_used }`

---

### 3.3 Climate & Weather Data APIs – `/weather/*`

To support climate-first decision making and give frontend engineers clear integration points, Aglimate exposes a set of WeatherAPI-backed endpoints:

- **`GET /weather/current`**  
  - **Inputs**: `q` (free query), or `state`, or `lat`+`lon`; optional `aqi`.  
  - **Output**: Raw WeatherAPI `current.json` (realtime weather + optional air quality).

- **`GET /weather/forecast`**  
  - **Inputs**: same `q` / `state` / `lat`+`lon`; `days` (1–14), `alerts`, `aqi`.  
  - **Output**: Raw `forecast.json` (multi-day forecast + alerts + AQI).

- **`GET /weather-alerts`**  
  - **Inputs**: `q` / `state` / `lat`+`lon`.  
  - **Output**: `{ location, alerts }` extracted from `forecast.json` for UI alert displays.

- **`GET /weather/history`**  
  - **Inputs**: `q` / `state` / `lat`+`lon`, `dt`, optional `end_dt`, `hour`, `aqi`.  
  - **Output**: Raw `history.json` for past climate/condition analysis.

- **`GET /weather/marine`**  
  - **Inputs**: `q` or `lat`+`lon`, `days` (1–7), `tides`.  
  - **Output**: Raw `marine.json` (marine + tide data where available).

- **`GET /weather/future`**  
  - **Inputs**: `q` / `state` / `lat`+`lon`, `dt` (future date).  
  - **Output**: Raw `future.json` (3-hourly forecast for future date).

- **`GET /weather/timezone`**  
  - **Inputs**: `q` / `state` / `lat`+`lon`.  
  - **Output**: Raw `timezone.json` (time zone + local time data).

- **`GET /weather/search`**  
  - **Inputs**: `q` (partial city/zip/etc.).  
  - **Output**: Raw `search.json` (location suggestions for UI autocompletes).

- **`GET /weather/ip`**  
  - **Inputs**: optional `ip` (falls back to `auto:ip`).  
  - **Output**: Raw `ip.json` (IP-based location lookup).

These endpoints are designed as thin pass-throughs over WeatherAPI, so frontend engineers can call them directly or use their outputs inside richer Aglimate views.

## 4. Technologies Used

### 4.1 Backend Framework & Infrastructure
- **FastAPI**: Modern Python web framework for building REST APIs and WebSocket endpoints
- **Uvicorn**: ASGI server for running FastAPI applications
- **Python 3.10**: Programming language
- **Docker**: Containerization for deployment
- **Hugging Face Spaces**: Deployment platform (Docker runtime, CPU-only environment)

### 4.2 Core Language Models

#### 4.2.1 Expert Model: Qwen/Qwen1.5-1.8B
- **Model**: `Qwen/Qwen1.5-1.8B` (via Hugging Face Transformers)
- **Purpose**: Primary agricultural Q&A and conversation
- **Specialization**: **Finetuned/specialized** for Nigerian agricultural context through:
  - Custom system prompts focused on Nigerian farming practices
  - Domain-specific training data integration
  - Response formatting optimized for agricultural advice
- **Optimization**: 
  - Lazy loading via `model_manager` (loads on first use)
  - CPU-optimized inference (float32, device_map="cpu")
  - Reduced token limits to prevent over-generation

#### 4.2.2 Multimodal Model: Qwen-VL
- **Model**: `Qwen/Qwen2-VL-2B-Instruct` (via Hugging Face Transformers)
- **Purpose**: Climate-resilient, image- and location-aware advisory
- **Usage**: Powers the `/advise` endpoint with text + optional photo + GPS

### 4.3 Retrieval-Augmented Generation (RAG)

- **LangChain**: Framework for building LLM applications
- **LangChain Community**: Community integrations and tools
- **SentenceTransformers**: 
  - Model: `paraphrase-multilingual-MiniLM-L12-v2`
  - Purpose: Text embeddings for semantic search
- **FAISS (Facebook AI Similarity Search)**: 
  - Vector database for efficient similarity search
  - Two indices: Static (general knowledge) and Live (current updates)
- **APScheduler**: Background job scheduler for periodic RAG updates

### 4.4 Language Processing

- **FastText**: 
  - Model: `facebook/fasttext-language-identification`
  - Purpose: Language detection (English, Igbo, Hausa, Yoruba)
- **NLLB (No Language Left Behind)**: 
  - Model: `drrobot9/nllb-ig-yo-ha-finetuned`
  - Purpose: Translation between English and Nigerian languages (Hausa, Igbo, Yoruba)
  - Bidirectional translation support

### 4.5 External APIs & Data Sources

- **WeatherAPI**: 
  - Provides state-level weather data for Nigerian states
  - Real-time weather information integration
- **AgroNigeria / HarvestPlus**: 
  - Agricultural news feeds for RAG updates
  - News scraping and processing

### 4.6 Additional Libraries

- **transformers**: Hugging Face library for loading and using transformer models
- **torch**: PyTorch (CPU-optimized version)
- **numpy**: Numerical computing
- **requests**: HTTP library for API calls
- **beautifulsoup4**: Web scraping for news aggregation
- **python-multipart**: File upload support for FastAPI
- **python-dotenv**: Environment variable management

---

## 5. Safety & Decision-Support Scope

- Aglimate is a **decision-support tool for agriculture**, not a replacement for agronomists, veterinarians, or extension officers.
- Advice is based on text, images, and weather/context data only – it does **not** perform lab tests or physical inspections.
- Farmers should always confirm high-stakes decisions (e.g., major input purchases, large treatment changes) with trusted local experts.

---

## 6. Limitations & Issues Faced

### 6.1 Diagnostic Limitations

#### Input Quality Dependencies
- **Image Quality**: Blurry, poorly lit, or low-resolution images reduce accuracy
- **Description Clarity**: Vague or incomplete symptom descriptions limit diagnostic precision
- **Context Missing**: Lack of field history, crop variety, or environmental conditions affects recommendations

#### Inherent Limitations
- **No Physical Examination**: Cannot inspect internal plant structures or perform lab tests
- **No Real-Time Monitoring**: Cannot track disease progression over time
- **Regional Variations**: Some regional diseases may be under-represented in training data
- **Seasonal Factors**: Disease presentation may vary by season, which may not always be captured

### 6.2 Language & Translation Challenges

#### Translation Accuracy
- **NLLB Limitations**: Can misread slang, mixed-language (e.g., Pidgin + Hausa), or regional dialects
- **Technical Terminology**: Agricultural terms may not have direct translations, leading to approximations
- **Context Loss**: Subtle meaning can be lost across translation steps (user language → English → user language)

#### Language Detection
- **FastText Edge Cases**: May misclassify mixed-language inputs or code-switching
- **Dialect Variations**: Regional variations within languages may not be fully captured

### 6.3 Model Behavior Issues

#### Hallucination Risk
- **Qwen Limitations**: Can generate confident but incorrect answers
- **Mitigations Applied**:
  - Stricter system prompts with domain restrictions
  - Shorter output limits (400 tokens for general, 256 for weather)
  - Response cleaning to remove example continuations
  - Topic redirection for unrelated questions
- **Not Bulletproof**: Hallucination can still occur, especially for edge cases

#### Response Drift
- **Off-Topic Continuations**: Models may continue with example conversations or unrelated content
- **Mitigation**: Response cleaning logic removes "Human: / Assistant:" patterns and unrelated content

### 6.4 Latency & Compute Constraints

#### First-Request Latency
- **Model Loading**: First Qwen/NLLB call is slower due to model + weights loading on CPU
- **Cold Start**: ~5-10 seconds for first request after deployment
- **Subsequent Requests**: Faster due to cached models in memory

#### CPU-Only Environment
- **Inference Speed**: CPU inference is slower than GPU (acceptable for Hugging Face Spaces CPU tier)
- **Memory Constraints**: Limited RAM requires careful model management (lazy loading, model caching)

### 6.5 External Dependencies

#### WeatherAPI Issues
- **Outages**: WeatherAPI downtime affects weather-related responses
- **Rate Limits**: API quota limits may restrict frequent requests
- **Data Accuracy**: Weather data quality depends on third-party provider

#### News Source Reliability
- **Scraping Fragility**: News sources may change HTML structure, breaking scrapers
- **Update Frequency**: RAG updates are scheduled; failures can cause stale information
- **Content Quality**: News article quality and relevance vary

### 6.6 RAG & Data Freshness

#### Update Scheduling
- **Periodic Updates**: RAG indices updated on schedule (not real-time)
- **Job Failures**: If update job fails, index can lag behind real-world events
- **Index Rebuilding**: Full index rebuilds can be time-consuming

#### Vectorstore Limitations
- **Embedding Quality**: Semantic search quality depends on embedding model performance
- **Retrieval Accuracy**: Retrieved documents may not always be most relevant
- **Context Window**: Limited context window may truncate important information

### 6.7 Deployment & Infrastructure

#### Hugging Face Spaces Constraints
- **CPU-Only**: No GPU acceleration available
- **Memory Limits**: Limited RAM requires optimization (lazy loading, model size reduction)
- **Build Time**: Docker builds can be slow, especially with large dependencies
- **Cold Starts**: Spaces may spin down after inactivity, causing cold start delays

#### Docker Build Issues
- **Dependency Conflicts**: Some Python packages may conflict (e.g., pyaudio requiring system libraries)
- **Build Timeouts**: Long build times may cause deployment failures
- **Cache Management**: Docker layer caching can be inconsistent

---

## 7. Recommended UX & Safety Reminders

### 7.1 Visual Disclaimers

**Always display a clear banner near critical advisory results:**

> "⚠️ **This is AI-generated agricultural guidance. Always confirm major decisions with a local agronomist, veterinary doctor, or agricultural extension officer before taking major actions.**"

### 7.2 Call-to-Action Buttons

Provide quick access to professional help:
- **"Contact an Extension Officer"** button/link
- **"Find a Vet/Agronomist Near You"** button/link
- **"Schedule a Consultation"** option (if available)

### 7.3 Response Quality Indicators

- Show **confidence indicators** when available (e.g., "High confidence" vs "Uncertain")
- Display **input quality warnings** (e.g., "Image quality may affect accuracy")
- Provide **feedback mechanisms** for users to report incorrect diagnoses

### 7.4 Language Support

- Clearly indicate **detected language** in responses
- Provide **language switcher** for users to change language preference
- Show **translation quality warnings** if translation may be approximate

---

## 8. System Summary

### 8.1 Problem Addressed

Nigerian smallholder farmers face critical challenges:
- **Limited access to agricultural experts** (agronomists, veterinarians)
- **Language barriers** (most resources in English, farmers speak Hausa/Igbo/Yoruba)
- **Fragmented information sources** (weather, soil, disease data scattered)
- **Time-sensitive decision making** (disease outbreaks, weather changes, pest attacks)

### 8.2 Solution Provided

Aglimate combines multiple AI technologies to provide:
- **Fast, 24/7 AI-powered responses** in multiple languages
- **Integrated intelligence**:
  - **Finetuned Qwen 1.8B** expert model for agricultural Q&A
  - **Multimodal Qwen-VL** model for image- and location-aware climate-resilient advisory
  - **RAG + Weather + News** for live, contextual information
- **CPU-optimized, multilingual backend** (FastAPI on Hugging Face Spaces)
- **Multiple input modalities**: Text, image, and GPS-aware advisory

### 8.3 Safety & Professional Consultation

- All guidance is **advisory** and should be confirmed with local professionals for high-stakes decisions.
- The system is optimized to reduce risk but cannot eliminate uncertainty or replace human judgment.

### 8.4 Key Technologies

- **Expert Model**: Qwen/Qwen1.5-1.8B (finetuned for Nigerian agriculture)
- **Multimodal Model**: Qwen/Qwen2-VL-2B-Instruct (image- and location-aware advisory)
- **RAG**: LangChain + FAISS + SentenceTransformers
- **Language Processing**: FastText (detection) + NLLB (translation)
- **Backend**: FastAPI + Uvicorn + Docker
- **Deployment**: Hugging Face Spaces (CPU-optimized)

### 8.5 Developer & Credits

**Developer**: Ifeanyi Amogu Shalom  
**Intended Users**: Farmers, agronomists, agricultural extension officers, and agricultural support workers in Nigeria and similar contexts

---

## 9. Future Improvements & Roadmap

### 9.1 Potential Enhancements

- **Model Fine-tuning**: Further fine-tune Qwen on Nigerian agricultural datasets
- **Multi-modal RAG**: Integrate images into RAG for visual similarity search
- **Offline Mode**: Support for offline operation in areas with poor connectivity
- **Mobile App**: Native mobile applications for better user experience
- **Expert Network Integration**: Direct connection to network of agronomists/veterinarians
- **Historical Tracking**: Track disease progression and treatment outcomes over time

### 9.2 Technical Improvements

- **Response Caching**: Cache common queries to reduce latency
- **Model Quantization**: Further optimize models for CPU inference
- **Better Error Handling**: More robust error messages and fallback mechanisms
- **Monitoring & Analytics**: Track system performance and user feedback

---

**Last Updated**: 2026 
**Version**: 1.0  
**Status**: Production (Hugging Face Spaces)