@hue-run/sdk 0.18.0 → 0.18.1

package/dist/cli/langfuse.d.ts

@@ -0,0 +1,309 @@
+import { type AttributeValue, type HrTime } from "@opentelemetry/api";
+import type { Resource } from "@opentelemetry/resources";
+import type { ReadableSpan } from "@opentelemetry/sdk-trace";
+import { type BlobUploader, type UploadContext } from "../blobs.js";
+import { type InlineFilePart, type MediaValue } from "../inline-files.js";
+/** The Langfuse project an import reads and how it waits. */
+export interface LangfuseConnection {
+    /** The API's base URL, `https://cloud.langfuse.com` or a self-hosted origin, without a trailing
+     * slash. */
+    baseUrl: string;
+    publicKey: string;
+    secretKey: string;
+    fetch?: typeof fetch;
+    /** Waits `ms`; resolves early when the import is stopped. */
+    sleep: (ms: number) => Promise<void>;
+    signal: AbortSignal;
+    /** Told about each wait for a rate limit or a failed request, in whole seconds. */
+    onWait?: (seconds: number, reason: string) => void;
+}
+/** A request Langfuse refused or did not answer; `fatal` stops the whole import. */
+export declare class LangfuseError extends Error {
+    readonly status?: number | undefined;
+    readonly fatal: boolean;
+    constructor(message: string, status?: number | undefined, fatal?: boolean);
+}
+/** The import was stopped while a request was waiting. */
+export declare class ImportStopped extends Error {
+    constructor();
+}
+/** A trace's time window, as ISO 8601 instants. */
+export interface ImportWindow {
+    from?: string;
+    to?: string;
+}
+/** The API a Langfuse deployment reads traces through: `v2` (Langfuse Cloud and self-hosted v4
+ * and later, observations with cursor pages) or `v1` (self-hosted v3, traces and observations
+ * with numbered pages). */
+export type LangfuseApiVersion = "v1" | "v2";
+/** A Langfuse observation as the v1 or v2 API returns it, only the fields the import reads. */
+export interface LangfuseObservation {
+    id: string;
+    traceId: string;
+    type?: string;
+    name?: string;
+    startTime: string;
+    endTime?: string;
+    completionStartTime?: string;
+    parentObservationId?: string;
+    level?: string;
+    statusMessage?: string;
+    version?: string;
+    environment?: string;
+    input?: unknown;
+    output?: unknown;
+    metadata?: unknown;
+    model?: string;
+    modelParameters?: unknown;
+    usageDetails?: Record<string, unknown>;
+    costDetails?: Record<string, unknown>;
+    promptName?: string;
+    promptVersion?: number;
+    userId?: string;
+    sessionId?: string;
+    traceName?: string;
+    tags?: string[];
+    release?: string;
+}
+/** A Langfuse v1 trace, the fields the import reads. */
+export interface LangfuseTrace {
+    id: string;
+    timestamp: string;
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    metadata?: unknown;
+    sessionId?: string;
+    userId?: string;
+    release?: string;
+    version?: string;
+    tags?: string[];
+    public?: boolean;
+    environment?: string;
+}
+/** An observation from an API answer, or undefined when it lacks the fields every span needs. */
+export declare function readObservation(value: unknown): LangfuseObservation | undefined;
+/** A v1 trace from an API answer, or undefined when it lacks an id or timestamp. */
+export declare function readTrace(value: unknown): LangfuseTrace | undefined;
+/** An answer read whole: its status and body, or `tooLarge` for a body past the bound. */
+type Answer = {
+    status: number;
+    body: Buffer;
+} | {
+    status: number;
+    tooLarge: true;
+};
+/** Reads one Langfuse project through its public API with Basic authentication. */
+export declare class LangfuseApi {
+    private readonly connection;
+    private readonly fetchImpl;
+    private readonly authorization;
+    private readonly seen;
+    constructor(connection: LangfuseConnection);
+    private stopped;
+    private wait;
+    /**
+     * One GET with retries: a rate limit (HTTP 429) is waited out for as long as its `Retry-After`
+     * asks (up to 15 minutes, ten times in a row), and a connection failure, a timeout or a 5xx is
+     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). An
+     * authenticated request never follows a redirect, so the keys go only to the configured host;
+     * `authenticated` is false for a presigned media download, which carries no Langfuse keys.
+     */
+    get(url: URL, authenticated?: boolean, maxBytes?: number, timeoutMs?: number): Promise<Answer>;
+    /** A GET of `path` under the API, answered with JSON; refusals of the keys are fatal. */
+    private json;
+    /** Which API the deployment reads traces through: v2 unless it answers that it has none. */
+    version(): Promise<LangfuseApiVersion>;
+    /** Whether a trace id has not been listed before in this import. */
+    private first;
+    /** The ids of the traces whose root observations started in the window, newest first. */
+    rootTraceIds(window: ImportWindow): AsyncGenerator<string>;
+    /** A trace's observations through the v2 API, a page at a time. */
+    v2Observations(traceId: string): AsyncGenerator<LangfuseObservation[]>;
+    /** The v1 traces whose timestamp falls in the window, newest first. */
+    v1Traces(window: ImportWindow): AsyncGenerator<LangfuseTrace>;
+    /** One v1 trace by id, or undefined when Langfuse holds none. */
+    v1Trace(traceId: string): Promise<LangfuseTrace | undefined>;
+    /** A trace's observations through the v1 API, a page at a time. */
+    v1Observations(traceId: string): AsyncGenerator<LangfuseObservation[]>;
+    private page;
+    private observations;
+    /**
+     * A media file's bytes through `GET /api/public/media/{id}` and the download link it answers
+     * (fetched without the Langfuse keys): `missing` when Langfuse holds no bytes for it (no record,
+     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}.
+     */
+    media(id: string): Promise<Uint8Array | "missing" | "tooLarge">;
+}
+/** The OpenTelemetry trace id of a Langfuse trace: its own id when it is one (32 lowercase hex
+ * digits, as the Langfuse OpenTelemetry SDKs write), otherwise one derived from it by SHA-256, so
+ * the same trace always takes the same id. */
+export declare function hueTraceId(langfuseTraceId: string): string;
+/** The OpenTelemetry span id of a Langfuse observation: its own id when it is one (16 lowercase
+ * hex digits), otherwise one derived from the trace's and its own id. */
+export declare function hueSpanId(langfuseTraceId: string, observationId: string): string;
+/** The span id of the span that stands for a v1 trace itself. */
+export declare function traceSpanId(langfuseTraceId: string): string;
+/** An ISO 8601 instant as OpenTelemetry time, keeping up to nanosecond digits; undefined for
+ * anything else. */
+export declare function hrTimeOf(value: string | undefined): HrTime | undefined;
+/** The time a set of spans covers, from the earliest start to the latest end. */
+export interface TimeBounds {
+    start: HrTime;
+    end: HrTime;
+}
+/** `bounds` widened to cover `span`. */
+export declare function widen(bounds: TimeBounds | undefined, span: TimeBounds): TimeBounds;
+/** A span before it is handed to the exporter. */
+export interface ImportSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    start: HrTime;
+    end: HrTime;
+    attributes: Record<string, AttributeValue>;
+    /** Set for an observation at level `ERROR`: the span's status is an error with this message. */
+    error?: string;
+}
+/** What a v1 trace gives each of its observations, as the Langfuse SDKs propagate it. */
+export interface TraceContext {
+    langfuseTraceId: string;
+    /** The v1 trace's own span, the parent of its observations without one. */
+    rootSpanId?: string;
+    name?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    release?: string;
+}
+/**
+ * A Langfuse observation as the span the Langfuse OpenTelemetry SDKs would have recorded:
+ * `langfuse.observation.*` (type in lower case, input, output, one `metadata.<key>` attribute per
+ * key, level, status message, model, model parameters, usage and cost details, completion start,
+ * prompt), `langfuse.trace.name`, `langfuse.trace.tags`, `langfuse.user.id`,
+ * `langfuse.session.id`, `langfuse.release`, `langfuse.version` and `langfuse.environment`, with
+ * `gen_ai.request.model` and the input and output token counts as GenAI attributes. The
+ * observation's and trace's own ids are kept as `langfuse.observation.id` and
+ * `langfuse.trace.id`. Throws for a start time that is no ISO 8601 instant.
+ */
+export declare function observationSpan(observation: LangfuseObservation, context: TraceContext): ImportSpan;
+/** The context a v1 trace gives its observations. */
+export declare function traceContext(trace: LangfuseTrace): TraceContext;
+/**
+ * The span that stands for a v1 trace, the parent of its observations without one, as the trace
+ * Langfuse shows above them: `langfuse.trace.*` (name, input, output, one `metadata.<key>`
+ * attribute per key, tags, public), the user, session, release, version and environment. It
+ * covers the trace's timestamp and its observations, `observed`. Throws for a timestamp that is
+ * no ISO 8601 instant.
+ */
+export declare function traceSpan(trace: LangfuseTrace, observed: TimeBounds | undefined): ImportSpan;
+/** A converted span as the OpenTelemetry SDK hands a finished span to a processor. */
+export declare function readableSpan(span: ImportSpan, resource: Resource, scope: {
+    name: string;
+}): ReadableSpan;
+/** A Langfuse media reference, as the Langfuse SDKs write it in place of a file they uploaded. */
+export interface MediaToken {
+    type: string;
+    id: string;
+    source: string;
+}
+/** The token a whole string is (`@@@langfuseMedia:type=<media type>|id=<id>|source=<source>@@@`),
+ * or undefined when it is not exactly one. */
+export declare function parseMediaToken(value: string): MediaToken | undefined;
+/** The span attributes whose text Hue reads files from and the import rewrites tokens in. */
+export declare function isMediaAttribute(key: string): boolean;
+/** One token found where Hue reads a file, and the place it takes once its bytes are uploaded. */
+export interface MediaUse {
+    attribute: string;
+    token: MediaToken;
+    /** The token's JSON pointer in the attribute's value. */
+    pointer: string;
+    /** The `hue.blobs` key the file is listed under: `<attribute>#<pointer of its part>`. */
+    key: string;
+}
+/** The tokens of one attribute and the SDK's reading of its value with each token's place. */
+interface AttributeMedia {
+    attribute: string;
+    uses: MediaUse[];
+    media: MediaValue;
+    /** The files of `media` at each use's pointer. */
+    files: Map<string, InlineFilePart>;
+}
+/** The tokens a span carries: where each takes a file's place, and how many stay as they are
+ * (inside longer text, deeper than Hue reads, or in a place Hue reads no file from). */
+export interface SpanMedia {
+    attributes: AttributeMedia[];
+    kept: number;
+}
+/** The tokens of a span's media attributes. */
+export declare function spanMedia(span: ImportSpan): SpanMedia;
+/** A token's file once its bytes were read and uploaded under the span's trace. */
+export interface UploadedMedia {
+    sha256: string;
+    size: number;
+    /** The media type Hue stored the file under. */
+    contentType: string;
+}
+/** What became of one token's file. */
+export type MediaOutcome = {
+    kind: "uploaded";
+    file: UploadedMedia;
+}
+/** Langfuse holds no bytes for it, or more than an import reads: it stays a token. */
+ | {
+    kind: "kept";
+}
+/** Its bytes could not be read or stored now: the span is not sent, so a later run can. */
+ | {
+    kind: "failed";
+    reason: string;
+};
+/**
+ * The span's attributes with each token whose file was uploaded in the digest form the SDK
+ * writes for a recorded file, `{"type":"blob","mime_type","modality","sha256","size"}` for a
+ * whole string or the provider part with its bytes removed and `sha256` and `size` set, every
+ * other byte of the attribute's text kept, and each file listed under `hue.blobs` as
+ * `<attribute>#<pointer>`. At most {@link MAX_BLOB_ENTRIES} files per span are placed; the rest
+ * stay tokens. Returns how many were placed.
+ */
+export declare function placeMedia(span: ImportSpan, media: SpanMedia, outcomes: ReadonlyMap<MediaUse, UploadedMedia>): number;
+/** The uses of a span that may be uploaded: the first {@link MAX_BLOB_ENTRIES} with a key Hue
+ * accepts. */
+export declare function uploadableUses(media: SpanMedia): {
+    uses: MediaUse[];
+    kept: number;
+};
+/**
+ * Reads each file of a trace's tokens from Langfuse once and uploads it under the trace with the
+ * SDK's upload route (reservation, presigned PUT, completion); another reference to the same
+ * file in the trace reuses the outcome. Bytes are held only while their file uploads.
+ */
+export declare class TraceMedia {
+    private readonly api;
+    private readonly uploader;
+    private readonly traceId;
+    private readonly upload;
+    private readonly outcomes;
+    constructor(api: LangfuseApi, uploader: BlobUploader, traceId: string, upload: () => UploadContext);
+    /** The outcome for a token's file, read and uploaded on its first use in the trace. */
+    file(use: MediaUse): Promise<MediaOutcome>;
+    private fresh;
+}
+/**
+ * The rest of a span's content stored as the SDK's exporter stores it, but before the span is
+ * sent: files inline in the attributes Hue reads files from (a `data:` URL or base64 a provider
+ * part holds) uploaded and placed in their digest form, and text values still over Hue's inline
+ * limit (1 MiB of UTF-8, the limit Hue advertises) uploaded whole and replaced by their first
+ * 16 KiB, each listed in `hue.blobs` (and a whole value in `hue.truncated`). This is the
+ * exporter's own placement (`offloadAttributes`), run here so that a file or value that cannot be
+ * stored now holds its span back rather than being kept inline or cut, and every run sends the
+ * same span. A file or value over a limit (Hue's size limit, the span's 64 entries) is placed
+ * alike on every run and only counted. Resolves to the reason the span is held back, if it is.
+ */
+export declare function storeSpanContent(span: ImportSpan, uploader: BlobUploader, upload: UploadContext): Promise<{
+    heldBack?: string;
+    stored: number;
+    overLimits: number;
+}>;
+export {};