Documentation

This page holds the technical detail that the farmer never needs to see. The product itself is one button.

Overview

Zora lets farmers with no formal education ask questions by voice in Hausa, Yorùbá, Igbo, Nigerian Pidgin or English, and hear a detailed, practical answer. Answers combine verified crop science from the KGML-Ag engine with the reasoning and language ability of OpenAI GPT.

How an answer is made

1. Listen.The farmer's voice is turned into text (OpenAI Whisper, or the browser speech engine as a fallback).
2. Ground. The question goes to the KGML-Ag service, which returns verified diagnosis patterns, recommended actions, safety limits and live weather for the farm location.
3. Explain.GPT receives the question plus the KGML-Ag facts. It must stay inside the verified safety limits, but expands them into a full explanation, step-by-step actions with amounts and timing, practical tips with how to apply each one, a low-cost option and a follow-up check, written in the farmer's language.
4. Speak. A short spoken version is generated with a natural Nigerian-accented voice and played back. The full written answer stays on screen.

If no OpenAI key is configured or the network is down, Zora automatically falls back to the built-in multilingual knowledge base so it never goes silent.

Voice and languages

• Speech to text: whisper-1 (Hausa, Yorùbá, English) with browser SpeechRecognition fallback.
• Text to speech: gpt-4o-mini-tts with accent and tone instructions, falling back to tts-1, then the device voice.
• Languages: English, Hausa, Yorùbá, Igbo, Nigerian Pidgin (Fulfulde supported in the API).

API

Public assistant endpoint (rate limited per IP):

POST /api/assistant
{
  "message": "Holes in my maize leaves",
  "language": "ha",           // en | ha | yo | ig | pcm | ff
  "history": []               // optional previous turns
}

→ {
  "spoken": "...",            // read aloud
  "diagnosis": "...",
  "severity": "high",
  "explanation": "...",
  "steps": ["..."],
  "tips": [{ "tip": "...", "howToApply": "..." }],
  "organicAlternative": "...",
  "safety": "...",
  "followUp": "...",
  "sources": ["IITA", "FAO"],
  "engine": { "kgml": true, "gpt": true, "model": "gpt-4o-mini" }
}

Supporting endpoints:

• POST /api/assistant/transcribe: multipart audio to text
• POST /api/audio/speech: text to natural speech (mp3)
• POST /api/advisory: authenticated advisory with audit logging (dashboard)

Platform modules

Behind the assistant, the staff dashboard offers a command centre, field registry, IoT sensors, digital MRV for carbon credits and model management. Staff sign in.

Run locally

git clone https://github.com/CCSA-Cosmopolitan/ccsa-zora.git
cd ccsa-zora
pnpm install

# web app (http://localhost:3001)
pnpm --filter @ccsa-zora/web dev

# KGML-Ag service (http://127.0.0.1:8100)
cd apps/kgml-api
python -m venv .venv && .venv\Scripts\activate
pip install -e .
uvicorn app.main:app --port 8100

Configuration

Set these in apps/web/.env.local:

OPENAI_API_KEY=sk-...        # enables GPT answers, Whisper and natural voice
OPENAI_MODEL=gpt-4o-mini     # or gpt-4o for higher quality
KGML_API_URL=http://127.0.0.1:8100
KGML_SERVICE_KEY=...