llmz 0.9.0 → 1.0.2

package/dist/snapshots.d.ts

@@ -1,249 +0,0 @@
-import { ToolCall, SnapshotSignal } from './errors.js';
-import { Serializable } from './types.js';
-type Variable = {
-    name: string;
-    type: string;
-    bytes: number;
-    preview?: string;
-    value?: unknown;
-    truncated: boolean;
-} & ({
-    truncated: true;
-    preview: string;
-} | {
-    truncated: false;
-    value: unknown;
-});
-export type SnapshotStatus = SnapshotStatuses.Pending | SnapshotStatuses.Resolved | SnapshotStatuses.Rejected;
-export declare namespace SnapshotStatuses {
-    type Pending = {
-        type: 'pending';
-    };
-    type Resolved = {
-        type: 'resolved';
-        value: unknown;
-    };
-    type Rejected = {
-        type: 'rejected';
-        error: unknown;
-    };
-}
-export declare namespace Snapshot {
-    type JSON = {
-        id: string;
-        reason?: string;
-        stack: string;
-        variables: Variable[];
-        toolCall?: ToolCall;
-        status: SnapshotStatus;
-    };
-}
-/**
- * Snapshot represents a captured execution state that can be persisted and restored later.
- *
- * Snapshots are created when a SnapshotSignal is thrown during execution, typically from
- * within a tool handler to pause execution for long-running operations that need to be
- * completed asynchronously (e.g., background jobs, external API calls, user input).
- *
- * ## Use Cases
- * - **Long-running operations**: Pause execution while waiting for external processes
- * - **User interaction**: Collect input from users before continuing execution
- * - **Resource management**: Defer expensive operations to background workers
- * - **Workflow persistence**: Save execution state across process restarts
- *
- * ## Basic Usage
- *
- * ### Creating a Snapshot
- * From within a tool handler, throw a SnapshotSignal to create a snapshot:
- * ```typescript
- * const tool = new Tool({
- *   handler: async ({ input }) => {
- *     // Start long-running operation
- *     throw new SnapshotSignal('Waiting for external API response')
- *   }
- * })
- * ```
- *
- * ### Handling Interrupted Execution
- * ```typescript
- * const result = await execute({ tools: [tool], ... })
- *
- * if (result.isInterrupted()) {
- *   const snapshot = result.snapshot
- *
- *   // Serialize for persistence
- *   const serialized = snapshot.toJSON()
- *   await database.saveSnapshot(serialized)
- * }
- * ```
- *
- * ### Resuming from Snapshot
- * ```typescript
- * // Restore from persistence
- * const serialized = await database.getSnapshot(id)
- * const snapshot = Snapshot.fromJSON(serialized)
- *
- * // Resolve with the result of the long-running operation
- * snapshot.resolve({ result: 'Operation completed!' })
- *
- * // Continue execution
- * const continuation = await execute({
- *   snapshot,
- *   instructions: originalInstructions,
- *   tools: originalTools,
- *   exits: originalExits,
- *   client
- * })
- * ```
- *
- * ## Snapshot Lifecycle
- * 1. **Created**: When SnapshotSignal is thrown (status: pending)
- * 2. **Serialized**: Convert to JSON for persistence with toJSON()
- * 3. **Restored**: Recreate from JSON with fromJSON()
- * 4. **Resolved/Rejected**: Provide result data with resolve() or reject()
- * 5. **Resumed**: Continue execution with the resolved snapshot
- *
- * ## What's Captured
- * - **Execution stack**: Current code position and call stack
- * - **Variables**: All local variables and their values (up to size limit)
- * - **Tool context**: Information about the tool call that triggered the snapshot
- * - **Reason**: Human-readable description of why the snapshot was created
- *
- * @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/14_worker_snapshot/index.ts} Example usage
- */
-export declare class Snapshot implements Serializable<Snapshot.JSON> {
-    #private;
-    readonly id: string;
-    readonly reason?: string;
-    readonly stack: string;
-    readonly toolCall?: ToolCall;
-    variables: Variable[];
-    /**
-     * Gets the current status of the snapshot.
-     *
-     * @returns The snapshot status (pending, resolved, or rejected)
-     */
-    get status(): Readonly<{
-        type: 'pending';
-    } | {
-        type: 'rejected';
-        error: unknown;
-    } | {
-        type: 'resolved';
-        value: unknown;
-    }>;
-    private constructor();
-    /**
-     * Creates a new Snapshot from a SnapshotSignal.
-     *
-     * This method is called internally by the LLMz execution engine when a SnapshotSignal
-     * is thrown during execution. It captures the current execution state including
-     * variables, stack trace, and tool context.
-     *
-     * @param signal The SnapshotSignal containing execution state
-     * @returns A new Snapshot instance in pending status
-     * @internal
-     */
-    static fromSignal(signal: SnapshotSignal): Snapshot;
-    /**
-     * Serializes the snapshot to a JSON-compatible object for persistence.
-     *
-     * Use this method to save snapshots to databases, files, or other storage systems.
-     * The serialized snapshot can be restored later using fromJSON().
-     *
-     * @returns A JSON-serializable representation of the snapshot
-     * @example
-     * ```typescript
-     * const snapshot = result.snapshot
-     * const serialized = snapshot.toJSON()
-     * await database.save('snapshots', snapshot.id, serialized)
-     * ```
-     */
-    toJSON(): {
-        id: string;
-        reason: string | undefined;
-        stack: string;
-        variables: Variable[];
-        toolCall: ToolCall | undefined;
-        status: SnapshotStatus;
-    };
-    /**
-     * Restores a snapshot from its JSON representation.
-     *
-     * Use this method to recreate snapshots from persistent storage. The restored
-     * snapshot will maintain its original state and can be resolved/rejected as needed.
-     *
-     * @param json The serialized snapshot data from toJSON()
-     * @returns A restored Snapshot instance
-     * @example
-     * ```typescript
-     * const serialized = await database.get('snapshots', snapshotId)
-     * const snapshot = Snapshot.fromJSON(serialized)
-     * ```
-     */
-    static fromJSON(json: {
-        id: string;
-        reason?: string;
-        stack: string;
-        variables: Variable[];
-        toolCall?: ToolCall;
-        status: SnapshotStatus;
-    }): Snapshot;
-    /**
-     * Creates a deep copy of the snapshot.
-     *
-     * @returns A new Snapshot instance with identical data
-     */
-    clone(): Snapshot;
-    /**
-     * Resets the snapshot status back to pending.
-     *
-     * This allows a previously resolved or rejected snapshot to be resolved/rejected
-     * again with different data. Useful for retry scenarios.
-     */
-    reset(): void;
-    /**
-     * Resolves the snapshot with a successful result value.
-     *
-     * Call this method when the long-running operation that caused the snapshot
-     * has completed successfully. The provided value will be returned as the
-     * result of the original tool call when execution resumes.
-     *
-     * @param value The result value from the completed operation
-     * @throws Error if the snapshot is not in pending status
-     * @example
-     * ```typescript
-     * // After a background job completes
-     * const result = await backgroundJob.getResult()
-     * snapshot.resolve(result)
-     *
-     * // Continue execution
-     * const continuation = await execute({ snapshot, ... })
-     * ```
-     */
-    resolve(value: any): void;
-    /**
-     * Rejects the snapshot with an error.
-     *
-     * Call this method when the long-running operation that caused the snapshot
-     * has failed or encountered an error. The provided error will be thrown
-     * when execution resumes, allowing the generated code to handle it.
-     *
-     * @param error The error that occurred during the operation
-     * @throws Error if the snapshot is not in pending status
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await externalAPI.call()
-     *   snapshot.resolve(result)
-     * } catch (error) {
-     *   snapshot.reject(error)
-     * }
-     *
-     * // Continue execution (will throw the error)
-     * const continuation = await execute({ snapshot, ... })
-     * ```
-     */
-    reject(error: any): void;
-}
-export {};

package/dist/stack-traces-BIE_5Xwf.js

@@ -1,21 +0,0 @@
-//#region src/stack-traces.ts
-const isInternalLine = (line) => {
-	return line.includes("/llmz/") || line.includes("\\llmz\\src\\") || line.includes("node_modules");
-};
-function cleanStackTrace(stack, cleanInternal = true) {
-	let lines = stack.split("\n");
-	const until = lines.findIndex((line) => isInternalLine(line));
-	if (cleanInternal && until >= 0) lines = lines.slice(0, until);
-	else lines = lines.map((line) => {
-		let llmzIndex = line.indexOf("/llmz/");
-		if (llmzIndex === -1) llmzIndex = line.indexOf("\\llmz\\");
-		if (llmzIndex === -1) return line;
-		let lastSpaceIndex = line.lastIndexOf(" ", llmzIndex);
-		if (lastSpaceIndex === -1) lastSpaceIndex = 0;
-		const maybeParen = line[lastSpaceIndex + 1] === "(" ? "(" : "";
-		return line.slice(0, lastSpaceIndex + 1) + maybeParen + line.slice(llmzIndex);
-	});
-	return lines.join("\n");
-}
-//#endregion
-export { cleanStackTrace as t };

package/dist/stack-traces-ntw_qhoy.cjs

@@ -1,26 +0,0 @@
-//#region src/stack-traces.ts
-const isInternalLine = (line) => {
-	return line.includes("/llmz/") || line.includes("\\llmz\\src\\") || line.includes("node_modules");
-};
-function cleanStackTrace(stack, cleanInternal = true) {
-	let lines = stack.split("\n");
-	const until = lines.findIndex((line) => isInternalLine(line));
-	if (cleanInternal && until >= 0) lines = lines.slice(0, until);
-	else lines = lines.map((line) => {
-		let llmzIndex = line.indexOf("/llmz/");
-		if (llmzIndex === -1) llmzIndex = line.indexOf("\\llmz\\");
-		if (llmzIndex === -1) return line;
-		let lastSpaceIndex = line.lastIndexOf(" ", llmzIndex);
-		if (lastSpaceIndex === -1) lastSpaceIndex = 0;
-		const maybeParen = line[lastSpaceIndex + 1] === "(" ? "(" : "";
-		return line.slice(0, lastSpaceIndex + 1) + maybeParen + line.slice(llmzIndex);
-	});
-	return lines.join("\n");
-}
-//#endregion
-Object.defineProperty(exports, "cleanStackTrace", {
-	enumerable: true,
-	get: function() {
-		return cleanStackTrace;
-	}
-});

package/dist/truncator-CLkouTCO.cjs

@@ -1,276 +0,0 @@
-const require_compiler = require("./compiler-C-OI9sim.cjs");
-const require_utils = require("./utils-3ESwP3yg.cjs");
-//#region src/truncator.ts
-var truncator_exports = /* @__PURE__ */ require_compiler.__exportAll({
-	stripTruncationTags: () => stripTruncationTags,
-	truncateWrappedContent: () => truncateWrappedContent,
-	wrapContent: () => wrapContent
-});
-const DEFAULT_REMOVE_CHUNK = 250;
-const WRAP_OPEN_TAG_1 = "【TRUNCATE";
-const WRAP_OPEN_TAG_2 = "】";
-const WRAP_CLOSE_TAG = "【/TRUNCATE】";
-const REGEXP = `(${WRAP_OPEN_TAG_1}(?:\\s+[\\w:]+)*\\s*${WRAP_OPEN_TAG_2})([\\s\\S]*?)(${WRAP_CLOSE_TAG})`;
-const DEFAULT_TRUNCATE_OPTIONS = {
-	preserve: "top",
-	flex: 1,
-	minTokens: 0
-};
-/**
-* Wraps content with truncation tags to mark it as truncatable when using `truncateWrappedContent`.
-*
-* This function encases the provided content within special truncation tags that contain metadata
-* about how the content should be truncated. The wrapped content becomes eligible for intelligent
-* truncation while preserving non-wrapped content intact.
-*
-* @param content - The string content to wrap with truncation tags
-* @param options - Optional truncation configuration
-* @param options.preserve - Which part of the content to preserve when truncating:
-*   - 'top': Keep the beginning, remove from the end (default)
-*   - 'bottom': Keep the end, remove from the beginning
-*   - 'both': Keep both ends, remove from the middle
-* @param options.flex - Priority factor for truncation (default: 1). Higher values make this
-*   content more likely to be truncated. A flex of 2 means this content can shrink twice as
-*   much as content with flex of 1.
-* @param options.minTokens - Minimum number of tokens to preserve (default: 0). Content will
-*   never be truncated below this threshold.
-*
-* @returns The content wrapped with truncation tags and embedded metadata
-*
-* @example
-* ```typescript
-* // Basic usage - content will be truncated from the end if needed
-* const wrapped = wrapContent("This is some long content that might need truncation")
-*
-* // Preserve the end of the content
-* const bottomPreserved = wrapContent("Error log: ... important error details", {
-*   preserve: 'bottom'
-* })
-*
-* // High priority for truncation with minimum preservation
-* const flexible = wrapContent("Optional context information", {
-*   flex: 3,
-*   minTokens: 50
-* })
-* ```
-*/
-function wrapContent(content, options) {
-	const preserve = (options === null || options === void 0 ? void 0 : options.preserve) ?? DEFAULT_TRUNCATE_OPTIONS.preserve;
-	const flex = (options === null || options === void 0 ? void 0 : options.flex) ?? DEFAULT_TRUNCATE_OPTIONS.flex;
-	const minTokens = (options === null || options === void 0 ? void 0 : options.minTokens) ?? DEFAULT_TRUNCATE_OPTIONS.minTokens;
-	return `${WRAP_OPEN_TAG_1} preserve:${preserve} flex:${flex} min:${minTokens} ${WRAP_OPEN_TAG_2}${content}${WRAP_CLOSE_TAG}`;
-}
-/**
-* Intelligently truncates message content to fit within a token limit while preserving important parts.
-*
-* This function processes an array of messages and reduces their total token count to fit within the
-* specified limit. It only truncates content that has been wrapped with `wrapContent()`, leaving
-* unwrapped content completely intact. The truncation algorithm prioritizes content based on flex
-* values and respects preservation preferences and minimum token requirements.
-*
-* ## How it works:
-* 1. **Parsing**: Scans each message for wrapped content sections and unwrapped sections
-* 2. **Token counting**: Calculates tokens for each section using the configured tokenizer
-* 3. **Prioritization**: Identifies the largest truncatable sections based on flex values
-* 4. **Intelligent truncation**: Removes content according to preservation preferences
-* 5. **Reconstruction**: Rebuilds messages with truncated content and removes wrapper tags
-*
-* ## Truncation strategy:
-* - **Priority**: Higher flex values = higher truncation priority
-* - **Minimum tokens**: Content is never truncated below its `minTokens` threshold
-* - **Preservation modes**:
-*   - `'top'`: Removes from the end, keeps the beginning
-*   - `'bottom'`: Removes from the beginning, keeps the end
-*   - `'both'`: Removes from the middle, keeps both ends
-*
-* @template T - Type extending MessageLike (must have a content property)
-* @param options - Configuration object
-* @param options.messages - Array of messages to truncate
-* @param options.tokenLimit - Maximum total tokens allowed across all messages
-* @param options.throwOnFailure - Whether to throw an error if truncation fails (default: true).
-*   If false, returns the best effort result even if over the token limit.
-*
-* @returns Array of messages with content truncated to fit the token limit
-*
-* @throws Error if unable to truncate enough content to meet the token limit (when throwOnFailure is true)
-*
-* @example
-* ```typescript
-* const messages = [
-*   {
-*     role: 'system',
-*     content: 'You are a helpful assistant. ' + wrapContent('Here is some background info...', { flex: 2 })
-*   },
-*   {
-*     role: 'user',
-*     content: 'Please help me with: ' + wrapContent('detailed context and examples', { preserve: 'both' })
-*   }
-* ]
-*
-* // Truncate to fit within 1000 tokens
-* const truncated = truncateWrappedContent({
-*   messages,
-*   tokenLimit: 1000,
-*   throwOnFailure: false
-* })
-*
-* // The system message background info will be truncated first (higher flex),
-* // and user context will be truncated from the middle if needed (preserve: 'both')
-* ```
-*/
-function truncateWrappedContent({ messages, tokenLimit, throwOnFailure = true }) {
-	const tokenizer = require_utils.getTokenizer();
-	/**
-	* Before                      { content: 'content', tokens: 10, truncatable: false }
-	* <WRAPPER>content</WRAPPER>  { content: 'content', tokens: 10, truncatable: true }
-	* After                       { content: 'content', tokens: 10, truncatable: false }
-	*/
-	const parts = [];
-	for (const msg of messages) {
-		const current = [];
-		const content = typeof msg.content === "string" ? msg.content : "";
-		let match;
-		const parser = new _MessageContentParser();
-		while ((match = parser.parse(content)) !== null) {
-			const { attributes, nonTruncatableContent, wrappedContent } = match;
-			if (nonTruncatableContent) current.push({
-				content: nonTruncatableContent,
-				tokens: tokenizer.count(nonTruncatableContent),
-				truncatable: false
-			});
-			current.push({
-				content: wrappedContent,
-				tokens: tokenizer.count(wrappedContent),
-				truncatable: true,
-				attributes: {
-					preserve: attributes.preserve,
-					flex: Number(attributes.flex) || DEFAULT_TRUNCATE_OPTIONS.flex,
-					minTokens: Number(attributes.min) || DEFAULT_TRUNCATE_OPTIONS.minTokens
-				}
-			});
-		}
-		const remainingContent = parser.getRemainingContent(content);
-		if (remainingContent) current.push({
-			content: remainingContent,
-			tokens: tokenizer.count(remainingContent),
-			truncatable: false
-		});
-		parts.push(current);
-	}
-	let currentCount = _countTotalTokens(parts);
-	while (currentCount > tokenLimit) {
-		var _biggest$attributes, _biggest$attributes3;
-		const { biggest, secondBiggest } = _getTwoBiggestTruncables(parts);
-		if (!biggest || !biggest.truncatable || biggest.tokens <= 0) {
-			if (throwOnFailure) throw new Error(`Cannot truncate further, current count: ${currentCount}`);
-			else break;
-		}
-		const delta = Math.max(biggest.tokens - ((secondBiggest === null || secondBiggest === void 0 ? void 0 : secondBiggest.tokens) ?? 0), DEFAULT_REMOVE_CHUNK);
-		const room = Math.min(delta, biggest.tokens);
-		let toRemove = Math.min(room, currentCount - tokenLimit);
-		if (toRemove <= 0) {
-			if (throwOnFailure) throw new Error(`Cannot truncate further, current count: ${currentCount}`);
-			else break;
-		}
-		if (biggest.tokens - toRemove < (((_biggest$attributes = biggest.attributes) === null || _biggest$attributes === void 0 ? void 0 : _biggest$attributes.minTokens) ?? 0)) {
-			var _biggest$attributes2;
-			toRemove = biggest.tokens - (((_biggest$attributes2 = biggest.attributes) === null || _biggest$attributes2 === void 0 ? void 0 : _biggest$attributes2.minTokens) ?? 0);
-		}
-		const preserve = ((_biggest$attributes3 = biggest.attributes) === null || _biggest$attributes3 === void 0 ? void 0 : _biggest$attributes3.preserve) ?? DEFAULT_TRUNCATE_OPTIONS.preserve;
-		const split = tokenizer.splitAndSlice(biggest.content);
-		if (preserve === "bottom") biggest.content = split.slice(toRemove).join("");
-		else if (preserve === "top") biggest.content = split.slice(0, -toRemove).join("");
-		else {
-			const anchor = Math.ceil(split.length / 2);
-			const radius = Math.ceil(toRemove / 2);
-			const left = anchor - radius;
-			const right = anchor + radius;
-			biggest.content = split.slice(0, left).join("") + split.slice(right).join("");
-		}
-		biggest.tokens -= toRemove;
-		currentCount -= toRemove;
-	}
-	return messages.map((msg, i) => {
-		const p = parts[i];
-		return {
-			...msg,
-			content: typeof msg.content === "string" ? _renderRemainingWrappers(p.map((part) => part.content).join("")) : msg.content
-		};
-	});
-}
-var _MessageContentParser = class {
-	_regex;
-	_lastIndex = 0;
-	constructor() {
-		this._regex = _createRegex();
-	}
-	parse(content) {
-		const match = this._regex.exec(content);
-		if (!match) return null;
-		const attributes = match[1].split(/\s+/).slice(1).filter((x) => x !== WRAP_OPEN_TAG_2).map((x) => x.split(":")).reduce((acc, [key, value]) => ({
-			...acc,
-			[key]: value
-		}), {});
-		let nonTruncatableContent = void 0;
-		if (match.index > this._lastIndex) nonTruncatableContent = content.slice(this._lastIndex, match.index);
-		const wrappedContent = match[2];
-		this._lastIndex = this._regex.lastIndex;
-		return {
-			attributes,
-			nonTruncatableContent,
-			wrappedContent
-		};
-	}
-	getRemainingContent(content) {
-		if (this._lastIndex < content.length) return content.slice(this._lastIndex);
-		return null;
-	}
-};
-const _createRegex = () => new RegExp(REGEXP, "g");
-const _renderRemainingWrappers = (content) => content.replace(_createRegex(), "$2");
-/** Removes truncation wrapper tags from content, leaving the wrapped content intact. */
-const stripTruncationTags = (content) => _renderRemainingWrappers(content);
-const _countTotalTokens = (parts) => parts.reduce((acc, x) => acc + x.reduce((acc, y) => acc + y.tokens, 0), 0);
-const _getTwoBiggestTruncables = (parts) => {
-	let biggest = null;
-	let secondBiggest = null;
-	for (const part of parts.flat()) if (part.truncatable) {
-		var _part$attributes, _part$attributes2;
-		if (part.tokens <= (((_part$attributes = part.attributes) === null || _part$attributes === void 0 ? void 0 : _part$attributes.minTokens) ?? 0)) continue;
-		const flex = ((_part$attributes2 = part.attributes) === null || _part$attributes2 === void 0 ? void 0 : _part$attributes2.flex) ?? DEFAULT_TRUNCATE_OPTIONS.flex;
-		const tokens = part.tokens * flex;
-		if (!biggest || tokens > biggest.tokens) {
-			secondBiggest = biggest;
-			biggest = part;
-		} else if (!secondBiggest || tokens > secondBiggest.tokens) secondBiggest = part;
-	}
-	return {
-		biggest,
-		secondBiggest
-	};
-};
-//#endregion
-Object.defineProperty(exports, "stripTruncationTags", {
-	enumerable: true,
-	get: function() {
-		return stripTruncationTags;
-	}
-});
-Object.defineProperty(exports, "truncateWrappedContent", {
-	enumerable: true,
-	get: function() {
-		return truncateWrappedContent;
-	}
-});
-Object.defineProperty(exports, "truncator_exports", {
-	enumerable: true,
-	get: function() {
-		return truncator_exports;
-	}
-});
-Object.defineProperty(exports, "wrapContent", {
-	enumerable: true,
-	get: function() {
-		return wrapContent;
-	}
-});