v1.1.0: the first run ends somewhere

pip install -U agronaut
agronaut setup

Then agronaut and start talking to it. That last part is what this release is about.

The first run now ends somewhere

1.0.0 could leave you stranded. Pick WhatsApp in agronaut setup and you got two lines pointing at the README, and nothing you could actually run. The closing "Try it" only ever offered the sizing calculator, which needs no model at all, plus the Telegram bot if you had chosen Telegram. So unless you picked Telegram, setup configured a model and then never gave you a single command that used it. Choosing "Terminal only" did not help either.

That was found by installing the package and using it, one day after 1.0.0 shipped.

• The terminal is offered first, and it is named. agronaut with no arguments is the chat, it needs no token and no account, and it works the moment setup exits.
• Setup always ends with a command you can run. However the channel step goes, including when it goes badly.
• WhatsApp is guided instead of deferred. It now prompts for the token, phone number id, app secret and allowed numbers, generates the verify token rather than sending you to hunt the dashboard for a value you are supposed to invent, and runs the WhatsApp doctor on what you entered.
• And it tells you the thing that actually blocks people. Telegram long-polls, so a laptop works. WhatsApp needs Meta to POST to a public HTTPS address, which means a tunnel running beside it. The wizard prints the cloudflared and ngrok one-liners and says plainly that a laptop is the wrong host for anything lasting.

A dead model provider no longer kills the session

The terminal chat used to raise an httpx traceback and exit if the provider was unreachable, which is easy to hit because setup will save LLM_PROVIDER=ollama right after telling you Ollama is not running. Now:

agronaut> I could not reach ollama at http://localhost:11434, so I cannot answer that right now.
Start it with `ollama serve`, then try again.
Run `agronaut setup` to switch provider. The sizing engine needs no model and still works: `agronaut size --help`

Rejected API keys and missing models get their own message, because "start the server" and "retype your key" are different instructions. Every one of them ends by naming the sizing engine, which needs no model and therefore always works.

Two new commands

agronaut --version prints where the code came from, not just a number:

agronaut 1.1.0
  code    /usr/local/lib/python3.12/site-packages/agronaut_agent
  python  /usr/local/bin/python3
  config  /home/you/.config/agronaut/.env

If you have both a checkout and a pip install, that path is the only way to tell which one you are running. It also flags an editable install and says that git pull is what updates it.

agronaut update checks PyPI and installs. It refuses to overwrite an editable install, because pip would silently detach the command from the checkout you are editing, and it will not offer you a downgrade when your build is ahead of the release.

Also in this release

• The PNG schematic rendered every label at the same size on macOS, because no font candidate matched and Pillow's fallback is pinned at 10px. Titles, box labels and arrows are distinct again.
• The database now stamps its schema version, so the first migration after 1.0.0 will not fail mid-conversation on somebody's only copy of their system history.
• CI runs Python 3.11 through 3.14. 3.13 was advertised and never tested; 3.14 was installable and tested by nobody.
• Water spinach (kangkong) joins the crop database. The crop table is at 32.
• One version number, in one place. aqua_model.__version__ had been sitting at "0.1.0" since before 1.0.0 because nothing read it.

What this does not change

The engineering core is the same as 1.0.0, and so is what it is willing to claim.

The production twin was scored against 7 real ponds on held-out data. It tracked the direction of change on 5 of 7, median correlation 0.30, and it beat both a flat and a linear-trend baseline on 0 of 7. So it is a tool for comparing options, not for predicting a level, and it says so in every projection it prints. The record is data/twin_validation.json and you can regenerate it with scripts/validate_twin.py.

Still not modelled: dissolved oxygen, pH and alkalinity, solids handling as anything but a fixed fraction, staggered cohorts, and micronutrient chemistry. Every design output lists its own gaps. Issues #108, #137, #138 and #107 are where that work is happening, and contributions are welcome.

Verified for this release: 1279 tests, the advice-safety golden set at 43 probes and 395 checks with no failures, and the built wheel installed into a clean environment and run from outside the checkout, with all 7 reference tables, 22 knowledge documents and the validation record present.

Thank you

Agronaut is a one-maintainer project, and it keeps getting better because people who have no obligation to help show up and help anyway. Everyone who has landed a change:

• @Mr-Neutr0n expanded the cited fish-species database (#81), which is why the model can answer "when do I harvest?" for more than a couple of species.
• @TrueFurina wrote the winter and cold-season operation knowledge document (#100). Written knowledge from someone who has actually run a system through a cold season is the kind of thing no amount of code produces.
• @kr1xh built the headless CLI for design and optimize (#93). That is the agronaut size command in the quick start above, and it is the reason the whole engine is usable with no browser and no model.
• @visheshbpatel added the India regional price book (#122), so cost estimates are true somewhere else too. This is the contribution the project most wants more of, one country at a time.
• @sOuL2000s added water spinach (kangkong) to the crop database (#127), a staple across South and Southeast Asia that the crop table could not grow.
• @jordansilly77-stack collapsed a duplicated filter in the retrieval layer (#31).

If you want to be on this list, #27 is the front door. The most valuable contributions here are usually not code: a price book for your country, a knowledge document, a photograph of a sick plant, or a published system the model can be tested against. No API key or ML experience needed for any of it.

v1.0.0: pip install agronaut

Agronaut computes aquaponics system designs from a deterministic, source-cited engineering
core, and talks to you on Telegram or WhatsApp from a bot you run yourself.

pip install agronaut
agronaut size --fish tilapia --crop lettuce --area 12 --temp 27 --water 3000

No API key, no account, no network. That prints a sized system with a bill of materials, a
source for every number, and an explicit list of what it does not model.

To add the conversation:

agronaut setup

It asks which model and which channel you want, validates each key against the live service
as you paste it, reads your Telegram id off a message you send your own bot, and writes the
config file itself.

What's in it

A deterministic core. Sizing, mass balance, nitrogen cycling, fish growth, crop growth
and costing, every coefficient carrying its source. aqua_model imports no LLM and no
network, and CI enforces that.

A production twin. Simulate a season at a real site through NASA POWER climate, log your
test-kit readings into a persistent twin, and forecast the week ahead. The growth
coefficient is fitted per pond against a public Nigerian catfish dataset (10 usable ponds
of 11), not taken from a textbook.

An advisory layer that proposes rather than acts. /advise turns the twin's state into
numbered recommendations, each with its reasoning, its source, what to measure to check it,
and a confidence derived from the class of evidence behind it, capped by what the twin's
own held-out validation earned. Nothing is actuated: you approve or reject by number.

Six model providers. Claude, Ollama (local, no key), NVIDIA, Hugging Face, a local
transformers pipeline, and any OpenAI-compatible endpoint. One environment variable
switches between them.

Two channels, one command layer. Telegram and WhatsApp share a single dispatcher, so
/log, /forecast, /advise and /approve behave identically on both. None of them put
a model in the path, so they keep working when the LLM does not.

A 3D view. Any design renders as an offline HTML page: graded pipe runs, a real
hydraulic grade line, and pump head derived from the drawing rather than a constant.

Honesty

The twin's absolute numbers are literature-seeded projections. Scored against held-out
nitrate it tracks the direction of change on 5 of 7 QC-passing ponds and does not beat a
linear-trend null on level, because the available pond sensors are uncalibrated. That
verdict is computed, not asserted (data/twin_validation.json), and the advisory layer caps
its own confidence to match. Dissolved oxygen and pH are not modelled at all, and every
output says so.

1,240 tests green in CI. A 43-case advice-safety golden set, 384 individual checks, gates CI.

MIT. The sizing method is a granted Taiwan utility model patent (TW M661364).