@hue-run/sdk 0.21.0 → 0.22.0

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

@@ -0,0 +1,260 @@
+import { ConversionError, isObject } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { count, jsonOf, object, text } from "./row-platform-fields.js";
+import { nanosFrom, readRecords } from "./rows.js";
+/**
+ * MLflow traces as `Trace.to_dict()` writes them (`mlflow traces get`, `trace.to_json()`): an
+ * `info` (`TraceInfo`: `trace_id`, `request_time`, `trace_metadata`, `tags`) and `data.spans`, each
+ * span OpenTelemetry-shaped with base64 ids, nanosecond times and every attribute JSON-encoded.
+ * Read from one trace, a JSON array or JSON Lines of them, and `mlflow traces search --output json`
+ * (`{"traces": […], "next_page_token": …}`); MLflow 2's form (`info.request_id`,
+ * `request_metadata`, spans with `context`, `parent_id` and `start_time`) is read too.
+ *
+ * - `mlflow.spanType` names the kind: `LLM` and `CHAT_MODEL` a model call, `TOOL` a tool call,
+ *   `AGENT`, `RETRIEVER` and `EMBEDDING`; `mlflow.spanInputs` and `mlflow.spanOutputs` are the
+ *   content, `mlflow.chat.tokenUsage` the token counts, `mlflow.llm.model` and
+ *   `mlflow.llm.provider` the model.
+ * - The user and conversation are the trace's `mlflow.trace.user` and `mlflow.trace.session`
+ *   metadata, else a span's own `user.id` and `session.id`. `mlflow.user` and `mlflow.auth.*`
+ *   name who logged the trace, never the end user.
+ * - A trace tagged `mlflow.eval.requestId` (made by `mlflow.genai.evaluate`) or
+ *   `mlflow.trace.sourceScorer` (a judge's own trace) is evaluation traffic.
+ * - A span's `links`, which `Span.to_dict()` writes beside its parent, become span links, to a
+ *   span of the same trace or of another, their ids read as the trace's own are.
+ * - A trace is one record: a malformed span refuses its trace. The spans without a parent keep the
+ *   trace's `info` beside the span in their source record.
+ */
+const isTrace = (value) => isObject(value) &&
+    isObject(value.info) &&
+    isObject(value.data) &&
+    Array.isArray(value.data.spans) &&
+    (typeof value.info.trace_id === "string" || typeof value.info.request_id === "string");
+/** The traces `mlflow traces search --output json` answers, when it holds any. */
+const envelopeTraces = (value) => isObject(value) && Array.isArray(value.traces) && value.traces.some(isTrace)
+    ? value.traces
+    : undefined;
+/** An MLflow id as lowercase hex: the base64 of its bytes (`Span.to_dict`), its hex (MLflow
+ * 3.5), `0x`-prefixed hex (MLflow 2) or a `tr-` trace id; undefined when it is none of these. */
+function hexId(value, bytes) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const hex = value.replace(/^0x|^tr-/i, "");
+    if (hex.length === bytes * 2 && /^[0-9a-f]+$/i.test(hex))
+        return hex.toLowerCase();
+    if (/^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length === Math.ceil(bytes / 3) * 4) {
+        const decoded = Buffer.from(value, "base64");
+        if (decoded.byteLength === bytes)
+            return decoded.toString("hex");
+    }
+    return undefined;
+}
+const KINDS = {
+    LLM: "llm",
+    CHAT_MODEL: "llm",
+    TOOL: "tool",
+    AGENT: "agent",
+    RETRIEVER: "retrieval",
+    EMBEDDING: "embedding",
+};
+/** The span's attributes with MLflow's JSON encoding undone; text that is not JSON is kept. */
+function decodedAttributes(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (!isObject(value))
+        throw new ConversionError("a span's attributes are not an object");
+    const decoded = {};
+    for (const [key, raw] of Object.entries(value))
+        decoded[key] = jsonOf(raw) ?? raw;
+    return decoded;
+}
+/** An attribute value OTLP holds as it is: text, a number or a boolean; anything else as JSON. */
+const attributeValue = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+    ? value
+    : JSON.stringify(value);
+/** A trace reference as a trace key: an id in any of MLflow's forms (`tr-<hex>`, hex, a v4
+ * `trace:/<location>/<hex>`), else the reference as recorded. */
+const traceKeyOf = (reference) => hexId(reference, 16) ?? hexId(reference.split("/").at(-1), 16) ?? reference;
+/** A span's links (`Link.to_dict()`: `trace_id`, `span_id`, `attributes`). */
+function linksOf(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new ConversionError("a span's links are not a list");
+    return value.map((item) => {
+        const link = object(item);
+        const traceId = text(link?.trace_id);
+        const spanId = text(link?.span_id);
+        if (!link || !traceId || !spanId)
+            throw new ConversionError("a span link without a trace_id or span_id");
+        const attributes = object(link.attributes);
+        return {
+            traceKey: traceKeyOf(traceId),
+            spanKey: hexId(spanId, 8) ?? spanId,
+            ...(attributes ? { attributes } : {}),
+        };
+    });
+}
+/** The instant a span field records, in nanoseconds; undefined when absent. */
+const instant = (value) => value === undefined || value === null || value === "" || value === 0
+    ? undefined
+    : nanosFrom(value, "ns");
+/** One span as a row and its events. */
+function readSpan(span, trace) {
+    if (!isObject(span))
+        throw new ConversionError("a span that is not an object");
+    const v2 = isObject(span.context);
+    const rawId = v2 ? span.context.span_id : span.span_id;
+    const rawParent = v2 ? span.parent_id : span.parent_span_id;
+    const spanKey = hexId(rawId, 8) ?? text(rawId);
+    if (spanKey === undefined)
+        throw new ConversionError("a span without a span_id");
+    const parentKey = rawParent ? (hexId(rawParent, 8) ?? text(rawParent)) : undefined;
+    const status = object(span.status);
+    const code = text(v2 ? span.status_code : status?.code);
+    const message = text(v2 ? span.status_message : status?.message);
+    const attributes = decodedAttributes(span.attributes);
+    const type = text(attributes["mlflow.spanType"]);
+    const kind = type && Object.hasOwn(KINDS, type) ? KINDS[type] : undefined;
+    const start = instant(v2 ? span.start_time : span.start_time_unix_nano);
+    const end = instant(v2 ? span.end_time : span.end_time_unix_nano);
+    const events = span.events ?? [];
+    if (!Array.isArray(events))
+        throw new ConversionError("a span's events are not a list");
+    let exceptionType;
+    const eventRows = events.map((event) => {
+        if (!isObject(event))
+            throw new ConversionError("a span event that is not an object");
+        const time = instant(v2 ? event.timestamp : event.time_unix_nano);
+        const eventAttributes = object(event.attributes);
+        if (event.name === "exception")
+            exceptionType ??= text(eventAttributes?.["exception.type"]);
+        return {
+            traceKey: trace.traceKey,
+            spanKey,
+            name: text(event.name) ?? "event",
+            ...(time !== undefined ? { time } : {}),
+            ...(eventAttributes ? { attributes: eventAttributes } : {}),
+            record: event,
+        };
+    });
+    const links = linksOf(span.links);
+    const input = attributes["mlflow.spanInputs"];
+    const output = attributes["mlflow.spanOutputs"];
+    const own = {};
+    for (const [key, value] of Object.entries(attributes))
+        if (key.startsWith("mlflow.") &&
+            key !== "mlflow.spanInputs" &&
+            key !== "mlflow.spanOutputs" &&
+            value !== null)
+            own[key] = attributeValue(value);
+    const row = {
+        traceKey: trace.traceKey,
+        spanKey,
+        ...(parentKey !== undefined ? { parentKey } : {}),
+        ...(links.length ? { links } : {}),
+        name: text(span.name) ?? "span",
+        ...(kind ? { kind } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        ...(input !== undefined && input !== null ? { input } : {}),
+        ...(output !== undefined && output !== null ? { output } : {}),
+        record: parentKey === undefined ? { info: trace.info, span } : span,
+        ...(trace.metadata ? { metadata: trace.metadata } : {}),
+        attributes: own,
+    };
+    if (code && /ERROR$/.test(code))
+        row.error = {
+            ...(message ? { message } : {}),
+            ...(exceptionType ? { type: exceptionType } : {}),
+        };
+    const model = text(attributes["mlflow.llm.model"]);
+    const provider = text(attributes["mlflow.llm.provider"]);
+    if (model)
+        row.model = model;
+    if (provider)
+        row.provider = provider;
+    const usage = object(attributes["mlflow.chat.tokenUsage"]);
+    if (usage)
+        row.usage = {
+            input: count(usage.input_tokens),
+            output: count(usage.output_tokens),
+            cacheRead: count(usage.cache_read_input_tokens),
+            cacheWrite: count(usage.cache_creation_input_tokens),
+        };
+    if (kind === "tool")
+        row.tool = {
+            name: row.name,
+            ...(input !== undefined && input !== null ? { arguments: input } : {}),
+            ...(output !== undefined && output !== null ? { result: output } : {}),
+        };
+    else {
+        const user = trace.user ?? identityText(attributes["user.id"]);
+        const session = trace.session ?? identityText(attributes["session.id"]);
+        if (user !== undefined)
+            row.user = user;
+        if (session !== undefined)
+            row.session = session;
+    }
+    if (trace.evaluation)
+        row.origin = "evaluation";
+    return { row, events: eventRows };
+}
+function readTrace(value, context) {
+    const trace = traceOf(value);
+    if (!trace)
+        throw new ConversionError("a trace without a trace_id");
+    const spans = value.data.spans;
+    if (!spans.length)
+        throw new ConversionError("a trace exported without its spans; export it with its spans");
+    // Every span is read before any is added, so a malformed one refuses the trace whole.
+    const read = spans.map((span) => readSpan(span, trace));
+    for (const { row, events } of read) {
+        context.row(row);
+        for (const event of events)
+            context.event(event);
+    }
+}
+function traceOf(value) {
+    const info = value.info;
+    const reference = text(info.trace_id) ?? text(info.request_id);
+    if (reference === undefined)
+        return undefined;
+    const spans = value.data.spans;
+    const spanTraces = new Set(spans.flatMap((span) => {
+        const raw = isObject(span)
+            ? isObject(span.context)
+                ? span.context.trace_id
+                : span.trace_id
+            : undefined;
+        return hexId(raw, 16) ?? [];
+    }));
+    const traceKey = hexId(reference, 16) ??
+        hexId(reference.split("/").at(-1), 16) ??
+        (spanTraces.size === 1 ? [...spanTraces][0] : traceKeyOf(reference));
+    const metadata = object(info.trace_metadata ?? info.request_metadata);
+    const tags = object(info.tags);
+    const user = identityText(metadata?.["mlflow.trace.user"]);
+    const session = identityText(metadata?.["mlflow.trace.session"]);
+    return {
+        traceKey,
+        info,
+        ...(metadata ? { metadata } : {}),
+        ...(user !== undefined ? { user } : {}),
+        ...(session !== undefined ? { session } : {}),
+        evaluation: tags?.["mlflow.eval.requestId"] !== undefined ||
+            tags?.["mlflow.trace.sourceScorer"] !== undefined,
+    };
+}
+export const mlflowTraces = {
+    id: "mlflow_traces",
+    manifestFormat: "otlp_json",
+    detect: (value) => isTrace(value) || envelopeTraces(value) !== undefined,
+    convert(value, context) {
+        const records = isTrace(value) ? [value] : (envelopeTraces(value) ?? []);
+        readRecords(context, records, (record) => (isTrace(record) ? traceOf(record)?.traceKey : undefined), (record) => {
+            if (!isTrace(record))
+                throw new ConversionError("a record that is not an MLflow trace");
+            readTrace(record, context);
+        });
+    },
+};

package/dist/cli/import-formats/openai-agents.d.ts

@@ -0,0 +1,2 @@
+import type { ImportAdapter } from "./adapter.js";
+export declare const openaiAgents: ImportAdapter;

package/dist/cli/import-formats/openai-agents.js

@@ -0,0 +1,221 @@
+import { ConversionError, isObject, parseNestedJsonText, unixNano, } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { metadataUser } from "./row-platform-fields.js";
+import { readRecords } from "./rows.js";
+const object = (value) => isObject(value) ? value : undefined;
+const text = (value) => typeof value === "string" && value ? value : undefined;
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string")
+    ? value
+    : undefined;
+const isTrace = (value) => isObject(value) && value.object === "trace" && typeof value.id === "string";
+const isSpan = (value) => isObject(value) && value.object === "trace.span" && typeof value.trace_id === "string";
+const isRecord = (value) => isTrace(value) || isSpan(value);
+/** The records an ingest body (`{"data": […]}`) holds, when it holds any. */
+function envelopeRecords(value) {
+    return isObject(value) && Array.isArray(value.data) && value.data.some(isRecord)
+        ? value.data
+        : undefined;
+}
+const SESSION_FIELDS = [
+    "session_id",
+    "sessionId",
+    "thread_id",
+    "threadId",
+    "conversation_id",
+    "conversationId",
+];
+const first = (fields, names) => {
+    for (const name of names) {
+        const value = identityText(fields?.[name]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+};
+/** An instant the SDK recorded (`started_at`, `ended_at`), or none when it is null. */
+const instant = (value) => value === undefined || value === null ? undefined : BigInt(unixNano(value));
+/** Token usage of a model call: `input_tokens`, `output_tokens` and their details, also as the
+ * SDK's OpenAI exporter nests them under `details`. */
+function usageOf(value) {
+    const usage = object(value);
+    if (!usage)
+        return undefined;
+    const details = object(usage.details);
+    const detail = (name) => {
+        const found = usage[name] ?? details?.[name];
+        return object(Array.isArray(found) ? found[0] : found);
+    };
+    const input = detail("input_tokens_details");
+    const output = detail("output_tokens_details");
+    return {
+        input: count(usage.input_tokens),
+        output: count(usage.output_tokens),
+        cacheRead: count(input?.cached_tokens) ?? count(usage.cached_input_tokens),
+        cacheWrite: count(input?.cache_write_tokens) ?? count(usage.cache_write_input_tokens),
+        reasoning: count(output?.reasoning_tokens),
+    };
+}
+/** A function tool's arguments: the JSON text the model wrote, parsed when it is JSON. */
+function argumentsOf(value) {
+    if (typeof value !== "string")
+        return value ?? undefined;
+    try {
+        return parseNestedJsonText(value).value;
+    }
+    catch {
+        return value;
+    }
+}
+function readTrace(record, context) {
+    const traceKey = text(record.id);
+    if (!traceKey)
+        throw new ConversionError("a trace without an id");
+    const metadata = object(record.metadata);
+    if (record.metadata != null && !metadata)
+        throw new ConversionError("metadata is not an object");
+    const user = metadataUser(metadata);
+    const session = identityText(record.group_id) ?? first(metadata, SESSION_FIELDS);
+    context.row({
+        traceKey,
+        spanKey: traceKey,
+        name: text(record.workflow_name) ?? "trace",
+        ...(user !== undefined ? { user } : {}),
+        ...(session !== undefined ? { session } : {}),
+        attributes: metadata && Object.keys(metadata).length
+            ? { "openai_agents.metadata": JSON.stringify(metadata) }
+            : {},
+        record,
+        ...(metadata ? { metadata } : {}),
+    });
+}
+function readSpan(record, context) {
+    const traceKey = text(record.trace_id);
+    const spanKey = text(record.id);
+    if (!traceKey || !spanKey)
+        throw new ConversionError("a span without an id or trace_id");
+    if (record.parent_id != null && !text(record.parent_id))
+        throw new ConversionError("parent_id is not a span id");
+    const data = object(record.span_data);
+    const type = text(data?.type);
+    if (!data || !type)
+        throw new ConversionError("span_data has no type");
+    const error = record.error;
+    if (error != null && !object(error))
+        throw new ConversionError("error is not an object");
+    const metadata = object(record.metadata);
+    const name = text(data.name) ?? type;
+    const attributes = { "openai_agents.span.type": type };
+    const json = (key, value) => {
+        if (value !== undefined && value !== null)
+            attributes[key] = JSON.stringify(value);
+    };
+    if (metadata && Object.keys(metadata).length)
+        json("openai_agents.metadata", metadata);
+    let kind;
+    const row = {};
+    switch (type) {
+        case "agent":
+            kind = "agent";
+            row.agentName = name;
+            for (const field of ["handoffs", "tools"])
+                if (strings(data[field]))
+                    attributes[`openai_agents.agent.${field}`] = strings(data[field]);
+            if (text(data.output_type))
+                attributes["openai_agents.agent.output_type"] = data.output_type;
+            break;
+        case "function":
+            kind = "tool";
+            row.tool = {
+                name,
+                ...(data.input != null ? { arguments: argumentsOf(data.input) } : {}),
+                ...(data.output != null ? { result: data.output } : {}),
+            };
+            json("openai_agents.mcp_data", data.mcp_data);
+            break;
+        case "generation":
+            kind = "llm";
+            if (data.input != null)
+                row.input = data.input;
+            if (data.output != null)
+                row.output = data.output;
+            if (text(data.model))
+                row.model = text(data.model);
+            row.usage = usageOf(data.usage);
+            json("openai_agents.model_config", data.model_config);
+            break;
+        case "response":
+            kind = "llm";
+            if (text(data.response_id))
+                attributes["gen_ai.response.id"] = data.response_id;
+            row.usage = usageOf(data.usage);
+            break;
+        case "handoff":
+            if (text(data.from_agent))
+                attributes["openai_agents.handoff.from_agent"] = data.from_agent;
+            if (text(data.to_agent))
+                attributes["openai_agents.handoff.to_agent"] = data.to_agent;
+            break;
+        case "guardrail":
+            if (typeof data.triggered === "boolean")
+                attributes["openai_agents.guardrail.triggered"] = data.triggered;
+            break;
+        case "custom":
+            json("openai_agents.custom.data", data.data);
+            break;
+        case "mcp_tools":
+            if (text(data.server))
+                attributes["openai_agents.mcp.server"] = data.server;
+            if (strings(data.result))
+                attributes["openai_agents.mcp.tools"] = strings(data.result);
+            break;
+        default:
+            // Voice and future span types: the model they name, their data in the source record.
+            if (text(data.model))
+                row.model = text(data.model);
+    }
+    const start = instant(record.started_at);
+    const end = instant(record.ended_at);
+    const errorFields = object(error);
+    context.row({
+        traceKey,
+        spanKey,
+        parentKey: text(record.parent_id) ?? traceKey,
+        name,
+        ...(kind ? { kind } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        ...row,
+        ...(errorFields
+            ? {
+                error: text(errorFields.message) ? { message: text(errorFields.message) } : {},
+            }
+            : {}),
+        attributes: {
+            ...attributes,
+            ...(errorFields?.data != null
+                ? { "openai_agents.error.data": JSON.stringify(errorFields.data) }
+                : {}),
+        },
+        record,
+        ...(metadata ? { metadata } : {}),
+        // A processor may write a span when it starts and again when it ends: the ended copy wins.
+        revision: end === undefined ? "0" : "1",
+    });
+}
+export const openaiAgents = {
+    id: "openai_agents",
+    manifestFormat: "otlp_json",
+    detect: (value) => isRecord(value) || envelopeRecords(value) !== undefined,
+    convert(value, context) {
+        const records = isRecord(value) ? [value] : (envelopeRecords(value) ?? []);
+        readRecords(context, records, (record) => isTrace(record) ? text(record.id) : isSpan(record) ? text(record.trace_id) : undefined, (record) => {
+            if (isTrace(record))
+                readTrace(record, context);
+            else if (isSpan(record))
+                readSpan(record, context);
+            else
+                throw new ConversionError("a record that is not an OpenAI Agents trace or span");
+        });
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { ImportAdapter } from "./adapter.js";
+export declare const opikTraces: ImportAdapter;

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

@@ -0,0 +1,193 @@
+import { ConversionError, isObject } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { count, first, isoNanos, metadataUser, object, SESSION_FIELDS, text, } from "./row-platform-fields.js";
+import { readRecords } from "./rows.js";
+/**
+ * Opik traces and spans (`TracePublic` and `SpanPublic` in Opik's REST API). Read from the files
+ * `opik export … project …` writes, one per trace (`{"trace": …, "spans": […], …}`), and from
+ * span records alone: one span, JSON Lines of them or the spans API's page (`{"content": […]}`).
+ *
+ * - The trace becomes the root span of its trace, its id the span id; a span without a
+ *   `parent_span_id` is its child. Spans read without their trace keep it as their missing parent.
+ * - `type` names the kind: `llm` a model call, `tool` a tool call; `general` and `guardrail` record
+ *   no operation. Token counts (`usage`) are read from `llm` spans, `prompt_tokens` and
+ *   `completion_tokens` with the provider's own cache and reasoning counts (`original_usage.*`).
+ * - The conversation is the trace's `thread_id`, else its metadata's; the user comes from the
+ *   metadata (`userId`, `user_id`, …, in the order Hue reads a metadata map). `created_by` names
+ *   who logged it, never the end user.
+ * - A trace from an experiment, evaluator, optimization or the playground (`source`, `experiment`)
+ *   is evaluation traffic; `environment` is the deployment environment.
+ * - A record exported more than once keeps the copy updated last (`last_updated_at`).
+ */
+const SPAN_TYPES = new Set(["general", "tool", "llm", "guardrail"]);
+const KINDS = { llm: "llm", tool: "tool" };
+const EVALUATION_SOURCES = new Set(["experiment", "evaluator", "optimization", "playground"]);
+const isSpan = (value) => isObject(value) &&
+    typeof value.id === "string" &&
+    typeof value.trace_id === "string" &&
+    typeof value.type === "string" &&
+    SPAN_TYPES.has(value.type) &&
+    typeof value.start_time === "string" &&
+    value.run_type === undefined;
+/** An `opik export` trace file: the trace with its spans. */
+const isExport = (value) => isObject(value) &&
+    isObject(value.trace) &&
+    typeof value.trace.id === "string" &&
+    typeof value.trace.start_time === "string" &&
+    Array.isArray(value.spans) &&
+    (value.spans.some(isSpan) || typeof value.downloaded_at === "string");
+/** The spans a spans API page holds, when it holds any. */
+const spanPage = (value) => isObject(value) && Array.isArray(value.content) && value.content.some(isSpan)
+    ? value.content
+    : undefined;
+/** A token count from Opik's usage, the OpenAI-shaped total first, then the provider's own. */
+const usageCount = (usage, names) => {
+    for (const name of names) {
+        const value = count(usage?.[name]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+};
+/** The fields Opik's trace and span records share, as a row. */
+function readRecord(record, traceKey, spanKey, parentKey) {
+    const start = isoNanos(record.start_time);
+    const end = record.end_time == null ? undefined : isoNanos(record.end_time);
+    const metadata = object(record.metadata);
+    const tags = Array.isArray(record.tags) && record.tags.every((tag) => typeof tag === "string")
+        ? record.tags
+        : undefined;
+    const updated = record.last_updated_at == null ? undefined : isoNanos(record.last_updated_at);
+    const row = {
+        traceKey,
+        spanKey,
+        ...(parentKey !== undefined ? { parentKey } : {}),
+        name: text(record.name) ?? "span",
+        start,
+        ...(end !== undefined ? { end } : {}),
+        ...(record.input != null ? { input: record.input } : {}),
+        ...(record.output != null ? { output: record.output } : {}),
+        record,
+        ...(metadata ? { metadata } : {}),
+        ...(updated !== undefined ? { revision: updated.toString() } : {}),
+        attributes: {
+            ...(record.metadata != null
+                ? {
+                    "opik.metadata": typeof record.metadata === "string"
+                        ? record.metadata
+                        : JSON.stringify(record.metadata),
+                }
+                : {}),
+            ...(tags?.length ? { "opik.tags": tags } : {}),
+        },
+    };
+    const error = object(record.error_info);
+    if (record.error_info != null && !error)
+        throw new ConversionError("error_info is not an object");
+    if (error) {
+        const type = text(error.exception_type);
+        const message = text(error.message) ?? type;
+        row.error = { ...(message ? { message } : {}), ...(type ? { type } : {}) };
+    }
+    const source = text(record.source);
+    if ((source && EVALUATION_SOURCES.has(source)) || isObject(record.experiment))
+        row.origin = "evaluation";
+    const environment = text(record.environment);
+    if (environment)
+        row.environment = environment;
+    return row;
+}
+function traceRow(trace) {
+    const id = trace.id;
+    const row = readRecord(trace, id, id, undefined);
+    const metadata = object(trace.metadata);
+    const user = metadataUser(metadata);
+    const session = identityText(trace.thread_id) ?? first(metadata, SESSION_FIELDS);
+    if (user !== undefined)
+        row.user = user;
+    if (session !== undefined)
+        row.session = session;
+    return row;
+}
+function spanRow(span) {
+    const traceKey = text(span.trace_id);
+    const spanKey = text(span.id);
+    if (!traceKey || !spanKey)
+        throw new ConversionError("a span without an id or trace_id");
+    const parent = text(span.parent_span_id) ?? traceKey;
+    const row = readRecord(span, traceKey, spanKey, parent);
+    const type = text(span.type);
+    const kind = type && Object.hasOwn(KINDS, type) ? KINDS[type] : undefined;
+    if (kind)
+        row.kind = kind;
+    if (type)
+        row.attributes["opik.span.type"] = type;
+    const model = text(span.model);
+    const provider = text(span.provider);
+    if (model)
+        row.model = model;
+    if (provider)
+        row.provider = provider;
+    const usage = object(span.usage);
+    if (kind === "llm" && usage)
+        row.usage = {
+            input: usageCount(usage, ["prompt_tokens", "original_usage.input_tokens"]),
+            output: usageCount(usage, ["completion_tokens", "original_usage.output_tokens"]),
+            cacheRead: usageCount(usage, [
+                "original_usage.prompt_tokens_details.cached_tokens",
+                "original_usage.input_tokens_details.cached_tokens",
+                "original_usage.cache_read_input_tokens",
+            ]),
+            cacheWrite: usageCount(usage, ["original_usage.cache_creation_input_tokens"]),
+            reasoning: usageCount(usage, [
+                "original_usage.completion_tokens_details.reasoning_tokens",
+                "original_usage.output_tokens_details.reasoning_tokens",
+            ]),
+        };
+    if (kind === "tool")
+        row.tool = {
+            name: row.name,
+            ...(row.input !== undefined ? { arguments: row.input } : {}),
+            ...(row.output !== undefined ? { result: row.output } : {}),
+        };
+    else {
+        const metadata = object(span.metadata);
+        const user = metadataUser(metadata);
+        const session = first(metadata, SESSION_FIELDS);
+        if (user !== undefined)
+            row.user = user;
+        if (session !== undefined)
+            row.session = session;
+    }
+    return row;
+}
+/** Reads an export file whole: a malformed trace or span refuses the trace. */
+function readExport(value, context) {
+    const traceKey = value.trace.id;
+    const rows = [traceRow(value.trace)];
+    for (const span of value.spans) {
+        if (!isObject(span))
+            throw new ConversionError("a span that is not an object");
+        if (span.trace_id !== traceKey)
+            throw new ConversionError("a span of another trace");
+        rows.push(spanRow(span));
+    }
+    for (const row of rows)
+        context.row(row);
+}
+export const opikTraces = {
+    id: "opik_traces",
+    manifestFormat: "otlp_json",
+    detect: (value) => isExport(value) || isSpan(value) || spanPage(value) !== undefined,
+    convert(value, context) {
+        if (isExport(value)) {
+            readRecords(context, [value], (record) => record.trace.id, (record) => readExport(record, context));
+            return;
+        }
+        readRecords(context, isSpan(value) ? [value] : (spanPage(value) ?? []), (record) => (isObject(record) ? text(record.trace_id) : undefined), (record) => {
+            if (!isObject(record))
+                throw new ConversionError("a record that is not an Opik span");
+            context.row(spanRow(record));
+        });
+    },
+};