@hue-run/sdk 0.21.1 → 0.22.0

package/dist/cli/import-formats/rows.d.ts

@@ -0,0 +1,165 @@
+import { type ConvertedTrace, type JsonValue, type Refusal } from "../traces-import-convert.js";
+import type { ConvertContext, Location, TraceCollector } from "./adapter.js";
+import { type IdentityKeys } from "./identity.js";
+/**
+ * The canonical span row every row format maps its records to, and the one emitter that turns a
+ * trace's rows into the OTLP spans Hue reads: the GenAI conventions for the operation, model,
+ * messages, tool call and usage, the end user and conversation on the trace's root, and the
+ * source record whole beside them. Nothing else writes spans for a row format.
+ */
+/** What a span did, as the GenAI conventions name it (`gen_ai.operation.name`). A span of none of
+ * these (a task, a chain, a scorer) records no operation. */
+export type SpanKind = "agent" | "llm" | "tool" | "embedding" | "retrieval";
+export interface SpanRow {
+    /** The source's trace id. Kept when it is 32 hex digits, otherwise mapped by SHA-256 with the
+     * original kept as `hue.import.original_trace_id`. */
+    traceKey: string;
+    /** The source's span id: kept when it is 16 hex digits, otherwise mapped likewise. */
+    spanKey: string;
+    /** The parent's span id in the source. A parent the export does not hold leaves the span a
+     * root of the trace, with the original kept as `hue.import.original_parent_span_id`. */
+    parentKey?: string;
+    /** Further parents, emitted as span links. */
+    linkKeys?: string[];
+    /** Links the source records to a span of this trace or of another, by that trace's and span's
+     * keys as recorded, mapped to OpenTelemetry ids as their own spans' are. */
+    links?: {
+        traceKey: string;
+        spanKey: string;
+        attributes?: Record<string, JsonValue>;
+    }[];
+    name: string;
+    kind?: SpanKind;
+    /** `gen_ai.operation.name` when the kind's is not the source's. */
+    operation?: string;
+    /** Recorded instants, in Unix nanoseconds (see {@link nanosFrom}). A missing one is inferred by
+     * the documented rule and named in `hue.import.timing`. */
+    start?: bigint;
+    end?: bigint;
+    /** How the adapter took a recorded instant from another field, such as `start_from_created`;
+     * several rules are separated by `; `. */
+    timing?: string;
+    model?: string;
+    responseModel?: string;
+    provider?: string;
+    agentName?: string;
+    /** Content as recorded: chat messages in any common shape become `gen_ai.input.messages` and
+     * `gen_ai.output.messages`; anything else is kept as `input.value` and `output.value`. */
+    input?: JsonValue;
+    output?: JsonValue;
+    systemInstructions?: JsonValue;
+    /** A tool call's own fields; `arguments` and `result` default to `input` and `output`. */
+    tool?: {
+        name?: string;
+        callId?: string;
+        type?: string;
+        arguments?: JsonValue;
+        result?: JsonValue;
+    };
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        reasoning?: number;
+    };
+    error?: {
+        message?: string;
+        type?: string;
+    };
+    /** The end user and conversation the record names. Never taken from a tool row: a tool's
+     * arguments and result may name the account it acted on, never who asked. */
+    user?: string;
+    session?: string;
+    /** Evaluation or simulation traffic, which Hue keeps out of production history. */
+    origin?: "evaluation" | "simulation";
+    /** The vendor's own evaluation recorded inside the trace (a scorer, a judge, an automation):
+     * this row and every row beneath it are emitted without a GenAI operation, model, messages,
+     * tool call, usage or identity attribute, their content kept as `input.value`/`output.value`,
+     * and never name the trace's user or conversation, as a tool's subtree never does. */
+    scoring?: boolean;
+    /** The deployment environment the source recorded (`deployment.environment.name`). */
+    environment?: string;
+    /** The format's own attributes, under its own names (never `hue.import.*`). */
+    attributes?: Record<string, JsonValue>;
+    resource?: Record<string, JsonValue>;
+    /** The whole source record, kept as `hue.import.source_record`. */
+    record: JsonValue;
+    /** Where a dotted `--user-key` or `--session-key` looks after the span's attributes. */
+    metadata?: JsonValue;
+    /** A revision of a record exported more than once: the highest is kept. Decimal digits compare
+     * as numbers. Without one, copies of a span must agree. */
+    revision?: string;
+    /** The record's position in its source, used to order an untimed trace. */
+    sequence?: number;
+}
+/** A point in time on a span (a log line, a message): a span event. */
+export interface EventRow {
+    traceKey: string;
+    spanKey: string;
+    name: string;
+    time?: bigint;
+    attributes?: Record<string, JsonValue>;
+    record: JsonValue;
+}
+declare const UNITS: {
+    readonly s: 9;
+    readonly ms: 6;
+    readonly us: 3;
+    readonly ns: 0;
+};
+/** A timestamp in `unit` (a number or its decimal text, exponent allowed) as Unix nanoseconds,
+ * read from its decimal digits so no float rounding is added. */
+export declare function nanosFrom(value: unknown, unit: keyof typeof UNITS): bigint;
+/** Reads each record with `read`: a record that throws a ConversionError (or is too deep or
+ * large to walk) refuses the trace `traceKeyOf` names (or is reported alone), never the rest of
+ * the value. */
+export declare function readRecords<T>(context: ConvertContext, records: readonly T[], traceKeyOf: (record: T) => string | undefined, read: (record: T) => void): void;
+/** The OpenTelemetry trace id of a row format's trace: its own id when it is one, otherwise one
+ * derived from the format and the id by SHA-256. */
+export declare const rowTraceId: (format: string, traceKey: string) => string;
+/** Gathers one row format's rows by trace across files and lines, and emits each trace. */
+export declare class RowTraceCollector implements TraceCollector {
+    private readonly format;
+    private readonly keys;
+    private readonly traces;
+    constructor(format: string, keys?: IdentityKeys);
+    private draft;
+    /**
+     * Adds a row read at `at`. Returns where an identical copy of the record was read before, when
+     * one was read somewhere else: the record is then read once, and the caller may say so.
+     */
+    add(row: SpanRow, sourceDigest: string, at?: Location): Location | undefined;
+    /**
+     * Adds an event. `repeats` counts, for one source value, the identical records it gave each span
+     * so far: an event the value repeats on a span is kept each time, the same value read again (a
+     * file read twice) adds nothing.
+     */
+    addEvent(event: EventRow, sourceDigest: string, repeats?: Map<string, number>): void;
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+    private emit;
+}
+/** Whether the parents of a trace's rows close on themselves anywhere; each row's ancestry is
+ * walked once, so the check takes time in proportion to the rows. */
+export declare function cyclic(rows: ReadonlyMap<string, SpanRow>, parentOf: (row: SpanRow) => string | undefined): boolean;
+/**
+ * Every span's start and end, the recorded ones kept and the rest inferred by these rules, each
+ * named in the span's `hue.import.timing` and the report:
+ * - `start_at_end`: no start but an end: the span starts at its end;
+ * - `start_from_parent`: no instant at all: the span starts with its parent;
+ * - `start_from_trace`: nor has its parent: it starts with the trace's earliest recorded instant;
+ * - `untimed_trace`: the trace records no instant: spans are placed at 2000-01-01T00:00:00Z, a
+ *   millisecond apart in source order;
+ * - `end_from_children` / `end_at_start`: no end: the span ends with its last child, else at its
+ *   start.
+ * A recorded end before its start refuses the trace.
+ */
+export declare function timesOf(rows: ReadonlyMap<string, SpanRow>, parentOf: (row: SpanRow) => string | undefined): {
+    starts: Map<string, bigint>;
+    ends: Map<string, bigint>;
+    notes: Map<string, string[]>;
+};
+export {};