bump to 0.6.44

* parse: loosen PageItem.rows type hint

* bump version to 0.6.41

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# and
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/build_package.yml

@@ -21,9 +21,9 @@ jobs:
         os: [ubuntu-latest, windows-latest]
         python-version: ["3.9"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Poetry

.github/workflows/codeql.yml

@@ -1,14 +1,3 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
 name: "CodeQL"
 
 on:
@@ -28,54 +17,25 @@ jobs:
     #   - https://gh.io/supported-runners-and-hardware-resources
     #   - https://gh.io/using-larger-runners
     # Consider using larger runners for possible analysis time improvements.
-    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
-    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    runs-on: "ubuntu-latest"
+    timeout-minutes: 360
     permissions:
       actions: read
       contents: read
       security-events: write
 
-    strategy:
-      fail-fast: false
-      matrix:
-        language: ["python"]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' ]
-        # Use only 'java' to analyze code written in Java, Kotlin or both
-        # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both
-        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
-
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
-          languages: ${{ matrix.language }}
-          # If you wish to specify custom queries, you can do so here or in a config file.
-          # By default, queries listed here will override any specified in a config file.
-          # Prefix the list here with "+" to use these queries and those in the config file.
-
-          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-          # queries: security-extended,security-and-quality
-
-      # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
-      # If this step fails, then you should remove it and run the build manually (see below)
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-
-      #   If the Autobuild fails above, remove it and uncomment the following three lines.
-      #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
-
-      # - run: |
-      #     echo "Run, Build Application using script"
-      #     ./location_of_script_within_repo/buildscript.sh
+          languages: python
+          dependency-caching: true
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
-          category: "/language:${{matrix.language}}"
+          category: "/language:python"

.github/workflows/lint.yml

@@ -18,11 +18,11 @@ jobs:
       matrix:
         python-version: ["3.9"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}
       - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Poetry

.github/workflows/publish_release.yml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
@@ -39,10 +39,18 @@ jobs:
           pypi_token: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
           poetry_install_options: "--without dev"
 
+      - name: Wait for PyPI to update
+        run: |
+          sleep 120
+
+      - name: Update llama-parse lock file
+        run: |
+          cd llama_parse && poetry lock
+
       - name: Build and publish llama-parse
         uses: JRubics/poetry-publish@v2.1
         with:
-          working_directory: "llama_parse"
+          package_directory: "./llama_parse"
           pypi_token: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
           poetry_install_options: "--without dev"
 

.github/workflows/unit_test.yml

@@ -19,11 +19,11 @@ jobs:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Poetry

README.md

@@ -10,7 +10,7 @@ This includes:
 
 - [LlamaParse](./parse.md) - A GenAI-native document parser that can parse complex document data for any downstream LLM use case (Agents, RAG, data processing, etc.).
 - [LlamaReport (beta/invite-only)](./report.md) - A prebuilt agentic report builder that can be used to build reports from a variety of data sources.
-- [LlamaExtract (beta/invite-only)](./extract.md) - A prebuilt agentic data extractor that can be used to transform data into a structured JSON representation.
+- [LlamaExtract](./extract.md) - A prebuilt agentic data extractor that can be used to transform data into a structured JSON representation.
 
 ## Getting Started
 
@@ -36,7 +36,26 @@ See the quickstart guides for each service for more information:
 
 - [LlamaParse](./parse.md)
 - [LlamaReport (beta/invite-only)](./report.md)
-- [LlamaExtract (beta/invite-only)](./extract.md)
+- [LlamaExtract](./extract.md)
+
+## Switch to EU SaaS 🇪🇺
+
+If you are interested in using LlamaCloud services in the EU, you can adjust your base URL to `https://api.cloud.eu.llamaindex.ai`.
+
+You can also create your API key in the EU region [here](https://cloud.eu.llamaindex.ai).
+
+```python
+from llama_cloud_services import (
+    LlamaParse,
+    LlamaReport,
+    LlamaExtract,
+    EU_BASE_URL,
+)
+
+parser = LlamaParse(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
+report = LlamaReport(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
+extract = LlamaExtract(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
+```
 
 ## Documentation
 

examples/extract/data/automotive_sector_analysis/modeling_assumptions.txt

@@ -0,0 +1,10 @@
+# Financial Modeling Assumptions
+Discount Rate: 8%
+Terminal Growth Rate: 2%
+Tax Rate: 25%
+Revenue Growth (Years 1-5): 10% per annum
+Revenue Growth (Years 6-10): 5% per annum
+Capital Expenditures as % of Revenue: 7%
+Working Capital Assumption: 3% of Revenue
+Depreciation Rate: 10% per annum
+Cost of Capital Assumption: 8%

examples/extract/data/insider_transactions/.gitignore

@@ -0,0 +1 @@
+sec_form_4_dump.json

examples/extract/extract_data_with_citations.ipynb

@@ -0,0 +1,440 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Extract Data from Financial Reports - with Citations and Reasoning\n",
+    "\n",
+    "Given complex files like financial reports, contracts, invoices etc, Llama Extract allows you to make use of an LLM to extract the information relevant to you, in a structured format.\n",
+    "\n",
+    "In this example, we'll be using [LlamaExtract](https://docs.cloud.llamaindex.ai/llamaextract/getting_started?utm_campaign=extract&utm_medium=recipe) to extract structured data from an SEC filing (specifically, the filing by Nvidia for fiscal year 2025).\n",
+    "\n",
+    "On top of simple data extraction, we'll ask our extraction agent to provide citations and reasoning for each extracted field. This allows us to:\n",
+    "- Confirm  the accuracy of the extracted field\n",
+    "- Understand the reasoning behind why the LLM extracted a given piece of information\n",
+    "- This last point allows us an opportunity to adjust the system prompt or field descriptions and improve on results where needed.\n",
+    "\n",
+    "\n",
+    "The example we go through below is also replicable within Llama Cloud as well, where you will also be able to pick between a number of pre-defined schemas, instead of building your own."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install llama-cloud-services"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Connect to Llama Cloud\n",
+    "\n",
+    "To get started, make sure you provide your [Llama Cloud](https://cloud.llamaindex.ai?utm_campaign=extract&utm_medium=recipe) API key."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Enter your Llama Cloud API Key: ··········\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "from getpass import getpass\n",
+    "\n",
+    "if \"LLAMA_CLOUD_API_KEY\" not in os.environ:\n",
+    "    os.environ[\"LLAMA_CLOUD_API_KEY\"] = getpass(\"Enter your Llama Cloud API Key: \")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Extract Data with Llama Extract Agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "No project_id provided, fetching default project.\n"
+     ]
+    }
+   ],
+   "source": [
+    "from llama_cloud_services import LlamaExtract\n",
+    "\n",
+    "# Optionally, provide your project id, if not, it will use the 'Default' project\n",
+    "llama_extract = LlamaExtract()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Provide Your Custom Schema\n",
+    "\n",
+    "When using LlamaExtract via the API, you provide your own schema that describes what you want extracted from files and data provided to your agent. Here, we are essentially building an SEC filings extraction agent."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pydantic import BaseModel, Field\n",
+    "from enum import Enum\n",
+    "\n",
+    "\n",
+    "class FilingType(str, Enum):\n",
+    "    ten_k = \"10 K\"\n",
+    "    ten_q = \"10-Q\"\n",
+    "    ten_ka = \"10-K/A\"\n",
+    "    ten_qa = \"10-Q/A\"\n",
+    "\n",
+    "\n",
+    "class FinancialReport(BaseModel):\n",
+    "    company_name: str = Field(description=\"The name of the company\")\n",
+    "    description: str = Field(\n",
+    "        description=\"Short description of the filing and what it contains\"\n",
+    "    )\n",
+    "    filing_type: FilingType = Field(description=\"Type of SEC filing\")\n",
+    "    filing_date: str = Field(description=\"Date when filing was submitted to SEC\")\n",
+    "    fiscal_year: int = Field(description=\"Fiscal year\")\n",
+    "    unit: str = Field(\n",
+    "        description=\"Unit of financial figures (thousands, millions, etc.)\"\n",
+    "    )\n",
+    "    revenue: int = Field(description=\"Total revenue for period\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Set Up Citations and Reasoning\n",
+    "\n",
+    "Optionally, we can set the `ExtractConfig` to extract citations for each field the agent extracts. These cications will cite the specific pages and sections of the file from which a given field was extractedd.\n",
+    "\n",
+    "By setting `use_reasoning` to True, we als ask the agent to do an additional reasoning step, explaining why a given field was extracted."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llama_cloud.types import ExtractConfig, ExtractMode\n",
+    "\n",
+    "config = ExtractConfig(\n",
+    "    use_reasoning=True, cite_sources=True, extraction_mode=ExtractMode.MULTIMODAL\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/usr/local/lib/python3.11/dist-packages/llama_cloud_services/extract/extract.py:127: ExperimentalWarning: `use_reasoning` is an experimental feature. Results will be available in the `extraction_metadata` field for the extraction run.\n",
+      "  warnings.warn(\n",
+      "/usr/local/lib/python3.11/dist-packages/llama_cloud_services/extract/extract.py:133: ExperimentalWarning: `cite_sources` is an experimental feature. This may greatly increase the size of the response, and slow down the extraction. Results will be available in the `extraction_metadata` field for the extraction run.\n",
+      "  warnings.warn(\n"
+     ]
+    }
+   ],
+   "source": [
+    "agent = llama_extract.create_agent(\n",
+    "    name=\"filing-parser\", data_schema=FinancialReport, config=config\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Demo Time - Download a PDF and Extract Data with Citations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "PDF downloaded successfully.\n"
+     ]
+    }
+   ],
+   "source": [
+    "import requests\n",
+    "\n",
+    "url = \"https://raw.githubusercontent.com/run-llama/llama_cloud_services/refs/heads/main/examples/extract/data/sec_filings/nvda_10k.pdf\"\n",
+    "\n",
+    "response = requests.get(url)\n",
+    "\n",
+    "if response.status_code == 200:\n",
+    "    with open(\"/content/nvda_10k.pdf\", \"wb\") as f:\n",
+    "        f.write(response.content)\n",
+    "    print(\"PDF downloaded successfully.\")\n",
+    "else:\n",
+    "    print(f\"Failed to download. Status code: {response.status_code}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Uploading files: 100%|██████████| 1/1 [00:00<00:00,  1.83it/s]\n",
+      "Creating extraction jobs: 100%|██████████| 1/1 [00:00<00:00,  4.38it/s]\n",
+      "Extracting files: 100%|██████████| 1/1 [02:03<00:00, 123.40s/it]\n"
+     ]
+    }
+   ],
+   "source": [
+    "filing_info = agent.extract(\"/content/nvda_10k.pdf\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'company_name': 'NVIDIA Corporation',\n",
+       " 'description': \"The filing provides a detailed overview of NVIDIA's business as a full-stack computing infrastructure company, discusses various technologies including digital avatars and autonomous vehicles, outlines numerous risk factors affecting operations such as supply chain issues and geopolitical tensions, and describes employee stock purchase plans and related compliance requirements.\",\n",
+       " 'filing_type': '10 K',\n",
+       " 'filing_date': 'February 26, 2025',\n",
+       " 'fiscal_year': 2025,\n",
+       " 'unit': 'millions',\n",
+       " 'revenue': 130497}"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "filing_info.data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Inspect Citations and Reasoning"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'field_metadata': {'company_name': {'reasoning': 'VERBATIM EXTRACTION',\n",
+       "   'citation': [{'page': 1, 'matching_text': 'NVIDIA CORPORATION'},\n",
+       "    {'page': 2, 'matching_text': 'NVIDIA Corporation'},\n",
+       "    {'page': 3,\n",
+       "     'matching_text': 'All references to \"NVIDIA,\" \"we,\" \"us,\" \"our,\" or the \"Company\" mean NVIDIA Corporation and its subsidiaries.'},\n",
+       "    {'page': 35,\n",
+       "     'matching_text': 'Comparison of 5 Year Cumulative Total Return* Among NVIDIA Corporation'},\n",
+       "    {'page': 49,\n",
+       "     'matching_text': 'To the Board of Directors and Shareholders of NVIDIA Corporation'},\n",
+       "    {'page': 90, 'matching_text': 'NVIDIA Corporation'},\n",
+       "    {'page': 119,\n",
+       "     'matching_text': '*\"Company\"* means NVIDIA Corporation, a Delaware corporation.'},\n",
+       "    {'page': 126,\n",
+       "     'matching_text': 'Annual Report on Form 10-K of NVIDIA Corporation'}]},\n",
+       "  'filing_type': {'reasoning': \"VERBATIM EXTRACTION from multiple sources confirming the filing type as '10 K'.\",\n",
+       "   'citation': [{'page': 1, 'matching_text': 'FORM 10-K'},\n",
+       "    {'page': 2, 'matching_text': 'Item 16. | Form 10-K Summary'},\n",
+       "    {'page': 3,\n",
+       "     'matching_text': 'This Annual Report on Form 10-K contains forward-looking statements...'},\n",
+       "    {'page': 13, 'matching_text': 'this Annual Report on Form 10-K'},\n",
+       "    {'page': 15, 'matching_text': 'this Annual Report on Form 10-K'},\n",
+       "    {'page': 32,\n",
+       "     'matching_text': 'Annual Report on Form 10-K, which information is hereby incorporated by reference.'},\n",
+       "    {'page': 36, 'matching_text': 'this Annual Report on Form 10-K'},\n",
+       "    {'page': 43,\n",
+       "     'matching_text': 'Annual Report on Form 10-K for additional information'},\n",
+       "    {'page': 45, 'matching_text': 'Annual Report on Form 10-K'},\n",
+       "    {'page': 46, 'matching_text': 'this Annual Report on Form 10-K'},\n",
+       "    {'page': 62, 'matching_text': 'Annual Report on Form 10-K'},\n",
+       "    {'page': 83,\n",
+       "     'matching_text': 'Restated Certificate of Incorporation | 10-K'},\n",
+       "    {'page': 84, 'matching_text': 'Item 16. Form 10-K Summary'},\n",
+       "    {'page': 126, 'matching_text': 'which appears in this Form 10-K'},\n",
+       "    {'page': 127, 'matching_text': 'Annual Report on Form 10-K'},\n",
+       "    {'page': 128, 'matching_text': 'Annual Report on Form 10-K'},\n",
+       "    {'page': 129, 'matching_text': \"The Company's Annual Report on Form 10-K\"},\n",
+       "    {'page': 130,\n",
+       "     'matching_text': \"The Company's Annual Report on Form 10-K for the year ended January 26, 2025\"}]},\n",
+       "  'fiscal_year': {'reasoning': 'The fiscal year ended January 26, 2025, indicates the fiscal year is 2025. Additionally, multiple references throughout the text confirm the fiscal year 2025 in various contexts.',\n",
+       "   'citation': [{'page': 1,\n",
+       "     'matching_text': 'For the fiscal year ended January 26, 2025'},\n",
+       "    {'page': 6,\n",
+       "     'matching_text': 'In fiscal year 2025, we launched the NVIDIA Blackwell architecture'},\n",
+       "    {'page': 12, 'matching_text': 'fiscal year 2025'},\n",
+       "    {'page': 17,\n",
+       "     'matching_text': 'our gross margins in the second quarter of fiscal year 2025 were negatively impacted'},\n",
+       "    {'page': 20,\n",
+       "     'matching_text': 'we generated 53% of our revenue in fiscal year 2025 from sales outside the United States.'},\n",
+       "    {'page': 23,\n",
+       "     'matching_text': 'For fiscal year 2025, an indirect customer which primarily purchases our products through system integrators...'},\n",
+       "    {'page': 33,\n",
+       "     'matching_text': 'In fiscal year 2025, we repurchased 310 million shares of our common stock for $34.0 billion.'},\n",
+       "    {'page': 37,\n",
+       "     'matching_text': 'Our Data Center revenue in China grew in fiscal year 2025.'},\n",
+       "    {'page': 44,\n",
+       "     'matching_text': 'Cash provided by operating activities increased in fiscal year 2025 compared to fiscal year 2024'},\n",
+       "    {'page': 57,\n",
+       "     'matching_text': 'Fiscal years 2025, 2024 and 2023 were all 52-week years.'},\n",
+       "    {'page': 65,\n",
+       "     'matching_text': 'Beginning in the second quarter of fiscal year 2025'},\n",
+       "    {'page': 69, 'matching_text': 'In the fourth quarter of fiscal year 2025'},\n",
+       "    {'page': 78,\n",
+       "     'matching_text': 'Depreciation and amortization expense attributable to our Compute and Networking segment for fiscal years 2025'},\n",
+       "    {'page': 129, 'matching_text': 'for the year ended January 26, 2025'}]},\n",
+       "  'description': {'reasoning': 'The extracted data combines multiple descriptions from the source text, ensuring no duplication while maintaining the order and context of the information. Each section of the filing is summarized to reflect the key points without losing the essence of the original text.',\n",
+       "   'citation': [{'page': 4,\n",
+       "     'matching_text': 'NVIDIA is now a full-stack computing infrastructure company with data-center-scale offerings that are reshaping industry.'},\n",
+       "    {'page': 8,\n",
+       "     'matching_text': 'a suite of technologies that help developers bring digital avatars to life with generative Al...autonomous vehicles, or AV, and electric vehicles, or EV, is revolutionizing the transportation industry...Our worldwide sales and marketing strategy is key to achieving our objective of providing markets with our high-performance and efficient computing platforms and software.'},\n",
+       "    {'page': 14, 'matching_text': 'Risk Factors Summary'},\n",
+       "    {'page': 16,\n",
+       "     'matching_text': 'Risks Related to Demand, Supply, and Manufacturing\\n\\nLong manufacturing lead times and uncertain supply and component availability...'},\n",
+       "    {'page': 18,\n",
+       "     'matching_text': 'cryptocurrency mining, on demand for our products. Volatility in the cryptocurrency market, including new compute technologies...'},\n",
+       "    {'page': 21,\n",
+       "     'matching_text': 'supply-chain attacks or other business disruptions. We cannot guarantee that third parties and infrastructure in our supply chain...'},\n",
+       "    {'page': 22,\n",
+       "     'matching_text': 'We are monitoring the impact of the geopolitical conflict in and around Israel on our operations... Climate change may have a long-term impact on our business.'},\n",
+       "    {'page': 25,\n",
+       "     'matching_text': 'We are subject to complex laws, rules, regulations, and political and other actions, including restrictions on the export of our products, which may adversely impact our business.'},\n",
+       "    {'page': 28,\n",
+       "     'matching_text': 'Our competitive position has been harmed by the existing export controls, and our competitive position and future results may be further harmed'},\n",
+       "    {'page': 29,\n",
+       "     'matching_text': 'restrictions imposed by the Chinese government on the duration of gaming activities and access to games may adversely affect our Gaming revenue'},\n",
+       "    {'page': 29,\n",
+       "     'matching_text': 'our business depends on our ability to receive consistent and reliable supply from our overseas partners, especially in Taiwan and South Korea'},\n",
+       "    {'page': 29,\n",
+       "     'matching_text': 'Increased scrutiny from shareholders, regulators and others regarding our corporate sustainability practices could result in additional costs'},\n",
+       "    {'page': 29,\n",
+       "     'matching_text': 'Concerns relating to the responsible use of new and evolving technologies, such as Al, in our products and services may result in reputational or financial harm'},\n",
+       "    {'page': 31,\n",
+       "     'matching_text': 'Data protection laws around the world are quickly changing and may be interpreted and applied in an increasingly stringent fashion...'}]},\n",
+       "  'filing_date': {'reasoning': 'The filing date is consistently mentioned as February 26, 2025 across multiple entries, making it the most reliable date for the filing.',\n",
+       "   'citation': [{'page': 51, 'matching_text': 'February 26, 2025'},\n",
+       "    {'page': 86, 'matching_text': 'on February 26, 2025.'},\n",
+       "    {'page': 87, 'matching_text': 'February 26, 2025'},\n",
+       "    {'page': 126, 'matching_text': 'our report dated February 26, 2025'},\n",
+       "    {'page': 127, 'matching_text': 'Date: February 26, 2025'},\n",
+       "    {'page': 128, 'matching_text': 'Date: February 26, 2025'},\n",
+       "    {'page': 129, 'matching_text': 'Date: February 26, 2025'},\n",
+       "    {'page': 130, 'matching_text': 'Date: February 26, 2025'}]},\n",
+       "  'unit': {'reasoning': \"The unit of financial figures is explicitly mentioned multiple times in the text as 'millions', including in table headers and notes. This is confirmed by various citations from pages 38, 42, 43, 52, 53, 54, 56, 65, 71, 72, 73, 75, 77, 79, 80, and 82.\",\n",
+       "   'citation': [{'page': 38,\n",
+       "     'matching_text': '($ in millions, except per share data)'},\n",
+       "    {'page': 42, 'matching_text': '($ in millions)'},\n",
+       "    {'page': 43, 'matching_text': '($ in millions)'},\n",
+       "    {'page': 52, 'matching_text': '(In millions, except per share data)'},\n",
+       "    {'page': 53,\n",
+       "     'matching_text': 'Consolidated Statements of Comprehensive Income (In millions)'},\n",
+       "    {'page': 54,\n",
+       "     'matching_text': 'Consolidated Balance Sheets (In millions, except par value)'},\n",
+       "    {'page': 55, 'matching_text': '(In millions, except per share data)'},\n",
+       "    {'page': 56,\n",
+       "     'matching_text': 'Consolidated Statements of Cash Flows (In millions)'},\n",
+       "    {'page': 65,\n",
+       "     'matching_text': 'Year Ended<br/>Jan 26, 2025<br/>(In millions, except per share data)'},\n",
+       "    {'page': 71, 'matching_text': '(In millions) | (In millions)'},\n",
+       "    {'page': 72, 'matching_text': '(In millions)'}]},\n",
+       "  'revenue': {'reasoning': 'The total revenue for fiscal year 2025 is extracted from multiple sources within the text, all confirming the same figure of $130,497 million. The revenue recognized for fiscal year 2025 is also noted as $4,607 million, which is a separate figure. However, the primary focus is on the total revenue figure, which is consistently cited.',\n",
+       "   'citation': [{'page': 38,\n",
+       "     'matching_text': 'Revenue for fiscal year 2025 was $130.5 billion'},\n",
+       "    {'page': 41,\n",
+       "     'matching_text': 'Total                | $ 130,497    | $ | 60,922'},\n",
+       "    {'page': 52, 'matching_text': 'Revenue | $ 130,497'},\n",
+       "    {'page': 78,\n",
+       "     'matching_text': 'Revenue | $ 116,193 | $ 14,304 | $ - | $ 130,497'},\n",
+       "    {'page': 79, 'matching_text': 'Total revenue | $ 130,497'},\n",
+       "    {'page': 80, 'matching_text': 'Total revenue              | $ 130,497'}]}},\n",
+       " 'usage': {'num_pages_extracted': 130,\n",
+       "  'num_document_tokens': 105932,\n",
+       "  'num_output_tokens': 31306}}"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "filing_info.extraction_metadata"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## What's Next?\n",
+    "\n",
+    "In this example, we built an Extraction Agent that is capable of citing it's sources from the document it's extracting data from, and reasoning about its reponse. To further customize and improve on the results, you can also try to customize the `system_prompt` in the `ExtractConfig`.\n",
+    "\n",
+    "#### Learn More\n",
+    "\n",
+    "- [LlamaExtract Documentation](https://docs.cloud.llamaindex.ai/llamaextract/getting_started)\n",
+    "- [Example Notebooks](https://github.com/run-llama/llama_cloud_services/tree/main/examples/extract)"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

examples/extract/lm317_structured_extraction.ipynb

@@ -0,0 +1,318 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1f6bd03d-1b8b-45a0-bc2c-5a13f1a5d8d3",
+   "metadata": {},
+   "source": [
+    "# LM317 Voltage Regulator Datasheet Structured Extraction\n",
+    "\n",
+    "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/extract/lm317_structured_extraction.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
+    "\n",
+    "This notebook demonstrates an agentic document workflow using LlamaExtract to process an LM317 voltage regulator datasheet. In this example, we define a structured extraction schema that converts key technical fields into standardized subfields. For instance, the output voltage is split into a minimum and maximum value with a defined unit, and we capture page citations for each extracted field.\n",
+    "\n",
+    "The target user is an electronics engineer at a component manufacturing company who needs to consolidate datasheet information into a standardized specification sheet for design and quality control.\n",
+    "\n",
+    "This approach reduces manual data entry, improves extraction accuracy and standardization, and provides traceability for each technical detail."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a3b8c8d5-ff3e-48ce-b0b8-29b6b1f517f8",
+   "metadata": {},
+   "source": [
+    "## Use Case Overview\n",
+    "\n",
+    "### Problem\n",
+    "Datasheets like that for the LM317 regulator are often distributed as PDFs containing multiple tables, charts, and complex textual descriptions. Engineers must manually extract technical details such as voltage ranges, dropout voltage, maximum current, input voltage range, and pin configurations. This process is error-prone and time-consuming.\n",
+    "\n",
+    "### Agent Workflow (Combination of Automation and Chat)\n",
+    "1. **Upload Datasheet:** The engineer uploads the LM317 datasheet PDF.  \n",
+    "2. **Structured Extraction:** An automated agent processes the PDF and extracts key technical details into structured fields (e.g., output voltage as a range with separate min/max values).\n",
+    "3. **Interactive Verification:** The engineer can query the agent (via chat) for further details or clarification (e.g., \"Show me the detailed pin configuration extraction\") and review the cited pages.\n",
+    "\n",
+    "**Value Delivered:**\n",
+    "- Up to 70% reduction in manual data extraction time.\n",
+    "- Increased accuracy and standardization with structured fields."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a704e843-54be-4969-842b-713584cb3c35",
+   "metadata": {},
+   "source": [
+    "## Setup and Download Data\n",
+    "\n",
+    "Download the [LM317 Datasheet](https://www.ti.com/lit/ds/symlink/lm317.pdf) and setup LlamaExtract."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e5b1f91-8785-44d4-a710-8be1b48b76de",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!mkdir -p data/lm317_structured_extraction\n",
+    "!wget https://www.ti.com/lit/ds/symlink/lm317.pdf -O data/lm317_structured_extraction/lm317.pdf"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f17b914a-00ed-4b63-8198-69fd7c4a7c62",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from dotenv import load_dotenv\n",
+    "from llama_cloud_services import LlamaExtract\n",
+    "from llama_cloud.core.api_error import ApiError\n",
+    "\n",
+    "# Load environment variables (ensure LLAMA_CLOUD_API_KEY is set in your .env file)\n",
+    "load_dotenv(override=True)\n",
+    "\n",
+    "# Initialize the LlamaExtract client\n",
+    "llama_extract = LlamaExtract(\n",
+    "    project_id=\"<project_id>\",\n",
+    "    organization_id=\"<organization_id>\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ed9f6e9a-96c8-4ee1-8b45-0b6a4f7dbbf1",
+   "metadata": {},
+   "source": [
+    "## Defining a Structured Extraction Schema\n",
+    "\n",
+    "We now define a rich Pydantic schema to extract technical specifications from the LM317 datasheet. In this schema:\n",
+    "\n",
+    "- The **output_voltage** and **input_voltage** fields are structured as ranges with separate minimum and maximum values and a unit.\n",
+    "- The **pin_configuration** field is structured to include a pin count and a descriptive layout.\n",
+    "- Additional technical fields (e.g., dropout voltage, max current) are captured as numbers.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4f7e9b44-5e69-4b30-9864-cd98f1e2a7d4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pydantic import BaseModel, Field\n",
+    "from typing import List\n",
+    "\n",
+    "\n",
+    "class VoltageRange(BaseModel):\n",
+    "    min_voltage: float = Field(..., description=\"Minimum voltage in volts\")\n",
+    "    max_voltage: float = Field(..., description=\"Maximum voltage in volts\")\n",
+    "    unit: str = Field(\"V\", description=\"Voltage unit\")\n",
+    "\n",
+    "\n",
+    "class PinConfiguration(BaseModel):\n",
+    "    pin_count: int = Field(..., description=\"Number of pins\")\n",
+    "    layout: str = Field(..., description=\"Detailed pin layout description\")\n",
+    "\n",
+    "\n",
+    "class LM317Spec(BaseModel):\n",
+    "    component_name: str = Field(..., description=\"Name of the component\")\n",
+    "    output_voltage: VoltageRange = Field(\n",
+    "        ..., description=\"Output voltage range specification\"\n",
+    "    )\n",
+    "    dropout_voltage: float = Field(..., description=\"Dropout voltage in volts\")\n",
+    "    max_current: float = Field(..., description=\"Maximum current rating in amperes\")\n",
+    "    input_voltage: VoltageRange = Field(\n",
+    "        ..., description=\"Input voltage range specification\"\n",
+    "    )\n",
+    "    pin_configuration: PinConfiguration = Field(\n",
+    "        ..., description=\"Pin configuration details\"\n",
+    "    )\n",
+    "    features: List[str] = Field([], description=\"List of additional technical features\")\n",
+    "\n",
+    "\n",
+    "class LM317Schema(BaseModel):\n",
+    "    specs: List[LM317Spec] = Field(\n",
+    "        ..., description=\"List of extracted LM317 technical specifications\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e0508e38-35be-446c-afe7-129e39553281",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "try:\n",
+    "    existing_agent = llama_extract.get_agent(name=\"lm317-datasheet\")\n",
+    "    if existing_agent:\n",
+    "        llama_extract.delete_agent(existing_agent.id)\n",
+    "except ApiError as e:\n",
+    "    if e.status_code == 404:\n",
+    "        pass\n",
+    "    else:\n",
+    "        raise"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bb197dfd-dd37-459e-8953-cc1b12f25bdd",
+   "metadata": {},
+   "source": [
+    "Here we use our balanced extraction mode."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e3defc0a-c685-4fbd-bbb1-1270f1442e72",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llama_cloud import ExtractConfig\n",
+    "\n",
+    "extract_config = ExtractConfig(\n",
+    "    extraction_mode=\"BALANCED\",\n",
+    ")\n",
+    "\n",
+    "agent = llama_extract.create_agent(\n",
+    "    name=\"lm317-datasheet\", data_schema=LM317Schema, config=extract_config\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c0a0f9f9-2ef3-4a38-bd74-68d2c2e9e2d8",
+   "metadata": {},
+   "source": [
+    "## Extracting Information from the LM317 Datasheet\n",
+    "\n",
+    "For this demonstration, please download a publicly available LM317 voltage regulator datasheet (for example, from Texas Instruments) and save it as `lm317.pdf` in the `./data` directory. Then run the cell below to extract the structured technical specifications."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c58e8b7a-8f9b-46f3-8f72-3c2f96b49e8f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Uploading files: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:01<00:00,  1.08s/it]\n",
+      "Creating extraction jobs: 100%|████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  1.96it/s]\n",
+      "Extracting files: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [01:27<00:00, 87.38s/it]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Path to the LM317 datasheet PDF\n",
+    "lm317_pdf = \"./data/lm317_structured_extraction/lm317.pdf\"\n",
+    "\n",
+    "# Extract structured technical specifications from the datasheet\n",
+    "lm317_extract = agent.extract(lm317_pdf)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1a2e2e44-6c48-4a38-a6de-5f2f3c7d4d8b",
+   "metadata": {},
+   "source": [
+    "## Assessing the Extraction Results\n",
+    "\n",
+    "The output will be a consolidated list of LM317 technical specifications. For each entry, you should see structured fields including:\n",
+    "\n",
+    "- **component_name**\n",
+    "- **output_voltage** as a range (with separate `min_voltage` and `max_voltage` plus `unit`)\n",
+    "- **dropout_voltage** and **max_current** as numbers\n",
+    "- **input_voltage** as a structured range\n",
+    "- **pin_configuration** with a `pin_count` and `layout`\n",
+    "- **features** (if available)\n",
+    "\n",
+    "This structured approach makes it easier to standardize the information for downstream integration and verification. Engineers can click on the cited page numbers (in a UI that supports it) to validate the extraction."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fb2abc44-7c9b-4b19-958e-d0d7b390ae57",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'specs': [{'component_name': 'LM317',\n",
+       "   'output_voltage': {'min_voltage': 1.25, 'max_voltage': 37.0, 'unit': 'V'},\n",
+       "   'dropout_voltage': 0.0,\n",
+       "   'max_current': 1.5,\n",
+       "   'input_voltage': {'min_voltage': 4.25, 'max_voltage': 40.0, 'unit': 'V'},\n",
+       "   'pin_configuration': {'pin_count': 3,\n",
+       "    'layout': '1: ADJUST, 2: OUTPUT, 3: INPUT'},\n",
+       "   'features': ['Output voltage range adjustable from 1.25 V to 37 V',\n",
+       "    'Output current greater than 1.5 A',\n",
+       "    'Internal short-circuit current limiting',\n",
+       "    'Thermal overload protection',\n",
+       "    'Output safe-area compensation']}]}"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Display the extraction results\n",
+    "lm317_extract.data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c7a2a523-095e-40bf-b713-f509c13a7747",
+   "metadata": {},
+   "source": [
+    "You can also see the output result in the UI."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dc22dfa5-b667-4fb0-8dbe-24e401b12389",
+   "metadata": {},
+   "source": [
+    "![](data/lm317_structured_extraction/lm317_extraction.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e0e0c12a-9f89-4bb3-b40d-3e9f7c6d2fef",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "This notebook demonstrated how to use LlamaExtract with a structured extraction schema for the LM317 voltage regulator datasheet. By defining detailed subfields (such as splitting voltage ranges into minimum and maximum values, and structuring the pin configuration), we ensure that the extracted data is standardized and traceable through page citations. This approach minimizes manual effort and improves accuracy, providing a robust example of an agentic document workflow for technical documentation processing.\n",
+    "\n",
+    "Feel free to modify or extend the schema to capture additional technical details or to suit your own use cases."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "llama_parse",
+   "language": "python",
+   "name": "llama_parse"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/extract/solar_panel_e2e_comparison.ipynb

@@ -0,0 +1,450 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "00f6713b-2a32-4f8f-80e5-9a7d9b6e3b90",
+   "metadata": {},
+   "source": [
+    "# Solar Panel Datasheet Comparison Workflow\n",
+    "\n",
+    "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/extract/solar_panel_e2e_comparison.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
+    "\n",
+    "\n",
+    "This notebook demonstrates an end‑to‑end agentic workflow using LlamaExtract and the LlamaIndex event‑driven workflow framework. In this workflow, we:\n",
+    "\n",
+    "1. **Extract** structured technical specifications from a solar panel datasheet (e.g. a PDF downloaded from a vendor).\n",
+    "2. **Load** design requirements (provided as a text blob) for a lab‑grade solar panel.\n",
+    "3. **Generate** a detailed comparison report by triggering an event that injects both the extracted data and the requirements into an LLM prompt.\n",
+    "\n",
+    "The workflow is designed for renewable energy engineers who need to quickly validate that a solar panel meets specific design criteria.\n",
+    "\n",
+    "The following notebook uses the event‑driven syntax (with custom events, steps, and a workflow class) adapted from the technical datasheet and contract review examples."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36d8e34e-ed98-46ac-b744-1642f6e253d5",
+   "metadata": {},
+   "source": [
+    "## Setup and Load Data\n",
+    "\n",
+    "We download the [Honey M TSM-DE08M.08(II) datasheet](https://static.trinasolar.com/sites/default/files/EU_Datasheet_HoneyM_DE08M.08%28II%29_2021_A.pdf) as a PDF.\n",
+    "\n",
+    "**NOTE**: The design requirements are already stored in `data/solar_panel_e2e_comparison/design_reqs.txt`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1de7b1b3-c285-492c-8b2e-b37974b4fc63",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "--2025-04-01 14:47:56--  https://static.trinasolar.com/sites/default/files/EU_Datasheet_HoneyM_DE08M.08%28II%29_2021_A.pdf\n",
+      "Resolving static.trinasolar.com (static.trinasolar.com)... 47.246.23.232, 47.246.23.234, 47.246.23.227, ...\n",
+      "Connecting to static.trinasolar.com (static.trinasolar.com)|47.246.23.232|:443... connected.\n",
+      "WARNING: cannot verify static.trinasolar.com's certificate, issued by ‘CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1,O=DigiCert Inc,C=US’:\n",
+      "  Unable to locally verify the issuer's authority.\n",
+      "HTTP request sent, awaiting response... 200 OK\n",
+      "Length: 1888183 (1.8M) [application/pdf]\n",
+      "Saving to: ‘data/solar_panel_e2e_comparison/datasheet.pdf’\n",
+      "\n",
+      "data/solar_panel_e2 100%[===================>]   1.80M  7.47MB/s    in 0.2s    \n",
+      "\n",
+      "2025-04-01 14:47:56 (7.47 MB/s) - ‘data/solar_panel_e2e_comparison/datasheet.pdf’ saved [1888183/1888183]\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "!wget https://static.trinasolar.com/sites/default/files/EU_Datasheet_HoneyM_DE08M.08%28II%29_2021_A.pdf -O data/solar_panel_e2e_comparison/datasheet.pdf --no-check-certificate"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "89d2f4c9-f785-424d-a409-3381796c457c",
+   "metadata": {},
+   "source": [
+    "## Define the Structured Extraction Schema\n",
+    "\n",
+    "We define a new, rich schema called `SolarPanelSchema` to capture key technical details from the datasheet. This schema includes:\n",
+    "\n",
+    "- **PowerRange:** Structured as minimum and maximum power output (in Watts).\n",
+    "- **SolarPanelSpec:** Includes module name, power output range, maximum efficiency, certifications, and a mapping of page citations.\n",
+    "\n",
+    "This schema replaces the earlier LM317 schema and will be used when creating our extraction agent."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bfb40d48-36e0-4b1c-97a1-32a1704c582b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pydantic import BaseModel, Field\n",
+    "from typing import List\n",
+    "\n",
+    "\n",
+    "class PowerRange(BaseModel):\n",
+    "    min_power: float = Field(..., description=\"Minimum power output in Watts\")\n",
+    "    max_power: float = Field(..., description=\"Maximum power output in Watts\")\n",
+    "    unit: str = Field(\"W\", description=\"Power unit\")\n",
+    "\n",
+    "\n",
+    "class SolarPanelSpec(BaseModel):\n",
+    "    module_name: str = Field(..., description=\"Name or model of the solar panel module\")\n",
+    "    power_output: PowerRange = Field(..., description=\"Power output range\")\n",
+    "    maximum_efficiency: float = Field(\n",
+    "        ..., description=\"Maximum module efficiency in percentage\"\n",
+    "    )\n",
+    "    temperature_coefficient: float = Field(\n",
+    "        ..., description=\"Temperature coefficient in %/°C\"\n",
+    "    )\n",
+    "    certifications: List[str] = Field([], description=\"List of certifications\")\n",
+    "    page_citations: dict = Field(\n",
+    "        ..., description=\"Mapping of each extracted field to its page numbers\"\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "class SolarPanelSchema(BaseModel):\n",
+    "    specs: List[SolarPanelSpec] = Field(\n",
+    "        ..., description=\"List of extracted solar panel specifications\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "19dc309e-7cec-43c1-8f6c-72e14df58f8f",
+   "metadata": {},
+   "source": [
+    "## Initialize Extraction Agent\n",
+    "\n",
+    "Here we initialize our extraction agent that will be responsible for extracting the schema from the solar panel datasheet."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c9d9f4a2-2e14-493d-8a7e-d01159d38b8f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from dotenv import load_dotenv\n",
+    "from llama_cloud_services import LlamaExtract\n",
+    "from llama_cloud.core.api_error import ApiError\n",
+    "from llama_cloud import ExtractConfig\n",
+    "\n",
+    "# Initialize the LlamaExtract client\n",
+    "llama_extract = LlamaExtract(\n",
+    "    project_id=\"2fef999e-1073-40e6-aeb3-1f3c0e64d99b\",\n",
+    "    organization_id=\"43b88c8f-e488-46f6-9013-698e3d2e374a\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec0eb2a7-6e02-45da-a6af-227e2f7c81f2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "try:\n",
+    "    existing_agent = llama_extract.get_agent(name=\"solar-panel-datasheet\")\n",
+    "    if existing_agent:\n",
+    "        llama_extract.delete_agent(existing_agent.id)\n",
+    "except ApiError as e:\n",
+    "    if e.status_code == 404:\n",
+    "        pass\n",
+    "    else:\n",
+    "        raise\n",
+    "\n",
+    "extract_config = ExtractConfig(\n",
+    "    extraction_mode=\"BALANCED\",\n",
+    ")\n",
+    "\n",
+    "agent = llama_extract.create_agent(\n",
+    "    name=\"solar-panel-datasheet\", data_schema=SolarPanelSchema, config=extract_config\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b4d7bb60-0456-4a2d-8d48-14f9bb3e71d2",
+   "metadata": {},
+   "source": [
+    "## Workflow Overview\n",
+    "\n",
+    "The workflow consists of four main steps:\n",
+    "\n",
+    "1. **parse_datasheet:** Reads the solar panel datasheet (PDF) and converts its content into text (with page citations).\n",
+    "2. **load_requirements:** Loads the design requirements (as a text blob) that will be injected into the prompt.\n",
+    "3. **generate_comparison_report:** Constructs a prompt using the extracted datasheet content and design requirements and triggers the LLM to generate a comparison report.\n",
+    "4. **output_result:** Logs and returns the final report as the workflow’s result.\n",
+    "\n",
+    "Each step is implemented as an asynchronous function decorated with `@step`, and the workflow is built by subclassing `Workflow`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7c482e3a-66b4-4e1b-8d2d-9a9c6b3967f3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llama_index.core.workflow import (\n",
+    "    Event,\n",
+    "    StartEvent,\n",
+    "    StopEvent,\n",
+    "    Context,\n",
+    "    Workflow,\n",
+    "    step,\n",
+    ")\n",
+    "from llama_index.llms.openai import OpenAI\n",
+    "from llama_index.core.prompts import ChatPromptTemplate\n",
+    "from llama_cloud_services import LlamaExtract\n",
+    "from llama_cloud.core.api_error import ApiError\n",
+    "from pydantic import BaseModel, Field\n",
+    "from typing import List\n",
+    "\n",
+    "\n",
+    "# Define output schema for the comparison report (for reference)\n",
+    "class ComparisonReportOutput(BaseModel):\n",
+    "    component_name: str = Field(\n",
+    "        ..., description=\"The name of the component being evaluated.\"\n",
+    "    )\n",
+    "    meets_requirements: bool = Field(\n",
+    "        ...,\n",
+    "        description=\"Overall indicator of whether the component meets the design criteria.\",\n",
+    "    )\n",
+    "    summary: str = Field(..., description=\"A brief summary of the evaluation results.\")\n",
+    "    details: dict = Field(\n",
+    "        ..., description=\"Detailed comparisons for each key parameter.\"\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "# Define custom events\n",
+    "\n",
+    "\n",
+    "class DatasheetParseEvent(Event):\n",
+    "    datasheet_content: dict\n",
+    "\n",
+    "\n",
+    "class RequirementsLoadEvent(Event):\n",
+    "    requirements_text: str\n",
+    "\n",
+    "\n",
+    "class ComparisonReportEvent(Event):\n",
+    "    report: ComparisonReportOutput\n",
+    "\n",
+    "\n",
+    "class LogEvent(Event):\n",
+    "    msg: str\n",
+    "    delta: bool = False\n",
+    "\n",
+    "\n",
+    "# For our demonstration, we assume that LlamaExtract is used to parse the datasheet into text.\n",
+    "# We'll also use OpenAI (via LlamaIndex) as our LLM for generating the report.\n",
+    "\n",
+    "llm = OpenAI(model=\"gpt-4o\")  # or your preferred model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "67a0c391-c7f5-4b93-8d6b-9e31b2d7a817",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class SolarPanelComparisonWorkflow(Workflow):\n",
+    "    \"\"\"\n",
+    "    Workflow to extract data from a solar panel datasheet and generate a comparison report\n",
+    "    against provided design requirements.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    def __init__(self, agent: LlamaExtract, requirements_path: str, **kwargs):\n",
+    "        super().__init__(**kwargs)\n",
+    "        self.agent = agent\n",
+    "        # Load design requirements from file as a text blob\n",
+    "        with open(requirements_path, \"r\") as f:\n",
+    "            self.requirements_text = f.read()\n",
+    "\n",
+    "    @step\n",
+    "    async def parse_datasheet(\n",
+    "        self, ctx: Context, ev: StartEvent\n",
+    "    ) -> DatasheetParseEvent:\n",
+    "        # datasheet_path is provided in the StartEvent\n",
+    "        datasheet_path = (\n",
+    "            ev.datasheet_path\n",
+    "        )  # e.g., \"./data/solar_panel_comparison/datasheet.pdf\"\n",
+    "        extraction_result = await self.agent.aextract(datasheet_path)\n",
+    "        datasheet_dict = (\n",
+    "            extraction_result.data\n",
+    "        )  # assumed to be a string with page citations\n",
+    "        await ctx.set(\"datasheet_content\", datasheet_dict)\n",
+    "        ctx.write_event_to_stream(LogEvent(msg=\"Datasheet parsed successfully.\"))\n",
+    "        return DatasheetParseEvent(datasheet_content=datasheet_dict)\n",
+    "\n",
+    "    @step\n",
+    "    async def load_requirements(\n",
+    "        self, ctx: Context, ev: DatasheetParseEvent\n",
+    "    ) -> RequirementsLoadEvent:\n",
+    "        # Use the pre-loaded requirements text from __init__\n",
+    "        req_text = self.requirements_text\n",
+    "        ctx.write_event_to_stream(LogEvent(msg=\"Design requirements loaded.\"))\n",
+    "        return RequirementsLoadEvent(requirements_text=req_text)\n",
+    "\n",
+    "    @step\n",
+    "    async def generate_comparison_report(\n",
+    "        self, ctx: Context, ev: RequirementsLoadEvent\n",
+    "    ) -> StopEvent:\n",
+    "        # Build a prompt that injects both the extracted datasheet content and the design requirements\n",
+    "        datasheet_content = await ctx.get(\"datasheet_content\")\n",
+    "        prompt_str = \"\"\"\n",
+    "You are an expert renewable energy engineer.\n",
+    "\n",
+    "Compare the following solar panel datasheet information with the design requirements.\n",
+    "\n",
+    "Design Requirements:\n",
+    "{requirements_text}\n",
+    "\n",
+    "Extracted Datasheet Information:\n",
+    "{datasheet_content}\n",
+    "\n",
+    "Generate a detailed comparison report in JSON format with the following schema:\n",
+    "  - component_name: string\n",
+    "  - meets_requirements: boolean\n",
+    "  - summary: string\n",
+    "  - details: dictionary of comparisons for each parameter\n",
+    "\n",
+    "For each parameter (Maximum Power, Open-Circuit Voltage, Short-Circuit Current, Efficiency, Temperature Coefficient),\n",
+    "indicate PASS or FAIL and provide brief explanations and recommendations.\n",
+    "\"\"\"\n",
+    "\n",
+    "        # extract from contract\n",
+    "        prompt = ChatPromptTemplate.from_messages([(\"user\", prompt_str)])\n",
+    "\n",
+    "        # Call the LLM to generate the report using the prompt\n",
+    "        report_output = await llm.astructured_predict(\n",
+    "            ComparisonReportOutput,\n",
+    "            prompt,\n",
+    "            requirements_text=ev.requirements_text,\n",
+    "            datasheet_content=str(datasheet_content),\n",
+    "        )\n",
+    "        ctx.write_event_to_stream(LogEvent(msg=\"Comparison report generated.\"))\n",
+    "        return StopEvent(\n",
+    "            result={\"report\": report_output, \"datasheet_content\": datasheet_content}\n",
+    "        )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d205f532-1a11-4a48-b5a8-87a7f85e9ce7",
+   "metadata": {},
+   "source": [
+    "## Running the Workflow\n",
+    "\n",
+    "Below, we instantiate and run the workflow. We inject the design requirements as a text blob (no custom code to load) and pass the path to the solar panel datasheet (the HoneyM datasheet from Trina).\n",
+    "\n",
+    "The design requirements are:\n",
+    "\n",
+    "```\n",
+    "Solar Panel Design Requirements:\n",
+    "- Power Output Range: ≥ 350 W\n",
+    "- Maximum Efficiency: ≥ 18%\n",
+    "- Certifications: Must include IEC61215 and UL1703\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6b24fa61-a2f5-4ebb-84eb-1c9b48683b1b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import nest_asyncio\n",
+    "\n",
+    "nest_asyncio.apply()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "be3ebad5-1f70-4671-a2ec-17bf9e4d788f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Path to design requirements file (e.g., a text file with design criteria for solar panels)\n",
+    "requirements_path = \"./data/solar_panel_e2e_comparison/design_reqs.txt\"\n",
+    "\n",
+    "# Instantiate the workflow\n",
+    "workflow = SolarPanelComparisonWorkflow(\n",
+    "    agent=agent, requirements_path=requirements_path, verbose=True, timeout=120\n",
+    ")\n",
+    "\n",
+    "# Run the workflow; pass the datasheet path in the StartEvent\n",
+    "result = await workflow.run(\n",
+    "    datasheet_path=\"./data/solar_panel_e2e_comparison/datasheet.pdf\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e1e61f1e-8701-4acc-8f99-cc89d8aae535",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "********Final Comparison Report:********\n",
+      "\n",
+      "{\n",
+      "    \"component_name\": \"TSM-DE08M.08(II)\",\n",
+      "    \"meets_requirements\": true,\n",
+      "    \"summary\": \"The solar panel TSM-DE08M.08(II) meets all the design requirements, making it a suitable choice for the intended application.\",\n",
+      "    \"details\": {\n",
+      "        \"Maximum Power Output\": \"PASS - The panel's power output ranges from 360 W to 385 W, exceeding the minimum requirement of 350 W.\",\n",
+      "        \"Open-Circuit Voltage\": \"PASS - The datasheet does not specify Voc, but the panel meets other critical requirements. Verification of Voc is recommended.\",\n",
+      "        \"Short-Circuit Current\": \"PASS - The datasheet does not specify Isc, but the panel meets other critical requirements. Verification of Isc is recommended.\",\n",
+      "        \"Efficiency\": \"PASS - The panel's efficiency is 21.0%, which is above the required 18%.\",\n",
+      "        \"Temperature Coefficient\": \"PASS - The temperature coefficient is -0.34%/°C, which is better than the maximum allowable -0.5%/°C.\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"\\n********Final Comparison Report:********\\n\")\n",
+    "print(result[\"report\"].model_dump_json(indent=4))\n",
+    "# print(\"\\n********Datasheet Content:********\\n\", result[\"datasheet_content\"])"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "llama_parse",
+   "language": "python",
+   "name": "llama_parse"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/parse/demo_astradb.ipynb

@@ -1,295 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Using llama-parse with AstraDB"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "In this notebook, we show a basic RAG-style example that uses `llama-parse` to parse a PDF document, store the corresponding document into a vector store (`AstraDB`) and finally, perform some basic queries against that store. The notebook is modeled after the quick start notebooks and hence is meant as a way of getting started with `llama-parse`, backed by a vector database."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Requirements"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# First, install the required dependencies\n",
-    "%pip install --quiet llama-index llama-parse llama-index-vector-stores-astra-db llama-index-llms-openai"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Configuration"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import os\n",
-    "import openai\n",
-    "\n",
-    "from getpass import getpass\n",
-    "\n",
-    "# Get all required API keys and parameters\n",
-    "llama_cloud_api_key = getpass(\"Enter your Llama Index Cloud API Key: \")\n",
-    "api_endpoint = input(\"Enter your Astra DB API Endpoint: \")\n",
-    "token = getpass(\"Enter your Astra DB Token: \")\n",
-    "namespace = (\n",
-    "    input(\"Enter your Astra DB namespace (optional, must exist on Astra): \") or None\n",
-    ")\n",
-    "openai_api_key = getpass(\"Enter your OpenAI API Key: \")\n",
-    "\n",
-    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = llama_cloud_api_key\n",
-    "openai.api_key = openai_api_key"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# llama-parse is async-first, running the sync code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Using llama-parse to parse a PDF"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Download complete.\n"
-     ]
-    }
-   ],
-   "source": [
-    "# Grab a PDF from Arxiv for indexing\n",
-    "import requests\n",
-    "\n",
-    "# The URL of the file you want to download\n",
-    "url = \"https://arxiv.org/pdf/1706.03762.pdf\"\n",
-    "# The local path where you want to save the file\n",
-    "file_path = \"./attention.pdf\"\n",
-    "\n",
-    "# Perform the HTTP request\n",
-    "response = requests.get(url)\n",
-    "\n",
-    "# Check if the request was successful\n",
-    "if response.status_code == 200:\n",
-    "    # Open the file in binary write mode and save the content\n",
-    "    with open(file_path, \"wb\") as file:\n",
-    "        file.write(response.content)\n",
-    "    print(\"Download complete.\")\n",
-    "else:\n",
-    "    print(\"Error downloading the file.\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Started parsing the file under job_id ce3909a7-54cf-438b-849a-fe9a903b0c71\n"
-     ]
-    }
-   ],
-   "source": [
-    "from llama_cloud_services import LlamaParse\n",
-    "\n",
-    "documents = LlamaParse(result_type=\"text\").load_data(file_path)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'rmer - model architecture.\\nThe Transformer follows this overall architecture using stacked self-attention and point-wise, fully\\nconnected layers for both the encoder and decoder, shown in the left and right halves of Figure 1,\\nrespectively.\\n3.1   Encoder and Decoder Stacks\\nEncoder:     The encoder is composed of a stack of N = 6 identical layers. Each layer has two\\nsub-layers. The first is a multi-head self-attention mechanism, and the second is a simple, position-\\nwise fully connected feed-forward network. We employ a residual connection [11] around each of\\nthe two sub-layers, followed by layer normalization [1]. That is, the output of each sub-layer is\\nLayerNorm(x + Sublayer(x)), where Sublayer(x) is the function implemented by the sub-layer\\nitself. To facilitate these residual connections, all sub-layers in the model, as well as the embedding\\nlayers, produce outputs of dimension dmodel = 512.\\nDecoder:    The decoder is also composed of a stack of N = 6 identical layers. In addition '"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "# Take a quick look at some of the parsed text from the document:\n",
-    "documents[0].get_content()[10000:11000]"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Storing into Astra DB"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.vector_stores.astra_db import AstraDBVectorStore\n",
-    "\n",
-    "astra_db_store = AstraDBVectorStore(\n",
-    "    token=token,\n",
-    "    api_endpoint=api_endpoint,\n",
-    "    namespace=namespace,\n",
-    "    collection_name=\"astra_v_table_llamaparse\",\n",
-    "    embedding_dimension=1536,\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.core.node_parser import SimpleNodeParser\n",
-    "\n",
-    "node_parser = SimpleNodeParser()\n",
-    "\n",
-    "nodes = node_parser.get_nodes_from_documents(documents)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.embeddings.openai import OpenAIEmbedding\n",
-    "from llama_index.core import VectorStoreIndex, StorageContext\n",
-    "\n",
-    "storage_context = StorageContext.from_defaults(vector_store=astra_db_store)\n",
-    "\n",
-    "index = VectorStoreIndex(\n",
-    "    nodes=nodes,\n",
-    "    storage_context=storage_context,\n",
-    "    embed_model=OpenAIEmbedding(api_key=openai_api_key),\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Simple RAG Example"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "query_engine = index.as_query_engine(similarity_top_k=15)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "***********New LlamaParse+ Basic Query Engine***********\n",
-      "Multi-Head Attention is also known as multi-headed self-attention.\n"
-     ]
-    }
-   ],
-   "source": [
-    "query = \"What is Multi-Head Attention also known as?\"\n",
-    "\n",
-    "response_1 = query_engine.query(query)\n",
-    "print(\"\\n***********New LlamaParse+ Basic Query Engine***********\")\n",
-    "print(response_1)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'We used beam search as described in the previous section, but no\\ncheckpoint averaging. We present these results in Table 3.\\nIn Table 3 rows (A), we vary the number of attention heads and the attention key and value dimensions,\\nkeeping the amount of computation constant, as described in Section 3.2.2. While single-head\\nattention is 0.9 BLEU worse than the best setting, quality also drops off with too many heads.\\nIn Table 3 rows (B), we observe that reducing the attention key size dk hurts model quality. This\\nsuggests that determining compatibility is not easy and that a more sophisticated compatibility\\nfunction than dot product may be beneficial. We further observe in rows (C) and (D) that, as expected,\\nbigger models are better, and dropout is very helpful in avoiding over-fitting. In row (E) we replace our\\nsinusoidal positional encoding with learned positional embeddings [9], and observe nearly identical\\nresults to the base model.\\n6.3    English Constituency Parsing\\nTo evaluate if the Transformer can generalize to other tasks we performed experiments on English\\nconstituency parsing. This task presents specific challenges: the output is subject to strong structural\\nconstraints and is significantly longer than the input. Furthermore, RNN sequence-to-sequence\\nmodels have not been able to attain state-of-the-art results in small-data regimes [37].\\nWe trained a 4-layer transformer with dmodel = 1024 on the Wall Street Journal (WSJ) portion of the\\nPenn Treebank [25], about 40K training sentences. We also trained it in a semi-supervised setting,\\nusing the larger high-confidence and BerkleyParser corpora from with approximately 17M sentences\\n[37]. We used a vocabulary of 16K tokens for the WSJ only setting and a vocabulary of 32K tokens\\nfor the semi-supervised setting.\\nWe performed only a small number of experiments to select the dropout, both attention and residual\\n(section 5.4), learning rates and beam size on the Section 22 development set, all other parameters\\nremained unchanged from the English-to-German base translation model. During inference, we\\n                                                             9\\n---\\nTable 4: The Transformer generalizes well to English constituency parsing (Results are on Section 23\\nof WSJ)\\n                          Parser                           Training             WSJ 23 F1\\n            Vinyals & Kaiser el al. (2014) [37]    WSJ only, discriminative         88.3\\n                 Petrov et al. (2006) [29]         WSJ only, discriminative         90.4\\n                   Zhu et al. (2013) [40]          WSJ only, discriminative         90.4\\n                   Dyer et al. (2016) [8]          WSJ only, discriminative         91.7\\n                  Transformer (4 layers)           WSJ only, discriminative         91.3\\n                   Zhu et al. (2013) [40]              semi-supervised              91.3\\n               Huang & Harper (2009) [14]              semi-supervised              91.3\\n               McClosky et al. (2006) [26]             semi-supervised              92.1\\n            Vinyals & Kaiser el al. (2014) [37]        semi-supervised              92.1\\n                  Transformer (4 layers)               semi-supervised              92.7\\n                 Luong et al. (2015) [23]                  multi-task               93.0\\n                   Dyer et al. (2016) [8]                  generative               93.3\\nincreased the maximum output length to input length + 300. We used a beam size of 21 and α = 0.3\\nfor both WSJ only and the semi-supervised setting.\\nOur results in Table 4 show that despite the lack of task-specific tuning our model performs sur-\\nprisingly well, yielding better results than all previously reported models with the exception of the\\nRecurrent Neural Network Grammar [8].\\nIn contrast to RNN sequence-to-sequence models [37], the Transformer outperforms the Berkeley-\\nParser [29] even when training only on the WSJ training set of 40K sentences.\\n7    Conclusion\\nIn this work, we presented the Transformer, the first sequence transduction model based entirely on\\nattention, replacing the recurrent layers most commonly used in encoder-decoder architectures with\\nmulti-headed self-attention.\\nFor translation tasks, the Transformer can be trained significantly faster than architectures based\\non recurrent or convolutional layers.'"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "# Take a look at one of the source nodes from the response\n",
-    "response_1.source_nodes[0].get_content()"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}

examples/parse/demo_basic.ipynb

@@ -13,32 +13,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install llama-index llama-parse"
+    "%pip install llama-index llama-cloud-services"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "--2024-02-02 11:10:10--  https://arxiv.org/pdf/1706.03762.pdf\n",
-      "Resolving arxiv.org (arxiv.org)... 151.101.131.42, 151.101.3.42, 151.101.67.42, ...\n",
-      "Connecting to arxiv.org (arxiv.org)|151.101.131.42|:443... connected.\n",
-      "HTTP request sent, awaiting response... 200 OK\n",
-      "Length: 2215244 (2.1M) [application/pdf]\n",
-      "Saving to: ‘./attention.pdf’\n",
-      "\n",
-      "./attention.pdf     100%[===================>]   2.11M  --.-KB/s    in 0.08s   \n",
-      "\n",
-      "2024-02-02 11:10:10 (25.9 MB/s) - ‘./attention.pdf’ saved [2215244/2215244]\n",
-      "\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "!wget \"https://arxiv.org/pdf/1706.03762.pdf\" -O \"./attention.pdf\""
    ]
@@ -49,11 +31,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# llama-parse is async-first, running the sync code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import os\n",
     "\n",
     "os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-...\""
@@ -68,14 +45,14 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Started parsing the file under job_id dd0b8e31-0c09-4497-b78a-cc1c92f1d6cf\n"
+      "Started parsing the file under job_id 79ae653c-4598-4bd0-ba6e-b3dab7eab57e\n"
      ]
     }
    ],
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "documents = LlamaParse(result_type=\"text\").load_data(\"./attention.pdf\")"
+    "result = await LlamaParse().aparse(\"./attention.pdf\")"
    ]
   },
   {
@@ -87,23 +64,62 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "ad\n",
+      "1   Introduction\n",
+      "Recurrent neural networks, long short-term memory [13] and gated recurrent [7] neural networks\n",
+      "in particular, have been firmly established as state of the art approaches in sequence modeling and\n",
+      "transduction problems such as language modeling and machine translation [35, 2, 5]. Numerous\n",
+      "efforts have since continued to push the boundaries of recurrent language models and encoder-decoder\n",
+      "architectures [38, 24, 15].\n",
+      "Recurrent models typically factor computation along the symbol positions of the input and output\n",
+      "sequences. Aligning the positions to steps in computation time, they generate a sequence of hidden\n",
+      "states ht, as a function of the previous hidden state ht−1 and the input for position t. This inherently\n",
+      "sequential nature precludes parallelization within training examples, which becomes critical at longer\n",
+      "sequence lengths, as memory constraints limit batching across examples. Recent work has achieved\n",
+      "significant improvements in computational efficiency through factorization tricks [21] and conditional\n",
+      "computation [32], while also improving model performance in case of the latter. The fundamental\n",
+      "constraint of sequential computation, however, remains.\n",
+      "Attention mechanisms have become an integral part of compelling sequence modeling and transduc-\n",
+      "tion models in various tasks, allowing modeling of dependencies without regard to their distance in\n",
+      "the input or output sequences [2, 19]. In all but a few cases [27], however, such attention mechanisms\n",
+      "are used in conjunction with a recurrent network.\n",
+      "In this work we propose the Transformer, a model architecture eschewing recurrence and instead\n",
       "relying entirely on an attention mechanism to draw global dependencies between input and output.\n",
       "The Transformer allows for significantly more parallelization and can reach a new state of the art in\n",
       "translation quality after being trained for as little as twelve hours on eight P100 GPUs.\n",
-      "2    Background\n",
+      "2   Background\n",
       "The goal of reducing sequential computation also forms the foundation of the Extended Neural GPU\n",
       "[16], ByteNet [18] and ConvS2S [9], all of which use convolutional neural networks as basic building\n",
       "block, computing hidden representations in parallel for all input and output positions. In these models,\n",
       "the number of operations required to relate signals from two arbitrary input or output positions grows\n",
       "in the distance between positions, linearly for ConvS2S and logarithmically for ByteNet. This makes\n",
       "it more difficult to learn dependencies between distant positions [12]. In the Transformer this is\n",
-      "reduced to a constant number of operations, albeit at the cost of reduced effective res\n"
+      "reduced to a constant number of operations, albeit at the cost of reduced effective resolution due\n",
+      "to averaging attention-weighted positions, an effect we counteract with Multi-Head Attention as\n",
+      "described in section 3.2.\n",
+      "Self-attention, sometimes called intra-attention is an attention mechanism relating different positions\n",
+      "of a single sequence in order to compute a representation of the sequence. Self-attention has been\n",
+      "used successfully in a variety of tasks including reading comprehension, abstractive summarization,\n",
+      "textual entailment and learning task-independent sentence representations [4, 27, 28, 22].\n",
+      "End-to-end memory networks are based on a recurrent attention mechanism instead of sequence-\n",
+      "aligned recurrence and have been shown to perform well on simple-language question answering and\n",
+      "language modeling tasks [34].\n",
+      "To the best of our knowledge, however, the Transformer is the first transduction model relying\n",
+      "entirely on self-attention to compute representations of its input and output without using sequence-\n",
+      "aligned RNNs or convolution. In the following sections, we will describe the Transformer, motivate\n",
+      "self-attention and discuss its advantages over models such as [17, 18] and [9].\n",
+      "3   Model Architecture\n",
+      "Most competitive neural sequence transduction models have an encoder-decoder structure [5, 2, 35].\n",
+      "Here, the encoder maps an input sequence of symbol representations (x1, ..., xn) to a sequence\n",
+      "of continuous representations z = (z1, ..., zn). Given z, the decoder then generates an output\n",
+      "sequence (y1, ..., ym) of symbols one element at a time. At each step the model is auto-regressive\n",
+      "[10], consuming the previously generated symbols as additional input when generating the next.\n",
+      "                                                2\n"
      ]
     }
    ],
    "source": [
-    "print(documents[0].text[6000:7000])"
+    "documents = result.get_text_documents(split_by_page=True)\n",
+    "print(documents[1].text)"
    ]
   },
   {
@@ -115,48 +131,45 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Started parsing the file under job_id d4531453-1bbb-48c4-8324-ae9fea9f2fa2\n"
+      "arXiv:1706.03762v7  [cs.CL]  2 Aug 2023\n",
+      "\n",
+      "Provided proper attribution is provided, Google hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works.\n",
+      "\n",
+      "# Attention Is All You Need\n",
+      "\n",
+      "Ashish Vaswani∗        Noam Shazeer∗           Niki Parmar∗        Jakob Uszkoreit∗\n",
+      "\n",
+      "Google Brain        Google Brain         Google Research       Google Research\n",
+      "\n",
+      "avaswani@google.com   noam@google.com        nikip@google.com      usz@google.com\n",
+      "\n",
+      "Llion Jones∗                Aidan N. Gomez∗ †               Łukasz Kaiser∗\n",
+      "\n",
+      "Google Research         University of Toronto                Google Brain\n",
+      "\n",
+      "llion@google.com      aidan@cs.toronto.edu           lukaszkaiser@google.com\n",
+      "\n",
+      "Illia Polosukhin∗ ‡\n",
+      "\n",
+      "illia.polosukhin@gmail.com\n",
+      "\n",
+      "# Abstract\n",
+      "\n",
+      "The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder. The best performing models also connect the encoder and decoder through an attention mechanism. We propose a new simple network architecture, the Transformer, based solely on attention mechanisms, dispensing with recurrence and convolutions entirely. Experiments on two machine translation tasks show these models to be superior in quality while being more parallelizable and requiring significantly less time to train. Our model achieves 28.4 BLEU on the WMT 2014 English-to-German translation task, improving over the existing best results, including ensembles, by over 2 BLEU. On the WMT 2014 English-to-French translation task, our model establishes a new single-model state-of-the-art BLEU score of 41.8 after training for 3.5 days on eight GPUs, a small fraction of the training costs of the best models from the literature. We show that the Transformer generalizes well to other tasks by applying it successfully to English constituency parsing both with large and limited training data.\n",
+      "\n",
+      "∗Equal contribution. Listing order is random. Jakob proposed replacing RNNs with self-attention and started the effort to evaluate this idea. Ashish, with Illia, designed and implemented the first Transformer models and has been crucially involved in every aspect of this work. Noam proposed scaled dot-product attention, multi-head attention and the parameter-free position representation and became the other person involved in nearly every detail. Niki designed, implemented, tuned and evaluated countless model variants in our original codebase and tensor2tensor. Llion also experimented with novel model variants, was responsible for our initial codebase, and efficient inference and visualizations. Lukasz and Aidan spent countless long days designing various parts of and implementing tensor2tensor, replacing our earlier codebase, greatly improving results and massively accelerating our research.\n",
+      "\n",
+      "†Work performed while at Google Brain.\n",
+      "\n",
+      "‡Work performed while at Google Research.\n",
+      "\n",
+      "31st Conference on Neural Information Processing Systems (NIPS 2017), Long Beach, CA, USA.\n"
      ]
     }
    ],
    "source": [
-    "from llama_cloud_services import LlamaParse\n",
-    "\n",
-    "documents = LlamaParse(result_type=\"markdown\").load_data(\"./attention.pdf\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "ction describes the training regime for our models.\n",
-      "\n",
-      "##### Training Data and Batching\n",
-      "\n",
-      "We trained on the standard WMT 2014 English-German dataset consisting of about 4.5 million\n",
-      "sentence pairs. Sentences were encoded using byte-pair encoding [3], which has a shared source-\n",
-      "target vocabulary of about 37000 tokens. For English-French, we used the significantly larger WMT\n",
-      "2014 English-French dataset consisting of 36M sentences and split tokens into a 32000 word-piece\n",
-      "vocabulary [38]. Sentence pairs were batched together by approximate sequence length. Each training\n",
-      "batch contained a set of sentence pairs containing approximately 25000 source tokens and 25000\n",
-      "target tokens.\n",
-      "\n",
-      "##### Hardware and Schedule\n",
-      "\n",
-      "We trained our models on one machine with 8 NVIDIA P100 GPUs. For our base models using\n",
-      "the hyperparameters described throughout the paper, each training step took about 0.4 seconds. We\n",
-      "trained the base models for a total of 100,000 steps or 12 hours. For our big models,(described on the\n",
-      "bo...\n"
-     ]
-    }
-   ],
-   "source": [
-    "print(documents[0].text[20000:21000] + \"...\")"
+    "documents = result.get_markdown_documents(split_by_page=True)\n",
+    "print(documents[0].text)"
    ]
   }
  ],

examples/parse/demo_json.ipynb

@@ -31,11 +31,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pip install llama-index\n",
-    "!pip install llama-index-core\n",
-    "!pip install llama-index-llms-anthropic llama-index-multi-modal-llms-anthropic\n",
-    "!pip install llama-index-embeddings-huggingface\n",
-    "!pip install llama-cloud-services"
+    "%pip install llama-index\n",
+    "%pip install llama-index-core\n",
+    "%pip install llama-index-llms-anthropic\n",
+    "%pip install llama-index-embeddings-huggingface\n",
+    "%pip install llama-cloud-services"
    ]
   },
   {
@@ -45,11 +45,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# llama-parse is async-first, running the async code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import os\n",
     "\n",
     "# API access to llama-cloud\n",
@@ -68,7 +63,7 @@
    "source": [
     "from llama_index.llms.anthropic import Anthropic\n",
     "\n",
-    "llm = Anthropic(model=\"claude-3-opus-20240229\", temperature=0.0)"
+    "llm = Anthropic(model=\"claude-3-5-sonnet-20241022\")"
    ]
   },
   {
@@ -131,28 +126,8 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "parser = LlamaParse(verbose=True)\n",
-    "json_objs = parser.get_json_result(\"./uber_10q_march_2022.pdf\")\n",
-    "json_list = json_objs[0][\"pages\"]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "b26d21d1-05b5-4f49-b937-c13106a84015",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.core.schema import TextNode\n",
-    "from typing import List\n",
-    "\n",
-    "\n",
-    "def get_text_nodes(json_list: List[dict]):\n",
-    "    text_nodes = []\n",
-    "    for idx, page in enumerate(json_list):\n",
-    "        text_node = TextNode(text=page[\"text\"], metadata={\"page\": page[\"page\"]})\n",
-    "        text_nodes.append(text_node)\n",
-    "    return text_nodes"
+    "parser = LlamaParse(take_screenshot=True)\n",
+    "result = await parser.aparse(\"./uber_10q_march_2022.pdf\")"
    ]
   },
   {
@@ -162,7 +137,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "text_nodes = get_text_nodes(json_list)"
+    "text_nodes = await result.aget_text_nodes(split_by_page=True)\n",
+    "image_nodes = await result.aget_image_nodes(\n",
+    "    include_screenshot_images=True,\n",
+    "    include_object_images=True,\n",
+    "    image_download_dir=\"./uber_10q_images\",\n",
+    ")"
    ]
   },
   {
@@ -172,7 +152,7 @@
    "source": [
     "## Extract/Index images from image dicts\n",
     "\n",
-    "Here we use a multimodal model to extract and index images from image dictionaries."
+    "Here we use a multimodal model to caption images and create text nodes for indexing."
    ]
   },
   {
@@ -190,27 +170,32 @@
     }
    ],
    "source": [
-    "# call get_images on parser, convert to ImageDocuments\n",
-    "!mkdir llama2_images\n",
+    "!mkdir -p llama2_images\n",
     "\n",
-    "from llama_index.core.schema import ImageDocument\n",
-    "from llama_index.multi_modal_llms.anthropic import AnthropicMultiModal\n",
+    "from llama_index.core.llms import ChatMessage, ImageBlock, TextBlock\n",
+    "from llama_index.core.schema import ImageNode, TextNode\n",
+    "from llama_index.llms.anthropic import Anthropic\n",
     "\n",
     "\n",
-    "def get_image_text_nodes(json_objs: List[dict]):\n",
+    "def get_image_text_nodes(image_nodes: list[ImageNode]):\n",
     "    \"\"\"Extract out text from images using a multimodal model.\"\"\"\n",
-    "    anthropic_mm_llm = AnthropicMultiModal(max_tokens=300)\n",
-    "    image_dicts = parser.get_images(json_objs, download_path=\"llama2_images\")\n",
-    "    image_documents = []\n",
+    "    llm = Anthropic(model=\"claude-3-5-haiku-20241022\", max_tokens=300)\n",
     "    img_text_nodes = []\n",
-    "    for image_dict in image_dicts:\n",
-    "        image_doc = ImageDocument(image_path=image_dict[\"path\"])\n",
-    "        response = anthropic_mm_llm.complete(\n",
-    "            prompt=\"Describe the images as alt text\",\n",
-    "            image_documents=[image_doc],\n",
+    "    for image_node in image_nodes:\n",
+    "        image_path = image_node.image_path\n",
+    "        message = ChatMessage(\n",
+    "            role=\"user\",\n",
+    "            blocks=[\n",
+    "                TextBlock(text=\"Describe the images as alt text\"),\n",
+    "                ImageBlock(path=image_path),\n",
+    "            ],\n",
+    "        )\n",
+    "        response = llm.chat([message])\n",
+    "        text_node = TextNode(\n",
+    "            text=str(response.message.content), metadata={\"path\": image_path}\n",
     "        )\n",
-    "        text_node = TextNode(text=str(response), metadata={\"path\": image_dict[\"path\"]})\n",
     "        img_text_nodes.append(text_node)\n",
+    "\n",
     "    return img_text_nodes"
    ]
   },
@@ -221,7 +206,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "image_text_nodes = get_image_text_nodes(json_objs)"
+    "image_text_nodes = get_image_text_nodes(image_nodes)"
    ]
   },
   {

examples/parse/demo_languages.ipynb

@@ -31,14 +31,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# llama-parse is async-first, running the sync code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import os\n",
     "\n",
-    "# os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-...\""
+    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-...\""
    ]
   },
   {
@@ -79,8 +74,9 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "parser = LlamaParse(result_type=\"text\", language=\"fr\")\n",
-    "documents = parser.load_data(\"./treasury_report.pdf\")"
+    "parser = LlamaParse(language=\"fr\")\n",
+    "result = await parser.aparse(\"./treasury_report.pdf\")\n",
+    "documents = result.get_text_documents(split_by_page=False)"
    ]
   },
   {
@@ -252,8 +248,9 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "parser = LlamaParse(result_type=\"text\", language=\"ch_sim\")\n",
-    "documents = parser.load_data(\"./chinese_pdf.pdf\")"
+    "parser = LlamaParse(language=\"ch_sim\")\n",
+    "result = await parser.aparse(\"./chinese_pdf.pdf\")\n",
+    "documents = result.get_text_documents(split_by_page=False)"
    ]
   },
   {
@@ -406,8 +403,9 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "base_parser = LlamaParse(result_type=\"text\", language=\"en\")\n",
-    "base_documents = parser.load_data(\"./chinese_pdf2.pdf\")"
+    "base_parser = LlamaParse(language=\"en\")\n",
+    "result = await base_parser.aparse(\"./chinese_pdf2.pdf\")\n",
+    "base_documents = result.get_text_documents(split_by_page=False)"
    ]
   },
   {

examples/parse/demo_mongodb.ipynb

@@ -60,11 +60,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# llama-parse is async-first, running the sync code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import requests\n",
     "import pymongo\n",
     "\n",
@@ -72,7 +67,7 @@
     "from llama_cloud_services import LlamaParse\n",
     "from llama_index.embeddings.openai import OpenAIEmbedding\n",
     "from llama_index.core import VectorStoreIndex, StorageContext\n",
-    "from llama_index.core.node_parser import SimpleNodeParser"
+    "from llama_index.core.node_parser import SentenceSplitter"
    ]
   },
   {
@@ -137,7 +132,8 @@
     }
    ],
    "source": [
-    "documents = LlamaParse(result_type=\"text\").load_data(file_path)"
+    "result = await LlamaParse().aparse(file_path)\n",
+    "documents = result.get_text_documents(split_by_page=False)"
    ]
   },
   {
@@ -203,7 +199,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "node_parser = SimpleNodeParser()\n",
+    "node_parser = SentenceSplitter()\n",
     "\n",
     "nodes = node_parser.get_nodes_from_documents(documents)"
    ]

examples/parse/demo_parsing_instructions.ipynb

@@ -1,544 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# LlamaParse - Parsing comic books with parsing intructions\n",
-    "Parsing intructions allow you to instruct our parsing model the same way you would instruct an LLM!\n",
-    "\n",
-    "They can be useful to help the parser get better results on complex document layouts, to extract data in a specific format, or to transform the document in other ways.\n",
-    "\n",
-    "Using Parsing Instruction you will get better results out of LlamaParse on complicated documents, and also be able to simplify your application code."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Installation\n",
-    "\n",
-    "Parsing instructions are part of the llamaParse API. They can be accessed by directly specifying the parsing_instruction parameter in the API or by using the LlamaParse python module (which we will use for this tutorial).\n",
-    "\n",
-    "To install llama-parse, just get it from PIP:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Collecting llama-parse\n",
-      "  Downloading llama_parse-0.3.8-py3-none-any.whl (6.7 kB)\n",
-      "Collecting llama-index-core>=0.10.7 (from llama-parse)\n",
-      "  Downloading llama_index_core-0.10.19-py3-none-any.whl (15.3 MB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m15.3/15.3 MB\u001b[0m \u001b[31m31.9 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: PyYAML>=6.0.1 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (6.0.1)\n",
-      "Requirement already satisfied: SQLAlchemy[asyncio]>=1.4.49 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (2.0.28)\n",
-      "Requirement already satisfied: aiohttp<4.0.0,>=3.8.6 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (3.9.3)\n",
-      "Collecting dataclasses-json (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading dataclasses_json-0.6.4-py3-none-any.whl (28 kB)\n",
-      "Collecting deprecated>=1.2.9.3 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading Deprecated-1.2.14-py2.py3-none-any.whl (9.6 kB)\n",
-      "Collecting dirtyjson<2.0.0,>=1.0.8 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading dirtyjson-1.0.8-py3-none-any.whl (25 kB)\n",
-      "Requirement already satisfied: fsspec>=2023.5.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (2023.6.0)\n",
-      "Collecting httpx (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading httpx-0.27.0-py3-none-any.whl (75 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m75.6/75.6 kB\u001b[0m \u001b[31m6.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hCollecting llamaindex-py-client<0.2.0,>=0.1.13 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading llamaindex_py_client-0.1.13-py3-none-any.whl (107 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m108.0/108.0 kB\u001b[0m \u001b[31m10.0 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: nest-asyncio<2.0.0,>=1.5.8 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (1.6.0)\n",
-      "Requirement already satisfied: networkx>=3.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (3.2.1)\n",
-      "Requirement already satisfied: nltk<4.0.0,>=3.8.1 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (3.8.1)\n",
-      "Requirement already satisfied: numpy in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (1.25.2)\n",
-      "Collecting openai>=1.1.0 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading openai-1.13.3-py3-none-any.whl (227 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m227.4/227.4 kB\u001b[0m \u001b[31m16.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: pandas in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (1.5.3)\n",
-      "Requirement already satisfied: pillow>=9.0.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (9.4.0)\n",
-      "Requirement already satisfied: requests>=2.31.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (2.31.0)\n",
-      "Requirement already satisfied: tenacity<9.0.0,>=8.2.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (8.2.3)\n",
-      "Collecting tiktoken>=0.3.3 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading tiktoken-0.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m1.8/1.8 MB\u001b[0m \u001b[31m43.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: tqdm<5.0.0,>=4.66.1 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (4.66.2)\n",
-      "Requirement already satisfied: typing-extensions>=4.5.0 in /usr/local/lib/python3.10/dist-packages (from llama-index-core>=0.10.7->llama-parse) (4.10.0)\n",
-      "Collecting typing-inspect>=0.8.0 (from llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading typing_inspect-0.9.0-py3-none-any.whl (8.8 kB)\n",
-      "Requirement already satisfied: aiosignal>=1.1.2 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (1.3.1)\n",
-      "Requirement already satisfied: attrs>=17.3.0 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (23.2.0)\n",
-      "Requirement already satisfied: frozenlist>=1.1.1 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (1.4.1)\n",
-      "Requirement already satisfied: multidict<7.0,>=4.5 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (6.0.5)\n",
-      "Requirement already satisfied: yarl<2.0,>=1.0 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (1.9.4)\n",
-      "Requirement already satisfied: async-timeout<5.0,>=4.0 in /usr/local/lib/python3.10/dist-packages (from aiohttp<4.0.0,>=3.8.6->llama-index-core>=0.10.7->llama-parse) (4.0.3)\n",
-      "Requirement already satisfied: wrapt<2,>=1.10 in /usr/local/lib/python3.10/dist-packages (from deprecated>=1.2.9.3->llama-index-core>=0.10.7->llama-parse) (1.14.1)\n",
-      "Requirement already satisfied: pydantic>=1.10 in /usr/local/lib/python3.10/dist-packages (from llamaindex-py-client<0.2.0,>=0.1.13->llama-index-core>=0.10.7->llama-parse) (2.6.3)\n",
-      "Requirement already satisfied: anyio in /usr/local/lib/python3.10/dist-packages (from httpx->llama-index-core>=0.10.7->llama-parse) (3.7.1)\n",
-      "Requirement already satisfied: certifi in /usr/local/lib/python3.10/dist-packages (from httpx->llama-index-core>=0.10.7->llama-parse) (2024.2.2)\n",
-      "Collecting httpcore==1.* (from httpx->llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading httpcore-1.0.4-py3-none-any.whl (77 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m77.8/77.8 kB\u001b[0m \u001b[31m8.5 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: idna in /usr/local/lib/python3.10/dist-packages (from httpx->llama-index-core>=0.10.7->llama-parse) (3.6)\n",
-      "Requirement already satisfied: sniffio in /usr/local/lib/python3.10/dist-packages (from httpx->llama-index-core>=0.10.7->llama-parse) (1.3.1)\n",
-      "Collecting h11<0.15,>=0.13 (from httpcore==1.*->httpx->llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading h11-0.14.0-py3-none-any.whl (58 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m58.3/58.3 kB\u001b[0m \u001b[31m5.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: click in /usr/local/lib/python3.10/dist-packages (from nltk<4.0.0,>=3.8.1->llama-index-core>=0.10.7->llama-parse) (8.1.7)\n",
-      "Requirement already satisfied: joblib in /usr/local/lib/python3.10/dist-packages (from nltk<4.0.0,>=3.8.1->llama-index-core>=0.10.7->llama-parse) (1.3.2)\n",
-      "Requirement already satisfied: regex>=2021.8.3 in /usr/local/lib/python3.10/dist-packages (from nltk<4.0.0,>=3.8.1->llama-index-core>=0.10.7->llama-parse) (2023.12.25)\n",
-      "Requirement already satisfied: distro<2,>=1.7.0 in /usr/lib/python3/dist-packages (from openai>=1.1.0->llama-index-core>=0.10.7->llama-parse) (1.7.0)\n",
-      "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests>=2.31.0->llama-index-core>=0.10.7->llama-parse) (3.3.2)\n",
-      "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.10/dist-packages (from requests>=2.31.0->llama-index-core>=0.10.7->llama-parse) (2.0.7)\n",
-      "Requirement already satisfied: greenlet!=0.4.17 in /usr/local/lib/python3.10/dist-packages (from SQLAlchemy[asyncio]>=1.4.49->llama-index-core>=0.10.7->llama-parse) (3.0.3)\n",
-      "Collecting mypy-extensions>=0.3.0 (from typing-inspect>=0.8.0->llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading mypy_extensions-1.0.0-py3-none-any.whl (4.7 kB)\n",
-      "Collecting marshmallow<4.0.0,>=3.18.0 (from dataclasses-json->llama-index-core>=0.10.7->llama-parse)\n",
-      "  Downloading marshmallow-3.21.1-py3-none-any.whl (49 kB)\n",
-      "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m49.4/49.4 kB\u001b[0m \u001b[31m4.5 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
-      "\u001b[?25hRequirement already satisfied: python-dateutil>=2.8.1 in /usr/local/lib/python3.10/dist-packages (from pandas->llama-index-core>=0.10.7->llama-parse) (2.8.2)\n",
-      "Requirement already satisfied: pytz>=2020.1 in /usr/local/lib/python3.10/dist-packages (from pandas->llama-index-core>=0.10.7->llama-parse) (2023.4)\n",
-      "Requirement already satisfied: exceptiongroup in /usr/local/lib/python3.10/dist-packages (from anyio->httpx->llama-index-core>=0.10.7->llama-parse) (1.2.0)\n",
-      "Requirement already satisfied: packaging>=17.0 in /usr/local/lib/python3.10/dist-packages (from marshmallow<4.0.0,>=3.18.0->dataclasses-json->llama-index-core>=0.10.7->llama-parse) (23.2)\n",
-      "Requirement already satisfied: annotated-types>=0.4.0 in /usr/local/lib/python3.10/dist-packages (from pydantic>=1.10->llamaindex-py-client<0.2.0,>=0.1.13->llama-index-core>=0.10.7->llama-parse) (0.6.0)\n",
-      "Requirement already satisfied: pydantic-core==2.16.3 in /usr/local/lib/python3.10/dist-packages (from pydantic>=1.10->llamaindex-py-client<0.2.0,>=0.1.13->llama-index-core>=0.10.7->llama-parse) (2.16.3)\n",
-      "Requirement already satisfied: six>=1.5 in /usr/local/lib/python3.10/dist-packages (from python-dateutil>=2.8.1->pandas->llama-index-core>=0.10.7->llama-parse) (1.16.0)\n",
-      "Installing collected packages: dirtyjson, mypy-extensions, marshmallow, h11, deprecated, typing-inspect, tiktoken, httpcore, httpx, dataclasses-json, openai, llamaindex-py-client, llama-index-core, llama-parse\n",
-      "Successfully installed dataclasses-json-0.6.4 deprecated-1.2.14 dirtyjson-1.0.8 h11-0.14.0 httpcore-1.0.4 httpx-0.27.0 llama-index-core-0.10.19 llama-parse-0.3.8 llamaindex-py-client-0.1.13 marshmallow-3.21.1 mypy-extensions-1.0.0 openai-1.13.3 tiktoken-0.6.0 typing-inspect-0.9.0\n"
-     ]
-    }
-   ],
-   "source": [
-    "%pip install llama-cloud-services"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## API key\n",
-    "\n",
-    "The use of LlamaParse requires an API key which you can get here: https://cloud.llamaindex.ai/parse"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import os\n",
-    "\n",
-    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-...\""
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Async (Notebook only)\n",
-    "llama-parse is async-first, so running the code in a notebook requires the use of nest_asyncio\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Import the package"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_cloud_services import LlamaParse"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Using llamaparse for getting better results (on Manga!)\n",
-    "\n",
-    "Sometimes the layout of a page is unusual and you will get sub-optimal reading order results with LlamaParse. For example, when parsing manga you expect the reading order to be right to left even if the content is in English!"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Let's download an extract of a great manga \"The manga guide to calculus\", by Hiroyuki Kojima (https://www.amazon.com/Manga-Guide-Calculus-Hiroyuki-Kojima/dp/1593271948)\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "--2024-03-13 13:57:19--  https://drive.usercontent.google.com/uc?id=1tZJhcpepLRdQFJFCFX50QIqLyLgqzZsY&export=download\n",
-      "Resolving drive.usercontent.google.com (drive.usercontent.google.com)... 173.194.211.132, 2607:f8b0:400c:c10::84\n",
-      "Connecting to drive.usercontent.google.com (drive.usercontent.google.com)|173.194.211.132|:443... connected.\n",
-      "HTTP request sent, awaiting response... 303 See Other\n",
-      "Location: https://drive.usercontent.google.com/download?id=1tZJhcpepLRdQFJFCFX50QIqLyLgqzZsY&export=download [following]\n",
-      "--2024-03-13 13:57:19--  https://drive.usercontent.google.com/download?id=1tZJhcpepLRdQFJFCFX50QIqLyLgqzZsY&export=download\n",
-      "Reusing existing connection to drive.usercontent.google.com:443.\n",
-      "HTTP request sent, awaiting response... 200 OK\n",
-      "Length: 3041634 (2.9M) [application/octet-stream]\n",
-      "Saving to: ‘./manga.pdf’\n",
-      "\n",
-      "./manga.pdf         100%[===================>]   2.90M  --.-KB/s    in 0.04s   \n",
-      "\n",
-      "2024-03-13 13:57:20 (78.6 MB/s) - ‘./manga.pdf’ saved [3041634/3041634]\n",
-      "\n"
-     ]
-    }
-   ],
-   "source": [
-    "! wget \"https://drive.usercontent.google.com/uc?id=1tZJhcpepLRdQFJFCFX50QIqLyLgqzZsY&export=download\" -O ./manga.pdf"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Without parsing instructions\n",
-    "For the sake of comparison, let's first parse without any instructions."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Started parsing the file under job_id 25bf4202-78d8-4705-88cf-c616ae7c82af\n"
-     ]
-    }
-   ],
-   "source": [
-    "vanilaParsing = LlamaParse(result_type=\"markdown\").load_data(\"./manga.pdf\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "As you can see below, LlamaParse is not doing a great job here. It is interpreting the grid of comic panels as a table, and trying to fit the dialogue into a table. It's very hard to follow."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "The Asagake Times Sanda-Cho Distributor\n",
-      "\n",
-      "A newspaper distributor? do I have the wrong map?\n",
-      "\n",
-      "You’re looking It’s next for the Sanda-cho door. branch office? Everybody mistakes us for the office because we are larger. What Is a Function? 3\n",
-      "---\n",
-      "## Calculating the Derivative of a Constant, Linear, or Quadratic Function\n",
-      "\n",
-      "|1.|Let’s find the derivative of constant function f(x) = α. The differential coefficient of f(x) at x = a is|\n",
-      "|---|---|\n",
-      "| |lim ε→0 (f(a + ε) - f(a)) / ε = lim ε→0 (α - α) = lim ε→0 0 = 0|\n",
-      "| |Thus, the derivative of f(x) is f′(x) = 0. This makes sense, since our function is constant—the rate of change is 0.|\n",
-      "\n",
-      "Note: The differential coefficient of f(x) at x = a is often simply called the derivative of f(x) at x = a, or just f′(a).\n",
-      "\n",
-      "|2.|Let’s calculate the derivative of linear function f(x) = αx + β. The derivative of f(x) at x = α is|\n",
-      "|---|---|\n",
-      "| |lim ε→0 (f(α + ε) - f(a)) = \n"
-     ]
-    }
-   ],
-   "source": [
-    "print(vanilaParsing[0].text[100:1000])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Using parsing instructions\n",
-    "Let's try to parse the manga with custom instructions:\n",
-    "\n",
-    "\"The provided document is a manga comic book. Most pages do NOT have a title. It does not contain tables. Try to reconstruct the dialogue spoken in a cohesive way.\"\n",
-    "\n",
-    "To do so just pass the parsing instruction as a parameter to LlamaParse:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Started parsing the file under job_id 88ab273e-b2a7-4f84-8e72-e9367cf6b114\n",
-      "."
-     ]
-    }
-   ],
-   "source": [
-    "parsingInstructionManga = \"\"\"The provided document is a manga comic book. Most pages do NOT have a title.\n",
-    "It does not contain tables.\n",
-    "Try to reconstruct the dialogue spoken in a cohesive way.\"\"\"\n",
-    "withInstructionParsing = LlamaParse(\n",
-    "    result_type=\"markdown\", parsing_instruction=parsingInstructionManga\n",
-    ").load_data(\"./manga.pdf\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Let's see how it compare with page 3! We encourage you to play with the target page and explore other pages. As you will see, the parsing instruction allowed LlamaParse to make sense of the document!\n",
-    "\n",
-    "<img src=\"https://drive.usercontent.google.com/download?id=1M87rXTIZE8d5v7aHmVZVW6gW3eDGq6ks&authuser=0\" />\n",
-    "\n",
-    "\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "The Asagake Times Sanda-Cho Distributor\n",
-      "\n",
-      "A newspaper distributor? do I have the wrong map?\n",
-      "\n",
-      "You’re looking It’s next for the Sanda-cho door. branch office? Everybody mistakes us for the office because we are larger. What Is a Function? 3\n",
-      "\n",
-      "\n",
-      "------------------------------------------------------------\n",
-      "\n",
-      "\n",
-      "# The Asagake Times\n",
-      "\n",
-      "Sanda-Cho Distributor\n",
-      "\n",
-      "A newspaper distributor?\n",
-      "\n",
-      "Do I have the wrong map?\n",
-      "\n",
-      "You're looking for the Sanda-cho branch office?\n",
-      "\n",
-      "It's next door.\n",
-      "\n",
-      "Everybody mistakes us for the office because we are larger.\n",
-      "\n",
-      "What Is a Function? 3\n"
-     ]
-    }
-   ],
-   "source": [
-    "target_page = 1\n",
-    "print(vanilaParsing[0].text.split(\"\\n---\\n\")[target_page])\n",
-    "print(\"\\n\\n------------------------------------------------------------\\n\\n\")\n",
-    "print(withInstructionParsing[0].text.split(\"\\n---\\n\")[target_page])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Math - doing more with parsing instuction!\n",
-    "\n",
-    "But this manga is about math and full of equations, why not ask the parser to output them in **LaTeX**?\n",
-    "\n",
-    "<img src=\"https://drive.usercontent.google.com/download?id=1tze3xcQ7axVA-vC_iZeAj_GvYcyNuYDa&authuser=0\" />"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Started parsing the file under job_id 3a055e64-d91e-484e-b9b0-99a2e637c08d\n",
-      "."
-     ]
-    }
-   ],
-   "source": [
-    "parsingInstructionMangaLatex = \"\"\"The provided document is a manga comic book. Most pages do NOT have a title.\n",
-    "It does not contain tables.\n",
-    "Try to reconstruct the dialogue spoken in a cohesive way.\n",
-    "Output any math equation in LATEX markdown (between $$)\"\"\"\n",
-    "withLatex = LlamaParse(\n",
-    "    result_type=\"markdown\", parsing_instruction=parsingInstructionMangaLatex\n",
-    ").load_data(\"./manga.pdf\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "\n",
-      "[Without instruction]------------------------------------------------------------\n",
-      "\n",
-      "\n",
-      "## Calculating the Derivative of a Constant, Linear, or Quadratic Function\n",
-      "\n",
-      "|1.|Let’s find the derivative of constant function f(x) = α. The differential coefficient of f(x) at x = a is|\n",
-      "|---|---|\n",
-      "| |lim ε→0 (f(a + ε) - f(a)) / ε = lim ε→0 (α - α) = lim ε→0 0 = 0|\n",
-      "| |Thus, the derivative of f(x) is f′(x) = 0. This makes sense, since our function is constant—the rate of change is 0.|\n",
-      "\n",
-      "Note: The differential coefficient of f(x) at x = a is often simply called the derivative of f(x) at x = a, or just f′(a).\n",
-      "\n",
-      "|2.|Let’s calculate the derivative of linear function f(x) = αx + β. The derivative of f(x) at x = α is|\n",
-      "|---|---|\n",
-      "| |lim ε→0 (f(α + ε) - f(a)) = lim ε→0 (α(a + ε) + β - (αa + β)) = lim ε→0 α = α|\n",
-      "| |Thus, the derivative of f(x) is f′(x) = α, a constant value. This result should also be intuitive—linear functions have a constant rate of change by definition.|\n",
-      "\n",
-      "|3.|Let’s find the derivative of f(x) = x^2, which appeared in the story. The differential coefficient of f(x) at x = a is|\n",
-      "|---|---|\n",
-      "| |lim ε→0 ((a + ε)^2 - a^2) / ε = lim (a^2 + 2aε + ε^2 - a^2) / ε = lim (2aε + ε^2) = lim (2a + ε) = 2a|\n",
-      "| |Thus, the differential coefficient of f(x) at x = a is 2a, or f′(a) = 2a. Therefore, the derivative of f(x) is f′(x) = 2x.|\n",
-      "\n",
-      "## Summary\n",
-      "\n",
-      "- The calculation of a limit that appears in calculus is simply a formula calculating an error.\n",
-      "- A limit is used to obtain a derivative.\n",
-      "- The derivative is the slope of the tangent line at a given point.\n",
-      "- The derivative is nothing but the rate of change.\n",
-      "\n",
-      "## Chapter 1 Let’s Differentiate a Function!\n",
-      "\n",
-      "\n",
-      "[With instruction to output math in LATEX!]------------------------------------------------------------\n",
-      "\n",
-      "\n",
-      "# Derivative of Constant, Linear, or Quadratic Function\n",
-      "\n",
-      "## Calculating the Derivative of a Constant, Linear, or Quadratic Function\n",
-      "\n",
-      "1. Let’s find the derivative of constant function f(x) = α. The differential coefficient of f(x) at x = a is\n",
-      "\n",
-      "$$\n",
-      "\\begin{align*}\n",
-      "&\\lim_{{\\varepsilon \\to 0}} \\left( \\frac{f(a + \\varepsilon) - f(a)}{\\varepsilon} \\right) = \\lim_{{\\varepsilon \\to 0}} \\frac{\\alpha - \\alpha}{\\varepsilon} = \\lim_{{\\varepsilon \\to 0}} 0 = 0 \\\\\n",
-      "\\end{align*}\n",
-      "$$\n",
-      "Thus, the derivative of f(x) is f′(x) = 0. This makes sense, since our function is constant—the rate of change is 0.\n",
-      "\n",
-      "Note: The differential coefficient of f(x) at x = a is often simply called the derivative of f(x) at x = a, or just f′(a).\n",
-      "\n",
-      "2. Let’s calculate the derivative of linear function f(x) = αx + β. The derivative of f(x) at x = α is\n",
-      "\n",
-      "$$\n",
-      "\\begin{align*}\n",
-      "&\\lim_{{\\varepsilon \\to 0}} \\left( \\frac{f(\\alpha + \\varepsilon) - f(a)}{\\varepsilon} \\right) = \\lim_{{\\varepsilon \\to 0}} \\frac{\\alpha(a + \\varepsilon) + \\beta - (\\alpha a + \\beta)}{\\varepsilon} = \\lim_{{\\varepsilon \\to 0}} \\alpha = \\alpha \\\\\n",
-      "\\end{align*}\n",
-      "$$\n",
-      "Thus, the derivative of f(x) is f′(x) = α, a constant value. This result should also be intuitive—linear functions have a constant rate of change by definition.\n",
-      "\n",
-      "3. Let’s find the derivative of f(x) = x2. The differential coefficient of f(x) at x = a is\n",
-      "\n",
-      "$$\n",
-      "\\begin{align*}\n",
-      "&\\lim_{{\\varepsilon \\to 0}} \\left( \\frac{f(a + \\varepsilon) - f(a)}{\\varepsilon} \\right) = \\lim_{{\\varepsilon \\to 0}} \\left( (a + \\varepsilon)^2 - a^2 \\right) = \\lim_{{\\varepsilon \\to 0}} 2a\\varepsilon + \\varepsilon = \\lim_{{\\varepsilon \\to 0}} (2a + \\varepsilon) = 2a \\\\\n",
-      "\\end{align*}\n",
-      "$$\n",
-      "Thus, the differential coefficient of f(x) at x = a is 2a, or f′(a) = 2a. Therefore, the derivative of f(x) is f′(x) = 2x.\n",
-      "\n",
-      "### Summary\n",
-      "\n",
-      "- The calculation of a limit that appears in calculus is simply a formula calculating an error.\n",
-      "- A limit is used to obtain a derivative.\n",
-      "- The derivative is the slope of the tangent line at a given point.\n",
-      "- The derivative is nothing but the rate of change.\n"
-     ]
-    }
-   ],
-   "source": [
-    "target_page = 2\n",
-    "print(\n",
-    "    \"\\n\\n[Without instruction]------------------------------------------------------------\\n\\n\"\n",
-    ")\n",
-    "print(vanilaParsing[0].text.split(\"\\n---\\n\")[target_page])\n",
-    "print(\n",
-    "    \"\\n\\n[With instruction to output math in LATEX!]------------------------------------------------------------\\n\\n\"\n",
-    ")\n",
-    "print(withLatex[0].text.split(\"\\n---\\n\")[target_page])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "And here is the result as rendered by https://upmath.me/ .\n",
-    "\n",
-    "\n",
-    "<img src=\"https://drive.usercontent.google.com/download?id=1qGo5bMGYOiIC9MnprcgEByaYjU9YII2Q&authuser=0\" />\n",
-    "\n",
-    "\n",
-    "Over this short notebook we saw how to use parsing instructions to increase the quality and accuracy of parsing with LLamaParse!"
-   ]
-  }
- ],
- "metadata": {
-  "colab": {
-   "provenance": []
-  },
-  "kernelspec": {
-   "display_name": "Python 3",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
-}

examples/parse/demo_starter_multimodal.ipynb

@@ -55,10 +55,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import os\n",
     "\n",
     "# API access to llama-cloud\n",
@@ -80,25 +76,7 @@
    "execution_count": null,
    "id": "IjtKDQRLrylI",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "--2024-12-05 18:54:24--  https://arxiv.org/pdf/2409.18486\n",
-      "Resolving arxiv.org (arxiv.org)... 151.101.67.42, 151.101.131.42, 151.101.3.42, ...\n",
-      "Connecting to arxiv.org (arxiv.org)|151.101.67.42|:443... connected.\n",
-      "HTTP request sent, awaiting response... 200 OK\n",
-      "Length: 13986265 (13M) [application/pdf]\n",
-      "Saving to: ‘o1.pdf’\n",
-      "\n",
-      "o1.pdf              100%[===================>]  13.34M  11.8MB/s    in 1.1s    \n",
-      "\n",
-      "2024-12-05 18:54:26 (11.8 MB/s) - ‘o1.pdf’ saved [13986265/13986265]\n",
-      "\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "!wget \"https://arxiv.org/pdf/2409.18486\" -O \"o1.pdf\""
    ]
@@ -118,25 +96,6 @@
     "Using your own API key may incur additional costs from your model provider and could result in failed pages or documents if you do not have sufficient usage limits."
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "dc921729-3446-42ca-8e1b-a6fd26195ed9",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.core.schema import TextNode\n",
-    "from typing import List\n",
-    "\n",
-    "\n",
-    "def get_text_nodes(json_list: List[dict]):\n",
-    "    text_nodes = []\n",
-    "    for idx, page in enumerate(json_list):\n",
-    "        text_node = TextNode(text=page[\"md\"], metadata={\"page\": page[\"page\"]})\n",
-    "        text_nodes.append(text_node)\n",
-    "    return text_nodes"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "1b5d6da6",
@@ -163,15 +122,13 @@
     "from llama_cloud_services import LlamaParse\n",
     "\n",
     "parser = LlamaParse(\n",
-    "    result_type=\"markdown\",\n",
     "    use_vendor_multimodal_model=True,\n",
     "    vendor_multimodal_model_name=\"anthropic-sonnet-3.5\",\n",
     "    target_pages=\"24\"\n",
     "    # invalidate_cache=True\n",
     ")\n",
-    "json_objs = parser.get_json_result(\"o1.pdf\")\n",
-    "json_list = json_objs[0][\"pages\"]\n",
-    "docs = get_text_nodes(json_list)"
+    "result = await parser.aparse(\"o1.pdf\")\n",
+    "nodes = result.get_text_nodes(split_by_page=False)"
    ]
   },
   {
@@ -202,15 +159,13 @@
     "from llama_cloud_services import LlamaParse\n",
     "\n",
     "parser_gpt4o = LlamaParse(\n",
-    "    result_type=\"markdown\",\n",
     "    use_vendor_multimodal_model=True,\n",
     "    vendor_multimodal_model=\"openai-gpt4o\",\n",
     "    target_pages=\"24\",\n",
     "    # invalidate_cache=True\n",
     ")\n",
-    "json_objs_gpt4o = parser_gpt4o.get_json_result(\"o1.pdf\")\n",
-    "json_list_gpt4o = json_objs_gpt4o[0][\"pages\"]\n",
-    "docs_gpt4o = get_text_nodes(json_list_gpt4o)"
+    "result = await parser_gpt4o.aparse(\"o1.pdf\")\n",
+    "nodes = result.get_markdown_nodes(split_by_page=False)"
    ]
   },
   {
@@ -268,7 +223,7 @@
    ],
    "source": [
     "# using Sonnet-3.5\n",
-    "print(docs[0].get_content(metadata_mode=\"all\"))"
+    "print(nodes[0].get_content(metadata_mode=\"all\"))"
    ]
   },
   {
@@ -327,7 +282,7 @@
    ],
    "source": [
     "# using GPT-4o\n",
-    "print(docs_gpt4o[0].get_content(metadata_mode=\"all\"))"
+    "print(nodes[0].get_content(metadata_mode=\"all\"))"
    ]
   }
  ],

examples/parse/demo_starter_parse_selected_pages.ipynb

@@ -47,11 +47,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# llama-parse is async-first, running the async code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
     "import os\n",
     "\n",
     "# API access to llama-cloud\n",
@@ -71,25 +66,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "--2024-12-05 11:40:59--  https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/10k/uber_2021.pdf\n",
-      "Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 2606:50c0:8000::154, 2606:50c0:8002::154, 2606:50c0:8003::154, ...\n",
-      "Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|2606:50c0:8000::154|:443... connected.\n",
-      "HTTP request sent, awaiting response... 200 OK\n",
-      "Length: 1880483 (1.8M) [application/octet-stream]\n",
-      "Saving to: ‘./uber_2021.pdf’\n",
-      "\n",
-      "./uber_2021.pdf     100%[===================>]   1.79M  --.-KB/s    in 0.1s    \n",
-      "\n",
-      "2024-12-05 11:40:59 (14.2 MB/s) - ‘./uber_2021.pdf’ saved [1880483/1880483]\n",
-      "\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "!wget 'https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/10k/uber_2021.pdf' -O './uber_2021.pdf'"
    ]
@@ -119,9 +96,10 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "parser = LlamaParse(target_pages=\"0,1,2\", result_type=\"markdown\")\n",
+    "parser = LlamaParse(target_pages=\"0,1,2\")\n",
     "\n",
-    "documents = parser.load_data(\"./uber_2021.pdf\")"
+    "results = await parser.aparse(\"./uber_2021.pdf\")\n",
+    "documents = results.get_text_documents(split_by_page=True)"
    ]
   },
   {

examples/parse/demo_table_comparisons.ipynb

@@ -1,367 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# RAG for Table Comparisons with LlamaParse + LlamaIndex\n",
-    "\n",
-    "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/demo_table_comparisons.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
-    "\n",
-    "This notebook shows you how to do comparisons across both tabular and text data across multiple PDF documents.\n",
-    "\n",
-    "We load in multiple PDFs with embedded tables (2021 and 2020 10K filings for Apple) using LlamaParse, parse each into a hierarchy of tables/text objects, define a recursive retriever over each, and then compose both with a SubQuestionQueryEngine."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Setup\n",
-    "\n",
-    "Install core packages, download files, parse documents."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install llama-index\n",
-    "%pip install llama-index-core\n",
-    "%pip install llama-index-embeddings-openai\n",
-    "%pip install llama-index-question-gen-openai\n",
-    "%pip install llama-index-postprocessor-flag-embedding-reranker\n",
-    "%pip install git+https://github.com/FlagOpen/FlagEmbedding.git\n",
-    "%pip install llama-cloud-services"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!wget \"https://s2.q4cdn.com/470004039/files/doc_financials/2020/ar/_10-K-2020-(As-Filed).pdf\" -O apple_2020_10k.pdf\n",
-    "!wget \"https://s2.q4cdn.com/470004039/files/doc_financials/2021/q4/_10-K-2021-(As-Filed).pdf\" -O apple_2021_10k.pdf"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Some OpenAI and LlamaParse details"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# llama-parse is async-first, running the async code in a notebook requires the use of nest_asyncio\n",
-    "import nest_asyncio\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "\n",
-    "import os\n",
-    "\n",
-    "# API access to llama-cloud\n",
-    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-\"\n",
-    "\n",
-    "# Using OpenAI API for embeddings/llms\n",
-    "os.environ[\"OPENAI_API_KEY\"] = \"sk-\""
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.llms.openai import OpenAI\n",
-    "from llama_index.embeddings.openai import OpenAIEmbedding\n",
-    "from llama_index.core import VectorStoreIndex\n",
-    "from llama_index.core import Settings\n",
-    "\n",
-    "embed_model = OpenAIEmbedding(model=\"text-embedding-3-small\")\n",
-    "llm = OpenAI(model=\"gpt-3.5-turbo-0125\")\n",
-    "\n",
-    "Settings.llm = llm\n",
-    "Settings.embed_model = embed_model"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Using brand new `LlamaParse` PDF reader for PDF Parsing\n",
-    "\n",
-    "we also compare two different retrieval/query engine strategies:\n",
-    "1. Using raw Markdown text as nodes for building index and apply simple query engine for generating the results;\n",
-    "2. Using `MarkdownElementNodeParser` for parsing the `LlamaParse` output Markdown results and building recursive retriever query engine for generation."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_cloud_services import LlamaParse\n",
-    "\n",
-    "docs_2021 = LlamaParse(result_type=\"markdown\").load_data(\"./apple_2021_10k.pdf\")\n",
-    "docs_2020 = LlamaParse(result_type=\"markdown\").load_data(\"./apple_2020_10k.pdf\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Create Recursive Retriever over each Document\n",
-    "\n",
-    "We define a function to get a recursive retriever from each document. The steps are the following:\n",
-    "- Hierarchically parse the document using our `MarkdownElementNodeParser`, which will embed/summarize embedded tables.\n",
-    "- Load into a vector store. Under the hood we will automatically store links between nodes (e.g. table summary to table text).\n",
-    "- Get a query engine over the vector store, which performs retrieval/synthesis. Under the hood we will automatically perform recursive retrieval if there are links."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.core.node_parser import MarkdownElementNodeParser\n",
-    "\n",
-    "node_parser = MarkdownElementNodeParser(\n",
-    "    llm=OpenAI(model=\"gpt-3.5-turbo-0125\"), num_workers=8\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import pickle\n",
-    "from llama_index.postprocessor.flag_embedding_reranker import (\n",
-    "    FlagEmbeddingReranker,\n",
-    ")\n",
-    "\n",
-    "reranker = FlagEmbeddingReranker(\n",
-    "    top_n=5,\n",
-    "    model=\"BAAI/bge-reranker-large\",\n",
-    ")\n",
-    "\n",
-    "\n",
-    "def create_query_engine_over_doc(docs, nodes_save_path=None):\n",
-    "    \"\"\"Big function to go from document path -> recursive retriever.\"\"\"\n",
-    "    if nodes_save_path is not None and os.path.exists(nodes_save_path):\n",
-    "        raw_nodes = pickle.load(open(nodes_save_path, \"rb\"))\n",
-    "    else:\n",
-    "        raw_nodes = node_parser.get_nodes_from_documents(docs)\n",
-    "        if nodes_save_path is not None:\n",
-    "            pickle.dump(raw_nodes, open(nodes_save_path, \"wb\"))\n",
-    "\n",
-    "    base_nodes, objects = node_parser.get_nodes_and_objects(raw_nodes)\n",
-    "\n",
-    "    ### Construct Retrievers\n",
-    "    # construct top-level vector index + query engine\n",
-    "    vector_index = VectorStoreIndex(nodes=base_nodes + objects)\n",
-    "    query_engine = vector_index.as_query_engine(\n",
-    "        similarity_top_k=15, node_postprocessors=[reranker]\n",
-    "    )\n",
-    "    return query_engine, base_nodes"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "query_engine_2021, nodes_2021 = create_query_engine_over_doc(\n",
-    "    docs_2021, nodes_save_path=\"2021_nodes.pkl\"\n",
-    ")\n",
-    "query_engine_2020, nodes_2020 = create_query_engine_over_doc(\n",
-    "    docs_2020, nodes_save_path=\"2020_nodes.pkl\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from llama_index.core.tools import QueryEngineTool, ToolMetadata\n",
-    "from llama_index.core.query_engine import SubQuestionQueryEngine\n",
-    "\n",
-    "\n",
-    "# setup base query engine as tool\n",
-    "query_engine_tools = [\n",
-    "    QueryEngineTool(\n",
-    "        query_engine=query_engine_2021,\n",
-    "        metadata=ToolMetadata(\n",
-    "            name=\"apple_2021_10k\",\n",
-    "            description=(\"Provides information about Apple financials for year 2021\"),\n",
-    "        ),\n",
-    "    ),\n",
-    "    QueryEngineTool(\n",
-    "        query_engine=query_engine_2020,\n",
-    "        metadata=ToolMetadata(\n",
-    "            name=\"apple_2020_10k\",\n",
-    "            description=(\"Provides information about Apple financials for year 2020\"),\n",
-    "        ),\n",
-    "    ),\n",
-    "]\n",
-    "\n",
-    "sub_query_engine = SubQuestionQueryEngine.from_defaults(\n",
-    "    query_engine_tools=query_engine_tools,\n",
-    "    llm=llm,\n",
-    "    use_async=True,\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Try out Some Comparisons"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Generated 4 sub questions.\n",
-      "\u001b[1;3;38;2;237;90;200m[apple_2021_10k] Q: What are the deferred assets in 2021?\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2021_10k] Q: What are the deferred liabilities in 2021?\n",
-      "\u001b[0m\u001b[1;3;38;2;11;159;203m[apple_2020_10k] Q: What are the deferred assets in 2020?\n",
-      "\u001b[0m\u001b[1;3;38;2;155;135;227m[apple_2020_10k] Q: What are the deferred liabilities in 2020?\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2021_10k] A: $7,200\n",
-      "\u001b[0m\u001b[1;3;38;2;155;135;227m[apple_2020_10k] A: $10,138\n",
-      "\u001b[0m\u001b[1;3;38;2;237;90;200m[apple_2021_10k] A: $25,176 million\n",
-      "\u001b[0m\u001b[1;3;38;2;11;159;203m[apple_2020_10k] A: $19,336\n",
-      "\u001b[0m"
-     ]
-    }
-   ],
-   "source": [
-    "response = sub_query_engine.query(\n",
-    "    \"Can you compare and contrast the deferred assets and liabilities in 2021 with 2020?\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "In 2021, the deferred assets increased by $5,840 million compared to 2020, while the deferred liabilities decreased by $2,938 million in the same period.\n"
-     ]
-    }
-   ],
-   "source": [
-    "print(str(response))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Generated 2 sub questions.\n",
-      "\u001b[1;3;38;2;237;90;200m[apple_2021_10k] Q: What is the total number of RSUs in Apple's 2021 financials?\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2020_10k] Q: What is the total number of RSUs in Apple's 2020 financials?\n",
-      "\u001b[0m\u001b[1;3;38;2;237;90;200m[apple_2021_10k] A: The total number of RSUs in Apple's 2021 financials is 240,427.\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2020_10k] A: The total number of RSUs in Apple's 2020 financials is 310,778.\n",
-      "\u001b[0m"
-     ]
-    }
-   ],
-   "source": [
-    "response = sub_query_engine.query(\n",
-    "    \"Can you compare and contrast the total number of RSUs in 2021 and 2020?\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Generated 2 sub questions.\n",
-      "\u001b[1;3;38;2;237;90;200m[apple_2021_10k] Q: What are the risk factors mentioned in the 2021 financial report of Apple?\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2020_10k] Q: What are the risk factors mentioned in the 2020 financial report of Apple?\n",
-      "\u001b[0m\u001b[1;3;38;2;237;90;200m[apple_2021_10k] A: The risk factors mentioned in the 2021 financial report of Apple include risks related to COVID-19, macroeconomic and industry risks, political events, trade and international disputes, natural disasters, public health issues, industrial accidents, credit risk, fluctuations in foreign currency exchange rates, changes in tax rates and legislation, volatility in the price of the company's stock, and exposure to legal proceedings and claims.\n",
-      "\u001b[0m\u001b[1;3;38;2;90;149;237m[apple_2020_10k] A: The risk factors mentioned in the 2020 financial report of Apple include the impact of the COVID-19 pandemic on the company's business operations, financial condition, and stock price; global and regional economic conditions affecting demand for products and services; competition in global markets with rapid technological changes; potential disruptions in the supply chain due to industrial accidents or public health issues; information technology system failures or network disruptions affecting business operations; risks associated with confidential information security and potential unauthorized access; fluctuations in quarterly net sales and operating results due to various factors; stock price volatility impacting investor confidence and employee retention; financial performance risks related to changes in foreign currency exchange rates affecting sales and earnings.\n",
-      "\u001b[0m"
-     ]
-    }
-   ],
-   "source": [
-    "response = sub_query_engine.query(\n",
-    "    \"Can you compare and contrast the risk factors in 2021 vs. 2020?\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "The risk factors mentioned in the 2021 financial report of Apple include risks related to COVID-19, macroeconomic and industry risks, political events, trade and international disputes, natural disasters, public health issues, industrial accidents, credit risk, fluctuations in foreign currency exchange rates, changes in tax rates and legislation, volatility in the price of the company's stock, and exposure to legal proceedings and claims. In contrast, the risk factors mentioned in the 2020 financial report of Apple focused more on the impact of the COVID-19 pandemic on the company's business operations, financial condition, and stock price; global and regional economic conditions affecting demand for products and services; competition in global markets with rapid technological changes; potential disruptions in the supply chain due to industrial accidents or public health issues; information technology system failures or network disruptions affecting business operations; risks associated with confidential information security and potential unauthorized access; fluctuations in quarterly net sales and operating results due to various factors; stock price volatility impacting investor confidence and employee retention; financial performance risks related to changes in foreign currency exchange rates affecting sales and earnings.\n"
-     ]
-    }
-   ],
-   "source": [
-    "print(str(response))"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "llama_parse",
-   "language": "python",
-   "name": "llama_parse"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}

extract.md

@@ -1,9 +1,6 @@
 # LlamaExtract
 
-> **⚠️ EXPERIMENTAL**
-> This library is under active development with frequent breaking changes. APIs and functionality may change significantly between versions. If you're interested in being an early adopter, please contact us at [support@llamaindex.ai](mailto:support@llamaindex.ai) or join our [Discord](https://discord.com/invite/eN6D2HQ4aX).
-
-LlamaExtract provides a simple API for extracting structured data from unstructured documents like PDFs, text files and images (upcoming).
+LlamaExtract provides a simple API for extracting structured data from unstructured documents like PDFs, text files and images.
 
 ## Quick Start
 
@@ -100,11 +97,12 @@ _LlamaExtract only supports a subset of the JSON Schema specification._ While li
 be sufficient for a wide variety of use-cases.
 
 - All fields are required by default. Nullable fields must be explicitly marked as such,
-  using `"anyOf"` with a `"null"` type. See `"start_date"` field above.
-- Root node must be of type `"object"`.
+  using `anyOf` with a `null` type. See `"start_date"` field above.
+- Root node must be of type `object`.
 - Schema nesting must be limited to within 5 levels.
 - The important fields are key names/titles, type and description. Fields for
-  formatting, default values, etc. are not supported.
+  formatting, default values, etc. are **not supported**. If you need these, you can add the
+  restrictions to your field description and/or use a post-processing step. e.g. default values can be supported by making a field optional and then setting `"null"` values from the extraction result to the default value.
 - There are other restrictions on number of keys, size of the schema, etc. that you may
   hit for complex extraction use cases. In such cases, it is worth thinking how to restructure
   your extraction workflow to fit within these constraints, e.g. by extracting subset of fields
@@ -112,6 +110,23 @@ be sufficient for a wide variety of use-cases.
 
 ## Other Extraction APIs
 
+### Extraction over bytes or text
+
+You can use the `SourceText` class to extract from bytes or text directly without using a file. If passing the file bytes,
+you will need to pass the filename to the `SourceText` class.
+
+```python
+with open("resume.pdf", "rb") as f:
+    file_bytes = f.read()
+result = test_agent.extract(SourceText(file=file_bytes, filename="resume.pdf"))
+```
+
+```python
+result = test_agent.extract(
+    SourceText(text_content="Candidate Name: Jane Doe")
+)
+```
+
 ### Batch Processing
 
 Process multiple files asynchronously:
@@ -162,16 +177,18 @@ pip install llama-extract==0.1.0
 
 ## Tips & Best Practices
 
+At the core of LlamaExtract is the schema, which defines the structure of the data you want to extract from your documents.
+
 1. **Schema Design**:
 
    - Try to limit schema nesting to 3-4 levels.
    - Make fields optional when data might not always be present. Having required fields may force the model
      to hallucinate when these fields are not present in the documents.
-   - When you want to extract a variable number of entities, use an `array` type. Note that you cannot use
+   - When you want to extract a variable number of entities, use an `array` type. However, note that you cannot use
      an `array` type for the root node.
    - Use descriptive field names and detailed descriptions. Use descriptions to pass formatting
      instructions or few-shot examples.
-   - Start simple and iteratively build your schema to incorporate requirements.
+   - Above all, start simple and iteratively build your schema to incorporate requirements.
 
 2. **Running Extractions**:
    - Note that resetting `agent.schema` will not save the schema to the database,
@@ -180,6 +197,15 @@ pip install llama-extract==0.1.0
      part of `job.error` or `extraction_run.error` fields for debugging.
    - Consider async operations (`queue_extraction`) for large-scale extraction once you have finalized your schema.
 
+### Hitting "The response was too long to be processed" Error
+
+This implies that the extraction response is hitting output token limits of the LLM. In such cases, it is worth rethinking the design of your schema to enable a more efficient/scalable extraction. e.g.
+
+- Instead of one field that extracts a complex object, you can use multiple fields to distribute the extraction logic.
+- You can also use multiple schemas to extract different subsets of fields from the same document and merge them later.
+
+Another option (orthogonal to the above) is to break the document into smaller sections and extract from each section individually, when possible. LlamaExtract will in most cases be able to handle both document and schema chunking automatically, but there are cases where you may need to do this manually.
+
 ## Additional Resources
 
 - [Example Notebook](examples/resume_screening.ipynb) - Detailed walkthrough of resume parsing

llama_cloud_services/__init__.py

@@ -1,6 +1,7 @@
 from llama_cloud_services.parse import LlamaParse
 from llama_cloud_services.report import ReportClient, LlamaReport
 from llama_cloud_services.extract import LlamaExtract, ExtractionAgent
+from llama_cloud_services.constants import EU_BASE_URL
 
 __all__ = [
     "LlamaParse",
@@ -8,4 +9,5 @@ __all__ = [
     "LlamaReport",
     "LlamaExtract",
     "ExtractionAgent",
+    "EU_BASE_URL",
 ]

llama_cloud_services/beta/agent_data/__init__.py

@@ -0,0 +1,19 @@
+from .schema import (
+    TypedAgentData,
+    ExtractedData,
+    TypedAgentDataItems,
+    StatusType,
+    ExtractedT,
+    AgentDataT,
+)
+from .client import AsyncAgentDataClient
+
+__all__ = [
+    "TypedAgentData",
+    "AsyncAgentDataClient",
+    "ExtractedData",
+    "TypedAgentDataItems",
+    "StatusType",
+    "ExtractedT",
+    "AgentDataT",
+]

llama_cloud_services/beta/agent_data/client.py

@@ -0,0 +1,267 @@
+import os
+from typing import Dict, Generic, List, Optional, Type
+
+from llama_cloud import FilterOperation
+from llama_cloud.client import AsyncLlamaCloud
+from tenacity import (
+    WrappedFn,
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+import httpx
+
+from .schema import (
+    AgentDataT,
+    TypedAgentData,
+    TypedAgentDataItems,
+    TypedAggregateGroup,
+    TypedAggregateGroupItems,
+)
+
+
+def agent_data_retry(func: WrappedFn) -> WrappedFn:
+    """
+    Decorator that adds automatic retry logic to agent data API calls.
+
+    Applies exponential backoff retry strategy for common network-related exceptions:
+    - Up to 3 retry attempts
+    - Exponential wait time between 0.5s and 10s
+    - Retries on timeout, connection, and HTTP status errors
+
+    This ensures resilient API communication in distributed environments where
+    temporary network issues or service unavailability may occur.
+    """
+    return retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(min=0.5, max=10),
+        retry=retry_if_exception_type(
+            (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPStatusError)
+        ),
+    )(func)
+
+
+def get_default_agent_id() -> Optional[str]:
+    """
+    Retrieve the default agent ID from environment variables.
+
+    Returns:
+        The value of LLAMA_DEPLOY_DEPLOYMENT_NAME environment variable,
+        or None if not set
+
+    Note:
+        This provides a convenient way to configure agent ID globally
+        via environment variables instead of passing it explicitly
+        to each client instance.
+    """
+    return os.getenv("LLAMA_DEPLOY_DEPLOYMENT_NAME")
+
+
+class AsyncAgentDataClient(Generic[AgentDataT]):
+    """
+    Async client for managing agent-generated structured data with type safety.
+
+    This client provides a high-level interface for CRUD operations, searching, and
+    aggregation of structured data created by agents. It enforces type safety by
+    validating all data against a specified Pydantic model type.
+
+    The client is generic over AgentDataT, which must be a Pydantic BaseModel that
+    defines the structure of your agent's data output.
+
+    Example:
+        ```python
+        from pydantic import BaseModel
+        from llama_cloud.client import AsyncLlamaCloud
+        from llama_cloud_services.beta.agent_data import AsyncAgentDataClient
+
+        class ExtractedPerson(BaseModel):
+            name: str
+            age: int
+            email: str
+
+        # Initialize client
+        llama_client = AsyncLlamaCloud(token="your-api-key")
+        agent_client = AsyncAgentDataClient(
+            client=llama_client,
+            type=ExtractedPerson,
+            collection_name="extracted_people",
+            agent_url_id="person-extraction-agent"
+        )
+
+        # Create data
+        person = ExtractedPerson(name="John Doe", age=30, email="john@example.com")
+        result = await agent_client.create_agent_data(person)
+
+        # Search data
+        results = await agent_client.search_agent_data(
+            filter={"age": FilterOperation(gt=25)},
+            order_by="data.name",
+            page_size=20
+        )
+        ```
+
+    Type Parameters:
+        AgentDataT: Pydantic BaseModel type that defines the structure of agent data
+    """
+
+    def __init__(
+        self,
+        client: AsyncLlamaCloud,
+        type: Type[AgentDataT],
+        collection_name: str = "default",
+        agent_url_id: Optional[str] = None,
+    ):
+        """
+        Initialize the AsyncAgentDataClient.
+
+        Args:
+            client: AsyncLlamaCloud client instance for API communication
+            type: Pydantic BaseModel class that defines the data structure.
+                All agent data will be validated against this type.
+            collection_name: Named collection within the agent for organizing data.
+                Defaults to "default". Collections allow logical separation of
+                different data types or workflows within the same agent.
+            agent_url_id: Unique identifier for the agent. This normally appears in the
+                url of an agent within the llama cloud platform. If not provided,
+                will attempt to use the LLAMA_DEPLOY_DEPLOYMENT_NAME environment
+                variable. Data can only be added to an already existing agent in the
+                platform.
+
+        Raises:
+            ValueError: If agent_url_id is not provided and the
+                LLAMA_DEPLOY_DEPLOYMENT_NAME environment variable is not set
+
+        Note:
+            The client automatically applies retry logic to all API calls with
+            exponential backoff for timeout, connection, and HTTP status errors.
+        """
+
+        self.agent_url_id = agent_url_id or get_default_agent_id()
+        if not self.agent_url_id:
+            raise ValueError(
+                "Agent ID is required, or set the LLAMA_DEPLOY_DEPLOYMENT_NAME environment variable"
+            )
+
+        self.collection_name = collection_name
+        self.client = client
+        self.type = type
+
+    @agent_data_retry
+    async def get_agent_data(self, item_id: str) -> TypedAgentData[AgentDataT]:
+        raw_data = await self.client.beta.get_agent_data(
+            item_id=item_id,
+        )
+        return TypedAgentData.from_raw(raw_data, validator=self.type)
+
+    @agent_data_retry
+    async def create_agent_data(self, data: AgentDataT) -> TypedAgentData[AgentDataT]:
+        raw_data = await self.client.beta.create_agent_data(
+            agent_slug=self.agent_url_id,
+            collection=self.collection_name,
+            data=data.model_dump(),
+        )
+        return TypedAgentData.from_raw(raw_data, validator=self.type)
+
+    @agent_data_retry
+    async def update_agent_data(
+        self, item_id: str, data: AgentDataT
+    ) -> TypedAgentData[AgentDataT]:
+        raw_data = await self.client.beta.update_agent_data(
+            item_id=item_id,
+            data=data.model_dump(),
+        )
+        return TypedAgentData.from_raw(raw_data, validator=self.type)
+
+    @agent_data_retry
+    async def delete_agent_data(self, item_id: str) -> None:
+        await self.client.beta.delete_agent_data(item_id=item_id)
+
+    @agent_data_retry
+    async def search_agent_data(
+        self,
+        filter: Optional[Dict[str, Optional[FilterOperation]]] = None,
+        order_by: Optional[str] = None,
+        offset: Optional[int] = None,
+        page_size: Optional[int] = None,
+        include_total: bool = False,
+    ) -> TypedAgentDataItems[AgentDataT]:
+        """
+        Search agent data with filtering, sorting, and pagination.
+        Args:
+            filter: Filter conditions to apply to the search. Dict mapping field names to FilterOperation objects. Filters only by data fields
+                Examples:
+                - {"age": FilterOperation(gt=18)} - age greater than 18
+                - {"status": FilterOperation(eq="active")} - status equals "active"
+                - {"tags": FilterOperation(includes=["python", "ml"])} - tags include "python" or "ml"
+                - {"created_at": FilterOperation(gte="2024-01-01")} - created after date
+                - {"score": FilterOperation(lt=100, gte=50)} - score between 50 and 100
+            order_by: Comma delimited list of fields to sort results by. Can order by standard agent fields like created_at, or by data fields. Data fields must be prefixed with "data.". If ordering desceding, use a " desc" suffix.
+                Examples:
+                - "data.name desc, created_at" - sort by name in descending order, and then by creation date
+            page_size: Maximum number of items to return per page. Defaults to 10.
+            offset: Number of items to skip from the beginning. Defaults to 0.
+            include_total: Whether to include the total count in the response. Defaults to False to improve performance. It's recommended to only request on the first page.
+        """
+        raw = await self.client.beta.search_agent_data_api_v_1_beta_agent_data_search_post(
+            agent_slug=self.agent_url_id,
+            collection=self.collection_name,
+            filter=filter,
+            order_by=order_by,
+            offset=offset,
+            page_size=page_size,
+            include_total=include_total,
+        )
+        return TypedAgentDataItems(
+            items=[
+                TypedAgentData.from_raw(item, validator=self.type) for item in raw.items
+            ],
+            has_more=raw.next_page_token is not None,
+            total=raw.total_size,
+        )
+
+    @agent_data_retry
+    async def aggregate_agent_data(
+        self,
+        filter: Optional[Dict[str, Optional[FilterOperation]]] = None,
+        group_by: Optional[List[str]] = None,
+        count: Optional[bool] = None,
+        first: Optional[bool] = None,
+        order_by: Optional[str] = None,
+        offset: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> TypedAggregateGroupItems[AgentDataT]:
+        """
+        Aggregate agent data into groups according to the group_by fields.
+        Args:
+            filter: Filter conditions to apply to the search. Dict mapping field names to FilterOperation objects. Filters only by data fields
+                See search_agent_data for more details on filtering.
+            group_by: List of fields to group by. Groups strictly by equality. Can only group by data fields.
+                Examples:
+                - ["name"] - group by name
+                - ["name", "age"] - group by name and age
+            count: Whether to include the count of items in each group.
+            first: Whether to include the first item in each group.
+            order_by: Comma delimited list of fields to sort results by. See search_agent_data for more details on ordering.
+            offset: Number of groups to skip from the beginning. Defaults to 0.
+            page_size: Maximum number of groups to return per page.
+        """
+        raw = await self.client.beta.aggregate_agent_data_api_v_1_beta_agent_data_aggregate_post(
+            agent_slug=self.agent_url_id,
+            collection=self.collection_name,
+            page_size=page_size,
+            filter=filter,
+            order_by=order_by,
+            group_by=group_by,
+            count=count,
+            first=first,
+            offset=offset,
+        )
+        return TypedAggregateGroupItems(
+            items=[
+                TypedAggregateGroup.from_raw(item, validator=self.type)
+                for item in raw.items
+            ],
+            has_more=raw.next_page_token is not None,
+            total=raw.total_size,
+        )

llama_cloud_services/beta/agent_data/schema.py

@@ -0,0 +1,357 @@
+"""
+Agent Data API Schema Definitions
+
+This module provides typed wrappers around the raw LlamaCloud agent data API,
+enabling type-safe interactions with agent-generated structured data.
+
+The agent data API serves as a persistent storage system for structured data
+produced by LlamaCloud agents (particularly extraction agents). It provides
+CRUD operations, search capabilities, filtering, and aggregation functionality
+for managing agent-generated data at scale.
+
+Key Concepts:
+- Agent Slug: Unique identifier for an agent instance
+- Collection: Named grouping of data within an agent (defaults to "default"). Data within a collection should be of the same type.
+- Agent Data: Individual structured data records with metadata and timestamps
+
+Example Usage:
+    ```python
+    from pydantic import BaseModel
+
+    class Person(BaseModel):
+        name: str
+        age: int
+
+    client = AsyncAgentDataClient(
+        client=async_llama_cloud,
+        type=Person,
+        collection="people",
+        agent_url_id="my-extraction-agent-xyz"
+    )
+
+    # Create typed data
+    person = Person(name="John", age=30)
+    result = await client.create_agent_data(person)
+    print(result.data.name)  # Type-safe access
+    ```
+"""
+
+from datetime import datetime
+from llama_cloud.types.agent_data import AgentData
+from llama_cloud.types.aggregate_group import AggregateGroup
+from pydantic import BaseModel, Field
+from typing import (
+    Generic,
+    List,
+    Literal,
+    Optional,
+    Dict,
+    Type,
+    TypeVar,
+    Union,
+    Any,
+)
+
+
+# Type variable for user-defined data models
+AgentDataT = TypeVar("AgentDataT", bound=BaseModel)
+
+# Type variable for extracted data (can be dict or Pydantic model)
+ExtractedT = TypeVar("ExtractedT", bound=Union[BaseModel, dict])
+
+# Status types for extracted data workflow
+StatusType = Union[Literal["error", "accepted", "rejected", "in_review"], str]
+
+
+class TypedAgentData(BaseModel, Generic[AgentDataT]):
+    """
+    Type-safe wrapper for agent data records.
+
+    This class represents a single data record stored in the agent data API,
+    combining the structured data payload with metadata about when and where
+    it was created.
+
+    Attributes:
+        id: Unique identifier for this data record
+        agent_url_id: Identifier of the agent that created this data
+        collection: Named collection within the agent (used for organization)
+        data: The actual structured data payload (typed as AgentDataT)
+        created_at: Timestamp when the record was first created
+        updated_at: Timestamp when the record was last modified
+
+    Example:
+        ```python
+        # Access typed data
+        person_data: TypedAgentData[Person] = await client.get_agent_data(id)
+        print(person_data.data.name)  # Type-safe access to Person fields
+        print(person_data.created_at)  # Access metadata
+        ```
+    """
+
+    id: Optional[str] = Field(description="Unique identifier for this data record")
+    agent_url_id: str = Field(
+        description="Identifier of the agent that created this data"
+    )
+    collection: Optional[str] = Field(
+        description="Named collection within the agent for data organization"
+    )
+    data: AgentDataT = Field(description="The structured data payload")
+    created_at: Optional[datetime] = Field(description="When this record was created")
+    updated_at: Optional[datetime] = Field(
+        description="When this record was last modified"
+    )
+
+    @classmethod
+    def from_raw(
+        cls, raw_data: AgentData, validator: Type[AgentDataT]
+    ) -> "TypedAgentData[AgentDataT]":
+        """
+        Convert raw API response to typed agent data.
+
+        Args:
+            raw_data: Raw agent data from the API
+            validator: Pydantic model class to validate the data field
+
+        Returns:
+            TypedAgentData instance with validated data
+        """
+        data: AgentDataT = validator.model_validate(raw_data.data)
+
+        return cls(
+            id=raw_data.id,
+            agent_url_id=raw_data.agent_slug,
+            collection=raw_data.collection,
+            data=data,
+            created_at=raw_data.created_at,
+            updated_at=raw_data.updated_at,
+        )
+
+
+class TypedAgentDataItems(BaseModel, Generic[AgentDataT]):
+    """
+    Paginated collection of agent data records.
+
+    This class represents a page of search results from the agent data API,
+    providing both the data records and pagination metadata.
+
+    Attributes:
+        items: List of agent data records in this page
+        total: Total number of records matching the query (only present if requested)
+        has_more: Whether there are more records available beyond this page
+
+    Example:
+        ```python
+        # Search with pagination
+        results = await client.search_agent_data(
+            page_size=10,
+            include_total=True
+        )
+
+        for item in results.items:
+            print(item.data.name)
+
+        if results.has_more:
+            # Load next page
+            next_page = await client.search_agent_data(
+                page_size=10,
+                offset=10
+            )
+        ```
+    """
+
+    items: List[TypedAgentData[AgentDataT]] = Field(
+        description="List of agent data records in this page"
+    )
+    total: Optional[int] = Field(
+        description="Total number of records matching the query (only present if requested)"
+    )
+    has_more: bool = Field(
+        description="Whether there are more records available beyond this page"
+    )
+
+
+class ExtractedData(BaseModel, Generic[ExtractedT]):
+    """
+    Wrapper for extracted data with workflow status tracking.
+
+    This class is designed for extraction workflows where data goes through
+    review and approval stages. It maintains both the original extracted data
+    and the current state after any modifications.
+
+    Attributes:
+        original_data: The data as originally extracted from the source
+        data: The current state of the data (may differ from original after edits)
+        status: Current workflow status (in_review, accepted, rejected, error)
+        confidence: Confidence scores for individual fields (if available)
+
+    Status Workflow:
+        - "in_review": Initial state, awaiting human review
+        - "accepted": Data approved and ready for use
+        - "rejected": Data rejected, needs re-extraction or manual fix
+        - "error": Processing error occurred
+
+    Example:
+        ```python
+        # Create extracted data for review
+        extracted = ExtractedData.create(
+            extracted_data=person_data,
+            status="in_review",
+            confidence={"name": 0.95, "age": 0.87}
+        )
+
+        # Later, after review
+        if extracted.status == "accepted":
+            # Use the data
+            process_person(extracted.data)
+        ```
+    """
+
+    original_data: ExtractedT = Field(
+        description="The original data that was extracted from the document"
+    )
+    data: ExtractedT = Field(
+        description="The latest state of the data. Will differ if data has been updated"
+    )
+    status: Union[Literal["error", "accepted", "rejected", "in_review"], str] = Field(
+        description="The status of the extracted data"
+    )
+    confidence: Dict[str, Union[float, Dict]] = Field(
+        default_factory=dict,
+        description="Confidence scores, if any, for each primitive field in the original_data data",
+    )
+
+    @classmethod
+    def create(
+        cls,
+        extracted_data: ExtractedT,
+        status: StatusType = "in_review",
+        confidence: Optional[Dict[str, Union[float, Dict]]] = None,
+    ) -> "ExtractedData[ExtractedT]":
+        """
+        Create a new ExtractedData instance with sensible defaults.
+
+        Args:
+            extracted_data: The extracted data payload
+            status: Initial workflow status
+            confidence: Optional confidence scores for fields
+
+        Returns:
+            New ExtractedData instance ready for storage
+        """
+        return cls(
+            original_data=extracted_data,
+            data=extracted_data,
+            status=status,
+            confidence=confidence or {},
+        )
+
+
+class TypedAggregateGroup(BaseModel, Generic[AgentDataT]):
+    """
+    Represents a group of agent data records aggregated by common field values.
+
+    This class is used for grouping and analyzing agent data based on shared
+    characteristics. It's particularly useful for generating summaries and
+    statistics across large datasets.
+
+    Attributes:
+        group_key: The field values that define this group
+        count: Number of records in this group (if count aggregation was requested)
+        first_item: Representative data record from this group (if requested)
+
+    Example:
+        ```python
+        # Group by age range
+        groups = await client.aggregate_agent_data(
+            group_by=["age_range"],
+            count=True,
+            first=True
+        )
+
+        for group in groups.items:
+            print(f"Age range {group.group_key['age_range']}: {group.count} people")
+            if group.first_item:
+                print(f"Example: {group.first_item.name}")
+        ```
+    """
+
+    group_key: Dict[str, Any] = Field(
+        description="The field values that define this group"
+    )
+    count: Optional[int] = Field(
+        description="Number of records in this group (if count aggregation was requested)"
+    )
+    first_item: Optional[AgentDataT] = Field(
+        description="Representative data record from this group (if requested)"
+    )
+
+    @classmethod
+    def from_raw(
+        cls, raw_data: AggregateGroup, validator: Type[AgentDataT]
+    ) -> "TypedAggregateGroup[AgentDataT]":
+        """
+        Convert raw API response to typed aggregate group.
+
+        Args:
+            raw_data: Raw aggregate group from the API
+            validator: Pydantic model class to validate the first_item field
+
+        Returns:
+            TypedAggregateGroup instance with validated first_item
+        """
+        first_item: Optional[AgentDataT] = raw_data.first_item
+        if first_item is not None:
+            first_item = validator.model_validate(first_item)
+
+        return cls(
+            group_key=raw_data.group_key,
+            count=raw_data.count,
+            first_item=first_item,
+        )
+
+
+class TypedAggregateGroupItems(BaseModel, Generic[AgentDataT]):
+    """
+    Paginated collection of aggregate groups.
+
+    This class represents a page of aggregation results from the agent data API,
+    providing both the grouped data and pagination metadata.
+
+    Attributes:
+        items: List of aggregate groups in this page
+        total: Total number of groups matching the query (only present if requested)
+        has_more: Whether there are more groups available beyond this page
+
+    Example:
+        ```python
+        # Get first page of groups
+        results = await client.aggregate_agent_data(
+            group_by=["department"],
+            count=True,
+            page_size=20
+        )
+
+        for group in results.items:
+            dept = group.group_key["department"]
+            print(f"{dept}: {group.count} employees")
+
+        # Load more if needed
+        if results.has_more:
+            next_page = await client.aggregate_agent_data(
+                group_by=["department"],
+                count=True,
+                page_size=20,
+                offset=20
+            )
+        ```
+    """
+
+    items: List[TypedAggregateGroup[AgentDataT]] = Field(
+        description="List of aggregate groups in this page"
+    )
+    total: Optional[int] = Field(
+        description="Total number of groups matching the query (only present if requested)"
+    )
+    has_more: bool = Field(
+        description="Whether there are more groups available beyond this page"
+    )

llama_cloud_services/constants.py

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

llama_cloud_services/extract/__init__.py

@@ -1,3 +1,17 @@
-from llama_cloud_services.extract.extract import LlamaExtract, ExtractionAgent
+from llama_cloud_services.extract.extract import (
+    LlamaExtract,
+    ExtractConfig,
+    ExtractionAgent,
+    SourceText,
+    ExtractTarget,
+    ExtractMode,
+)
 
-__all__ = ["LlamaExtract", "ExtractionAgent"]
+__all__ = [
+    "LlamaExtract",
+    "ExtractionAgent",
+    "SourceText",
+    "ExtractConfig",
+    "ExtractTarget",
+    "ExtractMode",
+]

llama_cloud_services/extract/extract.py

@@ -1,31 +1,39 @@
 import asyncio
 import os
 import time
-from io import BufferedIOBase, BufferedReader, BytesIO
+from io import BufferedIOBase, BufferedReader, BytesIO, TextIOWrapper
 from pathlib import Path
 from typing import List, Optional, Type, Union, Coroutine, Any, TypeVar
+import secrets
 import warnings
 import httpx
 from pydantic import BaseModel
+from tenacity import (
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential_jitter,
+    AsyncRetrying,
+)
 from llama_cloud import (
     ExtractAgent as CloudExtractAgent,
-    ExtractAgentCreate,
     ExtractConfig,
     ExtractJob,
     ExtractJobCreate,
     ExtractRun,
-    ExtractSchemaValidateRequest,
-    ExtractAgentUpdate,
     File,
     ExtractMode,
     StatusEnum,
-    Project,
     ExtractTarget,
     LlamaExtractSettings,
     PaginatedExtractRunsResponse,
 )
 from llama_cloud.client import AsyncLlamaCloud
-from llama_cloud_services.extract.utils import JSONObjectType, augment_async_errors
+from llama_cloud.core.api_error import ApiError
+from llama_cloud_services.extract.utils import (
+    JSONObjectType,
+    augment_async_errors,
+    ExperimentalWarning,
+)
 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
@@ -34,15 +42,116 @@ from concurrent.futures import ThreadPoolExecutor
 
 T = TypeVar("T")
 
-FileInput = Union[str, Path, bytes, BufferedIOBase]
+
 SchemaInput = Union[JSONObjectType, Type[BaseModel]]
 
 DEFAULT_EXTRACT_CONFIG = ExtractConfig(
     extraction_target=ExtractTarget.PER_DOC,
-    extraction_mode=ExtractMode.ACCURATE,
+    extraction_mode=ExtractMode.BALANCED,
 )
 
 
+def _is_retryable_error(exception: BaseException) -> bool:
+    """Check if an exception is retryable."""
+    if isinstance(exception, ApiError):
+        return exception.status_code in (502, 503, 504, 425, 408)
+    elif isinstance(
+        exception, (httpx.HTTPStatusError, httpx.RequestError, httpx.TimeoutException)
+    ):
+        return True
+    return False
+
+
+class SourceText:
+    def __init__(
+        self,
+        *,
+        file: Union[bytes, BufferedIOBase, TextIOWrapper, str, Path, None] = None,
+        text_content: Optional[str] = None,
+        filename: Optional[str] = None,
+    ):
+        self.file = file
+        self.filename = filename
+        self.text_content = text_content
+        self._validate()
+
+    def _validate(self) -> None:
+        """Ensure filename is provided when needed."""
+        if not ((self.file is None) ^ (self.text_content is None)):
+            raise ValueError("Either file or text_content must be provided.")
+        if self.text_content is not None:
+            if not self.filename:
+                random_hex = secrets.token_hex(4)
+                self.filename = f"text_input_{random_hex}.txt"
+            return
+
+        if isinstance(self.file, (bytes, BufferedIOBase, TextIOWrapper)):
+            if not self.filename and hasattr(self.file, "name"):
+                self.filename = os.path.basename(str(self.file.name))
+            elif not hasattr(self.file, "name") and self.filename is None:
+                raise ValueError(
+                    "filename must be provided when file is bytes or a file-like object without a name"
+                )
+        elif isinstance(self.file, (str, Path)):
+            if not self.filename:
+                self.filename = os.path.basename(str(self.file))
+        else:
+            raise ValueError(f"Unsupported file type: {type(self.file)}")
+
+
+FileInput = Union[str, Path, BufferedIOBase, SourceText]
+
+
+def run_in_thread(
+    coro: Coroutine[Any, Any, T],
+    thread_pool: ThreadPoolExecutor,
+    verify: bool,
+    httpx_timeout: float,
+    client_wrapper: Any,
+) -> T:
+    """Run coroutine in a thread with proper client management."""
+
+    async def wrapped_coro() -> T:
+        client = httpx.AsyncClient(
+            verify=verify,
+            timeout=httpx_timeout,
+            limits=httpx.Limits(max_keepalive_connections=100, max_connections=100),
+        )
+        original_client = client_wrapper.httpx_client
+        try:
+            client_wrapper.httpx_client = client
+            return await coro
+        finally:
+            client_wrapper.httpx_client = original_client
+            await client.aclose()
+
+    def run_coro() -> T:
+        try:
+            return asyncio.run(wrapped_coro())
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Request timed out: {str(e)}") from e
+        except httpx.NetworkError as e:
+            raise ConnectionError(f"Network error: {str(e)}") from e
+
+    return thread_pool.submit(run_coro).result()
+
+
+def _extraction_config_warning(config: ExtractConfig) -> None:
+    if config.use_reasoning:
+        warnings.warn(
+            "`use_reasoning` is an experimental feature. Results will be available in "
+            "the `extraction_metadata` field for the extraction run.",
+            ExperimentalWarning,
+        )
+    if config.cite_sources:
+        warnings.warn(
+            "`cite_sources` is an experimental feature. This may greatly increase the "
+            "size of the response, and slow down the extraction. Results will be "
+            "available in the `extraction_metadata` field for the extraction run.",
+            ExperimentalWarning,
+        )
+
+
 class ExtractionAgent:
     """Class representing a single extraction agent with methods for extraction operations."""
 
@@ -77,31 +186,6 @@ class ExtractionAgent:
             max_workers=min(10, (os.cpu_count() or 1) + 4)
         )
 
-    def _run_in_thread(self, coro: Coroutine[Any, Any, T]) -> T:
-        """Run coroutine in a separate thread to avoid event loop issues"""
-
-        def run_coro() -> T:
-            async def wrapped_coro() -> T:
-                # Get the original client to preserve its configuration
-                original_client = self._client._client_wrapper.httpx_client
-
-                # Create a new client with the same configuration as the original
-                async with httpx.AsyncClient(
-                    verify=self.verify,
-                    timeout=self.httpx_timeout,
-                ) as client:
-                    # Temporarily replace the client
-                    self._client._client_wrapper.httpx_client = client
-                    try:
-                        return await coro
-                    finally:
-                        # Restore the original client
-                        self._client._client_wrapper.httpx_client = original_client
-
-            return asyncio.run(wrapped_coro())
-
-        return self._thread_pool.submit(run_coro).result()
-
     @property
     def id(self) -> str:
         return self._agent.id
@@ -128,7 +212,7 @@ class ExtractionAgent:
             )
         validated_schema = self._run_in_thread(
             self._client.llama_extract.validate_extraction_schema(
-                request=ExtractSchemaValidateRequest(data_schema=processed_schema)
+                data_schema=processed_schema
             )
         )
         self._data_schema = validated_schema.data_schema
@@ -139,58 +223,139 @@ class ExtractionAgent:
 
     @config.setter
     def config(self, config: ExtractConfig) -> None:
+        _extraction_config_warning(config)
         self._config = config
 
-    async def _upload_file(self, file_input: FileInput) -> File:
-        """Upload a file for extraction."""
-        if isinstance(file_input, BufferedIOBase):
-            upload_file = file_input
-        elif isinstance(file_input, bytes):
-            upload_file = BytesIO(file_input)
-        elif isinstance(file_input, (str, Path)):
-            upload_file = open(file_input, "rb")
-        else:
-            raise ValueError(
-                "file_input must be either a file path string, file bytes, or buffer object"
-            )
+    def _run_in_thread(self, coro: Coroutine[Any, Any, T]) -> T:
+        """Run coroutine in a separate thread to avoid event loop issues"""
+        return run_in_thread(
+            coro,
+            self._thread_pool,
+            self.verify,  # type: ignore
+            self.httpx_timeout,  # type: ignore
+            self._client._client_wrapper,
+        )
 
+    async def upload_file(self, file_input: SourceText) -> File:
+        """Upload a file for extraction.
+
+        Args:
+            file_input: The file to upload (path, bytes, or file-like object)
+
+        Raises:
+            ValueError: If filename is not provided for bytes input or for file-like objects
+                       without a name attribute.
+        """
+        file_contents: Optional[Union[BufferedIOBase, BytesIO]] = None
         try:
+            if file_input.text_content is not None:
+                # Handle direct text content
+                file_contents = BytesIO(file_input.text_content.encode("utf-8"))
+            elif isinstance(file_input.file, TextIOWrapper):
+                # Handle text-based IO objects
+                file_contents = BytesIO(file_input.file.read().encode("utf-8"))
+            elif isinstance(file_input.file, (str, Path)):
+                # Handle file paths
+                file_contents = open(file_input.file, "rb")
+            elif isinstance(file_input.file, bytes):
+                # Handle bytes
+                file_contents = BytesIO(file_input.file)
+            elif isinstance(file_input.file, BufferedIOBase):
+                # Handle binary IO objects
+                file_contents = file_input.file
+            else:
+                raise ValueError(f"Unsupported file type: {type(file_input.file)}")
+
+            # Add name attribute to file object if needed
+            if not hasattr(file_contents, "name"):
+                file_contents.name = file_input.filename  # type: ignore
+
             return await self._client.files.upload_file(
-                project_id=self._project_id, upload_file=upload_file
+                project_id=self._project_id, upload_file=file_contents
             )
         finally:
-            if isinstance(upload_file, BufferedReader):
-                upload_file.close()
+            if file_contents is not None and isinstance(file_contents, BufferedReader):
+                file_contents.close()
+
+    async def _upload_file(self, file_input: FileInput) -> File:
+        source_text = None
+        if isinstance(file_input, SourceText):
+            source_text = file_input
+        elif isinstance(file_input, (str, Path)):
+            path = Path(file_input)
+            source_text = SourceText(file=path, filename=path.name)
+        else:
+            # Try to get filename from the file object if not provided
+            filename = None
+            if hasattr(file_input, "name"):
+                filename = os.path.basename(str(file_input.name))
+            if filename is None:
+                raise ValueError(
+                    "Use SourceText to provide filename when uploading bytes or file-like objects."
+                )
+
+            warnings.warn(
+                "Use SourceText instead of bytes or file-like objects",
+                DeprecationWarning,
+            )
+            source_text = SourceText(file=file_input, filename=filename)
+
+        return await self.upload_file(source_text)
+
+    async def _get_job_with_retry(self, job_id: str) -> ExtractJob:
+        """Get job with retry logic for transient errors."""
+        async for attempt in AsyncRetrying(
+            retry=retry_if_exception(_is_retryable_error),
+            stop=stop_after_attempt(5),
+            wait=wait_exponential_jitter(initial=1, max=60, jitter=5),
+            reraise=True,
+        ):
+            with attempt:
+                return await self._client.llama_extract.get_job(job_id=job_id)
+
+    async def _get_run_with_retry(self, job_id: str) -> ExtractRun:
+        """Get extraction run with retry logic for transient errors."""
+        async for attempt in AsyncRetrying(
+            retry=retry_if_exception(_is_retryable_error),
+            stop=stop_after_attempt(3),
+            wait=wait_exponential_jitter(initial=1, max=20, jitter=3),
+            reraise=True,
+        ):
+            with attempt:
+                return await self._client.llama_extract.get_run_by_job_id(job_id=job_id)
 
     async def _wait_for_job_result(self, job_id: str) -> Optional[ExtractRun]:
         """Wait for and return the results of an extraction job."""
         start = time.perf_counter()
         tries = 0
+
         while True:
             await asyncio.sleep(self.check_interval)
             tries += 1
-            job = await self._client.llama_extract.get_job(
-                job_id=job_id,
-            )
 
-            if job.status == StatusEnum.SUCCESS:
-                return await self._client.llama_extract.get_run_by_job_id(
-                    job_id=job_id,
-                )
-            elif job.status == StatusEnum.PENDING:
-                end = time.perf_counter()
-                if end - start > self.max_timeout:
-                    raise Exception(f"Timeout while extracting the file: {job_id}")
-                if self._verbose and tries % 10 == 0:
-                    print(".", end="", flush=True)
-                continue
-            else:
-                warnings.warn(
-                    f"Failure in job: {job_id}, status: {job.status}, error: {job.error}"
-                )
-                return await self._client.llama_extract.get_run_by_job_id(
-                    job_id=job_id,
-                )
+            try:
+                job = await self._get_job_with_retry(job_id)
+
+                if job.status == StatusEnum.SUCCESS:
+                    return await self._get_run_with_retry(job_id)
+                elif job.status == StatusEnum.PENDING:
+                    end = time.perf_counter()
+                    if end - start > self.max_timeout:
+                        raise Exception(f"Timeout while extracting the file: {job_id}")
+                    if self._verbose and tries % 10 == 0:
+                        print(".", end="", flush=True)
+                    continue
+                else:
+                    warnings.warn(
+                        f"Failure in job: {job_id}, status: {job.status}, error: {job.error}"
+                    )
+                    return await self._get_run_with_retry(job_id)
+
+            except Exception as e:
+                # If we get a non-retryable error or all retries are exhausted, re-raise
+                if self._verbose:
+                    print(f"\nError in job polling for {job_id}: {e}")
+                raise e
 
     def save(self) -> None:
         """Persist the extraction agent's schema and config to the database.
@@ -201,14 +366,12 @@ class ExtractionAgent:
         self._agent = self._run_in_thread(
             self._client.llama_extract.update_extraction_agent(
                 extraction_agent_id=self.id,
-                request=ExtractAgentUpdate(
-                    data_schema=self.data_schema,
-                    config=self.config,
-                ),
+                data_schema=self.data_schema,
+                config=self.config,
             )
         )
 
-    async def _queue_extraction_test(
+    async def _run_extraction_test(
         self,
         files: Union[FileInput, List[FileInput]],
         extract_settings: LlamaExtractSettings,
@@ -242,7 +405,7 @@ class ExtractionAgent:
 
         job_tasks = [run_job(file) for file in uploaded_files]
         with augment_async_errors():
-            extract_jobs = await run_jobs(
+            extract_results = await run_jobs(
                 job_tasks,
                 workers=self.num_workers,
                 desc="Running extraction jobs",
@@ -250,15 +413,13 @@ class ExtractionAgent:
             )
 
         if self._verbose:
-            for file, job in zip(files, extract_jobs):
+            for file, job in zip(files, extract_results):
                 file_repr = (
                     str(file) if isinstance(file, (str, Path)) else "<bytes/buffer>"
                 )
-                print(
-                    f"Queued file extraction for file {file_repr} under job_id {job.id}"
-                )
+                print(f"Running extraction for file {file_repr} under job_id {job.id}")
 
-        return extract_jobs[0] if single_file else extract_jobs
+        return extract_results[0] if single_file else extract_results
 
     async def queue_extraction(
         self,
@@ -420,6 +581,14 @@ class ExtractionAgent:
     def __repr__(self) -> str:
         return f"ExtractionAgent(id={self.id}, name={self.name})"
 
+    def __del__(self) -> None:
+        """Cleanup resources properly."""
+        try:
+            if hasattr(self, "_thread_pool"):
+                self._thread_pool.shutdown(wait=True)
+        except Exception:
+            pass  # Suppress exceptions during cleanup
+
 
 class LlamaExtract(BaseComponent):
     """Factory class for creating and managing extraction agents."""
@@ -490,7 +659,7 @@ class LlamaExtract(BaseComponent):
             httpx_timeout=httpx_timeout,
             verbose=verbose,
         )
-        self._httpx_client = httpx.AsyncClient(verify=verify, timeout=httpx_timeout)
+        self._httpx_client = httpx.AsyncClient(verify=verify, timeout=httpx_timeout)  # type: ignore
         self.verify = verify
         self.httpx_timeout = httpx_timeout
 
@@ -502,51 +671,20 @@ class LlamaExtract(BaseComponent):
         self._thread_pool = ThreadPoolExecutor(
             max_workers=min(10, (os.cpu_count() or 1) + 4)
         )
-        # Fetch default project id if not provided
         if not project_id:
             project_id = os.getenv("LLAMA_CLOUD_PROJECT_ID", None)
-            if not project_id:
-                print("No project_id provided, fetching default project.")
-                projects: List[Project] = self._run_in_thread(
-                    self._async_client.projects.list_projects()
-                )
-                default_project = [p for p in projects if p.is_default]
-                if not default_project:
-                    raise ValueError(
-                        "No default project found. Please provide a project_id."
-                    )
-                project_id = default_project[0].id
-
         self._project_id = project_id
         self._organization_id = organization_id
 
     def _run_in_thread(self, coro: Coroutine[Any, Any, T]) -> T:
         """Run coroutine in a separate thread to avoid event loop issues"""
-
-        def run_coro() -> T:
-            # Create a new client for this thread
-            async def wrapped_coro() -> T:
-                assert (
-                    self._httpx_client is not None
-                ), "httpx_client should be initialized"
-                # Create a new client with the same configuration as the original
-                async with httpx.AsyncClient(
-                    verify=self.verify,
-                    timeout=self.httpx_timeout,
-                ) as client:
-                    # Temporarily replace the client
-                    self._async_client._client_wrapper.httpx_client = client
-                    try:
-                        return await coro
-                    finally:
-                        # Restore the original client
-                        self._async_client._client_wrapper.httpx_client = (
-                            self._httpx_client
-                        )
-
-            return asyncio.run(wrapped_coro())
-
-        return self._thread_pool.submit(run_coro).result()
+        return run_in_thread(
+            coro,
+            self._thread_pool,
+            self.verify,  # type: ignore
+            self.httpx_timeout,  # type: ignore
+            self._async_client._client_wrapper,
+        )
 
     def create_agent(
         self,
@@ -564,6 +702,10 @@ class LlamaExtract(BaseComponent):
         Returns:
             ExtractionAgent: The created extraction agent
         """
+        if config is not None:
+            _extraction_config_warning(config)
+        else:
+            config = DEFAULT_EXTRACT_CONFIG
 
         if isinstance(data_schema, dict):
             data_schema = data_schema
@@ -578,11 +720,9 @@ class LlamaExtract(BaseComponent):
             self._async_client.llama_extract.create_extraction_agent(
                 project_id=self._project_id,
                 organization_id=self._organization_id,
-                request=ExtractAgentCreate(
-                    name=name,
-                    data_schema=data_schema,
-                    config=config or DEFAULT_EXTRACT_CONFIG,
-                ),
+                name=name,
+                data_schema=data_schema,
+                config=config,
             )
         )
 
@@ -596,6 +736,8 @@ class LlamaExtract(BaseComponent):
             num_workers=self.num_workers,
             show_progress=self.show_progress,
             verbose=self.verbose,
+            verify=self.verify,
+            httpx_timeout=self.httpx_timeout,
         )
 
     def get_agent(
@@ -683,6 +825,14 @@ class LlamaExtract(BaseComponent):
             )
         )
 
+    def __del__(self) -> None:
+        """Cleanup resources properly."""
+        try:
+            if hasattr(self, "_thread_pool"):
+                self._thread_pool.shutdown(wait=True)
+        except Exception:
+            pass  # Suppress exceptions during cleanup
+
 
 if __name__ == "__main__":
     from dotenv import load_dotenv

llama_cloud_services/extract/utils.py

@@ -32,3 +32,9 @@ def augment_async_errors() -> Generator[None, None, None]:
 
 JSONType = Union[Dict[str, Any], List[Any], str, int, float, bool, None]
 JSONObjectType = Dict[str, JSONType]
+
+
+class ExperimentalWarning(Warning):
+    """Warning for experimental features."""
+
+    pass

llama_cloud_services/parse/__init__.py

@@ -1,3 +1,8 @@
-from llama_cloud_services.parse.base import LlamaParse, ResultType
+from llama_cloud_services.parse.base import (
+    LlamaParse,
+    ResultType,
+    ParsingMode,
+    FailedPageMode,
+)
 
-__all__ = ["LlamaParse", "ResultType"]
+__all__ = ["LlamaParse", "ResultType", "ParsingMode", "FailedPageMode"]

llama_cloud_services/parse/base.py

@@ -2,27 +2,41 @@ import asyncio
 import mimetypes
 import os
 import time
+import warnings
 from contextlib import asynccontextmanager
 from copy import deepcopy
+from enum import Enum
 from io import BufferedIOBase
 from pathlib import Path, PurePath, PurePosixPath
-from typing import Any, AsyncGenerator, Dict, List, Optional, Union
+from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple, Union
 from urllib.parse import urlparse
 
 import httpx
 from fsspec import AbstractFileSystem
 from llama_index.core.async_utils import asyncio_run, run_jobs
-from llama_index.core.bridge.pydantic import Field, PrivateAttr, field_validator
+from llama_index.core.bridge.pydantic import (
+    Field,
+    PrivateAttr,
+    field_validator,
+    model_validator,
+)
 from llama_index.core.constants import DEFAULT_BASE_URL
 from llama_index.core.readers.base import BasePydanticReader
 from llama_index.core.readers.file.base import get_default_fs
 from llama_index.core.schema import Document
 
+from llama_cloud_services.utils import check_extra_params
+from llama_cloud_services.parse.types import JobResult
 from llama_cloud_services.parse.utils import (
     SUPPORTED_FILE_TYPES,
     ResultType,
+    ParsingMode,
+    FailedPageMode,
+    expand_target_pages,
     nest_asyncio_err,
     nest_asyncio_msg,
+    make_api_request,
+    partition_pages,
 )
 
 # can put in a path to the file or the file bytes itself
@@ -52,6 +66,44 @@ def build_url(
     return base_url
 
 
+class JobFailedException(Exception):
+    """Parse job failed exception."""
+
+    def __init__(
+        self,
+        job_id: str,
+        status: str,
+        error_code: Optional[str] = None,
+        error_message: Optional[str] = None,
+    ):
+        exception_str = (
+            f"Job ID: {job_id} failed with status: {status}, "
+            f'Error code: {error_code or "No error code found"}, '
+            f'Error message: {error_message or "No error message found"}'
+        )
+        super().__init__(exception_str)
+        self.job_id = job_id
+        self.status = status
+        self.error_code = error_code
+        self.error_message = error_message
+
+    @classmethod
+    def from_result(cls, result_json: Dict[str, Any]) -> "JobFailedException":
+        job_id = result_json["id"]
+        status = result_json["status"]
+        error_code = result_json.get("error_code")
+        error_message = result_json.get("error_message")
+        return cls(job_id, status, error_code=error_code, error_message=error_message)
+
+
+class BackoffPattern(str, Enum):
+    """Backoff pattern for polling."""
+
+    CONSTANT = "constant"
+    LINEAR = "linear"
+    EXPONENTIAL = "exponential"
+
+
 class LlamaParse(BasePydanticReader):
     """A smart-parser for files."""
 
@@ -78,6 +130,15 @@ class LlamaParse(BasePydanticReader):
         description="The interval in seconds to check if the parsing is done.",
     )
 
+    backoff_pattern: BackoffPattern = Field(
+        default=BackoffPattern.LINEAR,
+        description="Controls the backoff pattern when retrying failed requests: 'constant', 'linear', or 'exponential'.",
+    )
+    max_check_interval: int = Field(
+        default=5,
+        description="Maximum interval in seconds between polling attempts when checking job status.",
+    )
+
     custom_client: Optional[httpx.AsyncClient] = Field(
         default=None, description="A custom HTTPX client to use for sending requests."
     )
@@ -93,7 +154,7 @@ class LlamaParse(BasePydanticReader):
     num_workers: int = Field(
         default=4,
         gt=0,
-        lt=10,
+        lt=20,
         description="The number of workers to use sending API requests for parsing.",
     )
     result_type: ResultType = Field(
@@ -123,6 +184,10 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="If set to true, the parser will automatically select the best mode to extract text from documents based on the rules provide. Will use the 'accurate' default mode by default and will upgrade page that match the rule to Premium mode.",
     )
+    auto_mode_configuration_json: Optional[str] = Field(
+        default=None,
+        description="A JSON string containing the configuration for the auto mode. If set, the parser will use the provided configuration for the auto mode.",
+    )
     auto_mode_trigger_on_image_in_page: Optional[bool] = Field(
         default=False,
         description="If auto_mode is set to true, the parser will upgrade the page that contain an image to Premium mode.",
@@ -167,7 +232,10 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="The top margin of the bounding box to use to extract text from documents expressed as a float between 0 and 1 representing the percentage of the page height.",
     )
-
+    compact_markdown_table: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will output compact markdown table (without trailing spaces in cells).",
+    )
     continuous_mode: Optional[bool] = Field(
         default=False,
         description="Parse documents continuously, leading to better results on documents where tables span across two pages.",
@@ -205,6 +273,10 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="Whether to guess the sheet names of the xlsx file.",
     )
+    high_res_ocr: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will use high resolution OCR to extract text from images. This will increase the accuracy of the parsing job, but reduce the speed.",
+    )
     html_make_all_elements_visible: Optional[bool] = Field(
         default=False,
         description="If set to true, when parsing HTML the parser will consider all elements display not element as display block.",
@@ -244,6 +316,10 @@ class LlamaParse(BasePydanticReader):
     language: Optional[str] = Field(
         default="en", description="The language of the text to parse."
     )
+    markdown_table_multiline_header_separator: Optional[str] = Field(
+        default=None,
+        description="The separator to use to split the header of the markdown table into multiple lines. Default is: <br/>",
+    )
     max_pages: Optional[int] = Field(
         default=None,
         description="The maximum number of pages to extract text from documents. If set to 0 or not set, all pages will be that should be extracted will be extracted (can work in combination with targetPages).",
@@ -264,6 +340,14 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="If set to true, the parser will output tables as HTML in the markdown.",
     )
+    outlined_table_extraction: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will use a dedicated approach to extract tables with outlined cells. This is useful for documents with spreadsheet-like tables where cells are outlined with borders. This could lead to false positives, so use with caution.",
+    )
+    page_error_tolerance: Optional[float] = Field(
+        default=None,
+        description="The error tolerance for the number of pages with error in a doc (percentage express as 0-1). If we fail to parse a greater percentage of pages than the tolerance value we fail the job.",
+    )
     page_prefix: Optional[str] = Field(
         default=None,
         description="A templated prefix to add to the beginning of each page. If it contain `{page_number}`, it will be replaced by the page number.",
@@ -276,7 +360,7 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="A templated suffix to add to the beginning of each page. If it contain `{page_number}`, it will be replaced by the page number.",
     )
-    parsing_mode: Optional[str] = Field(
+    parse_mode: Optional[Union[ParsingMode, str]] = Field(
         default=None,
         description="The parsing mode to use, see ParsingMode enum for possible values ",
     )
@@ -284,6 +368,26 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="Use our best parser mode if set to True.",
     )
+    preset: Optional[str] = Field(
+        default=None,
+        description="The preset to use for the parser. If set, the parser will use the preset configuration. See LlamaParse documentation for available presets. Preset override most other parameters.",
+    )
+    preserve_layout_alignment_across_pages: Optional[bool] = Field(
+        default=False,
+        description="Preserve grid alignment across page in text mode.",
+    )
+    replace_failed_page_mode: Optional[FailedPageMode] = Field(
+        default=None,
+        description="The mode to use to replace the failed page, see FailedPageMode enum for possible value. If set, the parser will replace the failed page with the specified mode. If not set, the default mode (raw_text) will be used.",
+    )
+    replace_failed_page_with_error_message_prefix: Optional[str] = Field(
+        default=None,
+        description="A prefix to add before error message in failed pages. If not set, no prefix will be used.",
+    )
+    replace_failed_page_with_error_message_suffix: Optional[str] = Field(
+        default=None,
+        description="A suffix to add after error message in failed pages. If not set, no suffix will be used.",
+    )
     skip_diagonal_text: Optional[bool] = Field(
         default=False,
         description="If set to true, the parser will ignore diagonal text (when the text rotation in degrees modulo 90 is not 0).",
@@ -353,10 +457,42 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="The model name for the vendor multimodal API.",
     )
+    model: Optional[str] = Field(
+        default=None,
+        description="The document model name to be used with `parse_with_agent`.",
+    )
     webhook_url: Optional[str] = Field(
         default=None,
         description="A URL that needs to be called at the end of the parsing job.",
     )
+    partition_pages: Optional[int] = Field(
+        default=None,
+        description="If set, documents will automatically be partitioned into segments containing the specified number of pages at most. Parsing will be split into separate jobs for each partition segment. Can be used in combination with targetPages and maxPages.",
+    )
+    hide_headers: Optional[bool] = Field(
+        default=False,
+        description="Whether to hide page header in output markdown.",
+    )
+    hide_footers: Optional[bool] = Field(
+        default=False,
+        description="Whether to hide page footers in output markdown.",
+    )
+    page_header_suffix: Optional[str] = Field(
+        default=None,
+        description="A suffix to add to the page header in the output markdown.",
+    )
+    page_header_prefix: Optional[str] = Field(
+        default=None,
+        description="A prefix to add to the page header in the output markdown.",
+    )
+    page_footer_suffix: Optional[str] = Field(
+        default=None,
+        description="A suffix to add to the page footer in the output markdown.",
+    )
+    page_footer_prefix: Optional[str] = Field(
+        default=None,
+        description="A prefix to add to the page footer in the output markdown.",
+    )
 
     # Deprecated
     bounding_box: Optional[str] = Field(
@@ -396,6 +532,21 @@ class LlamaParse(BasePydanticReader):
         description="Whether to use the vendor multimodal API.",
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def warn_extra_params(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        extra_params, suggestions = check_extra_params(cls, data)
+        if extra_params:
+            suggestions = [f"\n - {suggestion}" for suggestion in suggestions]
+            suggestions_str = "".join(suggestions)
+            warnings.warn(
+                "The following parameters are unused: "
+                + ", ".join(extra_params)
+                + f".\n{suggestions_str}",
+            )
+
+        return data
+
     @field_validator("api_key", mode="before", check_fields=True)
     @classmethod
     def validate_api_key(cls, v: str) -> str:
@@ -483,6 +634,7 @@ class LlamaParse(BasePydanticReader):
         file_input: FileInput,
         extra_info: Optional[dict] = None,
         fs: Optional[AbstractFileSystem] = None,
+        partition_target_pages: Optional[str] = None,
     ) -> str:
         files = None
         file_handle = None
@@ -533,6 +685,9 @@ class LlamaParse(BasePydanticReader):
         if self.auto_mode:
             data["auto_mode"] = self.auto_mode
 
+        if self.auto_mode_configuration_json is not None:
+            data["auto_mode_configuration_json"] = self.auto_mode_configuration_json
+
         if self.auto_mode_trigger_on_image_in_page:
             data[
                 "auto_mode_trigger_on_image_in_page"
@@ -577,6 +732,9 @@ class LlamaParse(BasePydanticReader):
         if self.bbox_top is not None:
             data["bbox_top"] = self.bbox_top
 
+        if self.compact_markdown_table:
+            data["compact_markdown_table"] = self.compact_markdown_table
+
         if self.complemental_formatting_instruction:
             print(
                 "WARNING: complemental_formatting_instruction is deprecated and may be remove in a future release. Use system_prompt, system_prompt_append or user_prompt instead."
@@ -627,6 +785,9 @@ class LlamaParse(BasePydanticReader):
         if self.html_make_all_elements_visible:
             data["html_make_all_elements_visible"] = self.html_make_all_elements_visible
 
+        if self.high_res_ocr:
+            data["high_res_ocr"] = self.high_res_ocr
+
         if self.html_remove_fixed_elements:
             data["html_remove_fixed_elements"] = self.html_remove_fixed_elements
 
@@ -689,9 +850,33 @@ class LlamaParse(BasePydanticReader):
         if self.output_tables_as_HTML:
             data["output_tables_as_HTML"] = self.output_tables_as_HTML
 
+        if self.outlined_table_extraction:
+            data["outlined_table_extraction"] = self.outlined_table_extraction
+
+        if self.page_error_tolerance is not None:
+            data["page_error_tolerance"] = self.page_error_tolerance
+
         if self.page_prefix is not None:
             data["page_prefix"] = self.page_prefix
 
+        if self.hide_headers:
+            data["hide_headers"] = self.hide_headers
+
+        if self.hide_footers:
+            data["hide_footers"] = self.hide_footers
+
+        if self.page_header_suffix is not None:
+            data["page_header_suffix"] = self.page_header_suffix
+
+        if self.page_header_prefix is not None:
+            data["page_header_prefix"] = self.page_header_prefix
+
+        if self.page_footer_suffix is not None:
+            data["page_footer_suffix"] = self.page_footer_suffix
+
+        if self.page_footer_prefix is not None:
+            data["page_footer_prefix"] = self.page_footer_prefix
+
         # only send page separator to server if it is not None
         # as if a null, "" string is sent the server will then ignore the page separator instead of using the default
         if self.page_separator is not None:
@@ -706,9 +891,33 @@ class LlamaParse(BasePydanticReader):
             )
             data["parsing_instruction"] = self.parsing_instruction
 
+        if self.parse_mode:
+            data["parse_mode"] = self.parse_mode
+
         if self.premium_mode:
             data["premium_mode"] = self.premium_mode
 
+        if self.preserve_layout_alignment_across_pages:
+            data[
+                "preserve_layout_alignment_across_pages"
+            ] = self.preserve_layout_alignment_across_pages
+
+        if self.preset is not None:
+            data["preset"] = self.preset
+
+        if self.replace_failed_page_mode is not None:
+            data["replace_failed_page_mode"] = self.replace_failed_page_mode.value
+
+        if self.replace_failed_page_with_error_message_prefix is not None:
+            data[
+                "replace_failed_page_with_error_message_prefix"
+            ] = self.replace_failed_page_with_error_message_prefix
+
+        if self.replace_failed_page_with_error_message_suffix is not None:
+            data[
+                "replace_failed_page_with_error_message_suffix"
+            ] = self.replace_failed_page_with_error_message_suffix
+
         if self.skip_diagonal_text:
             data["skip_diagonal_text"] = self.skip_diagonal_text
 
@@ -744,7 +953,9 @@ class LlamaParse(BasePydanticReader):
         if self.take_screenshot:
             data["take_screenshot"] = self.take_screenshot
 
-        if self.target_pages is not None:
+        if partition_target_pages is not None:
+            data["target_pages"] = partition_target_pages
+        elif self.target_pages is not None:
             data["target_pages"] = self.target_pages
         if self.user_prompt is not None:
             data["user_prompt"] = self.user_prompt
@@ -757,9 +968,17 @@ class LlamaParse(BasePydanticReader):
         if self.vendor_multimodal_model_name is not None:
             data["vendor_multimodal_model_name"] = self.vendor_multimodal_model_name
 
+        if self.model is not None:
+            data["model"] = self.model
+
         if self.webhook_url is not None:
             data["webhook_url"] = self.webhook_url
 
+        if self.markdown_table_multiline_header_separator is not None:
+            data[
+                "markdown_table_multiline_header_separator"
+            ] = self.markdown_table_multiline_header_separator
+
         # Deprecated
         if self.bounding_box is not None:
             data["bounding_box"] = self.bounding_box
@@ -772,7 +991,7 @@ class LlamaParse(BasePydanticReader):
 
         try:
             url = build_url(JOB_UPLOAD_ROUTE, self.organization_id, self.project_id)
-            resp = await self.aclient.post(url, files=files, data=data)  # type: ignore
+            resp = await make_api_request(self.aclient, "POST", url, timeout=self.max_timeout, files=files, data=data)  # type: ignore
             resp.raise_for_status()  # this raises if status is not 2xx
             return resp.json()["id"]
         except httpx.HTTPStatusError as err:  # this catches it
@@ -782,54 +1001,202 @@ class LlamaParse(BasePydanticReader):
             if file_handle is not None:
                 file_handle.close()
 
+    def _calculate_backoff(self, current_interval: float) -> float:
+        """Calculate the next backoff interval based on the backoff pattern.
+
+        Args:
+            current_interval: The current interval in seconds
+
+        Returns:
+            The next interval in seconds
+        """
+        if self.backoff_pattern == BackoffPattern.CONSTANT:
+            return current_interval
+        elif self.backoff_pattern == BackoffPattern.LINEAR:
+            return min(current_interval + 1, float(self.max_check_interval))
+        elif self.backoff_pattern == BackoffPattern.EXPONENTIAL:
+            return min(current_interval * 2, float(self.max_check_interval))
+        return current_interval  # Default fallback
+
     async def _get_job_result(
         self, job_id: str, result_type: str, verbose: bool = False
     ) -> Dict[str, Any]:
         start = time.time()
         tries = 0
+        error_count = 0
+        current_interval: float = float(self.check_interval)
 
         # so we're not re-setting the headers & stuff on each
         # usage... assume that there is not some other
         # coro also modifying base_url and the other client related configs.
         client = self.aclient
         while True:
-            await asyncio.sleep(self.check_interval)
-            tries += 1
-            result = await client.get(JOB_STATUS_ROUTE.format(job_id=job_id))
-            if result.status_code != 200:
+            try:
+                await asyncio.sleep(current_interval)
+                tries += 1
+                result = await client.get(JOB_STATUS_ROUTE.format(job_id=job_id))
+                result.raise_for_status()  # this raises if status is not 2xx
+                # Allowed values "PENDING", "SUCCESS", "ERROR", "CANCELED"
+                result_json = result.json()
+                status = result_json["status"]
+                if status == "SUCCESS":
+                    parsed_result = await client.get(
+                        JOB_RESULT_URL.format(job_id=job_id, result_type=result_type),
+                    )
+                    return parsed_result.json()
+                elif status == "PENDING":
+                    end = time.time()
+                    if end - start > self.max_timeout:
+                        raise Exception(f"Timeout while parsing the file: {job_id}")
+                    if verbose and tries % 10 == 0:
+                        print(".", end="", flush=True)
+                    current_interval = self._calculate_backoff(current_interval)
+                else:
+                    raise JobFailedException.from_result(result_json)
+            except (
+                httpx.ConnectError,
+                httpx.ReadError,
+                httpx.WriteError,
+                httpx.ConnectTimeout,
+                httpx.ReadTimeout,
+                httpx.WriteTimeout,
+                httpx.HTTPStatusError,
+                httpx.RemoteProtocolError,
+            ) as err:
+                error_count += 1
                 end = time.time()
                 if end - start > self.max_timeout:
-                    raise Exception(f"Timeout while parsing the file: {job_id}")
+                    raise Exception(
+                        f"Timeout while parsing the file: {job_id}"
+                    ) from err
                 if verbose and tries % 10 == 0:
-                    print(".", end="", flush=True)
-                await asyncio.sleep(self.check_interval)
-                continue
+                    print(
+                        f"HTTP error: {err}...",
+                        flush=True,
+                    )
+                current_interval = self._calculate_backoff(current_interval)
 
-            # Allowed values "PENDING", "SUCCESS", "ERROR", "CANCELED"
-            result_json = result.json()
-            status = result_json["status"]
-            if status == "SUCCESS":
-                parsed_result = await client.get(
-                    JOB_RESULT_URL.format(job_id=job_id, result_type=result_type),
+    async def _parse_one(
+        self,
+        file_path: FileInput,
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+        result_type: Optional[str] = None,
+        num_workers: Optional[int] = None,
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        if self.partition_pages is None:
+            job_results = [
+                await self._parse_one_unpartitioned(
+                    file_path,
+                    extra_info=extra_info,
+                    fs=fs,
+                    result_type=result_type,
                 )
-                return parsed_result.json()
+            ]
+        else:
+            job_results = await self._parse_one_partitioned(
+                file_path,
+                extra_info,
+                fs=fs,
+                result_type=result_type,
+                num_workers=num_workers,
+            )
+        return job_results
 
-            elif status == "PENDING":
-                end = time.time()
-                if end - start > self.max_timeout:
-                    raise Exception(f"Timeout while parsing the file: {job_id}")
-                if verbose and tries % 10 == 0:
-                    print(".", end="", flush=True)
-                await asyncio.sleep(self.check_interval)
+    async def _parse_one_unpartitioned(
+        self,
+        file_path: FileInput,
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+        result_type: Optional[str] = None,
+        **create_kwargs: Any,
+    ) -> Tuple[str, Dict[str, Any]]:
+        """Create one parse job and wait for the result."""
+        job_id = await self._create_job(
+            file_path, extra_info=extra_info, fs=fs, **create_kwargs
+        )
+        if self.verbose:
+            print("Started parsing the file under job_id %s" % job_id)
+        result = await self._get_job_result(
+            job_id, result_type or self.result_type.value, verbose=self.verbose
+        )
+        return job_id, result
 
+    async def _parse_one_partitioned(
+        self,
+        file_path: FileInput,
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+        result_type: Optional[str] = None,
+        num_workers: Optional[int] = None,
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        """Partition a file and run separate parse jobs per partition segment."""
+        assert self.partition_pages is not None
+
+        num_workers = num_workers or self.num_workers
+        if num_workers < 1:
+            raise ValueError("Invalid number of workers")
+        if self.target_pages is not None:
+            jobs = [
+                self._parse_one_unpartitioned(
+                    file_path,
+                    extra_info=extra_info,
+                    fs=fs,
+                    result_type=result_type,
+                    partition_target_pages=target_pages,
+                )
+                for target_pages in partition_pages(
+                    expand_target_pages(self.target_pages),
+                    self.partition_pages,
+                    max_pages=self.max_pages,
+                )
+            ]
+            return await run_jobs(
+                jobs,
+                workers=num_workers,
+                desc="Getting job results",
+                show_progress=self.show_progress,
+            )
+
+        total = 0
+        results: List[Tuple[str, Dict[str, Any]]] = []
+        while self.max_pages is None or total < self.max_pages:
+            if (
+                self.max_pages is not None
+                and total + self.partition_pages >= self.max_pages
+            ):
+                size = self.max_pages - total
             else:
-                error_code = result_json.get("error_code", "No error code found")
-                error_message = result_json.get(
-                    "error_message", "No error message found"
+                size = self.partition_pages
+            if not size:
+                break
+            try:
+                # Fetch JSON result type first to get accurate pagination data
+                # and then fetch the user's desired result type if needed
+                job_id, json_result = await self._parse_one_unpartitioned(
+                    file_path,
+                    extra_info=extra_info,
+                    fs=fs,
+                    result_type=ResultType.JSON.value,
+                    partition_target_pages=f"{total}-{total + size - 1}",
                 )
-
-                exception_str = f"Job ID: {job_id} failed with status: {status}, Error code: {error_code}, Error message: {error_message}"
-                raise Exception(exception_str)
+                result_type = result_type or self.result_type.value
+                if result_type == ResultType.JSON.value:
+                    job_result = json_result
+                else:
+                    job_result = await self._get_job_result(
+                        job_id, result_type, verbose=self.verbose
+                    )
+            except JobFailedException as e:
+                if results and e.error_code == "NO_DATA_FOUND_IN_FILE":
+                    # Expected when we try to read past the end of the file
+                    return results
+                raise
+            results.append((job_id, job_result))
+            if len(json_result["pages"]) < size:
+                break
+            total += size
+        return results
 
     async def _aload_data(
         self,
@@ -837,20 +1204,23 @@ class LlamaParse(BasePydanticReader):
         extra_info: Optional[dict] = None,
         fs: Optional[AbstractFileSystem] = None,
         verbose: bool = False,
+        num_workers: Optional[int] = None,
     ) -> List[Document]:
         """Load data from the input path."""
         try:
-            job_id = await self._create_job(file_path, extra_info=extra_info, fs=fs)
-            if verbose:
-                print("Started parsing the file under job_id %s" % job_id)
-
-            result = await self._get_job_result(
-                job_id, self.result_type.value, verbose=verbose
-            )
-
+            results = [
+                job_result
+                for _, job_result in await self._parse_one(
+                    file_path, extra_info, fs=fs, num_workers=num_workers
+                )
+            ]
+            # Flatten the resulting doc if it was partitioned
+            separator = self.page_separator or _DEFAULT_SEPARATOR
             docs = [
                 Document(
-                    text=result[self.result_type.value],
+                    text=separator.join(
+                        result[self.result_type.value] for result in results
+                    ),
                     metadata=extra_info or {},
                 )
             ]
@@ -873,7 +1243,11 @@ class LlamaParse(BasePydanticReader):
         extra_info: Optional[dict] = None,
         fs: Optional[AbstractFileSystem] = None,
     ) -> List[Document]:
-        """Load data from the input path."""
+        """Load data from the input path.
+
+        File(s) which were partitioned before parsing will be loaded as a single
+        re-assembled Document.
+        """
         if isinstance(file_path, (str, PurePosixPath, Path, bytes, BufferedIOBase)):
             return await self._aload_data(
                 file_path, extra_info=extra_info, fs=fs, verbose=self.verbose
@@ -885,6 +1259,7 @@ class LlamaParse(BasePydanticReader):
                     extra_info=extra_info,
                     fs=fs,
                     verbose=self.verbose and not self.show_progress,
+                    num_workers=1,
                 )
                 for f in file_path
             ]
@@ -923,21 +1298,161 @@ class LlamaParse(BasePydanticReader):
             else:
                 raise e
 
+    async def _aparse_one(
+        self,
+        file_path: FileInput,
+        file_name: str,
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+        num_workers: Optional[int] = None,
+    ) -> List[JobResult]:
+        job_results = await self._parse_one(
+            file_path,
+            extra_info,
+            fs=fs,
+            result_type=ResultType.JSON.value,
+            num_workers=num_workers,
+        )
+        return [
+            JobResult(
+                job_id=job_id,
+                file_name=file_name,
+                job_result=job_result,
+                api_key=self.api_key,
+                base_url=self.base_url,
+                client=self.aclient,
+                page_separator=self.page_separator or _DEFAULT_SEPARATOR,
+            )
+            for job_id, job_result in job_results
+        ]
+
+    async def aparse(
+        self,
+        file_path: Union[List[FileInput], FileInput],
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+    ) -> Union[List["JobResult"], "JobResult"]:
+        """
+        Parse the file and return a JobResult object instead of Document objects.
+
+        This method is similar to aload_data but returns JobResult objects that provide
+        direct access to the various output formats (text, markdown, json, etc.)
+
+        Args:
+            file_path: Path to the file to parse. Can be a string, path, bytes, file-like object, or a list of these.
+            extra_info: Additional metadata to include in the result.
+            fs: Optional filesystem to use for reading files.
+
+        Returns:
+            JobResult object or list of JobResult objects if either multiple files were provided or file(s) were partitioned before parsing.
+        """
+
+        if isinstance(file_path, (str, PurePosixPath, Path, bytes, BufferedIOBase)):
+            if isinstance(file_path, (bytes, BufferedIOBase)):
+                if not extra_info or "file_name" not in extra_info:
+                    raise ValueError(
+                        "file_name must be provided in extra_info when passing bytes"
+                    )
+                file_name = extra_info["file_name"]
+            else:
+                file_name = str(file_path)
+            result = await self._aparse_one(
+                file_path, file_name, extra_info=extra_info, fs=fs
+            )
+            return result[0] if len(result) == 1 else result
+
+        elif isinstance(file_path, list):
+            file_names = []
+            for f in file_path:
+                if isinstance(f, (bytes, BufferedIOBase)):
+                    if not extra_info or "file_name" not in extra_info:
+                        raise ValueError(
+                            "file_name must be provided in extra_info when passing bytes"
+                        )
+                    file_names.append(extra_info["file_name"])
+                else:
+                    file_names.append(str(f))
+
+            job_results = []
+            try:
+                for result in await run_jobs(
+                    [
+                        self._aparse_one(
+                            f,
+                            file_names[i],
+                            extra_info=extra_info,
+                            fs=fs,
+                            num_workers=1,
+                        )
+                        for i, f in enumerate(file_path)
+                    ],
+                    workers=self.num_workers,
+                    desc="Getting job results",
+                    show_progress=self.show_progress,
+                ):
+                    job_results.extend(result)
+                return job_results
+
+            except RuntimeError as e:
+                if nest_asyncio_err in str(e):
+                    raise RuntimeError(nest_asyncio_msg)
+                else:
+                    raise e
+        else:
+            raise ValueError(
+                "The input file_path must be a string or a list of strings."
+            )
+
+    def parse(
+        self,
+        file_path: Union[List[FileInput], FileInput],
+        extra_info: Optional[dict] = None,
+        fs: Optional[AbstractFileSystem] = None,
+    ) -> Union[List["JobResult"], "JobResult"]:
+        """
+        Parse the file and return a JobResult object instead of Document objects.
+
+        This method is similar to load_data but returns JobResult objects that provide
+        direct access to the various output formats (text, markdown, json, etc.)
+
+        Args:
+            file_path: Path to the file to parse. Can be a string, path, bytes, file-like object, or a list of these.
+            extra_info: Additional metadata to include in the result.
+            fs: Optional filesystem to use for reading files.
+
+        Returns:
+            JobResult object or list of JobResult objects if multiple files were provided
+        """
+        try:
+            return asyncio_run(self.aparse(file_path, extra_info, fs=fs))
+        except RuntimeError as e:
+            if nest_asyncio_err in str(e):
+                raise RuntimeError(nest_asyncio_msg)
+            else:
+                raise e
+
     async def _aget_json(
-        self, file_path: FileInput, extra_info: Optional[dict] = None
+        self,
+        file_path: FileInput,
+        extra_info: Optional[dict] = None,
+        num_workers: Optional[int] = None,
     ) -> List[dict]:
         """Load data from the input path."""
         try:
-            job_id = await self._create_job(file_path, extra_info=extra_info)
-            if self.verbose:
-                print("Started parsing the file under job_id %s" % job_id)
-            result = await self._get_job_result(job_id, "json")
-            result["job_id"] = job_id
+            job_results = await self._parse_one(
+                file_path,
+                extra_info=extra_info,
+                result_type=ResultType.JSON.value,
+                num_workers=num_workers,
+            )
 
-            if not isinstance(file_path, (bytes, BufferedIOBase)):
-                result["file_path"] = str(file_path)
-
-            return [result]
+            results = []
+            for job_id, job_result in job_results:
+                job_result["job_id"] = job_id
+                if not isinstance(file_path, (bytes, BufferedIOBase)):
+                    job_result["file_path"] = str(file_path)
+                results.append(job_result)
+            return results
         except Exception as e:
             file_repr = file_path if isinstance(file_path, str) else "<bytes/buffer>"
             print(f"Error while parsing the file '{file_repr}':", e)
@@ -952,7 +1467,7 @@ class LlamaParse(BasePydanticReader):
         extra_info: Optional[dict] = None,
     ) -> List[dict]:
         """Load data from the input path."""
-        if isinstance(file_path, (str, Path)):
+        if isinstance(file_path, (str, PurePosixPath, Path, bytes, BufferedIOBase)):
             return await self._aget_json(file_path, extra_info=extra_info)
         elif isinstance(file_path, list):
             jobs = [self._aget_json(f, extra_info=extra_info) for f in file_path]
@@ -973,7 +1488,7 @@ class LlamaParse(BasePydanticReader):
                     raise e
         else:
             raise ValueError(
-                "The input file_path must be a string or a list of strings."
+                "The input file_path must be a string, Path, bytes, BufferedIOBase, or a list of these types."
             )
 
     def get_json_result(
@@ -990,6 +1505,14 @@ class LlamaParse(BasePydanticReader):
             else:
                 raise e
 
+    def get_json(
+        self,
+        file_path: Union[List[FileInput], FileInput],
+        extra_info: Optional[dict] = None,
+    ) -> List[dict]:
+        """Load data from the input path."""
+        return self.get_json_result(file_path, extra_info)
+
     async def aget_assets(
         self, json_result: List[dict], download_path: str, asset_key: str
     ) -> List[dict]:
@@ -1028,7 +1551,9 @@ class LlamaParse(BasePydanticReader):
 
                         with open(asset_path, "wb") as f:
                             asset_url = f"{self.base_url}/api/parsing/job/{job_id}/result/image/{asset_name}"
-                            resp = await client.get(asset_url)
+                            resp = await make_api_request(
+                                client, "GET", asset_url, timeout=self.max_timeout
+                            )
                             resp.raise_for_status()
                             f.write(resp.content)
                         assets.append(asset)
@@ -1113,7 +1638,9 @@ class LlamaParse(BasePydanticReader):
                     xlsx_url = (
                         f"{self.base_url}/api/parsing/job/{job_id}/result/raw/xlsx"
                     )
-                    res = await client.get(xlsx_url)
+                    res = await make_api_request(
+                        client, "GET", xlsx_url, timeout=self.max_timeout
+                    )
                     res.raise_for_status()
                     f.write(res.content)
                 xlsx_list.append(xlsx)

llama_cloud_services/parse/types.py

@@ -0,0 +1,593 @@
+import httpx
+import os
+import re
+from pydantic import BaseModel, Field, SerializeAsAny
+from typing import Dict, Any, List, Optional
+
+from llama_cloud_services.parse.utils import make_api_request
+from llama_index.core.async_utils import asyncio_run
+from llama_index.core.schema import Document, ImageDocument, ImageNode, TextNode
+
+PAGE_REGEX = r"page[-_](\d+)\.jpg$"
+
+
+class JobMetadata(BaseModel):
+    """Metadata about the job."""
+
+    job_pages: int = Field(default=0, description="The number of pages in the job.")
+    job_auto_mode_triggered_pages: Optional[int] = Field(
+        default=None,
+        description="The number of pages that triggered auto mode (thus increasing the cost).",
+    )
+    job_is_cache_hit: bool = Field(
+        default=False, description="Whether the job was a cache hit."
+    )
+
+
+class BBox(BaseModel):
+    """A bounding box."""
+
+    x: float = Field(description="The x-coordinate of the bounding box.")
+    y: float = Field(description="The y-coordinate of the bounding box.")
+    w: float = Field(description="The width of the bounding box.")
+    h: float = Field(description="The height of the bounding box.")
+
+
+class PageItem(BaseModel):
+    """An item in a page."""
+
+    type: str = Field(description="The type of the item.")
+    lvl: Optional[int] = Field(
+        default=None, description="The level of indentation of the item."
+    )
+    value: Optional[str] = Field(
+        default=None, description="The text content of the item."
+    )
+    md: Optional[str] = Field(
+        default=None, description="The markdown-formatted content of the item."
+    )
+    rows: Optional[List[List[Any]]] = Field(
+        default=None, description="The rows of the item."
+    )
+    bBox: Optional[BBox] = Field(
+        default=None, description="The bounding box of the item."
+    )
+
+
+class ImageItem(BaseModel):
+    """An image in a page."""
+
+    name: str = Field(description="The name of the image.")
+    height: Optional[float] = Field(
+        default=None, description="The height of the image."
+    )
+    width: Optional[float] = Field(default=None, description="The width of the image.")
+    x: Optional[float] = Field(
+        default=None, description="The x-coordinate of the image."
+    )
+    y: Optional[float] = Field(
+        default=None, description="The y-coordinate of the image."
+    )
+    original_width: Optional[int] = Field(
+        default=None, description="The original width of the image."
+    )
+    original_height: Optional[int] = Field(
+        default=None, description="The original height of the image."
+    )
+    type: Optional[str] = Field(default=None, description="The type of the image.")
+
+
+class LayoutItem(BaseModel):
+    """The layout of a page."""
+
+    image: str = Field(description="The name of the image containing the layout item")
+    confidence: float = Field(description="The confidence of the layout item.")
+    label: str = Field(description="The label of the layout item.")
+    bbox: Optional[BBox] = Field(
+        default=None, description="The bounding box of the layout item."
+    )
+    isLikelyNoise: bool = Field(description="Whether the layout item is likely noise.")
+
+
+class ChartItem(BaseModel):
+    """A chart in a page."""
+
+    name: str = Field(description="The name of the chart.")
+    x: Optional[float] = Field(
+        default=None, description="The x-coordinate of the chart."
+    )
+    y: Optional[float] = Field(
+        default=None, description="The y-coordinate of the chart."
+    )
+    width: Optional[float] = Field(default=None, description="The width of the chart.")
+    height: Optional[float] = Field(
+        default=None, description="The height of the chart."
+    )
+
+
+class Page(BaseModel):
+    """A page of the document."""
+
+    page: int = Field(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(
+        default_factory=list,
+        description="The names of the image IDs in the page, including both objects and page screenshots.",
+    )
+    charts: List[ChartItem] = Field(
+        default_factory=list, description="The charts in the page."
+    )
+    tables: List[str] = Field(
+        default_factory=list, description="The names of the table IDs in the page."
+    )
+    layout: List[LayoutItem] = Field(
+        default_factory=list, description="The layout of the page."
+    )
+    items: List[PageItem] = Field(
+        default_factory=list, description="The items in the page."
+    )
+    status: Optional[str] = Field(default=None, description="The status of the page.")
+    links: List[SerializeAsAny[Any]] = Field(
+        default_factory=list, description="The links in the page."
+    )
+    width: Optional[float] = Field(default=None, description="The width of the page.")
+    height: Optional[float] = Field(default=None, description="The height of the page.")
+    triggeredAutoMode: Optional[bool] = Field(
+        default=False,
+        description="Whether the page triggered auto mode (thus increasing the cost).",
+    )
+    parsingMode: str = Field(
+        default="", description="The parsing mode used for the page."
+    )
+    structuredData: Optional[Dict[str, Any]] = Field(
+        default=None, description="The structured data of the page."
+    )
+    noStructuredContent: bool = Field(
+        default=True, description="Whether the page has no structured data."
+    )
+    noTextContent: bool = Field(
+        default=False, description="Whether the page has no text content."
+    )
+
+
+class JobResult(BaseModel):
+    """The raw JSON result from the LlamaParse API."""
+
+    pages: List[Page] = Field(
+        default_factory=list, description="The pages of the document."
+    )
+    job_metadata: JobMetadata = Field(
+        default_factory=JobMetadata, description="The metadata of the job."
+    )
+    file_name: str = Field(
+        default="", description="The path to the file that was parsed."
+    )
+    job_id: str = Field(default="", description="The ID of the job.")
+    is_done: bool = Field(default=False, description="Whether the job is done.")
+    error: Optional[str] = Field(
+        default=None, description="The error message if the job failed."
+    )
+
+    def __init__(
+        self,
+        job_id: str,
+        file_name: str,
+        job_result: Dict[str, Any],
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        client: Optional[httpx.AsyncClient] = None,
+        page_separator: str = "\n\n",
+    ):
+        """
+        Initialize JobResult with job_id and job_result.
+
+        Args:
+            job_id: The job ID of the parsing task
+            job_result: The JSON response from the parsing job or a JobResult instance (optional)
+            api_key: The API key for the LlamaParse API
+            base_url: The base URL of the Llama Parsing API
+            page_separator: The separator that was used to define page splits in the result
+        """
+        super().__init__(job_id=job_id, file_name=file_name, **job_result)
+
+        self._api_key = api_key or os.environ.get("LLAMA_CLOUD_API_KEY", "")
+        self._base_url = base_url or os.environ.get(
+            "LLAMA_CLOUD_BASE_URL", "https://api.llama-parse.ai"
+        )
+        self._client = client or httpx.AsyncClient()
+        self._client.base_url = self._base_url
+        self._client.headers["Authorization"] = f"Bearer {self._api_key}"
+        self._page_separator = page_separator
+
+    def get_text_documents(self, split_by_page: bool = False) -> List[Document]:
+        """
+        Get the documents from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        if split_by_page:
+            return [
+                Document(
+                    text=page.text,
+                    metadata={"page_number": page.page, "file_name": self.file_name},
+                )
+                for page in self.pages
+            ]
+        else:
+            text = self._page_separator.join(
+                [page.text if page.text is not None else "" for page in self.pages]
+            )
+            return [Document(text=text, metadata={"file_name": self.file_name})]
+
+    async def aget_text_documents(self, split_by_page: bool = False) -> List[Document]:
+        """
+        Get the documents from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        # No async needed, but here for consistency
+        return self.get_text_documents(split_by_page)
+
+    def get_text_nodes(self, split_by_page: bool = False) -> List[TextNode]:
+        """
+        Get the text nodes from the job.
+        """
+        documents = self.get_text_documents(split_by_page)
+        return [TextNode(text=doc.text, metadata=doc.metadata) for doc in documents]
+
+    async def aget_text_nodes(self, split_by_page: bool = False) -> List[TextNode]:
+        """
+        Get the text nodes from the job.
+        """
+        documents = await self.aget_text_documents(split_by_page)
+        return [TextNode(text=doc.text, metadata=doc.metadata) for doc in documents]
+
+    def get_markdown_documents(self, split_by_page: bool = False) -> List[Document]:
+        """
+        Get the markdown documents from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        if split_by_page:
+            return [
+                Document(
+                    text=page.md,
+                    metadata={"page_number": page.page, "file_name": self.file_name},
+                )
+                for page in self.pages
+            ]
+        else:
+            return [
+                Document(
+                    text=self._page_separator.join(
+                        [page.md if page.md is not None else "" for page in self.pages]
+                    ),
+                    metadata={"file_name": self.file_name},
+                )
+            ]
+
+    async def aget_markdown_documents(
+        self, split_by_page: bool = False
+    ) -> List[Document]:
+        """
+        Get the markdown documents from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        # No async needed, but here for consistency
+        return self.get_markdown_documents(split_by_page)
+
+    def get_markdown_nodes(self, split_by_page: bool = False) -> List[TextNode]:
+        """
+        Get the markdown nodes from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        documents = self.get_markdown_documents(split_by_page)
+        return [TextNode(text=doc.text, metadata=doc.metadata) for doc in documents]
+
+    async def aget_markdown_nodes(self, split_by_page: bool = False) -> List[TextNode]:
+        """
+        Get the markdown nodes from the job.
+
+        Args:
+            split_by_page: Whether to split the pages into separate documents
+        """
+        documents = await self.aget_markdown_documents(split_by_page)
+        return [TextNode(text=doc.text, metadata=doc.metadata) for doc in documents]
+
+    async def _get_image_document_with_bytes(
+        self, image: ImageItem, page: Page
+    ) -> ImageDocument:
+        image_data = await self.aget_image_data(image.name)
+
+        return ImageDocument(
+            image=image_data,
+            metadata={
+                "page_number": page.page,
+                "file_name": self.file_name,
+                "width": image.original_width,
+                "height": image.original_height,
+                "x": image.x,
+                "y": image.y,
+            },
+            excluded_embed_metadata_keys=["width", "height", "x", "y"],
+            excluded_llm_metadata_keys=["width", "height", "x", "y"],
+        )
+
+    async def _get_image_document_with_path(
+        self, image: ImageItem, page: Page, image_download_dir: str
+    ) -> ImageDocument:
+        image_path = await self.asave_image(image.name, image_download_dir)
+
+        return ImageDocument(
+            image_path=image_path,
+            metadata={
+                "page_number": page.page,
+                "file_name": self.file_name,
+                "width": image.original_width,
+                "height": image.original_height,
+                "x": image.x,
+                "y": image.y,
+            },
+            excluded_embed_metadata_keys=["width", "height", "x", "y"],
+            excluded_llm_metadata_keys=["width", "height", "x", "y"],
+        )
+
+    def get_image_documents(
+        self,
+        include_screenshot_images: bool = True,
+        include_object_images: bool = True,
+        image_download_dir: Optional[str] = None,
+    ) -> List[ImageDocument]:
+        """
+        Get the image documents from the job.
+
+        Args:
+            include_screenshot_images (bool):
+                Whether to include screenshot images. Default is True.
+            include_object_images (bool):
+                Whether to include object images. Default is True.
+            image_download_dir (Optional[str]):
+                The directory to save the images to. If not provided, the images will be loaded into memory.
+                Default is None.
+        """
+        return asyncio_run(
+            self.aget_image_documents(
+                include_screenshot_images, include_object_images, image_download_dir
+            )
+        )
+
+    async def aget_image_documents(
+        self,
+        include_screenshot_images: bool = True,
+        include_object_images: bool = True,
+        image_download_dir: Optional[str] = None,
+    ) -> List[ImageDocument]:
+        """
+        Get the image documents from the job.
+
+        Args:
+            include_screenshot_images (bool):
+                Whether to include screenshot images. Default is True.
+            include_object_images (bool):
+                Whether to include object images. Default is True.
+            image_download_dir (Optional[str]):
+                The directory to save the images to. If not provided, the images will be loaded into memory.
+                Default is None.
+        """
+        documents = []
+        for page in self.pages:
+            for image in page.images:
+                is_screenshot = re.search(PAGE_REGEX, image.name) is not None
+
+                # Skip images that don't match the inclusion criteria
+                if (is_screenshot and not include_screenshot_images) or (
+                    not is_screenshot and not include_object_images
+                ):
+                    continue
+
+                # Get image document using appropriate method based on download_dir
+                get_document = (
+                    self._get_image_document_with_path
+                    if image_download_dir
+                    else self._get_image_document_with_bytes
+                )
+
+                documents.append(
+                    await get_document(image, page, image_download_dir)  # type: ignore
+                    if image_download_dir
+                    else await get_document(image, page)  # type: ignore
+                )
+
+        return documents
+
+    def get_image_nodes(
+        self,
+        include_screenshot_images: bool = True,
+        include_object_images: bool = True,
+        image_download_dir: Optional[str] = None,
+    ) -> List[ImageNode]:
+        """
+        Get the image nodes from the job.
+
+        Args:
+            include_screenshot_images (bool):
+                Whether to include screenshot images. Default is True.
+            include_object_images (bool):
+                Whether to include object images. Default is True.
+            image_download_dir (Optional[str]):
+                The directory to save the images to. If not provided, the images will be loaded into memory.
+                Default is None.
+        """
+        documents = self.get_image_documents(
+            include_screenshot_images, include_object_images, image_download_dir
+        )
+        return [
+            ImageNode(
+                image=doc.image,
+                image_path=doc.image_path,
+                image_url=doc.image_url,
+                metadata=doc.metadata,
+            )
+            for doc in documents
+        ]
+
+    async def aget_image_nodes(
+        self,
+        include_screenshot_images: bool = True,
+        include_object_images: bool = True,
+        image_download_dir: Optional[str] = None,
+    ) -> List[ImageNode]:
+        """
+        Get the image nodes from the job.
+
+        Args:
+            include_screenshot_images (bool):
+                Whether to include screenshot images. Default is True.
+            include_object_images (bool):
+                Whether to include object images. Default is True.
+            image_download_dir (Optional[str]):
+                The directory to save the images to. If not provided, the images will be loaded into memory.
+                Default is None.
+        """
+        documents = await self.aget_image_documents(
+            include_screenshot_images, include_object_images, image_download_dir
+        )
+        return [
+            ImageNode(
+                image=doc.image,
+                image_path=doc.image_path,
+                image_url=doc.image_url,
+                metadata=doc.metadata,
+            )
+            for doc in documents
+        ]
+
+    async def aget_image_data(self, image_name: str) -> bytes:
+        """
+        Get image data by name using the job ID.
+
+        Args:
+            image_name: The name of the image to fetch
+
+        Returns:
+            The image data as bytes
+        """
+        url = f"{self._base_url}/api/v1/parsing/job/{self.job_id}/result/image/{image_name}"
+        response = await make_api_request(self._client, "GET", url)
+        return response.content
+
+    def get_image_data(self, image_name: str) -> bytes:
+        """
+        Get image data by name using the job ID (synchronous version).
+
+        Args:
+            image_name: The name of the image to fetch
+
+        Returns:
+            The image data as bytes
+        """
+        return asyncio_run(self.aget_image_data(image_name))
+
+    async def aget_xlsx_data(self) -> bytes:
+        """
+        Get the XLSX data for the job.
+
+        Returns:
+            The XLSX data as bytes
+        """
+        url = f"{self._base_url}/api/v1/parsing/job/{self.job_id}/result/xlsx"
+        response = await make_api_request(self._client, "GET", url)
+        return response.content
+
+    def get_xlsx_data(self) -> bytes:
+        """
+        Get the XLSX data for the job (synchronous version).
+
+        Returns:
+            The XLSX data as bytes
+        """
+        return asyncio_run(self.aget_xlsx_data())
+
+    async def asave_image(self, image_name: str, output_dir: str) -> str:
+        """
+        Save an image to a file.
+
+        Args:
+            image_name: The name of the image to fetch
+            output_dir: The directory to save the image to
+
+        Returns:
+            The path to the saved image
+        """
+        image_data = await self.aget_image_data(image_name)
+
+        # Create output directory if it doesn't exist
+        os.makedirs(output_dir, exist_ok=True)
+
+        # Save image to file
+        output_path = os.path.join(output_dir, image_name)
+        with open(output_path, "wb") as f:
+            f.write(image_data)
+
+        return output_path
+
+    def save_image(self, image_name: str, output_dir: str) -> str:
+        """
+        Save an image to a file (synchronous version).
+
+        Args:
+            image_name: The name of the image to fetch
+            output_dir: The directory to save the image to
+
+        Returns:
+            The path to the saved image
+        """
+        return asyncio_run(self.asave_image(image_name, output_dir))
+
+    def get_image_names(self) -> List[str]:
+        """
+        Get the names of all images in the job.
+
+        Returns:
+            A list of image names
+        """
+        return [image.name for page in self.pages for image in page.images]
+
+    async def asave_all_images(self, output_dir: str) -> List[str]:
+        """
+        Save all images to files.
+
+        Args:
+            output_dir: The directory to save the images to
+
+        Returns:
+            A list of paths to the saved images
+        """
+        image_names = self.get_image_names()
+        saved_paths = []
+
+        for name in image_names:
+            path = await self.asave_image(name, output_dir)
+            saved_paths.append(path)
+
+        return saved_paths
+
+    def save_all_images(self, output_dir: str) -> List[str]:
+        """
+        Save all images to files (synchronous version).
+
+        Args:
+            output_dir: The directory to save the images to
+
+        Returns:
+            A list of paths to the saved images
+        """
+        return asyncio_run(self.asave_all_images(output_dir))

llama_cloud_services/parse/utils.py

@@ -1,4 +1,17 @@
+import httpx
+import itertools
+import logging
 from enum import Enum
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception,
+    before_sleep_log,
+)
+from typing import Any, Iterable, Iterator, Optional
+
+logger = logging.getLogger(__name__)
 
 # Asyncio error messages
 nest_asyncio_err = "cannot be called from a running event loop"
@@ -22,6 +35,17 @@ class ParsingMode(str, Enum):
     parse_page_with_lvm = "parse_page_with_lvm"
     parse_page_with_agent = "parse_page_with_agent"
     parse_document_with_llm = "parse_document_with_llm"
+    parse_document_with_agent = "parse_document_with_agent"
+
+
+class FailedPageMode(str, Enum):
+    """
+    Enum for representing the different available page error handling modes
+    """
+
+    raw_text = "raw_text"
+    blank_page = "blank_page"
+    error_message = "error_message"
 
 
 class Language(str, Enum):
@@ -209,3 +233,121 @@ SUPPORTED_FILE_TYPES = [
     ".wav",
     ".webm",
 ]
+
+
+def should_retry(exception: Exception) -> bool:
+    """Check if the exception should be retried.
+
+    Args:
+        exception: The exception to check.
+    """
+    # Retry on connection errors (network issues)
+    if isinstance(
+        exception,
+        (
+            httpx.ConnectError,
+            httpx.ConnectTimeout,
+            httpx.ReadTimeout,
+            httpx.WriteTimeout,
+            httpx.RemoteProtocolError,
+        ),
+    ):
+        return True
+
+    # Retry on specific HTTP status codes
+    if isinstance(exception, httpx.HTTPStatusError):
+        status_code = exception.response.status_code
+        # Retry on rate limiting or temporary server errors
+        return status_code in (429, 500, 502, 503, 504)
+
+    return False
+
+
+async def make_api_request(
+    client: httpx.AsyncClient,
+    method: str,
+    url: str,
+    timeout: float = 60.0,
+    max_retries: int = 5,
+    **httpx_kwargs: Any,
+) -> httpx.Response:
+    """Make an retrying API request to the LlamaParse API.
+
+    Args:
+        client: The httpx.AsyncClient to use for the request.
+        url: The URL to request.
+        headers: The headers to include in the request.
+        timeout: The timeout for the request.
+        max_retries: The maximum number of retries for the request.
+    """
+
+    @retry(
+        stop=stop_after_attempt(max_retries),
+        wait=wait_exponential(multiplier=1, min=4, max=timeout),
+        retry=retry_if_exception(should_retry),
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def _make_request(url: str, **httpx_kwargs: Any) -> httpx.Response:
+        if method == "GET":
+            response = await client.get(url, **httpx_kwargs)
+        elif method == "POST":
+            response = await client.post(url, **httpx_kwargs)
+        else:
+            raise ValueError(f"Invalid method: {method}")
+        response.raise_for_status()
+        return response
+
+    return await _make_request(url, **httpx_kwargs)
+
+
+def expand_target_pages(target_pages: str) -> Iterator[int]:
+    """Yield all values in target_pages."""
+    for target in target_pages.strip().split(","):
+        if "-" in target:
+            try:
+                start, end = map(int, target.strip().split("-"))
+                if start > end:
+                    raise ValueError
+                yield from range(start, end + 1)
+            except ValueError as e:
+                raise ValueError(f"Invalid page range: {target}") from e
+        else:
+            try:
+                yield int(target)
+            except ValueError as e:
+                raise ValueError(f"Invalid page number: {target}") from e
+
+
+def partition_pages(
+    pages: Iterable[int], size: int, max_pages: Optional[int] = None
+) -> Iterator[str]:
+    """Yield partitioned target_pages segments."""
+    if size < 1:
+        raise ValueError(f"Invalid partition segment size: {size}")
+    if max_pages is not None and max_pages < 1:
+        raise ValueError("Max pages must be > 0")
+    it = iter(pages)
+    total = 0
+    while max_pages is None or total < max_pages:
+        segment = tuple(itertools.islice(it, size))
+        if segment:
+            targets = []
+            for _k, g in itertools.groupby(enumerate(segment), lambda x: x[0] - x[1]):
+                group = [item[1] for item in g]
+                if len(group) > 1:
+                    start, end = group[0], group[-1]
+                    group_size = end - start + 1
+                    if max_pages is not None and total + group_size > max_pages:
+                        end -= total + group_size - max_pages
+                        group_size = end - start + 1
+                    if group_size > 1:
+                        targets.append(f"{start}-{end}")
+                    else:
+                        targets.append(str(start))
+                    total += group_size
+                else:
+                    targets.append(str(group[0]))
+                    total += 1
+            yield ",".join(targets)
+        else:
+            return

llama_cloud_services/utils.py

@@ -0,0 +1,29 @@
+import difflib
+from pydantic import BaseModel
+from typing import Any, Dict, List, Tuple, Type
+
+
+def check_extra_params(
+    model_cls: Type[BaseModel], data: Dict[str, Any]
+) -> Tuple[List[str], List[str]]:
+    # check if one of the parameters is unused, and warn the user
+    model_attributes = set(model_cls.model_fields.keys())
+    extra_params = [param for param in data.keys() if param not in model_attributes]
+
+    suggestions: List[str] = []
+    if extra_params:
+        # for each unused parameter, check if it is similar to a valid parameter and suggest a typo correction, else suggest to check the documentation / update the package
+        for param in extra_params:
+            similar_params = difflib.get_close_matches(
+                param, model_attributes, n=1, cutoff=0.8
+            )
+            if similar_params:
+                suggestions.append(
+                    f"'{param}' is not a valid parameter. Did you mean '{similar_params[0]}' instead of '{param}'?"
+                )
+            else:
+                suggestions.append(
+                    f"'{param}' is not a valid parameter. Please check the documentation or update the package."
+                )
+
+    return extra_params, suggestions

llama_parse/llama_parse/__init__.py

@@ -1,3 +1,8 @@
-from llama_cloud_services.parse import LlamaParse, ResultType
+from llama_cloud_services.parse import (
+    LlamaParse,
+    ResultType,
+    ParsingMode,
+    FailedPageMode,
+)
 
-__all__ = ["LlamaParse", "ResultType"]
+__all__ = ["LlamaParse", "ResultType", "ParsingMode", "FailedPageMode"]

llama_parse/llama_parse/base.py

@@ -1,6 +1,8 @@
 from llama_cloud_services.parse.base import (
     LlamaParse,
     ResultType,
+    ParsingMode,
+    FailedPageMode,
     FileInput,
     _DEFAULT_SEPARATOR,
     JOB_RESULT_URL,
@@ -12,6 +14,8 @@ __all__ = [
     "LlamaParse",
     "ResultType",
     "FileInput",
+    "ParsingMode",
+    "FailedPageMode",
     "_DEFAULT_SEPARATOR",
     "JOB_RESULT_URL",
     "JOB_STATUS_ROUTE",

llama_parse/llama_parse/utils.py

@@ -2,10 +2,14 @@ from llama_cloud_services.parse.utils import (
     SUPPORTED_FILE_TYPES,
     Language,
     ResultType,
+    ParsingMode,
+    FailedPageMode,
 )
 
 __all__ = [
     "SUPPORTED_FILE_TYPES",
     "Language",
     "ResultType",
+    "ParsingMode",
+    "FailedPageMode",
 ]

llama_parse/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "llama-parse"
-version = "0.6.6"
+version = "0.6.44"
 description = "Parse files into RAG-Optimized formats."
 authors = ["Logan Markewich <logan@llamaindex.ai>"]
 license = "MIT"
@@ -13,7 +13,7 @@ packages = [{include = "llama_parse"}]
 
 [tool.poetry.dependencies]
 python = ">=3.9,<4.0"
-llama-cloud-services = ">=0.6.5"
+llama-cloud-services = ">=0.6.44"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"

parse.md

@@ -25,6 +25,8 @@ Then, install the package:
 
 `pip install llama-cloud-services`
 
+## CLI Usage
+
 Now you can parse your first PDF file using the command line interface. Use the command `llama-parse [file_paths]`. See the help text with `llama-parse --help`.
 
 ```bash
@@ -40,50 +42,72 @@ llama-parse my_file.pdf --result-type markdown --output-file output.md
 llama-parse my_file.pdf --output-raw-json --output-file output.json
 ```
 
+## Python Usage
+
 You can also create simple scripts:
 
 ```python
-import nest_asyncio
-
-nest_asyncio.apply()
-
 from llama_cloud_services import LlamaParse
 
 parser = LlamaParse(
     api_key="llx-...",  # can also be set in your env as LLAMA_CLOUD_API_KEY
-    result_type="markdown",  # "markdown" and "text" are available
     num_workers=4,  # if multiple files passed, split in `num_workers` API calls
     verbose=True,
     language="en",  # Optionally you can define a language, default=en
 )
 
 # sync
-documents = parser.load_data("./my_file.pdf")
+result = parser.parse("./my_file.pdf")
 
 # sync batch
-documents = parser.load_data(["./my_file1.pdf", "./my_file2.pdf"])
+results = parser.parse(["./my_file1.pdf", "./my_file2.pdf"])
 
 # async
-documents = await parser.aload_data("./my_file.pdf")
+result = await parser.aparse("./my_file.pdf")
 
 # async batch
-documents = await parser.aload_data(["./my_file1.pdf", "./my_file2.pdf"])
+results = await parser.aparse(["./my_file1.pdf", "./my_file2.pdf"])
 ```
 
-## Using with file object
+The result object is a fully typed `JobResult` object, and you can interact with it to parse and transform various parts of the result:
+
+```python
+# get the llama-index markdown documents
+markdown_documents = result.get_markdown_documents(split_by_page=True)
+
+# get the llama-index text documents
+text_documents = result.get_text_documents(split_by_page=False)
+
+# get the image documents
+image_documents = result.get_image_documents(
+    include_screenshot_images=True,
+    include_object_images=False,
+    # Optional: download the images to a directory
+    # (default is to return the image bytes in ImageDocument objects)
+    image_download_dir="./images",
+)
+
+# access the raw job result
+# Items will vary based on the parser configuration
+for page in result.pages:
+    print(page.text)
+    print(page.md)
+    print(page.images)
+    print(page.layout)
+    print(page.structuredData)
+```
+
+See more details about the result object in the [example notebook](./examples/parse/demo_json_tour.ipynb).
+
+### Using with file object / bytes
 
 You can parse a file object directly:
 
 ```python
-import nest_asyncio
-
-nest_asyncio.apply()
-
 from llama_cloud_services import LlamaParse
 
 parser = LlamaParse(
     api_key="llx-...",  # can also be set in your env as LLAMA_CLOUD_API_KEY
-    result_type="markdown",  # "markdown" and "text" are available
     num_workers=4,  # if multiple files passed, split in `num_workers` API calls
     verbose=True,
     language="en",  # Optionally you can define a language, default=en
@@ -94,24 +118,20 @@ extra_info = {"file_name": file_name}
 
 with open(f"./{file_name}", "rb") as f:
     # must provide extra_info with file_name key with passing file object
-    documents = parser.load_data(f, extra_info=extra_info)
+    result = parser.parse(f, extra_info=extra_info)
 
 # you can also pass file bytes directly
 with open(f"./{file_name}", "rb") as f:
     file_bytes = f.read()
     # must provide extra_info with file_name key with passing file bytes
-    documents = parser.load_data(file_bytes, extra_info=extra_info)
+    result = parser.parse(file_bytes, extra_info=extra_info)
 ```
 
-## Using with `SimpleDirectoryReader`
+### Using with `SimpleDirectoryReader`
 
 You can also integrate the parser as the default PDF loader in `SimpleDirectoryReader`:
 
 ```python
-import nest_asyncio
-
-nest_asyncio.apply()
-
 from llama_cloud_services import LlamaParse
 from llama_index.core import SimpleDirectoryReader
 
@@ -136,6 +156,7 @@ Several end-to-end indexing examples can be found in the examples folder
 - [Getting Started](examples/parse/demo_basic.ipynb)
 - [Advanced RAG Example](examples/parse/demo_advanced.ipynb)
 - [Raw API Usage](examples/parse/demo_api.ipynb)
+- [Result Object Tour](examples/parse/demo_json_tour.ipynb)
 
 ## Documentation
 

pyproject.toml

@@ -8,7 +8,7 @@ python_version = "3.10"
 
 [tool.poetry]
 name = "llama-cloud-services"
-version = "0.6.6"
+version = "0.6.44"
 description = "Tailored SDK clients for LlamaCloud services."
 authors = ["Logan Markewich <logan@runllama.ai>"]
 license = "MIT"
@@ -17,12 +17,14 @@ packages = [{include = "llama_cloud_services"}]
 
 [tool.poetry.dependencies]
 python = ">=3.9,<4.0"
-llama-index-core = ">=0.11.0"
-llama-cloud = "^0.1.15"
-pydantic = "!=2.10"
+llama-index-core = ">=0.12.0"
+llama-cloud = "==0.1.33"
+pydantic = ">=2.8,!=2.10"
 click = "^8.1.7"
 python-dotenv = "^1.0.1"
 eval-type-backport = {python = "<3.10", version = "^0.2.0"}
+platformdirs = "^4.3.7"
+tenacity = ">=8.5.0, <10.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"

tests/beta/agent_data/test_agent_data_client.py

@@ -0,0 +1,129 @@
+import os
+import httpx
+import pytest
+import uuid
+from pydantic import BaseModel
+from dotenv import load_dotenv
+from pathlib import Path
+
+from llama_cloud.client import AsyncLlamaCloud
+from llama_cloud_services.beta.agent_data import AsyncAgentDataClient
+
+
+class TrailingSlashHttpxClient(httpx.AsyncClient):
+    """Custom httpx client that ensures all URLs have trailing slashes"""
+
+    async def request(self, method, url, **kwargs):
+        # Convert URL to string and ensure trailing slash
+        url_str = str(url)
+        if not url_str.endswith("/") and "?" not in url_str:
+            url_str += "/"
+        self.headers["Authorization"] = f"Bearer {LLAMA_CLOUD_API_KEY}"
+        kwargs.pop("headers", None)
+        return await super().request(method, url_str, headers=self.headers, **kwargs)
+
+
+# Load environment variables
+def load_test_dotenv():
+    dotenv_path = Path(__file__).parent.parent.parent.parent / ".env.dev"
+    load_dotenv(dotenv_path, override=True)
+
+
+load_test_dotenv()
+
+# Get configuration from environment
+LLAMA_CLOUD_API_KEY = os.getenv("LLAMA_CLOUD_API_KEY")
+LLAMA_CLOUD_BASE_URL = os.getenv("LLAMA_CLOUD_BASE_URL")
+LLAMA_DEPLOY_DEPLOYMENT_NAME = os.getenv("LLAMA_DEPLOY_DEPLOYMENT_NAME")
+
+
+class TestData(BaseModel):
+    """Simple test data model for agent data testing"""
+
+    name: str
+    test_id: str
+    value: int
+
+
+# Skip all tests if API key is not set
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    not LLAMA_CLOUD_API_KEY or not LLAMA_DEPLOY_DEPLOYMENT_NAME,
+    reason="LLAMA_CLOUD_API_KEY or LLAMA_DEPLOY_DEPLOYMENT_NAME not set",
+)
+async def test_agent_data_crud_operations():
+    """Test basic CRUD operations for agent data with automatic cleanup"""
+    # Create unique test identifier to avoid conflicts
+    test_id = str(uuid.uuid4())
+
+    # Set up client
+    client = AsyncLlamaCloud(
+        token=LLAMA_CLOUD_API_KEY,
+        base_url=LLAMA_CLOUD_BASE_URL,
+        httpx_client=TrailingSlashHttpxClient(timeout=60, follow_redirects=True),
+    )
+
+    # Create agent data client with unique collection name
+    agent_data_client = AsyncAgentDataClient(
+        client=client,
+        type=TestData,
+        collection_name=f"test-collection-{test_id[:8]}",
+        agent_url_id=LLAMA_DEPLOY_DEPLOYMENT_NAME,
+    )
+
+    # Create test data
+    test_data = TestData(name="test-item", test_id=test_id, value=42)
+
+    created_item = None
+    try:
+        # Test CREATE
+        created_item = await agent_data_client.create_agent_data(test_data)
+        assert created_item.data.name == "test-item"
+        assert created_item.data.test_id == test_id
+        assert created_item.data.value == 42
+        assert created_item.id is not None
+
+        # Test READ
+        retrieved_item = await agent_data_client.get_agent_data(created_item.id)
+        assert retrieved_item.id == created_item.id
+        assert retrieved_item.data.name == "test-item"
+        assert retrieved_item.data.test_id == test_id
+        assert retrieved_item.data.value == 42
+
+        # Test SEARCH
+        search_results = await agent_data_client.search_agent_data(
+            filter={"test_id": {"eq": test_id}}, page_size=10, include_total=True
+        )
+        assert len(search_results.items) == 1
+        assert search_results.items[0].data.test_id == test_id
+        assert search_results.total == 1
+
+        # Test AGGREGATE
+        aggregate_results = await agent_data_client.aggregate_agent_data(
+            group_by=["test_id"], count=True
+        )
+        assert len(aggregate_results.items) == 1
+        assert aggregate_results.items[0].group_key["test_id"] == test_id
+        assert aggregate_results.items[0].count == 1
+
+        # Test UPDATE
+        updated_data = TestData(name="updated-item", test_id=test_id, value=84)
+        updated_item = await agent_data_client.update_agent_data(
+            created_item.id, updated_data
+        )
+        assert updated_item.data.name == "updated-item"
+        assert updated_item.data.value == 84
+        assert updated_item.id == created_item.id
+
+        # Verify update persisted
+        verified_item = await agent_data_client.get_agent_data(created_item.id)
+        assert verified_item.data.name == "updated-item"
+        assert verified_item.data.value == 84
+
+    finally:
+        # Clean up test data
+        if created_item is not None:
+            try:
+                await agent_data_client.delete_agent_data(created_item.id)
+            except Exception as e:
+                print(f"Warning: Failed to cleanup test data {created_item.id}: {e}")

tests/beta/agent_data/test_agent_data_schema.py

@@ -0,0 +1,109 @@
+from datetime import datetime
+from typing import Any, Dict
+
+import pytest
+from llama_cloud.types.agent_data import AgentData
+from llama_cloud.types.aggregate_group import AggregateGroup
+from pydantic import BaseModel, ValidationError
+
+from llama_cloud_services.beta.agent_data.schema import (
+    ExtractedData,
+    TypedAgentData,
+    TypedAggregateGroup,
+)
+
+
+# Test data models
+class Person(BaseModel):
+    name: str
+    age: int
+    email: str
+
+
+class Company(BaseModel):
+    name: str
+    industry: str
+    employees: int
+
+
+def test_typed_agent_data_from_raw():
+    """Test TypedAgentData.from_raw class method."""
+    raw_data = AgentData(
+        id="456",
+        agent_slug="extraction-agent",
+        collection="employees",
+        data={"name": "Jane Smith", "age": 25, "email": "jane@company.com"},
+        created_at=datetime.now(),
+        updated_at=datetime.now(),
+    )
+
+    typed_data = TypedAgentData.from_raw(raw_data, Person)
+
+    assert typed_data.id == "456"
+    assert typed_data.agent_url_id == "extraction-agent"
+    assert typed_data.collection == "employees"
+    assert typed_data.data.name == "Jane Smith"
+    assert typed_data.data.age == 25
+    assert typed_data.data.email == "jane@company.com"
+
+
+def test_typed_agent_data_from_raw_validation_error():
+    """Test TypedAgentData.from_raw with invalid data."""
+    raw_data = AgentData(
+        id="789",
+        agent_slug="test-agent",
+        collection="people",
+        data={"name": "Invalid Person", "age": "not_a_number"},  # Invalid age
+        created_at=datetime.now(),
+        updated_at=datetime.now(),
+    )
+
+    with pytest.raises(ValidationError):
+        TypedAgentData.from_raw(raw_data, Person)
+
+
+def test_extracted_data_create_method():
+    """Test ExtractedData.create class method."""
+    person = Person(name="Created Person", age=35, email="created@example.com")
+
+    # Test with defaults
+    extracted = ExtractedData.create(person)
+    assert extracted.original_data == person
+    assert extracted.data == person
+    assert extracted.status == "in_review"
+    assert extracted.confidence == {}
+
+    # Test with custom values
+    extracted_custom = ExtractedData.create(
+        person, status="accepted", confidence={"name": 0.99}
+    )
+    assert extracted_custom.status == "accepted"
+    assert extracted_custom.confidence["name"] == 0.99
+
+
+def test_extracted_data_with_dict():
+    """Test ExtractedData with dict data instead of Pydantic model."""
+    data_dict = {"name": "Dict Person", "age": 45, "email": "dict@example.com"}
+
+    extracted = ExtractedData[Dict[str, Any]](
+        original_data=data_dict, data=data_dict, status="accepted", confidence={}
+    )
+
+    assert extracted.original_data["name"] == "Dict Person"
+    assert extracted.data["age"] == 45
+
+
+def test_typed_aggregate_group_from_raw():
+    """Test TypedAggregateGroup.from_raw class method."""
+    raw_group = AggregateGroup(
+        group_key={"industry": "Technology"},
+        count=25,
+        first_item={"name": "Tech Corp", "industry": "Technology", "employees": 500},
+    )
+
+    typed_group = TypedAggregateGroup.from_raw(raw_group, Company)
+
+    assert typed_group.group_key["industry"] == "Technology"
+    assert typed_group.count == 25
+    assert typed_group.first_item.name == "Tech Corp"
+    assert typed_group.first_item.employees == 500

tests/extract/conftest.py

@@ -0,0 +1,41 @@
+import os
+from typing import List
+from llama_cloud_services.extract import LlamaExtract
+
+# Global storage for agents to cleanup
+_TEST_AGENTS_TO_CLEANUP: List[str] = []
+
+
+def pytest_sessionfinish(session, exitstatus):
+    """Hook that runs after all tests complete - cleanup agents here"""
+    print(
+        f"pytest_sessionfinish hook called! Agents to cleanup: {_TEST_AGENTS_TO_CLEANUP}"
+    )
+
+    if _TEST_AGENTS_TO_CLEANUP:
+        print("Creating cleanup client...")
+        # Create a fresh client just for cleanup
+        cleanup_client = LlamaExtract(
+            api_key=os.getenv("LLAMA_CLOUD_API_KEY"),
+            base_url=os.getenv("LLAMA_CLOUD_BASE_URL"),
+            project_id=os.getenv("LLAMA_CLOUD_PROJECT_ID"),
+            verbose=True,
+        )
+
+        for agent_id in _TEST_AGENTS_TO_CLEANUP:
+            try:
+                print(f"Deleting agent {agent_id}...")
+                cleanup_client.delete_agent(agent_id)
+                print(f"Cleaned up agent {agent_id}")
+            except Exception as e:
+                print(f"Warning: Failed to delete agent {agent_id}: {e}")
+
+        _TEST_AGENTS_TO_CLEANUP.clear()
+        print("Agent cleanup completed")
+    else:
+        print("No agents to cleanup")
+
+
+def register_agent_for_cleanup(agent_id: str):
+    """Register an agent ID for cleanup at the end of the test session"""
+    _TEST_AGENTS_TO_CLEANUP.append(agent_id)

tests/extract/test_benchmark.py

@@ -60,7 +60,7 @@ def get_test_cases():
 
         settings = [
             ExtractConfig(extraction_mode=ExtractMode.FAST),
-            ExtractConfig(extraction_mode=ExtractMode.ACCURATE),
+            ExtractConfig(extraction_mode=ExtractMode.BALANCED),
         ]
 
         for input_file in sorted(input_files):
@@ -133,7 +133,7 @@ async def test_extraction(
     test_case: TestCase, extraction_agent: ExtractionAgent
 ) -> None:
     start = perf_counter()
-    result = await extraction_agent._queue_extraction_test(
+    result = await extraction_agent._run_extraction_test(
         test_case.input_file,
         extract_settings=LlamaExtractSettings(
             llama_parse_params=LlamaParseParameters(

tests/extract/test_extract_api.py

@@ -3,8 +3,9 @@ import pytest
 from pathlib import Path
 from pydantic import BaseModel
 
-from llama_cloud_services.extract import LlamaExtract, ExtractionAgent
+from llama_cloud_services.extract import LlamaExtract, ExtractionAgent, SourceText
 from tests.extract.util import load_test_dotenv
+from .conftest import register_agent_for_cleanup
 
 load_test_dotenv()
 
@@ -27,7 +28,7 @@ class TestSchema(BaseModel):
 
 # Test data paths
 TEST_DIR = Path(__file__).parent / "data"
-TEST_PDF = TEST_DIR / "slide" / "saas_slide.pdf"
+TEST_PDF = TEST_DIR / "api_test" / "noisebridge_receipt.pdf"
 
 
 @pytest.fixture
@@ -58,7 +59,7 @@ def test_schema_dict():
 
 @pytest.fixture
 def test_agent(llama_extract, test_agent_name, test_schema_dict, request):
-    """Creates a test agent and cleans it up after the test"""
+    """Creates a test agent and collects it for cleanup at the end of all tests"""
     test_id = request.node.nodeid
     test_hash = hex(hash(test_id))[-8:]
     base_name = test_agent_name
@@ -86,13 +87,11 @@ def test_agent(llama_extract, test_agent_name, test_schema_dict, request):
         print(f"Warning: Failed to cleanup existing agent: {e}")
 
     agent = llama_extract.create_agent(name=name, data_schema=schema)
-    yield agent
 
-    # Cleanup after test
-    try:
-        llama_extract.delete_agent(agent.id)
-    except Exception as e:
-        print(f"Warning: Failed to delete agent {agent.id}: {e}")
+    # Add agent to cleanup list via conftest helper
+    register_agent_for_cleanup(agent.id)
+
+    yield agent
 
 
 class TestLlamaExtract:
@@ -150,6 +149,40 @@ class TestExtractionAgent:
         assert "title" in result.data
         assert "summary" in result.data
 
+    def test_extract_file_from_buffered_io(self, test_agent):
+        result = test_agent.extract(SourceText(file=open(TEST_PDF, "rb")))
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_file_from_bytes(self, test_agent):
+        with open(TEST_PDF, "rb") as f:
+            file_bytes = f.read()
+        result = test_agent.extract(SourceText(file=file_bytes, filename=TEST_PDF.name))
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
+    def test_extract_from_text_content(self, test_agent):
+        TEST_TEXT = """
+        # Llamas
+        Llamas are social animals and live with others as a herd. Their wool is soft and
+        contains only a small amount of lanolin.[2] Llamas can learn simple tasks after a
+        few repetitions. When using a pack, they can carry about 25 to 30% of their body
+        weight for 8 to 13 km (5–8 miles).[3] The name llama (also historically spelled
+        "glama") was adopted by European settlers from native Peruvians.
+        """
+        result = test_agent.extract(SourceText(text_content=TEST_TEXT))
+        assert result.status == "SUCCESS"
+        assert result.data is not None
+        assert isinstance(result.data, dict)
+        assert "title" in result.data
+        assert "summary" in result.data
+
     @pytest.mark.asyncio
     async def test_extract_multiple_files(self, test_agent):
         files = [TEST_PDF, TEST_PDF]  # Using same file twice for testing

tests/extract/test_extract_e2e.py

@@ -55,7 +55,7 @@ def get_test_cases():
 
         settings = [
             ExtractConfig(extraction_mode=ExtractMode.FAST),
-            ExtractConfig(extraction_mode=ExtractMode.ACCURATE),
+            ExtractConfig(extraction_mode=ExtractMode.BALANCED),
         ]
 
         for input_file in sorted(input_files):

tests/parse/test_llama_parse.py

@@ -1,6 +1,7 @@
 import os
 import pytest
 import shutil
+from typing import Optional, cast
 from fsspec.implementations.local import LocalFileSystem
 from httpx import AsyncClient
 
@@ -20,11 +21,15 @@ def test_simple_page_text() -> None:
     assert len(result[0].text) > 0
 
 
-@pytest.fixture
-def markdown_parser() -> LlamaParse:
+@pytest.fixture(params=[None, 2])
+def markdown_parser(request: pytest.FixtureRequest) -> LlamaParse:
     if os.environ.get("LLAMA_CLOUD_API_KEY", "") == "":
         pytest.skip("LLAMA_CLOUD_API_KEY not set")
-    return LlamaParse(result_type="markdown", ignore_errors=False)
+    return LlamaParse(
+        result_type="markdown",
+        ignore_errors=False,
+        partition_pages=cast(Optional[int], request.param),
+    )
 
 
 def test_simple_page_markdown(markdown_parser: LlamaParse) -> None:
@@ -35,8 +40,6 @@ def test_simple_page_markdown(markdown_parser: LlamaParse) -> None:
 
 
 def test_simple_page_markdown_bytes(markdown_parser: LlamaParse) -> None:
-    markdown_parser = LlamaParse(result_type="markdown", ignore_errors=False)
-
     filepath = "tests/test_files/attention_is_all_you_need.pdf"
     with open(filepath, "rb") as f:
         file_bytes = f.read()
@@ -51,8 +54,6 @@ def test_simple_page_markdown_bytes(markdown_parser: LlamaParse) -> None:
 
 
 def test_simple_page_markdown_buffer(markdown_parser: LlamaParse) -> None:
-    markdown_parser = LlamaParse(result_type="markdown", ignore_errors=False)
-
     filepath = "tests/test_files/attention_is_all_you_need.pdf"
     with open(filepath, "rb") as f:
         # client must provide extra_info with file_name
@@ -161,9 +162,12 @@ async def test_mixing_input_types() -> None:
     os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
     reason="LLAMA_CLOUD_API_KEY not set",
 )
+@pytest.mark.parametrize("partition_pages", [None, 2])
 @pytest.mark.asyncio
-async def test_download_images() -> None:
-    parser = LlamaParse(result_type="markdown", take_screenshot=True)
+async def test_download_images(partition_pages: Optional[int]) -> None:
+    parser = LlamaParse(
+        result_type="markdown", take_screenshot=True, partition_pages=partition_pages
+    )
     filepath = "tests/test_files/attention_is_all_you_need.pdf"
     json_result = await parser.aget_json([filepath])
 
@@ -175,3 +179,17 @@ async def test_download_images() -> None:
 
     await parser.aget_images(json_result, download_path)
     assert len(os.listdir(download_path)) == len(json_result[0]["pages"][0]["images"])
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("split_by_page,expected", [(True, 4), (False, 1)])
+async def test_multiple_page_markdown(
+    markdown_parser: LlamaParse,
+    split_by_page: bool,
+    expected: int,
+) -> None:
+    markdown_parser.split_by_page = split_by_page
+    filepath = "tests/test_files/TOS.pdf"
+    result = await markdown_parser.aload_data(filepath)
+    assert len(result) == expected
+    assert all(len(doc.text) > 0 for doc in result)

tests/parse/test_llama_parse_result.py

@@ -0,0 +1,204 @@
+import tempfile
+import os
+import pytest
+from typing import Optional
+from llama_cloud_services import LlamaParse
+from llama_cloud_services.parse.types import JobResult
+
+
+@pytest.fixture
+def file_path() -> str:
+    return "tests/test_files/attention_is_all_you_need.pdf"
+
+
+@pytest.fixture
+def chart_file_path() -> str:
+    return "tests/test_files/attention_is_all_you_need_chart.pdf"
+
+
+@pytest.fixture
+def multiple_page_path() -> str:
+    return "tests/test_files/TOS.pdf"
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+@pytest.mark.parametrize("partition_pages", [None, 2])
+async def test_basic_parse_result(file_path: str, partition_pages: Optional[int]):
+    parser = LlamaParse(
+        take_screenshot=True,
+        auto_mode=True,
+        fast_mode=False,
+        partition_pages=partition_pages,
+    )
+    result = await parser.aparse(file_path)
+
+    assert isinstance(result, JobResult)
+    assert result.job_id is not None
+    assert result.file_name == file_path
+    assert len(result.pages) > 0
+
+    assert result.pages[0].text is not None
+    assert len(result.pages[0].text) > 0
+
+    assert result.pages[0].md is not None
+    assert len(result.pages[0].md) > 0
+
+    assert result.pages[0].md != result.pages[0].text
+
+    assert len(result.pages[0].images) > 0
+    assert result.pages[0].images[0].name is not None
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        file_names = await result.asave_all_images(temp_dir)
+        assert len(file_names) > 0
+        for file_name in file_names:
+            assert os.path.exists(file_name)
+            assert os.path.getsize(file_name) > 0
+
+    assert result.job_metadata is not None
+
+    text_documents = result.get_text_documents(
+        split_by_page=True,
+    )
+    assert len(text_documents) > 0
+    assert text_documents[0].text is not None
+    assert len(text_documents[0].text) > 0
+
+    markdown_documents = result.get_markdown_documents(
+        split_by_page=True,
+    )
+    assert len(markdown_documents) > 0
+    assert markdown_documents[0].text is not None
+    assert len(markdown_documents[0].text) > 0
+
+    image_documents = await result.aget_image_documents(
+        include_screenshot_images=True,
+        include_object_images=False,
+    )
+    assert len(image_documents) > 0
+    assert image_documents[0].image is not None
+    assert len(image_documents[0].resolve_image().getvalue()) > 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.skip(
+    reason="TODO: I don't actually know how to trigger links in the output."
+)
+async def test_link_parse_result(file_path: str):
+    parser = LlamaParse(
+        annotate_links=True,
+    )
+    result = await parser.aparse(file_path)
+
+    assert isinstance(result, JobResult)
+    assert len(result.pages) > 0
+    assert len(result.pages[0].links) > 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+@pytest.mark.skip(reason="TODO: Needs to be fixed in prod. Raising 500 error.")
+async def test_parse_structured_output(file_path: str):
+    parser = LlamaParse(
+        structured_output=True,
+        structured_output_json_schema_name="imFeelingLucky",
+        invalidate_cache=True,
+    )
+    result = await parser.aparse(file_path)
+    assert isinstance(result, JobResult)
+    assert len(result.pages) > 0
+    assert len(result.pages[0].structuredData) > 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+async def test_parse_charts(chart_file_path: str):
+    parser = LlamaParse(
+        extract_charts=True,
+    )
+    result = await parser.aparse(chart_file_path)
+    assert isinstance(result, JobResult)
+    assert len(result.pages) > 0
+    assert len(result.pages[0].charts) > 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+async def test_parse_layout(file_path: str):
+    parser = LlamaParse(
+        extract_layout=True,
+    )
+    result = await parser.aparse(file_path)
+
+    assert isinstance(result, JobResult)
+    assert len(result.pages) > 0
+    assert len(result.pages[0].layout) > 0
+
+
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+@pytest.mark.parametrize("partition_pages", [None, 2])
+def test_parse_multiple_files(
+    file_path: str, chart_file_path: str, partition_pages: Optional[int]
+):
+    parser = LlamaParse(partition_pages=partition_pages)
+    result = parser.parse([file_path, chart_file_path])
+
+    assert isinstance(result, list)
+    assert len(result) == 2
+    assert isinstance(result[0], JobResult)
+    assert isinstance(result[1], JobResult)
+    assert result[0].file_name == file_path
+    assert result[1].file_name == chart_file_path
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("LLAMA_CLOUD_API_KEY", "") == "",
+    reason="LLAMA_CLOUD_API_KEY not set",
+)
+@pytest.mark.parametrize("partition_pages", [None, 2])
+async def test_multiple_page_parse_result(
+    multiple_page_path: str, partition_pages: Optional[int]
+):
+    parser = LlamaParse(
+        take_screenshot=True,
+        auto_mode=True,
+        fast_mode=False,
+        partition_pages=partition_pages,
+    )
+    results = await parser.aparse(multiple_page_path)
+    if partition_pages is None:
+        assert isinstance(results, JobResult)
+        results = [results]
+    else:
+        assert isinstance(results, list)
+
+    for result in results:
+        assert isinstance(result, JobResult)
+        assert result.job_id is not None
+        assert result.file_name == multiple_page_path
+        assert len(result.pages) > 0
+
+        assert result.pages[0].text is not None
+        assert len(result.pages[0].text) > 0
+
+        assert result.pages[0].md is not None
+        assert len(result.pages[0].md) > 0
+
+        assert result.pages[0].md != result.pages[0].text

tests/parse/test_utils.py

@@ -0,0 +1,30 @@
+import pytest
+
+
+from llama_cloud_services.parse.utils import expand_target_pages, partition_pages
+
+
+def test_expand_target_pages() -> None:
+    with pytest.raises(ValueError):
+        list(expand_target_pages("x"))
+    with pytest.raises(ValueError):
+        list(expand_target_pages("1-2-3"))
+    with pytest.raises(ValueError):
+        list(expand_target_pages("2-1"))
+    result = list(expand_target_pages("0,2-3,5,8-10"))
+    assert result == [0, 2, 3, 5, 8, 9, 10]
+
+
+def test_partion_pages() -> None:
+    pages = [0, 2, 3, 5, 8, 9, 10]
+    with pytest.raises(ValueError):
+        list(partition_pages(pages, 0))
+    result = list(partition_pages(pages, 3))
+    assert result == ["0,2-3", "5,8-9", "10"]
+
+    with pytest.raises(ValueError):
+        list(partition_pages(pages, 3, 0))
+    result = list(partition_pages(pages, 3, max_pages=5))
+    assert result == ["0,2-3", "5,8"]
+    result = list(partition_pages(pages, 3, max_pages=10))
+    assert result == ["0,2-3", "5,8-9", "10"]

tests/report/test_llama_report.py

@@ -7,7 +7,8 @@ from llama_cloud_services.report import LlamaReport, ReportClient
 
 # Skip tests if no API key is set
 pytestmark = pytest.mark.skipif(
-    not os.getenv("LLAMA_CLOUD_API_KEY"), reason="No API key provided"
+    not os.getenv("LLAMA_CLOUD_API_KEY") or os.getenv("CI") == "true",
+    reason="No API key provided",
 )
 
 
@@ -62,6 +63,10 @@ async def report(
 
 
 @pytest.mark.asyncio
+@pytest.mark.xfail(
+    condition=lambda: os.getenv("CI"),
+    reason="Backend db issues; needs to be fixed.",
+)
 async def test_create_and_delete_report(
     client: LlamaReport, report: ReportClient
 ) -> None:

tests/test_utils.py

@@ -0,0 +1,66 @@
+from pydantic import BaseModel
+from llama_cloud_services.utils import check_extra_params
+
+
+class MyModel(BaseModel):
+    name: str
+    age: int
+    email: str
+    is_active: bool
+
+
+def test_check_extra_params_no_extra():
+    """Test when all parameters are valid - should return empty lists."""
+    data = {"name": "John", "age": 25, "email": "john@example.com", "is_active": True}
+
+    extra_params, suggestions = check_extra_params(MyModel, data)
+
+    assert extra_params == []
+    assert suggestions == []
+
+
+def test_check_extra_params_with_typos():
+    """Test when there are extra parameters that are close to valid ones (typos)."""
+    data = {
+        "name": "John",
+        "age": 25,
+        "emial": "john@example.com",  # typo: emial instead of email
+        "is_activ": True,  # typo: is_activ instead of is_active
+        "address": "123 Main St",  # completely different parameter
+    }
+
+    extra_params, suggestions = check_extra_params(MyModel, data)
+
+    assert len(extra_params) == 3
+    assert "emial" in extra_params
+    assert "is_activ" in extra_params
+    assert "address" in extra_params
+
+    # Check that typo suggestions are provided
+    assert len(suggestions) == 3
+    assert "Did you mean 'email' instead of 'emial'?" in suggestions[0]
+    assert "Did you mean 'is_active' instead of 'is_activ'?" in suggestions[1]
+    assert "check the documentation or update the package" in suggestions[2]
+
+
+def test_check_extra_params_completely_invalid():
+    """Test when there are extra parameters with no close matches."""
+    data = {
+        "name": "John",
+        "xyz": "invalid",
+        "random_field": 123,
+        "completely_different": True,
+    }
+
+    extra_params, suggestions = check_extra_params(MyModel, data)
+
+    assert len(extra_params) == 3
+    assert "xyz" in extra_params
+    assert "random_field" in extra_params
+    assert "completely_different" in extra_params
+
+    # All suggestions should be generic (no close matches)
+    assert len(suggestions) == 3
+    for suggestion in suggestions:
+        assert "check the documentation or update the package" in suggestion
+        assert "Did you mean" not in suggestion