Draw a field. Ask a question. See why.
Draw the boundary on a map or import GeoJSON, fetch weather and Sentinel-2, and ask in plain English. Every input shows its origin, age and reliability.
Open research software · MIT · Python 3.9+
Advice that knows
when not to advise.
SmartAgri answers a farmer’s question about one maize field. Before a word is written, explicit rules decide whether it may recommend, recommend on a condition, ask one follow-up question, or abstain.
- “When should I irrigate?”
- “How much water should I apply?”
- “Is there a weather window for spraying this week?”
Four possible acts
The decision comes first.
The words come last.
The policy layer picks one act from the data that are actually available and how reliable they are. A language model, if one is configured, only phrases that act.
Recommend
The inputs this type of advice needs are present and reliable enough. A quantity is given only when the rules allow it.
Conditional
The answer hinges on one missing fact. Each possible value of that fact gets its own consequence.
Ask
One follow-up question, chosen because its answer would change the decision, with a tip on how to check it in the field.
Abstain
No recommendation, and the reason why. Questions outside the scope, or without support in the corpus, are referred to the extension service.
Features
Everything on the table.
Nothing hidden in a prompt.
On a phone, in the dark.
The same client, responsive, with light and dark themes and keyboard drawing.
Numbers from code
Crop water use, the water balance and irrigation doses come from tested FAO-56 functions, never from the language model.
ETc = Kc × ET0
Provenance in every run
Each answer stores its configuration, corpus and prompt hashes, the decision date, and the satellite and forecast dates it used.
Runs offline
SQLite and a deterministic template generator by default. No keys, no model and no network access to one.
English by default
Answers are in English. Set SMARTAGRI_LOCALE=sr-Latn for the local language. Sources stay in their original language.
How it works
Seven layers
you can read and test.
Each layer is plain code with its own tests and configuration file. Every answer keeps each layer’s decision, so “Why?” has a concrete answer.
- C
Context
The parcel, its agronomic inputs, Open-Meteo weather and Sentinel-2 L2A NDVI, each with its date.
- π
Applicability
A deterministic filter over passage metadata: crop, growth stage, region, date and source type. No hidden model.
- q
Quality
Origin, age, coverage and reliability of every input. Missing inputs are listed, never filled in.
- σ
Sufficiency
Whether the inputs are enough for the type of advice asked for, and which are missing.
- α
Next question
A missing input whose answer would change the decision, weighed against the effort of answering it.
- δ
Policy
The act: recommend, conditional, ask or abstain, with a reason code and whether a quantity is allowed.
- γ
Grounding
Checks the answer: numbers must come from the tools, and sentences must be supported by the cited passages.
Interfaces
One core.
Three ways in.
The web app and the research API share one service. The evaluation harness calls the decision pipeline directly, so its results never depend on the web layer.
A map-first client, served by the API.
- Draw the parcel on a map, or paste or import GeoJSON
- Fetch weather and Sentinel-2, with each input’s age and reliability
- Ask under any variant V0–V5 and answer the follow-up question
- Open “Why?” for the π, q, σ, α, δ and γ decisions and the provenance hashes
- Blind rating of evaluation items, without variant labels
- Open
http://127.0.0.1:8100- Client
- Plain JavaScript, no build step
- Map
- Leaflet 1.9.4, vendored with its licence
- Network
- Map tiles only; configurable, or off
- Themes
- Light and dark, follow the system
- Answers
- English by default;
SMARTAGRI_LOCALE
A small HTTP API for local research.
FastAPI, bound to 127.0.0.1 and without accounts by default. The OpenAPI schema is at /docs. For a public server, SMARTAGRI_ACCOUNTS=optional adds optional email accounts: anyone can try it, and a parcel is saved once you create an account.
- Parcels and their input profile with quality q
- Advisory conversation under a chosen variant
- Every run stored with config, corpus and prompt hashes
- Rubric and blinded rating queue
Terminal · commands, not output
python -m smartagri.research_api --port 8100
curl -s localhost:8100/api/health
curl -s -X POST localhost:8100/api/parcels \
-H 'Content-Type: application/json' \
-d @parcel.json # name, sowing_date, geometry
curl -s -X POST localhost:8100/api/parcels/$ID/profile/refresh
curl -s -X POST localhost:8100/api/parcels/$ID/chat \
-H 'Content-Type: application/json' \
-d '{"text": "When should I irrigate?", "variant": "V5"}'The evaluation harness, one command line.
runscenario sets under one or more variantsreportautomatic and rated measures, paired comparisonsguardn-gram leakage check between scenarios and corpuslocksha256 of scenarios, corpus, config, prompts and rater guideexportandsweepfor items, ratings and synthetic variations
Terminal · commands, not output
cd backend
python -m smartagri.evalkit run --set dev
python -m smartagri.evalkit report
python -m smartagri.evalkit report --compare V4 V3
python -m smartagri.evalkit guard --set devEvaluation and reproducibility
Built to be checked,
not just believed.
The repository holds the method and the harness. This page reports no results.
V0answer without retrieval
V1+ hybrid retrieval (BM25 + vectors)
V2+ π over the question’s conditions
V3+ π over the parcel, context C
V4+ q, σ and α
V5+ δ and γ
Ablation ladder
Each variant adds to the one before, so a paired comparison such as V4 against V3 isolates what those layers change. A free LLM conversation with the same data and passages (VC) is a baseline outside the ladder.
Blind rating
Raters score items on a five-criterion rubric with critical-error classes. They never see the variant, generator or model, and each rater gets a fixed item order.
Protocol lock
Before measurement, a lock file records the sha256 of the scenarios, corpus, configuration, prompts and rater guide. Held-out test scenarios are published only after the lock.
Limitations
A research prototype,
with clear edges.
- One crop. Maize only.
- One region. Rules, thresholds and passages are set for one reference region.
- Sources in their original language. Answers are in English by default;
SMARTAGRI_LOCALE=sr-Latnswitches them to the local language (Serbian, Latin script). The published development corpus consists of short paraphrases in Serbian, so source titles and excerpts appear in Serbian. The blind rating screen follows the rater guide and stays in the local language. - Small corpus. Short paraphrases of FAO material with citations, plus development notes marked as not an expert source.
- Not a substitute for an agronomist. The system can be wrong. It states its inputs and their reliability so that you can judge.
- Optional services. Sentinel-2 needs Copernicus Data Space credentials; the VC chat needs a configured language model.
Get started
Running in minutes.
No keys needed.
Python 3.9 or newer. SQLite and offline mode by default; Docker is not required.
Linux / macOS
git clone https://github.com/ZeljkoDzafic/smartagri-core.git
cd smartagri-core/backend
python3 -m venv .venv && . .venv/bin/activate
pip install -c constraints-py39.txt -e ".[dev,api]"
pytest -q
python -m smartagri.research_api # http://127.0.0.1:8100On Python 3.12, use -c requirements.lock. On Windows, create the environment with py -m venv .venv and run .venv\Scripts\python.exe. Optional settings are listed in .env.example: SMARTAGRI_LOCALE sets the answer language, and SMARTAGRI_TILE_URL sets another tile server (none turns tiles off).