modelrig 0.0.1 → 0.2.0

package/dist/telemetry/otel-map.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * OTLP mapping — E1 (spec §3, §4). PURE: no I/O, no env, no imports from the
+ * exporter/sinks/store. One `inferences` row → one OTLP/HTTP JSON span.
+ *
+ * ── THE ONE PLACE gen_ai.* NAMES LIVE ────────────────────────────────────
+ * Every OpenTelemetry semantic-convention attribute name this product emits is
+ * declared in THIS module and nowhere else (architect-review-2026-08 §2(f)).
+ * The pin is `SEMCONV_VERSION` below — bump it here and the wire changes in one
+ * edit, not scattered across the codebase. If you find a `"gen_ai.*"` string
+ * literal outside this file, it is a bug.
+ *
+ * ── WHY HAND-BUILT JSON, NOT @opentelemetry/* ────────────────────────────
+ * We are mapping completed rows, not instrumenting live code, so the SDK's
+ * tracer runtime would be dead weight (spec §2.2). The shape below is the
+ * OTLP/HTTP `ExportTraceServiceRequest` JSON encoding. Two encoding rules bite
+ * here and are easy to get wrong (plan §"risks"):
+ *   • trace_id / span_id are LOWERCASE HEX strings — the documented OTLP/JSON
+ *     exception to Protobuf's base64-for-bytes. NOT base64.
+ *   • int64 attribute + timestamp values are DECIMAL STRINGS; doubles are
+ *     numbers. `intValue`/`startTimeUnixNano` are strings on the wire.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACEPARENT_TAG = exports.SEMCONV_VERSION = void 0;
+exports.parseTraceparent = parseTraceparent;
+exports.inferenceToSpan = inferenceToSpan;
+exports.cacheDecisionSpanAttributes = cacheDecisionSpanAttributes;
+exports.buildExportTraceRequest = buildExportTraceRequest;
+const node_crypto_1 = require("node:crypto");
+/** Semantic-conventions pin (architect ruling §2(f)). The scope version on the
+ * wire and the single source of truth for which gen_ai vintage we speak. */
+exports.SEMCONV_VERSION = "1.41.0";
+/** SPAN_KIND_CLIENT — an LLM call leaving this process to a provider. */
+const SPAN_KIND_CLIENT = 3;
+/** SPAN_KIND_INTERNAL — the synthetic search/tool-execution span. */
+const SPAN_KIND_INTERNAL = 1;
+/** STATUS_CODE_UNSET / STATUS_CODE_ERROR (OK is never set — gen_ai convention
+ * leaves a successful span UNSET). */
+const STATUS_UNSET = 0;
+const STATUS_ERROR = 2;
+// ── attribute constructors (typed value wrappers) ────────────────────────
+const strAttr = (key, value) => ({ key, value: { stringValue: value } });
+const intAttr = (key, value) => ({
+    key,
+    value: { intValue: String(Math.trunc(value)) },
+});
+const dblAttr = (key, value) => ({ key, value: { doubleValue: value } });
+const boolAttr = (key, value) => ({ key, value: { boolValue: value } });
+// ── W3C traceparent ──────────────────────────────────────────────────────
+/** The tag key the gateway stashes an inbound traceparent under (spec §2.5). */
+exports.TRACEPARENT_TAG = "otel.traceparent";
+/** version(00) - trace-id(32hex) - parent-id(16hex) - flags(2hex). */
+const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+/**
+ * Parse a W3C `traceparent` value, or null when absent/malformed. The gateway
+ * (packages/modelrig-server) reuses this so the SDK and the server cannot
+ * disagree about what "well-formed" means. All-zero trace/parent ids are
+ * rejected per the W3C spec (they mean "no parent").
+ */
+function parseTraceparent(value) {
+    if (value === undefined || value === null)
+        return null;
+    const match = TRACEPARENT_RE.exec(value.trim());
+    if (match === null)
+        return null;
+    const traceId = match[1].toLowerCase();
+    const parentSpanId = match[2].toLowerCase();
+    if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+        return null;
+    return { traceId, parentSpanId };
+}
+// ── deterministic span identity (spec §2.6) ──────────────────────────────
+// Same row twice ⇒ byte-identical span, so a re-emit after a crash is
+// idempotent at the sink. Both are truncations of sha256(inference id).
+function sha256Hex(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(input).digest("hex");
+}
+function traceIdFor(inferenceId) {
+    return sha256Hex(inferenceId).slice(0, 32); // 16 bytes
+}
+function spanIdFor(inferenceId) {
+    return sha256Hex(inferenceId).slice(0, 16); // 8 bytes
+}
+/** ISO timestamp (+ optional ms offset) → OTLP `*UnixNano` decimal string.
+ * BigInt keeps nanosecond precision that Number would lose past 2^53. */
+function toUnixNano(iso, plusMs = 0) {
+    const ms = Date.parse(iso);
+    const baseMs = Number.isFinite(ms) ? ms : 0;
+    return (BigInt(baseMs + Math.trunc(plusMs)) * 1000000n).toString();
+}
+/** The synthetic search-cost row is emitted as a tool-execution span (§2.7). */
+function isSearchRow(row) {
+    return row.provider === "search";
+}
+function readTraceparentTag(row) {
+    let tags;
+    try {
+        tags = JSON.parse(row.tagsJson);
+    }
+    catch {
+        return null;
+    }
+    if (tags === null || typeof tags !== "object")
+        return null;
+    const raw = tags[exports.TRACEPARENT_TAG];
+    return typeof raw === "string" ? parseTraceparent(raw) : null;
+}
+/**
+ * Map one telemetry row to one OTLP span (spec §3, normative). Pure and total:
+ * every field comes from the row; nulls are omitted (never emitted as empty).
+ */
+function inferenceToSpan(row) {
+    const search = isSearchRow(row);
+    const operationName = search ? "execute_tool" : "chat";
+    const spanName = search ? "execute_tool search" : `chat ${row.model}`;
+    const attrs = [
+        strAttr("gen_ai.operation.name", operationName),
+        strAttr("gen_ai.provider.name", row.provider),
+        strAttr("gen_ai.request.model", row.model),
+        strAttr("gen_ai.response.model", row.model),
+        intAttr("gen_ai.usage.input_tokens", row.tokensIn),
+        intAttr("gen_ai.usage.output_tokens", row.tokensOut),
+        intAttr("gen_ai.usage.cached_input_tokens", row.tokensCached),
+        strAttr("modelrig.route", row.route),
+        intAttr("modelrig.route_version", row.routeVersion),
+        // Honest zero: cost stays 0 for an unpriced model; the flag says so rather
+        // than the code inventing a dollar figure (spec §3, addendum A1).
+        dblAttr("modelrig.cost_estimate_usd", row.costEstimateUsd),
+        strAttr("modelrig.served_tier", row.servedTier),
+    ];
+    // Cache accounting (WS-A / E1 parity). Emitted only when non-zero to keep the
+    // vast majority of spans lean. `cache_read_tokens` carries the same quantity
+    // as the pre-existing `cached_input_tokens` under the spelling the cache-aware
+    // spec (§2) names; both are kept — S3 retires nothing, and a consumer reads a
+    // specific key rather than summing, so this is detail, not double-count.
+    if (row.tokensCached > 0)
+        attrs.push(intAttr("gen_ai.usage.cache_read_tokens", row.tokensCached));
+    const cacheWrite = row.tokensCacheWrite ?? 0;
+    if (cacheWrite > 0)
+        attrs.push(intAttr("gen_ai.usage.cache_creation_tokens", cacheWrite));
+    if (row.pricingMissing)
+        attrs.push(boolAttr("modelrig.pricing_missing", true));
+    if (row.ttfbMs !== null)
+        attrs.push(intAttr("modelrig.ttfb_ms", row.ttfbMs));
+    if (row.servedVariant !== null)
+        attrs.push(strAttr("modelrig.served_variant", row.servedVariant));
+    if (row.repairedBy !== null)
+        attrs.push(strAttr("modelrig.repaired_by", row.repairedBy));
+    if (row.fingerprintCell !== null) {
+        // Irreversible by construction (a schema hash) — safe to emit (spec §3).
+        attrs.push(strAttr("modelrig.fingerprint_cell", row.fingerprintCell));
+    }
+    if (row.failureClass !== null)
+        attrs.push(strAttr("modelrig.failure_class", row.failureClass));
+    const parent = readTraceparentTag(row);
+    const traceId = parent !== null ? parent.traceId : traceIdFor(row.id);
+    const span = {
+        traceId,
+        spanId: spanIdFor(row.id),
+        ...(parent !== null ? { parentSpanId: parent.parentSpanId } : {}),
+        name: spanName,
+        kind: search ? SPAN_KIND_INTERNAL : SPAN_KIND_CLIENT,
+        startTimeUnixNano: toUnixNano(row.ts),
+        endTimeUnixNano: toUnixNano(row.ts, row.latencyMs),
+        attributes: attrs,
+        // Failures are facts: a non-null class flips the span to ERROR (spec §2.7).
+        status: row.failureClass !== null
+            ? { code: STATUS_ERROR, message: row.failureClass }
+            : { code: STATUS_UNSET },
+    };
+    return span;
+}
+/**
+ * Decision-span attributes for a cache-aware routing decision (cache-aware-routing
+ * spec §5.5 — "routing must never be opaque"). Returns the `modelrig.cache.*`
+ * attribute set a caller attaches to the swap/proposal decision span so the
+ * verdict + its economics travel to any OTLP backend alongside the inference
+ * spans. Declared HERE because this module is the one place OTLP attribute names
+ * live (the pin at the top of this file).
+ *
+ * `breakeven_conformant_calls` can be `Infinity` ("never breaks even"), which is
+ * not a valid JSON number — so it is emitted as a double ONLY when finite, and a
+ * boolean `modelrig.cache.breakeven_reachable` records the never-case explicitly
+ * rather than dropping the fact.
+ */
+function cacheDecisionSpanAttributes(ctx) {
+    const attrs = [
+        strAttr("modelrig.cache.verdict", ctx.verdict),
+        dblAttr("modelrig.cache.observed_hit_rate", ctx.observed_hit_rate),
+        dblAttr("modelrig.cache.observed_write_rate", ctx.observed_write_rate),
+        intAttr("modelrig.cache.window_days", ctx.window_days),
+        dblAttr("modelrig.cache.incumbent_effective_in_per_mtok", ctx.incumbent_effective_in_per_mtok),
+        dblAttr("modelrig.cache.challenger_cold_in_per_mtok", ctx.challenger_cold_in_per_mtok),
+        dblAttr("modelrig.cache.switch_cost_usd", ctx.switch_cost_usd),
+        dblAttr("modelrig.cache.cache_option_value_usd", ctx.cache_option_value_usd),
+    ];
+    const reachable = Number.isFinite(ctx.breakeven_conformant_calls);
+    attrs.push(boolAttr("modelrig.cache.breakeven_reachable", reachable));
+    if (reachable) {
+        attrs.push(dblAttr("modelrig.cache.breakeven_conformant_calls", ctx.breakeven_conformant_calls));
+    }
+    return attrs;
+}
+/**
+ * Wrap spans in the OTLP `ExportTraceServiceRequest` envelope (spec §4, pure).
+ * One resource, one scope (`modelrig` @ SEMCONV_VERSION), N spans.
+ */
+function buildExportTraceRequest(spans, resource) {
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [strAttr("service.name", resource.serviceName), ...(resource.attributes ?? [])],
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: "modelrig", version: exports.SEMCONV_VERSION },
+                        spans,
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/telemetry/otel-normalize.d.ts

@@ -0,0 +1,104 @@
+/**
+ * OTLP-in v0 normalizer — Expansion E3-Harvest (spec §3). PURE: no I/O, no env,
+ * no imports from the exporter/sinks/server. The INBOUND sibling of `otel-map.ts`
+ * (which is the OUTBOUND our-rows → OTLP mapper). Foreign OTLP spans in →
+ * `runs` + attested `steps` out.
+ *
+ * ── SCOPE (spec §3.1): identity, structure, timing, status, model/provider,
+ * usage ONLY. ZERO content extraction — prompts/completions/messages in foreign
+ * spans are never read, never stored, never passed to the envelope. Retention-
+ * free default; content custody arrives with E2-C. This deletes ~60% of
+ * Langfuse's problem surface deliberately.
+ *
+ * ── VINTAGE HANDLING is pure NAME-UNION, not versioned dispatch (learnings
+ * §1.1, their proven approach), with our two divergences (spec §3.3):
+ *   (1) namespaced attributes outrank bare ones — `gen_ai.*`/`llm.*` are checked
+ *       BEFORE a bare `model`;
+ *   (2) provider IS normalized (Langfuse never reads provider on ingest), because
+ *       `model_key = provider/model` feeds our registry/priors/leaderboard —
+ *       recorded honestly, ending at "unknown", never guessed.
+ *
+ * The usage de-double-counting and the agent-span aggregate skip are adopted
+ * from OtelIngestionProcessor's generic extractor (learnings §1.2, read for
+ * pattern per §5.3 — implemented fresh here, no bodies copied).
+ */
+import type { WireRun, WireStep } from "./ingest-protocol";
+export interface AttestedUsage {
+    /** Non-cached input tokens (cache buckets subtracted, floored 0). */
+    readonly input?: number;
+    /** Non-reasoning/-audio output tokens (subtracted, floored 0). */
+    readonly output?: number;
+    readonly total?: number;
+    readonly input_cached_tokens?: number;
+    readonly input_cache_creation?: number;
+    readonly output_reasoning_tokens?: number;
+    readonly output_audio_tokens?: number;
+    /** Any other gen_ai.usage.* / llm.token_count.* bucket, name preserved. */
+    readonly [bucket: string]: number | undefined;
+}
+export interface AttestedEnvelope {
+    /** Resolved model, or null when no model attribute was present. */
+    readonly model: string | null;
+    /** Resolved provider — honest, ending at "unknown", NEVER guessed. */
+    readonly provider: string;
+    /** Classified operation (generation/tool/agent/retriever/embedding/span). */
+    readonly operation: string;
+    /** De-double-counted usage; omitted entirely on agent-aggregate spans. */
+    readonly usage?: AttestedUsage;
+    /** The emitting instrumentation scope (name + optional version). */
+    readonly scope: {
+        readonly name: string;
+        readonly version: string | null;
+    };
+}
+type OtlpAnyValueIn = Record<string, unknown>;
+interface OtlpKeyValueIn {
+    key?: string;
+    value?: OtlpAnyValueIn;
+}
+/** What a decoded span looks like to us (both transports converge here). */
+export interface OtlpSpanIn {
+    traceId?: unknown;
+    trace_id?: unknown;
+    spanId?: unknown;
+    span_id?: unknown;
+    parentSpanId?: unknown;
+    parent_span_id?: unknown;
+    name?: unknown;
+    kind?: unknown;
+    startTimeUnixNano?: unknown;
+    start_time_unix_nano?: unknown;
+    endTimeUnixNano?: unknown;
+    end_time_unix_nano?: unknown;
+    attributes?: OtlpKeyValueIn[];
+    status?: {
+        code?: unknown;
+        message?: unknown;
+    };
+}
+export interface NormalizeResult {
+    readonly runs: WireRun[];
+    /** Attested steps (each carries the `attested` envelope). */
+    readonly steps: WireStep[];
+    /** reason → count (bad_otlp_span, unmapped_attribute, ts_copied_edge, …). */
+    readonly drops: Record<string, number>;
+    /** Total spans seen (before drops) — for the conversion-failure log. */
+    readonly spanCount: number;
+    /** Distinct instrumentation-scope names seen — named in the logs-mistake 400. */
+    readonly scopeNames: string[];
+}
+/**
+ * Normalize a decoded OTLP `TracesData` structure into runs + attested steps.
+ * Total and defensive: a malformed span is dropped-and-counted, never thrown.
+ * `nowMs` is injected so callers/tests are deterministic (default Date.now()).
+ */
+export declare function normalizeOtlpTraces(data: unknown, nowMs?: number): NormalizeResult;
+/**
+ * Logs-exporter detection (learnings §1.2). ResourceLogs and ResourceSpans share
+ * protobuf field numbers, so a logs exporter pointed at the traces endpoint
+ * decodes as id-less "spans". A JSON logs body carries `resourceLogs` outright.
+ * Returns true when the body is a logs payload that must be rejected 400.
+ */
+export declare function looksLikeLogsPayload(data: unknown): boolean;
+export {};
+//# sourceMappingURL=otel-normalize.d.ts.map

package/dist/telemetry/otel-normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-normalize.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel-normalize.ts"],"names":[],"mappings":"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"}