Deploy Waterleaf challenge app

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.venv
+.pytest_cache
+.ruff_cache
+.env
+data
+tests
+evaluation
+docs
+

.env.example

@@ -0,0 +1,13 @@
+# Hugging Face Space runtime
+WATERLEAF_DATA_DIR=data
+PUBLIC_BASE_URL=http://localhost:7860
+WATERLEAF_LOCAL_USER=local-gardener
+
+# Optional care-data provider
+PERENUAL_API_KEY=
+
+# Modal proxy-authenticated llama.cpp endpoint
+MODAL_ENDPOINT=
+MODAL_KEY=
+MODAL_SECRET=
+

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/sample-lavender.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+data/
+.superpowers/
+

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    WATERLEAF_DATA_DIR=/data
+
+RUN pip install --no-cache-dir uv==0.11.8 \
+    && useradd --create-home --uid 1000 user
+
+WORKDIR /app
+COPY --chown=user:user pyproject.toml uv.lock README.md ./
+COPY --chown=user:user waterleaf ./waterleaf
+COPY --chown=user:user assets ./assets
+COPY --chown=user:user app.py ./
+
+RUN uv sync --frozen --no-dev
+
+USER user
+ENV PATH="/app/.venv/bin:${PATH}"
+
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/health', timeout=3)"
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Hakan Karaoguz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -1,10 +1,266 @@
 ---
 title: Waterleaf
-emoji: 💻
-colorFrom: gray
-colorTo: yellow
+emoji: 🌿
+colorFrom: green
+colorTo: red
 sdk: docker
-pinned: false
+app_port: 7860
+hf_oauth: true
+hf_oauth_expiration_minutes: 43200
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Waterleaf
+
+Waterleaf identifies an outdoor garden plant from one to three photographs,
+grounds the result in a plant taxonomy database, builds an editable
+weather-aware watering plan, and exports one 30-day calendar for the garden.
+
+Built by Hakan Karaoguz (`hkaraoguz`) for the 2026 Hugging Face Build Small
+Hackathon.
+
+## Workflow
+
+1. Upload or capture one to three photographs of one plant.
+2. Gemma 4 extracts visible traits and proposes likely names.
+3. GBIF resolves those names to valid plant species.
+4. Gemma reranks only the valid records.
+5. Confirm or replace the species through autocomplete.
+6. Preview weather-adjusted dates and edit them.
+7. Save plants and export one whole-garden ICS file.
+
+## Architecture
+
+- **UI and web:** Gradio Blocks mounted in FastAPI
+- **Authentication:** Hugging Face OAuth
+- **Persistence:** SQLite and normalized JPEGs on an attached HF Storage Bucket
+- **Vision model:** `ggml-org/gemma-4-26B-A4B-it-GGUF`
+- **Runtime:** llama.cpp `server-cuda13-b9445` on a Modal L4
+- **Taxonomy:** GBIF Species API
+- **Care data:** Perenual, with persistent caching and manual interval fallback
+- **Weather:** Open-Meteo geocoding and 16-day forecast
+- **Calendar:** RFC 5545-compatible ICS with stable UIDs, alarms, profile URLs,
+  and image attachments
+
+See [docs/architecture.md](docs/architecture.md) for the data flow and privacy
+boundaries.
+
+## Local Development
+
+Python 3.11-3.13 and `uv` are supported.
+
+```bash
+uv sync
+uv run uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+Open `http://localhost:7860`. Without `MODAL_ENDPOINT`, Waterleaf uses a
+deterministic lavender demo identifier. Local persistence uses the
+`local-gardener` identity and `data/` directory.
+
+Run checks:
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## Modal Deployment
+
+### 1. Authenticate the Modal CLI
+
+Install the deploy dependency and connect the local CLI to the Modal workspace:
+
+```bash
+uv sync --group deploy
+uv run --group deploy modal setup
+```
+
+### 2. Deploy llama.cpp
+
+Deploy the protected GPU service:
+
+```bash
+uv run --group deploy modal deploy modal_app.py
+```
+
+The Modal service:
+
+- uses the pinned `ghcr.io/ggml-org/llama.cpp:server-cuda13-b9445` image;
+- starts `Gemma 4 26B-A4B Q4_K_M` with automatic multimodal projector download;
+- uses an 8K context, full GPU offload, Flash Attention, Q8 KV cache, and one
+  parallel slot;
+- uses a bounded 256-token thinking pass for database-candidate reranking while
+  keeping initial visual extraction non-thinking and schema-constrained;
+- caches Hugging Face artifacts in a Modal Volume;
+- requires Modal proxy-auth headers.
+
+The command prints the `modal.run` URL. Save it as `MODAL_ENDPOINT`.
+
+For the live demo and judging window, keep one container warm:
+
+```bash
+MODAL_MIN_CONTAINERS=1 uv run --group deploy modal deploy modal_app.py
+```
+
+Return to zero warm containers after judging to stop idle GPU spend:
+
+```bash
+MODAL_MIN_CONTAINERS=0 uv run --group deploy modal deploy modal_app.py
+```
+
+### 3. Create proxy credentials
+
+In Modal Workspace Settings, create a **Web endpoint proxy auth token**. Save
+the token ID as `MODAL_KEY` and token secret as `MODAL_SECRET`. These are not
+the same credentials used by `modal setup`.
+
+Test the endpoint before configuring the Space:
+
+```bash
+MODAL_ENDPOINT=https://...modal.run \
+MODAL_KEY=wk-... \
+MODAL_SECRET=ws-... \
+uv run python scripts/smoke_modal.py assets/sample-lavender.png
+```
+
+If a proxy token has not been created yet, a controlled one-time smoke test can
+temporarily publish the endpoint:
+
+```bash
+MODAL_PROXY_AUTH=0 MODAL_MIN_CONTAINERS=1 \
+  uv run --group deploy modal deploy modal_app.py
+MODAL_ENDPOINT=https://...modal.run \
+  uv run python scripts/smoke_modal.py assets/sample-lavender.png
+MODAL_PROXY_AUTH=1 MODAL_MIN_CONTAINERS=0 \
+  uv run --group deploy modal deploy modal_app.py
+```
+
+The middle deployment is unauthenticated and should exist only for the smoke
+test. Always run the final restore command immediately afterward.
+
+## Space Configuration
+
+### 1. Create the Space
+
+Create `build-small-hackathon/waterleaf` in the Hugging Face UI with:
+
+- **SDK:** Docker
+- **Visibility:** Public
+- **License:** MIT
+
+If the hackathon organization does not allow direct creation, create
+`hkaraoguz/waterleaf` first and transfer or duplicate it into the requested
+hackathon namespace.
+
+The root README metadata already enables Docker on port `7860` and HF OAuth.
+
+### 2. Push this repository
+
+Add the Space as a Git remote and push the feature branch:
+
+```bash
+git remote add hf https://huggingface.co/spaces/build-small-hackathon/waterleaf
+git push hf feat/waterleaf:main
+```
+
+Use an HF user access token as the Git password when prompted. Do not commit
+that token or any deployment secret.
+
+### 3. Attach persistent storage
+
+In **Space Settings → Storage Buckets**:
+
+1. Create or select a bucket for Waterleaf.
+2. Attach it read-write.
+3. Set the mount path to `/data`.
+
+The Docker image already sets `WATERLEAF_DATA_DIR=/data`. Without this mount,
+saved gardens and images disappear when the Space restarts.
+
+### 4. Configure secrets and variables
+
+In **Space Settings → Variables and secrets**, add:
+
+| Name | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `MODAL_ENDPOINT` | Secret | Production | Protected llama.cpp base URL |
+| `MODAL_KEY` | Secret | Production | Modal proxy token ID |
+| `MODAL_SECRET` | Secret | Production | Modal proxy token secret |
+| `PERENUAL_API_KEY` | Secret | Optional | Plant care benchmark lookup |
+| `PUBLIC_BASE_URL` | Variable | Optional | Override the derived Space URL |
+| `WATERLEAF_DATA_DIR` | Variable | No | Defaults to `/data` in Docker |
+
+Use only the base Modal URL for `MODAL_ENDPOINT`; do not append
+`/v1/chat/completions`.
+
+### 5. Rebuild and verify
+
+Trigger **Factory reboot** after attaching storage or changing secrets. Then
+verify:
+
+```bash
+curl --fail https://build-small-hackathon-waterleaf.hf.space/health
+```
+
+Expected response:
+
+```json
+{"status":"ok"}
+```
+
+Open the Space directly, not only inside the Hub iframe, and check:
+
+1. **Sign in with Hugging Face** completes successfully.
+2. A guest can preview one identification.
+3. A signed-in user can save a plant and see it after a factory restart.
+4. The generated ICS downloads and its public plant/image links open.
+
+Guests may run one temporary identification preview. Login is required to
+save, delete, or export plants.
+
+## Evaluation
+
+Populate `evaluation/manifest.csv` with at least 20 consented real-garden
+examples and run:
+
+```bash
+MODAL_ENDPOINT=... MODAL_KEY=... MODAL_SECRET=... \
+  uv run python scripts/evaluate.py evaluation/manifest.csv
+```
+
+The report includes species top-1/top-3 accuracy, genus top-1 accuracy,
+per-case predictions, and latency. A live one-to-three-photo smoke test is
+available at `scripts/smoke_modal.py`.
+
+## Privacy and Limitations
+
+- Images are resized, converted to JPEG, and stripped of EXIF.
+- Stored coordinates are rounded and never exposed on public plant pages.
+- Public pages use opaque slugs but are intentionally public for calendar use.
+- Plant identification and watering dates are suggestions, not horticultural
+  guarantees.
+- Dates after the 16-day forecast are labeled seasonal estimates.
+- ICS `ATTACH` support varies by calendar client; every event also includes a
+  portable public profile link.
+- Perenual can be omitted; users must provide a manual interval when no care
+  benchmark is available.
+
+## Submission Materials
+
+- [Field Notes draft](docs/field-notes.md)
+- [Demo script](docs/demo-script.md)
+- [Social post draft](docs/social-post.md)
+- [Submission checklist](docs/submission-checklist.md)
+
+Target quests: Backyard AI, Llama Champion, Modal-powered, and Field Notes.
+Waterleaf does not claim Off the Grid because inference and weather data are
+cloud-hosted.
+
+## Credits
+
+- [Gemma 4](https://huggingface.co/google/gemma-4-26B-A4B-it)
+- [llama.cpp](https://github.com/ggml-org/llama.cpp)
+- [GBIF](https://www.gbif.org/developer/species)
+- [Perenual](https://perenual.com/docs/api)
+- [Open-Meteo](https://open-meteo.com/)

app.py

@@ -0,0 +1,6 @@
+from waterleaf.runtime import build_application
+from waterleaf.web import create_web_app
+
+application = build_application()
+app = create_web_app(application)
+

docs/architecture.md

@@ -0,0 +1,37 @@
+# Waterleaf Architecture
+
+```mermaid
+flowchart LR
+    U[Gardener] --> G[Gradio Blocks]
+    G --> A[FastAPI application]
+    A --> O[Hugging Face OAuth]
+    A --> S[(SQLite + images\nHF Storage Bucket)]
+    A --> M[Modal proxy-auth endpoint]
+    M --> L[llama.cpp\nGemma 4 26B-A4B GGUF]
+    A --> B[GBIF taxonomy]
+    A --> P[Perenual care data]
+    A --> W[Open-Meteo]
+    A --> I[Whole-garden ICS]
+    I --> C[Apple / Google / Outlook]
+```
+
+## Identification
+
+1. Gemma extracts visible traits, candidate names, container status, and size.
+2. GBIF resolves names to valid `Plantae` species records.
+3. Gemma reranks only those records. Unknown keys are discarded.
+4. The user confirms a candidate or replaces it through taxonomy autocomplete.
+
+## Scheduling
+
+Perenual provides a baseline interval. Waterleaf shortens the interval for
+containers, applies bounded rain and heat adjustments to the 16-day forecast,
+and labels later dates as seasonal estimates. The language model never chooses
+watering dates.
+
+## Privacy
+
+HF username is the private ownership key. Coordinates are rounded before
+storage. Public plant profiles use opaque slugs and omit account and location
+data. Uploaded images are resized, converted to JPEG, and stripped of EXIF.
+

docs/demo-script.md

@@ -0,0 +1,14 @@
+# Waterleaf Demo Script
+
+Target length: 60-90 seconds.
+
+1. Open the garden dashboard and show the existing sample plant.
+2. Add one to three photographs of a real outdoor plant.
+3. Run analysis and point out the visible traits and three GBIF-backed matches.
+4. Replace or confirm the species using autocomplete.
+5. Enter the plant nickname, city, and preferred watering time.
+6. Show the inferred container status and editable 30-day dates.
+7. Save the plant and return to the dashboard.
+8. Generate the whole-garden ICS file.
+9. Open one imported calendar event and follow the plant profile/image link.
+10. End on the architecture diagram: Gradio Space, Modal, llama.cpp, Gemma 4.

docs/field-notes.md

@@ -0,0 +1,48 @@
+# Field Notes: Building Waterleaf with Gemma 4 and llama.cpp
+
+## The person and the problem
+
+Waterleaf is being built for a gardener who recognizes many plants by sight but
+does not want to maintain a spreadsheet of watering dates. The useful outcome
+is not another plant-identification answer. It is a calendar that can be acted
+on and corrected.
+
+## Why a grounded pipeline
+
+A vision-language model can describe leaf shape, flower form, growth habit, and
+visible planting context. It should not be the database of record. Waterleaf
+therefore asks Gemma 4 for observations and candidate names, resolves those
+names through GBIF, and allows Gemma to rerank only valid taxonomy records.
+The gardener makes the final choice.
+
+## Running the large model small
+
+The model is Gemma 4 26B-A4B, a mixture-of-experts model with roughly 4B active
+parameters per token. It runs as a Q4_K_M GGUF through llama.cpp on a Modal L4.
+The container is pinned to a llama.cpp build, uses an 8K context and quantized
+KV cache. Initial visual extraction is schema-constrained without thinking.
+The database-candidate rerank uses a bounded 256-token thinking pass, with
+llama.cpp separating reasoning from the final JSON response.
+The Hugging Face Space remains a small CPU application.
+
+## Scheduling without pretending
+
+Watering depends on species, planting context, rain, temperature, and drying
+conditions. Waterleaf combines a care-data interval with Open-Meteo data.
+Forecast dates are adjusted with deterministic rules and shown before export.
+Dates beyond the reliable forecast window are visibly marked as seasonal
+estimates. Users can edit or remove every event.
+
+## Calendar portability
+
+The export is one 30-day ICS file containing individual 15-minute events. Each
+event links to a public, location-free plant profile and includes the image as
+an ICS attachment. Calendar clients differ in how they display attachments, so
+the profile link is the portable visual fallback.
+
+## What to measure before submission
+
+The final report will include at least 20 real garden examples, species top-1
+and top-3 accuracy, genus accuracy, correction rate, and warm/cold latency.
+It will also document manual imports into Apple Calendar, Google Calendar, and
+Outlook, plus feedback from the gardener the project was built for.

docs/social-post.md

@@ -0,0 +1,16 @@
+# Social Post Draft
+
+I built Waterleaf for the Hugging Face Build Small Hackathon.
+
+Take 1-3 garden photos, confirm the GBIF-backed plant match, and export a
+weather-aware 30-day watering calendar. Each event links back to the plant
+photo, so the reminder still makes sense weeks later.
+
+Stack: Gradio + FastAPI on Hugging Face Spaces, Gemma 4 26B-A4B in GGUF through
+llama.cpp on Modal, GBIF, Perenual, and Open-Meteo.
+
+Tracks: Backyard AI, Llama Champion, Modal-powered, and Field Notes.
+
+Space: [ADD SPACE URL]
+Field Notes: [ADD ARTICLE URL]
+

docs/submission-checklist.md

@@ -0,0 +1,16 @@
+# Submission Checklist
+
+- [ ] Deploy Modal service and record its protected endpoint.
+- [ ] Create Modal proxy-auth token and add credentials as Space secrets.
+- [ ] Create and mount an HF Storage Bucket at `/data`.
+- [ ] Add `PERENUAL_API_KEY`, `MODAL_ENDPOINT`, `MODAL_KEY`, and `MODAL_SECRET`.
+- [ ] Deploy the Docker Space as `build-small-hackathon/waterleaf`.
+- [ ] Run at least 20 labeled real-garden evaluation cases.
+- [ ] Test one-, two-, and three-photo live inference.
+- [ ] Record warm and cold latency and Q5/Q4 fallback behavior.
+- [ ] Import ICS into Apple Calendar, Google Calendar, and Outlook.
+- [ ] Get the known gardener's consented usability quote.
+- [ ] Replace placeholders in Field Notes and the social post.
+- [ ] Record and publish the 60-90 second demo.
+- [ ] Submit before June 15, 2026.
+

evaluation/README.md

@@ -0,0 +1,16 @@
+# Identification Evaluation
+
+Create `evaluation/manifest.csv` with at least 20 real, consented outdoor-garden
+examples. Use one to three image paths separated by `|` in the `images` column.
+
+Run the live Modal evaluation:
+
+```bash
+MODAL_ENDPOINT=... MODAL_KEY=... MODAL_SECRET=... \
+  uv run python scripts/evaluate.py evaluation/manifest.csv
+```
+
+The report contains species top-1, species top-3, genus top-1, per-case
+predictions, and latency. Do not publish photographs, usernames, or precise
+locations without explicit consent.
+

evaluation/manifest.example.csv

@@ -0,0 +1,3 @@
+case_id,images,expected_scientific_name,notes
+lavender-01,assets/sample-lavender.png,Lavandula angustifolia,Generated smoke-test image; replace with real labeled garden photographs
+

modal_app.py

@@ -0,0 +1,116 @@
+"""Modal deployment for Gemma 4 vision inference through llama.cpp."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+import urllib.request
+
+import modal
+
+APP_NAME = "waterleaf-gemma4"
+PORT = 8000
+MODEL_REPO = "ggml-org/gemma-4-26B-A4B-it-GGUF"
+PRIMARY_QUANT = "Q4_K_M"
+FALLBACK_QUANT = PRIMARY_QUANT
+LLAMA_IMAGE = "ghcr.io/ggml-org/llama.cpp:server-cuda13-b9445"
+PROXY_AUTH_REQUIRED = os.getenv("MODAL_PROXY_AUTH", "1") != "0"
+
+app = modal.App(APP_NAME)
+model_cache = modal.Volume.from_name("waterleaf-model-cache", create_if_missing=True)
+minimum_containers = int(os.getenv("MODAL_MIN_CONTAINERS", "0"))
+image = (
+    modal.Image.from_registry(LLAMA_IMAGE, add_python="3.12")
+    .entrypoint([])
+    .env(
+        {
+            "HF_HOME": "/models/huggingface",
+            "LLAMA_CACHE": "/models/llama.cpp",
+            "HF_XET_HIGH_PERFORMANCE": "1",
+        }
+    )
+)
+
+
+@app.function(
+    image=image,
+    gpu="L4",
+    memory=32768,
+    volumes={"/models": model_cache},
+    startup_timeout=900,
+    timeout=900,
+    scaledown_window=600,
+    min_containers=minimum_containers,
+    max_containers=1,
+)
+@modal.concurrent(max_inputs=1)
+@modal.web_server(
+    PORT,
+    startup_timeout=900,
+    requires_proxy_auth=PROXY_AUTH_REQUIRED,
+)
+def serve() -> None:
+    requested = os.getenv("WATERLEAF_MODEL_QUANT", PRIMARY_QUANT)
+    attempts = list(dict.fromkeys([requested, FALLBACK_QUANT]))
+    errors: list[str] = []
+    for quant in attempts:
+        process = subprocess.Popen(_command(quant))
+        if _wait_until_ready(process, timeout_seconds=780):
+            print(f"Waterleaf llama.cpp ready with {quant}", flush=True)
+            return
+        errors.append(f"{quant}: exit={process.poll()}")
+        if process.poll() is None:
+            process.terminate()
+            process.wait(timeout=20)
+    raise RuntimeError("llama.cpp failed to start; " + ", ".join(errors))
+
+
+def _command(quant: str) -> list[str]:
+    return [
+        "/app/llama-server",
+        "-hf",
+        f"{MODEL_REPO}:{quant}",
+        "--alias",
+        "waterleaf-gemma-4",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(PORT),
+        "--ctx-size",
+        "8192",
+        "--n-gpu-layers",
+        "99",
+        "--flash-attn",
+        "on",
+        "--cache-type-k",
+        "q8_0",
+        "--cache-type-v",
+        "q8_0",
+        "--parallel",
+        "1",
+        "--jinja",
+        "--reasoning",
+        "auto",
+        "--reasoning-format",
+        "deepseek",
+        "--reasoning-budget",
+        "256",
+    ]
+
+
+def _wait_until_ready(process: subprocess.Popen, *, timeout_seconds: int) -> bool:
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            return False
+        try:
+            with urllib.request.urlopen(
+                f"http://127.0.0.1:{PORT}/health",
+                timeout=2,
+            ) as response:
+                if response.status == 200:
+                    return True
+        except OSError:
+            time.sleep(2)
+    return False

pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "waterleaf"
+version = "0.1.0"
+description = "Plant identification and weather-aware watering calendar for the Hugging Face Build Small Hackathon."
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+  "fastapi>=0.115,<1",
+  "gradio[oauth]>=5.49,<7",
+  "httpx>=0.28,<1",
+  "pillow>=11,<13",
+  "pydantic>=2.11,<3",
+  "python-multipart>=0.0.20,<1",
+  "uvicorn[standard]>=0.34,<1",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<10",
+  "pytest-cov>=6,<8",
+  "ruff>=0.11,<1",
+]
+deploy = [
+  "modal>=1.1,<2",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["waterleaf"]

scripts/evaluate.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import statistics
+import time
+from pathlib import Path
+
+from waterleaf.evaluation import score_predictions
+from waterleaf.runtime import build_application
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Evaluate Waterleaf plant identification.")
+    parser.add_argument("manifest", type=Path)
+    parser.add_argument("--out", type=Path, default=Path("evaluation/results.json"))
+    args = parser.parse_args()
+
+    application = build_application()
+    rows = []
+    latencies = []
+    with args.manifest.open(newline="") as handle:
+        for item in csv.DictReader(handle):
+            images = [Path(value) for value in item["images"].split("|") if value]
+            started = time.perf_counter()
+            result = application.identification.identify(images)
+            latency = time.perf_counter() - started
+            latencies.append(latency)
+            rows.append(
+                {
+                    "case_id": item["case_id"],
+                    "expected": item["expected_scientific_name"],
+                    "predictions": [
+                        candidate.scientific_name for candidate in result.candidates
+                    ],
+                    "latency_seconds": round(latency, 3),
+                }
+            )
+
+    report = {
+        "metrics": score_predictions(rows),
+        "latency_seconds": {
+            "mean": statistics.fmean(latencies) if latencies else 0,
+            "median": statistics.median(latencies) if latencies else 0,
+            "max": max(latencies, default=0),
+        },
+        "cases": rows,
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(report, indent=2))
+    print(json.dumps(report["metrics"], indent=2))
+
+
+if __name__ == "__main__":
+    main()
+

scripts/smoke_modal.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+import os
+import time
+from pathlib import Path
+
+from waterleaf.services.llama_cpp import LlamaCppClient
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run a live llama.cpp vision smoke test.")
+    parser.add_argument("images", type=Path, nargs="+")
+    args = parser.parse_args()
+    endpoint = os.environ["MODAL_ENDPOINT"]
+    client = LlamaCppClient(
+        endpoint=endpoint,
+        modal_key=os.getenv("MODAL_KEY"),
+        modal_secret=os.getenv("MODAL_SECRET"),
+    )
+    started = time.perf_counter()
+    result = client.analyze_images(args.images)
+    elapsed = time.perf_counter() - started
+    print(result.model_dump_json(indent=2))
+    print(f"latency_seconds={elapsed:.3f}")
+
+
+if __name__ == "__main__":
+    main()
+

tests/test_adapters.py

@@ -0,0 +1,325 @@
+import json
+from pathlib import Path
+
+import httpx
+from PIL import Image
+
+from waterleaf.models import TaxonCandidate, VisualAnalysis
+from waterleaf.services.gbif import GbifClient
+from waterleaf.services.llama_cpp import VISUAL_SCHEMA, LlamaCppClient
+from waterleaf.services.open_meteo import OpenMeteoClient
+from waterleaf.services.perenual import PerenualClient
+
+
+def test_gbif_suggest_returns_only_plant_species():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.params["q"] == "lavender"
+        assert request.url.path.endswith("/species/search")
+        return httpx.Response(
+            200,
+            json={
+                "results": [
+                    {
+                        "key": 999,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "DOUBTFUL",
+                        "canonicalName": "Lavandula angustifolia",
+                    },
+                    {
+                        "key": 2925518,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "ACCEPTED",
+                        "scientificName": "Lavandula angustifolia Mill.",
+                        "canonicalName": "Lavandula angustifolia",
+                        "vernacularNames": [
+                            {
+                                "vernacularName": "English lavender",
+                                "language": "eng",
+                            }
+                        ],
+                    },
+                    {
+                        "key": 1,
+                        "rank": "GENUS",
+                        "kingdom": "Plantae",
+                        "scientificName": "Lavandula",
+                    },
+                    {
+                        "key": 2,
+                        "rank": "SPECIES",
+                        "kingdom": "Animalia",
+                        "scientificName": "Lavandula mimic",
+                    },
+                ]
+            },
+        )
+
+    client = GbifClient(http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+    assert client.suggest("lavender")[0].model_dump() == {
+        "taxon_key": "2925518",
+        "scientific_name": "Lavandula angustifolia",
+        "common_name": "English lavender",
+        "confidence": 0.0,
+        "rationale": "",
+    }
+
+
+def test_gbif_prioritizes_exact_common_name_and_accepted_taxa():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "results": [
+                    {
+                        "key": 10,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "ACCEPTED",
+                        "canonicalName": "Lonchitis hirsuta",
+                        "vernacularNames": [
+                            {"vernacularName": "Tomato fern", "language": "eng"}
+                        ],
+                    },
+                    {
+                        "key": 20,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "ACCEPTED",
+                        "canonicalName": "Solanum lycopersicum",
+                        "vernacularNames": [
+                            {"vernacularName": "Garden tomato", "language": "eng"},
+                            {"vernacularName": "Tomato", "language": "eng"},
+                        ],
+                    },
+                ]
+            },
+        )
+
+    client = GbifClient(http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+    matches = client.suggest("tomato")
+
+    assert matches[0].scientific_name == "Solanum lycopersicum"
+    assert matches[0].common_name == "Tomato"
+
+
+def test_gbif_scientific_search_prefers_accepted_record_with_common_name():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "results": [
+                    {
+                        "key": 10,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "DOUBTFUL",
+                        "canonicalName": "Lavandula angustifolia",
+                    },
+                    {
+                        "key": 20,
+                        "rank": "SPECIES",
+                        "kingdom": "Plantae",
+                        "taxonomicStatus": "ACCEPTED",
+                        "canonicalName": "Lavandula angustifolia",
+                        "vernacularNames": [
+                            {
+                                "vernacularName": "English lavender",
+                                "language": "eng",
+                            }
+                        ],
+                    },
+                ]
+            },
+        )
+
+    client = GbifClient(http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+    matches = client.suggest("Lavandula angustifolia")
+
+    assert matches[0].taxon_key == "20"
+    assert matches[0].common_name == "English lavender"
+
+
+def test_perenual_fetches_details_once_then_uses_cache(tmp_path):
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(str(request.url))
+        if "species-list" in request.url.path:
+            return httpx.Response(200, json={"data": [{"id": 77}]})
+        return httpx.Response(
+            200,
+            json={
+                "id": 77,
+                "common_name": "English lavender",
+                "scientific_name": ["Lavandula angustifolia"],
+                "watering": "Minimum",
+                "watering_general_benchmark": {"value": "7-10", "unit": "days"},
+                "sunlight": ["full sun"],
+            },
+        )
+
+    client = PerenualClient(
+        api_key="test-key",
+        cache_path=tmp_path / "care-cache.json",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    first = client.get_care("Lavandula angustifolia")
+    second = client.get_care("Lavandula angustifolia")
+
+    assert first == second
+    assert first.min_days == 7
+    assert first.max_days == 10
+    assert first.sunlight == ["full sun"]
+    assert len(calls) == 2
+
+
+def test_open_meteo_geocodes_and_parses_forecast():
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.host == "geocoding-api.open-meteo.com":
+            return httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {
+                            "name": "Stockholm",
+                            "country": "Sweden",
+                            "latitude": 59.33,
+                            "longitude": 18.07,
+                            "timezone": "Europe/Stockholm",
+                        }
+                    ]
+                },
+            )
+        return httpx.Response(
+            200,
+            json={
+                "timezone": "Europe/Stockholm",
+                "daily": {
+                    "time": ["2026-06-08", "2026-06-09"],
+                    "precipitation_sum": [0.0, 7.2],
+                    "temperature_2m_max": [22.0, 19.0],
+                    "et0_fao_evapotranspiration": [3.1, 1.4],
+                },
+            },
+        )
+
+    client = OpenMeteoClient(
+        http_client=httpx.Client(transport=httpx.MockTransport(handler))
+    )
+    location = client.geocode("Stockholm")
+    forecast = client.forecast(location.latitude, location.longitude)
+
+    assert location.display_name == "Stockholm, Sweden"
+    assert location.timezone == "Europe/Stockholm"
+    assert forecast[1].precipitation_mm == 7.2
+
+
+def test_llama_cpp_sends_all_images_and_constrained_schema(tmp_path):
+    image_paths: list[Path] = []
+    for index in range(2):
+        path = tmp_path / f"plant-{index}.jpg"
+        Image.new("RGB", (20, 20), color=(30 + index, 120, 40)).save(path)
+        image_paths.append(path)
+
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.update(json.loads(request.content))
+        return httpx.Response(
+            200,
+            json={
+                "choices": [
+                    {
+                        "message": {
+                            "content": json.dumps(
+                                {
+                                    "traits": ["purple flower spikes"],
+                                    "proposed_names": ["Lavandula angustifolia"],
+                                    "is_container": True,
+                                    "size_label": "medium",
+                                }
+                            )
+                        }
+                    }
+                ]
+            },
+        )
+
+    client = LlamaCppClient(
+        endpoint="https://modal.example",
+        modal_key="key",
+        modal_secret="secret",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+    result = client.analyze_images(image_paths)
+
+    content = captured["messages"][1]["content"]
+    assert len([part for part in content if part["type"] == "image_url"]) == 2
+    assert captured["response_format"]["type"] == "json_schema"
+    assert captured["response_format"]["json_schema"] == {
+        "name": "visual_analysis",
+        "schema": VISUAL_SCHEMA,
+        "strict": True,
+    }
+    assert captured["chat_template_kwargs"] == {"enable_thinking": False}
+    assert result.proposed_names == ["Lavandula angustifolia"]
+    assert result.is_container is True
+
+
+def test_llama_cpp_enables_thinking_for_candidate_reranking():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.update(json.loads(request.content))
+        return httpx.Response(
+            200,
+            json={
+                "choices": [
+                    {
+                        "message": {
+                            "content": json.dumps(
+                                {
+                                    "ranking": [
+                                        {
+                                            "taxon_key": "2925518",
+                                            "confidence": 0.92,
+                                            "rationale": "Flower and leaf morphology match.",
+                                        }
+                                    ]
+                                }
+                            )
+                        }
+                    }
+                ]
+            },
+        )
+
+    client = LlamaCppClient(
+        endpoint="https://modal.example",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+    ranking = client.rerank(
+        [],
+        VisualAnalysis(
+            traits=["purple flower spikes"],
+            proposed_names=["Lavandula angustifolia"],
+            is_container=True,
+            size_label="medium",
+        ),
+        [
+            TaxonCandidate(
+                taxon_key="2925518",
+                scientific_name="Lavandula angustifolia",
+                common_name="English lavender",
+            )
+        ],
+    )
+
+    assert captured["chat_template_kwargs"] == {"enable_thinking": True}
+    assert ranking[0]["taxon_key"] == "2925518"

tests/test_application.py

@@ -0,0 +1,189 @@
+from datetime import date, time
+
+from fastapi.testclient import TestClient
+from PIL import Image
+
+from waterleaf.application import WaterleafApplication
+from waterleaf.models import CareProfile, LocationMatch, TaxonCandidate, WeatherDay
+from waterleaf.storage import GardenStore
+from waterleaf.web import create_web_app
+
+
+class FakeCare:
+    def get_care(self, scientific_name):
+        return CareProfile(
+            scientific_name=scientific_name,
+            common_name="English lavender",
+            min_days=7,
+            max_days=9,
+            watering_label="Minimum",
+            sunlight=["full sun"],
+        )
+
+
+class FakeWeather:
+    def geocode(self, query):
+        assert query == "Stockholm"
+        return LocationMatch(
+            display_name="Stockholm, Sweden",
+            latitude=59.33,
+            longitude=18.07,
+            timezone="Europe/Stockholm",
+        )
+
+    def forecast(self, latitude, longitude):
+        return [
+            WeatherDay(
+                date=date(2026, 6, 16),
+                precipitation_mm=7.0,
+                max_temperature_c=20.0,
+                et0_mm=2.0,
+            )
+        ]
+
+
+def test_application_saves_plan_and_exports_whole_garden(tmp_path):
+    source = tmp_path / "lavender.png"
+    Image.new("RGB", (300, 500), color=(90, 120, 60)).save(source)
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    application = WaterleafApplication(
+        store=store,
+        media_directory=tmp_path / "media",
+        export_directory=tmp_path / "exports",
+        public_base_url="https://waterleaf.example",
+        care=FakeCare(),
+        weather=FakeWeather(),
+    )
+    candidate = TaxonCandidate(
+        taxon_key="2925518",
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+        confidence=0.91,
+        rationale="Purple spikes and narrow leaves",
+    )
+
+    plan = application.preview_schedule(
+        candidate=candidate,
+        location_query="Stockholm",
+        is_container=True,
+        size_label="medium",
+        start=date(2026, 6, 8),
+    )
+    saved = application.save_plant(
+        owner="alice",
+        nickname="Patio lavender",
+        candidate=candidate,
+        source_image=source,
+        preferred_time=time(7, 30),
+        plan=plan,
+    )
+    exported = application.export_garden("alice", generated_at="20260608T100000Z")
+
+    assert saved.image_id
+    assert store.get_schedule("alice", saved.id)
+    content = exported.read_text()
+    unfolded = content.replace("\n ", "")
+    assert "SUMMARY:Water Patio lavender" in content
+    assert f"https://waterleaf.example/plants/{saved.public_slug}" in content
+    assert f"https://waterleaf.example/media/{saved.image_id}.jpg" in unfolded
+
+
+def test_public_profile_and_media_routes_exclude_private_location(tmp_path):
+    source = tmp_path / "lavender.png"
+    Image.new("RGB", (100, 100), color=(90, 120, 60)).save(source)
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    application = WaterleafApplication(
+        store=store,
+        media_directory=tmp_path / "media",
+        export_directory=tmp_path / "exports",
+        public_base_url="https://waterleaf.example",
+        care=FakeCare(),
+        weather=FakeWeather(),
+    )
+    candidate = TaxonCandidate(
+        taxon_key="2925518",
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+    )
+    plan = application.preview_schedule(
+        candidate=candidate,
+        location_query="Stockholm",
+        is_container=True,
+        size_label="medium",
+        start=date(2026, 6, 8),
+    )
+    saved = application.save_plant(
+        owner="alice",
+        nickname="Patio lavender",
+        candidate=candidate,
+        source_image=source,
+        preferred_time=time(7, 30),
+        plan=plan,
+    )
+    client = TestClient(create_web_app(application, mount_ui=False))
+
+    health = client.get("/health")
+    profile = client.get(f"/plants/{saved.public_slug}")
+    media = client.get(f"/media/{saved.image_id}.jpg")
+
+    assert health.json() == {"status": "ok"}
+    assert profile.status_code == 200
+    assert "Patio lavender" in profile.text
+    assert "Lavandula angustifolia" in profile.text
+    assert "7-9 days" in profile.text
+    assert "2026-06-" in profile.text
+    assert "Stockholm" not in profile.text
+    assert "alice" not in profile.text
+    assert media.status_code == 200
+    assert media.headers["content-type"] == "image/jpeg"
+    assert client.get("/media/../../private.jpg").status_code == 404
+
+
+def test_application_delete_removes_unreferenced_media(tmp_path):
+    source = tmp_path / "lavender.png"
+    Image.new("RGB", (100, 100), color=(90, 120, 60)).save(source)
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    application = WaterleafApplication(
+        store=store,
+        media_directory=tmp_path / "media",
+        export_directory=tmp_path / "exports",
+        public_base_url="https://waterleaf.example",
+        care=FakeCare(),
+        weather=FakeWeather(),
+    )
+    candidate = TaxonCandidate(
+        taxon_key="2925518",
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+    )
+    plan = application.preview_schedule(
+        candidate=candidate,
+        location_query="Stockholm",
+        is_container=True,
+        size_label="medium",
+        start=date(2026, 6, 8),
+    )
+    first = application.save_plant(
+        owner="alice",
+        nickname="Patio lavender",
+        candidate=candidate,
+        source_image=source,
+        preferred_time=time(7, 30),
+        plan=plan,
+    )
+    second = application.save_plant(
+        owner="alice",
+        nickname="Second lavender",
+        candidate=candidate,
+        source_image=source,
+        preferred_time=time(7, 30),
+        plan=plan,
+    )
+    media_path = application.media_directory / f"{first.image_id}.jpg"
+
+    assert first.image_id == second.image_id
+    assert media_path.exists()
+    assert application.delete_plant("alice", first.id) is True
+    assert media_path.exists()
+    assert application.delete_plant("alice", second.id) is True
+    assert not media_path.exists()

tests/test_calendar.py

@@ -0,0 +1,90 @@
+from datetime import date, time
+
+from waterleaf.calendar import CalendarPlant, build_garden_ics
+from waterleaf.models import WateringEvent
+
+
+def test_calendar_contains_timed_events_alarm_profile_and_attachment():
+    plant = CalendarPlant(
+        id="plant-1",
+        nickname="Front rose",
+        common_name="Dog rose",
+        scientific_name="Rosa canina",
+        timezone="Europe/Stockholm",
+        preferred_time=time(7, 30),
+        profile_url="https://waterleaf.example/plants/rose-abc",
+        image_url="https://waterleaf.example/media/image-1",
+        events=[
+            WateringEvent(
+                date=date(2026, 6, 12),
+                reason="Deferred after forecast rain",
+                confidence="forecast",
+            )
+        ],
+    )
+
+    content = build_garden_ics([plant], generated_at="20260608T100000Z")
+
+    assert "X-WR-CALNAME:Waterleaf" in content
+    assert "SUMMARY:Water Front rose" in content
+    assert "DTSTART;TZID=Europe/Stockholm:20260612T073000" in content
+    assert "DTEND;TZID=Europe/Stockholm:20260612T074500" in content
+    assert "TRIGGER:-PT30M" in content
+    assert "URL:https://waterleaf.example/plants/rose-abc" in content
+    assert "ATTACH;FMTTYPE=image/jpeg:https://waterleaf.example/media/image-1" in content
+    assert "Dog rose (Rosa canina)" in content
+
+
+def test_calendar_uid_is_stable_for_same_plant_and_date():
+    plant = CalendarPlant(
+        id="plant-1",
+        nickname="Mint",
+        common_name="Spearmint",
+        scientific_name="Mentha spicata",
+        timezone="UTC",
+        preferred_time=time(8, 0),
+        profile_url="https://example.com/plants/mint",
+        image_url="https://example.com/media/mint",
+        events=[
+            WateringEvent(
+                date=date(2026, 6, 12),
+                reason="Species care baseline",
+                confidence="baseline",
+            )
+        ],
+    )
+
+    first = build_garden_ics([plant], generated_at="20260608T100000Z")
+    second = build_garden_ics([plant], generated_at="20260609T100000Z")
+
+    first_uid = next(line for line in first.splitlines() if line.startswith("UID:"))
+    second_uid = next(line for line in second.splitlines() if line.startswith("UID:"))
+    assert first_uid == second_uid
+
+
+def test_calendar_escapes_text_and_folds_long_lines():
+    plant = CalendarPlant(
+        id="plant-2",
+        nickname="Herbs, north bed",
+        common_name="A very long common plant name used to force an RFC line fold",
+        scientific_name="Mentha longifolia",
+        timezone="UTC",
+        preferred_time=time(9, 0),
+        profile_url="https://example.com/plants/" + ("very-long-segment-" * 8),
+        image_url="https://example.com/media/image-2",
+        events=[
+            WateringEvent(
+                date=date(2026, 6, 14),
+                reason="Line one\nLine two; check",
+                confidence="seasonal",
+            )
+        ],
+    )
+
+    content = build_garden_ics([plant], generated_at="20260608T100000Z")
+
+    assert "SUMMARY:Water Herbs\\, north bed" in content
+    assert "Line one\\nLine two\\; check" in content.replace("\r\n ", "")
+    for line in content.split("\r\n"):
+        assert len(line.encode("utf-8")) <= 75
+

tests/test_evaluation.py

@@ -0,0 +1,33 @@
+from waterleaf.evaluation import score_predictions
+
+
+def test_evaluation_reports_species_genus_and_top_three_accuracy():
+    rows = [
+        {
+            "expected": "Lavandula angustifolia",
+            "predictions": [
+                "Lavandula angustifolia",
+                "Salvia officinalis",
+                "Salvia rosmarinus",
+            ],
+        },
+        {
+            "expected": "Salvia officinalis",
+            "predictions": [
+                "Salvia rosmarinus",
+                "Salvia officinalis",
+            ],
+        },
+        {
+            "expected": "Rosa canina",
+            "predictions": ["Rosa rubiginosa"],
+        },
+    ]
+
+    metrics = score_predictions(rows)
+
+    assert metrics["count"] == 3
+    assert metrics["species_top_1"] == 1 / 3
+    assert metrics["species_top_3"] == 2 / 3
+    assert metrics["genus_top_1"] == 1.0
+

tests/test_identification.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+from waterleaf.models import TaxonCandidate, VisualAnalysis
+from waterleaf.services.identification import IdentificationService
+
+
+class FakeVision:
+    def analyze_images(self, image_paths):
+        assert image_paths == [Path("plant.jpg")]
+        return VisualAnalysis(
+            traits=["purple flower spikes", "narrow gray-green leaves"],
+            proposed_names=["Lavandula angustifolia", "Salvia officinalis"],
+            is_container=True,
+            size_label="medium",
+        )
+
+    def rerank(self, image_paths, visual, candidates):
+        assert all(candidate.taxon_key for candidate in candidates)
+        return [
+            {"taxon_key": "lavender", "confidence": 0.91, "rationale": "Flower and leaf match"},
+            {"taxon_key": "sage", "confidence": 0.22, "rationale": "Leaf color only"},
+            {"taxon_key": "invented", "confidence": 0.99, "rationale": "Must be ignored"},
+        ]
+
+
+class FakeTaxonomy:
+    def suggest(self, query, limit=5):
+        if query == "Lavandula angustifolia":
+            return [
+                TaxonCandidate(
+                    taxon_key="lavender",
+                    scientific_name="Lavandula angustifolia",
+                    common_name="English lavender",
+                )
+            ]
+        if query == "Salvia officinalis":
+            return [
+                TaxonCandidate(
+                    taxon_key="sage",
+                    scientific_name="Salvia officinalis",
+                    common_name="Common sage",
+                )
+            ]
+        return []
+
+
+def test_identification_only_returns_grounded_reranked_candidates():
+    service = IdentificationService(vision=FakeVision(), taxonomy=FakeTaxonomy())
+
+    result = service.identify([Path("plant.jpg")])
+
+    assert [candidate.taxon_key for candidate in result.candidates] == [
+        "lavender",
+        "sage",
+    ]
+    assert result.candidates[0].confidence == 0.91
+    assert result.visual.is_container is True
+

tests/test_images.py

@@ -0,0 +1,32 @@
+from PIL import Image
+
+from waterleaf.images import normalize_plant_image
+
+
+def test_normalize_image_resizes_strips_exif_and_writes_jpeg(tmp_path):
+    source = tmp_path / "source.jpg"
+    image = Image.new("RGB", (2400, 1200), color=(70, 130, 70))
+    exif = Image.Exif()
+    exif[0x010E] = "private garden note"
+    image.save(source, exif=exif)
+
+    stored = normalize_plant_image(source, tmp_path / "media")
+
+    assert stored.path.suffix == ".jpg"
+    assert stored.width == 1600
+    assert stored.height == 800
+    with Image.open(stored.path) as normalized:
+        assert normalized.getexif() == {}
+        assert normalized.mode == "RGB"
+
+
+def test_normalize_image_generates_stable_content_id(tmp_path):
+    source = tmp_path / "source.png"
+    Image.new("RGB", (120, 80), color=(120, 80, 40)).save(source)
+
+    first = normalize_plant_image(source, tmp_path / "media")
+    second = normalize_plant_image(source, tmp_path / "media")
+
+    assert first.id == second.id
+    assert first.path == second.path
+

tests/test_rate_limit.py

@@ -0,0 +1,17 @@
+from waterleaf.rate_limit import SlidingWindowRateLimiter
+
+
+def test_rate_limiter_blocks_after_limit_inside_window():
+    limiter = SlidingWindowRateLimiter(limit=2, window_seconds=60)
+
+    assert limiter.allow("203.0.113.10", now=100.0) is True
+    assert limiter.allow("203.0.113.10", now=110.0) is True
+    assert limiter.allow("203.0.113.10", now=120.0) is False
+
+
+def test_rate_limiter_expires_old_attempts():
+    limiter = SlidingWindowRateLimiter(limit=1, window_seconds=60)
+
+    assert limiter.allow("203.0.113.10", now=100.0) is True
+    assert limiter.allow("203.0.113.10", now=161.0) is True
+

tests/test_runtime.py

@@ -0,0 +1,29 @@
+from waterleaf.runtime import build_application
+from waterleaf.services.demo import DemoTaxonomy
+from waterleaf.settings import Settings
+
+
+def test_settings_derive_public_url_from_space_host(monkeypatch, tmp_path):
+    monkeypatch.setenv("SPACE_HOST", "hkaraoguz-waterleaf.hf.space")
+    monkeypatch.setenv("WATERLEAF_DATA_DIR", str(tmp_path))
+
+    settings = Settings.from_env()
+
+    assert settings.public_base_url == "https://hkaraoguz-waterleaf.hf.space"
+    assert settings.database_path == tmp_path / "waterleaf.sqlite3"
+
+
+def test_runtime_uses_demo_identification_without_modal_endpoint(tmp_path):
+    settings = Settings(
+        data_directory=tmp_path,
+        public_base_url="http://localhost:7860",
+        perenual_api_key=None,
+        modal_endpoint=None,
+        modal_key=None,
+        modal_secret=None,
+    )
+
+    application = build_application(settings)
+
+    assert application.identification is not None
+    assert isinstance(application.taxonomy, DemoTaxonomy)

tests/test_scheduling.py

@@ -0,0 +1,91 @@
+from datetime import date
+
+from waterleaf.models import CareBenchmark, PlantContext, WeatherDay
+from waterleaf.scheduling import build_watering_schedule
+
+
+def test_container_plant_uses_shorter_interval():
+    schedule = build_watering_schedule(
+        start=date(2026, 6, 8),
+        days=30,
+        care=CareBenchmark(min_days=6, max_days=8),
+        context=PlantContext(is_container=True, size_label="medium"),
+        weather=[],
+    )
+
+    assert [item.date for item in schedule[:3]] == [
+        date(2026, 6, 13),
+        date(2026, 6, 18),
+        date(2026, 6, 23),
+    ]
+    assert all(item.confidence == "baseline" for item in schedule[:3])
+
+
+def test_meaningful_rain_defers_near_term_watering():
+    schedule = build_watering_schedule(
+        start=date(2026, 6, 8),
+        days=16,
+        care=CareBenchmark(min_days=4, max_days=4),
+        context=PlantContext(is_container=False, size_label="large"),
+        weather=[
+            WeatherDay(
+                date=date(2026, 6, 12),
+                precipitation_mm=8.0,
+                max_temperature_c=19.0,
+                et0_mm=2.0,
+            )
+        ],
+    )
+
+    assert schedule[0].date == date(2026, 6, 14)
+    assert schedule[0].reason == "Deferred after forecast rain"
+    assert schedule[0].confidence == "forecast"
+
+
+def test_high_heat_advances_near_term_watering_by_one_day():
+    schedule = build_watering_schedule(
+        start=date(2026, 6, 8),
+        days=16,
+        care=CareBenchmark(min_days=5, max_days=5),
+        context=PlantContext(is_container=False, size_label="small"),
+        weather=[
+            WeatherDay(
+                date=date(2026, 6, 13),
+                precipitation_mm=0.0,
+                max_temperature_c=32.0,
+                et0_mm=5.8,
+            )
+        ],
+    )
+
+    assert schedule[0].date == date(2026, 6, 12)
+    assert schedule[0].reason == "Advanced for hot, drying weather"
+
+
+def test_dates_after_forecast_window_are_marked_seasonal():
+    schedule = build_watering_schedule(
+        start=date(2026, 6, 8),
+        days=30,
+        care=CareBenchmark(min_days=7, max_days=7),
+        context=PlantContext(is_container=False, size_label="medium"),
+        weather=[],
+    )
+
+    assert schedule[2].date == date(2026, 6, 29)
+    assert schedule[2].confidence == "seasonal"
+    assert schedule[2].reason == "Seasonal care baseline"
+
+
+def test_missing_care_interval_requires_user_input():
+    try:
+        build_watering_schedule(
+            start=date(2026, 6, 8),
+            days=30,
+            care=CareBenchmark(min_days=None, max_days=None),
+            context=PlantContext(is_container=False, size_label="medium"),
+            weather=[],
+        )
+    except ValueError as exc:
+        assert str(exc) == "A watering interval is required"
+    else:
+        raise AssertionError("Expected a missing interval to be rejected")

tests/test_storage.py

@@ -0,0 +1,83 @@
+from datetime import time
+
+from waterleaf.models import PlantDraft
+from waterleaf.storage import GardenStore
+
+
+def _draft() -> PlantDraft:
+    return PlantDraft(
+        nickname="Patio lavender",
+        common_name="English lavender",
+        scientific_name="Lavandula angustifolia",
+        taxon_key="2925518",
+        location_name="Stockholm, Sweden",
+        latitude=59.32932,
+        longitude=18.06858,
+        timezone="Europe/Stockholm",
+        preferred_time=time(7, 30),
+        is_container=True,
+        size_label="medium",
+        image_id="image-1",
+        care_min_days=7,
+        care_max_days=10,
+    )
+
+
+def test_store_isolates_plants_by_owner(tmp_path):
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    plant = store.save_plant("alice", _draft())
+
+    assert store.list_plants("alice") == [plant]
+    assert store.list_plants("bob") == []
+    assert store.get_plant("bob", plant.id) is None
+    assert store.get_plant("alice", plant.id) == plant
+
+
+def test_store_rounds_private_coordinates_and_exposes_safe_public_record(tmp_path):
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    plant = store.save_plant("alice", _draft())
+
+    assert plant.latitude == 59.33
+    assert plant.longitude == 18.07
+    public = store.get_public_plant(plant.public_slug)
+
+    assert public is not None
+    assert public.nickname == "Patio lavender"
+    assert public.scientific_name == "Lavandula angustifolia"
+    assert not hasattr(public, "owner")
+    assert not hasattr(public, "latitude")
+    assert len(plant.public_slug) >= 20
+
+
+def test_only_owner_can_delete_plant(tmp_path):
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    plant = store.save_plant("alice", _draft())
+
+    assert store.delete_plant("bob", plant.id) is False
+    assert store.get_plant("alice", plant.id) is not None
+    assert store.delete_plant("alice", plant.id) is True
+    assert store.get_public_plant(plant.public_slug) is None
+
+
+def test_store_replaces_schedule_atomically(tmp_path):
+    store = GardenStore(tmp_path / "waterleaf.sqlite3")
+    plant = store.save_plant("alice", _draft())
+
+    store.replace_schedule(
+        "alice",
+        plant.id,
+        [
+            {"date": "2026-06-12", "reason": "Forecast", "confidence": "forecast"},
+            {"date": "2026-06-18", "reason": "Baseline", "confidence": "baseline"},
+        ],
+    )
+    store.replace_schedule(
+        "alice",
+        plant.id,
+        [{"date": "2026-06-14", "reason": "Edited", "confidence": "manual"}],
+    )
+
+    assert store.get_schedule("alice", plant.id) == [
+        {"date": "2026-06-14", "reason": "Edited", "confidence": "manual"}
+    ]
+

tests/test_ui.py

@@ -0,0 +1,129 @@
+import json
+
+import pytest
+
+from waterleaf.application import WaterleafApplication
+from waterleaf.models import TaxonCandidate
+from waterleaf.storage import GardenStore
+from waterleaf.ui import _candidate_label, _parse_optional_interval, build_ui
+
+
+class NoopCare:
+    def get_care(self, scientific_name):
+        raise AssertionError("Not called while building UI")
+
+
+class NoopWeather:
+    def geocode(self, query):
+        raise AssertionError("Not called while building UI")
+
+    def forecast(self, latitude, longitude):
+        raise AssertionError("Not called while building UI")
+
+
+class NoopIdentification:
+    def identify(self, image_paths):
+        raise AssertionError("Not called while building UI")
+
+
+class NoopTaxonomy:
+    def suggest(self, query, limit=10):
+        return []
+
+
+def test_ui_contains_dashboard_capture_confirmation_and_export(tmp_path):
+    application = WaterleafApplication(
+        store=GardenStore(tmp_path / "waterleaf.sqlite3"),
+        media_directory=tmp_path / "media",
+        export_directory=tmp_path / "exports",
+        public_base_url="https://waterleaf.example",
+        care=NoopCare(),
+        weather=NoopWeather(),
+    )
+
+    demo = build_ui(
+        application,
+        identification=NoopIdentification(),
+        taxonomy=NoopTaxonomy(),
+        sample_image="assets/sample-lavender.png",
+    )
+    config_file = demo.get_config_file()
+    config = json.dumps(config_file, default=str)
+
+    assert "Waterleaf" in config
+    assert "Add plant" in config
+    assert "Analyze photos" in config
+    assert "Confirm species" in config
+    assert "Generate 30-day calendar" in config
+    assert "Sign in with Hugging Face" in config
+    assert "Plant photo (required)" in config
+    assert "Database match (required)" in config
+    assert "Plant nickname (required)" in config
+    assert "City (required)" in config
+    assert "Watering time (required)" in config
+    assert "Custom watering interval (optional)" in config
+    assert "Leave blank to use plant care data" in config
+    assert "Example: 7" in config
+    assert "Garden location" not in config
+    assert "Interval override" not in config
+    city = next(
+        component
+        for component in config_file["components"]
+        if component.get("props", {}).get("label") == "City (required)"
+    )
+    assert city["props"]["value"] == "Stockholm, Sweden"
+
+
+def test_ui_handlers_are_not_exposed_as_public_api(tmp_path):
+    application = WaterleafApplication(
+        store=GardenStore(tmp_path / "waterleaf.sqlite3"),
+        media_directory=tmp_path / "media",
+        export_directory=tmp_path / "exports",
+        public_base_url="https://waterleaf.example",
+        care=NoopCare(),
+        weather=NoopWeather(),
+    )
+
+    demo = build_ui(
+        application,
+        identification=NoopIdentification(),
+        taxonomy=NoopTaxonomy(),
+        sample_image="assets/sample-lavender.png",
+    )
+    dependencies = demo.get_config_file()["dependencies"]
+
+    assert dependencies
+    assert all(item["api_visibility"] != "public" for item in dependencies)
+    save_dependency = next(
+        item for item in dependencies if item["api_name"] == "save"
+    )
+    assert len(save_dependency["outputs"]) == 2
+
+
+def test_optional_watering_interval_accepts_blank_or_one_to_thirty_days():
+    assert _parse_optional_interval("") is None
+    assert _parse_optional_interval("7") == 7
+
+    with pytest.raises(ValueError, match="whole number from 1 to 30"):
+        _parse_optional_interval("0")
+    with pytest.raises(ValueError, match="whole number from 1 to 30"):
+        _parse_optional_interval("weekly")
+
+
+def test_candidate_label_shows_common_and_scientific_names():
+    candidate = TaxonCandidate(
+        taxon_key="2927305",
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+        confidence=0.8,
+    )
+    unavailable = candidate.model_copy(
+        update={"common_name": "Lavandula angustifolia"}
+    )
+
+    assert _candidate_label(candidate) == (
+        "English lavender | Lavandula angustifolia | 80%"
+    )
+    assert _candidate_label(unavailable) == (
+        "Lavandula angustifolia | Common name unavailable | 80%"
+    )

waterleaf/__init__.py

@@ -0,0 +1,2 @@
+"""Waterleaf application package."""
+

waterleaf/application.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import hashlib
+from datetime import date, time
+from pathlib import Path
+from typing import Protocol
+
+from waterleaf.calendar import CalendarPlant, build_garden_ics
+from waterleaf.images import normalize_plant_image
+from waterleaf.models import (
+    CareBenchmark,
+    CareProfile,
+    LocationMatch,
+    PlantContext,
+    PlantDraft,
+    SavedPlant,
+    SchedulePlan,
+    TaxonCandidate,
+    WateringEvent,
+    WeatherDay,
+)
+from waterleaf.scheduling import build_watering_schedule
+from waterleaf.storage import GardenStore
+
+
+class CareService(Protocol):
+    def get_care(self, scientific_name: str) -> CareProfile: ...
+
+
+class WeatherService(Protocol):
+    def geocode(self, query: str) -> LocationMatch: ...
+
+    def forecast(self, latitude: float, longitude: float) -> list[WeatherDay]: ...
+
+
+class WaterleafApplication:
+    def __init__(
+        self,
+        *,
+        store: GardenStore,
+        media_directory: str | Path,
+        export_directory: str | Path,
+        public_base_url: str,
+        care: CareService,
+        weather: WeatherService,
+        identification: object | None = None,
+        taxonomy: object | None = None,
+    ):
+        self.store = store
+        self.media_directory = Path(media_directory)
+        self.export_directory = Path(export_directory)
+        self.public_base_url = public_base_url.rstrip("/")
+        self.care = care
+        self.weather = weather
+        self.identification = identification
+        self.taxonomy = taxonomy
+        self.media_directory.mkdir(parents=True, exist_ok=True)
+        self.export_directory.mkdir(parents=True, exist_ok=True)
+
+    def preview_schedule(
+        self,
+        *,
+        candidate: TaxonCandidate,
+        location_query: str,
+        is_container: bool,
+        size_label: str,
+        start: date | None = None,
+        manual_interval_days: int | None = None,
+    ) -> SchedulePlan:
+        location = self.weather.geocode(location_query)
+        care = self.care.get_care(candidate.scientific_name)
+        if manual_interval_days:
+            min_days = max(1, int(manual_interval_days))
+            max_days = min_days
+        else:
+            min_days = care.min_days
+            max_days = care.max_days
+        weather = self.weather.forecast(location.latitude, location.longitude)
+        events = build_watering_schedule(
+            start=start or date.today(),
+            days=30,
+            care=CareBenchmark(min_days=min_days, max_days=max_days),
+            context=PlantContext(is_container=is_container, size_label=size_label),
+            weather=weather,
+        )
+        return SchedulePlan(
+            location=location,
+            care=care,
+            events=events,
+            is_container=is_container,
+            size_label=size_label,
+        )
+
+    def save_plant(
+        self,
+        *,
+        owner: str,
+        nickname: str,
+        candidate: TaxonCandidate,
+        source_image: str | Path,
+        preferred_time: time,
+        plan: SchedulePlan,
+        edited_events: list[WateringEvent] | None = None,
+    ) -> SavedPlant:
+        image = normalize_plant_image(source_image, self.media_directory)
+        plant = self.store.save_plant(
+            owner,
+            PlantDraft(
+                nickname=nickname,
+                common_name=candidate.common_name,
+                scientific_name=candidate.scientific_name,
+                taxon_key=candidate.taxon_key,
+                location_name=plan.location.display_name,
+                latitude=plan.location.latitude,
+                longitude=plan.location.longitude,
+                timezone=plan.location.timezone,
+                preferred_time=preferred_time,
+                is_container=plan.is_container,
+                size_label=plan.size_label,
+                image_id=image.id,
+                care_min_days=plan.care.min_days,
+                care_max_days=plan.care.max_days,
+            ),
+        )
+        events = edited_events if edited_events is not None else plan.events
+        self.store.replace_schedule(
+            owner,
+            plant.id,
+            [
+                {
+                    "date": item.date.isoformat(),
+                    "reason": item.reason,
+                    "confidence": item.confidence,
+                }
+                for item in events
+            ],
+        )
+        return plant
+
+    def delete_plant(self, owner: str, plant_id: str) -> bool:
+        plant = self.store.get_plant(owner, plant_id)
+        if plant is None or not self.store.delete_plant(owner, plant_id):
+            return False
+        if self.store.image_reference_count(plant.image_id) == 0:
+            (self.media_directory / f"{plant.image_id}.jpg").unlink(missing_ok=True)
+        return True
+
+    def export_garden(
+        self,
+        owner: str,
+        *,
+        generated_at: str | None = None,
+    ) -> Path:
+        calendar_plants: list[CalendarPlant] = []
+        for plant in self.store.list_plants(owner):
+            events = [
+                WateringEvent(
+                    date=date.fromisoformat(item["date"]),
+                    reason=item["reason"],
+                    confidence=item["confidence"],
+                )
+                for item in self.store.get_schedule(owner, plant.id)
+            ]
+            calendar_plants.append(
+                CalendarPlant(
+                    id=plant.id,
+                    nickname=plant.nickname,
+                    common_name=plant.common_name,
+                    scientific_name=plant.scientific_name,
+                    timezone=plant.timezone,
+                    preferred_time=plant.preferred_time,
+                    profile_url=f"{self.public_base_url}/plants/{plant.public_slug}",
+                    image_url=f"{self.public_base_url}/media/{plant.image_id}.jpg",
+                    events=events,
+                )
+            )
+        if not calendar_plants:
+            raise ValueError("Add at least one plant before exporting")
+        owner_token = hashlib.sha256(owner.encode()).hexdigest()[:12]
+        destination = self.export_directory / f"waterleaf-{owner_token}.ics"
+        destination.write_text(
+            build_garden_ics(calendar_plants, generated_at=generated_at),
+            newline="",
+        )
+        return destination

waterleaf/calendar.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, time, timedelta
+
+from waterleaf.models import WateringEvent
+
+
+@dataclass(frozen=True)
+class CalendarPlant:
+    id: str
+    nickname: str
+    common_name: str
+    scientific_name: str
+    timezone: str
+    preferred_time: time
+    profile_url: str
+    image_url: str
+    events: list[WateringEvent]
+
+
+def build_garden_ics(
+    plants: list[CalendarPlant],
+    *,
+    generated_at: str | None = None,
+) -> str:
+    stamp = generated_at or datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
+    lines = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//Waterleaf//Garden Watering Calendar//EN",
+        "CALSCALE:GREGORIAN",
+        "METHOD:PUBLISH",
+        "X-WR-CALNAME:Waterleaf",
+    ]
+    for plant in plants:
+        for event in plant.events:
+            lines.extend(_event_lines(plant, event, stamp))
+    lines.append("END:VCALENDAR")
+    return "\r\n".join(_fold_line(line) for line in lines) + "\r\n"
+
+
+def _event_lines(
+    plant: CalendarPlant,
+    event: WateringEvent,
+    stamp: str,
+) -> list[str]:
+    start_dt = datetime.combine(event.date, plant.preferred_time)
+    end_dt = start_dt + timedelta(minutes=15)
+    uid_seed = f"{plant.id}:{event.date.isoformat()}".encode()
+    uid = hashlib.sha256(uid_seed).hexdigest()[:24]
+    description = (
+        f"{plant.common_name} ({plant.scientific_name})\n"
+        f"{event.reason}\n"
+        f"Plant profile: {plant.profile_url}"
+    )
+    return [
+        "BEGIN:VEVENT",
+        f"UID:{uid}@waterleaf",
+        f"DTSTAMP:{stamp}",
+        f"DTSTART;TZID={plant.timezone}:{start_dt:%Y%m%dT%H%M%S}",
+        f"DTEND;TZID={plant.timezone}:{end_dt:%Y%m%dT%H%M%S}",
+        f"SUMMARY:{_escape_text(f'Water {plant.nickname}')}",
+        f"DESCRIPTION:{_escape_text(description)}",
+        f"URL:{plant.profile_url}",
+        f"ATTACH;FMTTYPE=image/jpeg:{plant.image_url}",
+        "BEGIN:VALARM",
+        "ACTION:DISPLAY",
+        f"DESCRIPTION:{_escape_text(f'Water {plant.nickname}')}",
+        "TRIGGER:-PT30M",
+        "END:VALARM",
+        "END:VEVENT",
+    ]
+
+
+def _escape_text(value: str) -> str:
+    return (
+        value.replace("\\", "\\\\")
+        .replace("\r\n", "\n")
+        .replace("\r", "\n")
+        .replace("\n", "\\n")
+        .replace(";", "\\;")
+        .replace(",", "\\,")
+    )
+
+
+def _fold_line(line: str, limit: int = 75) -> str:
+    encoded = line.encode("utf-8")
+    if len(encoded) <= limit:
+        return line
+
+    chunks: list[str] = []
+    remaining = line
+    first = True
+    while remaining:
+        available = limit if first else limit - 1
+        byte_count = 0
+        split_at = 0
+        for char in remaining:
+            char_length = len(char.encode("utf-8"))
+            if byte_count + char_length > available:
+                break
+            byte_count += char_length
+            split_at += 1
+        if split_at == 0:
+            split_at = 1
+
+        prefix = "" if first else " "
+        chunks.append(prefix + remaining[:split_at])
+        remaining = remaining[split_at:]
+        first = False
+    return "\r\n".join(chunks)

waterleaf/evaluation.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+def score_predictions(rows: Sequence[dict]) -> dict[str, float | int]:
+    count = len(rows)
+    if count == 0:
+        return {
+            "count": 0,
+            "species_top_1": 0.0,
+            "species_top_3": 0.0,
+            "genus_top_1": 0.0,
+        }
+
+    species_top_1 = 0
+    species_top_3 = 0
+    genus_top_1 = 0
+    for row in rows:
+        expected = _normalize(row["expected"])
+        predictions = [_normalize(value) for value in row.get("predictions", [])]
+        if predictions and predictions[0] == expected:
+            species_top_1 += 1
+        if expected in predictions[:3]:
+            species_top_3 += 1
+        if predictions and _genus(predictions[0]) == _genus(expected):
+            genus_top_1 += 1
+
+    return {
+        "count": count,
+        "species_top_1": species_top_1 / count,
+        "species_top_3": species_top_3 / count,
+        "genus_top_1": genus_top_1 / count,
+    }
+
+
+def _normalize(value: str) -> str:
+    return " ".join(value.casefold().split())
+
+
+def _genus(scientific_name: str) -> str:
+    return scientific_name.split(" ", maxsplit=1)[0]
+

waterleaf/images.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import hashlib
+import io
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+MAX_IMAGE_EDGE = 1600
+
+
+@dataclass(frozen=True)
+class StoredImage:
+    id: str
+    path: Path
+    width: int
+    height: int
+
+
+def normalize_plant_image(
+    source_path: str | Path,
+    media_directory: str | Path,
+) -> StoredImage:
+    media_path = Path(media_directory)
+    media_path.mkdir(parents=True, exist_ok=True)
+
+    with Image.open(source_path) as source:
+        normalized = ImageOps.exif_transpose(source).convert("RGB")
+        normalized.thumbnail((MAX_IMAGE_EDGE, MAX_IMAGE_EDGE), Image.Resampling.LANCZOS)
+        width, height = normalized.size
+        buffer = io.BytesIO()
+        normalized.save(buffer, format="JPEG", quality=88, optimize=True)
+
+    content = buffer.getvalue()
+    image_id = hashlib.sha256(content).hexdigest()[:32]
+    destination = media_path / f"{image_id}.jpg"
+    if not destination.exists():
+        destination.write_bytes(content)
+    return StoredImage(id=image_id, path=destination, width=width, height=height)
+

waterleaf/models.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, time
+
+from pydantic import BaseModel, Field
+
+
+@dataclass(frozen=True)
+class CareBenchmark:
+    min_days: int | None
+    max_days: int | None
+
+    @property
+    def interval_days(self) -> int:
+        if self.min_days is None or self.max_days is None:
+            raise ValueError("A watering interval is required")
+        if self.min_days < 1 or self.max_days < self.min_days:
+            raise ValueError("Watering interval must be positive and ordered")
+        return round((self.min_days + self.max_days) / 2)
+
+
+@dataclass(frozen=True)
+class PlantContext:
+    is_container: bool
+    size_label: str
+
+
+@dataclass(frozen=True)
+class WeatherDay:
+    date: date
+    precipitation_mm: float
+    max_temperature_c: float
+    et0_mm: float
+
+
+@dataclass(frozen=True)
+class WateringEvent:
+    date: date
+    reason: str
+    confidence: str
+
+
+@dataclass(frozen=True)
+class PlantDraft:
+    nickname: str
+    common_name: str
+    scientific_name: str
+    taxon_key: str
+    location_name: str
+    latitude: float
+    longitude: float
+    timezone: str
+    preferred_time: time
+    is_container: bool
+    size_label: str
+    image_id: str
+    care_min_days: int | None
+    care_max_days: int | None
+
+
+@dataclass(frozen=True)
+class SavedPlant:
+    id: str
+    owner: str
+    public_slug: str
+    nickname: str
+    common_name: str
+    scientific_name: str
+    taxon_key: str
+    location_name: str
+    latitude: float
+    longitude: float
+    timezone: str
+    preferred_time: time
+    is_container: bool
+    size_label: str
+    image_id: str
+    care_min_days: int | None
+    care_max_days: int | None
+
+
+@dataclass(frozen=True)
+class PublicPlant:
+    public_slug: str
+    nickname: str
+    common_name: str
+    scientific_name: str
+    image_id: str
+    is_container: bool
+    size_label: str
+    care_min_days: int | None
+    care_max_days: int | None
+
+
+class TaxonCandidate(BaseModel):
+    taxon_key: str
+    scientific_name: str
+    common_name: str
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+    rationale: str = ""
+
+
+class VisualAnalysis(BaseModel):
+    traits: list[str]
+    proposed_names: list[str]
+    is_container: bool
+    size_label: str
+
+
+class IdentificationResult(BaseModel):
+    visual: VisualAnalysis
+    candidates: list[TaxonCandidate]
+
+
+class CareProfile(BaseModel):
+    scientific_name: str
+    common_name: str
+    min_days: int | None = None
+    max_days: int | None = None
+    watering_label: str = ""
+    sunlight: list[str] = []
+
+
+class LocationMatch(BaseModel):
+    display_name: str
+    latitude: float
+    longitude: float
+    timezone: str
+
+
+@dataclass(frozen=True)
+class SchedulePlan:
+    location: LocationMatch
+    care: CareProfile
+    events: list[WateringEvent]
+    is_container: bool
+    size_label: str

waterleaf/rate_limit.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+from threading import Lock
+
+
+class SlidingWindowRateLimiter:
+    def __init__(self, *, limit: int, window_seconds: float):
+        self.limit = limit
+        self.window_seconds = window_seconds
+        self._attempts: dict[str, deque[float]] = defaultdict(deque)
+        self._lock = Lock()
+
+    def allow(self, key: str, *, now: float | None = None) -> bool:
+        current = time.monotonic() if now is None else now
+        cutoff = current - self.window_seconds
+        with self._lock:
+            attempts = self._attempts[key]
+            while attempts and attempts[0] <= cutoff:
+                attempts.popleft()
+            if len(attempts) >= self.limit:
+                return False
+            attempts.append(current)
+            return True
+

waterleaf/runtime.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from waterleaf.application import WaterleafApplication
+from waterleaf.services.demo import DemoTaxonomy, build_demo_identification
+from waterleaf.services.gbif import GbifClient
+from waterleaf.services.identification import IdentificationService
+from waterleaf.services.llama_cpp import LlamaCppClient
+from waterleaf.services.open_meteo import OpenMeteoClient
+from waterleaf.services.perenual import PerenualClient
+from waterleaf.settings import Settings
+from waterleaf.storage import GardenStore
+
+
+def build_application(settings: Settings | None = None) -> WaterleafApplication:
+    settings = settings or Settings.from_env()
+    settings.data_directory.mkdir(parents=True, exist_ok=True)
+
+    if settings.modal_endpoint:
+        taxonomy = GbifClient()
+        identification = IdentificationService(
+            vision=LlamaCppClient(
+                endpoint=settings.modal_endpoint,
+                modal_key=settings.modal_key,
+                modal_secret=settings.modal_secret,
+            ),
+            taxonomy=taxonomy,
+        )
+    else:
+        taxonomy = DemoTaxonomy()
+        identification = build_demo_identification()
+
+    return WaterleafApplication(
+        store=GardenStore(settings.database_path),
+        media_directory=settings.media_directory,
+        export_directory=settings.export_directory,
+        public_base_url=settings.public_base_url,
+        care=PerenualClient(
+            api_key=settings.perenual_api_key,
+            cache_path=settings.care_cache_path,
+        ),
+        weather=OpenMeteoClient(),
+        identification=identification,
+        taxonomy=taxonomy,
+    )
+

waterleaf/scheduling.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from waterleaf.models import CareBenchmark, PlantContext, WateringEvent, WeatherDay
+
+FORECAST_WINDOW_DAYS = 16
+CONTAINER_INTERVAL_FACTOR = 0.75
+RAIN_THRESHOLD_MM = 5.0
+HOT_TEMPERATURE_C = 30.0
+HIGH_ET0_MM = 5.0
+
+
+def build_watering_schedule(
+    *,
+    start: date,
+    days: int,
+    care: CareBenchmark,
+    context: PlantContext,
+    weather: list[WeatherDay],
+) -> list[WateringEvent]:
+    if days < 1:
+        return []
+
+    interval = care.interval_days
+    if context.is_container:
+        interval = max(1, round(interval * CONTAINER_INTERVAL_FACTOR))
+
+    weather_by_date = {item.date: item for item in weather}
+    horizon = start + timedelta(days=days)
+    candidate = start + timedelta(days=interval)
+    events: list[WateringEvent] = []
+
+    while candidate <= horizon:
+        event_date, reason, confidence = _adjust_candidate(
+            start=start,
+            candidate=candidate,
+            weather=weather_by_date,
+        )
+        if event_date > horizon:
+            break
+        if not events or event_date > events[-1].date:
+            events.append(
+                WateringEvent(
+                    date=event_date,
+                    reason=reason,
+                    confidence=confidence,
+                )
+            )
+        candidate = event_date + timedelta(days=interval)
+
+    return events
+
+
+def _adjust_candidate(
+    *,
+    start: date,
+    candidate: date,
+    weather: dict[date, WeatherDay],
+) -> tuple[date, str, str]:
+    day_number = (candidate - start).days
+    if day_number > FORECAST_WINDOW_DAYS:
+        return candidate, "Seasonal care baseline", "seasonal"
+
+    nearby = [
+        weather.get(candidate - timedelta(days=1)),
+        weather.get(candidate),
+    ]
+    if any(item and item.precipitation_mm >= RAIN_THRESHOLD_MM for item in nearby):
+        return candidate + timedelta(days=2), "Deferred after forecast rain", "forecast"
+
+    current = weather.get(candidate)
+    if current and (
+        current.max_temperature_c >= HOT_TEMPERATURE_C or current.et0_mm >= HIGH_ET0_MM
+    ):
+        return candidate - timedelta(days=1), "Advanced for hot, drying weather", "forecast"
+
+    return candidate, "Species care baseline", "baseline"
+

waterleaf/services/__init__.py

@@ -0,0 +1,2 @@
+"""External service adapters."""
+

waterleaf/services/demo.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from waterleaf.models import TaxonCandidate, VisualAnalysis
+from waterleaf.services.identification import IdentificationService
+
+DEMO_TAXA = [
+    TaxonCandidate(
+        taxon_key="2925518",
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+    ),
+    TaxonCandidate(
+        taxon_key="2927009",
+        scientific_name="Salvia officinalis",
+        common_name="Common sage",
+    ),
+    TaxonCandidate(
+        taxon_key="2926017",
+        scientific_name="Salvia rosmarinus",
+        common_name="Rosemary",
+    ),
+]
+
+
+class DemoVision:
+    def analyze_images(self, image_paths: list[Path]) -> VisualAnalysis:
+        return VisualAnalysis(
+            traits=[
+                "purple flower spikes",
+                "narrow gray-green leaves",
+                "woody compact growth",
+            ],
+            proposed_names=[
+                "Lavandula angustifolia",
+                "Salvia officinalis",
+                "Salvia rosmarinus",
+            ],
+            is_container=True,
+            size_label="medium",
+        )
+
+    def rerank(self, image_paths, visual, candidates):
+        scores = [0.92, 0.34, 0.18]
+        reasons = [
+            "Flower spikes and narrow gray-green leaves match.",
+            "Leaf color is plausible, but the flower form is weaker.",
+            "Woody growth is plausible, but leaf and flower shape differ.",
+        ]
+        return [
+            {
+                "taxon_key": candidate.taxon_key,
+                "confidence": scores[index] if index < len(scores) else 0.1,
+                "rationale": reasons[index] if index < len(reasons) else "Weak visual match.",
+            }
+            for index, candidate in enumerate(candidates)
+        ]
+
+
+class DemoTaxonomy:
+    def suggest(self, query: str, limit: int = 10) -> list[TaxonCandidate]:
+        needle = query.casefold().strip()
+        if not needle:
+            return []
+        matches = [
+            candidate
+            for candidate in DEMO_TAXA
+            if needle in candidate.common_name.casefold()
+            or needle in candidate.scientific_name.casefold()
+        ]
+        return matches[:limit]
+
+
+def build_demo_identification() -> IdentificationService:
+    return IdentificationService(vision=DemoVision(), taxonomy=DemoTaxonomy())
+

waterleaf/services/gbif.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+import httpx
+
+from waterleaf.models import TaxonCandidate
+
+PLANTAE_KEY = 6
+
+
+class GbifClient:
+    def __init__(
+        self,
+        *,
+        http_client: httpx.Client | None = None,
+        base_url: str = "https://api.gbif.org/v1",
+    ):
+        self.http_client = http_client or httpx.Client(timeout=15.0)
+        self.base_url = base_url.rstrip("/")
+
+    def suggest(self, query: str, limit: int = 10) -> list[TaxonCandidate]:
+        query = query.strip()
+        if len(query) < 2:
+            return []
+        response = self.http_client.get(
+            f"{self.base_url}/species/search",
+            params={
+                "q": query,
+                "rank": "SPECIES",
+                "highertaxon_key": PLANTAE_KEY,
+                "language": "en",
+                "limit": min(max(limit * 3, 20), 100),
+            },
+            headers={"User-Agent": "Waterleaf/0.1 karaoguzh@gmail.com"},
+        )
+        response.raise_for_status()
+        matches: list[tuple[int, TaxonCandidate]] = []
+        seen: set[str] = set()
+        for item in response.json().get("results", []):
+            if item.get("kingdom") != "Plantae" or item.get("rank") != "SPECIES":
+                continue
+            key = str(item.get("key", ""))
+            if not key or key in seen:
+                continue
+            scientific_name = item.get("canonicalName") or item.get("scientificName")
+            if not scientific_name:
+                continue
+            seen.add(key)
+            common_name = _common_name(item, query) or scientific_name
+            candidate = TaxonCandidate(
+                taxon_key=key,
+                scientific_name=scientific_name,
+                common_name=common_name,
+            )
+            matches.append(
+                (
+                    _match_score(
+                        query=query,
+                        scientific_name=scientific_name,
+                        common_name=common_name,
+                        status=str(item.get("taxonomicStatus", "")),
+                    ),
+                    candidate,
+                )
+            )
+        matches.sort(
+            key=lambda match: (
+                -match[0],
+                match[1].common_name.casefold(),
+                match[1].scientific_name.casefold(),
+            )
+        )
+        candidates: list[TaxonCandidate] = []
+        seen_scientific_names: set[str] = set()
+        for _, candidate in matches:
+            scientific_name = candidate.scientific_name.casefold()
+            if scientific_name in seen_scientific_names:
+                continue
+            seen_scientific_names.add(scientific_name)
+            candidates.append(candidate)
+            if len(candidates) == limit:
+                break
+        return candidates
+
+
+def _common_name(item: dict[str, Any], query: str) -> str | None:
+    names = [
+        str(record.get("vernacularName", "")).strip()
+        for record in item.get("vernacularNames", [])
+        if str(record.get("language", "")).casefold() in {"en", "eng", "english"}
+        and str(record.get("vernacularName", "")).strip()
+    ]
+    direct = str(item.get("vernacularName", "")).strip()
+    if direct:
+        names.append(direct)
+    if not names:
+        return None
+
+    displays: dict[str, str] = {}
+    counts: Counter[str] = Counter()
+    for name in names:
+        normalized = name.casefold()
+        displays.setdefault(normalized, name)
+        counts[normalized] += 1
+    query_normalized = query.casefold()
+    best = min(
+        counts,
+        key=lambda name: (
+            name != query_normalized,
+            query_normalized not in name,
+            -counts[name],
+            len(name),
+            name,
+        ),
+    )
+    return displays[best]
+
+
+def _match_score(
+    *,
+    query: str,
+    scientific_name: str,
+    common_name: str,
+    status: str,
+) -> int:
+    needle = query.casefold()
+    scientific = scientific_name.casefold()
+    common = common_name.casefold()
+    score = 0
+    if common != scientific:
+        if common == needle:
+            score += 1000
+        elif needle in common:
+            score += 300
+    if scientific == needle:
+        score += 900
+    elif scientific.startswith(needle):
+        score += 250
+    if status.casefold() == "accepted":
+        score += 100
+    return score

waterleaf/services/identification.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from waterleaf.models import IdentificationResult, TaxonCandidate, VisualAnalysis
+
+
+class VisionService(Protocol):
+    def analyze_images(self, image_paths: list[Path]) -> VisualAnalysis: ...
+
+    def rerank(
+        self,
+        image_paths: list[Path],
+        visual: VisualAnalysis,
+        candidates: list[TaxonCandidate],
+    ) -> list[dict]: ...
+
+
+class TaxonomyService(Protocol):
+    def suggest(self, query: str, limit: int = 5) -> list[TaxonCandidate]: ...
+
+
+class IdentificationService:
+    def __init__(self, *, vision: VisionService, taxonomy: TaxonomyService):
+        self.vision = vision
+        self.taxonomy = taxonomy
+
+    def identify(self, image_paths: list[Path]) -> IdentificationResult:
+        visual = self.vision.analyze_images(image_paths)
+        grounded: list[TaxonCandidate] = []
+        seen: set[str] = set()
+        for name in visual.proposed_names:
+            for candidate in self.taxonomy.suggest(name, limit=3):
+                if candidate.taxon_key not in seen:
+                    grounded.append(candidate)
+                    seen.add(candidate.taxon_key)
+                    break
+
+        ranking = self.vision.rerank(image_paths, visual, grounded)
+        ranking_by_key = {
+            item["taxon_key"]: item for item in ranking if item["taxon_key"] in seen
+        }
+        candidates: list[TaxonCandidate] = []
+        for candidate in grounded:
+            scored = ranking_by_key.get(candidate.taxon_key)
+            if not scored:
+                continue
+            candidates.append(
+                candidate.model_copy(
+                    update={
+                        "confidence": scored["confidence"],
+                        "rationale": scored["rationale"],
+                    }
+                )
+            )
+        candidates.sort(key=lambda item: item.confidence, reverse=True)
+        return IdentificationResult(visual=visual, candidates=candidates[:3])
+

waterleaf/services/llama_cpp.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import base64
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from waterleaf.models import TaxonCandidate, VisualAnalysis
+
+VISUAL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "traits": {"type": "array", "items": {"type": "string"}},
+        "proposed_names": {"type": "array", "items": {"type": "string"}},
+        "is_container": {"type": "boolean"},
+        "size_label": {"type": "string", "enum": ["small", "medium", "large"]},
+    },
+    "required": ["traits", "proposed_names", "is_container", "size_label"],
+    "additionalProperties": False,
+}
+
+RERANK_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "ranking": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "taxon_key": {"type": "string"},
+                    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+                    "rationale": {"type": "string"},
+                },
+                "required": ["taxon_key", "confidence", "rationale"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["ranking"],
+    "additionalProperties": False,
+}
+
+
+class LlamaCppClient:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        modal_key: str | None = None,
+        modal_secret: str | None = None,
+        http_client: httpx.Client | None = None,
+        max_startup_wait_seconds: float = 120.0,
+    ):
+        self.endpoint = endpoint.rstrip("/")
+        self.http_client = http_client or httpx.Client(timeout=180.0)
+        self.max_startup_wait_seconds = max_startup_wait_seconds
+        self.headers = {"Authorization": "Bearer waterleaf"}
+        if modal_key and modal_secret:
+            self.headers.update({"Modal-Key": modal_key, "Modal-Secret": modal_secret})
+
+    def analyze_images(self, image_paths: list[Path]) -> VisualAnalysis:
+        content: list[dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": (
+                    "Identify visible botanical traits and propose up to five likely species. "
+                    "Infer only visible context: container versus in-ground and rough size."
+                ),
+            }
+        ]
+        content.extend(_image_part(path) for path in image_paths)
+        payload = self._completion_payload(
+            content,
+            schema_name="visual_analysis",
+            schema=VISUAL_SCHEMA,
+        )
+        result = self._post(payload)
+        return VisualAnalysis.model_validate(result)
+
+    def rerank(
+        self,
+        image_paths: list[Path],
+        visual: VisualAnalysis,
+        candidates: list[TaxonCandidate],
+    ) -> list[dict[str, Any]]:
+        content: list[dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": (
+                    "Rank only these database candidates against the images and observed traits. "
+                    "Do not add species. Candidates: "
+                    + json.dumps([item.model_dump() for item in candidates])
+                    + " Traits: "
+                    + json.dumps(visual.traits)
+                ),
+            }
+        ]
+        content.extend(_image_part(path) for path in image_paths)
+        result = self._post(
+            self._completion_payload(
+                content,
+                schema_name="candidate_ranking",
+                schema=RERANK_SCHEMA,
+                enable_thinking=True,
+            )
+        )
+        return result["ranking"]
+
+    def _completion_payload(
+        self,
+        content: list[dict[str, Any]],
+        schema_name: str,
+        schema: dict[str, Any],
+        enable_thinking: bool = False,
+    ) -> dict[str, Any]:
+        return {
+            "model": "waterleaf-gemma-4",
+            "messages": [
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a cautious plant identification assistant. Return only JSON "
+                        "matching the requested schema. Never claim certainty from an image."
+                    ),
+                },
+                {"role": "user", "content": content},
+            ],
+            "temperature": 0.1,
+            "max_tokens": 700,
+            "chat_template_kwargs": {"enable_thinking": enable_thinking},
+            "response_format": {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": schema_name,
+                    "schema": schema,
+                    "strict": True,
+                },
+            },
+        }
+
+    def _post(self, payload: dict[str, Any]) -> dict[str, Any]:
+        deadline = time.monotonic() + self.max_startup_wait_seconds
+        while True:
+            response = self.http_client.post(
+                f"{self.endpoint}/v1/chat/completions",
+                headers=self.headers,
+                json=payload,
+            )
+            if response.status_code != 503:
+                response.raise_for_status()
+                message = response.json()["choices"][0]["message"]["content"]
+                return json.loads(message)
+            if time.monotonic() >= deadline:
+                raise TimeoutError("Modal model did not become ready")
+            time.sleep(1)
+
+
+def _image_part(path: Path) -> dict[str, Any]:
+    mime = "image/png" if path.suffix.lower() == ".png" else "image/jpeg"
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return {
+        "type": "image_url",
+        "image_url": {"url": f"data:{mime};base64,{encoded}"},
+    }

waterleaf/services/open_meteo.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from datetime import date
+
+import httpx
+
+from waterleaf.models import LocationMatch, WeatherDay
+
+
+class OpenMeteoClient:
+    def __init__(self, *, http_client: httpx.Client | None = None):
+        self.http_client = http_client or httpx.Client(timeout=15.0)
+
+    def geocode(self, query: str) -> LocationMatch:
+        response = self.http_client.get(
+            "https://geocoding-api.open-meteo.com/v1/search",
+            params={"name": query, "count": 1, "language": "en", "format": "json"},
+        )
+        response.raise_for_status()
+        results = response.json().get("results", [])
+        if not results:
+            raise ValueError(f"Location not found: {query}")
+        item = results[0]
+        display = ", ".join(
+            part for part in [item.get("name"), item.get("admin1"), item.get("country")] if part
+        )
+        return LocationMatch(
+            display_name=display,
+            latitude=item["latitude"],
+            longitude=item["longitude"],
+            timezone=item["timezone"],
+        )
+
+    def forecast(self, latitude: float, longitude: float) -> list[WeatherDay]:
+        response = self.http_client.get(
+            "https://api.open-meteo.com/v1/forecast",
+            params={
+                "latitude": latitude,
+                "longitude": longitude,
+                "daily": (
+                    "precipitation_sum,temperature_2m_max,"
+                    "et0_fao_evapotranspiration"
+                ),
+                "forecast_days": 16,
+                "timezone": "auto",
+            },
+        )
+        response.raise_for_status()
+        daily = response.json()["daily"]
+        return [
+            WeatherDay(
+                date=date.fromisoformat(day),
+                precipitation_mm=float(daily["precipitation_sum"][index] or 0),
+                max_temperature_c=float(daily["temperature_2m_max"][index] or 0),
+                et0_mm=float(daily["et0_fao_evapotranspiration"][index] or 0),
+            )
+            for index, day in enumerate(daily["time"])
+        ]
+

waterleaf/services/perenual.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+
+from waterleaf.models import CareProfile
+
+DEMO_CARE = {
+    "Lavandula angustifolia": CareProfile(
+        scientific_name="Lavandula angustifolia",
+        common_name="English lavender",
+        min_days=7,
+        max_days=10,
+        watering_label="Minimum",
+        sunlight=["full sun"],
+    ),
+    "Salvia officinalis": CareProfile(
+        scientific_name="Salvia officinalis",
+        common_name="Common sage",
+        min_days=7,
+        max_days=10,
+        watering_label="Minimum",
+        sunlight=["full sun"],
+    ),
+}
+
+
+class PerenualClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        cache_path: str | Path,
+        http_client: httpx.Client | None = None,
+        base_url: str = "https://perenual.com/api/v2",
+    ):
+        self.api_key = api_key
+        self.cache_path = Path(cache_path)
+        self.http_client = http_client or httpx.Client(timeout=20.0)
+        self.base_url = base_url.rstrip("/")
+        self._cache = self._load_cache()
+
+    def get_care(self, scientific_name: str) -> CareProfile:
+        if scientific_name in self._cache:
+            return CareProfile.model_validate(self._cache[scientific_name])
+        if not self.api_key:
+            profile = DEMO_CARE.get(scientific_name) or CareProfile(
+                scientific_name=scientific_name,
+                common_name=scientific_name,
+            )
+            self._remember(scientific_name, profile)
+            return profile
+
+        search = self.http_client.get(
+            f"{self.base_url}/species-list",
+            params={"key": self.api_key, "q": scientific_name},
+        )
+        search.raise_for_status()
+        entries = search.json().get("data", [])
+        if not entries:
+            profile = CareProfile(
+                scientific_name=scientific_name,
+                common_name=scientific_name,
+            )
+            self._remember(scientific_name, profile)
+            return profile
+
+        details = self.http_client.get(
+            f"{self.base_url}/species/details/{entries[0]['id']}",
+            params={"key": self.api_key},
+        )
+        details.raise_for_status()
+        payload = details.json()
+        min_days, max_days = _parse_benchmark(payload.get("watering_general_benchmark"))
+        scientific = payload.get("scientific_name") or [scientific_name]
+        profile = CareProfile(
+            scientific_name=scientific[0] if isinstance(scientific, list) else scientific,
+            common_name=payload.get("common_name") or scientific_name,
+            min_days=min_days,
+            max_days=max_days,
+            watering_label=payload.get("watering") or "",
+            sunlight=payload.get("sunlight") or [],
+        )
+        self._remember(scientific_name, profile)
+        return profile
+
+    def _load_cache(self) -> dict:
+        if not self.cache_path.exists():
+            return {}
+        try:
+            return json.loads(self.cache_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _remember(self, key: str, profile: CareProfile) -> None:
+        self._cache[key] = profile.model_dump()
+        self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+        self.cache_path.write_text(json.dumps(self._cache, indent=2, sort_keys=True))
+
+
+def _parse_benchmark(payload: dict | None) -> tuple[int | None, int | None]:
+    if not payload or payload.get("unit") != "days":
+        return None, None
+    value = payload.get("value")
+    if isinstance(value, int):
+        return value, value
+    if isinstance(value, str):
+        parts = value.replace(" ", "").split("-")
+        try:
+            if len(parts) == 1:
+                parsed = int(parts[0])
+                return parsed, parsed
+            return int(parts[0]), int(parts[1])
+        except ValueError:
+            return None, None
+    return None, None
+

waterleaf/settings.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+    data_directory: Path
+    public_base_url: str
+    perenual_api_key: str | None
+    modal_endpoint: str | None
+    modal_key: str | None
+    modal_secret: str | None
+
+    @property
+    def database_path(self) -> Path:
+        return self.data_directory / "waterleaf.sqlite3"
+
+    @property
+    def media_directory(self) -> Path:
+        return self.data_directory / "media"
+
+    @property
+    def export_directory(self) -> Path:
+        return self.data_directory / "exports"
+
+    @property
+    def care_cache_path(self) -> Path:
+        return self.data_directory / "cache" / "perenual.json"
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        data_directory = Path(os.getenv("WATERLEAF_DATA_DIR", "data"))
+        public_base_url = os.getenv("PUBLIC_BASE_URL")
+        if not public_base_url:
+            space_host = os.getenv("SPACE_HOST")
+            public_base_url = (
+                f"https://{space_host}" if space_host else "http://localhost:7860"
+            )
+        return cls(
+            data_directory=data_directory,
+            public_base_url=public_base_url.rstrip("/"),
+            perenual_api_key=os.getenv("PERENUAL_API_KEY"),
+            modal_endpoint=os.getenv("MODAL_ENDPOINT"),
+            modal_key=os.getenv("MODAL_KEY"),
+            modal_secret=os.getenv("MODAL_SECRET"),
+        )

waterleaf/storage.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import json
+import secrets
+import sqlite3
+import uuid
+from datetime import time
+from pathlib import Path
+from typing import Any
+
+from waterleaf.models import PlantDraft, PublicPlant, SavedPlant
+
+
+class GardenStore:
+    def __init__(self, database_path: str | Path):
+        self.database_path = Path(database_path)
+        self.database_path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.database_path)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA foreign_keys = ON")
+        return connection
+
+    def _initialize(self) -> None:
+        with self._connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS plants (
+                    id TEXT PRIMARY KEY,
+                    owner TEXT NOT NULL,
+                    public_slug TEXT NOT NULL UNIQUE,
+                    nickname TEXT NOT NULL,
+                    common_name TEXT NOT NULL,
+                    scientific_name TEXT NOT NULL,
+                    taxon_key TEXT NOT NULL,
+                    location_name TEXT NOT NULL,
+                    latitude REAL NOT NULL,
+                    longitude REAL NOT NULL,
+                    timezone TEXT NOT NULL,
+                    preferred_time TEXT NOT NULL,
+                    is_container INTEGER NOT NULL,
+                    size_label TEXT NOT NULL,
+                    image_id TEXT NOT NULL,
+                    care_min_days INTEGER,
+                    care_max_days INTEGER,
+                    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+                );
+                CREATE INDEX IF NOT EXISTS idx_plants_owner ON plants(owner);
+
+                CREATE TABLE IF NOT EXISTS schedules (
+                    plant_id TEXT PRIMARY KEY,
+                    owner TEXT NOT NULL,
+                    events_json TEXT NOT NULL,
+                    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY (plant_id) REFERENCES plants(id) ON DELETE CASCADE
+                );
+                """
+            )
+
+    def save_plant(self, owner: str, draft: PlantDraft) -> SavedPlant:
+        plant_id = str(uuid.uuid4())
+        public_slug = secrets.token_urlsafe(18)
+        values = (
+            plant_id,
+            owner,
+            public_slug,
+            draft.nickname.strip(),
+            draft.common_name.strip(),
+            draft.scientific_name.strip(),
+            draft.taxon_key,
+            draft.location_name.strip(),
+            round(draft.latitude, 2),
+            round(draft.longitude, 2),
+            draft.timezone,
+            draft.preferred_time.isoformat(timespec="minutes"),
+            int(draft.is_container),
+            draft.size_label,
+            draft.image_id,
+            draft.care_min_days,
+            draft.care_max_days,
+        )
+        with self._connect() as connection:
+            connection.execute(
+                """
+                INSERT INTO plants (
+                    id, owner, public_slug, nickname, common_name, scientific_name,
+                    taxon_key, location_name, latitude, longitude, timezone,
+                    preferred_time, is_container, size_label, image_id,
+                    care_min_days, care_max_days
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                values,
+            )
+        plant = self.get_plant(owner, plant_id)
+        if plant is None:
+            raise RuntimeError("Saved plant could not be loaded")
+        return plant
+
+    def list_plants(self, owner: str) -> list[SavedPlant]:
+        with self._connect() as connection:
+            rows = connection.execute(
+                "SELECT * FROM plants WHERE owner = ? ORDER BY created_at, id",
+                (owner,),
+            ).fetchall()
+        return [self._plant_from_row(row) for row in rows]
+
+    def get_plant(self, owner: str, plant_id: str) -> SavedPlant | None:
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT * FROM plants WHERE owner = ? AND id = ?",
+                (owner, plant_id),
+            ).fetchone()
+        return self._plant_from_row(row) if row else None
+
+    def get_public_plant(self, public_slug: str) -> PublicPlant | None:
+        with self._connect() as connection:
+            row = connection.execute(
+                """
+                SELECT public_slug, nickname, common_name, scientific_name,
+                       image_id, is_container, size_label, care_min_days,
+                       care_max_days
+                FROM plants WHERE public_slug = ?
+                """,
+                (public_slug,),
+            ).fetchone()
+        if not row:
+            return None
+        return PublicPlant(
+            public_slug=row["public_slug"],
+            nickname=row["nickname"],
+            common_name=row["common_name"],
+            scientific_name=row["scientific_name"],
+            image_id=row["image_id"],
+            is_container=bool(row["is_container"]),
+            size_label=row["size_label"],
+            care_min_days=row["care_min_days"],
+            care_max_days=row["care_max_days"],
+        )
+
+    def delete_plant(self, owner: str, plant_id: str) -> bool:
+        with self._connect() as connection:
+            cursor = connection.execute(
+                "DELETE FROM plants WHERE owner = ? AND id = ?",
+                (owner, plant_id),
+            )
+        return cursor.rowcount == 1
+
+    def image_reference_count(self, image_id: str) -> int:
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT COUNT(*) AS count FROM plants WHERE image_id = ?",
+                (image_id,),
+            ).fetchone()
+        return int(row["count"])
+
+    def replace_schedule(
+        self,
+        owner: str,
+        plant_id: str,
+        events: list[dict[str, Any]],
+    ) -> None:
+        if self.get_plant(owner, plant_id) is None:
+            raise PermissionError("Plant not found for owner")
+        payload = json.dumps(events, separators=(",", ":"), sort_keys=True)
+        with self._connect() as connection:
+            connection.execute(
+                """
+                INSERT INTO schedules (plant_id, owner, events_json)
+                VALUES (?, ?, ?)
+                ON CONFLICT(plant_id) DO UPDATE SET
+                    owner = excluded.owner,
+                    events_json = excluded.events_json,
+                    updated_at = CURRENT_TIMESTAMP
+                """,
+                (plant_id, owner, payload),
+            )
+
+    def get_schedule(self, owner: str, plant_id: str) -> list[dict[str, Any]]:
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT events_json FROM schedules WHERE owner = ? AND plant_id = ?",
+                (owner, plant_id),
+            ).fetchone()
+        return json.loads(row["events_json"]) if row else []
+
+    def get_public_schedule(self, public_slug: str) -> list[dict[str, Any]]:
+        with self._connect() as connection:
+            row = connection.execute(
+                """
+                SELECT schedules.events_json
+                FROM schedules
+                JOIN plants ON plants.id = schedules.plant_id
+                WHERE plants.public_slug = ?
+                """,
+                (public_slug,),
+            ).fetchone()
+        return json.loads(row["events_json"]) if row else []
+
+    @staticmethod
+    def _plant_from_row(row: sqlite3.Row) -> SavedPlant:
+        return SavedPlant(
+            id=row["id"],
+            owner=row["owner"],
+            public_slug=row["public_slug"],
+            nickname=row["nickname"],
+            common_name=row["common_name"],
+            scientific_name=row["scientific_name"],
+            taxon_key=row["taxon_key"],
+            location_name=row["location_name"],
+            latitude=row["latitude"],
+            longitude=row["longitude"],
+            timezone=row["timezone"],
+            preferred_time=time.fromisoformat(row["preferred_time"]),
+            is_container=bool(row["is_container"]),
+            size_label=row["size_label"],
+            image_id=row["image_id"],
+            care_min_days=row["care_min_days"],
+            care_max_days=row["care_max_days"],
+        )