@trazum/core 1.81.0 → 1.82.0

package/src/helicone.ts

@@ -0,0 +1,227 @@
+/**
+ * Helicone's request export, read as a usage log.
+ *
+ * The third converter in the pattern `from-claude-code` started: a pure
+ * function turns one tool's export into Trazum's usage-log records, and every
+ * door prices it from there. Helicone sits as a proxy in front of the provider
+ * and keeps every request it saw, so a team using it already has the export.
+ *
+ * **The format is derived, not guessed.** The columns below are the SELECT
+ * that builds Helicone's own request table — `web/lib/api/request/request.ts`
+ * in Helicone/helicone — and the response shape its `POST /v1/request/query`
+ * endpoint documents. A converter written from memory of an API is a converter
+ * that silently mis-reads somebody's bill.
+ *
+ * ## The model, and why it takes three columns to answer
+ *
+ * Helicone carries `request_model`, `model_override` and `response_model`, and
+ * they can disagree: the override exists precisely because a proxy can send a
+ * different model than the caller asked for, and the response says what
+ * actually answered. **The response wins**, then the override, then the
+ * request — the bill is about what was billed, not what was intended — and
+ * `modelDisagreements` counts the rows where they differed so a reader can see
+ * the substitution happened rather than discover it in a total.
+ *
+ * ## What deliberately does not cross
+ *
+ * A Helicone row carries the request body and the response body — the prompt
+ * and the completion — and `request_user_id`, which is an email address in
+ * Helicone's own documented example. **None of it is read.** The converter
+ * names the fields it takes and takes nothing else, and a fixture plants a
+ * marker in each and greps the whole output.
+ *
+ * ## What it refuses to invent
+ *
+ * There is no cache-token split anywhere on the row: `cache_enabled` is a flag
+ * on the analytics table. A converted record therefore carries no cache fields
+ * and the caching questions come back `cannot-tell` rather than answered from
+ * a guess — the same refusal `from-otel` and `from-litellm` make.
+ *
+ * There is no conversation identity either. `request_id` is one call, so the
+ * records carry no `session` and the conversation-shaped findings stay
+ * unavailable. A custom property can carry one, and then it is there because
+ * the operator put it there — never because this file inferred it.
+ */
+
+/** One converted record, shaped exactly as `parseUsageLine` reads it. */
+export interface HeliconeRecord {
+  model: string;
+  ts?: string;
+  label?: string;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+export interface HeliconeConversion {
+  records: HeliconeRecord[];
+  /** Rows that were requests and converted. */
+  rows: number;
+  /** Rows naming no model in any of the three columns: counted, never guessed. */
+  unnamedModel: number;
+  /**
+   * Rows where the model that answered was not the model that was asked for.
+   *
+   * The response's model is what the bill rests on, and a proxy substituting
+   * one model for another is a fact worth seeing rather than a difference
+   * that only shows up as an unexplained total.
+   */
+  modelDisagreements: number;
+  /** Rows carrying no token counts at all — a logged request nobody can price. */
+  noTokens: number;
+  /** Rows Helicone served from its cache, with no token split behind the flag. */
+  cacheFlagged: number;
+  /** Lines or documents that did not parse as JSON at all. */
+  unparseable: number;
+}
+
+const asObject = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+
+const tryParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const asCount = (value: unknown): number | undefined => {
+  const n = typeof value === 'string' ? Number(value) : value;
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined;
+};
+
+const asName = (value: unknown): string | null =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+
+/**
+ * The label, from Helicone's custom properties.
+ *
+ * `request_properties` is the documented place for whatever a team tags its
+ * calls with, and the keys are theirs. Trazum looks for the ones a workload
+ * would plausibly be named by, in order, and takes the first — never joins
+ * several, because a workload has one name in a bill.
+ */
+function labelOf(row: Record<string, unknown>): string | undefined {
+  const properties = asObject(row.request_properties) ?? asObject(row.properties);
+  if (properties === null) return undefined;
+  for (const key of ['Helicone-Property-Label', 'label', 'workload', 'app', 'environment']) {
+    const found = asName(properties[key]);
+    if (found !== null) return found;
+  }
+  return undefined;
+}
+
+/** The request's creation time as an ISO instant, or undefined. */
+function timeOf(row: Record<string, unknown>): string | undefined {
+  const raw = row.request_created_at ?? row.created_at ?? row.response_created_at;
+  if (typeof raw !== 'string' && typeof raw !== 'number') return undefined;
+  const ms = typeof raw === 'number' ? raw : Date.parse(raw);
+  if (!Number.isFinite(ms)) return undefined;
+  return new Date(ms).toISOString();
+}
+
+/**
+ * Convert a Helicone request export.
+ *
+ * Accepts a JSON array of rows, a single row, `{ data: [...] }` as the query
+ * endpoint returns it, or newline-delimited rows. Pure over its input.
+ */
+export function heliconeRecords(text: string): HeliconeConversion {
+  const out: HeliconeConversion = {
+    records: [],
+    rows: 0,
+    unnamedModel: 0,
+    modelDisagreements: 0,
+    noTokens: 0,
+    cacheFlagged: 0,
+    unparseable: 0,
+  };
+
+  const rows: unknown[] = [];
+  const whole = tryParse(text);
+  if (whole !== undefined) {
+    if (Array.isArray(whole)) rows.push(...whole);
+    else {
+      const doc = asObject(whole);
+      if (doc !== null && Array.isArray(doc.data)) rows.push(...doc.data);
+      else if (doc !== null) rows.push(doc);
+    }
+  } else {
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      const parsed = tryParse(line);
+      if (parsed === undefined) out.unparseable += 1;
+      else if (Array.isArray(parsed)) rows.push(...parsed);
+      else rows.push(parsed);
+    }
+  }
+
+  for (const raw of rows) {
+    const row = asObject(raw);
+    if (row === null) continue;
+    const input = asCount(row.prompt_tokens);
+    const output = asCount(row.completion_tokens);
+    // A request row is one carrying at least one token column. Anything else
+    // in the same file is not a call and is skipped rather than recorded as a
+    // zero, which would be a call nobody made.
+    if (input === undefined && output === undefined) continue;
+
+    out.rows += 1;
+    if (input === 0 && output === 0) out.noTokens += 1;
+    if (row.cache_enabled === true || row.cache_enabled === 1 || row.cache_enabled === '1') {
+      out.cacheFlagged += 1;
+    }
+
+    /*
+      The response first, and this order is the whole point of counting the
+      disagreement. A proxy that substituted a model billed for the model that
+      answered, so that is what a bill has to price; taking the requested one
+      would report the intention and call it the cost.
+    */
+    const answered = asName(row.response_model);
+    const overridden = asName(row.model_override);
+    const requested = asName(row.request_model);
+    const model = answered ?? overridden ?? requested;
+    if (model === null) {
+      out.unnamedModel += 1;
+      continue;
+    }
+    if (requested !== null && answered !== null && requested !== answered) {
+      out.modelDisagreements += 1;
+    }
+
+    const ts = timeOf(row);
+    const label = labelOf(row);
+    out.records.push({
+      model,
+      ...(ts !== undefined ? { ts } : {}),
+      ...(label !== undefined ? { label } : {}),
+      usage: { input_tokens: input ?? 0, output_tokens: output ?? 0 },
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Whether a file looks like a Helicone request export, by shape.
+ *
+ * Deliberately narrow: a token column beside one of the names only Helicone's
+ * own SELECT produces. A looser test would claim an OpenAI usage response or a
+ * LiteLLM spend log — both of which also carry `prompt_tokens` — and refuse it
+ * in this file's words instead of letting the code that can read it try.
+ */
+export function looksLikeHelicone(text: string, prefixBytes = 8192): boolean {
+  const head = text.slice(0, prefixBytes);
+  if (!head.includes('prompt_tokens') && !head.includes('completion_tokens')) return false;
+  return (
+    head.includes('"request_created_at"') ||
+    head.includes('"request_model"') ||
+    head.includes('"response_model"') ||
+    head.includes('"request_properties"')
+  );
+}

package/src/i18n/en.ts

@@ -154,10 +154,12 @@ export const en: CoreMessages = {
       };
     },
 
-    promptCachingNotWorthIt: () => ({
+    promptCachingNotWorthIt: ({ readPct, writePct, breakEvenPct }) => ({
       title: 'At that hit rate, caching does not pay off',
       detail:
-        'A cache write costs 125% of the input price and a read costs 10%. Below roughly a 28% hit rate you pay more than you save. Either raise prefix reuse or leave caching off.',
+        breakEvenPct === null
+          ? `A cache write costs ${writePct}% of the input price on this model, the same as not caching, and a read costs ${readPct}%. So caching cannot lose you money here: at this hit rate it simply buys nothing. Raise prefix reuse and it starts paying immediately.`
+          : `A cache write costs ${writePct}% of the input price on this model and a read costs ${readPct}%. Below a ${breakEvenPct}% hit rate you pay more than you save. Either raise prefix reuse or leave caching off.`,
     }),
 
     belowCacheMinimum: ({
@@ -198,7 +200,12 @@ export const en: CoreMessages = {
 
     modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
       title: `This task may not need ${modelName}`,
-      detail: `By length and vocabulary the prompt looks like "${tier}" complexity. On ${candidateName} you would go from ${currentUsd} to ${candidateUsd} per month. This is a keyword heuristic, not a judgement about answer quality: measure the difference with your own evaluations before switching in production.`,
+      detail: `By length and vocabulary the prompt looks like "${tier}" complexity. On ${candidateName} you would go from ${currentUsd} to ${candidateUsd} per month. This is a keyword heuristic, not a judgement about answer quality. Measure it before switching in production: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <cases> --yes\` sends the same cases to both models and reports whether the cheaper one still does the job.`,
+    }),
+
+    tierSignalsConflict: ({ complexSignals, simpleSignals }) => ({
+      title: 'The prompt asks for depth and for brevity at once',
+      detail: `It carries ${complexSignals} signal${complexSignals === 1 ? '' : 's'} of a hard task and ${simpleSignals} of an easy one, and this heuristic scores those against each other, so they cancel. No tier is recommended here: a number produced by two opposite readings cancelling out looks exactly like a prompt with no signals at all, and they are not the same thing. Decide it by measurement rather than by vocabulary: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <cases> --yes\`.`,
     }),
 
     outputDominated: ({ outputUsd, inputUsd }) => ({

package/src/i18n/es.ts

@@ -138,10 +138,12 @@ export const es: CoreMessages = {
       };
     },
 
-    promptCachingNotWorthIt: () => ({
+    promptCachingNotWorthIt: ({ readPct, writePct, breakEvenPct }) => ({
       title: 'Con esa tasa de acierto, la caché no compensa',
       detail:
-        'Escribir en caché cuesta un 125% del precio de entrada y leer un 10%. Por debajo de un ~28% de aciertos pagas más de lo que ahorras. Sube la reutilización del prefijo o deja la caché desactivada.',
+        breakEvenPct === null
+          ? `En este modelo escribir en caché cuesta un ${writePct}% del precio de entrada, lo mismo que no usarla, y leer un ${readPct}%. Así que aquí la caché no puede costarte dinero: con esta tasa de acierto simplemente no te aporta nada. En cuanto subas la reutilización del prefijo, empieza a compensar.`
+          : `En este modelo escribir en caché cuesta un ${writePct}% del precio de entrada y leer un ${readPct}%. Por debajo de un ${breakEvenPct}% de aciertos pagas más de lo que ahorras. Sube la reutilización del prefijo o deja la caché desactivada.`,
     }),
 
     belowCacheMinimum: ({
@@ -182,7 +184,12 @@ export const es: CoreMessages = {
 
     modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
       title: `Esta tarea quizá no necesite ${modelName}`,
-      detail: `Por longitud y vocabulario, el prompt parece de complejidad "${tier}". Con ${candidateName} pasarías de ${currentUsd} a ${candidateUsd} al mes. Es una heurística por palabras clave, no un juicio de calidad: mide la diferencia con tus propias evaluaciones antes de cambiar en producción.`,
+      detail: `Por longitud y vocabulario, el prompt parece de complejidad "${tier}". Con ${candidateName} pasarías de ${currentUsd} a ${candidateUsd} al mes. Es una heurística por palabras clave, no un juicio de calidad. Mídelo antes de cambiar en producción: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <casos> --yes\` envía los mismos casos a ambos modelos y dice si el barato sigue haciendo el trabajo.`,
+    }),
+
+    tierSignalsConflict: ({ complexSignals, simpleSignals }) => ({
+      title: 'El prompt pide profundidad y brevedad a la vez',
+      detail: `Lleva ${complexSignals} señal${complexSignals === 1 ? '' : 'es'} de tarea difícil y ${simpleSignals} de tarea fácil, y esta heurística las resta entre sí, así que se anulan. Aquí no se recomienda ningún nivel: un número que sale de dos lecturas opuestas cancelándose se parece exactamente a un prompt sin ninguna señal, y no son lo mismo. Decídelo midiendo y no por vocabulario: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <casos> --yes\`.`,
     }),
 
     outputDominated: ({ outputUsd, inputUsd }) => ({

package/src/i18n/types.ts

@@ -215,6 +215,49 @@ export interface LlmMessages {
   suspiciousShrink(retainedPct: number): string;
 }
 
+/**
+ * What the caching-does-not-pay advisory needs to state a threshold that is
+ * true about **this** model.
+ *
+ * It used to take nothing and print one sentence for every model: *"a cache
+ * write costs 125% of the input price and a read costs 10%. Below roughly a 28%
+ * hit rate you pay more than you save."* Two of those three numbers were the
+ * Anthropic multipliers stated as universal, and the third was not derivable
+ * from any model in the catalogue: at 125% and 10% the break-even is 21.74%,
+ * not 28%.
+ *
+ * The multipliers were already in hand at the call site and already passed to
+ * the advisory next door. Only this message invented its own.
+ */
+export interface PromptCachingNotWorthItParams {
+  /** The model's cache read multiplier as a percentage of the input price. */
+  readPct: number;
+  /** Its 5-minute cache write multiplier, likewise. */
+  writePct: number;
+  /**
+   * The hit rate at which caching stops costing money, derived rather than
+   * quoted: `(1 - write) / (read - write)`.
+   *
+   * `null` when the write multiplier is 1, which is not a smaller threshold but
+   * a different situation: writing costs exactly what not caching costs, so
+   * caching can never lose money and there is no rate below which it does. Eight
+   * of the eighteen models in the catalogue are that shape, and the old sentence
+   * told all eight to consider turning caching off.
+   */
+  breakEvenPct: number | null;
+}
+
+/**
+ * What the tier heuristic saw when it declined to answer.
+ *
+ * Both counts, because "three of each" and "one of each" are different degrees
+ * of the same refusal and the reader can act on the difference.
+ */
+export interface TierSignalsConflictParams {
+  complexSignals: number;
+  simpleSignals: number;
+}
+
 /** Why a proposed rewrite did not survive checking against the prompt. */
 export interface SuggestMessages {
   'not-found'(): string;
@@ -236,11 +279,12 @@ export interface CoreMessages {
     contextOverflow(p: ContextOverflowParams): LocalizedMessage;
     contextNearLimit(p: ContextNearLimitParams): LocalizedMessage;
     promptCaching(p: PromptCachingParams): LocalizedMessage;
-    promptCachingNotWorthIt(): LocalizedMessage;
+    promptCachingNotWorthIt(p: PromptCachingNotWorthItParams): LocalizedMessage;
     belowCacheMinimum(p: BelowCacheMinimumParams): LocalizedMessage;
     cachePrefixReorder(p: CachePrefixReorderParams): LocalizedMessage;
     batchApi(): LocalizedMessage;
     modelDowngrade(p: ModelDowngradeParams): LocalizedMessage;
+    tierSignalsConflict(p: TierSignalsConflictParams): LocalizedMessage;
     outputDominated(p: OutputDominatedParams): LocalizedMessage;
     promoPricing(p: PromoPricingParams): LocalizedMessage;
     contradictoryInstructions(p: ContradictoryInstructionsParams): LocalizedMessage;

package/src/index.ts

@@ -166,7 +166,18 @@ export type {
   GatewayStanding,
   RefuseReason,
 } from './gateway.js';
+export {
+  BANDS,
+  MEASURED_FOREIGN_ERROR_PCT,
+  bandFor,
+  bucketFor,
+  foreignTokenizer,
+  measuredForeignError,
+} from './band.js';
+export type { BandBucket } from './band.js';
 export { conform, CONTRACT_NAMES, requiredFieldsOf } from './conform.js';
+export { readDroppedVerdict, verdictMatchesSlice } from './verdict-bridge.js';
+export type { DroppedVerdict, BridgeReading } from './verdict-bridge.js';
 export { CONTRACT_SCHEMAS, contractSchema } from './schemas.js';
 export type {
   ConformOptions,
@@ -203,6 +214,10 @@ export type { MeasuredIndex } from './position.js';
 export { claudeCodeRecords, looksLikeClaudeCodeTranscript } from './claude-code.js';
 export { otelRecords, looksLikeOtel } from './otel.js';
 export type { OtelConversion, OtelRecord } from './otel.js';
+export { litellmRecords, looksLikeLiteLlm } from './litellm.js';
+export type { LiteLlmConversion, LiteLlmRecord } from './litellm.js';
+export { heliconeRecords, looksLikeHelicone } from './helicone.js';
+export type { HeliconeConversion, HeliconeRecord } from './helicone.js';
 export type { ClaudeCodeConversion, ClaudeCodeRecord } from './claude-code.js';
 export { positionReport } from './position-report.js';
 export type {
@@ -424,7 +439,8 @@ export type {
 export { RULES, getRule } from './rules.js';
 export { segment, join, protectedTexts } from './segment.js';
 export { computeSavings, costOfCall, formatUsd, formatSignedUsd } from './savings.js';
-export { buildAdvisories, recommendTier } from './advisories.js';
+export { buildAdvisories, recommendTier, recommendTierDetailed } from './advisories.js';
+export type { TierRecommendation } from './advisories.js';
 export type { AdvisoryOptions } from './advisories.js';
 export { analyzeCachePrefix } from './cache.js';
 

package/src/litellm.ts

@@ -0,0 +1,243 @@
+/**
+ * LiteLLM's spend log, read as a usage log.
+ *
+ * `from-claude-code` proved the pattern and `from-otel` generalised it: a pure
+ * converter turns one tool's export into Trazum's usage-log records, and every
+ * door prices it from there. LiteLLM is the gateway a great many teams already
+ * put in front of every provider, so its `LiteLLM_SpendLogs` table is the one
+ * export most likely to already exist on somebody's disk.
+ *
+ * **The format is derived, not guessed.** Every field below is read off
+ * `litellm/proxy/schema.prisma` in BerriAI/litellm, model `LiteLLM_SpendLogs`.
+ * A converter written from memory of an API is a converter that silently
+ * mis-reads somebody's bill, and this project has one rule above all others
+ * about numbers it cannot justify.
+ *
+ * ## What maps
+ *
+ * | LiteLLM | Trazum |
+ * | --- | --- |
+ * | `model` | `model` |
+ * | `prompt_tokens` | `usage.input_tokens` |
+ * | `completion_tokens` | `usage.output_tokens` |
+ * | `startTime` | `ts` |
+ * | `session_id` | `session` |
+ * | `request_tags[0]`, else `metadata.tags[0]`, else `model_group` | `label` |
+ *
+ * ## What deliberately does not cross
+ *
+ * The row carries `messages` and `response` — the prompt itself and the
+ * completion — plus `api_key` (hashed, still credential-shaped),
+ * `requester_ip_address`, `user` and `end_user`. **None of it is read.** The
+ * converter names the fields it takes and takes nothing else, and a fixture
+ * plants a marker in each of them and greps the whole output.
+ *
+ * ## What it refuses to invent
+ *
+ * `cache_hit` is a flag and `cache_key` an identifier; neither is a token
+ * count. A converted record therefore carries no cache split at all, and the
+ * caching questions come back `cannot-tell` rather than answered from a
+ * guess — the same refusal as inventing a price. `cacheFlagged` counts the
+ * rows that said "hit" so the operator can see the gap is real rather than
+ * empty.
+ *
+ * `spend` is LiteLLM's own priced figure and is **never** merged into
+ * Trazum's catalogue-priced total. It is a second measurement of the same
+ * calls, kept apart the way the store's provider-billed standing is kept
+ * apart from the log's, and returned on its own so a caller who wants to
+ * compare the two can, deliberately.
+ */
+
+/** One converted record, shaped exactly as `parseUsageLine` reads it. */
+export interface LiteLlmRecord {
+  model: string;
+  ts?: string;
+  label?: string;
+  session?: string;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+export interface LiteLlmConversion {
+  records: LiteLlmRecord[];
+  /** Rows that were spend logs and converted. */
+  rows: number;
+  /** Rows naming no model: counted, never guessed at, never dropped silently. */
+  unnamedModel: number;
+  /** Rows carrying no token counts at all — a logged call nobody can price. */
+  noTokens: number;
+  /** Rows LiteLLM marked as a cache hit, with no token split to act on. */
+  cacheFlagged: number;
+  /**
+   * LiteLLM's own total for the converted rows, in USD, or null when no row
+   * carried one. **Never** added to anything Trazum computes: it is the
+   * gateway's arithmetic over the gateway's price table, and merging two
+   * price tables into one figure is how a report becomes quietly wrong.
+   */
+  reportedSpendUsd: number | null;
+  /** Lines or documents that did not parse as JSON at all. */
+  unparseable: number;
+}
+
+const asObject = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+
+const tryParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const asCount = (value: unknown): number | undefined => {
+  const n = typeof value === 'string' ? Number(value) : value;
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined;
+};
+
+/**
+ * The first tag LiteLLM carries for a row, from the two places it puts them.
+ *
+ * `request_tags` is the documented column and `metadata.tags` is where the
+ * proxy writes them when the caller passes them in the request body. First
+ * only: a workload has one name in a bill, and joining several tags into one
+ * label would invent a workload that does not exist.
+ */
+function labelOf(row: Record<string, unknown>): string | undefined {
+  const fromColumn = Array.isArray(row.request_tags) ? row.request_tags : null;
+  if (fromColumn !== null && typeof fromColumn[0] === 'string' && fromColumn[0] !== '') {
+    return fromColumn[0];
+  }
+  const metadata = asObject(row.metadata);
+  const fromMetadata = metadata !== null && Array.isArray(metadata.tags) ? metadata.tags : null;
+  if (fromMetadata !== null && typeof fromMetadata[0] === 'string' && fromMetadata[0] !== '') {
+    return fromMetadata[0];
+  }
+  // The public model name a proxy route is known by. A weaker label than a
+  // tag — it groups by route rather than by workload — and better than none.
+  if (typeof row.model_group === 'string' && row.model_group !== '') return row.model_group;
+  return undefined;
+}
+
+/** `startTime` as an ISO instant, or undefined when it is not a time. */
+function timeOf(row: Record<string, unknown>): string | undefined {
+  const raw = row.startTime ?? row.start_time;
+  if (typeof raw !== 'string' && typeof raw !== 'number') return undefined;
+  const ms = typeof raw === 'number' ? raw : Date.parse(raw);
+  if (!Number.isFinite(ms)) return undefined;
+  return new Date(ms).toISOString();
+}
+
+/**
+ * Convert a LiteLLM spend-log export.
+ *
+ * Accepts a JSON array of rows, a single row, `{ data: [...] }` as the proxy's
+ * own endpoints return it, or newline-delimited rows — so a `psql --json`
+ * dump, an API response and a streamed capture all work. Pure over its input.
+ */
+export function litellmRecords(text: string): LiteLlmConversion {
+  const out: LiteLlmConversion = {
+    records: [],
+    rows: 0,
+    unnamedModel: 0,
+    noTokens: 0,
+    cacheFlagged: 0,
+    reportedSpendUsd: null,
+    unparseable: 0,
+  };
+
+  const rows: unknown[] = [];
+  const whole = tryParse(text);
+  if (whole !== undefined) {
+    if (Array.isArray(whole)) rows.push(...whole);
+    else {
+      const doc = asObject(whole);
+      // `{ data: [...] }` is what the proxy's spend endpoints return.
+      if (doc !== null && Array.isArray(doc.data)) rows.push(...doc.data);
+      else if (doc !== null) rows.push(doc);
+    }
+  } else {
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      const parsed = tryParse(line);
+      if (parsed === undefined) out.unparseable += 1;
+      else if (Array.isArray(parsed)) rows.push(...parsed);
+      else rows.push(parsed);
+    }
+  }
+
+  let spend = 0;
+  let sawSpend = false;
+
+  for (const raw of rows) {
+    const row = asObject(raw);
+    if (row === null) continue;
+    // A spend log row is one that carries at least one of the two token
+    // columns. Anything else in the same file is not a call and is skipped
+    // rather than converted into a record of zero.
+    const input = asCount(row.prompt_tokens);
+    const output = asCount(row.completion_tokens);
+    if (input === undefined && output === undefined) continue;
+
+    out.rows += 1;
+
+    if (input === 0 && output === 0) out.noTokens += 1;
+    if (row.cache_hit === true || row.cache_hit === 'true' || row.cache_hit === 'True') {
+      out.cacheFlagged += 1;
+    }
+
+    const reported = asCount(row.spend);
+    if (reported !== undefined) {
+      spend += reported;
+      sawSpend = true;
+    }
+
+    const model = typeof row.model === 'string' ? row.model.trim() : '';
+    if (model === '') {
+      // Counted, never guessed at. `model_group` is a route name, not a model,
+      // and pricing a call by the route it took would be a figure attributed
+      // to something it does not describe.
+      out.unnamedModel += 1;
+      continue;
+    }
+
+    const ts = timeOf(row);
+    const label = labelOf(row);
+    const session = typeof row.session_id === 'string' && row.session_id !== ''
+      ? row.session_id
+      : undefined;
+
+    out.records.push({
+      model,
+      ...(ts !== undefined ? { ts } : {}),
+      ...(label !== undefined ? { label } : {}),
+      ...(session !== undefined ? { session } : {}),
+      usage: { input_tokens: input ?? 0, output_tokens: output ?? 0 },
+    });
+  }
+
+  out.reportedSpendUsd = sawSpend ? spend : null;
+  return out;
+}
+
+/**
+ * Whether a file looks like a LiteLLM spend log, by shape.
+ *
+ * Deliberately narrow: `request_id` beside one of the two token columns, and
+ * a field no other export in this project carries. A looser test would claim
+ * an OpenAI usage response, whose rows also have `prompt_tokens`, and refuse
+ * it in this file's words instead of letting the code that can read it try.
+ */
+export function looksLikeLiteLlm(text: string, prefixBytes = 8192): boolean {
+  const head = text.slice(0, prefixBytes);
+  if (!head.includes('prompt_tokens') && !head.includes('completion_tokens')) return false;
+  return (
+    head.includes('"request_id"') ||
+    head.includes('"custom_llm_provider"') ||
+    head.includes('"model_group"')
+  );
+}