llmz 0.3.1 → 0.5.0

package/dist/component.d.ts

@@ -1,10 +1,29 @@
 import { z } from '@bpinternal/zui';
 import { JsxComponent } from './jsx.js';
+import type { BodyFormat, GenerativeComponentMetadata } from './message-stream/types.js';
+/**
+ * @deprecated TSX-era examples are no longer shown to the model — llmz
+ * generates ■-protocol blocks, not TSX. Use `generation.examples`
+ * ({ props?, body? }) instead.
+ */
 export type ExampleUsage = {
     name: string;
     description: string;
     code: string;
 };
+/**
+ * Optional body configuration for components that accept a message body
+ * (`default` and `container` types). Controls how the body is documented to
+ * the model in the ■ protocol reference.
+ */
+export type ComponentBodyOptions = {
+    /** How the body should be written: 'markdown' (default), 'text' (plain prose) or 'code'. */
+    format?: BodyFormat;
+    /** Model-facing description of what the body must contain. */
+    description?: string;
+    /** Whether a body is required. Defaults to true. */
+    required?: boolean;
+};
 export type ComponentChild = {
     description: string;
     component: ComponentDefinition;
@@ -15,7 +34,12 @@ export type DefaultComponentDefinition<T extends z.ZodObject<any> = z.ZodObject<
     name: string;
     aliases: string[];
     description: string;
+    /** @deprecated Not shown to the model. Use `generation.examples` instead. */
     examples?: ExampleUsage[];
+    /** Body configuration for the ■ protocol reference (format, description, required). */
+    body?: ComponentBodyOptions;
+    /** Model-facing generation metadata: usage guidance and ■-protocol examples ({ props?, body? }). */
+    generation?: GenerativeComponentMetadata;
     default: {
         props: T;
         children: Array<ComponentChild>;
@@ -26,7 +50,10 @@ export type LeafComponentDefinition<T extends z.ZodObject<any> = z.ZodObject<any
     name: string;
     description: string;
     aliases?: string[];
+    /** @deprecated Not shown to the model. Use `generation.examples` instead. */
     examples?: ExampleUsage[];
+    /** Model-facing generation metadata: usage guidance and ■-protocol examples ({ props? }). */
+    generation?: GenerativeComponentMetadata;
     leaf: {
         props: T;
     };
@@ -36,7 +63,12 @@ export type ContainerComponentDefinition<T extends z.ZodObject<any> = z.ZodObjec
     name: string;
     description: string;
     aliases?: string[];
+    /** @deprecated Not shown to the model. Use `generation.examples` instead. */
     examples?: ExampleUsage[];
+    /** Body configuration for the ■ protocol reference (format, description, required). */
+    body?: ComponentBodyOptions;
+    /** Model-facing generation metadata: usage guidance and ■-protocol examples ({ props?, body? }). */
+    generation?: GenerativeComponentMetadata;
     container: {
         props: T;
         children: Array<ComponentChild>;

package/dist/component.default.d.ts

@@ -6,11 +6,16 @@ export declare const DefaultComponents: {
         description: string;
         name: string;
         aliases: string[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            usage: string;
+            examples: {
+                props: {
+                    action: string;
+                    label: string;
+                    value: string;
+                };
+            }[];
+        };
         leaf: {
             props: z.ZodObject<{
                 action: z.ZodDefault<z.ZodEnum<["say", "url", "postback"]>>;
@@ -25,11 +30,14 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            examples: {
+                props: {
+                    url: string;
+                    alt: string;
+                };
+            }[];
+        };
         leaf: {
             props: z.ZodObject<{
                 url: z.ZodString;
@@ -42,11 +50,14 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            examples: {
+                props: {
+                    url: string;
+                    name: string;
+                };
+            }[];
+        };
         leaf: {
             props: z.ZodObject<{
                 url: z.ZodString;
@@ -59,11 +70,14 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            examples: {
+                props: {
+                    url: string;
+                    title: string;
+                };
+            }[];
+        };
         leaf: {
             props: z.ZodObject<{
                 url: z.ZodString;
@@ -76,11 +90,14 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            examples: {
+                props: {
+                    url: string;
+                    title: string;
+                };
+            }[];
+        };
         leaf: {
             props: z.ZodObject<{
                 url: z.ZodString;
@@ -93,11 +110,15 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
+        generation: {
+            examples: {
+                props: {
+                    title: string;
+                    subtitle: string;
+                };
+                body: string;
+            }[];
+        };
         container: {
             props: z.ZodObject<{
                 title: z.ZodString;
@@ -110,11 +131,14 @@ export declare const DefaultComponents: {
                     name: string;
                     description: string;
                     aliases: never[];
-                    examples: {
-                        name: string;
-                        description: string;
-                        code: string;
-                    }[];
+                    generation: {
+                        examples: {
+                            props: {
+                                url: string;
+                                alt: string;
+                            };
+                        }[];
+                    };
                     leaf: {
                         props: z.ZodObject<{
                             url: z.ZodString;
@@ -129,11 +153,16 @@ export declare const DefaultComponents: {
                     description: string;
                     name: string;
                     aliases: string[];
-                    examples: {
-                        name: string;
-                        description: string;
-                        code: string;
-                    }[];
+                    generation: {
+                        usage: string;
+                        examples: {
+                            props: {
+                                action: string;
+                                label: string;
+                                value: string;
+                            };
+                        }[];
+                    };
                     leaf: {
                         props: z.ZodObject<{
                             action: z.ZodDefault<z.ZodEnum<["say", "url", "postback"]>>;
@@ -151,11 +180,6 @@ export declare const DefaultComponents: {
         name: string;
         description: string;
         aliases: never[];
-        examples: {
-            name: string;
-            description: string;
-            code: string;
-        }[];
         container: {
             props: z.ZodObject<{}, "strip">;
             children: {
@@ -165,11 +189,15 @@ export declare const DefaultComponents: {
                     name: string;
                     description: string;
                     aliases: never[];
-                    examples: {
-                        name: string;
-                        description: string;
-                        code: string;
-                    }[];
+                    generation: {
+                        examples: {
+                            props: {
+                                title: string;
+                                subtitle: string;
+                            };
+                            body: string;
+                        }[];
+                    };
                     container: {
                         props: z.ZodObject<{
                             title: z.ZodString;
@@ -182,11 +210,14 @@ export declare const DefaultComponents: {
                                 name: string;
                                 description: string;
                                 aliases: never[];
-                                examples: {
-                                    name: string;
-                                    description: string;
-                                    code: string;
-                                }[];
+                                generation: {
+                                    examples: {
+                                        props: {
+                                            url: string;
+                                            alt: string;
+                                        };
+                                    }[];
+                                };
                                 leaf: {
                                     props: z.ZodObject<{
                                         url: z.ZodString;
@@ -201,11 +232,16 @@ export declare const DefaultComponents: {
                                 description: string;
                                 name: string;
                                 aliases: string[];
-                                examples: {
-                                    name: string;
-                                    description: string;
-                                    code: string;
-                                }[];
+                                generation: {
+                                    usage: string;
+                                    examples: {
+                                        props: {
+                                            action: string;
+                                            label: string;
+                                            value: string;
+                                        };
+                                    }[];
+                                };
                                 leaf: {
                                     props: z.ZodObject<{
                                         action: z.ZodDefault<z.ZodEnum<["say", "url", "postback"]>>;
@@ -226,11 +262,31 @@ export declare const DefaultComponents: {
         name: string;
         aliases: string[];
         description: string;
-        examples: {
-            name: string;
+        generation: {
+            examples: {
+                body: string;
+            }[];
+        };
+        default: {
+            props: z.ZodObject<{}, "strip">;
+            children: never[];
+        };
+    }>;
+    Speech: Component<{
+        type: "default";
+        name: string;
+        aliases: string[];
+        description: string;
+        body: {
+            format: "text";
             description: string;
-            code: string;
-        }[];
+        };
+        generation: {
+            usage: string;
+            examples: {
+                body: string;
+            }[];
+        };
         default: {
             props: z.ZodObject<{}, "strip">;
             children: never[];

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import { Models } from '@botpress/cognitive';
+import { Models, SttModels } from '@botpress/cognitive';
 import { z } from '@bpinternal/zui';
 import { Chat } from './chat.js';
 import { Component } from './component.js';
@@ -564,6 +564,11 @@ export declare class Context implements Serializable<Context.JSON> {
      * before the cognitive service falls back to the next model/provider.
      */
     maxTimeToFirstToken?: number;
+    /**
+     * STT model used by the cognitive service to transcribe audio attachments
+     * when the target LLM does not support audio natively. Defaults to 'fast'.
+     */
+    transcriptionModel?: SttModels;
     metadata: Record<string, any>;
     snapshot?: Snapshot;
     iteration: number;
@@ -595,6 +600,7 @@ export declare class Context implements Serializable<Context.JSON> {
         timeout?: number;
         maxTokens?: number;
         maxTimeToFirstToken?: number;
+        transcriptionModel?: SttModels;
     });
     toJSON(): {
         id: string;

package/dist/{dual-modes-BYABHBDI.js → dual-modes-S5TJ5JVJ.js}

@@ -1,6 +1,6 @@
 import {
   DualModePrompt
-} from "./chunk-OXEKAOVI.js";
+} from "./chunk-LOX7GOR6.js";
 import "./chunk-YEAWWJSJ.js";
 import "./chunk-72ZWBNZV.js";
 import "./chunk-GLXADNTR.js";

package/dist/{dual-modes-HO6RRIZ5.cjs → dual-modes-TCMWBZIH.cjs}

@@ -1,10 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkOVRDJMZJcjs = require('./chunk-OVRDJMZJ.cjs');
+var _chunkKTDBAJBBcjs = require('./chunk-KTDBAJBB.cjs');
 require('./chunk-KIN7Y247.cjs');
 require('./chunk-HEAQAEFZ.cjs');
 require('./chunk-GOWPACSK.cjs');
 require('./chunk-HC2QZTVT.cjs');
 
 
-exports.DualModePrompt = _chunkOVRDJMZJcjs.DualModePrompt;
+exports.DualModePrompt = _chunkKTDBAJBBcjs.DualModePrompt;

package/dist/{execute-DPCZ6PKH.js → execute-FF7D46TY.js}

@@ -11,11 +11,11 @@ import {
   SuccessExecutionResult,
   _CustomModelClient,
   parseExit
-} from "./chunk-XMFQVARN.js";
+} from "./chunk-4POZJQXN.js";
 import {
   StreamingMessageParser,
   toParsedAssistantResponse
-} from "./chunk-OXEKAOVI.js";
+} from "./chunk-LOX7GOR6.js";
 import "./chunk-UGHFNCPD.js";
 import "./chunk-TDALRNGL.js";
 import "./chunk-GDJTKI7J.js";
@@ -168,6 +168,9 @@ var generateCode = async ({
     ended_at: startedAt,
     model: model.id
   });
+  const hasAudioParts = messages.some(
+    (message) => Array.isArray(message.content) && message.content.some((part) => part.type === "audio")
+  );
   const input = {
     model: iteration.model,
     temperature: iteration.temperature,
@@ -175,7 +178,8 @@ var generateCode = async ({
     reasoningEffort: iteration.reasoningEffort,
     messages,
     stopSequences: ctx.version.getStopTokens(),
-    meta: metadata ? { metadata } : void 0
+    meta: metadata ? { metadata } : void 0,
+    options: hasAudioParts ? { transcriptionModel: ctx.transcriptionModel ?? "fast" } : void 0
   };
   let responseMetadata;
   let raw;
@@ -232,7 +236,7 @@ var generateCode = async ({
         ...input,
         // Passed through to the cognitive request: fall back to the next
         // model/provider when the first token takes too long
-        ...ctx.maxTimeToFirstToken ? { options: { maxTimeToFirstToken: ctx.maxTimeToFirstToken } } : {}
+        ...ctx.maxTimeToFirstToken ? { options: { ...input.options, maxTimeToFirstToken: ctx.maxTimeToFirstToken } } : {}
       },
       { signal: streamController.signal }
     );
@@ -735,7 +739,7 @@ var executeContext = async (props) => {
   return result;
 };
 var executeContextInternal = async (props) => {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e;
   const controller = createJoinedAbortController([props.signal]);
   const { onIterationStart, onIterationEnd, onTrace, onExit, onBeforeExecution, onAfterTool, onBeforeTool } = props;
   const client = props.client ?? new Client();
@@ -749,6 +753,7 @@ var executeContextInternal = async (props) => {
     timeout: (_b = props.options) == null ? void 0 : _b.timeout,
     maxTokens: (_c = props.options) == null ? void 0 : _c.maxTokens,
     maxTimeToFirstToken: (_d = props.options) == null ? void 0 : _d.maxTimeToFirstToken,
+    transcriptionModel: (_e = props.options) == null ? void 0 : _e.transcriptionModel,
     exits: props.exits,
     snapshot: props.snapshot,
     model: props.model,

package/dist/{execute-2H4F7GFE.cjs → execute-IK6O4SU2.cjs}

@@ -11,11 +11,11 @@ var _chunk3UZKLXADcjs = require('./chunk-3UZKLXAD.cjs');
 
 
 
-var _chunkKG5E3UZZcjs = require('./chunk-KG5E3UZZ.cjs');
+var _chunk5WBNTV42cjs = require('./chunk-5WBNTV42.cjs');
 
 
 
-var _chunkOVRDJMZJcjs = require('./chunk-OVRDJMZJ.cjs');
+var _chunkKTDBAJBBcjs = require('./chunk-KTDBAJBB.cjs');
 require('./chunk-RGUG3UMF.cjs');
 require('./chunk-PZE6PIPG.cjs');
 require('./chunk-HMMM32RG.cjs');
@@ -168,6 +168,9 @@ var generateCode = async ({
     ended_at: startedAt,
     model: model.id
   });
+  const hasAudioParts = messages.some(
+    (message) => Array.isArray(message.content) && message.content.some((part) => part.type === "audio")
+  );
   const input = {
     model: iteration.model,
     temperature: iteration.temperature,
@@ -175,7 +178,8 @@ var generateCode = async ({
     reasoningEffort: iteration.reasoningEffort,
     messages,
     stopSequences: ctx.version.getStopTokens(),
-    meta: metadata ? { metadata } : void 0
+    meta: metadata ? { metadata } : void 0,
+    options: hasAudioParts ? { transcriptionModel: _nullishCoalesce(ctx.transcriptionModel, () => ( "fast")) } : void 0
   };
   let responseMetadata;
   let raw;
@@ -223,7 +227,7 @@ var generateCode = async ({
     }
   };
   if (typeof cognitive.generateTextStream === "function") {
-    const parser = new (0, _chunkOVRDJMZJcjs.StreamingMessageParser)();
+    const parser = new (0, _chunkKTDBAJBBcjs.StreamingMessageParser)();
     const fence = new LeadingFenceFilter();
     const streamController = createJoinedAbortController([controller.signal]);
     const requestedAt = Date.now();
@@ -232,7 +236,7 @@ var generateCode = async ({
         ...input,
         // Passed through to the cognitive request: fall back to the next
         // model/provider when the first token takes too long
-        ...ctx.maxTimeToFirstToken ? { options: { maxTimeToFirstToken: ctx.maxTimeToFirstToken } } : {}
+        ...ctx.maxTimeToFirstToken ? { options: { ...input.options, maxTimeToFirstToken: ctx.maxTimeToFirstToken } } : {}
       },
       { signal: streamController.signal }
     );
@@ -282,7 +286,7 @@ var generateCode = async ({
       await dispatchSends(parser.push(remaining));
     }
     await dispatchSends(parser.finish());
-    assistantResponse = _chunkOVRDJMZJcjs.toParsedAssistantResponse.call(void 0, parser.items, raw);
+    assistantResponse = _chunkKTDBAJBBcjs.toParsedAssistantResponse.call(void 0, parser.items, raw);
   } else {
     const response = await cognitive.generateText(input, { signal: controller.signal }).catch((thrown) => {
       throw new (0, _chunkPK72FAKDcjs.CognitiveError)(`LLM generation failed: ${_chunkGOWPACSKcjs.getErrorMessage.call(void 0, thrown)}`);
@@ -432,7 +436,7 @@ var applyNextExit = async ({
   if (!next) {
     throw new Error("applyNextExit called without a \u25A0next block on the iteration");
   }
-  const attempt = (props) => _chunkKG5E3UZZcjs.parseExit.call(void 0, Object.keys(props).length ? { action: next.name, value: props } : { action: next.name }, iteration.exits);
+  const attempt = (props) => _chunk5WBNTV42cjs.parseExit.call(void 0, Object.keys(props).length ? { action: next.name, value: props } : { action: next.name }, iteration.exits);
   let parsedExit = attempt(next.props);
   const keys = Object.keys(next.props);
   if (!parsedExit.success && keys.length === 1 && ["props", "value", "data"].includes(keys[0])) {
@@ -735,12 +739,12 @@ var executeContext = async (props) => {
   return result;
 };
 var executeContextInternal = async (props) => {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e;
   const controller = createJoinedAbortController([props.signal]);
   const { onIterationStart, onIterationEnd, onTrace, onExit, onBeforeExecution, onAfterTool, onBeforeTool } = props;
   const client = _nullishCoalesce(props.client, () => ( new (0, _client.Client)()));
-  const cognitive = _cognitive.Cognitive.isCognitiveClient(client) || _chunkKG5E3UZZcjs._CustomModelClient.isCustomClient(client) ? client : new (0, _cognitive.Cognitive)({ client });
-  const ctx = new (0, _chunkKG5E3UZZcjs.Context)({
+  const cognitive = _cognitive.Cognitive.isCognitiveClient(client) || _chunk5WBNTV42cjs._CustomModelClient.isCustomClient(client) ? client : new (0, _cognitive.Cognitive)({ client });
+  const ctx = new (0, _chunk5WBNTV42cjs.Context)({
     chat: props.chat,
     instructions: props.instructions,
     objects: props.objects,
@@ -749,6 +753,7 @@ var executeContextInternal = async (props) => {
     timeout: (_b = props.options) == null ? void 0 : _b.timeout,
     maxTokens: (_c = props.options) == null ? void 0 : _c.maxTokens,
     maxTimeToFirstToken: (_d = props.options) == null ? void 0 : _d.maxTimeToFirstToken,
+    transcriptionModel: (_e = props.options) == null ? void 0 : _e.transcriptionModel,
     exits: props.exits,
     snapshot: props.snapshot,
     model: props.model,
@@ -758,7 +763,7 @@ var executeContextInternal = async (props) => {
   try {
     while (true) {
       if (ctx.iterations.length >= ctx.loop) {
-        return new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, new (0, _chunkPK72FAKDcjs.LoopExceededError)());
+        return new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, new (0, _chunkPK72FAKDcjs.LoopExceededError)());
       }
       const iteration = await ctx.nextIteration();
       const unsubscribeTrace = iteration.traces.onPush((traces) => {
@@ -789,7 +794,7 @@ var executeContextInternal = async (props) => {
               }
             }
           });
-          return new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted")));
+          return new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted")));
         }
         const iterationResult = await executeIterationWithErrorHandling({
           iteration,
@@ -819,7 +824,7 @@ var executeContextInternal = async (props) => {
       }
     }
   } catch (error) {
-    return new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, _nullishCoalesce(error, () => ( "Unknown error")));
+    return new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(error, () => ( "Unknown error")));
   }
 };
 var executeIterationStartHook = async ({
@@ -906,7 +911,7 @@ var executeIterationWithErrorHandling = async ({
     if (!controller.signal.aborted) {
       return {
         type: "return",
-        result: new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, err)
+        result: new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, err)
       };
     }
     await finalizeIteration({
@@ -922,7 +927,7 @@ var executeIterationWithErrorHandling = async ({
     });
     return {
       type: "return",
-      result: new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted")))
+      result: new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted")))
     };
   }
 };
@@ -934,7 +939,7 @@ var transformIterationResult = ({
     const exitName = iteration.status.exit_success.exit_name;
     return {
       type: "return",
-      result: new (0, _chunkKG5E3UZZcjs.SuccessExecutionResult)(ctx, {
+      result: new (0, _chunk5WBNTV42cjs.SuccessExecutionResult)(ctx, {
         exit: iteration.exits.find((x) => x.name === exitName),
         result: iteration.status.exit_success.return_value
       })
@@ -943,17 +948,17 @@ var transformIterationResult = ({
   if (iteration.status.type === "callback_requested") {
     return {
       type: "return",
-      result: new (0, _chunkKG5E3UZZcjs.PartialExecutionResult)(
+      result: new (0, _chunk5WBNTV42cjs.PartialExecutionResult)(
         ctx,
         iteration.status.callback_requested.signal,
-        _chunkKG5E3UZZcjs.Snapshot.fromSignal(iteration.status.callback_requested.signal)
+        _chunk5WBNTV42cjs.Snapshot.fromSignal(iteration.status.callback_requested.signal)
       )
     };
   }
   if (iteration.status.type === "aborted") {
     return {
       type: "return",
-      result: new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( "The operation was aborted")))
+      result: new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( "The operation was aborted")))
     };
   }
   if (iteration.status.type === "thinking_requested" || iteration.status.type === "exit_error" || iteration.status.type === "execution_error" || iteration.status.type === "invalid_code_error") {
@@ -961,7 +966,7 @@ var transformIterationResult = ({
   }
   return {
     type: "return",
-    result: new (0, _chunkKG5E3UZZcjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( `Unknown error. Status: ${iteration.status.type}`)))
+    result: new (0, _chunk5WBNTV42cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( `Unknown error. Status: ${iteration.status.type}`)))
   };
 };
 var executeIteration = async ({