feat(ai): ImageRef abstraction for image_request() builder #128

New issue

Closed

opened 2026-04-16 13:44:06 +00:00 by casper-stevens · 0 comments

casper-stevens commented

2026-04-16 13:44:06 +00:00

Member

Context

The image_request() builder accepts raw bytes only. Callers that have image URLs or local file paths must do their own fetching, MIME detection, and resizing before calling the builder. Centralising this in herolib_ai keeps callers — specifically hero_slides_lib — free of reqwest and image deps. See ADR-0001 for the representation decision.

Goals

Add ImageRef enum (Url(String), Path(PathBuf), Bytes { mime: String, data: Vec<u8> }) to the herolib_ai public API
Add ImageGenerationRequest::add_image_ref(ImageRef) that resolves the ref synchronously (URL fetch via blocking HTTP, path read via fs::read) before attaching to the request
Reuse the existing image_io byte-budget resizer and MIME detector for resolved inputs
No new MSRV bump; no async surface added

Feasibility

Low-to-medium complexity. The image_io module already handles MIME detection, format conversion, and byte-budget resizing — this issue adds a resolution layer on top. URL fetching needs a sync HTTP client; ureq is the natural fit (small, no tokio dep). Path resolution is trivial.

The more significant part is downstream: once add_image_ref(ImageRef::Path) is available, discovery::image_file_to_png_base64() in hero_slides becomes dead code — it duplicates exactly what image_io does (resize + PNG-encode). That function and its base64 output should be removed as part of the hero_slides adoption work (see hero_slides S1 issue). This issue should include clear documentation on what image_io exposes so hero_slides can delete the duplicate without ambiguity.

## Context The `image_request()` builder accepts raw bytes only. Callers that have image URLs or local file paths must do their own fetching, MIME detection, and resizing before calling the builder. Centralising this in `herolib_ai` keeps callers — specifically `hero_slides_lib` — free of `reqwest` and `image` deps. See ADR-0001 for the representation decision. ## Goals - Add `ImageRef` enum (`Url(String)`, `Path(PathBuf)`, `Bytes { mime: String, data: Vec<u8> }`) to the `herolib_ai` public API - Add `ImageGenerationRequest::add_image_ref(ImageRef)` that resolves the ref synchronously (URL fetch via blocking HTTP, path read via `fs::read`) before attaching to the request - Reuse the existing `image_io` byte-budget resizer and MIME detector for resolved inputs - No new MSRV bump; no async surface added ## Feasibility Low-to-medium complexity. The `image_io` module already handles MIME detection, format conversion, and byte-budget resizing — this issue adds a resolution layer on top. URL fetching needs a sync HTTP client; `ureq` is the natural fit (small, no tokio dep). Path resolution is trivial. The more significant part is downstream: once `add_image_ref(ImageRef::Path)` is available, `discovery::image_file_to_png_base64()` in hero_slides becomes dead code — it duplicates exactly what `image_io` does (resize + PNG-encode). That function and its base64 output should be removed as part of the hero_slides adoption work (see hero_slides S1 issue). This issue should include clear documentation on what `image_io` exposes so hero_slides can delete the duplicate without ambiguity.