catherd-cli 1.1.1 → 1.2.1

package/src/services/standins.ts

@@ -0,0 +1,204 @@
+import {
+  type Catalog,
+  DIMS,
+  type Dim,
+  type Family,
+  type InferredStandIn,
+  rungInfo,
+  scoresOf,
+} from "../domain/catalog.ts";
+import { catalogRungs } from "../domain/failover.ts";
+import { EFFORT_ORDER } from "../domain/sources.ts";
+
+/**
+ * Spec 1.2 §6.3: the features a rung is compared on. Numbers are z-scored across the catalog; `vendor` and
+ * `family` are words, the same or not. Keyless: price, context, release date, vendor and family, the effort
+ * (plan 14 Ruling 6), and the rung's own values on each dimension (the Arena and Epoch values, with the
+ * shipped ones). With an Artificial Analysis key, its index, `hle`, `scicode`, `lcr`, cost per task and
+ * tokens/s join them (`Catalog.features`).
+ */
+export type Features = Record<string, number | string>;
+
+/** Spec 1.2 §6.3: a pair sharing fewer features than this is not suggested. */
+export const MIN_SHARED_FEATURES = 3;
+
+export interface Suggestion {
+  /** the canonical rung that would stand in */
+  like: string;
+  distance: number;
+  /** the features the distance rests on: those both rungs have */
+  features: string[];
+  /** the dimensions it would lend: those the rung lacks and it has */
+  lends: Dim[];
+}
+
+const DAY_MS = 86_400_000;
+const family = (c: Catalog, canonical: string): Family | null =>
+  c.families.find((f) => f.id === canonical.slice(0, canonical.lastIndexOf("#"))) ?? null;
+
+/** The rung's own value per dimension: a value it borrows, or catherd's guess (`inferred`), never counts. */
+function ownValues(c: Catalog, canonical: string): Partial<Record<Dim, number>> {
+  const out: Partial<Record<Dim, number>> = {};
+  for (const d of DIMS) {
+    const s = c.scores[canonical]?.[d];
+    if (s && s.confidence !== "inferred") out[d] = s.value;
+  }
+  return out;
+}
+
+/** Spec 1.2 §6.3: a canonical rung's features, from its family, its effort, its own values and AA's. */
+export function featuresOf(c: Catalog, canonical: string): Features {
+  const out: Features = {};
+  const f = family(c, canonical);
+  if (f) {
+    out.price = Math.log10(f.price.input + f.price.output + 1e-6);
+    const contexts = Object.values(f.on).flatMap((m) => (m ? [m.context] : []));
+    if (contexts.length) out.context = Math.log10(Math.max(...contexts));
+    if (f.releaseDate) out.release = Date.parse(f.releaseDate) / DAY_MS;
+    const vendor = (f as { vendor?: unknown }).vendor;
+    if (typeof vendor === "string") out.vendor = vendor;
+    out.family = f.id;
+  }
+  const effort = (EFFORT_ORDER as readonly string[]).indexOf(canonical.slice(canonical.lastIndexOf("#") + 1));
+  if (effort >= 0) out.effort = effort;
+  for (const [d, v] of Object.entries(ownValues(c, canonical))) out[d] = v;
+  for (const [k, v] of Object.entries(c.features[canonical] ?? {})) out[`aa.${k}`] = v;
+  return out;
+}
+
+/** Every canonical rung the catalog can name, and every one it holds a value for. */
+export function canonicalRungs(c: Catalog): string[] {
+  const out = new Set(Object.keys(c.scores));
+  for (const r of catalogRungs(c)) {
+    try {
+      out.add(rungInfo(c, r).canonical);
+    } catch {
+      // catalogRungs only names parseable rungs
+    }
+  }
+  return [...out].sort();
+}
+
+interface Scale {
+  mean: number;
+  sd: number;
+}
+
+/** Each numeric feature's mean and spread over `all`; a feature with no spread tells rungs apart by nothing. */
+function scales(all: Features[]): Map<string, Scale> {
+  const values = new Map<string, number[]>();
+  for (const f of all)
+    for (const [k, v] of Object.entries(f))
+      if (typeof v === "number") values.set(k, [...(values.get(k) ?? []), v]);
+  const out = new Map<string, Scale>();
+  for (const [k, xs] of values) {
+    const mean = xs.reduce((s, x) => s + x, 0) / xs.length;
+    const sd = Math.sqrt(xs.reduce((s, x) => s + (x - mean) ** 2, 0) / xs.length);
+    if (sd > 0) out.set(k, { mean, sd });
+  }
+  return out;
+}
+
+/**
+ * Spec 1.2 §6.3: the z-scored Euclidean distance over the features both have, as a root mean square so pairs
+ * sharing different numbers of features compare (plan 14 Ruling 6); a word counts 0 when equal, else 1. Null
+ * when they share fewer than MIN_SHARED_FEATURES.
+ */
+function distance(a: Features, b: Features, z: Map<string, Scale>): { d: number; shared: string[] } | null {
+  const shared: string[] = [];
+  let sum = 0;
+  for (const [k, va] of Object.entries(a)) {
+    const vb = b[k];
+    if (vb === undefined) continue;
+    if (typeof va === "string" || typeof vb === "string") {
+      shared.push(k);
+      sum += va === vb ? 0 : 1;
+      continue;
+    }
+    const s = z.get(k);
+    if (!s) continue;
+    shared.push(k);
+    sum += ((va - vb) / s.sd) ** 2;
+  }
+  if (shared.length < MIN_SHARED_FEATURES) return null;
+  return { d: Math.sqrt(sum / shared.length), shared };
+}
+
+/** The dimensions the bars use that `canonical` has no value for, of its own or through a treat-like. */
+export function missingDims(c: Catalog, canonical: string, dims: readonly Dim[] = barDimsIn(c)): Dim[] {
+  const own = c.scores[canonical] ?? {};
+  const like = c.treatLike[canonical]?.like;
+  const lent = like ? (c.scores[like] ?? {}) : {};
+  return dims.filter((d) => !own[d] && !lent[d]);
+}
+
+/** Every dimension some bar of the catalog (the defaults, with the user's override) has a threshold on. */
+export function barDimsIn(c: Catalog): Dim[] {
+  const used = new Set<string>();
+  for (const kind of Object.values(c.bars))
+    for (const bar of Object.values(kind))
+      for (const [d, min] of Object.entries(bar)) if (min !== undefined) used.add(d);
+  return DIMS.filter((d) => used.has(d));
+}
+
+class Ranker {
+  private readonly all = new Map<string, Features>();
+  private readonly z: Map<string, Scale>;
+  constructor(private readonly c: Catalog) {
+    for (const r of canonicalRungs(c)) this.all.set(r, featuresOf(c, r));
+    this.z = scales([...this.all.values()]);
+  }
+  /** The rungs with an own value on any of `dims`, nearest first; each with what it would lend. */
+  rank(canonical: string, dims: readonly Dim[]): Suggestion[] {
+    const mine = this.all.get(canonical) ?? featuresOf(this.c, canonical);
+    const out: Suggestion[] = [];
+    for (const [other, f] of this.all) {
+      if (other === canonical) continue;
+      const own = ownValues(this.c, other);
+      const lends = dims.filter((d) => own[d] !== undefined);
+      if (lends.length === 0) continue;
+      const got = distance(mine, f, this.z);
+      if (got) out.push({ like: other, distance: Number(got.d.toFixed(4)), features: got.shared, lends });
+    }
+    return out.sort((a, b) => a.distance - b.distance || a.like.localeCompare(b.like));
+  }
+}
+
+/**
+ * Spec 1.2 §6.4 `treat-like --suggest`: the `limit` nearest rungs that would lend `canonical` a value it lacks
+ * on a dimension the bars use (any scored rung when it lacks none), with their distance and features.
+ */
+export function suggestStandIns(c: Catalog, canonical: string, limit = 3): Suggestion[] {
+  const lacking = missingDims(c, canonical);
+  return new Ranker(c).rank(canonical, lacking.length ? lacking : DIMS).slice(0, limit);
+}
+
+/**
+ * Spec 1.2 §6.1: for every rung the catalog can name, per dimension the bars use that it has no value for
+ * (of its own or through a treat-like), its nearest stand-in with a value there. A rung no rung is near
+ * enough to (fewer than MIN_SHARED_FEATURES shared) gets none on that dimension.
+ */
+export function inferStandIns(c: Catalog): Catalog["inferred"] {
+  const dims = barDimsIn(c);
+  const ranker = new Ranker(c);
+  const out: Catalog["inferred"] = {};
+  for (const canonical of canonicalRungs(c)) {
+    const lacking = missingDims(c, canonical, dims);
+    for (const d of lacking) {
+      const best = ranker.rank(canonical, [d])[0];
+      if (!best) continue;
+      const entry: InferredStandIn = { like: best.like, distance: best.distance, features: best.features };
+      (out[canonical] ??= {})[d] = entry;
+    }
+  }
+  return out;
+}
+
+/** The catalog with its inferred stand-ins filled in: what routing, validation and the surfaces read. */
+export function withStandIns(c: Catalog): Catalog {
+  return { ...c, inferred: inferStandIns(c) };
+}
+
+/** Whether `canonical` leans on an inferred stand-in for any value (`scoresOf`'s `inferred`). */
+export const leansOnStandIn = (c: Catalog, canonical: string): boolean =>
+  (scoresOf(c, canonical)?.inferred.length ?? 0) > 0;

package/src/services/treat-likes.ts

@@ -0,0 +1,84 @@
+import { type Dim, scoresOf, rungInfo } from "../domain/catalog.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { tryParseRung } from "../domain/ids.ts";
+import { ROLES } from "../domain/roles.ts";
+import { canonicalRung, loadCatalog, readOverride, removeTreatLikes } from "./catalog-service.ts";
+import { getProfile, listProfiles } from "./profile-store.ts";
+import { type Suggestion, suggestStandIns } from "./standins.ts";
+
+/** A profile's rung that would lean on an inferred stand-in, or be left with no value at all (spec 1.2 §6.4). */
+export interface LeftOnStandIn {
+  profile: string;
+  rung: string;
+  /** the dimensions an inferred stand-in would fill; empty when the rung is left unscored */
+  dims: Dim[];
+  /** no value of its own and no stand-in near enough: routing skips it */
+  unscored: boolean;
+}
+
+/**
+ * Spec 1.2 §6.4: the rungs of every profile (enabled roles' rungs and failover stand-ins) that would lean on an
+ * inferred stand-in, or be left with no value at all, once the user's treat-likes for `removed` (canonical
+ * rungs, or all of them) are gone. Never removed silently.
+ */
+export function leftOnStandIns(removed: string[] | "all"): LeftOnStandIn[] {
+  const cur = readOverride();
+  const treatLike = Object.fromEntries(
+    Object.entries(cur.treatLike).filter(([r]) => removed !== "all" && !removed.includes(r)),
+  );
+  const gone = removed === "all" ? Object.keys(cur.treatLike) : removed;
+  const c = loadCatalog({ timings: false, override: { ...cur, treatLike } });
+  const out: LeftOnStandIn[] = [];
+  for (const profile of listProfiles()) {
+    const p = getProfile(profile);
+    const rungs = new Set([
+      ...ROLES.filter((r) => p.roles[r].enabled).flatMap((r) => p.roles[r].rungs),
+      ...Object.values(p.failover),
+    ]);
+    for (const rung of rungs) {
+      if (!tryParseRung(rung)) continue;
+      const canonical = rungInfo(c, rung).canonical;
+      if (!gone.includes(canonical)) continue;
+      const s = scoresOf(c, canonical);
+      if (!s) out.push({ profile, rung, dims: [], unscored: true });
+      else if (s.inferred.length) out.push({ profile, rung, dims: s.inferred, unscored: false });
+    }
+  }
+  return out;
+}
+
+/** Spec 1.2 §6.4 `--suggest`: the rung, in canonical form, and its three nearest stand-ins. */
+export function suggestFor(rung: string): { canonical: string; lacking: Dim[]; suggestions: Suggestion[] } {
+  const c = loadCatalog({ timings: false });
+  const canonical = canonicalRung(rung);
+  const s = scoresOf(c, canonical);
+  return {
+    canonical,
+    lacking: s ? s.inferred : [],
+    suggestions: suggestStandIns(c, canonical),
+  };
+}
+
+/**
+ * Spec 1.2 §6.4 `--clear`: removes the user's treat-like for `rung`, naming first the profile rungs it
+ * leaves on an inferred stand-in. A shipped treat-like is not the user's to remove.
+ */
+export async function clearTreatLike(
+  rung: string,
+): Promise<{ rung: string; like: string; left: LeftOnStandIn[] }> {
+  const canonical = canonicalRung(rung);
+  const like = readOverride().treatLike[canonical];
+  if (!like)
+    throw new CatherdError("E_INPUT_INVALID", `${canonical} has no treat-like of yours to clear`, {
+      fix: "catherd catalog list shows each rung's treat-like; a shipped one is not yours to clear",
+    });
+  const left = leftOnStandIns([canonical]);
+  await removeTreatLikes([canonical]);
+  return { rung: canonical, like, left };
+}
+
+/** Spec 1.2 §6.4 `--reset`: removes every treat-like of the user's, naming first the rungs left on a stand-in. */
+export async function resetTreatLikes(): Promise<{ removed: [string, string][]; left: LeftOnStandIn[] }> {
+  const left = leftOnStandIns("all");
+  return { removed: await removeTreatLikes("all"), left };
+}