Release 0.3.25 (#477)

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

.changeset/itchy-peas-obey.md

@@ -1,5 +0,0 @@
----
-"create-llama": patch
----
-
-feat: bump LITS 0.8.2

.changeset/light-parrots-work.md

@@ -1,5 +0,0 @@
----
-"create-llama": patch
----
-
-Optimize generated workflow code for Python

.changeset/nice-garlics-repeat.md

@@ -1,5 +0,0 @@
----
-"create-llama": patch
----
-
-feat: use llamaindex chat-ui for nextjs frontend

CHANGELOG.md

@@ -1,5 +1,120 @@
 # create-llama
 
+## 0.3.25
+
+### Patch Changes
+
+- 5450096: bump: react 19 stable
+
+## 0.3.24
+
+### Patch Changes
+
+- a84743c: Change --agents paramameter to --use-case
+- a84743c: Add LlamaCloud support for Reflex templates
+- a7a6592: Fix the npm issue on the full-stack Python template
+- fc5e56e: bump: code interpreter v1
+
+## 0.3.23
+
+### Patch Changes
+
+- 9077cae: Add contract review use case (Python)
+
+## 0.3.22
+
+### Patch Changes
+
+- 25667d4: Make OpenAPI spec usable by custom GPTs
+
+## 0.3.21
+
+### Patch Changes
+
+- 95227a7: Add query endpoint
+
+## 0.3.20
+
+### Patch Changes
+
+- 27d2499: Bump the LlamaCloud library and fix breaking changes (Python).
+
+## 0.3.19
+
+### Patch Changes
+
+- f9a057d: Add support multimodal indexes (e.g. from LlamaCloud)
+- aedd73d: bump: chat-ui
+
+## 0.3.18
+
+### Patch Changes
+
+- fe90a7e: chore: bump ai v4
+- 02b2473: Show streaming errors in Python, optimize system prompts for tool usage and set the weather tool as default for the Agentic RAG use case
+- 63e961e: Use auto_routed retriever mode for LlamaCloudIndex
+
+## 0.3.17
+
+### Patch Changes
+
+- 28c8808: Add fly.io deployment
+- 0a7dfcf: Generate NEXT_PUBLIC_CHAT_API for NextJS backend to specify alternative backend
+
+## 0.3.16
+
+### Patch Changes
+
+- 8b371d8: Set pydantic version to <2.10 to avoid incompatibility with llama-index.
+- 30fe269: Deactive duckduckgo tool for TS
+- 30fe269: Replace DuckDuckGo by Wikipedia tool for agentic template
+
+## 0.3.15
+
+### Patch Changes
+
+- fc5b266: Improve DX for Python template (use one deployment instead of two)
+- f8f97d2: Add support for python 3.13
+
+## 0.3.14
+
+### Patch Changes
+
+- 00f0b3a: fix: dont include user message in chat history
+- 4663dec: chore: bump react19 rc
+- 44b34fb: chore: update eslint 9, nextjs 15, react 19
+- 6925676: feat: use latest chat UI
+
+## 0.3.13
+
+### Patch Changes
+
+- 282eaa0: Ensure that the index and document store are created when uploading a file with no available index.
+
+## 0.3.12
+
+### Patch Changes
+
+- 6edea6a: Optimize generated workflow code for Python
+- 8431b78: Optimize Typescript multi-agent code
+- 8431b78: Add form filling use case (Typescript)
+
+## 0.3.11
+
+### Patch Changes
+
+- 2b8aaa8: Add support for local models via Hugging Face
+- b9570b2: Fix: use generic LLMAgent instead of OpenAIAgent (adds support for Gemini and Anthropic for Agentic RAG)
+- 1fe21f8: Fix the highlight.js issue with the Next.js static build
+- 00009ae: feat: import pdf css
+
+## 0.3.10
+
+### Patch Changes
+
+- 9172fed: feat: bump LITS 0.8.2
+- 78ccde7: feat: use llamaindex chat-ui for nextjs frontend
+
 ## 0.3.9
 
 ### Patch Changes

create-app.ts

@@ -7,17 +7,16 @@ import { getOnline } from "./helpers/is-online";
 import { isWriteable } from "./helpers/is-writeable";
 import { makeDir } from "./helpers/make-dir";
 
-import fs from "fs";
 import terminalLink from "terminal-link";
 import type { InstallTemplateArgs, TemplateObservability } from "./helpers";
 import { installTemplate } from "./helpers";
-import { writeDevcontainer } from "./helpers/devcontainer";
 import { templatesDir } from "./helpers/dir";
 import { toolsRequireConfig } from "./helpers/tools";
+import { configVSCode } from "./helpers/vscode";
 
 export type InstallAppArgs = Omit<
   InstallTemplateArgs,
-  "appName" | "root" | "isOnline" | "customApiPath"
+  "appName" | "root" | "isOnline" | "port"
 > & {
   appPath: string;
   frontend: boolean;
@@ -35,13 +34,12 @@ export async function createApp({
   communityProjectConfig,
   llamapack,
   vectorDb,
-  externalPort,
   postInstallAction,
   dataSources,
   tools,
   useLlamaParse,
   observability,
-  agents,
+  useCase,
 }: InstallAppArgs): Promise<void> {
   const root = path.resolve(appPath);
 
@@ -81,40 +79,30 @@ export async function createApp({
     communityProjectConfig,
     llamapack,
     vectorDb,
-    externalPort,
     postInstallAction,
     dataSources,
     tools,
     useLlamaParse,
     observability,
-    agents,
+    useCase,
   };
 
-  if (frontend) {
-    // install backend
-    const backendRoot = path.join(root, "backend");
-    await makeDir(backendRoot);
-    await installTemplate({ ...args, root: backendRoot, backend: true });
+  // Install backend
+  await installTemplate({ ...args, backend: true });
+
+  if (frontend && framework === "fastapi") {
     // install frontend
-    const frontendRoot = path.join(root, "frontend");
+    const frontendRoot = path.join(root, ".frontend");
     await makeDir(frontendRoot);
     await installTemplate({
       ...args,
       root: frontendRoot,
       framework: "nextjs",
-      customApiPath: `http://localhost:${externalPort ?? 8000}/api/chat`,
       backend: false,
     });
-    // copy readme for fullstack
-    await fs.promises.copyFile(
-      path.join(templatesDir, "README-fullstack.md"),
-      path.join(root, "README.md"),
-    );
-  } else {
-    await installTemplate({ ...args, backend: true });
   }
 
-  await writeDevcontainer(root, templatesDir, framework, frontend);
+  await configVSCode(root, templatesDir, framework);
 
   process.chdir(root);
   if (tryGitInit(root)) {

e2e/python/resolve_dependencies.spec.ts

@@ -63,7 +63,6 @@ if (
             vectorDb,
             tools: "none",
             port: 3000,
-            externalPort: 8000,
             postInstallAction: "none",
             templateUI: undefined,
             appType: "--no-frontend",
@@ -101,7 +100,6 @@ if (
             vectorDb: "none",
             tools: tool,
             port: 3000,
-            externalPort: 8000,
             postInstallAction: "none",
             templateUI: undefined,
             appType: "--no-frontend",
@@ -135,7 +133,6 @@ if (
             vectorDb: "none",
             tools: "none",
             port: 3000,
-            externalPort: 8000,
             postInstallAction: "none",
             templateUI: undefined,
             appType: "--no-frontend",
@@ -169,7 +166,6 @@ if (
             vectorDb: "none",
             tools: "none",
             port: 3000,
-            externalPort: 8000,
             postInstallAction: "none",
             templateUI: undefined,
             appType: "--no-frontend",

e2e/shared/extractor_template.spec.ts

@@ -1,63 +0,0 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
-import { expect, test } from "@playwright/test";
-import { ChildProcess } from "child_process";
-import fs from "fs";
-import path from "path";
-import { TemplateFramework } from "../../helpers";
-import { createTestDir, runCreateLlama } from "../utils";
-
-const templateFramework: TemplateFramework = process.env.FRAMEWORK
-  ? (process.env.FRAMEWORK as TemplateFramework)
-  : "fastapi";
-const dataSource: string = process.env.DATASOURCE
-  ? process.env.DATASOURCE
-  : "--example-file";
-
-// The extractor template currently only works with FastAPI and files (and not on Windows)
-if (
-  process.platform !== "win32" &&
-  templateFramework === "fastapi" &&
-  dataSource === "--example-file"
-) {
-  test.describe("Test extractor template", async () => {
-    let frontendPort: number;
-    let backendPort: number;
-    let name: string;
-    let appProcess: ChildProcess;
-    let cwd: string;
-
-    // Create extractor app
-    test.beforeAll(async () => {
-      cwd = await createTestDir();
-      frontendPort = Math.floor(Math.random() * 10000) + 10000;
-      backendPort = frontendPort + 1;
-      const result = await runCreateLlama({
-        cwd,
-        templateType: "extractor",
-        templateFramework: "fastapi",
-        dataSource: "--example-file",
-        vectorDb: "none",
-        port: frontendPort,
-        externalPort: backendPort,
-        postInstallAction: "runApp",
-      });
-      name = result.projectName;
-      appProcess = result.appProcess;
-    });
-
-    test.afterAll(async () => {
-      appProcess.kill();
-    });
-
-    test("App folder should exist", async () => {
-      const dirExists = fs.existsSync(path.join(cwd, name));
-      expect(dirExists).toBeTruthy();
-    });
-    test("Frontend should have a title", async ({ page }) => {
-      await page.goto(`http://localhost:${frontendPort}`);
-      await expect(page.getByText("Built by LlamaIndex")).toBeVisible({
-        timeout: 2000 * 60,
-      });
-    });
-  });
-}

e2e/shared/multiagent_template.spec.ts

@@ -16,22 +16,17 @@ const templateFramework: TemplateFramework = process.env.FRAMEWORK
 const dataSource: string = "--example-file";
 const templateUI: TemplateUI = "shadcn";
 const templatePostInstallAction: TemplatePostInstallAction = "runApp";
-const appType: AppType = templateFramework === "nextjs" ? "" : "--frontend";
+const appType: AppType = templateFramework === "fastapi" ? "--frontend" : "";
 const userMessage = "Write a blog post about physical standards for letters";
-const templateAgents = ["financial_report", "blog", "form_filling"];
+const templateUseCases = ["financial_report", "blog", "form_filling"];
 
-for (const agents of templateAgents) {
-  test.describe(`Test multiagent template ${agents} ${templateFramework} ${dataSource} ${templateUI} ${appType} ${templatePostInstallAction}`, async () => {
+for (const useCase of templateUseCases) {
+  test.describe(`Test multiagent template ${useCase} ${templateFramework} ${dataSource} ${templateUI} ${appType} ${templatePostInstallAction}`, async () => {
     test.skip(
       process.platform !== "linux" || process.env.DATASOURCE === "--no-files",
       "The multiagent template currently only works with files. We also only run on Linux to speed up tests.",
     );
-    test.skip(
-      agents === "form_filling" && templateFramework !== "fastapi",
-      "Form filling is currently only supported with FastAPI.",
-    );
     let port: number;
-    let externalPort: number;
     let cwd: string;
     let name: string;
     let appProcess: ChildProcess;
@@ -40,7 +35,6 @@ for (const agents of templateAgents) {
 
     test.beforeAll(async () => {
       port = Math.floor(Math.random() * 10000) + 10000;
-      externalPort = port + 1;
       cwd = await createTestDir();
       const result = await runCreateLlama({
         cwd,
@@ -49,11 +43,10 @@ for (const agents of templateAgents) {
         dataSource,
         vectorDb,
         port,
-        externalPort,
         postInstallAction: templatePostInstallAction,
         templateUI,
         appType,
-        agents,
+        useCase,
       });
       name = result.projectName;
       appProcess = result.appProcess;
@@ -65,6 +58,10 @@ for (const agents of templateAgents) {
     });
 
     test("Frontend should have a title", async ({ page }) => {
+      test.skip(
+        templatePostInstallAction !== "runApp" ||
+          templateFramework === "express",
+      );
       await page.goto(`http://localhost:${port}`);
       await expect(page.getByText("Built by LlamaIndex")).toBeVisible();
     });
@@ -73,7 +70,10 @@ for (const agents of templateAgents) {
       page,
     }) => {
       test.skip(
-        agents === "financial_report" || agents === "form_filling",
+        templatePostInstallAction !== "runApp" ||
+          useCase === "financial_report" ||
+          useCase === "form_filling" ||
+          templateFramework === "express",
         "Skip chat tests for financial report and form filling.",
       );
       await page.goto(`http://localhost:${port}`);

e2e/shared/reflex_template.spec.ts

@@ -0,0 +1,64 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+import { expect, test } from "@playwright/test";
+import { ChildProcess } from "child_process";
+import fs from "fs";
+import path from "path";
+import { TemplateFramework, TemplateUseCase } from "../../helpers";
+import { createTestDir, runCreateLlama } from "../utils";
+
+const templateFramework: TemplateFramework = process.env.FRAMEWORK
+  ? (process.env.FRAMEWORK as TemplateFramework)
+  : "fastapi";
+const dataSource: string = process.env.DATASOURCE
+  ? process.env.DATASOURCE
+  : "--example-file";
+const templateUseCases: TemplateUseCase[] = ["extractor", "contract_review"];
+
+// The reflex template currently only works with FastAPI and files (and not on Windows)
+if (
+  process.platform !== "win32" &&
+  templateFramework === "fastapi" &&
+  dataSource === "--example-file"
+) {
+  for (const useCase of templateUseCases) {
+    test.describe(`Test reflex template ${useCase} ${templateFramework} ${dataSource}`, async () => {
+      let appPort: number;
+      let name: string;
+      let appProcess: ChildProcess;
+      let cwd: string;
+
+      // Create reflex app
+      test.beforeAll(async () => {
+        cwd = await createTestDir();
+        appPort = Math.floor(Math.random() * 10000) + 10000;
+        const result = await runCreateLlama({
+          cwd,
+          templateType: "reflex",
+          templateFramework: "fastapi",
+          dataSource: "--example-file",
+          vectorDb: "none",
+          port: appPort,
+          postInstallAction: "runApp",
+          useCase,
+        });
+        name = result.projectName;
+        appProcess = result.appProcess;
+      });
+
+      test.afterAll(async () => {
+        appProcess.kill();
+      });
+
+      test("App folder should exist", async () => {
+        const dirExists = fs.existsSync(path.join(cwd, name));
+        expect(dirExists).toBeTruthy();
+      });
+      test("Frontend should have a title", async ({ page }) => {
+        await page.goto(`http://localhost:${appPort}`);
+        await expect(page.getByText("Built by LlamaIndex")).toBeVisible({
+          timeout: 2000 * 60,
+        });
+      });
+    });
+  }
+}

e2e/shared/streaming_template.spec.ts

@@ -22,7 +22,7 @@ const templatePostInstallAction: TemplatePostInstallAction = "runApp";
 const llamaCloudProjectName = "create-llama";
 const llamaCloudIndexName = "e2e-test";
 
-const appType: AppType = templateFramework === "nextjs" ? "" : "--frontend";
+const appType: AppType = templateFramework === "fastapi" ? "--frontend" : "";
 const userMessage =
   dataSource !== "--no-files" ? "Physical standard for letters" : "Hello";
 
@@ -35,7 +35,6 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
   }
 
   let port: number;
-  let externalPort: number;
   let cwd: string;
   let name: string;
   let appProcess: ChildProcess;
@@ -44,7 +43,6 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
 
   test.beforeAll(async () => {
     port = Math.floor(Math.random() * 10000) + 10000;
-    externalPort = port + 1;
     cwd = await createTestDir();
     const result = await runCreateLlama({
       cwd,
@@ -53,7 +51,6 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
       dataSource,
       vectorDb,
       port,
-      externalPort,
       postInstallAction: templatePostInstallAction,
       templateUI,
       appType,
@@ -68,8 +65,11 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
     const dirExists = fs.existsSync(path.join(cwd, name));
     expect(dirExists).toBeTruthy();
   });
+
   test("Frontend should have a title", async ({ page }) => {
-    test.skip(templatePostInstallAction !== "runApp");
+    test.skip(
+      templatePostInstallAction !== "runApp" || templateFramework === "express",
+    );
     await page.goto(`http://localhost:${port}`);
     await expect(page.getByText("Built by LlamaIndex")).toBeVisible();
   });
@@ -77,7 +77,9 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
   test("Frontend should be able to submit a message and receive a response", async ({
     page,
   }) => {
-    test.skip(templatePostInstallAction !== "runApp");
+    test.skip(
+      templatePostInstallAction !== "runApp" || templateFramework === "express",
+    );
     await page.goto(`http://localhost:${port}`);
     await page.fill("form textarea", userMessage);
     const [response] = await Promise.all([
@@ -102,7 +104,7 @@ test.describe(`Test streaming template ${templateFramework} ${dataSource} ${temp
     test.skip(templatePostInstallAction !== "runApp");
     test.skip(templateFramework === "nextjs");
     const response = await request.post(
-      `http://localhost:${externalPort}/api/chat/request`,
+      `http://localhost:${port}/api/chat/request`,
       {
         data: {
           messages: [

e2e/typescript/resolve_dependencies.spec.ts

@@ -56,7 +56,6 @@ test.describe("Test resolve TS dependencies", () => {
       dataSource: dataSource,
       vectorDb: vectorDb,
       port: 3000,
-      externalPort: 8000,
       postInstallAction: "none",
       templateUI: undefined,
       appType: templateFramework === "nextjs" ? "" : "--no-frontend",

e2e/utils.ts

@@ -25,7 +25,6 @@ export type RunCreateLlamaOptions = {
   dataSource: string;
   vectorDb: TemplateVectorDB;
   port: number;
-  externalPort: number;
   postInstallAction: TemplatePostInstallAction;
   templateUI?: TemplateUI;
   appType?: AppType;
@@ -34,7 +33,7 @@ export type RunCreateLlamaOptions = {
   tools?: string;
   useLlamaParse?: boolean;
   observability?: string;
-  agents?: string;
+  useCase?: string;
 };
 
 export async function runCreateLlama({
@@ -44,7 +43,6 @@ export async function runCreateLlama({
   dataSource,
   vectorDb,
   port,
-  externalPort,
   postInstallAction,
   templateUI,
   appType,
@@ -53,7 +51,7 @@ export async function runCreateLlama({
   tools,
   useLlamaParse,
   observability,
-  agents,
+  useCase,
 }: RunCreateLlamaOptions): Promise<CreateLlamaResult> {
   if (!process.env.OPENAI_API_KEY || !process.env.LLAMA_CLOUD_API_KEY) {
     throw new Error(
@@ -90,21 +88,15 @@ export async function runCreateLlama({
     ...dataSourceArgs,
     "--vector-db",
     vectorDb,
-    "--open-ai-key",
-    process.env.OPENAI_API_KEY,
-    "--use-pnpm",
+    "--use-npm",
     "--port",
     port,
-    "--external-port",
-    externalPort,
     "--post-install-action",
     postInstallAction,
     "--tools",
     tools ?? "none",
     "--observability",
     "none",
-    "--llama-cloud-key",
-    process.env.LLAMA_CLOUD_API_KEY,
   ];
 
   if (templateUI) {
@@ -121,8 +113,8 @@ export async function runCreateLlama({
   if (observability) {
     commandArgs.push("--observability", observability);
   }
-  if (templateType === "multiagent" && agents) {
-    commandArgs.push("--agents", agents);
+  if ((templateType === "multiagent" || templateType === "reflex") && useCase) {
+    commandArgs.push("--use-case", useCase);
   }
 
   const command = commandArgs.join(" ");
@@ -146,12 +138,7 @@ export async function runCreateLlama({
 
   // Wait for app to start
   if (postInstallAction === "runApp") {
-    await checkAppHasStarted(
-      appType === "--frontend",
-      templateFramework,
-      port,
-      externalPort,
-    );
+    await waitPorts([port]);
   } else if (postInstallAction === "dependencies") {
     await waitForProcess(appProcess, 1000 * 60); // wait 1 min for dependencies to be resolved
   } else {
@@ -171,19 +158,6 @@ export async function createTestDir() {
   return cwd;
 }
 
-// eslint-disable-next-line max-params
-async function checkAppHasStarted(
-  frontend: boolean,
-  framework: TemplateFramework,
-  port: number,
-  externalPort: number,
-) {
-  const portsToWait = frontend
-    ? [port, externalPort]
-    : [framework === "nextjs" ? port : externalPort];
-  await waitPorts(portsToWait);
-}
-
 async function waitPorts(ports: number[]): Promise<void> {
   const waitForPort = async (port: number): Promise<void> => {
     await waitPort({

helpers/copy.ts

@@ -61,6 +61,9 @@ export const assetRelocator = (name: string) => {
     case "README-template.md": {
       return "README.md";
     }
+    case "vscode_settings.json": {
+      return "settings.json";
+    }
     default: {
       return name;
     }

helpers/datasources.ts

@@ -18,6 +18,7 @@ export const EXAMPLE_10K_SEC_FILES: TemplateDataSource[] = [
       url: new URL(
         "https://s2.q4cdn.com/470004039/files/doc_earnings/2023/q4/filing/_10-K-Q4-2023-As-Filed.pdf",
       ),
+      filename: "apple_10k_report.pdf",
     },
   },
   {
@@ -26,10 +27,21 @@ export const EXAMPLE_10K_SEC_FILES: TemplateDataSource[] = [
       url: new URL(
         "https://ir.tesla.com/_flysystem/s3/sec/000162828024002390/tsla-20231231-gen.pdf",
       ),
+      filename: "tesla_10k_report.pdf",
     },
   },
 ];
 
+export const EXAMPLE_GDPR: TemplateDataSource = {
+  type: "file",
+  config: {
+    url: new URL(
+      "https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679",
+    ),
+    filename: "gdpr.pdf",
+  },
+};
+
 export function getDataSources(
   files?: string,
   exampleFile?: boolean,

helpers/env-variables.ts

@@ -13,6 +13,12 @@ import {
 
 import { TSYSTEMS_LLMHUB_API_URL } from "./providers/llmhub";
 
+const DEFAULT_SYSTEM_PROMPT =
+  "You are a helpful assistant who helps users with their questions.";
+
+const DATA_SOURCES_PROMPT =
+  "You have access to a knowledge base including the facts that you should start with to find the answer for the user question. Use the query engine tool to retrieve the facts from the knowledge base.";
+
 export type EnvVar = {
   name?: string;
   description?: string;
@@ -217,7 +223,13 @@ Otherwise, use CHROMA_HOST and CHROMA_PORT config above`,
         },
       ];
     default:
-      return [];
+      return [
+        {
+          name: "STORAGE_CACHE_DIR",
+          description: "The directory to store the local storage cache.",
+          value: ".cache",
+        },
+      ];
   }
 };
 
@@ -336,6 +348,20 @@ const getModelEnvs = (modelConfig: ModelConfig): EnvVar[] => {
           },
         ]
       : []),
+    ...(modelConfig.provider === "huggingface"
+      ? [
+          {
+            name: "EMBEDDING_BACKEND",
+            description:
+              "The backend to use for the Sentence Transformers embedding model, either 'torch', 'onnx', or 'openvino'. Defaults to 'onnx'.",
+          },
+          {
+            name: "EMBEDDING_TRUST_REMOTE_CODE",
+            description:
+              "Whether to trust remote code for the embedding model, required for some models with custom code.",
+          },
+        ]
+      : []),
     ...(modelConfig.provider === "t-systems"
       ? [
           {
@@ -387,6 +413,13 @@ const getFrameworkEnvs = (
       ],
     );
   }
+  if (framework === "nextjs") {
+    result.push({
+      name: "NEXT_PUBLIC_CHAT_API",
+      description:
+        "The API for the chat endpoint. Set when using a custom backend (e.g. Express). Use full URL like http://localhost:8000/api/chat",
+    });
+  }
   return result;
 };
 
@@ -422,9 +455,6 @@ const getSystemPromptEnv = (
   dataSources?: TemplateDataSource[],
   template?: TemplateType,
 ): EnvVar[] => {
-  const defaultSystemPrompt =
-    "You are a helpful assistant who helps users with their questions.";
-
   const systemPromptEnv: EnvVar[] = [];
   // build tool system prompt by merging all tool system prompts
   // multiagent template doesn't need system prompt
@@ -439,9 +469,12 @@ const getSystemPromptEnv = (
       }
     });
 
-    const systemPrompt = toolSystemPrompt
-      ? `\"${toolSystemPrompt}\"`
-      : defaultSystemPrompt;
+    const systemPrompt =
+      '"' +
+      DEFAULT_SYSTEM_PROMPT +
+      (dataSources?.length ? `\n${DATA_SOURCES_PROMPT}` : "") +
+      (toolSystemPrompt ? `\n${toolSystemPrompt}` : "") +
+      '"';
 
     systemPromptEnv.push({
       name: "SYSTEM_PROMPT",
@@ -492,7 +525,7 @@ Here is the conversation history
 ---------------------
 {conversation}
 ---------------------
-Given the conversation history, please give me 3 questions that you might ask next!
+Given the conversation history, please give me 3 questions that user might ask next!
 Your answer should be wrapped in three sticks which follows the following format:
 \`\`\`
 <question 1>
@@ -533,7 +566,7 @@ export const createBackendEnvFile = async (
     | "framework"
     | "dataSources"
     | "template"
-    | "externalPort"
+    | "port"
     | "tools"
     | "observability"
   >,
@@ -550,7 +583,7 @@ export const createBackendEnvFile = async (
     ...getModelEnvs(opts.modelConfig),
     ...getEngineEnvs(),
     ...getVectorDBEnvs(opts.vectorDb, opts.framework),
-    ...getFrameworkEnvs(opts.framework, opts.externalPort),
+    ...getFrameworkEnvs(opts.framework, opts.port),
     ...getToolEnvs(opts.tools),
     ...getTemplateEnvs(opts.template),
     ...getObservabilityEnvs(opts.observability),
@@ -565,18 +598,10 @@ export const createBackendEnvFile = async (
 export const createFrontendEnvFile = async (
   root: string,
   opts: {
-    customApiPath?: string;
     vectorDb?: TemplateVectorDB;
   },
 ) => {
   const defaultFrontendEnvs = [
-    {
-      name: "NEXT_PUBLIC_CHAT_API",
-      description: "The backend API for chat endpoint.",
-      value: opts.customApiPath
-        ? opts.customApiPath
-        : "http://localhost:8000/api/chat",
-    },
     {
       name: "NEXT_PUBLIC_USE_LLAMACLOUD",
       description: "Let's the user change indexes in LlamaCloud projects",

helpers/index.ts

@@ -118,7 +118,8 @@ const prepareContextData = async (
       const destPath = path.join(
         root,
         "data",
-        path.basename(dataSourceConfig.url.toString()),
+        dataSourceConfig.filename ??
+          path.basename(dataSourceConfig.url.toString()),
       );
       await downloadFile(dataSourceConfig.url.toString(), destPath);
     } else {
@@ -192,7 +193,7 @@ export const installTemplate = async (
     if (
       props.template === "streaming" ||
       props.template === "multiagent" ||
-      props.template === "extractor"
+      props.template === "reflex"
     ) {
       await createBackendEnvFile(props.root, props);
     }
@@ -225,7 +226,6 @@ export const installTemplate = async (
   } else {
     // this is a frontend for a full-stack app, create .env file with model information
     await createFrontendEnvFile(props.root, {
-      customApiPath: props.customApiPath,
       vectorDb: props.vectorDb,
     });
   }

helpers/providers/huggingface.ts

@@ -0,0 +1,68 @@
+import prompts from "prompts";
+import { ModelConfigParams } from ".";
+import { questionHandlers, toChoice } from "../../questions/utils";
+
+const MODELS = ["HuggingFaceH4/zephyr-7b-alpha"];
+type ModelData = {
+  dimensions: number;
+};
+const EMBEDDING_MODELS: Record<string, ModelData> = {
+  "BAAI/bge-small-en-v1.5": { dimensions: 384 },
+  "BAAI/bge-base-en-v1.5": { dimensions: 768 },
+  "BAAI/bge-large-en-v1.5": { dimensions: 1024 },
+  "sentence-transformers/all-MiniLM-L6-v2": { dimensions: 384 },
+  "sentence-transformers/all-mpnet-base-v2": { dimensions: 768 },
+  "intfloat/multilingual-e5-large": { dimensions: 1024 },
+  "mixedbread-ai/mxbai-embed-large-v1": { dimensions: 1024 },
+  "nomic-ai/nomic-embed-text-v1.5": { dimensions: 768 },
+};
+
+const DEFAULT_MODEL = MODELS[0];
+const DEFAULT_EMBEDDING_MODEL = Object.keys(EMBEDDING_MODELS)[0];
+const DEFAULT_DIMENSIONS = Object.values(EMBEDDING_MODELS)[0].dimensions;
+
+type HuggingfaceQuestionsParams = {
+  askModels: boolean;
+};
+
+export async function askHuggingfaceQuestions({
+  askModels,
+}: HuggingfaceQuestionsParams): Promise<ModelConfigParams> {
+  const config: ModelConfigParams = {
+    model: DEFAULT_MODEL,
+    embeddingModel: DEFAULT_EMBEDDING_MODEL,
+    dimensions: DEFAULT_DIMENSIONS,
+    isConfigured(): boolean {
+      return true;
+    },
+  };
+
+  if (askModels) {
+    const { model } = await prompts(
+      {
+        type: "select",
+        name: "model",
+        message: "Which Hugging Face model would you like to use?",
+        choices: MODELS.map(toChoice),
+        initial: 0,
+      },
+      questionHandlers,
+    );
+    config.model = model;
+
+    const { embeddingModel } = await prompts(
+      {
+        type: "select",
+        name: "embeddingModel",
+        message: "Which embedding model would you like to use?",
+        choices: Object.keys(EMBEDDING_MODELS).map(toChoice),
+        initial: 0,
+      },
+      questionHandlers,
+    );
+    config.embeddingModel = embeddingModel;
+    config.dimensions = EMBEDDING_MODELS[embeddingModel].dimensions;
+  }
+
+  return config;
+}

helpers/providers/index.ts

@@ -5,6 +5,7 @@ import { askAnthropicQuestions } from "./anthropic";
 import { askAzureQuestions } from "./azure";
 import { askGeminiQuestions } from "./gemini";
 import { askGroqQuestions } from "./groq";
+import { askHuggingfaceQuestions } from "./huggingface";
 import { askLLMHubQuestions } from "./llmhub";
 import { askMistralQuestions } from "./mistral";
 import { askOllamaQuestions } from "./ollama";
@@ -39,6 +40,7 @@ export async function askModelConfig({
 
     if (framework === "fastapi") {
       choices.push({ title: "T-Systems", value: "t-systems" });
+      choices.push({ title: "Huggingface", value: "huggingface" });
     }
     const { provider } = await prompts(
       {
@@ -76,6 +78,9 @@ export async function askModelConfig({
     case "t-systems":
       modelConfig = await askLLMHubQuestions({ askModels });
       break;
+    case "huggingface":
+      modelConfig = await askHuggingfaceQuestions({ askModels });
+      break;
     default:
       modelConfig = await askOpenAIQuestions({
         openAiKey,

helpers/providers/openai.ts

@@ -3,6 +3,7 @@ import ora from "ora";
 import { red } from "picocolors";
 import prompts from "prompts";
 import { ModelConfigParams, ModelConfigQuestionsParams } from ".";
+import { isCI } from "../../questions";
 import { questionHandlers } from "../../questions/utils";
 
 const OPENAI_API_URL = "https://api.openai.com/v1";
@@ -30,7 +31,7 @@ export async function askOpenAIQuestions({
     },
   };
 
-  if (!config.apiKey) {
+  if (!config.apiKey && !isCI) {
     const { key } = await prompts(
       {
         type: "text",

helpers/python.ts

@@ -20,6 +20,7 @@ interface Dependency {
   name: string;
   version?: string;
   extras?: string[];
+  constraints?: Record<string, string>;
 }
 
 const getAdditionalDependencies = (
@@ -36,28 +37,31 @@ const getAdditionalDependencies = (
     case "mongo": {
       dependencies.push({
         name: "llama-index-vector-stores-mongodb",
-        version: "^0.3.1",
+        version: "^0.6.0",
       });
       break;
     }
     case "pg": {
       dependencies.push({
         name: "llama-index-vector-stores-postgres",
-        version: "^0.2.5",
+        version: "^0.3.2",
       });
       break;
     }
     case "pinecone": {
       dependencies.push({
         name: "llama-index-vector-stores-pinecone",
-        version: "^0.2.1",
+        version: "^0.4.1",
+        constraints: {
+          python: ">=3.11,<3.13",
+        },
       });
       break;
     }
     case "milvus": {
       dependencies.push({
         name: "llama-index-vector-stores-milvus",
-        version: "^0.2.0",
+        version: "^0.3.0",
       });
       dependencies.push({
         name: "pymilvus",
@@ -68,35 +72,38 @@ const getAdditionalDependencies = (
     case "astra": {
       dependencies.push({
         name: "llama-index-vector-stores-astra-db",
-        version: "^0.2.0",
+        version: "^0.4.0",
       });
       break;
     }
     case "qdrant": {
       dependencies.push({
         name: "llama-index-vector-stores-qdrant",
-        version: "^0.3.0",
+        version: "^0.4.0",
+        constraints: {
+          python: ">=3.11,<3.13",
+        },
       });
       break;
     }
     case "chroma": {
       dependencies.push({
         name: "llama-index-vector-stores-chroma",
-        version: "^0.2.0",
+        version: "^0.4.0",
       });
       break;
     }
     case "weaviate": {
       dependencies.push({
         name: "llama-index-vector-stores-weaviate",
-        version: "^1.1.1",
+        version: "^1.2.3",
       });
       break;
     }
     case "llamacloud":
       dependencies.push({
         name: "llama-index-indices-managed-llama-cloud",
-        version: "^0.3.1",
+        version: "^0.6.3",
       });
       break;
   }
@@ -115,13 +122,13 @@ const getAdditionalDependencies = (
         case "web":
           dependencies.push({
             name: "llama-index-readers-web",
-            version: "^0.2.2",
+            version: "^0.3.0",
           });
           break;
         case "db":
           dependencies.push({
             name: "llama-index-readers-database",
-            version: "^0.2.0",
+            version: "^0.3.0",
           });
           dependencies.push({
             name: "pymysql",
@@ -160,15 +167,15 @@ const getAdditionalDependencies = (
       if (templateType !== "multiagent") {
         dependencies.push({
           name: "llama-index-llms-openai",
-          version: "^0.2.0",
+          version: "^0.3.2",
         });
         dependencies.push({
           name: "llama-index-embeddings-openai",
-          version: "^0.2.3",
+          version: "^0.3.1",
         });
         dependencies.push({
           name: "llama-index-agent-openai",
-          version: "^0.3.0",
+          version: "^0.4.0",
         });
       }
       break;
@@ -234,6 +241,21 @@ const getAdditionalDependencies = (
         version: "0.2.4",
       });
       break;
+    case "huggingface":
+      dependencies.push({
+        name: "llama-index-llms-huggingface",
+        version: "^0.3.5",
+      });
+      dependencies.push({
+        name: "llama-index-embeddings-huggingface",
+        version: "^0.3.1",
+      });
+      dependencies.push({
+        name: "optimum",
+        version: "^1.23.3",
+        extras: ["onnxruntime"],
+      });
+      break;
     case "t-systems":
       dependencies.push({
         name: "llama-index-agent-openai",
@@ -264,14 +286,19 @@ const mergePoetryDependencies = (
     value.version = dependency.version ?? value.version;
     value.extras = dependency.extras ?? value.extras;
 
+    // Merge constraints if they exist
+    if (dependency.constraints) {
+      value = { ...value, ...dependency.constraints };
+    }
+
     if (value.version === undefined) {
       throw new Error(
         `Dependency "${dependency.name}" is missing attribute "version"!`,
       );
     }
 
-    // Serialize separately only if extras are provided
-    if (value.extras && value.extras.length > 0) {
+    // Serialize as object if there are any additional properties
+    if (Object.keys(value).length > 1) {
       existingDependencies[dependency.name] = value;
     } else {
       // Otherwise, serialize just the version string
@@ -353,33 +380,37 @@ export const installPythonDependencies = (
 };
 
 export const installPythonTemplate = async ({
+  appName,
   root,
   template,
   framework,
   vectorDb,
+  postInstallAction,
+  modelConfig,
   dataSources,
   tools,
-  postInstallAction,
+  useLlamaParse,
+  useCase,
   observability,
-  modelConfig,
-  agents,
 }: Pick<
   InstallTemplateArgs,
+  | "appName"
   | "root"
-  | "framework"
   | "template"
+  | "framework"
   | "vectorDb"
+  | "postInstallAction"
+  | "modelConfig"
   | "dataSources"
   | "tools"
-  | "postInstallAction"
+  | "useLlamaParse"
+  | "useCase"
   | "observability"
-  | "modelConfig"
-  | "agents"
 >) => {
   console.log("\nInitializing Python project with template:", template, "\n");
   let templatePath;
-  if (template === "extractor") {
-    templatePath = path.join(templatesDir, "types", "extractor", framework);
+  if (template === "reflex") {
+    templatePath = path.join(templatesDir, "types", "reflex");
   } else {
     templatePath = path.join(templatesDir, "types", "streaming", framework);
   }
@@ -445,35 +476,30 @@ export const installPythonTemplate = async ({
       cwd: path.join(compPath, "engines", "python", engine),
     });
 
-    // Copy agent code
-    if (template === "multiagent") {
-      if (agents) {
-        await copy("**", path.join(root), {
-          parents: true,
-          cwd: path.join(compPath, "agents", "python", agents),
-          rename: assetRelocator,
-        });
-      } else {
-        console.log(
-          red(
-            "There is no agent selected for multi-agent template. Please pick an agent to use via --agents flag.",
-          ),
-        );
-        process.exit(1);
-      }
-    }
-
     // Copy router code
     await copyRouterCode(root, tools ?? []);
   }
 
-  if (template === "multiagent") {
-    // Copy multi-agent code
-    await copy("**", path.join(root), {
-      parents: true,
-      cwd: path.join(compPath, "multiagent", "python"),
-      rename: assetRelocator,
-    });
+  if (template === "multiagent" || template === "reflex") {
+    if (useCase) {
+      const sourcePath =
+        template === "multiagent"
+          ? path.join(compPath, "agents", "python", useCase)
+          : path.join(compPath, "reflex", useCase);
+
+      await copy("**", path.join(root), {
+        parents: true,
+        cwd: sourcePath,
+        rename: assetRelocator,
+      });
+    } else {
+      console.log(
+        red(
+          `There is no use case selected for ${template} template. Please pick a use case to use via --use-case flag.`,
+        ),
+      );
+      process.exit(1);
+    }
   }
 
   console.log("Adding additional dependencies");
@@ -497,7 +523,10 @@ export const installPythonTemplate = async ({
     if (observability === "llamatrace") {
       addOnDependencies.push({
         name: "llama-index-callbacks-arize-phoenix",
-        version: "^0.2.1",
+        version: "^0.3.0",
+        constraints: {
+          python: ">=3.11,<3.13",
+        },
       });
     }
 
@@ -518,9 +547,4 @@ export const installPythonTemplate = async ({
   if (postInstallAction === "runApp" || postInstallAction === "dependencies") {
     installPythonDependencies();
   }
-
-  // Copy deployment files for python
-  await copy("**", root, {
-    cwd: path.join(compPath, "deployments", "python"),
-  });
 };

helpers/run-app.ts

@@ -1,40 +1,39 @@
-import { ChildProcess, SpawnOptions, spawn } from "child_process";
-import path from "path";
-import { TemplateFramework } from "./types";
+import { SpawnOptions, spawn } from "child_process";
+import { TemplateFramework, TemplateType } from "./types";
 
 const createProcess = (
   command: string,
   args: string[],
   options: SpawnOptions,
-) => {
-  return spawn(command, args, {
-    ...options,
-    shell: true,
-  })
-    .on("exit", function (code) {
-      if (code !== 0) {
-        console.log(`Child process exited with code=${code}`);
-        process.exit(1);
-      }
+): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    spawn(command, args, {
+      ...options,
+      shell: true,
     })
-    .on("error", function (err) {
-      console.log("Error when running chill process: ", err);
-      process.exit(1);
-    });
+      .on("exit", function (code) {
+        if (code !== 0) {
+          console.log(`Child process exited with code=${code}`);
+          reject(code);
+        } else {
+          resolve();
+        }
+      })
+      .on("error", function (err) {
+        console.log("Error when running child process: ", err);
+        reject(err);
+      });
+  });
 };
 
-export function runReflexApp(
-  appPath: string,
-  frontendPort?: number,
-  backendPort?: number,
-) {
-  const commandArgs = ["run", "reflex", "run"];
-  if (frontendPort) {
-    commandArgs.push("--frontend-port", frontendPort.toString());
-  }
-  if (backendPort) {
-    commandArgs.push("--backend-port", backendPort.toString());
-  }
+export function runReflexApp(appPath: string, port: number) {
+  const commandArgs = [
+    "run",
+    "reflex",
+    "run",
+    "--frontend-port",
+    port.toString(),
+  ];
   return createProcess("poetry", commandArgs, {
     stdio: "inherit",
     cwd: appPath,
@@ -42,11 +41,10 @@ export function runReflexApp(
 }
 
 export function runFastAPIApp(appPath: string, port: number) {
-  const commandArgs = ["run", "uvicorn", "main:app", "--port=" + port];
-
-  return createProcess("poetry", commandArgs, {
+  return createProcess("poetry", ["run", "dev"], {
     stdio: "inherit",
     cwd: appPath,
+    env: { ...process.env, APP_PORT: `${port}` },
   });
 }
 
@@ -60,40 +58,24 @@ export function runTSApp(appPath: string, port: number) {
 
 export async function runApp(
   appPath: string,
-  template: string,
-  frontend: boolean,
+  template: TemplateType,
   framework: TemplateFramework,
   port?: number,
-  externalPort?: number,
-): Promise<any> {
-  const processes: ChildProcess[] = [];
+): Promise<void> {
+  try {
+    // Start the app
+    const defaultPort =
+      framework === "nextjs" || template === "reflex" ? 3000 : 8000;
 
-  // Callback to kill all sub processes if the main process is killed
-  process.on("exit", () => {
-    console.log("Killing app processes...");
-    processes.forEach((p) => p.kill());
-  });
-
-  // Default sub app paths
-  const backendPath = path.join(appPath, "backend");
-  const frontendPath = path.join(appPath, "frontend");
-
-  if (template === "extractor") {
-    processes.push(runReflexApp(appPath, port, externalPort));
+    const appRunner =
+      template === "reflex"
+        ? runReflexApp
+        : framework === "fastapi"
+          ? runFastAPIApp
+          : runTSApp;
+    await appRunner(appPath, port || defaultPort);
+  } catch (error) {
+    console.error("Failed to run app:", error);
+    throw error;
   }
-  if (template === "streaming" || template === "multiagent") {
-    if (framework === "fastapi" || framework === "express") {
-      const backendRunner = framework === "fastapi" ? runFastAPIApp : runTSApp;
-      if (frontend) {
-        processes.push(backendRunner(backendPath, externalPort || 8000));
-        processes.push(runTSApp(frontendPath, port || 3000));
-      } else {
-        processes.push(backendRunner(appPath, externalPort || 8000));
-      }
-    } else if (framework === "nextjs") {
-      processes.push(runTSApp(appPath, port || 3000));
-    }
-  }
-
-  return Promise.all(processes);
 }

helpers/tools.ts

@@ -41,7 +41,7 @@ export const supportedTools: Tool[] = [
     dependencies: [
       {
         name: "llama-index-tools-google",
-        version: "^0.2.0",
+        version: "^0.3.0",
       },
     ],
     supportedFrameworks: ["fastapi"],
@@ -62,17 +62,16 @@ export const supportedTools: Tool[] = [
     dependencies: [
       {
         name: "duckduckgo-search",
-        version: "6.1.7",
+        version: "^6.3.5",
       },
     ],
-    supportedFrameworks: ["fastapi", "nextjs", "express"],
+    supportedFrameworks: ["fastapi"], // TODO: Re-enable this tool once the duck-duck-scrape TypeScript library works again
     type: ToolType.LOCAL,
     envVars: [
       {
         name: TOOL_SYSTEM_PROMPT_ENV_VAR,
         description: "System prompt for DuckDuckGo search tool.",
-        value: `You are a DuckDuckGo search agent. 
-You can use the duckduckgo search tool to get information from the web to answer user questions.
+        value: `You have access to the duckduckgo search tool. Use it to get information from the web to answer user questions.
 For better results, you can specify the region parameter to get results from a specific region but it's optional.`,
       },
     ],
@@ -83,18 +82,11 @@ For better results, you can specify the region parameter to get results from a s
     dependencies: [
       {
         name: "llama-index-tools-wikipedia",
-        version: "^0.2.0",
+        version: "^0.3.0",
       },
     ],
     supportedFrameworks: ["fastapi", "express", "nextjs"],
     type: ToolType.LLAMAHUB,
-    envVars: [
-      {
-        name: TOOL_SYSTEM_PROMPT_ENV_VAR,
-        description: "System prompt for wiki tool.",
-        value: `You are a Wikipedia agent. You help users to get information from Wikipedia.`,
-      },
-    ],
   },
   {
     display: "Weather",
@@ -102,13 +94,6 @@ For better results, you can specify the region parameter to get results from a s
     dependencies: [],
     supportedFrameworks: ["fastapi", "express", "nextjs"],
     type: ToolType.LOCAL,
-    envVars: [
-      {
-        name: TOOL_SYSTEM_PROMPT_ENV_VAR,
-        description: "System prompt for weather tool.",
-        value: `You are a weather forecast agent. You help users to get the weather forecast for a given location.`,
-      },
-    ],
   },
   {
     display: "Document generator",
@@ -139,7 +124,7 @@ For better results, you can specify the region parameter to get results from a s
     dependencies: [
       {
         name: "e2b_code_interpreter",
-        version: "0.0.11b38",
+        version: "1.0.3",
       },
     ],
     supportedFrameworks: ["fastapi", "express", "nextjs"],
@@ -170,7 +155,7 @@ For better results, you can specify the region parameter to get results from a s
     dependencies: [
       {
         name: "e2b_code_interpreter",
-        version: "0.0.11b38",
+        version: "1.0.3",
       },
     ],
     supportedFrameworks: ["fastapi", "express", "nextjs"],
@@ -211,14 +196,6 @@ For better results, you can specify the region parameter to get results from a s
     },
     supportedFrameworks: ["fastapi", "express", "nextjs"],
     type: ToolType.LOCAL,
-    envVars: [
-      {
-        name: TOOL_SYSTEM_PROMPT_ENV_VAR,
-        description: "System prompt for openapi action tool.",
-        value:
-          "You are an OpenAPI action agent. You help users to make requests to the provided OpenAPI schema.",
-      },
-    ],
   },
   {
     display: "Image Generator",
@@ -231,11 +208,6 @@ For better results, you can specify the region parameter to get results from a s
         description:
           "STABILITY_API_KEY key is required to run image generator. Get it here: https://platform.stability.ai/account/keys",
       },
-      {
-        name: TOOL_SYSTEM_PROMPT_ENV_VAR,
-        description: "System prompt for image generator tool.",
-        value: `You are an image generator agent. You help users to generate images using the Stability API.`,
-      },
     ],
   },
   {

helpers/types.ts

@@ -9,6 +9,7 @@ export type ModelProvider =
   | "gemini"
   | "mistral"
   | "azure-openai"
+  | "huggingface"
   | "t-systems";
 export type ModelConfig = {
   provider: ModelProvider;
@@ -19,11 +20,11 @@ export type ModelConfig = {
   isConfigured(): boolean;
 };
 export type TemplateType =
-  | "extractor"
   | "streaming"
   | "community"
   | "llamapack"
-  | "multiagent";
+  | "multiagent"
+  | "reflex";
 export type TemplateFramework = "nextjs" | "express" | "fastapi";
 export type TemplateUI = "html" | "shadcn";
 export type TemplateVectorDB =
@@ -48,14 +49,21 @@ export type TemplateDataSource = {
 };
 export type TemplateDataSourceType = "file" | "web" | "db";
 export type TemplateObservability = "none" | "traceloop" | "llamatrace";
-export type TemplateAgents = "financial_report" | "blog" | "form_filling";
+export type TemplateUseCase =
+  | "financial_report"
+  | "blog"
+  | "form_filling"
+  | "extractor"
+  | "contract_review";
 // Config for both file and folder
 export type FileSourceConfig =
   | {
       path: string;
+      filename?: string;
     }
   | {
       url: URL;
+      filename?: string;
     };
 export type WebSourceConfig = {
   baseUrl?: string;
@@ -88,16 +96,15 @@ export interface InstallTemplateArgs {
   framework: TemplateFramework;
   ui: TemplateUI;
   dataSources: TemplateDataSource[];
-  customApiPath?: string;
   modelConfig: ModelConfig;
   llamaCloudKey?: string;
   useLlamaParse?: boolean;
   communityProjectConfig?: CommunityProjectConfig;
   llamapack?: string;
   vectorDb?: TemplateVectorDB;
-  externalPort?: number;
+  port?: number;
   postInstallAction?: TemplatePostInstallAction;
   tools?: Tool[];
   observability?: TemplateObservability;
-  agents?: TemplateAgents;
+  useCase?: TemplateUseCase;
 }

helpers/typescript.ts

@@ -26,7 +26,7 @@ export const installTSTemplate = async ({
   tools,
   dataSources,
   useLlamaParse,
-  agents,
+  useCase,
 }: InstallTemplateArgs & { backend: boolean }) => {
   console.log(bold(`Using ${packageManager}.`));
 
@@ -58,11 +58,9 @@ export const installTSTemplate = async ({
       console.log("\nUsing static site generation\n");
     } else {
       if (vectorDb === "milvus") {
-        nextConfigJson.experimental.serverComponentsExternalPackages =
-          nextConfigJson.experimental.serverComponentsExternalPackages ?? [];
-        nextConfigJson.experimental.serverComponentsExternalPackages.push(
-          "@zilliz/milvus2-sdk-node",
-        );
+        nextConfigJson.serverExternalPackages =
+          nextConfigJson.serverExternalPackages ?? [];
+        nextConfigJson.serverExternalPackages.push("@zilliz/milvus2-sdk-node");
       }
     }
     await fs.writeFile(
@@ -133,26 +131,29 @@ export const installTSTemplate = async ({
       cwd: path.join(multiagentPath, "workflow"),
     });
 
-    // Copy agents use case code for multiagent template
-    if (agents) {
-      console.log("\nCopying agent:", agents, "\n");
-
-      const agentsCodePath = path.join(
-        compPath,
-        "agents",
-        "typescript",
-        agents,
-      );
+    // Copy use case code for multiagent template
+    if (useCase) {
+      console.log("\nCopying use case:", useCase, "\n");
+      const useCasePath = path.join(compPath, "agents", "typescript", useCase);
+      const useCaseCodePath = path.join(useCasePath, "workflow");
 
+      // Copy use case codes
       await copy("**", path.join(root, relativeEngineDestPath, "workflow"), {
         parents: true,
-        cwd: agentsCodePath,
+        cwd: useCaseCodePath,
+        rename: assetRelocator,
+      });
+
+      // Copy use case files to project root
+      await copy("*.*", path.join(root), {
+        parents: true,
+        cwd: useCasePath,
         rename: assetRelocator,
       });
     } else {
       console.log(
         red(
-          "There is no agent selected for multi-agent template. Please pick an agent to use via --agents flag.",
+          `There is no use case selected for ${template} template. Please pick a use case to use via --use-case flag.`,
         ),
       );
       process.exit(1);
@@ -240,14 +241,12 @@ export const installTSTemplate = async ({
     vectorDb,
   });
 
-  if (postInstallAction === "runApp" || postInstallAction === "dependencies") {
+  if (
+    backend &&
+    (postInstallAction === "runApp" || postInstallAction === "dependencies")
+  ) {
     await installTSDependencies(packageJson, packageManager, isOnline);
   }
-
-  // Copy deployment files for typescript
-  await copy("**", root, {
-    cwd: path.join(compPath, "deployments", "typescript"),
-  });
 };
 
 async function updatePackageJson({

helpers/vscode.ts

@@ -1,40 +1,26 @@
 import fs from "fs";
 import path from "path";
+import { assetRelocator, copy } from "./copy";
 import { TemplateFramework } from "./types";
 
 function renderDevcontainerContent(
   templatesDir: string,
   framework: TemplateFramework,
-  frontend: boolean,
 ) {
   const devcontainerJson: any = JSON.parse(
     fs.readFileSync(path.join(templatesDir, "devcontainer.json"), "utf8"),
   );
 
   // Modify postCreateCommand
-  if (frontend) {
-    devcontainerJson.postCreateCommand =
-      framework === "fastapi"
-        ? "cd backend && poetry install && cd ../frontend && npm install"
-        : "cd backend && npm install && cd ../frontend && npm install";
-  } else {
-    devcontainerJson.postCreateCommand =
-      framework === "fastapi" ? "poetry install" : "npm install";
-  }
+  devcontainerJson.postCreateCommand =
+    framework === "fastapi" ? "poetry install" : "npm install";
 
   // Modify containerEnv
   if (framework === "fastapi") {
-    if (frontend) {
-      devcontainerJson.containerEnv = {
-        ...devcontainerJson.containerEnv,
-        PYTHONPATH: "${PYTHONPATH}:${workspaceFolder}/backend",
-      };
-    } else {
-      devcontainerJson.containerEnv = {
-        ...devcontainerJson.containerEnv,
-        PYTHONPATH: "${PYTHONPATH}:${workspaceFolder}",
-      };
-    }
+    devcontainerJson.containerEnv = {
+      ...devcontainerJson.containerEnv,
+      PYTHONPATH: "${PYTHONPATH}:${workspaceFolder}",
+    };
   }
 
   return JSON.stringify(devcontainerJson, null, 2);
@@ -44,7 +30,6 @@ export const writeDevcontainer = async (
   root: string,
   templatesDir: string,
   framework: TemplateFramework,
-  frontend: boolean,
 ) => {
   const devcontainerDir = path.join(root, ".devcontainer");
   if (fs.existsSync(devcontainerDir)) {
@@ -54,7 +39,6 @@ export const writeDevcontainer = async (
   const devcontainerContent = renderDevcontainerContent(
     templatesDir,
     framework,
-    frontend,
   );
   fs.mkdirSync(devcontainerDir);
   await fs.promises.writeFile(
@@ -62,3 +46,25 @@ export const writeDevcontainer = async (
     devcontainerContent,
   );
 };
+
+export const copyVSCodeSettings = async (
+  root: string,
+  templatesDir: string,
+) => {
+  const vscodeDir = path.join(root, ".vscode");
+  await copy("vscode_settings.json", vscodeDir, {
+    cwd: templatesDir,
+    rename: assetRelocator,
+  });
+};
+
+export const configVSCode = async (
+  root: string,
+  templatesDir: string,
+  framework: TemplateFramework,
+) => {
+  await writeDevcontainer(root, templatesDir, framework);
+  if (framework === "fastapi") {
+    await copyVSCodeSettings(root, templatesDir);
+  }
+};

index.ts

@@ -134,13 +134,6 @@ const program = new Command(packageJson.name)
     `
 
   Select UI port.
-`,
-  )
-  .option(
-    "--external-port <external>",
-    `
-
-  Select external port.
 `,
   )
   .option(
@@ -209,10 +202,10 @@ const program = new Command(packageJson.name)
     false,
   )
   .option(
-    "--agents <agents>",
+    "--use-case <useCase>",
     `
 
-  Select which agents to use for the multi-agent template (e.g: financial_report, blog).
+  Select which use case to use for the multi-agent template (e.g: financial_report, blog).
 `,
   )
   .allowUnknownOption()
@@ -222,7 +215,7 @@ const options = program.opts();
 
 if (
   process.argv.includes("--no-llama-parse") ||
-  options.template === "extractor"
+  options.template === "reflex"
 ) {
   options.useLlamaParse = false;
 }
@@ -333,7 +326,6 @@ async function run(): Promise<void> {
     ...answers,
     appPath: resolvedProjectPath,
     packageManager,
-    externalPort: options.externalPort,
   });
 
   if (answers.postInstallAction === "VSCode") {
@@ -362,14 +354,7 @@ Please check ${cyan(
     }
   } else if (answers.postInstallAction === "runApp") {
     console.log(`Running app in ${root}...`);
-    await runApp(
-      root,
-      answers.template,
-      answers.frontend,
-      answers.framework,
-      options.port,
-      options.externalPort,
-    );
+    await runApp(root, answers.template, answers.framework, options.port);
   }
 }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-llama",
-  "version": "0.3.9",
+  "version": "0.3.25",
   "description": "Create LlamaIndex-powered apps with one command",
   "keywords": [
     "rag",

questions/datasources.ts

@@ -49,7 +49,7 @@ export const getDataSourceChoices = (
     );
   }
 
-  if (framework === "fastapi" && template !== "extractor") {
+  if (framework === "fastapi" && template !== "reflex") {
     choices.push({
       title: "Use website content (requires Chrome)",
       value: "web",

questions/index.ts

@@ -4,10 +4,12 @@ import { askProQuestions } from "./questions";
 import { askSimpleQuestions } from "./simple";
 import { QuestionArgs, QuestionResults } from "./types";
 
+export const isCI = ciInfo.isCI || process.env.PLAYWRIGHT_TEST === "1";
+
 export const askQuestions = async (
   args: QuestionArgs,
 ): Promise<QuestionResults> => {
-  if (ciInfo.isCI || process.env.PLAYWRIGHT_TEST === "1") {
+  if (isCI) {
     return await getCIQuestionResults(args);
   } else if (args.pro) {
     // TODO: refactor pro questions to return a result object

questions/questions.ts

@@ -1,7 +1,8 @@
-import { blue, green } from "picocolors";
+import { blue } from "picocolors";
 import prompts from "prompts";
+import { isCI } from ".";
 import { COMMUNITY_OWNER, COMMUNITY_REPO } from "../helpers/constant";
-import { EXAMPLE_FILE } from "../helpers/datasources";
+import { EXAMPLE_FILE, EXAMPLE_GDPR } from "../helpers/datasources";
 import { getAvailableLlamapackOptions } from "../helpers/llama-pack";
 import { askModelConfig } from "../helpers/providers";
 import { getProjectOptions } from "../helpers/repo";
@@ -32,7 +33,7 @@ export const askProQuestions = async (program: QuestionArgs) => {
             title: "Multi-agent app (using workflows)",
             value: "multiagent",
           },
-          { title: "Structured Extractor", value: "extractor" },
+          { title: "Fullstack python template with Reflex", value: "reflex" },
           {
             title: `Community template from ${styledRepo}`,
             value: "community",
@@ -94,11 +95,29 @@ export const askProQuestions = async (program: QuestionArgs) => {
     return; // early return - no further questions needed for llamapack projects
   }
 
-  if (program.template === "extractor") {
-    // Extractor template only supports FastAPI, empty data sources, and llamacloud
+  if (program.template === "reflex") {
+    // Reflex template only supports FastAPI, empty data sources, and llamacloud
     // So we just use example file for extractor template, this allows user to choose vector database later
     program.dataSources = [EXAMPLE_FILE];
     program.framework = "fastapi";
+    // Ask for which Reflex use case to use
+    const { useCase } = await prompts(
+      {
+        type: "select",
+        name: "useCase",
+        message: "Which use case would you like to build?",
+        choices: [
+          { title: "Structured Extractor", value: "extractor" },
+          {
+            title: "Contract review (using Workflow)",
+            value: "contract_review",
+          },
+        ],
+        initial: 0,
+      },
+      questionHandlers,
+    );
+    program.useCase = useCase;
   }
 
   if (!program.framework) {
@@ -122,24 +141,17 @@ export const askProQuestions = async (program: QuestionArgs) => {
   }
 
   if (
-    (program.framework === "express" || program.framework === "fastapi") &&
+    program.framework === "fastapi" &&
     (program.template === "streaming" || program.template === "multiagent")
   ) {
     // if a backend-only framework is selected, ask whether we should create a frontend
     if (program.frontend === undefined) {
       const styledNextJS = blue("NextJS");
-      const styledBackend = green(
-        program.framework === "express"
-          ? "Express "
-          : program.framework === "fastapi"
-            ? "FastAPI (Python) "
-            : "",
-      );
       const { frontend } = await prompts({
         onState: onPromptState,
         type: "toggle",
         name: "frontend",
-        message: `Would you like to generate a ${styledNextJS} frontend for your ${styledBackend}backend?`,
+        message: `Would you like to generate a ${styledNextJS} frontend for your FastAPI backend?`,
         initial: false,
         active: "Yes",
         inactive: "No",
@@ -177,32 +189,50 @@ export const askProQuestions = async (program: QuestionArgs) => {
     program.observability = observability;
   }
 
-  // Ask agents
-  if (program.template === "multiagent" && !program.agents) {
-    const { agents } = await prompts(
+  if (
+    (program.template === "reflex" || program.template === "multiagent") &&
+    !program.useCase
+  ) {
+    const choices =
+      program.template === "reflex"
+        ? [
+            { title: "Structured Extractor", value: "extractor" },
+            {
+              title: "Contract review (using Workflow)",
+              value: "contract_review",
+            },
+          ]
+        : [
+            {
+              title: "Financial report (generate a financial report)",
+              value: "financial_report",
+            },
+            {
+              title: "Form filling (fill missing value in a CSV file)",
+              value: "form_filling",
+            },
+            { title: "Blog writer (Write a blog post)", value: "blog" },
+          ];
+
+    const { useCase } = await prompts(
       {
         type: "select",
-        name: "agents",
-        message: "Which agents would you like to use?",
-        choices: [
-          {
-            title: "Financial report (generate a financial report)",
-            value: "financial_report",
-          },
-          {
-            title: "Form filling (fill missing value in a CSV file)",
-            value: "form_filling",
-          },
-          {
-            title: "Blog writer (Write a blog post)",
-            value: "blog_writer",
-          },
-        ],
+        name: "useCase",
+        message: "Which use case would you like to use?",
+        choices,
         initial: 0,
       },
       questionHandlers,
     );
-    program.agents = agents;
+    program.useCase = useCase;
+  }
+
+  // Configure framework and data sources for Reflex template
+  if (program.template === "reflex") {
+    program.framework = "fastapi";
+
+    program.dataSources =
+      program.useCase === "extractor" ? [EXAMPLE_FILE] : [EXAMPLE_GDPR];
   }
 
   if (!program.modelConfig) {
@@ -228,8 +258,8 @@ export const askProQuestions = async (program: QuestionArgs) => {
     program.vectorDb = vectorDb;
   }
 
-  if (program.vectorDb === "llamacloud") {
-    // When using a LlamaCloud index, don't ask for data sources just copy an example file
+  if (program.vectorDb === "llamacloud" && program.dataSources.length === 0) {
+    // When using a LlamaCloud index and no data sources are provided, just copy an example file
     program.dataSources = [EXAMPLE_FILE];
   }
 
@@ -360,11 +390,8 @@ export const askProQuestions = async (program: QuestionArgs) => {
     // default to use LlamaParse if using LlamaCloud
     program.useLlamaParse = true;
   } else {
-    // Extractor template doesn't support LlamaParse and LlamaCloud right now (cannot use asyncio loop in Reflex)
-    if (
-      program.useLlamaParse === undefined &&
-      program.template !== "extractor"
-    ) {
+    // Reflex template doesn't support LlamaParse right now (cannot use asyncio loop in Reflex)
+    if (program.useLlamaParse === undefined && program.template !== "reflex") {
       // if already set useLlamaParse, don't ask again
       if (program.dataSources.some((ds) => ds.type === "file")) {
         const { useLlamaParse } = await prompts(
@@ -386,7 +413,7 @@ export const askProQuestions = async (program: QuestionArgs) => {
 
   // Ask for LlamaCloud API key when using a LlamaCloud index or LlamaParse
   if (isUsingLlamaCloud || program.useLlamaParse) {
-    if (!program.llamaCloudKey) {
+    if (!program.llamaCloudKey && !isCI) {
       // if already set, don't ask again
       // Ask for LlamaCloud API key
       const { llamaCloudKey } = await prompts(

questions/simple.ts

@@ -1,5 +1,9 @@
 import prompts from "prompts";
-import { EXAMPLE_10K_SEC_FILES, EXAMPLE_FILE } from "../helpers/datasources";
+import {
+  EXAMPLE_10K_SEC_FILES,
+  EXAMPLE_FILE,
+  EXAMPLE_GDPR,
+} from "../helpers/datasources";
 import { askModelConfig } from "../helpers/providers";
 import { getTools } from "../helpers/tools";
 import { ModelConfig, TemplateFramework } from "../helpers/types";
@@ -12,6 +16,7 @@ type AppType =
   | "financial_report_agent"
   | "form_filling"
   | "extractor"
+  | "contract_review"
   | "data_scientist";
 
 type SimpleAnswers = {
@@ -42,6 +47,10 @@ export const askSimpleQuestions = async (
         },
         { title: "Code Artifact Agent", value: "code_artifact" },
         { title: "Information Extractor", value: "extractor" },
+        {
+          title: "Contract Review (using Workflows)",
+          value: "contract_review",
+        },
       ],
     },
     questionHandlers,
@@ -51,51 +60,48 @@ export const askSimpleQuestions = async (
   let llamaCloudKey = args.llamaCloudKey;
   let useLlamaCloud = false;
 
-  if (appType !== "extractor") {
-    // TODO: Add TS support for form filling use case
-    if (appType !== "form_filling") {
-      const { language: newLanguage } = await prompts(
-        {
-          type: "select",
-          name: "language",
-          message: "What language do you want to use?",
-          choices: [
-            { title: "Python (FastAPI)", value: "fastapi" },
-            { title: "Typescript (NextJS)", value: "nextjs" },
-          ],
-        },
-        questionHandlers,
-      );
-      language = newLanguage;
-    }
-
-    const { useLlamaCloud: newUseLlamaCloud } = await prompts(
+  if (appType !== "extractor" && appType !== "contract_review") {
+    const { language: newLanguage } = await prompts(
       {
-        type: "toggle",
-        name: "useLlamaCloud",
-        message: "Do you want to use LlamaCloud services?",
-        initial: false,
-        active: "Yes",
-        inactive: "No",
-        hint: "see https://www.llamaindex.ai/enterprise for more info",
+        type: "select",
+        name: "language",
+        message: "What language do you want to use?",
+        choices: [
+          { title: "Python (FastAPI)", value: "fastapi" },
+          { title: "Typescript (NextJS)", value: "nextjs" },
+        ],
       },
       questionHandlers,
     );
-    useLlamaCloud = newUseLlamaCloud;
+    language = newLanguage;
+  }
 
-    if (useLlamaCloud && !llamaCloudKey) {
-      // Ask for LlamaCloud API key, if not set
-      const { llamaCloudKey: newLlamaCloudKey } = await prompts(
-        {
-          type: "text",
-          name: "llamaCloudKey",
-          message:
-            "Please provide your LlamaCloud API key (leave blank to skip):",
-        },
-        questionHandlers,
-      );
-      llamaCloudKey = newLlamaCloudKey || process.env.LLAMA_CLOUD_API_KEY;
-    }
+  const { useLlamaCloud: newUseLlamaCloud } = await prompts(
+    {
+      type: "toggle",
+      name: "useLlamaCloud",
+      message: "Do you want to use LlamaCloud services?",
+      initial: false,
+      active: "Yes",
+      inactive: "No",
+      hint: "see https://www.llamaindex.ai/enterprise for more info",
+    },
+    questionHandlers,
+  );
+  useLlamaCloud = newUseLlamaCloud;
+
+  if (useLlamaCloud && !llamaCloudKey) {
+    // Ask for LlamaCloud API key, if not set
+    const { llamaCloudKey: newLlamaCloudKey } = await prompts(
+      {
+        type: "text",
+        name: "llamaCloudKey",
+        message:
+          "Please provide your LlamaCloud API key (leave blank to skip):",
+      },
+      questionHandlers,
+    );
+    llamaCloudKey = newLlamaCloudKey || process.env.LLAMA_CLOUD_API_KEY;
   }
 
   const results = await convertAnswers(args, {
@@ -127,14 +133,14 @@ const convertAnswers = async (
     AppType,
     Pick<
       QuestionResults,
-      "template" | "tools" | "frontend" | "dataSources" | "agents"
+      "template" | "tools" | "frontend" | "dataSources" | "useCase"
     > & {
       modelConfig?: ModelConfig;
     }
   > = {
     rag: {
       template: "streaming",
-      tools: getTools(["duckduckgo"]),
+      tools: getTools(["weather"]),
       frontend: true,
       dataSources: [EXAMPLE_FILE],
     },
@@ -154,7 +160,7 @@ const convertAnswers = async (
     },
     financial_report_agent: {
       template: "multiagent",
-      agents: "financial_report",
+      useCase: "financial_report",
       tools: getTools(["document_generator", "interpreter"]),
       dataSources: EXAMPLE_10K_SEC_FILES,
       frontend: true,
@@ -162,18 +168,26 @@ const convertAnswers = async (
     },
     form_filling: {
       template: "multiagent",
-      agents: "form_filling",
+      useCase: "form_filling",
       tools: getTools(["form_filling"]),
       dataSources: EXAMPLE_10K_SEC_FILES,
       frontend: true,
       modelConfig: MODEL_GPT4o,
     },
     extractor: {
-      template: "extractor",
+      template: "reflex",
+      useCase: "extractor",
       tools: [],
       frontend: false,
       dataSources: [EXAMPLE_FILE],
     },
+    contract_review: {
+      template: "reflex",
+      useCase: "contract_review",
+      tools: [],
+      frontend: false,
+      dataSources: [EXAMPLE_GDPR],
+    },
   };
   const results = lookup[answers.appType];
   return {

questions/types.ts

@@ -2,7 +2,7 @@ import { InstallAppArgs } from "../create-app";
 
 export type QuestionResults = Omit<
   InstallAppArgs,
-  "appPath" | "packageManager" | "externalPort"
+  "appPath" | "packageManager"
 >;
 
 export type PureQuestionArgs = {

templates/.gitignore

@@ -1,3 +0,0 @@
-__pycache__
-poetry.lock
-storage

templates/README-fullstack.md

@@ -1,18 +0,0 @@
-This is a [LlamaIndex](https://www.llamaindex.ai/) project bootstrapped with [`create-llama`](https://github.com/run-llama/LlamaIndexTS/tree/main/packages/create-llama).
-
-## Getting Started
-
-First, startup the backend as described in the [backend README](./backend/README.md).
-
-Second, run the development server of the frontend as described in the [frontend README](./frontend/README.md).
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-## Learn More
-
-To learn more about LlamaIndex, take a look at the following resources:
-
-- [LlamaIndex Documentation](https://docs.llamaindex.ai) - learn about LlamaIndex (Python features).
-- [LlamaIndexTS Documentation](https://ts.llamaindex.ai) - learn about LlamaIndex (Typescript features).
-
-You can check out [the LlamaIndexTS GitHub repository](https://github.com/run-llama/LlamaIndexTS) - your feedback and contributions are welcome!

templates/components/agents/python/blog/README-template.md

@@ -32,7 +32,7 @@ poetry run generate
 Third, run the development server:
 
 ```shell
-poetry run python main.py
+poetry run dev
 ```
 
 Per default, the example is using the explicit workflow. You can change the example by setting the `EXAMPLE_TYPE` environment variable to `choreography` or `orchestrator`.
@@ -47,14 +47,18 @@ curl --location 'localhost:8000/api/chat' \
 
 You can start editing the API by modifying `app/api/routers/chat.py` or `app/examples/workflow.py`. The API auto-updates as you save the files.
 
-Open [http://localhost:8000/docs](http://localhost:8000/docs) with your browser to see the Swagger UI of the API.
+Open [http://localhost:8000](http://localhost:8000) with your browser to start the app.
 
-The API allows CORS for all origins to simplify development. You can change this behavior by setting the `ENVIRONMENT` environment variable to `prod`:
+To start the app optimized for **production**, run:
 
 ```
-ENVIRONMENT=prod poetry run python main.py
+poetry run prod
 ```
 
+## Deployments
+
+For production deployments, check the [DEPLOY.md](DEPLOY.md) file.
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

templates/components/agents/python/blog/app/agents/researcher.py

@@ -1,4 +1,3 @@
-import os
 from textwrap import dedent
 from typing import List
 
@@ -6,42 +5,24 @@ from app.engine.index import IndexConfig, get_index
 from app.engine.tools import ToolFactory
 from app.workflows.single import FunctionCallingAgent
 from llama_index.core.chat_engine.types import ChatMessage
-from llama_index.core.tools import QueryEngineTool, ToolMetadata
+from app.engine.tools.query_engine import get_query_engine_tool
 
 
-def _create_query_engine_tool(params=None) -> QueryEngineTool:
-    """
-    Provide an agent worker that can be used to query the index.
-    """
-    # Add query tool if index exists
-    index_config = IndexConfig(**(params or {}))
-    index = get_index(index_config)
-    if index is None:
-        return None
-    top_k = int(os.getenv("TOP_K", 0))
-    query_engine = index.as_query_engine(
-        **({"similarity_top_k": top_k} if top_k != 0 else {})
-    )
-    return QueryEngineTool(
-        query_engine=query_engine,
-        metadata=ToolMetadata(
-            name="query_index",
-            description="""
-                Use this tool to retrieve information about the text corpus from the index.
-            """,
-        ),
-    )
-
-
-def _get_research_tools(**kwargs) -> QueryEngineTool:
+def _get_research_tools(**kwargs):
     """
     Researcher take responsibility for retrieving information.
     Try init wikipedia or duckduckgo tool if available.
     """
     tools = []
-    query_engine_tool = _create_query_engine_tool(**kwargs)
-    if query_engine_tool is not None:
-        tools.append(query_engine_tool)
+    # Create query engine tool
+    index_config = IndexConfig(**kwargs)
+    index = get_index(index_config)
+    if index is not None:
+        query_engine_tool = get_query_engine_tool(index=index)
+        if query_engine_tool is not None:
+            tools.append(query_engine_tool)
+
+    # Create duckduckgo tool
     researcher_tool_names = [
         "duckduckgo_search",
         "duckduckgo_image_search",

templates/components/agents/python/financial_report/README-template.md

@@ -21,7 +21,7 @@ poetry run generate
 Third, run the development server:
 
 ```shell
-poetry run python main.py
+poetry run dev
 ```
 
 The example provides one streaming API endpoint `/api/chat`.
@@ -35,14 +35,18 @@ curl --location 'localhost:8000/api/chat' \
 
 You can start editing the API by modifying `app/api/routers/chat.py` or `app/workflows/financial_report.py`. The API auto-updates as you save the files.
 
-Open [http://localhost:8000/docs](http://localhost:8000/docs) with your browser to see the Swagger UI of the API.
+Open [http://localhost:8000](http://localhost:8000) with your browser to start the app.
 
-The API allows CORS for all origins to simplify development. You can change this behavior by setting the `ENVIRONMENT` environment variable to `prod`:
+To start the app optimized for **production**, run:
 
 ```
-ENVIRONMENT=prod poetry run python main.py
+poetry run prod
 ```
 
+## Deployments
+
+For production deployments, check the [DEPLOY.md](DEPLOY.md) file.
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

templates/components/agents/python/financial_report/app/workflows/financial_report.py

@@ -1,8 +1,8 @@
-import os
 from typing import Any, Dict, List, Optional
 
 from app.engine.index import IndexConfig, get_index
 from app.engine.tools import ToolFactory
+from app.engine.tools.query_engine import get_query_engine_tool
 from app.workflows.events import AgentRunEvent
 from app.workflows.tools import (
     call_tools,
@@ -10,7 +10,6 @@ from app.workflows.tools import (
 )
 from llama_index.core import Settings
 from llama_index.core.base.llms.types import ChatMessage, MessageRole
-from llama_index.core.indices.vector_store import VectorStoreIndex
 from llama_index.core.llms.function_calling import FunctionCallingLLM
 from llama_index.core.memory import ChatMemoryBuffer
 from llama_index.core.tools import FunctionTool, QueryEngineTool, ToolSelection
@@ -27,16 +26,16 @@ from llama_index.core.workflow import (
 def create_workflow(
     chat_history: Optional[List[ChatMessage]] = None,
     params: Optional[Dict[str, Any]] = None,
-    filters: Optional[List[Any]] = None,
+    **kwargs,
 ) -> Workflow:
+    # Create query engine tool
     index_config = IndexConfig(**params)
-    index: VectorStoreIndex = get_index(config=index_config)
+    index = get_index(index_config)
     if index is None:
-        query_engine_tool = None
-    else:
-        top_k = int(os.getenv("TOP_K", 10))
-        query_engine = index.as_query_engine(similarity_top_k=top_k, filters=filters)
-        query_engine_tool = QueryEngineTool.from_defaults(query_engine=query_engine)
+        raise ValueError(
+            "Index is not found. Try run generation script to create the index first."
+        )
+    query_engine_tool = get_query_engine_tool(index=index)
 
     configured_tools: Dict[str, FunctionTool] = ToolFactory.from_env(map_result=True)  # type: ignore
     code_interpreter_tool = configured_tools.get("interpret")

templates/components/agents/python/form_filling/README-template.md

@@ -16,7 +16,7 @@ Make sure you have the `OPENAI_API_KEY` set.
 Second, run the development server:
 
 ```shell
-poetry run python main.py
+poetry run dev
 ```
 
 ## Use Case: Filling Financial CSV Template
@@ -41,14 +41,18 @@ curl --location 'localhost:8000/api/chat' \
 
 You can start editing the API by modifying `app/api/routers/chat.py` or `app/workflows/form_filling.py`. The API auto-updates as you save the files.
 
-Open [http://localhost:8000/docs](http://localhost:8000/docs) with your browser to see the Swagger UI of the API.
+Open [http://localhost:8000](http://localhost:8000) with your browser to start the app.
 
-The API allows CORS for all origins to simplify development. You can change this behavior by setting the `ENVIRONMENT` environment variable to `prod`:
+To start the app optimized for **production**, run:
 
 ```
-ENVIRONMENT=prod poetry run python main.py
+poetry run prod
 ```
 
+## Deployments
+
+For production deployments, check the [DEPLOY.md](DEPLOY.md) file.
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

templates/components/agents/python/form_filling/app/workflows/form_filling.py

@@ -1,16 +1,7 @@
-import os
 from typing import Any, Dict, List, Optional
 
-from app.engine.index import IndexConfig, get_index
-from app.engine.tools import ToolFactory
-from app.workflows.events import AgentRunEvent
-from app.workflows.tools import (
-    call_tools,
-    chat_with_tools,
-)
 from llama_index.core import Settings
 from llama_index.core.base.llms.types import ChatMessage, MessageRole
-from llama_index.core.indices.vector_store import VectorStoreIndex
 from llama_index.core.llms.function_calling import FunctionCallingLLM
 from llama_index.core.memory import ChatMemoryBuffer
 from llama_index.core.tools import FunctionTool, QueryEngineTool, ToolSelection
@@ -23,24 +14,28 @@ from llama_index.core.workflow import (
     step,
 )
 
+from app.engine.index import IndexConfig, get_index
+from app.engine.tools import ToolFactory
+from app.engine.tools.query_engine import get_query_engine_tool
+from app.workflows.events import AgentRunEvent
+from app.workflows.tools import (
+    call_tools,
+    chat_with_tools,
+)
+
 
 def create_workflow(
     chat_history: Optional[List[ChatMessage]] = None,
     params: Optional[Dict[str, Any]] = None,
-    filters: Optional[List[Any]] = None,
+    **kwargs,
 ) -> Workflow:
-    if params is None:
-        params = {}
-    if filters is None:
-        filters = []
+    # Create query engine tool
     index_config = IndexConfig(**params)
-    index: VectorStoreIndex = get_index(config=index_config)
+    index = get_index(index_config)
     if index is None:
         query_engine_tool = None
     else:
-        top_k = int(os.getenv("TOP_K", 10))
-        query_engine = index.as_query_engine(similarity_top_k=top_k, filters=filters)
-        query_engine_tool = QueryEngineTool.from_defaults(query_engine=query_engine)
+        query_engine_tool = get_query_engine_tool(index=index)
 
     configured_tools = ToolFactory.from_env(map_result=True)
     extractor_tool = configured_tools.get("extract_questions")  # type: ignore

templates/components/agents/typescript/blog/factory.ts

@@ -1,230 +0,0 @@
-import {
-  Context,
-  StartEvent,
-  StopEvent,
-  Workflow,
-  WorkflowEvent,
-} from "@llamaindex/core/workflow";
-import { Message } from "ai";
-import { ChatMessage, ChatResponseChunk, Settings } from "llamaindex";
-import { getAnnotations } from "../llamaindex/streaming/annotations";
-import {
-  createPublisher,
-  createResearcher,
-  createReviewer,
-  createWriter,
-} from "./agents";
-import { AgentInput, AgentRunEvent } from "./type";
-
-const TIMEOUT = 360 * 1000;
-const MAX_ATTEMPTS = 2;
-
-class ResearchEvent extends WorkflowEvent<{ input: string }> {}
-class WriteEvent extends WorkflowEvent<{
-  input: string;
-  isGood: boolean;
-}> {}
-class ReviewEvent extends WorkflowEvent<{ input: string }> {}
-class PublishEvent extends WorkflowEvent<{ input: string }> {}
-
-const prepareChatHistory = (chatHistory: Message[]): ChatMessage[] => {
-  // By default, the chat history only contains the assistant and user messages
-  // all the agents messages are stored in annotation data which is not visible to the LLM
-
-  const MAX_AGENT_MESSAGES = 10;
-  const agentAnnotations = getAnnotations<{ agent: string; text: string }>(
-    chatHistory,
-    { role: "assistant", type: "agent" },
-  ).slice(-MAX_AGENT_MESSAGES);
-
-  const agentMessages = agentAnnotations
-    .map(
-      (annotation) =>
-        `\n<${annotation.data.agent}>\n${annotation.data.text}\n</${annotation.data.agent}>`,
-    )
-    .join("\n");
-
-  const agentContent = agentMessages
-    ? "Here is the previous conversation of agents:\n" + agentMessages
-    : "";
-
-  if (agentContent) {
-    const agentMessage: ChatMessage = {
-      role: "assistant",
-      content: agentContent,
-    };
-    return [
-      ...chatHistory.slice(0, -1),
-      agentMessage,
-      chatHistory.slice(-1)[0],
-    ] as ChatMessage[];
-  }
-  return chatHistory as ChatMessage[];
-};
-
-export const createWorkflow = (messages: Message[], params?: any) => {
-  const chatHistoryWithAgentMessages = prepareChatHistory(messages);
-  const runAgent = async (
-    context: Context,
-    agent: Workflow,
-    input: AgentInput,
-  ) => {
-    const run = agent.run(new StartEvent({ input }));
-    for await (const event of agent.streamEvents()) {
-      if (event.data instanceof AgentRunEvent) {
-        context.writeEventToStream(event.data);
-      }
-    }
-    return await run;
-  };
-
-  const start = async (context: Context, ev: StartEvent) => {
-    context.set("task", ev.data.input);
-
-    const chatHistoryStr = chatHistoryWithAgentMessages
-      .map((msg) => `${msg.role}: ${msg.content}`)
-      .join("\n");
-
-    // Decision-making process
-    const decision = await decideWorkflow(ev.data.input, chatHistoryStr);
-
-    if (decision !== "publish") {
-      return new ResearchEvent({
-        input: `Research for this task: ${ev.data.input}`,
-      });
-    } else {
-      return new PublishEvent({
-        input: `Publish content based on the chat history\n${chatHistoryStr}\n\n and task: ${ev.data.input}`,
-      });
-    }
-  };
-
-  const decideWorkflow = async (task: string, chatHistoryStr: string) => {
-    const llm = Settings.llm;
-
-    const prompt = `You are an expert in decision-making, helping people write and publish blog posts.
-If the user is asking for a file or to publish content, respond with 'publish'.
-If the user requests to write or update a blog post, respond with 'not_publish'.
-
-Here is the chat history:
-${chatHistoryStr}
-
-The current user request is:
-${task}
-
-Given the chat history and the new user request, decide whether to publish based on existing information.
-Decision (respond with either 'not_publish' or 'publish'):`;
-
-    const output = await llm.complete({ prompt: prompt });
-    const decision = output.text.trim().toLowerCase();
-    return decision === "publish" ? "publish" : "research";
-  };
-
-  const research = async (context: Context, ev: ResearchEvent) => {
-    const researcher = await createResearcher(
-      chatHistoryWithAgentMessages,
-      params,
-    );
-    const researchRes = await runAgent(context, researcher, {
-      message: ev.data.input,
-    });
-    const researchResult = researchRes.data.result;
-    return new WriteEvent({
-      input: `Write a blog post given this task: ${context.get("task")} using this research content: ${researchResult}`,
-      isGood: false,
-    });
-  };
-
-  const write = async (context: Context, ev: WriteEvent) => {
-    const writer = createWriter(chatHistoryWithAgentMessages);
-
-    context.set("attempts", context.get("attempts", 0) + 1);
-    const tooManyAttempts = context.get("attempts") > MAX_ATTEMPTS;
-    if (tooManyAttempts) {
-      context.writeEventToStream(
-        new AgentRunEvent({
-          name: "writer",
-          msg: `Too many attempts (${MAX_ATTEMPTS}) to write the blog post. Proceeding with the current version.`,
-        }),
-      );
-    }
-
-    if (ev.data.isGood || tooManyAttempts) {
-      // the blog post is good or too many attempts
-      // stream the final content
-      const result = await runAgent(context, writer, {
-        message: `Based on the reviewer's feedback, refine the post and return only the final version of the post. Here's the current version: ${ev.data.input}`,
-        streaming: true,
-      });
-      return result as unknown as StopEvent<AsyncGenerator<ChatResponseChunk>>;
-    }
-
-    const writeRes = await runAgent(context, writer, {
-      message: ev.data.input,
-    });
-    const writeResult = writeRes.data.result;
-    context.set("result", writeResult); // store the last result
-    return new ReviewEvent({ input: writeResult });
-  };
-
-  const review = async (context: Context, ev: ReviewEvent) => {
-    const reviewer = createReviewer(chatHistoryWithAgentMessages);
-    const reviewRes = await reviewer.run(
-      new StartEvent<AgentInput>({ input: { message: ev.data.input } }),
-    );
-    const reviewResult = reviewRes.data.result;
-    const oldContent = context.get("result");
-    const postIsGood = reviewResult.toLowerCase().includes("post is good");
-    context.writeEventToStream(
-      new AgentRunEvent({
-        name: "reviewer",
-        msg: `The post is ${postIsGood ? "" : "not "}good enough for publishing. Sending back to the writer${
-          postIsGood ? " for publication." : "."
-        }`,
-      }),
-    );
-    if (postIsGood) {
-      return new WriteEvent({
-        input: "",
-        isGood: true,
-      });
-    }
-
-    return new WriteEvent({
-      input: `Improve the writing of a given blog post by using a given review.
-            Blog post:
-            \`\`\`
-            ${oldContent}
-            \`\`\`
-
-            Review:
-            \`\`\`
-            ${reviewResult}
-            \`\`\``,
-      isGood: false,
-    });
-  };
-
-  const publish = async (context: Context, ev: PublishEvent) => {
-    const publisher = await createPublisher(chatHistoryWithAgentMessages);
-
-    const publishResult = await runAgent(context, publisher, {
-      message: `${ev.data.input}`,
-      streaming: true,
-    });
-    return publishResult as unknown as StopEvent<
-      AsyncGenerator<ChatResponseChunk>
-    >;
-  };
-
-  const workflow = new Workflow({ timeout: TIMEOUT, validate: true });
-  workflow.addStep(StartEvent, start, {
-    outputs: [ResearchEvent, PublishEvent],
-  });
-  workflow.addStep(ResearchEvent, research, { outputs: WriteEvent });
-  workflow.addStep(WriteEvent, write, { outputs: [ReviewEvent, StopEvent] });
-  workflow.addStep(ReviewEvent, review, { outputs: WriteEvent });
-  workflow.addStep(PublishEvent, publish, { outputs: StopEvent });
-
-  return workflow;
-};

templates/components/agents/typescript/blog/tools.ts

@@ -1,54 +0,0 @@
-import fs from "fs/promises";
-import { BaseToolWithCall, QueryEngineTool } from "llamaindex";
-import path from "path";
-import { getDataSource } from "../engine";
-import { createTools } from "../engine/tools/index";
-
-export const getQueryEngineTool = async (
-  params?: any,
-): Promise<QueryEngineTool | null> => {
-  const index = await getDataSource(params);
-  if (!index) {
-    return null;
-  }
-
-  const topK = process.env.TOP_K ? parseInt(process.env.TOP_K) : undefined;
-  return new QueryEngineTool({
-    queryEngine: index.asQueryEngine({
-      similarityTopK: topK,
-    }),
-    metadata: {
-      name: "query_index",
-      description: `Use this tool to retrieve information about the text corpus from the index.`,
-    },
-  });
-};
-
-export const getAvailableTools = async () => {
-  const configFile = path.join("config", "tools.json");
-  let toolConfig: any;
-  const tools: BaseToolWithCall[] = [];
-  try {
-    toolConfig = JSON.parse(await fs.readFile(configFile, "utf8"));
-  } catch (e) {
-    console.info(`Could not read ${configFile} file. Using no tools.`);
-  }
-  if (toolConfig) {
-    tools.push(...(await createTools(toolConfig)));
-  }
-  const queryEngineTool = await getQueryEngineTool();
-  if (queryEngineTool) {
-    tools.push(queryEngineTool);
-  }
-
-  return tools;
-};
-
-export const lookupTools = async (
-  toolNames: string[],
-): Promise<BaseToolWithCall[]> => {
-  const availableTools = await getAvailableTools();
-  return availableTools.filter((tool) =>
-    toolNames.includes(tool.metadata.name),
-  );
-};

templates/components/agents/typescript/blog/workflow/agents.ts

@@ -1,19 +1,16 @@
 import { ChatMessage } from "llamaindex";
+import { getTool } from "../engine/tools";
 import { FunctionCallingAgent } from "./single-agent";
-import { getQueryEngineTool, lookupTools } from "./tools";
+import { getQueryEngineTool } from "./tools";
 
-export const createResearcher = async (
-  chatHistory: ChatMessage[],
-  params?: any,
-) => {
-  const queryEngineTool = await getQueryEngineTool(params);
-  const tools = (
-    await lookupTools([
-      "wikipedia_tool",
-      "duckduckgo_search",
-      "image_generator",
-    ])
-  ).concat(queryEngineTool ? [queryEngineTool] : []);
+export const createResearcher = async (chatHistory: ChatMessage[]) => {
+  const queryEngineTool = await getQueryEngineTool();
+  const tools = [
+    await getTool("wikipedia_tool"),
+    await getTool("duckduckgo_search"),
+    await getTool("image_generator"),
+    queryEngineTool,
+  ].filter((tool) => tool !== undefined);
 
   return new FunctionCallingAgent({
     name: "researcher",
@@ -81,17 +78,17 @@ Example:
 };
 
 export const createPublisher = async (chatHistory: ChatMessage[]) => {
-  const tools = await lookupTools(["document_generator"]);
+  const tool = await getTool("document_generator");
   let systemPrompt = `You are an expert in publishing blog posts. You are given a task to publish a blog post. 
 If the writer says that there was an error, you should reply with the error and not publish the post.`;
-  if (tools.length > 0) {
+  if (tool) {
     systemPrompt = `${systemPrompt}. 
 If the user requests to generate a file, use the document_generator tool to generate the file and reply with the link to the file.
 Otherwise, simply return the content of the post.`;
   }
   return new FunctionCallingAgent({
     name: "publisher",
-    tools: tools,
+    tools: tool ? [tool] : [],
     systemPrompt: systemPrompt,
     chatHistory,
   });

templates/components/agents/typescript/blog/workflow/factory.ts

@@ -0,0 +1,291 @@
+import {
+  HandlerContext,
+  StartEvent,
+  StopEvent,
+  Workflow,
+  WorkflowContext,
+  WorkflowEvent,
+} from "@llamaindex/workflow";
+import { ChatMessage, ChatResponseChunk, Settings } from "llamaindex";
+import {
+  createPublisher,
+  createResearcher,
+  createReviewer,
+  createWriter,
+} from "./agents";
+import {
+  FunctionCallingAgent,
+  FunctionCallingAgentInput,
+} from "./single-agent";
+import { AgentInput, AgentRunEvent } from "./type";
+
+const TIMEOUT = 360 * 1000;
+const MAX_ATTEMPTS = 2;
+
+class ResearchEvent extends WorkflowEvent<{ input: string }> {}
+class WriteEvent extends WorkflowEvent<{
+  input: string;
+  isGood: boolean;
+}> {}
+class ReviewEvent extends WorkflowEvent<{ input: string }> {}
+class PublishEvent extends WorkflowEvent<{ input: string }> {}
+
+type BlogContext = {
+  task: string;
+  attempts: number;
+  result: string;
+};
+
+export const createWorkflow = ({
+  chatHistory,
+  params,
+}: {
+  chatHistory: ChatMessage[];
+  params?: any;
+}) => {
+  const runAgent = async (
+    context: HandlerContext<BlogContext>,
+    agent: FunctionCallingAgent,
+    input: FunctionCallingAgentInput,
+  ) => {
+    const agentContext = agent.run(input, {
+      streaming: input.streaming ?? false,
+    });
+    for await (const event of agentContext) {
+      if (event instanceof AgentRunEvent) {
+        context.sendEvent(event);
+      }
+      if (event instanceof StopEvent) {
+        return event;
+      }
+    }
+    return null;
+  };
+
+  const start = async (
+    context: HandlerContext<BlogContext>,
+    ev: StartEvent<AgentInput>,
+  ) => {
+    const chatHistoryStr = chatHistory
+      .map((msg) => `${msg.role}: ${msg.content}`)
+      .join("\n");
+
+    // Decision-making process
+    const decision = await decideWorkflow(
+      ev.data.message.toString(),
+      chatHistoryStr,
+    );
+
+    if (decision !== "publish") {
+      return new ResearchEvent({
+        input: `Research for this task: ${JSON.stringify(context.data.task)}`,
+      });
+    } else {
+      return new PublishEvent({
+        input: `Publish content based on the chat history\n${chatHistoryStr}\n\n and task: ${context.data.task}`,
+      });
+    }
+  };
+
+  const decideWorkflow = async (task: string, chatHistoryStr: string) => {
+    const llm = Settings.llm;
+
+    const prompt = `You are an expert in decision-making, helping people write and publish blog posts.
+If the user is asking for a file or to publish content, respond with 'publish'.
+If the user requests to write or update a blog post, respond with 'not_publish'.
+
+Here is the chat history:
+${chatHistoryStr}
+
+The current user request is:
+${task}
+
+Given the chat history and the new user request, decide whether to publish based on existing information.
+Decision (respond with either 'not_publish' or 'publish'):`;
+
+    const output = await llm.complete({ prompt: prompt });
+    const decision = output.text.trim().toLowerCase();
+    return decision === "publish" ? "publish" : "research";
+  };
+
+  const research = async (
+    context: HandlerContext<BlogContext>,
+    ev: ResearchEvent,
+  ) => {
+    const researcher = await createResearcher(chatHistory);
+    const researchRes = await runAgent(context, researcher, {
+      displayName: "Researcher",
+      message: ev.data.input,
+    });
+    const researchResult = researchRes?.data;
+
+    return new WriteEvent({
+      input: `Write a blog post given this task: ${JSON.stringify(
+        context.data.task,
+      )} using this research content: ${researchResult}`,
+      isGood: false,
+    });
+  };
+
+  const write = async (
+    context: HandlerContext<BlogContext>,
+    ev: WriteEvent,
+  ) => {
+    const writer = createWriter(chatHistory);
+    context.data.attempts = context.data.attempts + 1;
+    const tooManyAttempts = context.data.attempts > MAX_ATTEMPTS;
+    if (tooManyAttempts) {
+      context.sendEvent(
+        new AgentRunEvent({
+          agent: "writer",
+          text: `Too many attempts (${MAX_ATTEMPTS}) to write the blog post. Proceeding with the current version.`,
+          type: "text",
+        }),
+      );
+    }
+
+    if (ev.data.isGood || tooManyAttempts) {
+      // the blog post is good or too many attempts
+      // stream the final content
+      const result = await runAgent(context, writer, {
+        message: `Based on the reviewer's feedback, refine the post and return only the final version of the post. Here's the current version: ${ev.data.input}`,
+        displayName: "Writer",
+        streaming: true,
+      });
+      return result as unknown as StopEvent<AsyncGenerator<ChatResponseChunk>>;
+    }
+
+    const writeRes = await runAgent(context, writer, {
+      message: ev.data.input,
+      displayName: "Writer",
+      streaming: false,
+    });
+    const writeResult = writeRes?.data;
+    context.data.result = writeResult; // store the last result
+
+    return new ReviewEvent({ input: writeResult });
+  };
+
+  const review = async (
+    context: HandlerContext<BlogContext>,
+    ev: ReviewEvent,
+  ) => {
+    const reviewer = createReviewer(chatHistory);
+    const reviewResult = (await runAgent(context, reviewer, {
+      message: ev.data.input,
+      displayName: "Reviewer",
+      streaming: false,
+    })) as unknown as StopEvent<string>;
+    const reviewResultStr = reviewResult.data;
+    const oldContent = context.data.result;
+    const postIsGood = reviewResultStr.toLowerCase().includes("post is good");
+    context.sendEvent(
+      new AgentRunEvent({
+        agent: "reviewer",
+        text: `The post is ${postIsGood ? "" : "not "}good enough for publishing. Sending back to the writer${
+          postIsGood ? " for publication." : "."
+        }`,
+        type: "text",
+      }),
+    );
+    if (postIsGood) {
+      return new WriteEvent({
+        input: "",
+        isGood: true,
+      });
+    }
+
+    return new WriteEvent({
+      input: `Improve the writing of a given blog post by using a given review.
+            Blog post:
+            \`\`\`
+            ${oldContent}
+            \`\`\`
+
+            Review:
+            \`\`\`
+            ${reviewResult}
+            \`\`\``,
+      isGood: false,
+    });
+  };
+
+  const publish = async (
+    context: HandlerContext<BlogContext>,
+    ev: PublishEvent,
+  ) => {
+    const publisher = await createPublisher(chatHistory);
+
+    const publishResult = await runAgent(context, publisher, {
+      message: `${ev.data.input}`,
+      displayName: "Publisher",
+      streaming: true,
+    });
+    return publishResult as unknown as StopEvent<
+      AsyncGenerator<ChatResponseChunk>
+    >;
+  };
+
+  const workflow: Workflow<
+    BlogContext,
+    AgentInput,
+    string | AsyncGenerator<boolean | ChatResponseChunk>
+  > = new Workflow();
+
+  workflow.addStep(
+    {
+      inputs: [StartEvent<AgentInput>],
+      outputs: [ResearchEvent, PublishEvent],
+    },
+    start,
+  );
+
+  workflow.addStep(
+    {
+      inputs: [ResearchEvent],
+      outputs: [WriteEvent],
+    },
+    research,
+  );
+
+  workflow.addStep(
+    {
+      inputs: [WriteEvent],
+      outputs: [ReviewEvent, StopEvent<AsyncGenerator<ChatResponseChunk>>],
+    },
+    write,
+  );
+
+  workflow.addStep(
+    {
+      inputs: [ReviewEvent],
+      outputs: [WriteEvent],
+    },
+    review,
+  );
+
+  workflow.addStep(
+    {
+      inputs: [PublishEvent],
+      outputs: [StopEvent],
+    },
+    publish,
+  );
+
+  // Overload run method to initialize the context
+  workflow.run = function (
+    input: AgentInput,
+  ): WorkflowContext<
+    AgentInput,
+    string | AsyncGenerator<boolean | ChatResponseChunk>,
+    BlogContext
+  > {
+    return Workflow.prototype.run.call(workflow, new StartEvent(input), {
+      task: input.message.toString(),
+      attempts: 0,
+      result: "",
+    });
+  };
+
+  return workflow;
+};

templates/components/agents/typescript/financial_report/README-template.md

@@ -0,0 +1,47 @@
+This is a [LlamaIndex](https://www.llamaindex.ai/) project using [Next.js](https://nextjs.org/) bootstrapped with [`create-llama`](https://github.com/run-llama/LlamaIndexTS/tree/main/packages/create-llama).
+
+## Getting Started
+
+First, install the dependencies:
+
+```
+npm install
+```
+
+Then check the parameters that have been pre-configured in the `.env` file in this directory.
+Make sure you have the `OPENAI_API_KEY` set.
+
+Second, generate the embeddings of the documents in the `./data` directory:
+
+```
+npm run generate
+```
+
+Third, run the development server:
+
+```
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the chat UI.
+
+## Use Case: Filling Financial CSV Template
+
+You can start by sending an request on the chat UI to create a report comparing the finances of Apple and Tesla.
+Or you can test the `/api/chat` endpoint with the following curl request:
+
+```
+curl --location 'localhost:3000/api/chat' \
+--header 'Content-Type: application/json' \
+--data '{ "messages": [{ "role": "user", "content": "Create a report comparing the finances of Apple and Tesla" }] }'
+```
+
+## Learn More
+
+To learn more about LlamaIndex, take a look at the following resources:
+
+- [LlamaIndex Documentation](https://docs.llamaindex.ai) - learn about LlamaIndex (Python features).
+- [LlamaIndexTS Documentation](https://ts.llamaindex.ai/docs/llamaindex) - learn about LlamaIndex (Typescript features).
+- [Workflows Introduction](https://ts.llamaindex.ai/docs/llamaindex/guide/workflow) - learn about LlamaIndexTS workflows.
+
+You can check out [the LlamaIndexTS GitHub repository](https://github.com/run-llama/LlamaIndexTS) - your feedback and contributions are welcome!

templates/components/agents/typescript/financial_report/agents.ts

@@ -1,65 +0,0 @@
-import { ChatMessage } from "llamaindex";
-import { FunctionCallingAgent } from "./single-agent";
-import { getQueryEngineTools, lookupTools } from "./tools";
-
-export const createResearcher = async (
-  chatHistory: ChatMessage[],
-  params?: any,
-) => {
-  const queryEngineTools = await getQueryEngineTools(params);
-
-  if (!queryEngineTools) {
-    throw new Error("Query engine tool not found");
-  }
-
-  return new FunctionCallingAgent({
-    name: "researcher",
-    tools: queryEngineTools,
-    systemPrompt: `You are a researcher agent. You are responsible for retrieving information from the corpus.
-## Instructions:
-+ Don't synthesize the information, just return the whole retrieved information.
-+ Don't need to retrieve the information that is already provided in the chat history and respond with: "There is no new information, please reuse the information from the conversation."
-`,
-    chatHistory,
-  });
-};
-
-export const createAnalyst = async (chatHistory: ChatMessage[]) => {
-  let systemPrompt = `You are an expert in analyzing financial data.
-You are given a task and a set of financial data to analyze. Your task is to analyze the financial data and return a report.
-Your response should include a detailed analysis of the financial data, including any trends, patterns, or insights that you find.
-Construct the analysis in textual format; including tables would be great!
-Don't need to synthesize the data, just analyze and provide your findings.
-Always use the provided information, don't make up any information yourself.`;
-  const tools = await lookupTools(["interpreter"]);
-  if (tools.length > 0) {
-    systemPrompt = `${systemPrompt}
-You are able to visualize the financial data using code interpreter tool.
-It's very useful to create and include visualizations in the report. Never include any code in the report, just the visualization.`;
-  }
-  return new FunctionCallingAgent({
-    name: "analyst",
-    tools: tools,
-    chatHistory,
-  });
-};
-
-export const createReporter = async (chatHistory: ChatMessage[]) => {
-  const tools = await lookupTools(["document_generator"]);
-  let systemPrompt = `You are a report generation assistant tasked with producing a well-formatted report given parsed context.
-Given a comprehensive analysis of the user request, your task is to synthesize the information and return a well-formatted report.
-
-## Instructions
-You are responsible for representing the analysis in a well-formatted report. If tables or visualizations are provided, add them to the most relevant sections.
-Finally, the report should be presented in markdown format.`;
-  if (tools.length > 0) {
-    systemPrompt = `${systemPrompt}. 
-You are also able to generate an HTML file of the report.`;
-  }
-  return new FunctionCallingAgent({
-    name: "reporter",
-    tools: tools,
-    systemPrompt: systemPrompt,
-    chatHistory,
-  });
-};

templates/components/agents/typescript/financial_report/factory.ts

@@ -1,159 +0,0 @@
-import {
-  Context,
-  StartEvent,
-  StopEvent,
-  Workflow,
-  WorkflowEvent,
-} from "@llamaindex/core/workflow";
-import { Message } from "ai";
-import { ChatMessage, ChatResponseChunk, Settings } from "llamaindex";
-import { getAnnotations } from "../llamaindex/streaming/annotations";
-import { createAnalyst, createReporter, createResearcher } from "./agents";
-import { AgentInput, AgentRunEvent } from "./type";
-
-const TIMEOUT = 360 * 1000;
-const MAX_ATTEMPTS = 2;
-
-class ResearchEvent extends WorkflowEvent<{ input: string }> {}
-class AnalyzeEvent extends WorkflowEvent<{ input: string }> {}
-class ReportEvent extends WorkflowEvent<{ input: string }> {}
-
-const prepareChatHistory = (chatHistory: Message[]): ChatMessage[] => {
-  // By default, the chat history only contains the assistant and user messages
-  // all the agents messages are stored in annotation data which is not visible to the LLM
-
-  const MAX_AGENT_MESSAGES = 10;
-  const agentAnnotations = getAnnotations<{ agent: string; text: string }>(
-    chatHistory,
-    { role: "assistant", type: "agent" },
-  ).slice(-MAX_AGENT_MESSAGES);
-
-  const agentMessages = agentAnnotations
-    .map(
-      (annotation) =>
-        `\n<${annotation.data.agent}>\n${annotation.data.text}\n</${annotation.data.agent}>`,
-    )
-    .join("\n");
-
-  const agentContent = agentMessages
-    ? "Here is the previous conversation of agents:\n" + agentMessages
-    : "";
-
-  if (agentContent) {
-    const agentMessage: ChatMessage = {
-      role: "assistant",
-      content: agentContent,
-    };
-    return [
-      ...chatHistory.slice(0, -1),
-      agentMessage,
-      chatHistory.slice(-1)[0],
-    ] as ChatMessage[];
-  }
-  return chatHistory as ChatMessage[];
-};
-
-export const createWorkflow = (messages: Message[], params?: any) => {
-  const chatHistoryWithAgentMessages = prepareChatHistory(messages);
-  const runAgent = async (
-    context: Context,
-    agent: Workflow,
-    input: AgentInput,
-  ) => {
-    const run = agent.run(new StartEvent({ input }));
-    for await (const event of agent.streamEvents()) {
-      if (event.data instanceof AgentRunEvent) {
-        context.writeEventToStream(event.data);
-      }
-    }
-    return await run;
-  };
-
-  const start = async (context: Context, ev: StartEvent) => {
-    context.set("task", ev.data.input);
-
-    const chatHistoryStr = chatHistoryWithAgentMessages
-      .map((msg) => `${msg.role}: ${msg.content}`)
-      .join("\n");
-
-    // Decision-making process
-    const decision = await decideWorkflow(ev.data.input, chatHistoryStr);
-
-    if (decision !== "publish") {
-      return new ResearchEvent({
-        input: `Research for this task: ${ev.data.input}`,
-      });
-    } else {
-      return new ReportEvent({
-        input: `Publish content based on the chat history\n${chatHistoryStr}\n\n and task: ${ev.data.input}`,
-      });
-    }
-  };
-
-  const decideWorkflow = async (task: string, chatHistoryStr: string) => {
-    const llm = Settings.llm;
-
-    const prompt = `You are an expert in decision-making, helping people write and publish blog posts.
-If the user is asking for a file or to publish content, respond with 'publish'.
-If the user requests to write or update a blog post, respond with 'not_publish'.
-
-Here is the chat history:
-${chatHistoryStr}
-
-The current user request is:
-${task}
-
-Given the chat history and the new user request, decide whether to publish based on existing information.
-Decision (respond with either 'not_publish' or 'publish'):`;
-
-    const output = await llm.complete({ prompt: prompt });
-    const decision = output.text.trim().toLowerCase();
-    return decision === "publish" ? "publish" : "research";
-  };
-
-  const research = async (context: Context, ev: ResearchEvent) => {
-    const researcher = await createResearcher(
-      chatHistoryWithAgentMessages,
-      params,
-    );
-    const researchRes = await runAgent(context, researcher, {
-      message: ev.data.input,
-    });
-    const researchResult = researchRes.data.result;
-    return new AnalyzeEvent({
-      input: `Write a blog post given this task: ${context.get("task")} using this research content: ${researchResult}`,
-    });
-  };
-
-  const analyze = async (context: Context, ev: AnalyzeEvent) => {
-    const analyst = await createAnalyst(chatHistoryWithAgentMessages);
-    const analyzeRes = await runAgent(context, analyst, {
-      message: ev.data.input,
-    });
-    return new ReportEvent({
-      input: `Publish content based on the chat history\n${analyzeRes.data.result}\n\n and task: ${ev.data.input}`,
-    });
-  };
-
-  const report = async (context: Context, ev: ReportEvent) => {
-    const reporter = await createReporter(chatHistoryWithAgentMessages);
-
-    const reportResult = await runAgent(context, reporter, {
-      message: `${ev.data.input}`,
-      streaming: true,
-    });
-    return reportResult as unknown as StopEvent<
-      AsyncGenerator<ChatResponseChunk>
-    >;
-  };
-
-  const workflow = new Workflow({ timeout: TIMEOUT, validate: true });
-  workflow.addStep(StartEvent, start, {
-    outputs: [ResearchEvent, ReportEvent],
-  });
-  workflow.addStep(ResearchEvent, research, { outputs: AnalyzeEvent });
-  workflow.addStep(AnalyzeEvent, analyze, { outputs: ReportEvent });
-  workflow.addStep(ReportEvent, report, { outputs: StopEvent });
-
-  return workflow;
-};

templates/components/agents/typescript/financial_report/tools.ts

@@ -1,86 +0,0 @@
-import fs from "fs/promises";
-import { BaseToolWithCall, LlamaCloudIndex, QueryEngineTool } from "llamaindex";
-import path from "path";
-import { getDataSource } from "../engine";
-import { createTools } from "../engine/tools/index";
-
-export const getQueryEngineTools = async (
-  params?: any,
-): Promise<QueryEngineTool[] | null> => {
-  const topK = process.env.TOP_K ? parseInt(process.env.TOP_K) : undefined;
-
-  const index = await getDataSource(params);
-  if (!index) {
-    return null;
-  }
-  // index is LlamaCloudIndex use two query engine tools
-  if (index instanceof LlamaCloudIndex) {
-    return [
-      new QueryEngineTool({
-        queryEngine: index.asQueryEngine({
-          similarityTopK: topK,
-          retrieval_mode: "files_via_content",
-        }),
-        metadata: {
-          name: "document_retriever",
-          description: `Document retriever that retrieves entire documents from the corpus.
-  ONLY use for research questions that may require searching over entire research reports.
-  Will be slower and more expensive than chunk-level retrieval but may be necessary.`,
-        },
-      }),
-      new QueryEngineTool({
-        queryEngine: index.asQueryEngine({
-          similarityTopK: topK,
-          retrieval_mode: "chunks",
-        }),
-        metadata: {
-          name: "chunk_retriever",
-          description: `Retrieves a small set of relevant document chunks from the corpus.
-      Use for research questions that want to look up specific facts from the knowledge corpus,
-      and need entire documents.`,
-        },
-      }),
-    ];
-  } else {
-    return [
-      new QueryEngineTool({
-        queryEngine: (index as any).asQueryEngine({
-          similarityTopK: topK,
-        }),
-        metadata: {
-          name: "retriever",
-          description: `Use this tool to retrieve information about the text corpus from the index.`,
-        },
-      }),
-    ];
-  }
-};
-
-export const getAvailableTools = async () => {
-  const configFile = path.join("config", "tools.json");
-  let toolConfig: any;
-  const tools: BaseToolWithCall[] = [];
-  try {
-    toolConfig = JSON.parse(await fs.readFile(configFile, "utf8"));
-  } catch (e) {
-    console.info(`Could not read ${configFile} file. Using no tools.`);
-  }
-  if (toolConfig) {
-    tools.push(...(await createTools(toolConfig)));
-  }
-  const queryEngineTools = await getQueryEngineTools();
-  if (queryEngineTools) {
-    tools.push(...queryEngineTools);
-  }
-
-  return tools;
-};
-
-export const lookupTools = async (
-  toolNames: string[],
-): Promise<BaseToolWithCall[]> => {
-  const availableTools = await getAvailableTools();
-  return availableTools.filter((tool) =>
-    toolNames.includes(tool.metadata.name),
-  );
-};

templates/components/agents/typescript/financial_report/workflow/factory.ts

@@ -0,0 +1,28 @@
+import { ChatMessage, ToolCallLLM } from "llamaindex";
+import { getTool } from "../engine/tools";
+import { FinancialReportWorkflow } from "./fin-report";
+import { getQueryEngineTool } from "./tools";
+
+const TIMEOUT = 360 * 1000;
+
+export async function createWorkflow(options: {
+  chatHistory: ChatMessage[];
+  llm?: ToolCallLLM;
+}) {
+  const queryEngineTool = await getQueryEngineTool();
+  const codeInterpreterTool = await getTool("interpreter");
+  const documentGeneratorTool = await getTool("document_generator");
+
+  if (!queryEngineTool || !codeInterpreterTool || !documentGeneratorTool) {
+    throw new Error("One or more required tools are not defined");
+  }
+
+  return new FinancialReportWorkflow({
+    chatHistory: options.chatHistory,
+    queryEngineTool,
+    codeInterpreterTool,
+    documentGeneratorTool,
+    llm: options.llm,
+    timeout: TIMEOUT,
+  });
+}

templates/components/agents/typescript/financial_report/workflow/fin-report.ts

@@ -0,0 +1,320 @@
+import {
+  HandlerContext,
+  StartEvent,
+  StopEvent,
+  Workflow,
+  WorkflowEvent,
+} from "@llamaindex/workflow";
+import {
+  BaseToolWithCall,
+  ChatMemoryBuffer,
+  ChatMessage,
+  ChatResponseChunk,
+  Settings,
+  ToolCall,
+  ToolCallLLM,
+} from "llamaindex";
+import { callTools, chatWithTools } from "./tools";
+import { AgentInput, AgentRunEvent } from "./type";
+
+// Create a custom event type
+class InputEvent extends WorkflowEvent<{ input: ChatMessage[] }> {}
+
+class ResearchEvent extends WorkflowEvent<{
+  toolCalls: ToolCall[];
+}> {}
+
+class AnalyzeEvent extends WorkflowEvent<{
+  input: ChatMessage | ToolCall[];
+}> {}
+
+class ReportGenerationEvent extends WorkflowEvent<{
+  toolCalls: ToolCall[];
+}> {}
+
+const DEFAULT_SYSTEM_PROMPT = `
+You are a financial analyst who are given a set of tools to help you.
+It's good to using appropriate tools for the user request and always use the information from the tools, don't make up anything yourself.
+For the query engine tool, you should break down the user request into a list of queries and call the tool with the queries.
+`;
+
+export class FinancialReportWorkflow extends Workflow<
+  null,
+  AgentInput,
+  ChatResponseChunk
+> {
+  llm: ToolCallLLM;
+  memory: ChatMemoryBuffer;
+  queryEngineTool: BaseToolWithCall;
+  codeInterpreterTool: BaseToolWithCall;
+  documentGeneratorTool: BaseToolWithCall;
+  systemPrompt?: string;
+
+  constructor(options: {
+    llm?: ToolCallLLM;
+    chatHistory: ChatMessage[];
+    queryEngineTool: BaseToolWithCall;
+    codeInterpreterTool: BaseToolWithCall;
+    documentGeneratorTool: BaseToolWithCall;
+    systemPrompt?: string;
+    verbose?: boolean;
+    timeout?: number;
+  }) {
+    super({
+      verbose: options?.verbose ?? false,
+      timeout: options?.timeout ?? 360,
+    });
+
+    this.llm = options.llm ?? (Settings.llm as ToolCallLLM);
+    if (!(this.llm instanceof ToolCallLLM)) {
+      throw new Error("LLM is not a ToolCallLLM");
+    }
+    this.systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    this.queryEngineTool = options.queryEngineTool;
+    this.codeInterpreterTool = options.codeInterpreterTool;
+
+    this.documentGeneratorTool = options.documentGeneratorTool;
+    this.memory = new ChatMemoryBuffer({
+      llm: this.llm,
+      chatHistory: options.chatHistory,
+    });
+
+    // Add steps
+    this.addStep(
+      {
+        inputs: [StartEvent<AgentInput>],
+        outputs: [InputEvent],
+      },
+      this.prepareChatHistory,
+    );
+
+    this.addStep(
+      {
+        inputs: [InputEvent],
+        outputs: [
+          InputEvent,
+          ResearchEvent,
+          AnalyzeEvent,
+          ReportGenerationEvent,
+          StopEvent,
+        ],
+      },
+      this.handleLLMInput,
+    );
+
+    this.addStep(
+      {
+        inputs: [ResearchEvent],
+        outputs: [AnalyzeEvent],
+      },
+      this.handleResearch,
+    );
+
+    this.addStep(
+      {
+        inputs: [AnalyzeEvent],
+        outputs: [InputEvent],
+      },
+      this.handleAnalyze,
+    );
+
+    this.addStep(
+      {
+        inputs: [ReportGenerationEvent],
+        outputs: [InputEvent],
+      },
+      this.handleReportGeneration,
+    );
+  }
+
+  prepareChatHistory = async (
+    ctx: HandlerContext<null>,
+    ev: StartEvent<AgentInput>,
+  ): Promise<InputEvent> => {
+    const { message } = ev.data;
+
+    if (this.systemPrompt) {
+      this.memory.put({ role: "system", content: this.systemPrompt });
+    }
+    this.memory.put({ role: "user", content: message });
+
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+
+  handleLLMInput = async (
+    ctx: HandlerContext<null>,
+    ev: InputEvent,
+  ): Promise<
+    | InputEvent
+    | ResearchEvent
+    | AnalyzeEvent
+    | ReportGenerationEvent
+    | StopEvent
+  > => {
+    const chatHistory = ev.data.input;
+
+    const tools = [
+      this.codeInterpreterTool,
+      this.documentGeneratorTool,
+      this.queryEngineTool,
+    ];
+
+    const toolCallResponse = await chatWithTools(this.llm, tools, chatHistory);
+
+    if (!toolCallResponse.hasToolCall()) {
+      return new StopEvent(toolCallResponse.responseGenerator);
+    }
+
+    if (toolCallResponse.hasMultipleTools()) {
+      this.memory.put({
+        role: "assistant",
+        content:
+          "Calling different tools is not allowed. Please only use multiple calls of the same tool.",
+      });
+      return new InputEvent({ input: this.memory.getMessages() });
+    }
+
+    // Put the LLM tool call message into the memory
+    // And trigger the next step according to the tool call
+    if (toolCallResponse.toolCallMessage) {
+      this.memory.put(toolCallResponse.toolCallMessage);
+    }
+    const toolName = toolCallResponse.getToolNames()[0];
+    switch (toolName) {
+      case this.codeInterpreterTool.metadata.name:
+        return new AnalyzeEvent({
+          input: toolCallResponse.toolCalls,
+        });
+      case this.documentGeneratorTool.metadata.name:
+        return new ReportGenerationEvent({
+          toolCalls: toolCallResponse.toolCalls,
+        });
+      default:
+        if (this.queryEngineTool.metadata.name === toolName) {
+          return new ResearchEvent({
+            toolCalls: toolCallResponse.toolCalls,
+          });
+        }
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  };
+
+  handleResearch = async (
+    ctx: HandlerContext<null>,
+    ev: ResearchEvent,
+  ): Promise<AnalyzeEvent> => {
+    ctx.sendEvent(
+      new AgentRunEvent({
+        agent: "Researcher",
+        text: "Researching data",
+        type: "text",
+      }),
+    );
+
+    const { toolCalls } = ev.data;
+
+    const toolMsgs = await callTools({
+      tools: [this.queryEngineTool],
+      toolCalls,
+      ctx,
+      agentName: "Researcher",
+    });
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+    return new AnalyzeEvent({
+      input: {
+        role: "assistant",
+        content:
+          "I have finished researching the data, please analyze the data.",
+      },
+    });
+  };
+
+  /**
+   * Analyze a research result or a tool call for code interpreter from the LLM
+   */
+  handleAnalyze = async (
+    ctx: HandlerContext<null>,
+    ev: AnalyzeEvent,
+  ): Promise<InputEvent> => {
+    ctx.sendEvent(
+      new AgentRunEvent({
+        agent: "Analyst",
+        text: `Starting analysis`,
+        type: "text",
+      }),
+    );
+    // Request by workflow LLM, input is a list of tool calls
+    let toolCalls: ToolCall[] = [];
+    if (Array.isArray(ev.data.input)) {
+      toolCalls = ev.data.input;
+    } else {
+      // Requested by Researcher, input is a ChatMessage
+      // We start new LLM chat specifically for analyzing the data
+      const analysisPrompt = `
+      You are an expert in analyzing financial data.
+      You are given a set of financial data to analyze. Your task is to analyze the financial data and return a report.
+      Your response should include a detailed analysis of the financial data, including any trends, patterns, or insights that you find.
+      Construct the analysis in textual format; including tables would be great!
+      Don't need to synthesize the data, just analyze and provide your findings.
+      `;
+
+      // Clone the current chat history
+      // Add the analysis system prompt and the message from the researcher
+      const newChatHistory = [
+        ...this.memory.getMessages(),
+        { role: "system", content: analysisPrompt },
+        ev.data.input,
+      ];
+      const toolCallResponse = await chatWithTools(
+        this.llm,
+        [this.codeInterpreterTool],
+        newChatHistory as ChatMessage[],
+      );
+
+      if (!toolCallResponse.hasToolCall()) {
+        this.memory.put(await toolCallResponse.asFullResponse());
+        return new InputEvent({
+          input: this.memory.getMessages(),
+        });
+      } else {
+        this.memory.put(toolCallResponse.toolCallMessage);
+        toolCalls = toolCallResponse.toolCalls;
+      }
+    }
+
+    // Call the tools
+    const toolMsgs = await callTools({
+      tools: [this.codeInterpreterTool],
+      toolCalls,
+      ctx,
+      agentName: "Analyst",
+    });
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+
+    return new InputEvent({
+      input: this.memory.getMessages(),
+    });
+  };
+
+  handleReportGeneration = async (
+    ctx: HandlerContext<null>,
+    ev: ReportGenerationEvent,
+  ): Promise<InputEvent> => {
+    const { toolCalls } = ev.data;
+
+    const toolMsgs = await callTools({
+      tools: [this.documentGeneratorTool],
+      toolCalls,
+      ctx,
+      agentName: "Reporter",
+    });
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+}

templates/components/agents/typescript/form_filling/README-template.md

@@ -0,0 +1,37 @@
+This is a [LlamaIndex](https://www.llamaindex.ai/) project using [Next.js](https://nextjs.org/) bootstrapped with [`create-llama`](https://github.com/run-llama/LlamaIndexTS/tree/main/packages/create-llama).
+
+## Getting Started
+
+First, install the dependencies:
+
+```
+npm install
+```
+
+Then check the parameters that have been pre-configured in the `.env` file in this directory.
+Make sure you have the `OPENAI_API_KEY` set.
+
+Second, run the development server:
+
+```
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the chat UI.
+
+## Use Case: Filling Financial CSV Template
+
+1. Upload the Apple and Tesla financial reports from the [data](./data) directory. Just send an empty message.
+2. Upload the CSV file [sec_10k_template.csv](./sec_10k_template.csv) and send the message "Fill the missing cells in the CSV file".
+
+The agent will fill the missing cells by retrieving the information from the uploaded financial reports and return a new CSV file with the filled cells.
+
+## Learn More
+
+To learn more about LlamaIndex, take a look at the following resources:
+
+- [LlamaIndex Documentation](https://docs.llamaindex.ai) - learn about LlamaIndex (Python features).
+- [LlamaIndexTS Documentation](https://ts.llamaindex.ai/docs/llamaindex) - learn about LlamaIndex (Typescript features).
+- [Workflows Introduction](https://ts.llamaindex.ai/docs/llamaindex/guide/workflow) - learn about LlamaIndexTS workflows.
+
+You can check out [the LlamaIndexTS GitHub repository](https://github.com/run-llama/LlamaIndexTS) - your feedback and contributions are welcome!

templates/components/agents/typescript/form_filling/sec_10k_template.csv

@@ -0,0 +1,17 @@
+Parameter,2023 Apple (AAPL),2023 Tesla (TSLA)
+Revenue,,
+Net Income,,
+Earnings Per Share (EPS),,
+Debt-to-Equity Ratio,,
+Current Ratio,,
+Gross Margin,,
+Operating Margin,,
+Net Profit Margin,,
+Inventory Turnover,,
+Accounts Receivable Turnover,,
+Capital Expenditure,,
+Research and Development Expense,,
+Market Cap,,
+Price to Earnings Ratio,,
+Dividend Yield,,
+Year-over-Year Growth Rate,,

templates/components/agents/typescript/form_filling/workflow/factory.ts

@@ -0,0 +1,27 @@
+import { ChatMessage, ToolCallLLM } from "llamaindex";
+import { getTool } from "../engine/tools";
+import { FormFillingWorkflow } from "./form-filling";
+import { getQueryEngineTool } from "./tools";
+
+const TIMEOUT = 360 * 1000;
+
+export async function createWorkflow(options: {
+  chatHistory: ChatMessage[];
+  llm?: ToolCallLLM;
+}) {
+  const extractorTool = await getTool("extract_missing_cells");
+  const fillMissingCellsTool = await getTool("fill_missing_cells");
+
+  if (!extractorTool || !fillMissingCellsTool) {
+    throw new Error("One or more required tools are not defined");
+  }
+
+  return new FormFillingWorkflow({
+    chatHistory: options.chatHistory,
+    queryEngineTool: (await getQueryEngineTool()) || undefined,
+    extractorTool,
+    fillMissingCellsTool,
+    llm: options.llm,
+    timeout: TIMEOUT,
+  });
+}

templates/components/agents/typescript/form_filling/workflow/form-filling.ts

@@ -0,0 +1,275 @@
+import {
+  HandlerContext,
+  StartEvent,
+  StopEvent,
+  Workflow,
+  WorkflowEvent,
+} from "@llamaindex/workflow";
+import {
+  BaseToolWithCall,
+  ChatMemoryBuffer,
+  ChatMessage,
+  ChatResponseChunk,
+  Settings,
+  ToolCall,
+  ToolCallLLM,
+} from "llamaindex";
+import { callTools, chatWithTools } from "./tools";
+import { AgentInput, AgentRunEvent } from "./type";
+
+// Create a custom event type
+class InputEvent extends WorkflowEvent<{ input: ChatMessage[] }> {}
+
+class ExtractMissingCellsEvent extends WorkflowEvent<{
+  toolCalls: ToolCall[];
+}> {}
+
+class FindAnswersEvent extends WorkflowEvent<{
+  toolCalls: ToolCall[];
+}> {}
+
+class FillMissingCellsEvent extends WorkflowEvent<{
+  toolCalls: ToolCall[];
+}> {}
+
+const DEFAULT_SYSTEM_PROMPT = `
+You are a helpful assistant who helps fill missing cells in a CSV file.
+Only use the information from the retriever tool - don't make up any information yourself. Fill N/A if an answer is not found.
+If there is no retriever tool or the gathered information has many N/A values indicating the questions don't match the data, respond with a warning and ask the user to upload a different file or connect to a knowledge base.
+You can make multiple tool calls at once but only call with the same tool.
+Only use the local file path for the tools.
+`;
+
+export class FormFillingWorkflow extends Workflow<
+  null,
+  AgentInput,
+  ChatResponseChunk
+> {
+  llm: ToolCallLLM;
+  memory: ChatMemoryBuffer;
+  extractorTool: BaseToolWithCall;
+  queryEngineTool?: BaseToolWithCall;
+  fillMissingCellsTool: BaseToolWithCall;
+  systemPrompt?: string;
+
+  constructor(options: {
+    llm?: ToolCallLLM;
+    chatHistory: ChatMessage[];
+    extractorTool: BaseToolWithCall;
+    queryEngineTool?: BaseToolWithCall;
+    fillMissingCellsTool: BaseToolWithCall;
+    systemPrompt?: string;
+    verbose?: boolean;
+    timeout?: number;
+  }) {
+    super({
+      verbose: options?.verbose ?? false,
+      timeout: options?.timeout ?? 360,
+    });
+
+    this.llm = options.llm ?? (Settings.llm as ToolCallLLM);
+    if (!(this.llm instanceof ToolCallLLM)) {
+      throw new Error("LLM is not a ToolCallLLM");
+    }
+    this.systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    this.extractorTool = options.extractorTool;
+    this.queryEngineTool = options.queryEngineTool;
+    this.fillMissingCellsTool = options.fillMissingCellsTool;
+
+    this.memory = new ChatMemoryBuffer({
+      llm: this.llm,
+      chatHistory: options.chatHistory,
+    });
+
+    // Add steps
+    this.addStep(
+      {
+        inputs: [StartEvent<AgentInput>],
+        outputs: [InputEvent],
+      },
+      this.prepareChatHistory,
+    );
+
+    this.addStep(
+      {
+        inputs: [InputEvent],
+        outputs: [
+          InputEvent,
+          ExtractMissingCellsEvent,
+          FindAnswersEvent,
+          FillMissingCellsEvent,
+          StopEvent,
+        ],
+      },
+      this.handleLLMInput,
+    );
+
+    this.addStep(
+      {
+        inputs: [ExtractMissingCellsEvent],
+        outputs: [InputEvent],
+      },
+      this.handleExtractMissingCells,
+    );
+
+    this.addStep(
+      {
+        inputs: [FindAnswersEvent],
+        outputs: [InputEvent],
+      },
+      this.handleFindAnswers,
+    );
+
+    this.addStep(
+      {
+        inputs: [FillMissingCellsEvent],
+        outputs: [InputEvent],
+      },
+      this.handleFillMissingCells,
+    );
+  }
+
+  prepareChatHistory = async (
+    ctx: HandlerContext<null>,
+    ev: StartEvent<AgentInput>,
+  ): Promise<InputEvent> => {
+    const { message } = ev.data;
+
+    if (this.systemPrompt) {
+      this.memory.put({ role: "system", content: this.systemPrompt });
+    }
+    this.memory.put({ role: "user", content: message });
+
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+
+  handleLLMInput = async (
+    ctx: HandlerContext<null>,
+    ev: InputEvent,
+  ): Promise<
+    | InputEvent
+    | ExtractMissingCellsEvent
+    | FindAnswersEvent
+    | FillMissingCellsEvent
+    | StopEvent
+  > => {
+    const chatHistory = ev.data.input;
+
+    const tools = [this.extractorTool, this.fillMissingCellsTool];
+    if (this.queryEngineTool) {
+      tools.push(this.queryEngineTool);
+    }
+
+    const toolCallResponse = await chatWithTools(this.llm, tools, chatHistory);
+
+    if (!toolCallResponse.hasToolCall()) {
+      return new StopEvent(toolCallResponse.responseGenerator);
+    }
+
+    if (toolCallResponse.hasMultipleTools()) {
+      this.memory.put({
+        role: "assistant",
+        content:
+          "Calling different tools is not allowed. Please only use multiple calls of the same tool.",
+      });
+      return new InputEvent({ input: this.memory.getMessages() });
+    }
+
+    // Put the LLM tool call message into the memory
+    // And trigger the next step according to the tool call
+    if (toolCallResponse.toolCallMessage) {
+      this.memory.put(toolCallResponse.toolCallMessage);
+    }
+    const toolName = toolCallResponse.getToolNames()[0];
+    switch (toolName) {
+      case this.extractorTool.metadata.name:
+        return new ExtractMissingCellsEvent({
+          toolCalls: toolCallResponse.toolCalls,
+        });
+      case this.fillMissingCellsTool.metadata.name:
+        return new FillMissingCellsEvent({
+          toolCalls: toolCallResponse.toolCalls,
+        });
+      default:
+        if (
+          this.queryEngineTool &&
+          this.queryEngineTool.metadata.name === toolName
+        ) {
+          return new FindAnswersEvent({
+            toolCalls: toolCallResponse.toolCalls,
+          });
+        }
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  };
+
+  handleExtractMissingCells = async (
+    ctx: HandlerContext<null>,
+    ev: ExtractMissingCellsEvent,
+  ): Promise<InputEvent> => {
+    ctx.sendEvent(
+      new AgentRunEvent({
+        agent: "CSVExtractor",
+        text: "Extracting missing cells",
+        type: "text",
+      }),
+    );
+    const { toolCalls } = ev.data;
+    const toolMsgs = await callTools({
+      tools: [this.extractorTool],
+      toolCalls,
+      ctx,
+      agentName: "CSVExtractor",
+    });
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+
+  handleFindAnswers = async (
+    ctx: HandlerContext<null>,
+    ev: FindAnswersEvent,
+  ): Promise<InputEvent> => {
+    const { toolCalls } = ev.data;
+    if (!this.queryEngineTool) {
+      throw new Error("Query engine tool is not available");
+    }
+    ctx.sendEvent(
+      new AgentRunEvent({
+        agent: "Researcher",
+        text: "Finding answers",
+        type: "text",
+      }),
+    );
+    const toolMsgs = await callTools({
+      tools: [this.queryEngineTool],
+      toolCalls,
+      ctx,
+      agentName: "Researcher",
+    });
+
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+
+  handleFillMissingCells = async (
+    ctx: HandlerContext<null>,
+    ev: FillMissingCellsEvent,
+  ): Promise<InputEvent> => {
+    const { toolCalls } = ev.data;
+
+    const toolMsgs = await callTools({
+      tools: [this.fillMissingCellsTool],
+      toolCalls,
+      ctx,
+      agentName: "Processor",
+    });
+    for (const toolMsg of toolMsgs) {
+      this.memory.put(toolMsg);
+    }
+    return new InputEvent({ input: this.memory.getMessages() });
+  };
+}

templates/components/engines/python/agent/engine.py

@@ -1,18 +1,18 @@
 import os
 from typing import List
 
-from app.engine.index import IndexConfig, get_index
-from app.engine.tools import ToolFactory
 from llama_index.core.agent import AgentRunner
 from llama_index.core.callbacks import CallbackManager
 from llama_index.core.settings import Settings
 from llama_index.core.tools import BaseTool
-from llama_index.core.tools.query_engine import QueryEngineTool
+
+from app.engine.index import IndexConfig, get_index
+from app.engine.tools import ToolFactory
+from app.engine.tools.query_engine import get_query_engine_tool
 
 
-def get_chat_engine(filters=None, params=None, event_handlers=None, **kwargs):
+def get_chat_engine(params=None, event_handlers=None, **kwargs):
     system_prompt = os.getenv("SYSTEM_PROMPT")
-    top_k = int(os.getenv("TOP_K", 0))
     tools: List[BaseTool] = []
     callback_manager = CallbackManager(handlers=event_handlers or [])
 
@@ -20,10 +20,7 @@ def get_chat_engine(filters=None, params=None, event_handlers=None, **kwargs):
     index_config = IndexConfig(callback_manager=callback_manager, **(params or {}))
     index = get_index(index_config)
     if index is not None:
-        query_engine = index.as_query_engine(
-            filters=filters, **({"similarity_top_k": top_k} if top_k != 0 else {})
-        )
-        query_engine_tool = QueryEngineTool.from_defaults(query_engine=query_engine)
+        query_engine_tool = get_query_engine_tool(index, **kwargs)
         tools.append(query_engine_tool)
 
     # Add additional tools

templates/components/engines/python/agent/tools/interpreter.py

@@ -5,7 +5,7 @@ import uuid
 from typing import List, Optional
 
 from app.services.file import DocumentFile, FileService
-from e2b_code_interpreter import CodeInterpreter
+from e2b_code_interpreter import Sandbox
 from e2b_code_interpreter.models import Logs
 from llama_index.core.tools import FunctionTool
 from pydantic import BaseModel
@@ -61,7 +61,7 @@ class E2BCodeInterpreter:
         Lazily initialize the interpreter.
         """
         logger.info(f"Initializing interpreter with {len(sandbox_files)} files")
-        self.interpreter = CodeInterpreter(api_key=self.api_key)
+        self.interpreter = Sandbox(api_key=self.api_key)
         if len(sandbox_files) > 0:
             for file_path in sandbox_files:
                 file_name = os.path.basename(file_path)
@@ -159,11 +159,11 @@ class E2BCodeInterpreter:
         if self.interpreter is None:
             self._init_interpreter(sandbox_files)
 
-        if self.interpreter and self.interpreter.notebook:
+        if self.interpreter:
             logger.info(
                 f"\n{'='*50}\n> Running following AI-generated code:\n{code}\n{'='*50}"
             )
-            exec = self.interpreter.notebook.exec_cell(code)
+            exec = self.interpreter.run_code(code)
 
             if exec.error:
                 error_message = f"The code failed to execute successfully. Error: {exec.error}. Try to fix the code and run again."

templates/components/engines/python/agent/tools/query_engine.py

@@ -0,0 +1,187 @@
+import os
+from typing import Any, Dict, List, Optional, Sequence
+
+from llama_index.core import get_response_synthesizer
+from llama_index.core.base.base_query_engine import BaseQueryEngine
+from llama_index.core.base.response.schema import RESPONSE_TYPE, Response
+from llama_index.core.multi_modal_llms import MultiModalLLM
+from llama_index.core.prompts.base import BasePromptTemplate
+from llama_index.core.prompts.default_prompt_selectors import (
+    DEFAULT_TEXT_QA_PROMPT_SEL,
+)
+from llama_index.core.query_engine.multi_modal import _get_image_and_text_nodes
+from llama_index.core.response_synthesizers.base import BaseSynthesizer, QueryTextType
+from llama_index.core.schema import (
+    ImageNode,
+    NodeWithScore,
+)
+from llama_index.core.tools.query_engine import QueryEngineTool
+from llama_index.core.types import RESPONSE_TEXT_TYPE
+
+from app.settings import get_multi_modal_llm
+
+
+def create_query_engine(index, **kwargs) -> BaseQueryEngine:
+    """
+    Create a query engine for the given index.
+
+    Args:
+        index: The index to create a query engine for.
+        params (optional): Additional parameters for the query engine, e.g: similarity_top_k
+    """
+
+    top_k = int(os.getenv("TOP_K", 0))
+    if top_k != 0 and kwargs.get("filters") is None:
+        kwargs["similarity_top_k"] = top_k
+    multimodal_llm = get_multi_modal_llm()
+    if multimodal_llm:
+        kwargs["response_synthesizer"] = MultiModalSynthesizer(
+            multimodal_model=multimodal_llm,
+        )
+
+    # If index is index is LlamaCloudIndex
+    # use auto_routed mode for better query results
+    if index.__class__.__name__ == "LlamaCloudIndex":
+        if kwargs.get("retrieval_mode") is None:
+            kwargs["retrieval_mode"] = "auto_routed"
+        if multimodal_llm:
+            kwargs["retrieve_image_nodes"] = True
+    return index.as_query_engine(**kwargs)
+
+
+def get_query_engine_tool(
+    index,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    **kwargs,
+) -> QueryEngineTool:
+    """
+    Get a query engine tool for the given index.
+
+    Args:
+        index: The index to create a query engine for.
+        name (optional): The name of the tool.
+        description (optional): The description of the tool.
+    """
+    if name is None:
+        name = "query_index"
+    if description is None:
+        description = (
+            "Use this tool to retrieve information about the text corpus from an index."
+        )
+    query_engine = create_query_engine(index, **kwargs)
+    return QueryEngineTool.from_defaults(
+        query_engine=query_engine,
+        name=name,
+        description=description,
+    )
+
+
+class MultiModalSynthesizer(BaseSynthesizer):
+    """
+    A synthesizer that summarizes text nodes and uses a multi-modal LLM to generate a response.
+    """
+
+    def __init__(
+        self,
+        multimodal_model: MultiModalLLM,
+        response_synthesizer: Optional[BaseSynthesizer] = None,
+        text_qa_template: Optional[BasePromptTemplate] = None,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self._multi_modal_llm = multimodal_model
+        self._response_synthesizer = response_synthesizer or get_response_synthesizer()
+        self._text_qa_template = text_qa_template or DEFAULT_TEXT_QA_PROMPT_SEL
+
+    def _get_prompts(self, **kwargs) -> Dict[str, Any]:
+        return {
+            "text_qa_template": self._text_qa_template,
+        }
+
+    def _update_prompts(self, prompts: Dict[str, Any]) -> None:
+        if "text_qa_template" in prompts:
+            self._text_qa_template = prompts["text_qa_template"]
+
+    async def aget_response(
+        self,
+        *args,
+        **response_kwargs: Any,
+    ) -> RESPONSE_TEXT_TYPE:
+        return await self._response_synthesizer.aget_response(*args, **response_kwargs)
+
+    def get_response(self, *args, **kwargs) -> RESPONSE_TEXT_TYPE:
+        return self._response_synthesizer.get_response(*args, **kwargs)
+
+    async def asynthesize(
+        self,
+        query: QueryTextType,
+        nodes: List[NodeWithScore],
+        additional_source_nodes: Optional[Sequence[NodeWithScore]] = None,
+        **response_kwargs: Any,
+    ) -> RESPONSE_TYPE:
+        image_nodes, text_nodes = _get_image_and_text_nodes(nodes)
+
+        if len(image_nodes) == 0:
+            return await self._response_synthesizer.asynthesize(query, text_nodes)
+
+        # Summarize the text nodes to avoid exceeding the token limit
+        text_response = str(
+            await self._response_synthesizer.asynthesize(query, text_nodes)
+        )
+
+        fmt_prompt = self._text_qa_template.format(
+            context_str=text_response,
+            query_str=query.query_str,  # type: ignore
+        )
+
+        llm_response = await self._multi_modal_llm.acomplete(
+            prompt=fmt_prompt,
+            image_documents=[
+                image_node.node
+                for image_node in image_nodes
+                if isinstance(image_node.node, ImageNode)
+            ],
+        )
+
+        return Response(
+            response=str(llm_response),
+            source_nodes=nodes,
+            metadata={"text_nodes": text_nodes, "image_nodes": image_nodes},
+        )
+
+    def synthesize(
+        self,
+        query: QueryTextType,
+        nodes: List[NodeWithScore],
+        additional_source_nodes: Optional[Sequence[NodeWithScore]] = None,
+        **response_kwargs: Any,
+    ) -> RESPONSE_TYPE:
+        image_nodes, text_nodes = _get_image_and_text_nodes(nodes)
+
+        if len(image_nodes) == 0:
+            return self._response_synthesizer.synthesize(query, text_nodes)
+
+        # Summarize the text nodes to avoid exceeding the token limit
+        text_response = str(self._response_synthesizer.synthesize(query, text_nodes))
+
+        fmt_prompt = self._text_qa_template.format(
+            context_str=text_response,
+            query_str=query.query_str,  # type: ignore
+        )
+
+        llm_response = self._multi_modal_llm.complete(
+            prompt=fmt_prompt,
+            image_documents=[
+                image_node.node
+                for image_node in image_nodes
+                if isinstance(image_node.node, ImageNode)
+            ],
+        )
+
+        return Response(
+            response=str(llm_response),
+            source_nodes=nodes,
+            metadata={"text_nodes": text_nodes, "image_nodes": image_nodes},
+        )

templates/components/engines/python/chat/engine.py

@@ -9,7 +9,7 @@ from llama_index.core.memory import ChatMemoryBuffer
 from llama_index.core.settings import Settings
 
 
-def get_chat_engine(filters=None, params=None, event_handlers=None, **kwargs):
+def get_chat_engine(params=None, event_handlers=None, **kwargs):
     system_prompt = os.getenv("SYSTEM_PROMPT")
     citation_prompt = os.getenv("SYSTEM_CITATION_PROMPT", None)
     top_k = int(os.getenv("TOP_K", 0))
@@ -33,10 +33,9 @@ def get_chat_engine(filters=None, params=None, event_handlers=None, **kwargs):
                 "StorageContext is empty - call 'poetry run generate' to generate the storage first"
             ),
         )
-
-    retriever = index.as_retriever(
-        filters=filters, **({"similarity_top_k": top_k} if top_k != 0 else {})
-    )
+    if top_k != 0 and kwargs.get("similarity_top_k") is None:
+        kwargs["similarity_top_k"] = top_k
+    retriever = index.as_retriever(**kwargs)
 
     return CondensePlusContextChatEngine(
         llm=llm,

templates/components/engines/typescript/agent/chat.ts

@@ -1,14 +1,9 @@
-import {
-  BaseChatEngine,
-  BaseToolWithCall,
-  OpenAIAgent,
-  QueryEngineTool,
-} from "llamaindex";
+import { BaseChatEngine, BaseToolWithCall, LLMAgent } from "llamaindex";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getDataSource } from "./index";
-import { generateFilters } from "./queryFilter";
 import { createTools } from "./tools";
+import { createQueryEngineTool } from "./tools/query-engine";
 
 export async function createChatEngine(documentIds?: string[], params?: any) {
   const tools: BaseToolWithCall[] = [];
@@ -17,17 +12,7 @@ export async function createChatEngine(documentIds?: string[], params?: any) {
   // Delete this code if you don't have a data source
   const index = await getDataSource(params);
   if (index) {
-    tools.push(
-      new QueryEngineTool({
-        queryEngine: index.asQueryEngine({
-          preFilters: generateFilters(documentIds || []),
-        }),
-        metadata: {
-          name: "data_query_engine",
-          description: `A query engine for documents from your data source.`,
-        },
-      }),
-    );
+    tools.push(createQueryEngineTool(index, { documentIds }));
   }
 
   const configFile = path.join("config", "tools.json");
@@ -42,7 +27,7 @@ export async function createChatEngine(documentIds?: string[], params?: any) {
     tools.push(...(await createTools(toolConfig)));
   }
 
-  const agent = new OpenAIAgent({
+  const agent = new LLMAgent({
     tools,
     systemPrompt: process.env.SYSTEM_PROMPT,
   }) as unknown as BaseChatEngine;

templates/components/engines/typescript/agent/tools/code-generator.ts

@@ -103,6 +103,7 @@ export class CodeGeneratorTool implements BaseTool<CodeGeneratorParameter> {
       const artifact = await this.generateArtifact(
         input.requirement,
         input.oldCode,
+        input.sandboxFiles, // help the generated code use exact files
       );
       if (input.sandboxFiles) {
         artifact.files = input.sandboxFiles;
@@ -117,10 +118,12 @@ export class CodeGeneratorTool implements BaseTool<CodeGeneratorParameter> {
   async generateArtifact(
     query: string,
     oldCode?: string,
+    attachments?: string[],
   ): Promise<CodeArtifact> {
     const userMessage = `
     ${query}
     ${oldCode ? `The existing code is: \n\`\`\`${oldCode}\`\`\`` : ""}
+    ${attachments ? `The attachments are: \n${attachments.join("\n")}` : ""}
     `;
     const messages: ChatMessage[] = [
       { role: "system", content: CODE_GENERATION_PROMPT },

templates/components/engines/typescript/agent/tools/form-filling.ts

@@ -0,0 +1,296 @@
+import { JSONSchemaType } from "ajv";
+import fs from "fs";
+import { BaseTool, Settings, ToolMetadata } from "llamaindex";
+import Papa from "papaparse";
+import path from "path";
+import { saveDocument } from "../../llamaindex/documents/helper";
+
+type ExtractMissingCellsParameter = {
+  filePath: string;
+};
+
+export type MissingCell = {
+  rowIndex: number;
+  columnIndex: number;
+  question: string;
+};
+
+const CSV_EXTRACTION_PROMPT = `You are a data analyst. You are given a table with missing cells.
+Your task is to identify the missing cells and the questions needed to fill them.
+IMPORTANT: Column indices should be 0-based
+
+# Instructions:
+- Understand the entire content of the table and the topics of the table.
+- Identify the missing cells and the meaning of the data in the cells.
+- For each missing cell, provide the row index and the correct column index (remember: first data column is 1).
+- For each missing cell, provide the question needed to fill the cell (it's important to provide the question that is relevant to the topic of the table).
+- Since the cell's value should be concise, the question should request a numerical answer or a specific value.
+- Finally, only return the answer in JSON format with the following schema:
+{
+  "missing_cells": [
+    {
+      "rowIndex": number,
+      "columnIndex": number,
+      "question": string
+    }
+  ]
+}
+- If there are no missing cells, return an empty array.
+- The answer is only the JSON object, nothing else and don't wrap it inside markdown code block.
+
+# Example:
+# |    | Name | Age | City |
+# |----|------|-----|------|
+# | 0  | John |     | Paris|
+# | 1  | Mary |     |      |
+# | 2  |      | 30  |      |
+#
+# Your thoughts:
+# - The table is about people's names, ages, and cities.
+# - Row: 1, Column: 2 (Age column), Question: "How old is Mary? Please provide only the numerical answer."
+# - Row: 1, Column: 3 (City column), Question: "In which city does Mary live? Please provide only the city name."
+# Your answer:
+# {
+#   "missing_cells": [
+#     {
+#       "rowIndex": 1,
+#       "columnIndex": 2,
+#       "question": "How old is Mary? Please provide only the numerical answer."
+#     },
+#     {
+#       "rowIndex": 1,
+#       "columnIndex": 3,
+#       "question": "In which city does Mary live? Please provide only the city name."
+#     }
+#   ]
+# }
+
+
+# Here is your task:
+
+- Table content:
+{table_content}
+
+- Your answer:
+`;
+
+const DEFAULT_METADATA: ToolMetadata<
+  JSONSchemaType<ExtractMissingCellsParameter>
+> = {
+  name: "extract_missing_cells",
+  description: `Use this tool to extract missing cells in a CSV file and generate questions to fill them. This tool only works with local file path.`,
+  parameters: {
+    type: "object",
+    properties: {
+      filePath: {
+        type: "string",
+        description: "The local file path to the CSV file.",
+      },
+    },
+    required: ["filePath"],
+  },
+};
+
+export interface ExtractMissingCellsParams {
+  metadata?: ToolMetadata<JSONSchemaType<ExtractMissingCellsParameter>>;
+}
+
+export class ExtractMissingCellsTool
+  implements BaseTool<ExtractMissingCellsParameter>
+{
+  metadata: ToolMetadata<JSONSchemaType<ExtractMissingCellsParameter>>;
+  defaultExtractionPrompt: string;
+
+  constructor(params: ExtractMissingCellsParams) {
+    this.metadata = params.metadata ?? DEFAULT_METADATA;
+    this.defaultExtractionPrompt = CSV_EXTRACTION_PROMPT;
+  }
+
+  private readCsvFile(filePath: string): Promise<string[][]> {
+    return new Promise((resolve, reject) => {
+      fs.readFile(filePath, "utf8", (err, data) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+
+        const parsedData = Papa.parse<string[]>(data, {
+          skipEmptyLines: false,
+        });
+
+        if (parsedData.errors.length) {
+          reject(parsedData.errors);
+          return;
+        }
+
+        // Ensure all rows have the same number of columns as the header
+        const maxColumns = parsedData.data[0].length;
+        const paddedRows = parsedData.data.map((row) => {
+          return [...row, ...Array(maxColumns - row.length).fill("")];
+        });
+
+        resolve(paddedRows);
+      });
+    });
+  }
+
+  private formatToMarkdownTable(data: string[][]): string {
+    if (data.length === 0) return "";
+
+    const maxColumns = data[0].length;
+
+    const headerRow = `| ${data[0].join(" | ")} |`;
+    const separatorRow = `| ${Array(maxColumns).fill("---").join(" | ")} |`;
+
+    const dataRows = data.slice(1).map((row) => {
+      return `| ${row.join(" | ")} |`;
+    });
+
+    return [headerRow, separatorRow, ...dataRows].join("\n");
+  }
+
+  async call(input: ExtractMissingCellsParameter): Promise<MissingCell[]> {
+    const { filePath } = input;
+    let tableContent: string[][];
+    try {
+      tableContent = await this.readCsvFile(filePath);
+    } catch (error) {
+      throw new Error(
+        `Failed to read CSV file. Make sure that you are reading a local file path (not a sandbox path).`,
+      );
+    }
+
+    const prompt = this.defaultExtractionPrompt.replace(
+      "{table_content}",
+      this.formatToMarkdownTable(tableContent),
+    );
+
+    const llm = Settings.llm;
+    const response = await llm.complete({
+      prompt,
+    });
+    const rawAnswer = response.text;
+    const parsedResponse = JSON.parse(rawAnswer) as {
+      missing_cells: MissingCell[];
+    };
+    if (!parsedResponse.missing_cells) {
+      throw new Error(
+        "The answer is not in the correct format. There should be a missing_cells array.",
+      );
+    }
+    const answer = parsedResponse.missing_cells;
+
+    return answer;
+  }
+}
+
+type FillMissingCellsParameter = {
+  filePath: string;
+  cells: {
+    rowIndex: number;
+    columnIndex: number;
+    answer: string;
+  }[];
+};
+
+const FILL_CELLS_METADATA: ToolMetadata<
+  JSONSchemaType<FillMissingCellsParameter>
+> = {
+  name: "fill_missing_cells",
+  description: `Use this tool to fill missing cells in a CSV file with provided answers. This tool only works with local file path.`,
+  parameters: {
+    type: "object",
+    properties: {
+      filePath: {
+        type: "string",
+        description: "The local file path to the CSV file.",
+      },
+      cells: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            rowIndex: { type: "number" },
+            columnIndex: { type: "number" },
+            answer: { type: "string" },
+          },
+          required: ["rowIndex", "columnIndex", "answer"],
+        },
+        description: "Array of cells to fill with their answers",
+      },
+    },
+    required: ["filePath", "cells"],
+  },
+};
+
+export interface FillMissingCellsParams {
+  metadata?: ToolMetadata<JSONSchemaType<FillMissingCellsParameter>>;
+}
+
+export class FillMissingCellsTool
+  implements BaseTool<FillMissingCellsParameter>
+{
+  metadata: ToolMetadata<JSONSchemaType<FillMissingCellsParameter>>;
+
+  constructor(params: FillMissingCellsParams = {}) {
+    this.metadata = params.metadata ?? FILL_CELLS_METADATA;
+  }
+
+  async call(input: FillMissingCellsParameter): Promise<string> {
+    const { filePath, cells } = input;
+
+    // Read the CSV file
+    const fileContent = await new Promise<string>((resolve, reject) => {
+      fs.readFile(filePath, "utf8", (err, data) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(data);
+        }
+      });
+    });
+
+    // Parse CSV with PapaParse
+    const parseResult = Papa.parse<string[]>(fileContent, {
+      header: false, // Ensure the header is not treated as a separate object
+      skipEmptyLines: false, // Ensure empty lines are not skipped
+    });
+
+    if (parseResult.errors.length) {
+      throw new Error(
+        "Failed to parse CSV file: " + parseResult.errors[0].message,
+      );
+    }
+
+    const rows = parseResult.data;
+
+    // Fill the cells with answers
+    for (const cell of cells) {
+      // Adjust rowIndex to start from 1 for data rows
+      const adjustedRowIndex = cell.rowIndex + 1;
+      if (
+        adjustedRowIndex < rows.length &&
+        cell.columnIndex < rows[adjustedRowIndex].length
+      ) {
+        rows[adjustedRowIndex][cell.columnIndex] = cell.answer;
+      }
+    }
+
+    // Convert back to CSV format
+    const updatedContent = Papa.unparse(rows, {
+      delimiter: parseResult.meta.delimiter,
+    });
+
+    // Use the helper function to write the file
+    const parsedPath = path.parse(filePath);
+    const newFileName = `${parsedPath.name}-filled${parsedPath.ext}`;
+    const newFilePath = path.join("output/tools", newFileName);
+
+    const newFileUrl = await saveDocument(newFilePath, updatedContent);
+
+    return (
+      "Successfully filled missing cells in the CSV file. File URL to show to the user: " +
+      newFileUrl
+    );
+  }
+}

templates/components/engines/typescript/agent/tools/index.ts

@@ -1,11 +1,19 @@
 import { BaseToolWithCall } from "llamaindex";
 import { ToolsFactory } from "llamaindex/tools/ToolsFactory";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { CodeGeneratorTool, CodeGeneratorToolParams } from "./code-generator";
 import {
   DocumentGenerator,
   DocumentGeneratorParams,
 } from "./document-generator";
 import { DuckDuckGoSearchTool, DuckDuckGoToolParams } from "./duckduckgo";
+import {
+  ExtractMissingCellsParams,
+  ExtractMissingCellsTool,
+  FillMissingCellsParams,
+  FillMissingCellsTool,
+} from "./form-filling";
 import { ImgGeneratorTool, ImgGeneratorToolParams } from "./img-gen";
 import { InterpreterTool, InterpreterToolParams } from "./interpreter";
 import { OpenAPIActionTool } from "./openapi-action";
@@ -54,6 +62,12 @@ const toolFactory: Record<string, ToolCreator> = {
   document_generator: async (config: unknown) => {
     return [new DocumentGenerator(config as DocumentGeneratorParams)];
   },
+  form_filling: async (config: unknown) => {
+    return [
+      new ExtractMissingCellsTool(config as ExtractMissingCellsParams),
+      new FillMissingCellsTool(config as FillMissingCellsParams),
+    ];
+  },
 };
 
 async function createLocalTools(
@@ -70,3 +84,19 @@ async function createLocalTools(
 
   return tools;
 }
+
+export async function getConfiguredTools(
+  configPath?: string,
+): Promise<BaseToolWithCall[]> {
+  const configFile = path.join(configPath ?? "config", "tools.json");
+  const toolConfig = JSON.parse(await fs.readFile(configFile, "utf8"));
+  const tools = await createTools(toolConfig);
+  return tools;
+}
+
+export async function getTool(
+  toolName: string,
+): Promise<BaseToolWithCall | undefined> {
+  const tools = await getConfiguredTools();
+  return tools.find((tool) => tool.metadata.name === toolName);
+}

templates/components/engines/typescript/agent/tools/interpreter.ts

@@ -1,4 +1,4 @@
-import { CodeInterpreter, Logs, Result } from "@e2b/code-interpreter";
+import { Logs, Result, Sandbox } from "@e2b/code-interpreter";
 import type { JSONSchemaType } from "ajv";
 import fs from "fs";
 import { BaseTool, ToolMetadata } from "llamaindex";
@@ -82,7 +82,7 @@ export class InterpreterTool implements BaseTool<InterpreterParameter> {
   private apiKey?: string;
   private fileServerURLPrefix?: string;
   metadata: ToolMetadata<JSONSchemaType<InterpreterParameter>>;
-  codeInterpreter?: CodeInterpreter;
+  codeInterpreter?: Sandbox;
 
   constructor(params?: InterpreterToolParams) {
     this.metadata = params?.metadata || DEFAULT_META_DATA;
@@ -104,24 +104,27 @@ export class InterpreterTool implements BaseTool<InterpreterParameter> {
 
   public async initInterpreter(input: InterpreterParameter) {
     if (!this.codeInterpreter) {
-      this.codeInterpreter = await CodeInterpreter.create({
+      this.codeInterpreter = await Sandbox.create({
         apiKey: this.apiKey,
       });
-    }
-    // upload files to sandbox
-    if (input.sandboxFiles) {
-      console.log(`Uploading ${input.sandboxFiles.length} files to sandbox`);
-      try {
-        for (const filePath of input.sandboxFiles) {
-          const fileName = path.basename(filePath);
-          const localFilePath = path.join(this.uploadedFilesDir, fileName);
-          const content = fs.readFileSync(localFilePath);
-          await this.codeInterpreter?.files.write(filePath, content);
+      // upload files to sandbox when it's initialized
+      if (input.sandboxFiles) {
+        console.log(`Uploading ${input.sandboxFiles.length} files to sandbox`);
+        try {
+          for (const filePath of input.sandboxFiles) {
+            const fileName = path.basename(filePath);
+            const localFilePath = path.join(this.uploadedFilesDir, fileName);
+            const content = fs.readFileSync(localFilePath);
+
+            const arrayBuffer = new Uint8Array(content).buffer;
+            await this.codeInterpreter?.files.write(filePath, arrayBuffer);
+          }
+        } catch (error) {
+          console.error("Got error when uploading files to sandbox", error);
         }
-      } catch (error) {
-        console.error("Got error when uploading files to sandbox", error);
       }
     }
+
     return this.codeInterpreter;
   }
 
@@ -148,7 +151,7 @@ export class InterpreterTool implements BaseTool<InterpreterParameter> {
       `\n${"=".repeat(50)}\n> Running following AI-generated code:\n${input.code}\n${"=".repeat(50)}`,
     );
     const interpreter = await this.initInterpreter(input);
-    const exec = await interpreter.notebook.execCell(input.code);
+    const exec = await interpreter.runCode(input.code);
     if (exec.error) console.error("[Code Interpreter error]", exec.error);
     const extraResult = await this.getExtraResult(exec.results[0]);
     const result: InterpreterToolOutput = {
@@ -167,7 +170,7 @@ export class InterpreterTool implements BaseTool<InterpreterParameter> {
   }
 
   async close() {
-    await this.codeInterpreter?.close();
+    await this.codeInterpreter?.kill();
   }
 
   private async getExtraResult(

templates/components/engines/typescript/agent/tools/query-engine.ts

@@ -0,0 +1,57 @@
+import {
+  BaseQueryEngine,
+  CloudRetrieveParams,
+  LlamaCloudIndex,
+  MetadataFilters,
+  QueryEngineTool,
+  VectorStoreIndex,
+} from "llamaindex";
+import { generateFilters } from "../queryFilter";
+
+interface QueryEngineParams {
+  documentIds?: string[];
+  topK?: number;
+}
+
+export function createQueryEngineTool(
+  index: VectorStoreIndex | LlamaCloudIndex,
+  params?: QueryEngineParams,
+  name?: string,
+  description?: string,
+): QueryEngineTool {
+  return new QueryEngineTool({
+    queryEngine: createQueryEngine(index, params),
+    metadata: {
+      name: name || "query_engine",
+      description:
+        description ||
+        `Use this tool to retrieve information about the text corpus from an index.`,
+    },
+  });
+}
+
+function createQueryEngine(
+  index: VectorStoreIndex | LlamaCloudIndex,
+  params?: QueryEngineParams,
+): BaseQueryEngine {
+  const baseQueryParams = {
+    similarityTopK:
+      params?.topK ??
+      (process.env.TOP_K ? parseInt(process.env.TOP_K) : undefined),
+  };
+
+  if (index instanceof LlamaCloudIndex) {
+    return index.asQueryEngine({
+      ...baseQueryParams,
+      retrieval_mode: "auto_routed",
+      preFilters: generateFilters(
+        params?.documentIds || [],
+      ) as CloudRetrieveParams["filters"],
+    });
+  }
+
+  return index.asQueryEngine({
+    ...baseQueryParams,
+    preFilters: generateFilters(params?.documentIds || []) as MetadataFilters,
+  });
+}

templates/components/llamaindex/typescript/documents/helper.ts

@@ -13,7 +13,7 @@ const MIME_TYPE_TO_EXT: Record<string, string> = {
     "docx",
 };
 
-const UPLOADED_FOLDER = "output/uploaded";
+export const UPLOADED_FOLDER = "output/uploaded";
 
 export async function storeAndParseFile(
   name: string,

templates/components/llamaindex/typescript/documents/pipeline.ts

@@ -3,6 +3,7 @@ import {
   IngestionPipeline,
   Settings,
   SimpleNodeParser,
+  storageContextFromDefaults,
   VectorStoreIndex,
 } from "llamaindex";
 
@@ -28,11 +29,20 @@ export async function runPipeline(
     return documents.map((document) => document.id_);
   } else {
     // Initialize a new index with the documents
-    const newIndex = await VectorStoreIndex.fromDocuments(documents);
-    newIndex.storageContext.docStore.persist();
     console.log(
       "Got empty index, created new index with the uploaded documents",
     );
+    const persistDir = process.env.STORAGE_CACHE_DIR;
+    if (!persistDir) {
+      throw new Error("STORAGE_CACHE_DIR environment variable is required!");
+    }
+    const storageContext = await storageContextFromDefaults({
+      persistDir,
+    });
+    const newIndex = await VectorStoreIndex.fromDocuments(documents, {
+      storageContext,
+    });
+    await newIndex.storageContext.docStore.persist();
     return documents.map((document) => document.id_);
   }
 }

templates/components/llamaindex/typescript/documents/upload.ts

@@ -1,7 +1,5 @@
 import { Document, LLamaCloudFileService, VectorStoreIndex } from "llamaindex";
 import { LlamaCloudIndex } from "llamaindex/cloud/LlamaCloudIndex";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { DocumentFile } from "../streaming/annotations";
 import { parseFile, storeFile } from "./helper";
 import { runPipeline } from "./pipeline";
@@ -18,8 +16,8 @@ export async function uploadDocument(
   // Store file
   const fileMetadata = await storeFile(name, fileBuffer, mimeType);
 
-  // If the file is csv and has codeExecutorTool, we don't need to index the file.
-  if (mimeType === "text/csv" && (await hasCodeExecutorTool())) {
+  // Do not index csv files
+  if (mimeType === "text/csv") {
     return fileMetadata;
   }
   let documentIds: string[] = [];
@@ -61,14 +59,3 @@ export async function uploadDocument(
   fileMetadata.refs = documentIds;
   return fileMetadata;
 }
-
-const hasCodeExecutorTool = async () => {
-  const codeExecutorTools = ["interpreter", "artifact"];
-
-  const configFile = path.join("config", "tools.json");
-  const toolConfig = JSON.parse(await fs.readFile(configFile, "utf8"));
-
-  const localTools = toolConfig.local || {};
-  // Check if local tools contains codeExecutorTools
-  return codeExecutorTools.some((tool) => localTools[tool] !== undefined);
-};

templates/components/llamaindex/typescript/streaming/annotations.ts

@@ -1,5 +1,11 @@
 import { JSONValue, Message } from "ai";
-import { MessageContent, MessageContentDetail } from "llamaindex";
+import {
+  ChatMessage,
+  MessageContent,
+  MessageContentDetail,
+  MessageType,
+} from "llamaindex";
+import { UPLOADED_FOLDER } from "../documents/helper";
 
 export type DocumentFileType = "csv" | "pdf" | "txt" | "docx";
 
@@ -58,6 +64,45 @@ export function retrieveMessageContent(messages: Message[]): MessageContent {
   ];
 }
 
+export function convertToChatHistory(messages: Message[]): ChatMessage[] {
+  if (!messages || !Array.isArray(messages)) {
+    return [];
+  }
+  const agentHistory = retrieveAgentHistoryMessage(messages);
+  if (agentHistory) {
+    const previousMessages = messages.slice(0, -1);
+    return [...previousMessages, agentHistory].map((msg) => ({
+      role: msg.role as MessageType,
+      content: msg.content,
+    }));
+  }
+  return messages.map((msg) => ({
+    role: msg.role as MessageType,
+    content: msg.content,
+  }));
+}
+
+function retrieveAgentHistoryMessage(
+  messages: Message[],
+  maxAgentMessages = 10,
+): ChatMessage | null {
+  const agentAnnotations = getAnnotations<{ agent: string; text: string }>(
+    messages,
+    { role: "assistant", type: "agent" },
+  ).slice(-maxAgentMessages);
+
+  if (agentAnnotations.length > 0) {
+    const messageContent =
+      "Here is the previous conversation of agents:\n" +
+      agentAnnotations.map((annotation) => annotation.data.text).join("\n");
+    return {
+      role: "assistant",
+      content: messageContent,
+    };
+  }
+  return null;
+}
+
 function getFileContent(file: DocumentFile): string {
   let defaultContent = `=====File: ${file.name}=====\n`;
   // Include file URL if it's available
@@ -84,6 +129,10 @@ function getFileContent(file: DocumentFile): string {
   const sandboxFilePath = `/tmp/${file.name}`;
   defaultContent += `Sandbox file path (instruction: only use sandbox path for artifact or code interpreter tool): ${sandboxFilePath}\n`;
 
+  // Include local file path
+  const localFilePath = `${UPLOADED_FOLDER}/${file.name}`;
+  defaultContent += `Local file path (instruction: use for local tool that requires a local path): ${localFilePath}\n`;
+
   return defaultContent;
 }
 
@@ -127,13 +176,10 @@ function retrieveLatestArtifact(messages: Message[]): MessageContentDetail[] {
 }
 
 function convertAnnotations(messages: Message[]): MessageContentDetail[] {
-  // annotations from the last user message that has annotations
-  const annotations: Annotation[] =
-    messages
-      .slice()
-      .reverse()
-      .find((message) => message.role === "user" && message.annotations)
-      ?.annotations?.map(getValidAnnotation) || [];
+  // get all annotations from user messages
+  const annotations: Annotation[] = messages
+    .filter((message) => message.role === "user" && message.annotations)
+    .flatMap((message) => message.annotations?.map(getValidAnnotation) || []);
   if (annotations.length === 0) return [];
 
   const content: MessageContentDetail[] = [];

templates/components/multiagent/python/app/api/routers/chat.py

@@ -1,12 +1,13 @@
 import logging
 
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Request, status
+
 from app.api.routers.models import (
     ChatData,
 )
 from app.api.routers.vercel_response import VercelStreamResponse
 from app.engine.query_filter import generate_filters
 from app.workflows import create_workflow
-from fastapi import APIRouter, BackgroundTasks, HTTPException, Request, status
 
 chat_router = r = APIRouter()
 
@@ -28,7 +29,9 @@ async def chat(
         params = data.data or {}
 
         workflow = create_workflow(
-            chat_history=messages, params=params, filters=filters
+            chat_history=messages,
+            params=params,
+            filters=filters,
         )
 
         event_handler = workflow.run(input=last_message_content, streaming=True)

templates/components/multiagent/python/app/api/routers/vercel_response.py

@@ -19,6 +19,7 @@ class VercelStreamResponse(StreamingResponse):
 
     TEXT_PREFIX = "0:"
     DATA_PREFIX = "8:"
+    ERROR_PREFIX = "3:"
 
     def __init__(self, request: Request, chat_data: ChatData, *args, **kwargs):
         self.request = request
@@ -41,13 +42,16 @@ class VercelStreamResponse(StreamingResponse):
 
                     yield output
         except asyncio.CancelledError:
-            logger.info("Stopping workflow")
-            await event_handler.cancel_run()
+            logger.warning("Workflow has been cancelled!")
         except Exception as e:
             logger.error(
                 f"Unexpected error in content_generator: {str(e)}", exc_info=True
             )
+            yield self.convert_error(
+                "An unexpected error occurred while processing your request, preventing the creation of a final answer. Please try again."
+            )
         finally:
+            await event_handler.cancel_run()
             logger.info("The stream has been stopped!")
 
     def _create_stream(
@@ -107,6 +111,11 @@ class VercelStreamResponse(StreamingResponse):
         data_str = json.dumps(data)
         return f"{cls.DATA_PREFIX}[{data_str}]\n"
 
+    @classmethod
+    def convert_error(cls, error: str):
+        error_str = json.dumps(error)
+        return f"{cls.ERROR_PREFIX}{error_str}\n"
+
     @staticmethod
     async def _generate_next_questions(chat_history: List[Message], response: str):
         questions = await NextQuestionSuggestion.suggest_next_questions(

templates/components/multiagent/python/app/workflows/tools.py

@@ -24,16 +24,6 @@ class ContextAwareTool(FunctionTool, ABC):
         pass
 
 
-class ResponseGenerator(BaseModel):
-    """
-    A response generator from chat_with_tools.
-    """
-
-    generator: AsyncGenerator[ChatResponse | None, None]
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-
 class ChatWithToolsResponse(BaseModel):
     """
     A tool call response from chat_with_tools.

templates/components/multiagent/typescript/express/chat.controller.ts

@@ -1,36 +1,47 @@
-import { StopEvent } from "@llamaindex/core/workflow";
-import { Message, streamToResponse } from "ai";
+import { LlamaIndexAdapter, Message } from "ai";
 import { Request, Response } from "express";
-import { ChatResponseChunk } from "llamaindex";
+import {
+  convertToChatHistory,
+  retrieveMessageContent,
+} from "./llamaindex/streaming/annotations";
 import { createWorkflow } from "./workflow/factory";
-import { toDataStream, workflowEventsToStreamData } from "./workflow/stream";
+import { createStreamFromWorkflowContext } from "./workflow/stream";
 
 export const chat = async (req: Request, res: Response) => {
   try {
-    const { messages, data }: { messages: Message[]; data?: any } = req.body;
-    const userMessage = messages.pop();
-    if (!messages || !userMessage || userMessage.role !== "user") {
+    const { messages }: { messages: Message[] } = req.body;
+    if (!messages || messages.length === 0) {
       return res.status(400).json({
-        error:
-          "messages are required in the request body and the last message must be from the user",
+        error: "messages are required in the request body",
       });
     }
+    const chatHistory = convertToChatHistory(messages);
+    const userMessageContent = retrieveMessageContent(messages);
 
-    const agent = createWorkflow(messages, data);
-    const result = agent.run<AsyncGenerator<ChatResponseChunk>>(
-      userMessage.content,
-    ) as unknown as Promise<StopEvent<AsyncGenerator<ChatResponseChunk>>>;
+    const workflow = await createWorkflow({ chatHistory });
 
-    // convert the workflow events to a vercel AI stream data object
-    const agentStreamData = await workflowEventsToStreamData(
-      agent.streamEvents(),
-    );
-    // convert the workflow result to a vercel AI content stream
-    const stream = toDataStream(result, {
-      onFinal: () => agentStreamData.close(),
+    const context = workflow.run({
+      message: userMessageContent,
+      streaming: true,
     });
 
-    return streamToResponse(stream, res, {}, agentStreamData);
+    const { stream, dataStream } =
+      await createStreamFromWorkflowContext(context);
+
+    const streamResponse = LlamaIndexAdapter.toDataStreamResponse(stream, {
+      data: dataStream,
+    });
+    if (streamResponse.body) {
+      const reader = streamResponse.body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          res.end();
+          return;
+        }
+        res.write(value);
+      }
+    }
   } catch (error) {
     console.error("[LlamaIndex]", error);
     return res.status(500).json({

templates/components/multiagent/typescript/nextjs/route.ts

@@ -1,11 +1,14 @@
 import { initObservability } from "@/app/observability";
-import { StopEvent } from "@llamaindex/core/workflow";
-import { Message, StreamingTextResponse } from "ai";
-import { ChatResponseChunk } from "llamaindex";
+import { LlamaIndexAdapter, type Message } from "ai";
 import { NextRequest, NextResponse } from "next/server";
 import { initSettings } from "./engine/settings";
+import {
+  convertToChatHistory,
+  isValidMessages,
+  retrieveMessageContent,
+} from "./llamaindex/streaming/annotations";
 import { createWorkflow } from "./workflow/factory";
-import { toDataStream, workflowEventsToStreamData } from "./workflow/stream";
+import { createStreamFromWorkflowContext } from "./workflow/stream";
 
 initObservability();
 initSettings();
@@ -16,9 +19,8 @@ export const dynamic = "force-dynamic";
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json();
-    const { messages, data }: { messages: Message[]; data?: any } = body;
-    const userMessage = messages.pop();
-    if (!messages || !userMessage || userMessage.role !== "user") {
+    const { messages }: { messages: Message[]; data?: any } = body;
+    if (!isValidMessages(messages)) {
       return NextResponse.json(
         {
           error:
@@ -28,20 +30,20 @@ export async function POST(request: NextRequest) {
       );
     }
 
-    const agent = createWorkflow(messages, data);
-    // TODO: fix type in agent.run in LITS
-    const result = agent.run<AsyncGenerator<ChatResponseChunk>>(
-      userMessage.content,
-    ) as unknown as Promise<StopEvent<AsyncGenerator<ChatResponseChunk>>>;
-    // convert the workflow events to a vercel AI stream data object
-    const agentStreamData = await workflowEventsToStreamData(
-      agent.streamEvents(),
-    );
-    // convert the workflow result to a vercel AI content stream
-    const stream = toDataStream(result, {
-      onFinal: () => agentStreamData.close(),
+    const chatHistory = convertToChatHistory(messages);
+    const userMessageContent = retrieveMessageContent(messages);
+
+    const workflow = await createWorkflow({ chatHistory });
+
+    const context = workflow.run({
+      message: userMessageContent,
+      streaming: true,
+    });
+    const { stream, dataStream } =
+      await createStreamFromWorkflowContext(context);
+    return LlamaIndexAdapter.toDataStreamResponse(stream, {
+      data: dataStream,
     });
-    return new StreamingTextResponse(stream, {}, agentStreamData);
   } catch (error) {
     console.error("[LlamaIndex]", error);
     return NextResponse.json(

templates/components/multiagent/typescript/workflow/single-agent.ts

@@ -1,22 +1,21 @@
 import {
-  Context,
+  HandlerContext,
   StartEvent,
   StopEvent,
   Workflow,
   WorkflowEvent,
-} from "@llamaindex/core/workflow";
+} from "@llamaindex/workflow";
 import {
   BaseToolWithCall,
   ChatMemoryBuffer,
   ChatMessage,
-  ChatResponse,
   ChatResponseChunk,
+  QueryEngineTool,
   Settings,
   ToolCall,
   ToolCallLLM,
-  ToolCallLLMMessageOptions,
-  callTool,
 } from "llamaindex";
+import { callTools, chatWithTools } from "./tools";
 import { AgentInput, AgentRunEvent } from "./type";
 
 class InputEvent extends WorkflowEvent<{
@@ -27,11 +26,23 @@ class ToolCallEvent extends WorkflowEvent<{
   toolCalls: ToolCall[];
 }> {}
 
-export class FunctionCallingAgent extends Workflow {
+type FunctionCallingAgentContextData = {
+  streaming: boolean;
+};
+
+export type FunctionCallingAgentInput = AgentInput & {
+  displayName: string;
+};
+
+export class FunctionCallingAgent extends Workflow<
+  FunctionCallingAgentContextData,
+  FunctionCallingAgentInput,
+  string | AsyncGenerator<boolean | ChatResponseChunk<object>>
+> {
   name: string;
   llm: ToolCallLLM;
   memory: ChatMemoryBuffer;
-  tools: BaseToolWithCall[];
+  tools: BaseToolWithCall[] | QueryEngineTool[];
   systemPrompt?: string;
   writeEvents: boolean;
   role?: string;
@@ -53,7 +64,9 @@ export class FunctionCallingAgent extends Workflow {
     });
     this.name = options?.name;
     this.llm = options.llm ?? (Settings.llm as ToolCallLLM);
-    this.checkToolCallSupport();
+    if (!(this.llm instanceof ToolCallLLM)) {
+      throw new Error("LLM is not a ToolCallLLM");
+    }
     this.memory = new ChatMemoryBuffer({
       llm: this.llm,
       chatHistory: options.chatHistory,
@@ -64,175 +77,103 @@ export class FunctionCallingAgent extends Workflow {
     this.role = options?.role;
 
     // add steps
-    this.addStep(StartEvent<AgentInput>, this.prepareChatHistory, {
-      outputs: InputEvent,
-    });
-    this.addStep(InputEvent, this.handleLLMInput, {
-      outputs: [ToolCallEvent, StopEvent],
-    });
-    this.addStep(ToolCallEvent, this.handleToolCalls, {
-      outputs: InputEvent,
-    });
+    this.addStep(
+      {
+        inputs: [StartEvent<AgentInput>],
+        outputs: [InputEvent],
+      },
+      this.prepareChatHistory,
+    );
+    this.addStep(
+      {
+        inputs: [InputEvent],
+        outputs: [ToolCallEvent, StopEvent],
+      },
+      this.handleLLMInput,
+    );
+    this.addStep(
+      {
+        inputs: [ToolCallEvent],
+        outputs: [InputEvent],
+      },
+      this.handleToolCalls,
+    );
   }
 
   private get chatHistory() {
     return this.memory.getMessages();
   }
 
-  private async prepareChatHistory(
-    ctx: Context,
+  prepareChatHistory = async (
+    ctx: HandlerContext<FunctionCallingAgentContextData>,
     ev: StartEvent<AgentInput>,
-  ): Promise<InputEvent> {
-    const { message, streaming } = ev.data.input;
-    ctx.set("streaming", streaming);
+  ): Promise<InputEvent> => {
+    const { message, streaming } = ev.data;
+    ctx.data.streaming = streaming ?? false;
     this.writeEvent(`Start to work on: ${message}`, ctx);
     if (this.systemPrompt) {
       this.memory.put({ role: "system", content: this.systemPrompt });
     }
     this.memory.put({ role: "user", content: message });
     return new InputEvent({ input: this.chatHistory });
-  }
+  };
 
-  private async handleLLMInput(
-    ctx: Context,
+  handleLLMInput = async (
+    ctx: HandlerContext<FunctionCallingAgentContextData>,
     ev: InputEvent,
-  ): Promise<StopEvent<string | AsyncGenerator> | ToolCallEvent> {
-    if (ctx.get("streaming")) {
-      return await this.handleLLMInputStream(ctx, ev);
+  ): Promise<StopEvent<string | AsyncGenerator> | ToolCallEvent> => {
+    const toolCallResponse = await chatWithTools(
+      this.llm,
+      this.tools,
+      this.chatHistory,
+    );
+    if (toolCallResponse.toolCallMessage) {
+      this.memory.put(toolCallResponse.toolCallMessage);
     }
 
-    const result = await this.llm.chat({
-      messages: this.chatHistory,
-      tools: this.tools,
-    });
-    this.memory.put(result.message);
-
-    const toolCalls = this.getToolCallsFromResponse(result);
-    if (toolCalls.length) {
-      return new ToolCallEvent({ toolCalls });
+    if (toolCallResponse.hasToolCall()) {
+      return new ToolCallEvent({ toolCalls: toolCallResponse.toolCalls });
     }
-    this.writeEvent("Finished task", ctx);
-    return new StopEvent({ result: result.message.content.toString() });
-  }
 
-  private async handleLLMInputStream(
-    context: Context,
-    ev: InputEvent,
-  ): Promise<StopEvent<AsyncGenerator> | ToolCallEvent> {
-    const { llm, tools, memory } = this;
-    const llmArgs = { messages: this.chatHistory, tools };
-
-    const responseGenerator = async function* () {
-      const responseStream = await llm.chat({ ...llmArgs, stream: true });
-
-      let fullResponse = null;
-      let yieldedIndicator = false;
-      for await (const chunk of responseStream) {
-        const hasToolCalls = chunk.options && "toolCall" in chunk.options;
-        if (!hasToolCalls) {
-          if (!yieldedIndicator) {
-            yield false;
-            yieldedIndicator = true;
-          }
-          yield chunk;
-        } else if (!yieldedIndicator) {
-          yield true;
-          yieldedIndicator = true;
-        }
-
-        fullResponse = chunk;
+    if (ctx.data.streaming) {
+      if (!toolCallResponse.responseGenerator) {
+        throw new Error("No streaming response");
       }
-
-      if (fullResponse?.options && Object.keys(fullResponse.options).length) {
-        memory.put({
-          role: "assistant",
-          content: "",
-          options: fullResponse.options,
-        });
-        yield fullResponse;
-      }
-    };
-
-    const generator = responseGenerator();
-    const isToolCall = await generator.next();
-    if (isToolCall.value) {
-      const fullResponse = await generator.next();
-      const toolCalls = this.getToolCallsFromResponse(
-        fullResponse.value as ChatResponseChunk<ToolCallLLMMessageOptions>,
-      );
-      return new ToolCallEvent({ toolCalls });
+      return new StopEvent(toolCallResponse.responseGenerator);
     }
 
-    this.writeEvent("Finished task", context);
-    return new StopEvent({ result: generator });
-  }
+    const fullResponse = await toolCallResponse.asFullResponse();
+    this.memory.put(fullResponse);
+    return new StopEvent(fullResponse.content.toString());
+  };
 
-  private async handleToolCalls(
-    ctx: Context,
+  handleToolCalls = async (
+    ctx: HandlerContext<FunctionCallingAgentContextData>,
     ev: ToolCallEvent,
-  ): Promise<InputEvent> {
+  ): Promise<InputEvent> => {
     const { toolCalls } = ev.data;
 
-    const toolMsgs: ChatMessage[] = [];
-
-    for (const call of toolCalls) {
-      const targetTool = this.tools.find(
-        (tool) => tool.metadata.name === call.name,
-      );
-      // TODO: make logger optional in callTool in framework
-      const toolOutput = await callTool(targetTool, call, {
-        log: () => {},
-        error: (...args: unknown[]) => {
-          console.error(`[Tool ${call.name} Error]:`, ...args);
-        },
-        warn: () => {},
-      });
-      toolMsgs.push({
-        content: JSON.stringify(toolOutput.output),
-        role: "user",
-        options: {
-          toolResult: {
-            result: toolOutput.output,
-            isError: toolOutput.isError,
-            id: call.id,
-          },
-        },
-      });
-    }
+    const toolMsgs = await callTools({
+      tools: this.tools,
+      toolCalls,
+      ctx,
+      agentName: this.name,
+    });
 
     for (const msg of toolMsgs) {
       this.memory.put(msg);
     }
 
     return new InputEvent({ input: this.memory.getMessages() });
-  }
+  };
 
-  private writeEvent(msg: string, context: Context) {
+  writeEvent = (
+    msg: string,
+    ctx: HandlerContext<FunctionCallingAgentContextData>,
+  ) => {
     if (!this.writeEvents) return;
-    context.writeEventToStream({
-      data: new AgentRunEvent({ name: this.name, msg }),
-    });
-  }
-
-  private checkToolCallSupport() {
-    const { supportToolCall } = this.llm as ToolCallLLM;
-    if (!supportToolCall) throw new Error("LLM does not support tool calls");
-  }
-
-  private getToolCallsFromResponse(
-    response:
-      | ChatResponse<ToolCallLLMMessageOptions>
-      | ChatResponseChunk<ToolCallLLMMessageOptions>,
-  ): ToolCall[] {
-    let options;
-    if ("message" in response) {
-      options = response.message.options;
-    } else {
-      options = response.options;
-    }
-    if (options && "toolCall" in options) {
-      return options.toolCall as ToolCall[];
-    }
-    return [];
-  }
+    ctx.sendEvent(
+      new AgentRunEvent({ agent: this.name, text: msg, type: "text" }),
+    );
+  };
 }

templates/components/multiagent/typescript/workflow/stream.ts

@@ -1,65 +1,69 @@
-import { StopEvent } from "@llamaindex/core/workflow";
 import {
-  createCallbacksTransformer,
-  createStreamDataTransformer,
-  StreamData,
-  trimStartOfStreamHelper,
-  type AIStreamCallbacksAndOptions,
-} from "ai";
-import { ChatResponseChunk } from "llamaindex";
+  StopEvent,
+  WorkflowContext,
+  WorkflowEvent,
+} from "@llamaindex/workflow";
+import { StreamData } from "ai";
+import { ChatResponseChunk, EngineResponse } from "llamaindex";
+import { ReadableStream } from "stream/web";
 import { AgentRunEvent } from "./type";
 
-export function toDataStream(
-  result: Promise<StopEvent<AsyncGenerator<ChatResponseChunk>>>,
-  callbacks?: AIStreamCallbacksAndOptions,
-) {
-  return toReadableStream(result)
-    .pipeThrough(createCallbacksTransformer(callbacks))
-    .pipeThrough(createStreamDataTransformer());
-}
+export async function createStreamFromWorkflowContext<Input, Output, Context>(
+  context: WorkflowContext<Input, Output, Context>,
+): Promise<{ stream: ReadableStream<EngineResponse>; dataStream: StreamData }> {
+  const dataStream = new StreamData();
+  let generator: AsyncGenerator<ChatResponseChunk> | undefined;
 
-function toReadableStream(
-  result: Promise<StopEvent<AsyncGenerator<ChatResponseChunk>>>,
-) {
-  const trimStartOfStream = trimStartOfStreamHelper();
-  return new ReadableStream<string>({
-    start(controller) {
-      controller.enqueue(""); // Kickstart the stream
+  const closeStreams = (controller: ReadableStreamDefaultController) => {
+    controller.close();
+    dataStream.close();
+  };
+
+  const stream = new ReadableStream<EngineResponse>({
+    async start(controller) {
+      // Kickstart the stream by sending an empty string
+      controller.enqueue({ delta: "" } as EngineResponse);
     },
-    async pull(controller): Promise<void> {
-      const stopEvent = await result;
-      const generator = stopEvent.data.result;
-      const { value, done } = await generator.next();
+    async pull(controller) {
+      while (!generator) {
+        // get next event from workflow context
+        const { value: event, done } =
+          await context[Symbol.asyncIterator]().next();
+        if (done) {
+          closeStreams(controller);
+          return;
+        }
+        generator = handleEvent(event, dataStream);
+      }
+
+      const { value: chunk, done } = await generator.next();
       if (done) {
-        controller.close();
+        closeStreams(controller);
         return;
       }
-
-      const text = trimStartOfStream(value.delta ?? "");
-      if (text) controller.enqueue(text);
+      const delta = chunk.delta ?? "";
+      if (delta) {
+        controller.enqueue({ delta } as EngineResponse);
+      }
     },
   });
+
+  return { stream, dataStream };
 }
 
-export async function workflowEventsToStreamData(
-  events: AsyncIterable<AgentRunEvent>,
-): Promise<StreamData> {
-  const streamData = new StreamData();
-
-  (async () => {
-    for await (const event of events) {
-      if (event instanceof AgentRunEvent) {
-        const { name, msg } = event.data;
-        if ((streamData as any).isClosed) {
-          break;
-        }
-        streamData.appendMessageAnnotation({
-          type: "agent",
-          data: { agent: name, text: msg },
-        });
-      }
-    }
-  })();
-
-  return streamData;
+function handleEvent(
+  event: WorkflowEvent<any>,
+  dataStream: StreamData,
+): AsyncGenerator<ChatResponseChunk> | undefined {
+  // Handle for StopEvent
+  if (event instanceof StopEvent) {
+    return event.data as AsyncGenerator<ChatResponseChunk>;
+  }
+  // Handle for AgentRunEvent
+  if (event instanceof AgentRunEvent) {
+    dataStream.appendMessageAnnotation({
+      type: "agent",
+      data: event.data,
+    });
+  }
 }

templates/components/multiagent/typescript/workflow/tools.ts

@@ -0,0 +1,300 @@
+import { HandlerContext } from "@llamaindex/workflow";
+import {
+  BaseToolWithCall,
+  callTool,
+  ChatMessage,
+  ChatResponse,
+  ChatResponseChunk,
+  PartialToolCall,
+  QueryEngineTool,
+  ToolCall,
+  ToolCallLLM,
+  ToolCallLLMMessageOptions,
+} from "llamaindex";
+import crypto from "node:crypto";
+import { getDataSource } from "../engine";
+import { createQueryEngineTool } from "../engine/tools/query-engine";
+import { AgentRunEvent } from "./type";
+
+export const getQueryEngineTool = async (): Promise<QueryEngineTool | null> => {
+  const index = await getDataSource();
+
+  if (!index) {
+    return null;
+  }
+
+  return createQueryEngineTool(index);
+};
+
+/**
+ * Call multiple tools and return the tool messages
+ */
+export const callTools = async <T>({
+  tools,
+  toolCalls,
+  ctx,
+  agentName,
+  writeEvent = true,
+}: {
+  toolCalls: ToolCall[];
+  tools: BaseToolWithCall[];
+  ctx: HandlerContext<T>;
+  agentName: string;
+  writeEvent?: boolean;
+}): Promise<ChatMessage[]> => {
+  const toolMsgs: ChatMessage[] = [];
+  if (toolCalls.length === 0) {
+    return toolMsgs;
+  }
+  if (toolCalls.length === 1) {
+    const tool = tools.find((tool) => tool.metadata.name === toolCalls[0].name);
+    if (!tool) {
+      throw new Error(`Tool ${toolCalls[0].name} not found`);
+    }
+    return [
+      await callSingleTool(
+        tool,
+        toolCalls[0],
+        writeEvent
+          ? (msg: string) => {
+              ctx.sendEvent(
+                new AgentRunEvent({
+                  agent: agentName,
+                  text: msg,
+                  type: "text",
+                }),
+              );
+            }
+          : undefined,
+      ),
+    ];
+  }
+  // Multiple tool calls, show events in progress
+  const progressId = crypto.randomUUID();
+  const totalSteps = toolCalls.length;
+  let currentStep = 0;
+  for (const toolCall of toolCalls) {
+    const tool = tools.find((tool) => tool.metadata.name === toolCall.name);
+    if (!tool) {
+      throw new Error(`Tool ${toolCall.name} not found`);
+    }
+    const toolMsg = await callSingleTool(tool, toolCall, (msg: string) => {
+      ctx.sendEvent(
+        new AgentRunEvent({
+          agent: agentName,
+          text: msg,
+          type: "progress",
+          data: {
+            id: progressId,
+            total: totalSteps,
+            current: currentStep,
+          },
+        }),
+      );
+      currentStep++;
+    });
+    toolMsgs.push(toolMsg);
+  }
+  return toolMsgs;
+};
+
+export const callSingleTool = async (
+  tool: BaseToolWithCall,
+  toolCall: ToolCall,
+  eventEmitter?: (msg: string) => void,
+): Promise<ChatMessage> => {
+  if (eventEmitter) {
+    eventEmitter(
+      `Calling tool ${toolCall.name} with input: ${JSON.stringify(toolCall.input)}`,
+    );
+  }
+
+  const toolOutput = await callTool(tool, toolCall, {
+    log: () => {},
+    error: (...args: unknown[]) => {
+      console.error(`Tool ${toolCall.name} got error:`, ...args);
+      if (eventEmitter) {
+        eventEmitter(`Tool ${toolCall.name} got error: ${args.join(" ")}`);
+      }
+      return {
+        content: JSON.stringify({
+          error: args.join(" "),
+        }),
+        role: "user",
+        options: {
+          toolResult: {
+            id: toolCall.id,
+            result: JSON.stringify({
+              error: args.join(" "),
+            }),
+            isError: true,
+          },
+        },
+      };
+    },
+    warn: () => {},
+  });
+
+  return {
+    content: JSON.stringify(toolOutput.output),
+    role: "user",
+    options: {
+      toolResult: {
+        result: toolOutput.output,
+        isError: toolOutput.isError,
+        id: toolCall.id,
+      },
+    },
+  };
+};
+
+class ChatWithToolsResponse {
+  toolCalls: ToolCall[];
+  toolCallMessage?: ChatMessage;
+  responseGenerator?: AsyncGenerator<ChatResponseChunk>;
+
+  constructor(options: {
+    toolCalls: ToolCall[];
+    toolCallMessage?: ChatMessage;
+    responseGenerator?: AsyncGenerator<ChatResponseChunk>;
+  }) {
+    this.toolCalls = options.toolCalls;
+    this.toolCallMessage = options.toolCallMessage;
+    this.responseGenerator = options.responseGenerator;
+  }
+
+  hasMultipleTools() {
+    const uniqueToolNames = new Set(this.getToolNames());
+    return uniqueToolNames.size > 1;
+  }
+
+  hasToolCall() {
+    return this.toolCalls.length > 0;
+  }
+
+  getToolNames() {
+    return this.toolCalls.map((toolCall) => toolCall.name);
+  }
+
+  async asFullResponse(): Promise<ChatMessage> {
+    if (!this.responseGenerator) {
+      throw new Error("No response generator");
+    }
+    let fullResponse = "";
+    for await (const chunk of this.responseGenerator) {
+      fullResponse += chunk.delta;
+    }
+    return {
+      role: "assistant",
+      content: fullResponse,
+    };
+  }
+}
+
+export const chatWithTools = async (
+  llm: ToolCallLLM,
+  tools: BaseToolWithCall[],
+  messages: ChatMessage[],
+): Promise<ChatWithToolsResponse> => {
+  const responseGenerator = async function* (): AsyncGenerator<
+    boolean | ChatResponseChunk,
+    void,
+    unknown
+  > {
+    const responseStream = await llm.chat({ messages, tools, stream: true });
+
+    let fullResponse = null;
+    let yieldedIndicator = false;
+    const toolCallMap = new Map();
+    for await (const chunk of responseStream) {
+      const hasToolCalls = chunk.options && "toolCall" in chunk.options;
+      if (!hasToolCalls) {
+        if (!yieldedIndicator) {
+          yield false;
+          yieldedIndicator = true;
+        }
+        yield chunk;
+      } else if (!yieldedIndicator) {
+        yield true;
+        yieldedIndicator = true;
+      }
+
+      if (chunk.options && "toolCall" in chunk.options) {
+        for (const toolCall of chunk.options.toolCall as PartialToolCall[]) {
+          if (toolCall.id) {
+            toolCallMap.set(toolCall.id, toolCall);
+          }
+        }
+      }
+
+      if (
+        hasToolCalls &&
+        (chunk.raw as any)?.choices?.[0]?.finish_reason !== null
+      ) {
+        // Update the fullResponse with the tool calls
+        const toolCalls = Array.from(toolCallMap.values());
+        fullResponse = {
+          ...chunk,
+          options: {
+            ...chunk.options,
+            toolCall: toolCalls,
+          },
+        };
+      }
+    }
+
+    if (fullResponse) {
+      yield fullResponse;
+    }
+  };
+
+  const generator = responseGenerator();
+  const isToolCall = await generator.next();
+
+  if (isToolCall.value) {
+    // If it's a tool call, we need to wait for the full response
+    let fullResponse = null;
+    for await (const chunk of generator) {
+      fullResponse = chunk;
+    }
+
+    if (fullResponse) {
+      const responseChunk = fullResponse as ChatResponseChunk;
+      const toolCalls = getToolCallsFromResponse(responseChunk);
+      return new ChatWithToolsResponse({
+        toolCalls,
+        toolCallMessage: {
+          options: responseChunk.options,
+          role: "assistant",
+          content: "",
+        },
+      });
+    } else {
+      throw new Error("Cannot get tool calls from response");
+    }
+  }
+
+  return new ChatWithToolsResponse({
+    toolCalls: [],
+    responseGenerator: generator as AsyncGenerator<ChatResponseChunk>,
+  });
+};
+
+export const getToolCallsFromResponse = (
+  response:
+    | ChatResponse<ToolCallLLMMessageOptions>
+    | ChatResponseChunk<ToolCallLLMMessageOptions>,
+): ToolCall[] => {
+  let options;
+
+  if ("message" in response) {
+    options = response.message.options;
+  } else {
+    options = response.options;
+  }
+
+  if (options && "toolCall" in options) {
+    return options.toolCall as ToolCall[];
+  }
+  return [];
+};

templates/components/multiagent/typescript/workflow/type.ts

@@ -1,11 +1,24 @@
-import { WorkflowEvent } from "@llamaindex/core/workflow";
+import { WorkflowEvent } from "@llamaindex/workflow";
+import { MessageContent } from "llamaindex";
 
 export type AgentInput = {
-  message: string;
+  message: MessageContent;
   streaming?: boolean;
 };
 
+export type AgentRunEventType = "text" | "progress";
+
+export type ProgressEventData = {
+  id: string;
+  total: number;
+  current: number;
+};
+
+export type AgentRunEventData = ProgressEventData;
+
 export class AgentRunEvent extends WorkflowEvent<{
-  name: string;
-  msg: string;
+  agent: string;
+  text: string;
+  type: AgentRunEventType;
+  data?: AgentRunEventData;
 }> {}

templates/components/reflex/contract_review/README-template.md

@@ -0,0 +1,59 @@
+This is a [LlamaIndex](https://www.llamaindex.ai/) project using [Reflex](https://reflex.dev/) bootstrapped with [`create-llama`](https://github.com/run-llama/LlamaIndexTS/tree/main/packages/create-llama) featuring automated contract review and compliance analysis use case.
+
+## Getting Started
+
+First, setup the environment with poetry:
+
+> **_Note:_** This step is not needed if you are using the dev-container.
+
+```shell
+poetry install
+```
+
+Then check the parameters that have been pre-configured in the `.env` file in this directory. (E.g. you might need to configure an `OPENAI_API_KEY` if you're using OpenAI as model provider).
+
+Second, generate the embeddings of the example document in the `./data` directory:
+
+```shell
+poetry run generate
+```
+
+Third, start app with `reflex` command:
+
+```shell
+poetry run reflex run
+```
+
+To deploy the application, refer to the Reflex deployment guide: https://reflex.dev/docs/hosting/deploy-quick-start/
+
+### UI
+
+The application provides an interactive web interface accessible at http://localhost:3000 for testing the contract review workflow.
+
+To get started:
+
+1. Upload a contract document:
+
+   - Use the provided [example_vendor_agreement.md](./example_vendor_agreement.md) for testing
+   - Or upload your own document (supported formats: PDF, TXT, Markdown, DOCX)
+
+2. Review Process:
+   - The system will automatically analyze your document against compliance guidelines
+   - By default, it uses [GDPR](./data/gdpr.pdf) as the compliance benchmark
+   - Custom guidelines can be used by adding your policy documents to the `./data` directory and running `poetry run generate` to update the embeddings
+
+The interface will display the analysis results for the compliance of the contract document.
+
+### Development
+
+You can start editing the backend workflow by modifying the [`ContractReviewWorkflow`](./app/services/contract_reviewer.py).
+
+For UI, you can start looking at the [`AppState`](./app/ui/states/app.py) code and navigating to the appropriate components.
+
+## Learn More
+
+To learn more about LlamaIndex, take a look at the following resources:
+
+- [LlamaIndex Documentation](https://docs.llamaindex.ai) - learn about LlamaIndex.
+
+You can check out [the LlamaIndex GitHub repository](https://github.com/run-llama/llama_index) - your feedback and contributions are welcome!

templates/components/reflex/contract_review/app/config.py

@@ -0,0 +1,47 @@
+DATA_DIR = "data"
+UPLOADED_DIR = "output/uploaded"
+
+# Workflow prompts
+CONTRACT_EXTRACT_PROMPT = """\
+You are given contract data below. \
+Please extract out relevant information from the contract into the defined schema - the schema is defined as a function call.\
+
+{contract_data}
+"""
+
+CONTRACT_MATCH_PROMPT = """\
+Given the following contract clause and the corresponding relevant guideline text, evaluate the compliance \
+and provide a JSON object that matches the ClauseComplianceCheck schema.
+
+**Contract Clause:**
+{clause_text}
+
+**Matched Guideline Text(s):**
+{guideline_text}
+"""
+
+
+COMPLIANCE_REPORT_SYSTEM_PROMPT = """\
+You are a compliance reporting assistant. Your task is to generate a final compliance report \
+based on the results of clause compliance checks against \
+a given set of guidelines. 
+
+Analyze the provided compliance results and produce a structured report according to the specified schema. 
+Ensure that if there are no noncompliant clauses, the report clearly indicates full compliance.
+"""
+
+COMPLIANCE_REPORT_USER_PROMPT = """\
+A set of clauses within a contract were checked against GDPR compliance guidelines for the following vendor: {vendor_name}. 
+The set of noncompliant clauses are given below.
+
+Each section includes:
+- **Clause:** The exact text of the contract clause.
+- **Guideline:** The relevant GDPR guideline text.
+- **Compliance Status:** Should be `False` for noncompliant clauses.
+- **Notes:** Additional information or explanations.
+
+{compliance_results}
+
+Based on the above compliance results, generate a final compliance report following the `ComplianceReport` schema below. 
+If there are no noncompliant clauses, the report should indicate that the contract is fully compliant.
+"""

templates/components/reflex/contract_review/app/models.py

@@ -0,0 +1,85 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ContractClause(BaseModel):
+    clause_text: str = Field(..., description="The exact text of the clause.")
+    mentions_data_processing: bool = Field(
+        False,
+        description="True if the clause involves personal data collection or usage.",
+    )
+    mentions_data_transfer: bool = Field(
+        False,
+        description="True if the clause involves transferring personal data, especially to third parties or across borders.",
+    )
+    requires_consent: bool = Field(
+        False,
+        description="True if the clause explicitly states that user consent is needed for data activities.",
+    )
+    specifies_purpose: bool = Field(
+        False,
+        description="True if the clause specifies a clear purpose for data handling or transfer.",
+    )
+    mentions_safeguards: bool = Field(
+        False,
+        description="True if the clause mentions security measures or other safeguards for data.",
+    )
+
+
+class ContractExtraction(BaseModel):
+    vendor_name: Optional[str] = Field(
+        None, description="The vendor's name if identifiable."
+    )
+    effective_date: Optional[str] = Field(
+        None, description="The effective date of the agreement, if available."
+    )
+    governing_law: Optional[str] = Field(
+        None, description="The governing law of the contract, if stated."
+    )
+    clauses: List[ContractClause] = Field(
+        ..., description="List of extracted clauses and their relevant indicators."
+    )
+
+
+class GuidelineMatch(BaseModel):
+    guideline_text: str = Field(
+        ...,
+        description="The single most relevant guideline excerpt related to this clause.",
+    )
+    similarity_score: float = Field(
+        ...,
+        description="Similarity score indicating how closely the guideline matches the clause, e.g., between 0 and 1.",
+    )
+    relevance_explanation: Optional[str] = Field(
+        None, description="Brief explanation of why this guideline is relevant."
+    )
+
+
+class ClauseComplianceCheck(BaseModel):
+    clause_text: str = Field(
+        ..., description="The exact text of the clause from the contract."
+    )
+    matched_guideline: Optional[GuidelineMatch] = Field(
+        None, description="The most relevant guideline extracted via vector retrieval."
+    )
+    compliant: bool = Field(
+        ...,
+        description="Indicates whether the clause is considered compliant with the referenced guideline.",
+    )
+    notes: Optional[str] = Field(
+        None, description="Additional commentary or recommendations."
+    )
+
+
+class ComplianceReport(BaseModel):
+    vendor_name: Optional[str] = Field(
+        None, description="The vendor's name if identified from the contract."
+    )
+    overall_compliant: bool = Field(
+        ..., description="Indicates if the contract is considered overall compliant."
+    )
+    summary_notes: str = Field(
+        ...,
+        description="Always give a general summary or recommendations for achieving full compliance.",
+    )

templates/components/reflex/contract_review/app/services/contract_reviewer.py

@@ -0,0 +1,361 @@
+import logging
+import os
+import uuid
+from enum import Enum
+from pathlib import Path
+from typing import List
+
+from llama_index.core import SimpleDirectoryReader
+from llama_index.core.llms import LLM
+from llama_index.core.prompts import ChatPromptTemplate
+from llama_index.core.retrievers import BaseRetriever
+from llama_index.core.settings import Settings
+from llama_index.core.workflow import (
+    Context,
+    Event,
+    StartEvent,
+    StopEvent,
+    Workflow,
+    step,
+)
+
+from app.config import (
+    COMPLIANCE_REPORT_SYSTEM_PROMPT,
+    COMPLIANCE_REPORT_USER_PROMPT,
+    CONTRACT_EXTRACT_PROMPT,
+    CONTRACT_MATCH_PROMPT,
+)
+from app.engine.index import get_index
+from app.models import (
+    ClauseComplianceCheck,
+    ComplianceReport,
+    ContractClause,
+    ContractExtraction,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_workflow():
+    index = get_index()
+    if index is None:
+        raise RuntimeError(
+            "Index not found! Please run `poetry run generate` to populate an index first."
+        )
+    return ContractReviewWorkflow(
+        guideline_retriever=index.as_retriever(),
+        llm=Settings.llm,
+        verbose=True,
+        timeout=120,
+    )
+
+
+class Step(Enum):
+    PARSE_CONTRACT = "parse_contract"
+    ANALYZE_CLAUSES = "analyze_clauses"
+    HANDLE_CLAUSE = "handle_clause"
+    GENERATE_REPORT = "generate_report"
+
+
+class ContractExtractionEvent(Event):
+    contract_extraction: ContractExtraction
+
+
+class MatchGuidelineEvent(Event):
+    request_id: str
+    clause: ContractClause
+    vendor_name: str
+
+
+class MatchGuidelineResultEvent(Event):
+    result: ClauseComplianceCheck
+
+
+class GenerateReportEvent(Event):
+    match_results: List[ClauseComplianceCheck]
+
+
+class LogEvent(Event):
+    msg: str
+    step: Step
+    data: dict = {}
+    is_step_completed: bool = False
+
+
+class ContractReviewWorkflow(Workflow):
+    """Contract review workflow."""
+
+    def __init__(
+        self,
+        guideline_retriever: BaseRetriever,
+        llm: LLM | None = None,
+        similarity_top_k: int = 20,
+        **kwargs,
+    ) -> None:
+        """Init params."""
+        super().__init__(**kwargs)
+
+        self.guideline_retriever = guideline_retriever
+
+        self.llm = llm or Settings.llm
+        self.similarity_top_k = similarity_top_k
+
+        # if not exists, create
+        out_path = Path("output") / "workflow_output"
+        if not out_path.exists():
+            out_path.mkdir(parents=True, exist_ok=True)
+            os.chmod(str(out_path), 0o0777)
+        self.output_dir = out_path
+
+    @step
+    async def parse_contract(
+        self, ctx: Context, ev: StartEvent
+    ) -> ContractExtractionEvent:
+        """Parse the contract."""
+        uploaded_contract_path = Path(ev.contract_path)
+        contract_file_name = uploaded_contract_path.name
+        # Set contract file name in context
+        await ctx.set("contract_file_name", contract_file_name)
+
+        # Parse and read the contract to documents
+        docs = SimpleDirectoryReader(
+            input_files=[str(uploaded_contract_path)]
+        ).load_data()
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Loaded document: {contract_file_name}",
+                step=Step.PARSE_CONTRACT,
+                data={
+                    "saved_path": str(uploaded_contract_path),
+                    "parsed_data": None,
+                },
+            )
+        )
+
+        # Parse the contract into a structured model
+        # See the ContractExtraction model for information we want to extract
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg="Extracting information from the document",
+                step=Step.PARSE_CONTRACT,
+                data={
+                    "saved_path": str(uploaded_contract_path),
+                    "parsed_data": None,
+                },
+            )
+        )
+        prompt = ChatPromptTemplate.from_messages([("user", CONTRACT_EXTRACT_PROMPT)])
+        contract_extraction = await self.llm.astructured_predict(
+            ContractExtraction,
+            prompt,
+            contract_data="\n".join(
+                [d.get_content(metadata_mode="all") for d in docs]  # type: ignore
+            ),
+        )
+        if not isinstance(contract_extraction, ContractExtraction):
+            raise ValueError(f"Invalid extraction from contract: {contract_extraction}")
+
+        # save output template to file
+        contract_extraction_path = Path(f"{self.output_dir}/{contract_file_name}.json")
+        with open(contract_extraction_path, "w") as fp:
+            fp.write(contract_extraction.model_dump_json())
+
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg="Extracted successfully",
+                step=Step.PARSE_CONTRACT,
+                is_step_completed=True,
+                data={
+                    "saved_path": str(contract_extraction_path),
+                    "parsed_data": contract_extraction.model_dump_json(),
+                },
+            )
+        )
+
+        return ContractExtractionEvent(contract_extraction=contract_extraction)
+
+    @step
+    async def dispatch_guideline_match(  # type: ignore
+        self, ctx: Context, ev: ContractExtractionEvent
+    ) -> MatchGuidelineEvent:
+        """For each clause in the contract, find relevant guidelines.
+
+        Use a map-reduce pattern, send each parsed clause as a MatchGuidelineEvent.
+        """
+        await ctx.set("num_clauses", len(ev.contract_extraction.clauses))
+        await ctx.set("vendor_name", ev.contract_extraction.vendor_name)
+
+        for clause in ev.contract_extraction.clauses:
+            request_id = str(uuid.uuid4())
+            ctx.send_event(
+                MatchGuidelineEvent(
+                    request_id=request_id,
+                    clause=clause,
+                    vendor_name=ev.contract_extraction.vendor_name or "Not identified",
+                )
+            )
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Created {len(ev.contract_extraction.clauses)} tasks for analyzing with the guidelines",
+                step=Step.ANALYZE_CLAUSES,
+            )
+        )
+
+    @step
+    async def handle_guideline_match(
+        self, ctx: Context, ev: MatchGuidelineEvent
+    ) -> MatchGuidelineResultEvent:
+        """Handle matching clause against guideline."""
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Handling clause for request {ev.request_id}",
+                step=Step.HANDLE_CLAUSE,
+                data={
+                    "request_id": ev.request_id,
+                    "clause_text": ev.clause.clause_text,
+                    "is_compliant": None,
+                },
+            )
+        )
+
+        # retrieve matching guideline
+        query = f"""\
+Find the relevant guideline from {ev.vendor_name} that aligns with the following contract clause:
+
+{ev.clause.clause_text}
+"""
+        guideline_docs = self.guideline_retriever.retrieve(query)
+        guideline_text = "\n\n".join([g.get_content() for g in guideline_docs])
+
+        # extract compliance from contract into a structured model
+        # see ClauseComplianceCheck model for the schema
+        prompt = ChatPromptTemplate.from_messages([("user", CONTRACT_MATCH_PROMPT)])
+        compliance_output = await self.llm.astructured_predict(
+            ClauseComplianceCheck,
+            prompt,
+            clause_text=ev.clause.model_dump_json(),
+            guideline_text=guideline_text,
+        )
+
+        if not isinstance(compliance_output, ClauseComplianceCheck):
+            raise ValueError(f"Invalid compliance check: {compliance_output}")
+
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Completed compliance check for request {ev.request_id}",
+                step=Step.HANDLE_CLAUSE,
+                is_step_completed=True,
+                data={
+                    "request_id": ev.request_id,
+                    "clause_text": ev.clause.clause_text,
+                    "is_compliant": compliance_output.compliant,
+                    "result": compliance_output,
+                },
+            )
+        )
+
+        return MatchGuidelineResultEvent(result=compliance_output)
+
+    @step
+    async def gather_guideline_match(
+        self, ctx: Context, ev: MatchGuidelineResultEvent
+    ) -> GenerateReportEvent | None:
+        """Handle matching clause against guideline."""
+        num_clauses = await ctx.get("num_clauses")
+        events = ctx.collect_events(ev, [MatchGuidelineResultEvent] * num_clauses)
+        if events is None:
+            return None
+
+        match_results = [e.result for e in events]
+        # save match results
+        contract_file_name = await ctx.get("contract_file_name")
+        match_results_path = Path(
+            f"{self.output_dir}/match_results_{contract_file_name}.jsonl"
+        )
+        with open(match_results_path, "w") as fp:
+            for mr in match_results:
+                fp.write(mr.model_dump_json() + "\n")
+
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Processed {len(match_results)} clauses",
+                step=Step.ANALYZE_CLAUSES,
+                is_step_completed=True,
+                data={"saved_path": str(match_results_path)},
+            )
+        )
+        return GenerateReportEvent(match_results=[e.result for e in events])
+
+    @step
+    async def generate_output(self, ctx: Context, ev: GenerateReportEvent) -> StopEvent:
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg="Generating Compliance Report",
+                step=Step.GENERATE_REPORT,
+                data={"is_completed": False},
+            )
+        )
+
+        # if all clauses are compliant, return a compliant result
+        non_compliant_results = [r for r in ev.match_results if not r.compliant]
+
+        # generate compliance results string
+        result_tmpl = """
+1. **Clause**: {clause}
+2. **Guideline:** {guideline}
+3. **Compliance Status:** {compliance_status}
+4. **Notes:** {notes}
+"""
+        non_compliant_strings = []
+        for nr in non_compliant_results:
+            non_compliant_strings.append(
+                result_tmpl.format(
+                    clause=nr.clause_text,
+                    guideline=nr.matched_guideline.guideline_text
+                    if nr.matched_guideline is not None
+                    else "No relevant guideline found",
+                    compliance_status=nr.compliant,
+                    notes=nr.notes,
+                )
+            )
+        non_compliant_str = "\n\n".join(non_compliant_strings)
+
+        prompt = ChatPromptTemplate.from_messages(
+            [
+                ("system", COMPLIANCE_REPORT_SYSTEM_PROMPT),
+                ("user", COMPLIANCE_REPORT_USER_PROMPT),
+            ]
+        )
+        compliance_report = await self.llm.astructured_predict(
+            ComplianceReport,
+            prompt,
+            compliance_results=non_compliant_str,
+            vendor_name=await ctx.get("vendor_name"),
+        )
+
+        # Save compliance report to file
+        contract_file_name = await ctx.get("contract_file_name")
+        compliance_report_path = Path(
+            f"{self.output_dir}/report_{contract_file_name}.json"
+        )
+        with open(compliance_report_path, "w") as fp:
+            fp.write(compliance_report.model_dump_json())
+
+        ctx.write_event_to_stream(
+            LogEvent(
+                msg=f"Compliance report saved to {compliance_report_path}",
+                step=Step.GENERATE_REPORT,
+                is_step_completed=True,
+                data={
+                    "saved_path": str(compliance_report_path),
+                    "result": compliance_report,
+                },
+            )
+        )
+
+        return StopEvent(
+            result={
+                "report": compliance_report,
+                "non_compliant_results": non_compliant_results,
+            }
+        )

templates/components/reflex/contract_review/app/ui/components/__init__.py

@@ -0,0 +1,9 @@
+from .upload import upload_component
+from .workflow import guideline_component, load_contract_component, report_component
+
+__all__ = [
+    "upload_component",
+    "load_contract_component",
+    "guideline_component",
+    "report_component",
+]

templates/components/reflex/contract_review/app/ui/components/shared/__init__.py

@@ -0,0 +1,5 @@
+from .card import card_component
+
+__all__ = [
+    "card_component",
+]

templates/components/reflex/contract_review/app/ui/components/shared/card.py

@@ -0,0 +1,20 @@
+import reflex as rx
+
+
+def card_component(
+    title: str,
+    children: rx.Component,
+    show_loading: bool = False,
+) -> rx.Component:
+    return rx.card(
+        rx.hstack(
+            rx.cond(show_loading, rx.spinner(size="2")),
+            rx.text(title, size="4"),
+            align_items="center",
+            gap="2",
+        ),
+        rx.divider(orientation="horizontal"),
+        rx.container(children),
+        width="100%",
+        background_color="var(--gray-3)",
+    )

templates/components/reflex/contract_review/app/ui/components/upload.py

@@ -0,0 +1,30 @@
+import reflex as rx
+
+from app.ui.components.shared import card_component
+from app.ui.states.app import AppState
+
+
+def upload_component() -> rx.Component:
+    return card_component(
+        title="Upload",
+        children=rx.container(
+            rx.vstack(
+                rx.upload(
+                    rx.vstack(
+                        rx.text("Drag and drop files here or click to select files"),
+                    ),
+                    on_drop=AppState.handle_upload(
+                        rx.upload_files(upload_id="upload1")
+                    ),
+                    id="upload1",
+                    border="1px dotted rgb(107,99,246)",
+                    padding="1rem",
+                ),
+                rx.cond(
+                    AppState.uploaded_file != None,  # noqa: E711
+                    rx.text(AppState.uploaded_file.file_name),  # type: ignore
+                    rx.text("No file uploaded"),
+                ),
+            ),
+        ),
+    )

templates/components/reflex/contract_review/app/ui/components/workflow/__init__.py

@@ -0,0 +1,9 @@
+from .guideline import guideline_component
+from .load import load_contract_component
+from .report import report_component
+
+__all__ = [
+    "guideline_component",
+    "load_contract_component",
+    "report_component",
+]

templates/components/reflex/contract_review/app/ui/components/workflow/guideline.py

@@ -0,0 +1,113 @@
+from typing import List
+
+import reflex as rx
+
+from app.models import ClauseComplianceCheck
+from app.ui.components.shared import card_component
+from app.ui.states.workflow import GuidelineData, GuidelineHandlerState, GuidelineState
+
+
+def guideline_handler_component(item: List) -> rx.Component:
+    _id: str = item[0]
+    status: GuidelineData = item[1]
+
+    return rx.hover_card.root(
+        rx.hover_card.trigger(
+            rx.card(
+                rx.stack(
+                    rx.container(
+                        rx.cond(
+                            ~status.is_completed,
+                            rx.spinner(size="1"),
+                            rx.cond(
+                                status.is_compliant,
+                                rx.icon(tag="check", color="green"),
+                                rx.icon(tag="x", color="red"),
+                            ),
+                        ),
+                    ),
+                    rx.flex(
+                        rx.text(status.clause_text, size="1"),
+                    ),
+                ),
+            ),
+        ),
+        rx.hover_card.content(
+            rx.cond(
+                status.is_completed,
+                guideline_result_component(status.result),  # type: ignore
+                rx.spinner(size="1"),
+            ),
+            side="right",
+        ),
+    )
+
+
+def guideline_result_component(result: ClauseComplianceCheck) -> rx.Component:
+    return rx.inset(
+        rx.table.root(
+            rx.table.header(
+                rx.table.row(
+                    rx.table.cell("Clause"),
+                    rx.table.cell("Guideline"),
+                ),
+            ),
+            rx.table.body(
+                rx.table.row(
+                    # rx.table.cell("Clause"),
+                    rx.table.cell(
+                        rx.text(result.clause_text, size="1"),
+                    ),  # type: ignore
+                    rx.table.cell(
+                        rx.text(result.matched_guideline.guideline_text, size="1"),  # type: ignore
+                    ),
+                ),
+            ),
+        ),
+        rx.container(
+            rx.cond(
+                result.compliant,
+                rx.text(
+                    result.notes,  # type: ignore
+                    size="2",
+                    color="green",
+                ),
+                rx.text(
+                    result.notes,  # type: ignore
+                    size="2",
+                    color="red",
+                ),
+            )
+        ),
+    )
+
+
+def guideline_component() -> rx.Component:
+    return rx.cond(
+        GuidelineState.is_started,
+        card_component(
+            title="Analyze the document with provided guidelines",
+            children=rx.vstack(
+                rx.vstack(
+                    rx.foreach(
+                        GuidelineState.log,
+                        lambda log: rx.box(
+                            rx.text(log["msg"]),
+                        ),
+                    ),
+                ),
+                rx.cond(
+                    GuidelineHandlerState.has_data(),  # type: ignore
+                    rx.grid(
+                        rx.foreach(
+                            GuidelineHandlerState.data,
+                            guideline_handler_component,
+                        ),
+                        columns="2",
+                        spacing="1",
+                    ),
+                ),
+            ),
+            show_loading=GuidelineState.is_running,
+        ),
+    )

templates/components/reflex/contract_review/app/ui/components/workflow/load.py

@@ -0,0 +1,22 @@
+import reflex as rx
+
+from app.ui.components.shared import card_component
+from app.ui.states.workflow import ContractLoaderState
+
+
+def load_contract_component() -> rx.Component:
+    return rx.cond(
+        ContractLoaderState.is_started,
+        card_component(
+            title="Parse contract",
+            children=rx.vstack(
+                rx.foreach(
+                    ContractLoaderState.log,
+                    lambda log: rx.box(
+                        rx.text(log["msg"]),
+                    ),
+                ),
+            ),
+            show_loading=ContractLoaderState.is_running,
+        ),
+    )

templates/components/reflex/contract_review/app/ui/components/workflow/report.py

@@ -0,0 +1,48 @@
+import reflex as rx
+
+from app.ui.components.shared import card_component
+from app.ui.states.workflow import ReportState
+
+
+def report_component() -> rx.Component:
+    return rx.cond(
+        ReportState.is_running,
+        card_component(
+            title="Conclusion",
+            show_loading=~ReportState.is_completed,  # type: ignore
+            children=rx.cond(
+                ReportState.is_completed,
+                rx.vstack(
+                    rx.box(
+                        rx.inset(
+                            rx.table.root(
+                                rx.table.body(
+                                    rx.table.row(
+                                        rx.table.cell("Vendor"),
+                                        rx.table.cell(ReportState.result.vendor_name),  # type: ignore
+                                    ),
+                                    rx.table.row(
+                                        rx.table.cell("Overall Compliance"),
+                                        rx.table.cell(
+                                            rx.cond(
+                                                ReportState.result.overall_compliant,
+                                                rx.text("Compliant", color="green"),
+                                                rx.text("Non-compliant", color="red"),
+                                            )
+                                        ),
+                                    ),
+                                    rx.table.row(
+                                        rx.table.cell("Summary Notes"),
+                                        rx.table.cell(ReportState.result.summary_notes),  # type: ignore
+                                    ),
+                                ),
+                            ),
+                        )
+                    ),
+                ),
+                rx.vstack(
+                    rx.text("Analyzing compliance results for final conclusion..."),
+                ),
+            ),
+        ),
+    )

templates/components/reflex/contract_review/app/ui/pages/index.py

@@ -0,0 +1,46 @@
+import reflex as rx
+
+from app.ui.components import (
+    guideline_component,
+    load_contract_component,
+    report_component,
+    upload_component,
+)
+from app.ui.templates import template
+
+
+@template(
+    route="/",
+    title="Structure extractor",
+)
+def index() -> rx.Component:
+    """The main index page."""
+    return rx.vstack(
+        rx.vstack(
+            rx.heading("Built by LlamaIndex", size="6"),
+            rx.text(
+                "Upload a contract to start the review process.",
+            ),
+            background_color="var(--gray-3)",
+            align_items="left",
+            justify_content="left",
+            width="100%",
+            padding="1rem",
+        ),
+        rx.container(
+            rx.vstack(
+                # Upload
+                upload_component(),
+                # Workflow
+                rx.vstack(
+                    load_contract_component(),
+                    guideline_component(),
+                    report_component(),
+                    width="100%",
+                ),
+            ),
+            width="100%",
+            padding="1rem",
+        ),
+        width="100%",
+    )

templates/components/reflex/contract_review/app/ui/states/__init__.py

@@ -0,0 +1,15 @@
+from .app import AppState
+from .workflow import (
+    ContractLoaderState,
+    GuidelineHandlerState,
+    GuidelineState,
+    ReportState,
+)
+
+__all__ = [
+    "AppState",
+    "ContractLoaderState",
+    "GuidelineHandlerState",
+    "GuidelineState",
+    "ReportState",
+]

templates/components/reflex/contract_review/app/ui/states/app.py

@@ -0,0 +1,94 @@
+import logging
+import os
+from typing import List, Optional
+
+import reflex as rx
+
+from app.config import UPLOADED_DIR
+from app.services.contract_reviewer import LogEvent, Step, get_workflow
+from app.ui.states.workflow import (
+    ContractLoaderState,
+    GuidelineHandlerState,
+    GuidelineState,
+    ReportState,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class UploadedFile(rx.Base):
+    file_name: str
+    size: int
+
+
+class AppState(rx.State):
+    """
+    Whole main state for the app.
+    Handle for file upload, trigger workflow and produce workflow events.
+    """
+
+    uploaded_file: Optional[UploadedFile] = None
+
+    @rx.event
+    async def handle_upload(self, files: List[rx.UploadFile]):
+        if len(files) > 1:
+            yield rx.toast.error(
+                "You can only upload one file at a time", position="top-center"
+            )
+            return
+        try:
+            file = files[0]
+            upload_data = await file.read()
+            outfile = os.path.join(UPLOADED_DIR, file.filename)
+            with open(outfile, "wb") as f:
+                f.write(upload_data)
+            self.uploaded_file = UploadedFile(
+                file_name=file.filename, size=len(upload_data)
+            )
+            yield AppState.reset_workflow
+            yield AppState.trigger_workflow
+        except Exception as e:
+            yield rx.toast.error(str(e), position="top-center")
+
+    @rx.event
+    def reset_workflow(self):
+        yield ContractLoaderState.reset_state
+        yield GuidelineState.reset_state
+        yield GuidelineHandlerState.reset_state
+        yield ReportState.reset_state
+
+    @rx.event(background=True)
+    async def trigger_workflow(self):
+        """
+        Trigger backend to start reviewing the contract in a loop.
+        Get the event from the loop and update the state.
+        """
+        if self.uploaded_file is None:
+            yield rx.toast.error("No file uploaded", position="top-center")
+        else:
+            uploaded_file_path = os.path.join(
+                UPLOADED_DIR, self.uploaded_file.file_name
+            )
+
+            try:
+                workflow = get_workflow()
+                handler = workflow.run(
+                    contract_path=uploaded_file_path,
+                )
+                async for event in handler.stream_events():
+                    if isinstance(event, LogEvent):
+                        match event.step:
+                            case Step.PARSE_CONTRACT:
+                                yield ContractLoaderState.add_log(event)
+                            case Step.ANALYZE_CLAUSES:
+                                yield GuidelineState.add_log(event)
+                            case Step.HANDLE_CLAUSE:
+                                yield GuidelineHandlerState.add_log(event)
+                            case Step.GENERATE_REPORT:
+                                yield ReportState.add_log(event)
+                # Wait for workflow completion and propagate any exceptions
+                _ = await handler
+            except Exception as e:
+                logger.error(f"Error in trigger_workflow: {e}")
+                yield rx.toast.error(str(e), position="top-center")
+                yield AppState.reset_workflow

templates/components/reflex/contract_review/app/ui/states/workflow.py

@@ -0,0 +1,137 @@
+from typing import Any, Dict, List, Optional
+
+import reflex as rx
+from pydantic import BaseModel
+
+from app.models import ClauseComplianceCheck, ComplianceReport
+from app.services.contract_reviewer import LogEvent
+from rxconfig import config as rx_config
+
+
+class ContractLoaderState(rx.State):
+    is_running: bool = False
+    is_started: bool = False
+    log: List[Dict[str, Any]] = []
+
+    @rx.event
+    async def add_log(self, log: LogEvent):
+        if not self.is_started:
+            yield ContractLoaderState.start
+        self.log.append(log.model_dump())
+        if log.is_step_completed:
+            yield ContractLoaderState.stop
+
+    def has_log(self):
+        return len(self.log) > 0
+
+    @rx.event
+    def start(self):
+        self.is_running = True
+        self.is_started = True
+
+    @rx.event
+    def stop(self):
+        self.is_running = False
+
+    @rx.event
+    def reset_state(self):
+        self.is_running = False
+        self.is_started = False
+        self.log = []
+
+
+class GuidelineState(rx.State):
+    is_running: bool = False
+    is_started: bool = False
+    log: List[Dict[str, Any]] = []
+
+    @rx.event
+    def add_log(self, log: LogEvent):
+        if not self.is_started:
+            yield GuidelineState.start
+        self.log.append(log.model_dump())
+        if log.is_step_completed:
+            yield GuidelineState.stop
+
+    def has_log(self):
+        return len(self.log) > 0
+
+    @rx.event
+    def reset_state(self):
+        self.is_running = False
+        self.is_started = False
+        self.log = []
+
+    @rx.event
+    def start(self):
+        self.is_running = True
+        self.is_started = True
+
+    @rx.event
+    def stop(self):
+        self.is_running = False
+
+
+class GuidelineData(BaseModel):
+    is_completed: bool
+    is_compliant: Optional[bool]
+    clause_text: Optional[str]
+    result: Optional[ClauseComplianceCheck] = None
+
+
+class GuidelineHandlerState(rx.State):
+    data: Dict[str, GuidelineData] = {}
+
+    def has_data(self):
+        return len(self.data) > 0
+
+    @rx.event
+    def add_log(self, log: LogEvent):
+        _id = log.data.get("request_id")
+        if _id is None:
+            return
+        is_compliant = log.data.get("is_compliant", None)
+        self.data[_id] = GuidelineData(
+            is_completed=log.is_step_completed,
+            is_compliant=is_compliant,
+            clause_text=log.data.get("clause_text", None),
+            result=log.data.get("result", None),
+        )
+        if log.is_step_completed:
+            yield self.stop(request_id=_id)
+
+    @rx.event
+    def reset_state(self):
+        self.data = {}
+
+    @rx.event
+    def stop(self, request_id: str):
+        # Update the item in the data to be completed
+        self.data[request_id].is_completed = True
+
+
+class ReportState(rx.State):
+    is_running: bool = False
+    is_completed: bool = False
+    saved_path: str = ""
+    result: Optional[ComplianceReport] = None
+
+    @rx.var()
+    def download_url(self) -> str:
+        return f"{rx_config.api_url}/api/download/{self.saved_path}"
+
+    @rx.event
+    def add_log(self, log: LogEvent):
+        if not self.is_running:
+            self.is_running = True
+        if log.is_step_completed:
+            self.is_completed = True
+            self.saved_path = log.data.get("saved_path")
+            self.result = log.data.get("result")
+
+    @rx.event
+    def reset_state(self):
+        self.is_running = False
+        self.is_completed = False
+        self.saved_path = ""
+        self.result = None

templates/components/reflex/contract_review/example_vendor_agreement.md

@@ -0,0 +1,142 @@
+# ACME Vendor Agreement
+
+**Effective Date:** January 1, 2024
+
+## Parties:
+
+- **Client:** LlamaCo ("Client")
+- **Vendor:** ACME Office Supply, Inc. ("Vendor")
+
+## 1. Overview
+
+This Vendor Agreement ("Agreement") sets forth the terms and conditions under which ACME Office Supply, Inc. will provide office supplies, consumables, related goods ("Products"), and associated data processing services to LlamaCo.
+
+## 2. Definitions
+
+- **Personal Data:** Any information relating to an identified or identifiable natural person ('data subject').
+- **Processing:** Any operation performed on Personal Data, including collection, storage, modification, transfer, or deletion.
+- **Data Controller:** LlamaCo, who determines the purposes and means of processing Personal Data.
+- **Data Processor:** ACME Office Supply, Inc., who processes Personal Data on behalf of the Controller.
+
+## 3. Data Protection and Privacy
+
+### 3.1 Scope of Processing
+
+Vendor shall process Personal Data only:
+
+- To fulfill orders and manage deliveries
+- To provide customer support services
+- To maintain business records
+- To comply with legal obligations
+
+### 3.2 Data Subject Rights
+
+Vendor shall:
+
+- Respond to data subject requests within 30 days
+- Provide data in a structured, commonly used format
+- Implement measures to facilitate data portability
+- Assist with data subject rights requests at no additional cost
+
+### 3.3 Data Transfers and Storage
+
+- Vendor maintains primary data centers in the United States
+- Vendor may transfer data to any country where it maintains operations
+- No prior notification required for new data storage locations
+- Vendor will rely on its standard data transfer mechanisms
+- Data may be processed by staff operating outside the EEA
+
+### 3.4 Subprocessors
+
+- Vendor may engage subprocessors without prior Client approval
+- Subprocessors may be located in any jurisdiction globally
+- Notice of new subprocessors provided within 30 days of engagement
+- Client has no right to object to new subprocessors
+
+## 4. Security Measures
+
+### 4.1 Technical and Organizational Measures
+
+Vendor shall implement appropriate measures including:
+
+- Encryption of Personal Data in transit and at rest
+- Access controls and authentication
+- Regular security testing and assessments
+- Employee training on data protection
+- Incident response procedures
+
+### 4.2 Data Breaches
+
+Vendor shall:
+
+- Notify Client of any Personal Data breach within 72 hours
+- Provide details necessary to meet regulatory requirements
+- Cooperate with Client's breach investigation
+- Maintain records of all data breaches
+
+## 5. Data Retention
+
+### 5.1 Retention Period
+
+- Personal Data retained only as long as necessary
+- Standard retention period of 3 years after last transaction
+- Deletion of Personal Data upon written request
+- Backup copies retained for maximum of 6 months
+
+### 5.2 Termination
+
+Upon termination of services:
+
+- Return all Personal Data in standard format
+- Delete existing copies within 30 days
+- Provide written confirmation of deletion
+- Cease all processing activities
+
+## 6. Compliance and Audit
+
+### 6.1 Documentation
+
+Vendor shall maintain:
+
+- Records of all processing activities
+- Security measure documentation
+- Data transfer mechanisms
+- Subprocessor agreements
+
+### 6.2 Audits
+
+- Annual compliance audits permitted
+- 30 days notice required for audits
+- Vendor to provide necessary documentation
+- Client bears reasonable audit costs
+
+## 7. Liability and Indemnification
+
+### 7.1 Liability
+
+- Vendor liable for data protection violations
+- Reasonable compensation for damages
+- Coverage for regulatory fines where applicable
+- Joint liability as required by law
+
+## 8. Governing Law
+
+This Agreement shall be governed by the laws of Ireland, without regard to its conflict of laws principles.
+
+---
+
+IN WITNESS WHEREOF, the parties have executed this Agreement as of the Effective Date.
+
+**LlamaCo**
+
+By: **_
+Name: [Authorized Representative]  
+Title: [Title]  
+Date: _**
+
+**ACME Office Supply, Inc.**
+
+By: **_  
+Name: [Authorized Representative]  
+Title: [Title]  
+Date: _**

templates/components/reflex/contract_review/pyproject.toml

@@ -0,0 +1,44 @@
+[tool]
+[tool.poetry]
+name = "app"
+version = "0.1.0"
+description = ""
+authors = [ "Marcus Schiesser <mail@marcusschiesser.de>" ]
+readme = "README.md"
+
+[tool.poetry.scripts]
+generate = "app.engine.generate:generate_datasource"
+
+[tool.poetry.dependencies]
+python = "^3.11,<4.0"
+fastapi = "^0.109.1"
+python-dotenv = "^1.0.0"
+pydantic = "<2.10"
+llama-index = "^0.12.1"
+cachetools = "^5.3.3"
+reflex = "^0.6.2.post1"
+
+[tool.poetry.dependencies.uvicorn]
+extras = [ "standard" ]
+version = "^0.23.2"
+
+[tool.poetry.dependencies.docx2txt]
+version = "^0.8"
+
+[tool.poetry.dependencies.llama-index-llms-openai]
+version = "^0.3.2"
+
+[tool.poetry.dependencies.llama-index-embeddings-openai]
+version = "^0.3.1"
+
+[tool.poetry.dependencies.llama-index-agent-openai]
+version = "^0.4.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest-asyncio = "^0.25.0"
+pytest = "^8.3.4"
+
+[build-system]
+requires = [ "poetry-core" ]
+build-backend = "poetry.core.masonry.api"