pyyol 1.8.0 → 1.9.0

package/dist/cli.js

@@ -636,7 +636,31 @@ async function cmdWallet(a) {
         console.error(`${BAD} not logged in — run \`pyyol login\` first.`);
         return 2;
     }
+    // AN AGENT KEY CANNOT READ THE OWNER'S TREASURY, and must not be sent here.
+    //
+    // The fallback chain above ends at PYYOL_TOKEN, which the deployment docs define as
+    // the sk_arena_… AGENT key for CI and containers. That key resolves server-side to
+    // its owner's user id, so this command used to work with it — an agent credential
+    // reading its owner's full balance and ledger. The arena now requires user scope on
+    // /v1/user/wallet and answers 403, which would surface here as an opaque
+    // "could not fetch wallet (403)".
+    //
+    // Refusing locally, by shape, is better than relaying that: it names the credential
+    // actually in play (easy to miss when it arrives from the environment rather than a
+    // flag) and says which one the command needs.
+    if (token.startsWith(AGENT_KEY_PREFIX)) {
+        console.error(`${BAD} \`pyyol wallet\` shows the OWNER's treasury, so it needs your dashboard login — ` +
+            `not an agent key.\n` +
+            `    The token in use is an agent key (sk_arena_…), probably from $PYYOL_TOKEN.\n` +
+            `    Run \`pyyol login\` on this machine, or unset PYYOL_TOKEN for this command.`);
+        return 2;
+    }
     const [st, w] = await apiGet(`${base}/v1/user/wallet`, token);
+    if (st === 403) {
+        console.error(`${BAD} this credential is not allowed to read the owner's treasury. ` +
+            `Sign in with \`pyyol login\` and try again.`);
+        return 1;
+    }
     if (st !== 200) {
         console.error(`${BAD} could not fetch wallet (${st}): ${JSON.stringify(w)}`);
         return 1;

package/dist/instrument.d.ts

@@ -6,6 +6,13 @@ export declare function disableGateway(): void;
 export declare function gatewayBaseUrl(provider: string): string;
 /** The X-Pyyol-* identity headers for the current turn (empty if routing off). */
 export declare function gatewayHeaders(): Record<string, string>;
+/** The provider for one instrumented call.
+ *
+ *  `patchedAs` is the SDK we wrapped (which wire format this is). The client's baseURL
+ *  is consulted first and wins. A baseURL pointing at the PYYOL GATEWAY is not used for
+ *  attribution — it says the call was proxied, not who served it — so the upstream is
+ *  recovered from the gateway path by matching it back against PROVIDER_PATH. */
+export declare function resolveCallProvider(resource: Any, patchedAs: string): string;
 /** Point a provider client at the Pyyol Gateway (sets its baseURL). Explicit, robust
  *  opt-in that operates on the given instance. Returns the client. No-op when routing
  *  is off or the provider can't be determined. */
@@ -18,9 +25,6 @@ export interface ExtractedUsage {
     cachedTokens: number;
     reasoningTokens: number;
 }
-/** Pull normalized usage from a provider response, or null if it has none.
- *  Handles OpenAI Chat Completions, Anthropic Messages, and the OpenAI Responses
- *  API; duck-typed so a plain object or an SDK object both work. */
 export declare function extractUsage(resp: Any): ExtractedUsage | null;
 /** Record usage from a provider response: compute cost, add to the turn
  *  accumulator, and emit a Lens model_call span. Returns the extracted usage (or

package/dist/instrument.js

@@ -16,6 +16,7 @@
 // pass `stream_options: { include_usage: true }` and record manually, or use
 // non-streaming calls for automatic capture.
 import { estimateCost } from "./pricing.js";
+import * as providers from "./providers.js";
 import { currentSpan, currentUsage } from "./telemetry.js";
 // [prototype, method, original] for uninstrument().
 const PATCHED = [];
@@ -54,11 +55,15 @@ export function gatewayHeaders() {
     return h;
 }
 function detectProvider(client) {
-    const name = (client?.constructor?.name ?? "").toLowerCase();
-    if (name.includes("openai"))
-        return "openai";
-    if (name.includes("anthropic"))
-        return "anthropic";
+    // baseURL first: most of the ecosystem speaks the OpenAI wire format, so an OpenAI
+    // client pointed at http://localhost:11434/v1 IS Ollama — and calling it "openai"
+    // would price a model on the developer's own GPU at OpenAI's rates.
+    const byUrl = providers.fromBaseUrl(String(client?.baseURL ?? ""));
+    if (byUrl)
+        return byUrl;
+    const byName = providers.fromName(client?.constructor?.name ?? "");
+    if (byName)
+        return byName;
     // duck-type fallback
     if (client?.chat?.completions)
         return "openai";
@@ -66,6 +71,24 @@ function detectProvider(client) {
         return "anthropic";
     return "";
 }
+/** The provider for one instrumented call.
+ *
+ *  `patchedAs` is the SDK we wrapped (which wire format this is). The client's baseURL
+ *  is consulted first and wins. A baseURL pointing at the PYYOL GATEWAY is not used for
+ *  attribution — it says the call was proxied, not who served it — so the upstream is
+ *  recovered from the gateway path by matching it back against PROVIDER_PATH. */
+export function resolveCallProvider(resource, patchedAs) {
+    const base = clientBaseUrl(resource);
+    if (base && gateway.base && base.startsWith(gateway.base)) {
+        const tail = base.slice(gateway.base.length);
+        for (const [provider, path] of Object.entries(PROVIDER_PATH)) {
+            if (tail.startsWith(path))
+                return provider;
+        }
+        return patchedAs;
+    }
+    return providers.resolve({ baseUrl: base, fallback: patchedAs });
+}
 /** Point a provider client at the Pyyol Gateway (sets its baseURL). Explicit, robust
  *  opt-in that operates on the given instance. Returns the client. No-op when routing
  *  is off or the provider can't be determined. */
@@ -130,10 +153,71 @@ function get(obj, name, dflt) {
 /** Pull normalized usage from a provider response, or null if it has none.
  *  Handles OpenAI Chat Completions, Anthropic Messages, and the OpenAI Responses
  *  API; duck-typed so a plain object or an SDK object both work. */
+/** Ollama's native shape: no `usage` object at all, counts at the top level.
+ *  Without this an agent running Ollama reported zero tokens forever — it looked
+ *  instrumented and measured nothing, and no bill ever arrives to contradict a zero. */
+function extractOllama(resp) {
+    const prompt = get(resp, "prompt_eval_count");
+    const completion = get(resp, "eval_count");
+    if (prompt === undefined && completion === undefined)
+        return null;
+    return {
+        model: get(resp, "model", "") || "",
+        provider: providers.OLLAMA,
+        promptTokens: Math.trunc(prompt || 0),
+        completionTokens: Math.trunc(completion || 0),
+        cachedTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+/** Google Gemini: counts hang off `usageMetadata` (camelCase in the JS SDK). */
+function extractGoogle(resp) {
+    const um = get(resp, "usageMetadata") ?? get(resp, "usage_metadata");
+    if (um == null)
+        return null;
+    const prompt = get(um, "promptTokenCount", get(um, "prompt_token_count", 0)) || 0;
+    const completion = get(um, "candidatesTokenCount", get(um, "candidates_token_count", 0)) || 0;
+    if (!prompt && !completion)
+        return null;
+    return {
+        model: get(resp, "modelVersion", "") || get(resp, "model", "") || "",
+        provider: providers.GOOGLE,
+        promptTokens: Math.trunc(prompt),
+        completionTokens: Math.trunc(completion),
+        cachedTokens: Math.trunc(get(um, "cachedContentTokenCount", get(um, "cached_content_token_count", 0)) || 0),
+        reasoningTokens: Math.trunc(get(um, "thoughtsTokenCount", get(um, "thoughts_token_count", 0)) || 0),
+    };
+}
+/** Cohere nests counts under `meta.tokens`. */
+function extractCohere(resp) {
+    const tokens = get(get(resp, "meta"), "tokens");
+    if (tokens == null)
+        return null;
+    const prompt = get(tokens, "inputTokens", get(tokens, "input_tokens", 0)) || 0;
+    const completion = get(tokens, "outputTokens", get(tokens, "output_tokens", 0)) || 0;
+    if (!prompt && !completion)
+        return null;
+    return {
+        model: get(resp, "model", "") || "",
+        provider: "cohere",
+        promptTokens: Math.trunc(prompt),
+        completionTokens: Math.trunc(completion),
+        cachedTokens: 0,
+        reasoningTokens: 0,
+    };
+}
 export function extractUsage(resp) {
     const u = get(resp, "usage");
-    if (u == null)
+    if (u == null) {
+        // Shapes that carry no `usage` at all. Only consulted here, so they can never
+        // hijack a normal OpenAI or Anthropic response.
+        for (const extractor of [extractOllama, extractGoogle, extractCohere]) {
+            const info = extractor(resp);
+            if (info !== null)
+                return info;
+        }
         return null;
+    }
     const model = get(resp, "model", "") || "";
     let prompt = get(u, "prompt_tokens");
     let completion = get(u, "completion_tokens");
@@ -175,6 +259,10 @@ export function recordResponse(resp, o = {}) {
         return null;
     const provider = o.provider || info.provider;
     const cost = estimateCost(info.model, {
+        // WHO served it, not just what was served: an open-weight model is free on your
+        // own hardware and billed when a hosted provider serves it, and the model id is
+        // identical either way.
+        provider,
         promptTokens: info.promptTokens,
         completionTokens: info.completionTokens,
         cachedTokens: info.cachedTokens,
@@ -213,7 +301,9 @@ export function patchPrototype(proto, method, provider) {
         const start = Date.now();
         const resp = await orig.apply(this, args);
         try {
-            recordResponse(resp, { provider, latencyMs: Date.now() - start });
+            // Resolve from the CLIENT's baseURL — the wire format we patched is not the
+            // same thing as who actually served the call.
+            recordResponse(resp, { provider: resolveCallProvider(this, provider), latencyMs: Date.now() - start });
         }
         catch {
             // instrumentation must never break the dev's call

package/dist/pricing.d.ts

@@ -7,10 +7,13 @@ export interface Rate {
     /** USD per 1M cached (prompt-cache read) input tokens; defaults to `input`. */
     cachedInput?: number;
 }
-/** Map a raw model string to a canonical table key, or null if unknown. */
-export declare function canonical(model: string): string | null;
-/** The Rate for a model (falls back to a mid-tier rate for unknown models). */
-export declare function rateFor(model: string): Rate;
+/** 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 declare function canonical(model: string, provider?: string): string | null;
+/** 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 declare function rateFor(model: string, provider?: string): Rate;
 /** True if the model maps to an explicit table entry (not the fallback). */
 export declare function isKnown(model: string): boolean;
 export interface CostArgs {
@@ -18,6 +21,9 @@ export interface CostArgs {
     completionTokens?: number;
     cachedTokens?: number;
     reasoningTokens?: number;
+    /** WHO served the call. Decides whether there is a bill at all: the same model id
+     *  is billed on a hosted provider and free on the developer's own hardware. */
+    provider?: string;
 }
 /**
  * USD cost estimate for one model call. `cachedTokens` are a subset of

package/dist/pricing.js

@@ -6,6 +6,7 @@
 // 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";
 // Canonical model id -> Rate. Lowercase, provider-agnostic.
@@ -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,9 +111,19 @@ 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). */
@@ -99,7 +136,7 @@ export function isKnown(model) {
  * 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));

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/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.8.0";
+export declare const SDK_VERSION = "1.9.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/genversion.mjs — do not edit by hand.
 // Source of truth is the "version" field in package.json.
-export const SDK_VERSION = "1.8.0";
+export const SDK_VERSION = "1.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",

package/rules/llms-full.txt

@@ -1172,7 +1172,55 @@ JSON (YAML also accepted). All keys are **camelCase**.
 | `runtime.maxMemory` | string, e.g. `"256Mi"` |
 | `sdk.language` | required (`python` / `js`) |
 | `contact.email` | valid email |
-| `model` | **optional**; if present, `provider` + `model` required. Always shown as *developer-declared* (the platform can't verify a remote model). |
+| `model` | **optional**, but scaffolded by `pyyol init` — see below. If present, `provider` + `model` are both required. |
+
+## How your model is identified on the benchmark
+
+The [model board](https://pyyol.com/models) ranks by the model that actually played
+each match, resolved at whichever of these tiers it can reach — best first:
+
+| tier | source | can you misreport it? |
+| --- | --- | --- |
+| **verified** | the model name in the provider's own API response, read by the Pyyol gateway | no |
+| **observed** | the model your SDK reported for the calls it made that turn | yes, but per call |
+| **claimed** | this `model:` block | yes |
+
+Two practical consequences:
+
+- Route your LLM calls through the gateway (`/gw/openai/...`, `/gw/anthropic/...`) and
+  your rows show as **verified** — and your cost-per-win is computed from spend the
+  server measured rather than from a number your agent reported.
+- Fill the `model:` block in anyway. It is the fallback for any match where neither
+  the gateway nor the SDK saw a model name, and an agent with none can disappear from
+  the board entirely. `pyyol init` writes placeholders (`your-provider` /
+  `your-model`) — replace them, because an unedited block is not a useful claim.
+
+### Running something other than OpenAI or Anthropic
+
+`pyyol.instrument()` identifies your model whatever serves it. It resolves the
+provider from the client's **base URL** first, then its SDK, because almost everything
+speaks the OpenAI wire format — so an OpenAI client pointed somewhere else is not an
+OpenAI call, and treating it as one would price it wrong.
+
+| you run | what happens |
+| --- | --- |
+| OpenAI / Anthropic SDKs | captured natively |
+| **Ollama** (native client or `ollama.chat`) | captured, reported as `ollama`, priced at **$0** |
+| OpenAI SDK → `localhost:11434` / `:1234` / `:8000` / `:8080` | detected as ollama / LM Studio / vLLM / llama.cpp, priced at **$0** |
+| OpenAI SDK → any private or loopback address | `self-hosted`, priced at **$0** |
+| OpenAI SDK → Groq, OpenRouter, Together, DeepSeek, Fireworks, xAI, Perplexity, Cerebras, Azure… | detected by host and priced as that provider |
+| Google Gemini (`google-genai` or `google-generativeai`) | captured natively |
+| Cohere | captured natively |
+
+Self-hosted models are recorded at **$0 per token** — you already paid for the
+hardware — but their tokens, latency and move quality are measured exactly like
+anyone else's, so they compete on the board on equal terms. The board also groups by
+open-weights vs proprietary and hosted vs self-hosted, so you can see how your setup
+compares to the camp rather than only to individual models.
+
+If you use a client the SDK cannot recognise, call `pyyol.record_response(resp,
+provider="...")` yourself, or `pyyol.route(client, provider="...")` to name it
+explicitly.
 
 ## The endpoint secret