Re-order extraction metadata union for better parsing (#865)

* Re-order args so that pydantic doesn't parse nested dict to a empty extraction result

* Use a citations array instead

.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "restricted",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

.github/workflows/release.yml

@@ -1,52 +0,0 @@
-name: Publish - Changeset
-
-on:
-  push:
-    branches: [main]
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  publish:
-    name: Publish
-    runs-on: ubuntu-latest
-    # Only run if this is a merge commit and the PR was authored by github-actions[bot]
-    if: ${{ github.event.head_commit.message != null && startsWith(github.event.head_commit.message, 'Merge pull request') && contains(github.event.head_commit.message, '/changeset-release/main') }}
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 10
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: "ts/llama_cloud_services/.nvmrc"
-
-      - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
-
-      - name: Add auth token to .npmrc file
-        run: |
-          cat << EOF >> ".npmrc"
-            //registry.npmjs.org/:_authToken=$NPM_TOKEN
-          EOF
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish packages based on changesets
-        run: |
-          pnpm run release
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          PYPI_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}

.github/workflows/version_bump.yml

@@ -1,47 +0,0 @@
-name: Version Bump - Changeset
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  version:
-    name: Version Bump
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@v4
-        with:
-          # Need to fetch full history for changesets
-          fetch-depth: 0
-
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 10
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: "ts/cute_cats_terminal/.nvmrc"
-
-      - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
-
-      - name: Create Release Pull Request
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          version: pnpm run version
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -1,166 +1,33 @@
-# Contribute to `llama-cloud-services`
+# Python
 
-## Common Patterns
+## Installation
 
-### Issues
+This project uses uv. Create a virtual environment, and run `uv sync`
 
-One of the forms of contribution can be issues.
+## Versioning (Maintainers only)
 
-Issues should be used when there are bugs or feature request you would like to bring to the attention of the maintainers.
+Before merging your changes, make sure to bump the versions.
 
-When opening an issue:
+Make a version bump to `pyproject.toml`. If the underlying dependency on the llamacloud platform OpenAPI
+sdk needs bumping, make sure to bring that in as well. If updating dependencies, run `uv lock`.
 
-- preferably, use the provided templates
-- check for other issues (closed and open) to avoid duplicates
-- try to be detailed and specific, reporting all the pieces the maintainer would need to have in order to reproduce your issue.
+The legacy `llama_parse` package re-exports some of `llama_cloud_services` in the old namespace. The
+versions need to be kept consistent to sidecar it with `llama_cloud_services`. Bump it's version in `llama_parse/pyproject.toml`, and also bump it's dependency version of `llama-cloud-services` to match.
 
-### Pull requests
+**Note**: Don't worry about updating the `llama_parse/poetry.lock` file when bumping versions. The GitHub action will automatically run `poetry lock` for the llama_parse package during the build process (though it doesn't commit the updated lockfile back to the repo).
 
-In order to open a valid pull request:
+You can also do this with `./scripts/version-bump.py set 0.x.x` if you have `uv` installed.
 
-- Fork the repository
-- Checkout a secondary branch (common prefixes for secondary branches include: `fix`, `feat`, `chore`, `docs`). We tend to prefer the naming convention that uses `/`, such as: `fix/your-awesome-bug-fix`.
-- Add and commit the changes to the secondary branch, following language-specific logic (see below)
-- When the changes are pushed to your branch, open a pull request
+Once the change is merged, push a tag `git tag -a v0.x.x -m 0.x.x` and `git push origin 0.x.x`.
 
-## Python
+This tagging step can be done with `./scripts/version-bump tag`.
 
-### Set Up
+# Typescript
 
-The two python packages, which can be found under `py/`, are:
+## Installation
 
-- `llama-cloud-services`
-- `llama-parse`
+...
 
-> [!NOTE]
->
-> `llama-parse` mostly re-exports from `llama-cloud-services`, so you should not modify that directly.
+## Versioning
 
-These packages are managed through [uv](https://docs.astral.sh/uv/), so make sure to have uv [installed](https://docs.astral.sh/uv/getting-started/installation/).
-
-### Tests
-
-It is important to make sure all tests pass after your changes, and cover new features with suitable unit tests.
-
-Tests are found in `py/tests/` (end to end) and `py/unit_tests/` (unit tests, no API key required) and you can execute them with:
-
-```bash
-pytest tests/ unit_tests/
-```
-
-### Pre-Commit Versioning
-
-Once you made your changes and tested them, **prior to committing** you should run (from the root folder) this command to automatically bump the version of python packages:
-
-```bash
-pnpm pre-commit-version
-```
-
-this will prompt you to choose what package's version you want to bump and what kind of bump you want to perform. Choose `@llama_cloud_services/py` for python and choose the version bump according to the type of changing you made.
-
-### Pre-commit checks
-
-Before you commit, your files should pass the linting and formatting requirements. In order to do that, you should have `pre-commit` installed and set-up in your repository:
-
-```bash
-pip install pre-commit
-pre-commit install
-```
-
-Once you have that set up, the files will be automatically linted and formatted according to the requirements.
-
-## TypeScript
-
-### Set Up
-
-The TypeScript package, which can be found under `ts/llama_cloud_services/`, is managed through [`pnpm`](https://pnpm.io), so make sure to have it [installed](https://pnpm.io/installation).
-
-In order to be able to run and test the package, make sure to install all the dependencies:
-
-```bash
-pnpm install
-```
-
-### Activate Test Mode
-
-In order to activate test mode (to dynamically test your changes while you are performing them) you can use:
-
-```bash
-pnpm turbo run dev
-```
-
-### Test
-
-It is important to make sure all tests pass after your changes, and cover new features with suitable unit tests.
-
-Tests are found in `ts/llama_cloud_services/tests/` and you can execute them with:
-
-```bash
-pnpm test
-```
-
-### Pre-Commit Versioning
-
-Once you made your changes and tested them, **prior to committing** you should run (from the root folder) two commands to automatically bump the version of python packages:
-
-```bash
-pnpm pre-commit-version
-```
-
-This will prompt you to choose what package's version you want to bump and what kind of bump you want to perform. Choose `llama-cloud-services` for TypeScript and choose the version bump according to the type of changing you made.
-
-### Pre-commit checks
-
-Before you commit, your files should pass the linting and formatting requirements. In order to do that, run (from the root folder):
-
-```bash
-pnpm pre-commit
-```
-
-The files will be then automatically linted and formatted according to the requirements.
-
-## TypeScript _and_ Python
-
-If you change **both PY and TS**, for versioning run:
-
-```bash
-pnpm pre-commit-version # choose both packages
-```
-
-## Release (maintainers only)
-
-Every push to main might trigger a release.
-
-Whether a release is pushed out or not depends on the presence of versioning files in `.changesets`: if you want a release to be packaged, then, you need to always run `pnpm pre-commit-version` prior to merging a pull request into main. See [version_bump_and_release](./.github/workflows/version_bump_and_release.yml) action to better understand the process.
-
-You can, nevertheless, manually set up language-specific releases, using the logic reported below.
-
-### Python
-
-To release `llama-cloud-services` and `llama-parse` in Python, run:
-
-```bash
-git checkout main
-git pull
-git tag <your-version> # e.g. v0.7.0
-git push <your-version>
-```
-
-> [!NOTE]
->
-> The tag must start with `v`
-
-This will trigger the release workflow automatically.
-
-### TypeScript
-
-To release `llama-cloud-services` in TypeScript, run:
-
-```bash
-git checkout main
-git pull
-git tag llama-cloud-services@<your-version> # e.g. llama-cloud-services@0.3.0
-git push origin llama-cloud-services@<your-version>
-```
-
-This will trigger the release workflow automatically.
+...

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/logger.ts

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

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"
   }
 }

extract.md

@@ -2,6 +2,29 @@
 
 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:
@@ -12,7 +35,7 @@ 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
@@ -64,7 +87,9 @@ result = extractor.extract(Resume, config, SourceText(text_content=text))
 
 ### Async Extraction
 
-For better performance with multiple files or when integrating with async applications:
+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
@@ -80,10 +105,18 @@ async def extract_resumes():
         Resume, config, ["resume1.pdf", "resume2.pdf"]
     )
     print(f"Queued {len(jobs)} extraction jobs")
+    return jobs
 
 
 # Run async function
-asyncio.run(extract_resumes())
+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
@@ -159,24 +192,6 @@ config = ExtractConfig(extraction_mode=ExtractMode.FAST)
 result = extractor.extract(schema, config, "resume.pdf")
 ```
 
-## Extraction Configuration
-
-Configure how extraction is performed using `ExtractConfig`:
-
-```python
-from llama_cloud import ExtractConfig, ExtractMode
-
-# Fast extraction (lower accuracy, faster processing)
-fast_config = ExtractConfig(extraction_mode=ExtractMode.FAST)
-
-# Balanced extraction (good balance of speed and accuracy)
-balanced_config = ExtractConfig(extraction_mode=ExtractMode.BALANCED)
-
-# Use different configs for different needs
-result = extractor.extract(schema, fast_config, "simple_document.pdf")
-result = extractor.extract(schema, balanced_config, "complex_document.pdf")
-```
-
 ### Important restrictions on JSON/Pydantic Schema
 
 _LlamaExtract only supports a subset of the JSON Schema specification._ While limited, it should
@@ -194,6 +209,62 @@ 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.
 
+## Extraction Configuration
+
+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
+from llama_cloud import ExtractConfig, ExtractMode, ChunkMode, ExtractTarget
+
+# 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
+)
+```
+
+### Key Configuration Options
+
+**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:
@@ -326,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

package.json

@@ -1,19 +0,0 @@
-{
-  "name": "llama_cloud_services",
-  "version": "1.0.0",
-  "private": "true",
-  "license": "MIT",
-  "scripts": {
-    "pre-commit-version": "pnpm changeset",
-    "version": "pnpm version-ts && pnpm version-py",
-    "release": "pnpm release-ts && pnpm release-py",
-    "release-ts": "pnpm run --filter llama-cloud-services release",
-    "release-py": "pnpm run --filter @llama_cloud_services/py release",
-    "version-ts": "pnpm run --filter llama-cloud-services version",
-    "version-py": "pnpm run --filter @llama_cloud_services/py version"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "changesets": "^1.0.2"
-  }
-}

pnpm-workspace.yaml

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

py/llama_cloud_services/beta/agent_data/schema.py

@@ -37,11 +37,10 @@ Example Usage:
 """
 
 from datetime import datetime
-import numbers
 from llama_cloud import ExtractRun
 from llama_cloud.types.agent_data import AgentData
 from llama_cloud.types.aggregate_group import AggregateGroup
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, Field, ValidationError, model_validator, ConfigDict
 from typing import (
     Generic,
     List,
@@ -176,6 +175,16 @@ class TypedAgentDataItems(BaseModel, Generic[AgentDataT]):
     )
 
 
+class FieldCitation(BaseModel):
+    page: Optional[int] = Field(
+        None, description="The page number that the field occurred on"
+    )
+    matching_text: Optional[str] = Field(
+        None,
+        description="The original text this field's value was derived from",
+    )
+
+
 class ExtractedFieldMetadata(BaseModel):
     """
     Metadata for an extracted data field, such as confidence, and citation information.
@@ -193,14 +202,14 @@ class ExtractedFieldMetadata(BaseModel):
         None,
         description="The confidence score for the field based on the extracted text only",
     )
-    page_number: Optional[int] = Field(
-        None, description="The page number that the field occurred on"
-    )
-    matching_text: Optional[str] = Field(
+    citation: Optional[List[FieldCitation]] = Field(
         None,
-        description="The original text this field's value was derived from",
+        description="The citation for the field, including page number and matching text",
     )
 
+    # Forbid unknown keys to avoid swallowing nested dicts
+    model_config = ConfigDict(extra="forbid")
+
 
 ExtractedFieldMetaDataDict = Dict[
     str, Union[ExtractedFieldMetadata, Dict[str, Any], list[Any]]
@@ -238,19 +247,10 @@ def _parse_extracted_field_metadata_recursive(
         if len(indicator_fields.intersection(field_value.keys())) > 0:
             try:
                 merged = {**field_value, **additional_fields}
+                allowed_fields = ExtractedFieldMetadata.model_fields.keys()
+                merged = {k: v for k, v in merged.items() if k in allowed_fields}
                 validated = ExtractedFieldMetadata.model_validate(merged)
 
-                # grab the citation from the array. This is just an array for backwards compatibility.
-                if "citation" in field_value and len(field_value["citation"]) > 0:
-                    first_citation = field_value["citation"][0]
-                    if "page" in first_citation and isinstance(
-                        first_citation["page"], numbers.Number
-                    ):
-                        validated.page_number = int(first_citation["page"])  # type: ignore
-                    if "matching_text" in first_citation and isinstance(
-                        first_citation["matching_text"], str
-                    ):
-                        validated.matching_text = first_citation["matching_text"]
                 return validated
             except ValidationError:
                 pass
@@ -340,6 +340,28 @@ class ExtractedData(BaseModel, Generic[ExtractedT]):
         description="Additional metadata about the extracted data, such as errors, tokens, etc.",
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_field_metadata_on_input(cls, value: Any) -> Any:
+        # Ensure any inbound representation (including JSON round-trips)
+        # gets normalized so nested dicts become ExtractedFieldMetadata where appropriate.
+        if (
+            isinstance(value, dict)
+            and "field_metadata" in value
+            and isinstance(value["field_metadata"], dict)
+        ):
+            try:
+                value = {
+                    **value,
+                    "field_metadata": parse_extracted_field_metadata(
+                        value["field_metadata"]
+                    ),
+                }
+            except Exception:
+                # Let pydantic surface detailed errors later rather than swallowing completely
+                pass
+        return value
+
     @classmethod
     def create(
         cls,

py/llama_cloud_services/beta/classifier/client.py

@@ -0,0 +1,187 @@
+import asyncio
+import time
+from typing import Optional
+from pydantic import BaseModel
+from llama_cloud.client import AsyncLlamaCloud
+from llama_cloud.types import (
+    ClassifierRule,
+    ClassifyJobResults,
+    ClassifyParsingConfiguration,
+    StatusEnum,
+    ClassifyJobWithStatus,
+    File,
+)
+from llama_cloud.resources.classifier.client import OMIT
+from llama_cloud_services.files.client import FileClient
+from llama_cloud_services.constants import POLLING_TIMEOUT_SECONDS
+from llama_cloud_services.utils import is_terminal_status, augment_async_errors
+from llama_index.core.async_utils import DEFAULT_NUM_WORKERS, run_jobs
+
+
+class ClassificationOutput(BaseModel):
+    file_id: str
+    classification: str
+
+
+class ClassifyClient:
+    """
+    Experimental - Client for interacting with the LlamaCloud Classifier API.
+    The Classification API is currently in beta and may change in the future without notice.
+
+    Args:
+        client: The LlamaCloud client to use.
+        project_id: The project ID to use.
+        organization_id: The organization ID to use.
+        polling_interval: The interval to poll for job completion in seconds.
+        polling_timeout: The timeout for the job to complete in seconds.
+    """
+
+    def __init__(
+        self,
+        client: AsyncLlamaCloud,
+        project_id: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        polling_interval: float = 1.0,
+        polling_timeout: float = POLLING_TIMEOUT_SECONDS,
+    ):
+        self.client = client
+        self.project_id = project_id
+        self.organization_id = organization_id
+        self.polling_interval = polling_interval
+        self.file_client = FileClient(client, project_id, organization_id)
+        self.polling_timeout = polling_timeout
+
+    async def aclassify_file_ids(
+        self,
+        rules: list[ClassifierRule],
+        file_ids: list[str],
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+    ) -> ClassifyJobResults:
+        """
+        Classify a list of files by their IDs.
+        Note that even if a job fails, some of the files may have been classified successfully.
+        In this case, you may want to set raise_on_error to False and check the results for successful classifications.
+
+        Args:
+            rules: The rules to use for classification.
+            file_ids: The IDs of the files to classify.
+            parsing_configuration: The parsing configuration to use for classification.
+            raise_on_error: Whether to raise an error if the classification job fails.
+
+        Returns:
+            The results of the classification job.
+        """
+        classify_job = await self.client.classifier.create_classify_job(
+            rules=rules,
+            file_ids=file_ids,
+            parsing_configuration=parsing_configuration or OMIT,
+            project_id=self.project_id,
+            organization_id=self.organization_id,
+        )
+
+        classify_job_with_status = await self._wait_for_job_completion(classify_job.id)
+
+        if raise_on_error and classify_job_with_status.status == StatusEnum.ERROR:
+            raise ValueError(
+                f"Error classifying files under job ID {classify_job_with_status.id}"
+            )
+
+        results = await self.client.classifier.get_classification_job_results(
+            classify_job_with_status.id,
+            project_id=self.project_id,
+            organization_id=self.organization_id,
+        )
+
+        return results
+
+    def classify_file_ids(
+        self,
+        rules: list[ClassifierRule],
+        file_ids: list[str],
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+    ) -> ClassifyJobResults:
+        with augment_async_errors():
+            return asyncio.run(
+                self.aclassify_file_ids(
+                    rules, file_ids, parsing_configuration, raise_on_error
+                )
+            )
+
+    async def aclassify_file_path(
+        self,
+        rules: list[ClassifierRule],
+        file_input_path: str,
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+    ) -> ClassifyJobResults:
+        file = await self.file_client.upload_file(file_input_path)
+        return await self.aclassify_file_ids(
+            rules, [file.id], parsing_configuration, raise_on_error
+        )
+
+    def classify_file_path(
+        self,
+        rules: list[ClassifierRule],
+        file_input_path: str,
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+    ) -> ClassifyJobResults:
+        with augment_async_errors():
+            return asyncio.run(
+                self.aclassify_file_path(
+                    rules, file_input_path, parsing_configuration, raise_on_error
+                )
+            )
+
+    async def aclassify_file_paths(
+        self,
+        rules: list[ClassifierRule],
+        file_input_paths: list[str],
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+        workers: int = DEFAULT_NUM_WORKERS,
+        show_progress: bool = False,
+    ) -> ClassifyJobResults:
+        coroutines = [self.file_client.upload_file(path) for path in file_input_paths]
+        files: list[File] = await run_jobs(
+            coroutines,
+            show_progress=show_progress,
+            workers=workers,
+            desc="Uploading files for classification",
+        )
+        return await self.aclassify_file_ids(
+            rules, [file.id for file in files], parsing_configuration, raise_on_error
+        )
+
+    def classify_file_paths(
+        self,
+        rules: list[ClassifierRule],
+        file_input_paths: list[str],
+        parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
+        raise_on_error: bool = True,
+    ) -> ClassifyJobResults:
+        with augment_async_errors():
+            return asyncio.run(
+                self.aclassify_file_paths(
+                    rules, file_input_paths, parsing_configuration, raise_on_error
+                )
+            )
+
+    async def _wait_for_job_completion(self, job_id: str) -> ClassifyJobWithStatus:
+        job = await self.client.classifier.get_classify_job(
+            job_id, project_id=self.project_id, organization_id=self.organization_id
+        )
+        start_time = time.time()
+        while not is_terminal_status(job.status):
+            polling_duration = time.time() - start_time
+            if polling_duration > self.polling_timeout:
+                raise TimeoutError(
+                    f"Job {job_id} timed out after {polling_duration} seconds"
+                )
+            await asyncio.sleep(self.polling_interval)
+            job = await self.client.classifier.get_classify_job(
+                job_id, project_id=self.project_id, organization_id=self.organization_id
+            )
+        return job

py/llama_cloud_services/constants.py

@@ -1 +1,2 @@
 EU_BASE_URL = "https://api.cloud.eu.llamaindex.ai"
+POLLING_TIMEOUT_SECONDS = 300.0

py/llama_cloud_services/extract/extract.py

@@ -33,9 +33,9 @@ from llama_cloud.client import AsyncLlamaCloud
 from llama_cloud.core.api_error import ApiError
 from llama_cloud_services.extract.utils import (
     JSONObjectType,
-    augment_async_errors,
     ExperimentalWarning,
 )
+from llama_cloud_services.utils import augment_async_errors
 from llama_index.core.schema import BaseComponent
 from llama_index.core.async_utils import run_jobs
 from llama_index.core.bridge.pydantic import Field, PrivateAttr

py/llama_cloud_services/extract/utils.py

@@ -1,12 +1,4 @@
-from typing import Any, Dict, List, Union, Generator
-from contextlib import contextmanager
-
-# Asyncio error messages
-nest_asyncio_err = "cannot be called from a running event loop"
-nest_asyncio_msg = (
-    "The event loop is already running. "
-    "Add `import nest_asyncio; nest_asyncio.apply()` to your code to fix this issue."
-)
+from typing import Any, Dict, List, Union
 
 
 def is_jupyter() -> bool:
@@ -19,17 +11,6 @@ def is_jupyter() -> bool:
         return False
 
 
-@contextmanager
-def augment_async_errors() -> Generator[None, None, None]:
-    """Context manager to add helpful information for errors due to nested event loops."""
-    try:
-        yield
-    except RuntimeError as e:
-        if nest_asyncio_err in str(e):
-            raise RuntimeError(nest_asyncio_msg)
-        raise
-
-
 JSONType = Union[Dict[str, Any], List[Any], str, int, float, bool, None]
 JSONObjectType = Dict[str, JSONType]
 

py/llama_cloud_services/files/__init__.py

@@ -0,0 +1,3 @@
+from .client import FileClient
+
+__all__ = ["FileClient"]

py/llama_cloud_services/files/client.py

@@ -0,0 +1,97 @@
+from io import BytesIO
+from typing import BinaryIO
+import os
+from llama_cloud.client import AsyncLlamaCloud
+from llama_cloud.types import File, FileCreate
+from typing import Optional
+
+
+class FileClient:
+    """
+    Higher-level client for interacting with the LlamaCloud Files API.
+    Uses presigned URLs for uploads by default.
+
+    Args:
+        client: The LlamaCloud client to use.
+        project_id: The project ID to use.
+        organization_id: The organization ID to use.
+        use_presigned_url: Whether to use presigned URLs for uploads (set to False when uploading to BYOC deployments).
+    """
+
+    def __init__(
+        self,
+        client: AsyncLlamaCloud,
+        project_id: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        use_presigned_url: bool = True,
+    ):
+        self.client = client
+        self.project_id = project_id
+        self.organization_id = organization_id
+        self.use_presigned_url = use_presigned_url
+
+    async def get_file(self, file_id: str) -> File:
+        return await self.client.files.get_file(
+            file_id, project_id=self.project_id, organization_id=self.organization_id
+        )
+
+    async def read_file_content(self, file_id: str) -> bytes:
+        presigned_url = await self.client.files.read_file_content(
+            file_id,
+            project_id=self.project_id,
+            organization_id=self.organization_id,
+        )
+        httpx_client = self.client._client_wrapper.httpx_client
+        response = await httpx_client.get(presigned_url.url)
+        response.raise_for_status()
+        return response.content
+
+    async def upload_file(
+        self, file_path: str, external_file_id: Optional[str] = None
+    ) -> File:
+        external_file_id = external_file_id or file_path
+        file_size = os.path.getsize(file_path)
+        with open(file_path, "rb") as file:
+            return await self.upload_buffer(file, external_file_id, file_size)
+
+    async def upload_bytes(self, bytes: bytes, external_file_id: str) -> File:
+        return await self.upload_buffer(BytesIO(bytes), external_file_id, len(bytes))
+
+    async def upload_buffer(
+        self,
+        buffer: BinaryIO,
+        external_file_id: str,
+        file_size: int,
+    ) -> File:
+        if self.use_presigned_url:
+            if getattr(buffer, "name", None):
+                name = os.path.basename(str(getattr(buffer, "name", external_file_id)))
+            else:
+                name = external_file_id
+            presigned_url = await self.client.files.generate_presigned_url(
+                project_id=self.project_id,
+                organization_id=self.organization_id,
+                request=FileCreate(
+                    name=name,
+                    external_file_id=external_file_id,
+                    file_size=file_size,
+                ),
+            )
+            httpx_client = self.client._client_wrapper.httpx_client
+            upload_response = await httpx_client.put(
+                presigned_url.url,
+                data=buffer.read(),
+            )
+            upload_response.raise_for_status()
+            return await self.client.files.get_file(
+                presigned_url.file_id,
+                project_id=self.project_id,
+                organization_id=self.organization_id,
+            )
+        else:
+            return await self.client.files.upload_file(
+                upload_file=buffer,
+                external_file_id=external_file_id,
+                project_id=self.project_id,
+                organization_id=self.organization_id,
+            )

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):
@@ -108,7 +112,7 @@ class ChartItem(BaseModel):
 class Page(BaseModel):
     """A page of the document."""
 
-    page: int = Field(description="The page number.")
+    page: int = Field(default=0, description="The page number.")
     text: Optional[str] = Field(default=None, description="The text of the page.")
     md: Optional[str] = Field(default=None, description="The markdown of the page.")
     images: List[ImageItem] = Field(
@@ -149,6 +153,12 @@ class Page(BaseModel):
     noTextContent: bool = Field(
         default=False, description="Whether the page has no text content."
     )
+    isAudioTranscript: bool = Field(
+        default=False, description="Whether the page is an audio transcript."
+    )
+    durationInSeconds: Optional[float] = Field(
+        default=None, description="The duration of the audio transcript in seconds."
+    )
 
 
 class JobResult(BaseModel):

py/llama_cloud_services/utils.py

@@ -1,12 +1,21 @@
 import os
 import importlib.metadata
-
+from contextlib import contextmanager
+from typing import Generator
 import difflib
+from llama_cloud.types import StatusEnum
 import httpx
 import packaging.version
 from pydantic import BaseModel
 from typing import Any, Dict, List, Tuple, Type
 
+# Asyncio error messages
+nest_asyncio_err = "cannot be called from a running event loop"
+nest_asyncio_msg = (
+    "The event loop is already running. "
+    "Add `import nest_asyncio; nest_asyncio.apply()` to your code to fix this issue."
+)
+
 
 def check_extra_params(
     model_cls: Type[BaseModel], data: Dict[str, Any]
@@ -34,6 +43,25 @@ def check_extra_params(
     return extra_params, suggestions
 
 
+def is_terminal_status(status: StatusEnum) -> bool:
+    """
+    Check if a status is terminal, i.e. the job is done and no more updates are expected.
+    Note: this must be updated if the status enum is updated.
+
+    Args:
+        status: The status to check
+
+    Returns:
+        True if the status is terminal, False otherwise
+    """
+    return status in {
+        StatusEnum.SUCCESS,
+        StatusEnum.ERROR,
+        StatusEnum.CANCELLED,
+        StatusEnum.PARTIAL_SUCCESS,
+    }
+
+
 async def check_for_updates(client: httpx.AsyncClient, quiet: bool = True) -> bool:
     """Check if an SDK update is available.
 
@@ -65,3 +93,14 @@ async def check_for_updates(client: httpx.AsyncClient, quiet: bool = True) -> bo
     elif not quiet:
         print(f"{package_name} is up to date")
     return False
+
+
+@contextmanager
+def augment_async_errors() -> Generator[None, None, None]:
+    """Context manager to add helpful information for errors due to nested event loops."""
+    try:
+        yield
+    except RuntimeError as e:
+        if nest_asyncio_err in str(e):
+            raise RuntimeError(nest_asyncio_msg)
+        raise

py/llama_parse/pyproject.toml

@@ -11,13 +11,13 @@ dev = [
 
 [project]
 name = "llama-parse"
-version = "0.6.55"
+version = "0.6.58"
 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.55"]
+dependencies = ["llama-cloud-services>=0.6.58"]
 
 [project.scripts]
 llama-parse = "llama_parse.cli.main:parse"

py/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@llama_cloud_services/py",
-  "version": "0.6.55",
-  "private": "true",
-  "license": "MIT",
-  "scripts": {
-    "version": "cd .. && pnpm changeset version && bash py/scripts/new_version.sh",
-    "release": "bash scripts/release.sh"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "changesets": "^1.0.2"
-  }
-}

py/pyproject.toml

@@ -12,12 +12,13 @@ dev = [
   "deepdiff>=8.1.1,<9",
   "ipython>=8.12.3,<9",
   "jupyter>=1.1.1,<2",
-  "mypy>=1.14.1,<2"
+  "mypy>=1.14.1,<2",
+  "pydantic-settings>=2.10.1"
 ]
 
 [project]
 name = "llama-cloud-services"
-version = "0.6.55"
+version = "0.6.58"
 description = "Tailored SDK clients for LlamaCloud services."
 authors = [{name = "Logan Markewich", email = "logan@runllama.ai"}]
 requires-python = ">=3.9,<4.0"

py/pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+asyncio_mode = auto

py/scripts/new_version.py

@@ -1,34 +0,0 @@
-import toml  # type: ignore [import]
-import json
-
-
-def change_parse_dep(data: dict, version: str) -> dict:
-    dep, ver = (
-        data["project"]["dependencies"][0].split(">=")[0],
-        data["project"]["dependencies"][0].split(">=")[1],
-    )
-    ver = version
-    dependency = dep + ">=" + ver
-    data["project"]["dependencies"].insert(0, dependency)
-    data["project"]["dependencies"].pop(1)
-    return data
-
-
-with open("py/package.json", "r") as p:
-    package_data = json.load(p)
-
-with open("py/pyproject.toml", "r") as t:
-    toml_data = toml.load(t)
-
-with open("py/llama_parse/pyproject.toml", "r") as pt:
-    parse_toml_data = toml.load(pt)
-
-toml_data["project"]["version"] = package_data["version"]
-parse_toml_data["project"]["version"] = package_data["version"]
-parse_toml_data = change_parse_dep(parse_toml_data, package_data["version"])
-
-with open("py/pyproject.toml", "w") as w:
-    toml.dump(toml_data, w)
-
-with open("py/llama_parse/pyproject.toml", "w") as pw:
-    toml.dump(parse_toml_data, pw)

py/scripts/new_version.sh

@@ -1,22 +0,0 @@
-# create uv virtual environment
-uv venv
-source .venv/bin/activate
-
-# install toml
-uv pip install -r py/scripts/requirements.txt
-
-# run version change
-uv run -- python3 py/scripts/new_version.py
-
-# test version change
-status_code=$(uv run -- python3 py/scripts/test_new_version.py) # returns 0 if the versions are the same, 1 if they are not
-
-if [ "$status_code" -eq 1 ]; then
-   echo "Versions do not match, the version change failed..."
-   exit 1
-elif [ "$status_code" -eq 0 ]; then
-   # lock the version changes
-   cd py/ && uv lock
-   echo "Versions successfully changed"
-   exit 0
-fi

py/scripts/pre_release_check.py

@@ -1,21 +0,0 @@
-import toml  # type: ignore [import]
-import requests
-
-
-def get_latest_version(package_name: str) -> str:
-    url = f"https://pypi.org/pypi/{package_name}/json"
-    response = requests.get(url)
-    if response.status_code == 200:
-        data = response.json()
-        return data["info"]["version"]
-    else:
-        raise Exception(f"Package '{package_name}' not found on PyPI.")
-
-
-with open("pyproject.toml", "r") as t:
-    toml_data = toml.load(t)
-
-if toml_data["project"]["version"] == get_latest_version("llama-cloud-services"):
-    print("1")
-else:
-    print("0")

py/scripts/release.sh

@@ -1,36 +0,0 @@
-# initialize pypi_token
-pypi_token="no_token"
-
-while
-    [[ $# -gt 0 ]] \
-        ;
-do
-    case "$1" in
-    -t | --token)
-        pypi_token="$2"
-    esac
-done
-
-if [[ $pypi_token == "no_token" ]]; then
-    if [[ $LLAMA_PARSE_PYPI_TOKEN == "" ]]; then
-        echo "No token provided and no token in the environment, exiting..."
-        exit 1
-    else
-        pypi_token="$LLAMA_PARSE_PYPI_TOKEN"
-    fi
-fi
-
-# check pre-release
-uv venv && source .venv/bin/activate && uv pip install -r scripts/requirements.txt
-do_not_release=$(python3 scripts/pre_release_check.py)
-
-if [ "$do_not_release" -eq 1 ]; then
-   echo "Nothing to release"
-   exit 0
-else
-    # build and publish llama_cloud_services
-    ## build
-    uv build
-    ## publish
-    uv publish --token $pypi_token
-fi

py/scripts/requirements.txt

@@ -1,2 +0,0 @@
-toml
-requests

py/scripts/test_new_version.py

@@ -1,32 +0,0 @@
-import toml  # type: ignore [import]
-import json
-
-
-def test_versions_equal(
-    package_data: dict, toml_data: dict, parse_toml_data: dict
-) -> None:
-    llama_cloud_version = toml_data["project"]["version"]
-    package_version = package_data["version"]
-    parse_version = parse_toml_data["project"]["version"]
-    parse_dep_version = parse_toml_data["project"]["dependencies"][0].split(">=")[1]
-    try:
-        assert (
-            llama_cloud_version == package_version
-            and llama_cloud_version == parse_version
-            and llama_cloud_version == parse_dep_version
-        )
-        print("0")
-    except AssertionError:
-        print("1")
-
-
-with open("py/package.json", "r") as p:
-    package_data = json.load(p)
-
-with open("py/pyproject.toml", "r") as t:
-    toml_data = toml.load(t)
-
-with open("py/llama_parse/pyproject.toml", "r") as pt:
-    parse_toml_data = toml.load(pt)
-
-test_versions_equal(package_data, toml_data, parse_toml_data)

py/tests/classifier/test_client.py

@@ -0,0 +1,212 @@
+import os
+import pytest
+from llama_cloud.client import AsyncLlamaCloud
+from llama_cloud.types import Project, ClassifierRule, ClassifyJobResults
+from llama_cloud_services.beta.classifier.client import ClassifyClient
+from llama_cloud_services.files.client import FileClient
+from llama_cloud.errors.unprocessable_entity_error import UnprocessableEntityError
+from tests.conftest import EndToEndTestSettings
+import nest_asyncio
+
+# Skip all tests if API key is not set
+pytestmark = pytest.mark.skipif(
+    not os.getenv("LLAMA_CLOUD_API_KEY"), reason="LLAMA_CLOUD_API_KEY not set"
+)
+
+
+@pytest.fixture
+def async_llama_cloud_client(
+    e2e_test_settings: EndToEndTestSettings,
+) -> AsyncLlamaCloud:
+    return AsyncLlamaCloud(
+        token=e2e_test_settings.LLAMA_CLOUD_API_KEY.get_secret_value(),
+        base_url=e2e_test_settings.LLAMA_CLOUD_BASE_URL,
+    )
+
+
+@pytest.fixture
+async def project(
+    async_llama_cloud_client: AsyncLlamaCloud, e2e_test_settings: EndToEndTestSettings
+) -> Project:
+    projects = await async_llama_cloud_client.projects.list_projects(
+        project_name=e2e_test_settings.LLAMA_CLOUD_PROJECT_NAME,
+        organization_id=e2e_test_settings.LLAMA_CLOUD_ORGANIZATION_ID,
+    )
+    assert len(projects) == 1
+    return projects[0]
+
+
+@pytest.fixture
+def classify_client(
+    async_llama_cloud_client: AsyncLlamaCloud, project: Project
+) -> ClassifyClient:
+    return ClassifyClient(
+        async_llama_cloud_client,
+        project_id=project.id,
+        organization_id=project.organization_id,
+        polling_interval=1,
+    )
+
+
+@pytest.fixture
+def file_client(
+    async_llama_cloud_client: AsyncLlamaCloud, project: Project
+) -> FileClient:
+    return FileClient(
+        async_llama_cloud_client,
+        project_id=project.id,
+        organization_id=project.organization_id,
+        use_presigned_url=False,
+    )
+
+
+@pytest.fixture(scope="session", autouse=True)
+def apply_nest_asyncio():
+    nest_asyncio.apply()
+
+
+@pytest.fixture
+def simple_pdf_file_path() -> str:
+    return "tests/test_files/index/Simple PDF Slides.pdf"
+
+
+@pytest.fixture
+def research_paper_path() -> str:
+    return "tests/test_files/attention_is_all_you_need_chart.pdf"
+
+
+@pytest.fixture
+def classification_rules() -> list[ClassifierRule]:
+    return [
+        ClassifierRule(
+            type="number",
+            description="Documents with numbers",
+        ),
+        ClassifierRule(
+            type="research_paper",
+            description="Research papers",
+        ),
+    ]
+
+
+parameterize_sync_and_async = pytest.mark.parametrize("sync", [True, False])
+
+
+@parameterize_sync_and_async
+@pytest.mark.asyncio
+async def test_classify_file_ids(
+    classify_client: ClassifyClient,
+    file_client: FileClient,
+    simple_pdf_file_path: str,
+    research_paper_path: str,
+    classification_rules: list[ClassifierRule],
+    sync: bool,
+):
+    """Test classifying files by their IDs"""
+    # Upload test files first to get their IDs
+    pdf_file = await file_client.upload_file(simple_pdf_file_path)
+    research_paper_file = await file_client.upload_file(research_paper_path)
+
+    # Classify the uploaded files
+    if sync:
+        results = classify_client.classify_file_ids(
+            rules=classification_rules, file_ids=[pdf_file.id, research_paper_file.id]
+        )
+    else:
+        results = await classify_client.aclassify_file_ids(
+            rules=classification_rules, file_ids=[pdf_file.id, research_paper_file.id]
+        )
+
+    assert isinstance(results, ClassifyJobResults)
+    assert len(results.items) == 2
+
+    file_id_to_expected_type = {
+        pdf_file.id: "number",
+        research_paper_file.id: "research_paper",
+    }
+    # Verify each file got classified
+    for item in results.items:
+        expected_type = file_id_to_expected_type[item.file_id]
+        assert item.result.type == expected_type
+
+
+@parameterize_sync_and_async
+@pytest.mark.asyncio
+async def test_classify_file_path(
+    classify_client: ClassifyClient,
+    simple_pdf_file_path: str,
+    classification_rules: list[ClassifierRule],
+    sync: bool,
+):
+    """Test classifying a single file by path"""
+    # Classify the file
+    if sync:
+        results = classify_client.classify_file_path(
+            rules=classification_rules, file_input_path=simple_pdf_file_path
+        )
+    else:
+        results = await classify_client.aclassify_file_path(
+            rules=classification_rules, file_input_path=simple_pdf_file_path
+        )
+
+    assert isinstance(results, ClassifyJobResults)
+    assert len(results.items) == 1
+
+    # Verify the file got classified
+    item = results.items[0]
+    assert item.result.type == "number"
+
+
+@parameterize_sync_and_async
+@pytest.mark.asyncio
+async def test_classify_file_paths(
+    classify_client: ClassifyClient,
+    file_client: FileClient,
+    simple_pdf_file_path: str,
+    research_paper_path: str,
+    classification_rules: list[ClassifierRule],
+    sync: bool,
+):
+    """Test classifying multiple files by paths"""
+    # Classify all test files
+    if sync:
+        results = classify_client.classify_file_paths(
+            rules=classification_rules,
+            file_input_paths=[simple_pdf_file_path, research_paper_path],
+        )
+    else:
+        results = await classify_client.aclassify_file_paths(
+            rules=classification_rules,
+            file_input_paths=[simple_pdf_file_path, research_paper_path],
+        )
+
+    assert isinstance(results, ClassifyJobResults)
+    assert len(results.items) == 2
+
+    file_name_to_expected_type = {
+        os.path.basename(simple_pdf_file_path): "number",
+        os.path.basename(research_paper_path): "research_paper",
+    }
+    # Verify each file got classified
+    for item in results.items:
+        file = await file_client.get_file(item.file_id)
+        expected_type = file_name_to_expected_type[file.name]
+        assert item.result.type == expected_type
+
+
+@parameterize_sync_and_async
+@pytest.mark.asyncio
+async def test_classify_empty_file_list(
+    classify_client: ClassifyClient,
+    classification_rules: list[ClassifierRule],
+    sync: bool,
+):
+    """Test classifying an empty list of files"""
+    # This should throw an error
+    with pytest.raises(UnprocessableEntityError):
+        if sync:
+            classify_client.classify_file_ids(rules=classification_rules, file_ids=[])
+        else:
+            await classify_client.aclassify_file_ids(
+                rules=classification_rules, file_ids=[]
+            )

py/tests/conftest.py

@@ -0,0 +1,26 @@
+import pytest
+from llama_index.core.constants import DEFAULT_BASE_URL
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings
+
+
+class EndToEndTestSettings(BaseSettings):
+    LLAMA_CLOUD_BASE_URL: str = Field(
+        description="The base URL of the LlamaCloud API", default=DEFAULT_BASE_URL
+    )
+    LLAMA_CLOUD_API_KEY: SecretStr = Field(
+        description="The API key for the LlamaCloud API"
+    )
+    LLAMA_CLOUD_ORGANIZATION_ID: str | None = Field(
+        description="The organization ID for the LlamaCloud API",
+        default=None,
+    )
+    LLAMA_CLOUD_PROJECT_NAME: str = Field(
+        description="The project name for the LlamaCloud API",
+        default="framework_integration_test",
+    )
+
+
+@pytest.fixture
+def e2e_test_settings() -> EndToEndTestSettings:
+    return EndToEndTestSettings()

py/tests/index/test_index.py

@@ -27,8 +27,6 @@ api_key = os.environ.get("LLAMA_CLOUD_API_KEY", None)
 organization_id = os.environ.get("LLAMA_CLOUD_ORGANIZATION_ID", None)
 project_name = os.environ.get("LLAMA_CLOUD_PROJECT_NAME", "framework_integration_test")
 
-print("api-key", api_key, "base-url", base_url)
-
 
 @pytest.fixture()
 def remote_file() -> Tuple[str, str]:

py/tests/parse/test_llama_parse.py

@@ -202,3 +202,12 @@ async def test_get_result(markdown_parser: LlamaParse) -> None:
     result = await markdown_parser.aget_result(expected.job_id)
     assert result.job_id == expected.job_id
     assert len(result.pages) == len(expected.pages)
+
+
+@pytest.mark.asyncio
+async def test_parse_audio() -> None:
+    parser = LlamaParse()
+    filepath = "tests/test_files/hello_world.m4a"
+
+    result = await parser.aparse(filepath)
+    assert result.job_id is not None

py/tests/test_files_client.py

@@ -0,0 +1,147 @@
+import os
+import pytest
+from io import BytesIO
+from llama_cloud.client import AsyncLlamaCloud
+from llama_cloud.types import Project, File
+from llama_cloud_services.files.client import FileClient
+from tests.conftest import EndToEndTestSettings
+
+
+@pytest.fixture
+async def llama_cloud_client(
+    e2e_test_settings: EndToEndTestSettings,
+) -> AsyncLlamaCloud:
+    return AsyncLlamaCloud(
+        token=e2e_test_settings.LLAMA_CLOUD_API_KEY.get_secret_value(),
+        base_url=e2e_test_settings.LLAMA_CLOUD_BASE_URL,
+    )
+
+
+@pytest.fixture
+async def project(
+    llama_cloud_client: AsyncLlamaCloud, e2e_test_settings: EndToEndTestSettings
+) -> Project:
+    projects = await llama_cloud_client.projects.list_projects(
+        project_name=e2e_test_settings.LLAMA_CLOUD_PROJECT_NAME,
+        organization_id=e2e_test_settings.LLAMA_CLOUD_ORGANIZATION_ID,
+    )
+    assert len(projects) == 1
+    return projects[0]
+
+
+@pytest.fixture
+async def file_client(
+    llama_cloud_client: AsyncLlamaCloud, project: Project, use_presigned_url: bool
+) -> FileClient:
+    return FileClient(
+        llama_cloud_client,
+        project_id=project.id,
+        organization_id=project.organization_id,
+        use_presigned_url=use_presigned_url,
+    )
+
+
+@pytest.fixture
+def test_file() -> str:
+    return "tests/test_files/index/Simple PDF Slides.pdf"
+
+
+parametrize_use_presigned_url = pytest.mark.parametrize(
+    "use_presigned_url", [True, False]
+)
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_upload_file_from_path(file_client: FileClient, test_file: str):
+    """Test uploading a file from file path"""
+    external_file_id = f"test_upload_path_{os.getpid()}"
+    uploaded_file = await file_client.upload_file(test_file, external_file_id)
+
+    assert isinstance(uploaded_file, File)
+    expected_name = os.path.basename(test_file)
+    assert uploaded_file.name == expected_name
+    assert uploaded_file.external_file_id == external_file_id
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_upload_bytes(
+    file_client: FileClient, test_file: str, use_presigned_url: bool
+):
+    """Test uploading a file from bytes"""
+    # Read file as bytes
+    with open(test_file, "rb") as f:
+        file_bytes = f.read()
+
+    external_file_id = f"test_upload_bytes_{os.getpid()}"
+    uploaded_file = await file_client.upload_bytes(file_bytes, external_file_id)
+
+    assert isinstance(uploaded_file, File)
+    expected_name = external_file_id if use_presigned_url else "upload"
+    assert uploaded_file.name == expected_name
+    assert uploaded_file.external_file_id == external_file_id
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_upload_buffer(
+    file_client: FileClient, test_file: str, use_presigned_url: bool
+):
+    """Test uploading a file from buffer"""
+    # Read file as bytes and create buffer
+    with open(test_file, "rb") as f:
+        file_bytes = f.read()
+
+    buffer = BytesIO(file_bytes)
+    file_size = len(file_bytes)
+    external_file_id = f"test_upload_buffer_{os.getpid()}"
+
+    uploaded_file = await file_client.upload_buffer(buffer, external_file_id, file_size)
+
+    assert isinstance(uploaded_file, File)
+    expected_name = external_file_id if use_presigned_url else "upload"
+    assert uploaded_file.name == expected_name
+    assert uploaded_file.external_file_id == external_file_id
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_get_file(file_client: FileClient, test_file: str):
+    """Test retrieving a file by ID"""
+    # Upload a file first
+    external_file_id = f"test_get_file_{os.getpid()}"
+    uploaded_file = await file_client.upload_file(test_file, external_file_id)
+
+    # Retrieve the file by ID
+    retrieved_file = await file_client.get_file(uploaded_file.id)
+
+    assert isinstance(retrieved_file, File)
+    assert retrieved_file == uploaded_file
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_upload_with_default_external_id(file_client: FileClient, test_file: str):
+    """Test uploading file with default external_file_id"""
+    # Upload file without specifying external_file_id
+    uploaded_file = await file_client.upload_file(test_file)
+
+    assert isinstance(uploaded_file, File)
+    assert uploaded_file.name == os.path.basename(test_file)
+    assert uploaded_file.external_file_id == test_file
+
+
+@parametrize_use_presigned_url
+@pytest.mark.asyncio
+async def test_read_file_content(file_client: FileClient, test_file: str):
+    """Test reading a file content"""
+    # Upload a file first
+    external_file_id = f"test_read_file_content_{os.getpid()}"
+    uploaded_file = await file_client.upload_file(test_file, external_file_id)
+
+    # Read the file content
+    file_content = await file_client.read_file_content(uploaded_file.id)
+    with open(test_file, "rb") as f:
+        expected_file_content = f.read()
+    assert file_content == expected_file_content

py/unit_tests/beta/agent/test_agent_data_schema.py

@@ -1,15 +1,18 @@
 from datetime import datetime
-from typing import Any, Dict
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
 
 import pytest
 from llama_cloud import ExtractRun, File
 from llama_cloud.types.agent_data import AgentData
 from llama_cloud.types.aggregate_group import AggregateGroup
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, Field, ValidationError
 
 from llama_cloud_services.beta.agent_data.schema import (
     ExtractedData,
     ExtractedFieldMetadata,
+    FieldCitation,
     InvalidExtractionData,
     TypedAgentData,
     TypedAggregateGroup,
@@ -81,8 +84,12 @@ def test_extracted_data_create_method():
 
     # Test with custom values using ExtractedFieldMetadata
     field_metadata = {
-        "name": ExtractedFieldMetadata(confidence=0.99, page_number=1),
-        "age": ExtractedFieldMetadata(confidence=0.85, page_number=1),
+        "name": ExtractedFieldMetadata(
+            confidence=0.99, citation=[FieldCitation(page=1)]
+        ),
+        "age": ExtractedFieldMetadata(
+            confidence=0.85, citation=[FieldCitation(page=1)]
+        ),
     }
     extracted_custom = ExtractedData.create(
         person, status="accepted", field_metadata=field_metadata
@@ -254,14 +261,16 @@ def test_parse_extracted_field_metadata():
     # name should have parsed citation data
     assert isinstance(result["name"], ExtractedFieldMetadata)
     assert result["name"].confidence == 0.95
-    assert result["name"].page_number == 1
-    assert result["name"].matching_text == "John Smith"
+    assert result["name"].citation == [
+        FieldCitation(page=1, matching_text="John Smith")
+    ]
 
     # age should handle float page number
     assert isinstance(result["age"], ExtractedFieldMetadata)
     assert result["age"].confidence == 0.87
-    assert result["age"].page_number == 2  # Should be converted to int
-    assert result["age"].matching_text == "25 years old"
+    assert result["age"].citation == [
+        FieldCitation(page=2, matching_text="25 years old")
+    ]
 
     # email should handle empty citations
     assert isinstance(result["email"], ExtractedFieldMetadata)
@@ -327,30 +336,38 @@ def test_parse_extracted_field_metadata_complex():
             reasoning="Combined key parametrics and construction from the datasheet for a structured title.",
             confidence=0.9470628580889779,
             extraction_confidence=0.9470628580889779,
-            page_number=1,
-            matching_text="PHE844/F844, Film, Metallized Polypropylene, Safety, 0.47 uF",
+            citation=[
+                FieldCitation(
+                    page=1,
+                    matching_text="PHE844/F844, Film, Metallized Polypropylene, Safety, 0.47 uF",
+                )
+            ],
         ),
         "manufacturer": ExtractedFieldMetadata(
             reasoning="VERBATIM EXTRACTION",
             confidence=0.9997446550976602,
             extraction_confidence=0.9997446550976602,
-            page_number=1,
-            matching_text="YAGEO KEMET",
+            citation=[FieldCitation(page=1, matching_text="YAGEO KEMET")],
         ),
         "features": [
             ExtractedFieldMetadata(
                 reasoning="VERBATIM EXTRACTION",
                 confidence=0.9999308195540074,
                 extraction_confidence=0.9999308195540074,
-                page_number=1,
-                matching_text="Features</td><td>EMI Safety",
+                citation=[
+                    FieldCitation(
+                        page=1,
+                        matching_text="Features</td><td>EMI Safety",
+                    )
+                ],
             ),
             ExtractedFieldMetadata(
                 reasoning="VERBATIM EXTRACTION",
                 confidence=0.8642493886452225,
                 extraction_confidence=0.8642493886452225,
-                page_number=1,
-                matching_text="THB Performance</td><td>Yes",
+                citation=[
+                    FieldCitation(page=1, matching_text="THB Performance</td><td>Yes")
+                ],
             ),
         ],
         "dimensions": {
@@ -358,15 +375,13 @@ def test_parse_extracted_field_metadata_complex():
                 reasoning="VERBATIM EXTRACTION",
                 confidence=0.8986941382802304,
                 extraction_confidence=0.8986941382802304,
-                page_number=1,
-                matching_text="L</td><td>41mm MAX",
+                citation=[FieldCitation(page=1, matching_text="L</td><td>41mm MAX")],
             ),
             "width": ExtractedFieldMetadata(
                 reasoning="VERBATIM EXTRACTION",
                 confidence=0.9999377974447091,
                 extraction_confidence=0.9999377974447091,
-                page_number=1,
-                matching_text="T</td><td>13mm MAX",
+                citation=[FieldCitation(page=1, matching_text="T</td><td>13mm MAX")],
             ),
         },
     }
@@ -450,8 +465,9 @@ def test_extracted_data_from_extraction_result_success():
     # Verify field metadata was parsed
     assert isinstance(extracted.field_metadata["name"], ExtractedFieldMetadata)
     assert extracted.field_metadata["name"].confidence == 0.95
-    assert extracted.field_metadata["name"].page_number == 1
-    assert extracted.field_metadata["name"].matching_text == "John Doe"
+    assert extracted.field_metadata["name"].citation == [
+        FieldCitation(page=1, matching_text="John Doe")
+    ]
 
     # Verify overall confidence was calculated
     expected_confidence = (0.95 + 0.87 + 0.92) / 3
@@ -523,3 +539,54 @@ def test_extracted_data_from_extraction_result_invalid_data():
     assert isinstance(invalid_data.field_metadata["name"], ExtractedFieldMetadata)
     assert invalid_data.field_metadata["name"].confidence == 0.9
     assert invalid_data.overall_confidence == 0.9
+
+
+class Dimensions(BaseModel):
+    length: Optional[str] = Field(
+        None, description="Length in mm (Size, Longest Side, L)"
+    )
+    width: Optional[str] = Field(
+        None, description="Width in mm (Breadth, Side Width, W)"
+    )
+    height: Optional[str] = Field(
+        None, description="Height in mm (Thickness, Vertical Size, H)"
+    )
+    diameter: Optional[str] = Field(
+        None,
+        description="Diameter in mm (for radial or cylindrical types) (Outer Diameter, dt, OD, D, d<sub>t</sub>)",
+    )
+    lead_spacing: Optional[str] = Field(
+        None, description="Lead spacing in mm (Pin Pitch, Terminal Gap, LS)"
+    )
+
+
+class Capacitor(BaseModel):
+    dimensions: Optional[Dimensions] = None
+
+
+def test_full_parse_nested_dimensions():
+    with open(Path(__file__).parent.parent.parent / "data" / "capacitor.json") as f:
+        data = json.load(f)
+    result = ExtractedData.from_extraction_result(ExtractRun.parse_obj(data), Capacitor)
+    expected = {
+        "dimensions": {
+            "diameter": ExtractedFieldMetadata(
+                reasoning="VERBATIM EXTRACTION",
+                confidence=1.0,
+                extraction_confidence=1.0,
+            ),
+            "lead_spacing": ExtractedFieldMetadata(
+                reasoning="VERBATIM EXTRACTION",
+                confidence=0.9999999031936799,
+                extraction_confidence=0.9999999031936799,
+            ),
+            "length": ExtractedFieldMetadata(
+                reasoning="VERBATIM EXTRACTION",
+                confidence=0.9999968039036192,
+                extraction_confidence=0.9999968039036192,
+            ),
+        }
+    }
+    assert result.field_metadata == expected
+    parsed = ExtractedData.model_validate_json(result.model_dump_json())
+    assert parsed.field_metadata == expected

py/unit_tests/data/capacitor.json

@@ -0,0 +1,116 @@
+{
+  "id": "de058dda-6ca7-4eea-a426-da802f84f971",
+  "created_at": "2025-08-13T15:45:39.286921Z",
+  "updated_at": "2025-08-13T15:47:04.878069Z",
+  "extraction_agent_id": "e834e99f-1f35-4748-b82f-03de4bd07ca6",
+  "data_schema": {
+    "additionalProperties": false,
+    "properties": {
+      "dimensions": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "length": {
+                "anyOf": [{ "type": "string" }, { "type": "null" }],
+                "description": "Length in mm (Size, Longest Side, L)"
+              },
+              "width": {
+                "anyOf": [{ "type": "string" }, { "type": "null" }],
+                "description": "Width in mm (Breadth, Side Width, W)"
+              },
+              "height": {
+                "anyOf": [{ "type": "string" }, { "type": "null" }],
+                "description": "Height in mm (Thickness, Vertical Size, H)"
+              },
+              "diameter": {
+                "anyOf": [{ "type": "string" }, { "type": "null" }],
+                "description": "Diameter in mm (for radial or cylindrical types) (Outer Diameter, OD, D)"
+              },
+              "lead_spacing": {
+                "anyOf": [{ "type": "string" }, { "type": "null" }],
+                "description": "Lead spacing in mm (Pin Pitch, Terminal Gap, LS)"
+              }
+            },
+            "required": [
+              "length",
+              "width",
+              "height",
+              "diameter",
+              "lead_spacing"
+            ],
+            "type": "object"
+          },
+          { "type": "null" }
+        ]
+      }
+    },
+    "required": ["dimensions"],
+    "type": "object"
+  },
+  "config": {
+    "priority": null,
+    "extraction_target": "PER_DOC",
+    "extraction_mode": "PREMIUM",
+    "multimodal_fast_mode": false,
+    "system_prompt": "",
+    "use_reasoning": true,
+    "cite_sources": false,
+    "confidence_scores": true,
+    "chunk_mode": "PAGE",
+    "high_resolution_mode": false,
+    "invalidate_cache": false,
+    "page_range": null
+  },
+  "file": {
+    "id": "9233cc2b-00e3-4ddd-b426-b8b59357d4cb",
+    "created_at": "2025-08-12T18:31:54.269440Z",
+    "updated_at": "2025-08-13T15:45:39.064906Z",
+    "name": "document (2).pdf.txt",
+    "external_file_id": "document (2).pdf.txt",
+    "file_size": 2562,
+    "file_type": "txt",
+    "project_id": "77bdc79f-fb69-49ae-a783-fcc573eec7ce",
+    "last_modified_at": "2025-08-13T15:45:39Z",
+    "resource_info": {
+      "file_size": 2562,
+      "last_modified_at": "2025-08-13T15:45:39"
+    },
+    "permission_info": null,
+    "data_source_id": null
+  },
+  "status": "SUCCESS",
+  "error": null,
+  "job_id": "5bb8a583-366c-416c-ba55-4f5724fef9a9",
+  "data": {
+    "dimensions": {
+      "length": "82 mm",
+      "width": null,
+      "height": null,
+      "diameter": "35 mm",
+      "lead_spacing": "6.0 mm"
+    }
+  },
+  "extraction_metadata": {
+    "field_metadata": {
+      "dimensions": {
+        "length": {
+          "extraction_confidence": 0.9999968039036192,
+          "confidence": 0.9999968039036192
+        },
+        "diameter": { "extraction_confidence": 1.0, "confidence": 1.0 },
+        "lead_spacing": {
+          "extraction_confidence": 0.9999999031936799,
+          "confidence": 0.9999999031936799
+        },
+        "reasoning": "VERBATIM EXTRACTION"
+      }
+    },
+    "usage": {
+      "num_pages_extracted": 2,
+      "num_document_tokens": 1034,
+      "num_output_tokens": 3440
+    }
+  },
+  "from_ui": false
+}

py/uv.lock

@@ -1587,7 +1587,7 @@ wheels = [
 
 [[package]]
 name = "llama-cloud-services"
-version = "0.6.54"
+version = "0.6.58"
 source = { editable = "." }
 dependencies = [
     { name = "click", version = "8.1.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
@@ -1612,6 +1612,7 @@ dev = [
     { name = "jupyter" },
     { name = "mypy" },
     { name = "pre-commit" },
+    { name = "pydantic-settings" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
 ]
@@ -1638,6 +1639,7 @@ dev = [
     { name = "jupyter", specifier = ">=1.1.1,<2" },
     { name = "mypy", specifier = ">=1.14.1,<2" },
     { name = "pre-commit", specifier = "==3.2.0" },
+    { name = "pydantic-settings", specifier = ">=2.10.1" },
     { name = "pytest", specifier = ">=8.0.0,<9" },
     { name = "pytest-asyncio" },
 ]
@@ -2855,6 +2857,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/29/3cade8a924a61f60ccfa10842f75eb12787e1440e2b8660ceffeb26685e7/pydantic_core-2.33.2-pp39-pypy39_pp73-win_amd64.whl", hash = "sha256:2807668ba86cb38c6817ad9bc66215ab8584d1d304030ce4f0887336f28a5e27", size = 2066661, upload-time = "2025-04-23T18:33:49.995Z" },
 ]
 
+[[package]]
+name = "pydantic-settings"
+version = "2.10.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/68/85/1ea668bbab3c50071ca613c6ab30047fb36ab0da1b92fa8f17bbc38fd36c/pydantic_settings-2.10.1.tar.gz", hash = "sha256:06f0062169818d0f5524420a360d632d5857b83cffd4d42fe29597807a1614ee", size = 172583, upload-time = "2025-06-24T13:26:46.841Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.19.2"

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.2",
   "type": "module",
   "license": "MIT",
   "scripts": {
@@ -12,9 +12,7 @@
     "test": "vitest run --testTimeout=60000",
     "test:watch": "vitest --watch",
     "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "version": "cd .. && pnpm changeset version",
-    "release": "pnpm run build && cd .. && pnpm changeset publish"
+    "test:coverage": "vitest --coverage"
   },
   "files": [
     "openapi.json",
@@ -22,7 +20,8 @@
     "./api",
     "./reader",
     "./parse",
-    "./beta/agent"
+    "./beta/agent",
+    "./extract"
   ],
   "exports": {
     "./openapi.json": "./openapi.json",
@@ -70,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",
@@ -115,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/beta/agent/types.ts

@@ -38,8 +38,12 @@ export interface ExtractedFieldMetadata {
   confidence?: number;
   /** The confidence score for the field based on the extracted text only */
   extraction_confidence?: number;
+  citation: FieldCitation[];
+}
+
+export interface FieldCitation {
   /** The page number that the field occurred on */
-  page_number?: number;
+  page?: number;
   /** The original text this field's value was derived from */
   matching_text?: string;
 }

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",