@zanii/blackbox 0.12.0 → 0.13.0

package/README.md

@@ -83,6 +83,10 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.13.0
+
+- `fromOtlp(body)`: OpenTelemetry spans (GenAI semconv or OpenInference) as session events, the mapping behind gateway v0.15's `POST /v1/traces`. Point any framework's OTLP exporter at the gateway with the session's token, and its spans join the record.
+
 ## New in 0.12.0
 
 - Tax credit notes: `taxCreditNote` / `renderTaxCreditNote`, the document and printable copy behind gateway v0.14's `POST /v1/invoices/:number/credit-notes`.

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMem
 export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
 export { deadlinesDue, filingPack, type OccurrenceFacts, type OccurrenceFramework, type OccurrenceReport, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.ts";
 export { ingestOcsf, type OcsfEvent, type OcsfVersion, ocsfLine, toOcsf } from "./ocsf/index.ts";
-export { toOtlp } from "./otlp/index.ts";
+export { fromOtlp, type OtlpEvent, toOtlp } from "./otlp/index.ts";
 export { checkIdentifier, checkPack, corePack, type PackEntry, packData, packFrameworks, } from "./packs/index.ts";
 export { type PolicyChange, type PolicyDelta, policyDelta } from "./policy/delta.ts";
 export { type Draft, type DraftGroup, policyDrafts } from "./policy/drafts.ts";

package/dist/index.js

@@ -44,7 +44,7 @@ export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMem
 export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
 export { deadlinesDue, filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
-export { toOtlp } from "./otlp/index.js";
+export { fromOtlp, toOtlp } from "./otlp/index.js";
 export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";

package/dist/otlp/index.d.ts

@@ -28,4 +28,21 @@ export declare function toOtlp(lines: readonly string[], options?: {
         }[];
     }[];
 };
+/** One event for `POST /v1/sessions/:id/sdk-events`, numbered by the server (spec/sdk.md §1). */
+export interface OtlpEvent {
+    event_id: string;
+    type: string;
+    name: string;
+    ts: string;
+    data: Record<string, unknown>;
+}
+/**
+ * spec/otlp.md §4: OTLP/JSON traces as session events: one per span, typed from its GenAI or
+ * OpenInference attributes, its event_id `otel:<trace>:<span>` so a resent span adds nothing.
+ */
+export declare function fromOtlp(body: unknown): {
+    events: OtlpEvent[];
+} | {
+    error: string;
+};
 export {};

package/dist/otlp/index.js

@@ -398,3 +398,122 @@ function toOtlpV2(lines) {
         ],
     };
 }
+const LLM_OPS = new Set(["chat", "text_completion", "generate_content", "embeddings"]);
+const MAX_SPANS = 5000;
+const MAX_DATA = 60_000;
+function anyValue(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    if (typeof v.stringValue === "string")
+        return v.stringValue;
+    if (typeof v.boolValue === "boolean")
+        return v.boolValue;
+    if (v.intValue !== undefined) {
+        const n = Number(v.intValue);
+        return Number.isSafeInteger(n) ? n : String(v.intValue);
+    }
+    if (typeof v.doubleValue === "number")
+        return v.doubleValue;
+    if (v.arrayValue)
+        return (v.arrayValue.values ?? []).map(anyValue);
+    if (v.kvlistValue)
+        return attributes(v.kvlistValue.values);
+    return null;
+}
+function attributes(list) {
+    const out = {};
+    if (!Array.isArray(list))
+        return out;
+    for (const kv of list)
+        if (typeof kv?.key === "string")
+            out[kv.key] = anyValue(kv.value);
+    return out;
+}
+/** The event type for a span, from GenAI semconv and OpenInference attributes. */
+function spanType(a) {
+    const op = a["gen_ai.operation.name"];
+    const kind = a["openinference.span.kind"];
+    if ((typeof op === "string" && LLM_OPS.has(op)) || kind === "LLM" || kind === "EMBEDDING")
+        return "llm.call";
+    if (op === "execute_tool" || kind === "TOOL")
+        return "tool.call";
+    if (kind === "RETRIEVER")
+        return "retrieval";
+    if (op === "invoke_agent" || op === "create_agent" || kind === "AGENT" || kind === "CHAIN")
+        return "step";
+    return "otel.span";
+}
+const isoOfNanos = (n) => {
+    const s = typeof n === "string" || typeof n === "number" ? String(n) : "";
+    if (!/^[0-9]{1,20}$/.test(s))
+        return "";
+    return new Date(Number(BigInt(s) / 1000000n)).toISOString();
+};
+const size = (o) => new TextEncoder().encode(JSON.stringify(o)).length;
+/**
+ * spec/otlp.md §4: OTLP/JSON traces as session events: one per span, typed from its GenAI or
+ * OpenInference attributes, its event_id `otel:<trace>:<span>` so a resent span adds nothing.
+ */
+export function fromOtlp(body) {
+    const rs = body?.resourceSpans;
+    if (!body || typeof body !== "object" || !Array.isArray(rs))
+        return { error: "not OTLP/JSON traces (no resourceSpans)" };
+    const events = [];
+    for (const r of rs) {
+        const service = attributes(r?.resource?.attributes)["service.name"];
+        const scopes = Array.isArray(r?.scopeSpans) ? r.scopeSpans : [];
+        for (const ss of scopes) {
+            const spans = Array.isArray(ss?.spans) ? ss.spans : [];
+            for (const sp of spans) {
+                const trace = sp?.traceId;
+                const span = sp?.spanId;
+                if (typeof trace !== "string" || !/^[0-9a-f]{32}$/i.test(trace))
+                    return { error: "a span without a 32-hex traceId" };
+                if (typeof span !== "string" || !/^[0-9a-f]{16}$/i.test(span))
+                    return { error: "a span without a 16-hex spanId" };
+                if (events.length === MAX_SPANS)
+                    return { error: `more than ${MAX_SPANS} spans` };
+                const attrs = attributes(sp.attributes);
+                const status = sp.status;
+                const data = {
+                    source: "otlp",
+                    ...(typeof service === "string" ? { service } : {}),
+                    scope: {
+                        name: typeof ss?.scope?.name === "string" ? ss.scope.name : "",
+                        ...(typeof ss?.scope?.version === "string" ? { version: ss.scope.version } : {}),
+                    },
+                    trace_id: trace.toLowerCase(),
+                    span_id: span.toLowerCase(),
+                    ...(typeof sp.parentSpanId === "string" && sp.parentSpanId
+                        ? { parent_span_id: sp.parentSpanId.toLowerCase() }
+                        : {}),
+                    kind: typeof sp.kind === "number" ? sp.kind : 0,
+                    start_unix_nano: String(sp.startTimeUnixNano ?? ""),
+                    end_unix_nano: String(sp.endTimeUnixNano ?? ""),
+                    ...(status && typeof status.code === "number" && status.code !== 0
+                        ? {
+                            status: {
+                                code: status.code,
+                                ...(typeof status.message === "string" ? { message: status.message } : {}),
+                            },
+                        }
+                        : {}),
+                    attributes: attrs,
+                };
+                if (size(data) > MAX_DATA) {
+                    // keep the small attributes (ids, models, counts), drop the long ones (prompts, outputs)
+                    data.attributes = Object.fromEntries(Object.entries(attrs).filter(([, v]) => size(v) <= 1000));
+                    data.truncated = true;
+                }
+                events.push({
+                    event_id: `otel:${trace.toLowerCase()}:${span.toLowerCase()}`,
+                    type: spanType(attrs),
+                    name: typeof sp.name === "string" ? sp.name.slice(0, 256) : "span",
+                    ts: isoOfNanos(sp.startTimeUnixNano),
+                    data,
+                });
+            }
+        }
+    }
+    return { events };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.12.0";
+export declare const VERSION = "0.13.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.12.0";
+export const VERSION = "0.13.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",