gazetta 0.7.0 → 0.8.0

package/dist/ai/compose-prompt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Generic prompt composer — assembles a final prompt string from an
+ * ordered list of `PromptPolicy<T>` functions, where `T` is the typed
+ * request shape for the calling task.
+ *
+ * # Why generic over `T`
+ *
+ * Each AI task has its own typed request (alt-text has `AltRequest`
+ * with `locale`, `maxChars`, `style`; future translation will have its
+ * own with source/target language pairs, formality, etc.). The
+ * composer doesn't need to know task-specific fields — it just calls
+ * each policy in order and joins the non-empty results.
+ *
+ * Putting the composer in `ai/` (not in `alt/`) means the second task
+ * doesn't reimplement composition. Each task contributes its own
+ * `PromptPolicy<TaskRequest>` modules that import this composer.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "ordered policies → final prompt string"
+ *   - OCP: callers pass their own policy array; the default policy set
+ *     is the task's responsibility, not this module's
+ *   - LSP: every policy is `(req: T) => string`; trivially substitutable
+ *   - DIP: tasks depend on this generic composer, not on each other
+ *
+ * # Empty-string convention
+ *
+ * Policies that don't apply (e.g., the locale policy when locale is
+ * the default 'en') return an empty string. The composer filters these
+ * out before joining, so empty paragraphs don't appear in the final
+ * prompt. This keeps each policy decision local — no callers need to
+ * reason about "should I include this policy?"
+ */
+/**
+ * One dimension of prompt content. A function from a typed request to
+ * a string paragraph. Empty string means "this policy doesn't apply
+ * for this request" and is dropped before assembly.
+ */
+export type PromptPolicy<TRequest> = (req: TRequest) => string;
+/**
+ * Assemble policies into a prompt. Joins non-empty results with two
+ * newlines (paragraph break) — model providers parse this as natural
+ * structure. Order matters: callers pass the array in the order they
+ * want paragraphs to appear.
+ *
+ * Tests can pass a custom policy array to validate composition without
+ * coupling to any task's default set.
+ */
+export declare function composePrompt<TRequest>(req: TRequest, policies: readonly PromptPolicy<TRequest>[]): string;
+//# sourceMappingURL=compose-prompt.d.ts.map

package/dist/ai/compose-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.d.ts","sourceRoot":"","sources":["../../src/ai/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,CAK1G"}

package/dist/ai/compose-prompt.js

@@ -0,0 +1,49 @@
+/**
+ * Generic prompt composer — assembles a final prompt string from an
+ * ordered list of `PromptPolicy<T>` functions, where `T` is the typed
+ * request shape for the calling task.
+ *
+ * # Why generic over `T`
+ *
+ * Each AI task has its own typed request (alt-text has `AltRequest`
+ * with `locale`, `maxChars`, `style`; future translation will have its
+ * own with source/target language pairs, formality, etc.). The
+ * composer doesn't need to know task-specific fields — it just calls
+ * each policy in order and joins the non-empty results.
+ *
+ * Putting the composer in `ai/` (not in `alt/`) means the second task
+ * doesn't reimplement composition. Each task contributes its own
+ * `PromptPolicy<TaskRequest>` modules that import this composer.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "ordered policies → final prompt string"
+ *   - OCP: callers pass their own policy array; the default policy set
+ *     is the task's responsibility, not this module's
+ *   - LSP: every policy is `(req: T) => string`; trivially substitutable
+ *   - DIP: tasks depend on this generic composer, not on each other
+ *
+ * # Empty-string convention
+ *
+ * Policies that don't apply (e.g., the locale policy when locale is
+ * the default 'en') return an empty string. The composer filters these
+ * out before joining, so empty paragraphs don't appear in the final
+ * prompt. This keeps each policy decision local — no callers need to
+ * reason about "should I include this policy?"
+ */
+/**
+ * Assemble policies into a prompt. Joins non-empty results with two
+ * newlines (paragraph break) — model providers parse this as natural
+ * structure. Order matters: callers pass the array in the order they
+ * want paragraphs to appear.
+ *
+ * Tests can pass a custom policy array to validate composition without
+ * coupling to any task's default set.
+ */
+export function composePrompt(req, policies) {
+    return policies
+        .map(policy => policy(req))
+        .filter(paragraph => paragraph.length > 0)
+        .join('\n\n');
+}
+//# sourceMappingURL=compose-prompt.js.map

package/dist/ai/compose-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.js","sourceRoot":"","sources":["../../src/ai/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAW,GAAa,EAAE,QAA2C;IAChG,OAAO,QAAQ;SACZ,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC1B,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,MAAM,CAAC,CAAA;AACjB,CAAC"}

package/dist/ai/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Typed errors for the AI domain — one class per failure mode, each
+ * carrying an HTTP status so route handlers don't pattern-match on
+ * messages.
+ *
+ * Pattern mirrors `assets/errors.ts`: subclass `AIError`, declare the
+ * `code` and `httpStatus` on the class, override `toResponseBody()` if
+ * extra structured fields are needed.
+ *
+ * Adding a new AI error is one new subclass + one new code in the
+ * union. Routes pick up the new HTTP status via the `httpStatus`
+ * property — no route-handler edits required (OCP).
+ */
+export type AIErrorCode = 'AI_ADAPTER_UNAVAILABLE' | 'AI_ADAPTER_FAILED' | 'AI_INVALID_RESPONSE';
+export type AIErrorHttpStatus = 502 | 503;
+export interface AIErrorResponseBody {
+    readonly code: AIErrorCode;
+    readonly message: string;
+}
+/**
+ * Base class. Subclasses set `code` and `httpStatus` as readonly
+ * properties; the base provides the `toResponseBody()` machinery.
+ */
+export declare abstract class AIError extends Error {
+    abstract readonly code: AIErrorCode;
+    abstract readonly httpStatus: AIErrorHttpStatus;
+    toResponseBody(): AIErrorResponseBody;
+}
+/**
+ * No adapter is configured for the target, OR the adapter is configured
+ * but its credentials are missing, OR the adapter doesn't support the
+ * requested MIME. UI hides AI affordances; route returns 503.
+ *
+ * Distinct from `AIAdapterFailedError` because this is a configuration
+ * state, not a runtime failure — retrying won't help.
+ */
+export declare class AIAdapterUnavailableError extends AIError {
+    readonly code = "AI_ADAPTER_UNAVAILABLE";
+    readonly httpStatus = 503;
+}
+/**
+ * Adapter was reached but the call failed — network error, auth
+ * rejection, rate limit not handled by the SDK's own retry, malformed
+ * response. Route returns 502 (we're acting as a gateway to the
+ * upstream provider).
+ *
+ * The provider-specific cause is attached as `cause` (per the standard
+ * Error.cause property) so logs can drill into the underlying failure
+ * without leaking provider details into the API response.
+ */
+export declare class AIAdapterFailedError extends AIError {
+    readonly code = "AI_ADAPTER_FAILED";
+    readonly httpStatus = 502;
+}
+/**
+ * Adapter received a response from the provider, but it didn't parse
+ * into the expected shape (missing content field, unexpected null,
+ * etc.). 502 — same gateway semantics as `AIAdapterFailedError`, but
+ * the cause is parsing rather than transport.
+ */
+export declare class AIInvalidResponseError extends AIError {
+    readonly code = "AI_INVALID_RESPONSE";
+    readonly httpStatus = 502;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/ai/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ai/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GAAG,wBAAwB,GAAG,mBAAmB,GAAG,qBAAqB,CAAA;AAEhG,MAAM,MAAM,iBAAiB,GAAG,GAAG,GAAG,GAAG,CAAA;AAEzC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IAE/C,cAAc,IAAI,mBAAmB;CAGtC;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,OAAO;IACpD,QAAQ,CAAC,IAAI,4BAA2B;IACxC,QAAQ,CAAC,UAAU,OAAM;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAC/C,QAAQ,CAAC,IAAI,uBAAsB;IACnC,QAAQ,CAAC,UAAU,OAAM;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,OAAO;IACjD,QAAQ,CAAC,IAAI,yBAAwB;IACrC,QAAQ,CAAC,UAAU,OAAM;CAC1B"}

package/dist/ai/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Typed errors for the AI domain — one class per failure mode, each
+ * carrying an HTTP status so route handlers don't pattern-match on
+ * messages.
+ *
+ * Pattern mirrors `assets/errors.ts`: subclass `AIError`, declare the
+ * `code` and `httpStatus` on the class, override `toResponseBody()` if
+ * extra structured fields are needed.
+ *
+ * Adding a new AI error is one new subclass + one new code in the
+ * union. Routes pick up the new HTTP status via the `httpStatus`
+ * property — no route-handler edits required (OCP).
+ */
+/**
+ * Base class. Subclasses set `code` and `httpStatus` as readonly
+ * properties; the base provides the `toResponseBody()` machinery.
+ */
+export class AIError extends Error {
+    toResponseBody() {
+        return { code: this.code, message: this.message };
+    }
+}
+/**
+ * No adapter is configured for the target, OR the adapter is configured
+ * but its credentials are missing, OR the adapter doesn't support the
+ * requested MIME. UI hides AI affordances; route returns 503.
+ *
+ * Distinct from `AIAdapterFailedError` because this is a configuration
+ * state, not a runtime failure — retrying won't help.
+ */
+export class AIAdapterUnavailableError extends AIError {
+    code = 'AI_ADAPTER_UNAVAILABLE';
+    httpStatus = 503;
+}
+/**
+ * Adapter was reached but the call failed — network error, auth
+ * rejection, rate limit not handled by the SDK's own retry, malformed
+ * response. Route returns 502 (we're acting as a gateway to the
+ * upstream provider).
+ *
+ * The provider-specific cause is attached as `cause` (per the standard
+ * Error.cause property) so logs can drill into the underlying failure
+ * without leaking provider details into the API response.
+ */
+export class AIAdapterFailedError extends AIError {
+    code = 'AI_ADAPTER_FAILED';
+    httpStatus = 502;
+}
+/**
+ * Adapter received a response from the provider, but it didn't parse
+ * into the expected shape (missing content field, unexpected null,
+ * etc.). 502 — same gateway semantics as `AIAdapterFailedError`, but
+ * the cause is parsing rather than transport.
+ */
+export class AIInvalidResponseError extends AIError {
+    code = 'AI_INVALID_RESPONSE';
+    httpStatus = 502;
+}
+//# sourceMappingURL=errors.js.map

package/dist/ai/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ai/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;;;GAGG;AACH,MAAM,OAAgB,OAAQ,SAAQ,KAAK;IAIzC,cAAc;QACZ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;IACnD,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,OAAO;IAC3C,IAAI,GAAG,wBAAwB,CAAA;IAC/B,UAAU,GAAG,GAAG,CAAA;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAqB,SAAQ,OAAO;IACtC,IAAI,GAAG,mBAAmB,CAAA;IAC1B,UAAU,GAAG,GAAG,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,OAAO;IACxC,IAAI,GAAG,qBAAqB,CAAA;IAC5B,UAAU,GAAG,GAAG,CAAA;CAC1B"}

package/dist/ai/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of `ai/` — cross-task AI infrastructure shared by
+ * per-task implementations (alt-text in v1.5; translation, tag
+ * suggestion, summarization in future).
+ *
+ * `ai/` is a code library, not an inheritance hierarchy. Tasks compose
+ * these utilities — they don't extend a base class. Per
+ * [team-preferences.md] convention 1: composition over inheritance.
+ */
+export type { AIProvider, AltTextTaskConfig } from './provider.js';
+export { PROVIDER_DEFAULT_MODELS } from './provider.js';
+export { AIError, AIAdapterUnavailableError, AIAdapterFailedError, AIInvalidResponseError, type AIErrorCode, type AIErrorHttpStatus, type AIErrorResponseBody, } from './errors.js';
+export { detectRefusal, type RefusalDetection } from './refusal.js';
+export { composePrompt, type PromptPolicy } from './compose-prompt.js';
+export { prepareForVision, MAX_EDGE, type PrepareInput, type PreparedImage } from './vision-prep.js';
+export { buildAltAdapterFromScaffold, type AdapterScaffoldOptions, type ProviderCallInput, } from './adapter-scaffold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACpG,OAAO,EACL,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,uBAAuB,CAAA"}

package/dist/ai/index.js

@@ -0,0 +1,16 @@
+/**
+ * Public surface of `ai/` — cross-task AI infrastructure shared by
+ * per-task implementations (alt-text in v1.5; translation, tag
+ * suggestion, summarization in future).
+ *
+ * `ai/` is a code library, not an inheritance hierarchy. Tasks compose
+ * these utilities — they don't extend a base class. Per
+ * [team-preferences.md] convention 1: composition over inheritance.
+ */
+export { PROVIDER_DEFAULT_MODELS } from './provider.js';
+export { AIError, AIAdapterUnavailableError, AIAdapterFailedError, AIInvalidResponseError, } from './errors.js';
+export { detectRefusal } from './refusal.js';
+export { composePrompt } from './compose-prompt.js';
+export { prepareForVision, MAX_EDGE } from './vision-prep.js';
+export { buildAltAdapterFromScaffold, } from './adapter-scaffold.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GAIvB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAyB,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,aAAa,EAAqB,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAyC,MAAM,kBAAkB,CAAA;AACpG,OAAO,EACL,2BAA2B,GAG5B,MAAM,uBAAuB,CAAA"}

package/dist/ai/provider.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `AIProvider` — transport-only interface for an AI account / endpoint.
+ *
+ * Per [`design-ai.md`](../../../.claude/rules/design-ai.md) "Two-axis split":
+ * the provider holds transport (apiKey, baseUrl, organizationId, timeout)
+ * and exposes per-task builder methods that return per-task adapters.
+ * Operational config (model, systemPrompt, maxTokens) lives in
+ * data-literal blocks the resolver feeds to `provider.altText({...})`
+ * at boot — not on the provider constructor.
+ *
+ * Why split: one Anthropic account legitimately serves multiple tasks
+ * (alt-text, future translation, future summarization, future
+ * image-gen) with different model + prompt + token-budget per task.
+ * Putting model/prompt on the constructor would force operators to
+ * build a separate provider per task; transport-only keeps providers
+ * reusable across tasks.
+ *
+ * Future tasks add their own builder method here:
+ *   - `translation(taskConfig: TranslationTaskConfig): TranslationAdapter`
+ *   - `summarization(taskConfig: SummarizationTaskConfig): SummarizationAdapter`
+ *
+ * Plugin-supplied providers may extend this with their own builder
+ * methods; consumers depend on the abstraction (`AIProvider`), not
+ * the concrete provider classes.
+ */
+import type { AltTextAdapter } from '../alt/adapter.js';
+/**
+ * Per-task configuration for the alt-text task. Data-literal type fed to
+ * `provider.altText(taskConfig)` by the resolver. Field details:
+ *
+ *   - `model` — non-optional at adapter construction; the resolver always
+ *     supplies one (chain falls through to `PROVIDER_DEFAULT_MODELS`).
+ *     Operator-facing config blocks make it optional and inherit per the
+ *     three-rung chain (target → site → gazetta → provider default).
+ *
+ *   - `systemPrompt` — operator-supplied voice/style override. When set,
+ *     the suggester prepends it to the system-composed neutral prompt
+ *     (see `design-ai.md` "Prompt composition"). Null/undefined = use
+ *     system default only. Custom prompt policies (full replacement of
+ *     the WCAG-grounded base) remain v1.6+ deferred.
+ *
+ *   - `maxTokens` — generation budget cap. Provider-specific default
+ *     applies when null/undefined (Anthropic derives from `maxChars`;
+ *     OpenAI/Ollama use SDK defaults).
+ */
+export interface AltTextTaskConfig {
+    /** Model ID. Non-optional at adapter construction (resolver always supplies). */
+    model: string;
+    /** Operator-supplied system prompt; prepended to the system-composed prompt. */
+    systemPrompt?: string;
+    /** Generation token cap; provider-default applies when absent. */
+    maxTokens?: number;
+}
+/**
+ * Transport-only AI provider. Constructor takes credentials/endpoint
+ * config; builder methods construct per-task adapters from data-literal
+ * task config.
+ */
+export interface AIProvider {
+    /** Stable identifier for diagnostics + per-provider default-model lookup. */
+    readonly name: string;
+    /**
+     * Construct an alt-text adapter from per-task config. Resolver supplies
+     * the merged `AltTextTaskConfig` from the three-rung inheritance chain.
+     */
+    altText(taskConfig: AltTextTaskConfig): AltTextAdapter;
+}
+/**
+ * Per-provider sensible default model. Used when the model field is
+ * unset across the entire chain (gazetta → site → target). Plugin
+ * providers contribute their own name; default-model fallback for
+ * unknown plugin names returns undefined (operator must specify
+ * `model` somewhere in the chain).
+ */
+export declare const PROVIDER_DEFAULT_MODELS: Record<string, string>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,cAAc,CAAA;CAKvD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI1D,CAAA"}

package/dist/ai/provider.js

@@ -0,0 +1,13 @@
+/**
+ * Per-provider sensible default model. Used when the model field is
+ * unset across the entire chain (gazetta → site → target). Plugin
+ * providers contribute their own name; default-model fallback for
+ * unknown plugin names returns undefined (operator must specify
+ * `model` somewhere in the chain).
+ */
+export const PROVIDER_DEFAULT_MODELS = {
+    anthropic: 'claude-haiku-4-5',
+    openai: 'gpt-4o-mini',
+    ollama: 'llama3.2-vision:11b',
+};
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,SAAS,EAAE,kBAAkB;IAC7B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,qBAAqB;CAC9B,CAAA"}

package/dist/ai/refusal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Refusal detection for AI provider responses.
+ *
+ * # Why this lives in `ai/` and not `alt/`
+ *
+ * Provider safety refusals look the same regardless of task. Whether
+ * the model is asked to describe an image (alt-text) or translate a
+ * paragraph (future), a refusal arrives as a 200 OK with text like
+ * "I can't help with that" in the response body — structurally
+ * indistinguishable from a successful response without inspection.
+ *
+ * v1.5's only consumer is `alt/`, but refusal detection is conceptually
+ * cross-task. Right structure now beats right structure later, per
+ * [team-preferences rule 18]: "extract shared code when you first see
+ * the split concern". Translation as the documented next consumer
+ * (per [design-ai-implementation.md]) makes this a known split.
+ *
+ * # Marker maintenance
+ *
+ * The marker list below MUST stay current as providers tune their
+ * safety messaging. Plan: review at every major model version bump
+ * (e.g., when an adapter's `defaultModel` jumps a major). Provider-
+ * specific phrases live in the adapter (passed via `adapterMarkers`)
+ * so generic markers and provider-specific ones can evolve
+ * independently.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "raw text → structured refusal info"
+ *   - OCP: per-adapter markers extend without touching the shared list
+ *   - DIP: callers depend on `detectRefusal`, not on substring inspection
+ *     scattered across the codebase
+ */
+export interface RefusalDetection {
+    refused: boolean;
+    /** Truncated reason text when refused; null when not. */
+    reason: string | null;
+}
+/**
+ * Detect whether `text` is a refusal. Caller passes adapter-specific
+ * markers (e.g., Anthropic's particular phrasing) on top of the shared
+ * list.
+ *
+ * Returns `{ refused: false, reason: null }` for descriptive responses;
+ * `{ refused: true, reason: <truncated text> }` otherwise. Reason is
+ * truncated to 200 chars so logs and UI toasts don't render arbitrarily
+ * long refusal blocks.
+ */
+export declare function detectRefusal(text: string, adapterMarkers?: readonly string[]): RefusalDetection;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/ai/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/ai/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA2CH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,GAAE,SAAS,MAAM,EAAO,GAAG,gBAAgB,CAgBpG"}

package/dist/ai/refusal.js

@@ -0,0 +1,100 @@
+/**
+ * Refusal detection for AI provider responses.
+ *
+ * # Why this lives in `ai/` and not `alt/`
+ *
+ * Provider safety refusals look the same regardless of task. Whether
+ * the model is asked to describe an image (alt-text) or translate a
+ * paragraph (future), a refusal arrives as a 200 OK with text like
+ * "I can't help with that" in the response body — structurally
+ * indistinguishable from a successful response without inspection.
+ *
+ * v1.5's only consumer is `alt/`, but refusal detection is conceptually
+ * cross-task. Right structure now beats right structure later, per
+ * [team-preferences rule 18]: "extract shared code when you first see
+ * the split concern". Translation as the documented next consumer
+ * (per [design-ai-implementation.md]) makes this a known split.
+ *
+ * # Marker maintenance
+ *
+ * The marker list below MUST stay current as providers tune their
+ * safety messaging. Plan: review at every major model version bump
+ * (e.g., when an adapter's `defaultModel` jumps a major). Provider-
+ * specific phrases live in the adapter (passed via `adapterMarkers`)
+ * so generic markers and provider-specific ones can evolve
+ * independently.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "raw text → structured refusal info"
+ *   - OCP: per-adapter markers extend without touching the shared list
+ *   - DIP: callers depend on `detectRefusal`, not on substring inspection
+ *     scattered across the codebase
+ */
+/**
+ * Cross-provider refusal phrases. Lowercase substrings — the matcher
+ * lowercases both sides, so casing in the upstream response doesn't
+ * matter. Order is irrelevant; `Array.some` is fine at this size.
+ *
+ * Each entry corresponds to a phrase observed across at least two
+ * providers' refusal outputs. Provider-specific phrasing belongs in
+ * the adapter, passed via `adapterMarkers`.
+ */
+const SHARED_REFUSAL_MARKERS = [
+    "i can't describe",
+    'i cannot describe',
+    "i'm not able to describe",
+    'i am not able to describe',
+    "i'm unable to describe",
+    'i am unable to describe',
+    "i can't provide",
+    'i cannot provide',
+    "i'm unable to provide",
+    'i am unable to provide',
+    "i can't help",
+    'i cannot help',
+    "i'm not able to help",
+    "i'm sorry, but",
+];
+/**
+ * Minimum useful response length. Below this, even a non-refusal
+ * response is too short to be a real description — treat as a refusal
+ * with a generic reason. Calibrated for the alt-text use case where
+ * five chars is below "Cat." (4) but above "Hi" (2); empty responses
+ * also fall through here.
+ *
+ * If a future task has different length expectations (e.g., a single-
+ * word tag), the consumer should normalize the response before passing
+ * it to `detectRefusal`, OR the threshold becomes a parameter. Don't
+ * generalize speculatively — wait for the second task to force the
+ * shape.
+ */
+const MIN_USEFUL_LENGTH = 5;
+/**
+ * Detect whether `text` is a refusal. Caller passes adapter-specific
+ * markers (e.g., Anthropic's particular phrasing) on top of the shared
+ * list.
+ *
+ * Returns `{ refused: false, reason: null }` for descriptive responses;
+ * `{ refused: true, reason: <truncated text> }` otherwise. Reason is
+ * truncated to 200 chars so logs and UI toasts don't render arbitrarily
+ * long refusal blocks.
+ */
+export function detectRefusal(text, adapterMarkers = []) {
+    const lower = text.toLowerCase();
+    for (const marker of SHARED_REFUSAL_MARKERS) {
+        if (lower.includes(marker)) {
+            return { refused: true, reason: text.slice(0, 200) };
+        }
+    }
+    for (const marker of adapterMarkers) {
+        if (lower.includes(marker.toLowerCase())) {
+            return { refused: true, reason: text.slice(0, 200) };
+        }
+    }
+    if (text.trim().length < MIN_USEFUL_LENGTH) {
+        return { refused: true, reason: 'Empty or unusably short response' };
+    }
+    return { refused: false, reason: null };
+}
+//# sourceMappingURL=refusal.js.map

package/dist/ai/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../src/ai/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;GAQG;AACH,MAAM,sBAAsB,GAAsB;IAChD,kBAAkB;IAClB,mBAAmB;IACnB,0BAA0B;IAC1B,2BAA2B;IAC3B,wBAAwB;IACxB,yBAAyB;IACzB,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;IACvB,wBAAwB;IACxB,cAAc;IACd,eAAe;IACf,sBAAsB;IACtB,gBAAgB;CACjB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAQ3B;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,iBAAoC,EAAE;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IAChC,KAAK,MAAM,MAAM,IAAI,sBAAsB,EAAE,CAAC;QAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;QACtD,CAAC;IACH,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;QACtD,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAA;IACtE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AACzC,CAAC"}

package/dist/ai/vision-prep.d.ts

@@ -0,0 +1,32 @@
+/** Default long-edge cap. Per-call override available via `maxEdge`. */
+export declare const MAX_EDGE = 768;
+export interface PrepareInput {
+    /** Source bytes (raw asset bytes, post-preprocess). */
+    bytes: Uint8Array;
+    /** Source MIME type from the asset manifest. */
+    mime: string;
+    /**
+     * For animated images, the analyzer's extracted first-frame poster
+     * bytes (always PNG). When provided, used directly — no further
+     * rasterization. Skip for static images.
+     */
+    posterBytes?: Uint8Array;
+    /** Long-edge cap override; defaults to {@link MAX_EDGE}. */
+    maxEdge?: number;
+}
+export interface PreparedImage {
+    /** Bytes ready to send to a vision provider. */
+    bytes: Uint8Array;
+    /** MIME of the prepared bytes — `image/jpeg` or `image/png`. */
+    mime: string;
+}
+/**
+ * Prepare image bytes for a vision-call. Single async call that picks
+ * the right code path based on input.
+ *
+ * Throws on hard failures (corrupt source bytes that sharp can't
+ * decode, even past metadata). Callers wrap in their adapter's error
+ * taxonomy.
+ */
+export declare function prepareForVision(input: PrepareInput): Promise<PreparedImage>;
+//# sourceMappingURL=vision-prep.d.ts.map

package/dist/ai/vision-prep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-prep.d.ts","sourceRoot":"","sources":["../../src/ai/vision-prep.ts"],"names":[],"mappings":"AA2DA,wEAAwE;AACxE,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAA;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,KAAK,EAAE,UAAU,CAAA;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;CACb;AAWD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAuClF"}