Spaces:

nexusbert
/

Aglimate

Sleeping

App Files Files Community

Aglimate / SYSTEM_OVERVIEW.md

nexusbert

Update SYSTEM_OVERVIEW.md

12b9ece verified 29 days ago

preview code

raw

history blame contribute delete

19.8 kB

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:

Input Reception
- User sends query (text) with optional session_id for conversation continuity
Language Detection
- FastText model (facebook/fasttext-language-identification) detects input language
- Supports: English, Igbo, Hausa, Yoruba
Translation (if needed)
- If language ≠ English, translates to English using NLLB (drrobot9/nllb-ig-yo-ha-finetuned)
- Preserves original language for back-translation
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
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
Conversation Memory
- Loads per-session history from MemoryStore (TTL cache, 1-hour expiration)
- Trims to MAX_HISTORY_MESSAGES (default: 30) to prevent context overflow
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
Back-Translation
- If original language ≠ English, translates answer back to user's language using NLLB
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:

Input Reception
- query: Farmer question or situation description (required)
- Optional fields: latitude, longitude (GPS), photo (field image), session_id
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
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
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)