llmz 0.0.13 → 0.0.15

package/dist/index.cjs

@@ -8,15 +8,15 @@
 
 
 
-var _chunkHJKOSEH2cjs = require('./chunk-HJKOSEH2.cjs');
-require('./chunk-SHJDRZF5.cjs');
+var _chunkTCRRSS44cjs = require('./chunk-TCRRSS44.cjs');
+require('./chunk-PIDLNYIP.cjs');
 
 
-var _chunkC6WNNTEVcjs = require('./chunk-C6WNNTEV.cjs');
+var _chunkXGJOEQMWcjs = require('./chunk-XGJOEQMW.cjs');
 
 
 
-var _chunk4L6D2A6Ocjs = require('./chunk-4L6D2A6O.cjs');
+var _chunkFZJHYLM2cjs = require('./chunk-FZJHYLM2.cjs');
 
 
 
@@ -26,7 +26,7 @@ var _chunkJDABP4SDcjs = require('./chunk-JDABP4SD.cjs');
 require('./chunk-IKSIOIIP.cjs');
 
 
-var _chunkGWFYZDURcjs = require('./chunk-GWFYZDUR.cjs');
+var _chunk3G3BS5IAcjs = require('./chunk-3G3BS5IA.cjs');
 
 
 
@@ -35,12 +35,16 @@ var _chunkGWFYZDURcjs = require('./chunk-GWFYZDUR.cjs');
 
 var _chunkZRCU35UVcjs = require('./chunk-ZRCU35UV.cjs');
 require('./chunk-KMZDFWYZ.cjs');
-require('./chunk-JGVAZO4X.cjs');
 
 
+var _chunkGZPN7RGHcjs = require('./chunk-GZPN7RGH.cjs');
 
 
-var _chunk276Q6EWPcjs = require('./chunk-276Q6EWP.cjs');
+
+
+
+
+var _chunkWHNOR4ZUcjs = require('./chunk-WHNOR4ZU.cjs');
 
 
 
@@ -296,7 +300,7 @@ async function hoistTypings(code, formatOptions) {
       break;
     }
   }
-  return _chunk4L6D2A6Ocjs.formatTypings.call(void 0, code, formatOptions);
+  return _chunkFZJHYLM2cjs.formatTypings.call(void 0, code, formatOptions);
 }
 
 // src/objects.ts
@@ -307,9 +311,65 @@ var ObjectInstance = class {
   
   
   
+  /**
+   * Creates a new ObjectInstance.
+   *
+   * @param props - Object configuration
+   * @param props.name - Unique object name (must be valid TypeScript identifier)
+   * @param props.description - Human-readable description of the object
+   * @param props.tools - Array of tools to group under this object namespace
+   * @param props.properties - Array of stateful properties for this object
+   * @param props.metadata - Additional metadata for the object
+   *
+   * @throws Error if name is not a valid identifier
+   * @throws Error if description is not a string
+   * @throws Error if metadata is not an object
+   * @throws Error if properties/tools are not arrays
+   * @throws Error if properties exceed 100 limit
+   * @throws Error if property names are duplicated or invalid
+   * @throws Error if property descriptions exceed 5000 characters
+   *
+   * @example
+   * ```typescript
+   * const userProfile = new ObjectInstance({
+   *   name: 'user',
+   *   description: 'User profile management',
+   *   properties: [
+   *     {
+   *       name: 'name',
+   *       value: 'John Doe',
+   *       type: z.string().min(1),
+   *       description: 'User full name',
+   *       writable: true,
+   *     },
+   *     {
+   *       name: 'email',
+   *       value: null,
+   *       type: z.string().email().nullable(),
+   *       description: 'User email address',
+   *       writable: true,
+   *     },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'updateProfile',
+   *       input: z.object({ name: z.string(), email: z.string() }),
+   *       handler: async ({ name, email }) => {
+   *         // Update external system
+   *         await updateUserInDatabase({ name, email })
+   *       },
+   *     }),
+   *   ],
+   *   metadata: {
+   *     version: '1.0',
+   *     category: 'user-management',
+   *   },
+   * })
+   * ```
+   */
   constructor(props) {
     var _a;
-    if (!_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, props.name)) {
+    if (!_chunkWHNOR4ZUcjs.isValidIdentifier.call(void 0, props.name)) {
       throw new Error(
         `Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
       );
@@ -342,7 +402,7 @@ var ObjectInstance = class {
         if (props.properties.filter((p) => p.name === prop.name).length > 1) {
           throw new Error(`Duplicate property name "${prop.name}" in tool ${props.name}`);
         }
-        if (!_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, prop.name)) {
+        if (!_chunkWHNOR4ZUcjs.isValidIdentifier.call(void 0, prop.name)) {
           throw new Error(
             `Invalid name for property ${prop.name}. A property name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
           );
@@ -366,11 +426,66 @@ var ObjectInstance = class {
     this.description = props.description;
     this.metadata = _nullishCoalesce(props.metadata, () => ( {}));
     this.properties = props.properties;
-    this.tools = _chunkC6WNNTEVcjs.Tool.withUniqueNames(_nullishCoalesce(props.tools, () => ( [])));
+    this.tools = _chunkXGJOEQMWcjs.Tool.withUniqueNames(_nullishCoalesce(props.tools, () => ( [])));
   }
+  /**
+   * Generates TypeScript namespace declarations for this object.
+   *
+   * This method creates TypeScript definitions that are included in the LLM context
+   * to help it understand the available properties and tools. Properties become
+   * const declarations with appropriate Readonly/Writable types, and tools become
+   * function signatures.
+   *
+   * @returns Promise resolving to TypeScript namespace declaration
+   *
+   * @example
+   * ```typescript
+   * const obj = new ObjectInstance({
+   *   name: 'user',
+   *   properties: [
+   *     { name: 'name', value: 'John', writable: true },
+   *     { name: 'id', value: 123, writable: false },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'save',
+   *       input: z.object({ data: z.string() }),
+   *       handler: async ({ data }) => { /* ... *\/ },
+   *     }),
+   *   ],
+   * })
+   *
+   * const typings = await obj.getTypings()
+   * console.log(typings)
+   * // Output:
+   * // export namespace user {
+   * //   const name: Writable<string> = "John"
+   * //   const id: Readonly<number> = 123
+   * //   function save(args: { data: string }): Promise<void>
+   * // }
+   * ```
+   */
   async getTypings() {
     return getObjectTypings(this).withProperties().withTools().build();
   }
+  /**
+   * Converts this ObjectInstance to its JSON representation.
+   *
+   * This method serializes the object into a JSON format that includes its name,
+   * description, properties, tools, and metadata. It is used for serialization
+   * and transmission of the object state.
+   *
+   * @returns JSON representation of the ObjectInstance
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      description: this.description,
+      properties: this.properties,
+      tools: (_nullishCoalesce(this.tools, () => ( []))).map((tool) => tool.toJSON()),
+      metadata: this.metadata
+    };
+  }
 };
 function getObjectTypings(obj) {
   let includeProperties = false;
@@ -388,11 +503,11 @@ function getObjectTypings(obj) {
       for (const prop of _nullishCoalesce(obj.properties, () => ( []))) {
         const description = _nullishCoalesce(prop.description, () => ( ""));
         if (description == null ? void 0 : description.trim().length) {
-          typings.push(_chunk276Q6EWPcjs.getMultilineComment.call(void 0, description));
+          typings.push(_chunkWHNOR4ZUcjs.getMultilineComment.call(void 0, description));
         }
         let type = "unknown";
         if (prop.type) {
-          type = await _chunk4L6D2A6Ocjs.getTypings.call(void 0, prop.type, {});
+          type = await _chunkFZJHYLM2cjs.getTypings.call(void 0, prop.type, {});
         } else if (prop.value !== void 0) {
           type = typeof prop.value;
         }
@@ -412,7 +527,7 @@ function getObjectTypings(obj) {
       typings.push("");
       for (const tool of obj.tools) {
         const fnType = _zui.z.function(tool.zInput, tool.zOutput).title(tool.name).describe(_nullishCoalesce(tool.description, () => ( "")));
-        let temp = await _chunk4L6D2A6Ocjs.getTypings.call(void 0, fnType, {
+        let temp = await _chunkFZJHYLM2cjs.getTypings.call(void 0, fnType, {
           declaration: true
         });
         temp = temp.replace("declare function ", "function ");
@@ -433,9 +548,9 @@ function getObjectTypings(obj) {
     typings.push("}" + closingBracket);
     let header = "";
     if ((_a = obj.description) == null ? void 0 : _a.trim().length) {
-      header = _chunk276Q6EWPcjs.getMultilineComment.call(void 0, obj.description);
+      header = _chunkWHNOR4ZUcjs.getMultilineComment.call(void 0, obj.description);
     }
-    return _chunk4L6D2A6Ocjs.formatTypings.call(void 0, 
+    return _chunkFZJHYLM2cjs.formatTypings.call(void 0, 
       `${header}
       export namespace ${obj.name} {
       ${body}
@@ -466,7 +581,7 @@ function getObjectTypings(obj) {
 }
 function embedPropertyValue(property) {
   if (typeof property.value === "string") {
-    return _chunk276Q6EWPcjs.escapeString.call(void 0, property.value);
+    return _chunkWHNOR4ZUcjs.escapeString.call(void 0, property.value);
   }
   if (Number.isNaN(property.value)) {
     return "NaN";
@@ -484,7 +599,7 @@ function embedPropertyValue(property) {
     return `new Date('${property.value.toISOString()}')`;
   }
   if (property.value instanceof RegExp) {
-    return `new RegExp(${_chunk276Q6EWPcjs.escapeString.call(void 0, property.value.source)}, ${_chunk276Q6EWPcjs.escapeString.call(void 0, property.value.flags)})`;
+    return `new RegExp(${_chunkWHNOR4ZUcjs.escapeString.call(void 0, property.value.source)}, ${_chunkWHNOR4ZUcjs.escapeString.call(void 0, property.value.flags)})`;
   }
   if (property.value === null) {
     return "null";
@@ -502,7 +617,7 @@ function embedPropertyValue(property) {
     return `${property.value}n`;
   }
   if (property.value instanceof Error) {
-    return `Error(${_chunk276Q6EWPcjs.escapeString.call(void 0, property.value.message)})`;
+    return `Error(${_chunkWHNOR4ZUcjs.escapeString.call(void 0, property.value.message)})`;
   }
   if (property.value instanceof Map) {
     return `new Map(${JSON.stringify(Array.from(property.value.entries()))})`;
@@ -866,31 +981,140 @@ var Chat = class {
   
   
   
+  /**
+   * Creates a new Chat instance.
+   *
+   * @param props - Chat configuration
+   * @param props.handler - Function to handle agent messages (called for every agent output)
+   * @param props.components - Available UI components (static array or dynamic function)
+   * @param props.transcript - Conversation history (static array or dynamic function, defaults to empty)
+   *
+   * @example
+   * ```typescript
+   * // Basic chat with static configuration
+   * const chat = new Chat({
+   *   handler: async (input) => {
+   *     if (isComponent(input, DefaultComponents.Text)) {
+   *       console.log('Agent:', input.children.join(''))
+   *     }
+   *   },
+   *   components: [DefaultComponents.Text, DefaultComponents.Button],
+   *   transcript: [
+   *     { role: 'user', content: 'Hello', timestamp: Date.now() }
+   *   ],
+   * })
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Dynamic chat with functions for real-time updates
+   * class MyChat extends Chat {
+   *   private messages: Transcript.Message[] = []
+   *
+   *   constructor() {
+   *     super({
+   *       handler: (input) => this.handleMessage(input),
+   *
+   *       // Dynamic components - can change during execution
+   *       components: () => [
+   *         DefaultComponents.Text,
+   *         DefaultComponents.Button,
+   *         ...this.getCustomComponents()
+   *       ],
+   *
+   *       // Dynamic transcript - always reflects current state
+   *       transcript: () => this.messages,
+   *     })
+   *   }
+   * }
+   * ```
+   */
   constructor(props) {
     this.handler = props.handler;
     this.components = props.components;
     this.transcript = props.transcript || [];
   }
+  /**
+   * Called when an execution cycle completes, regardless of the outcome.
+   *
+   * Override this method to handle execution results, manage conversation flow,
+   * or perform cleanup tasks. This is called after each `execute()` call completes,
+   * whether it succeeds, fails, or is interrupted.
+   *
+   * @param result - The execution result containing status, iterations, and exit information
+   *
+   * @example
+   * ```typescript
+   * class MyChat extends Chat {
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     // Store result for conversation flow control
+   *     this.result = result
+   *
+   *     // Handle different result types
+   *     if (result.isSuccess()) {
+   *       console.log('✅ Execution completed successfully')
+   *       console.log('Exit:', result.output.exit_name)
+   *     } else if (result.isError()) {
+   *       console.error('❌ Execution failed:', result.output.error)
+   *     } else if (result.isInterrupted()) {
+   *       console.log('⏸️ Execution interrupted (partial result)')
+   *     }
+   *   }
+   *
+   *   // Use stored result for conversation flow
+   *   isWaitingForInput(): boolean {
+   *     return this.result?.is(ListenExit) ?? false
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // CLIChat implementation example
+   * class CLIChat extends Chat {
+   *   public status?: IterationStatus
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     this.result = result
+   *     this.status = result.iterations.at(-1)?.status
+   *   }
+   *
+   *   // Check if agent exited with specific exit type
+   *   hasExitedWith<R>(exit: Exit<R>): boolean {
+   *     return this.status?.type === 'exit_success' &&
+   *            this.status.exit_success.exit_name === exit.name
+   *   }
+   * }
+   * ```
+   */
   onExecutionDone(_result) {
   }
 };
 
 // src/index.ts
+var utils = {
+  toValidObjectName: _chunkWHNOR4ZUcjs.toValidObjectName,
+  toValidFunctionName: _chunkWHNOR4ZUcjs.toValidFunctionName,
+  wrapContent: _chunkGZPN7RGHcjs.wrapContent
+};
 var execute = async (props) => {
-  const { executeContext } = await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-QLZBDG2Z.cjs")));
+  const { executeContext } = await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-WVNKAMCP.cjs")));
   return executeContext(props);
 };
 var init = async () => {
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-QLZBDG2Z.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-WVNKAMCP.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./component-R4WTW6DZ.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./tool-QP4MVRWI.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./exit-TRXEU4OU.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./tool-O4SFRIE4.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./exit-XAYKJ6TR.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./jsx-AJAXBWFE.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./vm-2DLG7V4G.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./utils-A7WNEFTA.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./truncator-DUMWEGQO.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./typings-2CPHOFDN.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./dual-modes-VLIGPIHX.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./utils-L5QAQXV2.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./truncator-W3NXBLYJ.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./typings-Y45GMPZT.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./dual-modes-OFHV2C3X.cjs")));
 };
 
 
@@ -918,4 +1142,5 @@ var init = async () => {
 
 
 
-exports.Chat = Chat; exports.CitationsManager = CitationsManager; exports.Component = _chunkZRCU35UVcjs.Component; exports.DefaultComponents = DefaultComponents; exports.DefaultExit = _chunkHJKOSEH2cjs.DefaultExit; exports.ErrorExecutionResult = _chunkHJKOSEH2cjs.ErrorExecutionResult; exports.ExecutionResult = _chunkHJKOSEH2cjs.ExecutionResult; exports.Exit = _chunkGWFYZDURcjs.Exit; exports.ListenExit = _chunkHJKOSEH2cjs.ListenExit; exports.LoopExceededError = _chunkJDABP4SDcjs.LoopExceededError; exports.ObjectInstance = ObjectInstance; exports.PartialExecutionResult = _chunkHJKOSEH2cjs.PartialExecutionResult; exports.Snapshot = _chunkHJKOSEH2cjs.Snapshot; exports.SnapshotSignal = _chunkJDABP4SDcjs.SnapshotSignal; exports.SuccessExecutionResult = _chunkHJKOSEH2cjs.SuccessExecutionResult; exports.ThinkExit = _chunkHJKOSEH2cjs.ThinkExit; exports.ThinkSignal = _chunkJDABP4SDcjs.ThinkSignal; exports.Tool = _chunkC6WNNTEVcjs.Tool; exports.assertValidComponent = _chunkZRCU35UVcjs.assertValidComponent; exports.execute = execute; exports.getValue = _chunkHJKOSEH2cjs.getValue; exports.init = init; exports.isAnyComponent = _chunkZRCU35UVcjs.isAnyComponent; exports.isComponent = _chunkZRCU35UVcjs.isComponent; exports.renderToTsx = _chunkZRCU35UVcjs.renderToTsx;
+
+exports.Chat = Chat; exports.CitationsManager = CitationsManager; exports.Component = _chunkZRCU35UVcjs.Component; exports.DefaultComponents = DefaultComponents; exports.DefaultExit = _chunkTCRRSS44cjs.DefaultExit; exports.ErrorExecutionResult = _chunkTCRRSS44cjs.ErrorExecutionResult; exports.ExecutionResult = _chunkTCRRSS44cjs.ExecutionResult; exports.Exit = _chunk3G3BS5IAcjs.Exit; exports.ListenExit = _chunkTCRRSS44cjs.ListenExit; exports.LoopExceededError = _chunkJDABP4SDcjs.LoopExceededError; exports.ObjectInstance = ObjectInstance; exports.PartialExecutionResult = _chunkTCRRSS44cjs.PartialExecutionResult; exports.Snapshot = _chunkTCRRSS44cjs.Snapshot; exports.SnapshotSignal = _chunkJDABP4SDcjs.SnapshotSignal; exports.SuccessExecutionResult = _chunkTCRRSS44cjs.SuccessExecutionResult; exports.ThinkExit = _chunkTCRRSS44cjs.ThinkExit; exports.ThinkSignal = _chunkJDABP4SDcjs.ThinkSignal; exports.Tool = _chunkXGJOEQMWcjs.Tool; exports.assertValidComponent = _chunkZRCU35UVcjs.assertValidComponent; exports.execute = execute; exports.getValue = _chunkTCRRSS44cjs.getValue; exports.init = init; exports.isAnyComponent = _chunkZRCU35UVcjs.isAnyComponent; exports.isComponent = _chunkZRCU35UVcjs.isComponent; exports.renderToTsx = _chunkZRCU35UVcjs.renderToTsx; exports.utils = utils;

package/dist/index.d.ts

@@ -9,11 +9,81 @@ export { Snapshot } from './snapshots.js';
 export { Chat, type MessageHandler } from './chat.js';
 import { type ExecutionProps } from './llmz.js';
 import { ExecutionResult } from './result.js';
+import { wrapContent } from './truncator.js';
 export { Transcript } from './transcript.js';
 export { ErrorExecutionResult, ExecutionResult, PartialExecutionResult, SuccessExecutionResult } from './result.js';
-export { Trace } from './types.js';
+export { type Trace, type Traces } from './types.js';
 export { type Iteration, ListenExit, ThinkExit, DefaultExit, IterationStatuses, IterationStatus } from './context.js';
+export { type Context } from './context.js';
+export type { LLMzPrompts } from './prompts/prompt.js';
 export { type ValueOrGetter, getValue } from './getter.js';
+export declare const utils: {
+    toValidObjectName: (str: string) => string;
+    toValidFunctionName: (str: string) => string;
+    wrapContent: typeof wrapContent;
+};
+/**
+ * Executes an LLMz agent in either Chat Mode or Worker Mode.
+ *
+ * LLMz is a code-first AI agent framework that generates and runs TypeScript code
+ * in a sandbox rather than using traditional JSON tool calling. This enables complex
+ * logic, multi-tool orchestration, and native LLM thinking via comments and code structure.
+ *
+ * @param props - Configuration object for the execution
+ * @param props.client - Botpress Client or Cognitive Client instance for LLM generation
+ * @param props.instructions - System prompt/instructions for the LLM (static string or dynamic function)
+ * @param props.chat - Optional Chat instance to enable Chat Mode with user interaction
+ * @param props.tools - Array of Tool instances available to the agent (static or dynamic)
+ * @param props.objects - Array of ObjectInstance for namespaced tools and variables (static or dynamic)
+ * @param props.exits - Array of Exit definitions for structured completion (static or dynamic)
+ * @param props.snapshot - Optional Snapshot to resume paused execution
+ * @param props.signal - Optional AbortSignal to cancel execution
+ * @param props.options - Optional execution options (loop limit, temperature, model, timeout)
+ * @param props.onTrace - Optional non-blocking hook for monitoring traces during execution
+ * @param props.onIterationEnd - Optional blocking hook called after each iteration
+ * @param props.onExit - Optional blocking hook called when an exit is reached (can prevent exit)
+ * @param props.onBeforeExecution - Optional blocking hook to modify code before VM execution
+ * @param props.onBeforeTool - Optional blocking hook to modify tool inputs before execution
+ * @param props.onAfterTool - Optional blocking hook to modify tool outputs after execution
+ *
+ * @returns Promise<ExecutionResult> - Result containing success/error/interrupted status with type-safe exit checking
+ *
+ * @example
+ * // Worker Mode - Automated execution
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: 'Calculate the sum of numbers 1 to 100',
+ *   exits: [myExit]
+ * })
+ *
+ * if (result.is(myExit)) {
+ *   console.log('Result:', result.output)
+ * }
+ *
+ * @example
+ * // Chat Mode - Interactive conversation
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: 'You are a helpful assistant',
+ *   chat: myChatInstance,
+ *   tools: [searchTool, calculatorTool]
+ * })
+ *
+ * if (result.is(ListenExit)) {
+ *   // Agent is waiting for user input
+ * }
+ *
+ * @example
+ * // With dynamic instructions and hooks
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: (ctx) => `Process ${ctx.variables.dataCount} records`,
+ *   tools: async (ctx) => await getContextualTools(ctx),
+ *   options: { loop: 10, temperature: 0.1 },
+ *   onTrace: ({ trace, iteration }) => console.log(trace),
+ *   onExit: async (result) => await validateResult(result)
+ * })
+ */
 export declare const execute: (props: ExecutionProps) => Promise<ExecutionResult>;
 /**
  * Loads the necessary dependencies for the library to work