@swizzy_ai/kit 1.0.0 → 1.0.1

package/README.md

@@ -2,583 +2,987 @@
 
 <div align="center">
 
-<h1 style="font-size:2.5em; font-weight:bold; margin:1em 0;">
-  <img
-    src="https://img.shields.io/badge/Wizard-Framework-blue?style=for-the-badge&logo=magic&logoColor=white"
-    alt="Wizard Framework"
-    style="border-radius: 10px;"
-  />
-</h1>
+**A Framework for Designing LLM Experiences**
 
-**Type-Safe AI Workflow Framework**
-
-[![npm version](https://img.shields.io/badge/npm-1.0.0-blue.svg?style=flat&logo=npm)](https://www.npmjs.com/package/@swizzy_ai/kit)
+[![npm version](https://img.shields.io/badge/npm-1.0.0-blue.svg)](https://www.npmjs.com/package/@swizzy_ai/kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
-
-[![GitHub stars](https://img.shields.io/github/stars/swizzy-ai/wizard-framework?style=social)](https://github.com/swizzy-ai/wizard-framework/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/swizzy-ai/wizard-framework?style=social)](https://github.com/swizzy-ai/wizard-framework/network/members)
-[![GitHub watchers](https://img.shields.io/github/watchers/swizzy-ai/wizard-framework?style=social)](https://github.com/swizzy-ai/wizard-framework/watchers)
 
-⭐ If you find Wizard Framework useful, please give it a star. It helps the community grow!
-
-*Structured Control • Type Safety First • Full Observability*
+[Install](#installation) • [Documentation](https://docs.wizard.dev) • [Examples](#examples)
 
 </div>
 
 ---
 
-## Project Status[![](./docs/img/pin.svg)](#project-status)
-
-<table>
-  <tr>
-    <td><img src="https://img.shields.io/badge/Build-Passing-brightgreen.svg?style=flat&logo=github-actions&logoColor=white" alt="Build Status"/></td>
-    <td><img src="https://img.shields.io/badge/Tests-Passing-brightgreen.svg?style=flat&logo=jest&logoColor=white" alt="Test Status"/></td>
-    <td><img src="https://img.shields.io/badge/Coverage-95%25-brightgreen.svg?style=flat&logo=codecov&logoColor=white" alt="Coverage"/></td>
-  </tr>
-  <tr>
-    <td><img src="https://img.shields.io/badge/Solution-TypeScript-blue.svg?style=flat&logo=typescript&logoColor=white&labelColor=363D44" alt="TypeScript solution"/></td>
-    <td><img src="https://img.shields.io/badge/Runtime-Node.js-blue?style=flat&logo=node.js&logoColor=white&labelColor=363D44" alt="Node.js runtime"/></td>
-    <td><img src="https://img.shields.io/badge/AI-LLM%20Integration-blue?style=flat&logo=openai&logoColor=white&labelColor=363D44" alt="AI Integration"/></td>
-  </tr>
-</table>
+## Why Wizard Exists
 
----
+### The Current State is Broken
+
+Today's LLM orchestration assumes the **LLM itself is the agent** - an intelligent entity you hand tools to and hope it figures things out. This paradigm works brilliantly in controlled environments (see: Claude Code's success), but fails catastrophically when:
+
+- The environment isn't perfectly curated
+- Mistakes or hallucinations have real costs
+- Context limits constrain what the model can see
+- Each turn summons a "new spirit" with no memory of the last
+
+The mental model is fundamentally flawed.
 
-## Table of Contents[![](./docs/img/pin.svg)](#table-of-contents)
+### What Wizard Believes
 
-- [What is a Wizard?](#what-is-a-wizard)
-- [The 3 Core Pillars](#the-3-core-pillars)
-- [Installation](#installation)
-- [Core Components](#core-components)
-- [Feature Spotlight: Bungee Jumps](#feature-spotlight-bungee-jumps)
-- [Developer Experience](#developer-experience)
-- [API Reference](#api-reference)
-- [Examples](#examples)
-- [Contributing](#contributing)
-- [License](#license)
-- [Call to Action](#call-to-action)
+**Real agency and intelligence are emergent products of process and design.**
 
-> [!IMPORTANT]
-> Full technical guidance for building, using, and integrating Wizard Framework is available in the [documentation](./docs/ "Wizard Framework documentation").
+Wizard inverts the paradigm: the **developer is the orchestrator**, the **LLM is the user**. You design the experience - what information to present, what to collect, what happens next. The LLM focuses on what it does best: generating the most plausible text for each scenario.
+
+This is agentic Lego bricks, not autonomous agents.
 
 ---
 
-## What is a Wizard?[![](./docs/img/pin.svg)](#what-is-a-wizard)
+## Installation
+
+```bash
+npm install @swizzy_ai/kit
+```
+
+### API Key Configuration
+
+For multimodal functions and different LLM providers, set all your API keys as environment variables:
 
-A **Wizard** transforms AI workflows into deterministic state machines. Instead of chaining LLM calls haphazardly, Wizards provide structured control flow, type-safe data handling, and complete observability.
+```bash
+# Required for multimodal features
+export OPENAI_API_KEY="your-openai-key"
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export GEMINI_API_KEY="your-gemini-key"
+```
+
+Or configure them programmatically:
 
 ```javascript
 const { Wizard, Models } = require('@swizzy_ai/kit');
 
 const wizard = new Wizard({
   id: 'my-workflow',
-  onUsage: (usage, provider) => {
-    console.log(`Used ${usage.totalTokens} tokens`);
+  apiKeys: {
+    openai: process.env.OPENAI_API_KEY,
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    gemini: process.env.GEMINI_API_KEY,
+    groq: process.env.GROQ_API_KEY,
+    together: process.env.TOGETHER_API_KEY
   }
 });
 ```
 
-### The 3 Core Pillars
+---
+
+## Core Concepts
+
+### Understanding Wizard's Architecture
+
+Wizard workflows operate on a simple execution loop:
+
+```
+Step → LLM Generation → Update Function → Signal → Next Step
+```
 
-#### 🏗️ Structured Control
-Move beyond unstructured chains to finite state machines. Every step has a clear purpose, and flow control is explicit and predictable.
+You, the developer, design each step in this loop:
+- **What the LLM sees** (via context functions)
+- **What the LLM generates** (via instructions and schemas)
+- **What happens next** (via signals)
+
+The LLM never decides where to go or what to do - it only generates text based on what you show it and where to tell it. You orchestrate the intelligence.
+
+---
+
+### Context and State Management
+
+**Context** is the shared state that flows through your entire workflow. Every step can read from it and write to it.
+
+#### Setting Initial Context
 
 ```javascript
-wizard.addTextStep({
-  id: 'analyze_sentiment',
-  instruction: 'Analyze sentiment of: {{text}}',
-  schema: z.object({
-    sentiment: z.enum(['positive', 'negative', 'neutral']),
-    confidence: z.number().min(0).max(1)
-  }),
-  model: Models.SWIZZY_DEFAULT,
+wizard.setContext({
+  userQuestion: 'What are the key findings?',
+  documents: [
+    { title: 'Q1 Report', pages: 45, data: [...] },
+    { title: 'Q2 Report', pages: 52, data: [...] }
+  ],
+  processedCount: 0
+});
+```
+
+#### Reading Context
+
+Context is available in every `update` function and `context`:
+
+```javascript
+wizard.addComputeStep({
+  id: 'check_status',
   update: (result, context, actions) => {
-    if (result.confidence < 0.8) {
-      return actions.retry(); // Explicit error handling
-    }
-    return actions.next(); // Clear flow control
+    // Access any context property
+    console.log(`Processed ${context.processedCount} documents`);
+    return actions.next();
   }
 });
 ```
 
-#### 🔒 Type Safety First
-Leverage Zod schemas to ensure LLMs produce usable data structures, not just conversational text. Catch errors at runtime, not in production.
+#### Updating Context
 
 ```javascript
-const AnalysisSchema = z.object({
-  topics: z.array(z.string()),
-  sentiment: z.enum(['positive', 'negative', 'neutral']),
-  entities: z.array(z.object({
-    name: z.string(),
-    type: z.enum(['person', 'organization', 'location'])
-  }))
+wizard.addComputeStep({
+  id: 'increment_counter',
+  update: (result, context, actions) => {
+    actions.updateContext({
+      processedCount: context.processedCount + 1
+    });
+    return actions.next();
+  }
 });
+```
+
+#### Context Functions: Controlling What the LLM Sees
 
+The `context` transforms your full context into a focused view for the LLM. This is where you design the information architecture.
+
+```javascript
 wizard.addTextStep({
-  id: 'analyze_content',
-  instruction: 'Analyze this content: {{content}}',
-  schema: AnalysisSchema,
+  id: 'analyze',
+  instruction: 'Analyze these documents:\n{{formattedDocs}}',
+  context: (context) => ({
+    // Transform complex data into LLM-friendly format
+    formattedDocs: context.documents
+      .map((doc, i) => `${i + 1}. ${doc.title} (${doc.pages} pages)`)
+      .join('\n'),
+    // Only expose what's needed
+    totalDocs: context.documents.length
+  }),
+  schema: z.object({
+    insights: z.array(z.string())
+  }),
   model: Models.SWIZZY_DEFAULT,
-  update: (validatedData, context, actions) => {
-    // validatedData is fully typed - no runtime surprises
-    console.log(validatedData.sentiment); // TypeScript knows this exists
+  update: (result, context, actions) => {
+    actions.updateContext({ insights: result.insights });
     return actions.next();
   }
 });
 ```
 
-#### 👁️ Full Observability
-If you can't see your workflow executing in real-time, you can't debug it. Our visualization layer makes every step, token, and decision transparent.
+**Why This Matters**: 
+- Keep token usage low by showing only relevant data
+- Present information in the optimal format
+- Prevent the LLM from seeing sensitive or confusing data
+- Design the exact "user interface" the LLM experiences
 
-```javascript
-// Start real-time visualization
-const { server, url } = await wizard.visualize(3000);
-console.log(`Open ${url} to watch your workflow execute`);
+---
 
-// Features:
-// - Live step execution tracking
-// - Token usage per step
-// - Context changes in real-time
-// - Interactive pause/resume controls
-```
+### Steps: The Building Blocks
 
----
+A **Step** is the fundamental unit of a Wizard workflow. Each step defines a single action in your process.
 
-## Installation
+#### Step Anatomy
 
-```bash
-npm install @swizzy_ai/kit
-# or
-yarn add @swizzy_ai/kit
-# or
-pnpm add @swizzy_ai/kit
-```
+Every step has five components:
 
----
+1. **ID**: Unique identifier for the step
+2. **Type**: What kind of step (text, structured, or compute)
+3. **Instruction**: What to ask the LLM (for LLM steps)
+4. **Context Function**: What information to expose (optional)
+5. **Update Function**: How to handle the result and what to do next
+
+#### Step Variants
 
-## Core Components
+Choose the right step type for your task:
 
-### Shared Memory (Context)
+**Normal Step (Structured Data)**
 
-Context is the persistent data store that all steps can read from and write to. Think of it as a shared JavaScript object that maintains state throughout the workflow.
+Use when you need the LLM to generate data matching a specific schema:
 
 ```javascript
-// Initialize context
-wizard.setContext({
-  userName: 'Alice',
-  documents: ['doc1.pdf', 'doc2.pdf'],
-  currentStep: 0
+wizard.addStep({
+  id: 'extract_entities',
+  instruction: 'Extract entities from: {{text}}',
+  schema: z.object({
+    people: z.array(z.string()),
+    organizations: z.array(z.string()),
+    locations: z.array(z.string())
+  }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    // result is guaranteed to match schema
+    actions.updateContext({ entities: result });
+    return actions.next();
+  }
 });
+```
 
-// Steps can read context
+**Text Step (Simple Text)**
+
+Use when you just need a text response without structured data:
+
+```javascript
 wizard.addTextStep({
-  id: 'greet_user',
-  instruction: 'Greet {{userName}} and mention they have {{documents.length}} documents',
-  // ...
+  id: 'summarize',
+  instruction: 'Summarize: {{document}}',
+  model: Models.SWIZZY_DEFAULT,
+  update: (text, context, actions) => {
+    actions.updateContext({ summary: text });
+    return actions.next();
+  }
 });
+```
 
-// Steps can write to context
+**Compute Step (Non-LLM Logic)**
+
+Use for calculations, API calls, validation, or any logic that doesn't need an LLM:
+
+```javascript
 wizard.addComputeStep({
-  id: 'process_docs',
+  id: 'validate',
   update: (result, context, actions) => {
-    actions.updateContext({
-      processedCount: context.documents.length,
-      status: 'completed'
+    if (context.entities.people.length === 0) {
+      return actions.retry(); // No entities found, retry
+    }
+    
+    // Call external API
+    const enrichedData = await fetch(`/api/enrich`, {
+      method: 'POST',
+      body: JSON.stringify(context.entities)
     });
+    
+    actions.updateContext({ enrichedData });
     return actions.next();
   }
 });
 ```
 
-#### Template Variables
-Use `{{variable}}` syntax for simple value injection:
+---
+
+### Instructions: Prompt Templates
+
+The **instruction** is the prompt shown to the LLM. It uses a template engine that replaces `{{variables}}` with data from your context function.
+
+#### Basic Template Syntax
 
 ```javascript
 wizard.addTextStep({
-  id: 'personalize',
-  instruction: 'Hello {{userName}}, you are {{userAge}} years old',
-  // ...
+  id: 'greet_user',
+  instruction: 'Greet {{userName}} who has {{documentCount}} documents',
+  context: (context) => ({
+    userName: context.user.name,
+    documentCount: context.user.documents.length
+  }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (text, context, actions) => {
+    console.log(text); // "Hello Alice! I see you have 5 documents."
+    return actions.next();
+  }
 });
 ```
 
-#### Context Functions
-For complex data preparation:
+At runtime, the instruction becomes:
+```
+"Greet Alice who has 5 documents"
+```
+
+#### Multi-line Instructions
 
 ```javascript
-wizard.addTextStep({
-  id: 'summarize',
-  instruction: 'Summarize these documents: {{docList}}',
-  contextType: 'template',
-  contextFunction: (context) => ({
-    docList: context.documents.map((doc, i) =>
-      `${i + 1}. ${doc.title} (${doc.pages} pages)`
-    ).join('\n')
+wizard.addStep({
+  id: 'analyze_sentiment',
+  instruction: `
+You are analyzing customer feedback.
+
+Customer Review:
+{{review}}
+
+Previous Sentiment: {{previousSentiment}}
+
+Analyze the sentiment and confidence level.
+  `.trim(),
+  context: (context) => ({
+    review: context.currentReview.text,
+    previousSentiment: context.lastSentiment || 'unknown'
+  }),
+  schema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    confidence: z.number().min(0).max(1)
   }),
-  // ...
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    actions.updateContext({ 
+      lastSentiment: result.sentiment,
+      sentimentConfidence: result.confidence
+    });
+    return actions.next();
+  }
 });
 ```
 
-### Steps: The Building Blocks
+---
 
-Steps are the individual units of execution in your workflow. There are three types:
+### Update Functions: State Mutation and Control
 
-#### 1. TextStep: LLM-Powered Steps
-Generate structured text with schema validation.
+The **update function** runs after a step completes. It's where you:
+1. Process the LLM's output
+2. Update context/state
+3. Decide what happens next (via signals)
+
+#### Function Signature
 
 ```javascript
-wizard.addTextStep({
-  id: 'extract_keywords',
-  instruction: 'Extract key topics from: {{text}}',
+update: (result, context, actions) => {
+  // result: The output from this step
+  // context: Current workflow state (read-only)
+  // actions: Methods to update state and control flow
+  
+  return actions.next(); // Must return a signal
+}
+```
+
+#### Processing Results
+
+```javascript
+wizard.addStep({
+  id: 'extract_data',
+  instruction: 'Extract key data from {{document}}',
   schema: z.object({
-    keywords: z.array(z.string()),
-    confidence: z.number()
+    title: z.string(),
+    date: z.string(),
+    amount: z.number()
   }),
   model: Models.SWIZZY_DEFAULT,
-  update: (data, context, actions) => {
-    actions.updateContext({ keywords: data.keywords });
+  update: (result, context, actions) => {
+    // Validate the result
+    if (result.amount < 0) {
+      console.error('Invalid amount detected');
+      return actions.retry();
+    }
+    
+    // Transform the result
+    const enrichedData = {
+      ...result,
+      parsedDate: new Date(result.date),
+      formattedAmount: `$${result.amount.toFixed(2)}`
+    };
+    
+    // Update context
+    actions.updateContext({ extractedData: enrichedData });
+    
+    // Continue
     return actions.next();
   }
 });
 ```
 
-#### 2. ComputeStep: Logic Steps
-Pure computation without LLM calls.
+---
+
+## Workflow Control: Signals
+
+### What Are Signals?
+
+**Signals** are how steps communicate "what happens next" in your workflow. Every `update` function must return a signal.
+
+Think of signals as the control flow language of Wizard - they let you build complex branching logic, retry mechanisms, and dynamic routing.
+
+---
+
+### Available Signals
+
+#### `actions.next()`
+
+Move to the next sequential step in your workflow.
 
 ```javascript
 wizard.addComputeStep({
-  id: 'validate_keywords',
+  id: 'step_1',
   update: (result, context, actions) => {
-    const keywords = context.keywords;
-    if (keywords.length < 3) {
-      return actions.goto('extract_keywords'); // Retry extraction
-    }
-    return actions.next();
+    return actions.next(); // Goes to step_2
+  }
+});
+
+wizard.addComputeStep({
+  id: 'step_2',
+  update: (result, context, actions) => {
+    return actions.next(); // Goes to step_3
   }
 });
 ```
 
-#### 3. General Step: Custom Steps
-Maximum flexibility with `addStep()`.
+**Use when**: Following a linear, predictable flow.
+
+---
+
+#### `actions.goto(stepId)`
+
+Jump to a specific step by its ID.
 
 ```javascript
-wizard.addStep({
-  id: 'custom_logic',
-  instruction: 'Custom step logic',
-  customHandler: myCustomFunction,
-  update: (data, context, actions) => {
-    // Your custom logic here
+wizard.addComputeStep({
+  id: 'router',
+  update: (result, context, actions) => {
+    if (context.needsValidation) {
+      return actions.goto('validate_step');
+    }
+    
+    if (context.needsEnrichment) {
+      return actions.goto('enrich_step');
+    }
+    
+    return actions.goto('finalize_step');
+  }
+});
+
+wizard.addComputeStep({
+  id: 'validate_step',
+  update: (result, context, actions) => {
+    // Validation logic
+    return actions.next();
+  }
+});
+
+wizard.addComputeStep({
+  id: 'enrich_step',
+  update: (result, context, actions) => {
+    // Enrichment logic
     return actions.next();
   }
 });
 ```
 
----
+**Use when**: Implementing conditional branching or complex routing logic.
 
-## The Architecture (Core Concepts)
+---
 
-### The Wizard: Your Orchestrator
+#### `actions.retry()`
 
-The `Wizard` class is the heart of the framework. It manages:
-- **Step Registry**: All your workflow steps
-- **Context Store**: Shared memory across steps
-- **Execution Engine**: Runs steps in the correct order
-- **Flow Control**: Handles branching, retries, and termination
+Re-run the current step.
 
 ```javascript
-const wizard = new Wizard({
-  id: 'my-workflow',
-  systemPrompt: 'You are a helpful AI assistant.',
-  onUsage: (usage, provider) => {
-    // Track token usage
-    console.log(`${usage.totalTokens} tokens used`);
+wizard.addStep({
+  id: 'extract_with_retry',
+  instruction: 'Extract entities from: {{text}}',
+  schema: z.object({
+    entities: z.array(z.string()),
+    confidence: z.number()
+  }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    // Retry if confidence is too low
+    if (result.confidence < 0.8) {
+      const retryCount = context.retryCount || 0;
+      
+      if (retryCount < 3) {
+        actions.updateContext({ retryCount: retryCount + 1 });
+        return actions.retry();
+      }
+    }
+    
+    // Success or max retries reached
+    actions.updateContext({ finalEntities: result.entities });
+    return actions.next();
   }
 });
 ```
 
-### The Context: Shared Memory
+**Use when**: The LLM output needs improvement or validation failed.
 
-Context is the "memory" that persists across all steps. Think of it as a shared JavaScript object that steps can read from and write to.
+**Pro tip**: Track retry counts to avoid infinite loops.
 
-#### Template Variables
-Use `{{variableName}}` in instructions for simple value replacement:
+---
 
-```javascript
-wizard.setContext({
-  userName: 'Bob',
-  task: 'write a poem'
-});
+#### `actions.stop()`
 
-wizard.addTextStep({
-  id: 'create_poem',
-  instruction: 'Write a {{task}} about {{userName}}',
-  // ...
+End the workflow immediately.
+
+```javascript
+wizard.addComputeStep({
+  id: 'check_completion',
+  update: (result, context, actions) => {
+    if (context.allDocumentsProcessed) {
+      console.log('Workflow complete!');
+      return actions.stop(); // End here
+    }
+    
+    return actions.next(); // Continue processing
+  }
 });
 ```
 
-#### Context Functions
-For complex data transformations, use `contextFunction`:
+**Use when**: Early termination, error conditions, or goal achievement.
+
+---
+
+#### `actions.wait()`
+
+Pause for 10 seconds before continuing to the next step.
 
 ```javascript
-wizard.addTextStep({
-  id: 'analyze_data',
-  instruction: 'Analyze this dataset: {{formattedData}}',
-  contextType: 'template',
-  contextFunction: (context) => ({
-    formattedData: context.rawData.map(item =>
-      `${item.name}: ${item.value}`
-    ).join(', ')
-  }),
-  // ...
+wizard.addComputeStep({
+  id: 'rate_limit_handler',
+  update: (result, context, actions) => {
+    if (context.apiCallsThisMinute >= 60) {
+      console.log('Rate limit reached, waiting...');
+      actions.updateContext({ apiCallsThisMinute: 0 });
+      return actions.wait(); // Pause 10 seconds
+    }
+    
+    return actions.next();
+  }
 });
 ```
 
-### The Steps: Your Building Blocks
+**Use when**: Rate limiting, waiting for external systems, or pacing execution.
 
-Steps are the individual units of work in your workflow. There are three types:
+---
+
+### Signal Patterns
 
-#### 1. TextStep: LLM Interactions
-Generates structured text using LLMs with schema validation.
+#### Sequential Execution
 
 ```javascript
 wizard.addTextStep({
-  id: 'extract_entities',
-  instruction: 'Extract named entities from: {{text}}',
-  schema: z.object({
-    people: z.array(z.string()),
-    organizations: z.array(z.string()),
-    locations: z.array(z.string())
-  }),
+  id: 'step_1',
+  instruction: 'Do task 1',
   model: Models.SWIZZY_DEFAULT,
-  update: (validatedData, context, actions) => {
-    // validatedData is guaranteed to match the schema
-    actions.updateContext({
-      extractedEntities: validatedData
-    });
+  update: (text, context, actions) => {
+    actions.updateContext({ task1Result: text });
+    return actions.next();
+  }
+});
+
+wizard.addTextStep({
+  id: 'step_2',
+  instruction: 'Do task 2 using {{task1Result}}',
+  model: Models.SWIZZY_DEFAULT,
+  update: (text, context, actions) => {
     return actions.next();
   }
 });
 ```
 
-#### 2. ComputeStep: Pure Logic
-For computations, API calls, or any code that doesn't need LLMs.
+#### Conditional Routing
 
 ```javascript
 wizard.addComputeStep({
-  id: 'validate_data',
-  instruction: 'Validate the extracted entities',
+  id: 'router',
   update: (result, context, actions) => {
-    const entities = context.extractedEntities;
-    const isValid = entities.people.length > 0 ||
-                   entities.organizations.length > 0;
-
-    if (!isValid) {
-      console.log('⚠️ No entities found, retrying...');
-      return actions.retry();
+    if (context.complexity === 'simple') {
+      return actions.goto('simple_path');
+    } else if (context.complexity === 'medium') {
+      return actions.goto('medium_path');
+    } else {
+      return actions.goto('complex_path');
     }
-
-    actions.updateContext({ validationPassed: true });
-    return actions.next();
   }
 });
 ```
 
-#### 3. General Step: Full Control
-The `addStep()` method accepts any configuration for maximum flexibility.
+#### Retry with Backoff
 
 ```javascript
 wizard.addStep({
-  id: 'custom_step',
-  instruction: 'Custom logic here',
-  customProperty: 'value',
-  update: (data, context, actions) => {
-    // Your custom logic
+  id: 'api_call_with_retry',
+  instruction: 'Process: {{data}}',
+  schema: z.object({ success: z.boolean() }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    if (!result.success) {
+      const retries = context.retries || 0;
+      
+      if (retries < 3) {
+        actions.updateContext({ retries: retries + 1 });
+        return actions.wait(); // Wait before retry
+      }
+      
+      return actions.goto('error_handler');
+    }
+    
     return actions.next();
   }
 });
 ```
 
-### Flow Control: The Router
+#### Loop Pattern
 
-Control execution flow with explicit signals:
+```javascript
+wizard.addComputeStep({
+  id: 'process_items',
+  update: (result, context, actions) => {
+    const currentIndex = context.currentIndex || 0;
+    
+    if (currentIndex < context.items.length) {
+      actions.updateContext({ 
+        currentItem: context.items[currentIndex],
+        currentIndex: currentIndex + 1
+      });
+      return actions.goto('process_single_item');
+    }
+    
+    // All items processed
+    return actions.next();
+  }
+});
 
-```mermaid
-stateDiagram-v2
-    [*] --> Step1
-    Step1 --> Step2: next()
-    Step1 --> Step3: goto('step3')
-    Step1 --> [*]: stop()
-    Step2 --> Step2: retry()
-    Step2 --> Waiting: wait()
-    Waiting --> Step2: 10s timeout
-```
-
-- **`actions.next()`**: Continue to the next step in sequence
-- **`actions.goto('stepId')`**: Jump to any step by ID
-- **`actions.stop()`**: End the workflow immediately
-- **`actions.retry()`**: Retry the current step (with exponential backoff)
-- **`actions.wait()`**: Pause for 10 seconds before continuing
+wizard.addTextStep({
+  id: 'process_single_item',
+  instruction: 'Process: {{currentItem}}',
+  model: Models.SWIZZY_DEFAULT,
+  update: (text, context, actions) => {
+    // Store result
+    actions.updateContext({
+      [`result_${context.currentIndex}`]: text
+    });
+    // Loop back
+    return actions.goto('process_items');
+  }
+});
+```
 
 ---
 
-## Feature Spotlight: Bungee Jumps (Parallelism)
+## Advanced Patterns
 
-**Bungee Jumps are our secret weapon** - the pattern that makes @swizzy_ai/kit uniquely powerful for AI workflows.
+### The Bungee Action: Parallelism
 
-### The Concept
+The **Bungee Action** is Wizard's most powerful pattern. It implements fan-out/fan-in: launch a step multiple times in parallel, then automatically return to the anchor point.
 
-Traditional AI workflows are sequential: Step 1 → Step 2 → Step 3. But what if Step 2 needs to process 100 documents? You'd wait 100x longer than necessary.
+#### Anatomy of a Bungee
 
-Bungee Jumps implement the **fan-out/fan-in pattern**:
-1. **Anchor**: The main flow pauses at a step
-2. **Jump**: Launch multiple parallel "worker" instances
-3. **Batch**: Each worker processes a different data point
-4. **Return**: All workers complete, main flow resumes
+- **Anchor Step**: Where the bungee launches from (typically a compute step)
+- **Destination Step**: The step that runs in parallel for each item
+- **Batch**: Each parallel run receives unique context
+- **Fan-in**: All parallel runs complete, execution returns to the anchor
+- **Continuation**: The anchor's next signal determines where to go
 
 ```mermaid
 graph TD
-    A[Main Flow] --> B[Anchor Step]
-    B --> C[🪂 Bungee Jump]
-    C --> D[Worker 1<br/>Process Item A]
-    C --> E[Worker 2<br/>Process Item B]
-    C --> F[Worker N<br/>Process Item Z]
-    D --> G[Collect Results]
-    E --> G
-    F --> G
-    G --> H[Return to Anchor]
-    H --> I[Continue Main Flow]
+    A[Anchor Step] --> B[🪂 Bungee Launch]
+    B --> C[Worker 1: Item A]
+    B --> D[Worker 2: Item B]
+    B --> E[Worker N: Item Z]
+    C --> F[All Complete]
+    D --> F
+    E --> F
+    F --> G[Return to Anchor]
+    G --> H[Continue Flow]
 ```
 
-### Real-World Example: Document Search
+---
 
-Imagine searching a 100-page document for answers. Instead of checking pages one-by-one:
+#### Basic Bungee Example
 
 ```javascript
-// Sequential approach (slow)
-for (let page = 1; page <= 100; page++) {
-  searchPage(page); // 100 sequential calls = ~5 minutes
-}
+wizard.setContext({
+  documents: ['doc1.txt', 'doc2.txt', 'doc3.txt']
+});
+
+// Anchor step
+wizard.addComputeStep({
+  id: 'parallel_processor',
+  update: (result, context, actions) => {
+    return actions.bungee.init()
+      .batch(
+        'process_document',           // Destination step
+        context.documents.length,     // Run 3 times
+        (index) => ({                 // Each run gets unique context
+          documentName: context.documents[index],
+          documentIndex: index
+        })
+      )
+      .config({ 
+        concurrency: 2,  // Process 2 at a time
+        timeout: 30000   // 30 second timeout per worker
+      })
+      .jump(); // Launch!
+  }
+});
+
+// Destination step (runs 3 times in parallel)
+wizard.addTextStep({
+  id: 'process_document',
+  instruction: 'Summarize document: {{documentName}}',
+  schema: z.object({
+    summary: z.string(),
+    wordCount: z.number()
+  }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    // Store result with unique key
+    actions.updateContext({
+      [`summary_${context.documentIndex}`]: result.summary,
+      [`wordCount_${context.documentIndex}`]: result.wordCount
+    });
+    return actions.next(); // Return to anchor
+  }
+});
 
-// Bungee approach (fast)
+// Back at anchor - collect results
+wizard.addComputeStep({
+  id: 'collect_results',
+  update: (result, context, actions) => {
+    const allSummaries = context.documents.map((_, i) => 
+      context[`summary_${i}`]
+    );
+    
+    actions.updateContext({ allSummaries });
+    return actions.next();
+  }
+});
+```
+
+---
+
+#### Real-World Example: Parallel Document Search
+
+Search 100 pages simultaneously instead of sequentially:
+
+```javascript
+wizard.setContext({
+  userQuestion: 'What are the key findings about climate change?',
+  totalPages: 100
+});
+
+// Anchor: Launch parallel search
 wizard.addComputeStep({
   id: 'parallel_search',
   update: (result, context, actions) => {
     return actions.bungee.init()
-      .batch('search_page', 100, (pageIndex) => ({
-        pageNumber: pageIndex + 1,
-        query: context.userQuestion
-      }))
-      .config({ concurrency: 10 }) // 10 pages at once
-      .jump(); // ~30 seconds total
+      .batch(
+        'search_page',
+        context.totalPages,         // 100 parallel searches
+        (pageIndex) => ({
+          pageNumber: pageIndex + 1,
+          query: context.userQuestion
+        })
+      )
+      .config({ 
+        concurrency: 10,  // 10 workers at a time
+        timeout: 30000
+      })
+      .jump();
   }
 });
 
+// Worker: Search a single page
 wizard.addTextStep({
   id: 'search_page',
-  instruction: 'Search page {{pageNumber}} for: {{query}}',
+  instruction: 'Search page {{pageNumber}} for information about: {{query}}',
+  schema: z.object({
+    hasRelevantInfo: z.boolean(),
+    excerpt: z.string().optional(),
+    relevanceScore: z.number().min(0).max(10).optional()
+  }),
+  model: Models.SWIZZY_DEFAULT,
   update: (result, context, actions) => {
-    if (result.includes('relevant content')) {
+    if (result.hasRelevantInfo && result.relevanceScore >= 7) {
       actions.updateContext({
-        [`page_${context.pageNumber}_result`]: result
+        [`page_${context.pageNumber}_excerpt`]: result.excerpt,
+        [`page_${context.pageNumber}_score`]: result.relevanceScore
       });
     }
+    return actions.next(); // Return to anchor
+  }
+});
+
+// Collect and rank results
+wizard.addComputeStep({
+  id: 'collect_and_rank',
+  update: (result, context, actions) => {
+    const results = [];
+    
+    for (let i = 1; i <= context.totalPages; i++) {
+      const excerpt = context[`page_${i}_excerpt`];
+      const score = context[`page_${i}_score`];
+      
+      if (excerpt) {
+        results.push({ page: i, excerpt, score });
+      }
+    }
+    
+    // Sort by relevance
+    results.sort((a, b) => b.score - a.score);
+    
+    actions.updateContext({ 
+      searchResults: results.slice(0, 10) // Top 10
+    });
+    
     return actions.next();
   }
 });
 ```
 
-**Result**: 10x faster execution with the same code complexity.
+**Performance**: Process 100 pages in ~30 seconds (with concurrency: 10) instead of 5+ minutes sequentially.
+
+---
+
+#### When to Use Bungee
 
-### Configuration Options
+**Perfect for:**
+- Batch processing (documents, images, data records)
+- Parallel API calls or searches
+- Multi-source information gathering
+- Any workflow bottleneck that can be parallelized
+
+**Not ideal for:**
+- Tasks that must run sequentially
+- When order matters
+- Shared state that can't be partitioned
+
+---
+
+#### Bungee Configuration Options
 
 ```javascript
 actions.bungee.init()
-  .batch('stepId', itemCount, (index) => ({
-    // Context for each worker instance
-    itemIndex: index,
-    data: items[index]
-  }))
+  .batch('destination_step', count, contextFn)
   .config({
-    concurrency: 5,    // Max parallel workers
-    timeout: 30000     // Per-worker timeout in ms
+    concurrency: 10,    // Max parallel workers (default: 5)
+    timeout: 30000,     // Timeout per worker in ms (default: 60000)
+    retryOnError: true  // Retry failed workers (default: false)
   })
-  .jump()
+  .jump();
 ```
 
 ---
 
-## Developer Experience (DX)
-
-### Real-Time Visualization
+### Multi-API Configuration
 
-Debug workflows visually with the built-in web interface:
+Wizard supports multiple LLM providers. Configure API keys for different models:
 
 ```javascript
-const { server, url } = await wizard.visualize(3000);
-console.log(`🎯 Open ${url} in your browser`);
-```
-
-**Features:**
-- **Live Step Tracking**: See each step execute in real-time
-- **Token Monitoring**: Track LLM usage per step and total
-- **Context Inspector**: View context changes as they happen
-- **Interactive Controls**: Pause, resume, or step through execution
-- **Error Visualization**: See failures and retry attempts
-
-### Error Handling & Resilience
+const wizard = new Wizard({
+  id: 'multi-provider-workflow',
+  apiKeys: {
+    openai: process.env.OPENAI_API_KEY,
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    gemini: process.env.GEMINI_API_KEY
+  }
+});
 
-```javascript
+// Use different models for different tasks
 wizard.addTextStep({
-  id: 'unreliable_step',
-  instruction: 'This might fail sometimes',
-  update: (result, context, actions) => {
-    if (result.includes('ERROR')) {
-      // Automatic retry with backoff
-      return actions.retry();
-    }
-
-    if (someCondition) {
-      // Jump to error handling step
-      return actions.goto('error_handler');
-    }
+  id: 'fast_extraction',
+  instruction: 'Quick extract: {{data}}',
+  model: Models.GPT_4O_MINI,  // Fast, cheap
+  update: (text, context, actions) => {
+    actions.updateContext({ extracted: text });
+    return actions.next();
+  }
+});
 
+wizard.addTextStep({
+  id: 'deep_analysis',
+  instruction: 'Deeply analyze: {{extracted}}',
+  model: Models.CLAUDE_SONNET,  // Powerful reasoning
+  update: (text, context, actions) => {
+    actions.updateContext({ analysis: text });
     return actions.next();
   }
 });
 ```
 
-**Built-in Resilience:**
-- Automatic retry with exponential backoff
-- Configurable timeout handling
-- Context preservation across retries
-- Error context tracking (`${stepId}_error`)
+---
 
-### TypeScript + Zod Integration
+## Complete Example
 
-Full type safety from LLM outputs to your application code:
+Here's a full workflow that demonstrates all concepts:
 
-```typescript
-import { z } from 'zod';
+```javascript
+const { Wizard, Models } = require('@swizzy_ai/kit');
+const { z } = require('zod');
 
-const AnalysisSchema = z.object({
-  sentiment: z.enum(['positive', 'negative', 'neutral']),
-  confidence: z.number().min(0).max(1),
-  keywords: z.array(z.string())
+const wizard = new Wizard({
+  id: 'document-analyzer',
+  onUsage: (usage, provider) => {
+    console.log(`📊 ${provider}: ${usage.totalTokens} tokens`);
+  }
 });
 
-wizard.addTextStep({
-  id: 'analyze_text',
-  instruction: 'Analyze: {{text}}',
-  schema: AnalysisSchema,
+// Initialize context
+wizard.setContext({
+  documentText: 'Your document content here...',
+  userQuery: 'Extract key insights',
+  maxRetries: 3
+});
+
+// Step 1: Extract entities with retry logic
+wizard.addStep({
+  id: 'extract_entities',
+  instruction: 'Extract named entities from: {{documentText}}',
+  schema: z.object({
+    people: z.array(z.string()),
+    organizations: z.array(z.string()),
+    confidence: z.number().min(0).max(1)
+  }),
   model: Models.SWIZZY_DEFAULT,
-  update: (data, context, actions) => {
-    // data is fully typed: AnalysisSchema.Type
-    console.log(data.sentiment); // TypeScript knows this is a valid enum
-    console.log(data.confidence); // TypeScript knows this is a number 0-1
+  update: (result, context, actions) => {
+    const retries = context.extractRetries || 0;
+    
+    // Low confidence? Retry
+    if (result.confidence < 0.8 && retries < context.maxRetries) {
+      actions.updateContext({ extractRetries: retries + 1 });
+      return actions.retry();
+    }
+    
+    // Store entities
+    actions.updateContext({ 
+      entities: result,
+      extractRetries: 0
+    });
+    return actions.next();
+  }
+});
+
+// Step 2: Validate entities
+wizard.addComputeStep({
+  id: 'validate_entities',
+  update: (result, context, actions) => {
+    const hasEntities = 
+      context.entities.people.length > 0 ||
+      context.entities.organizations.length > 0;
+    
+    if (!hasEntities) {
+      console.log('No entities found, retrying extraction');
+      return actions.goto('extract_entities');
+    }
+    
+    console.log(`Found ${context.entities.people.length} people, ${context.entities.organizations.length} orgs`);
     return actions.next();
   }
 });
+
+// Step 3: Generate summary
+wizard.addTextStep({
+  id: 'generate_summary',
+  instruction: `
+Summarize key insights about these entities:
+
+{{entityList}}
+
+Focus on their relationships and significance.
+  `.trim(),
+  context: (context) => ({
+    entityList: [
+      ...context.entities.people.map(p => `Person: ${p}`),
+      ...context.entities.organizations.map(o => `Organization: ${o}`)
+    ].join('\n')
+  }),
+  schema: z.object({
+    summary: z.string(),
+    keyInsights: z.array(z.string()),
+    confidence: z.number()
+  }),
+  model: Models.SWIZZY_DEFAULT,
+  update: (result, context, actions) => {
+    console.log('Summary:', result.summary);
+    console.log('Key Insights:');
+    result.keyInsights.forEach((insight, i) => {
+      console.log(`  ${i + 1}. ${insight}`);
+    });
+    
+    return actions.stop(); // Workflow complete!
+  }
+});
+
+// Run the workflow
+wizard.run();
 ```
 
 ---
@@ -588,130 +992,129 @@ wizard.addTextStep({
 ### Wizard Constructor
 
 ```typescript
-new Wizard(config: WizardConfig)
+new Wizard(config: {
+  id: string;
+  systemPrompt?: string;
+  onUsage?: (usage: TokenUsage, provider: string) => void;
+  apiKeys?: {
+    openai?: string;
+    anthropic?: string;
+    gemini?: string;
+  }
+})
 ```
 
-```typescript
-interface WizardConfig {
-  id: string;                                    // Unique workflow identifier
-  systemPrompt?: string;                        // Global system prompt for LLMs
-  onUsage?: (usage: TokenUsage, provider: string) => void; // Token tracking callback
-}
-```
+### Context Methods
 
-### Core Methods
+| Method | Description |
+|--------|-------------|
+| `setContext(data)` | Initialize workflow context |
+| `getContext()` | Retrieve current context |
+| `updateContext(data)` | Update context (returns Wizard instance for chaining) |
 
-| Method | Description | Example |
-|--------|-------------|---------|
-| `addStep(config)` | Add any type of step | `wizard.addStep({ id: 'step1', ... })` |
-| `addTextStep(config)` | Add LLM text generation step | `wizard.addTextStep({ id: 'generate', ... })` |
-| `addComputeStep(config)` | Add computational step | `wizard.addComputeStep({ id: 'process', ... })` |
-| `setContext(data)` | Initialize shared context | `wizard.setContext({ user: 'Alice' })` |
-| `getContext()` | Get current context | `const ctx = wizard.getContext()` |
-| `updateContext(data)` | Update context (fluent) | `wizard.updateContext({ result: data })` |
-| `run()` | Execute the workflow | `await wizard.run()` |
-| `visualize(port)` | Start web UI | `await wizard.visualize(3000)` |
+### Step Methods
 
-### Step Configuration
+| Method | Description |
+|--------|-------------|
+| `addStep(config)` | Add structured LLM step with schema validation |
+| `addTextStep(config)` | Add simple text generation step |
+| `addComputeStep(config)` | Add non-LLM logic step |
 
-#### TextStep Configuration
-```typescript
-interface TextStepConfig {
-  id: string;                           // Unique step identifier
-  instruction: string;                  // LLM prompt/instruction
-  schema?: z.ZodType;                   // Output validation schema
-  model: string;                        // LLM model identifier
-  contextType?: 'template' | 'xml' | 'both'; // How to inject context
-  contextFunction?: (context: any) => any;     // Dynamic context builder
-  update: StepUpdateFunction;           // Result handler
-}
-```
+### Execution Methods
 
-#### ComputeStep Configuration
-```typescript
-interface ComputeStepConfig {
-  id: string;                    // Unique step identifier
-  instruction: string;           // Documentation/description
-  update: StepUpdateFunction;    // Logic handler
-}
-```
+| Method | Description |
+|--------|-------------|
+| `run()` | Execute the workflow from the first step |
+| `stop()` | Manually stop a running workflow |
 
 ### Actions Interface
 
+Available in every `update` function:
+
 ```typescript
-interface WizardActions {
-  updateContext: (updates: Record<string, any>) => void;
-  llmClient: LLMClient;          // Direct LLM access if needed
-  goto: (stepId: string) => FlowControlSignal;
+{
+  updateContext: (updates: object) => void;
   next: () => FlowControlSignal;
-  stop: () => FlowControlSignal;
+  goto: (stepId: string) => FlowControlSignal;
   retry: () => FlowControlSignal;
+  stop: () => FlowControlSignal;
   wait: () => FlowControlSignal;
   bungee: {
-    init: () => BungeeBuilder;   // Start parallel execution
-  };
+    init: () => BungeeBuilder;
+  }
 }
 ```
 
-### TokenUsage Interface
+### Bungee Builder Interface
 
 ```typescript
-interface TokenUsage {
-  promptTokens: number;
-  completionTokens: number;
-  totalTokens: number;
+BungeeBuilder {
+  batch: (
+    destinationStepId: string,
+    count: number,
+    context: (index: number) => object
+  ) => BungeeBuilder;
+  
+  config: (options: {
+    concurrency?: number;
+    timeout?: number;
+    retryOnError?: boolean;
+  }) => BungeeBuilder;
+  
+  jump: () => FlowControlSignal;
 }
 ```
 
 ---
 
-## Contributing
+## Comparison with Alternatives
 
-We welcome contributions! Here's how to get started:
+| Feature | Wizard | LangChain | Vercel AI SDK | Raw LLM APIs |
+|---------|---------|-----------|---------------|--------------|
+| **Mental Model** | Developer orchestrates, LLM executes | LLM is the agent | Linear chat flows | Full manual control |
+| **Context Control** | ✅ Context functions + templates | ⚠️ Chain-based passing | ❌ Manual | ❌ Manual |
+| **State Machine** | ✅ Explicit signals (next/goto/retry/stop) | ❌ Sequential chains | ❌ Linear only | ❌ Build yourself |
+| **Type Safety** | ✅ Zod validation on outputs | ⚠️ Optional | ⚠️ TypeScript only | ❌ None |
+| **Parallelism** | ✅ Bungee actions | ❌ Manual orchestration | ❌ Manual | ❌ Manual |
+| **Flow Control** | ✅ Signals with branching | ⚠️ Limited | ⚠️ Limited | ❌ Manual |
+| **Learning Curve** | Medium | Steep | Low | High |
+| **Best For** | Complex multi-step workflows | General orchestration | Simple chat | Full control |
 
-1. **Fork** the repository
-2. **Clone** your fork: `git clone https://github.com/swizzy-ai/swizzy-kit.git`
-3. **Install** dependencies: `npm install`
-4. **Create** a feature branch: `git checkout -b feature/amazing-feature`
-5. **Make** your changes with tests
-6. **Run** tests: `npm test`
-7. **Submit** a pull request
+---
 
-### Development Setup
+## Examples
 
-```bash
-# Install dependencies
-npm install
+Check the `/examples` directory for complete workflows:
 
-# Run tests
-npm test
+- **Document Analyzer**: Extract entities and generate insights with retry logic
+- **Parallel Search**: Search 100+ pages simultaneously using Bungee actions
+- **Multi-Step Validation**: Complex validation with conditional routing
+- **Data Pipeline**: Transform and validate data across multiple steps
+- **Multi-Provider Workflow**: Use different LLM providers for different tasks
 
-# Build TypeScript
-npm run build
+---
 
-# Run examples
-cd examples && node document-reader.js
-```
+## Contributing
 
-### Guidelines
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+```bash
+# Setup
+git clone https://github.com/swizzy-ai/wizard-framework.git
+npm install
 
-- **Type Safety**: All code must be TypeScript with proper types
-- **Testing**: Add tests for new features
-- **Documentation**: Update README and inline docs
-- **Consistency**: Match existing code style and patterns
+# Development
+npm test        # Run tests
+npm run build   # Build TypeScript
+npm run lint    # Lint code
+```
 
 ---
 
 ## License
 
-**MIT License** - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](./LICENSE) for details.
 
 ---
 
-<div align="center">
-
-**Built with ❤️ for the AI orchestration revolution**
-
-[GitHub](https://github.com/swizzy-ai/swizzy-kit) • [Documentation](https://swizzy-kit.dev) • [Discord](https://discord.gg/swizzy-kit)
-
-</div>
+<div align="center">