steveandClaude Opus 4.8
156b3fd14c
Photograph a seed packet → it fills in the plant and the purchase. This is the backend; the scan UI is a follow-up PR. Vision model config (mirrors the agent model from #79): - Migration 0011 adds instance_settings.vision_model; PANSY_VISION_MODEL is the env default. Precedence Settings → env → empty; the KEY stays in the env. - EffectiveVision resolves it; /capabilities advertises "vision" only when a model + key are configured, so the UI offers the scan button only when it works. Extraction is one-shot, NOT an agent loop (internal/vision): - majordomo.Generate[SeedPacket] derives a JSON schema from the struct tags and hands the image to the vision model; it can't call a tool, so it can't touch the garden — it only reads a picture and returns data. Numeric fields are pointers, so a field the packet doesn't print comes back nil, not a made-up 0. - Hermetic test: majordomo's fake provider returns canned packet JSON and Generate unmarshals it, image + derived schema included. No live model. The image is normalized to JPEG at the upload boundary (imagenorm from #80), which is where an iPhone HEIC becomes readable — majordomo's media path can't decode HEIC. imagenorm now links into the binary (~7 MB, the cost #80 deferred). The hard part is catalog matching, not OCR (internal/service/seed_packet.go): - A wrong auto-match splits a variety's seed-lot history across duplicate rows, so the service NEVER auto-creates. matchPlants surfaces RANKED candidates (exact name → variety-in-name → same species, conservative and name-based), the user confirms, and CreateFromPacket makes the plant (new or existing) + the lot. Exactly one of plantId/newPlant, refused otherwise. - Plants/lots aren't in the undo history (catalog/inventory), so no change set. - The extractor is injectable (service.WithPacketExtractor) so ExtractSeedPacket and the /scan endpoint test end to end against a fake, no live model. Endpoints: POST /seed-lots/scan (multipart image → proposal, reads only; extends the read deadline for a slow phone upload, caps the body, maps too-large/unreadable to clear statuses) and POST /seed-lots/from-packet (confirmed proposal → 201). Docs: README (PANSY_VISION_MODEL), DESIGN (routes + the decision and why the model can't touch the garden). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ
127 lines
7.9 KiB
Markdown
127 lines
7.9 KiB
Markdown
# pansy
|
|
|
|
Self-hostable garden planner: drag beds, bags, and containers onto a real-scale field, click into them to place freeform plops of plants, and zoom out to see what's planted where. Go backend + React frontend, one static binary.
|
|
|
|
> ### 🤖 This is a vibe-coded project
|
|
>
|
|
> **Essentially all of the code in pansy was written by an LLM** (Claude), with a human directing the work, reviewing it, and deciding what ships. Every pull request also gets an automated adversarial review before it lands.
|
|
>
|
|
> That's said up front because you deserve to know it before you trust pansy with anything: it hasn't been through the kind of scrutiny a hand-written, widely-used project has. Read the code before you self-host it. Back up your database. Bugs here are the ordinary kind of bugs, not a scandal — but so is the fact that nobody hand-wrote the thing.
|
|
|
|
See [DESIGN.md](DESIGN.md) for the architecture. Work is tracked in this repo's issues — start from the tracking epic.
|
|
|
|
## Quickstart
|
|
|
|
**Prerequisites:** Go 1.26+, Node 20+.
|
|
|
|
### Develop
|
|
|
|
Run the Go API and the Vite dev server together (Vite proxies `/api` → the API):
|
|
|
|
```sh
|
|
make dev
|
|
```
|
|
|
|
Then open http://localhost:5173. Or run the two halves in separate terminals for independent restarts:
|
|
|
|
```sh
|
|
make dev-api # Go API on :8080
|
|
make dev-web # Vite dev server on :5173
|
|
```
|
|
|
|
### Build & run
|
|
|
|
Produce the single static binary with the web build embedded, then run it:
|
|
|
|
```sh
|
|
make build
|
|
./pansy
|
|
```
|
|
|
|
Open http://localhost:8080 — one process serves both the JSON API and the app.
|
|
|
|
### Test
|
|
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables; every value has a default, so `./pansy` runs with none set.
|
|
|
|
| Variable | Default | Description |
|
|
| ------------------------- | ------------------ | ------------------------------------------------------------------ |
|
|
| `PANSY_PORT` | `8080` | TCP port the HTTP server listens on. |
|
|
| `PANSY_DB` | `./pansy.db` | SQLite database file path (created if absent). |
|
|
| `PANSY_BASE_URL` | *(empty)* | Externally-visible base URL; used to derive the OIDC redirect URI. |
|
|
| `PANSY_REGISTRATION` | `open` | `open` or `closed` — gates local self-service signup. |
|
|
| `PANSY_LOCAL_AUTH` | `true` | Enable local password auth. Set `false` for pure-OIDC. |
|
|
| `PANSY_OIDC_ISSUER` | *(empty)* | OIDC issuer/discovery URL (Authentik). Enables SSO when set. |
|
|
| `PANSY_OIDC_CLIENT_ID` | *(empty)* | OIDC client ID. |
|
|
| `PANSY_OIDC_CLIENT_SECRET`| *(empty)* | OIDC client secret. |
|
|
| `PANSY_OIDC_BUTTON_LABEL` | `Sign in with Authentik` | Label for the OIDC button on the login page. |
|
|
| `PANSY_TRUSTED_PROXIES` | *(none)* | Comma-separated proxy CIDRs/IPs to trust for client-IP resolution. |
|
|
|
|
The garden assistant reads three more. Setting none of them leaves the assistant off; the app runs exactly as it does without it.
|
|
|
|
| Variable | Default | Description |
|
|
| ----------------------- | ------------------------------ | --------------------------------------------------------------------------- |
|
|
| `OLLAMA_CLOUD_API_KEY` | *(empty)* | Ollama Cloud API key. Without it the assistant is off, not broken. This is the one agent value that stays in the environment — it is **never** stored in the database or editable in Settings. |
|
|
| `PANSY_AGENT_MODEL` | `ollama-cloud/glm-5.2:cloud` | Default model spec, passed verbatim to `majordomo.Parse` — a comma-separated list is a failover chain, e.g. `ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud`. An admin can override this per-instance in **Settings** without a redeploy; a blank Settings value inherits this. |
|
|
| `PANSY_AGENT_ENABLED` | on when a key is present | Default on/off for the assistant. Also overridable in Settings (which can inherit this default). |
|
|
| `PANSY_VISION_MODEL` | *(empty)* | Default model for **seed-packet capture** (photograph a packet → it fills in the plant + purchase). A *vision-capable* model (the chat model may not be). Empty = the feature isn't offered. Runs against the same `OLLAMA_CLOUD_API_KEY`, and is overridable in Settings. |
|
|
|
|
The agent model + enabled flag, and the vision model, can be changed at runtime by an admin under **Settings** (the gear appears in the nav for admins) — an agent change swaps the live assistant with no restart. The env vars above are the defaults an untouched instance uses, and the API key is intentionally not among the runtime-editable settings: a secret in the database would land in every backup. Precedence is **Settings value, if set → env var → built-in default**.
|
|
|
|
The assistant acts without asking first, which is only reasonable because every turn is one undoable change set — see the History panel in the editor.
|
|
|
|
**If you set the key and the assistant still doesn't appear**, check that the variable reaches the *container*, not just your orchestrator's stack config — Compose needs it listed under the service's `environment:`. pansy logs why the assistant is off at startup, and Settings shows the same status (a key present, the resolved model, and whether it's actually running).
|
|
|
|
Local email/password auth is live (`POST /api/v1/auth/register`, `/auth/login`, `/auth/logout`, `GET /auth/me`, `GET /auth/providers`); the session is an HttpOnly cookie (`Secure` when `PANSY_BASE_URL` is https). The first account registered becomes admin, and it may register even when `PANSY_REGISTRATION=closed` to bootstrap the instance.
|
|
|
|
OIDC (Authentik-first) is live too: set `PANSY_OIDC_ISSUER`, `PANSY_OIDC_CLIENT_ID`, `PANSY_OIDC_CLIENT_SECRET`, and `PANSY_BASE_URL` (needed for the redirect URI). Register `PANSY_BASE_URL` + `/api/v1/auth/oidc/callback` as the redirect URI in your IdP. `GET /auth/oidc/login` starts an authorization-code + PKCE flow; first login provisions a user just-in-time (a matching *verified* email links to an existing local account instead of duplicating it). Provider discovery is lazy, so a briefly-unreachable IdP never blocks startup or local auth. Set `PANSY_LOCAL_AUTH=false` for pure-Authentik deployments (local register/login are then rejected and hidden from `/auth/providers`).
|
|
|
|
## Docker & deployment
|
|
|
|
CI (`.gitea/workflows/build-image.yml`) builds the single-binary image and pushes it to the Gitea registry on every branch push:
|
|
|
|
| Ref | Tag |
|
|
| --- | --- |
|
|
| `main` | `gitea.stevedudenhoeffer.com/steve/pansy:latest` |
|
|
| any other branch | `gitea.stevedudenhoeffer.com/steve/pansy:<branch-name>` |
|
|
| every build | `gitea.stevedudenhoeffer.com/steve/pansy:sha-<short>` (immutable; use to pin) |
|
|
|
|
The image runs as a non-root user, serves on `:8080`, and stores the SQLite database on the `/data` volume. Run it directly:
|
|
|
|
```sh
|
|
docker run -d --name pansy \
|
|
-p 8080:8080 \
|
|
-v pansy-data:/data \
|
|
gitea.stevedudenhoeffer.com/steve/pansy:latest
|
|
```
|
|
|
|
Or as a Komodo/Compose stack:
|
|
|
|
```yaml
|
|
services:
|
|
pansy:
|
|
image: gitea.stevedudenhoeffer.com/steve/pansy:${PANSY_TAG:-latest}
|
|
ports:
|
|
- "8080:8080"
|
|
volumes:
|
|
- pansy-data:/data
|
|
environment:
|
|
PANSY_BASE_URL: https://pansy.example.com
|
|
# PANSY_OIDC_ISSUER: https://auth.example.com/application/o/pansy/
|
|
# PANSY_OIDC_CLIENT_ID: ...
|
|
# PANSY_OIDC_CLIENT_SECRET: ...
|
|
# OLLAMA_CLOUD_API_KEY: ${OLLAMA_CLOUD_API_KEY} # enables the garden assistant
|
|
# PANSY_AGENT_MODEL: ollama-cloud/glm-5.2:cloud
|
|
restart: unless-stopped
|
|
volumes:
|
|
pansy-data:
|
|
```
|
|
|
|
Pin `PANSY_TAG` to a `sha-<short>` tag for reproducible deploys, or leave it at `latest` to track `main`.
|