Shuka

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Shuka

Inspiration

Nigeria has roughly one agricultural extension worker per several thousand farmers. The modern fallback — ask an AI — fails exactly where farming happens: no connectivity, low-end laptops, no payment rails. Worse, small models are dangerous agronomists: our baseline run had the bare 1B model recommending 30 maize seeds per hole, harvesting cassava at 4 months, and fungicide for striga (a parasitic weed).

What it does

Shuka is a fully offline agronomy assistant for the people farmers already ask — extension workers, agro-dealers and cooperative offices. Every answer is grounded in 8 license-verified extension manuals (FAO, IITA, CABI, IRRI — about 850 pages) and cited by manual and page, like a printed bulletin. When the manuals don't cover a question, Shuka refuses and points to the local extension office — silence beats confident error when the cost of being wrong is someone's growing season. Desk features: one-click printed answer sheets, a local ledger that answers reworded repeat questions in 0.3 seconds, and copy-as-text for WhatsApp.

The evidence — all published in the repo

• 30-question adversarial eval, same model twice: raw 9 dangerous answers, 0 correct → grounded 0 dangerous, 17 correct
• Red team: 8 adversarial prompts (prompt injection, dosage pressure, roleplay, citation forgery) → 0/8 unsafe
• Official ADTC profiler: 19.2 tok/s generation (reference is 15), 1.39 GB peak of the 7 GB budget, zero thermal throttling
• Full transcripts, grading rubric, benchmark records, red-team results and an honest limitations section

How we built it

Llama 3.2 1B Instruct Q4_K_M on llama.cpp — the saer uses, one GGUF shared by app and judge. MiniLMONNX embeddings, exact cosine retrieval over 1,308 passages, a two-tier relevance gate tuned on recorded eval scores, greedy decoding with a repetition penalty, unit tests pinineering finding worth sharing: hybrid P/E-corelaptop CPUs starve generic llama.cpp builds (~3 tok/s), but the same laptop's integrated GPU over Vulkan prefills 27× faster — the most underused compute in the African laptop fleet

Challenges

A full disk that corrupted the first model download; TLS-intercepting networks breaking every package manager differently; discovering our own model's dangerous hallucinatio around never letting it speak unsupervised.

What's next

Nigeria's NAERLS bulletins the day their licensing clears; Hausa, Yoruba and Pidgin question understanding; a packaged installer; and a first field pilot with a cooperative — to reservations.

Built With

• llama-3.2
• llama.cpp
• node-llama-cpp
• node.js
• onnx
• transformers.js
• vulkan