@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/observability/spans.js

@@ -0,0 +1,72 @@
+const OMIT_INJECTION = '[omitted - injection]';
+const OMIT_SENSITIVE = '[omitted -sensitive]';
+const OMIT_CANARY = '[omitted - canary]';
+const OMIT_PROMPT = '[omitted - instructions]';
+const OMIT_IMAGE = '[omitted - image]';
+const OMIT_LINK = '[omitted - link]';
+const OMIT_TOOL = '[omitted - tool]';
+const OMIT_DIRECTIVE = '[omitted - directive]';
+/** A match of a detector of the host's own: it says nothing of what was there. */
+const OMIT_HOST = '[omitted]';
+const OMIT = {
+    injection: OMIT_INJECTION,
+    sensitive: OMIT_SENSITIVE,
+    canary: OMIT_CANARY,
+    prompt: OMIT_PROMPT,
+    image: OMIT_IMAGE,
+    link: OMIT_LINK,
+    tool: OMIT_TOOL,
+    directive: OMIT_DIRECTIVE,
+    host: OMIT_HOST,
+};
+function tokenFor(kind) {
+    return OMIT[kind];
+}
+function blobAt(match) {
+    const [blob] = match;
+    const { index } = match;
+    if (blob && index !== undefined) {
+        return { blob, index };
+    }
+    return undefined;
+}
+function mergeSpans(spans) {
+    const sorted = [...spans].sort((left, right) => left.start - right.start || right.end - left.end);
+    const out = [];
+    for (const span of sorted) {
+        if (span.end > span.start) {
+            const last = out.at(-1);
+            if (!last || span.start >= last.end) {
+                out.push(span);
+            }
+            else if (span.end > last.end) {
+                last.end = span.end;
+            }
+        }
+    }
+    return out;
+}
+function applySpans(text, spans) {
+    let out = text;
+    const merged = mergeSpans(spans);
+    for (let i = merged.length - 1; i >= 0; i -= 1) {
+        const span = merged[i];
+        if (span) {
+            out = out.slice(0, span.start) + tokenFor(span.kind) + out.slice(span.end);
+        }
+    }
+    return out;
+}
+function spansFromPatterns(text, patterns, kind) {
+    const spans = [];
+    for (const pattern of patterns) {
+        for (const match of text.matchAll(pattern)) {
+            const found = blobAt(match);
+            if (found) {
+                spans.push({ start: found.index, end: found.index + found.blob.length, kind });
+            }
+        }
+    }
+    return spans;
+}
+export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns, };

package/esm/src/observability/trace-catalog.d.ts

@@ -0,0 +1,128 @@
+import type { TraceSpan } from './trace-span.js';
+/** How a value reads: the unit or shape a viewer formats it by. */
+type TraceValueFormat = 'text'
+/** An identifier: shown as is, in monospace. */
+ | 'id' | 'number' | 'tokens' | 'seconds' | 'milliseconds' | 'usd' | 'boolean'
+/** A list of strings. */
+ | 'list' | 'object'
+/** A `{ content_sha256 }` reference to text in the record's `content`. */
+ | 'content'
+/** A `{ json_sha256 }` reference to JSON in the record's `content`. */
+ | 'json'
+/** Semconv chat messages whose parts reference `content`. */
+ | 'messages'
+/** Semconv message parts whose text references `content`. */
+ | 'parts'
+/** A unix-nanosecond timestamp string. */
+ | 'time';
+/** The groups the attribute catalog sorts attributes into. */
+type TraceAttributeGroup = 'agent' | 'request' | 'response' | 'messages' | 'usage' | 'tool' | 'http' | 'error' | 'record' | 'part' | 'decision' | 'evaluation';
+/** A label and description for one option in a catalog. */
+interface TraceOptionMeta {
+    label: string;
+    doc: string;
+}
+/** What the catalog says about a span attribute: its label, description, and format. */
+interface TraceAttributeMeta {
+    label: string;
+    doc: string;
+    format: TraceValueFormat;
+    group: TraceAttributeGroup;
+    options?: Readonly<Record<string, TraceOptionMeta>>;
+    /** The options name the common values only: another value is real and shows as is. */
+    open?: true;
+    /** For an `object`: what its keys mean (for a list of objects, each item's keys). */
+    fields?: Readonly<Record<string, TraceAttributeMeta>>;
+}
+/** What the catalog says about a span event: its label, description, and keys. */
+interface TraceEventMeta {
+    label: string;
+    doc: string;
+    /** Keys this event carries. A key missing here reads from the span attribute catalog. */
+    attributes: Readonly<Record<string, TraceAttributeMeta>>;
+}
+/** The kinds of span THEOREM writes, plus `host` for a span the host recorded itself. */
+type TraceSpanType = 'turn' | 'session' | 'call' | 'response' | 'tool' | 'http' | 'cutout' | 'decision' | 'evaluation' | 'host';
+/** `subject` is the thing the span acted on (the model, tool, or agent), when it names one. */
+interface TraceSpanMeta {
+    type: TraceSpanType;
+    label: string;
+    doc: string;
+    subject?: string;
+}
+/** Labels and descriptions for each attribute group. */
+declare const TRACE_ATTRIBUTE_GROUPS: Readonly<Record<TraceAttributeGroup, TraceOptionMeta>>;
+/** Labels and descriptions for each span status. */
+declare const TRACE_STATUS: Readonly<Record<TraceSpan['status']['code'], TraceOptionMeta>>;
+/** A record's and a span's own fields, beside their attributes. */
+declare const TRACE_FIELDS: {
+    resource: {
+        label: string;
+        doc: string;
+    };
+    metadata: {
+        label: string;
+        doc: string;
+    };
+    span: {
+        label: string;
+        doc: string;
+    };
+    type: {
+        label: string;
+        doc: string;
+    };
+    children: {
+        label: string;
+        doc: string;
+    };
+    traceId: {
+        label: string;
+        doc: string;
+    };
+    spanId: {
+        label: string;
+        doc: string;
+    };
+    status: {
+        label: string;
+        doc: string;
+    };
+    start: {
+        label: string;
+        doc: string;
+    };
+    duration: {
+        label: string;
+        doc: string;
+    };
+    events: {
+        label: string;
+        doc: string;
+    };
+    links: {
+        label: string;
+        doc: string;
+    };
+};
+/** What an attribute key means; `undefined` for a key THEOREM does not write. */
+declare function traceAttributeMeta(key: string): TraceAttributeMeta | undefined;
+/** What an event records; `undefined` for an event THEOREM does not write. */
+declare function traceEventMeta(name: string): TraceEventMeta | undefined;
+/** The event's own entry, else the span attribute of that key. */
+declare function traceEventAttributeMeta(event: string, key: string): TraceAttributeMeta | undefined;
+/** Labels and descriptions for each span type. */
+declare const TRACE_SPAN_TYPES: Readonly<Record<TraceSpanType, TraceOptionMeta>>;
+/**
+ * Every trace field and span type, named by the record they belong to: `trace.resource`, and a
+ * span type by the field it fills, `trace.type.turn`.
+ */
+declare function traceCatalogRows(): readonly {
+    name: string;
+    label: string;
+    doc: string;
+}[];
+/** The label, subject, and description to show for a span. */
+declare function traceSpanMeta(span: TraceSpan): TraceSpanMeta;
+export type { TraceAttributeGroup, TraceAttributeMeta, TraceEventMeta, TraceOptionMeta, TraceSpanMeta, TraceSpanType, TraceValueFormat, };
+export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceCatalogRows, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, };