smoltalk 0.8.1 → 0.8.3

package/dist/util/jsonSchema.js

@@ -0,0 +1,133 @@
+/**
+ * JSON Schema sanitization for structured output.
+ *
+ * Zod converts `z.any()` / `z.unknown()` to an unconstrained schema — a bare
+ * `{}` (nested), `{"$schema":…}` (top-level), or the boolean `true`. That is
+ * valid JSON Schema ("accept any value"), but every provider rejects an
+ * unconstrained node inside a structured-output or strict-tool schema, since the
+ * whole point of structured output is that it is structured. These helpers map
+ * such nodes to `{"type":"string"}` (the safe universal container) and let
+ * callers detect the whole-schema-is-`any` case so they can drop structured
+ * output entirely and return free text.
+ */
+/**
+ * Pure-annotation keywords. A node carrying *only* these constrains nothing, so
+ * it is treated as unconstrained. Everything else — `type`, `properties`,
+ * `enum`, `$ref`, any validation keyword — counts as constraining. This is an
+ * allowlist, not a denylist of structural keywords, so unknown/future keywords
+ * are constraining by default (the safe direction: never rewrite a schema that
+ * means something).
+ */
+const ANNOTATION_KEYS = new Set([
+    "$schema",
+    "$id",
+    "$anchor",
+    "$comment",
+    "description",
+    "title",
+    "default",
+    "examples",
+    "readOnly",
+    "deprecated",
+]);
+/**
+ * True if `node` accepts any value: the boolean `true`, or a plain object whose
+ * every own key is a pure annotation (`{}`, `{$schema:…}`,
+ * `{$schema:…, description:…}`). `false` and any object with a structural or
+ * validation keyword are constrained.
+ */
+export function isUnconstrainedSchema(node) {
+    if (node === true)
+        return true;
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+        return false;
+    }
+    return Object.keys(node).every((key) => ANNOTATION_KEYS.has(key));
+}
+/**
+ * Convert a Zod `responseFormat` schema to a sanitized JSON Schema for a
+ * provider's structured-output request: any nested unconstrained node becomes
+ * `{"type":"string"}`. (The whole-schema-is-`any` case is handled upstream in
+ * `BaseClient.normalizeResponseFormat`, which drops structured output entirely.)
+ */
+export function responseFormatToJsonSchema(schema) {
+    // Zod's top-level toJSONSchema() is always an object, and the whole-schema-is-
+    // `any` case is stripped upstream, so sanitize always yields an object here.
+    return sanitizeJsonSchema(schema.toJSONSchema());
+}
+/**
+ * Subschema positions holding a single nested value schema (recursed into).
+ *
+ * `not` and `contains` are deliberately excluded: they are *assertions*, not
+ * value slots, so an unconstrained schema there is meaningful and must not be
+ * rewritten — `not: {}` means "reject everything" and would silently become
+ * "reject only strings" if mapped to `{type:"string"}`. Zod never emits either,
+ * so leaving them untouched is both correct and zero-impact in practice.
+ */
+const SCHEMA_KEYS = ["items", "propertyNames"];
+/** Subschema positions holding an object map of schemas. */
+const SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions"];
+/** Subschema positions holding an array of schemas. */
+const SCHEMA_ARRAY_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"];
+/**
+ * Returns a new JSON Schema with every unconstrained node replaced by
+ * `{"type":"string"}` (annotations preserved), recursing through all subschema
+ * positions. Idempotent — a node that already has `type` is left untouched.
+ *
+ * `additionalProperties` and `items` may be a boolean (`true`/`false`), which is
+ * a legitimate provider-accepted flag, not an any-typed value slot; booleans
+ * there are left as-is and only an object subschema is sanitized.
+ */
+export function sanitizeJsonSchema(node) {
+    if (node === true)
+        return { type: "string" };
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+        return node;
+    }
+    if (isUnconstrainedSchema(node)) {
+        return { ...node, type: "string" };
+    }
+    const src = node;
+    const out = { ...src };
+    for (const key of SCHEMA_KEYS) {
+        if (key in out) {
+            out[key] = sanitizeSubschema(out[key]);
+        }
+    }
+    for (const key of SCHEMA_MAP_KEYS) {
+        const map = out[key];
+        if (map && typeof map === "object" && !Array.isArray(map)) {
+            // Object.create(null): a property literally named "__proto__" (a legal Zod
+            // key) would otherwise reassign the prototype instead of setting an own key.
+            const sanitized = Object.create(null);
+            for (const [name, sub] of Object.entries(map)) {
+                sanitized[name] = sanitizeJsonSchema(sub);
+            }
+            out[key] = sanitized;
+        }
+    }
+    for (const key of SCHEMA_ARRAY_KEYS) {
+        const arr = out[key];
+        if (Array.isArray(arr)) {
+            out[key] = arr.map((sub) => sanitizeJsonSchema(sub));
+        }
+    }
+    // additionalProperties: leave booleans as-is, sanitize an object subschema.
+    if ("additionalProperties" in out) {
+        out.additionalProperties = sanitizeSubschema(out.additionalProperties);
+    }
+    return out;
+}
+/**
+ * Sanitize a value at a single-schema position (`items`, `propertyNames`,
+ * `additionalProperties`). These positions may legitimately hold a boolean:
+ * `additionalProperties: false`/`true` and `items: false` are provider-accepted
+ * flags, not any-typed value slots, so booleans pass through untouched and only
+ * an object subschema is recursively sanitized. (Zod does not emit a boolean at
+ * these positions, so `items: true` etc. are theoretical.)
+ */
+function sanitizeSubschema(value) {
+    if (typeof value === "boolean")
+        return value;
+    return sanitizeJsonSchema(value);
+}

package/dist/util/stopReason.d.ts

@@ -0,0 +1,11 @@
+import type { StopReason } from "../types/stopReason.js";
+export declare function normalizeOpenAIStopReason(raw: string | null | undefined): StopReason;
+export declare function normalizeAnthropicStopReason(raw: string | null | undefined): StopReason;
+export declare function normalizeGoogleStopReason(raw: string | null | undefined, hasToolCalls: boolean): StopReason;
+export declare function normalizeOllamaStopReason(raw: string | null | undefined): StopReason;
+/**
+ * The Responses API has no single finish-reason field: a `completed` response
+ * is a normal stop (or tool use, if it carries tool calls), while an
+ * `incomplete` one carries the reason in `incomplete_details.reason`.
+ */
+export declare function normalizeOpenAIResponsesStopReason(status: string | null | undefined, incompleteReason: string | null | undefined, hasToolCalls: boolean): StopReason;

package/dist/util/stopReason.js

@@ -0,0 +1,80 @@
+/**
+ * Pure mappers from each provider's raw finish/stop-reason vocabulary to the
+ * unified {@link StopReason}. Clients set `PromptResult.stopReason` from these
+ * and keep the untouched provider value in `PromptResult.rawStopReason`.
+ */
+const OPENAI_MAP = {
+    stop: "stop",
+    length: "length",
+    tool_calls: "tool_use",
+    function_call: "tool_use",
+    content_filter: "content_filter",
+};
+export function normalizeOpenAIStopReason(raw) {
+    return (raw && OPENAI_MAP[raw]) || "other";
+}
+const ANTHROPIC_MAP = {
+    end_turn: "stop",
+    max_tokens: "length",
+    // Ran out of context window — a length-class stop, same bucket as max_tokens.
+    model_context_window_exceeded: "length",
+    tool_use: "tool_use",
+    stop_sequence: "stop_sequence",
+    refusal: "content_filter",
+    pause_turn: "pause",
+};
+export function normalizeAnthropicStopReason(raw) {
+    return (raw && ANTHROPIC_MAP[raw]) || "other";
+}
+const GOOGLE_MAP = {
+    STOP: "stop",
+    MAX_TOKENS: "length",
+    SAFETY: "content_filter",
+    PROHIBITED_CONTENT: "content_filter",
+    RECITATION: "content_filter",
+    BLOCKLIST: "content_filter",
+    SPII: "content_filter",
+    IMAGE_SAFETY: "content_filter",
+    LANGUAGE: "content_filter",
+};
+export function normalizeGoogleStopReason(raw, hasToolCalls) {
+    // Gemini reports `STOP` even for tool-call turns, so infer `tool_use` when
+    // tool calls are present — otherwise the unified field couldn't detect tool
+    // use on Google the way it does on OpenAI/Anthropic.
+    if (raw === "STOP" && hasToolCalls) {
+        return "tool_use";
+    }
+    return (raw && GOOGLE_MAP[raw]) || "other";
+}
+const OLLAMA_MAP = {
+    stop: "stop",
+    length: "length",
+};
+export function normalizeOllamaStopReason(raw) {
+    return (raw && OLLAMA_MAP[raw]) || "other";
+}
+const RESPONSES_INCOMPLETE_MAP = {
+    max_output_tokens: "length",
+    content_filter: "content_filter",
+};
+/**
+ * The Responses API has no single finish-reason field: a `completed` response
+ * is a normal stop (or tool use, if it carries tool calls), while an
+ * `incomplete` one carries the reason in `incomplete_details.reason`.
+ */
+export function normalizeOpenAIResponsesStopReason(status, incompleteReason, hasToolCalls) {
+    if (incompleteReason) {
+        return RESPONSES_INCOMPLETE_MAP[incompleteReason] || "other";
+    }
+    // Tool-call turns report a generic terminal status, so infer tool_use from the
+    // presence of tool calls. Also treat a missing status (e.g. a stream that ended
+    // without a completed/incomplete event) as "unknown but has tools" rather than
+    // letting a tool-call turn silently degrade to "other".
+    if (hasToolCalls && (status === "completed" || status == null)) {
+        return "tool_use";
+    }
+    if (status === "completed") {
+        return "stop";
+    }
+    return "other";
+}

package/dist/util/tool.js

@@ -1,8 +1,9 @@
 import { validateToolName } from "./util.js";
+import { sanitizeJsonSchema } from "./jsonSchema.js";
 export function zodToOpenAITool(name, schema, options = {}) {
     validateToolName(name);
     // Convert Zod schema to JSON Schema
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     let description = "";
     if (options?.description) {
         description = options.description;
@@ -37,7 +38,7 @@ export function zodToOpenAITool(name, schema, options = {}) {
 }
 export function zodToOpenAIResponsesTool(name, schema, options = {}) {
     validateToolName(name);
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     const strict = options?.strict ?? false;
     const parameters = {
         type: "object",
@@ -67,7 +68,7 @@ export function zodToOpenAIResponsesTool(name, schema, options = {}) {
 }
 export function zodToAnthropicTool(name, schema, options = {}) {
     validateToolName(name);
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     let description;
     if (options?.description) {
         description = options.description;

package/package.json

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