@hue-run/sdk 0.21.1 → 0.23.0

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

@@ -0,0 +1,244 @@
+import { ConversionError, isObject } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { count, first, isoNanos, metadataUser, object, objectField, SESSION_FIELDS, text, } from "./row-platform-fields.js";
+import { readRecords } from "./rows.js";
+const RUN_TYPES = new Set(["chain", "llm", "embedding", "prompt", "tool", "retriever", "parser"]);
+const KINDS = {
+    llm: "llm",
+    tool: "tool",
+    embedding: "embedding",
+    retriever: "retrieval",
+};
+const isRun = (value) => isObject(value) &&
+    typeof value.id === "string" &&
+    typeof value.run_type === "string" &&
+    RUN_TYPES.has(value.run_type.toLowerCase()) &&
+    (typeof value.start_time === "string" || typeof value.dotted_order === "string");
+/** The runs a query page (`runs` of v1, `items` of v2) holds, when it holds any. */
+function envelopeRuns(value) {
+    if (!isObject(value))
+        return undefined;
+    for (const key of ["runs", "items"])
+        if (Array.isArray(value[key]) && value[key].some(isRun))
+            return value[key];
+    return undefined;
+}
+/** A run and every run nested in its `child_runs`, each kept without its children. */
+function flatten(record, out) {
+    if (!isRun(record) || !Array.isArray(record.child_runs)) {
+        out.push(record);
+        return;
+    }
+    const { child_runs: children, ...run } = record;
+    out.push(run);
+    for (const child of children)
+        flatten(child, out);
+}
+/** `dotted_order`'s segments, root first: each `<start>Z<run id>`, the start as
+ * `YYYYMMDDTHHMMSSffffff`; undefined when it is not one. */
+function dottedOrder(value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const segments = [];
+    for (const segment of value.split(".")) {
+        const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{0,9})Z(.+)$/.exec(segment);
+        if (!match)
+            return undefined;
+        const [, year, month, day, hour, minute, second, fraction] = match;
+        try {
+            const start = isoNanos(`${year}-${month}-${day}T${hour}:${minute}:${second}${fraction ? `.${fraction}` : ""}Z`);
+            segments.push({ start, id: match[8] });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return segments;
+}
+/** The run's trace and parent: `trace_id`, `parent_run_id` (or the last of v2's
+ * `parent_run_ids`), else what `dotted_order` records; a run with no parent is its trace's root. */
+function placement(run) {
+    const ancestors = Array.isArray(run.parent_run_ids) ? run.parent_run_ids : undefined;
+    const order = text(run.trace_id) === undefined || (run.parent_run_id === undefined && ancestors === undefined)
+        ? dottedOrder(run.dotted_order)
+        : undefined;
+    const parentKey = text(run.parent_run_id) ??
+        (ancestors ? text(ancestors.at(-1)) : undefined) ??
+        (order && order.length > 1 ? order.at(-2).id : undefined);
+    const traceKey = text(run.trace_id) ??
+        order?.[0]?.id ??
+        (parentKey === undefined ? run.id : undefined);
+    return {
+        ...(traceKey !== undefined ? { traceKey } : {}),
+        ...(parentKey !== undefined && parentKey !== run.id ? { parentKey } : {}),
+    };
+}
+/** A LangChain `ToolMessage` (serialized or as a dict) as its content and call id. */
+function toolMessage(value) {
+    const message = object(value);
+    if (!message)
+        return undefined;
+    const constructor = message.lc === 1 && Array.isArray(message.id) && message.id.at(-1) === "ToolMessage"
+        ? object(message.kwargs)
+        : undefined;
+    const fields = constructor ?? (message.type === "tool" ? message : undefined);
+    if (!fields || !("content" in fields))
+        return undefined;
+    const callId = text(fields.tool_call_id);
+    return { content: fields.content, ...(callId ? { callId } : {}) };
+}
+/** A tool run's result: LangChain records it as `{"output": …}`, a `ToolMessage` when the tool
+ * answered one. */
+function toolResult(outputs) {
+    if (outputs === undefined)
+        return {};
+    const keys = Object.keys(outputs);
+    if (keys.length !== 1 || keys[0] !== "output")
+        return { result: outputs };
+    const message = toolMessage(outputs.output);
+    return message
+        ? { result: message.content, callId: message.callId }
+        : { result: outputs.output };
+}
+/** The exception class LangChain's error text opens with (`repr(error)`, as in
+ * `ValueError('…')`), when it does. */
+const errorType = (message) => message ? /^([A-Za-z_][\w.]*)\(/.exec(message)?.[1] : undefined;
+/** A token count from a `*_token_details` map (v2 wraps it in `raw`) or LangChain's
+ * `usage_metadata` details. */
+const detail = (details, name) => count(object(details)?.[name]) ?? count(object(object(details)?.raw)?.[name]);
+/** Cache writes as LangSmith records them: `cache_creation`, the v2 API's `cache_write`, or, as
+ * LangSmith's own Anthropic wrapper records them, the sum of `ephemeral_5m_input_tokens` and
+ * `ephemeral_1h_input_tokens`. */
+function cacheWrites(details) {
+    const recorded = detail(details, "cache_creation") ?? detail(details, "cache_write");
+    if (recorded !== undefined)
+        return recorded;
+    const short = detail(details, "ephemeral_5m_input_tokens");
+    const long = detail(details, "ephemeral_1h_input_tokens");
+    return short === undefined && long === undefined ? undefined : (short ?? 0) + (long ?? 0);
+}
+function readRun(run, context) {
+    const { traceKey, parentKey } = placement(run);
+    if (traceKey === undefined)
+        throw new ConversionError("a run without a trace_id");
+    const runType = run.run_type.toLowerCase();
+    const ancestors = run.parent_run_ids;
+    if (ancestors != null &&
+        (!Array.isArray(ancestors) || !ancestors.every((id) => typeof id === "string" && id)))
+        throw new ConversionError("parent_run_ids is not a list of run ids");
+    let start = run.start_time == null ? undefined : isoNanos(run.start_time);
+    const end = run.end_time == null ? undefined : isoNanos(run.end_time);
+    let timing;
+    if (start === undefined) {
+        const own = dottedOrder(run.dotted_order)?.at(-1);
+        if (own?.id === run.id) {
+            start = own.start;
+            timing = "start_from_dotted_order";
+        }
+    }
+    const extra = objectField(run.extra, "extra");
+    const metadata = object(run.metadata) ?? object(extra?.metadata);
+    const inputs = objectField(run.inputs, "inputs");
+    const outputs = objectField(run.outputs, "outputs");
+    const tags = Array.isArray(run.tags) && run.tags.every((tag) => typeof tag === "string")
+        ? run.tags
+        : undefined;
+    const kind = Object.hasOwn(KINDS, runType) ? KINDS[runType] : undefined;
+    // A completion model records its prompt as `{"prompts": [text]}`.
+    const prompts = inputs?.prompts;
+    const input = kind === "llm" &&
+        Array.isArray(prompts) &&
+        prompts.length === 1 &&
+        typeof prompts[0] === "string"
+        ? prompts[0]
+        : inputs;
+    const row = {
+        traceKey,
+        spanKey: run.id,
+        ...(parentKey !== undefined ? { parentKey } : {}),
+        name: text(run.name) ?? runType,
+        ...(kind ? { kind } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(end !== undefined ? { end } : {}),
+        ...(timing ? { timing } : {}),
+        ...(input !== undefined ? { input } : {}),
+        ...(outputs !== undefined ? { output: outputs } : {}),
+        record: run,
+        ...(metadata ? { metadata } : {}),
+        revision: end !== undefined ? "1" : "0",
+        attributes: {
+            "langsmith.span.kind": runType,
+            ...(metadata && Object.keys(metadata).length
+                ? { "langsmith.metadata": JSON.stringify(metadata) }
+                : {}),
+            ...(tags?.length ? { "langsmith.span.tags": tags } : {}),
+        },
+    };
+    const error = text(run.error);
+    if (error !== undefined || text(run.status)?.toLowerCase() === "error") {
+        const type = errorType(error);
+        row.error = { ...(error !== undefined ? { message: error } : {}), ...(type ? { type } : {}) };
+    }
+    if (kind === "llm" || kind === "embedding") {
+        const params = object(extra?.invocation_params);
+        const model = text(metadata?.ls_model_name) ??
+            text(params?.model) ??
+            text(params?.model_name) ??
+            text(inputs?.model);
+        const provider = text(metadata?.ls_provider);
+        if (model)
+            row.model = model;
+        if (provider)
+            row.provider = provider;
+    }
+    if (kind === "llm") {
+        const usage = object(metadata?.usage_metadata) ?? object(outputs?.usage_metadata);
+        row.usage = {
+            input: count(run.prompt_tokens) ?? count(usage?.input_tokens),
+            output: count(run.completion_tokens) ?? count(usage?.output_tokens),
+            cacheRead: detail(run.prompt_token_details, "cache_read") ??
+                detail(usage?.input_token_details, "cache_read"),
+            cacheWrite: cacheWrites(run.prompt_token_details) ?? cacheWrites(usage?.input_token_details),
+            reasoning: detail(run.completion_token_details, "reasoning") ??
+                detail(usage?.output_token_details, "reasoning"),
+        };
+    }
+    if (kind === "tool") {
+        const returned = toolResult(outputs);
+        row.tool = {
+            name: text(run.name) ?? "tool",
+            ...(inputs !== undefined ? { arguments: inputs } : {}),
+            ...(returned.result !== undefined ? { result: returned.result } : {}),
+        };
+        // LangChain passes the call id a tool answers to the tracer, which keeps it in `extra`.
+        const callId = text(extra?.tool_call_id) ?? returned.callId;
+        if (callId)
+            row.tool.callId = callId;
+    }
+    else {
+        const user = metadataUser(metadata);
+        const session = first(metadata, SESSION_FIELDS) ?? identityText(run.thread_id);
+        if (user !== undefined)
+            row.user = user;
+        if (session !== undefined)
+            row.session = session;
+    }
+    if (text(run.reference_example_id))
+        row.origin = "evaluation";
+    context.row(row);
+}
+export const langsmithRuns = {
+    id: "langsmith_runs",
+    manifestFormat: "otlp_json",
+    detect: (value) => isRun(value) || envelopeRuns(value) !== undefined,
+    convert(value, context) {
+        const records = [];
+        for (const record of isRun(value) ? [value] : (envelopeRuns(value) ?? []))
+            flatten(record, records);
+        readRecords(context, records, (record) => (isRun(record) ? placement(record).traceKey : undefined), (record) => {
+            if (!isRun(record))
+                throw new ConversionError("a record that is not a LangSmith run");
+            readRun(record, context);
+        });
+    },
+};

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

@@ -0,0 +1,28 @@
+import { type JsonValue } from "../traces-import-convert.js";
+/**
+ * Chat content as the OpenTelemetry GenAI conventions record it (`gen_ai.input.messages`,
+ * `gen_ai.output.messages`): a list of `{role, parts}` messages whose parts are `text`,
+ * `tool_call`, `tool_call_response`, `reasoning`, `blob` and `uri`, read from the shapes exports
+ * commonly hold: OpenAI chat messages and choices, OpenAI Responses items, Anthropic content
+ * blocks, LangChain messages and generations, Vercel AI SDK messages and plain strings. A part of
+ * any other type is kept whole under its own `type`; content of no recognized shape converts to
+ * nothing, and the emitter keeps it raw instead.
+ */
+type Part = {
+    type: string;
+} & {
+    [key: string]: JsonValue;
+};
+export interface GenAiMessage {
+    role: string;
+    parts: Part[];
+    name?: string;
+    finish_reason?: string;
+}
+/**
+ * `value` as GenAI messages, or undefined when it holds no recognized chat content. A plain
+ * string is one message from `stringRole` when one is given; `{messages: […]}` and
+ * `{choices: […]}` wrappers, LangChain's batched lists and `LLMResult` generations are unwrapped.
+ */
+export declare function genAiMessages(value: JsonValue | undefined, stringRole?: "user" | "assistant"): GenAiMessage[] | undefined;
+export {};

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

@@ -0,0 +1,301 @@
+import { isObject, parseNestedJsonText } from "../traces-import-convert.js";
+const object = (value) => isObject(value) ? value : undefined;
+const string = (value) => typeof value === "string" ? value : undefined;
+/** Tool call arguments as recorded: an OpenAI arguments string is read as the JSON it holds. */
+function argumentsOf(value) {
+    if (typeof value === "string")
+        try {
+            return parseNestedJsonText(value).value;
+        }
+        catch {
+            return value;
+        }
+    return value ?? null;
+}
+const DATA_URL = /^data:([\w.+-]+\/[\w.+-]+)?((?:;[\w.+-]+=[^;,]*)*);base64,(.*)$/s;
+/** An image, audio or file reference: a base64 data URL becomes a blob part, a URL a uri part. */
+function mediaPart(url, modality) {
+    const data = DATA_URL.exec(url);
+    if (data)
+        return {
+            type: "blob",
+            modality: data[1]?.split("/")[0] ?? modality,
+            ...(data[1] ? { mime_type: data[1] } : {}),
+            content: data[3],
+        };
+    return { type: "uri", modality, uri: url };
+}
+/** One content part of any recognized shape, or undefined when it is not one. */
+function contentPart(raw) {
+    if (typeof raw === "string")
+        return { type: "text", content: raw };
+    const part = object(raw);
+    const type = string(part?.type);
+    if (!part || !type)
+        return undefined;
+    switch (type) {
+        case "text":
+        case "input_text":
+        case "output_text": {
+            const content = string(part.text) ?? string(part.content);
+            return content === undefined ? { ...part, type } : { type: "text", content };
+        }
+        case "image_url": {
+            const url = string(object(part.image_url)?.url) ?? string(part.image_url);
+            return url === undefined ? { ...part, type } : mediaPart(url, "image");
+        }
+        case "image": {
+            const source = object(part.source);
+            if (source?.type === "base64" && typeof source.data === "string")
+                return {
+                    type: "blob",
+                    modality: "image",
+                    ...(typeof source.media_type === "string" ? { mime_type: source.media_type } : {}),
+                    content: source.data,
+                };
+            if (source?.type === "url" && typeof source.url === "string")
+                return { type: "uri", modality: "image", uri: source.url };
+            return { ...part, type };
+        }
+        case "tool_use":
+            return {
+                type: "tool_call",
+                ...(typeof part.id === "string" ? { id: part.id } : {}),
+                name: string(part.name) ?? "",
+                arguments: part.input ?? null,
+            };
+        case "tool-call":
+            return {
+                type: "tool_call",
+                ...(typeof part.toolCallId === "string" ? { id: part.toolCallId } : {}),
+                name: string(part.toolName) ?? "",
+                arguments: argumentsOf(part.input ?? part.args),
+            };
+        case "tool_result":
+            return {
+                type: "tool_call_response",
+                ...(typeof part.tool_use_id === "string" ? { id: part.tool_use_id } : {}),
+                response: part.content ?? null,
+            };
+        case "tool-result":
+            return {
+                type: "tool_call_response",
+                ...(typeof part.toolCallId === "string" ? { id: part.toolCallId } : {}),
+                response: part.output ?? part.result ?? null,
+            };
+        case "thinking":
+            return { type: "reasoning", content: string(part.thinking) ?? "" };
+        case "reasoning": {
+            const content = string(part.text) ?? string(part.content);
+            return content === undefined ? { ...part, type } : { type: "reasoning", content };
+        }
+        default:
+            return { ...part, type };
+    }
+}
+/** A message's content: a string, a list of parts or nothing; undefined when not readable. */
+function contentParts(content) {
+    if (content === undefined || content === null)
+        return [];
+    if (typeof content === "string")
+        return content ? [{ type: "text", content }] : [];
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const item of content) {
+        const part = contentPart(item);
+        if (!part)
+            return undefined;
+        parts.push(part);
+    }
+    return parts;
+}
+/** OpenAI-shaped `tool_calls` (`{id, function: {name, arguments}}`) and LangChain's
+ * (`{id, name, args}`) as tool call parts. */
+function toolCallParts(calls) {
+    if (calls === undefined || calls === null)
+        return [];
+    if (!Array.isArray(calls))
+        return undefined;
+    const parts = [];
+    for (const raw of calls) {
+        const call = object(raw);
+        if (!call)
+            return undefined;
+        const fn = object(call.function);
+        parts.push({
+            type: "tool_call",
+            ...(typeof call.id === "string" ? { id: call.id } : {}),
+            name: string(fn?.name) ?? string(call.name) ?? "",
+            arguments: fn ? argumentsOf(fn.arguments) : (call.args ?? null),
+        });
+    }
+    return parts;
+}
+const LANGCHAIN_ROLES = {
+    human: "user",
+    user: "user",
+    ai: "assistant",
+    assistant: "assistant",
+    system: "system",
+    tool: "tool",
+    function: "tool",
+};
+const LANGCHAIN_CLASSES = {
+    HumanMessage: "human",
+    HumanMessageChunk: "human",
+    AIMessage: "ai",
+    AIMessageChunk: "ai",
+    SystemMessage: "system",
+    ToolMessage: "tool",
+    FunctionMessage: "function",
+    ChatMessage: "chat",
+};
+/** A LangChain message (`{type, content}`, `{type, data}` or the serialized constructor form)
+ * as role and fields, or undefined when it is not one. */
+function langchain(message) {
+    if (message.lc === 1 && Array.isArray(message.id) && object(message.kwargs)) {
+        const kind = LANGCHAIN_CLASSES[string(message.id.at(-1)) ?? ""];
+        const fields = object(message.kwargs);
+        if (!kind)
+            return undefined;
+        const role = kind === "chat" ? string(fields.role) : LANGCHAIN_ROLES[kind];
+        return role ? { role, fields } : undefined;
+    }
+    const type = string(message.type);
+    if (!type || message.role !== undefined)
+        return undefined;
+    const fields = object(message.data) ?? message;
+    if (!("content" in fields))
+        return undefined;
+    const role = type === "chat" ? string(fields.role) : LANGCHAIN_ROLES[type];
+    return role ? { role, fields } : undefined;
+}
+/** A tool's answer as one `tool_call_response` part. */
+const responsePart = (id, response) => ({
+    type: "tool_call_response",
+    ...(typeof id === "string" ? { id } : {}),
+    response: response ?? null,
+});
+/** One message of any recognized shape, or undefined. */
+function message(raw) {
+    const item = object(raw);
+    if (!item)
+        return undefined;
+    // An OpenAI choice: the message and why the model stopped.
+    if (object(item.message) && ("finish_reason" in item || "index" in item)) {
+        const inner = message(item.message);
+        const finish = string(item.finish_reason);
+        return inner && finish ? { ...inner, finish_reason: finish } : inner;
+    }
+    // OpenAI Responses items.
+    if (item.type === "function_call")
+        return {
+            role: "assistant",
+            parts: [
+                {
+                    type: "tool_call",
+                    ...(typeof item.call_id === "string" ? { id: item.call_id } : {}),
+                    name: string(item.name) ?? "",
+                    arguments: argumentsOf(item.arguments),
+                },
+            ],
+        };
+    if (item.type === "function_call_output")
+        return { role: "tool", parts: [responsePart(item.call_id, item.output)] };
+    if (item.type === "reasoning" && Array.isArray(item.summary)) {
+        const text = item.summary.map((entry) => string(object(entry)?.text) ?? "").join("\n");
+        return { role: "assistant", parts: [{ type: "reasoning", content: text }] };
+    }
+    const chain = langchain(item);
+    if (chain) {
+        const { role, fields } = chain;
+        if (role === "tool")
+            return { role, parts: [responsePart(fields.tool_call_id, fields.content)] };
+        const parts = contentParts(fields.content);
+        const calls = toolCallParts(fields.tool_calls);
+        if (!parts || !calls)
+            return undefined;
+        return { role, parts: [...parts, ...calls], ...nameOf(fields) };
+    }
+    const role = string(item.role);
+    if (!role)
+        return undefined;
+    // Already GenAI parts.
+    if (Array.isArray(item.parts) &&
+        item.parts.every((part) => typeof object(part)?.type === "string"))
+        return { ...item };
+    if (role === "tool" || role === "function")
+        return {
+            role: "tool",
+            parts: [responsePart(item.tool_call_id, item.content)],
+            ...nameOf(item),
+        };
+    const parts = contentParts(item.content);
+    const calls = toolCallParts(item.tool_calls);
+    if (!parts || !calls)
+        return undefined;
+    const legacy = object(item.function_call);
+    if (legacy)
+        calls.push({
+            type: "tool_call",
+            name: string(legacy.name) ?? "",
+            arguments: argumentsOf(legacy.arguments),
+        });
+    const stop = string(item.stop_reason);
+    return {
+        role,
+        parts: [...parts, ...calls],
+        ...nameOf(item),
+        ...(stop ? { finish_reason: stop } : {}),
+    };
+}
+const nameOf = (fields) => typeof fields.name === "string" && fields.name ? { name: fields.name } : {};
+/**
+ * `value` as GenAI messages, or undefined when it holds no recognized chat content. A plain
+ * string is one message from `stringRole` when one is given; `{messages: […]}` and
+ * `{choices: […]}` wrappers, LangChain's batched lists and `LLMResult` generations are unwrapped.
+ */
+export function genAiMessages(value, stringRole) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return stringRole && value
+            ? [{ role: stringRole, parts: [{ type: "text", content: value }] }]
+            : undefined;
+    const wrapper = object(value);
+    if (wrapper) {
+        for (const key of ["messages", "choices"])
+            if (Array.isArray(wrapper[key]))
+                return genAiMessages(wrapper[key], stringRole);
+        if (Array.isArray(wrapper.generations)) {
+            const generations = wrapper.generations.flatMap((batch) => Array.isArray(batch) ? batch : [batch]);
+            const messages = generations.map((generation) => {
+                const entry = object(generation);
+                const inner = object(entry?.message);
+                if (inner)
+                    return message(inner);
+                const text = string(entry?.text);
+                return text === undefined
+                    ? undefined
+                    : { role: "assistant", parts: [{ type: "text", content: text }] };
+            });
+            return messages.length && messages.every(Boolean) ? messages : undefined;
+        }
+        const single = message(wrapper);
+        return single ? [single] : undefined;
+    }
+    if (!Array.isArray(value) || !value.length)
+        return undefined;
+    // LangChain records a batch of prompts as a list of message lists.
+    if (value.length === 1 && Array.isArray(value[0]))
+        return genAiMessages(value[0], stringRole);
+    const messages = [];
+    for (const raw of value) {
+        const converted = message(raw);
+        if (!converted)
+            return undefined;
+        messages.push(converted);
+    }
+    return messages;
+}

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

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