Unified batch enrichment: single API call per product

[rhoerr]

Summary

• Adds ProductContextBuilder service that builds AI context from visible/searchable product attributes with configurable max-length truncation
• Adds generateBatch() to AiClientInterface/OpenAiClient using OpenAI Structured Outputs (response_format: json_schema) to generate all attribute values in a single API call per product
• Restructures Enricher into three phases (collect → generate → record) with automatic fallback to individual generate() calls if batch fails
• Adds admin config field for Product Context Max Value Length (default: 500) in Advanced Settings

Design

Replaces per-attribute API calls with a single batch call per product, reducing API costs ~80% and improving content consistency across attributes. The batch schema enforces typed responses via OpenAI's json_schema response format with strict: true.

Falls back gracefully: if batch returns empty (parse error, API failure), each attribute is retried individually via the existing generate() method.

Test Plan

• 11 tests for ProductContextBuilder (visible/searchable filtering, truncation, empty/null/array handling)
• 6 tests for OpenAiClient batch helpers (schema building, prompt assembly, JSON parsing)
• 14 tests for restructured Enricher (batch, cache hit/miss, partial cache, fallback, approval, deferred, overwrite)
• Full suite: 146 tests, 316 assertions, 0 failures

Refs: #44

🤖 Generated with Claude Code

[DavidLambauer]

Hey @rhoerr, before I do anything with this I want to surface the tension and save it for our next sync.

The work is real: 31 new tests, a clean collect → generate → record split, and the hybrid fallback is smart. ~80% API cost reduction is a big claim and it's plausible for stores enriching at scale.

What I'm stuck on:

1. Cache key conflict with Add enrichment review, caching, and approval workflow (#28) #46. The enrichment cache keys on SHA-256(parsedPrompt|systemPrompt|attributeCode|storeId). Batch generation produces all attributes from one combined prompt, so when one attribute's input changes (say, the admin tweaks the description prompt), the batch cache miss regenerates every attribute even if the others would have been individual cache hits. On incremental updates, batch mode loses the cache benefits that are the whole point of the review workflow.

2. Per-attribute prompt engineering gets flattened. With the dynamic attribute table from Make enrichment attributes configurable (#27) #45, admins configure different prompts per attribute. Short description and meta title want different tones, lengths, and ideally different temperatures. One batch call with one schema forces them into one shape. The strict json_schema helps with format but not with voice.

3. Rate-limit backoff is hidden in the batch. The current per-call backoff responds to 429s per attribute. In batch mode, a rate-limit error aborts the whole product, falling back to individual calls, which is the worst path for both cost and latency.

4. Fallback can undo the cost savings. If batch fails, we pay for the batch attempt plus N individual calls. On an unstable API day, that spikes costs rather than reduces them.

Not a rejection, just things I want to talk through in our sync. There's probably a version where batch is flag-gated per store (or per attribute group) and the cache accounts for partial hits, which would get us most of the upside without regressing #46's cache design. Let's chat.