llmz 0.0.13 → 0.0.15

package/dist/objects.d.ts

@@ -1,18 +1,305 @@
 import { z } from '@bpinternal/zui';
 import { Tool } from './tool.js';
+import { Serializable } from './types.js';
+/**
+ * Defines a property within an ObjectInstance.
+ *
+ * Properties are stateful variables that can be accessed and optionally modified
+ * by the generated TypeScript code. They provide a way to maintain state across
+ * execution iterations and can include validation rules.
+ *
+ * @example
+ * ```typescript
+ * const userAgeProperty: ObjectProperty = {
+ *   name: 'age',
+ *   description: 'User age with validation constraints',
+ *   value: 25,
+ *   type: z.number().min(18).max(100),
+ *   writable: true,
+ * }
+ * ```
+ */
 export type ObjectProperty = {
+    /** The name of the property (must be a valid TypeScript identifier) */
     name: string;
+    /** The current value of the property */
     value: any;
+    /** Optional Zod schema for validation when the property is modified */
     type?: z.Schema;
+    /** Optional human-readable description of the property */
     description?: string;
+    /** Whether the LLM can modify this property (default: false) */
     writable?: boolean;
 };
-export declare class ObjectInstance {
+export declare namespace ObjectInstance {
+    type JSON = {
+        name: string;
+        description?: string;
+        properties?: ObjectProperty[];
+        tools?: Tool.JSON[];
+        metadata?: Record<string, unknown>;
+    };
+}
+/**
+ * ObjectInstance creates stateful, namespace-scoped objects for LLMz agents.
+ *
+ * Objects combine properties (stateful variables) and tools (functions) into a
+ * single namespace that the LLM can interact with. This provides organized,
+ * type-safe interfaces for complex data and functionality.
+ *
+ * ## Key Features
+ * - **Stateful Properties**: Variables that persist across execution iterations
+ * - **Validation**: Zod schema validation for property changes
+ * - **Tool Grouping**: Organize related tools under a common namespace
+ * - **Type Safety**: Full TypeScript inference and validation
+ * - **Dynamic Updates**: Properties can reflect real-time state changes
+ *
+ * ## Use Cases
+ * - **User Profile Management**: Collect and validate user data over time
+ * - **API Namespacing**: Group related API calls under a common interface
+ * - **State Machines**: Track and modify execution state
+ * - **Configuration Objects**: Manage settings and preferences
+ * - **Multi-Agent Systems**: Per-agent state and capabilities
+ *
+ * ## Basic Usage
+ *
+ * ### Simple Property Object
+ * ```typescript
+ * const userProfile = new ObjectInstance({
+ *   name: 'user',
+ *   description: 'User profile data',
+ *   properties: [
+ *     {
+ *       name: 'name',
+ *       value: 'John Doe',
+ *       type: z.string().min(1),
+ *       writable: true,
+ *     },
+ *     {
+ *       name: 'email',
+ *       value: null,
+ *       type: z.string().email().nullable(),
+ *       writable: true,
+ *     },
+ *     {
+ *       name: 'id',
+ *       value: 'user_123',
+ *       writable: false, // Read-only
+ *     },
+ *   ],
+ * })
+ *
+ * // LLM can access and modify: user.name, user.email
+ * // LLM can read only: user.id
+ * ```
+ *
+ * ### Tool Grouping
+ * ```typescript
+ * const fileSystem = new ObjectInstance({
+ *   name: 'fs',
+ *   description: 'File system operations',
+ *   tools: [
+ *     new Tool({
+ *       name: 'readFile',
+ *       input: z.object({ path: z.string() }),
+ *       output: z.string(),
+ *       handler: async ({ path }) => readFileSync(path, 'utf8'),
+ *     }),
+ *     new Tool({
+ *       name: 'writeFile',
+ *       input: z.object({ path: z.string(), content: z.string() }),
+ *       handler: async ({ path, content }) => writeFileSync(path, content),
+ *     }),
+ *   ],
+ * })
+ *
+ * // LLM can call: fs.readFile(), fs.writeFile()
+ * ```
+ *
+ * ### Combined Properties and Tools
+ * ```typescript
+ * const database = new ObjectInstance({
+ *   name: 'db',
+ *   description: 'Database connection with state',
+ *   properties: [
+ *     {
+ *       name: 'connectionString',
+ *       value: 'postgresql://localhost:5432/mydb',
+ *       writable: false,
+ *     },
+ *     {
+ *       name: 'lastQuery',
+ *       value: null,
+ *       type: z.string().nullable(),
+ *       writable: true,
+ *     },
+ *   ],
+ *   tools: [
+ *     new Tool({
+ *       name: 'query',
+ *       input: z.object({ sql: z.string() }),
+ *       output: z.array(z.record(z.any())),
+ *       handler: async ({ sql }) => {
+ *         // Execute query and update lastQuery property
+ *         const results = await executeQuery(sql)
+ *         return results
+ *       },
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * ## Dynamic Objects
+ *
+ * Objects can be created dynamically to reflect current state:
+ *
+ * ```typescript
+ * const memory: Record<string, any> = {}
+ *
+ * const getObjects = () => [
+ *   new ObjectInstance({
+ *     name: 'user',
+ *     properties: [
+ *       {
+ *         name: 'name',
+ *         value: memory.name ?? null,
+ *         type: z.string().nullable(),
+ *         writable: true,
+ *       },
+ *       {
+ *         name: 'age',
+ *         value: memory.age ?? null,
+ *         type: z.number().min(18).max(100).nullable(),
+ *         writable: true,
+ *       },
+ *     ],
+ *   }),
+ * ]
+ *
+ * await execute({
+ *   objects: getObjects, // Function returning current state
+ *   onTrace: ({ trace }) => {
+ *     if (trace.type === 'property') {
+ *       // Persist property changes
+ *       memory[trace.property] = trace.value
+ *     }
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * ## Property Validation
+ *
+ * Properties support comprehensive validation through Zod schemas:
+ *
+ * ```typescript
+ * const userSettings = new ObjectInstance({
+ *   name: 'settings',
+ *   properties: [
+ *     {
+ *       name: 'theme',
+ *       value: 'light',
+ *       type: z.enum(['light', 'dark']),
+ *       writable: true,
+ *     },
+ *     {
+ *       name: 'maxRetries',
+ *       value: 3,
+ *       type: z.number().min(1).max(10),
+ *       writable: true,
+ *     },
+ *     {
+ *       name: 'email',
+ *       value: null,
+ *       type: z.string().email().nullable(),
+ *       writable: true,
+ *     },
+ *   ],
+ * })
+ * ```
+ *
+ * ## TypeScript Integration
+ *
+ * Objects generate TypeScript namespace declarations:
+ *
+ * ```typescript
+ * // Generated types for the LLM context:
+ * export namespace user {
+ *   const name: Writable<string | null> = null
+ *   const age: Writable<number | null> = null
+ *   const id: Readonly<string> = "user_123"
+ * }
+ *
+ * export namespace fs {
+ *   function readFile(args: { path: string }): Promise<string>
+ *   function writeFile(args: { path: string, content: string }): Promise<void>
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/09_chat_variables/index.ts} Example usage
+ */
+export declare class ObjectInstance implements Serializable<ObjectInstance.JSON> {
     name: string;
     description?: string;
     properties?: ObjectProperty[];
     tools?: Tool[];
     metadata?: Record<string, unknown>;
+    /**
+     * 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: {
         name: string;
         description?: string;
@@ -20,5 +307,67 @@ export declare class ObjectInstance {
         properties?: ObjectProperty[];
         metadata?: Record<string, unknown>;
     });
+    /**
+     * 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>
+     * // }
+     * ```
+     */
     getTypings(): Promise<string>;
+    /**
+     * 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(): {
+        name: string;
+        description: string | undefined;
+        properties: ObjectProperty[] | undefined;
+        tools: {
+            name: string;
+            aliases: string[];
+            description: string | undefined;
+            metadata: Record<string, unknown>;
+            input: import("json-schema").JSONSchema7 | undefined;
+            output: import("json-schema").JSONSchema7 | undefined;
+            staticInputValues: unknown;
+            maxRetries: number;
+        }[];
+        metadata: Record<string, unknown> | undefined;
+    };
 }