@plurnk/plurnk-providers 1.3.3 → 1.3.5

package/src/standardProviders.ts

@@ -14,7 +14,7 @@ import OpenAICompatProvider, { type ReasoningStyle, type GrammarStyle } from "./
 import { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, reasoningFromEnv, dataCaptureFromEnv, contextWindowFromEnv, envelopeFromEnv, resolveReserve, type ReserveSpec } from "./env.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import { providerSource } from "./telemetry.ts";
-import { computeCost } from "./usage.ts";
+import { calculateCostUsd } from "./usage.ts";
 import { lookup } from "@plurnk/plurnk-models";
 
 type StandardProviderSpec = {
@@ -59,21 +59,19 @@ type StandardProviderSpec = {
     // not already include it.
     flexBaseStrip?: boolean;
     reasoningStyle: ReasoningStyle;
-    // How this backend carries a GBNF grammar (default "none" — not sent). A
-    // probeNctx entry is upgraded to "llamacpp" when the probe sees a
-    // llama-server; cloud backends that support GBNF set their shape statically
-    // (fireworks → "response_format", verified live).
-    grammarStyle?: GrammarStyle;
-    // SSE streaming (default true). The streaming transport is dropped
-    // per-request only when it would break a feature (a response_format grammar
-    // arrives mislabeled as reasoning_content under fireworks' stream); leave
-    // unset to keep streaming on for every other call. See OpenAICompat.generate.
+    // SSE streaming (default true).
     streaming?: boolean;
     // Constant model-id prefix the backend requires but the alias shouldn't
     // repeat (fireworks → "accounts/fireworks/models/", so the alias is just
     // `fireworks/deepseek-v4-pro`). Prepended idempotently to form the wire id,
     // which is ALSO the catalog key (models.dev keys fireworks-ai on the full id).
     modelPrefix?: string;
+    // A fully qualified model namespace that bypasses modelPrefix. Fireworks
+    // uses sibling models/, routers/, and deployments/ resource collections.
+    qualifiedModelPrefix?: string;
+    // Fixed request tiers supported by this provider. An unset knob means the
+    // provider default; configured values are validated and sent every call.
+    serviceTiers?: readonly string[];
     // First-party telemetry forwarding. ONLY the plurnk hosted endpoint sets
     // this — it forwards the consumer's per-turn `attributions` (contributor
     // credit) and `client` (originating frontend) as `Plurnk-Attribution` /
@@ -93,9 +91,6 @@ type StandardProviderSpec = {
     // Default ON for standard providers (OpenAI-standard field, broadly accepted);
     // set false to opt a backend out (e.g. anthropic's cache_control mechanism).
     promptCacheKey?: boolean;
-    // Top-level response field the endpoint reports account balance (pico-USD) in,
-    // surfaced as ProviderResponse.balancePico (plurnk only, #23). Absent elsewhere.
-    balanceMetaKey?: string;
     // RETIRED knob (#27→mimetypes#44): exact client-side tokenizer families were
     // removed with the tokenizer shed — the var is kept ONLY to fail hard with a
     // migration pointer when an operator still sets it.
@@ -155,7 +150,11 @@ export const STANDARD_PROVIDERS: Readonly<Record<string, StandardProviderSpec>>
     fireworks: {
         apiKeyVar: "FIREWORKS_API_KEY", apiKeyRequired: true,
         baseUrlVar: "FIREWORKS_BASE_URL", chatPath: "/chat/completions",
-        reasoningStyle: "effort_explicit", grammarStyle: "response_format", modelPrefix: "accounts/fireworks/models/", tokenizerEnvVar: "FIREWORKS_TOKENIZER",
+        reasoningStyle: "effort_explicit",
+        modelPrefix: "accounts/fireworks/models/",
+        qualifiedModelPrefix: "accounts/fireworks/",
+        serviceTiers: ["auto", "default", "flex", "priority"],
+        tokenizerEnvVar: "FIREWORKS_TOKENIZER",
     },
     deepinfra: {
         apiKeyVar: ["DEEPINFRA_API_KEY", "DEEPINFRA_API_TOKEN", "DEEPINFRA_TOKEN"], apiKeyRequired: true,
@@ -289,8 +288,8 @@ export const STANDARD_PROVIDERS: Readonly<Record<string, StandardProviderSpec>>
         apiKeyVar: "PLURNK_API_KEY", apiKeyRequired: true,
         apiKeyMessage: "PLURNK_API_KEY not found. Acquire one at https://plurnk.ai . Plurnk also supports local models and alternative cloud provider configurations.",
         apiKeyRejectedMessage: "PLURNK_API_KEY was rejected by plurnk.ai (invalid or expired). Verify it at https://plurnk.ai .",
-        reasoningStyle: "none", grammarStyle: "none", tokenizerEnvVar: "PLURNK_TOKENIZER",
-        probeNctx: true, detectLlamaServer: false, firstPartyMetadata: true, balanceMetaKey: "balance_pico", suppressTuningFloors: true,
+        reasoningStyle: "none", tokenizerEnvVar: "PLURNK_TOKENIZER",
+        probeNctx: true, detectLlamaServer: false, firstPartyMetadata: true, suppressTuningFloors: true,
     },
 });
 
@@ -417,7 +416,8 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     // The on-the-wire model id: a backend-required constant prefix (fireworks)
     // prepended idempotently, so the operator's alias carries only the distinctive
     // tail. This id is what the backend, the probe, AND the catalog key on.
-    const wireModel = spec.modelPrefix !== undefined && !model.startsWith(spec.modelPrefix)
+    const qualified = spec.qualifiedModelPrefix !== undefined && model.startsWith(spec.qualifiedModelPrefix);
+    const wireModel = spec.modelPrefix !== undefined && !qualified && !model.startsWith(spec.modelPrefix)
         ? `${spec.modelPrefix}${model}`
         : model;
 
@@ -444,17 +444,29 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     );
     const url = resolveUrl(spec, env, name, baseUrlOverride);
     const fetchTimeoutMs = parseRequiredInt(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", name);
+    const streamIdleTimeoutMs = parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", name);
+    const serviceTier = (() => {
+        const raw = env.PLURNK_PROVIDERS_SERVICE_TIER;
+        if (raw === undefined || raw.length === 0) return undefined;
+        if (spec.serviceTiers === undefined) {
+            throw new Error(`${name} provider: PLURNK_PROVIDERS_SERVICE_TIER is not supported`);
+        }
+        if (!spec.serviceTiers.includes(raw)) {
+            throw new Error(`${name} provider: PLURNK_PROVIDERS_SERVICE_TIER must be one of ${spec.serviceTiers.map((tier) => JSON.stringify(tier)).join(", ")} (got "${raw}")`);
+        }
+        return raw;
+    })();
 
     // The probe always runs for probeNctx specs — grammar capability must not
     // hinge on whether the operator pinned PLURNK_PROVIDERS_CONTEXT_WINDOW. For
     // contextWindow itself, explicit env still wins over the probed n_ctx.
     let contextWindow = contextWindowFromEnv(env, name);
-    // Grammar shape: a static spec choice (e.g. fireworks → "response_format"),
-    // upgraded to "llamacpp" when the probe fingerprints a llama-server. Slot
+    // GBNF transport is upgraded to "llamacpp" only when the probe fingerprints
+    // a llama-server. Slot
     // pinning is llama-server-only, so it keys on that same fingerprint. A spec
     // can opt out of the fingerprint entirely (detectLlamaServer: false → plurnk)
     // to read the window but stay a plain remote OpenAI server.
-    let grammarStyle: GrammarStyle = spec.grammarStyle ?? "none";
+    let grammarStyle: GrammarStyle = "none";
     let supportsSlotPinning = false;
     let slotCount: number | null = null;
     let eosText: string | undefined;
@@ -500,7 +512,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
             // un-upgraded, but NEVER silently (#34) — rails going dark without a
             // signal cost the consumer weeks of misattributed rambles.
             emitWarningOnce(
-                `${name} provider: llama-server detection failed after ${probeAttempts} attempts — grammar transport stays OFF (grammarStyle "none"). If this endpoint IS a llama-server, pin PLURNK_PROVIDERS_LLAMA_SERVER=1 (or its _<alias> form).`,
+                `${name} provider: llama-server detection failed after ${probeAttempts} attempts — local capabilities are unknown. If this endpoint is a llama-server, pin PLURNK_PROVIDERS_LLAMA_SERVER=1 (or its _<alias> form).`,
                 "PLURNK_PROBE_FAILED",
             );
         }
@@ -511,7 +523,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     // window for a known cloud model (groq/deepseek/mistral/…, which don't
     // probe). A local llama-server model misses the catalog and keeps its
     // probed n_ctx. Standard providers carry NO live pricing, so the catalog is
-    // the sole — never shadowing — cost source; per-1M USD → pico-USD/token (×1e6).
+    // the sole — never shadowing — cost source, expressed in USD per 1M tokens.
     // A relay with a catalogContextLookup (bedrock) resolves its window via the
     // underlying model's publisher and carries NO catalog cost (native rate ≠ relay
     // rate, #22); everyone else keys the catalog directly on (name, wireModel).
@@ -536,12 +548,12 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         );
     }
     const cost = fallback?.cost;
-    const costFor = cost === undefined
+    const calculateCost = cost === undefined
         ? undefined
-        : (usage: ProviderUsage): number => computeCost(usage, {
-            input: cost.inputPer1M * 1e6,
-            output: cost.outputPer1M * 1e6,
-            cached: (cost.cacheReadPer1M ?? cost.inputPer1M) * 1e6,
+        : (usage: ProviderUsage): number => calculateCostUsd(usage, {
+            input: cost.inputPer1M,
+            output: cost.outputPer1M,
+            cached: cost.cacheReadPer1M ?? cost.inputPer1M,
         });
 
     // #507: completion cap — when the catalog reports a maxOutput, use
@@ -577,6 +589,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         headers,
         contextWindow,
         fetchTimeoutMs,
+        streamIdleTimeoutMs,
         reasoning,
         temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
         repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
@@ -594,7 +607,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         retryDelayMs: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_DELAY, "PLURNK_PROVIDERS_RETRY_DELAY", name),
         retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", name),
         reasoningStyle,
-        costFor,
+        calculateCost,
         source: providerSource(name),
         grammarStyle,
         // Optional debug toggle (off by default): validate a transported grammar
@@ -607,7 +620,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         firstPartyMetadata: spec.firstPartyMetadata,
         apiKeyRejectedMessage: spec.apiKeyRejectedMessage,
         promptCacheKey: spec.promptCacheKey ?? true, // #518: default-on for standard providers (OpenAI-standard field, 6/6 backends verified accept it); per-spec opt-out below
-        balanceMetaKey: spec.balanceMetaKey,
+        serviceTier,
         supportsSlotPinning,
         slotCount,
         eosText,

package/src/types.ts

@@ -69,9 +69,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 +191,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);

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;
 };