gazetta 0.7.0 → 0.8.0

package/dist/alt/factory.js

@@ -0,0 +1,69 @@
+/**
+ * Alt-text adapter factory — the single seam between configuration
+ * (gazetta + site + target manifests) and adapter construction.
+ *
+ * Per Phase 4 of the Path X migration: operator constructs the
+ * `AIProvider` instance via a factory call (`anthropicProvider({...})`)
+ * inside `defineSite({...})` or `defineGazetta({...})`. The resolver
+ * walks the three-rung chain (target → site → gazetta) and the factory
+ * delegates to `provider.altText(taskConfig)` to build the adapter.
+ *
+ * No env-var reads in this module — operators pass `process.env.X!` to
+ * the provider factory at config-eval. No SDK side effects at boot:
+ * provider authors document construction-time semantics; convention is
+ * that providers build SDK config objects at construction and defer
+ * network/auth to first method call.
+ *
+ * Two functions:
+ *
+ *   - `buildAltAdapter(site, target, gazetta?)` — returns a fully-
+ *     constructed `AltTextAdapter`. Returns `nullAltAdapter` when no
+ *     adapter is configured anywhere in the chain.
+ *
+ *   - `isAltAdapterConfigured(site, target, gazetta?)` — pure
+ *     introspection for the capability check exposed via `/api/targets`.
+ *     Doesn't construct an adapter.
+ *
+ * # Why split into two functions
+ *
+ * The factory and the capability check answer different questions:
+ *   - Factory: "give me an adapter to call right now"
+ *   - Capability: "should the UI render AI affordances on this target?"
+ *
+ * The capability check shouldn't allocate SDK clients (every call to
+ * `/api/targets` would). Splitting at this seam is SRP.
+ */
+import { resolveAltConfig } from './config.js';
+import { nullAltAdapter } from './null-adapter.js';
+/**
+ * True when the resolved alt-text config has all required pieces.
+ * Pure: returns the structural state — does NOT verify the credential
+ * works (no network call). Verification surfaces at first use of the route.
+ */
+export function isAltAdapterConfigured(site, target, gazetta) {
+    return resolveAltConfig(site, target, gazetta) !== null;
+}
+/**
+ * Construct the alt-text adapter for the resolved config. Returns the
+ * null adapter when no provider is configured at any layer.
+ *
+ * Always returns an `AltTextAdapter` — consumers never null-check the
+ * factory's return value. The null adapter throws if `generate()` is
+ * called, but that only happens if a consumer skips the
+ * `supports()` / `available()` capability check.
+ */
+export function buildAltAdapter(site, target, gazetta) {
+    const resolved = resolveAltConfig(site, target, gazetta);
+    if (!resolved)
+        return nullAltAdapter;
+    // Build the per-task adapter via the provider's `.altText()` builder.
+    // Provider supplies transport (apiKey, baseUrl, etc.) from its
+    // construction; we supply per-task config (model, systemPrompt,
+    // maxTokens) from the resolver chain.
+    return resolved.provider.altText({
+        model: resolved.model,
+        systemPrompt: resolved.systemPrompt ?? undefined,
+        maxTokens: resolved.maxTokens,
+    });
+}
+//# sourceMappingURL=factory.js.map

package/dist/alt/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/alt/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAIlD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA0C,EAC1C,MAAiD,EACjD,OAAiD;IAEjD,OAAO,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA0C,EAC1C,MAAiD,EACjD,OAAiD;IAEjD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;IACxD,IAAI,CAAC,QAAQ;QAAE,OAAO,cAAc,CAAA;IAEpC,sEAAsE;IACtE,+DAA+D;IAC/D,gEAAgE;IAChE,sCAAsC;IACtC,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;QAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,YAAY,EAAE,QAAQ,CAAC,YAAY,IAAI,SAAS;QAChD,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC,CAAA;AACJ,CAAC"}

package/dist/alt/null-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { AltTextAdapter } from './adapter.js';
+export declare const nullAltAdapter: AltTextAdapter;
+//# sourceMappingURL=null-adapter.d.ts.map

package/dist/alt/null-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-adapter.d.ts","sourceRoot":"","sources":["../../src/alt/null-adapter.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,eAAO,MAAM,cAAc,EAAE,cAU5B,CAAA"}

package/dist/alt/null-adapter.js

@@ -0,0 +1,43 @@
+/**
+ * `nullAltAdapter` — the safe default returned by the factory when no
+ * adapter is configured for a target.
+ *
+ * # Why this exists (vs. the factory returning null)
+ *
+ * The factory `buildAltAdapter(target)` could return `AltTextAdapter |
+ * null`, forcing every consumer to null-check. That would be the
+ * stub-on-the-interface anti-pattern in disguise — every caller
+ * writes `if (adapter) { ... }`, which is dead code in 99% of cases
+ * (the suggester wraps the adapter and handles the unconfigured case
+ * via `available()` returning false).
+ *
+ * Instead, the factory always returns an `AltTextAdapter`. When
+ * unconfigured, it returns this null implementation: `supports()`
+ * always false, `generate()` throws `AIAdapterUnavailableError` if
+ * ever called. The suggester's `available(mime)` checks `supports`
+ * first and returns false — so `generate` is never reached on the
+ * null adapter in practice. The throw is a defense-in-depth signal
+ * that something has gone wrong if it IS reached.
+ *
+ * This is the LSP validation seam: a real adapter, full contract
+ * surface, no nulls in the type system. Tests can substitute it for
+ * any consumer and verify the consumer handles "unavailable" correctly
+ * via `supports`-returns-false rather than via null-checks.
+ *
+ * # SOLID
+ *
+ *   - LSP: full contract; `supports`/`generate` return real values
+ *   - SRP: single concern — represent "no adapter configured"
+ *   - OCP: not relevant (no extension point here)
+ */
+import { AIAdapterUnavailableError } from '../ai/errors.js';
+export const nullAltAdapter = {
+    name: 'null',
+    supports() {
+        return false;
+    },
+    async generate() {
+        throw new AIAdapterUnavailableError('No AI alt-text adapter is configured. Add `altText:` to site.config.ts or set provider credentials in .env.local.');
+    },
+};
+//# sourceMappingURL=null-adapter.js.map

package/dist/alt/null-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-adapter.js","sourceRoot":"","sources":["../../src/alt/null-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAG3D,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,MAAM;IACZ,QAAQ;QACN,OAAO,KAAK,CAAA;IACd,CAAC;IACD,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,yBAAyB,CACjC,mHAAmH,CACpH,CAAA;IACH,CAAC;CACF,CAAA"}

package/dist/alt/ollama.d.ts

@@ -0,0 +1,40 @@
+import type { AIProvider } from '../ai/provider.js';
+import type { AltTextAdapter } from './adapter.js';
+/** Default base URL when running Ollama locally with default settings. */
+export declare const OLLAMA_DEFAULT_BASE_URL = "http://localhost:11434";
+/** Default model. Ollama Library publishes 11B and 90B variants of llama3.2-vision. */
+export declare const OLLAMA_DEFAULT_MODEL = "llama3.2-vision:11b";
+/**
+ * Ollama transport-only options. Per Path X (transport-vs-task split).
+ * Ollama needs no API key; baseUrl is the only transport knob.
+ */
+export interface OllamaTransportOptions {
+    /** Base URL of the Ollama server. Defaults to {@link OLLAMA_DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+}
+/**
+ * Internal type for `createOllamaAltAdapter` callers (tests). Combines
+ * transport with per-task config; new code goes through
+ * `ollamaProvider(transport).altText(taskConfig)`.
+ */
+export interface OllamaAltAdapterOptions extends OllamaTransportOptions {
+    /** Model ID. Defaults to {@link OLLAMA_DEFAULT_MODEL}. */
+    model?: string;
+    /** Operator-supplied system prompt; prepended to system-composed prompt. */
+    systemPrompt?: string;
+    /** Generation token cap. Ollama doesn't expose it directly, but the
+     *  scaffold passes it through to keep the contract uniform. */
+    maxTokens?: number;
+}
+/**
+ * Construct the Ollama alt-text adapter. Internal factory — kept public
+ * for tests + advanced wiring. Operator-facing config goes through
+ * `ollamaProvider(transport).altText(taskConfig)` (Path X).
+ */
+export declare function createOllamaAltAdapter(opts?: OllamaAltAdapterOptions): AltTextAdapter;
+/**
+ * Operator-facing Ollama provider. See `anthropicProvider` for the full
+ * Path X rationale. Ollama needs no API key; transport is just baseUrl.
+ */
+export declare function ollamaProvider(transport?: OllamaTransportOptions): AIProvider;
+//# sourceMappingURL=ollama.d.ts.map

package/dist/alt/ollama.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.d.ts","sourceRoot":"","sources":["../../src/alt/ollama.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAA;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAUlD,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,2BAA2B,CAAA;AAE/D,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,wBAAwB,CAAA;AAIzD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;mEAC+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAQD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,uBAA4B,GAAG,cAAc,CAqEzF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,GAAE,sBAA2B,GAAG,UAAU,CAYjF"}

package/dist/alt/ollama.js

@@ -0,0 +1,139 @@
+/**
+ * Ollama adapter — alt-text via the local `/api/chat` endpoint.
+ *
+ * # Why no SDK
+ *
+ * Ollama's API is a single endpoint, no auth, no streaming negotiation,
+ * no schema beyond simple JSON. The official `ollama` npm SDK exists
+ * but adds little value over raw `fetch` for this single-call use case.
+ * Skipping the SDK keeps adapter dependencies minimal.
+ *
+ * # Defaults
+ *
+ *   - Base URL: `http://localhost:11434` (Ollama's documented default).
+ *     Operators running Ollama on a different host configure via
+ *     `baseUrl` on the transport.
+ *   - Model: `llama3.2-vision:11b`. The 11B variant is the entry-level
+ *     size; `:90b` is also available for operators who want better
+ *     description quality at higher GPU/RAM cost.
+ *
+ * # API contract details (verified against Ollama API docs)
+ *
+ *   - Endpoint: `POST /api/chat` (chat-style fits the system+user pattern).
+ *   - Images are base64 strings in the per-message `images` array.
+ *     Different from Anthropic and OpenAI shapes — same adapter
+ *     abstraction holds via the scaffold.
+ *   - Response: `{ message: { content: "..." }, done: true, ... }`
+ *   - Auth: none for local install
+ *   - AbortSignal: standard fetch — `fetch(url, { signal })`. Errors
+ *     surface as `Error` with `name: 'AbortError'`.
+ *
+ * # SOLID
+ *
+ *   - Same lenses as Anthropic / OpenAI — orchestration via
+ *     `ai/adapter-scaffold.ts`, Ollama-specific request/response/error
+ *     shape here only.
+ */
+import { AIAdapterFailedError, AIInvalidResponseError } from '../ai/errors.js';
+import { buildAltAdapterFromScaffold } from '../ai/adapter-scaffold.js';
+const OLLAMA_REFUSAL_MARKERS = [
+    // llama3.2-vision tends to refuse with these patterns more than
+    // saas providers; markers maintained per [refusal.ts] convention.
+    "i'm not able to process this image",
+    'i am not able to process this image',
+    'sorry, i cannot',
+];
+/** Default base URL when running Ollama locally with default settings. */
+export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';
+/** Default model. Ollama Library publishes 11B and 90B variants of llama3.2-vision. */
+export const OLLAMA_DEFAULT_MODEL = 'llama3.2-vision:11b';
+const OLLAMA_SUPPORTED_MIMES = new Set(['image/jpeg', 'image/png']);
+/**
+ * Construct the Ollama alt-text adapter. Internal factory — kept public
+ * for tests + advanced wiring. Operator-facing config goes through
+ * `ollamaProvider(transport).altText(taskConfig)` (Path X).
+ */
+export function createOllamaAltAdapter(opts = {}) {
+    const baseUrl = (opts.baseUrl ?? OLLAMA_DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const model = opts.model ?? OLLAMA_DEFAULT_MODEL;
+    const endpoint = `${baseUrl}/api/chat`;
+    return buildAltAdapterFromScaffold({
+        name: 'ollama',
+        supportedMimes: OLLAMA_SUPPORTED_MIMES,
+        operatorSystemPrompt: opts.systemPrompt,
+        operatorMaxTokens: opts.maxTokens,
+        refusalMarkers: OLLAMA_REFUSAL_MARKERS,
+        isAbortError: err => err instanceof Error && err.name === 'AbortError',
+        errorContextSuffix: `Is Ollama running at ${baseUrl}?`,
+        async callProvider({ bytes, mime: _mime, systemPrompt, signal }) {
+            const imageB64 = Buffer.from(bytes).toString('base64');
+            const body = {
+                model,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    {
+                        role: 'user',
+                        content: 'Describe this image for use as alt text.',
+                        images: [imageB64],
+                    },
+                ],
+                stream: false,
+            };
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!res.ok) {
+                // Ollama returns plain-text errors for connection-level issues
+                // and JSON `{ error: "..." }` for model-level issues. Surface
+                // both as AIAdapterFailedError; the message includes status
+                // code so logs can disambiguate (404 → model not pulled, 400
+                // → malformed request, etc.).
+                let detail = `HTTP ${res.status}`;
+                try {
+                    const errorBody = await res.text();
+                    if (errorBody)
+                        detail += `: ${errorBody.slice(0, 200)}`;
+                }
+                catch {
+                    // Body unreadable; status code alone is the diagnostic.
+                }
+                throw new AIAdapterFailedError(`Ollama HTTP error: ${detail}`);
+            }
+            let parsed;
+            try {
+                parsed = (await res.json());
+            }
+            catch (err) {
+                throw new AIInvalidResponseError(`Ollama returned non-JSON response: ${err instanceof Error ? err.message : 'unknown'}`);
+            }
+            if (parsed.error) {
+                throw new AIAdapterFailedError(`Ollama: ${parsed.error}`);
+            }
+            if (typeof parsed.message?.content !== 'string') {
+                throw new AIInvalidResponseError('Ollama response had no message.content');
+            }
+            return parsed.message.content;
+        },
+    });
+}
+/**
+ * Operator-facing Ollama provider. See `anthropicProvider` for the full
+ * Path X rationale. Ollama needs no API key; transport is just baseUrl.
+ */
+export function ollamaProvider(transport = {}) {
+    return {
+        name: 'ollama',
+        altText(taskConfig) {
+            return createOllamaAltAdapter({
+                ...transport,
+                model: taskConfig.model,
+                systemPrompt: taskConfig.systemPrompt,
+                maxTokens: taskConfig.maxTokens,
+            });
+        },
+    };
+}
+//# sourceMappingURL=ollama.js.map

package/dist/alt/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/alt/ollama.ts"],"names":[],"mappings":"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"}

package/dist/alt/openai.d.ts

@@ -0,0 +1,46 @@
+import type { AIProvider } from '../ai/provider.js';
+import type { AltTextAdapter } from './adapter.js';
+/**
+ * Default model. Vision-capable across OpenAI's gpt-4o family. Sites
+ * with high-volume asset libraries should benchmark cost against
+ * actual workload.
+ */
+export declare const OPENAI_DEFAULT_MODEL = "gpt-4o-mini";
+/**
+ * OpenAI transport-only options. Per Path X (transport-vs-task split).
+ */
+export interface OpenAITransportOptions {
+    apiKey: string;
+    /** Optional override of the SDK base URL — for tests pointing at msw or proxy setups. */
+    baseURL?: string;
+    /**
+     * Override the SDK's retry count (default 2). Tests pass 0 to keep
+     * runs deterministic and fast.
+     */
+    maxRetries?: number;
+}
+/**
+ * Internal type for `createOpenAIAltAdapter` callers (tests). Combines
+ * transport with per-task config; new code goes through
+ * `openaiProvider(transport).altText(taskConfig)`.
+ */
+export interface OpenAIAltAdapterOptions extends OpenAITransportOptions {
+    /** Model ID; defaults to {@link OPENAI_DEFAULT_MODEL}. */
+    model?: string;
+    /** Operator-supplied system prompt; prepended to system-composed prompt. */
+    systemPrompt?: string;
+    /** Generation token cap; provider derives from maxChars when absent. */
+    maxTokens?: number;
+}
+/**
+ * Construct the OpenAI alt-text adapter. Internal factory — kept public
+ * for tests + advanced wiring. Operator-facing config goes through
+ * `openaiProvider(transport).altText(taskConfig)` (Path X).
+ */
+export declare function createOpenAIAltAdapter(opts: OpenAIAltAdapterOptions): AltTextAdapter;
+/**
+ * Operator-facing OpenAI provider. See `anthropicProvider` for the full
+ * Path X rationale.
+ */
+export declare function openaiProvider(transport: OpenAITransportOptions): AIProvider;
+//# sourceMappingURL=openai.d.ts.map

package/dist/alt/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/alt/openai.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAA;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAYlD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAA;AAIjD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,CAwCpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,sBAAsB,GAAG,UAAU,CAe5E"}

package/dist/alt/openai.js

@@ -0,0 +1,118 @@
+/**
+ * OpenAI adapter — alt-text via the `chat.completions.create` vision API.
+ *
+ * # Defaults
+ *
+ *   - Model: `gpt-4o-mini` — vision-capable, well-supported. Note that
+ *     OpenAI's vision pricing is non-trivial: while gpt-4o-mini is
+ *     cheaper per text token than gpt-4o, vision token cost differs
+ *     and the math is workload-dependent. Sites comparing costs
+ *     should benchmark against their actual asset library.
+ *
+ * # API contract details (verified against `openai` SDK v6+)
+ *
+ *   - Image content uses `{ type: 'image_url', image_url: { url } }`.
+ *     The URL is a base64 data URL: `data:{mime};base64,{data}`.
+ *   - Accepted MIMEs: JPEG, PNG, GIF, WebP. After `prepareForVision`
+ *     our bytes are JPEG or PNG.
+ *   - System prompt is a `role: 'system'` message (not a top-level
+ *     parameter like Anthropic). User message contains the image.
+ *   - `max_tokens` is optional but the scaffold sets it (operator
+ *     override OR derived from maxChars).
+ *
+ * # AbortSignal
+ *
+ *   - Passed via `chat.completions.create(body, { signal })`. SDK throws
+ *     `APIUserAbortError` on abort; scaffold's `isAbortError` recognizes
+ *     it so the suggester can return null on cancellation.
+ *
+ * # SOLID
+ *
+ *   - Same lenses as Anthropic adapter — orchestration via
+ *     `ai/adapter-scaffold.ts`, OpenAI-specific request/response
+ *     shape here only.
+ */
+import OpenAI from 'openai';
+import { AIInvalidResponseError } from '../ai/errors.js';
+import { buildAltAdapterFromScaffold } from '../ai/adapter-scaffold.js';
+/**
+ * OpenAI-specific refusal phrases. Layered on top of the shared list
+ * in `ai/refusal.ts`.
+ */
+const OPENAI_REFUSAL_MARKERS = [
+    "i'm sorry, i can't assist",
+    "i can't assist with that",
+    'i am unable to assist',
+];
+/**
+ * Default model. Vision-capable across OpenAI's gpt-4o family. Sites
+ * with high-volume asset libraries should benchmark cost against
+ * actual workload.
+ */
+export const OPENAI_DEFAULT_MODEL = 'gpt-4o-mini';
+const OPENAI_SUPPORTED_MIMES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+function toBase64DataUrl(bytes, mime) {
+    return `data:${mime};base64,${Buffer.from(bytes).toString('base64')}`;
+}
+/**
+ * Construct the OpenAI alt-text adapter. Internal factory — kept public
+ * for tests + advanced wiring. Operator-facing config goes through
+ * `openaiProvider(transport).altText(taskConfig)` (Path X).
+ */
+export function createOpenAIAltAdapter(opts) {
+    const client = new OpenAI({
+        apiKey: opts.apiKey,
+        baseURL: opts.baseURL,
+        maxRetries: opts.maxRetries,
+    });
+    const model = opts.model ?? OPENAI_DEFAULT_MODEL;
+    return buildAltAdapterFromScaffold({
+        name: 'openai',
+        supportedMimes: OPENAI_SUPPORTED_MIMES,
+        operatorSystemPrompt: opts.systemPrompt,
+        operatorMaxTokens: opts.maxTokens,
+        refusalMarkers: OPENAI_REFUSAL_MARKERS,
+        isAbortError: err => err instanceof OpenAI.APIUserAbortError,
+        async callProvider({ bytes, mime, systemPrompt, maxTokens, signal }) {
+            const response = await client.chat.completions.create({
+                model,
+                max_tokens: maxTokens,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    {
+                        role: 'user',
+                        content: [{ type: 'image_url', image_url: { url: toBase64DataUrl(bytes, mime) } }],
+                    },
+                ],
+            }, { signal });
+            // Response shape: choices[0].message.content. May be null when
+            // the model returns a tool-call instead — defensive against that.
+            const content = response.choices[0]?.message.content;
+            if (typeof content !== 'string') {
+                throw new AIInvalidResponseError('OpenAI response had no text content');
+            }
+            return content;
+        },
+    });
+}
+/**
+ * Operator-facing OpenAI provider. See `anthropicProvider` for the full
+ * Path X rationale.
+ */
+export function openaiProvider(transport) {
+    if (!transport.apiKey) {
+        throw new Error('openaiProvider: "apiKey" is required (typically `process.env.OPENAI_API_KEY!`)');
+    }
+    return {
+        name: 'openai',
+        altText(taskConfig) {
+            return createOpenAIAltAdapter({
+                ...transport,
+                model: taskConfig.model,
+                systemPrompt: taskConfig.systemPrompt,
+                maxTokens: taskConfig.maxTokens,
+            });
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/alt/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/alt/openai.ts"],"names":[],"mappings":"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"}

package/dist/alt/prompt-policies.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Alt-text prompt policies — five `AltPromptPolicy` modules that each
+ * own one dimension of prompt content.
+ *
+ * # Why split into five
+ *
+ * Per [team-preferences rule 18], "structurally correct from the
+ * start". A single mega-string would be a god-string with five
+ * reasons to change (task framing, style, length, locale, output
+ * discipline). Splitting at the SOLID seam means:
+ *
+ *   - WCAG guidance update → edit `styleGuidancePolicy` only
+ *   - Locale strategy change → edit `localePolicy` only
+ *   - Length convention change → edit `lengthPolicy` only
+ *
+ * Each policy is independently testable. The composer assembles them
+ * via `composePrompt(req, DEFAULT_POLICIES)`.
+ *
+ * # Adding a new style
+ *
+ * Future styles like `'marketing'` or `'technical'` extend the
+ * `AltStyle` enum + add a switch arm in `styleGuidancePolicy`. Other
+ * policies untouched (OCP).
+ *
+ * # Locale handling
+ *
+ * Direct generation: when locale ≠ default, ask the model to write in
+ * that locale. Modern vision models are competently multilingual at
+ * description tasks. Translation as a separate pipeline was rejected
+ * — would require a parallel `TranslationAdapter` system before its
+ * second consumer exists.
+ */
+import type { AltPromptPolicy } from './adapter.js';
+/**
+ * Policy 1 — frame the task. Sets the model's frame: this is alt
+ * text generation following web-accessibility conventions, not
+ * caption generation.
+ */
+export declare const taskFramingPolicy: AltPromptPolicy;
+/**
+ * Policy 2 — style guidance per `request.style`. Currently only
+ * `'descriptive'`; extending the enum adds a switch arm here.
+ *
+ * The descriptive guidance steers the model away from common
+ * caption-style patterns ("Image of...", "A photograph of...") and
+ * toward direct description.
+ */
+export declare const styleGuidancePolicy: AltPromptPolicy;
+/**
+ * Policy 3 — length cap as model guidance. Soft instruction; the
+ * suggester doesn't enforce truncation. WAI-ARIA convention is 125
+ * chars; per-call override via `request.maxChars`.
+ */
+export declare const lengthPolicy: AltPromptPolicy;
+/**
+ * Policy 4 — locale instruction. Empty string when locale is the
+ * default (composer drops empty-string policies; the prompt has one
+ * fewer paragraph), non-empty otherwise.
+ *
+ * When locale ≠ 'en', the model writes the description in that
+ * language directly. No translation step.
+ */
+export declare const localePolicy: AltPromptPolicy;
+/**
+ * Policy 5 — output discipline. Clamp the model's tendency to add
+ * preamble or wrapper quotes around its answer. Last in the order
+ * because it's the closing instruction.
+ */
+export declare const outputDisciplinePolicy: AltPromptPolicy;
+/**
+ * Default policy set, in composition order. Most prompt-tuning lives
+ * in editing the policies above; the order here changes only when
+ * paragraph priority changes (rare).
+ *
+ * Callers can pass a custom array for one-off requests, but the
+ * default is what every alt-text generation uses in production.
+ */
+export declare const DEFAULT_ALT_PROMPT_POLICIES: readonly AltPromptPolicy[];
+//# sourceMappingURL=prompt-policies.d.ts.map

package/dist/alt/prompt-policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-policies.d.ts","sourceRoot":"","sources":["../../src/alt/prompt-policies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,cAAc,CAAA;AAQ7D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,eACgD,CAAA;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAMjC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,eAA8D,CAAA;AAEzF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,eAG1B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAA6E,CAAA;AAElH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,eAAe,EAMjE,CAAA"}

package/dist/alt/prompt-policies.js

@@ -0,0 +1,67 @@
+/**
+ * The default locale for which `localePolicy` doesn't add anything.
+ * Aligned with the WCAG-grounded prompts being written in English.
+ */
+const DEFAULT_LOCALE = 'en';
+/**
+ * Policy 1 — frame the task. Sets the model's frame: this is alt
+ * text generation following web-accessibility conventions, not
+ * caption generation.
+ */
+export const taskFramingPolicy = () => `You are writing alt text for a webpage image, following WCAG 2.1 guidelines.`;
+/**
+ * Policy 2 — style guidance per `request.style`. Currently only
+ * `'descriptive'`; extending the enum adds a switch arm here.
+ *
+ * The descriptive guidance steers the model away from common
+ * caption-style patterns ("Image of...", "A photograph of...") and
+ * toward direct description.
+ */
+export const styleGuidancePolicy = req => {
+    const style = req.style;
+    switch (style) {
+        case 'descriptive':
+            return `Describe what's visually present and meaningful. Be specific and concrete. Don't start with "image of" or "picture of" — write the description directly.`;
+    }
+};
+/**
+ * Policy 3 — length cap as model guidance. Soft instruction; the
+ * suggester doesn't enforce truncation. WAI-ARIA convention is 125
+ * chars; per-call override via `request.maxChars`.
+ */
+export const lengthPolicy = req => `Maximum ${req.maxChars} characters.`;
+/**
+ * Policy 4 — locale instruction. Empty string when locale is the
+ * default (composer drops empty-string policies; the prompt has one
+ * fewer paragraph), non-empty otherwise.
+ *
+ * When locale ≠ 'en', the model writes the description in that
+ * language directly. No translation step.
+ */
+export const localePolicy = req => {
+    if (req.locale === DEFAULT_LOCALE)
+        return '';
+    return `Write the description in ${req.locale}.`;
+};
+/**
+ * Policy 5 — output discipline. Clamp the model's tendency to add
+ * preamble or wrapper quotes around its answer. Last in the order
+ * because it's the closing instruction.
+ */
+export const outputDisciplinePolicy = () => `Output the description only, no preamble or quotes.`;
+/**
+ * Default policy set, in composition order. Most prompt-tuning lives
+ * in editing the policies above; the order here changes only when
+ * paragraph priority changes (rare).
+ *
+ * Callers can pass a custom array for one-off requests, but the
+ * default is what every alt-text generation uses in production.
+ */
+export const DEFAULT_ALT_PROMPT_POLICIES = [
+    taskFramingPolicy,
+    styleGuidancePolicy,
+    lengthPolicy,
+    localePolicy,
+    outputDisciplinePolicy,
+];
+//# sourceMappingURL=prompt-policies.js.map

package/dist/alt/prompt-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-policies.js","sourceRoot":"","sources":["../../src/alt/prompt-policies.ts"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAoB,GAAG,EAAE,CACrD,8EAA8E,CAAA;AAEhF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAoB,GAAG,CAAC,EAAE;IACxD,MAAM,KAAK,GAAa,GAAG,CAAC,KAAK,CAAA;IACjC,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,aAAa;YAChB,OAAO,0JAA0J,CAAA;IACrK,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoB,GAAG,CAAC,EAAE,CAAC,WAAW,GAAG,CAAC,QAAQ,cAAc,CAAA;AAEzF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoB,GAAG,CAAC,EAAE;IACjD,IAAI,GAAG,CAAC,MAAM,KAAK,cAAc;QAAE,OAAO,EAAE,CAAA;IAC5C,OAAO,4BAA4B,GAAG,CAAC,MAAM,GAAG,CAAA;AAClD,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAoB,GAAG,EAAE,CAAC,qDAAqD,CAAA;AAElH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA+B;IACrE,iBAAiB;IACjB,mBAAmB;IACnB,YAAY;IACZ,YAAY;IACZ,sBAAsB;CACvB,CAAA"}