mimo2codex 0.1.15 → 0.1.17

package/mimoskill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mimoskill
-description: Use Xiaomi MiMo V2.5 (the LLM behind mimo2codex) for chat, vision, web search, TTS and ASR — and route around capabilities MiMo doesn't natively support, especially image generation needed for things like Codex Pets `/hatch`. Trigger when the user mentions MiMo, calls into mimo2codex, asks to generate / hatch a Codex pet, asks for image generation while using MiMo as the chat backend, or hits a "no image generation available" / "image_gen tool unavailable" message inside Codex.
+description: Use Xiaomi MiMo V2.5 (the LLM behind mimo2codex) for chat, vision, web search, TTS and ASR — and route around capabilities MiMo doesn't natively support, especially OCR / image recognition / 识图 / 提取图片文字 / extract text from image when the current model can't see images, and image generation / 图像生成 / 生成图片 / draw a picture / 画一张 including Codex Pets `/hatch`. Trigger when the user mentions MiMo, calls into mimo2codex, asks to read text from an image, asks to describe or 识别 an image while using a non-vision model (mimo-v2.5-pro, mimo-v2-flash, …), asks to generate / hatch a Codex pet, asks for image generation while using MiMo as the chat backend, or hits a "no image generation available" / "image_gen tool unavailable" / "this model does not support image input" message inside Codex.
 ---
 
 # mimoskill — Xiaomi MiMo V2.5 + gap fillers
@@ -18,6 +18,8 @@ Trigger this skill when:
 - User asks "how do I generate a Codex pet" / "/hatch isn't working" / "image_gen tool not available"
 - User wants image generation as part of a MiMo-backed workflow
 - User pastes the Codex error: `the image generation tool (image_gen) is not available in this environment` or `the CLI fallback requires the openai Python package`
+- User wants to **OCR / read text from / describe / 识别 / 提取文字 from an image** while the active chat model is non-vision (e.g. mimo-v2.5-pro, mimo-v2-flash, deepseek-*, or any third-party text-only model) — use `scripts/ocr.py`. Works with or without a MiMo key (free pollinations fallback when `MIMO_API_KEY` is unset).
+- User sees the proxy's `[N image attachment(s) omitted: this model does not support image input …]` placeholder in their transcript
 - Anything in the `mimo2codex` repo that touches a feature MiMo doesn't support
 
 ## What MiMo V2.5 does and doesn't do
@@ -35,7 +37,8 @@ Quick answer:
 | ASR (speech recog) | ✅ | `mimo-v2.5-asr` | separate endpoint |
 | Audio chat | ✅ | `mimo-v2-omni` | input only |
 | Video understanding | ✅ | `mimo-v2-omni` | input only |
-| **Image generation** | ❌ | — | **see workaround below** |
+| **Image generation** | ❌ | — | `scripts/generate_image.py` (general) or `scripts/generate_pet.py` (Codex pets) — see below |
+| OCR / 识图 (when chat model is non-vision) | ⚠️ via `mimo-v2.5` or free pollinations | `scripts/ocr.py` | `--engine auto`: mimo if `MIMO_API_KEY` set, else pollinations (no key) |
 | Code interpreter / sandbox | ❌ | — | not provided |
 
 For the full capability matrix and examples, read [references/models.md](references/models.md).
@@ -43,31 +46,95 @@ For the full capability matrix and examples, read [references/models.md](referen
 ## Decision tree: what does the user actually want?
 
 ```
-Is it chat / vision / search / TTS / ASR?
-├── Yes → use MiMo directly (see "Calling MiMo directly" below) or via mimo2codex if Codex is the client
-└── No, they want image generation
+Is it OCR / read text from image / describe / 识别 an image
+when the active chat model is non-vision?
+├── Yes → use scripts/ocr.py (mimo-v2.5 if MIMO_API_KEY set, else free pollinations)
+└── No
     │
-    Is it for a Codex pet (`/hatch`)?
-    ├── Yes → see "Generating a Codex pet" below
-    └── No → see "Image generation in general" below
+    Is it chat / vision / search / TTS / ASR with a vision-capable model?
+    ├── Yes → use MiMo directly (see "Calling MiMo directly" below) or via mimo2codex if Codex is the client
+    └── No, they want image generation
+        │
+        Is it for a Codex pet (`/hatch`)?
+        ├── Yes → see "Generating a Codex pet" below (scripts/generate_pet.py + install_pet.sh)
+        └── No  → see "General (non-pet) image generation" below (scripts/generate_image.py)
 ```
 
-## Calling MiMo directly
+## Calling chat directly (works without any key)
 
-Use `scripts/mimo_chat.py` to send a single chat completion (or stream):
+Use `scripts/mimo_chat.py` for one-shot or streaming chat. Two engines, `--engine auto` (default) picks `mimo` if `MIMO_API_KEY` is set, else `pollinations` (free, no key) — so **the script works without any key** for text and vision.
 
 ```bash
+# Zero-setup — uses pollinations fallback when MIMO_API_KEY is unset
+python3 mimoskill/scripts/mimo_chat.py "your prompt here"
+python3 mimoskill/scripts/mimo_chat.py --image https://example.com/x.png "describe this"
+
+# Best quality + MiMo-specific features (web search, TTS, ASR)
 export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
 python3 mimoskill/scripts/mimo_chat.py "your prompt here"
-python3 mimoskill/scripts/mimo_chat.py --model mimo-v2.5 --image https://example.com/x.png "describe this"
-python3 mimoskill/scripts/mimo_chat.py --search "今天上海天气?"
+python3 mimoskill/scripts/mimo_chat.py "今天上海天气?"   # web search auto-enabled on sk-* keys
 python3 mimoskill/scripts/mimo_chat.py --stream "tell me a story"
 ```
 
-The script handles all the MiMo-specific quirks — `max_completion_tokens` instead of `max_tokens`, the required `text` part next to `image_url`, web_search plugin invocation, `reasoning_content` round-tripping, etc.
+When the mimo engine is active the script handles all MiMo-specific quirks — `max_completion_tokens` instead of `max_tokens`, the required `text` part next to `image_url`, `reasoning_content` round-tripping, etc. **Web search is auto-enabled on pay-as-you-go (`sk-*`) keys** — the `web_search` builtin is always included in the tools array and the model decides when to invoke it (`tool_choice: "auto"`). Token-plan (`tp-*`) keys skip web search (the endpoint doesn't support it). The pollinations engine doesn't support web search, TTS, or ASR (those are MiMo native features); it auto-switches to OpenAI-compat field names (`max_tokens`).
 
 For non-trivial integrations, [references/models.md](references/models.md) and [the official MiMo OpenAI-compat doc](https://platform.xiaomimimo.com/docs/api/chat/openai-api) are the authoritative references.
 
+## OCR / image recognition (when the chat model can't see images)
+
+If the user wants to **read text from an image** or **describe / 识别 an image** but the current chat model is non-vision (`mimo-v2.5-pro`, `mimo-v2.5-pro[1m]`, `mimo-v2-flash`, `deepseek-*`, or any third-party text-only model), invoke `scripts/ocr.py`. Two engines, `--engine auto` (default) picks the right one:
+
+- **`mimo`** — needs `MIMO_API_KEY`, uses `mimo-v2.5` regardless of the chat model. Best quality.
+- **`pollinations`** — free public vision endpoint at `text.pollinations.ai`, **no key required**. Mirrors the same no-key fallback `generate_pet.py` uses. Rate-limited but always available — covers users who only have a DeepSeek key (or no key at all).
+
+The proxy silently drops image attachments on non-vision models (`src/translate/reqToChat.ts:48-72`) and leaves a `[N image attachment(s) omitted: …]` placeholder. **When you see that placeholder in the transcript, the right move is to run ocr.py and feed the text back into the conversation.** Don't ask the user to switch models.
+
+```bash
+# Zero-setup — uses pollinations fallback when MIMO_API_KEY is unset
+python3 mimoskill/scripts/ocr.py path/to/image.png
+python3 mimoskill/scripts/ocr.py --mode describe https://example.com/x.png
+python3 mimoskill/scripts/ocr.py --mode structured a.png b.jpg
+cat scan.png | python3 mimoskill/scripts/ocr.py --mode markdown
+
+# Best quality — set MiMo key, auto picks mimo
+export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
+python3 mimoskill/scripts/ocr.py path/to/image.png
+
+# Force the free engine even when you have a MiMo key (e.g. to save quota)
+python3 mimoskill/scripts/ocr.py --engine pollinations form.png
+```
+
+`ocr.py` accepts local paths, http(s) URLs, `data:` URLs, or stdin bytes. Magic-byte sniffs the MIME (PNG / JPEG / GIF / WebP / BMP). Multiple positional args are batched into one upstream call. Non-vision `--model` values are auto-coerced to `mimo-v2.5` with one stderr note (mimo engine only; on pollinations use `--pollinations-model`).
+
+See [references/ocr_workflow.md](references/ocr_workflow.md) for full mode reference, exit codes, JSON shape for `--mode structured`, and the `--lang` / `--prompt` knobs.
+
+## General (non-pet) image generation
+
+For arbitrary image generation, use `scripts/generate_image.py` — a thin wrapper over `generate_pet.py` with the chibi-pet prompt boilerplate removed and an optional `--style` for common looks. Same providers (`auto` / `pollinations` / `gpt-image-1` / `replicate` / `local-sd`), same env vars, same `auto` fallback to free Pollinations when you only have a MiMo key.
+
+```bash
+# free, no key
+python3 mimoskill/scripts/generate_image.py \
+    --prompt "isometric cyberpunk city at dusk" --out /tmp/out.png
+
+# with a style preset
+python3 mimoskill/scripts/generate_image.py --style pixel-art \
+    --prompt "a brave knight" --out /tmp/knight.png
+
+# multiple variants -> /tmp/img-1.png /tmp/img-2.png /tmp/img-3.png /tmp/img-4.png
+python3 mimoskill/scripts/generate_image.py --n 4 \
+    --prompt "watercolor desert sunrise" --out /tmp/img.png
+
+# best quality (needs PET_OPENAI_API_KEY — same env var as the pet flow)
+export PET_OPENAI_API_KEY=sk-real-openai-key
+python3 mimoskill/scripts/generate_image.py --provider gpt-image-1 \
+    --prompt "..." --out /tmp/out.png
+```
+
+`--style` choices: `plain` (default, no prefix), `pixel-art`, `photo`, `3d-render`, `line-art`, `watercolor`, `sticker`. `plain` sends your prompt verbatim — pick that when the user gave a fully-specified prompt.
+
+For **Codex `/hatch` pets** keep using `generate_pet.py` + `install_pet.sh` — that flow is unchanged and tuned for the chibi sprite + 3-state bundle Codex wants.
+
 ## Generating a Codex pet (the `/hatch` alternative)
 
 **Why this needs special handling**: Codex's built-in `/hatch` pet generation requires OpenAI's image generation API (`gpt-image-1`). MiMo doesn't have an image generation endpoint, and mimo2codex can't fake one. So `/hatch` from inside Codex won't work when Codex is pointed at MiMo.

package/mimoskill/references/ocr_workflow.md

@@ -0,0 +1,240 @@
+# OCR / image recognition workflow
+
+`mimoskill/scripts/ocr.py` is the fallback path for reading or describing
+images when the surrounding chat model can't see them. Two engines:
+
+| Engine | Needs API key? | Quality | Notes |
+|---|---|---|---|
+| `mimo` | yes (`MIMO_API_KEY`) | best | Calls `mimo-v2.5` regardless of the chat model used elsewhere. |
+| `pollinations` | **no** | decent | Free public endpoint at `text.pollinations.ai`. Rate-limited but no signup. |
+
+`--engine auto` (default) picks `mimo` if `MIMO_API_KEY` is set, else falls
+back to `pollinations` so users with only a DeepSeek key (or no key at all)
+still get OCR.
+
+## TL;DR
+
+```bash
+# Zero-setup — uses free pollinations fallback when MIMO_API_KEY is unset
+python3 mimoskill/scripts/ocr.py path/to/image.png
+python3 mimoskill/scripts/ocr.py --mode describe path/to/image.png
+python3 mimoskill/scripts/ocr.py --mode structured a.png b.jpg
+python3 mimoskill/scripts/ocr.py --mode markdown form.png
+
+# Force the free engine even when you have a MiMo key (e.g. to save quota)
+python3 mimoskill/scripts/ocr.py --engine pollinations form.png
+
+# Best quality — set MiMo key
+export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
+python3 mimoskill/scripts/ocr.py path/to/image.png   # auto -> mimo
+```
+
+## Why this skill exists
+
+The proxy strips image attachments when the active chat model can't accept
+them (`src/translate/reqToChat.ts:48-72`). Non-vision MiMo variants —
+`mimo-v2.5-pro`, `mimo-v2.5-pro[1m]`, `mimo-v2-flash` — return 404
+"No endpoints found that support image input" if images are forwarded.
+The proxy drops the images and leaves an `[N image attachment(s) omitted: …]`
+placeholder so the conversation doesn't crash.
+
+`ocr.py` is the recommended way to recover that content **without changing
+the chat model**: it independently calls `mimo-v2.5`, returns text, and the
+caller pipes that text back into the conversation as a normal user message.
+
+## Input modes
+
+The positional `IMAGE` args (0 or more) accept:
+
+| Form | Example | What ocr.py does |
+|---|---|---|
+| Local path | `./scan.png`, `C:\foo.jpg` | reads bytes, magic-byte sniffs MIME, base64-encodes to a `data:` URL |
+| `http(s)://` URL | `https://example.com/x.png` | forwarded as-is; MiMo fetches server-side |
+| `data:` URL | `data:image/png;base64,…` | forwarded as-is |
+| `-` (single dash) | piped from stdin | reads one image's bytes from stdin |
+| nothing + non-TTY stdin | `cat x.png \| ocr.py` | same as `-` |
+
+Magic-byte table (file extension is **not** trusted):
+
+| Bytes | MIME |
+|---|---|
+| `89 50 4E 47 0D 0A 1A 0A` | `image/png` |
+| `FF D8 FF` | `image/jpeg` |
+| `47 49 46 38 37 61` / `…39 61` | `image/gif` |
+| `52 49 46 46 …. 57 45 42 50` | `image/webp` |
+| `42 4D` | `image/bmp` |
+| (anything else) | falls back to `image/png` |
+
+## Output modes (`--mode`)
+
+### `text` (default) — verbatim OCR
+
+```bash
+python3 mimoskill/scripts/ocr.py invoice.png
+```
+
+Stdout is the raw extracted text. Line breaks, reading order, and rough
+column/table layout (whitespace + pipes) are preserved. No commentary, no
+translation, no summary. Unreadable spans become `[unreadable]`. Image with
+no text returns the single line `[no text detected]`.
+
+### `describe` — short prose description
+
+```bash
+python3 mimoskill/scripts/ocr.py --mode describe screenshot.png
+```
+
+2-4 sentences covering layout, key elements, visible text (quoted), and
+notable colors. No invented details.
+
+### `structured` — JSON
+
+```bash
+python3 mimoskill/scripts/ocr.py --mode structured form.png
+```
+
+Stdout is a single JSON object:
+
+```json
+{
+  "text": "...",
+  "language": "zh-Hans",
+  "regions": [
+    {"label": "title", "text": "增值税电子发票", "role": "title"},
+    {"label": "buyer", "text": "...", "role": "paragraph"},
+    {"label": "items", "text": "...", "role": "table"}
+  ],
+  "summary": "A Chinese VAT e-invoice with buyer/seller and four line items."
+}
+```
+
+`regions[].role` is one of `title`, `paragraph`, `list`, `table`, `caption`,
+`ui`, `handwriting`, `other`.
+
+**Note**: `structured` returns **logical regions** (role classification),
+not pixel bounding boxes. MiMo does not currently expose grounded pixel
+coordinates the way some other vision models do; this skill won't pretend
+to. If you need pixel boxes, use a model that does (e.g. Gemini grounding,
+Tesseract with `--psm 6` + position data).
+
+### `markdown` — re-render as GFM
+
+```bash
+python3 mimoskill/scripts/ocr.py --mode markdown spec.png
+```
+
+Headings become `#`/`##`, tables become pipe tables, code-like text becomes
+fenced blocks, lists become `-`. Reading order preserved. Output is the
+Markdown body only — no preamble, no outer fence.
+
+## Batch (multi-image) calls
+
+Pass multiple positional args:
+
+```bash
+python3 mimoskill/scripts/ocr.py page1.png page2.png page3.png
+```
+
+All images go to MiMo in a **single** chat completion (one billable call).
+The model can cross-reference (e.g. ID front + back). Output is a single
+text body in reading order across the images.
+
+When you need a different prompt per image, run `ocr.py` N times instead.
+
+## `--lang` and `--prompt`
+
+- `--lang LANG` appends `Primary language: <LANG>.` to the prompt. Useful
+  for CJK to prevent the model from outputting Pinyin transliteration:
+  `ocr.py --lang Chinese scan.png` or `--lang zh` or `--lang 日本語`.
+
+- `--prompt EXTRA` appends a free-text instruction:
+  `ocr.py --mode text --prompt "Only handwriting, ignore printed text." form.png`
+
+## Model selection
+
+| You pass | ocr.py uses |
+|---|---|
+| nothing | `$MIMO_OCR_MODEL` → `$MIMO_MODEL` (if vision-capable) → `mimo-v2.5` |
+| `--model mimo-v2.5` | `mimo-v2.5` |
+| `--model mimo-v2.5[1m]` | `mimo-v2.5[1m]` |
+| `--model mimo-v2-omni` | `mimo-v2-omni` |
+| `--model mimo-v2.5-pro` | **switches to `mimo-v2.5`** (stderr note) |
+| `--model mimo-v2.5-pro[1m]` | **switches to `mimo-v2.5`** |
+| `--model mimo-v2-flash` | **switches to `mimo-v2.5`** |
+
+Non-vision models would return 404 from MiMo, so the script coerces them
+silently (one stderr line) rather than failing.
+
+## When `MIMO_API_KEY` isn't set
+
+`--engine auto` (the default) silently falls back to `pollinations`:
+
+```
+[engine] auto -> pollinations (free, no key). Set MIMO_API_KEY for higher quality (mimo-v2.5).
+[ocr] engine=pollinations mode=text model=openai images=1
+<extracted text>
+```
+
+Exit code `3` is only raised when the user explicitly passes `--engine mimo`
+without a key (passing the flag is treated as an assertion that MiMo should
+be used; auto-falling-back would mask the misconfiguration).
+
+If you'd rather use **fully-local OCR** with no network at all, install
+tesseract and shell to it directly — this skill won't auto-invoke it:
+
+```bash
+macOS:    brew install tesseract tesseract-lang
+Ubuntu:   sudo apt install tesseract-ocr tesseract-ocr-chi-sim
+Windows:  https://github.com/UB-Mannheim/tesseract/wiki
+tesseract <image> - -l eng+chi_sim
+```
+
+## Pollinations specifics
+
+- Endpoint: `https://text.pollinations.ai/openai` (OpenAI Chat Completions
+  compatible).
+- Default model: `openai` (vision-capable). Override with
+  `--pollinations-model <name>` or `POLLINATIONS_MODEL=<name>`. Other
+  vision-capable picks include `openai-large`, `openai-fast`.
+- No `Authorization` header is sent; the service is open. Rate limits apply
+  per-IP; if you hit them you'll see HTTP 429 in stderr — wait or retry.
+- `reasoning_content` is normally empty for pollinations responses (the
+  underlying models don't expose chain-of-thought).
+
+## Common pitfalls
+
+- **PDFs are not supported directly.** Rasterize first with one of:
+  - `pdftoppm -png input.pdf out` (Poppler)
+  - `mutool draw -o out-%d.png input.pdf` (MuPDF)
+  - macOS: `sips -s format png input.pdf --out out.png`
+- **Multi-image batches share one prompt.** If you need different modes /
+  languages per image, invoke `ocr.py` once per image.
+- **`structured` mode is logical regions, not pixel boxes.** See above.
+- **`--stream` + `structured`**: the streamed body is still a single JSON
+  object; buffer it before parsing.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Upstream HTTP error (MiMo or Pollinations; error body printed to stderr) |
+| 2 | argv / usage error (no image, mutually exclusive flags, etc.) |
+| 3 | `--engine mimo` explicitly requested but `MIMO_API_KEY` not set |
+| 4 | Local image file not found / unreadable |
+
+## Composing with `mimo_chat.py`
+
+OCR + downstream LLM call is a common pattern:
+
+```bash
+TEXT=$(python3 mimoskill/scripts/ocr.py invoice.png)
+python3 mimoskill/scripts/mimo_chat.py "Summarize this invoice:\n$TEXT"
+```
+
+Or structured + parse:
+
+```bash
+JSON=$(python3 mimoskill/scripts/ocr.py --mode structured invoice.png)
+echo "$JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['summary'])"
+```

package/mimoskill/scripts/generate_image.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+generate_image.py — general (non-pet) image generation.
+
+Thin wrapper over generate_pet.py: same providers (auto / pollinations /
+gpt-image-1 / replicate / local-sd), no chibi-pet prompt boilerplate,
+plus an optional --style for common looks.
+
+For Codex /hatch pets, keep using generate_pet.py — it has pet-tuned prompt
+prefixes and the --bundle (idle/working/done) state machine.
+
+Usage:
+    # free, no key
+    python3 generate_image.py --prompt "isometric cyberpunk city at dusk" --out out.png
+
+    # styled
+    python3 generate_image.py --style pixel-art --prompt "a brave knight" --out k.png
+
+    # best quality (needs PET_OPENAI_API_KEY — same env var as the pet flow)
+    python3 generate_image.py --provider gpt-image-1 --prompt "..." --out out.png
+
+    # multiple variants
+    python3 generate_image.py --n 4 --prompt "..." --out img.png
+    # produces img-1.png, img-2.png, img-3.png, img-4.png
+
+Only depends on the standard library.
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+
+# Load generate_pet.py as a module by absolute path (not `import generate_pet`)
+# — the skill is invoked from arbitrary cwd, and we don't ship an __init__.py.
+_HERE = Path(__file__).resolve().parent
+_GP_PATH = _HERE / "generate_pet.py"
+_spec = importlib.util.spec_from_file_location("_generate_pet", _GP_PATH)
+if _spec is None or _spec.loader is None:
+    sys.stderr.write(f"error: cannot load {_GP_PATH}\n")
+    sys.exit(2)
+_gp = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_gp)
+
+
+# --- style presets ----------------------------------------------------------
+
+STYLES: dict[str, tuple[str, str]] = {
+    "plain": ("", ""),
+    "pixel-art": (
+        "Retro 16-bit pixel art sprite of ",
+        ", transparent background, single sprite, nearest-neighbor",
+    ),
+    "photo": (
+        "Photorealistic photograph of ",
+        ", natural lighting, sharp focus, shallow depth of field",
+    ),
+    "3d-render": (
+        "Cute 3D render of ",
+        ", soft global illumination, octane render",
+    ),
+    "line-art": (
+        "Black ink line art of ",
+        ", clean linework, white background, no shading",
+    ),
+    "watercolor": (
+        "Hand-drawn ink and watercolor of ",
+        ", loose linework, watercolor wash",
+    ),
+    "sticker": (
+        "Chibi sticker mascot of ",
+        ", transparent background, soft cel-shading, single character",
+    ),
+}
+
+
+def apply_style(prompt: str, style: str) -> str:
+    prefix, suffix = STYLES[style]
+    if not prefix and not suffix:
+        return prompt
+    body = prompt.strip().rstrip(".,;")
+    return f"{prefix}{body}{suffix}"
+
+
+# --- main -------------------------------------------------------------------
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description=__doc__.split("\n", 1)[0],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--prompt", required=True, help="what to draw (used verbatim by default)")
+    p.add_argument(
+        "--style",
+        choices=list(STYLES),
+        default="plain",
+        help="optional prompt preset (default: plain — no prefix/suffix)",
+    )
+    p.add_argument(
+        "--provider",
+        choices=["auto"] + list(_gp.PROVIDERS),
+        default="auto",
+        help="image gen backend (same as generate_pet.py)",
+    )
+    p.add_argument("--reference", type=Path, help="reference image (gpt-image-1 only)")
+    p.add_argument("--quality", default="medium", choices=["low", "medium", "high", "hd"])
+    p.add_argument("--out", type=Path, required=True, help="output path (PNG)")
+    p.add_argument("--n", type=int, default=1, help="number of variants to generate")
+    p.add_argument("--size", default=None, help="forwarded where supported (e.g. 1024x1024)")
+    p.add_argument("--seed", type=int, default=None, help="forwarded where supported")
+    args = p.parse_args()
+
+    if args.n < 1:
+        sys.stderr.write("error: --n must be >= 1\n")
+        sys.exit(2)
+
+    # Resolve auto provider with the same status line generate_pet.py emits.
+    if args.provider == "auto":
+        chosen = _gp.resolve_auto_provider()
+        if chosen == "pollinations":
+            sys.stderr.write(
+                "[provider] auto -> pollinations (free, no key required).\n"
+                "           For higher quality, set PET_OPENAI_API_KEY (real OpenAI key)\n"
+                "           and rerun, or pass --provider replicate / local-sd.\n\n"
+            )
+        else:
+            sys.stderr.write(f"[provider] auto -> {chosen}\n\n")
+        args.provider = chosen
+
+    final_prompt = apply_style(args.prompt, args.style)
+    sys.stderr.write(f"prompt: {final_prompt}\n")
+
+    # --size / --seed: emit a note where the underlying provider doesn't
+    # plumb them through. v1 forwards nothing (generate_pet.py hard-codes
+    # 1024x1024 / no seed); future versions can extend per-provider.
+    if args.size and args.size != "1024x1024":
+        sys.stderr.write(
+            f"note: --size {args.size} ignored in v1 (providers run at 1024x1024).\n"
+        )
+    if args.seed is not None:
+        sys.stderr.write(
+            "note: --seed ignored in v1 (not plumbed through to providers yet).\n"
+        )
+
+    def out_path_for(i: int) -> Path:
+        if args.n == 1:
+            return args.out
+        stem = args.out.stem
+        suffix = args.out.suffix or ".png"
+        return args.out.parent / f"{stem}-{i + 1}{suffix}"
+
+    for i in range(args.n):
+        out = out_path_for(i)
+        sys.stderr.write(f"generating ({i + 1}/{args.n}) -> {out}\n")
+        _gp.generate_one(args.provider, final_prompt, args.reference, args.quality, out)
+
+    sys.stderr.write(f"\n[ok] wrote {args.n} image(s)\n")
+
+
+if __name__ == "__main__":
+    main()