@hue-run/sdk 0.21.0 → 0.22.0

package/dist/cli/import-formats/phoenix.js

@@ -0,0 +1,256 @@
+import { anyValue, ConversionError, isObject, unixNano, } from "../traces-import-convert.js";
+import { otelTraceKey, OtelSpanCollector, unsigned } from "./otel-spans.js";
+import { readRecords } from "./rows.js";
+const object = (value) => isObject(value) ? value : undefined;
+const text = (value) => typeof value === "string" && value ? value : undefined;
+/** A page's records, or the value itself when it is one record. */
+function recordsOf(value, isRecord) {
+    if (isRecord(value))
+        return [value];
+    const page = object(value);
+    return page && Array.isArray(page.data) && page.data.some(isRecord) ? page.data : undefined;
+}
+/** An OTLP id as hex: hex as recorded, or the base64 the OTLP JSON mapping allows; any other
+ * text is kept and mapped by SHA-256. */
+function hexId(value, bytes) {
+    if (new RegExp(`^[0-9a-f]{${bytes * 2}}$`, "i").test(value))
+        return value.toLowerCase();
+    if (/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+        const decoded = Buffer.from(value, "base64");
+        if (decoded.byteLength === bytes && decoded.toString("base64") === value)
+            return decoded.toString("hex");
+    }
+    return value;
+}
+/** A nanosecond instant: absent when null, refused when malformed or zero. */
+function nanos(value, what) {
+    if (value === undefined || value === null)
+        return undefined;
+    const count = unsigned(value);
+    if (!count)
+        throw new ConversionError(`${what} is not a nanosecond instant`);
+    return count;
+}
+const KINDS = {
+    SPAN_KIND_UNSPECIFIED: 0,
+    SPAN_KIND_INTERNAL: 1,
+    SPAN_KIND_SERVER: 2,
+    SPAN_KIND_CLIENT: 3,
+    SPAN_KIND_PRODUCER: 4,
+    SPAN_KIND_CONSUMER: 5,
+};
+const STATUS = { UNSET: 0, OK: 1, ERROR: 2 };
+/** An `OtlpAnyValue` in proto field names as OTLP/JSON. A dictionary, which Phoenix writes as an
+ * empty value, stays empty. */
+function anyValueOf(raw) {
+    const value = object(raw);
+    if (raw === undefined || raw === null)
+        return {};
+    if (!value)
+        throw new ConversionError("an attribute value that is not an object");
+    if (typeof value.string_value === "string")
+        return { stringValue: value.string_value };
+    if (typeof value.bool_value === "boolean")
+        return { boolValue: value.bool_value };
+    if (value.int_value !== undefined && value.int_value !== null) {
+        const integer = value.int_value;
+        if (typeof integer === "number" && Number.isSafeInteger(integer))
+            return { intValue: String(integer) };
+        if (typeof integer === "string" && /^-?\d+$/.test(integer))
+            return { intValue: integer };
+        throw new ConversionError("an int_value that is not an integer");
+    }
+    if (typeof value.double_value === "number")
+        return { doubleValue: value.double_value };
+    if (typeof value.double_value === "string") {
+        // An infinite or undefined double, which Phoenix writes as Python prints it, is kept as its
+        // text: OTLP/JSON has no number for it.
+        if (!/^-?(?:inf|infinity|nan)$/i.test(value.double_value))
+            throw new ConversionError("a double_value that is not a number");
+        return { stringValue: value.double_value };
+    }
+    if (typeof value.bytes_value === "string")
+        return { bytesValue: value.bytes_value };
+    const array = object(value.array_value);
+    if (array) {
+        const values = array.values ?? [];
+        if (!Array.isArray(values))
+            throw new ConversionError("an array_value without values");
+        return { arrayValue: { values: values.map(anyValueOf) } };
+    }
+    return {};
+}
+function keyValues(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new ConversionError("attributes is not a list");
+    return raw.map((item) => {
+        const pair = object(item);
+        if (!pair || typeof pair.key !== "string")
+            throw new ConversionError("an attribute without a key");
+        return { key: pair.key, value: anyValueOf(pair.value) };
+    });
+}
+const isOtlpSpan = (value) => isObject(value) &&
+    typeof value.trace_id === "string" &&
+    typeof value.span_id === "string" &&
+    ("start_time_unix_nano" in value || "end_time_unix_nano" in value) &&
+    !("context" in value) &&
+    !("root_span_id" in value);
+function readOtlpSpan(span) {
+    const { trace_id: rawTraceId, span_id: rawSpanId } = span;
+    if (!isOtlpSpan(span) || typeof rawTraceId !== "string" || typeof rawSpanId !== "string")
+        throw new ConversionError("a record that is not a Phoenix OTLP span");
+    const traceId = hexId(rawTraceId, 16);
+    const parent = text(span.parent_span_id);
+    const kind = span.kind;
+    const status = object(span.status);
+    const code = status?.code;
+    const message = text(status?.message);
+    const start = nanos(span.start_time_unix_nano, "start_time_unix_nano");
+    const end = nanos(span.end_time_unix_nano, "end_time_unix_nano");
+    const events = span.events ?? [];
+    if (!Array.isArray(events))
+        throw new ConversionError("events is not a list");
+    const flags = unsigned(span.flags);
+    const dropped = unsigned(span.dropped_attributes_count);
+    return {
+        traceId,
+        spanKey: hexId(rawSpanId, 8),
+        ...(parent ? { parentKey: hexId(parent, 8) } : {}),
+        name: text(span.name) ?? "",
+        kind: typeof kind === "number" && Number.isInteger(kind) && kind >= 0 && kind <= 5
+            ? kind
+            : typeof kind === "string"
+                ? (KINDS[kind] ?? 1)
+                : 1,
+        ...(text(span.trace_state) ? { traceState: text(span.trace_state) } : {}),
+        ...(flags !== undefined && flags <= 0xffffffffn ? { flags: Number(flags) } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        attributes: keyValues(span.attributes),
+        ...(dropped ? { droppedAttributesCount: Number(dropped) } : {}),
+        events: events.map((item) => {
+            const event = object(item);
+            if (!event)
+                throw new ConversionError("an event that is not an object");
+            const time = nanos(event.time_unix_nano, "an event time");
+            return {
+                name: text(event.name) ?? "",
+                ...(time ? { time } : {}),
+                attributes: keyValues(event.attributes),
+            };
+        }),
+        links: [],
+        ...(typeof code === "number" && code >= 0 && code <= 2
+            ? { status: { code, ...(message ? { message } : {}) } }
+            : {}),
+        resource: [],
+        record: span,
+    };
+}
+const isPhoenixSpan = (value) => {
+    const spanContext = object(object(value)?.context);
+    return (spanContext !== undefined &&
+        typeof spanContext.trace_id === "string" &&
+        typeof spanContext.span_id === "string" &&
+        isObject(value) &&
+        ("start_time" in value || "span_kind" in value));
+};
+/** A flattened attribute dictionary as OTLP attributes, the dotted keys kept. */
+function dictionary(raw, what) {
+    if (raw === undefined || raw === null)
+        return [];
+    const values = object(raw);
+    if (!values)
+        throw new ConversionError(`${what} is not an object`);
+    return Object.entries(values).map(([key, value]) => ({ key, value: anyValue(value) }));
+}
+const instant = (value, what) => {
+    if (value === undefined || value === null)
+        return undefined;
+    try {
+        return BigInt(unixNano(value));
+    }
+    catch {
+        throw new ConversionError(`${what} is not a timestamp with a zone`);
+    }
+};
+function readPhoenixSpan(span) {
+    const spanContext = object(span.context);
+    const rawTraceId = spanContext?.trace_id;
+    const rawSpanId = spanContext?.span_id;
+    if (!isPhoenixSpan(span) || typeof rawTraceId !== "string" || typeof rawSpanId !== "string")
+        throw new ConversionError("a record that is not a Phoenix span");
+    const traceId = hexId(rawTraceId, 16);
+    const parent = text(span.parent_id);
+    const attributes = dictionary(span.attributes, "attributes");
+    const kind = text(span.span_kind);
+    if (kind &&
+        kind !== "UNKNOWN" &&
+        !attributes.some((item) => item.key === "openinference.span.kind"))
+        attributes.unshift({ key: "openinference.span.kind", value: { stringValue: kind } });
+    const code = text(span.status_code);
+    const message = text(span.status_message);
+    const start = instant(span.start_time, "start_time");
+    const end = instant(span.end_time, "end_time");
+    const events = span.events ?? [];
+    if (!Array.isArray(events))
+        throw new ConversionError("events is not a list");
+    return {
+        traceId,
+        spanKey: hexId(rawSpanId, 8),
+        ...(parent ? { parentKey: hexId(parent, 8) } : {}),
+        name: text(span.name) ?? "",
+        kind: 1,
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        attributes,
+        events: events.map((item) => {
+            const event = object(item);
+            if (!event)
+                throw new ConversionError("an event that is not an object");
+            const time = instant(event.timestamp, "an event timestamp");
+            return {
+                name: text(event.name) ?? "",
+                ...(time !== undefined ? { time } : {}),
+                attributes: dictionary(event.attributes, "event attributes"),
+            };
+        }),
+        links: [],
+        ...(code && code in STATUS
+            ? { status: { code: STATUS[code], ...(message ? { message } : {}) } }
+            : {}),
+        resource: [],
+        record: span,
+    };
+}
+function convertWith(format, records, isRecord, traceIdOf, read, context) {
+    const collector = context.collector(() => new OtelSpanCollector(format));
+    readRecords(context, records, (record) => {
+        const fields = object(record);
+        const traceId = fields ? traceIdOf(fields) : undefined;
+        return typeof traceId === "string" && traceId ? otelTraceKey(hexId(traceId, 16)) : undefined;
+    }, (record) => {
+        if (!isRecord(record))
+            throw new ConversionError(`a record that is not a ${format} span`);
+        collector.add(read(record), context.source.digest);
+    });
+}
+export const phoenixOtlp = {
+    id: "phoenix_otlp",
+    manifestFormat: "otlp_json",
+    detect: (value) => recordsOf(value, isOtlpSpan) !== undefined,
+    convert(value, context) {
+        convertWith("phoenix_otlp", recordsOf(value, isOtlpSpan) ?? [], isOtlpSpan, (record) => record.trace_id, readOtlpSpan, context);
+    },
+};
+export const phoenixSpans = {
+    id: "phoenix_spans",
+    manifestFormat: "otlp_json",
+    detect: (value) => recordsOf(value, isPhoenixSpan) !== undefined,
+    convert(value, context) {
+        convertWith("phoenix_spans", recordsOf(value, isPhoenixSpan) ?? [], isPhoenixSpan, (record) => object(record.context)?.trace_id, readPhoenixSpan, context);
+    },
+};

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

@@ -0,0 +1,21 @@
+import type { ImportAdapter } from "./adapter.js";
+export declare const raindrop: ImportAdapter;
+/**
+ * Raindrop's span rows: the Query API's `GET /v1/traces?event_id=` answer (`{"data": […]}`), one
+ * row alone, or one per line. Each row (`trace_id`, `span_id`, `parent_span_id`, `span_name`,
+ * `span_type`, `status`, `start_time_ns`, `end_time_ns`, `duration_ns`, `input`, `output`,
+ * `input_tokens`, `output_tokens`, `model`, `provider`, `attributes`) is one span of its trace; it
+ * carries the content, tool arguments and results, tokens and model an event record lacks.
+ *
+ * - `span_type` names the kind: `LLM_GENERATION` and `LLM_GENERATION_STREAM` a model call,
+ *   `TOOL_CALL` a tool call, `INTERNAL` none. A tool span's input and output are its arguments and
+ *   result; payload text holding JSON is read as that JSON.
+ * - Times are Unix nanoseconds; a row without `end_time_ns` ends `duration_ns` after it starts
+ *   (`end_from_duration`). `status` `ERROR` is an error.
+ * - `attributes` (text and numbers only, as Raindrop serves them) are kept under their own names.
+ *   The user and conversation are those Raindrop's SDKs stamp on every span of the interaction
+ *   (`traceloop.association.properties.user_id` and `convo_id`, `ai.telemetry.metadata.raindrop.*`),
+ *   read as Hue reads them; the rows name no event, so the event's own `user_id` is not joined in,
+ *   and `--user-key` names a user the attributes lack.
+ */
+export declare const raindropSpans: ImportAdapter;

package/dist/cli/import-formats/raindrop.js

@@ -0,0 +1,255 @@
+import { canonicalJson, ConversionError, isObject, parseNestedJsonText, sha256Hex, unixNano, } from "../traces-import-convert.js";
+import { identityText, readIdentity } from "./identity.js";
+import { nanosFrom, readRecords } from "./rows.js";
+const object = (value) => isObject(value) ? value : undefined;
+const text = (value) => typeof value === "string" && value ? value : undefined;
+/** An event as sent to the track endpoint. */
+const isTrackEvent = (value) => isObject(value) &&
+    typeof value.event === "string" &&
+    (isObject(value.ai_data) || (typeof value.event_id === "string" && "user_id" in value));
+/** An event as the Query API answers it. */
+const isQueryEvent = (value) => isObject(value) &&
+    typeof value.event_name === "string" &&
+    "user_input" in value &&
+    "assistant_output" in value;
+const isEvent = (value) => isObject(value) && (isTrackEvent(value) || isQueryEvent(value));
+/** The events a Query API answer holds: a page (`data` a list) or one event (`data` an event). */
+function envelopeEvents(value) {
+    if (!isObject(value))
+        return undefined;
+    if (isQueryEvent(value.data))
+        return [value.data];
+    return Array.isArray(value.data) && value.data.some(isQueryEvent) ? value.data : undefined;
+}
+const traceKeyOf = (record) => text(record.event_id) ?? text(record.id) ?? sha256Hex(canonicalJson(record));
+/** A recorded instant, or none. */
+const instant = (value) => text(value) ? BigInt(unixNano(value)) : undefined;
+/** A tool call's span: its name, call, timing and status as the event records them. */
+function toolRow(call, index, parent) {
+    const fields = object(call);
+    const name = text(fields?.name) ?? text(fields?.tool_name);
+    if (!fields || !name)
+        throw new ConversionError(`tool call ${index + 1} has no name`);
+    const start = instant(fields.started_at);
+    const duration = fields.duration_ms;
+    if (duration != null && (typeof duration !== "number" || !(duration >= 0)))
+        throw new ConversionError(`tool call ${index + 1} has an invalid duration_ms`);
+    const status = text(fields.status)?.toLowerCase();
+    const error = fields.error;
+    return {
+        traceKey: parent.traceKey,
+        spanKey: text(fields.span_id) ?? `tool_calls[${index}]`,
+        parentKey: parent.spanKey,
+        name,
+        kind: "tool",
+        ...(start !== undefined ? { start } : {}),
+        ...(start !== undefined && typeof duration === "number"
+            ? { end: start + (duration === 0 ? 0n : nanosFrom(duration, "ms")) }
+            : {}),
+        tool: {
+            name,
+            ...(text(fields.call_id) ? { callId: text(fields.call_id) } : {}),
+            ...(fields.arguments !== undefined ? { arguments: fields.arguments } : {}),
+            ...(fields.result !== undefined ? { result: fields.result } : {}),
+        },
+        ...((error !== undefined && error !== null && error !== "") || status === "error"
+            ? {
+                error: typeof error === "string" && error ? { message: error } : {},
+            }
+            : {}),
+        record: call,
+        sequence: index + 1,
+    };
+}
+function readEvent(record, context) {
+    const query = !isTrackEvent(record);
+    const ai = object(record.ai_data);
+    if (!query && record.ai_data != null && !ai)
+        throw new ConversionError("ai_data is not an object");
+    if (!query && !ai) {
+        // An analytics event: reported on its own, with no trace to refuse.
+        context.refuse("a Raindrop event without ai_data records no agent turn");
+        return;
+    }
+    const traceKey = traceKeyOf(record);
+    const spanKey = traceKey;
+    const calls = (query ? record.tool_calls : ai.tool_calls) ?? [];
+    if (!Array.isArray(calls))
+        throw new ConversionError("tool_calls is not a list");
+    const properties = object(record.properties);
+    const user = identityText(record.user_id);
+    const session = identityText(query ? record.convo_id : ai.convo_id);
+    const input = query ? record.user_input : ai.input;
+    const output = query ? record.assistant_output : ai.output;
+    const model = text(query ? record.model : ai.model);
+    const start = instant(record.timestamp);
+    const attributes = {};
+    const keep = (name, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (Array.isArray(value) ? value.length : isObject(value) ? Object.keys(value).length : true)
+            attributes[name] = typeof value === "object" ? JSON.stringify(value) : value;
+    };
+    keep("raindrop.properties", properties);
+    keep("raindrop.feature_flags", record.feature_flags);
+    keep("raindrop.attachments", record.attachments);
+    keep("raindrop.topics", record.topics);
+    keep("raindrop.signals", record.signals);
+    // A pending event (`is_pending`, sent before the turn finished) gives way to the finished one.
+    const revision = record.is_pending === true ? "0" : "1";
+    const event = {
+        traceKey,
+        spanKey,
+        name: text(query ? record.event_name : record.event) ?? "event",
+        kind: "agent",
+        ...(start !== undefined ? { start } : {}),
+        ...(model ? { model } : {}),
+        ...(input != null && input !== "" ? { input } : {}),
+        ...(output != null && output !== "" ? { output } : {}),
+        ...(user !== undefined ? { user } : {}),
+        ...(session !== undefined ? { session } : {}),
+        attributes,
+        record,
+        sequence: 0,
+    };
+    const rows = [event, ...calls.map((call, index) => toolRow(call, index, { traceKey, spanKey }))];
+    for (const row of rows)
+        context.row({ ...row, revision });
+}
+export const raindrop = {
+    id: "raindrop",
+    manifestFormat: "otlp_json",
+    detect: (value) => isEvent(value) || envelopeEvents(value) !== undefined,
+    convert(value, context) {
+        const records = isEvent(value) ? [value] : (envelopeEvents(value) ?? []);
+        readRecords(context, records, (record) => (isEvent(record) ? traceKeyOf(record) : undefined), (record) => {
+            if (!isEvent(record))
+                throw new ConversionError("a record that is not a Raindrop event");
+            readEvent(record, context);
+        });
+    },
+};
+// --- raindrop_spans --------------------------------------------------------------------------
+/** Raindrop's span types, by the kind each is. */
+const SPAN_TYPES = {
+    INTERNAL: undefined,
+    LLM_GENERATION: "llm",
+    LLM_GENERATION_STREAM: "llm",
+    TOOL_CALL: "tool",
+};
+/** A span row of the Query API's `GET /v1/traces`. */
+const isSpanRow = (value) => isObject(value) &&
+    typeof value.trace_id === "string" &&
+    typeof value.span_id === "string" &&
+    typeof value.span_name === "string" &&
+    typeof value.span_type === "string" &&
+    Object.hasOwn(SPAN_TYPES, value.span_type) &&
+    "start_time_ns" in value;
+/** The span rows a `GET /v1/traces` answer (`{"data": […]}`) holds, when it holds any. */
+const envelopeSpans = (value) => isObject(value) && Array.isArray(value.data) && value.data.some(isSpanRow)
+    ? value.data
+    : undefined;
+/** A payload Raindrop keeps as text: the JSON it holds when it holds an object or a list. */
+function payload(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string" || !/^\s*[[{]/.test(value))
+        return value;
+    try {
+        return parseNestedJsonText(value).value;
+    }
+    catch {
+        return value;
+    }
+}
+/** An instant or duration in nanoseconds (a number, or its decimal text for one past 2^53). */
+const nanos = (value) => value === undefined || value === null || value === 0 ? undefined : nanosFrom(value, "ns");
+function readSpanRow(record, context) {
+    const traceKey = text(record.trace_id);
+    const spanKey = text(record.span_id);
+    if (!traceKey || !spanKey)
+        throw new ConversionError("a span without a trace_id or span_id");
+    const attributes = object(record.attributes);
+    if (record.attributes != null && !attributes)
+        throw new ConversionError("attributes is not an object");
+    const kind = SPAN_TYPES[record.span_type];
+    const start = nanos(record.start_time_ns);
+    const duration = record.end_time_ns == null ? nanos(record.duration_ns) : undefined;
+    const end = nanos(record.end_time_ns) ?? (start && duration ? start + duration : undefined);
+    const input = payload(record.input);
+    const output = payload(record.output);
+    const row = {
+        traceKey,
+        spanKey,
+        ...(text(record.parent_span_id) ? { parentKey: text(record.parent_span_id) } : {}),
+        name: text(record.span_name) ?? "span",
+        ...(kind ? { kind } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        ...(record.end_time_ns == null && duration !== undefined
+            ? { timing: "end_from_duration" }
+            : {}),
+        ...(input !== undefined ? { input } : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(attributes ? { attributes, metadata: attributes } : {}),
+        record,
+    };
+    if (text(record.status) === "ERROR")
+        row.error = {};
+    if (kind === "llm") {
+        if (text(record.model))
+            row.model = text(record.model);
+        if (text(record.provider))
+            row.provider = text(record.provider).toLowerCase();
+        const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+        row.usage = { input: count(record.input_tokens), output: count(record.output_tokens) };
+    }
+    if (kind === "tool")
+        row.tool = {
+            name: row.name,
+            ...(input !== undefined ? { arguments: input } : {}),
+            ...(output !== undefined ? { result: output } : {}),
+        };
+    else {
+        // Raindrop's SDKs stamp the interaction's user and conversation on every span they open
+        // (`traceloop.association.properties.user_id`, `ai.telemetry.metadata.raindrop.userId`, …),
+        // read as Hue reads them.
+        const user = readIdentity("user", (key) => attributes?.[key]);
+        const session = readIdentity("session", (key) => attributes?.[key]);
+        if (user !== undefined)
+            row.user = user;
+        if (session !== undefined)
+            row.session = session;
+    }
+    context.row(row);
+}
+/**
+ * Raindrop's span rows: the Query API's `GET /v1/traces?event_id=` answer (`{"data": […]}`), one
+ * row alone, or one per line. Each row (`trace_id`, `span_id`, `parent_span_id`, `span_name`,
+ * `span_type`, `status`, `start_time_ns`, `end_time_ns`, `duration_ns`, `input`, `output`,
+ * `input_tokens`, `output_tokens`, `model`, `provider`, `attributes`) is one span of its trace; it
+ * carries the content, tool arguments and results, tokens and model an event record lacks.
+ *
+ * - `span_type` names the kind: `LLM_GENERATION` and `LLM_GENERATION_STREAM` a model call,
+ *   `TOOL_CALL` a tool call, `INTERNAL` none. A tool span's input and output are its arguments and
+ *   result; payload text holding JSON is read as that JSON.
+ * - Times are Unix nanoseconds; a row without `end_time_ns` ends `duration_ns` after it starts
+ *   (`end_from_duration`). `status` `ERROR` is an error.
+ * - `attributes` (text and numbers only, as Raindrop serves them) are kept under their own names.
+ *   The user and conversation are those Raindrop's SDKs stamp on every span of the interaction
+ *   (`traceloop.association.properties.user_id` and `convo_id`, `ai.telemetry.metadata.raindrop.*`),
+ *   read as Hue reads them; the rows name no event, so the event's own `user_id` is not joined in,
+ *   and `--user-key` names a user the attributes lack.
+ */
+export const raindropSpans = {
+    id: "raindrop_spans",
+    manifestFormat: "otlp_json",
+    detect: (value) => isSpanRow(value) || envelopeSpans(value) !== undefined,
+    convert(value, context) {
+        readRecords(context, isSpanRow(value) ? [value] : (envelopeSpans(value) ?? []), (record) => (isSpanRow(record) ? text(record.trace_id) : undefined), (record) => {
+            if (!isSpanRow(record))
+                throw new ConversionError("a record that is not a Raindrop span");
+            readSpanRow(record, context);
+        });
+    },
+};

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

@@ -0,0 +1,56 @@
+import { type ConvertedTrace } from "../traces-import-convert.js";
+import type { Location } from "./adapter.js";
+import { type IdentityKeys } from "./identity.js";
+export type { Location } from "./adapter.js";
+export interface ReadResult {
+    /** Every trace read, in trace id order, its identity read as Hue reads it. */
+    traces: ConvertedTrace[];
+    supported: {
+        file: string;
+        format: string;
+        traces: number;
+    }[];
+    unsupported: {
+        file: string;
+        reason: string;
+    }[];
+    skipped: (Location & {
+        reason: string;
+    })[];
+    /** What was read with a repair, or read once though the input held it more than once. */
+    notes: (Location & {
+        reason: string;
+    })[];
+    refused: (Partial<Location> & {
+        trace_id?: string;
+        reason: string;
+    })[];
+}
+export declare class ImportReader {
+    private readonly options;
+    /** Run-wide collectors, by format id or by the key formats that share one name. */
+    private readonly collectors;
+    /** The shared collector key of each format that named one. */
+    private readonly sharedKeys;
+    private readonly rowCollectors;
+    private readonly whole;
+    /** Traces already refused and named; a collector's own refusal of one is not repeated. */
+    private readonly refusedTraces;
+    /** The file names each content digest was read under. */
+    private readonly fileNames;
+    private readonly supported;
+    private readonly result;
+    /** `unsupported` is where files that cannot be read are listed, in the order they are read. */
+    constructor(options: {
+        maxFileBytes: number;
+        keys?: IdentityKeys;
+        unsupported?: ReadResult["unsupported"];
+    });
+    /** Reads one file's bytes; returns the size of its decoded content. */
+    read(file: string, raw: Uint8Array): number;
+    private rows;
+    private convert;
+    /** Every trace read, merged across files: the same trace from two sources is one trace when
+     * its spans agree, and refused when they differ. */
+    finish(): ReadResult;
+}