@sudobility/shapeshyft_engine 1.0.5 → 1.0.8

package/dist/services/llm/jev.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Jev (TypeSafe AI) LLM provider
+ * @description Jev is not a text-generation model. It is a "System One"
+ * model that answers pre-declared Choice/Score/Noul questions -- evaluated in
+ * parallel -- with calibrated probabilities instead of writing free-form
+ * text or arbitrary JSON. This adapter maps an endpoint's `outputSchema` onto
+ * those primitives one top-level property at a time; see
+ * {@link classifyJevField} for the exact rule, and {@link checkJevCompatibility}
+ * to check a schema without calling Jev.
+ *
+ * Confirmed against https://docs.typesafe.ai on 2026-09-23. A page at
+ * jevapi.org advertises a different endpoint domain ("tokenra.io") for the
+ * same model; every official TypeSafe AI source (docs.typesafe.ai, its
+ * Wikipedia entry, and the `@typesafe-ai/sdk` npm package's own metadata)
+ * agrees only on api.typesafe.ai, so that's the only endpoint this adapter
+ * will ever call.
+ *
+ * @see https://docs.typesafe.ai/api.md
+ * @see https://docs.typesafe.ai/primitives.md
+ */
+import type { ILLMProvider, LLMRequest, LLMResponse, ProviderConfig } from "./types.js";
+import type { JsonSchema } from "../../types/index.js";
+type JevQuestion = {
+    type: "noul";
+    instructions: string;
+} | {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, null>;
+} | {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+interface JevField {
+    key: string;
+    question: JevQuestion;
+    /** Ordered rubric levels, for a "score" question only (low to high). */
+    levels?: string[];
+}
+export interface JevCompatibility {
+    compatible: boolean;
+    /** One message per top-level field Jev cannot answer, naming the field. */
+    errors: string[];
+}
+/**
+ * Classify one top-level schema property into a Jev question, or explain why
+ * it cannot be one:
+ *
+ * - `{ type: "boolean" }` -> Noul
+ * - `{ type: "string", enum: [...] }` -> Choice (enum values become options)
+ * - `{ type: "string", enum: [...], "x-jev-kind": "score" }` -> Score (the
+ *   enum, in the given order, becomes the rubric's levels from low to high)
+ *
+ * Anything else (free text, numbers, arrays, nested objects) has no mapping.
+ *
+ * Exported so a frontend schema editor can give the same answer without a
+ * round trip to `generate()`. Keep any such copy in sync with this one until
+ * it can be shared as a published dependency instead.
+ */
+export declare function classifyJevField(key: string, schema: JsonSchema): {
+    field: JevField;
+} | {
+    error: string;
+};
+/**
+ * Check whether an endpoint's `outputSchema` can be answered by Jev at all,
+ * without calling it. `generate()` and `buildApiPayload()` both call this and
+ * throw when it fails; it is also safe to call from a schema editor for live
+ * feedback before an endpoint is saved.
+ */
+export declare function checkJevCompatibility(schema: JsonSchema): JevCompatibility;
+export declare class JevProvider implements ILLMProvider {
+    readonly providerName: "jev";
+    private apiKey;
+    private defaultModel;
+    constructor(config: ProviderConfig);
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    buildApiPayload(request: LLMRequest): Record<string, unknown>;
+    private buildPayload;
+}
+export {};
+//# sourceMappingURL=jev.d.ts.map

package/dist/services/llm/jev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev.d.ts","sourceRoot":"","sources":["../../../src/services/llm/jev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EAEX,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAQvD,KAAK,WAAW,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAkBhE,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,WAAW,CAAC;IACtB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,UAAU,GACjB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAoDzC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAmB1E;AAsCD,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,YAAY,EAAG,KAAK,CAAU;IACvC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,cAAc;IAQ5B,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IA8EzD,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAM7D,OAAO,CAAC,YAAY;CAgBrB"}

package/dist/services/llm/jev.js

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview Jev (TypeSafe AI) LLM provider
+ * @description Jev is not a text-generation model. It is a "System One"
+ * model that answers pre-declared Choice/Score/Noul questions -- evaluated in
+ * parallel -- with calibrated probabilities instead of writing free-form
+ * text or arbitrary JSON. This adapter maps an endpoint's `outputSchema` onto
+ * those primitives one top-level property at a time; see
+ * {@link classifyJevField} for the exact rule, and {@link checkJevCompatibility}
+ * to check a schema without calling Jev.
+ *
+ * Confirmed against https://docs.typesafe.ai on 2026-09-23. A page at
+ * jevapi.org advertises a different endpoint domain ("tokenra.io") for the
+ * same model; every official TypeSafe AI source (docs.typesafe.ai, its
+ * Wikipedia entry, and the `@typesafe-ai/sdk` npm package's own metadata)
+ * agrees only on api.typesafe.ai, so that's the only endpoint this adapter
+ * will ever call.
+ *
+ * @see https://docs.typesafe.ai/api.md
+ * @see https://docs.typesafe.ai/primitives.md
+ */
+import { attachUsage } from "./usage-error.js";
+const DEFAULT_MODEL = "jev-latest";
+/** The only endpoint TypeSafe AI documents for Jev -- see the file header. */
+const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+/**
+ * Classify one top-level schema property into a Jev question, or explain why
+ * it cannot be one:
+ *
+ * - `{ type: "boolean" }` -> Noul
+ * - `{ type: "string", enum: [...] }` -> Choice (enum values become options)
+ * - `{ type: "string", enum: [...], "x-jev-kind": "score" }` -> Score (the
+ *   enum, in the given order, becomes the rubric's levels from low to high)
+ *
+ * Anything else (free text, numbers, arrays, nested objects) has no mapping.
+ *
+ * Exported so a frontend schema editor can give the same answer without a
+ * round trip to `generate()`. Keep any such copy in sync with this one until
+ * it can be shared as a published dependency instead.
+ */
+export function classifyJevField(key, schema) {
+    const instructions = schema.description ?? key;
+    if (schema.type === "boolean") {
+        return { field: { key, question: { type: "noul", instructions } } };
+    }
+    if (schema.type === "string" &&
+        Array.isArray(schema.enum) &&
+        schema.enum.length > 0) {
+        const levels = schema.enum.map(v => String(v));
+        if (schema["x-jev-kind"] === "score") {
+            if (levels.length < 2 || levels.length > 10) {
+                return {
+                    error: `"${key}" has ${levels.length} enum values, but a Jev score rubric ("x-jev-kind": "score") needs between 2 and 10 ordered levels`,
+                };
+            }
+            return {
+                field: {
+                    key,
+                    question: { type: "score", instructions, criteria: levels },
+                    levels,
+                },
+            };
+        }
+        if (levels.length > 255) {
+            return {
+                error: `"${key}" has ${levels.length} enum values, but Jev's Choice primitive supports at most 255 options`,
+            };
+        }
+        return {
+            field: {
+                key,
+                question: {
+                    type: "choice",
+                    instructions,
+                    criteria: Object.fromEntries(levels.map(v => [v, null])),
+                },
+            },
+        };
+    }
+    return {
+        error: `"${key}" is a ${schema.type ?? "untyped"} field` +
+            (schema.type === "string" ? " without an enum" : "") +
+            `; Jev only answers boolean fields (Noul) or string fields with an "enum" (Choice, or Score with "x-jev-kind": "score")`,
+    };
+}
+/**
+ * Check whether an endpoint's `outputSchema` can be answered by Jev at all,
+ * without calling it. `generate()` and `buildApiPayload()` both call this and
+ * throw when it fails; it is also safe to call from a schema editor for live
+ * feedback before an endpoint is saved.
+ */
+export function checkJevCompatibility(schema) {
+    if (schema.type !== "object" ||
+        !schema.properties ||
+        Object.keys(schema.properties).length === 0) {
+        return {
+            compatible: false,
+            errors: [
+                "Jev endpoints need an output schema that is a JSON object with at least one property, and each property must be a boolean or a string with an enum",
+            ],
+        };
+    }
+    const errors = [];
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const result = classifyJevField(key, propSchema);
+        if ("error" in result)
+            errors.push(result.error);
+    }
+    return { compatible: errors.length === 0, errors };
+}
+/** Builds the per-field question list, or throws with every incompatible field named. */
+function buildFields(schema) {
+    const check = checkJevCompatibility(schema);
+    if (!check.compatible) {
+        throw new Error(`Output schema is not compatible with Jev: ${check.errors.join("; ")}`);
+    }
+    return Object.entries(schema.properties).map(([key, propSchema]) => {
+        const result = classifyJevField(key, propSchema);
+        if ("error" in result) {
+            // Unreachable: checkJevCompatibility above already rejected this schema.
+            throw new Error(result.error);
+        }
+        return result.field;
+    });
+}
+/** Turn one of Jev's answers back into the value its field's schema declared. */
+function decodeAnswer(field, answer) {
+    switch (answer.type) {
+        case "noul":
+            return answer.noul >= 0.5;
+        case "choice":
+            return answer.choice;
+        case "score": {
+            const levels = field.levels ?? [];
+            const index = Math.min(levels.length - 1, Math.max(0, Math.round(answer.score)));
+            return levels[index];
+        }
+    }
+}
+export class JevProvider {
+    providerName = "jev";
+    apiKey;
+    defaultModel;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("Jev (TypeSafe AI) API key is required");
+        }
+        this.apiKey = config.apiKey;
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+    }
+    async generate(request) {
+        if (request.media?.length) {
+            throw new Error("Jev is text-only (state must be a string, JSON object, or array of text) and cannot accept media input");
+        }
+        const model = request.model ?? this.defaultModel;
+        const fields = buildFields(request.outputSchema);
+        const payload = this.buildPayload(model, request, fields);
+        const startTime = Date.now();
+        let response;
+        try {
+            response = await fetch(JEV_ENDPOINT, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(payload),
+            });
+        }
+        catch (fetchError) {
+            const message = fetchError instanceof Error ? fetchError.message : String(fetchError);
+            throw new Error(`Failed to reach Jev at ${JEV_ENDPOINT}: ${message}`);
+        }
+        const latencyMs = Date.now() - startTime;
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "");
+            throw new Error(`Jev error (${response.status}): ${errorText || response.statusText}`);
+        }
+        const body = (await response.json());
+        const usage = {
+            promptTokens: body.usage?.input_tokens ?? 0,
+            completionTokens: body.usage?.output_tokens ?? 0,
+            totalTokens: (body.usage?.input_tokens ?? 0) + (body.usage?.output_tokens ?? 0),
+        };
+        const answers = body.answers ?? {};
+        const content = {};
+        for (const field of fields) {
+            const answer = answers[field.key];
+            if (!answer) {
+                // The call was billed even though this field came back empty.
+                throw attachUsage(new Error(`Jev did not answer "${field.key}"`), usage, body.model ?? model);
+            }
+            content[field.key] = decodeAnswer(field, answer);
+        }
+        return {
+            content,
+            rawResponse: JSON.stringify(body),
+            usage,
+            model: body.model ?? model,
+            provider: this.providerName,
+            latencyMs,
+            // Jev answers every declared question in one parallel pass -- there is
+            // no partial or truncated generation for it to report.
+            finishReason: "stop",
+        };
+    }
+    buildApiPayload(request) {
+        const model = request.model ?? this.defaultModel;
+        const fields = buildFields(request.outputSchema);
+        return this.buildPayload(model, request, fields);
+    }
+    buildPayload(model, request, fields) {
+        return {
+            model,
+            // Docs recommend objects for most requests, and keeping state (the
+            // material to evaluate) separate from questions (the judgments to
+            // make about it) -- https://docs.typesafe.ai/concepts/state.md
+            state: request.systemPrompt
+                ? { instructions: request.systemPrompt, input: request.prompt }
+                : request.prompt,
+            questions: Object.fromEntries(fields.map(f => [f.key, f.question])),
+        };
+    }
+}
+//# sourceMappingURL=jev.js.map

package/dist/services/llm/jev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev.js","sourceRoot":"","sources":["../../../src/services/llm/jev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,aAAa,GAAG,YAAY,CAAC;AAEnC,8EAA8E;AAC9E,MAAM,YAAY,GAAG,sCAAsC,CAAC;AAoC5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,MAAkB;IAElB,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC;IAE/C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IACtE,CAAC;IAED,IACE,MAAM,CAAC,IAAI,KAAK,QAAQ;QACxB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EACtB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/C,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,OAAO,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBAC5C,OAAO;oBACL,KAAK,EAAE,IAAI,GAAG,SAAS,MAAM,CAAC,MAAM,oGAAoG;iBACzI,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,KAAK,EAAE;oBACL,GAAG;oBACH,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE;oBAC3D,MAAM;iBACP;aACF,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACxB,OAAO;gBACL,KAAK,EAAE,IAAI,GAAG,SAAS,MAAM,CAAC,MAAM,uEAAuE;aAC5G,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK,EAAE;gBACL,GAAG;gBACH,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,YAAY;oBACZ,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;iBACzD;aACF;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EACH,IAAI,GAAG,UAAU,MAAM,CAAC,IAAI,IAAI,SAAS,QAAQ;YACjD,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,wHAAwH;KAC3H,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAkB;IACtD,IACE,MAAM,CAAC,IAAI,KAAK,QAAQ;QACxB,CAAC,MAAM,CAAC,UAAU;QAClB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAC3C,CAAC;QACD,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE;gBACN,oJAAoJ;aACrJ;SACF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACjD,IAAI,OAAO,IAAI,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,yFAAyF;AACzF,SAAS,WAAW,CAAC,MAAkB;IACrC,MAAM,KAAK,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,6CAA6C,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE;QAClE,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACjD,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;YACtB,yEAAyE;YACzE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AACjF,SAAS,YAAY,CAAC,KAAe,EAAE,MAAiB;IACtD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,MAAM,CAAC,MAAM,GAAG,CAAC,EACjB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACtC,CAAC;YACF,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,OAAO,WAAW;IACb,YAAY,GAAG,KAAc,CAAC;IAC/B,MAAM,CAAS;IACf,YAAY,CAAS;IAE7B,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAmB;QAChC,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACjD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE;gBACnC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;oBACtC,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC9B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,MAAM,OAAO,GACX,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACxE,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,KAAK,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEzC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,cAAc,QAAQ,CAAC,MAAM,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CACtE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAIlC,CAAC;QAEF,MAAM,KAAK,GAAa;YACtB,YAAY,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC;YAC3C,gBAAgB,EAAE,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC;YAChD,WAAW,EACT,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC,CAAC;SACrE,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QACnC,MAAM,OAAO,GAA4B,EAAE,CAAC;QAC5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,8DAA8D;gBAC9D,MAAM,WAAW,CACf,IAAI,KAAK,CAAC,uBAAuB,KAAK,CAAC,GAAG,GAAG,CAAC,EAC9C,KAAK,EACL,IAAI,CAAC,KAAK,IAAI,KAAK,CACpB,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;QAED,OAAO;YACL,OAAO;YACP,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YACjC,KAAK;YACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK;YAC1B,QAAQ,EAAE,IAAI,CAAC,YAAY;YAC3B,SAAS;YACT,uEAAuE;YACvE,uDAAuD;YACvD,YAAY,EAAE,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,OAAmB;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACjD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAEO,YAAY,CAClB,KAAa,EACb,OAAmB,EACnB,MAAkB;QAElB,OAAO;YACL,KAAK;YACL,mEAAmE;YACnE,kEAAkE;YAClE,+DAA+D;YAC/D,KAAK,EAAE,OAAO,CAAC,YAAY;gBACzB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;gBAC/D,CAAC,CAAC,OAAO,CAAC,MAAM;YAClB,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;SACpE,CAAC;IACJ,CAAC;CACF"}

package/dist/services/llm/json-repair.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Read model JSON that is nearly, but not quite, JSON.
+ * @description A model writing a long answer slips now and then: a trailing
+ * comma, a missing one, a bracket left open, a number like `0480`, an unescaped
+ * quote inside a lyric. Function calling guarantees the SHAPE of the payload,
+ * not that the text is valid — and a strict `JSON.parse` turns any of those
+ * into a failed, billed call that then has to be asked for again.
+ *
+ * Measured on one product's history through this server: 1,045 of 1,205 failed
+ * calls were parse failures, every one starting with a well-formed `{` and
+ * breaking somewhere after it, at 500-1,700 tokens against a ceiling ten times
+ * that. Most were "Unable to parse JSON string", "Expected ']'", "Invalid
+ * number" and "Property name must be a string literal". At temperature 0 the
+ * same prompt gives the same slip, so asking again does not help; reading the
+ * answer tolerantly does, and costs nothing.
+ *
+ * What a real DeepSeek answer actually got wrong, from the first patched run
+ * (6 repairs): five were TRAILING TEXT — a complete document, then the model
+ * closed the outer object one brace early and carried on writing its notes,
+ * which is what "Unable to parse JSON string" (55% of the history) was — and one
+ * was arithmetic in a number, `[1920 - 480, 480, "F3", 106]`. Failed calls in
+ * that run's styles fell from 6, 3 and 2 per song to one across three.
+ *
+ * The rule that keeps this safe: **strict parsing is tried first and is what
+ * valid input gets**, byte for byte. The tolerant reader only runs on text
+ * `JSON.parse` has already refused, and it reports every repair it made, so the
+ * caller can log it. It never guesses at meaning — it closes what is open,
+ * inserts what is missing between two values, and drops what is stray. A repaired
+ * answer is still only as good as the shape the caller validates it against.
+ */
+/** One thing the reader had to fix to make the text parse. */
+export type JsonRepair = {
+    kind: string;
+    at: number;
+};
+/** A parsed answer and what it took to parse it. */
+export type ParsedModelJson = {
+    value: unknown;
+    repairs: JsonRepair[];
+};
+/**
+ * Read `text` tolerantly, or return null when it is not recoverable JSON.
+ *
+ * Exported for tests. Callers want `parseModelJson`, which is strict first.
+ */
+export declare function lenientParse(text: string): ParsedModelJson | null;
+/**
+ * `JSON.parse`, then — only if that refuses — the tolerant reader.
+ *
+ * Valid JSON is returned exactly as `JSON.parse` returns it, with no repairs,
+ * so putting this where `JSON.parse` was cannot change what a good answer
+ * means. Throws the strict parser's own error when the text cannot be repaired,
+ * so a caller's failure handling is unchanged.
+ */
+export declare function parseModelJson(text: string): ParsedModelJson;
+/** A short window of `text` around the first repair, for a log line. */
+export declare function windowAroundFirstRepair(text: string, repairs: readonly JsonRepair[], radius?: number): string;
+/** "trailing comma x2, missing comma" — what was repaired, once each. */
+export declare function summarizeRepairs(repairs: readonly JsonRepair[]): string;
+/**
+ * `parseModelJson` for an adapter: same result, and a log line when a repair
+ * was needed.
+ *
+ * The line names what was fixed and shows the text around the first fix, which
+ * is the only record there will be of what a model actually got wrong — the
+ * failed answers were never kept, and a repair that works leaves no error to
+ * read. `source` says which provider produced it.
+ */
+export declare function readModelJson(text: string, source: string): unknown;
+//# sourceMappingURL=json-repair.d.ts.map

package/dist/services/llm/json-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-repair.d.ts","sourceRoot":"","sources":["../../../src/services/llm/json-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,oDAAoD;AACpD,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAsZxE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CASjE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAQ5D;AAED,wEAAwE;AACxE,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,MAAM,SAAK,GACV,MAAM,CAMR;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAMvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAUnE"}