@plurnk/plurnk-providers 1.11.0 → 1.12.0

package/src/sdkModels.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { configuredProviderInfo, createSdkModel, providerReadiness } from "./sdkModels.ts";
+import { configuredProviderInfo, createEmbeddingModel, createSdkModel, providerReadiness } from "./sdkModels.ts";
 
 test("{§provider-fact-authority} one env declaration holds one credential name", () => {
     assert.deepEqual(configuredProviderInfo("acme-cloud", {
@@ -290,3 +290,44 @@ test("createSdkModel fails clearly for a declared but unsupported SDK package",
         /Models.dev declares unsupported AI SDK package @acme\/ai-sdk/,
     );
 });
+
+test("{§provider-embedding-resolution} compatible catalog and declared routes share the standard embedding adapter", () => {
+    const cloudflare = createEmbeddingModel("cloudflare", "@cf/qwen/qwen3-embedding-0.6b", {
+        CLOUDFLARE_ACCOUNT_ID: "account",
+        CLOUDFLARE_API_KEY: "key",
+    });
+    assert.equal(cloudflare?.providerId, "cloudflare-workers-ai");
+    assert.equal(cloudflare?.embeddingModel.provider, "cloudflare.embedding");
+    assert.equal(cloudflare?.embeddingModel.modelId, "@cf/qwen/qwen3-embedding-0.6b");
+
+    const fireworks = createEmbeddingModel("fireworks", "fireworks/qwen3-embedding-8b", {
+        FIREWORKS_API_KEY: "key",
+    });
+    assert.equal(fireworks?.providerId, "fireworks-ai");
+    assert.equal(fireworks?.embeddingModel.provider, "fireworks.embedding");
+
+    const local = createEmbeddingModel("local-embed", "Qwen/Qwen3-Embedding-0.6B", {
+        PLURNK_PROVIDERS_PROVIDER_LOCAL_EMBED_NPM: "@ai-sdk/openai-compatible",
+        PLURNK_PROVIDERS_PROVIDER_LOCAL_EMBED_BASE_URL: "http://127.0.0.1:8080/v1",
+    });
+    assert.equal(local?.providerId, "local-embed");
+    assert.equal(local?.embeddingModel.provider, "local-embed.embedding");
+});
+
+test("{§provider-embedding-resolution} OpenRouter uses its official embedding model", () => {
+    const resolved = createEmbeddingModel("openrouter", "openai/text-embedding-3-small", {
+        OPENROUTER_API_KEY: "key",
+        OPENROUTER_HTTP_REFERER: "https://github.com/plurnk/plurnk-service",
+        OPENROUTER_APP_TITLE: "Plurnk",
+    });
+    assert.equal(resolved?.providerId, "openrouter");
+    assert.equal(resolved?.embeddingModel.provider, "openrouter");
+    assert.equal(resolved?.embeddingModel.modelId, "openai/text-embedding-3-small");
+});
+
+test("{§provider-embedding-resolution} a generation-only SDK fails before transport", () => {
+    assert.throws(
+        () => createEmbeddingModel("cerebras", "text-embedding", { CEREBRAS_API_KEY: "key" }),
+        /@ai-sdk\/cerebras does not expose an embedding model/,
+    );
+});

package/src/sdkModels.ts

@@ -6,18 +6,29 @@ 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 { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { createTogetherAI } from "@ai-sdk/togetherai";
 import { createXai } from "@ai-sdk/xai";
+import type { EmbeddingModelV4, EmbeddingModelV4Result } from "@ai-sdk/provider";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import {
     isProviderCredentialName,
+    lookup,
     lookupProvider,
     providerCatalogSnapshot,
     type ProviderInfo,
 } from "@plurnk/plurnk-models";
-import { Validator, type ModelReadiness, type ModelReadinessCause, type ReasoningPolicy } from "@plurnk/plurnk-contracts";
+import {
+    Validator,
+    type ModelReadiness,
+    type ModelReadinessCause,
+    type ProviderRequestAccounting,
+    type ProviderUsage,
+    type ReasoningPolicy,
+} from "@plurnk/plurnk-contracts";
 import type { LanguageModel } from "ai";
-import { providerCostNormalizer } from "./accounting.ts";
+import { providerCostNormalizer, validateProviderRequestAccounting } from "./accounting.ts";
+import { estimateProviderCost, resolveProviderCost } from "./cost.ts";
 import type { AiSdkProviderOptions, CacheAffinity } from "./AiSdkProvider.ts";
 import type { ProviderCostNormalizer } from "./types.ts";
 
@@ -35,6 +46,17 @@ export type SdkModel = {
     readonly catalog: ProviderInfo | null;
 };
 
+export type EmbeddingModelResolution = {
+    readonly embeddingModel: EmbeddingModelV4;
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly normalizeAccounting: (evidence: {
+        readonly outcome: "response" | "error";
+        readonly status?: number;
+        readonly result?: EmbeddingModelV4Result;
+    }) => ProviderRequestAccounting;
+};
+
 const cacheControl = { type: "ephemeral" as const };
 // The release generator admits only packages implemented by this package.
 // Derive runtime readiness from that same pinned provider projection instead
@@ -297,20 +319,30 @@ const openRouterReasoningSettings = (
         ? {}
         : { reasoning: { effort: reasoning === "off" ? "none" : reasoning } };
 
-export const createSdkModel = (
+const resolveSdkProvider = (
     provider: string,
-    model: string,
     env: NodeJS.ProcessEnv,
     baseUrlOverride?: string,
-    reasoning?: ReasoningPolicy,
-): SdkModel | null => {
+): { catalog: ProviderInfo; url: string | undefined } | null => {
     const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
     if (catalog === null) return null;
     if (!supportedSdkPackages.has(catalog.npm)) {
         throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
     }
     assertProviderReady(provider, env, baseUrlOverride);
-    const url = baseUrl(provider, env, catalog, baseUrlOverride);
+    return { catalog, url: baseUrl(provider, env, catalog, baseUrlOverride) };
+};
+
+export const createSdkModel = (
+    provider: string,
+    model: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+    reasoning?: ReasoningPolicy,
+): SdkModel | null => {
+    const resolved = resolveSdkProvider(provider, env, baseUrlOverride);
+    if (resolved === null) return null;
+    const { catalog, url } = resolved;
     const normalizeCost = providerCostNormalizer(catalog.npm);
 
     switch (catalog.npm) {
@@ -430,3 +462,108 @@ export const createSdkModel = (
             throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
     }
 };
+
+// {§provider-embedding-resolution} Provider construction owns transport and
+// authentication only. Model-space facts stay in the embedding profile.
+export const createEmbeddingModel = (
+    provider: string,
+    model: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): EmbeddingModelResolution | null => {
+    const resolved = resolveSdkProvider(provider, env, baseUrlOverride);
+    if (resolved === null) return null;
+    const { catalog, url } = resolved;
+    const directCost = providerCostNormalizer(catalog.npm);
+    const modelCost = lookup(provider, model)?.cost ?? lookup(catalog.id, model)?.cost;
+    const rates = modelCost === undefined
+        ? null
+        : {
+            input: modelCost.inputPer1M,
+            output: modelCost.outputPer1M,
+            ...(modelCost.reasoningPer1M === undefined ? {} : { reasoning: modelCost.reasoningPer1M }),
+            ...(modelCost.cacheReadPer1M === undefined ? {} : { cacheRead: modelCost.cacheReadPer1M }),
+            ...(modelCost.cacheWritePer1M === undefined ? {} : { cacheWrite: modelCost.cacheWritePer1M }),
+        };
+    const normalizeAccounting: EmbeddingModelResolution["normalizeAccounting"] = (evidence) => {
+        const tokens = evidence.result?.usage?.tokens;
+        const usage: ProviderUsage | undefined = Number.isSafeInteger(tokens) && tokens! >= 0
+            ? { inputTokens: tokens!, outputTokens: 0, totalTokens: tokens! }
+            : undefined;
+        const body = evidence.result?.response?.body;
+        const rawUsage = typeof body === "object" && body !== null && !Array.isArray(body)
+            ? (body as Record<string, unknown>).usage
+            : undefined;
+        const direct = directCost?.({
+            providerMetadata: evidence.result?.providerMetadata,
+            usage: rawUsage,
+            response: { headers: evidence.result?.response?.headers },
+        });
+        const cost = resolveProviderCost(
+            direct,
+            estimateProviderCost(
+                usage,
+                rates,
+                `Models.dev ${catalog.id}/${model} rates`,
+            ),
+        );
+        return validateProviderRequestAccounting({
+            provider: catalog.id,
+            model,
+            outcome: evidence.outcome,
+            ...(evidence.status === undefined ? {} : { status: evidence.status }),
+            ...(usage === undefined ? {} : { usage }),
+            cost,
+        });
+    };
+    const result = (embeddingModel: EmbeddingModelV4): EmbeddingModelResolution => ({
+        embeddingModel,
+        providerId: catalog.id,
+        modelId: model,
+        normalizeAccounting,
+    });
+
+    switch (catalog.npm) {
+        case "@ai-sdk/openai":
+            return result(createOpenAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
+        case "@ai-sdk/google":
+            return result(createGoogle({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
+        case "@ai-sdk/mistral":
+            return result(createMistral({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
+        case "@ai-sdk/deepinfra":
+            return result(createDeepInfra({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embeddingModel(model));
+        case "@ai-sdk/togetherai":
+            return result(createTogetherAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embeddingModel(model));
+        case "@ai-sdk/amazon-bedrock":
+            return result(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,
+            }).embedding(model));
+        case "@openrouter/ai-sdk-provider":
+            return result(createOpenRouter({
+                apiKey: requireApiKey(provider, env, catalog),
+                baseURL: url,
+                headers: openRouterHeaders(provider, env, catalog),
+            }).textEmbeddingModel(model));
+        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`);
+            }
+            const keyNames = configuredKeyNames(provider, env, catalog);
+            const key = keyNames.length === 0 ? undefined : requireApiKey(provider, env, catalog);
+            return result(createOpenAICompatible({
+                name: provider,
+                baseURL: url,
+                ...(key === undefined ? {} : { apiKey: key }),
+            }).embeddingModel(model));
+        }
+        default:
+            throw new Error(
+                `${provider} provider: ${catalog.npm} does not expose an embedding model through Plurnk's AI SDK adapter`,
+            );
+    }
+};

package/src/types.ts

@@ -12,6 +12,7 @@ import type {
 import type {
     ProviderCost,
     ProviderRequestAccounting,
+    ProviderRequestObserver,
     ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 
@@ -19,6 +20,9 @@ export type {
     ProviderAccounting,
     ProviderCost,
     ProviderRequestAccounting,
+    ProviderRequestIdentity,
+    ProviderRequestObserver,
+    ProviderRequestSettlement,
     ProviderUsage,
     ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
@@ -105,26 +109,11 @@ export type ProviderCostNormalizer = (
     evidence: ProviderChargeEvidence,
 ) => ProviderCost | undefined;
 
-export interface ProviderRequestIdentity {
-    readonly provider: string;
-    readonly model: string;
-}
-
-export type ProviderRequestSettlement = (
-    accounting: ProviderRequestAccounting,
-) => Promise<void>;
-
 // {§provider-reasoning-observer} Transient readable-reasoning observation. The completed ProviderResponse is
 // still the sole authoritative value; this callback exposes exact, ordered,
 // nonempty deltas early enough for an attached client to render them live.
 export type ProviderReasoningObserver = (delta: string) => void;
 
-// Core opens durable physical-request identity through this observer before
-// provider I/O. The returned settlement closes that exact identity.
-export type ProviderRequestObserver = (
-    identity: ProviderRequestIdentity,
-) => Promise<ProviderRequestSettlement>;
-
 // A successful exchange's closed finish set. ProviderAttemptFinishReason adds
 // the failed disposition that may occur only on ProviderError attempt evidence.
 export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;