@nola-lang/providers 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgen Mykhailenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @nola-lang/providers
+
+Everything provider-shaped in [Nola](https://github.com/nola-lang/nola):
+provider factories, resilience combinators, and record/replay.
+
+```ts
+import { defineConfig } from "@nola-lang/runtime";
+import { openai, mockProvider, withRetry, exponential, fallback, record, replay } from "@nola-lang/providers";
+
+export default defineConfig({
+  providers: {
+    default: withRetry(openai({ model: "gpt-5" }), exponential({ maxRetries: 3 })),
+    fast: fallback([openai({ model: "gpt-5-mini" }), openai({ model: "gpt-5-nano" })]),
+    test: replay("./nola.replay.jsonl"),   // record(...) once, replay offline forever
+  },
+});
+```
+
+`openai()` reads `OPENAI_API_KEY` lazily and takes an injectable `fetch`.
+`mockProvider([...])` gives deterministic, network-free answers for tests.

package/dist/combinators.d.ts

@@ -0,0 +1,32 @@
+import type { NolaProvider } from "@nola-lang/core";
+export interface RetryPolicy {
+    maxRetries: number;
+    delayMs: number;
+    multiplier: number;
+    maxDelayMs: number;
+}
+export declare function constant(opts: {
+    maxRetries: number;
+    delayMs?: number;
+}): RetryPolicy;
+export declare function exponential(opts: {
+    maxRetries: number;
+    delayMs?: number;
+    multiplier?: number;
+    maxDelayMs?: number;
+}): RetryPolicy;
+/** Definitive errors must not be retried: explicit flag, or HTTP 4xx except 408/429. */
+export declare function isDefinitiveProviderError(error: unknown): boolean;
+/**
+ * Wire-level retry: re-attempts the single `provider.complete` call with
+ * backoff, fail-fasting on definitive errors. Honors the provider's
+ * `retryAfterMs` (Retry-After) when it exceeds the scheduled delay, capped at
+ * `policy.maxDelayMs` — so a policy whose maxDelayMs is 0 (e.g. `constant()`
+ * with no delay) ignores the header entirely. Distinct from the intent method
+ * `.withRetry(n)`, which flat-retries the entire ask (composition, provider
+ * call, parse, validation) with no backoff and no definitive-error check.
+ */
+export declare function withRetry(provider: NolaProvider, policy: RetryPolicy): NolaProvider;
+export declare function fallback(providers: NolaProvider[]): NolaProvider;
+export declare function roundRobin(providers: NolaProvider[]): NolaProvider;
+//# sourceMappingURL=combinators.d.ts.map

package/dist/combinators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinators.d.ts","sourceRoot":"","sources":["../src/combinators.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAGpF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,WAAW,CAOd;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKjE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAoBnF;AAED,wBAAgB,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,YAAY,CAiBhE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,YAAY,CAoBlE"}

package/dist/combinators.js

@@ -0,0 +1,108 @@
+import { Codes } from "@nola-lang/ast";
+import { NolaConfigError, NolaProviderError } from "@nola-lang/core";
+export function constant(opts) {
+    const delayMs = opts.delayMs ?? 0;
+    return { maxRetries: opts.maxRetries, delayMs, multiplier: 1, maxDelayMs: delayMs };
+}
+export function exponential(opts) {
+    return {
+        maxRetries: opts.maxRetries,
+        delayMs: opts.delayMs ?? 200,
+        multiplier: opts.multiplier ?? 2,
+        maxDelayMs: opts.maxDelayMs ?? 10_000,
+    };
+}
+/** Definitive errors must not be retried: explicit flag, or HTTP 4xx except 408/429. */
+export function isDefinitiveProviderError(error) {
+    if (!(error instanceof NolaProviderError))
+        return false;
+    if (error.definitive)
+        return true;
+    const s = error.status;
+    return s !== undefined && s >= 400 && s < 500 && s !== 408 && s !== 429;
+}
+function sleep(ms) {
+    return ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
+}
+function requireProviders(providers, combinator) {
+    if (providers.length === 0) {
+        throw new NolaConfigError(`${combinator}([]) needs at least one provider.`, Codes.ConfigInvalid);
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Wire-level retry: re-attempts the single `provider.complete` call with
+ * backoff, fail-fasting on definitive errors. Honors the provider's
+ * `retryAfterMs` (Retry-After) when it exceeds the scheduled delay, capped at
+ * `policy.maxDelayMs` — so a policy whose maxDelayMs is 0 (e.g. `constant()`
+ * with no delay) ignores the header entirely. Distinct from the intent method
+ * `.withRetry(n)`, which flat-retries the entire ask (composition, provider
+ * call, parse, validation) with no backoff and no definitive-error check.
+ */
+export function withRetry(provider, policy) {
+    return {
+        name: `retry(${provider.name})`,
+        async complete(req) {
+            let delay = policy.delayMs;
+            let lastError;
+            for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+                try {
+                    return await provider.complete(req);
+                }
+                catch (error) {
+                    lastError = error;
+                    if (isDefinitiveProviderError(error) || attempt === policy.maxRetries)
+                        throw error;
+                    const retryAfterMs = error instanceof NolaProviderError ? (error.retryAfterMs ?? 0) : 0;
+                    await sleep(Math.min(Math.max(delay, retryAfterMs), policy.maxDelayMs));
+                    delay = Math.min(delay * policy.multiplier, policy.maxDelayMs);
+                }
+            }
+            throw lastError; // unreachable; satisfies control-flow analysis
+        },
+    };
+}
+export function fallback(providers) {
+    requireProviders(providers, "fallback");
+    const name = `fallback(${providers.map((p) => p.name).join(", ")})`;
+    return {
+        name,
+        async complete(req) {
+            const failures = [];
+            for (const p of providers) {
+                try {
+                    return await p.complete(req);
+                }
+                catch (error) {
+                    failures.push(`${p.name}: ${describeError(error)}`);
+                }
+            }
+            throw new NolaProviderError(`${name}: all providers failed —\n  ${failures.join("\n  ")}`);
+        },
+    };
+}
+export function roundRobin(providers) {
+    requireProviders(providers, "roundRobin");
+    const name = `roundRobin(${providers.map((p) => p.name).join(", ")})`;
+    let nextStart = 0;
+    return {
+        name,
+        async complete(req) {
+            const start = nextStart++ % providers.length;
+            const failures = [];
+            for (let i = 0; i < providers.length; i++) {
+                const p = providers[(start + i) % providers.length];
+                try {
+                    return await p.complete(req);
+                }
+                catch (error) {
+                    failures.push(`${p.name}: ${describeError(error)}`);
+                }
+            }
+            throw new NolaProviderError(`${name}: all providers failed —\n  ${failures.join("\n  ")}`);
+        },
+    };
+}
+//# sourceMappingURL=combinators.js.map

package/dist/combinators.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { mockProvider } from "./mock.js";
+import { openai } from "./openai.js";
+export { constant, exponential, fallback, isDefinitiveProviderError, type RetryPolicy, roundRobin, withRetry, } from "./combinators.js";
+export { mockProvider } from "./mock.js";
+export { type OpenAiOptions, openai } from "./openai.js";
+export { record, replay } from "./record-replay.js";
+/** Every built-in provider factory, keyed by the name its provider reports. */
+export declare const providers: {
+    readonly openai: typeof openai;
+    readonly mock: typeof mockProvider;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACL,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,yBAAyB,EACzB,KAAK,WAAW,EAChB,UAAU,EACV,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEpD,+EAA+E;AAC/E,eAAO,MAAM,SAAS;;;CAGZ,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+import { mockProvider } from "./mock.js";
+import { openai } from "./openai.js";
+export { constant, exponential, fallback, isDefinitiveProviderError, roundRobin, withRetry, } from "./combinators.js";
+export { mockProvider } from "./mock.js";
+export { openai } from "./openai.js";
+export { record, replay } from "./record-replay.js";
+/** Every built-in provider factory, keyed by the name its provider reports. */
+export const providers = {
+    openai,
+    mock: mockProvider,
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACL,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,yBAAyB,EAEzB,UAAU,EACV,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAsB,MAAM,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEpD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,MAAM;IACN,IAAI,EAAE,YAAY;CACV,CAAC"}

package/dist/mock.d.ts

@@ -0,0 +1,3 @@
+import type { NolaProvider, ProviderRequest } from "@nola-lang/core";
+export declare function mockProvider(source: unknown[] | ((req: ProviderRequest) => unknown)): NolaProvider;
+//# sourceMappingURL=mock.d.ts.map

package/dist/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../src/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAErE,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,YAAY,CAelG"}

package/dist/mock.js

@@ -0,0 +1,19 @@
+export function mockProvider(source) {
+    const queue = Array.isArray(source) ? [...source] : null;
+    return {
+        name: "mock",
+        async complete(req) {
+            let value;
+            if (queue) {
+                if (queue.length === 0)
+                    throw new Error("mockProvider queue exhausted");
+                value = queue.shift();
+            }
+            else {
+                value = source(req);
+            }
+            return { text: JSON.stringify(value) };
+        },
+    };
+}
+//# sourceMappingURL=mock.js.map

package/dist/mock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.js","sourceRoot":"","sources":["../src/mock.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAAC,MAAuD;IAClF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK,CAAC,QAAQ,CAAC,GAAG;YAChB,IAAI,KAAc,CAAC;YACnB,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBACxE,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,KAAK,GAAI,MAA4C,CAAC,GAAG,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/openai.d.ts

@@ -0,0 +1,12 @@
+import type { NolaProvider } from "@nola-lang/core";
+export interface OpenAiOptions {
+    apiKey?: string;
+    /** Env var name holding the key. Default: "OPENAI_API_KEY". Value is read lazily at the first request. */
+    apiKeyEnv?: string;
+    /** Required — there is no default model; every config names its own. */
+    model: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function openai(options: OpenAiOptions): NolaProvider;
+//# sourceMappingURL=openai.d.ts.map

package/dist/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../src/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGhE,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AA8HD,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAmE3D"}

package/dist/openai.js

@@ -0,0 +1,189 @@
+import { NolaProviderError } from "@nola-lang/core";
+/** Strict mode requires every property required; optionals become anyOf [T, null]. */
+function toStrict(schema) {
+    const out = toStrictNode(schema);
+    // $defs only ever appears at the root of our emissions; transform each def
+    // through the same strict rewrite so refs resolve to strict shapes.
+    if (schema.$defs) {
+        const defs = {};
+        for (const [key, def] of Object.entries(schema.$defs))
+            defs[key] = toStrictNode(def);
+        out.$defs = defs;
+    }
+    return out;
+}
+function toStrictNode(schema) {
+    if ("$ref" in schema)
+        return { $ref: schema.$ref };
+    switch (schema.type) {
+        case "object": {
+            const properties = {};
+            for (const [key, prop] of Object.entries(schema.properties)) {
+                const strict = toStrictNode(prop);
+                properties[key] = schema.required.includes(key) ? strict : { anyOf: [strict, { type: "null" }] };
+            }
+            return { type: "object", properties, required: Object.keys(schema.properties), additionalProperties: false };
+        }
+        case "array":
+            return { type: "array", items: toStrictNode(schema.items) };
+        default:
+            return schema.type === "string" && schema.enum
+                ? { type: "string", enum: [...schema.enum] }
+                : { type: schema.type };
+    }
+}
+// When a scalar/array schema is wrapped in the {value} envelope, the response_format
+// alone only constrains providers that do constrained decoding. Generate-then-validate
+// backends (e.g. Groq) follow the prompt, so the prompt must ask for the envelope too.
+const ENVELOPE_NOTE = ' Because the response schema is wrapped, reply with a JSON object of the form {"value": X} where X is the value that conforms to responseSchema.';
+/**
+ * Generate-then-validate backends return HTTP 400 `json_validate_failed` with the
+ * model's raw output in `error.failed_generation`. When that output is actually the
+ * answer (just unwrapped, or wrapped when we expected bare), recover it instead of
+ * hard-failing; the context layer re-validates it against the real schema.
+ */
+function recoverFailedGeneration(errorBody, enveloped, schema) {
+    let failed;
+    try {
+        failed = JSON.parse(errorBody).error?.failed_generation;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof failed !== "string")
+        return undefined;
+    let gen;
+    try {
+        gen = JSON.parse(failed);
+    }
+    catch {
+        return undefined;
+    }
+    const wrapped = enveloped && gen !== null && typeof gen === "object" && !Array.isArray(gen) && "value" in gen;
+    const value = wrapped ? gen.value : gen;
+    return JSON.stringify(fromStrict(value, schema));
+}
+/** Remove null-valued optionals the strict transport introduced. */
+function fromStrict(value, schema, defs) {
+    const activeDefs = schema.$defs ? { ...defs, ...schema.$defs } : defs;
+    if ("$ref" in schema) {
+        const name = /^#\/\$defs\/(.+)$/.exec(schema.$ref)?.[1];
+        const target = name ? activeDefs?.[name] : undefined;
+        // Data-driven recursion: each step consumes value structure, so it terminates.
+        return target ? fromStrict(value, target, activeDefs) : value;
+    }
+    if (schema.type === "object" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            const propSchema = schema.properties[key];
+            if (v === null && propSchema && !schema.required.includes(key))
+                continue;
+            out[key] = propSchema ? fromStrict(v, propSchema, activeDefs) : v;
+        }
+        return out;
+    }
+    if (schema.type === "array" && Array.isArray(value)) {
+        return value.map((item) => fromStrict(item, schema.items, activeDefs));
+    }
+    return value;
+}
+/** Follow root-level $ref chains so the envelope decision sees the real shape. */
+function resolveRootRef(schema) {
+    let current = schema;
+    const defs = schema.$defs;
+    for (let i = 0; i < 32 && "$ref" in current; i++) {
+        const name = /^#\/\$defs\/(.+)$/.exec(current.$ref)?.[1];
+        const next = name ? defs?.[name] : undefined;
+        if (!next)
+            break;
+        current = next;
+    }
+    return current;
+}
+/** Wrap a non-object schema in the {value} envelope, hoisting $defs to the new root. */
+function envelope(schema) {
+    const { $defs, ...rest } = schema;
+    return {
+        type: "object",
+        properties: { value: rest },
+        required: ["value"],
+        additionalProperties: false,
+        ...($defs ? { $defs } : {}),
+    };
+}
+/** Retry-After is either delta-seconds or an HTTP-date; both become a ms delta. */
+function parseRetryAfter(header) {
+    if (header === null || header.trim() === "")
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+export function openai(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const baseUrl = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    const model = options.model;
+    return {
+        name: "openai",
+        async complete(req) {
+            const requestedAt = Date.now();
+            const envName = options.apiKeyEnv ?? "OPENAI_API_KEY";
+            const apiKey = options.apiKey ?? process.env[envName];
+            if (!apiKey) {
+                throw new NolaProviderError(`OpenAI API key not found: environment variable ${envName} is not set (checked process.env, including the project .env applied by the Nola loader) and no \`apiKey\` was passed to openai(). Fix: set ${envName}, or pass openai({ apiKeyEnv: "MY_VAR" }) or openai({ apiKey }) in nola.config.ts.`, { definitive: true });
+            }
+            const reqSchema = req.output.syntax === "json" ? req.output.schema : undefined;
+            const rootShape = reqSchema === undefined ? undefined : resolveRootRef(reqSchema);
+            const enveloped = rootShape !== undefined && !("$ref" in rootShape) && rootShape.type !== "object";
+            const transport = reqSchema === undefined ? undefined : enveloped ? envelope(reqSchema) : reqSchema;
+            const system = enveloped ? req.system + ENVELOPE_NOTE : req.system;
+            const body = {
+                model,
+                messages: [{ role: "system", content: system }, ...req.messages],
+            };
+            if (transport) {
+                body.response_format = {
+                    type: "json_schema",
+                    json_schema: { name: "nola_extraction", strict: true, schema: toStrict(transport) },
+                };
+            }
+            const res = await doFetch(`${baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify(body),
+                signal: req.signal ?? null,
+            });
+            if (!res.ok) {
+                const errorBody = await res.text();
+                if (reqSchema !== undefined) {
+                    const recovered = recoverFailedGeneration(errorBody, enveloped, reqSchema);
+                    if (recovered !== undefined)
+                        return { text: recovered };
+                }
+                throw new NolaProviderError(`OpenAI request failed: ${res.status} ${res.statusText} — ${errorBody.slice(0, 500)}`, {
+                    status: res.status,
+                    retryAfterMs: parseRetryAfter(res.headers.get("retry-after")),
+                });
+            }
+            const data = (await res.json());
+            const content = data.choices?.[0]?.message?.content;
+            if (typeof content !== "string")
+                throw new NolaProviderError("OpenAI response had no message content.");
+            if (!reqSchema)
+                return { text: content };
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch (e) {
+                throw new NolaProviderError("OpenAI returned non-JSON despite structured outputs.", { cause: e });
+            }
+            const value = enveloped ? parsed.value : parsed;
+            const durationMs = Date.now() - requestedAt;
+            return { text: JSON.stringify(fromStrict(value, reqSchema)), durationMs };
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/openai.js.map

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

package/dist/record-replay.d.ts

@@ -0,0 +1,13 @@
+import type { NolaProvider } from "@nola-lang/core";
+/**
+ * Pass-through provider that appends `{ fingerprint, request, response }` JSONL
+ * entries. The fingerprint is computed from the RAW request (so replay-time
+ * lookups match) and is never redacted; persisted content strings are.
+ */
+export declare function record(inner: NolaProvider, ledgerPath: string): NolaProvider;
+/**
+ * Offline provider serving recorded responses by request fingerprint. Strict:
+ * an unrecorded request is a definitive error, never a silent live call.
+ */
+export declare function replay(ledgerPath: string): NolaProvider;
+//# sourceMappingURL=record-replay.d.ts.map

package/dist/record-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-replay.d.ts","sourceRoot":"","sources":["../src/record-replay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAkB5E;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CA0CvD"}

package/dist/record-replay.js

@@ -0,0 +1,69 @@
+import { appendFileSync, readFileSync } from "node:fs";
+import { Codes } from "@nola-lang/ast";
+import { fingerprintRequest, NolaConfigError, NolaProviderError, redactSecrets } from "@nola-lang/core";
+/**
+ * Pass-through provider that appends `{ fingerprint, request, response }` JSONL
+ * entries. The fingerprint is computed from the RAW request (so replay-time
+ * lookups match) and is never redacted; persisted content strings are.
+ */
+export function record(inner, ledgerPath) {
+    return {
+        name: `record(${inner.name})`,
+        async complete(req) {
+            const res = await inner.complete(req);
+            const entry = {
+                fingerprint: fingerprintRequest(req),
+                request: {
+                    system: redactSecrets(req.system),
+                    messages: req.messages.map((m) => ({ role: m.role, content: redactSecrets(m.content) })),
+                    output: req.output,
+                },
+                response: { text: redactSecrets(res.text) },
+            };
+            appendFileSync(ledgerPath, `${JSON.stringify(entry)}\n`, "utf8");
+            return res;
+        },
+    };
+}
+/**
+ * Offline provider serving recorded responses by request fingerprint. Strict:
+ * an unrecorded request is a definitive error, never a silent live call.
+ */
+export function replay(ledgerPath) {
+    let raw;
+    try {
+        raw = readFileSync(ledgerPath, "utf8");
+    }
+    catch (error) {
+        throw new NolaConfigError(`replay ledger ${ledgerPath} cannot be read: ${error instanceof Error ? error.message : String(error)}`, Codes.ReplayLedgerInvalid);
+    }
+    const entries = new Map();
+    raw.split("\n").forEach((line, i) => {
+        if (line.trim() === "")
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new NolaConfigError(`replay ledger ${ledgerPath}:${i + 1} is not valid JSON.`, Codes.ReplayLedgerInvalid);
+        }
+        const e = parsed;
+        if (typeof e.fingerprint !== "string" || typeof e.response?.text !== "string") {
+            throw new NolaConfigError(`replay ledger ${ledgerPath}:${i + 1} is missing fingerprint or response.text.`, Codes.ReplayLedgerInvalid);
+        }
+        entries.set(e.fingerprint, { text: e.response.text });
+    });
+    return {
+        name: "replay",
+        async complete(req) {
+            const fingerprint = fingerprintRequest(req);
+            const hit = entries.get(fingerprint);
+            if (!hit) {
+                throw new NolaProviderError(`[${Codes.ReplayFingerprintMismatch}] replay ledger ${ledgerPath} has no entry for fingerprint ${fingerprint} — the prompt, schema, or context changed since the ledger was recorded. Re-record it.`, { definitive: true });
+            }
+            return { text: hit.text };
+        },
+    };
+}
+//# sourceMappingURL=record-replay.js.map

package/dist/record-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-replay.js","sourceRoot":"","sources":["../src/record-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAExG;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAmB,EAAE,UAAkB;IAC5D,OAAO;QACL,IAAI,EAAE,UAAU,KAAK,CAAC,IAAI,GAAG;QAC7B,KAAK,CAAC,QAAQ,CAAC,GAAG;YAChB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACtC,MAAM,KAAK,GAAG;gBACZ,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC;gBACpC,OAAO,EAAE;oBACP,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;oBACjC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;oBACxF,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB;gBACD,QAAQ,EAAE,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;aAC5C,CAAC;YACF,cAAc,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACjE,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,UAAkB;IACvC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,iBAAiB,UAAU,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACvG,KAAK,CAAC,mBAAmB,CAC1B,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IACpD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QAClC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO;QAC/B,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CAAC,iBAAiB,UAAU,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAClH,CAAC;QACD,MAAM,CAAC,GAAG,MAAkE,CAAC;QAC7E,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9E,MAAM,IAAI,eAAe,CACvB,iBAAiB,UAAU,IAAI,CAAC,GAAG,CAAC,2CAA2C,EAC/E,KAAK,CAAC,mBAAmB,CAC1B,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,CAAC,QAAQ,CAAC,GAAG;YAChB,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACrC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,iBAAiB,CACzB,IAAI,KAAK,CAAC,yBAAyB,mBAAmB,UAAU,iCAAiC,WAAW,wFAAwF,EACpM,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nola-lang/providers",
+  "version": "0.1.0-alpha.0",
+  "description": "Nola LLM providers: openai, mock, resilience combinators, record/replay",
+  "keywords": [
+    "nola",
+    "llm",
+    "ai",
+    "openai",
+    "providers"
+  ],
+  "license": "MIT",
+  "author": "Evgen Mykhailenko",
+  "homepage": "https://github.com/nola-lang/nola#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nola-lang/nola.git",
+    "directory": "packages/providers"
+  },
+  "bugs": {
+    "url": "https://github.com/nola-lang/nola/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nola-lang/ast": "0.1.0-alpha.0",
+    "@nola-lang/core": "0.1.0-alpha.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}