smoltalk 0.14.2 → 0.15.0

package/README.md

@@ -548,6 +548,96 @@ same way and needs `smoltalk-llama-cpp` >= 0.5.0; the vector is computed in
 process. See that package's README for the embedding caveats (dimension
 truncation, one model file per role).
 
+## Decision models (Jev, Laya)
+
+A decision model does not write text. You send it a state and a map of typed
+questions, and it answers every question in one pass with probabilities.
+TypeSafe's Jev is one. Laya is an open-weights model that speaks the same
+protocol.
+
+```typescript
+import { decide } from "smoltalk";
+
+const r = await decide(
+  { subject: "Refund not received", body: "I cancelled two weeks ago..." },
+  {
+    department: {
+      type: "choice",
+      instructions: "Which team should handle this?",
+      criteria: { billing: "payments, refunds", support: "help, bugs" },
+    },
+    urgency: {
+      type: "score",
+      instructions: "How urgent?",
+      criteria: ["not urgent", "urgent", "critical"],
+    },
+    churn: { type: "noul", instructions: "Likely to cancel?" },
+  },
+  { model: "jev-latest" },
+);
+if (r.success) {
+  r.value.answers.department; // { type: "choice", choice: "billing", confidence: 0.86, probabilities: {...} }
+  r.value.answers.urgency;    // { type: "score", score: 1.2, confidence: 0.6, legend: {...}, probabilities: {...} }
+  r.value.answers.churn;      // { type: "noul", noul: 0.1 }
+}
+```
+
+The three question types:
+
+- `noul` is a yes/no question. The answer is the probability of yes.
+- `choice` picks one option from `criteria`, a map of option key to
+  description. The answer is the key, a confidence, and a probability per
+  option.
+- `score` places the state on `criteria`, an ordered list of level
+  descriptions. The answer is an expected level, which may be fractional, a
+  confidence, a legend, and a probability per level.
+
+The key comes from `config.apiKey.typesafe` or `TYPESAFE_API_KEY`. Cost is
+priced from the registry entry of the model you asked for, so a model the
+registry does not know has no cost.
+
+To use a Laya server, run `laya-serve` and point the provider at it. Laya
+needs no key, but the provider requires one, so pass any value:
+
+```typescript
+import { decide } from "smoltalk";
+
+const r = await decide(
+  "I was charged twice for my subscription.",
+  { refund: { type: "noul", instructions: "Is the customer asking for money back?" } },
+  {
+    model: "laya",
+    provider: "typesafe",
+    apiKey: { typesafe: "unused" },
+    baseUrl: { typesafe: "http://localhost:8000" },
+  },
+);
+```
+
+`provider: "typesafe"` is required for any model name the registry does not
+know. It says "this endpoint speaks the decision protocol".
+
+OpenRouter and Vercel AI Gateway also serve Jev over this protocol, so no
+TypeSafe account is needed. OpenRouter's model name, `jev-1.13`, is in the
+registry:
+
+```typescript
+import { decide } from "smoltalk";
+
+const r = await decide(
+  "I was charged twice for my subscription.",
+  { refund: { type: "noul", instructions: "Is the customer asking for money back?" } },
+  {
+    model: "jev-1.13",
+    apiKey: { typesafe: process.env.OPENROUTER_API_KEY },
+    baseUrl: { typesafe: "https://openrouter.ai/api" },
+  },
+);
+```
+
+Vercel's base URL is `https://ai-gateway.vercel.sh/typesafe` and its model
+name is `typesafe-ai/jev`, which needs `provider: "typesafe"`.
+
 ## Audio (STT/TTS)
 
 Three audio primitives. `transcribe()` (speech-to-text) and `speak()`

package/dist/decide.d.ts

@@ -0,0 +1,91 @@
+import type { ModelDataBlob } from "./modelData.js";
+import { Result } from "./types/result.js";
+import { TokenUsage } from "./types/tokenUsage.js";
+import { CostEstimate } from "./types/costEstimate.js";
+export declare const DECISION_PROVIDER = "typesafe";
+export type NoulQuestion = {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+};
+export type ChoiceQuestion = {
+    type: "choice";
+    instructions: string;
+    /** Option key to its description. */
+    criteria: Record<string, string>;
+};
+export type ScoreQuestion = {
+    type: "score";
+    instructions: string;
+    /** Ordered level descriptions, lowest first. At least two. */
+    criteria: string[];
+};
+export type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export type NoulAnswer = {
+    type: "noul";
+    /** Probability that the answer is yes, 0 to 1. */
+    noul: number;
+};
+export type ChoiceAnswer = {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    /** Option key to probability. */
+    probabilities: Record<string, number>;
+};
+export type ScoreAnswer = {
+    type: "score";
+    /** Expected level. May be fractional. */
+    score: number;
+    confidence: number;
+    /** Level index to description. */
+    legend: Record<string, string>;
+    /** Level index to probability. */
+    probabilities: Record<string, number>;
+};
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+/** What the model reads before answering: text, or a JSON value. */
+export type DecisionState = string | object;
+export type DecideConfig = {
+    model: string;
+    /** Required when the model is not in the registry. */
+    provider?: string;
+    /** API keys, nested by provider. Falls back to TYPESAFE_API_KEY. */
+    apiKey?: {
+        typesafe?: string;
+        [provider: string]: string | undefined;
+    };
+    /** Custom base URLs, nested by provider. Falls back to TYPESAFE_BASE_URL,
+     *  then TypeSafe's host. Point `typesafe` at a Laya server to use Laya. */
+    baseUrl?: {
+        typesafe?: string;
+        [provider: string]: string | undefined;
+    };
+    /** Refreshed model data to layer over the baked-in registry. */
+    modelData?: ModelDataBlob;
+    abortSignal?: AbortSignal;
+};
+export type DecideResult = {
+    answers: Record<string, DecisionAnswer>;
+    usage: TokenUsage;
+    cost?: CostEstimate;
+    /** The versioned model the server reports, e.g. `jev-1.13`. */
+    model: string;
+};
+/**
+ * Ask a decision model one or more typed questions about a state.
+ *
+ * ```ts
+ * const r = await decide(ticket, {
+ *   department: { type: "choice", instructions: "Which team?", criteria: { billing: "refunds", support: "bugs" } },
+ *   churn: { type: "noul", instructions: "Likely to cancel?" },
+ * }, { model: "jev-latest" });
+ * ```
+ *
+ * Cost is priced from the registry entry of the **requested** model, so a
+ * model the registry does not know, such as a Laya checkpoint, has no cost.
+ */
+export declare function decide(state: DecisionState, questions: Record<string, DecisionQuestion>, config: DecideConfig): Promise<Result<DecideResult>>;

package/dist/decide.js

@@ -0,0 +1,223 @@
+/**
+ * Decision models: typed questions in, probabilities out.
+ *
+ * A decision model such as TypeSafe's Jev, or the open-weights Laya, does not
+ * generate text. You send it a state (text or JSON) and a map of questions,
+ * and it answers every question in one forward pass. There are three question
+ * types: a yes/no `noul`, a `choice` from a fixed set of options, and a
+ * `score` on an ordered rubric. Every answer carries probabilities.
+ *
+ * `decide()` follows the shape of `embed()`: payload first, config last,
+ * provider and key and base URL resolved through the shared helpers. There
+ * is one provider, `typesafe`, which is the wire protocol. A Laya server
+ * speaks the same protocol, so it is reached by setting `baseUrl.typesafe`.
+ */
+import { z } from "zod";
+import { success, failure } from "./types/result.js";
+import { resolveProvider, resolveApiKey, resolveBaseUrl } from "./util/provider.js";
+import { isDecisionModel, resolveModelForProvider } from "./models.js";
+import { round } from "./util/util.js";
+export const DECISION_PROVIDER = "typesafe";
+const NoulAnswerSchema = z.object({
+    type: z.literal("noul"),
+    noul: z.number(),
+});
+const ChoiceAnswerSchema = z.object({
+    type: z.literal("choice"),
+    choice: z.string(),
+    confidence: z.number(),
+    probabilities: z.record(z.string(), z.number()),
+});
+const ScoreAnswerSchema = z.object({
+    type: z.literal("score"),
+    score: z.number(),
+    confidence: z.number(),
+    legend: z.record(z.string(), z.string()),
+    probabilities: z.record(z.string(), z.number()),
+});
+const DecisionAnswerSchema = z.discriminatedUnion("type", [
+    NoulAnswerSchema,
+    ChoiceAnswerSchema,
+    ScoreAnswerSchema,
+]);
+const ResponseSchema = z.object({
+    model: z.string().optional(),
+    answers: z.record(z.string(), DecisionAnswerSchema),
+    usage: z
+        .object({
+        input_tokens: z.number(),
+        output_tokens: z.number().optional(),
+    })
+        .optional(),
+});
+function errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+/** A problem with the questions that no server would accept. Checked before
+ *  any request so a bad question map never costs a round trip. */
+function checkQuestions(questions, maxQuestions) {
+    const names = Object.keys(questions);
+    if (names.length === 0) {
+        return "No questions given. A decision request needs at least one question.";
+    }
+    if (maxQuestions !== undefined && names.length > maxQuestions) {
+        return `Too many questions: ${names.length} given, the model accepts at most ${maxQuestions} per request.`;
+    }
+    for (const name of names) {
+        const q = questions[name];
+        if (q.type === "choice" && Object.keys(q.criteria).length < 2) {
+            return `Question "${name}" is a choice with fewer than two options.`;
+        }
+        if (q.type === "score" && q.criteria.length < 2) {
+            return `Question "${name}" is a score with fewer than two levels.`;
+        }
+    }
+    return undefined;
+}
+function isProbability(n) {
+    return n >= 0 && n <= 1;
+}
+/** A response that parsed but does not answer what was asked. The Zod
+ *  schema only says each field is a number or a string; this checks the
+ *  numbers are probabilities and the answer fits the question it is for. */
+function checkAnswers(questions, answers) {
+    for (const name of Object.keys(questions)) {
+        const q = questions[name];
+        const a = answers[name];
+        if (a === undefined) {
+            return `The response has no answer for question "${name}".`;
+        }
+        if (a.type !== q.type) {
+            return `Question "${name}" is a ${q.type} but the answer is a ${a.type}.`;
+        }
+        if (a.type === "noul" && !isProbability(a.noul)) {
+            return `Question "${name}" has a noul of ${a.noul}, which is not between 0 and 1.`;
+        }
+        if ((a.type === "choice" || a.type === "score") && !isProbability(a.confidence)) {
+            return `Question "${name}" has a confidence of ${a.confidence}, which is not between 0 and 1.`;
+        }
+        if (q.type === "choice" && a.type === "choice") {
+            if (!(a.choice in q.criteria)) {
+                return `Question "${name}" answered "${a.choice}", which is not one of its options.`;
+            }
+            const unknown = Object.keys(a.probabilities).find((k) => !(k in q.criteria));
+            if (unknown !== undefined) {
+                return `Question "${name}" has a probability for "${unknown}", which is not one of its options.`;
+            }
+        }
+        if (q.type === "score" && a.type === "score") {
+            const levels = q.criteria.length;
+            if (Object.keys(a.legend).length !== levels) {
+                return `Question "${name}" has ${levels} levels but the answer's legend has ${Object.keys(a.legend).length}.`;
+            }
+            if (Object.keys(a.probabilities).length !== levels) {
+                return `Question "${name}" has ${levels} levels but the answer has ${Object.keys(a.probabilities).length} probabilities.`;
+            }
+            if (a.score < 0 || a.score > levels - 1) {
+                return `Question "${name}" has a score of ${a.score}, outside its ${levels} levels.`;
+            }
+        }
+    }
+    return undefined;
+}
+function calculateDecisionCost(model, inputTokens) {
+    if (model === undefined || model.inputTokenCost === undefined) {
+        return undefined;
+    }
+    const inputCost = round((inputTokens * model.inputTokenCost) / 1_000_000, 6);
+    return { inputCost, outputCost: 0, totalCost: inputCost, currency: "USD" };
+}
+/**
+ * Ask a decision model one or more typed questions about a state.
+ *
+ * ```ts
+ * const r = await decide(ticket, {
+ *   department: { type: "choice", instructions: "Which team?", criteria: { billing: "refunds", support: "bugs" } },
+ *   churn: { type: "noul", instructions: "Likely to cancel?" },
+ * }, { model: "jev-latest" });
+ * ```
+ *
+ * Cost is priced from the registry entry of the **requested** model, so a
+ * model the registry does not know, such as a Laya checkpoint, has no cost.
+ */
+export async function decide(state, questions, config) {
+    let provider;
+    try {
+        provider = resolveProvider(config.model, config.provider, config.modelData);
+    }
+    catch (err) {
+        return failure(errorMessage(err));
+    }
+    if (provider !== DECISION_PROVIDER) {
+        return failure(`Provider "${provider}" does not answer decisions. Only "${DECISION_PROVIDER}" does; set config.provider to it for a model the registry does not know.`);
+    }
+    // The registry entry for the requested name, when there is one. It sets
+    // the question cap and the price. A Laya model has no entry and no price.
+    const found = resolveModelForProvider(provider, config.model, config.modelData);
+    const registryModel = found && isDecisionModel(found) ? found : undefined;
+    const questionProblem = checkQuestions(questions, registryModel?.maxQuestions);
+    if (questionProblem) {
+        return failure(questionProblem);
+    }
+    const apiKey = resolveApiKey(provider, config);
+    if (!apiKey) {
+        return failure("No TypeSafe API key provided. Set config.apiKey.typesafe or the TYPESAFE_API_KEY environment variable.");
+    }
+    const baseUrl = resolveBaseUrl(provider, config).replace(/\/+$/, "");
+    if (config.abortSignal?.aborted) {
+        return failure("Request was aborted");
+    }
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/v1/systemone`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ model: config.model, state, questions }),
+            signal: config.abortSignal,
+        });
+    }
+    catch (err) {
+        if (config.abortSignal?.aborted) {
+            return failure("Request was aborted");
+        }
+        return failure(`Decision request failed: ${errorMessage(err)}`);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        return failure(`Decision request failed with status ${response.status}: ${text}`);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return failure(`Decision response is not JSON: ${text.slice(0, 200)}`);
+    }
+    const parsed = ResponseSchema.safeParse(body);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+        return failure(`Decision response has an unexpected shape${where}: ${issue.message}`);
+    }
+    const answers = parsed.data.answers;
+    const answerProblem = checkAnswers(questions, answers);
+    if (answerProblem) {
+        return failure(answerProblem);
+    }
+    // Output is free, so only input tokens are priced. The server's output
+    // count is still reported: Jev sends 0, but a gateway may count its own.
+    const inputTokens = parsed.data.usage?.input_tokens ?? 0;
+    const outputTokens = parsed.data.usage?.output_tokens ?? 0;
+    return success({
+        answers,
+        usage: { inputTokens, outputTokens },
+        cost: calculateDecisionCost(registryModel, inputTokens),
+        model: parsed.data.model ?? config.model,
+    });
+}

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 export type { LlamaCppModule } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
+export * from "./decide.js";
+export { resolveProvider } from "./util/provider.js";
 export * from "./image.js";
 export { uploadFile, deleteFile, registerFileProvider, DEFAULT_UPLOAD_BYTES } from "./files.js";
 export type { UploadFileOptions, FileProviderContext, FileProvider } from "./files.js";

package/dist/index.js

@@ -13,6 +13,8 @@ export * from "./functions.js";
 export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
+export * from "./decide.js";
+export { resolveProvider } from "./util/provider.js";
 export * from "./image.js";
 // Explicit (not `export *`) so the test-only `_resetForTests` stays off the public surface.
 export { uploadFile, deleteFile, registerFileProvider, DEFAULT_UPLOAD_BYTES } from "./files.js";

package/dist/model.js

@@ -36,9 +36,10 @@ export class Model {
             return null;
         }
         // This token engine prices text generation and token-billed audio models
-        // (e.g. Gemini TTS). Image and embeddings models have their own cost paths,
-        // so they are never priced here even if they carry text-token rates.
-        if (model.type === "image" || model.type === "embeddings") {
+        // (e.g. Gemini TTS). Image, embeddings, and decision models have their own
+        // cost paths, so they are never priced here even if they carry text-token
+        // rates.
+        if (model.type === "image" || model.type === "embeddings" || model.type === "decision") {
             return null;
         }
         // BaseModel token-rate fields, read structurally across the model union.

package/dist/models.d.ts

@@ -115,7 +115,21 @@ export type EmbeddingsModel = {
     provider: string;
     tokenCost?: number;
 };
-export type ModelType = SpeechToTextModel | TextToSpeechModel | TextModel | EmbeddingsModel | ImageModel;
+/**
+ * A decision model answers typed questions about a state with probabilities
+ * instead of generating text. See `lib/decide.ts`.
+ */
+export type DecisionModel = {
+    type: "decision";
+    modelName: string;
+    provider: string;
+    description?: string;
+    /** Cost per 1M input tokens, in dollars. Output is free. */
+    inputTokenCost?: number;
+    /** The most questions one request may carry. */
+    maxQuestions?: number;
+};
+export type ModelType = SpeechToTextModel | TextToSpeechModel | TextModel | EmbeddingsModel | ImageModel | DecisionModel;
 export declare const speechToTextModels: readonly [{
     readonly type: "speech-to-text";
     readonly modelName: "whisper-1";
@@ -1943,6 +1957,7 @@ export declare const imageModels: readonly [{
     readonly costPerImage: 0.034;
 }];
 export declare const embeddingsModels: EmbeddingsModel[];
+export declare const decisionModels: DecisionModel[];
 export type TextModelName = (typeof textModels)[number]["modelName"];
 export type ImageModelName = (typeof imageModels)[number]["modelName"];
 export type SpeechToTextModelName = (typeof speechToTextModels)[number]["modelName"];
@@ -2006,4 +2021,5 @@ export declare function audioInputConstraints(model: ModelType): {
     supportedMimeTypes?: readonly string[];
 };
 export declare function isEmbeddingsModel(model: ModelType): model is EmbeddingsModel;
+export declare function isDecisionModel(model: ModelType): model is DecisionModel;
 export declare const ModelNameSchema: z.ZodString;

package/dist/models.js

@@ -1962,6 +1962,24 @@ export const embeddingsModels = [
         tokenCost: 0.2,
     },
 ];
+export const decisionModels = [
+    {
+        type: "decision",
+        modelName: "jev-latest",
+        provider: "typesafe",
+        description: "TypeSafe's System One model. Answers yes/no, choice, and score questions about a state with calibrated probabilities. Does not generate text.",
+        inputTokenCost: 0.042,
+        maxQuestions: 64,
+    },
+    {
+        type: "decision",
+        modelName: "jev-1.13",
+        provider: "typesafe",
+        description: "Jev 1.13, the name OpenRouter serves it under (baseUrl.typesafe = https://openrouter.ai/api). Same price and protocol as jev-latest.",
+        inputTokenCost: 0.042,
+        maxQuestions: 64,
+    },
+];
 export const hostedTools = [
     {
         name: "web_search",
@@ -2102,6 +2120,7 @@ function baselineModels() {
         ...textToSpeechModels,
         ...registeredTextModels,
         ...embeddingsModels,
+        ...decisionModels,
     ];
 }
 /**
@@ -2261,6 +2280,9 @@ export function audioInputConstraints(model) {
 export function isEmbeddingsModel(model) {
     return model.type === "embeddings";
 }
+export function isDecisionModel(model) {
+    return model.type === "decision";
+}
 export const ModelNameSchema = z
     .string()
     .regex(/^[a-zA-Z0-9._:@/-]+$/, "Model name must only contain letters, numbers, dots, underscores, hyphens, colons, slashes, and @");

package/dist/types.d.ts

@@ -162,8 +162,12 @@ export type PromptResult = {
     stopReason?: StopReason;
     /** The untouched provider finish/stop-reason value (e.g. `end_turn`, `MAX_TOKENS`). */
     rawStopReason?: string;
+    /** Whatever the provider returned beyond the text, for callers that want
+     *  it on the assistant message. A decision model puts its full answers
+     *  with probabilities here. */
+    rawData?: unknown;
 };
-export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, }: Partial<PromptResult>): PromptResult;
+export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }: Partial<PromptResult>): PromptResult;
 export type StreamChunk = {
     type: "text";
     text: string;

package/dist/types.js

@@ -4,7 +4,7 @@ import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
 export * from "./types/stopReason.js";
-export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, }) {
+export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }) {
     return {
         output: output || null,
         toolCalls: toolCalls || [],
@@ -15,6 +15,7 @@ export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, m
         hostedToolResults,
         stopReason,
         rawStopReason,
+        rawData,
     };
 }
 export const ThinkingBlockSchema = z.object({

package/dist/util/provider.d.ts

@@ -20,6 +20,7 @@ type NestedKeyConfig = {
         liteLlm?: string;
         openAiCompat?: string;
         groq?: string;
+        typesafe?: string;
         /** Arbitrary provider names, for keys targeting a custom-registered provider. */
         [provider: string]: string | undefined;
     };
@@ -30,6 +31,7 @@ type NestedKeyConfig = {
         liteLlm?: string;
         openAiCompat?: string;
         mlx?: string;
+        typesafe?: string;
     };
 };
 /**

package/dist/util/provider.js

@@ -39,6 +39,8 @@ export function resolveApiKey(provider, config) {
             return k?.openAiCompat || process.env.OPENAI_COMPAT_API_KEY;
         case "groq":
             return k?.groq || process.env.GROQ_API_KEY;
+        case "typesafe":
+            return k?.typesafe || process.env.TYPESAFE_API_KEY;
         default:
             return config.apiKey?.[provider];
     }
@@ -66,6 +68,9 @@ export function resolveBaseUrl(provider, config) {
             return b?.openAiCompat || process.env.OPENAI_COMPAT_BASE_URL;
         case "mlx":
             return b?.mlx || process.env.MLX_BASE_URL || "http://127.0.0.1:8080/v1";
+        case "typesafe":
+            // A Laya server (`laya-serve`) speaks the same protocol; point this at it.
+            return b?.typesafe || process.env.TYPESAFE_BASE_URL || "https://api.typesafe.ai";
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [