mAi
e22f286024
Every successful imagen generate now (a) uploads the PNG to the private imagen-generated bucket and (b) inserts a row into imagen.images, the data plane the flexsiebels owner-mode viewer reads from. Schema, RLS, indexes, bucket and PostgREST exposure landed via four applied migrations on msupabase: imagen_schema_init, imagen_schema_grants, imagen_storage_policies, imagen_pgrst_expose (authenticator role-level ALTER + reload). Owner UUID for m: ac6c9501-3757-4a6d-8b97-2cff4288382b — documented in the config sample. Code: new internal/cloud/ package mirroring the internal/usage/ shape. PostgREST POST against the imagen schema (Accept-Profile + Content- Profile headers), Storage upload via PUT with x-upsert, retry on 5xx / transport but not 4xx, owner_user_id required (the column is NOT NULL and the read-side RLS policy needs it). Wiring in cmd/imagen/generate.go: --no-cloud flag, output.cloud_sync config knob (auto|on|off mirroring --preview), $IMAGEN_CLOUD_SYNC env override. The hook reads the just-written PNG + sidecar from disk and calls cloud.Sync; failures emit "imagen: cloud sync: <err>" to stderr without changing exit code, so a Supabase blip never loses the artefact. output.Outputs grew Date/Slug/Seed fields so storage_path mirrors the local filename's prefix exactly (no UTC-vs-local drift). Config: owner_user_id field added; sample comment points at the auth.users lookup. imagen config validate warns on stderr when cloud_sync is on/auto but owner_user_id is empty. Tests: cloud_test.go covers happy path, retry-on-5xx, no-retry-on-4xx, missing-owner-uuid, missing-date-or-slug, signed URL, and the partial- success case where the upload landed but the DB insert failed. generate_test.go covers the precedence chain for cloud-sync mode resolution. Build + tests clean across the tree. Real smoke against mRock: generation through flux-schnell-local writes the local PNG + sidecar AND uploads to imagen-generated/2026-05-11/... AND inserts into imagen.images. Signed URL round-trips the same bytes. --no-cloud verified to skip both Storage and DB.
145 lines
6.2 KiB
Markdown
145 lines
6.2 KiB
Markdown
# Using imagen
|
|
|
|
## Subcommands
|
|
|
|
```
|
|
imagen generate <prompt> [flags] generate one image
|
|
imagen backends list configured + registered backends
|
|
imagen config init print a sample imagen.yaml on stdout
|
|
imagen config validate parse + validate the active config
|
|
imagen config path print the resolved config path
|
|
imagen serve [--addr :8080] (stub) start the HTTP server
|
|
imagen version print version
|
|
```
|
|
|
|
## `generate` flags
|
|
|
|
| Flag | Default | Notes |
|
|
| -------------- | ---------------------------- | ----------------------------------------------------------- |
|
|
| `--backend` | `default_backend` from config | Instance name from `imagen.yaml` |
|
|
| `--size` | `1024x1024` | `WxH` |
|
|
| `--seed` | `0` (= backend default) | |
|
|
| `--steps` | `0` (= backend default) | |
|
|
| `--style` | empty | One of `imagen config init`'s style names |
|
|
| `--negative` | empty | Negative prompt (ignored by some adapters) |
|
|
| `--output` | empty (= use naming template) | Explicit path |
|
|
| `--no-sidecar` | `false` | Skip the JSON sidecar even if config enables it |
|
|
| `--preview` | (auto) | Force open a tmux preview window via `tmux-img` |
|
|
| `--no-preview` | (auto) | Suppress the preview window (use for batch / CI callers) |
|
|
| `--no-cloud` | `false` | Skip Supabase upload + `imagen.images` insert for this call |
|
|
| `--config` | `~/.config/imagen.yaml` | Override config path |
|
|
|
|
### Preview window
|
|
|
|
After a successful generate, imagen optionally opens a sibling tmux window
|
|
named `img:<slug>` running `tmux-img --hold <path>`. The new window is
|
|
spawned in the background (`tmux new-window -d`) so the generating pane
|
|
keeps focus and its terminal output.
|
|
|
|
Resolution order is **config → `$IMAGEN_PREVIEW` → flag** (later wins):
|
|
|
|
- `output.preview` in `imagen.yaml`: `auto` (default) | `on` | `off`
|
|
- `IMAGEN_PREVIEW=auto|on|off` overrides config
|
|
- `--preview` / `--no-preview` override env
|
|
|
|
`auto` previews iff stdout is a TTY *and* `$TMUX` is set. `on` previews
|
|
unconditionally and errors outside a tmux session. `off` never previews.
|
|
|
|
Preview failures are non-fatal — the image already wrote.
|
|
|
|
## Examples
|
|
|
|
```sh
|
|
# Quick smoke test — mock backend ships in-tree
|
|
imagen generate "test" --backend mock --output /tmp/x.png
|
|
|
|
# Real generation, FLUX-schnell on mRock via ComfyUI
|
|
imagen generate "a wide editorial blog header about RAG systems" \
|
|
--backend flux-schnell-local \
|
|
--style blog-header \
|
|
--size 1536x768
|
|
|
|
# Explicit seed for reproducibility
|
|
imagen generate "a cat in a fishbowl" --backend mock --seed 42 --output /tmp/cat.png
|
|
```
|
|
|
|
## Config
|
|
|
|
A complete sample is in `imagen config init`. Adapters get only their own
|
|
sub-block — see [`../CLAUDE.md`](../CLAUDE.md) for the contract.
|
|
|
|
## Naming template
|
|
|
|
`output.naming` placeholders:
|
|
|
|
| Placeholder | Replaced with |
|
|
| ----------- | ---------------------------------------- |
|
|
| `{date}` | `2026-05-08` |
|
|
| `{time}` | `143015` (no separators) |
|
|
| `{slug}` | lowercased ASCII prompt, ≤ 40 chars |
|
|
| `{seed}` | seed actually used |
|
|
| `{backend}` | backend instance name |
|
|
| `{ext}` | file extension matching `Result.MimeType` |
|
|
|
|
Unknown placeholders are left literal.
|
|
|
|
## Credentials
|
|
|
|
API-backed adapters read tokens from env vars referenced by the config
|
|
(`api_token_env`, `api_key_env`). Never put a token in `imagen.yaml`.
|
|
|
|
```sh
|
|
export REPLICATE_API_TOKEN=...
|
|
imagen generate "a cat" --backend flux-dev-replicate
|
|
```
|
|
|
|
## Cost-tracking (Replicate)
|
|
|
|
Successful generations through the Replicate adapter write one row to
|
|
`mai.imagen_usage` on Supabase: backend, model, latency, per-image cost
|
|
estimate, prompt sha256 hash (never the prompt itself), and the caller
|
|
identity (resolved from `MAI_FROM_ID` or the tmux pane's `@mai-name`).
|
|
|
|
The writer is best-effort. If `SUPABASE_URL` / `SUPABASE_SERVICE_KEY` are
|
|
unset, or the database write fails, the image still lands and the CLI
|
|
prints a warning to stderr.
|
|
|
|
Inspect spend:
|
|
|
|
```sh
|
|
imagen usage # all rows, grouped by week + backend + model + caller
|
|
imagen usage --since 2026-05-01 # only rows on/after a UTC date
|
|
imagen usage --since 2026-05-01 --raw
|
|
```
|
|
|
|
Per-model rates live in `internal/backend/replicate_pricing.go` — they
|
|
are snapshotted from <https://replicate.com/pricing> and refreshed on a
|
|
quarterly cadence.
|
|
|
|
## Cloud-sync (Supabase)
|
|
|
|
Successful generations also upload the PNG to the private Supabase
|
|
Storage bucket `imagen-generated` (path: `<YYYY-MM-DD>/<slug>-<seed>.png`)
|
|
and insert a row into `imagen.images`. The row carries the prompt,
|
|
sha256-hashed prompt, backend, model, seed/steps/width/height, latency,
|
|
cost estimate, the full local sidecar JSON, and an empty `tags` array
|
|
ready for the flexsiebels viewer to fill in.
|
|
|
|
Configuration:
|
|
|
|
- `owner_user_id` in `imagen.yaml` — m's `auth.users.id`. Empty disables
|
|
inserts (the column is `NOT NULL`).
|
|
- `output.cloud_sync` in `imagen.yaml`: `auto` (default — on iff
|
|
SUPABASE creds + `owner_user_id` are set), `on` (errors if either is
|
|
missing), `off`.
|
|
- `IMAGEN_CLOUD_SYNC=auto|on|off` overrides config.
|
|
- `--no-cloud` overrides everything for one call.
|
|
|
|
Reuses the same Supabase env (`SUPABASE_URL` + `SUPABASE_SERVICE_KEY` or
|
|
`MAI_SUPABASE_KEY`) as cost-tracking. Service-role bypasses RLS for
|
|
inserts; the `owner_user_id = auth.uid()` policy on the table gates the
|
|
read path the flexsiebels viewer hits.
|
|
|
|
Failures (Storage 5xx, DB unreachable) emit `imagen: cloud sync: <err>`
|
|
to stderr and the local PNG + sidecar stay put. Exit code is unchanged.
|