code4foodsecurityTeam4/postharvest-iq

A USSD-powered sell-or-store decision intelligence service for smallholder maize farmers in Northern Ghana. Built for the WFP Code4FoodSecurity Fellowship 2026. # PostHarvest IQ A USSD-based agricultural decision intelligence service for smallholder cereal farmers in Northern Ghana. Farmers dial `*384#` and answer three questions — crop, district, number of bags — and receive a **STORE** or **SELL NOW** recommendation backed by a machine learning price forecast. Built for the Blossom Academy Code4FoodSecurity Fellowship 2026. --- ## How it works (end to end) ``` Farmer dials *384# ↓ Africa's Talking USSD gateway → POST /ussd ↓ ussd_service.py (manages session, language, bag count) ↓ ml_service.py (orchestrates both models) ├── LSTM forecaster → price in 3 months (GHS) └── RF classifier → STORE or SELL_NOW ↓ recommendation_service.py (net return = forecast gain − storage cost − transport cost) ↓ USSD response in English / Dagbani / Hausa ``` --- ## Setup ```bash # Clone git clone github.com cd postharvest-iq # Environment conda create -n postharvest python=3.11 conda activate postharvest pip install -r requirements.txt # Configure cp .env.example .env # Fill in your MySQL credentials in .env # Database mysql -u root -p CREATE DATABASE IF NOT EXISTS postharvest_iq; EXIT; # Run migrations to create all tables alembic upgrade head # Seed warehouse data (run once after creating the DB) python scripts/seed_storage_locations.py # Extend price data to current month python -m scripts.extend_recent_prices # Train models python -m app.ml.train_lstm python -m app.ml.train_xgboost # Run API uvicorn app.main:app --reload --host localhost # (Optional) Monitoring dashboard streamlit run dashboard/streamlit_app.py ``` API docs: `localhost` --- ## Project structure ``` postharvest-iq/ ├── app/ # Main application (FastAPI) │ ├── main.py # App entry point — wires up all routes │ ├── config.py # Reads .env (DB credentials, secrets) │ ├── core/ │ │ └── database.py # SQLAlchemy eng …