@nola-lang/providers 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -2,12 +2,14 @@ import { anthropic } from "./anthropic.js";
 import { google } from "./google.js";
 import { mockProvider } from "./mock.js";
 import { openai } from "./openai.js";
+import { typesafe } from "./typesafe.js";
 export { type AnthropicOptions, anthropic } from "./anthropic.js";
 export { constant, exponential, fallback, isDefinitiveProviderError, type RetryPolicy, roundRobin, withRetry, } from "./combinators.js";
 export { type GoogleOptions, google } from "./google.js";
 export { type MockRequest, mockProvider } from "./mock.js";
 export { type OpenAiOptions, openai } from "./openai.js";
 export { record, replay } from "./record-replay.js";
+export { type TypesafeOptions, typesafe } from "./typesafe.js";
 /**
  * Every bring-your-own provider factory, keyed by the name its provider
  * reports. The platform model is not here: `nola.infer()` lives in
@@ -17,6 +19,7 @@ export declare const providers: {
     readonly anthropic: typeof anthropic;
     readonly google: typeof google;
     readonly openai: typeof openai;
+    readonly typesafe: typeof typesafe;
     readonly mock: typeof mockProvider;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,12 +2,14 @@ import { anthropic } from "./anthropic.js";
 import { google } from "./google.js";
 import { mockProvider } from "./mock.js";
 import { openai } from "./openai.js";
+import { typesafe } from "./typesafe.js";
 export { anthropic } from "./anthropic.js";
 export { constant, exponential, fallback, isDefinitiveProviderError, roundRobin, withRetry, } from "./combinators.js";
 export { google } from "./google.js";
 export { mockProvider } from "./mock.js";
 export { openai } from "./openai.js";
 export { record, replay } from "./record-replay.js";
+export { typesafe } from "./typesafe.js";
 /**
  * Every bring-your-own provider factory, keyed by the name its provider
  * reports. The platform model is not here: `nola.infer()` lives in
@@ -17,6 +19,7 @@ export const providers = {
     anthropic,
     google,
     openai,
+    typesafe,
     mock: mockProvider,
 };
 //# sourceMappingURL=index.js.map

package/dist/typesafe-questions.d.ts

@@ -0,0 +1,36 @@
+import type { JsonSchema } from "@nola-lang/core";
+/** One question as `POST /v1/systemone` takes it. Only the two primitives Nola output types can express. */
+export type TypesafeQuestion = {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+} | {
+    type: "noul";
+    instructions: string;
+};
+export type DecodeResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Turns the wire answer for one question into the JSON value the ask expects. */
+export type Decoder = (answer: unknown) => DecodeResult;
+export interface QuestionPlan {
+    /** keyed by property name, or "value" for a scalar root */
+    questions: Record<string, TypesafeQuestion>;
+    decode: Record<string, Decoder>;
+    /** true ⇔ the reply is the bare "value" answer, not an object of answers */
+    scalar: boolean;
+}
+export type MappingResult = {
+    ok: true;
+    plan: QuestionPlan;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The questions and decoders for an ask's output schema, or why Jev cannot serve it. */
+export declare function questionsFor(schema: JsonSchema | undefined): MappingResult;
+//# sourceMappingURL=typesafe-questions.d.ts.map

package/dist/typesafe-questions.js

@@ -0,0 +1,124 @@
+const SERVES = "typesafe() serves only literal unions and booleans";
+const SCALAR_INSTRUCTIONS = "Determine the value the request asks for.";
+function fail(reason) {
+    return { ok: false, reason };
+}
+/** `labels` maps each wire label to the JSON value it stands for (the literal itself, or its number). */
+function choiceQuestion(key, instructions, labels) {
+    const criteria = {};
+    for (const label of labels.keys())
+        criteria[label] = label;
+    const decode = (answer) => {
+        if (answer === undefined || answer === null)
+            return fail(`answer "${key}" is missing from the reply`);
+        const choice = answer.choice;
+        if (typeof choice !== "string" || !labels.has(choice)) {
+            return fail(`answer "${key}" chose ${JSON.stringify(choice)}, which is not one of the options sent`);
+        }
+        return { ok: true, value: labels.get(choice) };
+    };
+    return { ok: true, question: { type: "choice", instructions, criteria }, decode };
+}
+function noulQuestion(key, instructions) {
+    const decode = (answer) => {
+        if (answer === undefined || answer === null)
+            return fail(`answer "${key}" is missing from the reply`);
+        const noul = answer.noul;
+        if (typeof noul !== "number" || Number.isNaN(noul))
+            return fail(`answer "${key}" has no numeric noul`);
+        return { ok: true, value: noul >= 0.5 };
+    };
+    return { ok: true, question: { type: "noul", instructions }, decode };
+}
+/** Follow a `$ref` chain through the root `$defs`; the FIRST description seen along the chain wins. */
+function resolve(node, defs, path) {
+    let current = node;
+    let description = node.description;
+    const seen = new Set();
+    while ("$ref" in current) {
+        const ref = current.$ref;
+        if (seen.has(ref))
+            return fail(`${path} is a cyclic reference ${JSON.stringify(ref)}; ${SERVES}`);
+        seen.add(ref);
+        const name = /^#\/\$defs\/(.+)$/.exec(ref)?.[1];
+        const next = name ? defs?.[name] : undefined;
+        if (!next)
+            return fail(`${path} is an unresolved reference ${JSON.stringify(ref)}; ${SERVES}`);
+        current = next;
+        description ??= current.description;
+    }
+    return description === undefined ? { ok: true, node: current } : { ok: true, node: current, description };
+}
+/** What an unsupported node is, in the words of the failure reason. */
+function kindOf(node) {
+    if ("const" in node)
+        return "a single literal";
+    if ("anyOf" in node)
+        return "a union that is not all string literals or all number literals";
+    if ("type" in node) {
+        switch (node.type) {
+            case "string":
+                return node.format === "date-time" ? "a date-time string" : "a free-form string";
+            case "number":
+            case "integer":
+                return "a number";
+            case "array":
+                return "an array";
+            case "object":
+                return "properties" in node ? "a nested object" : "a record";
+            case "null":
+                return "null";
+        }
+    }
+    return "an unsupported shape";
+}
+/** Map one schema node to a question. `path` names the node in failure reasons; `key` is the answer key. */
+function questionFor(raw, defs, path, key) {
+    const resolved = resolve(raw, defs, path);
+    if (!resolved.ok)
+        return resolved;
+    const { node, description } = resolved;
+    const instructions = description ?? (key === "value" ? SCALAR_INSTRUCTIONS : `Determine "${key}".`);
+    if ("type" in node && node.type === "boolean")
+        return noulQuestion(key, instructions);
+    if ("type" in node && node.type === "string" && node.enum) {
+        return choiceQuestion(key, instructions, new Map(node.enum.map((label) => [label, label])));
+    }
+    if ("anyOf" in node && node.anyOf.length >= 2) {
+        const consts = node.anyOf.map((branch) => ("const" in branch ? branch.const : undefined));
+        if (consts.every((c) => typeof c === "string")) {
+            return choiceQuestion(key, instructions, new Map(consts.map((c) => [c, c])));
+        }
+        if (consts.every((c) => typeof c === "number")) {
+            return choiceQuestion(key, instructions, new Map(consts.map((c) => [String(c), c])));
+        }
+    }
+    return fail(`${path} is ${kindOf(node)}; ${SERVES}`);
+}
+/** The questions and decoders for an ask's output schema, or why Jev cannot serve it. */
+export function questionsFor(schema) {
+    if (!schema)
+        return fail(`the ask has no output schema (free text); ${SERVES}`);
+    const defs = "$defs" in schema ? schema.$defs : undefined;
+    const root = resolve(schema, defs, "the output type");
+    if (!root.ok)
+        return root;
+    const node = root.node;
+    if ("type" in node && node.type === "object" && "properties" in node) {
+        const questions = {};
+        const decode = {};
+        for (const [name, prop] of Object.entries(node.properties)) {
+            const mapped = questionFor(prop, defs, `output property ${JSON.stringify(name)}`, name);
+            if (!mapped.ok)
+                return mapped;
+            questions[name] = mapped.question;
+            decode[name] = mapped.decode;
+        }
+        return { ok: true, plan: { questions, decode, scalar: false } };
+    }
+    const mapped = questionFor(schema, defs, "the output type", "value");
+    if (!mapped.ok)
+        return mapped;
+    return { ok: true, plan: { questions: { value: mapped.question }, decode: { value: mapped.decode }, scalar: true } };
+}
+//# sourceMappingURL=typesafe-questions.js.map

package/dist/typesafe.d.ts

@@ -0,0 +1,21 @@
+import type { LanguageModel } from "@nola-lang/core";
+export interface TypesafeOptions {
+    apiKey?: string;
+    /** Env var name holding the key. Default: "TYPESAFE_API_KEY". Value is read lazily at the first request. */
+    apiKeyEnv?: string;
+    /** Default: "jev-latest" — this vendor ships one model, so a bare `typesafe()` is the documented form. */
+    model?: string;
+    /** Default: "https://api.typesafe.ai" */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * typesafe.ai's System One API (model Jev): not a chat model. One request
+ * answers named choice / noul questions about a `state`, so this factory
+ * serves exactly the asks whose output type is literal unions and
+ * booleans (see `questionsFor`) and fails definitively — before the
+ * network — on anything else, which is what lets `fallback([typesafe(),
+ * openai("…")])` escalate. A bare string is shorthand for `{ model }`.
+ */
+export declare function typesafe(optionsOrModel?: TypesafeOptions | string): LanguageModel;
+//# sourceMappingURL=typesafe.d.ts.map

package/dist/typesafe.js

@@ -0,0 +1,71 @@
+import { joinBlocks, NolaProviderError, parseRetryAfter } from "@nola-lang/core";
+import { questionsFor } from "./typesafe-questions.js";
+const DEFAULT_MODEL = "jev-latest";
+const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+/**
+ * typesafe.ai's System One API (model Jev): not a chat model. One request
+ * answers named choice / noul questions about a `state`, so this factory
+ * serves exactly the asks whose output type is literal unions and
+ * booleans (see `questionsFor`) and fails definitively — before the
+ * network — on anything else, which is what lets `fallback([typesafe(),
+ * openai("…")])` escalate. A bare string is shorthand for `{ model }`.
+ */
+export function typesafe(optionsOrModel) {
+    const options = typeof optionsOrModel === "string" ? { model: optionsOrModel } : (optionsOrModel ?? {});
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    const model = options.model ?? DEFAULT_MODEL;
+    return {
+        name: "typesafe",
+        async complete(req) {
+            const requestedAt = Date.now();
+            const envName = options.apiKeyEnv ?? "TYPESAFE_API_KEY";
+            const apiKey = options.apiKey ?? process.env[envName];
+            if (!apiKey) {
+                throw new NolaProviderError(`TypeSafe 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 typesafe(). Fix: set ${envName}, or pass typesafe({ apiKeyEnv: "MY_VAR" }) or typesafe({ apiKey }) in nola.config.ts.`, { definitive: true });
+            }
+            const { system, messages, output } = req.payload;
+            const mapped = questionsFor(output.syntax === "json" ? output.schema : undefined);
+            if (!mapped.ok) {
+                throw new NolaProviderError(`TypeSafe cannot serve this ask: ${mapped.reason}`, { definitive: true });
+            }
+            const { plan } = mapped;
+            // Jev has no conversation: the state is the rendering's system text and
+            // its first user turn. A correction turn cannot occur in practice (the
+            // synthesized reply is schema-valid by construction), so any further
+            // messages are ignored and the ask is re-answered from the first turn.
+            const state = joinBlocks(system, messages[0]?.content ?? "");
+            const res = await doFetch(`${baseUrl}/v1/systemone`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify({ model, state, questions: plan.questions }),
+                signal: req.signal ?? null,
+            });
+            if (!res.ok) {
+                const errorBody = await res.text();
+                throw new NolaProviderError(`TypeSafe request failed: ${res.status} ${res.statusText} — ${errorBody.slice(0, 500)}`, { status: res.status, retryAfterMs: parseRetryAfter(res.headers.get("retry-after")) });
+            }
+            let data;
+            try {
+                data = (await res.json());
+            }
+            catch (e) {
+                throw new NolaProviderError("TypeSafe reply is not JSON.", { definitive: true, cause: e });
+            }
+            const answers = data.answers;
+            if (answers === null || typeof answers !== "object" || Array.isArray(answers)) {
+                throw new NolaProviderError("TypeSafe reply is malformed: no answers object", { definitive: true });
+            }
+            const value = {};
+            for (const [key, decode] of Object.entries(plan.decode)) {
+                const decoded = decode(answers[key]);
+                if (!decoded.ok)
+                    throw new NolaProviderError(`TypeSafe reply is malformed: ${decoded.reason}`, { definitive: true });
+                value[key] = decoded.value;
+            }
+            const durationMs = Date.now() - requestedAt;
+            return { text: JSON.stringify(plan.scalar ? value.value : value), durationMs };
+        },
+    };
+}
+//# sourceMappingURL=typesafe.js.map

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@nola-lang/providers",
-  "version": "0.1.8",
-  "description": "Nola bring-your-own LLM providers: openai, anthropic, google, mock, resilience combinators, record/replay",
+  "version": "0.1.9",
+  "description": "Nola bring-your-own LLM providers: openai, anthropic, google, typesafe, mock, resilience combinators, record/replay",
   "keywords": [
     "nola",
     "llm",
     "ai",
     "openai",
+    "typesafe",
     "providers"
   ],
   "license": "Apache-2.0",
@@ -36,8 +37,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@nola-lang/ast": "0.1.8",
-    "@nola-lang/core": "0.1.8"
+    "@nola-lang/ast": "0.1.9",
+    "@nola-lang/core": "0.1.9"
   },
   "engines": {
     "node": ">=22"