llmz 0.7.1 → 0.9.0

package/dist/index.js

@@ -1,5 +1,6 @@
-import { a as StreamingMessageParser, c as NAME_REGEX, o as tryParseJson, r as generateInstructions, s as MARKER } from "./dual-modes-mNyMThtf.js";
-import { a as ThinkExit, c as ExecutionResult, d as Snapshot, f as parseExit, i as ListenExit, l as PartialExecutionResult, o as getValue, r as DefaultExit, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-CMuy7fXU.js";
+import { d as generateInstructions, f as validateComponent, m as ComponentRegistry, p as validateProps, u as Example } from "./dual-modes-DDkoCp3R.js";
+import { c as MARKER, l as NAME_REGEX, o as StreamingMessageParser, s as tryParseJson } from "./common-BlRFtdf2.js";
+import { a as ThinkExit, c as ExecutionResult, d as Snapshot, f as parseExit, i as ListenExit, l as PartialExecutionResult, o as getValue, r as DefaultExit, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-ChuZ63zp.js";
 import { a as getMultilineComment, c as isJsonSchema, l as isValidIdentifier, m as toValidObjectName, n as escapeString, p as toValidFunctionName, t as configureTokenizer, u as isZuiSchema, v as upperFirst } from "./utils-UBeAFeEI.js";
 import { t as Tool } from "./tool-Bv8N4IPj.js";
 import { c as SnapshotSignal, l as ThinkSignal, o as LoopExceededError, r as CodeFormattingError } from "./errors-Cg1G0Awu.js";
@@ -10,7 +11,7 @@ import { i as wrapContent, n as truncateWrappedContent, t as stripTruncationTags
 import { t as configureQuickJS } from "./quickjs-variant-BYhMBpwU.js";
 import { transforms, z } from "@bpinternal/zui";
 //#region package.json
-var version = "0.7.1";
+var version = "0.9.0";
 //#endregion
 //#region src/hoist.ts
 /**
@@ -797,12 +798,37 @@ const Button = new 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: z.object({
 		action: z.enum([
@@ -820,10 +846,13 @@ const Image = new 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: z.object({
 		url: z.string().describe("The URL of the image (must be valid)"),
 		alt: z.string().optional().describe("Alternative text describing the image")
@@ -874,15 +903,18 @@ const Audio = new Component({
 const Card = new 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: z.object({
 			title: z.string().min(1).max(250).describe("Title text (1–250 characters)"),
@@ -897,6 +929,23 @@ const Card = new Component({
 		}]
 	}
 });
+const carouselProps = z.object({ cards: z.array(Card.definition.container.props.extend({
+	body: 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: 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 Component {
+	render(props, children = []) {
+		if (!("cards" in props) && children.length && children.every((child) => 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,
@@ -904,13 +953,44 @@ const DefaultComponents = {
 	Video,
 	Audio,
 	Card,
-	Carousel: new 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: z.object({}),
+			props: carouselProps,
 			children: [{
 				description: "Card component (required, 1–10 allowed)",
 				component: Card.definition
@@ -922,16 +1002,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: z.object({}),
 			children: []
@@ -1497,34 +1574,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 (!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",
@@ -1558,137 +1607,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
@@ -1715,6 +1633,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)
@@ -1773,7 +1692,7 @@ const utils = {
 * })
 */
 const execute = async (props) => {
-	const { executeContext } = await import("./execute-DP_17lYZ.js");
+	const { executeContext } = await import("./execute-BWcdv9so.js");
 	return executeContext(props);
 };
 /**
@@ -1782,16 +1701,16 @@ 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 import("./execute-DP_17lYZ.js");
+	await import("./execute-BWcdv9so.js");
 	await import("./component-DGG7d_Mz.js").then((n) => n.r);
 	await import("./tool-Bv8N4IPj.js").then((n) => n.n);
 	await import("./exit-CDdxDBRT.js").then((n) => n.n);
 	await import("./jsx-CIgdGGVs.js").then((n) => n.i);
-	await import("./vm-C5vf1LH3.js");
+	await import("./vm-BLsHw1da.js");
 	await import("./utils-UBeAFeEI.js").then((n) => n.h);
 	await import("./truncator-DZqEqnpD.js").then((n) => n.r);
 	await import("./typings-CrBa7Tyy.js").then((n) => n.n);
-	await import("./dual-modes-mNyMThtf.js").then((n) => n.n);
+	await import("./dual-modes-DDkoCp3R.js").then((n) => n.n);
 };
 //#endregion
-export { BaseResponse, Chat, CitationsManager, Component, ComponentRegistry, DefaultComponents, DefaultExit, ErrorExecutionResult, ExecutionResult, Exit, ListenExit, LoopExceededError, MARKER, NAME_REGEX, NextResponse, ObjectInstance, PartialExecutionResult, ReplayableAsyncIterable, RunResponse, SendResponse, Snapshot, SnapshotSignal, StreamingMessageParser, SuccessExecutionResult, ThinkExit, ThinkSignal, Tool, _CustomModelClient, assertValidComponent, collectText, configureQuickJS, configureTokenizer, execute, generateInstructions, getValue, init, isAnyComponent, isComponent, normalizeComponentDefinition, normalizeComponentName, normalizePropsSchema, parseExit, parseStream, parseText, sanitizeMessageText, tryParseJson, utils, validateComponent, validateProps, version };
+export { BaseResponse, Chat, CitationsManager, Component, ComponentRegistry, DefaultComponents, DefaultExit, ErrorExecutionResult, Example, ExecutionResult, Exit, ListenExit, LoopExceededError, MARKER, NAME_REGEX, NextResponse, ObjectInstance, PartialExecutionResult, ReplayableAsyncIterable, RunResponse, SendResponse, Snapshot, SnapshotSignal, StreamingMessageParser, SuccessExecutionResult, ThinkExit, ThinkSignal, Tool, _CustomModelClient, assertValidComponent, collectText, configureQuickJS, configureTokenizer, execute, generateInstructions, getValue, init, isAnyComponent, isComponent, normalizeComponentDefinition, normalizeComponentName, normalizePropsSchema, parseExit, parseStream, parseText, sanitizeMessageText, tryParseJson, utils, validateComponent, validateProps, version };