agronaut 1.0.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,12 @@
+"""agent — the LLM-facing layer that wraps the deterministic aqua_model core.
+
+Dependency rule (eng review): this layer may import from `aqua_model`, never the reverse.
+`aqua_model` stays pure and Ollama-free; everything that touches the LLM or the UI lives here.
+"""
+
+# Load project-root .env (HF_TOKEN, etc.) as early as possible. Importing any agent
+# submodule — the UI (calculator_ui/optimizer_ui) or the chat layer (agent.llm) —
+# triggers this, so secrets land in os.environ before any backend is built.
+from agent.env import load_env as _load_env
+
+_load_env()

agent/calculator_ui.py

@@ -0,0 +1,209 @@
+"""Streamlit view for the M1 design calculator.
+
+A structured form (the right UI for fixed engineering inputs) → the validated trust gate
+→ size_system() → results + the funder-facing report as a download. No LLM in this path:
+every number shown is traceable to a cited coefficient.
+"""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from agent import facts
+from aqua_model import size_system
+from aqua_model.report import to_markdown
+
+
+def _render_channel_verdict(label: str, c: dict, mode: str) -> None:
+    target, dne, median = c["target_band"], c["do_not_exceed_band"], c["median"]
+    position = c["median_position"]
+
+    if position == "within target band":
+        icon, verdict = "✅", "real ponds sit inside your target band"
+    elif dne[0] <= median <= dne[1]:
+        icon = "⚠️"
+        verdict = f"real ponds run {position.replace(' target band', '')} target (still within safe limits)"
+    else:
+        icon = "🚩"
+        verdict = f"real ponds run {position.replace(' target band', '')} target — outside safe limits"
+
+    st.markdown(f"**{icon} {label}** — {verdict}")
+    line = f"real median **{median}**"
+    if mode == "summary":
+        line += f" (p5–p95: {c['p5']}–{c['p95']})"
+    line += f"  ·  your target {target[0]}–{target[1]}  ·  safe {dne[0]}–{dne[1]}"
+    if mode == "full":
+        line += (
+            f"  ·  **{c['frac_in_target'] * 100:.0f}%** of readings in target, "
+            f"**{c['frac_in_do_not_exceed'] * 100:.0f}%** within safe limits"
+        )
+    st.caption(line)
+
+
+def _render_reality_check(operating_envelope: dict) -> None:
+    """Compare this design's envelope against real-pond readings (open dataset)."""
+    from aqua_model import datasets
+
+    reality = datasets.envelope_reality_check(operating_envelope)
+    with st.expander("Reality check — your envelope vs. real ponds"):
+        if reality is None:
+            st.caption(
+                "Open dataset not loaded. Run `python scripts/fetch_aquaponics_data.py` to "
+                "compare against ~233k readings from four real aquaponics ponds."
+            )
+            return
+        n = reality.get("n_readings")
+        scope = f"~{n:,} readings, " if n else ""
+        st.caption(
+            f"Compared against {scope}{reality['source']}. Only temperature and pH are "
+            "cross-checked — turbidity and ammonia sensors in this dataset are saturated and "
+            "not trustworthy."
+        )
+        labels = {"water_temp_c": "Water temperature (°C)", "ph": "pH"}
+        for channel, c in reality["channels"].items():
+            _render_channel_verdict(labels.get(channel, channel), c, reality["mode"])
+
+
+def _render_coefficient_sources(species: str, crop: str) -> None:
+    """Show the chosen species/crop sizing coefficients against published empirical ranges."""
+    from aqua_model import calibration as cal
+
+    relevant = [c for c in cal.all_calibrations() if c.key.split(".")[0] in (species, crop)]
+    if not relevant:
+        return
+    n_out = sum(not c.within for c in relevant)
+    title = "Sizing coefficients vs. published ranges"
+    if n_out:
+        title += f"  ⚠️ {n_out} outside range"
+    with st.expander(title):
+        st.caption(
+            "Seed values pinned to peer-reviewed empirical ranges. ✅ in range · ⚠️ outside — "
+            "calibrate against your own system before building."
+        )
+        for c in relevant:
+            icon = "✅" if c.within else "⚠️"
+            st.markdown(
+                f"**{icon} {c.label}** — seed **{c.seed} {c.unit}**  ·  "
+                f"published **{c.emp_low}–{c.emp_high}**  ·  _{c.verdict}_"
+            )
+            st.caption(c.note + "  \nSources: " + "; ".join(c.sources))
+
+
+def render_calculator() -> None:
+    st.subheader("Design Calculator")
+    st.caption(
+        "Size one system from fixed inputs. Pure deterministic model — no AI guessing; "
+        "every number is traceable to a cited coefficient."
+    )
+
+    with st.form("design_form"):
+        col1, col2 = st.columns(2)
+        with col1:
+            species = st.selectbox("Fish species", facts.available_species())
+            crops = st.multiselect(
+                "Crops", facts.available_crops(), default=["lettuce"],
+                help="Pick 2+ for a MIXED BED sharing one system — the grow area is split "
+                     "evenly, and the model warns if the crops can't share one water.")
+            site = st.text_input("Site / project name (optional)", "")
+        with col2:
+            grow_area = st.number_input("Grow area (m²)", min_value=0.1, value=6.0, step=0.5)
+            temperature = st.number_input("Mean water temp (°C)", min_value=0.0, max_value=45.0, value=26.0, step=0.5)
+            water_budget = st.number_input("Water budget (L/day)", min_value=0.0, value=200.0, step=10.0)
+            system_type = st.selectbox(
+                "Growing method", facts.available_system_types(),
+                help="raft/DWC (forgiving, more water), NFT (light, low water, needs reliable "
+                     "power), or media bed (robust, also biofilters).")
+        submitted = st.form_submit_button("Size system", use_container_width=True)
+
+    if not submitted:
+        st.info("Set your inputs and press **Size system**.")
+        return
+
+    if not crops:
+        st.error("Pick at least one crop.")
+        return
+
+    try:
+        if len(crops) > 1:
+            design = facts.design_from_form(
+                fish_species=species, crop=None, grow_area_m2=None,
+                temperature_c=temperature, water_budget_lpd=water_budget,
+                system_type=system_type,
+                crop_plan=facts.split_area_evenly(crops, grow_area),
+            )
+        else:
+            design = facts.design_from_form(
+                fish_species=species, crop=crops[0], grow_area_m2=grow_area,
+                temperature_c=temperature, water_budget_lpd=water_budget,
+                system_type=system_type,
+            )
+    except facts.ValidationError as err:
+        st.error("Invalid inputs:\n" + "\n".join(f"- {e}" for e in err.errors))
+        return
+
+    out = size_system(design)
+
+    if out.feasible:
+        st.success("Feasible design.")
+    else:
+        st.warning(f"Not feasible — binding constraint: **{out.binding_constraint}**.")
+
+    if out.crop_plan:
+        st.caption("Mixed bed (crops sharing the water): "
+                   + ", ".join(f"{p['crop']} {p['area_m2']:g} m²" for p in out.crop_plan))
+
+    for w in out.warnings:
+        st.warning(w)
+
+    m1, m2, m3 = st.columns(3)
+    m1.metric("Feed", f"{out.feed_g_per_day:g} g/day")
+    m2.metric("Fish", f"{out.fish_count} head")
+    m3.metric("Biomass", f"{out.fish_biomass_kg:g} kg")
+    m4, m5, m6 = st.columns(3)
+    m4.metric("System volume", f"{out.system_volume_l:g} L")
+    m5.metric("Pump", f"{out.pump_turnover_lph:g} L/h")
+    m6.metric("Makeup water", f"{out.makeup_water_lpd:g} L/day")
+    if out.footprint_ratio != 1.0:
+        st.metric("Floor footprint", f"{out.footprint_m2:g} m²",
+                  help=f"{out.grow_area_m2:g} m² of growing area packed onto the floor "
+                       f"(~{out.footprint_ratio:g}× via vertical towers).")
+
+    import base64
+
+    from aqua_model.schematic import to_svg
+    svg = to_svg(out)
+    st.subheader("System schematic")
+    # SVG rendered as a data-URI <img> (st.image's PIL path can't parse raw SVG).
+    b64 = base64.b64encode(svg.encode("utf-8")).decode("ascii")
+    st.markdown(f'<img src="data:image/svg+xml;base64,{b64}" style="max-width:100%"/>',
+                unsafe_allow_html=True)
+    st.download_button("Download schematic (SVG)", data=svg,
+                       file_name="agronaut_schematic.svg", mime="image/svg+xml")
+
+    with st.expander("Bill of materials"):
+        st.table(out.bill_of_materials)
+    with st.expander("Operating envelope"):
+        st.json(out.operating_envelope)
+    _render_reality_check(out.operating_envelope)
+    with st.expander("Nitrogen consistency check"):
+        st.json(out.nitrogen_check)
+    with st.expander("What is NOT modeled (read before building)"):
+        for n in out.not_modeled:
+            st.markdown(f"- {n}")
+    with st.expander("Coefficients used (auditable)"):
+        st.table([
+            {"name": c.name, "value": c.value, "range": f"{c.low}–{c.high}", "unit": c.unit, "source": c.source}
+            for c in out.coefficients_used
+        ])
+    # Coefficient-source panels for each crop in the design (one for a single crop).
+    for c in (crops or []):
+        _render_coefficient_sources(species, c)
+
+    report_md = to_markdown(design, out, site=site or None)
+    st.download_button(
+        "Download design report (Markdown)",
+        data=report_md,
+        file_name=f"aquaponics-design-{(site or 'system').strip().replace(' ', '-').lower()}.md",
+        mime="text/markdown",
+        use_container_width=True,
+    )

agent/classifier.py

@@ -0,0 +1,231 @@
+"""Pluggable image-classifier backend — an extra FEATURE source, never a verdict source.
+
+A specialist classifier (a PlantVillage-class CNN, say) beats a general vision model at
+fine-grained leaf disease. The temptation is to let its label be the answer. That would
+undo the whole point of the vision path: a label like `Tomato___Late_blight` is a diagnosis
+with no citation, no discriminating check, and no statement of what it cannot see.
+
+So the classifier is wired in as a **third source of categorical features**, alongside the
+prose extractor:
+
+    photo ──▶ VLM ──────────▶ prose ──▶ features ─┐
+        └──▶ classifier ──▶ label ──▶ features ───┴─▶ aqua_model.triage ──▶ cited differential
+
+The label is mapped, by a fixed table, onto the SAME `ObservationFeatures` vocabulary the
+prose extractor uses. Consequences that matter:
+
+* the differential's candidates stay cited to `knowledge/*.md` — a classifier can never
+  introduce an uncited candidate, no matter how confident it is;
+* a wrong label can only select a different branch of a differential, exactly like a
+  misread adjective;
+* the label itself is surfaced to the user as an unverified model suggestion, clearly
+  separated from the cited differential.
+
+Provider-agnostic, mirroring `agent/llm.py` and `agent/vision.py`: select with
+CLASSIFIER_PROVIDER / CLASSIFIER_MODEL. **No backend ships with Agronaut yet** — this is the
+seam a contributor implements. `default_classifier()` returns None until one exists, so the
+whole path is inert by default and nothing changes for existing deployments.
+
+Adding a backend: see CONTRIBUTING.md ("Adding an image classifier").
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+# Below this, a label is discarded rather than fed forward. A low-confidence guess is worse
+# than no guess: it adds a branch to the differential while carrying no real information.
+MIN_CONFIDENCE = 0.60
+
+DEFAULT_MODELS: dict[str, str] = {
+    # No backend is bundled yet. A contributor adding one registers its default here and a
+    # builder in _build_classifier_backend below. See issue "Plant-disease classifier".
+}
+SUPPORTED = tuple(DEFAULT_MODELS)
+
+
+@dataclass(frozen=True)
+class Prediction:
+    """One classifier output. `label` is the model's raw class name — kept verbatim so it can
+    be shown to the user as what the model actually said."""
+
+    label: str
+    confidence: float
+
+
+# --- label → features -------------------------------------------------------------------
+# The mapping is deliberately COARSE. We are not translating a diagnosis; we are extracting
+# the visible evidence a diagnosis would have been based on, so the cited table can do the
+# reasoning. `late blight` becomes "there are brown spots on the leaves", not "late blight".
+#
+# Keys are matched as substrings against a normalised label, so the same entry covers
+# `Tomato___Late_blight`, `tomato late blight`, and `Late Blight (tomato)`.
+_LABEL_FEATURES: tuple[tuple[str, dict], ...] = (
+    # nutrient pictures — the ones the cited table discriminates best
+    ("iron deficien",      {"leaf_pattern": ["interveinal"], "colour": ["yellow"], "leaf_age": "new"}),
+    ("interveinal",        {"leaf_pattern": ["interveinal"], "colour": ["yellow"]}),
+    ("nitrogen deficien",  {"leaf_pattern": ["whole_pale"], "colour": ["yellow"], "leaf_age": "old"}),
+    ("potassium deficien", {"leaf_pattern": ["margin_scorch"], "colour": ["brown"], "leaf_age": "old"}),
+    ("calcium deficien",   {"leaf_pattern": ["tip_burn"], "leaf_age": "new"}),
+    ("tip burn",           {"leaf_pattern": ["tip_burn"], "leaf_age": "new"}),
+    ("blossom_end",        {"leaf_pattern": ["tip_burn"], "leaf_age": "new"}),
+    ("blossom end",        {"leaf_pattern": ["tip_burn"], "leaf_age": "new"}),
+    # fungal / bacterial leaf disease → visible evidence only
+    ("powdery_mildew",     {"leaf_pattern": ["powder"], "colour": ["white"]}),
+    ("powdery mildew",     {"leaf_pattern": ["powder"], "colour": ["white"]}),
+    ("downy_mildew",       {"leaf_pattern": ["powder"], "colour": ["white"]}),
+    ("downy mildew",       {"leaf_pattern": ["powder"], "colour": ["white"]}),
+    ("late_blight",        {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("late blight",        {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("early_blight",       {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("early blight",       {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("leaf_spot",          {"leaf_pattern": ["spots"]}),
+    ("leaf spot",          {"leaf_pattern": ["spots"]}),
+    ("leaf_mold",          {"leaf_pattern": ["spots"], "colour": ["yellow"]}),
+    ("leaf mold",          {"leaf_pattern": ["spots"], "colour": ["yellow"]}),
+    ("rust",               {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("blight",             {"leaf_pattern": ["spots"], "colour": ["brown"]}),
+    ("root_rot",           {"root_state": "brown_slimy"}),
+    ("root rot",           {"root_state": "brown_slimy"}),
+    ("pythium",            {"root_state": "brown_slimy"}),
+    # pests
+    ("spider_mite",        {"pests_visible": ["mites"], "leaf_pattern": ["stippled"]}),
+    ("spider mite",        {"pests_visible": ["mites"], "leaf_pattern": ["stippled"]}),
+    ("aphid",              {"pests_visible": ["aphids"]}),
+    ("whitefly",           {"pests_visible": ["whiteflies"]}),
+    ("whiteflies",         {"pests_visible": ["whiteflies"]}),
+    ("thrip",              {"leaf_pattern": ["stippled"]}),
+    # fish
+    ("ich",                {"fish_body": ["white_spots"], "subject": ["fish"]}),
+    ("white_spot",         {"fish_body": ["white_spots"], "subject": ["fish"]}),
+    ("fin_rot",            {"fish_body": ["frayed_fins"], "subject": ["fish"]}),
+    ("fin rot",            {"fish_body": ["frayed_fins"], "subject": ["fish"]}),
+    ("saprolegnia",        {"fish_body": ["cotton_tufts"], "subject": ["fish"]}),
+    ("columnaris",         {"fish_body": ["lesion"], "subject": ["fish"]}),
+    # explicit healthy: carries no symptom, and must not invent one
+    ("healthy",            {}),
+)
+
+_LEAF_SUBJECT_HINT = re.compile(r"leaf|leaves|plant|tomato|lettuce|potato|pepper|corn|grape|"
+                                r"apple|cherry|peach|strawberr|squash|orange|blueberr|raspberr|"
+                                r"soybean", re.IGNORECASE)
+_FISH_SUBJECT_HINT = re.compile(r"fish|tilapia|catfish|carp|trout|koi", re.IGNORECASE)
+
+
+def _normalise(label: str) -> str:
+    return re.sub(r"[_\-/]+", " ", str(label or "")).strip().lower()
+
+
+def features_from_predictions(predictions) -> dict:
+    """Merge classifier labels into `ObservationFeatures` keyword arguments.
+
+    Only predictions at or above MIN_CONFIDENCE are considered, and only the coarse visible
+    evidence is extracted — never the diagnosis itself. Returns {} when nothing maps, which
+    leaves the differential to the prose extractor alone.
+
+    Pure and total: any iterable of Prediction-like objects in, a plain dict out."""
+    merged: dict = {}
+
+    def _add_seq(key: str, values) -> None:
+        cur = list(merged.get(key, []))
+        for v in values:
+            if v not in cur:
+                cur.append(v)
+        merged[key] = cur
+
+    for pred in predictions or ():
+        label = _normalise(getattr(pred, "label", ""))
+        try:
+            confidence = float(getattr(pred, "confidence", 0.0))
+        except (TypeError, ValueError):
+            continue
+        if not label or confidence < MIN_CONFIDENCE:
+            continue
+
+        # Subject comes from the label's own words, so a leaf class can't imply a fish.
+        if _FISH_SUBJECT_HINT.search(label):
+            _add_seq("subject", ["fish"])
+        elif _LEAF_SUBJECT_HINT.search(label):
+            _add_seq("subject", ["plant"])
+
+        for needle, feats in _LABEL_FEATURES:
+            if needle not in label:
+                continue
+            for key, value in feats.items():
+                if isinstance(value, list):
+                    _add_seq(key, value)
+                else:
+                    merged.setdefault(key, value)   # first scalar wins; don't fight the prose
+            break                                    # first (most specific) entry only
+    return merged
+
+
+def describe_predictions(predictions) -> str:
+    """One line naming what the classifier said, for the agent turn.
+
+    Presented as an unverified suggestion and kept OUT of the cited differential, because a
+    classifier label has no source, no discriminating check, and no statement of its limits."""
+    kept = [p for p in (predictions or ())
+            if float(getattr(p, "confidence", 0.0) or 0.0) >= MIN_CONFIDENCE]
+    if not kept:
+        return ""
+    parts = ", ".join(f"{getattr(p, 'label', '?')} ({float(p.confidence):.0%})" for p in kept[:3])
+    return ("[An image classifier suggested: " + parts + ". That is an UNVERIFIED model label "
+            "with no source — it is NOT part of the cited differential below. Use it only as a "
+            "hint about what to look at, and never repeat it as a diagnosis.]")
+
+
+def resolve(provider: str | None = None, model: str | None = None) -> tuple[str, str]:
+    provider = (provider or os.getenv("CLASSIFIER_PROVIDER") or "").strip().lower()
+    if not provider:
+        raise ValueError("No CLASSIFIER_PROVIDER set (no classifier backend ships yet).")
+    if provider not in SUPPORTED:
+        supported = ", ".join(SUPPORTED) or "none yet — see CONTRIBUTING.md"
+        raise ValueError(f"Unknown CLASSIFIER_PROVIDER {provider!r}. Supported: {supported}.")
+    model = model or os.getenv("CLASSIFIER_MODEL") or DEFAULT_MODELS[provider]
+    return provider, model
+
+
+def _build_classifier_backend(provider: str, model: str):
+    """Return a callable(image_bytes) -> list[Prediction]. Lazy imports, so adding a backend
+    never adds a hard dependency for anyone not using it."""
+    raise ValueError(  # pragma: no cover - no backend bundled yet
+        f"No classifier backend implemented for {provider!r}. See CONTRIBUTING.md "
+        "('Adding an image classifier') — this is a wanted contribution.")
+
+
+def make_classifier(backend):
+    """Wrap a backend callable into classify(image_bytes) -> list[Prediction]."""
+    def _classify(image_bytes: bytes):
+        raw = backend(image_bytes) or []
+        out = []
+        for item in raw:
+            if isinstance(item, Prediction):
+                out.append(item)
+                continue
+            try:                                     # accept (label, confidence) tuples too
+                label, confidence = item
+                out.append(Prediction(str(label), float(confidence)))
+            except Exception:
+                log.debug("classifier returned an unusable prediction: %r", item)
+        return out
+    return _classify
+
+
+def default_classifier():
+    """A lazily-built classifier for the configured provider, or None when unavailable —
+    which is the normal case today, since no backend is bundled. Never raises."""
+    if os.getenv("AGRONAUT_CLASSIFIER", "").lower() in {"off", "0", "false"}:
+        return None
+    try:
+        provider, model = resolve()
+        backend = _build_classifier_backend(provider, model)
+    except Exception:
+        log.debug("classifier backend unavailable", exc_info=True)
+        return None
+    return make_classifier(backend)

agent/env.py

@@ -0,0 +1,75 @@
+"""Minimal .env loader — no third-party dependency.
+
+Reads KEY=VALUE lines into os.environ. Real environment variables always win, so a shell
+export or a systemd unit overrides the file rather than fighting it.
+
+Where it looks, in order, first file wins:
+
+1. `$AGRONAUT_ENV_FILE` — an explicit path, for a service unit or a second deployment.
+2. `./.env` in the working directory — what someone expects after `cd ~/my-farm`.
+3. `~/.config/agronaut/.env` (or `$XDG_CONFIG_HOME`) — the per-user home for an
+   installed tool, and the answer for anyone who did `pip install agronaut`.
+4. The project root, for a source checkout.
+
+Order 2 and 3 exist because of a real gap: the loader used to look only at the project
+root, computed from this file's location. Inside an installed wheel that resolves to
+`site-packages/.env`, a path nobody will ever create — so a user who installed from PyPI
+had no way to configure a Telegram token at all except re-exporting variables in every new
+shell. State already went to the right per-user place; configuration did not follow it.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+
+def user_config_dir() -> Path:
+    """Per-user config directory. Honours XDG, as the data and cache dirs already do."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return (Path(base) if base else Path.home() / ".config") / "agronaut"
+
+
+def candidates() -> list[Path]:
+    """Every place a .env may live, in precedence order."""
+    explicit = os.environ.get("AGRONAUT_ENV_FILE")
+    found = [Path(explicit)] if explicit else []
+    found.append(Path.cwd() / ".env")
+    found.append(user_config_dir() / ".env")
+    found.append(_PROJECT_ROOT / ".env")
+    # Preserve order while dropping repeats (a checkout run from its own root hits the
+    # working directory and the project root with the same path).
+    seen, out = set(), []
+    for p in found:
+        key = str(p)
+        if key not in seen:
+            seen.add(key)
+            out.append(p)
+    return out
+
+
+def load_env(path: str | os.PathLike | None = None) -> Path | None:
+    """Load the first .env found and return it, or None when there is nothing to load."""
+    paths = [Path(path)] if path else candidates()
+    for env_path in paths:
+        try:
+            if not env_path.is_file():
+                continue
+            text = env_path.read_text()
+        except OSError:
+            # An unreadable candidate is not fatal: fall through to the next one rather
+            # than stop a bot from starting over a permissions problem on a stale path.
+            continue
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            key = key.strip()
+            val = val.strip().strip('"').strip("'")
+            if key and key not in os.environ:
+                os.environ[key] = val
+        return env_path
+    return None

agent/facts.py

@@ -0,0 +1,76 @@
+"""Fact collection seam between the UI/LLM and the deterministic model.
+
+For M1 the design calculator takes FIXED, structured inputs, so the safest "fact collection"
+is a validated form (no free-text parsing, no LLM guessing engineering numbers). This module
+exposes the option lists the UI needs and a single typed entry point into the trust zone.
+
+The free-text parsers in `srcs/chatbot.py` (temperature/pH/species extraction for the
+conversational troubleshooting flow) are extracted here in M3, when the orchestrator is
+refactored. They are not needed by the M1 calculator and are intentionally left untouched.
+"""
+
+from __future__ import annotations
+
+from aqua_model.crops import CROPS
+from aqua_model.species import SPECIES
+from aqua_model.types import DesignInput
+from aqua_model.validate import ValidationError, validate_design_input
+
+
+def available_species() -> list[str]:
+    return sorted(SPECIES)
+
+
+def available_crops() -> list[str]:
+    return sorted(CROPS)
+
+
+def available_system_types() -> list[str]:
+    from aqua_model.system_types import SYSTEM_TYPES
+    return list(SYSTEM_TYPES)
+
+
+def design_from_form(
+    fish_species: str,
+    crop: str,
+    grow_area_m2: float,
+    temperature_c: float,
+    water_budget_lpd: float,
+    source_water_note: str | None = None,
+    system_type: str = "raft",
+    crop_plan: list[dict] | None = None,
+) -> DesignInput:
+    """Validate structured form values into a DesignInput. Raises ValidationError on bad input.
+
+    This is the ONLY way the UI puts numbers into the model — the validation gate, reused.
+    Pass crop_plan (a list of {crop, area_m2}) for a mixed bed; then crop/grow_area_m2 are
+    derived from it and may be None.
+    """
+    return validate_design_input(
+        fish_species=fish_species,
+        crop=crop,
+        grow_area_m2=grow_area_m2,
+        temperature_c=temperature_c,
+        water_budget_lpd=water_budget_lpd,
+        source_water_note=source_water_note,
+        system_type=system_type,
+        crop_plan=crop_plan,
+    )
+
+
+def split_area_evenly(crops: list[str], grow_area_m2: float) -> list[dict]:
+    """Turn a list of crops + a total area into an even-split crop_plan. The calculator form
+    can't collect per-crop areas reactively inside one submit, so it splits equally; the chat
+    agent (size_mixed_bed_aquaponics) takes explicit per-crop areas for finer control."""
+    per = round(grow_area_m2 / len(crops), 3)
+    return [{"crop": c, "area_m2": per} for c in crops]
+
+
+__all__ = [
+    "available_species",
+    "available_crops",
+    "available_system_types",
+    "design_from_form",
+    "split_area_evenly",
+    "ValidationError",
+]