| # 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) |
| |
