feat(openai): simulate image generation endpoint (gpt-image / ChatGPT Images)

[chaliy]

What

Adds a simulated OpenAI image generation endpoint POST /openai/v1/images/generations, replicating the traffic shape of the gpt-image family (the "ChatGPT Images" capability) without running a real model.

Each request returns a synthetic but valid PNG of the exact requested size that renders the request prompt text and a clear "LLMSIM SIMULATED IMAGE" watermark, so generated bytes are unambiguously identifiable as simulated.

Highlights:

• Non-streaming JSON responses and SSE streaming with progressive partial images (image_generation.partial_image → image_generation.completed).
• Self-contained, dependency-free PNG synthesis (src/imagegen.rs): indexed-PNG encoder (CRC32/Adler32/stored-DEFLATE), base64 encoder, and a 5×7 bitmap font for readable, deterministic placeholders.
• Realistic, quality- and size-scaled generation latency, anchored to the configured latency profile (instant/fast collapse the wait for tests/load runs).
• Registers gpt-image-1, gpt-image-1-mini, gpt-image-1.5 model profiles; tracks an image_requests stat.
• New example clients (Python + TypeScript), a new spec, docs, and integration tests. Both examples are wired into CI.

Why

LLMSim simulates the shape of LLM API traffic for testing and development. Image generation is a common production workload (gpt-image / ChatGPT Images) that was not yet covered, so clients had no way to exercise image-generation request/response handling — including the partial-image streaming flow — against the simulator.

How

• src/openai/images.rs: request/response types, streaming event shapes, usage accounting (text input + size/quality-scaled image output tokens), and timing.
• src/imagegen.rs: placeholder image synthesis with a tiny self-contained PNG encoder and bitmap font; a Canvas abstraction draws the gradient background, header (model/size/quality), wrapped prompt, and watermark. Progressive previews are simulated via decreasing pixelation.
• src/image_stream.rs: streaming engine that emits partial frames then a completed frame, evenly spaced across the simulated generation time.
• src/cli/handlers.rs + src/cli/mod.rs: create_image handler and route, sharing the existing error-injection and stats plumbing.
• Model registry + default model list updated; EndpointType::Images and image_requests added to stats.

Risk

• Low. Purely additive — a new endpoint, new modules, and three new model ids. No changes to existing endpoints or behavior. No new third-party dependencies (the PNG/base64/font code is self-contained).
• Uncompressed PNGs make 1024×1024 frames ~1 MB (b64 ~1.4 MB); acceptable for a local simulator and a deliberate trade-off to avoid a compression dependency.

Checklist

• Tests added or updated — 15 unit tests (imagegen, image_stream, openai::images), 5 integration tests (tests/images_test.rs: non-streaming, n>1, defaults, streaming partials, model listing), and smoke-test coverage (tests/smoke_test.sh). Full suite green; cargo fmt --check and cargo clippy -D warnings clean.
• Backward compatibility considered — additive only; existing endpoints and stats fields unchanged.
• Specs updated — new specs/image-generation.md; updated specs/api-endpoints.md, specs/architecture.md, AGENTS.md.
• Docs updated — docs/api.md, README.md, examples/README.md, plus Python/TypeScript example clients.

https://claude.ai/code/session_01NqMz1eKZ5Cf4TUg2V11cB4

---

Generated by Claude Code