@plurnk/plurnk-providers 1.3.4 → 1.3.6

package/src/sdkModels.ts

@@ -0,0 +1,194 @@
+import { createAmazonBedrock } from "@ai-sdk/amazon-bedrock";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createDeepInfra } from "@ai-sdk/deepinfra";
+import { createGoogle } from "@ai-sdk/google";
+import { createGroq } from "@ai-sdk/groq";
+import { createMistral } from "@ai-sdk/mistral";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createTogetherAI } from "@ai-sdk/togetherai";
+import { createXai } from "@ai-sdk/xai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { lookupProvider, type ProviderInfo } from "@plurnk/plurnk-models";
+import type { LanguageModel } from "ai";
+
+export type SdkModel = {
+    readonly languageModel?: LanguageModel;
+    readonly compatible?: {
+        readonly url: string;
+        readonly headers: Readonly<Record<string, string>>;
+    };
+    readonly catalog: ProviderInfo | null;
+};
+
+const envPrefix = (provider: string): string =>
+    provider.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
+
+export const configuredProviderInfo = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+): ProviderInfo | null => {
+    const prefix = `PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}`;
+    const npm = env[`${prefix}_NPM`];
+    if (npm === undefined || npm.length === 0) return null;
+    const keyNames = env[`${prefix}_API_KEY_ENV`]
+        ?.split(",")
+        .map((name) => name.trim())
+        .filter(Boolean) ?? [];
+    const api = env[`${prefix}_BASE_URL`];
+    return {
+        id: provider,
+        npm,
+        env: keyNames,
+        ...(api === undefined || api.length === 0 ? {} : { api }),
+    };
+};
+
+const firstSet = (env: NodeJS.ProcessEnv, names: readonly string[]): string | undefined => {
+    for (const name of names) {
+        const value = env[name];
+        if (value !== undefined && value.length > 0) return value;
+    }
+    return undefined;
+};
+
+const configuredKeyNames = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): readonly string[] => {
+    const configured = env[`PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}_API_KEY_ENV`];
+    return configured === undefined || configured.length === 0
+        ? catalog.env
+        : configured.split(",").map((name) => name.trim()).filter(Boolean);
+};
+
+const expandEnv = (value: string, env: NodeJS.ProcessEnv, provider: string): string =>
+    value.replaceAll(/\$\{([A-Z0-9_]+)\}/g, (_match, name: string) => {
+        const replacement = env[name];
+        if (replacement === undefined || replacement.length === 0) {
+            throw new Error(`${provider} provider: ${name} must be set to resolve the Models.dev API URL`);
+        }
+        return replacement;
+    });
+
+const baseUrl = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+    override?: string,
+): string | undefined => {
+    const prefix = envPrefix(provider);
+    const configured = env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`]
+        ?? env[`${prefix}_BASE_URL`]
+        ?? catalog.api;
+    const value = override ?? configured;
+    return value === undefined ? undefined : expandEnv(value, env, provider).replace(/\/+$/, "");
+};
+
+const apiKey = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): string | undefined => firstSet(env, configuredKeyNames(provider, env, catalog));
+
+const requireApiKey = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): string => {
+    const names = configuredKeyNames(provider, env, catalog);
+    const key = firstSet(env, names);
+    if (key === undefined) throw new Error(`${provider} provider: ${names.join(" or ")} must be set`);
+    return key;
+};
+
+export const createSdkModel = (
+    provider: string,
+    model: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): SdkModel | null => {
+    const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
+    if (catalog === null) return null;
+    const url = baseUrl(provider, env, catalog, baseUrlOverride);
+
+    switch (catalog.npm) {
+        case "@ai-sdk/openai":
+            return {
+                languageModel: createOpenAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).chat(model),
+                catalog,
+            };
+        case "@ai-sdk/groq":
+            return {
+                languageModel: createGroq({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/mistral":
+            return {
+                languageModel: createMistral({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/togetherai":
+            return {
+                languageModel: createTogetherAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/deepinfra":
+            return {
+                languageModel: createDeepInfra({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/google":
+            return {
+                languageModel: createGoogle({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/xai":
+            return {
+                languageModel: createXai({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/anthropic":
+            return {
+                languageModel: createAnthropic({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/amazon-bedrock":
+            return {
+                languageModel: createAmazonBedrock({
+                    region: env.AWS_REGION ?? env.AWS_DEFAULT_REGION,
+                    accessKeyId: env.AWS_ACCESS_KEY_ID,
+                    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+                    sessionToken: env.AWS_SESSION_TOKEN,
+                    apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
+                    baseURL: url,
+                }).languageModel(model),
+                catalog,
+            };
+        case "@openrouter/ai-sdk-provider":
+            return {
+                languageModel: createOpenRouter({
+                    apiKey: requireApiKey(provider, env, catalog),
+                    baseURL: url,
+                    headers: {
+                        ...(env.OPENROUTER_HTTP_REFERER === undefined ? {} : { "HTTP-Referer": env.OPENROUTER_HTTP_REFERER }),
+                        ...(env.OPENROUTER_X_TITLE === undefined ? {} : { "X-Title": env.OPENROUTER_X_TITLE }),
+                    },
+                }).languageModel(model),
+                catalog,
+            };
+        case "@ai-sdk/openai-compatible":
+            if (url === undefined) throw new Error(`${provider} provider: Models.dev supplies no API URL and no base URL was configured`);
+            return {
+                compatible: {
+                    url: `${url}/chat/completions`,
+                    headers: apiKey(provider, env, catalog) === undefined
+                        ? {}
+                        : { Authorization: `Bearer ${apiKey(provider, env, catalog)}` },
+                },
+                catalog,
+            };
+        default:
+            throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
+    }
+};

package/src/telemetry.test.ts

@@ -1,7 +1,15 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
+import { APICallError } from "ai";
 import { ProviderError, classifyProviderError, toProviderError, providerSource } from "./telemetry.ts";
-import { OpenAiHttpError } from "./openaiStream.ts";
+
+const apiError = (statusCode: number, responseBody = "body") => new APICallError({
+    message: `request failed (${statusCode})`,
+    url: "https://example.test/v1/chat/completions",
+    requestBodyValues: {},
+    statusCode,
+    responseBody,
+});
 
 // Schema pattern for TelemetryEvent.source (from grammar's TelemetryEvent.json).
 const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
@@ -13,7 +21,7 @@ test("providerSource produces a schema-valid colon-namespaced source", () => {
 });
 
 test("classifyProviderError maps HTTP status to kind", () => {
-    const k = (status: number) => classifyProviderError(new OpenAiHttpError(status, "body", null)).kind;
+    const k = (status: number) => classifyProviderError(apiError(status)).kind;
     assert.equal(k(401), "unauthorized");
     assert.equal(k(403), "unauthorized");
     assert.equal(k(402), "quota_exceeded");
@@ -24,13 +32,11 @@ test("classifyProviderError maps HTTP status to kind", () => {
     assert.equal(k(404), "invalid_response");
 });
 
-test("classifyProviderError: a 422 flagged grammar_invalid is transient (#548); other 422s terminal", () => {
-    const rejected = new OpenAiHttpError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }), null);
+test("classifyProviderError: a 422 flagged grammar_invalid is distinct (#548); other 422s are invalid responses", () => {
+    const rejected = apiError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }));
     assert.equal(classifyProviderError(rejected).kind, "grammar_invalid");
-    // a 422 carrying any other error.type is a malformed request — terminal
-    assert.equal(classifyProviderError(new OpenAiHttpError(422, JSON.stringify({ error: { type: "invalid_request_error" } }), null)).kind, "invalid_response");
-    // a non-JSON 422 body (edge/proxy HTML) is terminal, and the sniff does not throw
-    assert.equal(classifyProviderError(new OpenAiHttpError(422, "<html>Bad</html>", null)).kind, "invalid_response");
+    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "invalid_response");
+    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "invalid_response");
 });
 
 test("classifyProviderError treats non-HTTP errors as network_failure", () => {
@@ -49,11 +55,12 @@ test("ProviderError.toTelemetryEvent emits the canonical envelope", () => {
 });
 
 test("toProviderError classifies and tags an HTTP error with the source + status", () => {
-    const pe = toProviderError(new OpenAiHttpError(401, "no key", null), "provider:groq");
+    const cause = apiError(401, "no key");
+    const pe = toProviderError(cause, "provider:groq");
     assert.equal(pe.kind, "unauthorized");
     assert.equal(pe.source, "provider:groq");
     assert.equal(pe.status, 401);
-    assert.equal(pe.cause instanceof OpenAiHttpError, true); // original preserved
+    assert.equal(pe.cause, cause);
 });
 
 test("toProviderError passes an existing ProviderError through unchanged", () => {

package/src/telemetry.ts

@@ -6,7 +6,7 @@
 // dependency on grammar (see SPEC §11). Consumers route provider events through
 // the same `source` + `kind` discriminator as parse/rail events.
 
-import { OpenAiHttpError } from "./openaiStream.ts";
+import { APICallError, RetryError } from "ai";
 
 // Required by the schema: source (producer id) + kind (discriminator). message
 // and position are optional. A transport failure isn't localizable, so it carries
@@ -29,11 +29,9 @@ export type ProviderTelemetryKind =
     | "invalid_response"
     | "unauthorized"
     | "quota_exceeded"
-    // A 422 whose error.type is "grammar_invalid" (#548): the backend served ONE
-    // generation and rejected it as non-conforming. Transient, not terminal — a
-    // fresh sample may conform — so it rides the retry budget. Distinct from
-    // grammar_unenforced below: that observes a SUCCEEDED exchange; this is a
-    // thrown transport failure the daemon retries, then fails as a leaf.
+    // A 422 whose error.type is "grammar_invalid" (#548): the backend served one
+    // generation and rejected it as non-conforming. This identifies the failure;
+    // whether to start another model exchange belongs to the engine.
     | "grammar_invalid"
     // Output did not conform to the GBNF. ALWAYS an observation, never a throw:
     // a completed exchange returns its bytes with this event on
@@ -80,18 +78,27 @@ const wireErrorType = (body: string): string | null => {
 // Map a thrown transport error to a (kind, message). Conservative; the message
 // is factual, no guidance prose (consumer SPEC §15.1 policy).
 export const classifyProviderError = (err: unknown): { kind: ProviderTelemetryKind; message: string } => {
-    if (err instanceof OpenAiHttpError) {
-        const { status, message } = err;
+    if (RetryError.isInstance(err)) return classifyProviderError(err.lastError);
+    if (APICallError.isInstance(err)) {
+        const status = err.statusCode ?? 0;
+        const message = err.message;
+        const body = err.responseBody ?? "";
         if (status === 401 || status === 403) return { kind: "unauthorized", message };
         if (status === 402) return { kind: "quota_exceeded", message };
         if (status === 429) return { kind: "rate_limit", message };
         if (status >= 500) return { kind: "network_failure", message };
-        // A 422 flagged grammar_invalid is a stochastic output reject (#548) — one
-        // generation served then rejected, so a fresh sample may conform: transient.
-        // Any other 422 is a malformed request: terminal (invalid_response).
-        if (status === 422 && wireErrorType(err.body) === "grammar_invalid") return { kind: "grammar_invalid", message };
+        // A flagged 422 identifies a grammar-rejected exchange. It is not
+        // transport replay policy; the engine decides whether to sample again.
+        if (status === 422 && wireErrorType(body) === "grammar_invalid") return { kind: "grammar_invalid", message };
         return { kind: "invalid_response", message };
     }
+    const wire = err as { message?: unknown; type?: unknown; status?: unknown };
+    if (wire?.type === "grammar_invalid") {
+        return {
+            kind: "grammar_invalid",
+            message: typeof wire.message === "string" ? wire.message : "grammar-invalid response",
+        };
+    }
     const e = err as { name?: string; message?: string };
     const message = (e?.message ?? String(err)) || "request failed";
     // Timeouts / fetch-level failures are transport, not a usable response.
@@ -102,7 +109,8 @@ export const classifyProviderError = (err: unknown): { kind: ProviderTelemetryKi
 // Already-classified errors pass through unchanged.
 export const toProviderError = (err: unknown, source: string): ProviderError => {
     if (err instanceof ProviderError) return err;
-    const { kind, message } = classifyProviderError(err);
-    const status = err instanceof OpenAiHttpError ? err.status : null;
+    const underlying = RetryError.isInstance(err) ? err.lastError : err;
+    const { kind, message } = classifyProviderError(underlying);
+    const status = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
     return new ProviderError(source, kind, message, { status, cause: err });
 };

package/src/types.ts

@@ -3,6 +3,7 @@
 // is the wire-reported CoT only.
 
 import type { TelemetryEvent } from "./telemetry.ts";
+import type { LanguageModel } from "ai";
 
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
@@ -69,9 +70,9 @@ export interface ProviderResponse {
     readonly assistant: ProviderAssistant;
     readonly assistantRaw: unknown;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
-    // response fields, passed through verbatim, PLUS validated known keys we hold a
-    // contract for (e.g. `balancePico` — a finite pico-USD number, from the plurnk
-    // endpoint). The consumer (service) merges this into its Turn metadata and
+    // response fields passed through verbatim. Monetary values carry their own
+    // amount and currency; the provider does not reinterpret them. The consumer
+    // (service) merges this into its Turn metadata and
     // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.
     // Absent when the backend reported no extra fields (#23, generalized).
     readonly meta?: Record<string, unknown>;
@@ -191,9 +192,9 @@ export interface Provider {
     // `tokenize === undefined` means the backend can't. Exact-counting
     // consumers (the tokenizer seam) prefer this over any client-side data.
     tokenize?(text: string): Promise<number[]>;
-    // Provider-owned cost calculation. Returns pico-USD (1e-12 USD).
+    // Provider-owned estimated cost calculation. Returns USD.
     // Returns 0 for siblings/models with no known rates.
-    costFor(usage: ProviderUsage): number;
+    calculateCost(usage: ProviderUsage): number;
 }
 
 // ProviderAlias moved to @plurnk/plurnk-aliases (the zero-dep parser, #27);
@@ -208,12 +209,8 @@ export interface ProviderOptions {
     readonly baseUrl?: string;
 }
 
-// Each provider package's default export MUST be a factory:
-//   static fromEnv(env, model, options?) → Provider | Promise<Provider>
-// `model` is the second positional arg because PLURNK_MODEL_<alias>=<provider>/<model>
-// is parsed by the registry; the resolved model id flows through. `options` is an
-// optional third arg (per-alias overrides, e.g. baseUrl); a factory that ignores
-// it keeps working unchanged.
-export interface ProviderFactory {
-    fromEnv(env: NodeJS.ProcessEnv, model: string, options?: ProviderOptions): Provider | Promise<Provider>;
+// A discovered provider plugin default-exports an AI SDK provider. PLURNK owns
+// the adapter into Provider; the plugin owns only its protocol binding.
+export interface AiSdkProviderPlugin {
+    languageModel(model: string): LanguageModel;
 }

package/src/usage.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { normalizeUsage, computeCost } from "./usage.ts";
+import { normalizeUsage, calculateCostUsd } from "./usage.ts";
 
 // — normalizeUsage —
 
@@ -115,22 +115,20 @@ test("normalizeUsage: no total reported -> re-split skipped, reasoning stays 0 (
     assert.deepEqual(u, { prompt: 10, completion: 20, reasoning: 0, cached: 0, total: 30 });
 });
 
-// — computeCost —
+// — calculateCostUsd —
 
-test("computeCost: bills reasoning at the output rate", () => {
+test("calculateCostUsd: bills reasoning at the USD-per-million output rate", () => {
     // 100 input, 0 cached, 50 completion + 200 reasoning = 250 output.
     const usage = { prompt: 100, completion: 50, reasoning: 200, cached: 0, total: 350 };
-    // input 1 pico/tok, output 10 pico/tok → 100*1 + 250*10 = 2600
-    assert.equal(computeCost(usage, { input: 1, output: 10, cached: 0 }), 2600);
+    assert.equal(calculateCostUsd(usage, { input: 1, output: 10, cached: 0 }), 0.0026);
 });
 
-test("computeCost: cached prompt billed at the cache rate, remainder at input", () => {
+test("calculateCostUsd: cached prompt billed at the cache rate, remainder at input", () => {
     const usage = { prompt: 1000, completion: 0, reasoning: 0, cached: 400, total: 1000 };
-    // 600 non-cached @5 + 400 cached @1 = 3000 + 400 = 3400
-    assert.equal(computeCost(usage, { input: 5, output: 99, cached: 1 }), 3400);
+    assert.equal(calculateCostUsd(usage, { input: 5, output: 99, cached: 1 }), 0.0034);
 });
 
-test("computeCost: zero rates → 0", () => {
+test("calculateCostUsd: zero rates → 0", () => {
     const usage = { prompt: 9, completion: 9, reasoning: 9, cached: 9, total: 27 };
-    assert.equal(computeCost(usage, { input: 0, output: 0, cached: 0 }), 0);
+    assert.equal(calculateCostUsd(usage, { input: 0, output: 0, cached: 0 }), 0);
 });

package/src/usage.ts

@@ -69,14 +69,18 @@ export const normalizeUsage = (raw: RawUsage | null | undefined, reasoningText =
     return { prompt, completion, reasoning, cached, total };
 };
 
-// Per-token rates in pico-USD (1e-12 USD).
+// Conventional provider pricing: USD per million tokens, matching Models.dev.
 export type TokenRates = { input: number; output: number; cached: number };
 
 // The one cost formula every provider uses: non-cached prompt at the input
 // rate, cached prompt at the cache rate, and billable output (completion +
 // reasoning) at the output rate.
-export const computeCost = (usage: ProviderUsage, rates: TokenRates): number => {
+export const calculateCostUsd = (usage: ProviderUsage, rates: TokenRates): number => {
     const nonCachedPrompt = Math.max(0, usage.prompt - usage.cached);
     const output = usage.completion + usage.reasoning;
-    return Math.round(nonCachedPrompt * rates.input + usage.cached * rates.cached + output * rates.output);
+    return (
+        nonCachedPrompt * rates.input
+        + usage.cached * rates.cached
+        + output * rates.output
+    ) / 1_000_000;
 };