m/ImaGen

Files

mAi b282325663 mAi: #3 - Replicate adapter, mai.imagen_usage cost-tracking, usage CLI

Implements the Replicate API backend (FLUX schnell / FLUX dev) per ImaGen
issue #3:

- internal/backend/replicate.go — Backend adapter. Supports model
  refs as "owner/name" (uses /v1/models/{owner}/{name}/predictions) and
  "owner/name:hash" (uses /v1/predictions with explicit version). Polls
  /v1/predictions/{id} every 500ms with model-aware timeout (60s schnell,
  120s dev). Resilience: 401 names api_token_env, 429 with exp backoff
  up to 3 retries (honours Retry-After), 5xx retries once, image
  download retries once on transient failure.
- internal/backend/replicate_pricing.go — hardcoded per-image USD rates
  for known FLUX models, snapshotted from replicate.com/pricing with a
  refresh TODO.
- internal/backend/replicate_test.go — mocked-HTTP unit tests covering
  happy path (model + version-pinned), 401, 429 retry policy, failed
  prediction, poll timeout, image-download retry, ctx cancel, BackendOpts
  passthrough, default_steps, aspect-ratio reduction, sha256 prompt hash.
- internal/usage/usage.go — Supabase REST sink + read-side query for
  mai.imagen_usage. Adapter writes are best-effort: failures warn but
  the image still lands.
- cmd/imagen/usage.go — `imagen usage [--since DATE] [--raw]` reads
  the table and prints a tab-aligned grouped or raw table with totals.
- cmd/imagen/backends.go — instances of type=replicate now report
  "ok" or "not configured (set REPLICATE_API_TOKEN)" depending on env.
- internal/config/config.go — sample adds flux-schnell-replicate +
  flux-dev-replicate; default_backend stays flux-schnell-local.
- Supabase migration mai.imagen_usage (id, created_at, backend, model,
  seed, prompt_hash, latency_ms, cost_usd_estimate, caller) + indexes
  on (created_at DESC) and (caller). The raw prompt is never stored.

Caller identity resolves from MAI_FROM_ID, then the tmux pane's
@mai-name option, mirroring the maimcp identity logic. Prompt hash is
sha256 of the user-facing prompt; raw prompt never reaches the table.

2026-05-08 17:28:29 +02:00

4.9 KiB

Raw Blame History

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)
`--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

# 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 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.

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:

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.

4.9 KiB Raw Blame History