chore: bump ts version for parse (#855)

* feat: add parse and getTables methods to LlamaParseReader

* feat: add tests

* fix: loop logic to fix test 🙈

* chore: implement suggestions

.github/workflows/claude-code.yml

@@ -0,0 +1,95 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    steps:
+      - name: Check repository access
+        id: check-access
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Get the user who triggered the event
+          case "${{ github.event_name }}" in
+            "issue_comment")
+              USER="${{ github.event.comment.user.login }}"
+              ;;
+            "pull_request_review_comment")
+              USER="${{ github.event.comment.user.login }}"
+              ;;
+            "pull_request_review")
+              USER="${{ github.event.review.user.login }}"
+              ;;
+            "issues")
+              USER="${{ github.event.issue.user.login }}"
+              ;;
+          esac
+
+          echo "Checking repository access for user: $USER"
+
+          # Check if user has write access to the repository
+          REPO="${{ github.repository }}"
+          if gh api repos/$REPO/collaborators/$USER/permission --jq '.permission' | grep -E "(admin|write)" > /dev/null 2>&1; then
+            echo "User $USER has write access to the repository"
+            echo "authorized=true" >> $GITHUB_OUTPUT
+          else
+            echo "User $USER does not have write access to the repository"
+            echo "authorized=false" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+      - name: Checkout repository
+        if: steps.check-access.outputs.authorized == 'true'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        if: steps.check-access.outputs.authorized == 'true'
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_GITHUB_API_KEY }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          # Allow bash commands to be run, for things like running tests, linting, etc.
+          allowed_tools: "Bash(rg:*),Bash(find:*),Bash(grep:*),Bash(pnpm:*),Bash(npm:*),Bash(uv:*),Bash(pip:*),Bash(pipx:*),Bash(make:*),Bash(cd:*),WebFetch"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test

.github/workflows/lint_ts.yml

@@ -28,7 +28,6 @@ jobs:
         with:
           node-version-file: "ts/llama_cloud_services/.nvmrc"
       - name: Install dependencies
-        working-directory: ts/llama_cloud_services/
         run: pnpm install --no-frozen-lockfile
       - name: Run lint
         working-directory: ts/llama_cloud_services/

.github/workflows/release_ts.yml

@@ -22,9 +22,12 @@ jobs:
           node-version-file: "ts/llama_cloud_services/.nvmrc"
 
       - name: Install dependencies
-        working-directory: ts/llama_cloud_services
         run: pnpm install --no-frozen-lockfile
 
+      - name: Run Build
+        working-directory: ts/llama_cloud_services/
+        run: pnpm build
+
       - name: Build tarball
         run: |
           pnpm pack

.github/workflows/test_ts.yml

@@ -30,8 +30,13 @@ jobs:
         with:
           node-version-file: "ts/llama_cloud_services/.nvmrc"
       - name: Install dependencies
-        working-directory: ts/llama_cloud_services/
         run: pnpm install --no-frozen-lockfile
-      - name: Run tests
+      - name: Run Build
+        working-directory: ts/llama_cloud_services/
+        run: pnpm build
+      - name: Run Tests
         working-directory: ts/llama_cloud_services/
         run: pnpm test
+      - name: Run e2e tests
+        working-directory: ts/e2e-tests/
+        run: pnpm test

.pre-commit-config.yaml

@@ -15,6 +15,7 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: trailing-whitespace
+        exclude: ^ts/llama_cloud_services/src/client/
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     rev: v0.1.5
 
@@ -63,13 +64,13 @@ repos:
     rev: v3.0.3
     hooks:
       - id: prettier
-        exclude: ^(uv.lock|ts/llama_cloud_services/pnpm-lock.yaml)
+        exclude: ^(uv.lock|ts/llama_cloud_services/pnpm-lock.yaml|ts/e2e-tests)
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:
       - id: codespell
         additional_dependencies: [tomli]
-        exclude: ^(uv.lock|docs|ts|examples)
+        exclude: ^(uv.lock|docs|ts|examples|pnpm-lock.yaml)
         args:
           [
             "--ignore-words-list",
@@ -86,4 +87,4 @@ repos:
       - id: toml-sort-fix
         exclude: ".*uv.lock"
 
-exclude: .github/ISSUE_TEMPLATE
+exclude: ^(.github/ISSUE_TEMPLATE|ts/llama_cloud_services/src/client|pnpm-lock.yaml)

examples-ts/README.md

@@ -0,0 +1,8 @@
+# LlamaCloud Services Examples - Python
+
+In this folder you will find several TypeScript end-to-end applications that contain examples regarding:
+
+- [LlamaParse](./parse/)
+- [LlamaCloud Index](./index/)
+
+Follow the instructions in each example folder to get started!

examples-ts/extract/README.md

@@ -0,0 +1,122 @@
+# LlamaExtract Demo
+
+A TypeScript demo application showcasing the power of **LlamaExract** - a structured data extraction agentic service from [LlamaCloud](https://cloud.llamaindex.ai). This demo allows you to extract structured information from scientific papers and get them into a nice markdown format.
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Start the Demo](#start-the-demo)
+  - [Development Mode](#development-mode)
+  - [Build the Project](#build-the-project)
+  - [Code Quality](#code-quality)
+  - [Quick Commands Reference](#quick-commands-reference)
+- [How It Works](#how-it-works)
+- [API Dependencies](#api-dependencies)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+- [License](#license)
+- [Contributing](#contributing)
+
+## Features
+
+- 📄 **Structured Data Extraction**: Extract data from your files effortlessly, and structure them the way you want!
+- 🤖 **Markdown Rendering**: Generate markdown directly from your extracted data
+- 🎨 **Beautiful CLI**: Styled console interface with colors and ASCII art
+- ⚡ **Fast Development**: Hot reload support with watch mode
+- 🛠️ **TypeScript**: Full TypeScript support with strict type checking
+
+## Prerequisites
+
+- Node.js (version 18 or higher)
+- pnpm package manager
+- LlamaCloud API key
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/extract/
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Set up your environment variables:
+
+```bash
+# Add your API key to your environment
+export LLAMA_CLOUD_API_KEY="your-llamacloud-api-key"
+```
+
+## Usage
+
+### Start the Demo
+
+```bash
+npm run start
+```
+
+The application will display a welcome screen and prompt you to enter the path to a document you'd like to process.
+
+### Development Mode
+
+For development with hot reload:
+
+```bash
+npm run dev
+```
+
+### Build the Project
+
+```bash
+npm run build
+```
+
+### Code Quality
+
+Format code:
+
+```bash
+npm run format
+```
+
+Lint code:
+
+```bash
+npm run lint
+```
+
+## How It Works
+
+1. **Document Input**: Enter the path to your document when prompted
+2. **Parsing**: LlamaExtract, based on the schema you can find [here](./src/schema.ts), processes the document and extracts structured data
+3. **Markdown Rendering**: The extracted content is rendered into beautiful markdown
+4. **Results**: View the results directly in your terminal
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Module Resolution Errors**: Ensure you're using Node.js 18+ and have all dependencies installed
+2. **API Key Issues**: Verify your LlamaCloud API key is correctly set
+3. **File Path Errors**: Use absolute paths or ensure relative paths are correct from the project root
+
+## License
+
+MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `npm run format` and `npm run lint`
+5. Submit a pull request

examples-ts/extract/eslint.config.mts

@@ -0,0 +1,14 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.browser },
+  },
+  tseslint.configs.recommended,
+]);

examples-ts/extract/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "llama-extract-demo",
+  "version": "0.1.0",
+  "description": "Demo for LlamaExtract in TypeScript",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"There are no tests\"",
+    "start": "npm exec tsx src/index.ts",
+    "lint": "eslint ./src/",
+    "format": "prettier --write ./src/",
+    "build": "tsc",
+    "dev": "npm exec tsx --watch src/index.ts"
+  },
+  "author": "LlamaIndex",
+  "license": "MIT",
+  "dependencies": {
+    "cli-markdown": "^3.5.1",
+    "consola": "^3.4.2",
+    "figlet": "^1.8.2",
+    "llama-cloud-services": "file:../../ts/llama_cloud_services",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "@types/figlet": "^1.7.0",
+    "@types/marked-terminal": "^6.1.1",
+    "@types/node": "^24.2.0",
+    "eslint": "^9.32.0",
+    "globals": "^16.3.0",
+    "jiti": "^2.5.1",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.0"
+  }
+}

examples-ts/extract/src/index.ts

@@ -0,0 +1,47 @@
+import { LlamaExtract, ExtractConfig } from "llama-cloud-services";
+import cliMarkdown from "cli-markdown";
+import { logger } from "./logger";
+import pc from "picocolors";
+import { consoleInput, renderLogo } from "./utils";
+import { dataSchema } from "./schema";
+import { renderMarkdown, ResearchData } from "./markdown";
+
+export async function main(): Promise<number> {
+  const extractClient = new LlamaExtract(
+    process.env.LLAMA_CLOUD_API_KEY!,
+    "https://api.cloud.llamaindex.ai",
+  );
+  await renderLogo();
+  logger.log(
+    `Welcome to ${pc.bold(
+      pc.magentaBright("LlamaExtract Demo✨"),
+    )}, our demo for ${pc.bold(pc.green("LlamaExtract"))}, a ${pc.bold(
+      pc.cyan("LlamaCloud☁️"),
+    )}  (https://cloud.llamaindex.ai) product!.\nIn this demo we are going to try extracting relevant information  ${pc.bold(
+      pc.yellowBright("from scientific papers"),
+    )}. Type the path to the paper you would like to process below👇\nIf you wish to exit, just type ${pc.bold(
+      pc.gray("quit"),
+    )}.\n`,
+  );
+  while (true) {
+    const userInput = await consoleInput();
+    if (userInput.toLowerCase() == "quit") {
+      break;
+    }
+    try {
+      const generatedData = await extractClient.extract(
+        dataSchema,
+        {} as ExtractConfig,
+        userInput,
+      );
+      const research = renderMarkdown(generatedData?.data as ResearchData); // Added await here
+      logger.log(`${pc.bold(pc.cyan("Extracted information:✨"))}:\n`);
+      logger.log(cliMarkdown(research));
+    } catch (error) {
+      logger.error(`Error processing file: ${error}`);
+    }
+  }
+  return 0;
+}
+
+main().catch(console.error);

examples-ts/extract/src/markdown.ts

@@ -0,0 +1,172 @@
+type Author = {
+  name: string;
+  affiliation?: string;
+  email?: string;
+};
+
+type Methodology = {
+  approach?: string;
+  participants?: string;
+  methods?: string[];
+};
+
+type Result = {
+  finding?: string;
+  significance?: string;
+  supportingData?: string;
+};
+
+type Reference = {
+  title: string;
+  authors: string;
+  year?: string;
+  relevance?: string;
+};
+
+type Discussion = {
+  implications?: string[];
+  limitations?: string[];
+  futureWork?: string[];
+};
+
+type Publication = {
+  journal?: string;
+  year: string;
+  doi?: string;
+  url?: string;
+};
+
+export type ResearchData = {
+  title: string;
+  authors: Author[];
+  abstract: string;
+  keywords?: string[];
+  mainFindings: string[];
+  methodology?: Methodology;
+  results?: Result[];
+  discussion?: Discussion;
+  references?: Reference[];
+  publication?: Publication;
+};
+
+export function renderMarkdown(data: ResearchData): string {
+  const {
+    title,
+    authors,
+    abstract,
+    keywords,
+    mainFindings,
+    methodology,
+    results,
+    discussion,
+    references,
+    publication,
+  } = data;
+
+  const md: string[] = [];
+
+  md.push(`# ${title}\n`);
+
+  // Authors
+  md.push(`## Authors`);
+  md.push(
+    authors
+      .map(
+        (author) =>
+          `- **${author.name}**${
+            author.affiliation ? `, *${author.affiliation}*` : ""
+          }${author.email ? ` (${author.email})` : ""}`,
+      )
+      .join("\n"),
+  );
+
+  // Abstract
+  md.push(`\n## Abstract\n${abstract}`);
+
+  // Keywords
+  if (keywords && keywords.length > 0) {
+    md.push(`\n## Keywords\n${keywords.map((k) => `- ${k}`).join("\n")}`);
+  }
+
+  // Main Findings
+  md.push(
+    `\n## Main Findings\n${mainFindings.map((f) => `- ${f}`).join("\n")}`,
+  );
+
+  // Methodology
+  if (methodology) {
+    md.push(`\n## Methodology`);
+    if (methodology.approach) md.push(`**Approach:** ${methodology.approach}`);
+    if (methodology.participants)
+      md.push(`**Participants:** ${methodology.participants}`);
+    if (methodology.methods?.length) {
+      md.push(
+        `**Methods:**\n${methodology.methods.map((m) => `- ${m}`).join("\n")}`,
+      );
+    }
+  }
+
+  // Results
+  if (results?.length) {
+    md.push(`\n## Results`);
+    results.forEach((result, i) => {
+      md.push(`\n### Result ${i + 1}`);
+      if (result.finding) md.push(`- **Finding:** ${result.finding}`);
+      if (result.significance)
+        md.push(`- **Significance:** ${result.significance}`);
+      if (result.supportingData)
+        md.push(`- **Supporting Data:** ${result.supportingData}`);
+    });
+  }
+
+  // Discussion
+  if (discussion) {
+    md.push(`\n## Discussion`);
+    if (discussion.implications?.length) {
+      md.push(
+        `### Implications\n${discussion.implications
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+    if (discussion.limitations?.length) {
+      md.push(
+        `### Limitations\n${discussion.limitations
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+    if (discussion.futureWork?.length) {
+      md.push(
+        `### Future Work\n${discussion.futureWork
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+  }
+
+  // References
+  if (references?.length) {
+    md.push(`\n## References`);
+    references.forEach((ref, i) => {
+      md.push(
+        `\n**[${i + 1}]** ${ref.title} — *${ref.authors}*${
+          ref.year ? ` (${ref.year})` : ""
+        }`,
+      );
+      if (ref.relevance) md.push(`> ${ref.relevance}`);
+    });
+  }
+
+  // Publication Info
+  if (publication) {
+    md.push(`\n## Publication`);
+    if (publication.journal) md.push(`- **Journal:** ${publication.journal}`);
+    if (publication.year) md.push(`- **Year:** ${publication.year}`);
+    if (publication.doi) md.push(`- **DOI:** ${publication.doi}`);
+    if (publication.url)
+      md.push(`- **URL:** [${publication.url}](${publication.url})`);
+  }
+
+  return md.join("\n");
+}

examples-ts/extract/src/schema.ts

@@ -0,0 +1,169 @@
+export const dataSchema = {
+  type: "object",
+  required: ["title", "authors", "abstract", "mainFindings"],
+  properties: {
+    title: {
+      type: "string",
+      description: "The full title of the research paper",
+    },
+    authors: {
+      type: "array",
+      description: "List of all authors of the paper",
+      items: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Full name of the author",
+          },
+          affiliation: {
+            type: "string",
+            description:
+              "Institution or organization the author is affiliated with",
+          },
+          email: {
+            type: "string",
+            description: "Contact email of the author if provided",
+          },
+        },
+      },
+    },
+    abstract: {
+      type: "string",
+      description: "Complete abstract or summary of the paper",
+    },
+    keywords: {
+      type: "array",
+      description:
+        "Key terms and phrases that describe the paper's main topics",
+      items: {
+        type: "string",
+      },
+    },
+    mainFindings: {
+      type: "array",
+      description: "Key findings, conclusions, or contributions of the paper",
+      items: {
+        type: "string",
+      },
+    },
+    methodology: {
+      type: "object",
+      description: "Research methods and approaches used",
+      properties: {
+        approach: {
+          type: "string",
+          description: "Overall research approach or study design",
+        },
+        participants: {
+          type: "string",
+          description: "Description of study participants or data sources",
+        },
+        methods: {
+          type: "array",
+          description: "Specific methods, techniques, or tools used",
+          items: {
+            type: "string",
+          },
+        },
+      },
+    },
+    results: {
+      type: "array",
+      description: "Main results and outcomes of the research",
+      items: {
+        type: "object",
+        properties: {
+          finding: {
+            type: "string",
+            description: "Description of the specific result or finding",
+          },
+          significance: {
+            type: "string",
+            description:
+              "Statistical significance or importance of the finding",
+          },
+          supportingData: {
+            type: "string",
+            description: "Relevant statistics, measurements, or data points",
+          },
+        },
+      },
+    },
+    discussion: {
+      type: "object",
+      properties: {
+        implications: {
+          type: "array",
+          description: "Theoretical or practical implications of the findings",
+          items: {
+            type: "string",
+          },
+        },
+        limitations: {
+          type: "array",
+          description: "Study limitations or constraints",
+          items: {
+            type: "string",
+          },
+        },
+        futureWork: {
+          type: "array",
+          description: "Suggested future research directions",
+          items: {
+            type: "string",
+          },
+        },
+      },
+    },
+    references: {
+      type: "array",
+      description:
+        "Key papers cited that are crucial to understanding this work",
+      items: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: "Title of the cited paper",
+          },
+          authors: {
+            type: "string",
+            description: "Authors of the cited paper",
+          },
+          year: {
+            type: "string",
+            description: "Publication year",
+          },
+          relevance: {
+            type: "string",
+            description: "Why this reference is important to the current paper",
+          },
+        },
+        required: ["title", "authors"],
+      },
+    },
+    publication: {
+      type: "object",
+      properties: {
+        journal: {
+          type: "string",
+          description: "Name of the journal or conference",
+        },
+        year: {
+          type: "string",
+          description: "Year of publication",
+        },
+        doi: {
+          type: "string",
+          description: "Digital Object Identifier (DOI) of the paper",
+        },
+        url: {
+          type: "string",
+          description: "URL where the paper can be accessed",
+        },
+      },
+      required: ["year"],
+    },
+  },
+};

examples-ts/extract/src/types/cli-markdown.d.ts

@@ -0,0 +1,4 @@
+declare module "cli-markdown" {
+  function cliMarkdown(input: string): string;
+  export default cliMarkdown;
+}

examples-ts/extract/src/utils.ts

@@ -0,0 +1,33 @@
+import * as readline from "readline/promises";
+import figlet from "figlet";
+import pc from "picocolors";
+
+export async function renderLogo(): Promise<void> {
+  const logoText = figlet.textSync("Extract Demo", {
+    font: "ANSI Shadow",
+    horizontalLayout: "default",
+    verticalLayout: "default",
+    width: 100,
+    whitespaceBreak: true,
+  });
+
+  // Add some styling with picocolors
+  const styledLogo = pc.bold(pc.redBright(logoText));
+
+  // Add some padding/margin
+  console.log("\n");
+  console.log(styledLogo);
+  console.log(pc.gray("─".repeat(60)));
+  console.log("\n");
+}
+
+export async function consoleInput(): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const answer = await rl.question("Path to your file: ");
+  rl.close();
+  return answer;
+}

examples-ts/index/README.md

@@ -40,8 +40,8 @@ A TypeScript demo application showcasing the power of **LlamaCloud Index** - a f
 1. Clone the repository:
 
 ```bash
-git clone <repository-url>
-cd llamaparse-demo
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/index/
 ```
 
 2. Install dependencies:
@@ -120,12 +120,12 @@ pnpm run lint
 
 ## License
 
-MIT License - see the [LICENSE](../../../LICENSE) file for details.
+MIT License - see the [LICENSE](../../LICENSE) file for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run `pnpm format` and `pnpm lint`
+4. Run `pnpm run format` and `pnpm run lint`
 5. Submit a pull request

examples-ts/index/package.json

@@ -42,7 +42,7 @@
     "consola": "^3.4.2",
     "dotenv": "^17.2.1",
     "figlet": "^1.8.2",
-    "llama-cloud-services": "link:../../../ts/llama_cloud_services",
+    "llama-cloud-services": "link:../../ts/llama_cloud_services",
     "picocolors": "^1.1.1"
   }
 }

examples-ts/parse/README.md

@@ -40,8 +40,8 @@ A TypeScript demo application showcasing the power of **LlamaParse** - an intell
 1. Clone the repository:
 
 ```bash
-git clone <repository-url>
-cd llamaparse-demo
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/parse/
 ```
 
 2. Install dependencies:
@@ -113,12 +113,12 @@ pnpm run lint
 
 ## License
 
-MIT License - see the [LICENSE](../../../LICENSE) file for details.
+MIT License - see the [LICENSE](../../LICENSE) file for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run `pnpm format` and `pnpm lint`
+4. Run `pnpm run format` and `pnpm run lint`
 5. Submit a pull request

examples-ts/parse/package.json

@@ -41,7 +41,7 @@
     "ai": "^4.3.19",
     "consola": "^3.4.2",
     "figlet": "^1.8.2",
-    "llama-cloud-services": "link:../../../ts/llama_cloud_services",
+    "llama-cloud-services": "link:../../ts/llama_cloud_services",
     "picocolors": "^1.1.1"
   }
 }

examples-ts/parse/src/logger.ts

@@ -0,0 +1,8 @@
+import { createConsola } from "consola";
+import type { ConsolaInstance } from "consola";
+
+export const logger: ConsolaInstance = createConsola({
+  formatOptions: {
+    date: false,
+  },
+});

examples/README.md

@@ -1,11 +1,9 @@
-# LlamaCloud Services Examples
+# LlamaCloud Services Examples - Python
 
-In this folder you will find several python notebooks and two end-to-end typescript applications that contain examples regarding:
+In this folder you will find several python notebooks that contain examples regarding:
 
-- [LlamaParse - Python](./parse/)
-- [LlamaParse - TypeScript](./parse-ts/)
-- [LlamaExtract - Python](./extract/)
-- [LlamaReport - Python](./report/)
-- [LlamaCloud Index - TypeScript](./index-ts/)
+- [LlamaParse](./parse/)
+- [LlamaExtract](./extract/)
+- [LlamaReport](./report/)
 
-Follow the instructions of each notebook/application to get started!
+Follow the instructions in each notebook to get started!

extract.md

@@ -2,14 +2,40 @@
 
 LlamaExtract provides a simple API for extracting structured data from unstructured documents like PDFs, text files and images.
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+  - [Supported File Types](#supported-file-types)
+  - [Different Input Types](#different-input-types)
+  - [Async Extraction](#async-extraction)
+- [Core Concepts](#core-concepts)
+- [Defining Schemas](#defining-schemas)
+  - [Using Pydantic (Recommended)](#using-pydantic-recommended)
+  - [Using JSON Schema](#using-json-schema)
+  - [Important restrictions on JSON/Pydantic Schema](#important-restrictions-on-jsonpydantic-schema)
+- [Extraction Configuration](#extraction-configuration)
+  - [Configuration Options](#configuration-options)
+- [Extraction Agents (Advanced)](#extraction-agents-advanced)
+  - [Creating Agents](#creating-agents)
+  - [Agent Batch Processing](#agent-batch-processing)
+  - [Updating Agent Schemas](#updating-agent-schemas)
+  - [Managing Agents](#managing-agents)
+  - [When to Use Agents vs Direct Extraction](#when-to-use-agents-vs-direct-extraction)
+- [Installation](#installation)
+- [Tips & Best Practices](#tips--best-practices)
+- [Additional Resources](#additional-resources)
+
 ## Quick Start
 
+The simplest way to get started is to use the stateless API with the extraction configuration and the file/text to extract from:
+
 ```python
 from llama_cloud_services import LlamaExtract
+from llama_cloud import ExtractConfig, ExtractMode
 from pydantic import BaseModel, Field
 
 # Initialize client
-extractor = LlamaExtract()
+extractor = LlamaExtract(api_key="YOUR_API_KEY")
 
 
 # Define schema using Pydantic
@@ -19,29 +45,97 @@ class Resume(BaseModel):
     skills: list[str] = Field(description="Technical skills and technologies")
 
 
-# Create extraction agent
-agent = extractor.create_agent(name="resume-parser", data_schema=Resume)
+# Configure extraction settings
+config = ExtractConfig(extraction_mode=ExtractMode.FAST)
 
-# Extract data from document
-result = agent.extract("resume.pdf")
+# Extract data directly from document - no agent needed!
+result = extractor.extract(Resume, config, "resume.pdf")
 print(result.data)
 ```
 
+### Supported File Types
+
+LlamaExtract supports the following file formats:
+
+- **Documents**: PDF (.pdf), Word (.docx)
+- **Text files**: Plain text (.txt), CSV (.csv), JSON (.json), HTML (.html, .htm), Markdown (.md)
+- **Images**: PNG (.png), JPEG (.jpg, .jpeg)
+
+### Different Input Types
+
+```python
+# From file path (string or Path)
+result = extractor.extract(Resume, config, "resume.pdf")
+
+# From file handle
+with open("resume.pdf", "rb") as f:
+    result = extractor.extract(Resume, config, f)
+
+# From bytes with filename
+with open("resume.pdf", "rb") as f:
+    file_bytes = f.read()
+from llama_cloud_services.extract import SourceText
+
+result = extractor.extract(
+    Resume, config, SourceText(file=file_bytes, filename="resume.pdf")
+)
+
+# From text content
+text = "Name: John Doe\nEmail: john@example.com\nSkills: Python, AI"
+result = extractor.extract(Resume, config, SourceText(text_content=text))
+```
+
+### Async Extraction
+
+For better performance with multiple files or when integrating with async applications.
+Here `queue_extraction` will enqueue the extraction jobs and exit. Alternatively, you
+can use `aextract` to poll for the job and return the extraction results.
+
+```python
+import asyncio
+
+
+async def extract_resumes():
+    # Async extraction
+    result = await extractor.aextract(Resume, config, "resume.pdf")
+    print(result.data)
+
+    # Queue extraction jobs (returns immediately)
+    jobs = await extractor.queue_extraction(
+        Resume, config, ["resume1.pdf", "resume2.pdf"]
+    )
+    print(f"Queued {len(jobs)} extraction jobs")
+    return jobs
+
+
+# Run async function
+jobs = asyncio.run(extract_resumes())
+# Check job status
+for job in jobs:
+    status = agent.get_extraction_job(job.id).status
+    print(f"Job {job.id}: {status}")
+
+# Get results when complete
+results = [agent.get_extraction_run_for_job(job.id) for job in jobs]
+```
+
 ## Core Concepts
 
-- **Extraction Agents**: Reusable extractors configured with a specific schema and extraction settings.
 - **Data Schema**: Structure definition for the data you want to extract in the form of a JSON schema or a Pydantic model.
+- **Extraction Config**: Settings that control how extraction is performed (e.g., speed vs accuracy trade-offs).
 - **Extraction Jobs**: Asynchronous extraction tasks that can be monitored.
+- **Extraction Agents** (Advanced): Reusable extractors configured with a specific schema and extraction settings.
 
 ## Defining Schemas
 
-Schemas can be defined using either Pydantic models or JSON Schema:
+Schemas define the structure of data you want to extract. You can use either Pydantic models or JSON Schema:
 
 ### Using Pydantic (Recommended)
 
 ```python
 from pydantic import BaseModel, Field
 from typing import List, Optional
+from llama_cloud import ExtractConfig, ExtractMode
 
 
 class Experience(BaseModel):
@@ -54,6 +148,11 @@ class Experience(BaseModel):
 class Resume(BaseModel):
     name: str = Field(description="Candidate name")
     experience: List[Experience] = Field(description="Work history")
+
+
+# Use the schema for extraction
+config = ExtractConfig(extraction_mode=ExtractMode.FAST)
+result = extractor.extract(Resume, config, "resume.pdf")
 ```
 
 ### Using JSON Schema
@@ -88,7 +187,9 @@ schema = {
     },
 }
 
-agent = extractor.create_agent(name="resume-parser", data_schema=schema)
+# Use the schema for extraction
+config = ExtractConfig(extraction_mode=ExtractMode.FAST)
+result = extractor.extract(schema, config, "resume.pdf")
 ```
 
 ### Important restrictions on JSON/Pydantic Schema
@@ -108,28 +209,100 @@ be sufficient for a wide variety of use-cases.
   your extraction workflow to fit within these constraints, e.g. by extracting subset of fields
   and later merging them together.
 
-## Other Extraction APIs
+## Extraction Configuration
 
-### Extraction over bytes or text
-
-You can use the `SourceText` class to extract from bytes or text directly without using a file. If passing the file bytes,
-you will need to pass the filename to the `SourceText` class.
+Configure how extraction is performed using `ExtractConfig`. The schema is the most important part, but several configuration options can significantly impact the extraction process.
 
 ```python
-with open("resume.pdf", "rb") as f:
-    file_bytes = f.read()
-result = test_agent.extract(SourceText(file=file_bytes, filename="resume.pdf"))
-```
+from llama_cloud import ExtractConfig, ExtractMode, ChunkMode, ExtractTarget
 
-```python
-result = test_agent.extract(
-    SourceText(text_content="Candidate Name: Jane Doe")
+# Basic configuration
+config = ExtractConfig(
+    extraction_mode=ExtractMode.BALANCED,  # FAST, BALANCED, MULTIMODAL, PREMIUM
+    extraction_target=ExtractTarget.PER_DOC,  # PER_DOC, PER_PAGE
+    system_prompt="Focus on the most recent data",
+    page_range="1-5,10-15",  # Extract from specific pages
+)
+
+# Advanced configuration
+advanced_config = ExtractConfig(
+    extraction_mode=ExtractMode.MULTIMODAL,
+    chunk_mode=ChunkMode.PAGE,  # PAGE, SECTION
+    high_resolution_mode=True,  # Better OCR accuracy
+    invalidate_cache=False,  # Bypass cached results
+    cite_sources=True,  # Enable source citations
+    use_reasoning=True,  # Enable reasoning (not in FAST mode)
+    confidence_scores=True,  # MULTIMODAL/PREMIUM only
 )
 ```
 
-### Batch Processing
+### Key Configuration Options
 
-Process multiple files asynchronously:
+**Extraction Mode**: Controls processing quality and speed
+
+- `FAST`: Fastest processing, suitable for simple documents with no OCR
+- `BALANCED`: Good speed/accuracy tradeoff for text-rich documents
+- `MULTIMODAL`: For visually rich documents with text, tables, and images (recommended)
+- `PREMIUM`: Highest accuracy with OCR, complex table/header detection
+
+**Extraction Target**: Defines extraction scope
+
+- `PER_DOC`: Apply schema to entire document (default)
+- `PER_PAGE`: Apply schema to each page, returns array of results
+
+**Advanced Options**:
+
+- `system_prompt`: Additional system-level instructions
+- `page_range`: Specific pages to extract (e.g., "1,3,5-7,9")
+- `chunk_mode`: Document splitting strategy (`PAGE` or `SECTION`)
+- `high_resolution_mode`: Better OCR for small text (slower processing)
+
+**Extensions** (return additional metadata):
+
+- `cite_sources`: Source tracing for extracted fields
+- `use_reasoning`: Explanations for extraction decisions
+- `confidence_scores`: Quantitative confidence measures (MULTIMODAL/PREMIUM only)
+
+For complete configuration options, advanced settings, and detailed examples, see the [LlamaExtract Configuration Documentation](https://docs.cloud.llamaindex.ai/llamaextract/features/options).
+
+## Extraction Agents (Advanced)
+
+For reusable extraction workflows, you can create extraction agents that encapsulate both schema and configuration:
+
+### Creating Agents
+
+```python
+from llama_cloud_services import LlamaExtract
+from llama_cloud import ExtractConfig, ExtractMode
+from pydantic import BaseModel, Field
+
+# Initialize client
+extractor = LlamaExtract()
+
+
+# Define schema
+class Resume(BaseModel):
+    name: str = Field(description="Full name of candidate")
+    email: str = Field(description="Email address")
+    skills: list[str] = Field(description="Technical skills and technologies")
+
+
+# Configure extraction settings
+config = ExtractConfig(extraction_mode=ExtractMode.FAST)
+
+# Create extraction agent
+agent = extractor.create_agent(
+    name="resume-parser", data_schema=Resume, config=config
+)
+
+# Use the agent
+result = agent.extract("resume.pdf")
+print(result.data)
+```
+
+### Agent Batch Processing
+
+Process multiple files with an agent:
 
 ```python
 # Queue multiple files for extraction
@@ -144,7 +317,7 @@ for job in jobs:
 results = [agent.get_extraction_run_for_job(job.id) for job in jobs]
 ```
 
-### Updating Schemas
+### Updating Agent Schemas
 
 Schemas can be modified and updated after creation:
 
@@ -169,10 +342,26 @@ agent = extractor.get_agent(name="resume-parser")
 extractor.delete_agent(agent.id)
 ```
 
+### When to Use Agents vs Direct Extraction
+
+**Use Direct Extraction When:**
+
+- One-off extractions
+- Different schemas for different documents
+- Simple workflows
+- Getting started quickly
+
+**Use Extraction Agents When:**
+
+- Repeated extractions with the same schema
+- Team collaboration (shared, named extractors)
+- Complex workflows requiring state management
+- Production systems with consistent extraction patterns
+
 ## Installation
 
 ```bash
-pip install llama-extract==0.1.0
+pip install llama-cloud-services
 ```
 
 ## Tips & Best Practices
@@ -193,9 +382,9 @@ At the core of LlamaExtract is the schema, which defines the structure of the da
 2. **Running Extractions**:
    - Note that resetting `agent.schema` will not save the schema to the database,
      until you call `agent.save`, but it will be used for running extractions.
-   - Check job status prior to accessing results. Any extraction error should be available as
-     part of `job.error` or `extraction_run.error` fields for debugging.
-   - Consider async operations (`queue_extraction`) for large-scale extraction once you have finalized your schema.
+   - Check extraction results for any errors. Error information is available in the `result.error` field for debugging.
+   - Consider async operations (`aextract` or `queue_extraction`) for large-scale extraction or when processing multiple files.
+   - For repeated extractions with the same schema, consider creating an extraction agent to avoid redefining the schema each time.
 
 ### Hitting "The response was too long to be processed" Error
 
@@ -208,5 +397,7 @@ Another option (orthogonal to the above) is to break the document into smaller s
 
 ## Additional Resources
 
+- [Extract Documentation](https://docs.cloud.llamaindex.ai/llamaextract/getting_started) - Details on Extract features, API and examples.
 - [Example Notebook](docs/examples-py/extract/resume_screening.ipynb) - Detailed walkthrough of resume parsing
+- [Example Application with TypeScript](./examples-ts/extract/) - End-to-end examples using LlamaExtract TypeScript client.
 - [Discord Community](https://discord.com/invite/eN6D2HQ4aX) - Get help and share feedback

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "ts/**"

py/llama_cloud_services/extract/extract.py

@@ -1,4 +1,5 @@
 import asyncio
+import base64
 import os
 import time
 from io import BufferedIOBase, BufferedReader, BytesIO, TextIOWrapper
@@ -21,6 +22,7 @@ from llama_cloud import (
     ExtractJobCreate,
     ExtractRun,
     File,
+    FileData,
     ExtractMode,
     StatusEnum,
     ExtractTarget,
@@ -47,7 +49,7 @@ SchemaInput = Union[JSONObjectType, Type[BaseModel]]
 
 DEFAULT_EXTRACT_CONFIG = ExtractConfig(
     extraction_target=ExtractTarget.PER_DOC,
-    extraction_mode=ExtractMode.BALANCED,
+    extraction_mode=ExtractMode.MULTIMODAL,
 )
 
 
@@ -62,6 +64,132 @@ def _is_retryable_error(exception: BaseException) -> bool:
     return False
 
 
+async def _validate_schema(
+    client: AsyncLlamaCloud, data_schema: SchemaInput
+) -> JSONObjectType:
+    """Convert SchemaInput to a validated JSON schema dictionary."""
+    processed_schema: JSONObjectType
+    if isinstance(data_schema, dict):
+        # TODO: if we expose a get_validated JSON schema method, we can use it here
+        processed_schema = data_schema  # type: ignore
+    elif isinstance(data_schema, type) and issubclass(data_schema, BaseModel):
+        processed_schema = data_schema.model_json_schema()
+    else:
+        raise ValueError("data_schema must be either a dictionary or a Pydantic model")
+
+    # Validate schema via API
+    validated_schema = await client.llama_extract.validate_extraction_schema(
+        data_schema=processed_schema
+    )
+    return validated_schema.data_schema
+
+
+async def _get_job_with_retry(
+    client: AsyncLlamaCloud,
+    job_id: str,
+    max_attempts: int = 5,
+    initial_wait: float = 1,
+    max_wait: float = 60,
+    jitter: float = 5,
+) -> ExtractJob:
+    """Get extraction job with retry logic."""
+    async for attempt in AsyncRetrying(
+        retry=retry_if_exception(_is_retryable_error),
+        stop=stop_after_attempt(max_attempts),
+        wait=wait_exponential_jitter(initial=initial_wait, max=max_wait, jitter=jitter),
+        reraise=True,
+    ):
+        with attempt:
+            return await client.llama_extract.get_job(job_id=job_id)
+
+
+async def _get_run_with_retry(
+    client: AsyncLlamaCloud,
+    job_id: str,
+    project_id: Optional[str] = None,
+    organization_id: Optional[str] = None,
+    max_attempts: int = 3,
+    initial_wait: float = 1,
+    max_wait: float = 20,
+    jitter: float = 3,
+) -> ExtractRun:
+    """Get extraction run with retry logic."""
+    async for attempt in AsyncRetrying(
+        retry=retry_if_exception(_is_retryable_error),
+        stop=stop_after_attempt(max_attempts),
+        wait=wait_exponential_jitter(initial=initial_wait, max=max_wait, jitter=jitter),
+        reraise=True,
+    ):
+        with attempt:
+            return await client.llama_extract.get_run_by_job_id(
+                job_id=job_id,
+                project_id=project_id,
+                organization_id=organization_id,
+            )
+
+
+async def _wait_for_job_result(
+    client: AsyncLlamaCloud,
+    job_id: str,
+    check_interval: int = 1,
+    max_timeout: int = 2000,
+    verbose: bool = False,
+    project_id: Optional[str] = None,
+    organization_id: Optional[str] = None,
+    job_retry_attempts: int = 5,
+    job_max_wait: float = 60,
+    job_jitter: float = 5,
+    run_retry_attempts: int = 3,
+    run_max_wait: float = 20,
+    run_jitter: float = 3,
+) -> Optional[ExtractRun]:
+    """Wait for and return the results of an extraction job."""
+    start = time.perf_counter()
+    poll_count = 0
+
+    while True:
+        await asyncio.sleep(check_interval)
+        poll_count += 1
+        job = await _get_job_with_retry(
+            client,
+            job_id,
+            max_attempts=job_retry_attempts,
+            max_wait=job_max_wait,
+            jitter=job_jitter,
+        )
+
+        if job.status == StatusEnum.SUCCESS:
+            return await _get_run_with_retry(
+                client,
+                job_id,
+                project_id,
+                organization_id,
+                max_attempts=run_retry_attempts,
+                max_wait=run_max_wait,
+                jitter=run_jitter,
+            )
+        elif job.status == StatusEnum.PENDING:
+            end = time.perf_counter()
+            if end - start > max_timeout:
+                raise Exception(f"Timeout while extracting the file: {job_id}")
+            if verbose and poll_count % 10 == 0:
+                print(".", end="", flush=True)
+            continue
+        else:
+            warnings.warn(
+                f"Failure in job: {job_id}, status: {job.status}, error: {job.error}"
+            )
+            return await _get_run_with_retry(
+                client,
+                job_id,
+                project_id,
+                organization_id,
+                max_attempts=run_retry_attempts,
+                max_wait=run_max_wait,
+                jitter=run_jitter,
+            )
+
+
 class SourceText:
     def __init__(
         self,
@@ -144,6 +272,21 @@ def _extraction_config_warning(config: ExtractConfig) -> None:
             "available in the `extraction_metadata` field for the extraction run.",
             ExperimentalWarning,
         )
+    if config.use_reasoning:
+        if config.extraction_mode == ExtractMode.FAST:
+            raise ValueError(
+                "`reasoning` is only supported with BALANCED, MULTIMODAL, or PREMIUM extraction modes."
+            )
+    if config.cite_sources:
+        if config.extraction_mode in (ExtractMode.FAST, ExtractMode.BALANCED):
+            raise ValueError(
+                "`cite_sources` is only supported with MULTIMODAL or PREMIUM extraction modes."
+            )
+    if config.confidence_scores:
+        if config.extraction_mode in (ExtractMode.FAST, ExtractMode.BALANCED):
+            raise ValueError(
+                "`confidence_scores` is only supported with MULTIMODAL or PREMIUM extraction modes."
+            )
 
 
 class ExtractionAgent:
@@ -194,22 +337,10 @@ class ExtractionAgent:
 
     @data_schema.setter
     def data_schema(self, data_schema: SchemaInput) -> None:
-        processed_schema: JSONObjectType
-        if isinstance(data_schema, dict):
-            # TODO: if we expose a get_validated JSON schema method, we can use it here
-            processed_schema = data_schema  # type: ignore
-        elif isinstance(data_schema, type) and issubclass(data_schema, BaseModel):
-            processed_schema = data_schema.model_json_schema()
-        else:
-            raise ValueError(
-                "data_schema must be either a dictionary or a Pydantic model"
-            )
-        validated_schema = self._run_in_thread(
-            self._client.llama_extract.validate_extraction_schema(
-                data_schema=processed_schema
-            )
+        # Use the shared schema processing and validation function
+        self._data_schema = self._run_in_thread(
+            _validate_schema(self._client, data_schema)
         )
-        self._data_schema = validated_schema.data_schema
 
     @property
     def config(self) -> ExtractConfig:
@@ -268,7 +399,9 @@ class ExtractionAgent:
                 project_id=self._project_id, upload_file=file_contents
             )
         finally:
-            if file_contents is not None and isinstance(file_contents, BufferedReader):
+            if file_contents is not None and isinstance(
+                file_contents, (BufferedReader, BytesIO)
+            ):
                 file_contents.close()
 
     async def _upload_file(self, file_input: FileInput) -> File:
@@ -296,60 +429,23 @@ class ExtractionAgent:
 
         return await self.upload_file(source_text)
 
-    async def _get_job_with_retry(self, job_id: str) -> ExtractJob:
-        """Get job with retry logic for transient errors."""
-        async for attempt in AsyncRetrying(
-            retry=retry_if_exception(_is_retryable_error),
-            stop=stop_after_attempt(5),
-            wait=wait_exponential_jitter(initial=1, max=60, jitter=5),
-            reraise=True,
-        ):
-            with attempt:
-                return await self._client.llama_extract.get_job(job_id=job_id)
-
-    async def _get_run_with_retry(self, job_id: str) -> ExtractRun:
-        """Get extraction run with retry logic for transient errors."""
-        async for attempt in AsyncRetrying(
-            retry=retry_if_exception(_is_retryable_error),
-            stop=stop_after_attempt(3),
-            wait=wait_exponential_jitter(initial=1, max=20, jitter=3),
-            reraise=True,
-        ):
-            with attempt:
-                return await self._client.llama_extract.get_run_by_job_id(job_id=job_id)
-
     async def _wait_for_job_result(self, job_id: str) -> Optional[ExtractRun]:
         """Wait for and return the results of an extraction job."""
-        start = time.perf_counter()
-        tries = 0
-
-        while True:
-            await asyncio.sleep(self.check_interval)
-            tries += 1
-
-            try:
-                job = await self._get_job_with_retry(job_id)
-
-                if job.status == StatusEnum.SUCCESS:
-                    return await self._get_run_with_retry(job_id)
-                elif job.status == StatusEnum.PENDING:
-                    end = time.perf_counter()
-                    if end - start > self.max_timeout:
-                        raise Exception(f"Timeout while extracting the file: {job_id}")
-                    if self._verbose and tries % 10 == 0:
-                        print(".", end="", flush=True)
-                    continue
-                else:
-                    warnings.warn(
-                        f"Failure in job: {job_id}, status: {job.status}, error: {job.error}"
-                    )
-                    return await self._get_run_with_retry(job_id)
-
-            except Exception as e:
-                # If we get a non-retryable error or all retries are exhausted, re-raise
-                if self._verbose:
-                    print(f"\nError in job polling for {job_id}: {e}")
-                raise e
+        return await _wait_for_job_result(
+            client=self._client,
+            job_id=job_id,
+            check_interval=self.check_interval,
+            max_timeout=self.max_timeout,
+            verbose=self._verbose,
+            project_id=self._project_id,
+            organization_id=self._organization_id,
+            job_retry_attempts=5,
+            job_max_wait=60,
+            job_jitter=5,
+            run_retry_attempts=3,
+            run_max_wait=20,
+            run_jitter=3,
+        )
 
     def save(self) -> None:
         """Persist the extraction agent's schema and config to the database.
@@ -643,12 +739,14 @@ class LlamaExtract(BaseComponent):
             base_url = os.getenv("LLAMA_CLOUD_BASE_URL", None) or DEFAULT_BASE_URL
 
         super().__init__(
-            api_key=api_key,
-            base_url=base_url,
+            api_key=api_key,  # type: ignore
+            base_url=base_url,  # type: ignore
             check_interval=check_interval,
             max_timeout=max_timeout,
             num_workers=num_workers,
             show_progress=show_progress,
+            project_id=project_id,
+            organization_id=organization_id,
             verify=verify,
             httpx_timeout=httpx_timeout,
             verbose=verbose,
@@ -702,7 +800,7 @@ class LlamaExtract(BaseComponent):
             config = DEFAULT_EXTRACT_CONFIG
 
         if isinstance(data_schema, dict):
-            data_schema = data_schema
+            pass
         elif issubclass(data_schema, BaseModel):
             data_schema = data_schema.model_json_schema()
         else:
@@ -803,6 +901,8 @@ class LlamaExtract(BaseComponent):
                 num_workers=self.num_workers,
                 show_progress=self.show_progress,
                 verbose=self.verbose,
+                verify=self.verify,
+                httpx_timeout=self.httpx_timeout,
             )
             for agent in agents
         ]
@@ -819,6 +919,245 @@ class LlamaExtract(BaseComponent):
             )
         )
 
+    async def _wait_for_job_result(self, job_id: str) -> Optional[ExtractRun]:
+        """Wait for and return the results of an extraction job."""
+        return await _wait_for_job_result(
+            client=self._async_client,
+            job_id=job_id,
+            check_interval=self.check_interval,
+            max_timeout=self.max_timeout,
+            verbose=self.verbose,
+            project_id=self._project_id,
+            organization_id=self._organization_id,
+            job_retry_attempts=3,
+            job_max_wait=4,
+            job_jitter=5,
+            run_retry_attempts=3,
+            run_max_wait=4,
+            run_jitter=3,
+        )
+
+    def _get_mime_type(
+        self,
+        filename: Optional[str] = None,
+        file_path: Optional[Union[str, Path]] = None,
+    ) -> str:
+        """Determine MIME type for a file based on filename or path."""
+        # MIME type mappings for supported formats
+        MIME_TYPE_MAP = {
+            # Text files
+            ".txt": "text/plain",
+            ".csv": "text/csv",
+            ".json": "application/json",
+            ".html": "text/html",
+            ".htm": "text/html",
+            ".md": "text/markdown",
+            # Document files
+            ".pdf": "application/pdf",
+            ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            # Image files
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+        }
+
+        # Try to get extension from filename or file_path
+        extension = None
+        if filename:
+            extension = Path(filename).suffix.lower()
+        elif file_path:
+            extension = Path(file_path).suffix.lower()
+
+        # Check if the extension is supported
+        if extension and extension in MIME_TYPE_MAP:
+            return MIME_TYPE_MAP[extension]
+
+        # If we don't have a supported extension, provide helpful error message
+        supported_extensions = [ext[1:] for ext in MIME_TYPE_MAP.keys()]  # Remove dots
+        supported_list = ", ".join(sorted(supported_extensions))
+
+        if extension:
+            ext_without_dot = extension[1:]  # Remove the leading dot
+            raise ValueError(
+                f"Unsupported file type: '{ext_without_dot}'. "
+                f"Supported formats are: {supported_list}"
+            )
+        else:
+            raise ValueError(
+                f"Could not determine file type. Please provide a filename with one of these supported extensions: {supported_list}"
+            )
+
+    def _convert_file_to_file_data(self, file_input: FileInput) -> Union[FileData, str]:
+        """Convert FileInput to FileData or text string for stateless extraction."""
+        if isinstance(file_input, SourceText):
+            if file_input.text_content is not None:
+                return file_input.text_content
+            elif file_input.file is not None:
+                if isinstance(file_input.file, bytes):
+                    data = file_input.file
+                    filename = file_input.filename
+                elif isinstance(file_input.file, (str, Path)):
+                    with open(file_input.file, "rb") as f:
+                        data = f.read()
+                    filename = file_input.filename or str(file_input.file)
+                elif isinstance(file_input.file, (BufferedIOBase, TextIOWrapper)):
+                    if hasattr(file_input.file, "read"):
+                        content = file_input.file.read()
+                        if isinstance(content, str):
+                            data = content.encode("utf-8")
+                        else:
+                            data = content
+                    else:
+                        raise ValueError("File object must have a read method")
+                    filename = file_input.filename or getattr(
+                        file_input.file, "name", None
+                    )
+                else:
+                    raise ValueError(f"Unsupported file type: {type(file_input.file)}")
+
+                # Encode as base64
+                encoded_data = base64.b64encode(data).decode("utf-8")
+
+                # Determine mime type
+                mime_type = self._get_mime_type(filename=filename)
+
+                return FileData(data=encoded_data, mime_type=mime_type)
+            else:
+                raise ValueError("SourceText must have either text_content or file")
+
+        elif isinstance(file_input, (str, Path)):
+            with open(file_input, "rb") as f:
+                data = f.read()
+            encoded_data = base64.b64encode(data).decode("utf-8")
+            mime_type = self._get_mime_type(file_path=file_input)
+            return FileData(data=encoded_data, mime_type=mime_type)
+
+        elif isinstance(file_input, bytes):
+            # For raw bytes, we can't determine the file type, so we need to raise an error
+            raise ValueError(
+                "Cannot determine file type from raw bytes. Please use SourceText with a filename, or provide a file path."
+            )
+
+        elif isinstance(file_input, (BufferedIOBase, TextIOWrapper)):
+            if hasattr(file_input, "read"):
+                content = file_input.read()
+                if isinstance(content, str):
+                    data = content.encode("utf-8")
+                else:
+                    data = content
+                encoded_data = base64.b64encode(data).decode("utf-8")
+
+                # Try to get filename from the file object
+                filename = getattr(file_input, "name", None)
+                mime_type = self._get_mime_type(filename=filename)
+
+                return FileData(data=encoded_data, mime_type=mime_type)
+            else:
+                raise ValueError("File object must have a read method")
+
+        else:
+            raise ValueError(f"Unsupported file input type: {type(file_input)}")
+
+    async def queue_extraction(
+        self,
+        data_schema: SchemaInput,
+        config: ExtractConfig,
+        files: Union[FileInput, List[FileInput]],
+    ) -> Union[ExtractJob, List[ExtractJob]]:
+        """Queue extraction jobs using stateless extraction (no agent required).
+
+        Args:
+            data_schema: The schema defining what data to extract
+            config: The extraction configuration
+            files: File(s) to extract from
+
+        Returns:
+            ExtractJob or list of ExtractJobs
+        """
+        _extraction_config_warning(config)
+        processed_schema = await _validate_schema(self._async_client, data_schema)
+
+        if not isinstance(files, list):
+            files = [files]
+
+        jobs = []
+        for file_input in files:
+            file_data_or_text = self._convert_file_to_file_data(file_input)
+
+            if isinstance(file_data_or_text, str):
+                # It's text content
+                job = await self._async_client.llama_extract.extract_stateless(
+                    project_id=self._project_id,
+                    organization_id=self._organization_id,
+                    data_schema=processed_schema,
+                    config=config,
+                    text=file_data_or_text,
+                )
+            else:
+                # It's FileData
+                job = await self._async_client.llama_extract.extract_stateless(
+                    project_id=self._project_id,
+                    organization_id=self._organization_id,
+                    data_schema=processed_schema,
+                    config=config,
+                    file=file_data_or_text,
+                )
+            jobs.append(job)
+
+        return jobs[0] if len(jobs) == 1 else jobs
+
+    async def aextract(
+        self,
+        data_schema: SchemaInput,
+        config: ExtractConfig,
+        files: Union[FileInput, List[FileInput]],
+    ) -> Union[ExtractRun, List[ExtractRun]]:
+        """Run stateless extraction and wait for results.
+
+        Args:
+            data_schema: The schema defining what data to extract
+            config: The extraction configuration
+            files: File(s) to extract from
+
+        Returns:
+            ExtractRun or list of ExtractRuns with the extraction results
+        """
+        jobs = await self.queue_extraction(data_schema, config, files)
+
+        if isinstance(jobs, list):
+            runs = []
+            for job in jobs:
+                run = await self._wait_for_job_result(job.id)
+                if run is None:
+                    raise RuntimeError(
+                        f"Failed to get extraction result for job {job.id}"
+                    )
+                runs.append(run)
+            return runs
+        else:
+            run = await self._wait_for_job_result(jobs.id)
+            if run is None:
+                raise RuntimeError(f"Failed to get extraction result for job {jobs.id}")
+            return run
+
+    def extract(
+        self,
+        data_schema: SchemaInput,
+        config: ExtractConfig,
+        files: Union[FileInput, List[FileInput]],
+    ) -> Union[ExtractRun, List[ExtractRun]]:
+        """Run stateless extraction and wait for results (synchronous version).
+
+        Args:
+            data_schema: The schema defining what data to extract
+            config: The extraction configuration
+            files: File(s) to extract from
+
+        Returns:
+            ExtractRun or list of ExtractRuns with the extraction results
+        """
+        return self._run_in_thread(self.aextract(data_schema, config, files))
+
     def __del__(self) -> None:
         """Cleanup resources properly."""
         try:
@@ -833,6 +1172,20 @@ if __name__ == "__main__":
 
     load_dotenv()
 
+    # Example usage:
+    #
+    # # Basic usage with stateless extraction (no agent required)
+    # extractor = LlamaExtract()
+    # schema = {"name": {"type": "string"}, "email": {"type": "string"}}
+    # config = ExtractConfig(extraction_mode=ExtractMode.FAST)
+    # files = ["path/to/document.pdf"]
+    #
+    # # Queue extraction jobs
+    # jobs = extractor.queue_extraction(schema, config, files)
+    #
+    # # Or run extraction and wait for results
+    # results = extractor.extract(schema, config, files)
+
     data_dir = Path(__file__).parent.parent / "tests" / "data"
     extractor = LlamaExtract()
     try:

py/llama_cloud_services/parse/base.py

@@ -25,7 +25,7 @@ from llama_index.core.readers.base import BasePydanticReader
 from llama_index.core.readers.file.base import get_default_fs
 from llama_index.core.schema import Document
 
-from llama_cloud_services.utils import check_extra_params
+from llama_cloud_services.utils import check_extra_params, check_for_updates
 from llama_cloud_services.parse.types import JobResult
 from llama_cloud_services.parse.utils import (
     SUPPORTED_FILE_TYPES,
@@ -541,6 +541,11 @@ class LlamaParse(BasePydanticReader):
         description="Whether to use the vendor multimodal API.",
     )
 
+    check_for_updates: Optional[bool] = Field(
+        default=False,
+        description="Automatically check for Python SDK updates.",
+    )
+
     @model_validator(mode="before")
     @classmethod
     def warn_extra_params(cls, data: Dict[str, Any]) -> Dict[str, Any]:
@@ -596,6 +601,16 @@ class LlamaParse(BasePydanticReader):
 
         return self._aclient
 
+    _update_checked = False
+
+    async def _check_for_updates(self) -> None:
+        if self.check_for_updates and not self._update_checked:
+            try:
+                await check_for_updates(self.aclient, quiet=False)
+                self._update_checked = True
+            except (ValueError, httpx.HTTPStatusError):
+                pass
+
     @asynccontextmanager
     async def client_context(self) -> AsyncGenerator[httpx.AsyncClient, None]:
         """Create a context for the HTTPX client."""
@@ -645,6 +660,7 @@ class LlamaParse(BasePydanticReader):
         fs: Optional[AbstractFileSystem] = None,
         partition_target_pages: Optional[str] = None,
     ) -> str:
+        await self._check_for_updates()
         files = None
         file_handle = None
         input_url = file_input if self._is_input_url(file_input) else None
@@ -1534,6 +1550,7 @@ class LlamaParse(BasePydanticReader):
         self, json_result: List[dict], download_path: str, asset_key: str
     ) -> List[dict]:
         """Download assets (images or charts) from the parsed result."""
+        await self._check_for_updates()
         # Make the download path
         if not os.path.exists(download_path):
             os.makedirs(download_path)
@@ -1642,6 +1659,7 @@ class LlamaParse(BasePydanticReader):
         self, json_result: List[dict], download_path: str
     ) -> List[dict]:
         """Download xlsx from the parsed result."""
+        await self._check_for_updates()
         # make the download path
         if not os.path.exists(download_path):
             os.makedirs(download_path)

py/llama_cloud_services/parse/types.py

@@ -52,6 +52,10 @@ class PageItem(BaseModel):
     bBox: Optional[BBox] = Field(
         default=None, description="The bounding box of the item."
     )
+    html: Optional[str] = Field(
+        default=None,
+        description="The HTML-formatted content of the item. Only applicable for table items when output_tables_as_HTML=True.",
+    )
 
 
 class ImageItem(BaseModel):

py/llama_cloud_services/utils.py

@@ -1,4 +1,9 @@
+import os
+import importlib.metadata
+
 import difflib
+import httpx
+import packaging.version
 from pydantic import BaseModel
 from typing import Any, Dict, List, Tuple, Type
 
@@ -27,3 +32,36 @@ def check_extra_params(
                 )
 
     return extra_params, suggestions
+
+
+async def check_for_updates(client: httpx.AsyncClient, quiet: bool = True) -> bool:
+    """Check if an SDK update is available.
+
+    Args:
+        client: HTTPX client to use.
+        quiet: If False, update availability will also be printed to stdout.
+
+    Returns: True if an update is available.
+
+    Raises:
+        ValueError: Failed to get a valid release version from PyPI.
+    """
+    package_name = "llama-cloud-services"
+    r = await client.get(f"https://pypi.org/pypi/{package_name}/json")
+    version = r.json().get("info", {}).get("version", "")
+    if not version:
+        raise ValueError("Failed to fetch package info from PyPI")
+    latest = packaging.version.parse(version)
+    current = packaging.version.parse(importlib.metadata.version(package_name))
+    if current < latest:
+        if not quiet:
+            msg = [
+                f"\u26A0\uFE0F {package_name} is out of date",
+                f"Current version: {current} | Latest: {latest}",
+                "To upgrade: pip install -U --force-reinstall llama-cloud-services",
+            ]
+            print(os.linesep.join(msg))
+        return True
+    elif not quiet:
+        print(f"{package_name} is up to date")
+    return False

py/llama_parse/pyproject.toml

@@ -11,13 +11,13 @@ dev = [
 
 [project]
 name = "llama-parse"
-version = "0.6.54"
+version = "0.6.56"
 description = "Parse files into RAG-Optimized formats."
 authors = [{name = "Logan Markewich", email = "logan@llamaindex.ai"}]
 requires-python = ">=3.9,<4.0"
 readme = "README.md"
 license = "MIT"
-dependencies = ["llama-cloud-services>=0.6.54"]
+dependencies = ["llama-cloud-services>=0.6.56"]
 
 [project.scripts]
 llama-parse = "llama_parse.cli.main:parse"

py/pyproject.toml

@@ -17,7 +17,7 @@ dev = [
 
 [project]
 name = "llama-cloud-services"
-version = "0.6.54"
+version = "0.6.56"
 description = "Tailored SDK clients for LlamaCloud services."
 authors = [{name = "Logan Markewich", email = "logan@runllama.ai"}]
 requires-python = ">=3.9,<4.0"
@@ -25,13 +25,14 @@ readme = "README.md"
 license = "MIT"
 dependencies = [
   "llama-index-core>=0.12.0",
-  "llama-cloud==0.1.35",
+  "llama-cloud==0.1.37",
   "pydantic>=2.8,!=2.10",
   "click>=8.1.7,<9",
   "python-dotenv>=1.0.1,<2",
   "eval-type-backport>=0.2.0,<0.3 ; python_version < '3.10'",
   "platformdirs>=4.3.7,<5",
-  "tenacity>=8.5.0, <10.0"
+  "tenacity>=8.5.0, <10.0",
+  "packaging>=25.0"
 ]
 
 [project.scripts]

py/tests/beta/agent_data/test_agent_data_client.py

@@ -37,7 +37,7 @@ LLAMA_CLOUD_BASE_URL = os.getenv("LLAMA_CLOUD_BASE_URL")
 LLAMA_DEPLOY_DEPLOYMENT_NAME = os.getenv("LLAMA_DEPLOY_DEPLOYMENT_NAME")
 
 
-class TestData(BaseModel):
+class ExampleData(BaseModel):
     """Simple test data model for agent data testing"""
 
     name: str
@@ -66,13 +66,13 @@ async def test_agent_data_crud_operations():
     # Create agent data client with unique collection name
     agent_data_client = AsyncAgentDataClient(
         client=client,
-        type=TestData,
+        type=ExampleData,
         collection=f"test-collection-{test_id[:8]}",
         agent_url_id=LLAMA_DEPLOY_DEPLOYMENT_NAME,
     )
 
     # Create test data
-    test_data = TestData(name="test-item", test_id=test_id, value=42)
+    test_data = ExampleData(name="test-item", test_id=test_id, value=42)
 
     created_item = None
     try:
@@ -107,7 +107,7 @@ async def test_agent_data_crud_operations():
         assert aggregate_results.items[0].count == 1
 
         # Test UPDATE
-        updated_data = TestData(name="updated-item", test_id=test_id, value=84)
+        updated_data = ExampleData(name="updated-item", test_id=test_id, value=84)
         updated_item = await agent_data_client.update_item(
             created_item.id, updated_data
         )

py/tests/extract/conftest.py

@@ -6,6 +6,12 @@ from llama_cloud_services.extract import LlamaExtract
 _TEST_AGENTS_TO_CLEANUP: List[str] = []
 
 
+def pytest_configure(config):
+    """Register custom markers for extract tests."""
+    config.addinivalue_line("markers", "agent_name: custom agent name for test")
+    config.addinivalue_line("markers", "agent_schema: custom agent schema for test")
+
+
 def pytest_sessionfinish(session, exitstatus):
     """Hook that runs after all tests complete - cleanup agents here"""
     print(

py/tests/extract/test_benchmark.py

@@ -23,8 +23,9 @@ LLAMA_CLOUD_API_KEY = os.getenv("LLAMA_CLOUD_API_KEY")
 LLAMA_CLOUD_BASE_URL = os.getenv("LLAMA_CLOUD_BASE_URL")
 LLAMA_CLOUD_PROJECT_ID = os.getenv("LLAMA_CLOUD_PROJECT_ID")
 
-TestCase = namedtuple(
-    "TestCase", ["name", "schema_path", "config", "input_file", "expected_output"]
+BenchmarkTestCase = namedtuple(
+    "BenchmarkTestCase",
+    ["name", "schema_path", "config", "input_file", "expected_output"],
 )
 
 
@@ -32,7 +33,7 @@ def get_test_cases():
     """Get all test cases from TEST_DIR.
 
     Returns:
-        List[TestCase]: List of test cases
+        List[BenchmarkTestCase]: List of test cases
     """
     test_cases = []
 
@@ -73,7 +74,7 @@ def get_test_cases():
             test_name = f"{data_type}/{os.path.basename(input_file)}"
             for setting in settings:
                 test_cases.append(
-                    TestCase(
+                    BenchmarkTestCase(
                         name=test_name,
                         schema_path=schema_path,
                         input_file=input_file,
@@ -100,7 +101,7 @@ def extractor():
 
 
 @pytest.fixture
-def extraction_agent(test_case: TestCase, extractor: LlamaExtract):
+def extraction_agent(test_case: BenchmarkTestCase, extractor: LlamaExtract):
     """Fixture to create and cleanup extraction agent for each test."""
     # Create unique name with random UUID (important for CI to avoid conflicts)
     unique_id = uuid.uuid4().hex[:8]
@@ -130,7 +131,7 @@ def extraction_agent(test_case: TestCase, extractor: LlamaExtract):
 @pytest.mark.parametrize("test_case", get_test_cases(), ids=lambda x: x.name)
 @pytest.mark.asyncio(loop_scope="session")
 async def test_extraction(
-    test_case: TestCase, extraction_agent: ExtractionAgent
+    test_case: BenchmarkTestCase, extraction_agent: ExtractionAgent
 ) -> None:
     start = perf_counter()
     result = await extraction_agent._run_extraction_test(

py/tests/extract/test_extract_api.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from pydantic import BaseModel
 
 from llama_cloud_services.extract import LlamaExtract, ExtractionAgent, SourceText
+from llama_cloud.types import ExtractConfig, ExtractMode, ExtractRun
 from tests.extract.util import load_test_dotenv
 from .conftest import register_agent_for_cleanup
 
@@ -21,7 +22,7 @@ pytestmark = pytest.mark.skipif(
 
 
 # Test data
-class TestSchema(BaseModel):
+class ExampleSchema(BaseModel):
     title: str
     summary: str
 
@@ -107,7 +108,7 @@ class TestLlamaExtract:
         assert isinstance(test_agent, ExtractionAgent)
 
     @pytest.mark.agent_name("test-pydantic-schema-agent")
-    @pytest.mark.agent_schema((TestSchema,))
+    @pytest.mark.agent_schema((ExampleSchema,))
     def test_create_agent_with_pydantic_schema(self, test_agent):
         assert isinstance(test_agent, ExtractionAgent)
 
@@ -222,7 +223,189 @@ class TestExtractionAgent:
 
     def test_delete_extraction_run(self, test_agent: ExtractionAgent):
         assert test_agent.list_extraction_runs().total == 0
-        run = test_agent.extract(TEST_PDF)
+        run: ExtractRun = test_agent.extract(TEST_PDF)
         test_agent.delete_extraction_run(run.id)
         runs = test_agent.list_extraction_runs()
         assert runs.total == 0
+
+
+@pytest.mark.skipif(
+    "CI" in os.environ, reason="Test locally; functionality is mostly duplicated."
+)
+class TestStatelessExtraction:
+    """Tests for stateless extraction methods that don't require creating an agent."""
+
+    @pytest.fixture
+    def test_config(self):
+        return ExtractConfig(extraction_mode=ExtractMode.FAST)
+
+    @pytest.fixture
+    def test_schema_dict(self):
+        return {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "summary": {"type": "string"},
+            },
+        }
+
+    @pytest.mark.asyncio
+    async def test_aextract_single_file(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test async stateless extraction with a single file."""
+        result = await llama_extract.aextract(test_schema_dict, test_config, TEST_PDF)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_single_file(self, llama_extract, test_schema_dict, test_config):
+        """Test synchronous stateless extraction with a single file."""
+        result = llama_extract.extract(test_schema_dict, test_config, TEST_PDF)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_from_bytes_with_source_text(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test stateless extraction from bytes using SourceText with filename."""
+        with open(TEST_PDF, "rb") as f:
+            file_bytes = f.read()
+        source_text = SourceText(file=file_bytes, filename=TEST_PDF.name)
+        result = llama_extract.extract(test_schema_dict, test_config, source_text)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_from_source_text_with_file(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test stateless extraction from SourceText with file."""
+        source_text = SourceText(file=TEST_PDF, filename=TEST_PDF.name)
+        result = llama_extract.extract(test_schema_dict, test_config, source_text)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_from_buffered_io(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test stateless extraction from BufferedIO file handle."""
+        with open(TEST_PDF, "rb") as file_handle:
+            result = llama_extract.extract(test_schema_dict, test_config, file_handle)
+            assert result.status == "SUCCESS"
+            assert result.data is not None
+            assert isinstance(result.data, dict)
+            assert "title" in result.data
+            assert "summary" in result.data
+
+    def test_extract_from_source_text_with_text_content(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test stateless extraction from SourceText with text content."""
+        TEST_TEXT = """
+        # Llamas
+        Llamas are social animals and live with others as a herd. Their wool is soft and
+        contains only a small amount of lanolin. Llamas can learn simple tasks after a
+        few repetitions. When using a pack, they can carry about 25 to 30% of their body
+        weight for 8 to 13 km (5–8 miles). The name llama was adopted by European settlers
+        from native Peruvians.
+        """
+        source_text = SourceText(text_content=TEST_TEXT)
+        result = llama_extract.extract(test_schema_dict, test_config, source_text)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    @pytest.mark.asyncio
+    async def test_queue_extraction_single_file(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test queuing extraction job without waiting for completion."""
+        job = await llama_extract.queue_extraction(
+            test_schema_dict, test_config, TEST_PDF
+        )
+        assert hasattr(job, "id")
+        assert hasattr(job, "status")
+
+    @pytest.mark.asyncio
+    async def test_extract_multiple_files(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test stateless extraction with multiple files."""
+        files = [TEST_PDF, TEST_PDF]  # Using same file twice for testing
+        results = await llama_extract.aextract(test_schema_dict, test_config, files)
+
+        assert isinstance(results, list)
+        assert len(results) == 2
+
+        for result in results:
+            assert result.status == "SUCCESS"
+            assert result.data is not None
+            assert isinstance(result.data, dict)
+            assert "title" in result.data
+            assert "summary" in result.data
+
+    def test_extract_with_pydantic_schema(self, llama_extract, test_config):
+        """Test stateless extraction with Pydantic schema."""
+        result = llama_extract.extract(ExampleSchema, test_config, TEST_PDF)
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_from_raw_bytes_raises_error(
+        self, llama_extract, test_schema_dict, test_config
+    ):
+        """Test that raw bytes without filename raises an error."""
+        with open(TEST_PDF, "rb") as f:
+            file_bytes = f.read()
+
+        with pytest.raises(
+            ValueError, match="Cannot determine file type from raw bytes"
+        ):
+            llama_extract.extract(test_schema_dict, test_config, file_bytes)
+
+    def test_mime_type_detection(self, llama_extract):
+        """Test that MIME types are correctly detected for various file types."""
+        # Test PDF
+        assert llama_extract._get_mime_type(filename="test.pdf") == "application/pdf"
+
+        # Test DOCX
+        assert (
+            llama_extract._get_mime_type(filename="test.docx")
+            == "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        )
+
+        # Test text files
+        assert llama_extract._get_mime_type(filename="test.txt") == "text/plain"
+        assert llama_extract._get_mime_type(filename="test.csv") == "text/csv"
+        assert llama_extract._get_mime_type(filename="test.json") == "application/json"
+
+        # Test image files
+        assert llama_extract._get_mime_type(filename="test.png") == "image/png"
+        assert llama_extract._get_mime_type(filename="test.jpg") == "image/jpeg"
+
+        # Test file path
+        from pathlib import Path
+
+        assert (
+            llama_extract._get_mime_type(file_path=Path("test.pdf"))
+            == "application/pdf"
+        )
+
+        # Test unsupported file type
+        with pytest.raises(ValueError, match="Unsupported file type: 'xyz'"):
+            llama_extract._get_mime_type(filename="test.xyz")

py/tests/extract/test_extract_e2e.py

@@ -19,8 +19,9 @@ LLAMA_CLOUD_API_KEY = os.getenv("LLAMA_CLOUD_API_KEY")
 LLAMA_CLOUD_BASE_URL = os.getenv("LLAMA_CLOUD_BASE_URL")
 LLAMA_CLOUD_PROJECT_ID = os.getenv("LLAMA_CLOUD_PROJECT_ID")
 
-TestCase = namedtuple(
-    "TestCase", ["name", "schema_path", "config", "input_file", "expected_output"]
+ExtractionTestCase = namedtuple(
+    "ExtractionTestCase",
+    ["name", "schema_path", "config", "input_file", "expected_output"],
 )
 
 
@@ -28,7 +29,7 @@ def get_test_cases():
     """Get all test cases from TEST_DIR.
 
     Returns:
-        List[TestCase]: List of test cases
+        List[ExtractionTestCase]: List of test cases
     """
     test_cases = []
 
@@ -69,7 +70,7 @@ def get_test_cases():
             test_name = f"{data_type}/{os.path.basename(input_file)}"
             for setting in settings:
                 test_cases.append(
-                    TestCase(
+                    ExtractionTestCase(
                         name=test_name,
                         schema_path=schema_path,
                         input_file=input_file,
@@ -96,7 +97,7 @@ def extractor():
 
 
 @pytest.fixture
-def extraction_agent(test_case: TestCase, extractor: LlamaExtract):
+def extraction_agent(test_case: ExtractionTestCase, extractor: LlamaExtract):
     """Fixture to create and cleanup extraction agent for each test."""
     # Create unique name with random UUID (important for CI to avoid conflicts)
     unique_id = uuid.uuid4().hex[:8]
@@ -128,7 +129,9 @@ def extraction_agent(test_case: TestCase, extractor: LlamaExtract):
     reason="LLAMA_CLOUD_API_KEY not set",
 )
 @pytest.mark.parametrize("test_case", get_test_cases(), ids=lambda x: x.name)
-def test_extraction(test_case: TestCase, extraction_agent: ExtractionAgent) -> None:
+def test_extraction(
+    test_case: ExtractionTestCase, extraction_agent: ExtractionAgent
+) -> None:
     result = extraction_agent.extract(test_case.input_file).data  # type: ignore
     with open(test_case.expected_output, "r") as f:
         expected = json.load(f)

py/unit_tests/test_utils.py

@@ -1,5 +1,9 @@
+from unittest.mock import Mock
+
+import httpx
+import pytest
 from pydantic import BaseModel
-from llama_cloud_services.utils import check_extra_params
+from llama_cloud_services.utils import check_extra_params, check_for_updates
 
 
 class MyModel(BaseModel):
@@ -64,3 +68,30 @@ def test_check_extra_params_completely_invalid():
     for suggestion in suggestions:
         assert "check the documentation or update the package" in suggestion
         assert "Did you mean" not in suggestion
+
+
+@pytest.mark.asyncio
+async def test_check_for_updates(capsys: pytest.CaptureFixture):
+    """Test update checker."""
+
+    mock_response = Mock()
+    mock_client = Mock(spec=httpx.AsyncClient)
+    mock_client.get.return_value = mock_response
+
+    mock_response.json.return_value = {"info": {"version": "0.0.0"}}
+    assert not await check_for_updates(mock_client)
+    out, err = capsys.readouterr()
+    assert not out and not err
+
+    assert not await check_for_updates(mock_client, quiet=False)
+    out, _ = capsys.readouterr()
+    assert "up to date" in out
+
+    mock_response.json.return_value = {"info": {"version": "999.0.0"}}
+    assert await check_for_updates(mock_client)
+    out, err = capsys.readouterr()
+    assert not out and not err
+
+    assert await check_for_updates(mock_client, quiet=False)
+    out, _ = capsys.readouterr()
+    assert "out of date" in out

py/uv.lock

@@ -1573,21 +1573,21 @@ wheels = [
 
 [[package]]
 name = "llama-cloud"
-version = "0.1.35"
+version = "0.1.37"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "certifi" },
     { name = "httpx" },
     { name = "pydantic" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9b/72/816e6e900448e1b4a8137d90e65876b296c5264a23db6ae888bd3e6660ba/llama_cloud-0.1.35.tar.gz", hash = "sha256:200349d5d57424d7461f304cdb1355a58eea3e6ca1e6b0d75c66b2e937216983", size = 106403, upload-time = "2025-07-28T17:22:06.41Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/9c/dd/c4f2516523778a0d4b284fa4b66a0136afdd59694f105102838cf793e675/llama_cloud-0.1.37.tar.gz", hash = "sha256:b6d62e7386d1aa85905b7e3f7c19a40694be54c1596668bceaa456cd84ede666", size = 108707, upload-time = "2025-08-04T22:00:37.18Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1d/d2/8d18a021ab757cea231428404f21fe3186bf1ebaac3f57a73c379483fd3f/llama_cloud-0.1.35-py3-none-any.whl", hash = "sha256:b7abab4423118e6f638d2f326749e7a07c6426543bea6da99b623c715b22af71", size = 303280, upload-time = "2025-07-28T17:22:04.946Z" },
+    { url = "https://files.pythonhosted.org/packages/59/ca/a7f874b041d2566f000ecc88bf1b76819a8bdbbaea85036ca6905ae3f0f7/llama_cloud-0.1.37-py3-none-any.whl", hash = "sha256:3109ec74575f53311ec4957ca8aea2d6e30556a43d24c6316ceab91c4fed6ab7", size = 314244, upload-time = "2025-08-04T22:00:35.696Z" },
 ]
 
 [[package]]
 name = "llama-cloud-services"
-version = "0.6.54"
+version = "0.6.56"
 source = { editable = "." }
 dependencies = [
     { name = "click", version = "8.1.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
@@ -1595,6 +1595,7 @@ dependencies = [
     { name = "eval-type-backport", marker = "python_full_version < '3.10'" },
     { name = "llama-cloud" },
     { name = "llama-index-core" },
+    { name = "packaging" },
     { name = "platformdirs" },
     { name = "pydantic" },
     { name = "python-dotenv" },
@@ -1619,8 +1620,9 @@ dev = [
 requires-dist = [
     { name = "click", specifier = ">=8.1.7,<9" },
     { name = "eval-type-backport", marker = "python_full_version < '3.10'", specifier = ">=0.2.0,<0.3" },
-    { name = "llama-cloud", specifier = "==0.1.35" },
+    { name = "llama-cloud", specifier = "==0.1.37" },
     { name = "llama-index-core", specifier = ">=0.12.0" },
+    { name = "packaging", specifier = ">=25.0" },
     { name = "platformdirs", specifier = ">=4.3.7,<5" },
     { name = "pydantic", specifier = ">=2.8,!=2.10" },
     { name = "python-dotenv", specifier = ">=1.0.1,<2" },

ts/e2e-tests/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@llamaindex/llama-cloud-services-e2e-tests",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "test": "pnpm run test:node16 && pnpm run test:nodenext && pnpm run test:bundler",
+    "build": "pnpm run build:node16 && pnpm run build:nodenext && pnpm run build:bundler",
+    "build:node16": "tsc -p src/tsconfig.node16.json --outDir dist/node16",
+    "test:node16": "pnpm run build:node16 && node --test dist/node16/index.e2e.js",
+    "build:nodenext": "tsc -p src/tsconfig.nodenext.json --outDir dist/nodenext",
+    "test:nodenext": "pnpm run build:nodenext && node --test dist/nodenext/index.e2e.js",
+    "build:bundler": "tsc -p src/tsconfig.bundler.json --outDir dist/bundler",
+    "test:bundler": "pnpm run build:bundler && node --test dist/bundler/index.e2e.js",
+    "build:node": "tsc -p src/tsconfig.node.json --outDir dist/node",
+    "test:node": "pnpm run build:node && node --test dist/node/index.e2e.js"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "llama-cloud-services": "workspace:*",
+    "typescript": "^5.9.2"
+  }
+}

ts/e2e-tests/src/index.e2e.ts

@@ -0,0 +1,38 @@
+import { ok } from "node:assert";
+import { test } from "node:test";
+
+import { LlamaCloudIndex } from "llama-cloud-services";
+import { LlamaParseReader } from "llama-cloud-services";
+
+test("LlamaIndex module resolution test", async (t) => {
+  await t.test("works with ES module", () => {
+    const index = new LlamaCloudIndex({
+      name: "test-index",
+      projectName: "Default",
+    });
+    const reader = new LlamaParseReader({
+      resultType: "markdown",
+      verbose: false,
+    });
+    ok(index !== undefined);
+    ok(reader !== undefined);
+  });
+
+  await t.test("works with dynamic imports", async () => {
+    const mod = await import("llama-cloud-services"); // simulates commonjs
+    ok(mod !== undefined);
+    const index = new mod.LlamaCloudIndex({
+      name: "test-index",
+      projectName: "Default",
+    });
+    ok(index !== undefined);
+  });
+
+  await t.test("all imports work", () => {
+    const allImports = [
+      LlamaCloudIndex,
+    ];
+
+    ok(allImports.filter(Boolean).length === allImports.length);
+  });
+});

ts/e2e-tests/src/tsconfig.bundler.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

ts/e2e-tests/src/tsconfig.node.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "node",
+    "target": "esnext",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

ts/e2e-tests/src/tsconfig.node16.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16",
+    "target": "esnext",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

ts/e2e-tests/src/tsconfig.nodenext.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "esnext",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

ts/e2e-tests/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": true,
+    "strictNullChecks": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "./src",
+    "outDir": "./dist/type",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "incremental": true,
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable",
+      "DOM.AsyncIterable"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "./src"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

ts/llama_cloud_services/extract/package.json

@@ -0,0 +1,8 @@
+{
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "private": true
+}

ts/llama_cloud_services/openapi.json

@@ -12855,6 +12855,72 @@
         }
       }
     },
+    "/api/v1/extraction/run": {
+      "post": {
+        "tags": ["LlamaExtract"],
+        "summary": "Extract Stateless",
+        "description": "Stateless extraction endpoint that uses a default extraction agent in the user's default project. Requires data_schema, config, and either file_id, text, or base64 encoded file data.",
+        "operationId": "extract_stateless_api_v1_extraction_run_post",
+        "security": [
+          {
+            "HTTPBearer": []
+          },
+          {
+            "HTTPBearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "session",
+            "in": "cookie",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Session"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/StatelessExtractionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExtractJob"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/extraction/jobs": {
       "get": {
         "tags": ["LlamaExtract"],
@@ -35483,6 +35549,64 @@
         "title": "WebhookConfiguration",
         "description": "Allows the user to configure webhook options for notifications and callbacks."
       },
+      "StatelessExtractionRequest": {
+        "type": "object",
+        "required": ["data_schema"],
+        "properties": {
+          "data_schema": {
+            "anyOf": [
+              {
+                "additionalProperties": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": true,
+                      "type": "object"
+                    },
+                    {
+                      "items": {},
+                      "type": "array"
+                    },
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "integer"
+                    },
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "type": "object"
+              },
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "config": {
+            "$ref": "#/components/schemas/ExtractConfig",
+            "description": "The configuration parameters for the extraction agent."
+          },
+          "file_id": {
+            "type": "string",
+            "format": "uuid",
+            "title": "File Id",
+            "description": "ID of an uploaded file to extract from"
+          }
+        },
+        "title": "StatelessExtractionRequest",
+        "description": "Request body for stateless extraction. Must include either file_id, text, or base64."
+      },
       "llama_index__core__base__llms__types__ChatMessage": {
         "properties": {
           "role": {

ts/llama_cloud_services/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llama-cloud-services",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "license": "MIT",
   "scripts": {
@@ -20,7 +20,8 @@
     "./api",
     "./reader",
     "./parse",
-    "./beta/agent"
+    "./beta/agent",
+    "./extract"
   ],
   "exports": {
     "./openapi.json": "./openapi.json",
@@ -68,6 +69,17 @@
       },
       "default": "./parse/dist/index.js"
     },
+    "./extract": {
+      "require": {
+        "types": "./extract/dist/index.d.cts",
+        "default": "./extract/dist/index.cjs"
+      },
+      "import": {
+        "types": "./extract/dist/index.d.ts",
+        "default": "./extract/dist/index.js"
+      },
+      "default": "./extract/dist/index.js"
+    },
     ".": {
       "require": {
         "types": "./dist/index.d.cts",
@@ -113,6 +125,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
+    "file-type": "^21.0.0",
     "p-retry": "^6.2.1",
     "zod": "^3.25.76"
   },

ts/llama_cloud_services/src/LlamaExtract.ts

@@ -0,0 +1,225 @@
+import { createClient, createConfig, type Client } from "@hey-api/client-fetch";
+import { File } from "buffer";
+import * as extract from "./extract";
+import type { ExtractAgent, ExtractConfig } from "./extract";
+import { getEnv } from "@llamaindex/env";
+import type { ExtractResult } from "./type";
+
+const URLS = {
+  us: "https://api.cloud.llamaindex.ai",
+  eu: "https://api.cloud.eu.llamaindex.ai",
+  "us-staging": "https://api.staging.llamaindex.ai",
+} as const;
+
+function getUrl(baseUrl: string | undefined, region: string | undefined) {
+  if (typeof baseUrl != "undefined") {
+    return baseUrl;
+  }
+  if (typeof region === "undefined") {
+    return URLS["us"];
+  } else if (region === "us" || region === "eu" || region === "us-staging") {
+    return URLS[region];
+  } else {
+    throw new Error(`Unsupported region: ${region}`);
+  }
+}
+
+export class LlamaExtractAgent {
+  private agent: ExtractAgent;
+  private client: Client;
+  id: string;
+  name: string;
+  dataSchema: {
+    [key: string]:
+      | string
+      | number
+      | boolean
+      | {
+          [key: string]: unknown;
+        }
+      | unknown[]
+      | null;
+  };
+
+  constructor(agent: ExtractAgent, client: Client) {
+    this.agent = agent;
+    this.client = client;
+    this.id = agent.id;
+    this.name = agent.name;
+    this.dataSchema = agent.data_schema;
+  }
+
+  async extract(
+    filePath: string | undefined = undefined,
+    fileContent:
+      | Buffer<ArrayBufferLike>
+      | Uint8Array<ArrayBuffer>
+      | string
+      | File
+      | undefined = undefined,
+    fileName: string | undefined = undefined,
+    project_id: string | null = null,
+    organization_id: string | null = null,
+    fromUi: boolean | undefined = undefined,
+    pollingInterval: number = 1,
+    maxPollingIterations: number = 1800,
+    maxRetriesOnError: number = 10,
+    retryInterval: number = 0.5,
+  ): Promise<ExtractResult | undefined> {
+    return await extract.extract(
+      this.agent.id,
+      filePath,
+      fileContent,
+      fileName,
+      project_id,
+      organization_id,
+      this.client,
+      fromUi,
+      pollingInterval,
+      maxPollingIterations,
+      maxRetriesOnError,
+      retryInterval,
+    );
+  }
+}
+
+export class LlamaExtract {
+  private client: Client;
+
+  constructor(
+    apiKey: string | undefined = undefined,
+    baseUrl: string | undefined = undefined,
+    region: string | undefined = undefined,
+  ) {
+    const key = apiKey ?? getEnv("LLAMA_CLOUD_API_KEY");
+    if (typeof key === "undefined") {
+      throw new Error(
+        "No API key provided and no API key found in environment. Please pass the API key or set `LLAMA_CLOUD_API_KEY` as an environment variable.",
+      );
+    }
+    const url = getUrl(baseUrl, region);
+    this.client = createClient(
+      createConfig({
+        baseUrl: url,
+        headers: {
+          Authorization: `Bearer ${key}`,
+        },
+      }),
+    );
+  }
+
+  async createAgent(
+    name: string,
+    dataSchema:
+      | {
+          [key: string]:
+            | { [key: string]: unknown }
+            | Array<unknown>
+            | string
+            | number
+            | number
+            | boolean
+            | null;
+        }
+      | string,
+    config: ExtractConfig | undefined = undefined,
+    project_id: string | null = null,
+    organization_id: string | null = null,
+    maxRetriesOnError: number = 10,
+    retryInterval: number = 0.5,
+  ): Promise<LlamaExtractAgent | undefined> {
+    const agent = await extract.createAgent(
+      name,
+      dataSchema,
+      config,
+      project_id,
+      organization_id,
+      this.client,
+      maxRetriesOnError,
+      retryInterval,
+    );
+    if (typeof agent != "undefined") {
+      return new LlamaExtractAgent(agent, this.client);
+    }
+  }
+
+  async getAgent(
+    name: string | undefined = undefined,
+    id: string | undefined = undefined,
+    project_id: string | null = null,
+    organization_id: string | null = null,
+    maxRetriesOnError: number = 10,
+    retryInterval: number = 0.5,
+  ): Promise<LlamaExtractAgent | undefined> {
+    const agent = await extract.getAgent(
+      id,
+      name,
+      project_id,
+      organization_id,
+      this.client,
+      maxRetriesOnError,
+      retryInterval,
+    );
+    if (typeof agent != "undefined") {
+      return new LlamaExtractAgent(agent, this.client);
+    }
+  }
+
+  async deleteAgent(
+    id: string,
+    maxRetriesOnError: number = 10,
+    retryInterval: number = 500,
+  ): Promise<boolean | undefined> {
+    return await extract.deleteAgent(
+      id,
+      this.client,
+      maxRetriesOnError,
+      retryInterval,
+    );
+  }
+
+  async extract(
+    dataSchema:
+      | {
+          [key: string]:
+            | { [key: string]: unknown }
+            | Array<unknown>
+            | string
+            | number
+            | number
+            | boolean
+            | null;
+        }
+      | string,
+    config: ExtractConfig | undefined = undefined,
+    filePath: string | undefined = undefined,
+    fileContent:
+      | Buffer<ArrayBufferLike>
+      | Uint8Array<ArrayBuffer>
+      | string
+      | File
+      | undefined = undefined,
+    fileName: string | undefined = undefined,
+    project_id: string | null = null,
+    organization_id: string | null = null,
+    pollingInterval: number = 1,
+    maxPollingIterations: number = 1800,
+    maxRetriesOnError: number = 10,
+    retryInterval: number = 0.5,
+  ): Promise<ExtractResult | undefined> {
+    return await extract.extractStateless(
+      dataSchema,
+      config,
+      filePath,
+      fileContent,
+      fileName,
+      project_id,
+      organization_id,
+      this.client,
+      pollingInterval,
+      maxPollingIterations,
+      maxRetriesOnError,
+      retryInterval,
+    );
+  }
+}

ts/llama_cloud_services/src/client/schemas.gen.ts

@@ -18644,6 +18644,66 @@ export const WebhookConfigurationSchema = {
     "Allows the user to configure webhook options for notifications and callbacks.",
 } as const;
 
+export const StatelessExtractionRequestSchema = {
+  type: "object",
+  required: ["data_schema"],
+  properties: {
+    data_schema: {
+      anyOf: [
+        {
+          additionalProperties: {
+            anyOf: [
+              {
+                additionalProperties: true,
+                type: "object",
+              },
+              {
+                items: {},
+                type: "array",
+              },
+              {
+                type: "string",
+              },
+              {
+                type: "integer",
+              },
+              {
+                type: "number",
+              },
+              {
+                type: "boolean",
+              },
+              {
+                type: "null",
+              },
+            ],
+          },
+          type: "object",
+        },
+        {
+          type: "string",
+        },
+        {
+          type: "null",
+        },
+      ],
+    },
+    config: {
+      $ref: "#/components/schemas/ExtractConfig",
+      description: "The configuration parameters for the extraction agent.",
+    },
+    file_id: {
+      type: "string",
+      format: "uuid",
+      title: "File Id",
+      description: "ID of an uploaded file to extract from",
+    },
+  },
+  title: "StatelessExtractionRequest",
+  description:
+    "Request body for stateless extraction. Must include either file_id, text, or base64.",
+} as const;
+
 export const llama_index__core__base__llms__types__ChatMessageSchema = {
   properties: {
     role: {

ts/llama_cloud_services/src/client/sdk.gen.ts

@@ -452,6 +452,9 @@ import type {
   UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutData,
   UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutResponse,
   UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutError,
+  ExtractStatelessApiV1ExtractionRunPostData,
+  ExtractStatelessApiV1ExtractionRunPostResponse,
+  ExtractStatelessApiV1ExtractionRunPostError,
   ListJobsApiV1ExtractionJobsGetData,
   ListJobsApiV1ExtractionJobsGetResponse,
   ListJobsApiV1ExtractionJobsGetError,
@@ -5701,6 +5704,39 @@ export const updateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgent
     });
   };
 
+/**
+ * Extract Stateless
+ * Stateless extraction endpoint that uses a default extraction agent in the user's default project. Requires data_schema, config, and either file_id, text, or base64 encoded file data.
+ */
+export const extractStatelessApiV1ExtractionRunPost = <
+  ThrowOnError extends boolean = false,
+>(
+  options: Options<ExtractStatelessApiV1ExtractionRunPostData, ThrowOnError>,
+) => {
+  return (options.client ?? _heyApiClient).post<
+    ExtractStatelessApiV1ExtractionRunPostResponse,
+    ExtractStatelessApiV1ExtractionRunPostError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/api/v1/extraction/run",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+};
+
 /**
  * List Jobs
  */

ts/llama_cloud_services/src/client/types.gen.ts

@@ -8272,6 +8272,35 @@ export type WebhookConfiguration = {
   > | null;
 };
 
+/**
+ * Request body for stateless extraction. Must include either file_id, text, or base64.
+ */
+export type StatelessExtractionRequest = {
+  data_schema:
+    | {
+        [key: string]:
+          | {
+              [key: string]: unknown;
+            }
+          | Array<unknown>
+          | string
+          | number
+          | number
+          | boolean
+          | null;
+      }
+    | string
+    | null;
+  /**
+   * The configuration parameters for the extraction agent.
+   */
+  config?: ExtractConfig;
+  /**
+   * ID of an uploaded file to extract from
+   */
+  file_id?: string;
+};
+
 /**
  * Chat message.
  */
@@ -13078,6 +13107,33 @@ export type UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentI
 export type UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutResponse =
   UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutResponses[keyof UpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutResponses];
 
+export type ExtractStatelessApiV1ExtractionRunPostData = {
+  body: StatelessExtractionRequest;
+  path?: never;
+  query?: never;
+  url: "/api/v1/extraction/run";
+};
+
+export type ExtractStatelessApiV1ExtractionRunPostErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type ExtractStatelessApiV1ExtractionRunPostError =
+  ExtractStatelessApiV1ExtractionRunPostErrors[keyof ExtractStatelessApiV1ExtractionRunPostErrors];
+
+export type ExtractStatelessApiV1ExtractionRunPostResponses = {
+  /**
+   * Successful Response
+   */
+  200: ExtractJob;
+};
+
+export type ExtractStatelessApiV1ExtractionRunPostResponse =
+  ExtractStatelessApiV1ExtractionRunPostResponses[keyof ExtractStatelessApiV1ExtractionRunPostResponses];
+
 export type ListJobsApiV1ExtractionJobsGetData = {
   body?: never;
   path?: never;

ts/llama_cloud_services/src/client/zod.gen.ts

@@ -3472,6 +3472,12 @@ export const zUserOrganizationRoleCreate = z.object({
   role_id: z.string().uuid(),
 });
 
+export const zStatelessExtractionRequest = z.object({
+  data_schema: z.union([z.object({}), z.string(), z.null()]),
+  config: zExtractConfig.optional(),
+  file_id: z.string().uuid().optional(),
+});
+
 export const zListKeysApiV1ApiKeysGetResponse = z.array(zApiKey);
 
 export const zGenerateKeyApiV1ApiKeysPostResponse = zApiKey;
@@ -3829,6 +3835,8 @@ export const zGetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentId
 export const zUpdateExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdPutResponse =
   zExtractAgent;
 
+export const zExtractStatelessApiV1ExtractionRunPostResponse = zExtractJob;
+
 export const zListJobsApiV1ExtractionJobsGetResponse = z.array(zExtractJob);
 
 export const zRunJobApiV1ExtractionJobsPostResponse = zExtractJob;

ts/llama_cloud_services/src/extract.ts

@@ -0,0 +1,651 @@
+import { emitWarning } from "process";
+import fs from "fs/promises";
+import { Blob } from "buffer";
+import * as path from "path";
+import type { ExtractResult } from "./type";
+import { randomUUID } from "@llamaindex/env";
+import { File } from "buffer";
+import {
+  type Options,
+  type ExtractAgentCreate,
+  type ExtractConfig,
+  type ExtractJobCreate,
+  type ExtractAgent,
+  type ExtractJob,
+  type CreateExtractionAgentApiV1ExtractionExtractionAgentsPostData,
+  type GetExtractionAgentByNameApiV1ExtractionExtractionAgentsByNameNameGetData,
+  type GetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGetData,
+  type RunJobApiV1ExtractionJobsPostData,
+  type GetJobApiV1ExtractionJobsJobIdGetData,
+  type GetJobResultApiV1ExtractionJobsJobIdResultGetData,
+  StatusEnum,
+  type UploadFileApiV1FilesPostData,
+  type StatelessExtractionRequest,
+  type ExtractStatelessApiV1ExtractionRunPostData,
+  type DeleteExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdDeleteData,
+  createExtractionAgentApiV1ExtractionExtractionAgentsPost,
+  getExtractionAgentByNameApiV1ExtractionExtractionAgentsByNameNameGet,
+  getExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGet,
+  runJobApiV1ExtractionJobsPost,
+  getJobApiV1ExtractionJobsJobIdGet,
+  getJobResultApiV1ExtractionJobsJobIdResultGet,
+  uploadFileApiV1FilesPost,
+  extractStatelessApiV1ExtractionRunPost,
+  deleteExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdDelete,
+} from "./api";
+import type { Client } from "@hey-api/client-fetch";
+import { sleep } from "./utils";
+import { fileTypeFromBuffer } from "file-type";
+
+type BodyUploadFileApiV1FilesPost = {
+  upload_file: Blob | File;
+};
+
+export async function createAgent(
+  name: string,
+  dataSchema:
+    | {
+        [key: string]:
+          | { [key: string]: unknown }
+          | Array<unknown>
+          | string
+          | number
+          | number
+          | boolean
+          | null;
+      }
+    | string,
+  config: ExtractConfig = {} as ExtractConfig,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  client: Client | undefined = undefined,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<ExtractAgent | undefined> {
+  const agentData = {
+    name: name,
+    data_schema: dataSchema,
+    config: config,
+  } as ExtractAgentCreate;
+  const agentDataCreation = {
+    body: agentData,
+    query: { project_id: project_id, organization_id: organization_id },
+  } as CreateExtractionAgentApiV1ExtractionExtractionAgentsPostData;
+  const options =
+    agentDataCreation as Options<CreateExtractionAgentApiV1ExtractionExtractionAgentsPostData>;
+  if (typeof client != "undefined") {
+    options.client = client;
+  }
+  let retries: number = 0;
+  while (true) {
+    if (retries > maxRetriesOnError) {
+      throw new Error(
+        "Error while creating the agent: Exceeded maximum number of retries, the API keeps returning errors.",
+      );
+    }
+    const response =
+      await createExtractionAgentApiV1ExtractionExtractionAgentsPost(options);
+    if (!response.response.ok) {
+      if ("error" in response) {
+        console.log(
+          `An error occurred while creating the extraction agent.\nDetails:\n\n${JSON.stringify(
+            response.error,
+          )}\n\nRetrying...`,
+        );
+      }
+      retries++;
+      await sleep(retryInterval * 1000);
+    } else {
+      return response.data as ExtractAgent;
+    }
+  }
+}
+
+export async function getAgent(
+  id: string | undefined = undefined,
+  name: string | undefined = undefined,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  client: Client | undefined = undefined,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<ExtractAgent | undefined> {
+  if (typeof id === "undefined" && typeof name === "undefined") {
+    throw new Error("One of `id` and `string` must be passed.");
+  } else if (typeof id != "undefined" && typeof name != "undefined") {
+    emitWarning("You passed both `id` and `name`, using only id...");
+    const data = {
+      path: { extraction_agent_id: id },
+    } as GetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGetData;
+    const options =
+      data as Options<GetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGetData>;
+    if (typeof client != "undefined") {
+      options.client = client;
+    }
+    let retries: number = 0;
+    while (true) {
+      if (retries > maxRetriesOnError) {
+        throw new Error(
+          "Error while getting the agent: Exceeded maximum number of retries, the API keeps returning errors.",
+        );
+      }
+      const response =
+        await getExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGet(
+          options,
+        );
+      if (!response.response.ok) {
+        if ("error" in response) {
+          console.log(
+            `An error occurred while getting the extraction agent by ID.\nDetails:\n\n${JSON.stringify(
+              response.error,
+            )}\n\nRetrying...`,
+          );
+        }
+        retries++;
+        await sleep(retryInterval * 1000);
+      } else {
+        return response.data as ExtractAgent;
+      }
+    }
+  } else if (typeof name != "undefined" && typeof id === "undefined") {
+    const data = {
+      path: { name: name },
+      query: { organization_id: organization_id, project_id: project_id },
+    } as GetExtractionAgentByNameApiV1ExtractionExtractionAgentsByNameNameGetData;
+    const options =
+      data as Options<GetExtractionAgentByNameApiV1ExtractionExtractionAgentsByNameNameGetData>;
+    if (typeof client != "undefined") {
+      options.client = client;
+    }
+    let retries: number = 0;
+    while (true) {
+      if (retries > maxRetriesOnError) {
+        throw new Error(
+          "Error while getting the agent: Exceeded maximum number of retries, the API keeps returning errors.",
+        );
+      }
+      const response =
+        await getExtractionAgentByNameApiV1ExtractionExtractionAgentsByNameNameGet(
+          options,
+        );
+      if (!response.response.ok) {
+        if ("error" in response) {
+          console.log(
+            `An error occurred while getting the extraction agent by name.\nDetails:\n\n${JSON.stringify(
+              response.error,
+            )}\n\nRetrying...`,
+          );
+        }
+        retries++;
+        await sleep(retryInterval * 1000);
+      } else {
+        return response.data as ExtractAgent;
+      }
+    }
+  } else {
+    const data = {
+      path: { extraction_agent_id: id },
+    } as GetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGetData;
+    const options =
+      data as Options<GetExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGetData>;
+    if (typeof client != "undefined") {
+      options.client = client;
+    }
+    let retries: number = 0;
+    while (true) {
+      if (retries > maxRetriesOnError) {
+        throw new Error(
+          "Error while getting the agent: Exceeded maximum number of retries, the API keeps returning errors.",
+        );
+      }
+      const response =
+        await getExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdGet(
+          options,
+        );
+      if (!response.response.ok) {
+        if (!response.response.ok) {
+          if ("error" in response) {
+            console.log(
+              `An error occurred while getting the extraction agent by ID.\nDetails:\n\n${JSON.stringify(
+                response.error,
+              )}\n\nRetrying...`,
+            );
+          }
+          retries++;
+          await sleep(retryInterval * 1000);
+        }
+      } else {
+        return response.data as ExtractAgent;
+      }
+    }
+  }
+}
+
+function textToFile(text: string, fileName: string | null = null) {
+  return new File(
+    [text],
+    fileName ?? "uploadedFile_" + randomUUID().replaceAll("-", "_") + ".txt",
+  );
+}
+
+async function uploadFile(
+  filePath: string | undefined = undefined,
+  fileContent:
+    | Buffer<ArrayBufferLike>
+    | File
+    | Uint8Array<ArrayBuffer>
+    | string
+    | undefined = undefined,
+  fileName: string | undefined = undefined,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  client: Client | undefined = undefined,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<string | undefined> {
+  let file: File | undefined = undefined;
+  if (typeof filePath === "undefined" && typeof fileContent === "undefined") {
+    throw new Error(
+      "One between filePath and fileContent needs to be provided",
+    );
+  } else if (typeof filePath != "undefined") {
+    const buffer = await fs.readFile(filePath);
+    const actualFileName = fileName ?? path.basename(filePath);
+    const uint8Array = new Uint8Array(buffer);
+    file = new File([uint8Array], actualFileName);
+  } else if (typeof fileContent != "undefined") {
+    if (fileContent instanceof File) {
+      file = fileContent;
+    } else if (fileContent instanceof Buffer) {
+      const fileType = await fileTypeFromBuffer(fileContent);
+      const ext = fileType?.ext ?? "pdf";
+      const uint8Array = new Uint8Array(fileContent);
+      file = new File(
+        [uint8Array],
+        fileName ??
+          "uploadedFile_" + randomUUID().replaceAll("-", "_") + "." + ext,
+      );
+    } else if (fileContent instanceof Uint8Array) {
+      const fileType = await fileTypeFromBuffer(fileContent);
+      const ext = fileType?.ext ?? "pdf";
+      file = new File(
+        [fileContent],
+        fileName ??
+          "uploadedFile_" + randomUUID().replaceAll("-", "_") + "." + ext,
+      );
+    } else if (typeof fileContent === "string") {
+      file = textToFile(fileContent, fileName);
+    } else {
+      throw new Error("Unsupported fileContent type");
+    }
+  }
+  const fileToUpload = {
+    upload_file: file,
+  } as BodyUploadFileApiV1FilesPost;
+  const uploadData = {
+    body: fileToUpload,
+    query: { organization_id: organization_id, project_id: project_id },
+  } as UploadFileApiV1FilesPostData;
+  const uploadOptions = uploadData as Options<UploadFileApiV1FilesPostData>;
+  if (typeof client != "undefined") {
+    uploadOptions.client = client;
+  }
+  let retries: number = 0;
+  while (true) {
+    if (retries > maxRetriesOnError) {
+      throw new Error(
+        "Error while processing your file: Exceeded maximum number of retries, the API keeps returning errors.",
+      );
+    }
+    const uploadResponse = await uploadFileApiV1FilesPost(uploadOptions);
+    let fileId: string | undefined = undefined;
+    if (!uploadResponse.response.ok) {
+      retries++;
+      await sleep(retryInterval * 1000);
+    }
+    if (typeof uploadResponse.data != "undefined") {
+      fileId = uploadResponse.data.id as string;
+      return fileId;
+    }
+  }
+}
+
+async function createExtractJob(
+  options:
+    | Options<RunJobApiV1ExtractionJobsPostData>
+    | Options<ExtractStatelessApiV1ExtractionRunPostData>,
+  stateless: boolean = false,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<string | undefined> {
+  let retries: number = 0;
+  while (true) {
+    if (retries > maxRetriesOnError) {
+      throw new Error(
+        "Error while creating the extraction job: Exceeded maximum number of retries, the API keeps returning errors.",
+      );
+    }
+    let response:
+      | {
+          data: ExtractJob | undefined;
+          request: Request;
+          response: Response;
+        }
+      | undefined = undefined;
+    if (!stateless) {
+      response = (await runJobApiV1ExtractionJobsPost(
+        options as Options<RunJobApiV1ExtractionJobsPostData>,
+      )) as {
+        data: ExtractJob | undefined;
+        request: Request;
+        response: Response;
+      };
+    } else {
+      response = (await extractStatelessApiV1ExtractionRunPost(
+        options as Options<ExtractStatelessApiV1ExtractionRunPostData>,
+      )) as {
+        data: ExtractJob | undefined;
+        request: Request;
+        response: Response;
+      };
+    }
+    if (!response.response.ok) {
+      if ("error" in response) {
+        console.log(
+          "An error occurred: ",
+          JSON.stringify(response.error),
+          "\nRetrying...",
+        );
+      }
+      retries++;
+      await sleep(retryInterval * 1000);
+    }
+    if (typeof response.data != "undefined") {
+      const jobStatus = response.data.status as StatusEnum;
+      if (jobStatus == "CANCELLED") {
+        retries++;
+        await sleep(retryInterval * 1000);
+      } else if (jobStatus == "ERROR") {
+        retries++;
+        await sleep(retryInterval * 1000);
+      } else {
+        return response.data.id as string;
+      }
+    }
+  }
+}
+
+async function pollForJobCompletion(
+  jobId: string,
+  interval: number = 1,
+  maxIterations: number = 1800,
+  client: Client | undefined = undefined,
+): Promise<boolean> {
+  let status: StatusEnum | undefined = undefined;
+  const jobData = {
+    path: { job_id: jobId },
+  } as GetJobApiV1ExtractionJobsJobIdGetData;
+  const jobOptions = jobData as Options<GetJobApiV1ExtractionJobsJobIdGetData>;
+  if (typeof client != "undefined") {
+    jobOptions.client = client;
+  }
+  let numIterations: number = 0;
+  while (true) {
+    if (numIterations > maxIterations) {
+      return false;
+    }
+    const response = await getJobApiV1ExtractionJobsJobIdGet(jobOptions);
+    if (!response.response.ok) {
+      numIterations++;
+    }
+    if (typeof response.data != "undefined") {
+      status = response.data.status as StatusEnum;
+      if (status == StatusEnum.CANCELLED || status == StatusEnum.ERROR) {
+        throw new Error("There was an error extracting data from your file.");
+      } else if (status == StatusEnum.SUCCESS) {
+        return true;
+      } else {
+        numIterations++;
+        await sleep(interval * 1000);
+      }
+    }
+  }
+}
+
+async function getJobResult(
+  jobId: string,
+  client: Client | undefined = undefined,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<ExtractResult | undefined> {
+  const jobData = {
+    path: { job_id: jobId },
+    query: { organization_id: organization_id, project_id: project_id },
+  } as GetJobResultApiV1ExtractionJobsJobIdResultGetData;
+  const jobOptions =
+    jobData as Options<GetJobResultApiV1ExtractionJobsJobIdResultGetData>;
+  if (typeof client != "undefined") {
+    jobOptions.client = client;
+  }
+  let retries: number = 0;
+  while (true) {
+    if (retries > maxRetriesOnError) {
+      throw new Error(
+        "Error while getting the result of the extraction job: Exceeded maximum number of retries, the API keeps returning errors.",
+      );
+    }
+    const response =
+      await getJobResultApiV1ExtractionJobsJobIdResultGet(jobOptions);
+    if (!response.response.ok) {
+      if ("error" in response) {
+        console.log(
+          "An error occurred: ",
+          JSON.stringify(response.error),
+          "\nRetrying...",
+        );
+      }
+      retries++;
+      await sleep(retryInterval * 1000);
+    }
+    if (typeof response.data != "undefined") {
+      return {
+        data: response.data.data,
+        extractionMetadata: response.data.extraction_metadata,
+      } as ExtractResult;
+    }
+  }
+}
+
+export async function extract(
+  agentId: string,
+  filePath: string | undefined = undefined,
+  fileContent:
+    | Buffer<ArrayBufferLike>
+    | File
+    | Uint8Array<ArrayBuffer>
+    | string
+    | undefined = undefined,
+  fileName: string | undefined = undefined,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  client: Client | undefined = undefined,
+  fromUi: boolean | undefined = undefined,
+  pollingInterval: number = 1,
+  maxPollingIterations: number = 1800,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<ExtractResult | undefined> {
+  const fileId = (await uploadFile(
+    filePath,
+    fileContent,
+    fileName,
+    project_id,
+    organization_id,
+    client,
+    maxRetriesOnError,
+    retryInterval,
+  )) as string;
+  const extractJobCreate = {
+    extraction_agent_id: agentId,
+    file_id: fileId,
+  } as ExtractJobCreate;
+  const extractData = {
+    body: extractJobCreate,
+    query: { from_ui: fromUi },
+  } as RunJobApiV1ExtractionJobsPostData;
+  const extractOptions =
+    extractData as Options<RunJobApiV1ExtractionJobsPostData>;
+  if (typeof client != "undefined") {
+    extractOptions.client = client;
+  }
+  const jobId = (await createExtractJob(
+    extractOptions,
+    false,
+    maxRetriesOnError,
+    retryInterval,
+  )) as string;
+  const success = await pollForJobCompletion(
+    jobId,
+    pollingInterval,
+    maxPollingIterations,
+    client,
+  );
+  if (!success) {
+    throw new Error("Your job is taking longer than 10 minutes, timing out...");
+  } else {
+    return (await getJobResult(
+      jobId,
+      client,
+      project_id,
+      organization_id,
+      maxRetriesOnError,
+      retryInterval,
+    )) as ExtractResult;
+  }
+}
+
+export async function extractStateless(
+  dataSchema:
+    | {
+        [key: string]:
+          | { [key: string]: unknown }
+          | Array<unknown>
+          | string
+          | number
+          | number
+          | boolean
+          | null;
+      }
+    | string,
+  config: ExtractConfig = {} as ExtractConfig,
+  filePath: string | undefined = undefined,
+  fileContent:
+    | Buffer<ArrayBufferLike>
+    | File
+    | Uint8Array<ArrayBuffer>
+    | string
+    | undefined = undefined,
+  fileName: string | undefined = undefined,
+  project_id: string | null = null,
+  organization_id: string | null = null,
+  client: Client | undefined = undefined,
+  pollingInterval: number = 1,
+  maxPollingIterations: number = 1800,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<ExtractResult | undefined> {
+  const fileId = (await uploadFile(
+    filePath,
+    fileContent,
+    fileName,
+    project_id,
+    organization_id,
+    client,
+    maxRetriesOnError,
+    retryInterval,
+  )) as string;
+  const extractStatetelessCreate = {
+    data_schema: dataSchema,
+    file_id: fileId,
+    config: config,
+  } as StatelessExtractionRequest;
+  const extractStatetelessData = {
+    body: extractStatetelessCreate,
+  } as ExtractStatelessApiV1ExtractionRunPostData;
+  const extractOptions =
+    extractStatetelessData as Options<ExtractStatelessApiV1ExtractionRunPostData>;
+  if (typeof client != "undefined") {
+    extractOptions.client = client;
+  }
+  const jobId = (await createExtractJob(
+    extractOptions,
+    true,
+    maxRetriesOnError,
+    retryInterval,
+  )) as string;
+  const success = await pollForJobCompletion(
+    jobId,
+    pollingInterval,
+    maxPollingIterations,
+    client,
+  );
+  if (!success) {
+    throw new Error("Your job is taking longer than 10 minutes, timing out...");
+  } else {
+    return (await getJobResult(
+      jobId,
+      client,
+      project_id,
+      organization_id,
+      maxRetriesOnError,
+      retryInterval,
+    )) as ExtractResult;
+  }
+}
+
+export async function deleteAgent(
+  id: string,
+  client: Client | undefined = undefined,
+  maxRetriesOnError: number = 10,
+  retryInterval: number = 0.5,
+): Promise<boolean | undefined> {
+  const deleteData = {
+    path: { extraction_agent_id: id },
+  } as DeleteExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdDeleteData;
+  const deleteOptions =
+    deleteData as Options<DeleteExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdDeleteData>;
+  if (typeof client != "undefined") {
+    deleteOptions.client = client;
+  }
+  let retries: number = 0;
+  while (true) {
+    if (retries > maxRetriesOnError) {
+      throw new Error(
+        "Maximum number of attempts for deleting agent " +
+          id +
+          " reached, but the API continues to return errors.",
+      );
+    }
+    const response =
+      await deleteExtractionAgentApiV1ExtractionExtractionAgentsExtractionAgentIdDelete(
+        deleteOptions,
+      );
+    if (!response.response.ok) {
+      if ("error" in response) {
+        console.log(
+          `An error occurred while deleting the agent: ${JSON.stringify(
+            response.error,
+          )}\nRetrying...`,
+        );
+      }
+      retries++;
+      await sleep(retryInterval * 1000);
+    } else {
+      return true;
+    }
+  }
+}
+
+export { type ExtractAgent, type ExtractConfig };

ts/llama_cloud_services/src/index.ts

@@ -6,3 +6,5 @@ export {
 } from "./LlamaCloudRetriever.js";
 export type { CloudConstructorParams } from "./type.js";
 export { LlamaParseReader } from "./reader.js";
+export { LlamaExtract, LlamaExtractAgent } from "./LlamaExtract.js";
+export type { ExtractConfig } from "./extract.js";

ts/llama_cloud_services/src/reader.ts

@@ -14,7 +14,8 @@ import {
   getJobTextResultApiV1ParsingJobJobIdResultTextGet,
   uploadFileApiV1ParsingUploadPost,
 } from "./api";
-import { sleep } from "./utils";
+import { sleep, getSavePath } from "./utils";
+import type { ParseResult } from "./type";
 
 export type Language = ParserLanguages;
 export type ResultType = "text" | "markdown" | "json";
@@ -594,15 +595,15 @@ export class LlamaParseReader extends FileReader {
   }
 
   /**
-   * Loads data from a file and returns an array of JSON objects.
+   * Loads data from a file and returns an array of  ParseResult objects.
    * To be used with resultType "json".
    *
    * @param filePathOrContent - The file path or the file content as a Uint8Array.
-   * @returns A Promise that resolves to an array of JSON objects.
+   * @returns A Promise that resolves to an array of ParseResult objects, encapsulating the JSON array resulting from the parsing within the pages attribute.
    */
   async loadJson(
     filePathOrContent: string | Uint8Array,
-  ): Promise<Record<string, any>[]> {
+  ): Promise<ParseResult[]> {
     let jobId;
     const isFilePath =
       typeof filePathOrContent === "string" &&
@@ -628,7 +629,7 @@ export class LlamaParseReader extends FileReader {
       const resultJson = await this.getJobResult(jobId, "json");
       resultJson.job_id = jobId;
       resultJson.file_path = isFilePath ? filePathOrContent : undefined;
-      return [resultJson];
+      return [resultJson] as ParseResult[];
     } catch (e) {
       console.error(`Error while parsing the file under job id ${jobId}`, e);
       if (this.ignoreErrors) {
@@ -639,6 +640,80 @@ export class LlamaParseReader extends FileReader {
     }
   }
 
+  /**
+   * Loads data from a file or file bytes (or an array of those) and returns an array of ParseResult objects.
+   *
+   * @param filePathOrContent - The file path or the file content as a Uint8Array, or an array of one of those two types.
+   * @returns A Promise that resolves to an array of ParseResult objects, encapsulating the JSON array resulting from the parsing within the pages attribute.
+   */
+  async parse(
+    filePathOrContent: string | Uint8Array | string[] | Uint8Array[],
+  ): Promise<ParseResult[]> {
+    const jsonResults: Record<string, any>[][] = [];
+    if (!Array.isArray(filePathOrContent)) {
+      const jsonResult = await this.loadJson(filePathOrContent);
+      jsonResults.push(jsonResult);
+    } else {
+      for (let i = 0; i < filePathOrContent.length; i++) {
+        console.log(
+          `Processing file ${i + 1} of ${filePathOrContent.length}...`,
+        );
+        const jsonResult = await this.loadJson(
+          filePathOrContent[i] as string | Uint8Array,
+        );
+        jsonResults.push(jsonResult);
+      }
+    }
+    const parseResults: ParseResult[] = [];
+    for (const jsonResult of jsonResults) {
+      for (const result of jsonResult) {
+        const parseResult = {
+          pages: result.pages,
+          job_metadata: result.job_metadata,
+          job_id: result.job_id,
+          file_path: result?.file_path ?? "",
+          is_completed: true,
+        } as ParseResult;
+        parseResults.push(parseResult);
+      }
+    }
+    return parseResults;
+  }
+
+  /**
+   * Downloads and saves tables from a given array of ParseResult to a specified download path.
+   *
+   * @param jsonResults - The array of ParseResult containing table information.
+   * @param downloadPath - The path where the downloaded tables will be saved as CSV files.
+   * @returns A Promise that resolves to an array of strings representing the paths to the tables.
+   */
+  async getTables(
+    jsonResults: ParseResult[],
+    downloadPath: string,
+  ): Promise<string[]> {
+    const tables: string[] = [];
+    for (const result of jsonResults) {
+      for (const page of result.pages) {
+        if ("items" in page && Array.isArray(page.items)) {
+          for (let i = 0; i < page.items.length; i++) {
+            if (
+              "type" in page.items[i] &&
+              page.items[i].type === "table" &&
+              "csv" in page.items[i] &&
+              typeof page.items[i].csv === "string" &&
+              page.items[i].csv != ""
+            ) {
+              const savePath = getSavePath(downloadPath, i);
+              await fs.writeFile(savePath, page.items[i].csv);
+              tables.push(savePath);
+            }
+          }
+        }
+      }
+    }
+    return tables;
+  }
+
   /**
    * Downloads and saves images from a given JSON result to a specified download path.
    * Currently only supports resultType "json".
@@ -648,7 +723,7 @@ export class LlamaParseReader extends FileReader {
    * @returns A Promise that resolves to an array of image objects.
    */
   async getImages(
-    jsonResult: Record<string, any>[],
+    jsonResult: ParseResult[],
     downloadPath: string,
   ): Promise<Record<string, any>[]> {
     try {

ts/llama_cloud_services/src/type.ts

@@ -8,3 +8,54 @@ export type CloudConstructorParams = {
   projectName: string;
   organizationId?: string | undefined;
 } & ClientParams;
+
+export type ExtractResult = {
+  data:
+    | {
+        [key: string]:
+          | {
+              [key: string]: unknown;
+            }
+          | Array<unknown>
+          | string
+          | number
+          | number
+          | boolean
+          | null;
+      }
+    | Array<{
+        [key: string]:
+          | {
+              [key: string]: unknown;
+            }
+          | Array<unknown>
+          | string
+          | number
+          | number
+          | boolean
+          | null;
+      }>
+    | null;
+  extractionMetadata: {
+    [key: string]:
+      | {
+          [key: string]: unknown;
+        }
+      | Array<unknown>
+      | string
+      | number
+      | number
+      | boolean
+      | null;
+  };
+};
+
+export type ParseResult = {
+  // eslint-disable-next-line  @typescript-eslint/no-explicit-any
+  pages: Record<string, any>[];
+  // eslint-disable-next-line  @typescript-eslint/no-explicit-any
+  job_metadata: Record<string, any>;
+  job_id: string;
+  is_completed: boolean;
+  file_path: string;
+};

ts/llama_cloud_services/src/utils.ts

@@ -6,6 +6,8 @@ import {
 import { DEFAULT_BASE_URL } from "@llamaindex/core/global";
 import { getEnv } from "@llamaindex/env";
 import type { ClientParams } from "./type.js";
+import fs from "fs";
+import path from "path";
 
 function getBaseUrl(baseUrl?: string): string {
   return baseUrl ?? getEnv("LLAMA_CLOUD_BASE_URL") ?? DEFAULT_BASE_URL;
@@ -99,3 +101,19 @@ export async function getPipelineId(
 export async function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+export function getSavePath(downloadPath: string, i: number): string {
+  const now = new Date();
+  const formatted =
+    now.toISOString().replace(/[-:T]/g, "_").replace(/\..+/, "") +
+    "_" +
+    now.getMilliseconds().toString().padStart(3, "0");
+
+  let savePath = path.join(downloadPath, `table_${formatted}.csv`);
+
+  if (fs.existsSync(savePath)) {
+    savePath = savePath.replace(".csv", "_") + i.toString() + ".csv";
+  }
+
+  return savePath;
+}

ts/llama_cloud_services/tests/integration.test.ts

@@ -1,8 +1,11 @@
 import { describe, it, expect, beforeEach, beforeAll } from "vitest";
 import { LlamaParseReader } from "../src/reader.js";
 import { LlamaCloudIndex } from "../src/LlamaCloudIndex.js";
+import { LlamaExtract, LlamaExtractAgent } from "../src/LlamaExtract.js";
 import { Document } from "@llamaindex/core/schema";
 import { fs } from "@llamaindex/env";
+import { ExtractConfig } from "../src/api.js";
+import { ParseResult } from "../src/type.js";
 
 // Integration tests that require actual API keys and files
 describe("Integration Tests", () => {
@@ -282,6 +285,78 @@ describe("Integration Tests", () => {
       },
       60000,
     );
+
+    it.skipIf(skipIfNoApiKey)(
+      "should parse a file and return a ParseResult array",
+      async () => {
+        const parseReader = new LlamaParseReader({
+          apiKey: process.env.LLAMA_CLOUD_API_KEY!,
+          verbose: false,
+        });
+
+        const testContent = "Test document for JSON parsing";
+        const testFilePath = "test-json.txt";
+
+        await fs.writeFile(testFilePath, new TextEncoder().encode(testContent));
+
+        try {
+          const result = await parseReader.parse(testFilePath);
+
+          expect(result).toBeDefined();
+          expect(Array.isArray(result)).toBe(true);
+          expect(result.length).toBeGreaterThan(0);
+          expect(result[0]).toHaveProperty("job_id");
+          expect(result[0]).toHaveProperty("job_metadata");
+          expect(result[0]).toHaveProperty("file_path");
+          expect(result[0]).toHaveProperty("pages");
+
+          await fs.unlink(testFilePath);
+        } catch (error) {
+          try {
+            await fs.unlink(testFilePath);
+          } catch {}
+          throw error;
+        }
+      },
+      60000,
+    );
+
+    it.skipIf(skipIfNoApiKey)(
+      "should extract tables correctly from a JSON result",
+      async () => {
+        const parseReader = new LlamaParseReader({
+          apiKey: process.env.LLAMA_CLOUD_API_KEY!,
+          verbose: false,
+        });
+        const pseudoJsonResult = [
+          {
+            pages: [
+              {
+                items: [
+                  {
+                    type: "table",
+                    csv: "Name,Age,Height (cm)\nAnna,12,140\nBob,22,175\nClaire,33,173\nDenis,44,185\n",
+                  },
+                ],
+              },
+            ],
+            job_id: "jobId",
+            job_metadata: { job_id: "jobId" },
+            file_path: "table.csv",
+            is_completed: true,
+          },
+        ] as ParseResult[];
+
+        const tmpdir = await fs.mkdtemp("tables");
+        const result = await parseReader.getTables(pseudoJsonResult, tmpdir);
+
+        expect(result).toBeDefined();
+        expect(Array.isArray(result)).toBe(true);
+        expect(result.length).toBeGreaterThan(0);
+        expect(typeof result[0] === "string").toBe(true);
+      },
+      60000,
+    );
   });
 
   describe("LlamaCloudIndex Integration", () => {
@@ -414,6 +489,121 @@ describe("Integration Tests", () => {
     );
   });
 
+  describe("LlamaExtract Integration", () => {
+    it.skipIf(skipIfNoApiKey)(
+      "should create agents correctly",
+      async () => {
+        const dataSchema = {
+          properties: {
+            text: {
+              description: "Text from the file",
+              type: "string",
+            },
+          },
+          required: ["text"],
+          type: "object",
+        };
+        const extractClient = new LlamaExtract(
+          process.env.LLAMA_CLOUD_API_KEY!,
+          "https://api.cloud.llamaindex.ai",
+        );
+        const agent = await extractClient.createAgent(
+          "ExtractTestAgent",
+          dataSchema,
+        );
+        expect(agent).instanceOf(LlamaExtractAgent);
+      },
+      60000,
+    );
+    it.skipIf(skipIfNoApiKey)(
+      "should fetch agents correctly",
+      async () => {
+        const extractClient = new LlamaExtract(
+          process.env.LLAMA_CLOUD_API_KEY!,
+          "https://api.cloud.llamaindex.ai",
+        );
+        const agent = await extractClient.getAgent("ExtractTestAgent");
+        expect(agent).instanceOf(LlamaExtractAgent);
+      },
+      60000,
+    );
+    it.skipIf(skipIfNoApiKey)(
+      "should extract data correctly (file paths and file contents) with an agent and delete that agent",
+      async () => {
+        const extractClient = new LlamaExtract(
+          process.env.LLAMA_CLOUD_API_KEY!,
+          "https://api.cloud.llamaindex.ai",
+        );
+        const agent = await extractClient.getAgent("ExtractTestAgent");
+        const testContent =
+          "**Text to extract**: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.";
+        const testFilePath = "test-extract-agent.md";
+
+        await fs.writeFile(testFilePath, new TextEncoder().encode(testContent));
+        const result = await agent!.extract("test-extract-agent.md");
+        expect("data" in result!).toBeTruthy();
+        expect("extractionMetadata" in result!).toBeTruthy();
+
+        const buffer = await fs.readFile("test-extract-agent.md");
+        const resultBuffer = await agent!.extract(
+          undefined,
+          buffer,
+          "test-extract-agent.md",
+        );
+        expect("data" in resultBuffer!).toBeTruthy();
+        expect("extractionMetadata" in resultBuffer!).toBeTruthy();
+
+        const success = await extractClient.deleteAgent(agent!.id);
+        expect(success).toBeTruthy();
+      },
+      60000,
+    );
+    it.skipIf(skipIfNoApiKey)(
+      "should extract statelessly file paths and file contents",
+      async () => {
+        const dataSchema = {
+          properties: {
+            text: {
+              description: "Text from the file",
+              type: "string",
+            },
+          },
+          required: ["text"],
+          type: "object",
+        };
+
+        const testContent =
+          "**Text to extract**: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.";
+        const testFilePath = "test-extract.md";
+
+        await fs.writeFile(testFilePath, new TextEncoder().encode(testContent));
+
+        const extractClient = new LlamaExtract(
+          process.env.LLAMA_CLOUD_API_KEY!,
+          "https://api.cloud.llamaindex.ai",
+        );
+        const result = await extractClient.extract(
+          dataSchema,
+          {} as ExtractConfig,
+          "test-extract.md",
+        );
+        expect("data" in result!).toBeTruthy();
+        expect("extractionMetadata" in result!).toBeTruthy();
+
+        const buffer = await fs.readFile("test-extract.md");
+        const resultBuffer = await extractClient.extract(
+          dataSchema,
+          {} as ExtractConfig,
+          undefined,
+          buffer,
+        ); // testing without passing a file name
+        expect("data" in resultBuffer!).toBeTruthy();
+        expect("extractionMetadata" in resultBuffer!).toBeTruthy();
+      },
+      60000,
+    );
+  });
+
   describe("Error Handling Integration", () => {
     it.skipIf(skipIfNoApiKey)(
       "should handle malformed files gracefully",