Made with 💚 by Lumi

🌱 CroPilot

The AI Copilot for Precision Agriculture — a complete farmer's assistant

See plant disease from a photo · Sense weather, soil & markets · Recommend fertilizer blends, crop rotation, what-to-plant & irrigation · Converse with a configurable BYOK AI assistant that ingests live data on the fly.

React + FastAPI + Python ML · only free / open data · runs with zero secrets via ./start.sh or docker compose up

---

What it does

Pillar	Capability	How
💬 COPILOT	A generative-UI workspace — the agent renders charts/tables/maps inline & in a preview pane; persisted multi-conversation history	CopilotKit + BYOK LLM (MiniMax-M3 + OpenAI/Anthropic/Gemini/Ollama)
🗺️ MAP	Draw & save field boundaries on satellite imagery · field-health (veg-index) & USDA crop-type overlays · field-boundary detection	MapLibre + Terra Draw · ESRI World Imagery · USDA CDL · OpenCV
👁️ SEE	Plant-disease ID from leaf / field / aerial images & video	Local MobileNetV2 CNN (PlantVillage) + LLM-vision (auto-routed)
📡 SENSE	Live weather, soil moisture/temp, ET₀, crop & fertilizer prices	Open-Meteo · USDA NASS · World Bank Pink Sheet · SSURGO/SoilGrids
🧪 RECOMMEND	Fertilizer raw-material blend · crop rotation · what-to-plant · irrigation · fertilizer buy-timing	Deterministic agronomy (FAO-56, blend math) + ML + SARIMAX
🧬 GENOMICS	Genomic-selection breeding sim — predict yield/traits (GEBV) · design the best crosses · forecast genetic gain · balance trait trade-offs; animated pipeline + Copilot Q&A over every run	rrBLUP · GBLUP · RandomForest · deep MLP (numpy + scikit-learn) on CropGS-style data
🚚 SUPPLY CHAIN	Fleet routing optimization on real roads — assign trucks across farms/packhouses/cold-storage/DCs/markets respecting capacity + cold-chain time limits, traced on the live road network, with the bottleneck hub flagged	OSMnx/OpenStreetMap (road network) · OR-Tools VRP · city2graph (supply-network graph)

Prerequisites

• Python 3.11+ and Node 20+ (with npm) — for the script / manual run
• Docker + Docker Compose — only for the Docker run
• (optional) Ollama for a free local LLM; (optional) a cloud LLM key (MiniMax / OpenAI / Anthropic / Gemini)

No API keys are required to start — the app boots with zero secrets.

Quick start

Option A — one script (no Docker) ✅ recommended

git clone https://github.com/CES-Ltd/cropPilot.git && cd cropPilot
./start.sh                 # 1st run: sets up venv + npm; then starts all 3 services (backend + runtime + frontend)
./start.sh --with-cnn      # same, but also installs the local pre-trained disease CNN (transformers+torch, ~2 GB)

start.sh auto-picks free ports (so it won't clash with anything already on :8000/:5173) and prints the actual URLs — watch the console, e.g.:

🚀 backend  → http://localhost:8000   (docs: /docs)
🚀 frontend → http://localhost:5173

Open the frontend URL it prints. Ctrl-C stops both. (make start does the same thing.)

Option B — Docker

cp .env.example .env          # optional — app boots with zero secrets
docker compose up --build     # frontend :5173 · backend :8000 · docs at :8000/docs
docker compose down           # stop

Option C — run the two servers manually

# terminal 1 — backend
cd backend && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt          # add: -r requirements-ml.txt  for the local CNN
uvicorn app.main:app --reload --port 8000

# terminal 2 — frontend
cd frontend && npm install
npm run dev                               # http://localhost:5173
# if the backend isn't on :8000, point the UI at it:  VITE_API_BASE=http://localhost:8001 npm run dev

Interactive API docs (Swagger) are always at <backend-url>/docs.

LLMs (BYOK) — set/change anytime in Settings → Providers

• MiniMax-M3 (default cloud option) — text + image + video; paste your key, endpoint api.minimax.io/v1.
• OpenAI / Anthropic / Gemini — paste your key.
• Ollama (local, zero-cost): ollama pull llama3.1 && ollama pull llama3.2-vision. Running locally (script/manual, not Docker)? Set the Ollama base URL to http://localhost:11434 in Settings → Providers (the host.docker.internal default is for the Docker run).

Plant-disease CNN — no training required

The local CNN uses a pre-trained Hugging Face PlantVillage model (auto-downloads & caches on first use, no key). Enable it with ./start.sh --with-cnn or pip install -r backend/requirements-ml.txt. Without it, disease ID still works via LLM-vision. (To train your own instead, see ml/ + scripts/train_disease.sh.)

Free data keys (optional) — Settings → Data-source API keys

Add your USDA NASS key in-app to enable live crop production / demand signals (Fernet-encrypted at rest).

Where keys are stored: saved BYOK/data keys are Fernet-encrypted in backend/.cropilot/ (git-ignored) and persist across restarts — for both ./start.sh and Docker (it's bind-mounted, so the same store is shared and survives docker compose down). make clean does not delete it. Pin CROPILOT_SECRET_KEY in .env if you reset that folder or deploy across multiple hosts.

Architecture

frontend/   Vite + React + TS + Tailwind + recharts + CopilotKit + MapLibre
  src/pages/Workspace.tsx    3-pane generative-UI copilot (history | chat | preview)
  src/pages/FieldMap.tsx     MapLibre satellite map: draw fields, overlays, detection
  src/components/copilot/    generative actions + artifact cards + preview pane
runtime/    Node CopilotKit runtime sidecar — proxies the chat to your BYOK LLM
backend/    FastAPI
  app/routers/         disease, crops, fertilizer, irrigation, prices, assistant, gis, conversations, settings, internal
  app/services/        agronomy engines, ML, GIS analysis, LiteLLM provider layer, persisted stores
  app/data_services/   cached clients for every free data source (Open-Meteo, NASS, World Bank, SoilGrids…)
ml/         offline training pipeline (MobileNetV2 on PlantVillage) — optional
seed/       committed offline fixtures (weather snapshot, Pink Sheet xlsx)

The Copilot runs as three processes (frontend + FastAPI backend + Node runtime); ./start.sh and docker compose up launch all three. The runtime reads your active BYOK key from the backend's localhost-guarded /internal endpoint — your key is never stored in the runtime or the browser.

See DATA_SOURCES.md for the full data-source list, licenses, and attribution.

Data & models

Big datasets and trained binaries are not committed — they're fetched on demand:

scripts/setup_data.sh       # (optional) download PlantVillage + refresh the Pink Sheet snapshot + Kaggle CSVs
scripts/train_disease.sh    # (optional) train your OWN MobileNetV2 on PlantVillage
scripts/download_models.sh  # (optional) pull a trained model you published to a GitHub Release

You usually don't need any of these: the disease CNN uses a pre-trained Hugging Face model that downloads automatically, the Pink Sheet ships as a committed snapshot in seed/, and the crop-recommendation CSV is vendored. The scripts are only for refreshing data or training your own model.

Status

Built in phases — see the in-repo plan. Each phase is independently runnable via docker compose up.

• Phase 0 — scaffold
• Phase 1 — four pillars (zero paid deps)
• Phase 2 — disease CNN + auto-routing
• Phase 3 — data depth + crop-recommend + plant-now
• Phase 4 — rotation + irrigation + assistant tools
• Phase 5 — price prediction + buy-timing
• Phase 6 — polish, BYOK security (Fernet), tests, offline seed fixtures
• v2 — CopilotKit generative-UI workspace · persisted conversations · GIS field mapping (MapLibre, draw boundaries, CDL + field-health overlays, boundary detection) · modern slate+indigo redesign
• v3 — Genomics & breeding simulation (genomic selection: rrBLUP/GBLUP/RandomForest/MLP · GEBV · crossing design · genetic-gain forecast · trait trade-offs · animated pipeline · Copilot Q&A over saved experiments)
• v4 — Supply-chain routing (real-road fleet VRP: OSMnx/OpenStreetMap network · OR-Tools capacity + cold-chain time-window optimization · city2graph supply-network graph + bottleneck hub · MapLibre route map · Copilot planSupplyRoutes)

Capabilities at a glance

Page	What it does	Free data / model
Copilot	Generative-UI chat — renders blend/price/irrigation/crop/map cards inline & in a preview pane; persisted history	CopilotKit + BYOK LLM
Field Map	Draw/save field boundaries on satellite; field-health & USDA crop-type overlays; boundary detection	MapLibre · Terra Draw · ESRI · USDA CDL · OpenCV
Dashboard	Live weather, soil moisture/temp, ET₀ vs rainfall chart	Open-Meteo
Disease ID	Leaf diagnosis (CNN→LLM auto) + aerial field-health veg-index map	PlantVillage CNN · LLM-vision · ExG/VARI/GLI
Fertilizer Blend	Soil NPK → raw-material blend (P→K→N), berry-aware	deterministic agronomy math
Crop Rotation	Previous crop → next-crop ranking + N-credit	rule engine (editable YAML)
What to Plant	Seasonal suggestions + ML NPK→crop recommender	RandomForest · phzmapi · NASS
Irrigation	FAO-56 ETc = Kc × ET₀ water-balance schedule	Open-Meteo ET₀
Markets & Buy-Timing	Fertilizer price forecast + best-time-to-buy	World Bank Pink Sheet · SARIMAX
Genomics	Genomic-selection breeding sim: predict GEBV · design best crosses · genetic-gain forecast · trait trade-offs — animated pipeline + plain-language reports	rrBLUP · GBLUP · RandomForest · MLP (numpy/scikit-learn) · CropGS-style data
Supply Chain	Fleet routing on real roads: assign trucks across facilities with capacity + cold-chain limits, draw routes on the map, flag the bottleneck hub	OSMnx/OpenStreetMap · OR-Tools VRP · city2graph

Supply Chain — how to use it

1. Open Supply Chain in the sidebar. A demo facility network (depot, farms, packhouse, cold storage, supplier, market in Monterey County) loads on a real road map.
2. Set the trucks, capacity per truck, and cold-chain limit (max minutes per route), then Optimize fleet routes. Each truck's route is drawn on the actual road network, color-coded, with a plan card (stops in order, load, distance, time, cost).
3. Tighten the inputs (fewer trucks, lower capacity, shorter cold-chain) and re-run — the optimizer will flag stops it can't serve within the limits so you know when you need another truck.
4. Add your own facilities (click the map to drop a location) or delete the demo ones.
5. Ask the Copilot: "plan the delivery routes with 4 trucks" — it runs the optimizer and renders the plan inline.

The road network is OpenStreetMap (no API key); a small demo graph is committed so it works offline, and any other region is fetched live on demand. Travel times/costs are estimates for decision-support. Refresh or extend the demo network with scripts/fetch_osm_graph.py.

Genomics — how to use it

1. Open Genomics in the sidebar. The bundled Rice (CropGS-style demo) panel loads automatically (400 lines × 4,000 SNPs, 5 correlated traits incl. yield).
2. Predict (GEBV) — pick a trait → ranks lines by genomic breeding value and compares the four models' cross-validated accuracy (linear GS typically wins on small data; the deep MLP is shown for honesty).
3. Design crosses — pick two parents → simulates 200 doubled-haploid progeny and shows the predicted trait distribution + chance of beating the elite check.
4. Crossing design — ranks the best parent pairs by usefulness (mid-parent GEBV + selection on segregation variance).
5. Genetic gain — forecasts multi-cycle recurrent-selection gain (the rising curve).
6. Trade-offs — builds a multi-trait selection index and plots the trait trade-off scatter.
7. Every run is saved as an experiment; ask the Copilot things like "design the best crosses for yield" or "summarize the results of my best cross" — it runs the pipeline and answers grounded in your saved runs.

GEBV/accuracy are model estimates on demo data — decision-support, not guarantees. The demo panel is synthesized CropGS-style (deterministic) for instant offline use; real CropGS-Hub data or your own genotype/phenotype CSVs load through the same pipeline. Methodology & attribution: DATA_SOURCES.md.

Tests

cd backend && . .venv/bin/activate && pip install -r requirements-dev.txt && pytest   # 28 engine + API + genomics + supply-chain tests
cd frontend && npm run build                                                          # typecheck + build

License

MIT (code). Data sources retain their own licenses — see DATA_SOURCES.md. Weather data by Open-Meteo.com (CC BY 4.0).