@hue-run/sdk 0.17.0 → 0.18.0

package/dist/evals/media.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Reading recorded media back. A trace records a large file as a digest part: the provider part
+ * with its content field removed and the file's `sha256` and `size` added, its bytes uploaded
+ * under the record's `hue.blobs`. `fetch` downloads one file by digest through a short-lived
+ * link Hue issues; `resolve` and {@link rehydrateMedia} put the bytes back into the parts of a
+ * recorded value, in the field and encoding each part's shape uses.
+ */
+/** Why a media read failed. */
+export type MediaFetchErrorReason = 
+/** Hue holds no such file for the trace or snapshot: an unknown trace, another project's, or a
+ * digest none of its records list (with `spanId`, that span's record). */
+"not_found"
+/** The trace lists the file, but its bytes were never uploaded or have been erased. */
+ | "missing"
+/** Hue could not read its evidence store, again after one retry; `retryAfterSeconds` says when
+ * to ask again. */
+ | "unavailable"
+/** The key cannot read recorded content: use a Read or Read and write key, and a Read and write
+ * key for a snapshot's copy. */
+ | "forbidden"
+/** The file is larger than `maxBytes`; nothing was downloaded. */
+ | "too_large"
+/** The downloaded bytes do not have the requested SHA-256 or the size Hue reported. */
+ | "digest_mismatch"
+/** A connection failure, a timeout, an unexpected status or an invalid response. */
+ | "failed";
+/** Thrown by {@link MediaClient.fetch}. The message is fixed and never includes response text. */
+export declare class MediaFetchError extends Error {
+    /** What failed. */
+    readonly reason: MediaFetchErrorReason;
+    /** HTTP status of the answer that failed, when there was one. */
+    readonly status?: number | undefined;
+    /** Seconds Hue asked the caller to wait, on `unavailable`, when it said. */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(
+    /** What failed. */
+    reason: MediaFetchErrorReason, 
+    /** HTTP status of the answer that failed, when there was one. */
+    status?: number | undefined, 
+    /** Seconds Hue asked the caller to wait, on `unavailable`, when it said. */
+    retryAfterSeconds?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** One recorded file, downloaded and checked against its digest. */
+export interface MediaFile {
+    /** The file's bytes; their SHA-256 is `sha256`. */
+    bytes: Uint8Array;
+    /** Lowercase hex SHA-256 of `bytes`, as requested. */
+    sha256: string;
+    /** Byte length of `bytes`. */
+    size: number;
+    /** The media type the record lists for the file; absent for a snapshot's copy, whose type is
+     * the part's own. */
+    contentType?: string;
+    /** The recorded file name as Hue serves it; absent for a snapshot's copy. */
+    fileName?: string;
+}
+/** The file {@link MediaClient.fetch} reads: from a trace, or from a snapshot's pinned copy. */
+export type MediaFetchTarget = {
+    /** Hue trace ID (UUID) or the 32-hex OpenTelemetry trace ID. */
+    traceId: string;
+    /** Lowercase hex SHA-256 the part records. */
+    sha256: string;
+    /** 16-hex OpenTelemetry span ID of the span that recorded the part. Pass it when known: Hue
+     * then reads that span's record alone instead of searching the trace. */
+    spanId?: string;
+    /** Not set when reading a live trace's file. */
+    snapshotId?: undefined;
+} | {
+    /** Trace snapshot ID (UUID), such as the one a case converted from a trace keeps. Reading
+     * its copy needs a Read and write key. */
+    snapshotId: string;
+    /** Lowercase hex SHA-256 the part records. */
+    sha256: string;
+    /** Not set when reading a snapshot's pinned copy. */
+    traceId?: undefined;
+    /** Not set when reading a snapshot's pinned copy. */
+    spanId?: undefined;
+};
+/** Options for {@link MediaClient.fetch}. */
+export interface MediaFetchOptions {
+    /** Largest file read into memory, in bytes; a larger one fails with `too_large` before any byte
+     * is downloaded. Default 64 MiB, at most 1 GB. */
+    maxBytes?: number;
+    /** Ends the request, the retry wait and the download. */
+    signal?: AbortSignal;
+}
+/** Where {@link MediaClient.resolve} reads the files of a recorded value from, and how it writes
+ * them. */
+export type MediaResolveOptions = ({
+    /** Hue trace ID (UUID) or the 32-hex OpenTelemetry trace ID the value was recorded in. */
+    traceId: string;
+    /** 16-hex OpenTelemetry span ID of the span that recorded the value. */
+    spanId?: string;
+    /** Not set when resolving a live trace's files. */
+    snapshotId?: undefined;
+} | {
+    /** Trace snapshot ID whose pinned copies hold the files; reading them needs a Read and
+     * write key. */
+    snapshotId: string;
+    /** Not set when resolving a snapshot's pinned copies. */
+    traceId?: undefined;
+    /** Not set when resolving a snapshot's pinned copies. */
+    spanId?: undefined;
+}) & MediaWriteOptions & {
+    /** The `hue.blobs` entries of the record the value was read from, in any form Hue reads: an
+     * array of compact JSON object strings (what the SDKs write), an array of objects, or one
+     * string holding the JSON array. A part that declares no media type, read from a copy that
+     * carries none (a snapshot's), takes the type of the entry with its SHA-256 for its `data:`
+     * URL, rather than `application/octet-stream`. A part whose content field an entry names and
+     * that holds only the first 16 KiB of its file is reported as `prefix_only`. Entries that do
+     * not parse are ignored. */
+    blobs?: readonly (string | Readonly<Record<string, unknown>>)[] | string;
+    /** Files downloaded at once, 1–16. Default 4. */
+    concurrency?: number;
+    /** Largest file read, as in {@link MediaFetchOptions.maxBytes}. */
+    maxBytes?: number;
+    /** Ends every request and download. */
+    signal?: AbortSignal;
+};
+/** How resolved bytes are written into a part. */
+export interface MediaWriteOptions {
+    /**
+     * `"dataUrl"` (the default) writes text: a `data:` URL where the part's field takes one (OpenAI
+     * `image_url` and `file_data`, Responses `input_image`, `input_file` and `computer_screenshot`,
+     * AI SDK `image` and `file` `data`), and bare base64 where its convention requires it (GenAI
+     * `blob` `content`, OpenAI `input_audio` and assistant `audio` `data`, Anthropic `source.data`,
+     * Gemini `inlineData.data`, Vertex `media` `data`, Bedrock `source.bytes`), so the value can be
+     * sent to the provider again. `"bytes"` writes the `Uint8Array` itself in the same field.
+     */
+    as?: "dataUrl" | "bytes";
+}
+/** A part {@link MediaClient.resolve} or {@link rehydrateMedia} left unchanged. */
+export interface MediaResolveFailure {
+    /** RFC 6901 JSON pointer of the part in the value. */
+    pointer: string;
+    /** The SHA-256 the part records, or for `prefix_only` the SHA-256 of the entry naming its
+     * content field. */
+    sha256: string;
+    /** Why its bytes were not written: as {@link MediaFetchError.reason}, `not_found` when no local
+     * file has the digest, or `prefix_only` for a part whose content field holds only the first
+     * 16 KiB of its file, as a `blobs` entry names it; {@link MediaClient.fetch} returns that file
+     * whole. */
+    reason: MediaFetchErrorReason | "prefix_only";
+}
+/** A recorded value with the bytes of its digest parts written back. */
+export interface MediaResolution<T = unknown> {
+    /** A new value: the input is never changed. Each resolved part holds its bytes in its content
+     * field and no longer carries `sha256` and `size`. */
+    value: T;
+    /** Parts whose bytes were written. */
+    resolved: number;
+    /** Parts left unchanged, in reading order. */
+    failures: MediaResolveFailure[];
+}
+/** A local copy of a file {@link rehydrateMedia} reads by digest: a runner's verified case file
+ * (`LocalFile`, read from `path`) or bytes already in memory. */
+export type MediaSourceFile = {
+    /** Lowercase hex SHA-256 of the file's bytes. */
+    sha256: string;
+    /** The file's media type, used when the part declares none. */
+    contentType?: string;
+} & ({
+    /** Path of the file on this machine. */
+    path: string;
+    /** Not set when the file is given as a path. */
+    bytes?: undefined;
+} | {
+    /** The file's bytes. */
+    bytes: Uint8Array;
+    /** Not set when the file is given as bytes. */
+    path?: undefined;
+});
+/** The least time a download may go without a byte before it ends: two minutes. Tests shorten it;
+ * it is not exported from the package. */
+export declare const mediaDownload: {
+    minIdleMillis: number;
+};
+/**
+ * Hue's media reads, `client.media`: one recorded file by digest (`fetch`), and every digest part
+ * of a recorded value written back with its bytes (`resolve`). The project key is sent to Hue
+ * only; the file itself comes from a short-lived link fetched without it.
+ */
+export declare class MediaClient {
+    #private;
+    /**
+     * Downloads one recorded file and checks it against its digest: from a trace (Hue reads the
+     * span's record that lists the digest under `hue.blobs`) or from a snapshot's pinned copy. A
+     * read Hue answers as unavailable (503 or 429) is asked once more after its `Retry-After`, at
+     * most 10 seconds, and so is one that lost its connection or timed out.
+     *
+     * @throws MediaFetchError for a file Hue does not hold, a refused key, an unavailable store, a
+     * file over `maxBytes`, bytes that do not match the digest or a failed request.
+     * @throws TypeError for an invalid trace, span or snapshot ID or digest.
+     */
+    fetch(target: MediaFetchTarget, options?: MediaFetchOptions): Promise<MediaFile>;
+    /**
+     * Writes the bytes of every digest part in `value` back into its content field, the reverse of
+     * the SDK's media capture: each distinct digest is downloaded once with {@link fetch}, at most
+     * `concurrency` at a time. Returns a new value; a part whose file cannot be read stays as it is
+     * and is reported in `failures`. Parse attributes recorded as JSON text (such as
+     * `gen_ai.input.messages`) before passing them; pass the record's `hue.blobs` as `blobs` when
+     * reading a snapshot, whose copies carry no media type.
+     *
+     * @throws TypeError for invalid identifiers or options; never for one file's failure.
+     */
+    resolve<T>(value: T, options: MediaResolveOptions): Promise<MediaResolution<T>>;
+}
+/**
+ * Writes case files back into the digest parts of a case's inputs, by SHA-256: the files a runner
+ * hands a target (`context.files`) or any bytes the caller holds, so a target can send the
+ * recorded model call again with the real image, document or audio. Each file is read once and
+ * checked against its digest; a part with no matching file, or whose file does not match, stays
+ * as it is and is reported in `failures`. Returns a new value; the input is never changed.
+ */
+export declare function rehydrateMedia<T>(value: T, files: readonly MediaSourceFile[], options?: MediaWriteOptions): Promise<MediaResolution<T>>;