pyyol 1.8.0 → 1.10.0

package/dist/pricing.js

@@ -6,8 +6,9 @@
 // authoritative cost comes from the Pyyol Gateway). When a provider changes prices,
 // bump PRICING_VERSION and update the table — never edit silently, so a cost can
 // always be traced to the table that produced it.
+import { isSelfHosted } from "./providers.js";
 // Bump whenever any rate below changes. Stamped onto every estimate.
-export const PRICING_VERSION = "2026-07-24";
+export const PRICING_VERSION = "2026-08-06";
 // Canonical model id -> Rate. Lowercase, provider-agnostic.
 const TABLE = {
     // OpenAI
@@ -29,12 +30,32 @@ const TABLE = {
     // Google (Gemini)
     "gemini-flash": { input: 0.15, output: 0.6, cachedInput: 0.0375 },
     "gemini-pro": { input: 1.25, output: 5.0, cachedInput: 0.3125 },
+    // Open-weight served by a HOSTED provider — there IS a per-token bill.
+    //
+    // "Open weight" does not mean "free". Groq bills per token like anyone else, and
+    // recording $0 for it meant a Groq-backed agent reported no cost at all on a platform
+    // that advertises verified LLM cost tracking. (The Python SDK already scoped these by
+    // provider; this table did not, so the two disagreed about the same call.)
+    "groq-llama-8b": { input: 0.05, output: 0.08 },
+    "groq-llama-70b": { input: 0.59, output: 0.79 },
     // Open-weight / self-hosted (no per-token bill)
     llama: { input: 0.0, output: 0.0 },
     mistral: { input: 0.0, output: 0.0 },
     qwen: { input: 0.0, output: 0.0 },
     deepseek: { input: 0.27, output: 1.1 },
 };
+// Provider-scoped rules, checked BEFORE the name rules. An open-weight model is $0
+// when you run it yourself and very much not $0 when a hosted provider serves it — and
+// the model id cannot tell you which, since "llama-3.3-70b" is the same string either
+// way. Only an explicitly provider-attributed call gets a hosted rate.
+const PROVIDER_RULES = {
+    groq: [
+        ["llama-3.1-8b", "groq-llama-8b"],
+        ["llama-3.1-70b", "groq-llama-70b"],
+        ["llama-3.3-70b", "groq-llama-70b"],
+        ["llama-4", "groq-llama-70b"],
+    ],
+};
 // Last-resort rate for an unmapped model (never silently $0 unless open-weight).
 const FALLBACK = { input: 0.5, output: 1.5 };
 // Ordered [substring, canonical] rules; first match wins, most specific first.
@@ -72,11 +93,17 @@ const RULES = [
     ["qwen", "qwen"],
     ["deepseek", "deepseek"],
 ];
-/** Map a raw model string to a canonical table key, or null if unknown. */
-export function canonical(model) {
+/** Map a raw model string to a canonical table key, or null if unknown.
+ *  `provider` scopes the lookup: provider-specific rules win, because they are the
+ *  only ones that know a hosted bill exists for a model that would otherwise be free. */
+export function canonical(model, provider = "") {
     const m = (model ?? "").trim().toLowerCase();
     if (!m)
         return null;
+    for (const [needle, key] of PROVIDER_RULES[provider.trim().toLowerCase()] ?? []) {
+        if (m.includes(needle))
+            return key;
+    }
     if (m in TABLE)
         return m;
     for (const [needle, key] of RULES)
@@ -84,27 +111,84 @@ export function canonical(model) {
             return key;
     return null;
 }
-/** The Rate for a model (falls back to a mid-tier rate for unknown models). */
-export function rateFor(model) {
-    const key = canonical(model);
+// Rate for a model the developer serves themselves. Not a guess and not a fallback —
+// there is no per-token bill, so any non-zero number here would be fiction.
+const FREE = { input: 0, output: 0, cachedInput: 0 };
+/** The Rate for a model (falls back to a mid-tier rate for unknown models).
+ *  `provider` scopes the lookup so a self-hosted model stays at $0. */
+export function rateFor(model, provider = "") {
+    // Self-hosted first, ahead of every name-based rule. The model id cannot tell you
+    // who served it — "llama-3.3-70b" is the same string on Groq's bill and on your own
+    // GPU — so without this an Ollama user is charged Groq's rates for electricity they
+    // already paid for, and the unknown-model fallback would invent a bill outright.
+    if (isSelfHosted(provider.trim().toLowerCase()))
+        return FREE;
+    const key = canonical(model, provider);
     return key !== null ? TABLE[key] : FALLBACK;
 }
 /** True if the model maps to an explicit table entry (not the fallback). */
 export function isKnown(model) {
     return canonical(model) !== null;
 }
+// Cache-WRITE multipliers, applied to a model's input rate.
+//
+// Writing a prompt into a provider's cache is a separately-billed event from reading it
+// back, and the two go in OPPOSITE directions: Anthropic surcharges a write to 1.25x
+// input and discounts a read to 0.1x, while OpenAI does not bill writes at all. Recording
+// only reads therefore does not merely lose a number — it prices the expensive half of
+// caching at zero, and does so for the agents that cache hardest.
+//
+// Expressed as a multiplier rather than a per-model rate because that is how providers
+// publish it: one ratio per model family. A multiplier also cannot drift out of step with
+// a model's input rate the way a duplicated absolute number can.
+const CACHE_WRITE_MULTIPLIER = [
+    ["claude-", 1.25], // Anthropic bills a cache write at 1.25x input
+    ["gpt-", 0.0], // OpenAI prompt caching is automatic; writes are not billed
+    ["o1", 0.0],
+    ["o3", 0.0],
+    ["o4", 0.0],
+    ["gemini-", 0.0], // implicit context caching is free
+];
+// Multiplier for a family with no published cache-write behaviour: a write costs what an
+// ordinary input token costs. Not 0.0, which would make an unrecognised model's caching
+// silently free — the flattering direction.
+const DEFAULT_CACHE_WRITE_MULTIPLIER = 1.0;
+/** USD per 1M tokens for writing a prompt into the provider's cache. */
+export function cacheWriteRate(model, provider = "") {
+    const rate = rateFor(model, provider);
+    const key = canonical(model, provider) ?? "";
+    for (const [prefix, mult] of CACHE_WRITE_MULTIPLIER) {
+        if (key.startsWith(prefix))
+            return rate.input * mult;
+    }
+    return rate.input * DEFAULT_CACHE_WRITE_MULTIPLIER;
+}
 /**
- * USD cost estimate for one model call. `cachedTokens` are a subset of
- * `promptTokens` billed at the cached-input rate; `reasoningTokens` are output
- * tokens already counted in `completionTokens` (kept for reporting).
+ * USD cost estimate for one model call.
+ *
+ * `promptTokens` is the TOTAL billable input, and `cachedTokens` (reads) and
+ * `cachedWriteTokens` (creations) are SUBSETS of it — so the three partition the input
+ * into full-rate, read-rate and write-rate portions. Normalizing onto that convention is
+ * the caller's job (extractUsage does it): providers disagree about whether cache tokens
+ * sit inside their reported input count, and pricing must not have to know which.
+ *
+ * `reasoningTokens` are output tokens already counted in `completionTokens` (kept for
+ * reporting).
  */
 export function estimateCost(model, a = {}) {
-    const rate = rateFor(model);
+    const rate = rateFor(model, a.provider ?? "");
     const prompt = Math.max(0, a.promptTokens ?? 0);
     const completion = Math.max(0, a.completionTokens ?? 0);
-    const cached = Math.max(0, Math.min(a.cachedTokens ?? 0, prompt));
-    const fullInput = prompt - cached;
-    const cachedRate = rate.cachedInput ?? rate.input;
-    const cost = (fullInput * rate.input + cached * cachedRate + completion * rate.output) / 1_000_000;
+    // Reads are taken out first, then writes from what remains, so the two subsets can
+    // never overlap and bill the same token twice.
+    const read = Math.max(0, Math.min(a.cachedTokens ?? 0, prompt));
+    const write = Math.max(0, Math.min(a.cachedWriteTokens ?? 0, prompt - read));
+    const fullInput = prompt - read - write;
+    const readRate = rate.cachedInput ?? rate.input;
+    const cost = (fullInput * rate.input +
+        read * readRate +
+        write * cacheWriteRate(model, a.provider ?? "") +
+        completion * rate.output) /
+        1_000_000;
     return Math.round(cost * 1e8) / 1e8;
 }

package/dist/providers.d.ts

@@ -0,0 +1,27 @@
+export declare const OPENAI = "openai";
+export declare const ANTHROPIC = "anthropic";
+export declare const GOOGLE = "google";
+export declare const GROQ = "groq";
+export declare const OLLAMA = "ollama";
+export declare const SELF_HOSTED = "self-hosted";
+/** True for loopback, link-local and private-network addresses, and for the hostnames
+ *  that conventionally mean "this machine". A model served from one of these has no
+ *  per-token bill, which is why it is worth detecting even when unnamed. */
+export declare function isLocalHost(host: string): boolean;
+/** Provider key implied by a base URL, or "" when the host says nothing. A local
+ *  address always resolves to SOMETHING — never "" — because "we could not tell" and
+ *  "it runs on your own hardware for free" must not be the same answer. */
+export declare function fromBaseUrl(baseUrl: string): string;
+/** Provider key implied by a client's constructor or module name, or "". */
+export declare function fromName(name: string): string;
+/** The provider serving this call. baseURL wins over the name: the name only says
+ *  which WIRE FORMAT the client speaks, while the URL says who is on the other end —
+ *  and for every OpenAI-compatible endpoint those are different answers. */
+export declare function resolve(o: {
+    name?: string;
+    baseUrl?: string;
+    fallback?: string;
+}): string;
+/** True when the provider runs on the developer's own hardware, so its tokens carry
+ *  no per-token bill. */
+export declare function isSelfHosted(provider: string): boolean;

package/dist/providers.js

@@ -0,0 +1,140 @@
+// Which provider is actually serving this call?
+//
+// Identifying the provider by the client CLASS is not enough, and getting it wrong is
+// not cosmetic: the provider decides whether a call is priced or free, and it is half
+// of the model attribution the public benchmark ranks on.
+//
+// The problem is that most of the ecosystem speaks the OpenAI wire format. Ollama,
+// vLLM, LM Studio, llama.cpp, OpenRouter, Together, Groq, DeepSeek, Azure and others
+// are all routinely driven through the OpenAI SDK with nothing changed but `baseURL`.
+// Classifying those by constructor name calls every one of them "openai" — pricing a
+// locally-served Llama at OpenAI's rates and filing it under the wrong vendor.
+//
+// Resolution order: baseURL host → module/constructor name → caller's fallback.
+// Anything on a loopback or private address is SELF-HOSTED even when the runtime is
+// unrecognised: it has no per-token bill, and "unknown" would price it as if it did.
+//
+// Keep the provider keys here in step with `internal/rating/taxonomy.go` and the
+// Python SDK's `providers.py` — the backend classifies exactly these strings.
+export const OPENAI = "openai";
+export const ANTHROPIC = "anthropic";
+export const GOOGLE = "google";
+export const GROQ = "groq";
+export const OLLAMA = "ollama";
+export const SELF_HOSTED = "self-hosted";
+/** host substring -> provider key. Most specific first. */
+const HOST_RULES = [
+    ["api.openai.com", OPENAI],
+    ["openai.azure.com", "azure"],
+    ["api.anthropic.com", ANTHROPIC],
+    ["bedrock-runtime", "bedrock"],
+    ["bedrock", "bedrock"],
+    ["generativelanguage.googleapis.com", GOOGLE],
+    ["aiplatform.googleapis.com", "vertex"],
+    ["api.groq.com", GROQ],
+    ["openrouter.ai", "openrouter"],
+    ["api.together.xyz", "together"],
+    ["together.ai", "together"],
+    ["api.fireworks.ai", "fireworks"],
+    ["api.deepinfra.com", "deepinfra"],
+    ["api.mistral.ai", "mistral"],
+    ["api.deepseek.com", "deepseek"],
+    ["api.cohere.ai", "cohere"],
+    ["api.cohere.com", "cohere"],
+    ["api.x.ai", "xai"],
+    ["api.perplexity.ai", "perplexity"],
+    ["api.cerebras.ai", "cerebras"],
+    ["api.sambanova.ai", "sambanova"],
+    ["api.studio.nebius", "nebius"],
+    ["api.hyperbolic.xyz", "hyperbolic"],
+    ["api.moonshot", "moonshot"],
+    ["dashscope.aliyuncs.com", "alibaba"],
+];
+/** Default ports of the common local runtimes. */
+const LOCAL_PORTS = {
+    "11434": OLLAMA,
+    "1234": "lmstudio",
+    "8000": "vllm",
+    "8080": "llamacpp",
+    "5000": "localai",
+    "3000": SELF_HOSTED,
+    "9997": SELF_HOSTED,
+};
+/** constructor/module-name substring -> provider. "openai" LAST: several packages
+ *  embed it in their own names. */
+const NAME_RULES = [
+    ["ollama", OLLAMA],
+    ["anthropic", ANTHROPIC],
+    ["groq", GROQ],
+    ["mistral", "mistral"],
+    ["cohere", "cohere"],
+    ["googlegenai", GOOGLE],
+    ["generativeai", GOOGLE],
+    ["google", GOOGLE],
+    ["openai", OPENAI],
+];
+const SELF_HOSTED_KEYS = new Set([OLLAMA, SELF_HOSTED, "vllm", "lmstudio", "llamacpp", "localai", "tgi"]);
+function parse(baseUrl) {
+    if (!baseUrl)
+        return { host: "", port: "" };
+    const withScheme = baseUrl.includes("://") ? baseUrl : `http://${baseUrl}`;
+    try {
+        const u = new URL(withScheme);
+        return { host: u.hostname.toLowerCase(), port: u.port };
+    }
+    catch {
+        return { host: "", port: "" };
+    }
+}
+/** True for loopback, link-local and private-network addresses, and for the hostnames
+ *  that conventionally mean "this machine". A model served from one of these has no
+ *  per-token bill, which is why it is worth detecting even when unnamed. */
+export function isLocalHost(host) {
+    if (!host)
+        return false;
+    if (["localhost", "127.0.0.1", "::1", "0.0.0.0", "host.docker.internal"].includes(host))
+        return true;
+    if (host.endsWith(".local") || host.endsWith(".internal"))
+        return true;
+    // IPv4 private ranges: 10/8, 192.168/16, 172.16–31/12, 127/8, 169.254/16.
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return a === 10 || a === 127 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 169 && b === 254);
+}
+/** Provider key implied by a base URL, or "" when the host says nothing. A local
+ *  address always resolves to SOMETHING — never "" — because "we could not tell" and
+ *  "it runs on your own hardware for free" must not be the same answer. */
+export function fromBaseUrl(baseUrl) {
+    const { host, port } = parse(baseUrl);
+    if (!host)
+        return "";
+    for (const [needle, provider] of HOST_RULES) {
+        if (host.includes(needle))
+            return provider;
+    }
+    if (isLocalHost(host))
+        return LOCAL_PORTS[port] ?? SELF_HOSTED;
+    return "";
+}
+/** Provider key implied by a client's constructor or module name, or "". */
+export function fromName(name) {
+    const n = (name || "").toLowerCase().replace(/[^a-z]/g, "");
+    for (const [needle, provider] of NAME_RULES) {
+        if (n.includes(needle))
+            return provider;
+    }
+    return "";
+}
+/** The provider serving this call. baseURL wins over the name: the name only says
+ *  which WIRE FORMAT the client speaks, while the URL says who is on the other end —
+ *  and for every OpenAI-compatible endpoint those are different answers. */
+export function resolve(o) {
+    return fromBaseUrl(o.baseUrl ?? "") || fromName(o.name ?? "") || o.fallback || "";
+}
+/** True when the provider runs on the developer's own hardware, so its tokens carry
+ *  no per-token bill. */
+export function isSelfHosted(provider) {
+    return SELF_HOSTED_KEYS.has(provider);
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,74 @@
+/** Bump only for a change that intentionally invalidates existing fingerprints: it is part
+ *  of the hashed payload, so a bump splits every agent's history into a new epoch. */
+export declare const SCAFFOLD_VERSION = "pyyol-scaffold-v1";
+/** Sampling parameters that change how a model behaves and are therefore part of the
+ *  scaffold. Anything not listed is ignored, so a provider adding an unrelated field does
+ *  not silently split every agent's history.
+ *
+ *  `model` is absent on purpose. So are baseURL, apiKey, timeout and stream: the first two
+ *  would make gateway routing look like a new scaffold, and the last two do not affect what
+ *  the model decides. */
+export declare const SAMPLING_KEYS: readonly string[];
+type Any = Record<string, unknown> | unknown;
+export type Components = Partial<Record<"client" | "roles" | "sampling" | "tools" | "system", string>>;
+/** The fingerprint components observable in one provider request.
+ *
+ *  Never throws: a fingerprinting problem must not break a developer's model call. */
+export declare function extract(kwargs: Record<string, unknown>, endpoint?: string): Components;
+/** The exact string that gets hashed.
+ *
+ *  Specified rather than incidental: the Python SDK builds the same string and a shared
+ *  conformance fixture checks both against the same expected fingerprints. Keys are emitted
+ *  in a FIXED order (not sorted, not insertion order) so neither language's map iteration
+ *  can affect the result, and an absent component is omitted rather than emitted empty — so
+ *  adding a component later does not change the fingerprint of requests that never had one. */
+export declare function canonical(c: Components): string;
+/** Short, prefixed id for a scaffold. 16 hex chars of SHA-256 (64 bits).
+ *
+ *  Short enough to read in a UI and group by in SQL. Collisions are irrelevant here in a way
+ *  they would not be for a security token: fingerprints are only compared WITHIN one agent's
+ *  own history, so the space that must stay distinct is a handful of harness versions. */
+export declare function fingerprint(c: Components): string;
+/** Why a request could not be fingerprinted, as a stable CODE rather than prose.
+ *
+ *  A code on the wire and prose at the point of reading, deliberately. The reason repeats on
+ *  every decision of every non-qualifying agent, so shipping and storing the sentence would
+ *  duplicate it thousands of times per match. A code is also aggregatable — "how many agents
+ *  are ineligible, and why" is a question worth being able to ask — and its wording can change
+ *  later without a migration. */
+export declare const ISSUE_NO_SYSTEM_PROMPT = "no_system_prompt";
+export declare const ISSUE_NO_MESSAGES = "no_messages";
+/** Prose for each code. Read by the CLI and the dev-facing trace; never stored. */
+export declare const ISSUE_EXPLANATIONS: Readonly<Record<string, string>>;
+/** Code for why this request yields no usable fingerprint, or "" when it does. */
+export declare function issue(kwargs: Record<string, unknown>, endpoint?: string): string;
+/** Human-readable reason for an issue code, or "" for no issue / an unknown code. */
+export declare function explain(code: string): string;
+/** Prose reason this request cannot be fingerprinted, or "" when it can.
+ *
+ *  Convenience for local developer output; the wire carries `issue` codes. */
+export declare function diagnose(kwargs: Record<string, unknown>, endpoint?: string): string;
+/** Fingerprint one provider request, or "" when it cannot be fingerprinted.
+ *
+ *  An empty result means "unknown", never a hash of nothing — a fingerprint shared by every
+ *  request that failed to yield components would silently pool unrelated scaffolds into one
+ *  bogus epoch and publish it as a controlled comparison.
+ *
+ *  A SYSTEM PROMPT IS REQUIRED, and this is the sharp edge of the whole design. Without one,
+ *  the hashable surface is `client` + `roles` + sampling — none of which move when the
+ *  developer rewrites the instructions they actually steer the model with, because those
+ *  instructions sit in a user message alongside the game state.
+ *
+ *  That is worse than having no fingerprint. It is a FALSE CERTIFICATE: an agent could
+ *  replace its entire strategy prompt mid-season, keep reporting the same scaffold id, and
+ *  have the improvement attributed to whatever model it swapped to — the fingerprint would be
+ *  manufacturing the confound it exists to remove. Hashing more cannot fix it, because the
+ *  instructions and the game state are the same string. See `diagnose`. */
+export declare function fromRequest(kwargs: Record<string, unknown>, endpoint?: string): string;
+/** True when a set of observations can support a within-scaffold model comparison.
+ *
+ *  Requires exactly one KNOWN scaffold. An unknown ("") fingerprint disqualifies rather than
+ *  being ignored: treating "we could not tell" as "the same as the others" is how a
+ *  confounded comparison gets published as a clean one. */
+export declare function eligibleForPairing(fingerprints: ReadonlyArray<string | undefined>): boolean;
+export type { Any };