llmz 0.8.0 → 1.0.1

package/README.md

@@ -1,605 +1,153 @@
-# LLMz
+# LLMZ
 
-**Stop chaining tools. Start generating code.**
+LLMZ runs agents that use JavaScript to call tools, work with data, and return typed outcomes. The model receives one native `run_javascript` tool. Programs run in a sandbox; the host supplies the business tools they can call.
 
-LLMz is a TypeScript AI agent framework that replaces traditional JSON tool calling with executable code generation. Instead of orchestrating tools through multiple LLM roundtrips, agents write and execute TypeScript directly—enabling complex logic, loops, and multi-tool coordination in a single pass.
+Use `Session` for conversation history and retained values, `Chat` for text and component delivery, and `Exit` for structured completion.
 
-Powers millions of production agents at [Botpress](https://botpress.com).
+[API guide](./DOCS.md) · [Examples](./examples) · [Migration](./DOCS.md#migrating-from-the-previous-api)
 
-|     |                                                                                           |
-| --- | ----------------------------------------------------------------------------------------- |
-| 📚  | [**Examples →**](https://github.com/botpress/botpress/tree/master/packages/llmz/examples) |
+## Installation
 
----
-
-## The Problem with Tool Calling
-
-Traditional agentic frameworks (LangChain, CrewAI, MCP servers) rely on JSON tool calling:
-
-```json
-{
-  "tool": "getTicketPrice",
-  "parameters": { "from": "quebec", "to": "new york" }
-}
+```sh
+pnpm add llmz @botpress/cognitive @bpinternal/zui @bpinternal/thicktoken
 ```
 
-This breaks down quickly:
-
-- **Verbose schemas**: LLMs struggle with complex JSON structures
-- **No logic**: Can't express conditionals, loops, or error handling
-- **Multiple roundtrips**: Each tool call requires another LLM inference ($$$)
-- **Fragile composition**: Chaining tools is error-prone and expensive
-
-You end up with brittle agents that cost 10-100x more than they should.
-
----
-
-## The LLMz Solution
-
-LLMz generates and executes **real TypeScript code** in a secure sandbox:
-
-```typescript
-const price = await getTicketPrice({ from: 'quebec', to: 'new york' })
-
-if (price > 500) {
-  throw new Error('Price too high')
-}
-
-const ticketId = await buyTicket({ from: 'quebec', to: 'new york' })
-```
-
-**Why this works:**
-
-- LLMs have seen billions of lines of TypeScript—they're exceptionally good at it
-- Complex logic (loops, conditionals, error handling) happens in one inference
-- Multiple tool calls execute synchronously without LLM roundtrips
-- Full type safety via Zui schemas and TypeScript inference
-
-**Real-world impact**: Anthropic reduced agent costs by 98.7% using code execution patterns ([source](https://www.anthropic.com/engineering/code-execution-with-mcp)).
-
----
-
-## The ■ Protocol
-
-Every model response is a sequence of streaming-native `■` blocks:
-
-```
-■send=message
-Let me check the next launch dates for the Moon...
-■run
-const dates = await checkAvailability({ destination: 'moon' })
-const reservation = await bookTrip({ destination: 'moon', date: dates[0], travelerName: 'Ada' })
-const payment = await processPayment({ reservationId: reservation.reservationId })
-return { ...payment, date: dates[0] }
-```
+The following examples assume `BOTPRESS_BOT_ID` and `BOTPRESS_TOKEN` are configured for Cognitive. Examples are type-checked with `pnpm check:docs`.
 
-- **`■send=<component> {props?}`** — sends a message to the user, delivered (and streamable) the moment it is parsed
-- **`■run`** — executes the TypeScript body in the sandbox; the returned value is fed back to the model
-- **`■next=<exit> {props?}`** — ends the turn through a typed exit (the built-in `listen` hands the turn back to the user)
+## Start a conversation
 
-Because the protocol is parsed incrementally, messages stream to your UI token-by-token, tool calls surface live, and code execution can start before the response has even finished streaming.
+```ts
+import { Cognitive } from '@botpress/cognitive'
+import { Chat, Session, execute } from 'llmz'
 
-Only explicit `■send` blocks produce messages or message deltas. Unexpected text outside protocol blocks is discarded in streaming, fallback restarts, and nonstreaming execution. Explicit Markdown (`■send=md`) is supported. A response with only unexpected text follows the normal invalid-response retry/error path. For debugging, `iteration.llm.output` retains the raw response and `iteration.llm.diagnostics` records parser diagnostics, including `unexpected-text`.
-
-As of 0.7.0, the parser options `strict` and `recoveryComponent` have been removed. All parsing requires explicit send blocks; callers relying on implicit messages must emit `■send=<component>` instead.
-
----
-
-## Quick Start
-
-**Requirements:** Node.js 20+
-
-```bash
-npm install @botpress/client llmz
-```
-
-### Platform Support
-
-| Platform           | Support |
-| ------------------ | ------- |
-| Node.js 20+        | ✅ Full |
-| Browser            | ✅ Full |
-| AWS Lambda         | ✅ Full |
-| Cloudflare Workers | ✅ Full |
-| Bun                | ✅ Full |
-| Deno               | ✅ Full |
-
-#### Sandbox Execution
-
-LLMz uses **QuickJS** (a lightweight JavaScript engine compiled to WebAssembly) to execute generated code in a secure, isolated sandbox. This provides:
-
-- **Complete isolation**: No access to filesystem, network, or host environment
-- **Memory limits**: Configurable heap size to prevent resource exhaustion
-- **Execution timeouts**: Automatic termination of runaway code
-- **Abort signals**: Support for programmatic execution cancellation
-- **Universal compatibility**: Works everywhere WebAssembly is supported
-
-The QuickJS sandbox is bundled as a singlefile variant with WASM inlined as base64, so it works out-of-the-box with any bundler (esbuild, webpack, vite, rollup) without configuration.
-
-### Worker Mode: Autonomous Execution
-
-```typescript
-import { Client } from '@botpress/client'
-import { execute } from 'llmz'
-
-const client = new Client({ botId: '...', token: '...' })
-
-const result = await execute({
-  instructions: 'Calculate sum of integers 14-1078 divisible by 3, 9, or 5',
-  client,
+const client = new Cognitive({
+  botId: process.env.BOTPRESS_BOT_ID!,
+  token: process.env.BOTPRESS_TOKEN!,
 })
-
-console.log(result.output) // 271575
-```
-
-**Generated response:**
-
-```
-■run
-let sum = 0
-for (let i = 14; i <= 1078; i++) {
-  if (i % 3 === 0 || i % 9 === 0 || i % 5 === 0) {
-    sum += i
-  }
-}
-return sum
-```
-
-### Chat Mode: Interactive Agents
-
-```typescript
-import { execute, Chat, DefaultComponents, ListenExit } from 'llmz'
-
-const transcript = []
-
+const session = new Session()
 const chat = new Chat({
-  components: [DefaultComponents.Text, DefaultComponents.Button],
-  transcript: () => transcript,
-
-  // Complete messages, delivered as soon as they are parsed
-  handler: async (component) => {
-    render(component)
-  },
-
-  // Optional: message body chunks, streamed while the LLM is still generating
-  onMessageDelta: (delta) => {
-    appendToBubble(delta.id, delta.delta)
+  response: {
+    preset: 'markdown',
+    handler: (text) => {
+      console.log(text)
+    },
   },
 })
 
-while (true) {
-  const result = await execute({ client, chat, tools: [searchFlights, bookTicket] })
+session.append({ role: 'user', content: 'Help me plan a weekend in Montreal.' })
+const result = await execute({ client, session, chat, instructions: 'Be concise and helpful.' })
 
-  if (result.is(ListenExit)) {
-    // Agent handed the turn back — wait for user input
-    transcript.push({ role: 'user', content: await getUserInput() })
-  } else {
-    break // Agent completed (custom exit) or errored
-  }
+if (result.isError()) {
+  console.error(result.error)
 }
 ```
 
-**Generated response:**
+Append the next message and call `execute` again with the same session. Inputs appended during execution wait for the next turn. Await one execution before starting another on that session.
 
-```
-■send=message
-Found 12 flights. The cheapest is **$249**. Want me to book it?
-■send=button {"label": "Book flight", "action": "postback", "value": "book"}
-■send=button {"label": "Cancel", "action": "postback", "value": "cancel"}
-■next=listen
-```
-
----
-
-## Core Concepts
+## Return a typed result
 
-### Execution Modes
+Workers complete through a named exit. Tool input and exit output use Zui schemas.
 
-**Worker Mode**: Autonomous agents that execute to completion
-
-```typescript
-const result = await execute({
-  instructions: 'Analyze Q4 sales data and generate report',
-  client,
-  tools: [fetchSales, calculateMetrics, generatePDF],
-})
-```
-
-**Chat Mode**: Interactive conversations with user input
-
-```typescript
-const result = await execute({
-  client,
-  tools,
-  chat, // a Chat instance: components + transcript + message handler
-})
-```
-
-### Tools: Type-Safe Functions
-
-```typescript
-import { Tool } from 'llmz'
+```ts
+import { Cognitive } from '@botpress/cognitive'
 import { z } from '@bpinternal/zui'
+import { Exit, Tool, execute } from 'llmz'
 
-const searchFlights = new Tool({
-  name: 'searchFlights',
-  description: 'Search for available flights',
-  input: z.object({
-    from: z.string(),
-    to: z.string(),
-    date: z.string(),
-  }),
-  output: z.array(
-    z.object({
-      id: z.string(),
-      price: z.number(),
-      departure: z.string(),
-    })
-  ),
-  handler: async ({ from, to, date }) => {
-    // Your implementation
-    return flights
-  },
+const client = new Cognitive({
+  botId: process.env.BOTPRESS_BOT_ID!,
+  token: process.env.BOTPRESS_TOKEN!,
 })
-```
-
-Tools are exposed to agents with full TypeScript signatures. Agents call them like regular async functions — and chain them freely inside a single `■run` block.
-
-Tool handlers can also be **async generators** that push UI components to the chat mid-execution (progress bars, previews) before returning their result — see [example 21](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/21_chat_tool_components).
-
-### Objects: Namespaced State
-
-Group related tools and variables:
-
-```typescript
-import { ObjectInstance } from 'llmz'
-import { z } from '@bpinternal/zui'
-
-const database = new ObjectInstance({
-  name: 'db',
-  description: 'Database operations',
-  tools: [queryUsers, updateRecord, deleteRecord],
-  properties: [
-    {
-      name: 'connectionString',
-      value: process.env.DB_URL,
-      writable: false,
-    },
-    {
-      name: 'lastQueryTime',
-      value: null,
-      type: z.string().nullable(),
-      writable: true,
-    },
-  ],
+const getPrice = new Tool({
+  name: 'getPrice',
+  description: 'Look up the unit price of an item.',
+  input: z.object({ sku: z.string() }),
+  output: z.number(),
+  handler: async ({ sku }) => (sku === 'coffee' ? 12 : 0),
 })
-```
-
-Agents access via namespaces:
-
-```typescript
-const users = await db.queryUsers({ active: true })
-db.lastQueryTime = new Date().toISOString()
-```
-
-### Exits: Structured Termination
-
-Define how agents can complete:
-
-```typescript
-import { Exit } from 'llmz'
-import { z } from '@bpinternal/zui'
-
-const TicketBooked = new Exit({
-  name: 'ticket_booked',
-  description: 'Successfully booked a ticket',
-  schema: z.object({
-    ticketId: z.string(),
-    price: z.number(),
-    confirmation: z.string(),
-  }),
+const done = new Exit({
+  name: 'done',
+  description: 'Return the calculated total.',
+  schema: z.object({ total: z.number() }),
 })
 
 const result = await execute({
   client,
-  tools,
-  exits: [TicketBooked],
+  instructions: 'Calculate the price of three units of coffee and finish with done.',
+  tools: [getPrice],
+  exits: [done],
 })
 
-if (result.is(TicketBooked)) {
-  console.log('Booked:', result.output.ticketId) // Fully typed
+if (result.is(done)) {
+  console.log(result.output.total)
+} else if (result.isError()) {
+  console.error(result.error)
 }
 ```
 
-Agents invoke exits with a `■next` block:
+The model can compose tool calls in a program. It uses `return inspect(value)` to examine evidence in another iteration, and `return exit('done', payload)` to finish. [Execution and memory](./DOCS.md#execution-and-memory) explains their lifetimes.
 
-```
-■next=ticket_booked {"ticketId": "TKT-12345", "price": 299, "confirmation": "ABC123"}
-```
+## Save a conversation
 
----
+Persist the session after execution settles. The execution result contains the outcome and diagnostics for one run.
 
-## Streaming
+```ts
+import { Session } from 'llmz'
 
-With a streaming client (`CognitiveBeta` / Cognitive v2), everything an execution produces surfaces in real time:
+const session = new Session({ variables: { accountId: 'customer-42' } })
+session.append({ role: 'user', content: 'Check my account.' })
 
-```typescript
-const chat = new Chat({
-  components: [DefaultComponents.Text],
-  transcript: () => transcript,
-  handler: async (component, metadata) => finalizeBubble(component, metadata),
-  // Fires per token-chunk while the LLM is still generating
-  onMessageDelta: (delta) => {
-    if (delta.restart) {
-      // Remove ALL this iteration's messages, including completed handler sends.
-      return clearIterationMessages(delta.iterationId)
-    }
-    return updateBubble(delta.iterationId, delta.id, delta.content)
-  },
-})
+const saved = JSON.stringify(session.toJSON())
+const restored = Session.fromJSON(JSON.parse(saved))
 
-const result = await execute({
-  client, // CognitiveBeta
-  chat,
-  tools,
-  options: { midStreamFallback: true },
-  onTrace: ({ trace }) => {
-    if (trace.type === 'llm_call_started') showSpinner()
-    if (trace.type === 'code_generation_started') showStatus('writing code…')
-    if (trace.type === 'llm_call_success') showCode(trace.code)
-    if (trace.type === 'tool_call') showToolCall(trace)
-  },
-})
+console.log(restored.pendingMessages)
+console.log(restored.memory.variables.accountId)
 ```
 
-- **Message deltas** stream to your UI token-by-token (`handler` remains the authoritative delivery)
-- **Live traces** cover the full turn lifecycle: `llm_call_started` → message deltas → `code_generation_started` → `llm_call_success` (with the code) → `tool_call`s → exit
-- **Fallback**: a `restart: true` delta invalidates the current iteration's messages before replacement output arrives. Replacement messages have fresh IDs under the same `iterationId`. Code executes only after the replacement stream succeeds; abandoned code never runs.
-- **Early execution**: without `midStreamFallback`, a closed `■run` block can start executing while the response tail is still streaming. A later generation failure returns an error without retrying the code. The VM pre-warms when code generation begins in either mode.
-
-Terminal failures return an `ErrorExecutionResult`; they do not emit a restart delta because there is no replacement attempt. Handle that result to clear or mark unfinished messages as failed. Already delivered messages remain delivered unless your consumer retracts them. Nonstreaming Cognitive fallback exposes only the successful response, so no message reset is needed.
+A failed execution retains its active turn. Calling `execute` again continues that turn; newly queued input remains separate. Completed tool effects are not rolled back. [Persistence and recovery](./DOCS.md#persistence-and-recovery) documents this contract.
 
-LLMz rejects explicit Cognitive errors, error metadata (`provider: "unknown"`), and responses stopped by a token limit or content filter before finalizing unfinished blocks. Such failures cannot turn a partial code prefix into executable code. With fallback disabled, this cannot undo code that already ran after a block boundary.
+## Stream text
 
-`■run` followed by `■send` is currently accepted, but that message was generated without seeing the code's result. Prefer sending an acknowledgement before `■run`, returning the needed data, then answering in the next iteration. A top-level `return` always requests another iteration; side-effect-only code can finish immediately with `■next`.
+`onDelta` receives provisional text. `handler` receives the complete accepted response. A restart retracts the preview for that iteration.
 
-Forward these events over a websocket or SSE stream and your frontend renders the agent live — see [example 22](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/22_chat_streaming).
+```ts
+import { Chat } from 'llmz'
 
-### Token Usage & Timings
-
-Every iteration reports what it consumed:
-
-```typescript
-const { input, output, total, limit, context } = result.iteration.tokens
-// context measures the prompt size by part (pre-truncation):
-// { framework, instructions, tools, transcript, protocol, iterations, total }
-console.log(`context used: ${Math.round((context.total / limit) * 100)}%`)
-
-const { time_to_first_token, time_to_last_token } = result.iteration.llm
-
-// Aggregated across all iterations:
-console.log(result.tokens) // { input, output, total }
-```
-
-### Execution Options
-
-```typescript
-const result = await execute({
-  client,
-  model: ['cerebras:gpt-oss-120b', 'anthropic:claude-haiku-4-5'], // fallback chain
-  reasoningEffort: 'low', // 'low' | 'medium' | 'high' | 'dynamic' | 'none'
-  options: {
-    loop: 5, // max iterations
-    timeout: 60_000, // VM execution timeout (ms)
-    maxTokens: 32_000, // context window cap: min(maxTokens, model max)
-    maxTimeToFirstToken: 5_000, // fall back to the next model if the first token is late (ms)
-  },
-})
-```
-
----
-
-## Advanced Features
-
-### Thinking: Forced Reflection
-
-Tools can force the agent to look at data before acting on it:
-
-```typescript
-import { ThinkSignal } from 'llmz'
-
-const complexAnalysis = new Tool({
-  name: 'analyze',
-  handler: async (data) => {
-    const result = performComplexCalculation(data)
-    // Force agent to reflect on results before proceeding
-    throw new ThinkSignal('Analysis complete. Review data before next step.')
-  },
-})
-```
-
-Agents self-initiate reflection by returning values from their code — the returned value is shown to them and they respond again:
-
-```
-■run
-const data = await fetchLargeDataset()
-return data.summary
-```
-
-### Snapshots: Pause and Resume
-
-Save execution state for long-running workflows:
-
-```typescript
-import { SnapshotSignal } from 'llmz'
-
-const approvalRequired = new Tool({
-  name: 'submitForApproval',
-  handler: async (request) => {
-    await saveToDatabase(request)
-    // Halt execution until manual approval
-    throw new SnapshotSignal('Awaiting manager approval')
-  },
-})
-
-// Later, resume from snapshot
-const result = await execute({
-  client,
-  snapshot: savedSnapshot,
-})
-```
-
-### Hooks: Custom Logic Injection
-
-```typescript
-const result = await execute({
-  client,
-  tools,
-
-  // Non-blocking: observe everything (and abort when needed)
-  onTrace: ({ trace, controller }) => {
-    logger.info(trace)
-    if (trace.type === 'tool_call' && trace.tool_name === 'forbidden') {
-      controller.abort('Forbidden tool call')
-    }
-  },
-
-  // Validate before allowing an exit — throw to retry, abort to stop
-  onExit: (result, controller) => {
-    if (result.exit.name === 'transfer_money' && result.result.amount > 10_000) {
-      throw new Error('Amount exceeds limit')
-    }
-  },
-
-  // Inspect/modify generated code before execution
-  onBeforeExecution: (iteration) => {
-    if (iteration.code?.includes('dangerousOperation')) {
-      return { code: '// blocked' }
-    }
+const previews = new Map<string, string>()
+const chat = new Chat({
+  response: {
+    preset: 'text',
+    onDelta: (event) => {
+      if (event.restart) {
+        previews.delete(event.iterationId)
+      } else {
+        previews.set(event.iterationId, event.content)
+      }
+    },
+    handler: (text, metadata) => {
+      previews.delete(metadata.iterationId)
+      console.log(metadata.id, text)
+    },
   },
-
-  // Also available: onIterationStart, onIterationEnd, onBeforeTool, onAfterTool
 })
 ```
 
----
-
-## Coming from MCP?
-
-LLMz is **not** a replacement for MCP—it's complementary.
-
-**MCP** (Model Context Protocol): Standardizes how AI applications connect to data sources and tools across processes/machines.
-
-**LLMz**: Replaces the execution pattern _after_ tools are exposed. Instead of making multiple LLM calls to orchestrate MCP tools via JSON, LLMz generates TypeScript code that calls those same tools in a single inference—reducing costs by up to 98%.
-
----
-
-## Production Ready
-
-LLMz has been running in production for over a year:
+Streaming requires a client with `generateTextStream`. See [streaming semantics](./DOCS.md#streaming-and-delivery) before enabling model fallback.
 
-- **Millions** of active users across enterprise and consumer applications
-- **Hundreds of thousands** of deployed agents handling real-world workloads
-- **Secure sandbox**: Uses QuickJS WASM for isolated code execution
-- **Type-safe**: Full TypeScript inference and Zui validation
-- **Observable**: Comprehensive tracing, token accounting and error handling
+## Examples and development
 
----
+- [Basic chat](./examples/01_chat_basic/index.ts)
+- [Typed chat exits](./examples/02_chat_exits/index.ts)
+- [Rich components](./examples/10_chat_components/index.ts)
+- [Worker tool chaining](./examples/16_worker_tool_chaining/index.ts)
+- [Streaming chat](./examples/22_chat_streaming/index.ts)
 
-## Architecture
-
-**Execution Pipeline:**
-
-1. **Prompt Generation**: Injects tools, schemas, and context into dual-mode prompts
-2. **Streaming Generation**: The LLM streams ■ blocks — messages dispatch to the chat as they are parsed
-3. **Compilation**: Babel AST transformation with instrumentation plugins (line tracking, tool call tracking, variable extraction)
-4. **Execution**: Runs in QuickJS WASM sandbox with full isolation — starting while the response tail is still streaming
-5. **Result Processing**: Type-safe exit handling, thinking loops and error recovery
-
-**Security:**
-
-- QuickJS WASM sandbox with complete isolation (no filesystem/network access)
-- Stack trace sanitization (removes internal framework details)
-- Configurable memory limits and execution timeouts
-- Tool-level permissions and rate limiting
-- Automatic token limit handling
-
----
-
-## Comparison
-
-| Feature                  | LangChain / CrewAI     | MCP Servers            | LLMz                      |
-| ------------------------ | ---------------------- | ---------------------- | ------------------------- |
-| Tool calling             | JSON                   | JSON                   | TypeScript code           |
-| Multi-tool orchestration | Multiple LLM calls     | Multiple LLM calls     | Single LLM call           |
-| Complex logic            | Limited                | Limited                | Full language support     |
-| Type safety              | Partial                | Schema-based           | Full TypeScript + Zui     |
-| Streaming                | Text only              | Text only              | Messages, code, tools     |
-| Execution environment    | Python/JS runtime      | Cross-process          | QuickJS WASM sandbox      |
-| Cost (complex workflows) | High (many roundtrips) | High (many roundtrips) | Low (one-shot generation) |
-| Production scale         | Varies                 | Emerging               | Battle-tested (1M+ users) |
-
----
-
-## Examples
-
-Check out the [examples folder](https://github.com/botpress/botpress/tree/master/packages/llmz/examples) for complete working examples:
-
-| Title                                                                                                                 | Mode   | Description                                                                               |
-| --------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
-| [Basic Chat](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/01_chat_basic)                   | Chat   | Simple interactive chat with button-based navigation                                      |
-| [Chat with Exits](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/02_chat_exits)              | Chat   | Custom exit conditions with type-safe validation                                          |
-| [Conditional Tools](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/03_chat_conditional_tool) | Chat   | Dynamic tool availability based on context                                                |
-| [Small Models](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/04_chat_small_models)          | Chat   | Optimized prompts for smaller language models                                             |
-| [Web Search](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/05_chat_web_search)              | Chat   | Integrate web search and content browsing                                                 |
-| [Tool Confirmation](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/06_chat_confirm_tool)     | Chat   | User confirmation before executing tools                                                  |
-| [Guardrails](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/07_chat_guardrails)              | Chat   | Safety constraints and content filtering                                                  |
-| [Multi-Agent](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/08_chat_multi_agent)            | Chat   | Coordinating multiple agents in one system                                                |
-| [Variables](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/09_chat_variables)                | Chat   | Stateful properties that persist across iterations                                        |
-| [Components](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/10_chat_components)              | Chat   | Rich UI components for interactive experiences                                            |
-| [Minimal Worker](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/11_worker_minimal)           | Worker | One-shot computational task execution                                                     |
-| [File System](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/12_worker_fs)                   | Worker | Automated file operations with conditional logic                                          |
-| [Sandbox](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/13_worker_sandbox)                  | Worker | Secure isolated code execution environment                                                |
-| [Snapshots](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/14_worker_snapshot)               | Worker | Pause and resume long-running workflows                                                   |
-| [Stack Traces](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/15_worker_stacktraces)         | Worker | Error handling and debugging patterns                                                     |
-| [Tool Chaining](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/16_worker_tool_chaining)      | Worker | Sequential multi-tool orchestration                                                       |
-| [Error Recovery](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/17_worker_error_recovery)    | Worker | Graceful failure handling and retries                                                     |
-| [Security](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/18_worker_security)                | Worker | Code inspection and security validation                                                   |
-| [Wrap Tools](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/19_worker_wrap_tool)             | Worker | Creating higher-order tool abstractions                                                   |
-| [RAG](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/20_chat_rag)                            | Chat   | Retrieval-augmented generation with knowledge bases                                       |
-| [Tool Components](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/21_chat_tool_components)    | Chat   | Tool handlers pushing UI components mid-execution                                         |
-| [Streaming](https://github.com/botpress/botpress/tree/master/packages/llmz/examples/22_chat_streaming)                | Chat   | Guided simulation: streamed messages, live code + tool calls, typed exits, per-turn stats |
-
----
-
-## Contributing
-
-```bash
-git clone https://github.com/botpress/botpress
-cd packages/llmz
-
-pnpm install
+```sh
 pnpm test
-pnpm build
+pnpm check:type
+pnpm check:e2e:type
+pnpm check:docs
+pnpm check:lint
+pnpm check:format
 ```
 
-**Commands:**
-
-- `pnpm test`: Run test suite (Vitest with LLM retries)
-- `pnpm test:watch`: Watch mode for development
-- `pnpm build`: Compile TypeScript and bundle (ESM + CJS)
-- `pnpm generate`: Regenerate prompt templates from markdown
-
----
-
-## License
-
-MIT
-
----
-
-## Learn More
-
-- [Anthropic: Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)
-- [How Code Execution Reduces Agent Costs by 98%](https://medium.com/@meshuggah22/weve-been-using-mcp-wrong-how-anthropic-reduced-ai-agent-costs-by-98-7-7c102fc22589)
-- [Botpress Documentation](https://botpress.com/docs)
+Unit tests use scripted clients. Model evaluations run separately through `pnpm test:e2e` and require the configured provider credentials.