@sanity/ailf 4.4.0 → 4.6.0

package/dist/_vendor/ailf-core/types/confidence.js

@@ -0,0 +1,49 @@
+/**
+ * Shared confidence contract for actionability-ladder emitters (D0049).
+ *
+ * Every confidence-emitting site in the actionability-ladder design set
+ * (per-document attribution ensemble, structured grader judgments,
+ * diagnosis cards, regression detection) emits the same abstract triple
+ * so consumers can reason about confidence uniformly across emitters.
+ *
+ * Bucket thresholds and the formula behind `level` are emitter-specific;
+ * the externally comparable behavior is the `level` enum. Consumers that
+ * need the underlying mechanic read `derivation` and can branch.
+ */
+/**
+ * Conventional `derivation` identifiers for the seed set of emitters
+ * named in D0049. Re-exported as a typed tuple so consumers and tests can
+ * reference one source of truth instead of redeclaring the literals.
+ *
+ * Adding a new emitter does not require editing this list — `derivation`
+ * is an open tag (see `ConfidenceDerivation`). The list is the
+ * recommended starting set, not the universe.
+ */
+export const CONVENTIONAL_DERIVATIONS = [
+    "ensemble-stdev",
+    "ceiling-cross-check",
+    "regression-gate",
+    "card-type-specific",
+];
+/**
+ * Structural type guard for `Confidence`. Verifies the runtime shape
+ * matches the contract — useful at trust boundaries that can't depend on
+ * a Zod schema (the schema lives at the consuming site since each emitter
+ * picks its own `level` thresholds, but the shape is shared).
+ */
+export function isConfidence(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v.level !== "high" && v.level !== "medium" && v.level !== "low") {
+        return false;
+    }
+    if (typeof v.signalsPresent !== "number" ||
+        !Number.isFinite(v.signalsPresent)) {
+        return false;
+    }
+    if (typeof v.derivation !== "string" || v.derivation.length === 0) {
+        return false;
+    }
+    return true;
+}

package/dist/_vendor/ailf-core/types/index.d.ts

@@ -30,6 +30,8 @@ export type { PipelineRequest, PipelineRequestCallback, PipelineRequestCallerExe
 export type { PackageSurfaceConfig, PackageSurfaceEntry, } from "./package-surface.js";
 export type { SymbolPreflightDeduction, SymbolPreflightFinding, SymbolPreflightReport, SymbolPreflightUnresolvedReason, } from "./symbol-preflight-report.js";
 export { DEFAULT_PREFLIGHT_CODE_CORRECTNESS_WEIGHT, type PreflightRubricContext, type PreflightScoringConfig, } from "./preflight-scoring.js";
+export type { Confidence, ConfidenceDerivation } from "./confidence.js";
+export { CONVENTIONAL_DERIVATIONS, isConfidence } from "./confidence.js";
 export type { ArtifactId, AssociationAxis, AssociationValues, Brand, EntryKey, Err, FixtureId, IdValidationError, NewReportId, Ok, ProviderId, PromptId, Result, ResultId, RubricId, RunFingerprint, RunId, SuiteId, TaskId, TaskSlug, TraceId, } from "./branded-ids.js";
 export { err, fixtureId, generateRunId, ok, providerId, resultId, runId, suiteId, taskId, traceId, } from "./branded-ids.js";
 export type { AgentHarnessTaskDefinition, ContentLakeAuthorableMode, ContentLakeAuthorableTask, CustomTaskDefinition, GeneralizedAssertionDefinition, GeneralizedDocRef, GeneralizedTaskDefinition, GeneralizedTemplatedAssertion, GeneralizedValueAssertion, IdDocRef, KnowledgeProbeTaskDefinition, LiteracyTaskDefinition, MCPServerTaskDefinition, PromptVars, PathDocRef, PerspectiveDocRef, ReservedPromptVarKey, RubricRef, SlugDocRef, TaskCommonFields, TaskDifficulty, TaskOptions, TaskProviderConfig, TaskStatus, } from "./generalized-task.js";

package/dist/_vendor/ailf-core/types/index.js

@@ -17,6 +17,7 @@ export { InMemoryPluginRegistry } from "./plugin-registry.js";
 // the mode-specific version, they import from "./eval-mode-config.js".
 export { evalModeType } from "./eval-mode-config.js";
 export { DEFAULT_PREFLIGHT_CODE_CORRECTNESS_WEIGHT, } from "./preflight-scoring.js";
+export { CONVENTIONAL_DERIVATIONS, isConfidence } from "./confidence.js";
 export { err, fixtureId, generateRunId, ok, providerId, resultId, runId, suiteId, taskId, traceId, } from "./branded-ids.js";
 // ---------------------------------------------------------------------------
 // Comparison (Approach 2: structured comparison output)

package/dist/adapters/llm/anthropic-llm-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Anthropic adapter for the LLMClient port.
+ *
+ * Uses fetch() against the Messages API — same transport pattern as the
+ * existing grader. No SDK dependency. Centralizes retry, rate-limit handling,
+ * cost accounting, and per-call telemetry tagging via `context.feature`.
+ *
+ * Anthropic does not have a first-class JSON mode like OpenAI. For
+ * `completeStructured`, the adapter uses the API's top-level `system`
+ * field to instruct the model to return JSON only (top-level system is
+ * harder for user-controlled content in `prompt` to override than a
+ * user-turn prefix), then strips any surrounding ``` fences before
+ * parsing through the Zod schema (parse-don't-validate).
+ *
+ * Per `.claude/rules/eval-pipeline.md` and `.claude/rules/typescript.md`:
+ * the adapter never reads `process.env`. Typed constructor args only.
+ */
+import { type LLMClient, type LLMCompleteArgs, type LLMCompleteStructuredArgs, type LLMCompletion, type LLMStructuredCompletion, type Logger } from "../../_vendor/ailf-core/index.d.ts";
+import type { ModelPricing } from "./pricing.js";
+import { type RetryPolicy } from "./retry.js";
+export interface AnthropicLLMClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Pricing keyed by canonical model id (without `anthropic:` prefix or `messages:` segment). */
+    pricing?: Record<string, ModelPricing>;
+    retryPolicy?: Partial<RetryPolicy>;
+    logger?: Logger;
+    sleep?: (ms: number) => Promise<void>;
+    rng?: () => number;
+    /** API version header. Default "2023-06-01" — matches the existing grader. */
+    apiVersion?: string;
+}
+export declare class AnthropicLLMClient implements LLMClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly apiVersion;
+    private readonly pricing;
+    private readonly retryPolicy;
+    private readonly logger?;
+    private readonly sleep?;
+    private readonly rng?;
+    constructor(options: AnthropicLLMClientOptions);
+    complete(args: LLMCompleteArgs): Promise<LLMCompletion>;
+    completeStructured<T>(args: LLMCompleteStructuredArgs<T>): Promise<LLMStructuredCompletion<T>>;
+    private callApi;
+    private computeCost;
+    private logTelemetry;
+}

package/dist/adapters/llm/anthropic-llm-client.js

@@ -0,0 +1,205 @@
+/**
+ * Anthropic adapter for the LLMClient port.
+ *
+ * Uses fetch() against the Messages API — same transport pattern as the
+ * existing grader. No SDK dependency. Centralizes retry, rate-limit handling,
+ * cost accounting, and per-call telemetry tagging via `context.feature`.
+ *
+ * Anthropic does not have a first-class JSON mode like OpenAI. For
+ * `completeStructured`, the adapter uses the API's top-level `system`
+ * field to instruct the model to return JSON only (top-level system is
+ * harder for user-controlled content in `prompt` to override than a
+ * user-turn prefix), then strips any surrounding ``` fences before
+ * parsing through the Zod schema (parse-don't-validate).
+ *
+ * Per `.claude/rules/eval-pipeline.md` and `.claude/rules/typescript.md`:
+ * the adapter never reads `process.env`. Typed constructor args only.
+ */
+import { AnthropicResponseSchema, splitModelId, } from "../../_vendor/ailf-core/index.js";
+import { DEFAULT_RETRY_POLICY, parseRetryAfterSeconds, runWithRetry, } from "./retry.js";
+const DEFAULT_BASE_URL = "https://api.anthropic.com/v1/messages";
+const DEFAULT_API_VERSION = "2023-06-01";
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * Pricing reference: https://www.anthropic.com/pricing#api
+ * Update when models or vendor pricing changes.
+ */
+const DEFAULT_PRICING = {
+    "claude-opus-4-6": { inputPer1k: 0.015, outputPer1k: 0.075 },
+    "claude-opus-4-5-20251101": { inputPer1k: 0.015, outputPer1k: 0.075 },
+    "claude-sonnet-4-6": { inputPer1k: 0.003, outputPer1k: 0.015 },
+};
+const STRUCTURED_SYSTEM = "Respond with only a single JSON object that conforms to the requested schema. " +
+    "Do not include any prose, commentary, or markdown code fences. " +
+    "Return raw JSON only.";
+export class AnthropicLLMClient {
+    apiKey;
+    baseUrl;
+    apiVersion;
+    pricing;
+    retryPolicy;
+    logger;
+    sleep;
+    rng;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+        this.pricing = { ...DEFAULT_PRICING, ...(options.pricing ?? {}) };
+        this.retryPolicy = {
+            ...DEFAULT_RETRY_POLICY,
+            ...(options.retryPolicy ?? {}),
+        };
+        if (options.logger)
+            this.logger = options.logger;
+        if (options.sleep)
+            this.sleep = options.sleep;
+        if (options.rng)
+            this.rng = options.rng;
+    }
+    async complete(args) {
+        const { modelName } = splitModelId(args.model);
+        const body = buildBody(modelName, args.prompt, {
+            temperature: args.temperature,
+            maxTokens: args.maxTokens,
+            stop: args.stop,
+        });
+        const data = await this.callApi(body);
+        const text = extractText(data.content);
+        if (text === "") {
+            throw new Error(`Anthropic returned empty completion for model ${args.model}`);
+        }
+        const usage = extractUsage(data.usage);
+        const cost = this.computeCost(modelName, usage);
+        this.logTelemetry(args.context, args.model, usage, cost);
+        return { text, usage, cost, model: args.model };
+    }
+    async completeStructured(args) {
+        const { modelName } = splitModelId(args.model);
+        const body = buildBody(modelName, args.prompt, {
+            temperature: args.temperature,
+            maxTokens: args.maxTokens,
+            system: STRUCTURED_SYSTEM,
+        });
+        const data = await this.callApi(body);
+        const raw = extractText(data.content);
+        if (raw === "") {
+            throw new Error(`Anthropic returned empty structured completion for model ${args.model}`);
+        }
+        const stripped = stripJsonFence(raw);
+        let parsed;
+        try {
+            parsed = JSON.parse(stripped);
+        }
+        catch (err) {
+            throw new Error(`Anthropic structured completion returned invalid JSON for model ${args.model}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        const value = args.schema.parse(parsed);
+        const usage = extractUsage(data.usage);
+        const cost = this.computeCost(modelName, usage);
+        this.logTelemetry(args.context, args.model, usage, cost);
+        return { value, usage, cost, model: args.model };
+    }
+    async callApi(body) {
+        return runWithRetry({
+            policy: this.retryPolicy,
+            ...(this.sleep ? { sleep: this.sleep } : {}),
+            ...(this.rng ? { rng: this.rng } : {}),
+            attempt: async () => {
+                const response = await fetch(this.baseUrl, {
+                    method: "POST",
+                    headers: {
+                        "x-api-key": this.apiKey,
+                        "anthropic-version": this.apiVersion,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    const text = await response.text();
+                    const retryAfter = parseRetryAfterSeconds(response.headers.get("retry-after"));
+                    return {
+                        ok: false,
+                        status: response.status,
+                        body: text,
+                        ...(retryAfter !== undefined
+                            ? { retryAfterSeconds: retryAfter }
+                            : {}),
+                    };
+                }
+                const json = await response.json();
+                const data = AnthropicResponseSchema.parse(json);
+                if (data.error?.message) {
+                    throw new Error(`Anthropic API error: ${data.error.message}`);
+                }
+                return { ok: true, value: data };
+            },
+        });
+    }
+    computeCost(modelName, usage) {
+        const price = this.pricing[modelName];
+        if (!price) {
+            this.logger?.warn(`Anthropic cost unknown for model "${modelName}" — recording cost=0. Add it to AnthropicLLMClientOptions.pricing.`);
+            return 0;
+        }
+        return ((usage.promptTokens / 1000) * price.inputPer1k +
+            (usage.completionTokens / 1000) * price.outputPer1k);
+    }
+    logTelemetry(context, model, usage, cost) {
+        if (!this.logger)
+            return;
+        const tag = context ? ` feature=${context.feature}` : "";
+        const runTag = context?.runId ? ` runId=${context.runId}` : "";
+        const cardTag = context?.cardId ? ` cardId=${context.cardId}` : "";
+        this.logger.debug(`LLM call (anthropic)${tag}${runTag}${cardTag} model=${model} ` +
+            `prompt_tokens=${usage.promptTokens} completion_tokens=${usage.completionTokens} ` +
+            `cost_usd=${cost.toFixed(6)}`);
+    }
+}
+function buildBody(modelName, prompt, opts) {
+    const body = {
+        model: modelName,
+        max_tokens: opts.maxTokens ?? DEFAULT_MAX_TOKENS,
+        messages: [{ role: "user", content: prompt }],
+    };
+    if (opts.temperature !== undefined)
+        body.temperature = opts.temperature;
+    if (opts.stop && opts.stop.length > 0)
+        body.stop_sequences = opts.stop;
+    if (opts.system)
+        body.system = opts.system;
+    return body;
+}
+/**
+ * Concatenate every `text` content block. Anthropic responses can interleave
+ * `text` and `tool_use` blocks; for non-tool calls there's typically one
+ * text block, but joining is the robust default.
+ */
+function extractText(content) {
+    if (!content)
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (block.type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+    }
+    return parts.join("");
+}
+function extractUsage(usage) {
+    return {
+        promptTokens: usage?.input_tokens ?? 0,
+        completionTokens: usage?.output_tokens ?? 0,
+    };
+}
+/**
+ * Strip a single ```json ... ``` or ``` ... ``` fence wrapper if present.
+ * Anthropic occasionally wraps JSON despite the system instruction.
+ */
+function stripJsonFence(text) {
+    const trimmed = text.trim();
+    const fenceMatch = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+    if (fenceMatch)
+        return fenceMatch[1].trim();
+    return trimmed;
+}

package/dist/adapters/llm/fake-llm-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fake LLMClient for tests.
+ *
+ * Returns canned responses in insertion order and records each call so
+ * consumers' tests can assert on prompts, models, and telemetry context.
+ *
+ * Exported alongside the real adapters so consuming-feature tests can
+ * stub the LLM cleanly without a network round-trip.
+ */
+import type { LLMClient, LLMCompleteArgs, LLMCompleteStructuredArgs, LLMCompletion, LLMStructuredCompletion } from "../../_vendor/ailf-core/index.d.ts";
+export interface FakeCallRecord {
+    kind: "complete" | "completeStructured";
+    model: string;
+    prompt: string;
+    context?: {
+        feature: string;
+        runId?: string;
+        cardId?: string;
+    };
+}
+export interface FakeCompletionResponse {
+    text: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    cost?: number;
+}
+export interface FakeStructuredResponse {
+    /**
+     * Value returned to the consumer. Run through the consumer-supplied Zod
+     * schema in `completeStructured` so consumers exercise their parse-don't-
+     * validate path even with the fake; supply a value that matches the
+     * schema's shape (or supply a deliberately malformed one to test failure).
+     */
+    value: unknown;
+    promptTokens?: number;
+    completionTokens?: number;
+    cost?: number;
+}
+export declare class FakeLLMClient implements LLMClient {
+    readonly calls: FakeCallRecord[];
+    private readonly completeQueue;
+    private readonly structuredQueue;
+    constructor(args?: {
+        completeResponses?: FakeCompletionResponse[];
+        structuredResponses?: FakeStructuredResponse[];
+    });
+    complete(args: LLMCompleteArgs): Promise<LLMCompletion>;
+    completeStructured<T>(args: LLMCompleteStructuredArgs<T>): Promise<LLMStructuredCompletion<T>>;
+}

package/dist/adapters/llm/fake-llm-client.js

@@ -0,0 +1,63 @@
+/**
+ * Fake LLMClient for tests.
+ *
+ * Returns canned responses in insertion order and records each call so
+ * consumers' tests can assert on prompts, models, and telemetry context.
+ *
+ * Exported alongside the real adapters so consuming-feature tests can
+ * stub the LLM cleanly without a network round-trip.
+ */
+export class FakeLLMClient {
+    calls = [];
+    completeQueue;
+    structuredQueue;
+    constructor(args = {}) {
+        this.completeQueue = [...(args.completeResponses ?? [])];
+        this.structuredQueue = [...(args.structuredResponses ?? [])];
+    }
+    async complete(args) {
+        this.calls.push({
+            kind: "complete",
+            model: args.model,
+            prompt: args.prompt,
+            ...(args.context ? { context: args.context } : {}),
+        });
+        const next = this.completeQueue.shift();
+        if (!next) {
+            throw new Error("FakeLLMClient: no more queued complete responses (call exceeded queue)");
+        }
+        return {
+            text: next.text,
+            usage: {
+                promptTokens: next.promptTokens ?? 0,
+                completionTokens: next.completionTokens ?? 0,
+            },
+            cost: next.cost ?? 0,
+            model: args.model,
+        };
+    }
+    async completeStructured(args) {
+        this.calls.push({
+            kind: "completeStructured",
+            model: args.model,
+            prompt: args.prompt,
+            ...(args.context ? { context: args.context } : {}),
+        });
+        const next = this.structuredQueue.shift();
+        if (!next) {
+            throw new Error("FakeLLMClient: no more queued structured responses (call exceeded queue)");
+        }
+        // Run through the consumer-supplied schema so consumers exercise the
+        // parse-don't-validate path even with the fake.
+        const value = args.schema.parse(next.value);
+        return {
+            value,
+            usage: {
+                promptTokens: next.promptTokens ?? 0,
+                completionTokens: next.completionTokens ?? 0,
+            },
+            cost: next.cost ?? 0,
+            model: args.model,
+        };
+    }
+}

package/dist/adapters/llm/index.d.ts

@@ -0,0 +1,9 @@
+export { AnthropicLLMClient } from "./anthropic-llm-client.js";
+export type { AnthropicLLMClientOptions } from "./anthropic-llm-client.js";
+export { FakeLLMClient } from "./fake-llm-client.js";
+export type { FakeCallRecord, FakeCompletionResponse, FakeStructuredResponse, } from "./fake-llm-client.js";
+export { OpenAILLMClient } from "./openai-llm-client.js";
+export type { OpenAILLMClientOptions } from "./openai-llm-client.js";
+export type { ModelPricing } from "./pricing.js";
+export { DEFAULT_RETRY_POLICY, LLMHttpError, isRetryableStatus, parseRetryAfterSeconds, runWithRetry, } from "./retry.js";
+export type { RetryPolicy } from "./retry.js";

package/dist/adapters/llm/index.js

@@ -0,0 +1,4 @@
+export { AnthropicLLMClient } from "./anthropic-llm-client.js";
+export { FakeLLMClient } from "./fake-llm-client.js";
+export { OpenAILLMClient } from "./openai-llm-client.js";
+export { DEFAULT_RETRY_POLICY, LLMHttpError, isRetryableStatus, parseRetryAfterSeconds, runWithRetry, } from "./retry.js";

package/dist/adapters/llm/openai-llm-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAI adapter for the LLMClient port.
+ *
+ * Uses fetch() against the Chat Completions API — same transport pattern as
+ * the existing grader (`packages/eval/src/pipeline/grader-api.ts`). No SDK
+ * dependency. Centralizes retry, rate-limit handling, cost accounting, and
+ * per-call telemetry tagging via `context.feature`.
+ *
+ * Per `.claude/rules/eval-pipeline.md` and `.claude/rules/typescript.md`:
+ * the adapter never reads `process.env`. The composition root maps env vars
+ * to typed constructor args.
+ */
+import { type LLMClient, type LLMCompleteArgs, type LLMCompleteStructuredArgs, type LLMCompletion, type LLMStructuredCompletion, type Logger } from "../../_vendor/ailf-core/index.d.ts";
+import type { ModelPricing } from "./pricing.js";
+import { type RetryPolicy } from "./retry.js";
+export interface OpenAILLMClientOptions {
+    /** OpenAI API key. */
+    apiKey: string;
+    /** Optional override of the chat-completions endpoint. */
+    baseUrl?: string;
+    /** Pricing table keyed by canonical model id (without the `openai:` prefix). */
+    pricing?: Record<string, ModelPricing>;
+    retryPolicy?: Partial<RetryPolicy>;
+    logger?: Logger;
+    /** Sleep injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Random source for jitter — injectable for tests. */
+    rng?: () => number;
+}
+export declare class OpenAILLMClient implements LLMClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly pricing;
+    private readonly retryPolicy;
+    private readonly logger?;
+    private readonly sleep?;
+    private readonly rng?;
+    constructor(options: OpenAILLMClientOptions);
+    complete(args: LLMCompleteArgs): Promise<LLMCompletion>;
+    completeStructured<T>(args: LLMCompleteStructuredArgs<T>): Promise<LLMStructuredCompletion<T>>;
+    private callApi;
+    private computeCost;
+    private logTelemetry;
+}

package/dist/adapters/llm/openai-llm-client.js

@@ -0,0 +1,168 @@
+/**
+ * OpenAI adapter for the LLMClient port.
+ *
+ * Uses fetch() against the Chat Completions API — same transport pattern as
+ * the existing grader (`packages/eval/src/pipeline/grader-api.ts`). No SDK
+ * dependency. Centralizes retry, rate-limit handling, cost accounting, and
+ * per-call telemetry tagging via `context.feature`.
+ *
+ * Per `.claude/rules/eval-pipeline.md` and `.claude/rules/typescript.md`:
+ * the adapter never reads `process.env`. The composition root maps env vars
+ * to typed constructor args.
+ */
+import { OpenAIChatResponseSchema, splitModelId, } from "../../_vendor/ailf-core/index.js";
+import { DEFAULT_RETRY_POLICY, parseRetryAfterSeconds, runWithRetry, } from "./retry.js";
+const DEFAULT_BASE_URL = "https://api.openai.com/v1/chat/completions";
+/**
+ * Conservative defaults for the models in `packages/eval/config/models.ts`.
+ * Update when models are added or vendor pricing changes. Unknown models
+ * fall through to `cost: 0` with a warning logged.
+ *
+ * Pricing reference: https://openai.com/api/pricing
+ */
+const DEFAULT_PRICING = {
+    "gpt-5.2": { inputPer1k: 0.005, outputPer1k: 0.015 },
+    "gpt-5": { inputPer1k: 0.005, outputPer1k: 0.015 },
+    "gpt-5.4": { inputPer1k: 0.005, outputPer1k: 0.015 },
+};
+export class OpenAILLMClient {
+    apiKey;
+    baseUrl;
+    pricing;
+    retryPolicy;
+    logger;
+    sleep;
+    rng;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.pricing = { ...DEFAULT_PRICING, ...(options.pricing ?? {}) };
+        this.retryPolicy = {
+            ...DEFAULT_RETRY_POLICY,
+            ...(options.retryPolicy ?? {}),
+        };
+        if (options.logger)
+            this.logger = options.logger;
+        if (options.sleep)
+            this.sleep = options.sleep;
+        if (options.rng)
+            this.rng = options.rng;
+    }
+    async complete(args) {
+        const { modelName } = splitModelId(args.model);
+        const body = buildBody(modelName, args.prompt, {
+            temperature: args.temperature,
+            maxTokens: args.maxTokens,
+            stop: args.stop,
+        });
+        const data = await this.callApi(body);
+        const text = data.choices?.[0]?.message?.content;
+        if (text == null || text === "") {
+            throw new Error(`OpenAI returned empty completion for model ${args.model}`);
+        }
+        const usage = extractUsage(data.usage);
+        const cost = this.computeCost(modelName, usage);
+        this.logTelemetry(args.context, args.model, usage, cost);
+        return { text, usage, cost, model: args.model };
+    }
+    async completeStructured(args) {
+        const { modelName } = splitModelId(args.model);
+        const body = buildBody(modelName, args.prompt, {
+            temperature: args.temperature,
+            maxTokens: args.maxTokens,
+            responseFormat: { type: "json_object" },
+        });
+        const data = await this.callApi(body);
+        const raw = data.choices?.[0]?.message?.content;
+        if (raw == null || raw === "") {
+            throw new Error(`OpenAI returned empty structured completion for model ${args.model}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`OpenAI structured completion returned invalid JSON for model ${args.model}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        const value = args.schema.parse(parsed);
+        const usage = extractUsage(data.usage);
+        const cost = this.computeCost(modelName, usage);
+        this.logTelemetry(args.context, args.model, usage, cost);
+        return { value, usage, cost, model: args.model };
+    }
+    async callApi(body) {
+        return runWithRetry({
+            policy: this.retryPolicy,
+            ...(this.sleep ? { sleep: this.sleep } : {}),
+            ...(this.rng ? { rng: this.rng } : {}),
+            attempt: async () => {
+                const response = await fetch(this.baseUrl, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    const text = await response.text();
+                    const retryAfter = parseRetryAfterSeconds(response.headers.get("retry-after"));
+                    return {
+                        ok: false,
+                        status: response.status,
+                        body: text,
+                        ...(retryAfter !== undefined
+                            ? { retryAfterSeconds: retryAfter }
+                            : {}),
+                    };
+                }
+                const json = await response.json();
+                const data = OpenAIChatResponseSchema.parse(json);
+                if (data.error?.message) {
+                    throw new Error(`OpenAI API error: ${data.error.message}`);
+                }
+                return { ok: true, value: data };
+            },
+        });
+    }
+    computeCost(modelName, usage) {
+        const price = this.pricing[modelName];
+        if (!price) {
+            this.logger?.warn(`OpenAI cost unknown for model "${modelName}" — recording cost=0. Add it to OpenAILLMClientOptions.pricing.`);
+            return 0;
+        }
+        return ((usage.promptTokens / 1000) * price.inputPer1k +
+            (usage.completionTokens / 1000) * price.outputPer1k);
+    }
+    logTelemetry(context, model, usage, cost) {
+        if (!this.logger)
+            return;
+        const tag = context ? ` feature=${context.feature}` : "";
+        const runTag = context?.runId ? ` runId=${context.runId}` : "";
+        const cardTag = context?.cardId ? ` cardId=${context.cardId}` : "";
+        this.logger.debug(`LLM call (openai)${tag}${runTag}${cardTag} model=${model} ` +
+            `prompt_tokens=${usage.promptTokens} completion_tokens=${usage.completionTokens} ` +
+            `cost_usd=${cost.toFixed(6)}`);
+    }
+}
+function buildBody(modelName, prompt, opts) {
+    const body = {
+        model: modelName,
+        messages: [{ role: "user", content: prompt }],
+    };
+    if (opts.temperature !== undefined)
+        body.temperature = opts.temperature;
+    if (opts.maxTokens !== undefined)
+        body.max_tokens = opts.maxTokens;
+    if (opts.stop && opts.stop.length > 0)
+        body.stop = opts.stop;
+    if (opts.responseFormat)
+        body.response_format = opts.responseFormat;
+    return body;
+}
+function extractUsage(usage) {
+    return {
+        promptTokens: usage?.prompt_tokens ?? 0,
+        completionTokens: usage?.completion_tokens ?? 0,
+    };
+}

package/dist/adapters/llm/pricing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-model pricing types shared by LLM adapters.
+ *
+ * Hard-coded vendor pricing drifts; treat the in-adapter defaults as a
+ * sensible starting point and override via constructor options when the
+ * vendor changes their rate card.
+ */
+/** USD per 1K tokens. */
+export interface ModelPricing {
+    inputPer1k: number;
+    outputPer1k: number;
+}