llmz 0.7.1 → 0.9.0

package/dist/index.cjs

@@ -1,17 +1,18 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dual_modes = require("./dual-modes-CfqTk9M8.cjs");
-const require_custom_client = require("./custom-client-Bp1TgTKk.cjs");
-const require_utils = require("./utils-ZpJm00ed.cjs");
-const require_tool = require("./tool-ReA9gxMp.cjs");
+const require_dual_modes = require("./dual-modes-DPXiuvNe.cjs");
+const require_common = require("./common-BnvrDnIT.cjs");
+const require_custom_client = require("./custom-client-DAsGRnYc.cjs");
+const require_utils = require("./utils-3ESwP3yg.cjs");
+const require_tool = require("./tool-Dy6AJpJH.cjs");
 const require_errors = require("./errors-C962uJdS.cjs");
-const require_typings = require("./typings-BwAz_TM9.cjs");
-const require_exit = require("./exit-BGi0Kk0y.cjs");
-const require_component = require("./component-BwixNVH8.cjs");
-const require_truncator = require("./truncator-B6aaJaN1.cjs");
+const require_typings = require("./typings-3lsqCbkn.cjs");
+const require_exit = require("./exit-DUM96DN1.cjs");
+const require_component = require("./component-C6Agl2ns.cjs");
+const require_truncator = require("./truncator-CLkouTCO.cjs");
 const require_quickjs_variant = require("./quickjs-variant-CsIwTVFC.cjs");
 let _bpinternal_zui = require("@bpinternal/zui");
 //#region package.json
-var version = "0.7.1";
+var version = "0.9.0";
 //#endregion
 //#region src/hoist.ts
 /**
@@ -798,12 +799,37 @@ const Button = new require_component.Component({
 	name: "Button",
 	aliases: ["btn"],
 	generation: {
-		usage: "Attach quick actions to a message, e.g. postback choices or a URL to open.",
-		examples: [{ props: {
-			action: "postback",
-			label: "Buy",
-			value: "buy_product"
-		} }]
+		usage: "Offer quick actions or choices after a message. It is common to send several buttons together: write one separate ■send=button block per choice in the SAME response. Each button has its own props and no body. Send all the choices before the final exit; do not wait for a user reply between buttons.",
+		examples: [
+			{ props: {
+				action: "say",
+				label: "Track my order"
+			} },
+			{ props: {
+				action: "url",
+				label: "View guide",
+				url: "https://example.com/guide"
+			} },
+			{ props: {
+				action: "postback",
+				label: "Choose Standard",
+				value: "plan_standard"
+			} },
+			[
+				{ props: {
+					action: "say",
+					label: "Track my order"
+				} },
+				{ props: {
+					action: "say",
+					label: "Return an item"
+				} },
+				{ props: {
+					action: "say",
+					label: "Contact support"
+				} }
+			]
+		]
 	},
 	leaf: { props: _bpinternal_zui.z.object({
 		action: _bpinternal_zui.z.enum([
@@ -821,10 +847,13 @@ const Image = new require_component.Component({
 	name: "Image",
 	description: "Displays an image from a URL.",
 	aliases: [],
-	generation: { examples: [{ props: {
-		url: "https://example.com/photo.jpg",
-		alt: "Example image"
-	} }] },
+	generation: {
+		usage: "Use a known image URL from the user or tool results; never invent an image URL. No body.",
+		examples: [{ props: {
+			url: "https://example.com/trail.jpg",
+			alt: "Forest trail beside a lake"
+		} }]
+	},
 	leaf: { props: _bpinternal_zui.z.object({
 		url: _bpinternal_zui.z.string().describe("The URL of the image (must be valid)"),
 		alt: _bpinternal_zui.z.string().optional().describe("Alternative text describing the image")
@@ -875,15 +904,18 @@ const Audio = new require_component.Component({
 const Card = new require_component.Component({
 	type: "container",
 	name: "Card",
-	description: "A visual card component that can include an image and buttons.",
+	description: "A card with a title, optional subtitle, and Markdown body.",
 	aliases: [],
-	generation: { examples: [{
-		props: {
-			title: "Product Name",
-			subtitle: "Limited offer"
-		},
-		body: "Featured product of the week."
-	}] },
+	generation: {
+		usage: "Present one item. The block body is Markdown, not nested component blocks or JSX.",
+		examples: [{
+			props: {
+				title: "Standard plan",
+				subtitle: "$20/month"
+			},
+			body: "Includes 5 projects and email support."
+		}]
+	},
 	container: {
 		props: _bpinternal_zui.z.object({
 			title: _bpinternal_zui.z.string().min(1).max(250).describe("Title text (1–250 characters)"),
@@ -898,6 +930,23 @@ const Card = new require_component.Component({
 		}]
 	}
 });
+const carouselProps = _bpinternal_zui.z.object({ cards: _bpinternal_zui.z.array(Card.definition.container.props.extend({
+	body: _bpinternal_zui.z.string().optional().describe("Markdown text for this card"),
+	image: Image.definition.leaf.props.optional().describe("Optional image for this card; use a known URL"),
+	buttons: _bpinternal_zui.z.array(Button.definition.leaf.props).max(5).optional().describe("Up to 5 actions for this card")
+})).min(1).max(10).describe("1–10 cards, in display order. Each card has its own title, optional subtitle, body, image, and buttons") });
+var CarouselComponent = class extends require_component.Component {
+	render(props, children = []) {
+		if (!("cards" in props) && children.length && children.every((child) => require_component.isComponent(child, Card))) return super.render(props, children);
+		const { cards } = carouselProps.parse(props);
+		const renderedCards = cards.map(({ body, image, buttons, ...cardProps }) => Card.render(cardProps, [
+			...body ? [body] : [],
+			...image ? [Image.render(image)] : [],
+			...(buttons ?? []).map((button) => Button.render(button))
+		]));
+		return super.render({}, renderedCards);
+	}
+};
 const DefaultComponents = {
 	Button,
 	Image,
@@ -905,13 +954,44 @@ const DefaultComponents = {
 	Video,
 	Audio,
 	Card,
-	Carousel: new require_component.Component({
+	Carousel: new CarouselComponent({
 		type: "container",
 		name: "Carousel",
-		description: "A virtual container for displaying 1 to 10 Card components as a carousel.",
+		description: "Displays a horizontally scrollable collection of cards, each with its own content and actions.",
 		aliases: [],
+		body: false,
+		generation: {
+			usage: "Use for several comparable items. Put ALL cards in the cards array of ONE send block. Each card can include title, subtitle, body, image {url, alt?}, and buttons [{action, label, value?, url?}]. Do not write a Markdown list or separate Card blocks; those do not form a carousel.",
+			examples: [{ props: { cards: [{
+				title: "Standard plan",
+				subtitle: "$20/month",
+				body: "5 projects and email support.",
+				image: {
+					url: "https://example.com/standard.jpg",
+					alt: "Standard plan"
+				},
+				buttons: [{
+					action: "postback",
+					label: "Choose Standard",
+					value: "plan_standard"
+				}]
+			}, {
+				title: "Team plan",
+				subtitle: "$50/month",
+				body: "20 projects and priority support.",
+				image: {
+					url: "https://example.com/team.jpg",
+					alt: "Team plan"
+				},
+				buttons: [{
+					action: "postback",
+					label: "Choose Team",
+					value: "plan_team"
+				}]
+			}] } }]
+		},
 		container: {
-			props: _bpinternal_zui.z.object({}),
+			props: carouselProps,
 			children: [{
 				description: "Card component (required, 1–10 allowed)",
 				component: Card.definition
@@ -923,16 +1003,13 @@ const DefaultComponents = {
 		name: "Message",
 		aliases: ["Text", "Markdown"],
 		description: "A Markdown-formatted text message. Long answers are written the same way: plain Markdown prose.",
-		generation: { examples: [{ body: `Great question! Deploying happens in three steps.
-
-First, connect your repository from the dashboard — we support GitHub and GitLab. Once connected, every push to your main branch triggers a build automatically.
+		generation: { examples: [{ body: `To reset your password:
 
-Then configure your build settings:
+1. Open the sign-in page and select **Forgot password?**
+2. Enter the email address you use for your account.
+3. Open the reset link in your email and choose a new password.
 
-- **Build command** — usually \`npm run build\`
-- **Output directory** — where the compiled assets end up
-
-Finally, hit **Deploy**. The first build takes a couple of minutes; subsequent ones are incremental and much faster. Want me to walk you through connecting your repository?` }, { body: "**Hello**, welcome to our service!" }] },
+If the email does not arrive, check your spam folder. If you sign in through your organization, use its password reset process.` }, { body: "How do you currently manage board meetings?" }] },
 		default: {
 			props: _bpinternal_zui.z.object({}),
 			children: []
@@ -1461,7 +1538,7 @@ function parseText(text, options) {
 	})(), options);
 }
 async function* parseResponses(stream, options) {
-	const pump = new EventPump(stream, new require_dual_modes.StreamingMessageParser(options));
+	const pump = new EventPump(stream, new require_common.StreamingMessageParser(options));
 	let activeBody;
 	while (true) {
 		if (activeBody) {
@@ -1498,34 +1575,6 @@ async function* bodyStream(pump, itemId) {
 	}
 }
 //#endregion
-//#region src/message-stream/registry.ts
-/**
-* Stores normalized component definitions. The registry (not the parser) is the
-* single source of truth for which components exist and how they are validated.
-*/
-var ComponentRegistry = class {
-	_definitions = /* @__PURE__ */ new Map();
-	constructor(definitions = []) {
-		for (const definition of definitions) this.register(definition);
-	}
-	register(definition) {
-		if (!require_dual_modes.NAME_REGEX.test(definition.name)) throw new Error(`Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`);
-		this._definitions.set(definition.name, definition);
-	}
-	unregister(name) {
-		this._definitions.delete(name);
-	}
-	has(name) {
-		return this._definitions.has(name);
-	}
-	get(name) {
-		return this._definitions.get(name);
-	}
-	list() {
-		return [...this._definitions.values()];
-	}
-};
-//#endregion
 //#region src/message-stream/normalizer.ts
 const EMPTY_PROPS_SCHEMA = {
 	type: "object",
@@ -1535,7 +1584,7 @@ const EMPTY_PROPS_SCHEMA = {
 const normalizeComponentName = (name) => name.trim().toLowerCase();
 function normalizeComponentDefinition(definition) {
 	const name = normalizeComponentName(definition.name ?? "");
-	if (!require_dual_modes.NAME_REGEX.test(name)) throw new Error(`Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`);
+	if (!require_common.NAME_REGEX.test(name)) throw new Error(`Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`);
 	return {
 		name,
 		description: definition.description,
@@ -1559,137 +1608,6 @@ function normalizePropsSchema(props, name) {
 	throw new Error(`Invalid props schema for "${name}". Expected a ZUI/Zod object schema or a JSON schema, but got type "${typeof props}".`);
 }
 //#endregion
-//#region src/message-stream/validator.ts
-/**
-* Validates a syntactically parsed `■send` item against the registered
-* component definitions. Validation is intentionally separate from parsing: a
-* validation failure never stops the stream, it only produces errors the caller
-* can turn into diagnostics or fallback rendering.
-*/
-function validateComponent(item, registry) {
-	const definition = registry.get(item.name);
-	if (!definition) {
-		const registered = registry.list().map((d) => d.name).join(", ") || "(none)";
-		return {
-			valid: false,
-			props: item.props,
-			errors: [{
-				code: "unknown-component",
-				message: `Unknown component "${item.name}". Registered components: ${registered}`
-			}]
-		};
-	}
-	const errors = [..._validateProps(item.props, definition), ..._validateBody(item, definition)];
-	return {
-		valid: errors.length === 0,
-		props: item.props,
-		errors
-	};
-}
-/** Validates a props object against a JSON schema (also used for `■next` exit props). */
-function validateProps(props, schema) {
-	const errors = [];
-	_checkValue(props, schema, "", errors);
-	return errors;
-}
-const _validateProps = (props, definition) => validateProps(props, definition.propsJsonSchema);
-const _validateBody = (item, definition) => {
-	var _definition$body;
-	const hasBody = typeof item.body === "string" && item.body.length > 0;
-	if (hasBody && !definition.body) return [{
-		code: "body-not-allowed",
-		message: `Component "${definition.name}" does not support a body`
-	}];
-	if (!hasBody && ((_definition$body = definition.body) === null || _definition$body === void 0 ? void 0 : _definition$body.required)) return [{
-		code: "missing-required-body",
-		message: `Component "${definition.name}" requires a body`
-	}];
-	return [];
-};
-const _typeOf = (value) => {
-	if (value === null) return "null";
-	if (Array.isArray(value)) return "array";
-	return typeof value;
-};
-const _matchesType = (value, type) => {
-	switch (type) {
-		case "string": return typeof value === "string";
-		case "number": return typeof value === "number";
-		case "integer": return typeof value === "number" && Number.isInteger(value);
-		case "boolean": return typeof value === "boolean";
-		case "null": return value === null;
-		case "array": return Array.isArray(value);
-		case "object": return !!value && typeof value === "object" && !Array.isArray(value);
-		default: return true;
-	}
-};
-const _isEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-/**
-* Minimal JSON-schema subset checker covering what component schemas need:
-* type, enum, const, required, properties, additionalProperties, items, anyOf/oneOf.
-* Unknown keywords are ignored (lenient by design).
-*/
-const _checkValue = (value, schema, path, errors) => {
-	if (schema === void 0 || typeof schema === "boolean" || typeof schema !== "object") return;
-	const label = path || "props";
-	const propError = (message) => {
-		errors.push({
-			code: "invalid-prop-value",
-			message,
-			path: path || void 0
-		});
-	};
-	if (schema.const !== void 0 && !_isEqual(value, schema.const)) {
-		propError(`Expected "${label}" to equal ${JSON.stringify(schema.const)}`);
-		return;
-	}
-	if (schema.enum && !schema.enum.some((allowed) => _isEqual(value, allowed))) {
-		propError(`Expected "${label}" to be one of: ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
-		return;
-	}
-	const variants = schema.anyOf ?? schema.oneOf;
-	if (variants === null || variants === void 0 ? void 0 : variants.length) {
-		if (!variants.some((variant) => {
-			const variantErrors = [];
-			_checkValue(value, variant, path, variantErrors);
-			return variantErrors.length === 0;
-		})) {
-			propError(`Value of "${label}" does not match any of the allowed types`);
-			return;
-		}
-	}
-	if (schema.type) {
-		const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-		if (!types.some((type) => _matchesType(value, type))) {
-			propError(`Expected "${label}" to be of type ${types.join(" | ")}, but got ${_typeOf(value)}`);
-			return;
-		}
-	}
-	if (Array.isArray(value) && schema.items && !Array.isArray(schema.items)) value.forEach((item, index) => _checkValue(item, schema.items, `${label}[${index}]`, errors));
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const record = value;
-		const properties = schema.properties ?? {};
-		for (const requiredKey of schema.required ?? []) if (record[requiredKey] === void 0) errors.push({
-			code: "missing-required-prop",
-			message: `Missing required prop "${path ? `${path}.` : ""}${requiredKey}"`,
-			path: path ? `${path}.${requiredKey}` : requiredKey
-		});
-		for (const [key, propValue] of Object.entries(record)) {
-			const propSchema = properties[key];
-			const propPath = path ? `${path}.${key}` : key;
-			if (propSchema === void 0) {
-				if (schema.additionalProperties === false) errors.push({
-					code: "unexpected-prop",
-					message: `Unexpected prop "${propPath}"`,
-					path: propPath
-				});
-				continue;
-			}
-			_checkValue(propValue, propSchema, propPath, errors);
-		}
-	}
-};
-//#endregion
 //#region src/message-stream/sanitize.ts
 /**
 * The protocol has no escaping mechanism by design. Any untrusted text that is
@@ -1716,6 +1634,7 @@ const utils = {
 * @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.examples - Optional labeled few-shot examples (static array 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)
@@ -1774,7 +1693,7 @@ const utils = {
 * })
 */
 const execute = async (props) => {
-	const { executeContext } = await Promise.resolve().then(() => require("./execute-msui51b2.cjs"));
+	const { executeContext } = await Promise.resolve().then(() => require("./execute-DM2-7y86.cjs"));
 	return executeContext(props);
 };
 /**
@@ -1783,32 +1702,33 @@ const execute = async (props) => {
 * It's recommended to call this function at the beginning of your application without awaiting it (void init())
 */
 const init = async () => {
-	await Promise.resolve().then(() => require("./execute-msui51b2.cjs"));
-	await Promise.resolve().then(() => require("./component-BwixNVH8.cjs")).then((n) => n.component_exports);
-	await Promise.resolve().then(() => require("./tool-ReA9gxMp.cjs")).then((n) => n.tool_exports);
-	await Promise.resolve().then(() => require("./exit-BGi0Kk0y.cjs")).then((n) => n.exit_exports);
-	await Promise.resolve().then(() => require("./jsx-BWvT6ukg.cjs")).then((n) => n.jsx_exports);
-	await Promise.resolve().then(() => require("./vm-BjkJqSQH.cjs"));
-	await Promise.resolve().then(() => require("./utils-ZpJm00ed.cjs")).then((n) => n.utils_exports);
-	await Promise.resolve().then(() => require("./truncator-B6aaJaN1.cjs")).then((n) => n.truncator_exports);
-	await Promise.resolve().then(() => require("./typings-BwAz_TM9.cjs")).then((n) => n.typings_exports);
-	await Promise.resolve().then(() => require("./dual-modes-CfqTk9M8.cjs")).then((n) => n.dual_modes_exports);
+	await Promise.resolve().then(() => require("./execute-DM2-7y86.cjs"));
+	await Promise.resolve().then(() => require("./component-C6Agl2ns.cjs")).then((n) => n.component_exports);
+	await Promise.resolve().then(() => require("./tool-Dy6AJpJH.cjs")).then((n) => n.tool_exports);
+	await Promise.resolve().then(() => require("./exit-DUM96DN1.cjs")).then((n) => n.exit_exports);
+	await Promise.resolve().then(() => require("./jsx-owqxrquU.cjs")).then((n) => n.jsx_exports);
+	await Promise.resolve().then(() => require("./vm-D6s1zF6M.cjs"));
+	await Promise.resolve().then(() => require("./utils-3ESwP3yg.cjs")).then((n) => n.utils_exports);
+	await Promise.resolve().then(() => require("./truncator-CLkouTCO.cjs")).then((n) => n.truncator_exports);
+	await Promise.resolve().then(() => require("./typings-3lsqCbkn.cjs")).then((n) => n.typings_exports);
+	await Promise.resolve().then(() => require("./dual-modes-DPXiuvNe.cjs")).then((n) => n.dual_modes_exports);
 };
 //#endregion
 exports.BaseResponse = BaseResponse;
 exports.Chat = Chat;
 exports.CitationsManager = CitationsManager;
 exports.Component = require_component.Component;
-exports.ComponentRegistry = ComponentRegistry;
+exports.ComponentRegistry = require_dual_modes.ComponentRegistry;
 exports.DefaultComponents = DefaultComponents;
 exports.DefaultExit = require_custom_client.DefaultExit;
 exports.ErrorExecutionResult = require_custom_client.ErrorExecutionResult;
+exports.Example = require_dual_modes.Example;
 exports.ExecutionResult = require_custom_client.ExecutionResult;
 exports.Exit = require_exit.Exit;
 exports.ListenExit = require_custom_client.ListenExit;
 exports.LoopExceededError = require_errors.LoopExceededError;
-exports.MARKER = require_dual_modes.MARKER;
-exports.NAME_REGEX = require_dual_modes.NAME_REGEX;
+exports.MARKER = require_common.MARKER;
+exports.NAME_REGEX = require_common.NAME_REGEX;
 exports.NextResponse = NextResponse;
 exports.ObjectInstance = ObjectInstance;
 exports.PartialExecutionResult = require_custom_client.PartialExecutionResult;
@@ -1817,7 +1737,7 @@ exports.RunResponse = RunResponse;
 exports.SendResponse = SendResponse;
 exports.Snapshot = require_custom_client.Snapshot;
 exports.SnapshotSignal = require_errors.SnapshotSignal;
-exports.StreamingMessageParser = require_dual_modes.StreamingMessageParser;
+exports.StreamingMessageParser = require_common.StreamingMessageParser;
 exports.SuccessExecutionResult = require_custom_client.SuccessExecutionResult;
 exports.ThinkExit = require_custom_client.ThinkExit;
 exports.ThinkSignal = require_errors.ThinkSignal;
@@ -1840,10 +1760,10 @@ exports.parseExit = require_custom_client.parseExit;
 exports.parseStream = parseStream;
 exports.parseText = parseText;
 exports.sanitizeMessageText = sanitizeMessageText;
-exports.tryParseJson = require_dual_modes.tryParseJson;
+exports.tryParseJson = require_common.tryParseJson;
 exports.utils = utils;
-exports.validateComponent = validateComponent;
-exports.validateProps = validateProps;
+exports.validateComponent = require_dual_modes.validateComponent;
+exports.validateProps = require_dual_modes.validateProps;
 Object.defineProperty(exports, "version", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { version } from '../package.json';
+export { Example, type ExampleDefinition, type ExampleMessage } from './example.js';
 export { Tool } from './tool.js';
 export { Exit, type ExitResult } from './exit.js';
 export { ObjectInstance } from './objects.js';
@@ -42,6 +43,7 @@ export declare const utils: {
  * @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.examples - Optional labeled few-shot examples (static array 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)