@arizeai/phoenix-client 5.2.1 → 5.3.0

package/dist/esm/types/experiments.d.ts

@@ -1,6 +1,6 @@
 import { AnnotatorKind } from "./annotations.js";
 import { Node } from "./core.js";
-import { Example } from "./datasets.js";
+import { Example, ExampleWithId } from "./datasets.js";
 /**
  * An experiment is a set of task runs on a dataset version
  */
@@ -9,16 +9,73 @@ export interface ExperimentInfo extends Node {
     datasetVersionId: string;
     datasetSplits?: string[];
     /**
-     * The project under which the experiment task traces are recorded
+     * Number of times the experiment is repeated
      */
-    projectName: string;
+    repetitions: number;
     /**
      * Metadata about the experiment as an object of key values
      * e.x. model name
      */
     metadata: Record<string, unknown>;
+    /**
+     * The project under which the experiment task traces are recorded
+     * Note: This can be null when no project is associated with the experiment
+     */
+    projectName: string | null;
+    /**
+     * The creation timestamp of the experiment
+     */
+    createdAt: string;
+    /**
+     * The last update timestamp of the experiment
+     */
+    updatedAt: string;
+    /**
+     * Number of examples in the experiment
+     */
+    exampleCount: number;
+    /**
+     * Number of successful runs in the experiment
+     */
+    successfulRunCount: number;
+    /**
+     * Number of failed runs in the experiment
+     */
+    failedRunCount: number;
+    /**
+     * Number of missing (not yet executed) runs in the experiment
+     */
+    missingRunCount: number;
 }
 export type ExperimentRunID = string;
+/**
+ * Represents incomplete experiment runs for a dataset example
+ * Groups all incomplete repetitions for a single example
+ */
+export interface IncompleteRun {
+    /**
+     * The dataset example that has incomplete runs
+     */
+    datasetExample: Example;
+    /**
+     * List of repetition numbers that need to be run for this example
+     */
+    repetitionNumbers: number[];
+}
+export interface IncompleteEvaluation {
+    /**
+     * The experiment run with incomplete evaluations
+     */
+    experimentRun: ExperimentRun;
+    /**
+     * The dataset example for this run
+     */
+    datasetExample: ExampleWithId;
+    /**
+     * List of evaluation names that are incomplete (either missing or failed)
+     */
+    evaluationNames: string[];
+}
 /**
  * A map of an experiment runId to the run
  */

package/dist/esm/types/experiments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"experiments.d.ts","sourceRoot":"","sources":["../../../src/types/experiments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"experiments.d.ts","sourceRoot":"","sources":["../../../src/types/experiments.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/channel.d.ts

@@ -0,0 +1,229 @@
+/**
+ * A bounded, buffered CSP channel implementation for TypeScript.
+ *
+ * Implements the Producer-Consumer pattern with automatic backpressure via
+ * blocking send/receive semantics. Based on Communicating Sequential Processes (Hoare, 1978).
+ *
+ * Properties:
+ * - Bounded buffer: O(capacity) memory usage
+ * - Blocking send: Blocks when buffer is full
+ * - Blocking receive: Blocks when buffer is empty
+ * - Graceful shutdown: Close drains buffer before terminating
+ *
+ * Performance Characteristics:
+ * - send(): O(R) where R = pending receivers (typically 0-10)
+ * - receive(): O(B + S) where B = buffer size, S = pending senders
+ * - Uses Array.shift() which is O(n) but acceptable for small queues
+ * - Same complexity trade-off as async.queue, p-limit, and similar libraries
+ * - For typical usage (buffer < 100, queues < 10), overhead is negligible (<10ms per 5000 operations)
+ *
+ * Note: Could be optimized to O(1) with linked list or circular buffer, but current
+ * implementation prioritizes simplicity and is comparable to standard JS libraries.
+ *
+ * Deadlock Prevention:
+ * JavaScript channels use cooperative blocking via Promises, not true thread blocking.
+ * Deadlocks are rare but possible in certain patterns:
+ *
+ * ❌ AVOID: Sequential operations on unbuffered channels
+ * ```typescript
+ * const ch = new Channel<number>(0);
+ * await ch.send(1);     // Blocks forever - no receiver started
+ * await ch.receive();   // Never reached
+ * ```
+ *
+ * ❌ AVOID: Circular dependencies between channels
+ * ```typescript
+ * const ch1 = new Channel(0);
+ * const ch2 = new Channel(0);
+ * // Task 1: await ch1.send() → await ch2.receive()
+ * // Task 2: await ch2.send() → await ch1.receive()
+ * // Both block on send, never reach receive
+ * ```
+ *
+ * ✅ SAFE: Concurrent start with buffered channels (recommended pattern)
+ * ```typescript
+ * const ch = new Channel<number>(); // Default (10) is safe
+ *
+ * // Start producer immediately
+ * const producer = (async () => {
+ *   for (let i = 0; i < 100; i++) {
+ *     await ch.send(i);
+ *   }
+ *   ch.close(); // Always close in finally block
+ * })();
+ *
+ * // Start consumers immediately
+ * const consumers = Array.from({ length: 5 }, async () => {
+ *   for await (const value of ch) {
+ *     await processValue(value);
+ *   }
+ * });
+ *
+ * // Wait for all to complete
+ * await Promise.all([producer, ...consumers]);
+ * ```
+ *
+ * Best Practices:
+ * 1. Use default capacity or higher (10+) for production - provides safety and throughput
+ * 2. Always close() channels in a finally block to prevent hanging operations
+ * 3. Start producers and consumers concurrently, not sequentially
+ * 4. Use for-await loops for automatic cleanup on close
+ * 5. Avoid circular dependencies between channels
+ * 6. Handle errors in workers so they don't crash and leave channel blocked
+ * 7. Only use unbuffered (capacity=0) when you need strict happens-before guarantees
+ *
+ * @see https://en.wikipedia.org/wiki/Communicating_sequential_processes
+ *
+ * @template T The type of values sent through the channel
+ *
+ * @example Safe Producer-Consumer Pattern
+ * ```typescript
+ * // Default capacity (10) is safe for most cases
+ * const ch = new Channel<number>(); // or explicit: new Channel<number>(50)
+ *
+ * // Producer with proper cleanup
+ * const producer = (async () => {
+ *   try {
+ *     for (let i = 0; i < 100; i++) {
+ *       await ch.send(i); // Blocks if buffer full (backpressure)
+ *     }
+ *   } finally {
+ *     ch.close(); // Guaranteed cleanup
+ *   }
+ * })();
+ *
+ * // Multiple consumers
+ * const consumers = Array.from({ length: 3 }, async () => {
+ *   for await (const value of ch) {
+ *     console.log(value);
+ *   }
+ * });
+ *
+ * await Promise.all([producer, ...consumers]);
+ * ```
+ *
+ * @example Unbuffered Channel (Rendezvous)
+ * ```typescript
+ * const ch = new Channel<number>(0); // Unbuffered - use with care!
+ *
+ * // Must start both operations before awaiting
+ * const sendPromise = ch.send(42);    // Starts but doesn't block caller yet
+ * const value = await ch.receive();   // Unblocks the sender
+ * await sendPromise;                  // Now safe to await
+ * ```
+ */
+/**
+ * Custom error class for channel operations
+ */
+export declare class ChannelError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class Channel<T> {
+    #private;
+    /**
+     * Create a new channel with the specified buffer capacity.
+     *
+     * @param capacity - Buffer size (default: 10)
+     *   - 0: Unbuffered/rendezvous channel - strict synchronization, higher deadlock risk.
+     *         Use only when you need guaranteed happens-before ordering.
+     *   - 1-100: Buffered channel - recommended for production use.
+     *   - Higher values: Better throughput but more memory usage.
+     *
+     * @example
+     * ```typescript
+     * // Default buffered (safe for most cases)
+     * const ch1 = new Channel<number>();
+     *
+     * // Explicit buffer size (production pattern)
+     * const ch2 = new Channel<number>(50);
+     *
+     * // Unbuffered (advanced - strict synchronization)
+     * const ch3 = new Channel<number>(0);
+     * ```
+     */
+    constructor(capacity?: number);
+    /**
+     * Send a value to the channel
+     * Blocks if the buffer is full until space is available
+     *
+     * @param value - The value to send
+     * @throws {ChannelError} If channel is closed
+     */
+    send(value: T): Promise<void>;
+    /**
+     * Receive a value from the channel
+     * Blocks if no value is available until one arrives
+     *
+     * @returns The received value, or CLOSED symbol if channel is closed and empty
+     */
+    receive(): Promise<T | typeof CLOSED>;
+    /**
+     * Try to receive a value without blocking
+     * Returns immediately with value or undefined if channel is empty
+     *
+     * @returns The received value, CLOSED if channel is closed, or undefined if empty
+     *
+     * @example
+     * ```typescript
+     * const ch = new Channel<number>(10);
+     * await ch.send(42);
+     *
+     * const value = ch.tryReceive();
+     * if (value !== undefined && value !== CLOSED) {
+     *   console.log("Got:", value);
+     * }
+     * ```
+     */
+    tryReceive(): T | typeof CLOSED | undefined;
+    /**
+     * Close the channel
+     * No more sends allowed, but remaining values can be received
+     */
+    close(): void;
+    /**
+     * Check if channel is closed
+     */
+    get isClosed(): boolean;
+    /**
+     * Get current buffer length
+     */
+    get length(): number;
+    /**
+     * Get the channel's capacity
+     */
+    get capacity(): number;
+    /**
+     * Get the number of blocked senders waiting
+     */
+    get pendingSends(): number;
+    /**
+     * Get the number of blocked receivers waiting
+     */
+    get pendingReceives(): number;
+    /**
+     * Async iterator support for for-await-of loops
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+/**
+ * Special symbol to indicate channel is closed
+ */
+export declare const CLOSED: unique symbol;
+/**
+ * Type guard to check if a value is the CLOSED symbol
+ *
+ * @param value - Value to check
+ * @returns true if value is CLOSED symbol
+ *
+ * @example
+ * ```typescript
+ * const value = await ch.receive();
+ * if (isClosed(value)) {
+ *   console.log("Channel is closed");
+ * } else {
+ *   console.log("Got value:", value);
+ * }
+ * ```
+ */
+export declare function isClosed<T>(value: T | typeof CLOSED): value is typeof CLOSED;
+//# sourceMappingURL=channel.d.ts.map

package/dist/esm/utils/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/utils/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AAmBH;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAWD,qBAAa,OAAO,CAAC,CAAC;;IAOpB;;;;;;;;;;;;;;;;;;;;OAoBG;gBACS,QAAQ,GAAE,MAAW;IAOjC;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBnC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,GAAG,OAAO,MAAM,CAAC;IAiC3C;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,IAAI,CAAC,GAAG,OAAO,MAAM,GAAG,SAAS;IA+B3C;;;OAGG;IACH,KAAK,IAAI,IAAI;IAkBb;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;OAEG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,CAAC,CAAC;CAO1D;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,eAAmB,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,MAAM,GAAG,KAAK,IAAI,OAAO,MAAM,CAE5E"}

package/dist/esm/utils/channel.js

@@ -0,0 +1,352 @@
+/**
+ * A bounded, buffered CSP channel implementation for TypeScript.
+ *
+ * Implements the Producer-Consumer pattern with automatic backpressure via
+ * blocking send/receive semantics. Based on Communicating Sequential Processes (Hoare, 1978).
+ *
+ * Properties:
+ * - Bounded buffer: O(capacity) memory usage
+ * - Blocking send: Blocks when buffer is full
+ * - Blocking receive: Blocks when buffer is empty
+ * - Graceful shutdown: Close drains buffer before terminating
+ *
+ * Performance Characteristics:
+ * - send(): O(R) where R = pending receivers (typically 0-10)
+ * - receive(): O(B + S) where B = buffer size, S = pending senders
+ * - Uses Array.shift() which is O(n) but acceptable for small queues
+ * - Same complexity trade-off as async.queue, p-limit, and similar libraries
+ * - For typical usage (buffer < 100, queues < 10), overhead is negligible (<10ms per 5000 operations)
+ *
+ * Note: Could be optimized to O(1) with linked list or circular buffer, but current
+ * implementation prioritizes simplicity and is comparable to standard JS libraries.
+ *
+ * Deadlock Prevention:
+ * JavaScript channels use cooperative blocking via Promises, not true thread blocking.
+ * Deadlocks are rare but possible in certain patterns:
+ *
+ * ❌ AVOID: Sequential operations on unbuffered channels
+ * ```typescript
+ * const ch = new Channel<number>(0);
+ * await ch.send(1);     // Blocks forever - no receiver started
+ * await ch.receive();   // Never reached
+ * ```
+ *
+ * ❌ AVOID: Circular dependencies between channels
+ * ```typescript
+ * const ch1 = new Channel(0);
+ * const ch2 = new Channel(0);
+ * // Task 1: await ch1.send() → await ch2.receive()
+ * // Task 2: await ch2.send() → await ch1.receive()
+ * // Both block on send, never reach receive
+ * ```
+ *
+ * ✅ SAFE: Concurrent start with buffered channels (recommended pattern)
+ * ```typescript
+ * const ch = new Channel<number>(); // Default (10) is safe
+ *
+ * // Start producer immediately
+ * const producer = (async () => {
+ *   for (let i = 0; i < 100; i++) {
+ *     await ch.send(i);
+ *   }
+ *   ch.close(); // Always close in finally block
+ * })();
+ *
+ * // Start consumers immediately
+ * const consumers = Array.from({ length: 5 }, async () => {
+ *   for await (const value of ch) {
+ *     await processValue(value);
+ *   }
+ * });
+ *
+ * // Wait for all to complete
+ * await Promise.all([producer, ...consumers]);
+ * ```
+ *
+ * Best Practices:
+ * 1. Use default capacity or higher (10+) for production - provides safety and throughput
+ * 2. Always close() channels in a finally block to prevent hanging operations
+ * 3. Start producers and consumers concurrently, not sequentially
+ * 4. Use for-await loops for automatic cleanup on close
+ * 5. Avoid circular dependencies between channels
+ * 6. Handle errors in workers so they don't crash and leave channel blocked
+ * 7. Only use unbuffered (capacity=0) when you need strict happens-before guarantees
+ *
+ * @see https://en.wikipedia.org/wiki/Communicating_sequential_processes
+ *
+ * @template T The type of values sent through the channel
+ *
+ * @example Safe Producer-Consumer Pattern
+ * ```typescript
+ * // Default capacity (10) is safe for most cases
+ * const ch = new Channel<number>(); // or explicit: new Channel<number>(50)
+ *
+ * // Producer with proper cleanup
+ * const producer = (async () => {
+ *   try {
+ *     for (let i = 0; i < 100; i++) {
+ *       await ch.send(i); // Blocks if buffer full (backpressure)
+ *     }
+ *   } finally {
+ *     ch.close(); // Guaranteed cleanup
+ *   }
+ * })();
+ *
+ * // Multiple consumers
+ * const consumers = Array.from({ length: 3 }, async () => {
+ *   for await (const value of ch) {
+ *     console.log(value);
+ *   }
+ * });
+ *
+ * await Promise.all([producer, ...consumers]);
+ * ```
+ *
+ * @example Unbuffered Channel (Rendezvous)
+ * ```typescript
+ * const ch = new Channel<number>(0); // Unbuffered - use with care!
+ *
+ * // Must start both operations before awaiting
+ * const sendPromise = ch.send(42);    // Starts but doesn't block caller yet
+ * const value = await ch.receive();   // Unblocks the sender
+ * await sendPromise;                  // Now safe to await
+ * ```
+ */
+/**
+ * Custom error class for channel operations
+ */
+export class ChannelError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ChannelError";
+    }
+}
+/**
+ * Error messages for channel operations
+ */
+const ERRORS = {
+    SEND_TO_CLOSED: "Cannot send to closed channel",
+    CLOSED_WHILE_BLOCKED: "Channel closed while send was blocked",
+    NEGATIVE_CAPACITY: "Channel capacity must be non-negative",
+};
+export class Channel {
+    #buffer = [];
+    #sendQueue = [];
+    #receiveQueue = [];
+    #closed = false;
+    #capacity;
+    /**
+     * Create a new channel with the specified buffer capacity.
+     *
+     * @param capacity - Buffer size (default: 10)
+     *   - 0: Unbuffered/rendezvous channel - strict synchronization, higher deadlock risk.
+     *         Use only when you need guaranteed happens-before ordering.
+     *   - 1-100: Buffered channel - recommended for production use.
+     *   - Higher values: Better throughput but more memory usage.
+     *
+     * @example
+     * ```typescript
+     * // Default buffered (safe for most cases)
+     * const ch1 = new Channel<number>();
+     *
+     * // Explicit buffer size (production pattern)
+     * const ch2 = new Channel<number>(50);
+     *
+     * // Unbuffered (advanced - strict synchronization)
+     * const ch3 = new Channel<number>(0);
+     * ```
+     */
+    constructor(capacity = 10) {
+        if (capacity < 0) {
+            throw new ChannelError(ERRORS.NEGATIVE_CAPACITY);
+        }
+        this.#capacity = capacity;
+    }
+    /**
+     * Send a value to the channel
+     * Blocks if the buffer is full until space is available
+     *
+     * @param value - The value to send
+     * @throws {ChannelError} If channel is closed
+     */
+    async send(value) {
+        if (this.#closed) {
+            throw new ChannelError(ERRORS.SEND_TO_CLOSED);
+        }
+        // Direct delivery to waiting receiver
+        const receiver = this.#receiveQueue.shift();
+        if (receiver) {
+            receiver.resolve(value);
+            return;
+        }
+        // Add to buffer if space available
+        if (this.#buffer.length < this.#capacity) {
+            this.#buffer.push(value);
+            return;
+        }
+        // Block until space available
+        return new Promise((resolve, reject) => {
+            this.#sendQueue.push({ value, resolve, reject });
+        });
+    }
+    /**
+     * Receive a value from the channel
+     * Blocks if no value is available until one arrives
+     *
+     * @returns The received value, or CLOSED symbol if channel is closed and empty
+     */
+    async receive() {
+        // Drain buffer first
+        if (this.#buffer.length > 0) {
+            const value = this.#buffer.shift();
+            // Unblock a waiting sender
+            const sender = this.#sendQueue.shift();
+            if (sender) {
+                this.#buffer.push(sender.value);
+                sender.resolve();
+            }
+            return value;
+        }
+        // Direct handoff from waiting sender (critical for unbuffered channels)
+        const sender = this.#sendQueue.shift();
+        if (sender) {
+            sender.resolve();
+            return sender.value;
+        }
+        // Channel closed and empty
+        if (this.#closed) {
+            return CLOSED;
+        }
+        // Block until value available
+        return new Promise((resolve, reject) => {
+            this.#receiveQueue.push({ resolve, reject });
+        });
+    }
+    /**
+     * Try to receive a value without blocking
+     * Returns immediately with value or undefined if channel is empty
+     *
+     * @returns The received value, CLOSED if channel is closed, or undefined if empty
+     *
+     * @example
+     * ```typescript
+     * const ch = new Channel<number>(10);
+     * await ch.send(42);
+     *
+     * const value = ch.tryReceive();
+     * if (value !== undefined && value !== CLOSED) {
+     *   console.log("Got:", value);
+     * }
+     * ```
+     */
+    tryReceive() {
+        // Drain buffer first
+        if (this.#buffer.length > 0) {
+            const value = this.#buffer.shift();
+            // Unblock a waiting sender
+            const sender = this.#sendQueue.shift();
+            if (sender) {
+                this.#buffer.push(sender.value);
+                sender.resolve();
+            }
+            return value;
+        }
+        // Direct handoff from waiting sender
+        const sender = this.#sendQueue.shift();
+        if (sender) {
+            sender.resolve();
+            return sender.value;
+        }
+        // Channel closed and empty
+        if (this.#closed) {
+            return CLOSED;
+        }
+        // Channel empty but not closed
+        return undefined;
+    }
+    /**
+     * Close the channel
+     * No more sends allowed, but remaining values can be received
+     */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        // Resolve all blocked receivers
+        for (const receiver of this.#receiveQueue) {
+            receiver.resolve(CLOSED);
+        }
+        this.#receiveQueue = [];
+        // Reject all blocked senders
+        const error = new ChannelError(ERRORS.CLOSED_WHILE_BLOCKED);
+        for (const sender of this.#sendQueue) {
+            sender.reject(error);
+        }
+        this.#sendQueue = [];
+    }
+    /**
+     * Check if channel is closed
+     */
+    get isClosed() {
+        return this.#closed;
+    }
+    /**
+     * Get current buffer length
+     */
+    get length() {
+        return this.#buffer.length;
+    }
+    /**
+     * Get the channel's capacity
+     */
+    get capacity() {
+        return this.#capacity;
+    }
+    /**
+     * Get the number of blocked senders waiting
+     */
+    get pendingSends() {
+        return this.#sendQueue.length;
+    }
+    /**
+     * Get the number of blocked receivers waiting
+     */
+    get pendingReceives() {
+        return this.#receiveQueue.length;
+    }
+    /**
+     * Async iterator support for for-await-of loops
+     */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.receive();
+            if (value === CLOSED)
+                return;
+            yield value;
+        }
+    }
+}
+/**
+ * Special symbol to indicate channel is closed
+ */
+export const CLOSED = Symbol("CLOSED");
+/**
+ * Type guard to check if a value is the CLOSED symbol
+ *
+ * @param value - Value to check
+ * @returns true if value is CLOSED symbol
+ *
+ * @example
+ * ```typescript
+ * const value = await ch.receive();
+ * if (isClosed(value)) {
+ *   console.log("Channel is closed");
+ * } else {
+ *   console.log("Got value:", value);
+ * }
+ * ```
+ */
+export function isClosed(value) {
+    return value === CLOSED;
+}
+//# sourceMappingURL=channel.js.map

package/dist/esm/utils/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/utils/channel.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/formatPromptMessages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatPromptMessages.d.ts","sourceRoot":"","sources":["../../../src/utils/formatPromptMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKlD,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI3E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,EAC5B,cAAc,EAAE,iBAAiB,EAAE,EACnC,SAAS,GAAE,SAAc;;;;;;;mBA4D4koF,uDAAsB;;;;;;;;;IAlB5noF"}
+{"version":3,"file":"formatPromptMessages.d.ts","sourceRoot":"","sources":["../../../src/utils/formatPromptMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKlD,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI3E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,EAC5B,cAAc,EAAE,iBAAiB,EAAE,EACnC,SAAS,GAAE,SAAc;;;;;;;mBA4DinyF,uDAAsB;;;;;;;;;IAlBjqyF"}