ChaiMetrics
KTDA Farm Intelligence Dashboard

AI-powered analytics platform for KTDA smallholder tea farmers, delivering yield predictions, seasonal forecasting, and plain-language farm insights.

Overview

ChaiMetrics is a multi-farm analytics platform built for smallholder tea farmers operating under the Kenya Tea Development Agency (KTDA) network. It combines machine learning, time-series forecasting, and a local AI narrative engine to turn raw farm data into actionable intelligence — presented in a way that is accessible to both field officers and farmers.

The platform currently models **240 farms across 15 seasons**, with two real KTDA factories integrated as reference nodes: Weru Factory (WRU-01, Tharaka-Nithi) and Rukuriri Factory (RKR-01, Embu, Fairtrade certified).

Key Features

Yield Prediction
Uses an XGBoost model trained on domain-accurate synthetic farm data to predict green leaf yield per farm. Accounts for pruning recovery curves, seasonal patterns, and weather inputs sourced from Open-Meteo.

Seasonal Forecasting
SARIMA/SARIMAX time-series models forecast yield trends across the KTDA season calendar (July–June), including minibonus payment month patterns and pruning cycle effects.

AI Farm Narratives
A cloud-hosted Groq LLM (qwen) generates plain-language summaries of farm performance, making insights readable for non-technical stakeholders and field extension officers.

Multi-Farm Dashboard
A React-based frontend presents per-farm and aggregate analytics, with support for farm-level drill-down, seasonal comparisons, and factory-level aggregation.

Weather Integration
Live and historical weather data pulled from Open-Meteo is fed into forecasting models to contextualise yield variation against rainfall and temperature conditions.

Project Status

Active Development - Core ML pipeline and API are functional. 
Frontend dashboard and deployment pipeline are actively being refined. Not yet production-ready for field deployment.

Tech Stack

| Layer | Technology |
|---|---|
| Frontend | React |
| Backend API | Flask (Python) |
| ML Models | XGBoost, LightGBM |
| Forecasting | SARIMA / SARIMAX |
| LLM Narratives | Groq (qwen)|
| Database | MongoDB |
| Cache | Redis |
| Weather Data | Open-Meteo API |
| Containerisation | Docker / Docker Compose |
| Deployment | Render |

Repository Structure

```
chaimetrics/
├── api/                  # Flask backend service
│   ├── blueprints/       # Route handlers (farms, insights, forecasts)
│   ├── utils.py          # Model loading and shared utilities
│   ├── app.py            # App factory
│   └── Dockerfile
├── models/               # Trained ML model artefacts (.pkl, .parquet)
├── scripts/              # preprocess.py, train_xgboost.py, generate_data.py
├── docker-compose.yml
└── README.md
```
ML Pipeline

Before running the API, model artefacts must be generated locally by running the training pipeline in order:

```bash
python scripts/preprocess.py
python scripts/train_xgboost.py
```

This produces the following files under `models/`:

```
models/
├── xgb_yield.pkl
├── preprocessor.pkl
├── xgb_feature_importances.parquet
├── X_features.parquet
└── row_ids.parquet
```

These artefacts are copied into the API container at build time and are required for the `/farms/:id/insights` endpoint to function.

---
Factory Reference Nodes

| Factory | Code | County | Certification |
|---|---|---|---|
| Weru | WRU-01 | Tharaka-Nithi | — |
| Rukuriri | RKR-01 | Embu | Fairtrade |

For KTDA Stakeholders

ChaiMetrics is designed to support factory managers, extension officers, and KTDA programme teams with data-driven tools for farm performance monitoring. The platform does not replace field knowledge — it augments it by surfacing patterns across large numbers of farms that would be difficult to track manually.

Insights are generated in plain language and are intended to be interpretable without a technical background. If you are a KTDA stakeholder interested in a demonstration or data partnership, please reach out via the contact details below.
Email - mogakanewton0@gmail.com

Contributing

This project is in active development. If you are a developer interested in contributing — particularly in areas of ML model improvement, frontend UX, or KTDA data integration — feel free to open an issue or submit a pull request.

License

To be defined. All rights reserved pending formal licensing decision.


Built for the Kenyan tea farming ecosystem.