@trazum/core 2.2.1 → 2.4.0

package/src/openrouter-activity.ts

@@ -0,0 +1,221 @@
+/**
+ * OpenRouter's activity report, read as a usage log.
+ *
+ * The eighth converter, and the third that reads a provider rather than a
+ * tool in front of one. OpenRouter is the one provider Trazum already has a
+ * price list for by construction: `openrouter.ts` turns its public model
+ * catalogue into a pricing overlay, keyed by the same slugs this report
+ * carries. So a row here is priceable the moment the overlay is loaded, for
+ * hundreds of models the bundled table never typed.
+ *
+ * ## Derived from the published schema
+ *
+ * `GET /api/v1/activity` needs a **management key** and answers the last
+ * thirty completed UTC days, one row per model per endpoint per day:
+ * `date` (`YYYY-MM-DD`), `model` (slug), `model_permaslug` (slug with
+ * version), `endpoint_id`, `provider_name`, `usage` (cost in USD),
+ * `byok_usage_inference` (BYOK cost in USD), `requests`, `prompt_tokens`,
+ * `completion_tokens`, `reasoning_tokens`, and `workspace_id` when the
+ * request said `group_by=workspace`. The schema's own example is the
+ * fixture.
+ *
+ * It takes the answer and never the key, for the reason `anthropic-usage.ts`
+ * gives: a management key manages the account, and this project holds no
+ * provider credential.
+ *
+ * ## Two figures that are never added
+ *
+ * `usage` is what OpenRouter charged, in dollars, and it is carried out of
+ * this conversion **beside** Trazum's catalogue-priced total, never merged
+ * into it — the rule `docs/commands.md` states for LiteLLM's `spend`. They
+ * are two measurements of the same rows; a reader is entitled to both and to
+ * the gap. `byok_usage_inference` is what an upstream provider charged on the
+ * operator's own key through OpenRouter, and is carried separately for the
+ * same reason.
+ *
+ * ## What the record says, and what it declines to say
+ *
+ * The record is `prompt_tokens` and `completion_tokens` under the model's
+ * slug, at the day's start. `model` rather than `model_permaslug`, because
+ * the slug is what the pricing overlay is keyed by and a versioned slug
+ * would price nothing until somebody mapped it.
+ *
+ * `reasoning_tokens` are counted and **not added** to the completion count.
+ * The schema does not say whether `completion_tokens` already includes
+ * them, and adding them if it does would charge reasoning twice on the
+ * models where it is the largest line. They are reported so the operator
+ * can see the count and settle the question against their own invoice.
+ *
+ * `endpoint_id` and `provider_name` are read by nothing that reaches the
+ * output: a row is priced by model, and which provider served it is what
+ * `usage` already reflects. `workspace_id` is read only through a mapping
+ * the operator writes, exact match, and unlike Anthropic's a `null` here has
+ * one meaning only — the request did not group by workspace.
+ */
+
+/** One workspace, and the label the operator gives it. Exact match. */
+export interface OpenrouterWorkspaceLabel {
+  workspace: string;
+  label: string;
+}
+
+export interface OpenrouterActivityRecord {
+  model: string;
+  ts: string;
+  label?: string;
+  usage: { prompt_tokens: number; completion_tokens: number };
+}
+
+export interface OpenrouterActivityConversion {
+  records: OpenrouterActivityRecord[];
+  /** Rows that became records. */
+  rows: number;
+  /** `requests`, summed. A row is a day's aggregate, not a call. */
+  requests: number;
+  /** What OpenRouter charged, summed, in dollars. Never merged into Trazum's total. */
+  reportedUsageUsd: number;
+  /** What upstream providers charged on the operator's own keys, summed. */
+  byokUsd: number;
+  /** `reasoning_tokens`, summed, and deliberately not added to any record. */
+  reasoningTokens: number;
+  /** Rows with no model slug, which nothing can price. */
+  unnamedModel: number;
+  /** Rows whose date was not a `YYYY-MM-DD` day. */
+  undatedRows: number;
+  /** Distinct days seen, so a reader knows how much of the thirty this is. */
+  days: number;
+  labelledByWorkspace: number;
+  unruledWorkspace: number;
+  /** Rules were given and no row carried a workspace id. */
+  workspaceNotGrouped: boolean;
+  /** The input was not the JSON this endpoint returns. */
+  unparseable: number;
+}
+
+const count = (value: unknown): number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+
+const asObject = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+export function openrouterActivityRecords(
+  text: string,
+  options: { label?: string; labelByWorkspace?: readonly OpenrouterWorkspaceLabel[] } = {},
+): OpenrouterActivityConversion {
+  const empty: OpenrouterActivityConversion = {
+    records: [],
+    rows: 0,
+    requests: 0,
+    reportedUsageUsd: 0,
+    byokUsd: 0,
+    reasoningTokens: 0,
+    unnamedModel: 0,
+    undatedRows: 0,
+    days: 0,
+    labelledByWorkspace: 0,
+    unruledWorkspace: 0,
+    workspaceNotGrouped: false,
+    unparseable: 0,
+  };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ...empty, unparseable: 1 };
+  }
+  const report = asObject(parsed);
+  if (report === null || !Array.isArray(report.data)) return { ...empty, unparseable: 1 };
+
+  const rules = options.labelByWorkspace;
+  const records: OpenrouterActivityRecord[] = [];
+  const days = new Set<string>();
+  let rows = 0;
+  let requests = 0;
+  let reportedUsageUsd = 0;
+  let byokUsd = 0;
+  let reasoningTokens = 0;
+  let unnamedModel = 0;
+  let undatedRows = 0;
+  let labelledByWorkspace = 0;
+  let unruledWorkspace = 0;
+  let anyWorkspace = false;
+
+  for (const found of report.data) {
+    const row = asObject(found);
+    if (row === null) continue;
+
+    /* The two billed figures are summed over every row, refused or not: a
+       refused row was still charged for, and a total that left it out would
+       be understated in the direction nobody questions. */
+    reportedUsageUsd += count(row.usage);
+    byokUsd += count(row.byok_usage_inference);
+    requests += count(row.requests);
+    reasoningTokens += count(row.reasoning_tokens);
+
+    if (typeof row.date !== 'string' || !DAY.test(row.date)) {
+      undatedRows += 1;
+      continue;
+    }
+    if (typeof row.model !== 'string' || row.model === '') {
+      unnamedModel += 1;
+      continue;
+    }
+    days.add(row.date);
+
+    let label = options.label;
+    if (rules !== undefined) {
+      const workspace = typeof row.workspace_id === 'string' ? row.workspace_id : null;
+      if (workspace !== null) {
+        anyWorkspace = true;
+        const named = rules.find((rule) => rule.workspace === workspace);
+        if (named !== undefined) {
+          label = named.label;
+          labelledByWorkspace += 1;
+        } else {
+          unruledWorkspace += 1;
+        }
+      }
+    }
+
+    records.push({
+      model: row.model,
+      ts: `${row.date}T00:00:00.000Z`,
+      ...(label === undefined ? {} : { label }),
+      usage: {
+        prompt_tokens: count(row.prompt_tokens),
+        completion_tokens: count(row.completion_tokens),
+      },
+    });
+    rows += 1;
+  }
+
+  return {
+    records,
+    rows,
+    requests,
+    reportedUsageUsd,
+    byokUsd,
+    reasoningTokens,
+    unnamedModel,
+    undatedRows,
+    days: days.size,
+    labelledByWorkspace,
+    unruledWorkspace,
+    workspaceNotGrouped: rules !== undefined && !anyWorkspace,
+    unparseable: 0,
+  };
+}
+
+/**
+ * Whether this text is an OpenRouter activity report. `model_permaslug`
+ * belongs to no other document, and `byok_usage_inference` likewise.
+ */
+export function looksLikeOpenrouterActivity(text: string, prefixBytes = 8192): boolean {
+  const head = text.slice(0, prefixBytes);
+  return head.includes('"model_permaslug"') || head.includes('"byok_usage_inference"');
+}

package/src/pricing.ts

@@ -47,10 +47,30 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
   openai: '2026-08-31',
   /* ai.google.dev/gemini-api/docs/pricing, read 2026-08-28. */
   google: '2026-08-28',
-  moonshot: '2026-06-24',
+  /*
+   * platform.kimi.ai/docs/pricing/chat (platform.moonshot.ai 301s there),
+   * read 2026-09-12. The page prices kimi-k3, kimi-k2.6, kimi-k2.7-code and
+   * its highspeed variant; `kimi-k2`, the one id this table carries, is no
+   * longer on it. Its price is kept because calls in somebody's log really
+   * happened at it, and it is not marked retired because that is recorded
+   * from the provider's own refusal to a request, which needs a key this
+   * repository does not hold. The newer models are not added: the page states
+   * no context window for any of them, and a context window this table did
+   * not read is a number it would be inventing.
+   */
+  moonshot: '2026-09-12',
   /* api-docs.deepseek.com/quick_start/pricing, read 2026-08-28. */
   deepseek: '2026-08-28',
-  xai: '2026-06-24',
+  /*
+   * docs.x.ai/docs/models, read 2026-09-12. The page prices grok-4.6, 4.5,
+   * 4.3 and the 4.20 family, each at two rates split at 200k prompt tokens;
+   * `grok-4`, the one id this table carries, is no longer on it. Kept and not
+   * marked retired, for the reasons given for kimi-k2 above. The newer models
+   * are not added: this table has no way to express a price that changes at
+   * 200k prompt tokens, and pricing a 300k-token call at the under-200k rate
+   * would understate it by half while looking exact.
+   */
+  xai: '2026-09-12',
   /*
    * `mistral.ai/pricing`, read 2026-08-28 — by a human, because the page
    * renders its table in the browser and serves a fetch only an FAQ example
@@ -379,7 +399,9 @@ export const MODELS: ModelPricing[] = [
     multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
     capability: 'mid',
     tier: 'sonnet',
-    notes: 'No batch API: the batch advisory stays quiet rather than offering a discount you cannot buy.',
+    notes:
+      'No batch API: the batch advisory stays quiet rather than offering a discount you cannot buy.'
+      + ' Not on the provider\'s pricing page as of 2026-09-12, which lists kimi-k3 and kimi-k2.6 instead; the price is the last one published for it.',
   },
 
   // ------------------------------------------------------------------------
@@ -475,6 +497,8 @@ export const MODELS: ModelPricing[] = [
     multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
     capability: 'large',
     tier: 'opus',
+    notes:
+      'Not on the provider\'s model page as of 2026-09-12, which lists grok-4.6 and later instead; the price is the last one published for it.',
   },
 
   // ------------------------------------------------------------------------
@@ -887,6 +911,70 @@ function describe(when: TierCondition): string {
   return `${windows.join(' and ')} UTC${when.weekdaysOnly ? ', Monday to Friday' : ''}`;
 }
 
+/**
+ * The date the prices behind one report were reviewed.
+ *
+ * ## The sentence this exists to make true
+ *
+ * `PRICING_LAST_REVIEWED` is the **oldest** provider's date, which is the right
+ * answer to *how old is this table* and the wrong answer to *how old are the
+ * prices in front of me*. Every surface that warns about staleness was using
+ * it, and the warning says, in these words, that the table behind **every
+ * dollar here** was last reviewed on that date.
+ *
+ * On 2026-08-31 that sentence was false on a report of Claude and OpenAI
+ * calls. It named 2026-06-24 — the date belonging to two models that appear in
+ * no such report and whose providers stopped listing them — while the prices
+ * actually used had been read four days and zero days earlier. A warning that
+ * fires on every run is one people stop reading, and a provenance that does
+ * not hold is the one thing this tool exists not to print.
+ *
+ * `trazum models` had already worked this out and prints the dates per
+ * provider, with the reason in a comment. The fix reached one surface and not
+ * the three that qualify a figure.
+ *
+ * ## What it returns, and the direction it errs in
+ *
+ * The oldest review date among the providers that actually priced these
+ * models. Where that cannot be established it returns the catalogue's own
+ * `lastReviewed`, which is the **conservative** direction: reporting a fresher
+ * date for a report containing a price of unknown provenance would be claiming
+ * provenance this table does not have.
+ *
+ * It cannot be established in three cases, all of which fall back:
+ *
+ * - **An overlay is in effect.** `--pricing` and `--pricing-live` replace
+ *   prices with numbers whose provenance is the overlay's own date, and
+ *   `PROVIDER_REVIEWED` describes the bundled table rather than theirs.
+ * - **A model the catalogue does not carry**, or one carrying no provider: a
+ *   price with no page behind it.
+ * - **A provider with no recorded review date.**
+ *
+ * The fallback is inside this function rather than at each call site on
+ * purpose. `isOffered` records why: the fifth call site is always the one
+ * written with only the first half of a two-part rule.
+ */
+export function reviewedForModels(
+  models: Iterable<string>,
+  catalogue: PricingCatalogue,
+): string {
+  /* An overlay's prices are not this table's, so this table's dates say
+     nothing about them. */
+  if (catalogue.lastReviewed !== PRICING_LAST_REVIEWED) return catalogue.lastReviewed;
+
+  let oldest: string | null = null;
+  for (const id of models) {
+    const model = catalogue.models.find((m) => m.id === id);
+    if (model?.provider === undefined) return catalogue.lastReviewed;
+    const date = PROVIDER_REVIEWED[model.provider];
+    if (date === undefined) return catalogue.lastReviewed;
+    if (oldest === null || date < oldest) oldest = date;
+  }
+  /* Nothing priced: there is no report-specific answer, so the table's own
+     date stands rather than an absence being read as freshness. */
+  return oldest ?? catalogue.lastReviewed;
+}
+
 /** Cheapest model of each capability tier, for recommendations. */
 export function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing {
   const candidates = MODELS.filter((m) => m.tier === tier && isOffered(m));