@sanity/ailf 0.1.0

package/dist/agent-observer/classifier.d.ts

@@ -0,0 +1,62 @@
+/**
+ * classifier.ts
+ *
+ * Classifies raw ObservedRequest records into meaningful categories:
+ *   - Doc page visits (sanity.io/docs/*)
+ *   - Search queries (search endpoints, query params)
+ *   - Sanity API calls (api.sanity.io, apicdn.sanity.io)
+ *   - External requests (everything else)
+ *
+ * Also extracts metadata like doc slugs, search query text, and page titles.
+ */
+import type { ObservedRequest, DocPageVisit, SearchQuery, ApiCall, ExternalRequest } from "./types.js";
+export interface ClassifiedRequests {
+    apiCalls: ApiCall[];
+    docPageVisits: DocPageVisit[];
+    externalRequests: ExternalRequest[];
+    searchQueries: SearchQuery[];
+}
+/**
+ * Classifies an array of raw observed requests into categorized buckets.
+ */
+export declare function classifyRequests(requests: ObservedRequest[]): ClassifiedRequests;
+/**
+ * Extracts the API endpoint path from a Sanity API URL.
+ *
+ * Example:
+ *   https://api.sanity.io/v2021-03-25/data/query/production → "/data/query/production"
+ */
+export declare function extractApiEndpoint(url: string): string;
+/**
+ * Extracts the doc slug from a sanity.io/docs URL.
+ *
+ * Examples:
+ *   https://www.sanity.io/docs/groq-introduction → "groq-introduction"
+ *   https://www.sanity.io/docs/getting-started/create-a-schema → "getting-started/create-a-schema"
+ *   https://www.sanity.io/docs → "" (root docs page)
+ */
+export declare function extractDocSlug(url: string): string;
+/**
+ * Extracts the domain from a URL.
+ */
+export declare function extractDomain(url: string): string;
+/**
+ * Attempts to extract a page title from an HTML response preview.
+ */
+export declare function extractPageTitle(responsePreview?: string): string | undefined;
+/**
+ * Extracts a search query string from a URL or request body.
+ */
+export declare function extractSearchQuery(req: ObservedRequest): string;
+/**
+ * Determines if a request is to a Sanity documentation page.
+ */
+export declare function isDocPageRequest(req: ObservedRequest): boolean;
+/**
+ * Determines if a request is to the Sanity API (not docs).
+ */
+export declare function isSanityApiRequest(req: ObservedRequest): boolean;
+/**
+ * Determines if a request is a search operation.
+ */
+export declare function isSearchRequest(req: ObservedRequest): boolean;

package/dist/agent-observer/classifier.js

@@ -0,0 +1,269 @@
+/**
+ * classifier.ts
+ *
+ * Classifies raw ObservedRequest records into meaningful categories:
+ *   - Doc page visits (sanity.io/docs/*)
+ *   - Search queries (search endpoints, query params)
+ *   - Sanity API calls (api.sanity.io, apicdn.sanity.io)
+ *   - External requests (everything else)
+ *
+ * Also extracts metadata like doc slugs, search query text, and page titles.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Zod schemas for parsed JSON bodies (search request payloads)
+// ---------------------------------------------------------------------------
+/** Single search request item (e.g., Algolia multi-index entry) */
+const SearchRequestItemSchema = z.object({
+    params: z.string().optional(),
+    query: z.string().optional(),
+});
+/** Search body payload — covers Algolia single-query, params-based, and multi-index formats */
+const SearchBodySchema = z.object({
+    params: z.string().optional(),
+    query: z.string().optional(),
+    requests: z.array(SearchRequestItemSchema).optional(),
+});
+// ---------------------------------------------------------------------------
+// URL pattern matchers
+// ---------------------------------------------------------------------------
+/** Matches sanity.io documentation pages */
+const SANITY_DOCS_PATTERN = /^https?:\/\/(r\.jina\.ai\/https?:\/\/)?(www\.)?sanity\.io\/docs(\/[^?#]*)?/;
+/** Matches Sanity API endpoints */
+const SANITY_API_PATTERN = /^https?:\/\/(api|apicdn|cdn)\.sanity\.io/;
+/** Matches sanity.io non-docs pages (blog, plugins, etc.) — including via proxies */
+const SANITY_SITE_PATTERN = /^https?:\/\/(r\.jina\.ai\/https?:\/\/)?(www\.)?sanity\.io/;
+/** Common search endpoint patterns */
+const SEARCH_PATTERNS = [
+    // Sanity docs search (Algolia, custom, etc.)
+    /sanity\.io\/docs.*[?&](q|query|search)=/i,
+    /sanity\.io\/api\/search/i,
+    /sanity\.io\/search/i,
+    // Algolia search (used by many doc sites)
+    /algolia(net)?\.com.*\/quer(y|ies)/i,
+    /algolia(net)?\.com.*\/search/i,
+    // Google / Bing / DuckDuckGo
+    /google\.com\/search/i,
+    /bing\.com\/search/i,
+    /duckduckgo\.com/i,
+    // Jina Reader proxied search URLs
+    /r\.jina\.ai\/https?:\/\/(www\.)?duckduckgo\.com/i,
+    /r\.jina\.ai\/https?:\/\/(www\.)?google\.com\/search/i,
+    /r\.jina\.ai\/https?:\/\/(www\.)?bing\.com\/search/i,
+];
+/**
+ * Classifies an array of raw observed requests into categorized buckets.
+ */
+export function classifyRequests(requests) {
+    const result = {
+        apiCalls: [],
+        docPageVisits: [],
+        externalRequests: [],
+        searchQueries: [],
+    };
+    for (const req of requests) {
+        // Skip failed requests (no response)
+        if (req.statusCode === 0)
+            continue;
+        // Order matters: API calls first (they may have ?query= params that look like searches),
+        // then searches, then doc pages, then external
+        if (isSanityApiRequest(req)) {
+            result.apiCalls.push({
+                endpoint: extractApiEndpoint(req.url),
+                method: req.method,
+                timestamp: req.timestamp,
+                url: req.url,
+            });
+        }
+        else if (isSearchRequest(req)) {
+            result.searchQueries.push({
+                query: extractSearchQuery(req),
+                timestamp: req.timestamp,
+                url: req.url,
+            });
+        }
+        else if (isDocPageRequest(req)) {
+            const slug = extractDocSlug(req.url);
+            result.docPageVisits.push({
+                contentSize: req.responseSize,
+                slug,
+                timestamp: req.timestamp,
+                title: extractPageTitle(req.responsePreview),
+                url: req.url,
+            });
+        }
+        else if (!SANITY_SITE_PATTERN.test(req.url)) {
+            // External request (not on sanity.io at all)
+            result.externalRequests.push({
+                domain: extractDomain(req.url),
+                method: req.method,
+                timestamp: req.timestamp,
+                url: req.url,
+            });
+        }
+        // else: sanity.io non-docs page — we track it in raw requests but don't classify it
+    }
+    return result;
+}
+/**
+ * Extracts the API endpoint path from a Sanity API URL.
+ *
+ * Example:
+ *   https://api.sanity.io/v2021-03-25/data/query/production → "/data/query/production"
+ */
+export function extractApiEndpoint(url) {
+    const match = url.match(/sanity\.io\/(v[\d-]+)?(.*)/);
+    if (!match)
+        return new URL(url).pathname;
+    return match[2] || "/";
+}
+/**
+ * Extracts the doc slug from a sanity.io/docs URL.
+ *
+ * Examples:
+ *   https://www.sanity.io/docs/groq-introduction → "groq-introduction"
+ *   https://www.sanity.io/docs/getting-started/create-a-schema → "getting-started/create-a-schema"
+ *   https://www.sanity.io/docs → "" (root docs page)
+ */
+export function extractDocSlug(url) {
+    const match = url.match(/sanity\.io\/docs\/([^?#]+)/);
+    if (!match)
+        return "";
+    // Remove trailing slash and .md extension
+    return match[1].replace(/\/$/, "").replace(/\.md$/, "");
+}
+// ---------------------------------------------------------------------------
+// Metadata extractors
+// ---------------------------------------------------------------------------
+/**
+ * Extracts the domain from a URL.
+ */
+export function extractDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        const match = url.match(/https?:\/\/([^/?#]+)/);
+        return match ? match[1] : "unknown";
+    }
+}
+/**
+ * Attempts to extract a page title from an HTML response preview.
+ */
+export function extractPageTitle(responsePreview) {
+    if (!responsePreview)
+        return undefined;
+    const match = responsePreview.match(/<title[^>]*>([^<]+)<\/title>/i);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Extracts a search query string from a URL or request body.
+ */
+export function extractSearchQuery(req) {
+    // Handle Jina-proxied URLs by extracting the inner URL's query params
+    // e.g., https://r.jina.ai/https://duckduckgo.com/?q=sanity+schema
+    let searchUrl = req.url;
+    const jinaMatch = req.url.match(/r\.jina\.ai\/(https?:\/\/.+)/);
+    if (jinaMatch) {
+        searchUrl = jinaMatch[1];
+    }
+    // Try URL query parameters first
+    try {
+        const urlObj = new URL(searchUrl);
+        for (const param of ["q", "query", "search", "s"]) {
+            const value = urlObj.searchParams.get(param);
+            if (value)
+                return value;
+        }
+    }
+    catch {
+        // Invalid URL — try regex fallback
+        const match = req.url.match(/[?&](q|query|search|s)=([^&]+)/);
+        if (match)
+            return decodeURIComponent(match[2]);
+    }
+    // Try request body (for POST search requests like Algolia)
+    if (req.body) {
+        try {
+            const bodyObj = SearchBodySchema.parse(JSON.parse(req.body));
+            // Algolia format
+            if (bodyObj.query)
+                return bodyObj.query;
+            if (bodyObj.params) {
+                const params = new URLSearchParams(bodyObj.params);
+                const q = params.get("query");
+                if (q)
+                    return q;
+            }
+            // Array of requests (Algolia multi-index)
+            if (bodyObj.requests) {
+                const queries = bodyObj.requests
+                    .map((r) => {
+                    if (r.query)
+                        return r.query;
+                    if (r.params) {
+                        const p = new URLSearchParams(r.params);
+                        return p.get("query");
+                    }
+                    return null;
+                })
+                    .filter(Boolean);
+                if (queries.length > 0)
+                    return queries.join("; ");
+            }
+        }
+        catch {
+            // Not JSON — ignore
+        }
+    }
+    return "";
+}
+/**
+ * Determines if a request is to a Sanity documentation page.
+ */
+export function isDocPageRequest(req) {
+    return (SANITY_DOCS_PATTERN.test(req.url) &&
+        !isSearchRequest(req) &&
+        req.method === "GET" &&
+        // Filter out static assets
+        !isStaticAsset(req.url));
+}
+/**
+ * Determines if a request is to the Sanity API (not docs).
+ */
+export function isSanityApiRequest(req) {
+    return SANITY_API_PATTERN.test(req.url);
+}
+// ---------------------------------------------------------------------------
+// Full classification pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Determines if a request is a search operation.
+ */
+export function isSearchRequest(req) {
+    // Exclude Sanity API calls — they may have ?query= params (GROQ)
+    if (SANITY_API_PATTERN.test(req.url))
+        return false;
+    // Check URL against search patterns
+    if (SEARCH_PATTERNS.some((p) => p.test(req.url)))
+        return true;
+    // Check POST body for search-like payloads (Algolia, etc.)
+    if (req.method === "POST" && req.body) {
+        try {
+            const bodyObj = SearchBodySchema.safeParse(JSON.parse(req.body));
+            if (bodyObj.success && (bodyObj.data.query || bodyObj.data.requests))
+                return true;
+        }
+        catch {
+            /* not JSON */
+        }
+    }
+    return false;
+}
+/**
+ * Determines if a URL points to a static asset (JS, CSS, images, fonts).
+ */
+function isStaticAsset(url) {
+    const assetExtensions = /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff2?|ttf|eot|map)(\?|$)/i;
+    return assetExtensions.test(url);
+}

package/dist/agent-observer/index.d.ts

@@ -0,0 +1,7 @@
+export { classifyRequests, extractDocSlug, extractSearchQuery, extractApiEndpoint, extractDomain, extractPageTitle, isDocPageRequest, isSearchRequest, isSanityApiRequest, } from "./classifier.js";
+export type { ClassifiedRequests } from "./classifier.js";
+export { calculateCost, formatCost, lookupPricing } from "./pricing.js";
+export { default as InstrumentedProvider } from "./provider.js";
+export { RequestRecorder } from "./proxy.js";
+export type { RecorderOptions } from "./proxy.js";
+export type { ObservedRequest, DocPageVisit, SearchQuery, ApiCall, ExternalRequest, AgentBehaviorLog, AgentBehaviorSummary, } from "./types.js";

package/dist/agent-observer/index.js

@@ -0,0 +1,4 @@
+export { classifyRequests, extractDocSlug, extractSearchQuery, extractApiEndpoint, extractDomain, extractPageTitle, isDocPageRequest, isSearchRequest, isSanityApiRequest, } from "./classifier.js";
+export { calculateCost, formatCost, lookupPricing } from "./pricing.js";
+export { default as InstrumentedProvider } from "./provider.js";
+export { RequestRecorder } from "./proxy.js";

package/dist/agent-observer/pricing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * pricing.ts
+ *
+ * Model pricing lookup and cost calculation for OpenAI and Anthropic models.
+ * Used by custom providers (agentic, instrumented) to calculate
+ * per-request cost from token counts.
+ *
+ * Prices are per-token (not per-million) for simpler arithmetic.
+ * Source: https://openai.com/api/pricing/ and https://docs.anthropic.com/en/docs/about-claude/models
+ */
+interface ModelPricing {
+    /** Cost per input/prompt token */
+    input: number;
+    /** Cost per output/completion token */
+    output: number;
+}
+/**
+ * Calculate the cost in USD for a given model and token usage.
+ * Returns 0 if the model is not in the pricing table.
+ */
+export declare function calculateCost(model: string, promptTokens: number, completionTokens: number): number;
+/**
+ * Format a cost value as a human-readable USD string.
+ * - Under $0.01: shows 4 decimal places (e.g., "$0.0023")
+ * - Under $1: shows 2 decimal places (e.g., "$0.45")
+ * - $1+: shows 2 decimal places (e.g., "$12.50")
+ */
+export declare function formatCost(cost: number): string;
+/**
+ * Look up pricing for a model. Supports exact matches and prefix
+ * matching (e.g., "gpt-4o-2024-08-06" matches "gpt-4o").
+ * Returns undefined if no pricing is found.
+ */
+export declare function lookupPricing(model: string): ModelPricing | undefined;
+export {};

package/dist/agent-observer/pricing.js

@@ -0,0 +1,82 @@
+/**
+ * pricing.ts
+ *
+ * Model pricing lookup and cost calculation for OpenAI and Anthropic models.
+ * Used by custom providers (agentic, instrumented) to calculate
+ * per-request cost from token counts.
+ *
+ * Prices are per-token (not per-million) for simpler arithmetic.
+ * Source: https://openai.com/api/pricing/ and https://docs.anthropic.com/en/docs/about-claude/models
+ */
+// ---------------------------------------------------------------------------
+// Pricing table
+// ---------------------------------------------------------------------------
+/**
+ * Per-token pricing for supported models.
+ * Prices are in USD. Update when providers change pricing or new models
+ * are added to models.yaml.
+ */
+// Source: https://openai.com/api/pricing/ and https://docs.anthropic.com/en/docs/about-claude/models
+const MODEL_PRICING = {
+    // Anthropic models
+    "claude-3.5-sonnet-20241022": {
+        input: 3 / 1_000_000,
+        output: 15 / 1_000_000,
+    },
+    "claude-opus-4-5-20251101": { input: 15 / 1_000_000, output: 75 / 1_000_000 },
+    "claude-opus-4-6": { input: 15 / 1_000_000, output: 75 / 1_000_000 },
+    "claude-sonnet-4-20250514": { input: 3 / 1_000_000, output: 15 / 1_000_000 },
+    // OpenAI models
+    "gpt-4-turbo": { input: 10 / 1_000_000, output: 30 / 1_000_000 },
+    "gpt-4.1": { input: 2 / 1_000_000, output: 8 / 1_000_000 },
+    "gpt-4.1-mini": { input: 0.4 / 1_000_000, output: 1.6 / 1_000_000 },
+    "gpt-4.1-nano": { input: 0.1 / 1_000_000, output: 0.4 / 1_000_000 },
+    "gpt-4o": { input: 2.5 / 1_000_000, output: 10 / 1_000_000 },
+    "gpt-4o-mini": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+    "gpt-5-2025-08-07": { input: 10 / 1_000_000, output: 30 / 1_000_000 },
+    "gpt-5.2": { input: 2 / 1_000_000, output: 8 / 1_000_000 },
+    "gpt-5.4": { input: 2 / 1_000_000, output: 8 / 1_000_000 },
+    "o3-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Calculate the cost in USD for a given model and token usage.
+ * Returns 0 if the model is not in the pricing table.
+ */
+export function calculateCost(model, promptTokens, completionTokens) {
+    const pricing = lookupPricing(model);
+    if (!pricing)
+        return 0;
+    return pricing.input * promptTokens + pricing.output * completionTokens;
+}
+/**
+ * Format a cost value as a human-readable USD string.
+ * - Under $0.01: shows 4 decimal places (e.g., "$0.0023")
+ * - Under $1: shows 2 decimal places (e.g., "$0.45")
+ * - $1+: shows 2 decimal places (e.g., "$12.50")
+ */
+export function formatCost(cost) {
+    if (cost === 0)
+        return "$0.00";
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+/**
+ * Look up pricing for a model. Supports exact matches and prefix
+ * matching (e.g., "gpt-4o-2024-08-06" matches "gpt-4o").
+ * Returns undefined if no pricing is found.
+ */
+export function lookupPricing(model) {
+    // Exact match first
+    if (MODEL_PRICING[model])
+        return MODEL_PRICING[model];
+    // Prefix match: "gpt-4o-2024-08-06" → "gpt-4o"
+    for (const [key, pricing] of Object.entries(MODEL_PRICING)) {
+        if (model.startsWith(key))
+            return pricing;
+    }
+    return undefined;
+}

package/dist/agent-observer/provider.d.ts

@@ -0,0 +1,77 @@
+/**
+ * provider.ts
+ *
+ * Instrumented Promptfoo custom provider that wraps any underlying LLM
+ * provider and records all HTTP activity the agent performs during a task.
+ *
+ * This is the integration point between the observation infrastructure
+ * (RequestRecorder) and Promptfoo's evaluation pipeline. It:
+ *
+ *   1. Starts a recording session before the LLM call
+ *   2. Delegates to the real provider (calls OpenAI directly)
+ *   3. Stops recording and attaches the AgentBehaviorLog to
+ *      ProviderResponse.metadata so it flows through scoring
+ *
+ * Promptfoo config usage:
+ *
+ *   providers:
+ *     - id: file://src/agent-observer/provider.ts
+ *       label: "gpt-4o (observed)"
+ *       config:
+ *         model: gpt-4o
+ *         temperature: 0
+ *         max_tokens: 4096
+ *         observe: true
+ *         observerOptions:
+ *           maxPreviewBytes: 2048
+ *           captureResponsePreview: true
+ *
+ * Promptfoo loads this file and instantiates the default export class.
+ */
+import { RequestRecorder } from "./proxy.js";
+interface CallApiContextParams {
+    prompt?: {
+        raw: string;
+        label?: string;
+    };
+    vars?: Record<string, object | string>;
+}
+interface ProviderOptions {
+    config?: Record<string, unknown>;
+    id?: string;
+}
+interface ProviderResponse {
+    cached?: boolean;
+    cost?: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    output?: object | string;
+    tokenUsage?: {
+        total?: number;
+        prompt?: number;
+        completion?: number;
+        cached?: number;
+    };
+}
+export default class InstrumentedProvider {
+    config: Record<string, unknown>;
+    protected providerId: string;
+    private recorder;
+    constructor(options: ProviderOptions);
+    /**
+     * Main Promptfoo provider entry point. Called for each test case.
+     */
+    callApi(prompt: string, context?: CallApiContextParams): Promise<ProviderResponse>;
+    /**
+     * Exposes the recorder for external integrations (e.g., agents that
+     * make their own HTTP requests outside the provider call).
+     */
+    getRecorder(): RequestRecorder;
+    id(): string;
+    /**
+     * Calls OpenAI Chat Completions API directly. Uses the recorder's
+     * fetch wrapper so the LLM call itself is captured in the observation log.
+     */
+    private callOpenAI;
+}
+export {};

package/dist/agent-observer/provider.js

@@ -0,0 +1,151 @@
+/**
+ * provider.ts
+ *
+ * Instrumented Promptfoo custom provider that wraps any underlying LLM
+ * provider and records all HTTP activity the agent performs during a task.
+ *
+ * This is the integration point between the observation infrastructure
+ * (RequestRecorder) and Promptfoo's evaluation pipeline. It:
+ *
+ *   1. Starts a recording session before the LLM call
+ *   2. Delegates to the real provider (calls OpenAI directly)
+ *   3. Stops recording and attaches the AgentBehaviorLog to
+ *      ProviderResponse.metadata so it flows through scoring
+ *
+ * Promptfoo config usage:
+ *
+ *   providers:
+ *     - id: file://src/agent-observer/provider.ts
+ *       label: "gpt-4o (observed)"
+ *       config:
+ *         model: gpt-4o
+ *         temperature: 0
+ *         max_tokens: 4096
+ *         observe: true
+ *         observerOptions:
+ *           maxPreviewBytes: 2048
+ *           captureResponsePreview: true
+ *
+ * Promptfoo loads this file and instantiates the default export class.
+ */
+import { config as loadDotenv } from "dotenv";
+import { randomUUID } from "crypto";
+import { RequestRecorder } from "./proxy.js";
+import { calculateCost } from "./pricing.js";
+loadDotenv({
+    override: true,
+    path: new URL("../../.env", import.meta.url).pathname,
+});
+// ---------------------------------------------------------------------------
+// Provider implementation
+// ---------------------------------------------------------------------------
+export default class InstrumentedProvider {
+    config;
+    providerId;
+    recorder;
+    constructor(options) {
+        this.providerId = options.id ?? "instrumented-observer";
+        this.config = options.config ?? {};
+        this.recorder = new RequestRecorder(this.config.observerOptions ?? {});
+    }
+    /**
+     * Main Promptfoo provider entry point. Called for each test case.
+     */
+    async callApi(prompt, context) {
+        const sessionId = randomUUID();
+        const taskDescription = context?.vars?.task ||
+            context?.prompt?.label ||
+            "unknown-task";
+        const observe = this.config.observe !== false;
+        // Start observation
+        if (observe) {
+            this.recorder.start(sessionId, this.id(), taskDescription);
+        }
+        let result;
+        try {
+            result = await this.callOpenAI(prompt);
+        }
+        catch (err) {
+            const error = err;
+            result = {
+                error: error.message,
+                output: undefined,
+            };
+        }
+        // Stop observation and attach behavior log
+        if (observe) {
+            const behaviorLog = this.recorder.stop();
+            result.metadata = {
+                ...(result.metadata ?? {}),
+                agentBehavior: behaviorLog,
+                agentBehaviorSummary: behaviorLog.summary,
+            };
+        }
+        return result;
+    }
+    /**
+     * Exposes the recorder for external integrations (e.g., agents that
+     * make their own HTTP requests outside the provider call).
+     */
+    getRecorder() {
+        return this.recorder;
+    }
+    id() {
+        return `instrumented:${this.providerId}`;
+    }
+    /**
+     * Calls OpenAI Chat Completions API directly. Uses the recorder's
+     * fetch wrapper so the LLM call itself is captured in the observation log.
+     */
+    async callOpenAI(prompt) {
+        const model = this.config.model || "gpt-4o";
+        const temperature = this.config.temperature ?? 0;
+        const maxTokens = this.config.max_tokens || 4096;
+        const apiKey = this.config.apiKey || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            return {
+                error: "OPENAI_API_KEY not set. Configure it in env or provider config.",
+                output: undefined,
+            };
+        }
+        // Use the recorder's fetch wrapper so the API call is recorded
+        const fetchFn = this.recorder.isRunning()
+            ? this.recorder.fetch.bind(this.recorder)
+            : globalThis.fetch;
+        const startTime = Date.now();
+        const response = await fetchFn("https://api.openai.com/v1/chat/completions", {
+            body: JSON.stringify({
+                max_tokens: maxTokens,
+                messages: [{ content: prompt, role: "user" }],
+                model,
+                temperature,
+            }),
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            method: "POST",
+        });
+        const data = (await response.json());
+        if (data.error) {
+            return {
+                error: data.error.message ?? "Unknown OpenAI error",
+                output: undefined,
+            };
+        }
+        const output = data.choices?.[0]?.message?.content ?? "";
+        return {
+            cost: calculateCost(model, data.usage?.prompt_tokens ?? 0, data.usage?.completion_tokens ?? 0),
+            metadata: {
+                latencyMs: Date.now() - startTime,
+                model,
+            },
+            output,
+            tokenUsage: {
+                completion: data.usage?.completion_tokens,
+                prompt: data.usage?.prompt_tokens,
+                total: data.usage?.total_tokens,
+            },
+        };
+    }
+}