Release 0.10.6 (#1942)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: marcusschiesser <17126+marcusschiesser@users.noreply.github.com>

.github/workflows/test.yml

@@ -87,6 +87,30 @@ jobs:
         run: pnpm run type-check
       - name: Run Circular Dependency Check
         run: pnpm run circular-check
+  e2e-npm:
+    runs-on: ubuntu-latest
+    name: Test using packages with npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build packages
+        run: pnpm run build
+      - name: Pack packages
+        run: |
+          pnpm pack --pack-destination ${{ runner.temp }} -C packages/llamaindex
+          pnpm pack --pack-destination ${{ runner.temp }} -C packages/workflow
+      - name: Install packed packages
+        run: npm add ${{ runner.temp }}/*.tgz
+        working-directory: e2e/npm
+      - name: Run tests
+        run: npm test
+        working-directory: e2e/npm
   e2e-llamaindex-examples:
     strategy:
       fail-fast: false

README.md

@@ -7,9 +7,10 @@
 </h3>
 
 [![NPM Version](https://img.shields.io/npm/v/llamaindex)](https://www.npmjs.com/package/llamaindex)
-[![NPM License](https://img.shields.io/npm/l/llamaindex)](https://www.npmjs.com/package/llamaindex)
+[![NPM License](https://img.shields.io/npm/l/llamaindex)](https://github.com/run-llama/LlamaIndexTS/blob/main/LICENSE)
 [![NPM Downloads](https://img.shields.io/npm/dm/llamaindex)](https://www.npmjs.com/package/llamaindex)
 [![Discord](https://img.shields.io/discord/1059199217496772688)](https://discord.com/invite/eN6D2HQ4aX)
+[![Twitter](https://img.shields.io/twitter/follow/llama_index)](https://x.com/llama_index)
 
 Use your own data with large language models (LLMs, OpenAI ChatGPT and others) in JS runtime environments with TypeScript support.
 
@@ -63,7 +64,7 @@ yarn add llamaindex
 
 ### Setup in Node.js, Deno, Bun, TypeScript...?
 
-See our official document: <https://ts.llamaindex.ai/docs/llamaindex/getting_started/>
+See our official document: https://ts.llamaindex.ai/docs/llamaindex/getting_started
 
 ### Adding provider packages
 
@@ -83,19 +84,7 @@ Check out our NextJS playground at https://llama-playground.vercel.app/. The sou
 
 ## Core concepts for getting started:
 
-- [Document](/packages/llamaindex/src/Node.ts): A document represents a text file, PDF file or other contiguous piece of data.
-
-- [Node](/packages/llamaindex/src/Node.ts): The basic data building block. Most commonly, these are parts of the document split into manageable pieces that are small enough to be fed into an embedding model and LLM.
-
-- [Embedding](/packages/llamaindex/src/embeddings/OpenAIEmbedding.ts): Embeddings are sets of floating point numbers which represent the data in a Node. By comparing the similarity of embeddings, we can derive an understanding of the similarity of two pieces of data. One use case is to compare the embedding of a question with the embeddings of our Nodes to see which Nodes may contain the data needed to answer that question. Because the default service context is OpenAI, the default embedding is `OpenAIEmbedding`. If using different models, say through Ollama, use this [Embedding](/packages/llamaindex/src/embeddings/OllamaEmbedding.ts) (see all [here](/packages/llamaindex/src/embeddings)).
-
-- [Indices](/packages/llamaindex/src/indices/): Indices store the Nodes and the embeddings of those nodes. QueryEngines retrieve Nodes from these Indices using embedding similarity.
-
-- [QueryEngine](/packages/llamaindex/src/engines/query/RetrieverQueryEngine.ts): Query engines are what generate the query you put in and give you back the result. Query engines generally combine a pre-built prompt with selected Nodes from your Index to give the LLM the context it needs to answer your query. To build a query engine from your Index (recommended), use the [`asQueryEngine`](/packages/llamaindex/src/indices/BaseIndex.ts) method on your Index. See all query engines [here](/packages/llamaindex/src/engines/query).
-
-- [ChatEngine](/packages/llamaindex/src/engines/chat/SimpleChatEngine.ts): A ChatEngine helps you build a chatbot that will interact with your Indices. See all chat engines [here](/packages/llamaindex/src/engines/chat).
-
-- [SimplePrompt](/packages/llamaindex/src/Prompt.ts): A simple standardized function call definition that takes in inputs and formats them in a template literal. SimplePrompts can be specialized using currying and combined using other SimplePrompt functions.
+See our documentation: https://ts.llamaindex.ai/docs/llamaindex/getting_started/concepts
 
 ## Contributing:
 

apps/next/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @llamaindex/doc
 
+## 0.2.18
+
+### Patch Changes
+
+- d671ed6: Add functionality for search params when querying Qdrant vector store.
+- Updated dependencies [76c9a80]
+- Updated dependencies [168d11f]
+- Updated dependencies [d671ed6]
+- Updated dependencies [40f5f41]
+  - @llamaindex/openai@0.3.7
+  - @llamaindex/workflow@1.1.2
+  - @llamaindex/core@0.6.5
+  - @llamaindex/cloud@4.0.7
+  - llamaindex@0.10.6
+  - @llamaindex/node-parser@2.0.5
+  - @llamaindex/readers@3.1.3
+
+## 0.2.17
+
+### Patch Changes
+
+- Updated dependencies [9b2e25a]
+  - @llamaindex/openai@0.3.6
+  - @llamaindex/core@0.6.4
+  - llamaindex@0.10.5
+  - @llamaindex/cloud@4.0.6
+  - @llamaindex/node-parser@2.0.4
+  - @llamaindex/readers@3.1.2
+  - @llamaindex/workflow@1.1.1
+
 ## 0.2.16
 
 ### Patch Changes

apps/next/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/doc",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "private": true,
   "scripts": {
     "postinstall": "fumadocs-mdx",

apps/next/src/content/docs/llamaindex/getting_started/concepts.mdx

@@ -0,0 +1,60 @@
+---
+title: High-Level Concepts
+---
+
+This is a quick guide to the high-level concepts you'll encounter frequently when building LLM applications.
+
+## Large Language Models (LLMs)
+
+LLMs are the fundamental innovation that launched LlamaIndex. They are an artificial intelligence (AI) computer system that can understand, generate, and manipulate natural language, including answering questions based on their training data or data provided to them at query time. 
+
+## Agentic Applications
+
+When an LLM is used within an application, it is often used to make decisions, take actions, and/or interact with the world. This is the core definition of an **agentic application**.
+
+While the definition of an agentic application is broad, there are several key characteristics that define an agentic application:
+
+- **LLM Augmentation**: The LLM is augmented with tools (i.e. arbitrary callable functions in code), memory, and/or dynamic prompts.
+- **Prompt Chaining**: Several LLM calls are used that build on each other, with the output of one LLM call being used as the input to the next.
+- **Routing**: The LLM is used to route the application to the next appropriate step or state in the application.
+- **Parallelism**: The application can perform multiple steps or actions in parallel.
+- **Orchestration**: A hierarchical structure of LLMs is used to orchestrate lower-level actions and LLMs.
+- **Reflection**: The LLM is used to reflect and validate outputs of previous steps or LLM calls, which can be used to guide the application to the next appropriate step or state.
+
+In LlamaIndex, you can build agentic applications by using the workflows to orchestrate a sequence of steps and LLMs. You can [learn more about workflows](/docs/llamaindex/tutorials/workflows).
+
+## Agents
+
+We define an agent as a specific instance of an "agentic application". An agent is a piece of software that semi-autonomously performs tasks by combining LLMs with other tools and memory, orchestrated in a reasoning loop that decides which tool to use next (if any).
+
+What this means in practice, is something like:
+- An agent receives a user message
+- The agent uses an LLM to determine the next appropriate action to take using the previous chat history, tools, and the latest user message
+- The agent may invoke one or more tools to assist in the users request
+- If tools are used, the agent will then interpret the tool outputs and use them to inform the next action
+- Once the agent stops taking actions, it returns the final output to the user
+
+You can [learn more about agents](/docs/llamaindex/tutorials/basic_agent).
+
+## Retrieval Augmented Generation (RAG)
+
+Retrieval-Augmented Generation (RAG) is a core technique for building data-backed LLM applications with LlamaIndex. It allows LLMs to answer questions about your private data by providing it to the LLM at query time, rather than training the LLM on your data. To avoid sending **all** of your data to the LLM every time, RAG indexes your data and selectively sends only the relevant parts along with your query. You can [learn more about RAG](/docs/llamaindex/tutorials/rag).
+
+## Use cases
+
+There are endless use cases for data-backed LLM applications but they can be roughly grouped into four categories:
+
+[**Agents**](/docs/llamaindex/tutorials/basic_agent):
+An agent is an automated decision-maker powered by an LLM that interacts with the world via a set of [tools](/docs/llamaindex/modules/agents/tool). Agents can take an arbitrary number of steps to complete a given task, dynamically deciding on the best course of action rather than following pre-determined steps. This gives it additional flexibility to tackle more complex tasks.
+
+[**Workflows**](/docs/llamaindex/tutorials/workflows):
+A Workflow in LlamaIndex is a specific event-driven abstraction that allows you to orchestrate a sequence of steps and LLMs calls. Workflows can be used to implement any agentic application, and are a core component of LlamaIndex.
+
+[**Structured Data Extraction**](/docs/llamaindex/tutorials/structured_data_extraction):
+Pydantic extractors allow you to specify a precise data structure to extract from your data and use LLMs to fill in the missing pieces in a type-safe way. This is useful for extracting structured data from unstructured sources like PDFs, websites, and more, and is key to automating workflows.
+
+[**Query Engines**](/docs/llamaindex/modules/rag/query_engines):
+A query engine is an end-to-end flow that allows you to ask questions over your data. It takes in a natural language query, and returns a response, along with reference context retrieved and passed to the LLM.
+
+[**Chat Engines**](/docs/llamaindex/modules/rag/chat_engine):
+A chat engine is an end-to-end flow for having a conversation with your data (multiple back-and-forth instead of a single question-and-answer).

apps/next/src/content/docs/llamaindex/getting_started/installation/index.mdx

@@ -9,10 +9,10 @@ To install llamaindex, run the following command:
 npm i llamaindex
 ```
 
-In most cases, you'll also need an LLM package to use LlamaIndex. For example, to use the OpenAI LLM, you would install the following:
+In most cases, you'll also need an LLM package and the Workflow package to use LlamaIndex. For example, to use the OpenAI LLM with agents, you would install the following:
 
 ```package-install
-npm i @llamaindex/openai
+npm i @llamaindex/openai @llamaindex/workflow
 ```
 
 Go to [LLM APIs](/docs/llamaindex/modules/models/llms) to find out how to use other LLMs.

apps/next/src/content/docs/llamaindex/getting_started/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Getting Started",
-  "pages": ["installation", "create_llama", "examples"]
+  "pages": ["concepts", "installation", "create_llama", "examples"]
 }

apps/next/src/content/docs/llamaindex/modules/agents/workflows.mdx

@@ -6,171 +6,13 @@ A `Workflow` in LlamaIndex is a lightweight, event-driven abstraction used to ch
 
 Workflows are designed to be flexible and can be used to build agents, RAG flows, extraction flows, or anything else you want to implement.
 
+To use workflows install this package:
+
 ```package-install
-npm i @llamaindex/workflow @llamaindex/openai
+npm i @llamaindex/workflow
 ```
 
-## Getting Started
+This package is a stable, production-ready version of our [llama-flow](../../../llamaflow) project. 
 
-Let's explore a simple workflow example where a joke is generated and then critiqued and iterated on:
+While you can still reference the llama-flow documentation for detailed information about the underlying concepts, we recommend using the `@llamaindex/workflow` package for all new projects to ensure stability and long-term availability.
 
-<include cwd>../../examples/agents/workflow/joke.ts</include>
-
-There are a few moving pieces here, so let's go through this step by step.
-
-### Defining Workflow Events
-
-```typescript
-const startEvent = workflowEvent<string>(); // Input topic for joke
-const jokeEvent = workflowEvent<{ joke: string }>(); // Intermediate joke
-const critiqueEvent = workflowEvent<{ joke: string; critique: string }>(); // Intermediate critique
-const resultEvent = workflowEvent<{ joke: string; critique: string }>(); // Final joke + critique
-```
-
-Events are defined using the `workflowEvent` function and contain arbitrary data provided as a generic type. In this example, we have four events:
-- `startEvent`: Takes a string input (the joke topic)
-- `jokeEvent`: Contains an object with a joke property
-- `critiqueEvent`: Contains both the joke and its critique, used for the feedback loop
-- `resultEvent`: Contains the final joke and critique after any iterations
-
-### Setting up the Workflow with Stateful Middleware
-
-```typescript
-const { withState, getContext } = createStatefulMiddleware(() => ({
-  numIterations: 0,
-  maxIterations: 3,
-}));
-const jokeFlow = withState(createWorkflow());
-```
-
-Our workflow is implemented using the `createWorkflow()` function, enhanced with the `withState` middleware. This middleware provides shared state across all handlers, which in this case tracks:
-- `numIterations`: Counts how many iterations of joke improvement we've done
-- `maxIterations`: Sets a limit to prevent infinite loops
-
-This state will be accessible within workflows by using the `getContext().state` function.
-
-### Adding Handlers with Loops
-
-We have three key handlers in our workflow:
-
-1. The first handler processes the `startEvent`, generates an initial joke, and emits a `jokeEvent`:
-
-```typescript
-jokeFlow.handle([startEvent], async (event) => {
-  // Prompt the LLM to write a joke
-  const prompt = `Write your best joke about ${event.data}. Write the joke between <joke> and </joke> tags.`;
-  const response = await llm.complete({ prompt });
- 
-  // Parse the joke from the response
-  const joke =
-    response.text.match(/<joke>([\s\S]*?)<\/joke>/)?.[1]?.trim() ??
-    response.text;
-  return jokeEvent.with({ joke: joke });
-});
-```
-
-2. The second handler handles the `jokeEvent`, critiques the joke, and either:
-   - Emits a `critiqueEvent` if the joke needs improvement
-   - Emits a `resultEvent` if the joke is good enough
-
-```typescript
-jokeFlow.handle([jokeEvent], async (event) => {
-  // Prompt the LLM to critique the joke
-  const prompt = `Give a thorough critique of the following joke. If the joke needs improvement, put "IMPROVE" somewhere in the critique: ${event.data.joke}`;
-  const response = await llm.complete({ prompt });
- 
-  // If the critique includes "IMPROVE", keep iterating, else, return the result
-  if (response.text.includes("IMPROVE")) {
-    return critiqueEvent.with({
-      joke: event.data.joke,
-      critique: response.text,
-    });
-  }
- 
-  return resultEvent.with({ joke: event.data.joke, critique: response.text });
-});
-```
-
-3. The third handler processes the `critiqueEvent`, generates an improved joke based on the critique, and either:
-   - Loops back to the joke evaluation (if under the iteration limit)
-   - Emits the final `resultEvent` (if iteration limit reached)
-
-```typescript
-jokeFlow.handle([critiqueEvent], async (event) => {
-  // Keep track of the number of iterations
-  const state = getContext().state;
-  state.numIterations++;
- 
-  // Write a new joke based on the previous joke and critique
-  const prompt = `Write a new joke based on the following critique and the original joke. Write the joke between <joke> and </joke> tags.\n\nJoke: ${event.data.joke}\n\nCritique: ${event.data.critique}`;
-  const response = await llm.complete({ prompt });
- 
-  // Parse the joke from the response
-  const joke =
-    response.text.match(/<joke>([\s\S]*?)<\/joke>/)?.[1]?.trim() ??
-    response.text;
- 
-  // If we've done less than the max number of iterations, keep iterating
-  // else, return the result
-  if (state.numIterations < state.maxIterations) {
-    return jokeEvent.with({ joke: joke });
-  }
- 
-  return resultEvent.with({ joke: joke, critique: event.data.critique });
-});
-```
-
-### Running the Workflow
-
-```typescript
-async function main() {
-  const { stream, sendEvent } = jokeFlow.createContext();
-  sendEvent(startEvent.with("pirates"));
-
-  let result: { joke: string, critique: string } | undefined;
-
-  for await (const event of stream) {
-    // console.log(event.data);  optionally log the event data
-    if (resultEvent.include(event)) {
-      result = event.data;
-      break; // Stop when we get the final result
-    }
-  }
-  
-  console.log(result);
-}
-```
-
-To run the workflow, we:
-1. Create a workflow context with `createContext()`
-2. Trigger the initial event with `sendEvent()`
-3. Listen to the event stream and process events as they arrive
-4. Use `include()` to check if an event is of a specific type
-5. Break the loop when we receive our final result
-
-### Using Stream Utilities
-
-The `stream` returned by `createContext` contains utility functions to make working with event streams easier:
-
-```typescript
-// Create a workflow context and send the initial event
-const { stream, sendEvent } = jokeFlow.createContext();
-sendEvent(startEvent.with("pirates"));
-
-// Collect all events until we get a resultEvent
-const allEvents = await stream.until(resultEvent).toArray(); 
-
-// The last event will be the resultEvent
-const finalEvent = allEvents.at(-1);
-console.log(finalEvent.data); // Output the joke and critique
-```
-
-The stream utilities make it easier to work with the asynchronous event flow. In this example, we use:
-- `toArray`: Aggregates all events into an array
-- `until`: Creates a stream that emits events until a condition is met (in this case, until a resultEvent is received)
-
-You can combine these utilities with other stream operators like `filter` and `map` to create powerful processing pipelines.
-
-## Next Steps
-
-To learn more about workflows, check out [the documentation in the tutorial section](../../../llamaflow).

apps/next/src/content/docs/llamaindex/modules/data/stores/vector_stores/qdrant.mdx

@@ -88,7 +88,7 @@ async function main() {
 
   const response = await queryEngine.query({
     query: "What did the author do in college?",
-  });
+  }); // Additional filters and params can be passed as options
 
   // Output response
   console.log(response.toString());

apps/next/src/content/docs/llamaindex/tutorials/basic_agent.mdx

@@ -8,9 +8,10 @@ We have a comprehensive, step-by-step [guide to building agents in LlamaIndex.TS
 
 In a new folder:
 
-```bash npm2yarn
+```package-install
 npm init
 npm i -D typescript @types/node
+npm i @llamaindex/openai @llamaindex/workflow llamaindex zod
 ```
 
 ## Run agent
@@ -20,15 +21,14 @@ Create the file `example.ts`. This code will:
 - Create two tools for use by the agent:
   - A `sumNumbers` tool that adds two numbers
   - A `divideNumbers` tool that divides numbers
--
 - Give an example of the data structure we wish to generate
 - Prompt the LLM with instructions and the example, plus a sample transcript
 
-<include cwd>../../examples/agent/openai.ts</include>
+<include cwd>../../examples/agents/agent/openai.ts</include>
 
 To run the code:
 
-```bash
+```package-install
 npx tsx example.ts
 ```
 
@@ -36,9 +36,18 @@ You should expect output something like:
 
 ```
 {
-  content: 'The sum of 5 + 5 is 10. When you divide 10 by 2, you get 5.',
-  role: 'assistant',
-  options: {}
+  result: '5 + 5 is 10. Then, 10 divided by 2 is 5.',
+  state: {
+    memory: ChatMemoryBuffer {
+      chatStore: SimpleChatStore {},
+      chatStoreKey: 'chat_history',
+      tokenLimit: 750000
+    },
+    scratchpad: [],
+    currentAgentName: 'Agent',
+    agents: [ 'Agent' ],
+    nextAgentName: null
+  }
 }
 Done
 ```

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

@@ -4,7 +4,7 @@
     "basic_agent",
     "rag",
     "agents",
-    "../../llamaflow",
+    "workflows",
     "local_llm",
     "chatbot",
     "structured_data_extraction"

apps/next/src/content/docs/llamaindex/tutorials/rag/concepts.mdx

@@ -16,7 +16,7 @@ LlamaIndex uses a two stage method when using an LLM with your data:
 1. **indexing stage**: preparing a knowledge base, and
 2. **querying stage**: retrieving relevant context from the knowledge to assist the LLM in responding to a question
 
-![](./_static/concepts/rag.jpg)
+![](/_static/concepts/rag.jpg)
 
 This process is also known as Retrieval Augmented Generation (RAG).
 
@@ -28,7 +28,7 @@ Let's explore each stage in detail.
 
 LlamaIndex.TS help you prepare the knowledge base with a suite of data connectors and indexes.
 
-![](./_static/concepts/indexing.jpg)
+![](/_static/concepts/indexing.jpg)
 
 [**Data Loaders**](/docs/llamaindex/modules/data/readers):
 A data connector (i.e. `Reader`) ingest data from different data sources and data formats into a simple `Document` representation (text and simple metadata).
@@ -54,7 +54,7 @@ LlamaIndex provides composable modules that help you build and integrate RAG pip
 
 These building blocks can be customized to reflect ranking preferences, as well as composed to reason over multiple knowledge bases in a structured way.
 
-![](./_static/concepts/querying.jpg)
+![](/_static/concepts/querying.jpg)
 
 #### Building Blocks
 

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

@@ -8,9 +8,10 @@ One of the most common use-cases for LlamaIndex is Retrieval-Augmented Generatio
 
 In a new folder, run:
 
-```bash npm2yarn
+```package-install
 npm init
 npm i -D typescript @types/node
+npm i llamaindex
 ```
 
 Then, check out the [installation](/docs/llamaindex/getting_started/installation) steps to install LlamaIndex.TS and prepare an OpenAI key.
@@ -34,7 +35,7 @@ Create a `tsconfig.json` file in the same folder:
 
 Now you can run the code with
 
-```bash
+```package-install
 npx tsx example.ts
 ```
 

apps/next/src/content/docs/llamaindex/tutorials/structured_data_extraction.mdx

@@ -10,9 +10,10 @@ You can use [other LLMs](/docs/llamaindex/modules/models/llms) via their APIs; i
 
 In a new folder:
 
-```bash npm2yarn
+```package-install
 npm init
 npm i -D typescript @types/node
+npm i @llamaindex/openai zod
 ```
 
 ## Extract data
@@ -27,7 +28,7 @@ Create the file `example.ts`. This code will:
 
 To run the code:
 
-```bash
+```package-install
 npx tsx example.ts
 ```
 

apps/next/src/content/docs/llamaindex/tutorials/workflows.mdx

@@ -0,0 +1,176 @@
+---
+title: Workflows
+---
+
+A `Workflow` in LlamaIndex is a lightweight, event-driven abstraction used to chain together several events. Workflows are made up of `handlers`, with each one responsible for processing specific event types and emitting new events.
+
+Workflows are designed to be flexible and can be used to build agents, RAG flows, extraction flows, or anything else you want to implement.
+
+```package-install
+npm i @llamaindex/workflow @llamaindex/openai
+```
+
+## Getting Started
+
+Let's explore a simple workflow example where a joke is generated and then critiqued and iterated on:
+
+<include cwd>../../examples/agents/workflow/joke.ts</include>
+
+There are a few moving pieces here, so let's go through this step by step.
+
+### Defining Workflow Events
+
+```typescript
+const startEvent = workflowEvent<string>(); // Input topic for joke
+const jokeEvent = workflowEvent<{ joke: string }>(); // Intermediate joke
+const critiqueEvent = workflowEvent<{ joke: string; critique: string }>(); // Intermediate critique
+const resultEvent = workflowEvent<{ joke: string; critique: string }>(); // Final joke + critique
+```
+
+Events are defined using the `workflowEvent` function and contain arbitrary data provided as a generic type. In this example, we have four events:
+- `startEvent`: Takes a string input (the joke topic)
+- `jokeEvent`: Contains an object with a joke property
+- `critiqueEvent`: Contains both the joke and its critique, used for the feedback loop
+- `resultEvent`: Contains the final joke and critique after any iterations
+
+### Setting up the Workflow with Stateful Middleware
+
+```typescript
+const { withState, getContext } = createStatefulMiddleware(() => ({
+  numIterations: 0,
+  maxIterations: 3,
+}));
+const jokeFlow = withState(createWorkflow());
+```
+
+Our workflow is implemented using the `createWorkflow()` function, enhanced with the `withState` middleware. This middleware provides shared state across all handlers, which in this case tracks:
+- `numIterations`: Counts how many iterations of joke improvement we've done
+- `maxIterations`: Sets a limit to prevent infinite loops
+
+This state will be accessible within workflows by using the `getContext().state` function.
+
+### Adding Handlers with Loops
+
+We have three key handlers in our workflow:
+
+1. The first handler processes the `startEvent`, generates an initial joke, and emits a `jokeEvent`:
+
+```typescript
+jokeFlow.handle([startEvent], async (event) => {
+  // Prompt the LLM to write a joke
+  const prompt = `Write your best joke about ${event.data}. Write the joke between <joke> and </joke> tags.`;
+  const response = await llm.complete({ prompt });
+ 
+  // Parse the joke from the response
+  const joke =
+    response.text.match(/<joke>([\s\S]*?)<\/joke>/)?.[1]?.trim() ??
+    response.text;
+  return jokeEvent.with({ joke: joke });
+});
+```
+
+2. The second handler handles the `jokeEvent`, critiques the joke, and either:
+   - Emits a `critiqueEvent` if the joke needs improvement
+   - Emits a `resultEvent` if the joke is good enough
+
+```typescript
+jokeFlow.handle([jokeEvent], async (event) => {
+  // Prompt the LLM to critique the joke
+  const prompt = `Give a thorough critique of the following joke. If the joke needs improvement, put "IMPROVE" somewhere in the critique: ${event.data.joke}`;
+  const response = await llm.complete({ prompt });
+ 
+  // If the critique includes "IMPROVE", keep iterating, else, return the result
+  if (response.text.includes("IMPROVE")) {
+    return critiqueEvent.with({
+      joke: event.data.joke,
+      critique: response.text,
+    });
+  }
+ 
+  return resultEvent.with({ joke: event.data.joke, critique: response.text });
+});
+```
+
+3. The third handler processes the `critiqueEvent`, generates an improved joke based on the critique, and either:
+   - Loops back to the joke evaluation (if under the iteration limit)
+   - Emits the final `resultEvent` (if iteration limit reached)
+
+```typescript
+jokeFlow.handle([critiqueEvent], async (event) => {
+  // Keep track of the number of iterations
+  const state = getContext().state;
+  state.numIterations++;
+ 
+  // Write a new joke based on the previous joke and critique
+  const prompt = `Write a new joke based on the following critique and the original joke. Write the joke between <joke> and </joke> tags.\n\nJoke: ${event.data.joke}\n\nCritique: ${event.data.critique}`;
+  const response = await llm.complete({ prompt });
+ 
+  // Parse the joke from the response
+  const joke =
+    response.text.match(/<joke>([\s\S]*?)<\/joke>/)?.[1]?.trim() ??
+    response.text;
+ 
+  // If we've done less than the max number of iterations, keep iterating
+  // else, return the result
+  if (state.numIterations < state.maxIterations) {
+    return jokeEvent.with({ joke: joke });
+  }
+ 
+  return resultEvent.with({ joke: joke, critique: event.data.critique });
+});
+```
+
+### Running the Workflow
+
+```typescript
+async function main() {
+  const { stream, sendEvent } = jokeFlow.createContext();
+  sendEvent(startEvent.with("pirates"));
+
+  let result: { joke: string, critique: string } | undefined;
+
+  for await (const event of stream) {
+    // console.log(event.data);  optionally log the event data
+    if (resultEvent.include(event)) {
+      result = event.data;
+      break; // Stop when we get the final result
+    }
+  }
+  
+  console.log(result);
+}
+```
+
+To run the workflow, we:
+1. Create a workflow context with `createContext()`
+2. Trigger the initial event with `sendEvent()`
+3. Listen to the event stream and process events as they arrive
+4. Use `include()` to check if an event is of a specific type
+5. Break the loop when we receive our final result
+
+### Using Stream Utilities
+
+The `stream` returned by `createContext` contains utility functions to make working with event streams easier:
+
+```typescript
+// Create a workflow context and send the initial event
+const { stream, sendEvent } = jokeFlow.createContext();
+sendEvent(startEvent.with("pirates"));
+
+// Collect all events until we get a resultEvent
+const allEvents = await stream.until(resultEvent).toArray(); 
+
+// The last event will be the resultEvent
+const finalEvent = allEvents.at(-1);
+console.log(finalEvent.data); // Output the joke and critique
+```
+
+The stream utilities make it easier to work with the asynchronous event flow. In this example, we use:
+- `toArray`: Aggregates all events into an array
+- `until`: Creates a stream that emits events until a condition is met (in this case, until a resultEvent is received)
+
+You can combine these utilities with other stream operators like `filter` and `map` to create powerful processing pipelines.
+
+## Next Steps
+
+To learn more about workflows, check out [the Workflows documentation](/docs/llamaindex/modules/agents/workflows).

apps/next/src/content/docs/meta.json

@@ -1,3 +1,3 @@
 {
-  "pages": ["llamaindex", "api"]
+  "pages": ["llamaindex", "api", "llamaflow"]
 }

e2e/examples/cloudflare-worker-agent/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @llamaindex/cloudflare-worker-agent-test
 
+## 0.0.160
+
+### Patch Changes
+
+- llamaindex@0.10.6
+
+## 0.0.159
+
+### Patch Changes
+
+- llamaindex@0.10.5
+
 ## 0.0.158
 
 ### Patch Changes

e2e/examples/cloudflare-worker-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/cloudflare-worker-agent-test",
-  "version": "0.0.158",
+  "version": "0.0.160",
   "type": "module",
   "private": true,
   "scripts": {

e2e/examples/llama-parse-browser/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @llamaindex/llama-parse-browser-test
 
+## 0.0.62
+
+### Patch Changes
+
+- Updated dependencies [40f5f41]
+  - @llamaindex/cloud@4.0.7
+
+## 0.0.61
+
+### Patch Changes
+
+- @llamaindex/cloud@4.0.6
+
 ## 0.0.60
 
 ### Patch Changes

e2e/examples/llama-parse-browser/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@llamaindex/llama-parse-browser-test",
   "private": true,
-  "version": "0.0.60",
+  "version": "0.0.62",
   "type": "module",
   "scripts": {
     "dev": "vite",

e2e/examples/nextjs-agent/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @llamaindex/next-agent-test
 
+## 0.1.160
+
+### Patch Changes
+
+- llamaindex@0.10.6
+
+## 0.1.159
+
+### Patch Changes
+
+- llamaindex@0.10.5
+
 ## 0.1.158
 
 ### Patch Changes

e2e/examples/nextjs-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/next-agent-test",
-  "version": "0.1.158",
+  "version": "0.1.160",
   "private": true,
   "scripts": {
     "dev": "next dev",

e2e/examples/nextjs-edge-runtime/CHANGELOG.md

@@ -1,5 +1,17 @@
 # test-edge-runtime
 
+## 0.1.159
+
+### Patch Changes
+
+- llamaindex@0.10.6
+
+## 0.1.158
+
+### Patch Changes
+
+- llamaindex@0.10.5
+
 ## 0.1.157
 
 ### Patch Changes

e2e/examples/nextjs-edge-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/nextjs-edge-runtime-test",
-  "version": "0.1.157",
+  "version": "0.1.159",
   "private": true,
   "scripts": {
     "dev": "next dev",

e2e/examples/nextjs-node-runtime/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @llamaindex/next-node-runtime
 
+## 0.1.27
+
+### Patch Changes
+
+- Updated dependencies [76c9a80]
+  - @llamaindex/huggingface@0.1.9
+  - llamaindex@0.10.6
+  - @llamaindex/readers@3.1.3
+
+## 0.1.26
+
+### Patch Changes
+
+- llamaindex@0.10.5
+- @llamaindex/huggingface@0.1.8
+- @llamaindex/readers@3.1.2
+
 ## 0.1.25
 
 ### Patch Changes

e2e/examples/nextjs-node-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/next-node-runtime-test",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "private": true,
   "scripts": {
     "dev": "next dev",

e2e/examples/vite-import-llamaindex/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vite-import-llamaindex
 
+## 0.0.26
+
+### Patch Changes
+
+- llamaindex@0.10.6
+
+## 0.0.25
+
+### Patch Changes
+
+- llamaindex@0.10.5
+
 ## 0.0.24
 
 ### Patch Changes

e2e/examples/vite-import-llamaindex/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vite-import-llamaindex",
   "private": true,
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "scripts": {
     "build": "vite build",

e2e/examples/vite-import-llamaindex/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/main.ts","./vite.config.ts"],"version":"5.7.3"}

e2e/examples/waku-query-engine/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @llamaindex/waku-query-engine-test
 
+## 0.0.160
+
+### Patch Changes
+
+- llamaindex@0.10.6
+
+## 0.0.159
+
+### Patch Changes
+
+- Updated dependencies [9b2e25a]
+  - @llamaindex/env@0.1.30
+  - llamaindex@0.10.5
+
 ## 0.0.158
 
 ### Patch Changes

e2e/examples/waku-query-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaindex/waku-query-engine-test",
-  "version": "0.0.158",
+  "version": "0.0.160",
   "type": "module",
   "private": true,
   "scripts": {

e2e/npm/.gitignore

@@ -0,0 +1 @@
+package-lock.json

e2e/npm/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "e2e-npm",
+  "private": true,
+  "scripts": {
+    "test": "node --import tsx --test test/*.e2e.ts"
+  },
+  "dependencies": {
+    "@llamaindex/workflow": "1.1.1",
+    "llamaindex": "0.10.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.1",
+    "@types/node": "^22.9.0"
+  }
+}

e2e/npm/test/workflow.e2e.ts

@@ -0,0 +1,28 @@
+import { agent } from "@llamaindex/workflow";
+import { OpenAI, Settings, tool } from "llamaindex";
+import { ok } from "node:assert";
+import { test } from "node:test";
+import { z } from "zod";
+
+Settings.llm = new OpenAI({ model: "gpt-4-0613" });
+
+test("creating agent from workflow package", async () => {
+  const calculatorAgent = agent({
+    tools: [
+      tool({
+        name: "add",
+        description: "Adds two numbers",
+        parameters: z.object({ x: z.number(), y: z.number() }),
+        execute: ({ x, y }) => x + y,
+      }),
+    ],
+  });
+  ok(calculatorAgent !== undefined, "calculatorAgent should be defined");
+
+  const agents = calculatorAgent.getAgents();
+  const currentLLM = agents?.[0].llm;
+  ok(
+    (currentLLM as OpenAI)?.model === (Settings.llm as OpenAI)?.model,
+    "Agent should use the same LLM model as setup in Settings instance",
+  );
+});

e2e/npm/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16",
+    "target": "ESNext",
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["test/**/*.ts"]
+}

examples/.gitignore

@@ -1,3 +1,2 @@
 package-lock.json
-storage
-tmp_data
+tmp_data

examples/CHANGELOG.md

@@ -1,5 +1,116 @@
 # examples
 
+## 0.3.15
+
+### Patch Changes
+
+- d671ed6: Add functionality for search params when querying Qdrant vector store.
+- Updated dependencies [7a7ca60]
+- Updated dependencies [7a7ca60]
+- Updated dependencies [76c9a80]
+- Updated dependencies [168d11f]
+- Updated dependencies [d671ed6]
+- Updated dependencies [40f5f41]
+  - @llamaindex/xai@0.0.2
+  - @llamaindex/fireworks@0.0.15
+  - @llamaindex/elastic-search@0.1.5
+  - @llamaindex/firestore@1.0.12
+  - @llamaindex/pinecone@0.1.5
+  - @llamaindex/postgres@0.0.48
+  - @llamaindex/supabase@0.1.4
+  - @llamaindex/weaviate@0.0.19
+  - @llamaindex/mongodb@0.0.20
+  - @llamaindex/upstash@0.0.19
+  - @llamaindex/chroma@0.0.19
+  - @llamaindex/milvus@0.1.14
+  - @llamaindex/qdrant@0.1.14
+  - @llamaindex/astra@0.0.19
+  - @llamaindex/azure@0.1.15
+  - @llamaindex/huggingface@0.1.9
+  - @llamaindex/assemblyai@0.1.4
+  - @llamaindex/mixedbread@0.0.19
+  - @llamaindex/perplexity@0.0.12
+  - @llamaindex/portkey-ai@0.0.47
+  - @llamaindex/anthropic@0.3.6
+  - @llamaindex/deepinfra@0.0.55
+  - @llamaindex/replicate@0.0.47
+  - @llamaindex/voyage-ai@1.0.11
+  - @llamaindex/discord@0.1.4
+  - @llamaindex/mistral@0.1.5
+  - @llamaindex/cohere@0.0.19
+  - @llamaindex/google@0.3.1
+  - @llamaindex/jinaai@0.0.15
+  - @llamaindex/notion@0.1.4
+  - @llamaindex/ollama@0.1.5
+  - @llamaindex/openai@0.3.7
+  - @llamaindex/vercel@0.1.5
+  - @llamaindex/clip@0.0.55
+  - @llamaindex/tools@0.0.10
+  - @llamaindex/workflow@1.1.2
+  - @llamaindex/core@0.6.5
+  - @llamaindex/cloud@4.0.7
+  - llamaindex@0.10.6
+  - @llamaindex/deepseek@0.0.15
+  - @llamaindex/groq@0.0.70
+  - @llamaindex/together@0.0.15
+  - @llamaindex/vllm@0.0.41
+  - @llamaindex/node-parser@2.0.5
+  - @llamaindex/readers@3.1.3
+
+## 0.3.14
+
+### Patch Changes
+
+- 9b2e25a: Use Uint8Array instead of Buffer for file type messages (works with non-NodeJS)
+- 206b491: Add support for google live api
+- Updated dependencies [9b2e25a]
+- Updated dependencies [206b491]
+  - @llamaindex/anthropic@0.3.5
+  - @llamaindex/google@0.3.0
+  - @llamaindex/openai@0.3.6
+  - @llamaindex/core@0.6.4
+  - @llamaindex/env@0.1.30
+  - llamaindex@0.10.5
+  - @llamaindex/clip@0.0.54
+  - @llamaindex/deepinfra@0.0.54
+  - @llamaindex/deepseek@0.0.14
+  - @llamaindex/fireworks@0.0.14
+  - @llamaindex/groq@0.0.69
+  - @llamaindex/huggingface@0.1.8
+  - @llamaindex/jinaai@0.0.14
+  - @llamaindex/perplexity@0.0.11
+  - @llamaindex/azure@0.1.14
+  - @llamaindex/elastic-search@0.1.4
+  - @llamaindex/milvus@0.1.13
+  - @llamaindex/qdrant@0.1.13
+  - @llamaindex/supabase@0.1.3
+  - @llamaindex/together@0.0.14
+  - @llamaindex/vllm@0.0.40
+  - @llamaindex/cloud@4.0.6
+  - @llamaindex/node-parser@2.0.4
+  - @llamaindex/assemblyai@0.1.3
+  - @llamaindex/cohere@0.0.18
+  - @llamaindex/discord@0.1.3
+  - @llamaindex/mistral@0.1.4
+  - @llamaindex/mixedbread@0.0.18
+  - @llamaindex/notion@0.1.3
+  - @llamaindex/ollama@0.1.4
+  - @llamaindex/portkey-ai@0.0.46
+  - @llamaindex/replicate@0.0.46
+  - @llamaindex/astra@0.0.18
+  - @llamaindex/chroma@0.0.18
+  - @llamaindex/firestore@1.0.11
+  - @llamaindex/mongodb@0.0.19
+  - @llamaindex/pinecone@0.1.4
+  - @llamaindex/postgres@0.0.47
+  - @llamaindex/upstash@0.0.18
+  - @llamaindex/weaviate@0.0.18
+  - @llamaindex/vercel@0.1.4
+  - @llamaindex/voyage-ai@1.0.10
+  - @llamaindex/readers@3.1.2
+  - @llamaindex/tools@0.0.9
+  - @llamaindex/workflow@1.1.1
+
 ## 0.3.13
 
 ### Patch Changes

examples/README.md

@@ -9,7 +9,7 @@ make sure you have basic knowledge of the [LlamaIndexTS](https://ts.llamaindex.a
 # export your API key
 export OPENAI_API_KEY="sk-..."
 
-npx tsx ./chatEngine.ts
+npx tsx ./rag/chatEngine.ts
 ```
 
 ## Build your own RAG app

examples/agents/agent/openai.ts

@@ -26,7 +26,7 @@ const divideNumbers = tool({
 async function main() {
   const mathAgent = agent({
     tools: [sumNumbers, divideNumbers],
-    llm: openai({ model: "gpt-4o-mini" }),
+    llm: openai({ model: "gpt-4.1-mini" }),
     verbose: false,
   });
 

examples/agents/agent/single-agent.ts

@@ -3,7 +3,7 @@
  */
 import { openai } from "@llamaindex/openai";
 import { agent } from "@llamaindex/workflow";
-import { getWeatherTool } from "../deprecated/utils/tools";
+import { getWeatherTool } from "../../deprecated/agents/utils/tools";
 
 async function main() {
   const weatherAgent = agent({

examples/agents/agent/with-ollama.ts

@@ -1,6 +1,6 @@
 import { ollama } from "@llamaindex/ollama";
 import { agent } from "@llamaindex/workflow";
-import { getWeatherTool } from "../deprecated/utils/tools";
+import { getWeatherTool } from "../../deprecated/agents/utils/tools";
 
 async function main() {
   const myAgent = agent({

examples/index/vectorIndexCustomize.ts

@@ -7,7 +7,7 @@ import {
   VectorStoreIndex,
 } from "llamaindex";
 
-import essay from "./essay";
+import essay from "../data/essay";
 
 // Update llm to use OpenAI
 Settings.llm = new OpenAI({ model: "gpt-3.5-turbo", temperature: 0.1 });

examples/longText.ts

@@ -1,20 +0,0 @@
-import {
-  Document,
-  SentenceSplitter,
-  Settings,
-  VectorStoreIndex,
-} from "llamaindex";
-
-export const STORAGE_DIR = "./data";
-
-// Update node parser
-Settings.nodeParser = new SentenceSplitter({
-  chunkSize: 512,
-  chunkOverlap: 20,
-});
-(async () => {
-  // generate a document with a very long sentence (9000 words long)
-  const longSentence = "is ".repeat(9000) + ".";
-  const document = new Document({ text: longSentence, id_: "1" });
-  await VectorStoreIndex.fromDocuments([document]);
-})();

examples/models/anthropic/chat-with-file.ts

@@ -25,7 +25,7 @@ async function main() {
           },
           {
             type: "file",
-            data: fs.readFileSync("./data/manga.pdf"),
+            data: Uint8Array.from(fs.readFileSync("./data/manga.pdf")),
             mimeType: "application/pdf",
           },
         ],

examples/models/gemini/chat.ts

@@ -32,7 +32,7 @@ import fs from "fs";
           },
           {
             type: "file",
-            data: fs.readFileSync("./data/manga.pdf"),
+            data: Uint8Array.from(fs.readFileSync("./data/manga.pdf")),
             mimeType: "application/pdf",
           },
         ],

examples/models/gemini/live/complex.ts

@@ -0,0 +1,160 @@
+import { fs } from "@llamaindex/env";
+import { gemini, GEMINI_MODEL, GeminiLiveSession } from "@llamaindex/google";
+import { liveEvents } from "llamaindex";
+
+import path from "path";
+import { saveWavFile } from "./util";
+
+async function main() {
+  const apiKey = process.env.GOOGLE_API_KEY;
+  if (!apiKey) {
+    console.error(
+      "Please set GOOGLE_API_KEY in your environment variables or .env file",
+    );
+    process.exit(1);
+  }
+
+  console.log("🚀 Initializing Gemini Live API example...");
+
+  const llm = gemini({
+    model: GEMINI_MODEL.GEMINI_2_0_FLASH_LIVE,
+    voiceName: "Zephyr",
+  });
+
+  console.log("📡 Connecting to Gemini Live session...");
+
+  const session = await llm.live.connect();
+
+  let isRunning = true;
+
+  const audioChunks: Buffer[] = [];
+  let audioResponse = false;
+
+  (async () => {
+    try {
+      console.log("🎧 Listening for events...");
+
+      for await (const event of session.streamEvents()) {
+        if (liveEvents.open.include(event)) {
+          console.log("✅ Connected to Gemini Live session");
+
+          console.log(
+            "💬 Sending text message: 'Say something about you for 10 seconds'",
+          );
+          session.sendMessage({
+            content: "Say something about you for 10 seconds",
+            role: "user",
+          });
+
+          setTimeout(() => {
+            sendPcmAudioFile(session);
+          }, 3000);
+        } else if (liveEvents.setupComplete.include(event)) {
+          console.log("✅ Setup complete");
+        } else if (liveEvents.text.include(event)) {
+          process.stdout.write(event.text);
+        } else if (liveEvents.audio.include(event)) {
+          console.log("\n🔊 Received audio chunk");
+          audioResponse = true;
+
+          try {
+            const chunk = Buffer.from(event.data as string, "base64");
+            audioChunks.push(chunk);
+            console.log(`Received audio chunk: ${chunk.length} bytes`);
+          } catch (error) {
+            console.error("❌ Error processing audio chunk:", error);
+          }
+        } else if (liveEvents.error.include(event)) {
+          console.error("❌ Error:", event.error);
+        } else if (liveEvents.close.include(event)) {
+          console.log("👋 Session closed");
+
+          if (audioResponse && audioChunks.length > 0) {
+            try {
+              await saveWavFile(audioChunks, "gemini-response.wav");
+            } catch (error) {
+              console.error("❌ Error saving final audio file:", error);
+            }
+          }
+
+          isRunning = false;
+          break;
+        }
+      }
+    } catch (error) {
+      console.error("❌ Error processing stream:", error);
+    }
+  })();
+
+  async function sendPcmAudioFile(session: GeminiLiveSession) {
+    try {
+      console.log("🎤 Reading PCM audio file...");
+
+      const filePath = path.join(__dirname, "hello_are_you_there.pcm");
+      console.log(`Reading file from: ${filePath}`);
+
+      const audioBuffer = await fs.readFile(filePath);
+
+      const base64Audio = audioBuffer.toString("base64");
+
+      session.sendMessage({
+        content: [
+          {
+            type: "audio",
+            data: base64Audio,
+            mimeType: "audio/pcm;rate=16000",
+          },
+        ],
+        role: "user",
+      });
+
+      console.log("🎤 PCM audio file sent! Waiting for response...");
+    } catch (error) {
+      console.error("❌ Error sending audio file:", error);
+    }
+  }
+
+  setTimeout(async () => {
+    console.log("\n⏱️ Time's up! Closing session...");
+
+    if (audioResponse && audioChunks.length > 0) {
+      try {
+        await saveWavFile(audioChunks, "gemini-response.wav");
+      } catch (error) {
+        console.error("❌ Error saving final audio file:", error);
+      }
+    }
+
+    await session.disconnect();
+    isRunning = false;
+  }, 60000);
+
+  process.on("SIGINT", async () => {
+    console.log("\n👋 Interrupted by user. Closing session...");
+
+    if (audioResponse && audioChunks.length > 0) {
+      try {
+        await saveWavFile(audioChunks, "gemini-response.wav");
+      } catch (error) {
+        console.error("❌ Error saving final audio file:", error);
+      }
+    }
+
+    await session.disconnect();
+    isRunning = false;
+  });
+
+  const waitForClose = () => {
+    if (isRunning) {
+      setTimeout(waitForClose, 1000);
+    } else {
+      process.exit(0);
+    }
+  };
+  waitForClose();
+}
+
+main().catch((error) => {
+  console.error("❌ Fatal error:", error);
+  process.exit(1);
+});

examples/models/gemini/live/simple.ts

@@ -0,0 +1,37 @@
+import { gemini, GEMINI_MODEL } from "@llamaindex/google";
+import { liveEvents } from "llamaindex";
+import { saveWavFile } from "./util";
+
+async function main() {
+  const llm = gemini({
+    model: GEMINI_MODEL.GEMINI_2_0_FLASH_LIVE,
+  });
+
+  const session = await llm.live.connect();
+  const audioChunks: Buffer[] = [];
+
+  setTimeout(async () => {
+    if (audioChunks.length > 0) {
+      await saveWavFile(audioChunks, "gemini-response.wav");
+    }
+    await session.disconnect();
+  }, 10000);
+
+  for await (const event of session.streamEvents()) {
+    if (liveEvents.open.include(event)) {
+      session.sendMessage({
+        content: "Say something about you for 10 seconds",
+        role: "user",
+      });
+    } else if (
+      liveEvents.audio.include(event) &&
+      typeof event.data === "string"
+    ) {
+      const chunk = Buffer.from(event.data, "base64");
+      audioChunks.push(chunk);
+      console.log(`Received audio chunk: ${chunk.length} bytes`);
+    }
+  }
+}
+
+main().catch(console.error);

examples/models/gemini/live/tool-call.ts

@@ -0,0 +1,104 @@
+import { ModalityType } from "@llamaindex/core/schema";
+import { tool } from "@llamaindex/core/tools";
+import { gemini, GEMINI_MODEL } from "@llamaindex/google";
+
+import { liveEvents } from "llamaindex";
+import { z } from "zod";
+
+const weatherTool = tool({
+  name: "weather",
+  description: "Get the weather",
+  parameters: z.object({
+    location: z.string({
+      description: "The location to get the weather for",
+    }),
+  }),
+  execute: ({ location }) => {
+    return `The weather in ${location} is rainy`;
+  },
+});
+
+const divideNumbers = tool({
+  name: "divideNumbers",
+  description: "Use this function to divide two numbers",
+  parameters: z.object({
+    a: z.number().describe("The dividend a to divide"),
+    b: z.number().describe("The divisor b to divide by"),
+  }),
+  execute: ({ a, b }) => `${a / b}`,
+});
+
+async function main() {
+  const apiKey = process.env.GOOGLE_API_KEY;
+  if (!apiKey) {
+    console.error(
+      "Please set GOOGLE_API_KEY in your environment variables or .env file",
+    );
+    process.exit(1);
+  }
+
+  console.log("🚀 Initializing Gemini Live API with tools example...");
+
+  const llm = gemini({
+    apiKey: apiKey,
+    model: GEMINI_MODEL.GEMINI_2_0_FLASH_LIVE, // Must use a live-compatible model
+  });
+
+  console.log("📡 Connecting to Gemini Live session...");
+
+  // Connect to a live session with tools
+  const session = await llm.live.connect({
+    // Specify response modalities (text response is required for tools)
+    responseModality: [ModalityType.TEXT],
+    // Register our tools with the session
+    tools: [weatherTool, divideNumbers],
+    // Optional system instruction
+    systemInstruction:
+      "You are a helpful assistant that can use tools. When answering questions about weather or divide numbers, always use the appropriate tool.",
+  });
+
+  (async () => {
+    console.log("🎧 Listening for events...");
+
+    for await (const event of session.streamEvents()) {
+      if (liveEvents.open.include(event)) {
+        console.log("✅ Connected to Gemini Live session");
+
+        console.log(
+          "💬 Sending message: 'What's the weather in San Francisco and what is 100 / 2?'",
+        );
+        session.sendMessage({
+          content: "What's the weather in San Francisco and what is 100 / 2?",
+          role: "user",
+        });
+      } else if (liveEvents.text.include(event)) {
+        process.stdout.write(event.text);
+      } else if (liveEvents.error.include(event)) {
+        console.error("❌ Error:", event.error);
+      } else if (liveEvents.close.include(event)) {
+        console.log("👋 Session closed");
+        process.exit(0);
+      } else if (liveEvents.setupComplete.include(event)) {
+        console.log("🔧 Setup complete");
+      }
+    }
+  })();
+
+  process.on("SIGINT", async () => {
+    console.log("\n👋 Interrupted by user. Closing session...");
+    await session.disconnect();
+    process.exit(0);
+  });
+
+  // Timeout after 2 minutes if no interaction
+  setTimeout(async () => {
+    console.log("\n⏱️ Session timeout. Closing session...");
+    await session.disconnect();
+    process.exit(0);
+  }, 120000);
+}
+
+main().catch((error) => {
+  console.error("❌ Fatal error:", error);
+  process.exit(1);
+});

examples/models/gemini/live/util.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+
+function createWavHeader(
+  sampleRate = 22050,
+  bitsPerSample = 16,
+  channels = 1,
+  dataLength: number,
+) {
+  const buffer = Buffer.alloc(44);
+
+  // RIFF chunk descriptor
+  buffer.write("RIFF", 0);
+  buffer.writeUInt32LE(36 + dataLength, 4); // File size - 8
+  buffer.write("WAVE", 8);
+
+  // fmt sub-chunk
+  buffer.write("fmt ", 12);
+  buffer.writeUInt32LE(16, 16); // Subchunk1Size (16 for PCM)
+  buffer.writeUInt16LE(1, 20); // AudioFormat (1 for PCM)
+  buffer.writeUInt16LE(channels, 22); // NumChannels
+  buffer.writeUInt32LE(sampleRate, 24); // SampleRate
+  buffer.writeUInt32LE((sampleRate * channels * bitsPerSample) / 8, 28); // ByteRate
+  buffer.writeUInt16LE((channels * bitsPerSample) / 8, 32); // BlockAlign
+  buffer.writeUInt16LE(bitsPerSample, 34); // BitsPerSample
+
+  // data sub-chunk
+  buffer.write("data", 36);
+  buffer.writeUInt32LE(dataLength, 40); // Subchunk2Size
+
+  return buffer;
+}
+
+export async function saveWavFile(
+  audioChunks: Buffer[],
+  filePath: string,
+  sampleRate = 22050,
+  bitsPerSample = 16,
+  channels = 1,
+): Promise<void> {
+  if (audioChunks.length === 0) {
+    throw new Error("No audio data to save");
+  }
+
+  try {
+    const combinedAudioData = Buffer.concat(audioChunks);
+    console.log(`Total audio data: ${combinedAudioData.length} bytes`);
+
+    const wavHeader = createWavHeader(
+      sampleRate,
+      bitsPerSample,
+      channels,
+      combinedAudioData.length,
+    );
+    const wavFile = Buffer.concat([wavHeader, combinedAudioData]);
+
+    await fs.writeFile(filePath, wavFile);
+    console.log(`💾 Saved audio to ${filePath}`);
+    return;
+  } catch (error) {
+    console.error("❌ Error saving audio file:", error);
+    throw error;
+  }
+}