Feat vision provider routing codex validation (#1)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

* **New Features**
* Added support for multiple metadata analysis providers: Claude, Codex,
and HTTP-based Vision APIs
* Introduced `--analysis-context` and `--analysis-context-file` options
for enriching image metadata analysis with custom guidance
* Implemented scene-aware analysis that intelligently processes UI and
illustration content

* **Improvements**
* Enhanced metadata validation with detailed diagnostic feedback for
recognition failures
* Added retry logic for recoverable validation issues to improve success
rates
  * Improved error messages with context-specific guidance

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Hagicode <noreply@hagicode.com>

Author: newbe36524

.env.example

@@ -4,16 +4,36 @@ IMGBIN_IMAGE_API_KEY=
 IMGBIN_IMAGE_API_MODEL=
 IMGBIN_IMAGE_API_TIMEOUT_MS=60000
 
-# Local Claude CLI metadata analysis.
+# Metadata analysis provider routing.
+# Supported values: claude, codex, http
+IMGBIN_ANALYSIS_PROVIDER=claude
+IMGBIN_ANALYSIS_TIMEOUT_MS=60000
+# Optional override for the bundled prompt file in prompts/default-analysis-prompt.txt
+IMGBIN_ANALYSIS_PROMPT_PATH=
+
+# Claude analysis provider.
 # Optional if `claude` is already available in PATH.
 IMGBIN_ANALYSIS_CLI_PATH=claude
+IMGBIN_CLAUDE_CLI_PATH=claude
 # Preferred: ImgBin-specific model override.
 IMGBIN_ANALYSIS_API_MODEL=
+IMGBIN_CLAUDE_MODEL=
 # Fallback: shared Claude/Anthropic model setting.
 ANTHROPIC_MODEL=
-IMGBIN_ANALYSIS_TIMEOUT_MS=60000
-# Optional override for the bundled prompt file in prompts/default-analysis-prompt.txt
-IMGBIN_ANALYSIS_PROMPT_PATH=
+IMGBIN_CLAUDE_TIMEOUT_MS=60000
+
+# Codex analysis provider.
+IMGBIN_CODEX_CLI_PATH=codex
+IMGBIN_CODEX_MODEL=
+IMGBIN_CODEX_TIMEOUT_MS=60000
+IMGBIN_CODEX_BASE_URL=
+IMGBIN_CODEX_API_KEY=
+
+# HTTP analysis provider.
+IMGBIN_VISION_API_URL=
+IMGBIN_VISION_API_KEY=
+IMGBIN_VISION_API_MODEL=
+IMGBIN_VISION_API_TIMEOUT_MS=60000
 
 IMGBIN_DEFAULT_OUTPUT_DIR=./library
 IMGBIN_THUMBNAIL_SIZE=512

README.md

@@ -1,12 +1,12 @@
 # ImgBin
 
-ImgBin is a TypeScript CLI for generating image assets, importing existing images into a managed library, writing searchable metadata, searching managed libraries, creating thumbnails, and running local Claude CLI image metadata analysis.
+ImgBin is a TypeScript CLI for generating image assets, importing existing images into a managed library, writing searchable metadata, searching managed libraries, creating thumbnails, and running provider-routed multimodal image metadata analysis.
 
 ## Requirements
 
 - Node.js 20+
 - Access to an image generation HTTP API for `generate`
-- A local `claude` CLI installation for `annotate` / `--annotate`
+- One configured analysis backend for `annotate` / `--annotate`: `claude`, `codex`, or a compatible HTTP vision API
 
 ## Installation
 
@@ -95,8 +95,8 @@ ImgBin now matches the Azure image-generation request format that was previously
 That means the current recommended setup is:
 
 1. configure Azure image generation for output,
-2. configure a local metadata-analysis model for the Claude-compatible CLI step, and
-3. run `imgbin generate` directly or call it through the site wrapper.
+2. configure a non-interactive multimodal analysis provider (`claude`, `codex`, or `http`), and
+3. run `imgbin generate` directly or call it through the site wrapper or CI automation.
 
 ### Minimal `.env` example
 
@@ -111,20 +111,41 @@ IMGBIN_IMAGE_API_KEY="<azure-api-key>"
 # AZURE_ENDPOINT="https://<resource>.openai.azure.com/openai/deployments/<deployment>/images/generations?api-version=<version>"
 # AZURE_API_KEY="<azure-api-key>"
 
-# Metadata analysis model for the local Claude-compatible CLI
-IMGBIN_ANALYSIS_API_MODEL="glm-5"
+# Select one metadata analysis backend
+IMGBIN_ANALYSIS_PROVIDER="codex"
+
+# Codex multimodal analysis
+IMGBIN_CODEX_CLI_PATH="codex"
+IMGBIN_CODEX_MODEL="gpt-5-codex"
+# Optional if Codex is already configured globally
+# IMGBIN_CODEX_BASE_URL="https://api.openai.com/v1"
+# IMGBIN_CODEX_API_KEY="<codex-api-key>"
+
+# Claude-compatible analysis remains available
+# IMGBIN_ANALYSIS_PROVIDER="claude"
+# IMGBIN_ANALYSIS_CLI_PATH="claude"
+# IMGBIN_ANALYSIS_API_MODEL="glm-5"
+# ANTHROPIC_MODEL="glm-5"
+
+# Or route analysis through a compatible HTTP vision endpoint
+# IMGBIN_ANALYSIS_PROVIDER="http"
+# IMGBIN_VISION_API_URL="https://example.com/vision"
+# IMGBIN_VISION_API_KEY="<vision-api-key>"
+# IMGBIN_VISION_API_MODEL="vision-model"
 
 # Optional runtime tuning
 IMGBIN_DEFAULT_OUTPUT_DIR="./library"
 IMGBIN_IMAGE_API_TIMEOUT_MS="60000"
+IMGBIN_ANALYSIS_TIMEOUT_MS="60000"
 ```
 
 Notes:
 
 - `IMGBIN_IMAGE_API_URL` / `IMGBIN_IMAGE_API_KEY` are the preferred names.
 - `AZURE_ENDPOINT` / `AZURE_API_KEY` are accepted as compatibility fallbacks.
 - GPT Image is used only for image generation.
-- Metadata still comes from the local Claude-compatible analysis step.
+- `IMGBIN_ANALYSIS_PROVIDER` defaults to `claude` for backward compatibility when omitted.
+- All three analysis backends share the same scene-aware prompt builder, validation rules, and metadata provenance fields.
 
 ## Environment Variables
 
@@ -137,18 +158,40 @@ Notes:
 - `AZURE_ENDPOINT`: compatibility fallback for `IMGBIN_IMAGE_API_URL`
 - `AZURE_API_KEY`: compatibility fallback for `IMGBIN_IMAGE_API_KEY`
 
-### Local Claude CLI analysis
+### Multimodal analysis routing
+
+- `IMGBIN_ANALYSIS_PROVIDER`: selects `claude`, `codex`, or `http`; defaults to `claude`
+- `IMGBIN_ANALYSIS_PROMPT_PATH`: optional override for the bundled default prompt file
+- `IMGBIN_ANALYSIS_TIMEOUT_MS`: shared timeout fallback for analysis providers, defaults to `60000`
+
+### Claude CLI analysis
 
 - `IMGBIN_ANALYSIS_CLI_PATH`: optional local Claude executable path; defaults to `claude`
+- `IMGBIN_CLAUDE_CLI_PATH`: explicit alias for the Claude executable path
 - `IMGBIN_ANALYSIS_API_MODEL`: preferred model identifier for ImgBin's local Claude analysis
+- `IMGBIN_CLAUDE_MODEL`: explicit alias for the Claude model identifier
 - `ANTHROPIC_MODEL`: fallback shared Claude model identifier used when `IMGBIN_ANALYSIS_API_MODEL` is not set
-- `IMGBIN_ANALYSIS_TIMEOUT_MS`: optional timeout override for the local Claude process, defaults to `60000`
-- `IMGBIN_ANALYSIS_PROMPT_PATH`: optional override for the bundled default prompt file
+- `IMGBIN_CLAUDE_TIMEOUT_MS`: optional timeout override for the local Claude process
 
 If `IMGBIN_ANALYSIS_PROMPT_PATH` is not set, ImgBin falls back to `prompts/default-analysis-prompt.txt`.
 If `IMGBIN_ANALYSIS_API_MODEL` is empty, ImgBin falls back to `ANTHROPIC_MODEL`.
 
-ImgBin also adds a runtime filename-guidance block to every Claude analysis request. Imported assets prefer the original source filename, generated assets fall back to the managed slug, and placeholder names such as `original.png` or `asset` are ignored. The filename is treated as a soft scene hint only; visible image evidence still wins when they disagree.
+### Codex CLI analysis
+
+- `IMGBIN_CODEX_CLI_PATH`: optional Codex executable path; defaults to `codex`
+- `IMGBIN_CODEX_MODEL`: optional Codex model identifier
+- `IMGBIN_CODEX_TIMEOUT_MS`: optional timeout override for the Codex process
+- `IMGBIN_CODEX_BASE_URL`: optional base URL override forwarded as `OPENAI_BASE_URL`
+- `IMGBIN_CODEX_API_KEY`: optional API key override forwarded as `CODEX_API_KEY`
+
+### HTTP vision analysis
+
+- `IMGBIN_VISION_API_URL`: required when `IMGBIN_ANALYSIS_PROVIDER=http`
+- `IMGBIN_VISION_API_KEY`: optional bearer token for the HTTP vision API
+- `IMGBIN_VISION_API_MODEL`: optional model identifier stored in metadata
+- `IMGBIN_VISION_API_TIMEOUT_MS`: optional timeout override for the HTTP vision API
+
+ImgBin appends runtime scene profiles and filename guidance to every CLI-based analysis request. Imported assets prefer the original source filename, generated assets fall back to the managed slug, and placeholder names such as `original.png` or `asset` are ignored. The filename remains a soft hint only; visible image evidence still wins when they disagree.
 
 ### General runtime
 
@@ -159,21 +202,23 @@ ImgBin also adds a runtime filename-guidance block to every Claude analysis requ
 
 ## Unified workflows
 
-### Generate one image with Azure + metadata analysis
+### Generate one image with Azure + multimodal metadata analysis
 
 ```bash
 imgbin generate \
   --prompt "A cheerful hand-drawn hero illustration of an AI coding assistant helping a developer at a desk." \
   --output ./library \
+  --analysis-context "This is a documentation hero illustration with a desk scene and AI assistant visual motif." \
   --annotate
 ```
 
 What happens:
 
 1. ImgBin sends an Azure-style image request,
 2. writes the generated file into a managed asset directory,
-3. runs the local Claude-compatible metadata analysis step, and
-4. stores structured metadata in `metadata.json`.
+3. routes multimodal analysis through the configured provider,
+4. validates the returned JSON before accepting it, and
+5. stores structured metadata plus provider provenance in `metadata.json`.
 
 ### Generate from raw prompt text
 
@@ -183,6 +228,7 @@ imgbin generate \
   --output ./library \
   --tag dashboard \
   --tag hero \
+  --analysis-context "This is a docs hero image that mixes product-dashboard cues with illustration styling." \
   --annotate \
   --thumbnail
 ```
@@ -193,6 +239,7 @@ imgbin generate \
 imgbin generate \
   --prompt-file ../docs/src/content/docs/img/product-overview/value-proposition-ai-assisted-coding/prompt.json \
   --output ./library \
+  --analysis-context "This prompt file generates a documentation hero asset with interface-inspired card layout." \
   --annotate
 ```
 
@@ -203,32 +250,60 @@ ImgBin reads the docs prompt file, extracts `userPrompt`, carries over generatio
 If image generation already succeeded and you only want to refresh title/tags/description:
 
 ```bash
-imgbin annotate ./library/2026-03/orange-dashboard-hero --overwrite
+imgbin annotate ./library/2026-03/orange-dashboard-hero \
+  --analysis-context "This is a product dashboard screenshot used in docs." \
+  --overwrite
 ```
 
-This is useful after changing `IMGBIN_ANALYSIS_API_MODEL` or updating the analysis prompt.
+This is useful after changing the configured analysis provider, model, or prompt.
 
 ### Filename-guided analysis
 
-ImgBin now enriches Claude metadata analysis with a lightweight filename hint:
+ImgBin now enriches multimodal metadata analysis with a lightweight filename hint:
 
 - imported assets prefer the source filename from `source.originalPath`,
 - generated assets fall back to the managed asset slug or directory name, and
 - placeholder names such as `original.jpg` or `asset` are skipped automatically.
 
 This guidance is appended at runtime, so it applies to both the bundled default prompt and any `--analysis-prompt` override. Treat it as a soft hint: if the filename conflicts with the image itself, the visible image content should take precedence.
 
+### Non-interactive provider examples
+
+Codex in CI:
+
+```bash
+IMGBIN_ANALYSIS_PROVIDER=codex \
+IMGBIN_CODEX_CLI_PATH=codex \
+IMGBIN_CODEX_MODEL=gpt-5-codex \
+imgbin annotate ./library/2026-03/orange-dashboard-hero \
+  --analysis-context "This is a product dashboard screenshot used in CI validation." \
+  --overwrite
+```
+
+HTTP provider in automation:
+
+```bash
+IMGBIN_ANALYSIS_PROVIDER=http \
+IMGBIN_VISION_API_URL=https://example.com/vision \
+IMGBIN_VISION_API_KEY=token \
+imgbin annotate ./library/2026-03/orange-dashboard-hero \
+  --analysis-context "This is a product dashboard screenshot used in automation." \
+  --overwrite
+```
+
 ### Annotate an existing managed asset
 
 ```bash
-imgbin annotate ./library/2026-03/orange-dashboard-hero
+imgbin annotate ./library/2026-03/orange-dashboard-hero \
+  --analysis-context "This is a product dashboard screenshot with KPI cards and navigation."
 ```
 
 ### Import a standalone image into the library, then analyze it
 
 ```bash
 imgbin annotate ./incoming/launch-hero.png \
   --import-to ./library \
+  --analysis-context "This is a launch hero visual combining marketing illustration and interface framing." \
   --tag imported \
   --thumbnail
 ```
@@ -240,9 +315,30 @@ This copies the source image into a new managed asset directory before writing `
 ```bash
 imgbin annotate ./library/2026-03/orange-dashboard-hero \
   --analysis-prompt ./prompts/custom-analysis-prompt.txt \
+  --analysis-context "This is a product dashboard screenshot used for launch documentation." \
+  --overwrite
+```
+
+### Add custom analysis context for tricky screenshots
+
+Image recognition now requires analysis context. Pass a short project-aware hint so ImgBin can classify tricky screenshots more accurately while still prioritizing visible image evidence.
+
+```bash
+imgbin annotate ./library/2026-03/adventure-squad \
+  --analysis-context "这是冒险团副本管理页面，重点识别副本配置、队伍编成、已分配英雄和右侧编辑器面板。" \
+  --overwrite
+```
+
+You can also store that context in a file:
+
+```bash
+imgbin annotate ./library/2026-03/adventure-squad \
+  --analysis-context-file ./prompts/adventure-squad-context.txt \
   --overwrite
 ```
 
+`annotate`, `generate --annotate`, and any batch job that performs recognition must provide either `--analysis-context` or `--analysis-context-file` (or the manifest equivalents `analysisContext` / `analysisContextFile`).
+
 ### Generate or refresh a thumbnail
 
 ```bash
@@ -295,10 +391,14 @@ ImgBin stores the reusable search index at `.imgbin/search-index.json` under the
 imgbin batch --manifest ./jobs/launch.yaml --output ./library
 ```
 
+Every manifest job that performs recognition must include `analysisContext` or `analysisContextFile`.
+
 ### Batch-process assets whose analysis is still pending or failed
 
 ```bash
-imgbin batch --pending-library ./library
+imgbin batch \
+  --pending-library ./library \
+  --analysis-context-file ./prompts/pending-library-context.txt
 ```
 
 ## Batch manifest examples
@@ -309,18 +409,22 @@ jobs:
     slug: docs-ai-assisted-coding
     tags: [docs, hero]
     annotate: true
+    analysisContext: This is a product hero illustration used in documentation.
     thumbnail: true
 
   - assetPath: ./incoming/marketing-card.png
     importTo: ./library
+    analysisContext: This is a marketing image with product-card framing and interface accents.
     tags: [marketing, imported]
     thumbnail: true
 
   - assetPath: ./library/2026-03/existing-card
     overwriteRecognition: true
     analysisPromptPath: ./prompts/custom-analysis-prompt.txt
+    analysisContextFile: ./prompts/existing-card-context.txt
 
   - pendingLibrary: ./library
+    analysisContextFile: ./prompts/pending-library-context.txt
 ```
 
 ## Metadata model
@@ -329,7 +433,7 @@ Each asset directory stores a `metadata.json` file with these high-level section
 
 - `source`: whether the asset was generated by ImgBin or imported from an external file
 - `generated`: prompt text, provider context, docs prompt provenance, and generation params
-- `recognized`: local Claude analysis suggestions plus prompt provenance
+- `recognized`: multimodal analysis suggestions, provider provenance, validator diagnostics, retry history, and optional custom context provenance
 - `manual`: human-maintained title, tags, or description that take precedence by default
 - `status`: per-step status for generation, recognition, and thumbnail creation
 - `paths`: relative file paths for original and thumbnail assets
@@ -344,14 +448,14 @@ The actual generated image is stored as the asset file on disk, while metadata k
 
 ## Notes on analysis behavior
 
-ImgBin does not call a remote Claude URL for metadata analysis. Instead, it:
+ImgBin routes metadata analysis through the configured provider. For CLI-based providers, it:
 
 1. loads the bundled or overridden analysis prompt,
-2. passes the selected model to the local `claude` CLI,
-3. asks Claude to inspect the local image file directly from disk, and
-4. parses the returned JSON into metadata fields.
+2. appends scene-aware guidance and filename hints at runtime,
+3. asks the selected provider to inspect the local image directly (`claude` by path, `codex` by `--image`, or HTTP by base64 payload), and
+4. validates the returned JSON before merging it into metadata.
 
-That means the only required Claude-side runtime setting is a usable model name plus a working local `claude` command.
+That means non-interactive runs only need a deterministic provider selection plus the corresponding CLI/API configuration.
 
 ## Notes on image provider requests
 

prompts/default-analysis-prompt.txt

@@ -1,4 +1,4 @@
-You are a Claude-compatible image metadata analyst.
+You are a multimodal image metadata analyst.
 Analyze the provided image and return strict JSON with this shape:
 {
   "title": "short human-friendly title",
@@ -11,5 +11,9 @@ Rules:
 - Use 2 to 8 lowercase kebab-case tags.
 - Keep the title under 80 characters.
 - Keep the description under 200 characters.
-- Filenames may be provided as auxiliary scene clues, but visible image evidence always takes precedence.
+- Ground every claim in visible image evidence first. Filenames, paths, slugs, prompts, and scene hints are only auxiliary clues.
+- If visible image evidence conflicts with filenames or prompt hints, trust the image.
+- For UI, admin dashboards, wireframes, product screenshots, game editors, and other interface-heavy images, prioritize layout, panels, controls, charts, forms, menus, and page purpose.
+- Do not hallucinate specific characters, skins, franchises, or IP names for UI-first screenshots unless that text or branding is directly visible in the image itself.
+- For mixed illustration plus interface scenes, preserve both semantics in the title, tags, and description.
 - Do not include markdown fences or extra commentary.