🌱 CroPilot

• 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.

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.)

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

# 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.

• 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).

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.)

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.

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.

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.

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)

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.

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.

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

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