@hue-run/sdk 0.20.1 → 0.20.3

package/dist/cli/traces-import-convert.d.ts

@@ -0,0 +1,262 @@
+/**
+ * The conversions behind `hue traces import prepare`: a source file is recognized by its content
+ * (an OTLP/JSON trace export, a complete Langfuse observation export or a text ATIF export),
+ * each trace becomes OTLP/JSON entries, one span each, that keep the recorded ids, hierarchy,
+ * timestamps, content, errors and usage, and the entries are packed into deterministic gzip
+ * batches. Nothing here depends on where a file sat or what it was called: a renamed or repacked
+ * bundle converts to byte-identical batches, so the manifest's digests name the same import.
+ */
+export declare const traceImportFormats: readonly ["otlp_json", "langfuse_observations", "atif"];
+export type TraceImportFormat = (typeof traceImportFormats)[number];
+export declare const traceImportOrigins: readonly ["production", "evaluation", "simulation", "unknown"];
+export type TraceImportOrigin = (typeof traceImportOrigins)[number];
+/** The bounds the import routes hold a manifest to. */
+export declare const traceImportLimits: {
+    readonly traces: 10000;
+    readonly batchesPerTrace: 64;
+    readonly blobsPerTrace: 1000;
+    readonly spansPerTrace: 100000;
+    readonly manifestBytes: number;
+    readonly batchBytes: number;
+    readonly blobBytes: 1000000000;
+};
+/** One batch, decoded, and on the wire: well inside the receiver's request bounds. */
+export declare const MAX_BATCH_DECODED_BYTES: number;
+export declare const MAX_BATCH_WIRE_BYTES: number;
+/** The largest value a record keeps inline; a longer text is stored apart from its span. */
+export declare const MAX_INLINE_VALUE_BYTES: number;
+export declare const SOURCE_RECORD = "hue.import.source_record";
+export declare const SOURCE_ENVELOPE = "hue.import.source_envelope";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface OtlpValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string;
+    doubleValue?: number;
+    arrayValue?: {
+        values: OtlpValue[];
+    };
+    kvlistValue?: {
+        values: OtlpAttribute[];
+    };
+    bytesValue?: string;
+}
+export interface OtlpAttribute {
+    key: string;
+    value: OtlpValue;
+}
+export type ImportSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+    status: {
+        code: number;
+        message?: string;
+    };
+};
+/** One resource group holding one scope group holding one span: the unit the packer serializes.
+ * A converted span is an {@link ImportSpan}; an OTLP/JSON span is kept as recorded. */
+export interface ImportEntry {
+    [key: string]: unknown;
+    scopeSpans: {
+        [key: string]: unknown;
+        spans: Record<string, unknown>[];
+    }[];
+}
+export interface TraceIdentity {
+    user?: string;
+    entity?: {
+        namespace: string;
+        id: string;
+    };
+    session?: string;
+}
+export interface PreparedBlob {
+    sha256: string;
+    byteSize: number;
+    contentType: string;
+    bytes: Uint8Array;
+}
+export interface ConvertedTrace {
+    traceId: string;
+    format: TraceImportFormat;
+    entries: ImportEntry[];
+    blobs: PreparedBlob[];
+    identity?: TraceIdentity;
+    origin: TraceImportOrigin;
+    /** The SHA-256 of every source file that held part of the trace. */
+    sourceDigests: Set<string>;
+    remappedTraceId: boolean;
+    remappedSpans: number;
+}
+/** A trace, span or file that was not converted, and why. */
+export interface Refusal {
+    traceId?: string;
+    reason: string;
+}
+export declare class ConversionError extends Error {
+}
+export declare const sha256Hex: (value: string | Uint8Array) => string;
+/**
+ * JSON text parsed with every integer too large for a JavaScript number kept as its decimal
+ * text, so an OTLP timestamp written as a number keeps its nanoseconds. `unsafeIntegers` says
+ * whether any was found; the Langfuse and ATIF readers refuse such a file, as Hue's do.
+ */
+export declare function parseJsonText(text: string): {
+    value: unknown;
+    unsafeIntegers: boolean;
+};
+/** Refuses a source value that JavaScript or OTLP cannot retain exactly; never omits it. */
+export declare function validateSource(value: JsonValue, depth?: number): void;
+/** JSON.parse otherwise loses duplicate members and can round decimal argument values. */
+export declare function validateJsonText(raw: string): void;
+export type DetectedSource = {
+    format: "otlp_json";
+    envelopes: Record<string, unknown>[];
+} | {
+    format: "langfuse_observations";
+    observations: Record<string, JsonValue>[];
+    envelope: Record<string, JsonValue>;
+    unsafeIntegers: boolean;
+} | {
+    format: "atif";
+    text: string;
+    document: unknown;
+    unsafeIntegers: boolean;
+} | {
+    format: "unsupported";
+    reason: string;
+};
+/** What a file holds, read from its content alone; never from its name. */
+export declare function detectFormat(bytes: Uint8Array): DetectedSource;
+export declare function anyValue(value: JsonValue): OtlpValue;
+/** The large values one trace stores apart from its spans, each once by digest. */
+export declare class BlobSink {
+    readonly blobs: Map<string, PreparedBlob>;
+    /** Stores a text whole and returns what its record keeps: the first 16 KiB and the `hue.blobs`
+     * entry; undefined when the text is over the limit of one stored value. */
+    place(key: string, text: string): {
+        prefix: string;
+        entry: string;
+    } | undefined;
+    /** The values in digest order: the manifest lists a trace's values the same whatever order its
+     * sources were read in, so renaming or repacking them keeps the manifest digest. */
+    sorted(): PreparedBlob[];
+}
+/** A converted span's attributes: a value over the inline limit is stored apart from the span
+ * through the trace's {@link BlobSink} and listed in `hue.blobs`, as the SDK's exporter lists
+ * the values it uploads, with the key in `hue.truncated`. */
+export declare class AttributeList {
+    private readonly blobs;
+    readonly values: OtlpAttribute[];
+    private readonly listed;
+    private readonly truncated;
+    constructor(blobs: BlobSink);
+    add(key: string, value: JsonValue): void;
+    json(key: string, value: unknown): void;
+    finish(): OtlpAttribute[];
+}
+/** Gathers the spans of OTLP/JSON exports by trace, across files: an export writes a trace's
+ * spans in the requests that carried them, which need not be one file. */
+export declare class OtlpTraceCollector {
+    private readonly traces;
+    /** Adds every span of the envelopes; the spans refused, with their reasons. */
+    add(envelopes: readonly Record<string, unknown>[], sourceDigest: string): Refusal[];
+    private addSpan;
+    /** Every trace gathered so far, spans in time order, and the traces refused whole. */
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+}
+export declare function unixNano(value: JsonValue | undefined): string;
+/** Gathers Langfuse observations by trace across files and converts each trace as Hue's reader
+ * converts an observation export: one span per observation, the record kept whole. */
+export declare class LangfuseTraceCollector {
+    private readonly traces;
+    add(observations: readonly Record<string, JsonValue>[], envelope: Record<string, JsonValue>, sourceDigest: string): void;
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+}
+/** The ATIF reader's bounds: a text export of at most 4 MiB and 2,000 spans. */
+export declare const MAX_ATIF_FILE_BYTES: number;
+export declare const MAX_ATIF_SPANS = 2000;
+/** Retains nanoseconds and requires an explicit timezone, valid calendar date and OTLP uint64. */
+export declare function atifUnixNano(value: string): string;
+/**
+ * A text ATIF v1.7 or v1.8 export as one trace: an agent span for the run, a model span per
+ * agent step with the conversation so far, a tool span per call under it, and an embedded
+ * subagent trajectory as its own agent span under the tool span of the call that spawned it.
+ * Identity is run scoped (`session_id` and `trajectory_id`), never a path. The complete original
+ * document stays on the root; each model and tool span keeps its own record. ATIF supplies step
+ * instants, not call durations: model and tool spans are zero-duration point spans.
+ */
+export declare function convertAtifExport(source: Extract<DetectedSource, {
+    format: "atif";
+}>, rawBytes: number): ConvertedTrace;
+export interface PreparedBatch {
+    sha256: string;
+    body: Uint8Array;
+    decodedBytes: number;
+    spanIds: string[];
+}
+/** `Math.floor(numerator / divisor)` for safe nonnegative integers, without a division: the
+ * published package's import-boundary check reads a `/` after a name as a regular expression, so
+ * the quotient is estimated from the reciprocal and corrected by whole steps, which makes it
+ * exact on every engine. */
+export declare function integerQuotient(numerator: number, divisor: number): number;
+/**
+ * The trace's entries packed into gzip OTLP/JSON batches in order, each at most 3 MiB decoded
+ * and 900 KiB on the wire. Packing is linear and the output depends on the entries alone, so the
+ * same trace packs to the same batches whatever bundle it came from.
+ */
+export declare function batchEntries(entries: readonly ImportEntry[]): PreparedBatch[];
+export interface ManifestTrace {
+    trace_id: string;
+    span_count: number;
+    batches: {
+        sha256: string;
+        bytes: number;
+        span_count: number;
+    }[];
+    blobs: {
+        sha256: string;
+        byte_size: number;
+        content_type: string;
+    }[];
+    identity?: TraceIdentity;
+    origin: TraceImportOrigin;
+    source_digest?: string;
+}
+export interface TraceImportManifest {
+    version: 1;
+    source: {
+        formats: TraceImportFormat[];
+        helper: string;
+        helper_version?: string;
+    };
+    traces: ManifestTrace[];
+}
+export interface TraceImportTotals {
+    traces: number;
+    batches: number;
+    spans: number;
+    blobs: number;
+    bytes: number;
+}
+/** The totals a manifest adds up to, as Hue computes them. */
+export declare function manifestTotals(manifest: TraceImportManifest): TraceImportTotals;
+export declare function manifestTraceHasIdentity(trace: Pick<ManifestTrace, "identity">): boolean;
+/** A manifest's problem, or undefined: the shape and cross-checks Hue's registration applies
+ * (every trace id once, every batch digest once, each trace's batches adding up to its span
+ * count, each trace's values distinct) so a bundle is refused here, before any upload. */
+export declare function validateManifest(value: unknown): string | undefined;