ensure build works

apps/next/src/content/docs/llamaindex/tutorials/workflow/advanced-events.mdx

@@ -0,0 +1,530 @@
+---
+title: Advanced Event Handling
+description: Master complex event patterns and middleware with Workflows
+---
+
+This guide explores advanced event handling techniques and patterns you can use with Workflows to build more sophisticated patterns.
+
+## Event Composition
+
+Workflows allow you to work with different event types and compose them in powerful ways:
+
+### Multiple Event Types
+
+You can define multiple event types for different kinds of data flowing through your workflow:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+// Define different event types
+const textEvent = workflowEvent<string>();
+const numberEvent = workflowEvent<number>();
+const booleanEvent = workflowEvent<boolean>();
+const complexEvent = workflowEvent<{ id: string; value: number }>();
+
+// Create a workflow that can process different event types
+const workflow = createWorkflow();
+
+// Handle text events
+workflow.handle([textEvent], (event) => {
+  console.log(`Processing text: ${event.data}`);
+  return numberEvent.with(event.data.length);
+});
+
+// Handle number events
+workflow.handle([numberEvent], (event) => {
+  const isEven = event.data % 2 === 0;
+  console.log(`Number ${event.data} is ${isEven ? 'even' : 'odd'}`);
+  return booleanEvent.with(isEven);
+});
+
+// Handle boolean events
+workflow.handle([booleanEvent], (event) => {
+  return complexEvent.with({
+    id: crypto.randomUUID(),
+    value: event.data ? 100 : 0
+  });
+});
+```
+
+### Event Branching and Merging
+
+You can create complex event flows with branching and merging patterns:
+
+```ts
+import { createWorkflow, workflowEvent, until, collect } from "llamaindex";
+
+// Define events for a data processing pipeline
+const inputEvent = workflowEvent<string>();
+const validateEvent = workflowEvent<string>();
+const processEvent = workflowEvent<string>();
+const errorEvent = workflowEvent<Error>();
+const resultEvent = workflowEvent<string>();
+const completeEvent = workflowEvent<string[]>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Branch based on input validation
+workflow.handle([inputEvent], (event) => {
+  if (event.data && event.data.trim().length > 0) {
+    return validateEvent.with(event.data.trim());
+  } else {
+    return errorEvent.with(new Error("Empty input"));
+  }
+});
+
+// Process valid inputs
+workflow.handle([validateEvent], (event) => {
+  return processEvent.with(event.data.toUpperCase());
+});
+
+// Handle processing
+workflow.handle([processEvent], (event) => {
+  return resultEvent.with(`Processed: ${event.data}`);
+});
+
+// Handle errors
+workflow.handle([errorEvent], (event) => {
+  return resultEvent.with(`Error: ${event.data.message}`);
+});
+
+// Merge results: collect multiple results into a single completion event
+workflow.handle([inputEvent], (start) => {
+  const { sendEvent, stream } = getContext();
+  
+  // Process all inputs
+  const inputs = start.data.split(',').map(s => s.trim());
+  inputs.forEach(input => sendEvent(inputEvent.with(input)));
+  
+  // Collect all results
+  const results = await collect(
+    until(stream, result => resultEvent.include(result))
+      .filter(ev => resultEvent.include(ev))
+      .take(inputs.length)
+  );
+  
+  return completeEvent.with(results.map(r => r.data));
+});
+```
+
+## Event Filtering and Transformation
+
+You can filter and transform events to build sophisticated data processing pipelines:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+// Define events
+const dataEvent = workflowEvent<number>();
+const evenEvent = workflowEvent<number>();
+const oddEvent = workflowEvent<number>();
+const transformedEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string[]>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Filter even numbers
+workflow.handle([dataEvent], (event) => {
+  if (event.data % 2 === 0) {
+    return evenEvent.with(event.data);
+  } else {
+    return oddEvent.with(event.data);
+  }
+});
+
+// Transform even numbers
+workflow.handle([evenEvent], (event) => {
+  return transformedEvent.with(`Even: ${event.data}`);
+});
+
+// Transform odd numbers
+workflow.handle([oddEvent], (event) => {
+  return transformedEvent.with(`Odd: ${event.data}`);
+});
+
+// Collect and organize results
+workflow.handle([dataEvent], (start) => {
+  const { sendEvent, stream } = getContext();
+  
+  // Generate a sequence of numbers
+  for (let i = 1; i <= 10; i++) {
+    sendEvent(dataEvent.with(i));
+  }
+  
+  // Collect transformed events
+  const results = await collect(
+    until(stream)
+      .filter(ev => transformedEvent.include(ev))
+      .take(10)
+  );
+  
+  return resultEvent.with(results.map(r => r.data));
+});
+```
+
+## Working with `withTraceEvents` Middleware
+
+The `withTraceEvents` middleware adds powerful tracing capabilities to your workflows:
+
+```ts
+import { 
+  createWorkflow, 
+  workflowEvent,
+  withTraceEvents,
+  runOnce,
+  createHandlerDecorator
+} from "llamaindex";
+
+// Define events
+const startEvent = workflowEvent<string>();
+const processEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string>();
+
+// Create workflow with tracing
+const workflow = withTraceEvents(createWorkflow());
+
+// Create a custom handler decorator that logs execution time
+const measureTime = createHandlerDecorator({
+  debugLabel: "measureTime",
+  getInitialValue: () => performance.now(),
+  onBeforeHandler: (handler, context, startTime) => {
+    console.log(`Starting handler execution at ${new Date().toISOString()}`);
+    return handler;
+  },
+  onAfterHandler: (result, context, startTime) => {
+    const duration = performance.now() - startTime;
+    console.log(`Handler executed in ${duration.toFixed(2)}ms`);
+    return startTime; // Return the initial value for next execution
+  }
+});
+
+// Run a specific handler only once
+workflow.handle(
+  [startEvent],
+  runOnce((event) => {
+    console.log("This handler will only run once per workflow context");
+    return processEvent.with(event.data);
+  })
+);
+
+// Measure the execution time of this handler
+workflow.handle(
+  [processEvent],
+  measureTime((event) => {
+    // Simulate processing time
+    const start = Date.now();
+    while (Date.now() - start < 100) {
+      // Busy wait for 100ms
+    }
+    return resultEvent.with(`Processed: ${event.data}`);
+  })
+);
+```
+
+### Debugging with Substreams
+
+You can use the `substream` feature to debug specific event flows:
+
+```ts
+import { createWorkflow, workflowEvent, withTraceEvents } from "llamaindex";
+
+// Define events
+const queryEvent = workflowEvent<string>();
+const fetchEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string>();
+
+// Create workflow with tracing
+const workflow = withTraceEvents(createWorkflow());
+
+// Query handler
+workflow.handle([queryEvent], (event) => {
+  const { sendEvent, stream } = getContext();
+  
+  // Create a specific fetch event for this query
+  const fetchInstance = fetchEvent.with(event.data);
+  sendEvent(fetchInstance);
+  
+  // Create a substream to only track events related to this fetch
+  const substream = workflow.substream(fetchInstance, stream);
+  
+  // Listen for results in the substream
+  (async () => {
+    for await (const event of substream) {
+      console.log(`Event in substream: ${event.type}`);
+    }
+  })();
+  
+  return resultEvent.with(`Querying: ${event.data}`);
+});
+
+// Fetch handler
+workflow.handle([fetchEvent], (event) => {
+  console.log(`Fetching data for: ${event.data}`);
+  // Actual fetch logic would go here
+  return resultEvent.with(`Results for: ${event.data}`);
+});
+```
+
+## Advanced Validation and Type Safety
+
+The `withValidation` middleware ensures your workflow connections are both type-safe and runtime-safe:
+
+```ts
+import { createWorkflow, workflowEvent, withValidation } from "llamaindex";
+
+// Define events with explicit types
+const inputEvent = workflowEvent<string, "input">();
+const validateEvent = workflowEvent<string, "validate">();
+const processEvent = workflowEvent<string, "process">();
+const resultEvent = workflowEvent<string, "result">();
+const errorEvent = workflowEvent<Error, "error">({
+  debugLabel: "errorEvent" // Add debug labels for better error messages
+});
+
+// Define the allowed event flow paths
+const workflow = withValidation(
+  createWorkflow(),
+  [
+    [[inputEvent], [validateEvent, errorEvent]],    // inputEvent can lead to validateEvent or errorEvent
+    [[validateEvent], [processEvent, errorEvent]],  // validateEvent can lead to processEvent or errorEvent
+    [[processEvent], [resultEvent, errorEvent]],    // processEvent can lead to resultEvent or errorEvent
+    [[errorEvent], [resultEvent]]                   // errorEvent can lead to resultEvent
+  ]
+);
+
+// Now use strictHandle to get compile-time validation
+workflow.strictHandle([inputEvent], (sendEvent, event) => {
+  try {
+    if (!event.data || event.data.trim().length === 0) {
+      throw new Error("Empty input");
+    }
+    // This is allowed by our validation rules
+    sendEvent(validateEvent.with(event.data.trim()));
+    
+    // This would cause a compile-time error:
+    // sendEvent(resultEvent.with("Result")); // ❌ Not allowed by validation rules
+  } catch (err) {
+    // This is allowed by our validation rules
+    sendEvent(errorEvent.with(err instanceof Error ? err : new Error(String(err))));
+  }
+});
+
+// The rest of the workflow with strict validation
+workflow.strictHandle([validateEvent], (sendEvent, event) => {
+  // Validation logic here
+  sendEvent(processEvent.with(event.data));
+});
+
+workflow.strictHandle([processEvent], (sendEvent, event) => {
+  // Processing logic here
+  sendEvent(resultEvent.with(`Processed: ${event.data}`));
+});
+
+workflow.strictHandle([errorEvent], (sendEvent, event) => {
+  // Error handling logic here
+  sendEvent(resultEvent.with(`Error handled: ${event.data.message}`));
+});
+```
+
+## Creating Custom Middleware
+
+You can create your own middleware to extend the workflow capabilities:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+// Create a logging middleware
+function withLogging(workflow) {
+  const originalHandle = workflow.handle;
+  
+  workflow.handle = function(eventTypes, handler) {
+    return originalHandle.call(workflow, eventTypes, async function(...args) {
+      const eventType = eventTypes.map(e => e.name || 'AnonymousEvent').join(',');
+      console.log(`[${new Date().toISOString()}] Handling ${eventType}`);
+      
+      try {
+        const result = await handler(...args);
+        console.log(`[${new Date().toISOString()}] Completed ${eventType}`);
+        return result;
+      } catch (error) {
+        console.error(`[${new Date().toISOString()}] Error in ${eventType}:`, error);
+        throw error;
+      }
+    });
+  };
+  
+  return workflow;
+}
+
+// Create a retry middleware
+function withRetry(maxRetries = 3, workflow) {
+  const originalHandle = workflow.handle;
+  
+  workflow.handle = function(eventTypes, handler) {
+    return originalHandle.call(workflow, eventTypes, async function(...args) {
+      let lastError;
+      
+      for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+          return await handler(...args);
+        } catch (error) {
+          lastError = error;
+          console.warn(`Attempt ${attempt}/${maxRetries} failed:`, error);
+          
+          if (attempt < maxRetries) {
+            // Exponential backoff
+            await new Promise(resolve => 
+              setTimeout(resolve, Math.pow(2, attempt - 1) * 100)
+            );
+          }
+        }
+      }
+      
+      throw lastError;
+    });
+  };
+  
+  return workflow;
+}
+
+// Use the custom middleware
+const workflow = withRetry(3, withLogging(createWorkflow()));
+
+// Define events
+const startEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string>();
+
+// Add handlers
+workflow.handle([startEvent], (event) => {
+  // This handler might fail but will be retried
+  if (Math.random() < 0.7) {
+    throw new Error("Random failure");
+  }
+  return resultEvent.with(`Processed: ${event.data}`);
+});
+```
+
+## Integrating with External Systems
+
+You can extend your workflows to integrate with external systems:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+// Define events
+const fetchEvent = workflowEvent<string>();
+const successEvent = workflowEvent<any>();
+const failureEvent = workflowEvent<Error>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Handle external API calls with proper error handling
+workflow.handle([fetchEvent], async (event) => {
+  const { signal } = getContext();
+  
+  try {
+    // Use AbortSignal for cancellation support
+    const response = await fetch(event.data, { signal });
+    
+    if (!response.ok) {
+      throw new Error(`HTTP error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    return successEvent.with(data);
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      return failureEvent.with(new Error('Request was aborted'));
+    }
+    return failureEvent.with(error instanceof Error ? error : new Error(String(error)));
+  }
+});
+
+// Database integration example
+const dbQueryEvent = workflowEvent<{ collection: string; query: any }>();
+const dbResultEvent = workflowEvent<any[]>();
+
+workflow.handle([dbQueryEvent], async (event) => {
+  // Connect to database (pseudo-code)
+  const db = await connectToDatabase();
+  
+  try {
+    const results = await db.collection(event.data.collection)
+      .find(event.data.query)
+      .toArray();
+      
+    return dbResultEvent.with(results);
+  } catch (error) {
+    return failureEvent.with(error);
+  } finally {
+    await db.close();
+  }
+});
+```
+
+## Handling Complex Asynchronous Patterns
+
+LlamaIndex workflows excel at managing complex asynchronous patterns:
+
+```ts
+import { createWorkflow, workflowEvent, until, collect } from "llamaindex";
+
+// Events for an orchestration workflow
+const orchestrateEvent = workflowEvent<string[]>();
+const taskEvent = workflowEvent<string>();
+const progressEvent = workflowEvent<{ task: string; progress: number }>();
+const taskCompleteEvent = workflowEvent<string>();
+const aggregateEvent = workflowEvent<any>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Orchestrator: distribute tasks and collect results
+workflow.handle([orchestrateEvent], async (event) => {
+  const { sendEvent, stream } = getContext();
+  const tasks = event.data;
+  
+  // Start all tasks
+  tasks.forEach(task => sendEvent(taskEvent.with(task)));
+  
+  // Track progress
+  let completed = 0;
+  const results = {};
+  
+  // Process task completion and progress events
+  for await (const event of until(stream, () => completed === tasks.length)) {
+    if (progressEvent.include(event)) {
+      console.log(`Task ${event.data.task}: ${event.data.progress}%`);
+    } else if (taskCompleteEvent.include(event)) {
+      completed++;
+      results[event.data] = `Completed ${event.data}`;
+      console.log(`Completed ${completed}/${tasks.length} tasks`);
+    }
+  }
+  
+  return aggregateEvent.with(results);
+});
+
+// Task processor
+workflow.handle([taskEvent], async (event) => {
+  const { sendEvent } = getContext();
+  const task = event.data;
+  
+  // Simulate task processing with progress updates
+  for (let progress = 0; progress <= 100; progress += 20) {
+    sendEvent(progressEvent.with({ task, progress }));
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  
+  return taskCompleteEvent.with(task);
+});
+```
+
+## Next Steps
+
+Now that you've explored advanced event handling with workflows, you're ready to build sophisticated applications:
+
+- [Integrating Workflows with other LlamaIndex Features](./llamaindex-integration.mdx) 

apps/next/src/content/docs/llamaindex/tutorials/workflow/basic-workflow.mdx

@@ -0,0 +1,263 @@
+---
+title: Basic Workflow Patterns
+description: Learn common patterns and techniques for building effective workflows
+---
+
+This guide explores common patterns you can use to build more complex workflows with workflows.
+
+## Fan-out (Parallelism)
+
+One of the most powerful features of workflows is the ability to run tasks in parallel:
+
+```ts
+import { createWorkflow, workflowEvent, until, collect } from "llamaindex";
+
+// Define events
+const startEvent = workflowEvent<string>();
+const processItemEvent = workflowEvent<number>();
+const resultEvent = workflowEvent<string>();
+const completeEvent = workflowEvent<string[]>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Process start event: fan out to multiple processItemEvent events
+workflow.handle([startEvent], (start) => {
+  const { sendEvent, stream } = getContext();
+  
+  // Emit multiple events to be processed in parallel
+  for (let i = 0; i < 10; i++) {
+    sendEvent(processItemEvent.with(i));
+  }
+  
+  // Collect all resultEvents and emit a final completeEvent
+  let condition = false;
+  const results = collect(
+    until(stream, () => condition)
+      .filter((ev) => resultEvent.includes(ev))
+  );
+  
+  return completeEvent.with(results.map(event => event.data));
+});
+
+// Process each item
+workflow.handle([processItemEvent], (event) => {
+  // Process the item
+  const processedValue = `Processed: ${event.data}`;
+  
+  // If this is the last item, set the condition to stop collecting
+  if (event.data === 9) {
+    condition = true;
+  }
+  
+  return resultEvent.with(processedValue);
+});
+```
+
+This pattern allows you to:
+1. Emit multiple events to be processed in parallel
+2. Collect results as they come in
+3. Complete once all parallel tasks are finished
+
+## Conditional Branching
+
+You can implement conditional logic in your workflows:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+const inputEvent = workflowEvent<number>();
+const evenNumberEvent = workflowEvent<string>();
+const oddNumberEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string>();
+
+const workflow = createWorkflow();
+
+// Branch based on whether the number is even or odd
+workflow.handle([inputEvent], (event) => {
+  if (event.data % 2 === 0) {
+    return evenNumberEvent.with(`${event.data} is even`);
+  } else {
+    return oddNumberEvent.with(`${event.data} is odd`);
+  }
+});
+
+// Handle even numbers
+workflow.handle([evenNumberEvent], (event) => {
+  return resultEvent.with(`Even result: ${event.data}`);
+});
+
+// Handle odd numbers
+workflow.handle([oddNumberEvent], (event) => {
+  return resultEvent.with(`Odd result: ${event.data}`);
+});
+```
+
+## Using Middleware
+
+LlamaIndex workflows provide middleware that can enhance your workflows:
+
+### `withStore` Middleware
+
+The `withStore` middleware adds a persistent store to your workflow context:
+
+```ts
+import { createWorkflow, workflowEvent, withStore } from "llamaindex";
+
+const startEvent = workflowEvent<void>();
+const incrementEvent = workflowEvent<number>();
+const resultEvent = workflowEvent<number>();
+
+// Create a workflow with store middleware
+const workflow = withStore(
+  () => ({
+    count: 0,
+    history: [] as number[],
+  }), 
+  createWorkflow()
+);
+
+// Increment the counter
+workflow.handle([startEvent], () => {
+  const store = workflow.getStore();
+  store.count += 1;
+  store.history.push(store.count);
+  return incrementEvent.with(store.count);
+});
+
+// Return the current count
+workflow.handle([incrementEvent], (event) => {
+  const store = workflow.getStore();
+  return resultEvent.with(store.count);
+});
+```
+
+### `withValidation` Middleware
+
+The `withValidation` middleware adds compile-time and runtime validation to your workflows:
+
+```ts
+import { createWorkflow, workflowEvent, withValidation } from "llamaindex";
+
+const startEvent = workflowEvent<string, "start">();
+const processEvent = workflowEvent<number, "process">();
+const resultEvent = workflowEvent<string, "result">();
+const disallowedEvent = workflowEvent<void, "disallowed">();
+
+// Create a workflow with validation middleware
+// Define allowed event paths
+const workflow = withValidation(
+  createWorkflow(), 
+  [
+    [[startEvent], [processEvent]], // startEvent can only lead to processEvent
+    [[processEvent], [resultEvent]], // processEvent can only lead to resultEvent
+  ]
+);
+
+// This will pass validation
+workflow.strictHandle([startEvent], (sendEvent, start) => {
+  sendEvent(processEvent.with(123)); // ✅ This is allowed
+});
+
+// This would fail at compile time and runtime
+workflow.strictHandle([startEvent], (sendEvent, start) => {
+  // sendEvent(disallowedEvent.with()); // ❌ This would cause an error
+  // sendEvent(resultEvent.with("result")); // ❌ This would also cause an error
+});
+```
+
+## Error Handling
+
+LlamaIndex workflows provide built-in mechanisms for handling errors:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+const startEvent = workflowEvent<string>();
+const processEvent = workflowEvent<number>();
+const errorEvent = workflowEvent<Error>();
+const resultEvent = workflowEvent<string>();
+
+const workflow = createWorkflow();
+
+workflow.handle([startEvent], (start) => {
+  try {
+    const num = Number.parseInt(start.data, 10);
+    if (isNaN(num)) {
+      throw new Error("Invalid number");
+    }
+    return processEvent.with(num);
+  } catch (err) {
+    return errorEvent.with(err instanceof Error ? err : new Error(String(err)));
+  }
+});
+
+workflow.handle([processEvent], (event) => {
+  return resultEvent.with(`Result: ${event.data * 2}`);
+});
+
+workflow.handle([errorEvent], (event) => {
+  return resultEvent.with(`Error: ${event.data.message}`);
+});
+```
+
+You can also use the signal in `getContext()` to handle errors:
+
+```ts
+workflow.handle([processEvent], () => {
+  const { signal } = getContext();
+
+  signal.onabort = () => {
+    console.error("Process aborted:", signal.reason);
+    // Clean up resources
+  };
+  
+  // Your processing logic here
+});
+```
+
+## Connecting with Server Endpoints
+
+Workflow can be used as middleware in server frameworks like Express, Hono, or Fastify:
+
+```ts
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { createWorkflow, workflowEvent, createHonoHandler } from "llamaindex";
+
+// Define events
+const queryEvent = workflowEvent<string>();
+const responseEvent = workflowEvent<string>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+workflow.handle([queryEvent], (event) => {
+  const response = `Processed: ${event.data}`;
+  return responseEvent.with(response);
+});
+
+// Create Hono app
+const app = new Hono();
+
+// Set up workflow endpoint
+app.post(
+  "/workflow",
+  createHonoHandler(
+    workflow,
+    async (ctx) => queryEvent.with(await ctx.req.text()),
+    responseEvent
+  )
+);
+
+// Start server
+serve(app, ({ port }) => {
+  console.log(`Server started at http://localhost:${port}`);
+});
+```
+
+## Next Steps
+
+Now that you've learned about basic workflow patterns, explore more advanced topics:
+- [Streaming with Workflows](./streaming.mdx)
+- [Advanced Event Handling](./advanced-events.mdx) 

apps/next/src/content/docs/llamaindex/tutorials/workflow/different-inputs-outputs.mdx

@@ -1,8 +1,18 @@
 ---
-title: Inputs / Outputs
-description: Learn how to use different inputs and outputs in your workflows.
+title: Inputs / Outputs (Outdated)
+description: This page has been replaced with newer documentation
 ---
 
+# ⚠️ Outdated Documentation
+
+This documentation is for an older version of the workflow API. Please refer to the new llama-flow documentation:
+
+- [Getting Started with llama-flow](./index.mdx)
+- [Basic Workflow Patterns](./basic-workflow.mdx)
+- [Advanced Event Handling](./advanced-events.mdx)
+
+The new API provides a more lightweight and flexible approach to building workflows.
+
 Inputs and outputs are the way to communicate between steps in a workflow. In the previous example,
 we used `StartEvent` and `StopEvent` to communicate between steps. However, you can use any type of event to communicate between steps.
 

apps/next/src/content/docs/llamaindex/tutorials/workflow/index.mdx

@@ -1,196 +1,111 @@
 ---
-title: Basic Usage
-description: Learn how to use the LlamaIndex workflow.
+title: Getting Started with Workflows
+description: Learn how to use LlamaIndex's lightweight workflow engine for TypeScript
 ---
 
-A `Workflow` in LlamaIndex.TS is an event-driven abstraction used to chain together several events.
-Workflows are made up of steps, with each step responsible for handling certain event types and emitting new events.
+Workflows are a simple and lightweight engine for TypeScript. Built with ❤️ by LlamaIndex.
 
-Workflows are designed for any cases that benefit from event-driven programming, not only for LLM and AI tasks.
+- Minimal core API (\<\=2kb)
+- 100% Type safe
+- Event-driven, stream oriented programming
+- Support for multiple JS runtimes/frameworks
 
-```package-install
-npm i @llamaindex/workflow
+## Installation
+
+It's directly included with the `llamaindex` package:
+
+```shell
+npm i llamaindex
 ```
 
-## Start from scratch
-
-Let's start from a Hello World workflow.
-
-```ts twoslash
-import { Workflow } from '@llamaindex/workflow';
-
-type ContextData = {
-	counter: number;
-}
-// ---cut---
-const contextData: ContextData = { counter: 0 };
-
-const workflow = new Workflow<ContextData, string, string>();
-//     ^?
+But can also be installed separately:
 
+```shell
+npm i @llama-flow/core
 
+# or with yarn
+yarn add @llama-flow/core
 
+# or with pnpm
+pnpm add @llama-flow/core
 ```
 
-First, we define a workflow with 3 generic types: `ContextData`, `Input`, and `Output`.
+## Key Concepts
 
-In general, `ContextData` is used to store the shared data between steps, `Input` is the type of the input event, and `Output` is the type of the output event.
+- **Events**: Data carriers that flow through the workflow
+- **Handlers**: Functions that process events and emit new events
+- **Workflow**: Connects events and handlers together
+- **Context**: Runtime environment for a workflow execution
 
-In you code logic, you should **share state between steps via `ContextData`**.
+## Basic Usage
 
-```ts twoslash
-import { Workflow, StartEvent, StopEvent } from '@llamaindex/workflow';
+Let's build a simple workflow that processes a text input:
 
-type ContextData = {
-	counter: number;
-}
+### 1. Define events
 
-const contextData: ContextData = { counter: 0 };
+First, we need to define the events that will flow through our workflow:
 
-const workflow = new Workflow<ContextData, string, string>();
-// ---cut---
-workflow.addStep({
-	inputs: [StartEvent<string>],
-	outputs: [StopEvent<string>]
-}, async (context, startEvent) => {
-	const input = startEvent.data;
-	context.data.counter++;
-	return new StopEvent(`Hello, ${input}!`);
+```ts
+import { workflowEvent } from "llamaindex";
+
+// Define input and output events
+const startEvent = workflowEvent<string>(); // Takes a string input
+const convertEvent = workflowEvent<Number>();       // Intermediate event
+const stopEvent = workflowEvent<1 | -1>();  // Final output event, returns 1 or -1
+```
+
+### 2. Create a workflow and connect events
+
+Next, we'll create our workflow and define how events are processed:
+
+```ts
+import { createWorkflow } from "llamaindex";
+
+const workflow = createWorkflow();
+
+// Handle the start event: convert the string to a number
+workflow.handle([startEvent], (start) => {
+  return convertEvent.with(Number.parseInt(start.data, 10));
+});
+
+// Handle the convert event: determine if number is positive or negative
+workflow.handle([convertEvent], (convert) => {
+  return stopEvent.with(convert.data > 0 ? 1 : -1);
 });
 ```
 
-In the workflow, we add a step that listens to `StartEvent<string>` and emits `StopEvent<string>`.
+### 3. Run the workflow
 
-The step is an async function that takes two arguments: `context` and `event`.
+Finally, we can execute our workflow:
 
-### `context` type
+```ts
+// Create a workflow context and send the initial event
+const { stream, sendEvent } = workflow.createContext();
+sendEvent(startEvent.with("42"));
 
-<AutoTypeTable path="./src/deps/type.ts" name="HandlerContext" />
+// Process the stream to get the result
+import { pipeline } from "node:stream/promises";
 
-There are two more properties in `HandlerContext`:
-
-- `sendEvent`: invoke another event in the workflow, other than `StartEvent`, `StopEvent`, or the current event. (Or there will have circular reference)
-- `requireEvent`: wait for a specific event to be emitted.
-
-You can use `sendEvent` and `requireEvent` to build complex workflows.
-
-```ts twoslash
-import { Workflow, StartEvent, StopEvent, WorkflowEvent } from '@llamaindex/workflow';
-
-type ContextData = {
-	counter: number;
-}
-
-const contextData: ContextData = { counter: 0 };
-
-const workflow = new Workflow<ContextData, string, string>();
-
-// ---cut---
-class AnalysisStartEvent extends WorkflowEvent<string> {}
-class AnalysisStopEvent extends WorkflowEvent<boolean> {}
-workflow.addStep({
-	inputs: [AnalysisStartEvent],
-	outputs: [AnalysisStopEvent]
-}, async (...args) => {
-	// do some analysis
-	return new AnalysisStopEvent(true);
-})
-workflow.addStep({
-	inputs: [StartEvent<string>],
-	outputs: [StopEvent<string>]
-}, async (context, startEvent) => {
-	const input = startEvent.data;
-	context.sendEvent(new AnalysisStartEvent('start'));
-	context.data.counter++;
-	const { data } = await context.requireEvent(AnalysisStopEvent);
-	return new StopEvent(`Hello, ${input}! Analysis result: ${data ? 'success' : 'fail'}`);
-});
-```
-
-For example, you can compile `requireEvent` with `waitUntil` in [Vercel Functions](https://vercel.com/docs/functions/functions-api-reference#waituntil) or [Cloudflare Worker](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil)
-
-```ts twoslash
-import { waitUntil } from '@vercel/functions';
-import { Workflow, StartEvent, StopEvent, WorkflowEvent } from '@llamaindex/workflow';
-
-type ContextData = {
-	counter: number;
-}
-
-const contextData: ContextData = { counter: 0 };
-
-const workflow = new Workflow<ContextData, string, string>();
-
-class AnalysisStartEvent extends WorkflowEvent<string> {}
-class AnalysisStopEvent extends WorkflowEvent<boolean> {}
-
-// ---cut---
-workflow.addStep({
-	inputs: [StartEvent<string>],
-	outputs: [StopEvent<string>]
-}, async (context, startEvent) => {
-	const input = startEvent.data;
-	context.sendEvent(new AnalysisStartEvent('start'));
-	context.data.counter++;
-	waitUntil(context.requireEvent(AnalysisStopEvent));
-	// note that `waitUntil` is not a promise, it will extend the lifetime of the workflow
-	// you can wait for some background tasks to finish
-	return new StopEvent(`Hello, ${input}!`);
-});
-```
-
-## Multiple runs
-
-You can run the same workflow multiple times with different inputs.
-
-```ts twoslash
-import { Workflow, StartEvent, StopEvent } from '@llamaindex/workflow';
-
-type ContextData = {
-	counter: number;
-}
-
-const contextData: ContextData = { counter: 0 };
-
-const workflow = new Workflow<ContextData, string, string>();
-
-workflow.addStep({
-	inputs: [StartEvent<string>],
-	outputs: [StopEvent<string>]
-}, async (context, startEvent) => {
-	const input = startEvent.data;
-	context.data.counter++;
-	return new StopEvent(`Hello, ${input}!`);
+const result = await pipeline(stream, async function (source) {
+  for await (const event of source) {
+    if (stopEvent.include(event)) {
+      return `Result: ${event.data === 1 ? 'positive' : 'negative'}`;
+    }
+  }
 });
 
-// ---cut---
-{
-	const ret = await workflow.run('Alex', contextData);
-	console.log(ret.data); // Hello, Alex!
-}
-
-{
-	const ret = await workflow.run('World', contextData);
-	console.log(ret.data); // Hello, World!
-}
+console.log(result); // "Result: positive"
 ```
 
-Context is shared between runs, so the counter will be increased.
+Or using the stream utilities:
 
-Ideally, it should be serializable to make sure it can be recovered from HTTP requests or other storage.
+```ts
+import { collect, until } from "llamaindex";
 
-### Full example
+// Collect all events until we get a stopEvent
+const allEvents = await collect(until(stream, stopEvent));
+const finalEvent = allEvents[allEvents.length - 1];
+console.log(`Result: ${finalEvent.data === 1 ? 'positive' : 'negative'}`);
+```
 
-<iframe
-	className="w-full h-[440px]"
-	aria-label="Workflow example"
-	src="https://stackblitz.com/github/run-llama/LlamaIndexTS/tree/main/examples?file=node/workflow/basic.ts"
-/>
-
-## `Workflow` type
-
-<AutoTypeTable path="./src/deps/type.ts" name="Workflow" />
-
-## `WorkflowContext` type
-
-<AutoTypeTable path="./src/deps/type.ts" name="WorkflowContext" />
+Ready to learn more? Check out our [detailed examples](./basic-workflow.mdx) to see llama-flow in action!

apps/next/src/content/docs/llamaindex/tutorials/workflow/llamaindex-integration.mdx

@@ -0,0 +1,288 @@
+---
+title: Integrating with LlamaIndex
+description: Build AI applications by combining Workflows with other LlamaIndex features
+---
+
+This guide demonstrates how to combine the power of the workflow engine with LlamaIndex's retrieval and reasoning capabilities to build sophisticated AI applications.
+
+## Basic RAG Workflow
+
+Let's build a simple Retrieval-Augmented Generation (RAG) workflow:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+import { Document, serviceContextFromDefaults, VectorStoreIndex } from "llamaindex";
+import { OpenAI, OpenAIEmbedding } from "@llamaindex/openai";
+import { Settings } from "@llamaindex/core/global"
+
+// Define events
+const queryEvent = workflowEvent<string>();
+const retrieveEvent = workflowEvent<{ query: string; documents: Document[] }>();
+const generateEvent = workflowEvent<{ query: string; context: string }>();
+const responseEvent = workflowEvent<string>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+// Set default global llm
+Settings.llm = new OpenAI({ 
+  model: "gpt-4.1-mini", 
+  temperature: 0.2 
+});
+
+// Set the default global embedModel
+Settings.embedModel = new OpenAIEmbedding({
+  model: "text-embedding-3-small",
+});
+
+// Sample documents
+const documents = [
+  new Document({
+    text: "LlamaIndex is a data framework for LLM applications to ingest, structure, and access private or domain-specific data.",
+  }),
+  new Document({
+    text: "LlamaIndex workflows are a lightweight workflow engine for TypeScript, designed to create event-driven processes.",
+  }),
+];
+
+// Create vector store index
+const index = await VectorStoreIndex.fromDocuments(documents);
+
+// Handle query: Retrieve relevant documents
+workflow.handle([queryEvent], (event) => {
+  const query = event.data;
+  console.log(`Processing query: ${query}`);
+  
+  // Retrieve relevant documents
+  const retriever = index.asRetriever();
+  const nodes = retriever.retrieve(query);
+  
+  return retrieveEvent.with({
+    query,
+    documents: nodes.map(node => node.node),
+  });
+});
+
+// Handle retrieval results: Generate response
+workflow.handle([retrieveEvent], async (event) => {
+  const { query, documents } = event.data;
+  
+  // Combine document content as context
+  const context = documents.map(doc => doc.text).join('\n\n');
+  
+  return generateEvent.with({ query, context });
+});
+
+// Handle generation: Produce final response
+workflow.handle([generateEvent], async (event) => {
+  const { query, context } = event.data;
+  
+  // Create a prompt with the context and query
+  const prompt = `
+Context information:
+${context}
+
+Based on the context information and no other knowledge, answer the following query:
+${query}
+  `;
+  
+  // Generate response with LLM
+  const response = await Settings.llm.complete({ prompt });
+  
+  return responseEvent.with(response.text);
+});
+
+// Execute the workflow
+const { stream, sendEvent } = workflow.createContext();
+sendEvent(queryEvent.with("What is LlamaIndex?"));
+
+// Process the stream
+for await (const event of stream) {
+  if (responseEvent.include(event)) {
+    console.log("Final response:", event.data);
+    break;
+  }
+}
+```
+
+## Building a Chat Application
+
+Let's create a more complex chat application that maintains conversation history:
+
+```ts
+import { createWorkflow, workflowEvent, withStore } from "llamaindex";
+import { OpenAI, OpenAIEmbedding } from "@llamaindex/openai";
+import { Document, serviceContextFromDefaults, VectorStoreIndex } from "llamaindex";
+import { Settings } from "@llamaindex/core/global"
+
+// Set default global llm
+Settings.llm = new OpenAI({ 
+  model: "gpt-4.1-mini", 
+  temperature: 0.2 
+});
+
+// Set the default global embedModel
+Settings.embedModel = new OpenAIEmbedding({
+  model: "text-embedding-3-small",
+});
+
+// Define store type
+type ChatStore = {
+  history: Array<{ role: string; content: string }>;
+  documents: Document[];
+  index: VectorStoreIndex | null;
+};
+
+// Define events
+const initEvent = workflowEvent<Document[]>();
+const indexCreatedEvent = workflowEvent<VectorStoreIndex>();
+const userMessageEvent = workflowEvent<string>();
+const retrievalEvent = workflowEvent<{ query: string; nodes: any[] }>();
+const responseEvent = workflowEvent<{ message: { content: string } }>();
+
+// Create workflow with store
+const workflow = withStore<ChatStore>(
+  () => ({
+    history: [],
+    documents: [],
+    index: null,
+  }),
+  createWorkflow()
+);
+
+// Initialize the chat context
+workflow.handle([initEvent], async (event) => {
+  const store = workflow.getStore();
+  store.documents = event.data;
+  
+  // Create index from documents
+  const index = await VectorStoreIndex.fromDocuments(store.documents);
+  
+  store.index = index;
+  return indexCreatedEvent.with(index);
+});
+
+// Process user message
+workflow.handle([userMessageEvent], (event) => {
+  const userMessage = event.data;
+  const store = workflow.getStore();
+  
+  // Add user message to history
+  store.history.push({
+    role: "user",
+    content: userMessage,
+  });
+  
+  if (!store.index) {
+    throw new Error("Index not initialized yet");
+  }
+  
+  // Retrieve relevant context
+  const retriever = store.index.asRetriever();
+  const nodes = retriever.retrieve(userMessage);
+  
+  return retrievalEvent.with({
+    query: userMessage,
+    nodes,
+  });
+});
+
+// Generate response from retrieval results
+workflow.handle([retrievalEvent], async (event) => {
+  const { query, nodes } = event.data;
+  const store = workflow.getStore();
+  
+  // Context from retrieved nodes
+  const context = nodes.map(node => node.node.text).join('\n\n');
+  
+  // Create the system message with context
+  const systemMessage = {
+    role: "system",
+    content: `You are a helpful assistant. Use the following information to answer the user's question:
+    
+${context}
+    
+Only use the information provided above to answer. If you don't know, say so.`,
+  };
+  
+  // Create full conversation history for the chat
+  const messages = [
+    systemMessage,
+    ...store.history,
+  ];
+  
+  // Generate response
+  const response = await Settings.llm.chat({
+    messages,
+  });
+  
+  // Add assistant response to history
+  store.history.push({
+    role: "assistant",
+    content: response.message.content,
+  });
+  
+  return responseEvent.with(response);
+});
+
+// Example usage
+async function runChat() {
+  // Sample documents
+  const documents = [
+    new Document({
+      text: "LlamaIndex is a data framework for LLM applications to ingest, structure, and access private or domain-specific data.",
+    }),
+    new Document({
+      text: "LlamaIndex Workflows are a lightweight workflow engine for TypeScript, designed to create event-driven processes.",
+    }),
+  ];
+  
+  // Initialize the chat
+  const { stream, sendEvent } = workflow.createContext();
+  sendEvent(initEvent.with(documents));
+  
+  // Wait for index creation
+  for await (const event of stream) {
+    if (indexCreatedEvent.include(event)) {
+      console.log("Index created successfully");
+      break;
+    }
+  }
+  
+  // Start conversation
+  async function sendUserMessage(message: string) {
+    sendEvent(userMessageEvent.with(message));
+    
+    for await (const event of stream) {
+      if (responseEvent.include(event)) {
+        console.log("Assistant:", event.data.message.content);
+        return event.data.message.content;
+      }
+    }
+  }
+  
+  await sendUserMessage("What is LlamaIndex?");
+  await sendUserMessage("Can you tell me about LlamaIndex workflows?");
+  await sendUserMessage("How might these two technologies work together?");
+}
+
+runChat();
+```
+
+## Building an Tool Calling Agent
+
+[TODO]
+
+## Conclusion
+
+By combining the lightweight, event-driven workflow engine with LlamaIndex's powerful document indexing and querying capabilities, you can build sophisticated AI applications with clean, maintainable code.
+
+The event-driven architecture allows you to:
+
+1. Break complex processes into manageable steps
+2. Create reusable components for common AI workflows
+3. Easily debug and monitor each phase of execution
+4. Scale your applications by isolating resource-intensive steps
+5. Build more resilient systems with better error handling
+
+As you build your own applications, consider how the patterns shown here can be adapted to your specific use cases. 

apps/next/src/content/docs/llamaindex/tutorials/workflow/meta.json

@@ -1,6 +1,12 @@
 {
-  "title": "Workflow",
-  "description": "See how to use @llamaindex/workflow",
+  "title": "Workflows",
+  "description": "Event-driven workflow engine for TypeScript",
   "defaultOpen": false,
-  "pages": ["index", "different-inputs-outputs", "streaming"]
+  "pages": [
+    "index",
+    "basic-workflow",
+    "streaming",
+    "advanced-events",
+    "llamaindex-integration"
+  ]
 }

apps/next/src/content/docs/llamaindex/tutorials/workflow/streaming.mdx

@@ -1,198 +1,371 @@
 ---
-title: Streaming
-description: Learn how to use the LlamaIndex workflow with streaming.
+title: Streaming with Workflows
+description: Learn how to build streaming workflows
 ---
 
-`Workflow` API by default is designed for streaming data. In this guide, we will show you how to use the `Workflow` API with streaming data.
+LlamaIndex workflows are designed from the ground up to work with streaming data. The streaming capabilities make it perfect for:
 
-Each `workflow.run` call returns `WorkflowContext`, which implements `AsyncIterable` interface. You can use it to stream data.
+- Building real-time applications
+- Handling large datasets incrementally
+- Creating responsive UIs that update as data becomes available
+- Implementing long-running tasks with partial results
 
-```ts twoslash
-import { Workflow, WorkflowEvent, StartEvent, StopEvent } from '@llamaindex/workflow';
-class ComputeEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
+## Basic Streaming
+
+Every workflow context provides a stream of events:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+// Define events
+const startEvent = workflowEvent<string>();
+const intermediateEvent = workflowEvent<string>();
+const resultEvent = workflowEvent<string>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+workflow.handle([startEvent], (event) => {
+  const { sendEvent } = getContext();
+  
+  // Emit multiple intermediate events
+  for (let i = 0; i < 5; i++) {
+    sendEvent(intermediateEvent.with(`Progress: ${i * 20}%`));
+  }
+  
+  return resultEvent.with("Completed");
+});
+
+// Run the workflow
+const { stream, sendEvent } = workflow.createContext();
+sendEvent(startEvent.with("Start processing"));
+
+// Process events as they arrive
+for await (const event of stream) {
+  if (intermediateEvent.include(event)) {
+    console.log(event.data); // Show progress updates
+  } else if (resultEvent.include(event)) {
+    console.log("Final result:", event.data);
+    break; // Exit the loop when done
+  }
 }
-class ComputeResultEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
+```
+
+## Using the Stream Utilities
+
+Workflows provide utility functions to make working with streams easier:
+
+```ts
+import { createWorkflow, workflowEvent, until, collect } from "llamaindex";
+
+const startEvent = workflowEvent<void>();
+const progressEvent = workflowEvent<number>();
+const resultEvent = workflowEvent<string>();
+
+const workflow = createWorkflow();
+
+workflow.handle([startEvent], () => {
+  const { sendEvent } = getContext();
+  
+  // Emit progress events
+  for (let i = 0; i < 100; i += 10) {
+    sendEvent(progressEvent.with(i));
+  }
+  
+  return resultEvent.with("Complete");
+});
+
+// Run the workflow and collect events until a condition is met
+const { stream, sendEvent } = workflow.createContext();
+sendEvent(startEvent.with());
+
+// Collect all events until resultEvent is encountered
+const events = await collect(until(stream, (event) => resultEvent.include(event)));
+
+// Filter only progress events
+const progressEvents = events.filter(event => progressEvent.include(event));
+console.log(`Received ${progressEvents.length} progress updates`);
+```
+
+## Conditional Stream Processing
+
+You can conditionally process events and even stop the stream early:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+const startEvent = workflowEvent<number>();
+const dataEvent = workflowEvent<number>();
+const thresholdEvent = workflowEvent<void>();
+const resultEvent = workflowEvent<number[]>();
+
+const workflow = createWorkflow();
+
+workflow.handle([startEvent], (event) => {
+  const { sendEvent } = getContext();
+  const max = event.data;
+  
+  for (let i = 0; i < max; i++) {
+    sendEvent(dataEvent.with(i));
+    if (i >= 10) {
+      // Signal that we've hit a threshold
+      sendEvent(thresholdEvent.with());
+    }
+  }
+  
+  return resultEvent.with(Array.from({ length: max }, (_, i) => i));
+});
+
+// Run the workflow
+const { stream, sendEvent } = workflow.createContext();
+sendEvent(startEvent.with(100)); // Generate 100 numbers
+
+const results = [];
+let hitThreshold = false;
+
+// Process the stream
+for await (const event of stream) {
+  if (dataEvent.include(event)) {
+    results.push(event.data);
+  } else if (thresholdEvent.include(event)) {
+    hitThreshold = true;
+    break; // Stop processing early
+  }
 }
 
-type ContextData = {
-	sum: number;
-}
+console.log(`Collected ${results.length} items before ${hitThreshold ? 'hitting threshold' : 'completion'}`);
+```
 
-const workflow = new Workflow<ContextData, number, number>();
-workflow.addStep({
-	inputs: [StartEvent<number>],
-	outputs: [StopEvent<number>]
-}, async (context, startEvent) => {
-	const total = startEvent.data;
-	for (let i = 0; i < total; i++) {
-		context.sendEvent(new ComputeEvent(i));
-	}
-	const computeResults = await Promise.all(Array.from({ length: total }).map(() => context.requireEvent(ComputeResultEvent)));
-	// Workflow API allows you to start events in parallel and wait for all of them to finish
-	context.data.sum = computeResults.reduce((acc, curr) => acc + curr.data, 0);
-	return new StopEvent(context.data.sum);
+## Integration with UI Frameworks
+
+Workflow streams can be easily integrated with UI frameworks like React to create responsive interfaces:
+
+```tsx
+// In a React component
+import { useEffect, useState } from 'react';
+import { createWorkflow, workflowEvent } from "llamaindex";
+
+function StreamingComponent() {
+  const [updates, setUpdates] = useState([]);
+  const [isComplete, setIsComplete] = useState(false);
+  
+  useEffect(() => {
+    // Set up workflow
+    const startEvent = workflowEvent<void>();
+    const updateEvent = workflowEvent<string>();
+    const completeEvent = workflowEvent<void>();
+    
+    const workflow = createWorkflow();
+    
+    workflow.handle([startEvent], () => {
+      const { sendEvent } = getContext();
+      
+      // Simulate async updates
+      const intervals = [
+        setTimeout(() => sendEvent(updateEvent.with("First update")), 500),
+        setTimeout(() => sendEvent(updateEvent.with("Second update")), 1000),
+        setTimeout(() => sendEvent(updateEvent.with("Final update")), 1500),
+        setTimeout(() => sendEvent(completeEvent.with()), 2000)
+      ];
+      
+      // Cleanup function
+      getContext().signal.onabort = () => {
+        intervals.forEach(clearTimeout);
+      };
+    });
+    
+    // Run the workflow
+    const { stream, sendEvent } = workflow.createContext();
+    sendEvent(startEvent.with());
+    
+    // Process events
+    const processEvents = async () => {
+      for await (const event of stream) {
+        if (updateEvent.include(event)) {
+          setUpdates(prev => [...prev, event.data]);
+        } else if (completeEvent.include(event)) {
+          setIsComplete(true);
+          break;
+        }
+      }
+    };
+    
+    processEvents();
+    
+    // Cleanup
+    return () => {
+      // The workflow will be aborted when the component unmounts
+    };
+  }, []);
+  
+  return (
+    <div>
+      <h2>Streaming Updates</h2>
+      <ul>
+        {updates.map((update, i) => (
+          <li key={i}>{update}</li>
+        ))}
+      </ul>
+      {isComplete && <div>Process complete!</div>}
+    </div>
+  );
+}
+```
+
+## Server-Sent Events (SSE)
+
+Workflows are also suitable for implementing Server-Sent Events:
+
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
+import express from 'express';
+
+// Define events
+const startEvent = workflowEvent<void>();
+const dataEvent = workflowEvent<string>();
+
+// Create workflow
+const workflow = createWorkflow();
+
+workflow.handle([startEvent], () => {
+  const { sendEvent } = getContext();
+  
+  // Send periodic updates
+  const intervals = [
+    setInterval(() => {
+      sendEvent(dataEvent.with(`Update: ${new Date().toISOString()}`));
+    }, 1000)
+  ];
+  
+  // Cleanup
+  getContext().signal.onabort = () => {
+    intervals.forEach(clearInterval);
+  };
+});
+
+// Set up Express server
+const app = express();
+
+app.get('/events', (req, res) => {
+  // Set headers for SSE
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  
+  // Run workflow
+  const { stream, sendEvent } = workflow.createContext();
+  sendEvent(startEvent.with());
+  
+  // Handle client disconnect
+  req.on('close', () => {
+    // This will trigger the abort signal in the workflow
+  });
+  
+  // Process and send events
+  (async () => {
+    for await (const event of stream) {
+      if (dataEvent.include(event)) {
+        res.write(`data: ${JSON.stringify(event.data)}\n\n`);
+      }
+    }
+  })();
+});
+
+app.listen(3000, () => {
+  console.log('SSE server running on port 3000');
 });
 ```
 
-We define a parallel computation workflow that computes the sum of numbers from 0 to `total`.
+## Advanced Techniques
 
-The workflow sends `ComputeEvent` events for each number and waits for `ComputeResultEvent` events. After receiving all `ComputeResultEvent` events, the workflow returns the sum as a `StopEvent`.
+### Flow Control
 
-What if we want cutoff if the sum exceeds a certain value?
+You can implement flow control with backpressure in your streaming workflows:
 
-## Streaming
+```ts
+import { createWorkflow, workflowEvent } from "llamaindex";
 
-```ts twoslash
-import { Workflow, WorkflowEvent, StartEvent, StopEvent } from '@llamaindex/workflow';
-import { StopCircle } from 'lucide-react';
-class ComputeEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
-class ComputeResultEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
+// This example shows how to process items with controlled concurrency
+const processItems = async (items, maxConcurrency = 3) => {
+  const startEvent = workflowEvent<string[]>();
+  const processItemEvent = workflowEvent<string>();
+  const itemProcessedEvent = workflowEvent<string>();
+  const resultEvent = workflowEvent<string[]>();
+  
+  const workflow = createWorkflow();
+  
+  // Handler to process individual items
+  workflow.handle([processItemEvent], async (event) => {
+    // Simulate processing time
+    await new Promise(resolve => setTimeout(resolve, 100));
+    return itemProcessedEvent.with(`Processed: ${event.data}`);
+  });
+  
+  // Main workflow handler
+  workflow.handle([startEvent], async (event) => {
+    const { sendEvent, stream } = getContext();
+    const results = [];
+    
+    // Process with controlled concurrency
+    const items = event.data;
+    let inProgress = 0;
+    let itemIndex = 0;
+    
+    // Start initial batch of items
+    while (inProgress < maxConcurrency && itemIndex < items.length) {
+      sendEvent(processItemEvent.with(items[itemIndex++]));
+      inProgress++;
+    }
+    
+    // Process items and collect results
+    for await (const event of stream) {
+      if (itemProcessedEvent.include(event)) {
+        results.push(event.data);
+        inProgress--;
+        
+        // Add next item if available
+        if (itemIndex < items.length) {
+          sendEvent(processItemEvent.with(items[itemIndex++]));
+          inProgress++;
+        } else if (inProgress === 0) {
+          // All done
+          break;
+        }
+      }
+    }
+    
+    return resultEvent.with(results);
+  });
+  
+  // Run the workflow
+  const { stream, sendEvent } = workflow.createContext();
+  sendEvent(startEvent.with(items));
+  
+  // Wait for final result
+  for await (const event of stream) {
+    if (resultEvent.include(event)) {
+      return event.data;
+    }
+  }
+  
+  return [];
+};
 
-
-type ContextData = {
-	sum: number;
-}
-
-const workflow = new Workflow<ContextData, number, number>();
-// ---cut---
-const context = workflow.run(1000, {
-	sum: 0
-});
-
-for await (const event of context) {
-	if (event instanceof ComputeEvent) {
-		if (context.data.sum > 100) {
-			throw new Error('Sum exceeds 100');
-		}
-	}
-	if (event instanceof StopEvent) {
-		console.log('result', event.data);
-	}
-}
-```
-
-You can define more custom logic using `AsyncIterable` interface.
-
-For example. I just want to stop the workflow if I get a `ComputeResultEvent`
-
-
-```ts twoslash
-import { Workflow, WorkflowEvent, StartEvent, StopEvent } from '@llamaindex/workflow';
-import { StopCircle } from 'lucide-react';
-class ComputeEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
-class ComputeResultEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
-
-
-type ContextData = {
-	sum: number;
-}
-
-const workflow = new Workflow<ContextData, number, number>();
-// ---cut---
-async function compute() {
-	const context = workflow.run(1000, {
-		sum: 0
-	});
-	for await (const event of context) {
-		if (event instanceof ComputeResultEvent) {
-			return event.data;
-		}
-	}
-	throw new Error('UNREACHABLE');
-}
-
-const result = await compute();
-```
-
-### Streaming with UI
-
-You can use the `Workflow` API with UI libraries like React.
-
-```tsx twoslash
-// @filename: utils.ts
-export async function runWithoutBlocking(fn: () => Promise<void>) {
-	fn();
-}
-// @filename: action.ts
-// ---cut---
-'use server';
-// "use server" is required to enable server side feature in React
-import { createStreamableUI } from 'ai/rsc';
-import { runWithoutBlocking } from './utils';
-// ---cut-start---
-import { Workflow, WorkflowEvent, StartEvent, StopEvent } from '@llamaindex/workflow';
-class ComputeEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
-class ComputeResultEvent extends WorkflowEvent<number> {
-	constructor(data: number) {
-		super(data);
-	}
-}
-
-
-type ContextData = {
-	sum: number;
-}
-
-const workflow = new Workflow<ContextData, number, number>();
-const min = 100;
-const max = 1000;
-workflow.addStep(
-	{
-		inputs: [ComputeEvent],
-		outputs: [ComputeResultEvent]
-	},
-	async (context, event) => {
-		await new Promise((resolve) =>
-			setTimeout(resolve, Math.floor(Math.random() * (max - min + 1) + min))
-		);
-		return new ComputeResultEvent(event.data);
-	}
+// Usage
+const results = await processItems(
+  Array.from({ length: 20 }, (_, i) => `Item ${i}`)
 );
-// ---cut-end---
-export async function compute() {
-	'use server';
-	const ui = createStreamableUI();
-	const context = workflow.run(100, {
-		sum: 0
-	});
-	runWithoutBlocking(async () => {
-		for await (const event of context) {
-			if (event instanceof ComputeResultEvent) {
-				// Update UI
-			} else if (event instanceof StopEvent) {
-				// Update UI
-			}
-			// ...
-		}
-	});
-	return ui.value;
-}
+console.log(results);
 ```
 
-<WorkflowStreamingDemo />
+This pattern allows you to:
+1. Process large datasets without overwhelming system resources
+2. Control the level of concurrency
+3. Process data as it becomes available
+4. Create efficient data pipelines
+
+## Next Steps
+
+Now that you've learned about streaming with workflows, explore more advanced topics:
+- [Advanced Event Handling](./advanced-events.mdx)
+- [Integration Workflows with other LlamaIndex features](./llamaindex-integration.mdx)