@trazum/core 1.81.0 → 1.83.0

package/src/types.ts

@@ -61,8 +61,10 @@ export type AdvisoryId =
   | 'cache-prefix-reorder'
   | 'batch-api'
   | 'model-downgrade'
+  | 'tier-signals-conflict'
   | 'output-dominated'
   | 'promo-pricing'
+  | 'model-retired'
   | 'contradictory-instructions'
   | 'redundant-examples'
   | 'restated-output-format'
@@ -148,6 +150,59 @@ export type CachingMode =
  */
 export type Capability = 'small' | 'mid' | 'large' | 'frontier' | 'unknown';
 
+/**
+ * What makes a conditional rate apply, as data a machine can evaluate.
+ *
+ * Deliberately a closed union rather than a predicate function. A catalogue
+ * entry is reviewed the way a price is reviewed, and a reviewer can check
+ * "peak is 01:00-04:00 and 06:00-10:00 UTC on weekdays" against a provider's
+ * page; nobody can review a closure. It also means the condition survives
+ * `JSON.stringify`, which matters because the catalogue can be overlaid from a
+ * file.
+ */
+export type TierCondition =
+  /**
+   * The prompt is larger than `tokens` input tokens.
+   *
+   * Decidable only where the token count is known, which is most of the places
+   * that price a specific call and none of the places that merely rank models.
+   * `effectivePricing` says which happened rather than guessing.
+   */
+  | { kind: 'input-tokens-above'; tokens: number }
+  /**
+   * The call falls inside one of `hours` in UTC, optionally on weekdays only.
+   *
+   * Decidable everywhere, because every caller already passes the date it is
+   * pricing for. `hours` lists the hour each window *starts*, so 01:00-04:00
+   * is `[1, 2, 3]` and not `[1, 4]`: an endpoint convention is the kind of
+   * thing two readers disagree about silently.
+   */
+  | { kind: 'utc-hours'; hours: number[]; weekdaysOnly: boolean };
+
+/**
+ * A rate that applies when its condition holds.
+ *
+ * Deliberately carries no multipliers of its own, and the first draft did. The
+ * reasoning for adding them was that DeepSeek halves the cache-hit price at
+ * off-peak along with everything else, so a cache read priced off the base
+ * would be wrong about the money — which is true of the *price* and false of
+ * the *ratio*: $0.007 against $0.22 and $0.014 against $0.44 are the same
+ * 3.18% to the last digit, on both models. Multiplying a tier's own input rate
+ * by the model's multiplier already gives the right answer.
+ *
+ * It was removed because the guard written to prove it mattered could not: with
+ * the tier multiplier equal to the base one, dropping it changed nothing and
+ * the test passed either way. An option nothing can distinguish from its
+ * absence is a claim nobody checks, which is worse than not having it.
+ */
+export interface PricingTier {
+  /** Short, stable, and printed: a reader has to be able to see which applied. */
+  id: string;
+  when: TierCondition;
+  inputPerMTok: number;
+  outputPerMTok: number;
+}
+
 export interface ModelPricing {
   id: string;
   displayName: string;
@@ -179,6 +234,32 @@ export interface ModelPricing {
    * buy is advice that wastes their time.
    */
   recommendable?: boolean;
+  /**
+   * Set when the provider refused a real request for this id.
+   *
+   * A retired model keeps its price and loses its future. Both halves matter:
+   * a log full of `deepseek-v3` calls records money that was genuinely spent,
+   * so deleting the row would make somebody's own history unpriceable — and a
+   * *new* call on that id will not happen at all, so quoting it as an option is
+   * a number for a question nobody can ask.
+   *
+   * `on` is the day `scripts/check-model-availability.mjs` was refused, and
+   * `because` is the provider's own sentence, quoted rather than paraphrased.
+   * Neither is a judgement, and neither implies anything about what the
+   * replacement costs: that is a price, and a price comes off the provider's
+   * own page or not at all.
+   *
+   * A retired model is never recommended, never offered as a cheaper
+   * alternative and never chosen as a tier's representative, in the same places
+   * `recommendable: false` is honoured — this is a stronger statement than that
+   * one and must not be weaker in effect.
+   */
+  retired?: {
+    /** ISO date the refusal was recorded. */
+    on: string;
+    /** What the provider answered, in the provider's words. */
+    because: string;
+  };
   /** Capability, on a vendor-neutral scale. */
   capability: Capability;
   /**
@@ -194,6 +275,29 @@ export interface ModelPricing {
     /** ISO date (inclusive) the promotional price applies until. */
     until: string;
   };
+  /**
+   * Rates that apply only under a stated condition.
+   *
+   * The catalogue held one input price and one output price per model until a
+   * real credential was pointed at the providers and two of them turned out not
+   * to charge that way:
+   *
+   * - **DeepSeek V4 bills by the clock.** Peak is 01:00-04:00 and 06:00-10:00
+   *   UTC, Monday to Friday, and off-peak is exactly half. That is 35 hours of
+   *   168, so the common case is the cheap one and a single number would have
+   *   been wrong by 2x in whichever direction it was chosen.
+   * - **Gemini 3.1 Pro bills by prompt size**, $2/$12 up to 200k input tokens
+   *   and $4/$18 above it.
+   *
+   * Both are *conditions*, so both are written as data rather than as prose in
+   * `notes`: a note is something a reader has to apply by hand, and this
+   * product exists to stop people doing arithmetic by hand.
+   *
+   * The base `inputPerMTok` and `outputPerMTok` stay the rate that applies when
+   * no condition matches, which keeps every model that has no tiers unchanged
+   * and keeps this field optional in effect as well as in the type.
+   */
+  tiers?: PricingTier[];
   /**
    * Other ids that bill at exactly this rate.
    *

package/src/verdict-bridge.ts

@@ -0,0 +1,200 @@
+/**
+ * Reading a dropped `route --json` verdict, so quality can stand beside cost.
+ *
+ * The bill is arithmetic: every figure in it comes from records already on
+ * disk, and it can say exactly what a cheaper model would have saved. It can
+ * say nothing at all about whether that model still does the job. That answer
+ * costs provider calls and a credential, which is why `trazum route` exists
+ * and why no surface that only reads a log will ever produce it.
+ *
+ * This is the bridge between the two, and it is deliberately one-directional:
+ * the measurement is made where the credential is, written out as the
+ * `routing-measurement` contract, and read back here by a pure function that
+ * touches no network and holds no key. A reader who has run `route` once can
+ * carry the verdict to any surface that prices the same workload.
+ *
+ * It was not possible to write until the document was worth reading. Before
+ * the JSON-text sweep, `route --json` printed the whole `EvalReport` — every
+ * case input and three model answers per case — so a bridge would have been a
+ * feature for carrying prompt text into a browser. The document carries the
+ * measurement and nothing else now, and `conform` is what says so rather than
+ * this file's own reading: the contract validates, the bridge only maps.
+ */
+
+import { conform } from './conform.js';
+import type { EvalVerdict } from './evaluate.js';
+import { UNLABELLED } from './usage.js';
+
+/** What a dropped routing measurement says, mapped onto what a bill can match. */
+export interface DroppedVerdict {
+  /** The workload the measurement was made on, or null when it was unlabelled. */
+  label: string | null;
+  /**
+   * The model those calls go to today, from the bill's own slice.
+   *
+   * Not the model that answered. `route` builds its baseline provider from
+   * the environment, so the model in the measurement is whatever
+   * `TRAZUM_LLM_MODEL` names, and it is only the log's model when the reader
+   * configured it that way. Pairing on it matched nothing on a real run
+   * against an OpenAI-compatible endpoint — `evaluation.model` said
+   * `stub-strong` while the log said `claude-opus-5` — and the bill would
+   * have shown no verdict at all with no explanation.
+   */
+  model: string;
+  /**
+   * The model that actually answered, when it is not the one the log records.
+   *
+   * Null when they agree, which is the ordinary case. Not null is worth
+   * saying out loud rather than smoothing over: a verdict measured on a
+   * stand-in is a weaker claim about this workload than one measured on the
+   * model the workload actually uses, and only this field can tell the
+   * difference.
+   */
+  measuredOn: string | null;
+  /** The model measured against it. */
+  candidateModel: string;
+  verdict: EvalVerdict;
+  /** The model's agreement with itself. The yardstick the other rate is read against. */
+  selfAgreement: number;
+  /** Agreement between the two models, same prompt on both sides. */
+  crossAgreement: number;
+  /** Cases the measurement covered, so a two-case verdict cannot pose as a hundred. */
+  cases: number;
+  /** Calls it cost to reach. */
+  callsMade: number;
+  /**
+   * What the measurement's own bill priced the route at, when the document
+   * carried it. Null rather than zero when it did not: a saving nobody
+   * measured is not a saving of nothing.
+   */
+  savingUsd: number | null;
+}
+
+/**
+ * What the bridge did with a file.
+ *
+ * `null` is not a failure: it means the file is not a routing measurement at
+ * all, and the caller should go on treating it as whatever else it was. A
+ * refusal is the other case — it looked like one and could not be read — and
+ * it names what is missing, because a refusal with nothing after it is
+ * indistinguishable from a bug.
+ */
+export type BridgeReading =
+  | { kind: 'verdict'; verdict: DroppedVerdict }
+  | { kind: 'refusal'; because: string };
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Whether this file is even claiming to be a routing measurement.
+ *
+ * Shape only, and deliberately narrow: an `evaluation` object carrying a
+ * `verdict`. Anything looser would swallow a usage log or a profile and
+ * refuse it in this file's words instead of letting the caller price it.
+ */
+function claimsToBeOne(parsed: unknown): boolean {
+  if (!isObject(parsed)) return false;
+  const evaluation = parsed.evaluation;
+  return isObject(evaluation) && typeof evaluation.verdict === 'string';
+}
+
+/**
+ * Reads a dropped `trazum route --json` document.
+ *
+ * Returns null when the text is something else entirely. Validation is
+ * `conform`'s, against the published `routing-measurement` contract, so this
+ * function cannot drift from the schema a connector author builds against —
+ * and a document that fails carries the contract's own sentences back to the
+ * reader rather than a second opinion written here.
+ */
+export function readDroppedVerdict(text: string): BridgeReading | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!claimsToBeOne(parsed)) return null;
+
+  const report = conform(text, { contract: 'routing-measurement' });
+  if (!report.conforms) {
+    const detail =
+      report.problems.length > 0
+        ? report.problems.map((problem) => `${problem.at}: ${problem.detail}`).join('; ')
+        : (report.because ?? 'it does not match the routing-measurement contract');
+    return { kind: 'refusal', because: detail };
+  }
+
+  const document = parsed as { slice?: unknown; evaluation?: unknown };
+  const slice = isObject(document.slice) ? document.slice : {};
+  const evaluation = document.evaluation as Record<string, unknown>;
+
+  /**
+   * Every field below is read defensively even though `conform` has passed,
+   * because the contract requires `slice` and `evaluation` to be objects and
+   * says nothing about what is inside them. A document from a future version
+   * with a thinner slice is a document this reads what it can from, not one
+   * it crashes on.
+   */
+  const answered = typeof evaluation.model === 'string' ? evaluation.model : null;
+  // The slice's model first: that is the fact the bill can be matched against.
+  const model = typeof slice.model === 'string' ? slice.model : answered;
+  const candidateModel =
+    typeof evaluation.candidateModel === 'string' ? evaluation.candidateModel : null;
+  const verdict = typeof evaluation.verdict === 'string' ? (evaluation.verdict as EvalVerdict) : null;
+  if (model === null || candidateModel === null || verdict === null) {
+    return {
+      kind: 'refusal',
+      because:
+        'the evaluation names no model, candidate model or verdict, so there is nothing to set beside a bill',
+    };
+  }
+
+  const number = (value: unknown): number => (typeof value === 'number' ? value : 0);
+  const route = isObject(slice.route) ? slice.route : null;
+  const rawLabel = typeof slice.label === 'string' ? slice.label : null;
+
+  return {
+    kind: 'verdict',
+    verdict: {
+      // `UNLABELLED` is the profile's own sentinel for calls that carry no
+      // label. It travels through the document as that sentinel and comes
+      // back as null here, so the bridge speaks the bill's language rather
+      // than leaking an internal marker into a caption.
+      label: rawLabel === null || rawLabel === UNLABELLED ? null : rawLabel,
+      model,
+      measuredOn: answered !== null && answered !== model ? answered : null,
+      candidateModel,
+      verdict,
+      selfAgreement: number(evaluation.selfAgreement),
+      crossAgreement: number(evaluation.crossAgreement),
+      cases: Array.isArray(evaluation.cases) ? evaluation.cases.length : 0,
+      callsMade: number(evaluation.callsMade),
+      savingUsd: route !== null && typeof route.savingUsd === 'number' ? route.savingUsd : null,
+    },
+  };
+}
+
+/**
+ * Whether a verdict describes the route a given slice of the bill is offering.
+ *
+ * Both halves must agree or the pairing is a lie: the same workload, the same
+ * model it goes to now, and the same candidate. A verdict measured on `chat`
+ * shown against `summarise`'s saving would be the exact fault this repository
+ * keeps finding in itself — a number describing something other than what was
+ * measured — and matching on the model alone would produce it on any log with
+ * two workloads on one model.
+ */
+export function verdictMatchesSlice(
+  verdict: DroppedVerdict,
+  slice: { label: string; model: string; route: { candidate: { id: string } } | null },
+): boolean {
+  if (slice.route === null) return false;
+  const sliceLabel = slice.label === UNLABELLED ? null : slice.label;
+  return (
+    sliceLabel === verdict.label &&
+    slice.model === verdict.model &&
+    slice.route.candidate.id === verdict.candidateModel
+  );
+}