# 🌱 Agronaut
[](https://pypi.org/project/agronaut/)
[](https://github.com/Rekin226/Agronaut/actions/workflows/ci.yml)
[](pyproject.toml)
[](LICENSE)
[](https://github.com/Rekin226/Agronaut/labels/good%20first%20issue)
**An open-source agriculture assistant you run on your own computer. It combines cited
aquaponics and hydroponics design with farm records and experimental field irrigation
tools, in the terminal, browser, Telegram or WhatsApp.**
Describe your water, space and species, and Agronaut returns a buildable design: tank and
pump sizes, fish count, feed rate, a bill of materials, the operating range to keep, a source
for every number, and a list of what it does *not* model. The language model only collects
facts and explains results. The numbers come from code you can audit.
Built by a working aquaponics operator. The sizing method is a granted Taiwan utility model
patent (TW M661364); the code is MIT.
---
## Quick start
You need **Python 3.11 or newer**.
### 1. Size a system (no API key, no account, offline)
```bash
pip install agronaut
agronaut size --fish tilapia --crop lettuce --area 12 --temp 27 --water 3000
```
You get a full design in a few seconds:
```
FEASIBLE design (raft / DWC grow beds).
Sizing: feed=720 g/day, fish=96 head, biomass=48 kg, system_volume=6666.7 L, rearing_tank=2400 L, pump=6666.7 L/h against 0.52 m head (~27 W), makeup_water=58 L/day
Biofilter media: ~84.57 m2 surface
Bill of materials:
...
```
followed by the operating range, a nitrogen cross-check, every coefficient with its source, and
what the design does not model.
Then try:
```bash
agronaut list # species and crops it knows
agronaut optimize --area 10 --temp 28 --water 5000 --objective food # best fish × crop ratio
```
### 2. Talk to it
```bash
agronaut setup # pick a model and a channel; it checks each key as you paste it
agronaut # chat in the terminal
agronaut web # or in the browser at http://localhost:8501
```
Choose any model you like:
- **Local, free, no key:** install [Ollama](https://ollama.com), then `ollama pull qwen3.5:4b`.
- **Your own API key:** Claude (Anthropic).
- **NVIDIA's hosted models** still work, set by hand: see [configuration](docs/configuration.md).
Run `agronaut setup` again any time to switch models or add a channel. Your saved keys are kept.
### 3. Put it on your phone (optional)
```bash
agronaut bot # Telegram (recommended: one token from @BotFather)
agronaut whatsapp # WhatsApp (more setup, see docs/whatsapp_setup.md)
```
On your phone, `/log ammonia 0.5 nitrate 40 temp 27` records a reading and `/forecast` shows
the week ahead. Neither calls a model, so they work even when the model is slow or offline.
### What needs a model?
| You want | You need |
|---|---|
| `size`, `size-hydro`, `optimize`, `list`, the Design page in the web app | **Nothing.** Deterministic, offline, cited. |
| Chat, photos, voice notes | A model (local or your own key) |
| Farm records, field calculations, `/log`, `/forecast`, `/plant`, `/waterlog`, `/measure`, `/task`, `/overview`, `/guide` | No model; messaging channels still need their channel configuration and connectivity |
### 4. Explore field irrigation
Version 1.4 adds crop-water and soil-water accounting, drip and sprinkler design checks,
surface-irrigation event analysis, and records from planting through harvest. These
calculations are **experimental, not field validated**. Surface cutoff recommendations
remain unsupported; missing measurements stay unknown.
From a source checkout (which includes the example inputs):
```bash
agronaut capabilities --system soil
agronaut water-needs --input examples/field_water.json
agronaut design-irrigation --method drip --input examples/drip_design.json
agronaut field-guide --topic choose-method --language fr
```
In the web app, use **Farm overview**, **Field records**, **Crop records**, and
**Farm resources**. The existing **Assistant**, **Design**, **My Twin**, and **Quality**
pages remain available. French and Traditional Chinese field guidance is available;
independent language and grower usability review remains outstanding.
---
## What it does
- **Designs aquaponic and hydroponic systems** for 10 fish species and 34 crops, with a bill of
materials and a downloadable report.
- **Finds the best fish-to-crop ratio** for your water budget, maximising food, protein or
water efficiency.
- **Runs a consultation**, one question at a time, and remembers your system between sessions.
- **Reads photos** of sick fish, yellow leaves or green water and returns a ranked, cited list
of possible causes, never a single confident verdict.
- **Simulates a season** for your site with real climate data, and shows it in an offline 3D view.
- **Checks its own replies**: every number the assistant quotes must match what the engine
computed.
More detail: [docs/features.md](docs/features.md).
---
## How it works
```
you ──▶ assistant (language model: collects facts, routes, explains)
│ proposes values
▼
validation gate ── rejects bad or uncertain input
│
▼
aqua_model: the engineering core (pure Python, tested, every number cited)
│
▼
a sized system + bill of materials + operating range + sources + "not modelled" list
```
The core (`aqua_model/`) imports no model and no network, and every coefficient carries a
value, a range, a unit and a published source (mostly FAO 589 and Goddek et al. 2019). The
assistant can only reach it through the validation gate. See
[docs/architecture.md](docs/architecture.md).
---
## How good is it? (measured, not claimed)
```bash
agronaut eval # every quality measurement, its last result and its age
```
- **Advice safety:** automated aquatic and field checks, enforced in CI on every change.
- **The season simulator** was scored against 7 real ponds on held-out data. It got the
**direction** of change right on 5 of 7, but did not beat a simple trend baseline on the
**level** on any of them. Use it to compare options, not to predict a number.
- **Answer faithfulness** is about 0.8 (0.79 on fresh answers on 2026-10-06, 0.84 on the
2026-09-30 answers under the same judge), with no fabricated citations. The automated judge
agrees with a person only fairly, so treat this as a guide.
- **Not modelled yet:** dissolved oxygen, pH and alkalinity, solids handling, staggered
harvests, micronutrients. Every design lists its own gaps.
Method and numbers: [docs/evaluation.md](docs/evaluation.md).
---
## When something is off
```bash
agronaut doctor # checks install, config, model, channels; every failure comes with a fix
agronaut --version # the version and which copy of the code is running
agronaut update # install the latest release
```
---
## Run from source
```bash
git clone https://github.com/Rekin226/Agronaut.git
cd Agronaut
python3 -m venv .venv && source .venv/bin/activate
pip install -e . pytest
python -m pytest # the full test suite, no model needed
python -m scripts.safety_eval # the advice-safety golden set
agronaut web # the app, from your checkout
```
Or with Docker:
```bash
docker compose up web # the web app at http://localhost:8501
docker compose --profile bot up # web + the Telegram bot (needs a .env)
```
---
## Documentation
| Page | What's in it |
|---|---|
| [Install and run](docs/running.md) | Every install option, all CLI commands, Docker, a hosted demo, keeping a bot running |
| [Configuration](docs/configuration.md) | Model providers, self-hosting with open weights, every environment variable |
| [WhatsApp setup](docs/whatsapp_setup.md) | Meta's dashboard, step by step |
| [Features](docs/features.md) | Photos, the 3D twin, voice, the consultation, honesty rules |
| [Architecture](docs/architecture.md) | The trust zone, the engineering model, project layout, the agent skill |
| [Evaluation](docs/evaluation.md) | Retrieval tuning, tracing, faithfulness, reply grounding |
| [Field calculations](docs/FIELD_CALCULATIONS.md) | Water demand, soil accounting, irrigation methods, assumptions and limits |
| [Crop records](docs/CROP_RECORDS.md) | Planting, scouting, work, harvest and season review |
| [Farm resources](docs/FARM_RESOURCES.md) | Shared water, supplies, equipment and recorded use |
| [Nutrient accounting](docs/NUTRIENT_ACCOUNTING.md) | Nutrient budgets and their limits |
| [Field-cycle rehearsal](docs/FIELD_CYCLE_REHEARSAL.md) | Reproduce a synthetic workflow, including a clean installation |
| [Privacy](docs/dpg/PRIVACY.md) | What is recorded, where, and how to delete it |
---
## Contributing
You don't need an API key, a GPU or ML experience. The most valuable contributions are often
not code:
- 🌾 **Agronomy knowledge:** a crop, a species, a symptom rule, a correction, with its source.
- 💰 **A price book for your country**, so cost estimates are true where you live.
- 📊 **Real system data** (feed, harvest weights, water readings) to calibrate the model.
- 📷 **Photographs** of deficient leaves, sick fish or algae.
Start with [issue #27](https://github.com/Rekin226/Agronaut/issues/27), the
[good first issues](https://github.com/Rekin226/Agronaut/labels/good%20first%20issue) and
[CONTRIBUTING.md](CONTRIBUTING.md). One rule before you write code: `aqua_model/` stays pure,
and every number in it needs a published source.
## Citing Agronaut
If you use Agronaut in research or programme work, see [CITATION.cff](CITATION.cff).
## Licence
Code: MIT, see [LICENSE](LICENSE). The knowledge corpus has mixed licences (FAO 589 is
non-commercial); see [docs/dpg/CORPUS.md](docs/dpg/CORPUS.md).