@hue-run/sdk 0.21.1 → 0.22.0

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

@@ -0,0 +1,161 @@
+import { ConversionError, isObject, parseNestedJsonText, unixNano, } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+import { nanosFrom, readRecords } from "./rows.js";
+import { requestContent, requestInstructions, responseContent } from "./transcripts.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 isRequest = (value) => isObject(value) &&
+    typeof value.request_id === "string" &&
+    "request_created_at" in value &&
+    ("response_status" in value || "request_user_id" in value || "request_properties" in value);
+/** The requests an API answer (`{"data": […]}`) holds, when it holds any. */
+function envelopeRequests(value) {
+    return isObject(value) && Array.isArray(value.data) && value.data.some(isRequest)
+        ? value.data
+        : undefined;
+}
+/** A body as recorded, JSON text parsed; Helicone's placeholder for an unfetched body is none. */
+function body(value) {
+    let parsed = value;
+    if (typeof value === "string") {
+        if (!value)
+            return undefined;
+        try {
+            parsed = parseNestedJsonText(value).value;
+        }
+        catch {
+            return value;
+        }
+    }
+    const fields = object(parsed);
+    if (fields && Object.keys(fields).length === 1 && "helicone_message" in fields)
+        return undefined;
+    return parsed ?? undefined;
+}
+/** A duration in milliseconds as nanoseconds; zero is allowed. */
+const milliseconds = (value) => (value === 0 ? 0n : nanosFrom(value, "ms"));
+/** Properties that mark Helicone's own evaluation traffic, lower-cased as Helicone compares
+ * them. */
+const EVALUATION_PROPERTIES = new Set(["helicone-experiment-id", "helicone-evaluator"]);
+/** The request's path: `target_url`'s, else `request_path` (the older Postgres export's). */
+function pathOf(record) {
+    const target = text(record.target_url);
+    if (target)
+        try {
+            return new URL(target).pathname;
+        }
+        catch {
+            // Not a URL: the recorded path, if any, is read instead.
+        }
+    return text(record.request_path) ?? "";
+}
+/** Input and output as the GenAI conventions count them: Helicone's counts with the cached and
+ * reasoning tokens it took out added back. */
+function usageOf(record) {
+    const prompt = count(record.prompt_tokens);
+    const completion = count(record.completion_tokens);
+    const cacheRead = count(record.prompt_cache_read_tokens);
+    const cacheWrite = count(record.prompt_cache_write_tokens);
+    const reasoning = count(record.reasoning_tokens);
+    return {
+        input: prompt === undefined ? undefined : prompt + (cacheRead ?? 0) + (cacheWrite ?? 0),
+        output: completion === undefined ? undefined : completion + (reasoning ?? 0),
+        cacheRead,
+        cacheWrite,
+        reasoning,
+    };
+}
+function readRequest(record, context) {
+    const requestId = text(record.request_id);
+    if (!requestId)
+        throw new ConversionError("a request without a request_id");
+    const properties = object(record.request_properties) ?? object(record.properties);
+    for (const key of ["request_properties", "properties"])
+        if (record[key] != null && !object(record[key]))
+            throw new ConversionError(`${key} is not an object`);
+    const session = identityText(properties?.["Helicone-Session-Id"]);
+    if (typeof record.request_created_at !== "string")
+        throw new ConversionError("a request without request_created_at");
+    const start = BigInt(unixNano(record.request_created_at));
+    let end;
+    let timing;
+    if (text(record.response_created_at))
+        end = BigInt(unixNano(record.response_created_at));
+    else if (typeof record.delay_ms === "number" && record.delay_ms >= 0) {
+        end = start + milliseconds(record.delay_ms);
+        timing = "end_from_latency";
+    }
+    const path = pathOf(record);
+    const embedding = /\/embeddings\/?$/.test(path);
+    const requestBody = body(record.request_body);
+    const responseBody = body(record.response_body);
+    const recorded = text(record.model);
+    const model = text(record.model_override) ??
+        text(record.request_model) ??
+        (recorded !== "unknown" ? recorded : undefined);
+    const status = record.response_status;
+    const system = embedding ? undefined : requestInstructions(requestBody);
+    const user = identityText(record.request_user_id);
+    const cost = typeof record.cost === "number" ? record.cost : record.costUSD;
+    const row = {
+        traceKey: session ?? requestId,
+        spanKey: requestId,
+        name: `${embedding ? "embeddings" : "chat"}${model ? ` ${model}` : ""}`,
+        kind: embedding ? "embedding" : "llm",
+        start,
+        ...(end !== undefined ? { end } : {}),
+        ...(timing ? { timing } : {}),
+        ...(model ? { model } : {}),
+        ...(text(record.response_model) ? { responseModel: text(record.response_model) } : {}),
+        ...(text(record.provider) ? { provider: text(record.provider).toLowerCase() } : {}),
+        ...(requestBody !== undefined
+            ? { input: embedding ? requestBody : requestContent(requestBody) }
+            : {}),
+        ...(responseBody !== undefined ? { output: responseContent(responseBody) } : {}),
+        ...(system !== undefined ? { systemInstructions: system } : {}),
+        usage: usageOf(record),
+        ...(user !== undefined ? { user } : {}),
+        ...(session !== undefined ? { session } : {}),
+        attributes: {
+            ...(properties && Object.keys(properties).length
+                ? { "helicone.properties": JSON.stringify(properties) }
+                : {}),
+            ...(text(properties?.["Helicone-Session-Path"])
+                ? { "helicone.session.path": text(properties?.["Helicone-Session-Path"]) }
+                : {}),
+            ...(text(properties?.["Helicone-Session-Name"])
+                ? { "helicone.session.name": text(properties?.["Helicone-Session-Name"]) }
+                : {}),
+            ...(path ? { "helicone.request.path": path } : {}),
+            ...(typeof cost === "number" && Number.isFinite(cost) ? { "helicone.cost_usd": cost } : {}),
+        },
+        record,
+        ...(text(record.updated_at) ? { revision: text(record.updated_at) } : {}),
+    };
+    if (Object.keys(properties ?? {}).some((key) => EVALUATION_PROPERTIES.has(key.toLowerCase())))
+        row.origin = "evaluation";
+    if (typeof status === "number" && status >= 400) {
+        const message = text(object(object(responseBody)?.error)?.message);
+        row.error = { message: message ?? `HTTP ${status}`, type: String(status) };
+    }
+    context.row(row);
+}
+export const helicone = {
+    id: "helicone",
+    manifestFormat: "otlp_json",
+    detect: (value) => isRequest(value) || envelopeRequests(value) !== undefined,
+    convert(value, context) {
+        const records = isRequest(value) ? [value] : (envelopeRequests(value) ?? []);
+        readRecords(context, records, (record) => {
+            if (!isRequest(record))
+                return undefined;
+            const properties = object(record.request_properties) ?? object(record.properties);
+            return identityText(properties?.["Helicone-Session-Id"]) ?? text(record.request_id);
+        }, (record) => {
+            if (!isRequest(record))
+                throw new ConversionError("a record that is not a Helicone request");
+            readRequest(record, context);
+        });
+    },
+};

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

@@ -0,0 +1,112 @@
+import { type ConvertedTrace, type ImportEntry, type JsonValue, type TraceIdentity } from "../traces-import-convert.js";
+/**
+ * Who a trace ran for and which conversation it belongs to, read the way Hue reads a trace it
+ * receives, so the manifest's identity and the report's `without_identity` say what Hue will
+ * capture. Two parts, both copied from Hue's reader and kept in its order:
+ *
+ * - The identity registry: the attributes and metadata fields instrumentations name a user or a
+ *   conversation by, first present wins on a record.
+ * - The owner rule: a trace's local roots (no parent, or a parent outside the trace) speak first;
+ *   when they name nobody, the agent's other spans do. A tool span and everything beneath it never
+ *   name the owner. Every carrier at the deciding step must agree, and an explicit
+ *   `hue.world.entity.*` declaration wins over users.
+ *
+ * `--user-key` and `--session-key` name the identity of exports whose user sits under a key of
+ * their own; see {@link parseKeyPath} and {@link applyIdentityKeys}.
+ */
+/** Dedicated attributes, in precedence order. */
+declare const DEDICATED: {
+    readonly user: readonly ["user.id", "enduser.id", "hue.user.id", "ai.telemetry.metadata.userId", "langfuse.user.id", "enduser.pseudo.id", "mlflow.trace.user", "mastra.metadata.resourceId"];
+    readonly session: readonly ["gen_ai.conversation.id", "session.id", "hue.session.id", "ai.telemetry.metadata.sessionId", "langfuse.session.id", "mlflow.trace.session"];
+};
+export type IdentityKind = keyof typeof DEDICATED;
+/** Whether Hue reads an owner or a conversation from an attribute of this name. */
+export declare const namesIdentity: (key: string) => boolean;
+/** A recorded attribute without what Hue would read a `kind` identifier from: undefined for an
+ * attribute that names one itself, and a metadata map without the kind's fields. */
+export declare function withoutIdentity(kind: IdentityKind, key: string, value: JsonValue): JsonValue | undefined;
+/** An identifier as recorded: a non-blank string, or an integer as its decimal text. */
+export declare function identityText(value: unknown): string | undefined;
+/** The record's `kind` identifier: the first registry key it carries. `read` answers an
+ * attribute in source form (an int64 as its decimal text, a kvlist as an object). */
+export declare function readIdentity(kind: IdentityKind, read: (key: string) => unknown): string | undefined;
+/** Whether Hue reads the span as a tool call: its operation names one, or an instrumentation
+ * convention reads a tool from its attributes. */
+export declare function isToolSpan(attributes: ReadonlyMap<string, JsonValue>): boolean;
+/** One span of a trace as the owner rule sees it. */
+export interface SpanView {
+    spanId: string;
+    parentSpanId?: string;
+    start: bigint;
+    attributes: Map<string, JsonValue>;
+    resource: Map<string, JsonValue>;
+    /** The span object as emitted, for a key path into it. */
+    span: Record<string, unknown>;
+}
+export declare function spanViews(entries: readonly ImportEntry[]): SpanView[];
+/** The ids of the spans `marked` picks and of every span beneath one, walked from them down
+ * without recursion; a parent chain that closes on itself reaches nothing marked on its own. */
+export declare function subtreeIds<T extends {
+    spanId: string;
+    parentSpanId?: string;
+}>(spans: readonly T[], marked: (span: T) => boolean): Set<string>;
+/** The spans the agent itself recorded, split into local roots and the rest: a tool span and
+ * every span beneath one are left out. */
+export declare function agentSpans<T extends {
+    spanId: string;
+    parentSpanId?: string;
+}>(spans: readonly T[], tool: (span: T) => boolean): {
+    roots: T[];
+    others: T[];
+};
+/** The trace's identity as Hue will capture it from these spans: the owner (an explicit entity or
+ * a user) and the session. */
+export declare function traceIdentity(entries: readonly ImportEntry[]): TraceIdentity | undefined;
+/** Where `--user-key` or `--session-key` reads: a JSON path into a span's source record, or a
+ * dotted key looked up on the span and its record. */
+export type KeyPath = {
+    kind: "pointer";
+    segments: string[];
+    text: string;
+} | {
+    kind: "dotted";
+    key: string;
+    text: string;
+};
+export interface IdentityKeys {
+    user?: KeyPath;
+    session?: KeyPath;
+}
+/**
+ * A key path from its command-line text, or undefined when it is malformed:
+ * - `/a/b` is a JSON Pointer into the source record (`~1` for `/`, `~0` for `~`);
+ * - `$.a.b`, `$.a["b.c"]` or `$.a[0]` is a JSONPath of members and indexes into the record;
+ * - anything else is a dotted key: an attribute of the span or its resource, then a key of the
+ *   record's metadata (exact, then as a dotted path), then of the record itself.
+ */
+export declare function parseKeyPath(text: string): KeyPath | undefined;
+/** What a key path names on one span, as an identifier. */
+export declare function resolveKey(path: KeyPath, view: {
+    attributes: ReadonlyMap<string, unknown>;
+    resource?: ReadonlyMap<string, unknown>;
+}, record: unknown, metadata?: unknown): string | undefined;
+/** The single value a key names across the agent's spans: the roots' when they name one, else
+ * the other spans'; spans that disagree name nothing. */
+export declare function decideKey<T extends {
+    spanId: string;
+    parentSpanId?: string;
+}>(spans: readonly T[], tool: (span: T) => boolean, value: (span: T) => string | undefined): {
+    found: boolean;
+    value?: string;
+};
+/**
+ * Applies `--user-key` and `--session-key` to a trace whose spans are kept as converted (OTLP,
+ * Langfuse, ATIF): a span's bytes never change, so a trace also sent live does not conflict.
+ * When a key names one user across the agent's spans and the trace names no owner, a child span
+ * `hue.import.user` with the single attribute `user.id` is added under the agent's earliest local
+ * root (never a tool span), which Hue reads as one of the agent's spans; `hue.import.session` with
+ * `gen_ai.conversation.id` likewise names a session the trace lacks. An owner the spans already
+ * name is kept: Hue reads it before any added span.
+ */
+export declare function applyIdentityKeys(trace: ConvertedTrace, keys: IdentityKeys): void;
+export {};