@node-llm/core 1.17.1 → 1.18.0

package/dist/judge/Question.js

@@ -0,0 +1,180 @@
+/**
+ * Typed questions for judgments.
+ *
+ * A judgment asks a set of named questions about one input and returns a typed
+ * answer for each: the probability that a statement holds, a choice among named
+ * options, or a score on an ordered scale. Questions are plain data, so they
+ * can be declared on a Judge class, passed to NodeLLM.judge, or built at
+ * runtime from application data.
+ */
+/**
+ * Declares a yes/no question whose answer is the probability of yes. A value
+ * near 0.5 means yes and no are about equally likely, not "medium"; use a
+ * score to measure degree.
+ *
+ * @example
+ * probability("Does this need attention today?", {
+ *   yes: "An explicit deadline today or an ongoing outage",
+ *   no: "A general question with no time pressure"
+ * })
+ */
+export function probability(instructions, criteria) {
+    return { type: "probability", instructions, ...(criteria ? { criteria } : {}) };
+}
+/**
+ * Declares a question that selects one named option and returns a probability
+ * for every option. Include a catch-all such as `other` when none of the
+ * specific options may fit. Use null for an option that needs no description.
+ *
+ * @example
+ * choice("Which team should handle this?", {
+ *   billing: "Payments and refunds",
+ *   technical: "Bugs and integrations",
+ *   other: null
+ * })
+ */
+export function choice(instructions, options) {
+    return { type: "choice", instructions, options };
+}
+/**
+ * Declares a question scored against ordered levels. The first level is 0, the
+ * second 1, and so on; the answer is probability-weighted and can fall between
+ * levels. Describe each level concretely.
+ *
+ * @example
+ * score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ */
+export function score(instructions, levels) {
+    return { type: "score", instructions, levels };
+}
+function isDescription(value) {
+    if (value === null || typeof value === "string")
+        return true;
+    if (Array.isArray(value))
+        return value.every(isJson);
+    if (typeof value === "object")
+        return isJson(value);
+    return false;
+}
+function isJson(value) {
+    if (value === null)
+        return true;
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return true;
+        case "number":
+            return Number.isFinite(value);
+        case "object":
+            if (Array.isArray(value))
+                return value.every(isJson);
+            if (Object.getPrototypeOf(value) !== Object.prototype &&
+                Object.getPrototypeOf(value) !== null) {
+                return false;
+            }
+            return Object.values(value).every(isJson);
+        default:
+            return false;
+    }
+}
+function invalid(name, message) {
+    throw new Error(`Invalid judgment question '${name}': ${message}`);
+}
+function validateDescriptions(name, values) {
+    if (!values.every(isDescription)) {
+        invalid(name, "descriptions must be text, an object, an array, or null");
+    }
+}
+/**
+ * Validates every question and returns them in declaration order with their
+ * names attached. Rejects the problems a provider would otherwise report as an
+ * opaque 400: unknown types, empty choices or scales, and probability criteria
+ * that describe anything other than yes and no.
+ */
+export function normalizeQuestions(questions) {
+    if (!questions || typeof questions !== "object" || Array.isArray(questions)) {
+        throw new Error("Judgment questions must be an object keyed by question name");
+    }
+    const entries = Object.entries(questions);
+    if (entries.length === 0) {
+        throw new Error("A judgment needs at least one question");
+    }
+    return entries.map(([name, question]) => {
+        if (name.length === 0)
+            invalid(name, "a question name cannot be empty");
+        if (!question || typeof question !== "object")
+            invalid(name, "the definition must be an object");
+        if (question.instructions !== undefined && !isDescription(question.instructions)) {
+            invalid(name, "instructions must be text, an object, an array, or null");
+        }
+        switch (question.type) {
+            case "probability":
+                validateProbability(name, question);
+                break;
+            case "choice":
+                validateChoice(name, question);
+                break;
+            case "score":
+                validateScore(name, question);
+                break;
+            default:
+                invalid(name, `unknown type '${String(question.type)}'`);
+        }
+        return { ...question, name };
+    });
+}
+function validateProbability(name, question) {
+    const extra = Object.keys(question).filter((k) => !["type", "instructions", "criteria"].includes(k));
+    if (extra.length > 0)
+        invalid(name, `unknown fields ${extra.join(", ")}`);
+    if (question.criteria === undefined)
+        return;
+    const criteria = question.criteria;
+    if (!criteria || typeof criteria !== "object" || Array.isArray(criteria)) {
+        invalid(name, "probability criteria must describe yes and no");
+    }
+    const keys = Object.keys(criteria);
+    const unknown = keys.filter((k) => !["yes", "no", "true", "false"].includes(k));
+    if (unknown.length > 0)
+        invalid(name, "probability criteria must describe yes and no");
+    // yes/true and no/false are the same outcome; describing one twice is ambiguous.
+    const positives = keys.filter((k) => k === "yes" || k === "true").length;
+    const negatives = keys.filter((k) => k === "no" || k === "false").length;
+    if (positives > 1 || negatives > 1)
+        invalid(name, "probability criteria contain duplicate outcomes");
+    validateDescriptions(name, Object.values(criteria));
+}
+function validateChoice(name, question) {
+    const extra = Object.keys(question).filter((k) => !["type", "instructions", "options"].includes(k));
+    if (extra.length > 0)
+        invalid(name, `unknown fields ${extra.join(", ")}`);
+    const options = question.options;
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        invalid(name, "a choice needs a non-empty object of options");
+    }
+    const keys = Object.keys(options);
+    if (keys.length === 0)
+        invalid(name, "a choice needs a non-empty object of options");
+    if (keys.some((k) => k.length === 0))
+        invalid(name, "choice options must have non-empty names");
+    validateDescriptions(name, Object.values(options));
+}
+function validateScore(name, question) {
+    const extra = Object.keys(question).filter((k) => !["type", "instructions", "levels"].includes(k));
+    if (extra.length > 0)
+        invalid(name, `unknown fields ${extra.join(", ")}`);
+    if (!Array.isArray(question.levels) || question.levels.length === 0) {
+        invalid(name, "a score needs a non-empty array of levels");
+    }
+    validateDescriptions(name, question.levels);
+}
+/** True when the value can be sent as judgment input. */
+export function isJudgmentInput(value) {
+    if (typeof value === "string")
+        return true;
+    if (Array.isArray(value))
+        return isJson(value);
+    if (value !== null && typeof value === "object")
+        return isJson(value);
+    return false;
+}

package/dist/llm.d.ts

@@ -9,6 +9,9 @@ import { Moderation } from "./moderation/Moderation.js";
 import { Embedding } from "./embedding/Embedding.js";
 import { NodeLLMConfig } from "./config.js";
 import { Middleware } from "./types/Middleware.js";
+import { JudgmentInput } from "./providers/Provider.js";
+import { QuestionMap } from "./judge/Question.js";
+import { JudgmentResult } from "./judge/Judgment.js";
 export interface RetryOptions {
     attempts?: number;
     delayMs?: number;
@@ -21,6 +24,7 @@ type LLMConfig = {
     defaultTranscriptionModel?: string;
     defaultModerationModel?: string;
     defaultEmbeddingModel?: string;
+    defaultJudgmentModel?: string;
 } & Omit<Partial<NodeLLMConfig>, "provider">;
 export declare class NodeLLMCore {
     readonly config: NodeLLMConfig;
@@ -35,11 +39,13 @@ export declare class NodeLLMCore {
         transcription?: string;
         moderation?: string;
         embedding?: string;
+        judgment?: string;
     });
     get defaultChatModel(): string | undefined;
     get defaultTranscriptionModel(): string | undefined;
     get defaultModerationModel(): string | undefined;
     get defaultEmbeddingModel(): string | undefined;
+    get defaultJudgmentModel(): string | undefined;
     /**
      * Returns a scoped LLM instance configured for a specific provider.
      * This returns a NEW immutable instance.
@@ -72,6 +78,8 @@ export declare class NodeLLMCore {
         language?: string;
         speakerNames?: string[];
         speakerReferences?: string[];
+        /** Word and/or segment timestamps, where the provider supports them. */
+        timestamp_granularities?: ("word" | "segment")[];
         assumeModelExists?: boolean;
         requestTimeout?: number;
         middlewares?: Middleware[];
@@ -89,6 +97,44 @@ export declare class NodeLLMCore {
         requestTimeout?: number;
         middlewares?: Middleware[];
     }): Promise<Embedding>;
+    /**
+     * Asks typed questions about one input and returns a typed answer for each:
+     * a probability, a choice among named options, or a score on a scale.
+     *
+     * The provider follows the model: `jev-latest` (the default) is answered by
+     * TypeSafe whichever provider this instance is scoped to. Pass `provider` to
+     * route explicitly, for example to a Jev-compatible local server configured
+     * through `typesafeApiBase`.
+     *
+     * Each call judges only the input given; it keeps no conversation history.
+     *
+     * @example
+     * const judgment = await NodeLLM.judge("Please refund the duplicate charge today.", {
+     *   questions: {
+     *     urgent: probability("Does this need attention today?"),
+     *     team: choice("Which team should handle this?", { billing: "Payments", other: null })
+     *   }
+     * });
+     * judgment.urgent.probability; // 0.91
+     * judgment.team.choice;        // "billing"
+     */
+    judge<const Q extends QuestionMap>(input: JudgmentInput, options: {
+        questions: Q;
+        model?: string;
+        provider?: string;
+        /** Provider-specific fields merged into the request body. */
+        providerOptions?: Record<string, unknown>;
+        requestTimeout?: number;
+        middlewares?: Middleware[];
+    }): Promise<JudgmentResult<Q>>;
+    /**
+     * Picks the provider that answers judgments for a model: an explicit choice
+     * first, then the registry's owner of a known judgment model, then this
+     * instance's own provider - which is how a model the registry does not know,
+     * such as one on a local Jev-compatible server, reaches the provider it was
+     * scoped to.
+     */
+    private judgmentProvider;
 }
 export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };
 /**

package/dist/llm.d.ts.map

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

package/dist/llm.js

@@ -1,16 +1,19 @@
 import { Chat } from "./chat/Chat.js";
-import { providerRegistry, ensureOpenAIRegistered, registerAnthropicProvider, registerGeminiProvider, registerDeepSeekProvider, registerOllamaProvider, registerOpenRouterProvider, registerBedrockProvider, registerXAIProvider, registerMistralProvider } from "./providers/registry.js";
+import { providerRegistry, ensureOpenAIRegistered, registerAnthropicProvider, registerGeminiProvider, registerDeepSeekProvider, registerOllamaProvider, registerOpenRouterProvider, registerBedrockProvider, registerXAIProvider, registerMistralProvider, registerTypeSafeProvider } from "./providers/registry.js";
 import { GeneratedImage } from "./image/GeneratedImage.js";
 import { ModelRegistry } from "./models/ModelRegistry.js";
 import { PricingRegistry } from "./models/PricingRegistry.js";
 import { Transcription } from "./transcription/Transcription.js";
 import { Moderation } from "./moderation/Moderation.js";
 import { Embedding } from "./embedding/Embedding.js";
-import { ProviderNotConfiguredError, UnsupportedFeatureError, ModelCapabilityError } from "./errors/index.js";
+import { ProviderNotConfiguredError, UnsupportedFeatureError, ModelCapabilityError, ConfigurationError } from "./errors/index.js";
 import { resolveModelAlias } from "./model_aliases.js";
 import { logger } from "./utils/logger.js";
 import { config, Configuration } from "./config.js";
 import { runMiddleware } from "./utils/middleware-runner.js";
+import { normalizeQuestions, isJudgmentInput } from "./judge/Question.js";
+import { buildJudgment } from "./judge/Judgment.js";
+import { DEFAULT_MODELS } from "./constants.js";
 import { randomUUID } from "node:crypto";
 // Provider registration map
 const PROVIDER_REGISTRARS = {
@@ -22,7 +25,8 @@ const PROVIDER_REGISTRARS = {
     openrouter: registerOpenRouterProvider,
     bedrock: registerBedrockProvider,
     xai: registerXAIProvider,
-    mistral: registerMistralProvider
+    mistral: registerMistralProvider,
+    typesafe: registerTypeSafeProvider
 };
 export class NodeLLMCore {
     config;
@@ -54,6 +58,9 @@ export class NodeLLMCore {
     get defaultEmbeddingModel() {
         return this.defaults.embedding;
     }
+    get defaultJudgmentModel() {
+        return this.defaults.judgment;
+    }
     /**
      * Returns a scoped LLM instance configured for a specific provider.
      * This returns a NEW immutable instance.
@@ -70,7 +77,8 @@ export class NodeLLMCore {
             defaultChatModel: this.defaults.chat,
             defaultTranscriptionModel: this.defaults.transcription,
             defaultModerationModel: this.defaults.moderation,
-            defaultEmbeddingModel: this.defaults.embedding
+            defaultEmbeddingModel: this.defaults.embedding,
+            defaultJudgmentModel: this.defaults.judgment
         });
     }
     /**
@@ -281,6 +289,97 @@ export class NodeLLMCore {
             throw error;
         }
     }
+    /**
+     * Asks typed questions about one input and returns a typed answer for each:
+     * a probability, a choice among named options, or a score on a scale.
+     *
+     * The provider follows the model: `jev-latest` (the default) is answered by
+     * TypeSafe whichever provider this instance is scoped to. Pass `provider` to
+     * route explicitly, for example to a Jev-compatible local server configured
+     * through `typesafeApiBase`.
+     *
+     * Each call judges only the input given; it keeps no conversation history.
+     *
+     * @example
+     * const judgment = await NodeLLM.judge("Please refund the duplicate charge today.", {
+     *   questions: {
+     *     urgent: probability("Does this need attention today?"),
+     *     team: choice("Which team should handle this?", { billing: "Payments", other: null })
+     *   }
+     * });
+     * judgment.urgent.probability; // 0.91
+     * judgment.team.choice;        // "billing"
+     */
+    async judge(input, options) {
+        if (!isJudgmentInput(input)) {
+            throw new Error("Judgment input must be text, an object, or an array of JSON-compatible values");
+        }
+        const questions = normalizeQuestions(options.questions);
+        const model = options.model || this.defaults.judgment || DEFAULT_MODELS.JUDGMENT;
+        const provider = this.judgmentProvider(model, options.provider);
+        if (!provider.judge) {
+            throw new UnsupportedFeatureError(provider.id, "judge");
+        }
+        const context = {
+            requestId: randomUUID(),
+            provider: provider.id,
+            model,
+            judgmentInput: input,
+            judgmentOptions: options,
+            state: {}
+        };
+        const middlewares = [...this.middlewares, ...(options.middlewares || [])];
+        try {
+            await runMiddleware(middlewares, "onRequest", context);
+            const response = await provider.judge({
+                model,
+                input: context.judgmentInput ?? input,
+                questions,
+                providerOptions: options.providerOptions,
+                requestTimeout: options.requestTimeout ?? this.config.requestTimeout
+            });
+            // Priced by the requested model, which is what the registry knows; the
+            // response names the exact build that answered (jev-latest comes back as
+            // e.g. jev-1.13.0). An unpriced model leaves cost undefined rather than a
+            // guessed number.
+            const usage = ModelRegistry.calculateCost(response.usage, model, provider.id);
+            const judgment = buildJudgment({ ...response, usage }, questions);
+            await runMiddleware(middlewares, "onResponse", context, judgment);
+            return judgment;
+        }
+        catch (error) {
+            await runMiddleware(middlewares, "onError", context, error);
+            throw error;
+        }
+    }
+    /**
+     * Picks the provider that answers judgments for a model: an explicit choice
+     * first, then the registry's owner of a known judgment model, then this
+     * instance's own provider - which is how a model the registry does not know,
+     * such as one on a local Jev-compatible server, reaches the provider it was
+     * scoped to.
+     */
+    judgmentProvider(model, explicit) {
+        const known = ModelRegistry.find(model);
+        const owner = explicit ??
+            (known &&
+                known.id.toLowerCase() === model.toLowerCase() &&
+                known.capabilities?.includes("judgment")
+                ? known.provider
+                : undefined);
+        if (!owner || owner === this.provider?.id) {
+            if (!this.provider) {
+                // Guessing a provider for an unknown model would send the request (and
+                // the credentials) somewhere the caller did not choose.
+                throw new ConfigurationError(`Unknown judgment model '${model}': no provider is known to serve it. ` +
+                    `Pass \`provider\` (for example "typesafe"), or call judge on ` +
+                    `NodeLLM.withProvider("typesafe").`);
+            }
+            return this.provider;
+        }
+        PROVIDER_REGISTRARS[owner]?.();
+        return providerRegistry.resolve(owner, this.config);
+    }
 }
 export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };
 /**
@@ -330,7 +429,8 @@ export function createLLM(options = {}) {
         chat: options.defaultChatModel,
         transcription: options.defaultTranscriptionModel,
         moderation: options.defaultModerationModel,
-        embedding: options.defaultEmbeddingModel
+        embedding: options.defaultEmbeddingModel,
+        judgment: options.defaultJudgmentModel
     };
     return new NodeLLMCore(baseConfig, providerInstance, retry, options.middlewares || [], defaults);
 }

package/dist/models/ModelRegistry.d.ts

@@ -25,30 +25,23 @@ export declare class ModelRegistry {
     /**
      * Calculate cost for usage.
      */
-    static calculateCost(usage: {
-        input_tokens: number;
-        output_tokens: number;
-        total_tokens: number;
-        cached_tokens?: number;
-        reasoning_tokens?: number;
-        image_tokens?: number;
-    }, modelId: string, provider: string): {
-        input_tokens: number;
-        output_tokens: number;
-        total_tokens: number;
-        cached_tokens?: number;
-        reasoning_tokens?: number;
-        image_tokens?: number;
-    } | {
-        input_cost: number;
-        output_cost: number;
-        cost: number;
+    /**
+     * Returns the usage with `input_cost`, `output_cost` and `cost` added when the
+     * model has known pricing. Without pricing the usage comes back unchanged and
+     * the cost fields are undefined - declared on the return type either way, so
+     * callers can read `.cost` without a cast.
+     */
+    static calculateCost<U extends {
         input_tokens: number;
         output_tokens: number;
         total_tokens: number;
         cached_tokens?: number;
         reasoning_tokens?: number;
         image_tokens?: number;
+    }>(usage: U, modelId: string, provider: string): U & {
+        input_cost?: number;
+        output_cost?: number;
+        cost?: number;
     };
 }
 //# sourceMappingURL=ModelRegistry.d.ts.map

package/dist/models/ModelRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelRegistry.d.ts","sourceRoot":"","sources":["../../src/models/ModelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAInC,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAA6C;IAElE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAmBlE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,IAAI;IAe1C;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAwB/E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9E;;OAEG;IACH,MAAM,CAAC,aAAa,CAClB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,EACD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;sBARA,MAAM;uBACL,MAAM;sBACP,MAAM;wBACJ,MAAM;2BACH,MAAM;uBACV,MAAM;;;;;sBALP,MAAM;uBACL,MAAM;sBACP,MAAM;wBACJ,MAAM;2BACH,MAAM;uBACV,MAAM;;CAoD1B"}
+{"version":3,"file":"ModelRegistry.d.ts","sourceRoot":"","sources":["../../src/models/ModelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAInC,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAA6C;IAElE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAmBlE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,IAAI;IAe1C;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAwB/E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9E;;OAEG;IACH;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAClB,CAAC,SAAS;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,EAED,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;CAgDpE"}

package/dist/models/ModelRegistry.js

@@ -77,6 +77,12 @@ export class ModelRegistry {
     /**
      * Calculate cost for usage.
      */
+    /**
+     * Returns the usage with `input_cost`, `output_cost` and `cost` added when the
+     * model has known pricing. Without pricing the usage comes back unchanged and
+     * the cost fields are undefined - declared on the return type either way, so
+     * callers can read `.cost` without a cast.
+     */
     static calculateCost(usage, modelId, provider) {
         const pricing = PricingRegistry.getPricing(modelId, provider);
         if (!pricing) {