Delete parse.md

Added deprecation notice and removed outdated content.

.github/workflows/hourly_extract_e2e.yml

@@ -0,0 +1,162 @@
+name: Extract E2E Tests (every 4 hours)
+
+on:
+  schedule:
+    - cron: "0 */4 * * *"
+  workflow_dispatch:
+    # Allows manual triggering
+    inputs:
+      environment:
+        description: "Environment to run the tests in"
+        required: false
+        default: staging
+        type: choice
+        options:
+          - staging
+          - production
+      notify_slack:
+        description: "Notify Slack"
+        required: false
+        default: false
+        type: boolean
+  workflow_call:
+
+env:
+  UV_VERSION: "0.7.20"
+  PYTHON_VERSION: "3.12"
+  SLACK_CHANNEL_ID: C078PHNTF44 # Extract channel ID
+  API_E2E_LOG_PATH: ${{ github.workspace }}/extract-e2e.log
+
+jobs:
+  extract-e2e:
+    name: "Extract E2E Tests (${{ matrix.environment }})"
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.environment }}
+      cancel-in-progress: true
+    strategy:
+      fail-fast: false
+      matrix:
+        environment: ${{ github.event_name == 'schedule' && fromJson('["staging", "production"]') || fromJson(format('["{0}"]', github.event.inputs.environment || 'staging')) }}
+    steps:
+      - name: Set runtime inputs
+        id: runtime
+        run: |
+          environment=${{ matrix.environment }}
+          notify_slack=${{ github.event.inputs.notify_slack || github.event_name == 'schedule' }}
+          echo "environment=${environment}" >> $GITHUB_OUTPUT
+          echo "notify_slack=${notify_slack}" >> $GITHUB_OUTPUT
+
+          if [ "${environment}" = "production" ]; then
+            echo "LLAMA_CLOUD_BASE_URL=https://api.cloud.llamaindex.ai" >> $GITHUB_ENV
+            api_key_secret="${{ secrets.LLAMA_CLOUD_API_KEY }}"
+            project_id_secret="${{ secrets.LLAMA_CLOUD_PROJECT_ID }}"
+          else
+            echo "LLAMA_CLOUD_BASE_URL=https://api.staging.llamaindex.ai" >> $GITHUB_ENV
+            api_key_secret="${{ secrets.LLAMA_CLOUD_API_KEY_STAGING }}"
+            project_id_secret="${{ secrets.LLAMA_CLOUD_PROJECT_ID_STAGING }}"
+          fi
+
+          if [ -n "$api_key_secret" ]; then
+            echo "LLAMA_CLOUD_API_KEY=$api_key_secret" >> $GITHUB_ENV
+          fi
+
+          if [ -n "$project_id_secret" ]; then
+            echo "LLAMA_CLOUD_PROJECT_ID=$project_id_secret" >> $GITHUB_ENV
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Set up Python
+        run: uv python install ${{ env.PYTHON_VERSION }} && uv python pin ${{ env.PYTHON_VERSION }}
+
+      - name: Run Extract E2E tests
+        id: extract-tests
+        continue-on-error: true
+        working-directory: py
+        run: |
+          set -o pipefail
+          rm -f "$API_E2E_LOG_PATH"
+          uv run pytest -v -n 8 --timeout=300 --session-timeout=1740 tests/extract/ 2>&1 | tee "$API_E2E_LOG_PATH"
+
+      - name: Extract pytest failure summary
+        id: failed-tests
+        if: steps.extract-tests.outcome == 'failure' || cancelled()
+        run: |
+          summary="$(python3 - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          log_path = Path(os.environ["API_E2E_LOG_PATH"])
+          if not log_path.exists():
+              print("Test log not found.")
+              raise SystemExit(0)
+
+          lines = log_path.read_text(errors="ignore").splitlines()
+
+          # Find the "short test summary info" section
+          start = None
+          for i, line in enumerate(lines):
+              if line.startswith("=") and "short test summary info" in line:
+                  start = i + 1
+                  break
+
+          if start is None:
+              print("No test summary found.")
+              raise SystemExit(0)
+
+          # Extract just the FAILED/ERROR lines (test name + short reason)
+          failed_tests = []
+          for line in lines[start:]:
+              if line.startswith("="):
+                  break  # End of section
+              if line.startswith("FAILED ") or line.startswith("ERROR "):
+                  # Extract test name and truncate the error message
+                  match = re.match(r"(FAILED|ERROR) ([\w/:.\[\]_-]+)", line)
+                  if match:
+                      failed_tests.append(f"{match.group(1)}: {match.group(2)}")
+
+          if failed_tests:
+              print("\n".join(failed_tests[:20]))  # Limit to 20 tests max
+          else:
+              print("No failed tests found in summary.")
+          PY
+          )"
+          if [ -z "$summary" ]; then
+            summary="Failed test summary not available. Review the full run logs."
+          fi
+          {
+            printf 'summary<<EOF\n%s\nEOF\n' "$summary"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Check test results
+        if: always()
+        run: |
+          if [ "${{ steps.extract-tests.outcome }}" == "failure" ]; then
+            echo "Extract E2E tests failed"
+            exit 1
+          fi
+
+      - name: Post to Extract Slack channel
+        id: slack
+        if: (failure() || cancelled()) && steps.runtime.outputs.notify_slack == 'true'
+        uses: slackapi/slack-github-action@v2.1.1
+        with:
+          channel-id: ${{ env.SLACK_CHANNEL_ID }}
+          slack-message: |
+            :red_circle: *Extract E2E Failed* (${{ steps.runtime.outputs.environment }})
+            ```
+            ${{ steps.failed-tests.outputs.summary }}
+            ```
+            <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>
+        env:
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

.github/workflows/test_e2e_py.yml

@@ -12,6 +12,7 @@ env:
 jobs:
   test_e2e:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     strategy:
       # You can use PyPy versions in python-version.
       # For example, pypy-2.7 and pypy-3.8

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
-        exclude: ".*uv.lock"
+        exclude: ".*uv.lock|examples/"
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.10.1
     hooks:
@@ -34,7 +34,7 @@ repos:
     rev: v1.0.1
     hooks:
       - id: mypy
-        exclude: ^py/tests|^py/unit_tests
+        exclude: ^py/tests|^py/unit_tests|^examples
         additional_dependencies:
           [
             "types-requests",

README.md

@@ -4,77 +4,12 @@
 
 # Llama Cloud Services
 
-This repository contains the code for hand-written SDKs and clients for interacting with LlamaCloud.
-
-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.).
-- [LlamaExtract](./extract.md) - A prebuilt agentic data extractor that can be used to transform data into a structured JSON representation.
-- [LlamaCloud Index](./index.md) - A widely customizable and fully automated document ingestion pipeline that also serves retrieval purposes.
-
-## Getting Started
-
-Install the package:
-
-```bash
-pip install llama-cloud-services
-```
-
-Then, get your API key from [LlamaCloud](https://cloud.llamaindex.ai/).
-
-Then, you can use the services in your code:
-
-```python
-from llama_cloud_services import (
-    LlamaParse,
-    LlamaExtract,
-    LlamaCloudIndex,
-)
-
-parser = LlamaParse(api_key="YOUR_API_KEY")
-extract = LlamaExtract(api_key="YOUR_API_KEY")
-index = LlamaCloudIndex(
-    "my_first_index", project_name="default", api_key="YOUR_API_KEY"
-)
-```
-
-See the quickstart guides for each service for more information:
-
-- [LlamaParse](./parse.md)
-- [LlamaExtract](./extract.md)
-- [LlamaCloud Index](./index.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,
-    LlamaExtract,
-    EU_BASE_URL,
-)
-
-parser = LlamaParse(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
-extract = LlamaExtract(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
-index = LlamaCloudIndex(
-    "my_first_index",
-    project_name="default",
-    api_key="YOUR_API_KEY",
-    base_url=EU_BASE_URL,
-)
-```
-
-## Documentation
-
-You can see complete SDK and API documentation for each service on [our official docs](https://docs.cloud.llamaindex.ai/).
-
-## Terms of Service
-
-See the [Terms of Service Here](./TOS.pdf).
-
-## Get in Touch (LlamaCloud)
-
-You can get in touch with us by following our [contact link](https://www.llamaindex.ai/contact).
+> **⚠️ DEPRECATION NOTICE**
+>
+> This repository and its packages are deprecated and will be maintained until **May 1, 2026**.
+>
+> **Please migrate to the new packages:**
+> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))
+> - **TypeScript**: `npm install @llamaindex/llama-cloud` ([GitHub](https://github.com/run-llama/llama-cloud-ts))
+>
+> The new packages provide the same functionality with improved performance, better support, and active development.

examples-ts/classify/package.json

@@ -12,7 +12,7 @@
     "@tanstack/react-router": "^1.133.22",
     "@tanstack/react-router-devtools": "^1.133.22",
     "@tanstack/react-start": "^1.133.22",
-    "llama-cloud-services": "^0.3.10",
+    "llama-cloud-services": "file:../../ts/llama_cloud_services",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwind-merge": "^2.6.0",

examples-ts/classify/src/routes/api/classify.ts

@@ -15,7 +15,7 @@ export const Route = createFileRoute('/api/classify')({
           const rawRes = await classifier.classify(
             classificationRules,
             parsingConfig,
-            [new Uint8Array(buff)],
+            { fileContents: [new Uint8Array(buff)] },
           )
           const results = rawRes.items
           let classification = ""

examples/README.md

@@ -1,4 +1,14 @@
 # LlamaCloud Services Examples - Python
+> **⚠️ DEPRECATION NOTICE**
+>
+> This repository and its packages are deprecated and will be maintained until **May 1, 2026**.
+>
+> **Please migrate to the new packages:**
+> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))
+> - **TypeScript**: `npm install @llamaindex/llama-cloud` ([GitHub](https://github.com/run-llama/llama-cloud-ts))
+>
+> The new packages provide the same functionality with improved performance, better support, and active development.
+
 
 In this folder you will find several python notebooks that contain examples regarding:
 

examples/batch/parse/.gitignore

@@ -0,0 +1 @@
+sample_files/

examples/batch/parse/batch_parse_directory.ipynb

@@ -0,0 +1,815 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cell-0",
+   "metadata": {},
+   "source": [
+    "# Batch Parse with LlamaCloud Directories\n",
+    "\n",
+    "This notebook demonstrates how to use LlamaCloud's batch processing API to parse multiple files in a directory. The workflow includes:\n",
+    "\n",
+    "1. **Creating a Directory** - Set up a directory to organize your files\n",
+    "2. **Uploading Files** - Upload multiple files to the directory\n",
+    "3. **Starting a Batch Parse Job** - Kick off batch processing on all files\n",
+    "4. **Monitoring Progress** - Check the status and view results\n",
+    "\n",
+    "This is useful when you need to parse many documents at once, as the batch API handles the orchestration and provides progress tracking."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0c2b5e1a",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-1",
+   "metadata": {},
+   "source": [
+    "## Setup and Installation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install llama-cloud python-dotenv"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "import httpx\n",
+    "\n",
+    "# Load environment variables\n",
+    "load_dotenv()\n",
+    "\n",
+    "# Set your API key\n",
+    "LLAMA_CLOUD_API_KEY = os.environ.get(\"LLAMA_CLOUD_API_KEY\", \"llx-...\")\n",
+    "\n",
+    "# Optional: Set base URL (defaults to https://api.cloud.llamaindex.ai if not set)\n",
+    "LLAMA_CLOUD_BASE_URL = os.environ.get(\n",
+    "    \"LLAMA_CLOUD_BASE_URL\", \"https://api.cloud.llamaindex.ai\"\n",
+    ")\n",
+    "\n",
+    "# Optional: Set project_id if you have one, otherwise it will use your default project\n",
+    "PROJECT_ID = os.environ.get(\"LLAMA_CLOUD_PROJECT_ID\", None)\n",
+    "\n",
+    "print(\"✅ API key configured\")\n",
+    "print(f\"   Base URL: {LLAMA_CLOUD_BASE_URL}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-4",
+   "metadata": {},
+   "source": [
+    "## Setup HTTP Client\n",
+    "\n",
+    "Since the current version of the llama-cloud SDK has some issues with the beta endpoints, we'll use direct HTTP requests with httpx for reliability."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create HTTP client with authentication\n",
+    "headers = {\n",
+    "    \"Authorization\": f\"Bearer {LLAMA_CLOUD_API_KEY}\",\n",
+    "}\n",
+    "\n",
+    "print(\"✅ HTTP client configured\")\n",
+    "print(f\"   Using base URL: {LLAMA_CLOUD_BASE_URL}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-6",
+   "metadata": {},
+   "source": [
+    "## Step 1: Create a Directory\n",
+    "\n",
+    "First, we'll create a directory to organize our files. Directories help you group related files together for batch processing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime\n",
+    "\n",
+    "# Create a directory with a timestamp in the name\n",
+    "timestamp = datetime.now().strftime(\"%Y%m%d-%H%M%S\")\n",
+    "directory_name = f\"batch-parse-demo-{timestamp}\"\n",
+    "\n",
+    "# Create directory using HTTP request\n",
+    "response = httpx.post(\n",
+    "    f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/directories\",\n",
+    "    headers=headers,\n",
+    "    params={\"project_id\": PROJECT_ID},\n",
+    "    json={\n",
+    "        \"name\": directory_name,\n",
+    "        \"description\": \"Demo directory for batch parse example\",\n",
+    "    },\n",
+    "    timeout=60.0,\n",
+    ")\n",
+    "\n",
+    "if response.status_code in [200, 201]:\n",
+    "    directory = response.json()\n",
+    "    directory_id = directory[\"id\"]\n",
+    "    project_id = directory[\"project_id\"]\n",
+    "\n",
+    "    print(f\"✅ Created directory: {directory['name']}\")\n",
+    "    print(f\"   Directory ID: {directory_id}\")\n",
+    "    print(f\"   Project ID: {project_id}\")\n",
+    "else:\n",
+    "    raise Exception(\n",
+    "        f\"Failed to create directory: {response.status_code} - {response.text}\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-8",
+   "metadata": {},
+   "source": [
+    "## Step 2: Upload Files to the Directory\n",
+    "\n",
+    "Now we'll upload some files to our directory. For this demo, we'll download some sample PDFs and upload them.\n",
+    "\n",
+    "You can replace these with your own files."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a directory for sample files\n",
+    "import requests\n",
+    "\n",
+    "os.makedirs(\"sample_files\", exist_ok=True)\n",
+    "\n",
+    "# Sample documents to download\n",
+    "sample_docs = {\n",
+    "    \"attention.pdf\": \"https://arxiv.org/pdf/1706.03762.pdf\",\n",
+    "    \"bert.pdf\": \"https://arxiv.org/pdf/1810.04805.pdf\",\n",
+    "}\n",
+    "\n",
+    "# Download sample documents\n",
+    "for filename, url in sample_docs.items():\n",
+    "    filepath = f\"sample_files/{filename}\"\n",
+    "    if not os.path.exists(filepath):\n",
+    "        print(f\"📥 Downloading {filename}...\")\n",
+    "        response = requests.get(url)\n",
+    "        if response.status_code == 200:\n",
+    "            with open(filepath, \"wb\") as f:\n",
+    "                f.write(response.content)\n",
+    "            print(f\"   ✅ Downloaded {filename}\")\n",
+    "        else:\n",
+    "            print(f\"   ❌ Failed to download {filename}\")\n",
+    "    else:\n",
+    "        print(f\"📁 {filename} already exists\")\n",
+    "\n",
+    "print(\"\\n✅ Sample files ready!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-10",
+   "metadata": {},
+   "source": [
+    "### Upload Files to Directory\n",
+    "\n",
+    "Now let's upload the files to our directory using the `upload_file_to_directory` endpoint."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uploaded_files = []\n",
+    "\n",
+    "# Workaround: Use direct HTTP requests instead of SDK due to SDK bug\n",
+    "import httpx\n",
+    "\n",
+    "for filename in os.listdir(\"sample_files\"):\n",
+    "    if filename.endswith(\".pdf\"):\n",
+    "        filepath = f\"sample_files/{filename}\"\n",
+    "\n",
+    "        print(f\"📤 Uploading {filename}...\")\n",
+    "\n",
+    "        # Upload file using direct HTTP request (SDK has a bug with file uploads)\n",
+    "        with open(filepath, \"rb\") as f:\n",
+    "            # Prepare the multipart form data correctly\n",
+    "            files = {\"upload_file\": (filename, f, \"application/pdf\")}\n",
+    "\n",
+    "            # Make the request directly\n",
+    "            response = httpx.post(\n",
+    "                f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/directories/{directory_id}/files/upload\",\n",
+    "                params={\"project_id\": project_id},\n",
+    "                files=files,\n",
+    "                headers={\"Authorization\": f\"Bearer {LLAMA_CLOUD_API_KEY}\"},\n",
+    "                timeout=60.0,\n",
+    "            )\n",
+    "\n",
+    "            if response.status_code in [200, 201]:\n",
+    "                directory_file = response.json()\n",
+    "                uploaded_files.append(directory_file)\n",
+    "                print(f\"   ✅ Uploaded: {directory_file.get('display_name')}\")\n",
+    "                print(f\"      File ID: {directory_file.get('id')}\")\n",
+    "            else:\n",
+    "                print(f\"   ❌ Upload failed: {response.status_code}\")\n",
+    "                print(f\"      Error: {response.text[:200]}\")\n",
+    "\n",
+    "print(f\"\\n✅ Uploaded {len(uploaded_files)} files to directory\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-12",
+   "metadata": {},
+   "source": [
+    "## Step 3: Create a Batch Parse Job\n",
+    "\n",
+    "Now that we have files in our directory, let's create a batch parse job to process them all at once.\n",
+    "\n",
+    "The batch processing API uses the same configuration as LlamaParse."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Configure the parse job\n",
+    "# This configuration will apply to all files in the directory\n",
+    "job_config = {\n",
+    "    \"job_name\": \"parse_raw_file_job\",  # Must match the JobNames enum value\n",
+    "    \"partitions\": {},\n",
+    "    \"parameters\": {\n",
+    "        \"type\": \"parse\",\n",
+    "        \"lang\": \"en\",\n",
+    "        \"fast_mode\": True,\n",
+    "    },\n",
+    "}\n",
+    "\n",
+    "print(\"✅ Job configuration created\")\n",
+    "print(f\"   Language: {job_config['parameters']['lang']}\")\n",
+    "print(f\"   Fast mode: {job_config['parameters']['fast_mode']}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-14",
+   "metadata": {},
+   "source": [
+    "### Submit the Batch Job\n",
+    "\n",
+    "Now let's submit the batch job to process all files in the directory."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"🚀 Submitting batch parse job for directory: {directory_id}\")\n",
+    "print(f\"   Processing {len(uploaded_files)} files...\\n\")\n",
+    "\n",
+    "# Submit batch job using HTTP request\n",
+    "response = httpx.post(\n",
+    "    f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/batch-processing\",\n",
+    "    headers=headers,\n",
+    "    params={\"project_id\": project_id},\n",
+    "    json={\n",
+    "        \"directory_id\": directory_id,\n",
+    "        \"job_config\": job_config,\n",
+    "        \"page_size\": 100,  # Number of files to fetch per batch\n",
+    "        \"continue_as_new_threshold\": 10,  # Workflow continuation threshold\n",
+    "    },\n",
+    "    timeout=60.0,\n",
+    ")\n",
+    "\n",
+    "if response.status_code in [200, 201]:\n",
+    "    batch_job = response.json()\n",
+    "    batch_job_id = batch_job[\"id\"]\n",
+    "\n",
+    "    print(\"✅ Batch job submitted successfully!\")\n",
+    "    print(f\"   Batch Job ID: {batch_job_id}\")\n",
+    "    print(f\"   Workflow ID: {batch_job.get('workflow_id')}\")\n",
+    "    print(f\"   Status: {batch_job.get('status')}\")\n",
+    "    print(f\"   Total Items: {batch_job.get('total_items')}\")\n",
+    "else:\n",
+    "    raise Exception(\n",
+    "        f\"Failed to create batch job: {response.status_code} - {response.text}\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-16",
+   "metadata": {},
+   "source": [
+    "## Step 4: Monitor Job Progress\n",
+    "\n",
+    "Now let's monitor the batch job progress. We'll poll the status endpoint to see how the job is progressing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import time\n",
+    "\n",
+    "\n",
+    "def print_job_status(status_data):\n",
+    "    \"\"\"Helper function to print job status in a readable format.\"\"\"\n",
+    "    job = status_data[\"job\"]\n",
+    "    progress_pct = status_data[\"progress_percentage\"]\n",
+    "\n",
+    "    print(f\"\\n{'='*60}\")\n",
+    "    print(f\"Job Status: {job['status']}\")\n",
+    "    print(f\"{'='*60}\")\n",
+    "    print(f\"Total Items: {job['total_items']}\")\n",
+    "    print(f\"Completed: {job['processed_items']}\")\n",
+    "    print(f\"Failed: {job['failed_items']}\")\n",
+    "    print(f\"Skipped: {job['skipped_items']}\")\n",
+    "    print(f\"Progress: {progress_pct:.1f}%\")\n",
+    "\n",
+    "    if job.get(\"completed_at\"):\n",
+    "        print(f\"Completed At: {job['completed_at']}\")\n",
+    "    elif job.get(\"started_at\"):\n",
+    "        print(f\"Started At: {job['started_at']}\")\n",
+    "\n",
+    "    print(f\"{'='*60}\")\n",
+    "\n",
+    "\n",
+    "# Poll for status updates\n",
+    "print(\"🔄 Monitoring batch job progress...\")\n",
+    "print(\n",
+    "    \"Note: It may take a few seconds for the workflow to initialize and count files.\\n\"\n",
+    ")\n",
+    "\n",
+    "max_polls = 60  # Maximum number of status checks (increased for longer jobs)\n",
+    "poll_interval = 10  # Seconds between checks\n",
+    "\n",
+    "for i in range(max_polls):\n",
+    "    response = httpx.get(\n",
+    "        f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/batch-processing/{batch_job_id}\",\n",
+    "        headers=headers,\n",
+    "        params={\"project_id\": project_id},\n",
+    "        timeout=60.0,\n",
+    "    )\n",
+    "\n",
+    "    if response.status_code == 200:\n",
+    "        status_data = response.json()\n",
+    "        print_job_status(status_data)\n",
+    "\n",
+    "        # Check if job is complete\n",
+    "        job_status = status_data[\"job\"][\"status\"]\n",
+    "        if job_status in [\"completed\", \"failed\", \"cancelled\"]:\n",
+    "            print(f\"\\n✅ Job finished with status: {job_status}\")\n",
+    "            break\n",
+    "\n",
+    "        if i < max_polls - 1:\n",
+    "            print(f\"\\n⏳ Waiting {poll_interval} seconds before next check...\")\n",
+    "            time.sleep(poll_interval)\n",
+    "    else:\n",
+    "        print(f\"Error getting status: {response.status_code} - {response.text}\")\n",
+    "        break\n",
+    "else:\n",
+    "    print(f\"\\n⚠️  Reached maximum polling attempts. Job may still be running.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-18",
+   "metadata": {},
+   "source": [
+    "## Step 5: View Job Items\n",
+    "\n",
+    "Let's look at the individual items in the batch job to see which files were processed successfully."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get all items in the batch job\n",
+    "response = httpx.get(\n",
+    "    f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/batch-processing/{batch_job_id}/items\",\n",
+    "    headers=headers,\n",
+    "    params={\"project_id\": project_id, \"limit\": 100},\n",
+    "    timeout=60.0,\n",
+    ")\n",
+    "\n",
+    "if response.status_code == 200:\n",
+    "    items_response = response.json()\n",
+    "\n",
+    "    print(f\"\\n📋 Batch Job Items ({items_response['total_size']} total)\")\n",
+    "    print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "    for item in items_response[\"items\"]:\n",
+    "        status_emoji = (\n",
+    "            \"✅\"\n",
+    "            if item[\"status\"] == \"completed\"\n",
+    "            else \"❌\"\n",
+    "            if item[\"status\"] == \"failed\"\n",
+    "            else \"⏳\"\n",
+    "        )\n",
+    "        print(f\"{status_emoji} {item['item_name']}\")\n",
+    "        print(f\"   Status: {item['status']}\")\n",
+    "        print(f\"   Item ID: {item['item_id']}\")\n",
+    "\n",
+    "        if item.get(\"error_message\"):\n",
+    "            print(f\"   Error: {item['error_message']}\")\n",
+    "\n",
+    "        print()\n",
+    "else:\n",
+    "    print(f\"Error listing items: {response.status_code} - {response.text}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-20",
+   "metadata": {},
+   "source": [
+    "## Step 6: Retrieve Processing Results\n",
+    "\n",
+    "For each completed file, we can retrieve the processing results to see where the parsed output is stored."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-21",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get processing results for a specific item\n",
+    "if items_response[\"items\"]:\n",
+    "    first_item = items_response[\"items\"][0]\n",
+    "\n",
+    "    print(f\"\\n🔍 Processing results for: {first_item['item_name']}\")\n",
+    "    print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "    response = httpx.get(\n",
+    "        f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/batch-processing/items/{first_item['item_id']}/processing-results\",\n",
+    "        headers=headers,\n",
+    "        params={\"project_id\": project_id},\n",
+    "        timeout=60.0,\n",
+    "    )\n",
+    "\n",
+    "    if response.status_code == 200:\n",
+    "        results = response.json()\n",
+    "\n",
+    "        print(f\"Item: {results['item_name']}\")\n",
+    "        print(f\"Total processing runs: {len(results['processing_results'])}\\n\")\n",
+    "\n",
+    "        for i, result in enumerate(results[\"processing_results\"], 1):\n",
+    "            print(f\"Run {i}:\")\n",
+    "            print(f\"  Job Type: {result['job_type']}\")\n",
+    "            print(f\"  Processed At: {result['processed_at']}\")\n",
+    "            print(f\"  Parameters Hash: {result['parameters_hash']}\")\n",
+    "\n",
+    "            if result.get(\"output_s3_path\"):\n",
+    "                print(f\"  Output S3 Path: {result['output_s3_path']}\")\n",
+    "\n",
+    "            if result.get(\"output_metadata\"):\n",
+    "                print(f\"  Output Metadata: {result['output_metadata']}\")\n",
+    "\n",
+    "            print()\n",
+    "    else:\n",
+    "        print(f\"Error getting results: {response.status_code} - {response.text}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-22",
+   "metadata": {},
+   "source": [
+    "## Optional: List All Batch Jobs\n",
+    "\n",
+    "You can also list all batch jobs in your project to see the history of batch processing operations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# List all parse jobs in the project\n",
+    "response = httpx.get(\n",
+    "    f\"{LLAMA_CLOUD_BASE_URL}/api/v1/beta/batch-processing\",\n",
+    "    headers=headers,\n",
+    "    params={\"project_id\": project_id, \"job_type\": \"parse\", \"limit\": 10},\n",
+    "    timeout=60.0,\n",
+    ")\n",
+    "\n",
+    "if response.status_code == 200:\n",
+    "    jobs_response = response.json()\n",
+    "\n",
+    "    print(f\"\\n📊 Recent Batch Parse Jobs ({jobs_response['total_size']} total)\")\n",
+    "    print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "    for job in jobs_response[\"items\"]:\n",
+    "        status_emoji = (\n",
+    "            \"✅\"\n",
+    "            if job[\"status\"] == \"completed\"\n",
+    "            else \"❌\"\n",
+    "            if job[\"status\"] == \"failed\"\n",
+    "            else \"⏳\"\n",
+    "        )\n",
+    "        print(f\"{status_emoji} Job ID: {job['id']}\")\n",
+    "        print(f\"   Status: {job['status']}\")\n",
+    "        print(f\"   Directory: {job['directory_id']}\")\n",
+    "        print(f\"   Total Items: {job['total_items']}\")\n",
+    "        print(f\"   Completed: {job['processed_items']}\")\n",
+    "        print(f\"   Created: {job['created_at']}\")\n",
+    "        print()\n",
+    "else:\n",
+    "    print(f\"Error listing jobs: {response.status_code} - {response.text}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "uug7591rkq",
+   "metadata": {},
+   "source": [
+    "## Step 7: Retrieve Parsed Text Results\n",
+    "\n",
+    "Once the batch job is complete, each BatchJobItem will have a `job_id` field that maps to a parse job ID. We can use this ID with the standard parse client methods to fetch the actual parsed text results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "vpp0vxtc0y",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get all completed items and their job IDs\n",
+    "completed_items = [\n",
+    "    item for item in items_response[\"items\"] if item[\"status\"] == \"completed\"\n",
+    "]\n",
+    "\n",
+    "print(f\"📄 Found {len(completed_items)} completed items\\n\")\n",
+    "print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "# Display the job_id for each completed item\n",
+    "for item in completed_items:\n",
+    "    print(f\"📝 {item['item_name']}\")\n",
+    "    print(f\"   Item ID: {item['item_id']}\")\n",
+    "    print(f\"   Parse Job ID: {item['job_id']}\")\n",
+    "    print()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4gck6hwpnl6",
+   "metadata": {},
+   "source": [
+    "### Fetch Parsed Text for a Specific Document\n",
+    "\n",
+    "Now let's use the `job_id` to retrieve the actual parsed text content using the parse client methods."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "g191kvgxxvk",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get the parsed text for the first completed item\n",
+    "if completed_items:\n",
+    "    first_completed = completed_items[0]\n",
+    "\n",
+    "    print(f\"📖 Retrieving parsed text for: {first_completed['item_name']}\")\n",
+    "    print(f\"   Using Parse Job ID: {first_completed['job_id']}\\n\")\n",
+    "    print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "    # Use the job_id to fetch the parse result\n",
+    "    response = httpx.get(\n",
+    "        f\"{LLAMA_CLOUD_BASE_URL}/api/v1/parsing/job/{first_completed['job_id']}/result/text\",\n",
+    "        headers=headers,\n",
+    "        params={\"project_id\": project_id},\n",
+    "        timeout=60.0,\n",
+    "    )\n",
+    "\n",
+    "    if response.status_code == 200:\n",
+    "        parse_result = response.text\n",
+    "\n",
+    "        print(f\"✅ Retrieved parsed text ({len(parse_result)} characters)\\n\")\n",
+    "\n",
+    "        # Display first 1000 characters as a preview\n",
+    "        print(\"Preview (first 1000 characters):\")\n",
+    "        print(\"-\" * 80)\n",
+    "        print(parse_result[:1000])\n",
+    "        print(\"-\" * 80)\n",
+    "\n",
+    "        if len(parse_result) > 1000:\n",
+    "            print(f\"\\n... and {len(parse_result) - 1000} more characters\")\n",
+    "    else:\n",
+    "        print(\n",
+    "            f\"Error retrieving parse result: {response.status_code} - {response.text}\"\n",
+    "        )\n",
+    "else:\n",
+    "    print(\"⚠️  No completed items found to retrieve results from\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2olccb4l8fj",
+   "metadata": {},
+   "source": [
+    "### Retrieve Parsed Results in Other Formats\n",
+    "\n",
+    "You can also retrieve the parsed results in JSON or Markdown format using different client methods."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "lcqsfxiw0sr",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if completed_items:\n",
+    "    first_completed = completed_items[0]\n",
+    "\n",
+    "    print(\n",
+    "        f\"📋 Retrieving parse results in different formats for: {first_completed['item_name']}\\n\"\n",
+    "    )\n",
+    "\n",
+    "    # Get as JSON (includes structured data with pages, images, etc.)\n",
+    "    print(\"1️⃣ Retrieving as JSON...\")\n",
+    "    response = httpx.get(\n",
+    "        f\"{LLAMA_CLOUD_BASE_URL}/api/v1/parsing/job/{first_completed['job_id']}/result/json\",\n",
+    "        headers=headers,\n",
+    "        params={\"project_id\": project_id},\n",
+    "        timeout=60.0,\n",
+    "    )\n",
+    "\n",
+    "    if response.status_code == 200:\n",
+    "        json_result = response.json()\n",
+    "        print(f\"   ✅ JSON result with {len(json_result['pages'])} pages\")\n",
+    "        print(f\"      Keys: {list(json_result.keys())}\\n\")\n",
+    "    else:\n",
+    "        print(f\"   Error: {response.status_code}\\n\")\n",
+    "\n",
+    "    # Get as Markdown\n",
+    "    print(\"2️⃣ Retrieving as Markdown...\")\n",
+    "    response = httpx.get(\n",
+    "        f\"{LLAMA_CLOUD_BASE_URL}/api/v1/parsing/job/{first_completed['job_id']}/result/markdown\",\n",
+    "        headers=headers,\n",
+    "        params={\"project_id\": project_id},\n",
+    "        timeout=60.0,\n",
+    "    )\n",
+    "\n",
+    "    if response.status_code == 200:\n",
+    "        markdown_result = response.text\n",
+    "        print(f\"   ✅ Markdown result ({len(markdown_result)} characters)\\n\")\n",
+    "\n",
+    "        # Display markdown preview\n",
+    "        print(\"Markdown Preview (first 500 characters):\")\n",
+    "        print(\"-\" * 80)\n",
+    "        print(markdown_result[:500])\n",
+    "        print(\"-\" * 80)\n",
+    "\n",
+    "        if len(markdown_result) > 500:\n",
+    "            print(f\"\\n... and {len(markdown_result) - 500} more characters\")\n",
+    "    else:\n",
+    "        print(f\"   Error: {response.status_code}\")\n",
+    "else:\n",
+    "    print(\"⚠️  No completed items found to retrieve results from\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "lr61wqkfq3",
+   "metadata": {},
+   "source": [
+    "### Batch Process All Parsed Results\n",
+    "\n",
+    "You can also loop through all completed items to retrieve and process all the parsed results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kltydf9xzkl",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Process all completed items\n",
+    "print(f\"🔄 Processing all {len(completed_items)} completed items...\\n\")\n",
+    "print(f\"{'='*80}\\n\")\n",
+    "\n",
+    "all_results = {}\n",
+    "\n",
+    "for item in completed_items:\n",
+    "    print(f\"📄 Processing: {item['item_name']}\")\n",
+    "    print(f\"   Parse Job ID: {item['job_id']}\")\n",
+    "\n",
+    "    try:\n",
+    "        # Retrieve the parsed text for this item\n",
+    "        response = httpx.get(\n",
+    "            f\"{LLAMA_CLOUD_BASE_URL}/api/v1/parsing/job/{item['job_id']}/result/text\",\n",
+    "            headers=headers,\n",
+    "            params={\"project_id\": project_id},\n",
+    "            timeout=60.0,\n",
+    "        )\n",
+    "\n",
+    "        if response.status_code == 200:\n",
+    "            parsed_text = response.text\n",
+    "\n",
+    "            all_results[item[\"item_name\"]] = {\n",
+    "                \"job_id\": item[\"job_id\"],\n",
+    "                \"text\": parsed_text,\n",
+    "                \"length\": len(parsed_text),\n",
+    "            }\n",
+    "\n",
+    "            print(f\"   ✅ Retrieved {len(parsed_text)} characters\")\n",
+    "        else:\n",
+    "            all_results[item[\"item_name\"]] = {\n",
+    "                \"job_id\": item[\"job_id\"],\n",
+    "                \"error\": f\"HTTP {response.status_code}\",\n",
+    "            }\n",
+    "            print(f\"   ❌ Error: HTTP {response.status_code}\")\n",
+    "\n",
+    "    except Exception as e:\n",
+    "        print(f\"   ❌ Error: {str(e)}\")\n",
+    "        all_results[item[\"item_name\"]] = {\"job_id\": item[\"job_id\"], \"error\": str(e)}\n",
+    "\n",
+    "    print()\n",
+    "\n",
+    "print(f\"{'='*80}\")\n",
+    "print(f\"\\n✅ Processed {len(all_results)} items\")\n",
+    "print(f\"\\nSummary:\")\n",
+    "for name, result in all_results.items():\n",
+    "    if \"error\" in result:\n",
+    "        print(f\"  ❌ {name}: Error - {result['error']}\")\n",
+    "    else:\n",
+    "        print(f\"  ✅ {name}: {result['length']:,} characters\")"
+   ]
+  }
+ ],
+ "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": 5
+}

examples/extract/asset_manager_fund_analysis.ipynb

@@ -16,6 +16,14 @@
     "![](asset_manager_fund_analysis.png)\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cbafd7ee",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "cda2e5e9-fe9d-42d9-9387-f529d970ff7b",

examples/extract/automotive_sector_analysis.ipynb

@@ -20,6 +20,14 @@
     "This workflow is designed for equity research analysts and investment professionals."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e7979faf",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/extract/extract_data_with_citations.ipynb

@@ -19,6 +19,13 @@
     "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": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/extract/insider_buy_sell.ipynb

@@ -15,6 +15,13 @@
     "Dow Jones Industrial Average (DJIA) is a stock market index that consists of 30 large companies listed on the New York Stock Exchange and the NASDAQ and is considered a good proxy for the overall US stock market. For this exercise, we will extract the insider transactions for all the companies in the DJIA. Let's first get the list of tickers in the Dow Jones Industrial Average using Wikipedia."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/extract/lm317_structured_extraction.ipynb

@@ -16,6 +16,14 @@
     "This approach reduces manual data entry, improves extraction accuracy and standardization, and provides traceability for each technical detail."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8d1efe6e",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a3b8c8d5-ff3e-48ce-b0b8-29b6b1f517f8",

examples/extract/resume_screening.ipynb

@@ -11,6 +11,13 @@
     "Take a look at one of the resumes in the `data/resumes` directory. "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/extract/sec_10k_filing.ipynb

@@ -20,6 +20,14 @@
     "> **Note:** This principle of what fields generalize across your target documents and what might be optional is an important one to keep in mind when designing your schema. \n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "355adfd4",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/extract/solar_panel_e2e_comparison.ipynb

@@ -21,6 +21,14 @@
     "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": "ab7be988",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "36d8e34e-ed98-46ac-b744-1642f6e253d5",

examples/extract/tabular_extraction.ipynb

@@ -0,0 +1,516 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a7oq3cfnync",
+   "metadata": {},
+   "source": [
+    "# Extracting Repeating Entities from Documents\n",
+    "\n",
+    "This notebook demonstrates how to use the `PER_TABLE_ROW` extraction target to extract structured data from documents containing repeating entities like tables, lists, or catalogs.\n",
+    "\n",
+    "## Why Use the Tabular Extraction Target?\n",
+    "\n",
+    "`PER_DOC` (refer to the table below for a quick overview of the different extraction targets) is the default extraction target in LlamaExtract, which looks at the entire document's context when doing an extraction. When extracting lists of entities, LLM-based extraction has a critical failure mode — it often **only extracts the first few tens of entries** from a long list. This happens because LLMs have limited attention spans for repetitive data. Document-level extraction doesn't guarantee exhaustive coverage, and long lists lead to incomplete extractions.\n",
+    "\n",
+    "**The Solution**: `PER_TABLE_ROW` solves this by processing each entity individually or in smaller batches, ensuring **exhaustive extraction** of all entries regardless of list length.\n",
+    "\n",
+    "### Entity-Level Extraction\n",
+    "\n",
+    "When using `extraction_target=ExtractTarget.PER_TABLE_ROW`, you define a schema for a **single entity** (e.g., one hospital, one product, one invoice line item), not the full document. LlamaExtract automatically:\n",
+    "- Detects the formatting patterns that distinguish individual entities (table rows, list items, section headers, etc.)\n",
+    "- Applies your schema to each identified entity\n",
+    "- Returns a `list[YourSchema]` with one object per entity\n",
+    "\n",
+    "This approach is ideal when each entity locally contains all the information needed for your schema.\n",
+    "\n",
+    "### Choosing the Right Extraction Target\n",
+    "\n",
+    "| Extraction Target | Best For | Returns |\n",
+    "|-------------------|----------|---------|\n",
+    "| `PER_DOC` | Single-entity documents, summaries, or short lists | One JSON object for entire document |\n",
+    "| `PER_PAGE` | Multi-page documents where each page is independent | One JSON object per page |\n",
+    "| `PER_TABLE_ROW` | **Long lists, tables, catalogs with repeating entities** | List of JSON objects (one per entity) |\n",
+    "\n",
+    "📖 For more details, see the [Extraction Target documentation](https://developers.llamaindex.ai/python/cloud/llamaextract/features/concepts/#extraction-target)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cb760594",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9427d1de",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from dotenv import load_dotenv\n",
+    "from llama_cloud_services import LlamaExtract\n",
+    "\n",
+    "\n",
+    "# Load environment variables (put LLAMA_CLOUD_API_KEY in your .env file)\n",
+    "load_dotenv(override=True)\n",
+    "\n",
+    "# Optionally, add your project id/organization id\n",
+    "llama_extract = LlamaExtract()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4426b360",
+   "metadata": {},
+   "source": [
+    "## Table of Hospitals by County and Insurance Plans\n",
+    "\n",
+    "We have a PDF document with a list of hospitals by county and different insurance plans offered by Blue Shield of California. \n",
+    "\n",
+    "\n",
+    "![First few entries from the PDF](./data/tables/bsc_page1.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c86sjymhn1r",
+   "metadata": {},
+   "source": [
+    "We want to extract each hospital from this table along with a list of applicable insurance plans. \n",
+    "\n",
+    "### Example 1: Structured Table\n",
+    "\n",
+    "This is an ideal use case for `PER_TABLE_ROW` extraction:\n",
+    "- **Clear structure**: The document has explicit table formatting with rows and columns\n",
+    "- **Repeating entities**: Each row represents one hospital with consistent attributes\n",
+    "- **Local information**: All data for each hospital (county, name, plans) is contained within its row\n",
+    "\n",
+    "Notice that our `Hospital` schema describes a **single hospital**, not the full document. LlamaExtract will return a `list[Hospital]` with one entry per table row."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7c61a802",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pydantic import BaseModel, Field\n",
+    "\n",
+    "\n",
+    "class Hospital(BaseModel):\n",
+    "    \"\"\"List of hospitals by county available for different BSC plans\"\"\"\n",
+    "\n",
+    "    county: str = Field(description=\"County name\")\n",
+    "    hospital_name: str = Field(description=\"Name of the hospital\")\n",
+    "    plan_names: list[str] = Field(\n",
+    "        description=\"List of plans available at the hospital. One of: Trio HMO, SaveNet, Access+ HMO, BlueHPN PPO, Tandem PPO, PPO\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b8a69b7a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llama_cloud_services.extract import ExtractConfig, ExtractMode, ExtractTarget\n",
+    "\n",
+    "\n",
+    "result = await llama_extract.aextract(\n",
+    "    data_schema=Hospital,\n",
+    "    files=\"./data/tables/BSC-Hospital-List-by-County.pdf\",\n",
+    "    config=ExtractConfig(\n",
+    "        extraction_mode=ExtractMode.PREMIUM,\n",
+    "        extraction_target=ExtractTarget.PER_TABLE_ROW,\n",
+    "        parse_model=\"anthropic-sonnet-4.5\",\n",
+    "    ),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "43722cda",
+   "metadata": {},
+   "source": [
+    "### Results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "95b5aca6",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "380"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "len(result.data)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1e355770",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[{'county': 'Alameda',\n",
+       "  'hospital_name': 'Alameda Hospital',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'SaveNet',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Alta Bates Med Ctr Herrick Campus',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Alta Bates Summit Med Ctr Alta Bates Campus',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Alta Bates Summit Med Ctr Summit Campus',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Alta Bates Summit Medical Center',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'BHC Fremont Hospital',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'SaveNet',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Centre For Neuro Skills San Francisco',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'SaveNet',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Eden Medical Center',\n",
+       "  'plan_names': ['Trio HMO', 'Access+ HMO', 'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Fairmont Hospital',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'SaveNet',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']},\n",
+       " {'county': 'Alameda',\n",
+       "  'hospital_name': 'Highland Hospital',\n",
+       "  'plan_names': ['Trio HMO',\n",
+       "   'SaveNet',\n",
+       "   'Access+ HMO',\n",
+       "   'BlueHPN PPO',\n",
+       "   'Tandem PPO',\n",
+       "   'PPO']}]"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "result.data[:10]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e28f0de8",
+   "metadata": {},
+   "source": [
+    "![](./data/tables/bsc_results.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "di156pb7s6j",
+   "metadata": {},
+   "source": [
+    "**Success!** We extracted all **380 hospitals** from the multi-page PDF. Each entity was correctly parsed with its county, hospital name, and applicable insurance plans. With `PER_DOC`, we would likely have only gotten the first 20-30 entries."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "gelvl6db268",
+   "metadata": {},
+   "source": [
+    "## Extracting from a Toy Catalog\n",
+    "\n",
+    "### Example 2: Semi-Structured List\n",
+    "\n",
+    "The `PER_TABLE_ROW` extraction target also works well for documents that aren't explicit tables but have similar properties:\n",
+    "- **Ordered listing**: The toys are listed sequentially with visual separation (section headers, spacing)\n",
+    "- **Repeating pattern**: Each toy entry has a consistent structure (code, name, specs, description)\n",
+    "- **Local information**: All attributes for each toy are grouped together in its entry\n",
+    "\n",
+    "Even though this isn't a traditional table format, each toy entity locally contains all the information needed for our schema. LlamaExtract detects the formatting patterns that distinguish each toy and extracts them as separate entities.\n",
+    "\n",
+    "![](./data/tables/toy_catalog_page.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8cf0b2db",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pydantic import BaseModel, Field\n",
+    "\n",
+    "\n",
+    "class ToyCatalog(BaseModel):\n",
+    "    \"\"\"Product information from a toy catalog.\"\"\"\n",
+    "\n",
+    "    section_name: str = Field(\n",
+    "        description=\"The name of the toy section (e.g. Table Toys, Active Toys).\"\n",
+    "    )\n",
+    "    product_code: str = Field(\n",
+    "        description=\"The unique product code for the toy (e.g., GA457).\"\n",
+    "    )\n",
+    "    toy_name: str = Field(description=\"The name of the toy.\")\n",
+    "    age_range: str = Field(\n",
+    "        description=\"The recommended age range for the toy (e.g., 6 +, 4 +).\",\n",
+    "    )\n",
+    "    player_range: str = Field(\n",
+    "        description=\"The number of players the toy is designed for (e.g., 2, 2-4, 1-6).\",\n",
+    "    )\n",
+    "    material: str = Field(\n",
+    "        description=\"The primary material(s) the toy is made of (e.g., wood, cardboard).\",\n",
+    "    )\n",
+    "    description: str = Field(\n",
+    "        description=\"A brief description of the toy and its components and dimensions.\",\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "mysu1i2qo9e",
+   "metadata": {},
+   "source": [
+    "### Results\n",
+    "\n",
+    "Again, our schema represents a **single toy product**, not the entire catalog. The system will return a `list[ToyCatalog]` with one entry per toy."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5b38b806",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = await llama_extract.aextract(\n",
+    "    data_schema=ToyCatalog,\n",
+    "    files=\"./data/tables/Click-BS-Toys-Catalogue-2024.pdf\",\n",
+    "    config=ExtractConfig(\n",
+    "        extraction_mode=ExtractMode.PREMIUM,\n",
+    "        extraction_target=ExtractTarget.PER_TABLE_ROW,\n",
+    "        parse_model=\"anthropic-sonnet-4.5\",\n",
+    "    ),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "91aface0",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "153"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "len(result.data)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "51278736",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[{'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA457',\n",
+       "  'toy_name': 'Dots and Boxes',\n",
+       "  'age_range': '6+',\n",
+       "  'player_range': '2',\n",
+       "  'material': 'wood',\n",
+       "  'description': 'base 17x17 cm\\n50 border pieces 4x1,2x0,3 cm\\n34 trees 2,6x1,4 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA456',\n",
+       "  'toy_name': '3 In a Row',\n",
+       "  'age_range': '8+',\n",
+       "  'player_range': '2',\n",
+       "  'material': 'wood, pine, cardboard',\n",
+       "  'description': 'base 24x22,5x2,5 cm\\n30 cards 5,5x5 cm\\n6 chips'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA467',\n",
+       "  'toy_name': 'Which Cow am i?',\n",
+       "  'age_range': '6+',\n",
+       "  'player_range': '2',\n",
+       "  'material': 'wood, beech',\n",
+       "  'description': '2 cow bases 56x4x4,5 cm\\n16 cards 4x5 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA460',\n",
+       "  'toy_name': 'Balance Bunnies',\n",
+       "  'age_range': '4+',\n",
+       "  'player_range': '2',\n",
+       "  'material': 'wood',\n",
+       "  'description': '1 base 35x12x25 cm\\n7 bunnies 7 foxes\\n1 dice 3 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA462',\n",
+       "  'toy_name': 'Color Combination Race',\n",
+       "  'age_range': '4+',\n",
+       "  'player_range': '2-4',\n",
+       "  'material': 'wood, cardboard',\n",
+       "  'description': 'base 6,5x6,5x15 cm, rings 5,5x5,5x0,5 mm\\ncardholder 6x6x2 cm, cards 5,5x5,5 cm\\ncolor cards Ø 15,5 cm - Ø 7 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA465',\n",
+       "  'toy_name': 'Plop It',\n",
+       "  'age_range': '6+',\n",
+       "  'player_range': '2-4',\n",
+       "  'material': 'wood, elastic, cardboard',\n",
+       "  'description': 'Catch the right balls and plop them in the net!\\n* 2 ploppers 8x5 cm\\n* 2 net holders Ø 5cm, length 55 cm\\n* 6 cards 1,5x2,5 cm, 30 balls Ø 2,5 cm\\n* 1 rope 120 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA466',\n",
+       "  'toy_name': 'Whack a Shape',\n",
+       "  'age_range': '4+',\n",
+       "  'player_range': '2-4',\n",
+       "  'material': 'wood',\n",
+       "  'description': '* base 38,5x15,5 cm\\n* 2 stands 36 half balls, 4 hammers\\n* 1 dice 2,5 cm\\n* 4 cards'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA458',\n",
+       "  'toy_name': 'Sling Puck | Table Hockey',\n",
+       "  'age_range': '6+',\n",
+       "  'player_range': '2',\n",
+       "  'material': 'wood',\n",
+       "  'description': '* double sides base 39x21x3 cm\\n* 10 chips Ø 2,5 cm\\n* 2 pushers 4x4x3 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA039',\n",
+       "  'toy_name': 'DIY Birdhouse',\n",
+       "  'age_range': '3+',\n",
+       "  'player_range': '1',\n",
+       "  'material': 'wood',\n",
+       "  'description': '* house 9x9x13 cm'},\n",
+       " {'section_name': 'Table Toys',\n",
+       "  'product_code': 'GA319',\n",
+       "  'toy_name': 'Triangle Domino',\n",
+       "  'age_range': '6+',\n",
+       "  'player_range': '2-4',\n",
+       "  'material': 'wood',\n",
+       "  'description': '* 35 triangles 10x10 x10 cm'}]"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "result.data[:10]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d1810c0a",
+   "metadata": {},
+   "source": [
+    "![](./data/tables/toy_catalog_results.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ezur9gnhmsb",
+   "metadata": {},
+   "source": [
+    "**Success!** Despite the semi-structured format, we extracted all **152 toy products** from the catalog (there's an extra repeated extracted toy from the Appendix section). LlamaExtract automatically detected the visual patterns separating each toy entry and applied our schema to each one."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aeyr3io29u",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "The `PER_TABLE_ROW` extraction target is powerful for extracting repeating structured entities from documents. Key takeaways:\n",
+    "\n",
+    "1. **Schema design**: Define your schema for a single entity, not the full document. The system returns `list[YourSchema]`.\n",
+    "\n",
+    "2. **Works with various formats**: Not just traditional tables—any document with distinguishable repeating entities (bullets, numbering, headers, visual separation, etc.). The common requirement is that each entity should contain all the necessary data for your schema within its local context.\n",
+    "\n",
+    "3. **Automatic pattern detection**: LlamaExtract identifies the formatting patterns that distinguish entities and applies your schema to each one."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "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": 5
+}

examples/index/getting_started.ipynb

@@ -31,6 +31,13 @@
     "| Sep-02-2025  | 0.6.62  | Active     |\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/misc/parse_classify_extract_workflow.ipynb

@@ -19,6 +19,13 @@
     "The workflow is implemented as a proper LlamaIndex Workflow with separate steps for parsing, classification, and extraction, connected by typed events. This provides modularity, observability, and type safety."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -280,7 +287,7 @@
    "source": [
     "## Phase 2: Document Classification\n",
     "\n",
-    "Next, let's classify our documents based on their content using the ClassifyClient."
+    "Next, let's classify our documents based on their content using `LlamaClassify`."
    ]
   },
   {
@@ -298,14 +305,14 @@
     }
    ],
    "source": [
-    "from llama_cloud_services.beta.classifier.client import ClassifyClient\n",
+    "from llama_cloud_services.beta.classifier.client import LlamaClassify\n",
     "from llama_cloud.types import ClassifierRule\n",
     "from llama_cloud_services.files.client import FileClient\n",
     "from llama_cloud.client import AsyncLlamaCloud\n",
     "\n",
     "# Initialize the classify client\n",
     "api_key = os.environ[\"LLAMA_CLOUD_API_KEY\"]\n",
-    "classify_client = ClassifyClient.from_api_key(api_key)\n",
+    "classify_client = LlamaClassify.from_api_key(api_key)\n",
     "\n",
     "print(\"🏷️  Setting up document classification...\")\n",
     "\n",
@@ -1097,7 +1104,7 @@
     "   - Preserves document structure and formatting\n",
     "   - Handles various file types (PDF, DOCX, etc.)\n",
     "\n",
-    "2. **ClassifyClient** (`llama_cloud_services.beta.classifier.client.ClassifyClient`):\n",
+    "2. **LlamaClassify** (`llama_cloud_services.beta.classifier.client.LlamaClassify`):\n",
     "   - Automatically categorizes documents based on content\n",
     "   - Uses customizable rules for classification\n",
     "   - Provides confidence scores for classifications\n",

examples/parse/advanced_rag/dynamic_section_retrieval.ipynb

@@ -27,6 +27,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e2b422f5",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "2e4f707a-c7b5-473f-b4a6-881e2245e82d",

examples/parse/agents/demo_simple_openai_agent.ipynb

@@ -14,6 +14,13 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/batch_parse_folder.py

@@ -0,0 +1,188 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""
+Example: Batch Processing a Folder of PDFs with LlamaParse
+
+This script demonstrates how to process multiple PDFs from a folder
+using LlamaParse with controlled concurrency using asyncio and semaphores.
+
+Usage:
+    python batch_parse_folder.py --input-dir ./pdfs --max-concurrent 5
+"""
+
+import asyncio
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any
+from datetime import datetime
+from dotenv import load_dotenv
+import os
+
+from llama_cloud_services import LlamaParse
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+async def parse_single_file(
+    parser: LlamaParse,
+    file_path: Path,
+    semaphore: asyncio.Semaphore,
+) -> Dict[str, Any]:
+    """
+    Parse a single PDF file with concurrency control.
+
+    Args:
+        parser: LlamaParse instance
+        file_path: Path to the PDF file
+        semaphore: Semaphore to control concurrent requests
+
+    Returns:
+        Dictionary with file info and parse result
+    """
+    async with semaphore:
+        try:
+            print(f"Starting parse: {file_path.name}")
+
+            result = await parser.aparse(str(file_path))
+
+            print(f"✓ Completed: {file_path.name} ({len(result.pages)} pages)")
+
+            return {
+                "file": file_path.name,
+                "status": "success",
+                "result": result,
+                "pages": len(result.pages) if result.pages else 0,
+            }
+        except Exception as e:
+            print(f"✗ Error parsing {file_path.name}: {str(e)}")
+            return {
+                "file": file_path.name,
+                "status": "error",
+                "error": str(e),
+            }
+
+
+async def parse_folder(
+    input_dir: Path,
+    max_concurrent: int = 5,
+    api_key: str = None,
+) -> List[Dict[str, any]]:
+    """
+    Parse all PDFs in a folder with controlled concurrency.
+
+    Args:
+        input_dir: Directory containing PDF files
+        max_concurrent: Maximum number of concurrent parse operations
+        api_key: LlamaCloud API key (loaded from .env file)
+
+    Returns:
+        List of parse results for each file
+    """
+    # Find all PDF files
+    pdf_files = list(input_dir.glob("*.pdf"))
+
+    if not pdf_files:
+        print(f"No PDF files found in {input_dir}")
+        return []
+
+    print(f"Found {len(pdf_files)} PDF files to parse")
+
+    # Initialize parser
+    parser = LlamaParse(
+        api_key=api_key,
+        num_workers=1,  # We control concurrency with semaphore
+        show_progress=False,  # We'll show our own progress
+    )
+
+    # Create semaphore to limit concurrent requests
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    # Create tasks for all files
+    tasks = [parse_single_file(parser, pdf_file, semaphore) for pdf_file in pdf_files]
+
+    # Run all tasks concurrently (but limited by semaphore)
+    print(
+        f"Processing {len(tasks)} files with max {max_concurrent} concurrent operations..."
+    )
+    start_time = datetime.now()
+
+    results = await asyncio.gather(*tasks)
+
+    end_time = datetime.now()
+    duration = (end_time - start_time).total_seconds()
+
+    # Process results
+    successful = [
+        r for r in results if isinstance(r, dict) and r.get("status") == "success"
+    ]
+    failed = [r for r in results if isinstance(r, dict) and r.get("status") == "error"]
+
+    # Print summary
+    print("PARSE SUMMARY \n")
+    print(f"Total files: {len(pdf_files)}")
+    print(f"Successful: {len(successful)}")
+    print(f"Failed: {len(failed)}")
+    print(f"Total time: {duration:.2f} seconds")
+    print(f"Average time per file: {duration / len(pdf_files):.2f} seconds")
+
+    if failed:
+        print("\nFailed files:")
+        for result in failed:
+            print(f"  - {result['file']}: {result.get('error', 'Unknown error')}")
+
+    return results
+
+
+def main():
+    """Main entry point for the script."""
+    parser = argparse.ArgumentParser(
+        description="Batch process PDFs in a folder with LlamaParse"
+    )
+    parser.add_argument(
+        "--input-dir",
+        type=str,
+        required=True,
+        help="Directory containing PDF files to parse",
+    )
+    parser.add_argument(
+        "--max-concurrent",
+        type=int,
+        default=5,
+        help="Maximum number of concurrent parse operations (default: 5)",
+    )
+
+    args = parser.parse_args()
+
+    input_dir = Path(args.input_dir)
+
+    # Validate input directory
+    if not input_dir.exists():
+        print(f"Error: Input directory does not exist: {input_dir}")
+        return
+
+    if not input_dir.is_dir():
+        print(f"Error: Input path is not a directory: {input_dir}")
+        return
+
+    # Get API key from environment (loaded from .env file)
+    api_key = os.getenv("LLAMA_CLOUD_API_KEY")
+    if not api_key:
+        print("Error: LLAMA_CLOUD_API_KEY not found. Please set it in your .env file")
+        return
+
+    # Run async function
+    asyncio.run(
+        parse_folder(
+            input_dir=input_dir,
+            max_concurrent=args.max_concurrent,
+            api_key=api_key,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

examples/parse/caltrain/caltrain_text_mode.ipynb

@@ -17,6 +17,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "0cb82ca8",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "ef115dbe-b834-4639-828e-e2c11aef710b",

examples/parse/demo_advanced.ipynb

@@ -18,6 +18,13 @@
     "| Aug-18-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/demo_api.ipynb

@@ -14,6 +14,13 @@
     "| Aug-18-2025   | N/A     | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/demo_basic.ipynb

@@ -14,6 +14,13 @@
     "| Aug-18-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/demo_excel.ipynb

@@ -18,6 +18,13 @@
     "| Aug-18-2025   | 0.6.61  | Maintained |\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/demo_get_charts.ipynb

@@ -19,6 +19,14 @@
     "| Aug-18-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "bb595498",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a004db48-8d3f-421c-915a-477692f71b90",

examples/parse/demo_insurance.ipynb

@@ -16,6 +16,13 @@
     "| Aug-19-2025   | 0.6.61  | Deprecated |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/demo_json.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8b937443",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a004db48-8d3f-421c-915a-477692f71b90",

examples/parse/demo_json_tour.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "037cc6d9",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a004db48-8d3f-421c-915a-477692f71b90",

examples/parse/demo_languages.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "7aa3be47",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/demo_mongodb.ipynb

@@ -21,6 +21,13 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/demo_starter_multimodal.ipynb

@@ -8,6 +8,14 @@
     "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/demo_starter_multimodal.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "da52cfa3",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "4e081457",

examples/parse/demo_starter_parse_selected_pages.ipynb

@@ -7,6 +7,13 @@
     "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/demo_starter_parse_selected_pages.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/demo_table_extraction.ipynb

@@ -14,6 +14,13 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/excel/dcf_rag.ipynb

@@ -17,6 +17,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a3636937",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "5f7d99ad-6ebd-47d0-92a7-566630b0c22a",

examples/parse/excel/o1_excel_rag.ipynb

@@ -7,6 +7,13 @@
     "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/excel/o1_excel_rag.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/knowledge_graphs/kg_agent.ipynb

@@ -17,6 +17,14 @@
     "| Before Feb 2025   | N/A  | Deprecated |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "0facb0b9",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "e8db8ac2-5221-44de-a53e-cb5ab37ac8f5",

examples/parse/multimodal/claude_parse.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "bb943339",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/multimodal/gemini2_flash.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "17e62444",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/multimodal/gpt4o_mini.ipynb

@@ -19,6 +19,14 @@
     "| Aug-19-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "fe7e837a",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "15e60ecf-519c-41fc-911b-765adaf8bad4",

examples/parse/multimodal/insurance_rag.ipynb

@@ -9,6 +9,13 @@
     "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/multimodal/insurance_rag.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/multimodal/legal_rag.ipynb

@@ -23,6 +23,13 @@
     "- [US Immigration Case](https://github.com/user-attachments/files/16536446/us_immigration_case.pdf)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/multimodal/multimodal_contextual_retrieval_rag.ipynb

@@ -27,6 +27,14 @@
     "![mm_rag_diagram](./multimodal_contextual_retrieval_rag_img.png)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "93d4f9ab",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54e8d9a7-5036-4d32-818f-00b2e888521f",

examples/parse/multimodal/multimodal_rag_slide_deck.ipynb

@@ -27,6 +27,14 @@
     "![mm_rag_diagram](./multimodal_rag_slide_deck_img.png)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "fc1b5803",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54e8d9a7-5036-4d32-818f-00b2e888521f",

examples/parse/multimodal/multimodal_report_generation.ipynb

@@ -19,6 +19,14 @@
     "| Aug-20-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "7dafd458",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54e8d9a7-5036-4d32-818f-00b2e888521f",

examples/parse/multimodal/multimodal_report_generation_agent.ipynb

@@ -21,6 +21,14 @@
     "We use our workflow abstraction to define an agentic system that contains two main phases: a research phase that pulls in relevant files through chunk-level or file-level retrieval, and then a blog generation phase that synthesizes the final report."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8c881021",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54e8d9a7-5036-4d32-818f-00b2e888521f",

examples/parse/multimodal/product_manual_rag.ipynb

@@ -9,6 +9,13 @@
     "<a href=\"https://colab.research.google.com/github/run-llama/llama_cloud_services/blob/main/examples/parse/multimodal/product_manual_rag.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/other_files/demo_ppt_basic.ipynb

@@ -19,6 +19,14 @@
     "| Prior to Feb-2025   | N/A  | Deprecated |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b27f0e78",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/other_files/demo_ppt_financial.ipynb

@@ -14,6 +14,13 @@
     "| Prior to Feb-2025   | N/A  | Deprecated |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/parsing_instructions/parsing_instructions.ipynb

@@ -29,6 +29,13 @@
     "In this demonstration, we showcase how parsing instructions can be used to extract specific information from unstructured documents. Using a McDonald's Receipt, we show how to ignore parts of the document and only parse the price of each order and the final amount to be paid."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/parsing_modes/demo_auto_mode.ipynb

@@ -18,6 +18,13 @@
     "Many documents can have varying complexity across pages - some pages have text, and other pages have images. The text-only pages only require cheap parsing modes, whereas the image-based pages require more advanced modes. In this notebook we show you how to take advantage of \"auto mode\" in LlamaParse which adaptively parses different pages according to different modes, which lets you get optimal performance at the cheapest cost.\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/parsing_modes/demo_layout_agent_mode_visual_citations.ipynb

@@ -37,6 +37,13 @@
     "With visual references, you can build applications that preserve document structure and provide users with trustworthy, traceable visual citations. We will now leverage this feature to build our query engine."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/parse/parsing_modes/demo_presets.ipynb

@@ -24,6 +24,13 @@
     "| Aug-18-2025   | 0.6.61  | Maintained |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/report_generation/rfp_response/generate_rfp.ipynb

@@ -26,6 +26,14 @@
     "We use LlamaParse to parse the context documents as well as the RFP document itself."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "ad140aef",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/parse/test_tesla_impact_report/test_gpt4o.ipynb

@@ -22,6 +22,14 @@
     "**NOTE**: The pricing for LlamaParse + gpt4o is an order more expensive than using LlamaParse by default. Currently, every page parsed with gpt4o counts for 10 pages in the LlamaParse usage tracker.\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "211c52fe",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

examples/sheets/coding-agent-analysis/CLAUDE.md

@@ -0,0 +1,73 @@
+This project uses LlamaSheets to extract data from spreadsheets for analysis.
+
+## Current Project Structure
+
+- `data/` - Contains extracted parquet files from LlamaSheets
+  - `{name}_region_{N}.parquet` - Table data files
+  - `{name}_metadata_{N}.parquet` - Cell metadata files
+  - `{name}_job_metadata.json` - Extraction job information
+- `scripts/` - Analysis and helper scripts
+- `reports/` - Your generated reports and outputs
+
+## Working with LlamaSheets Data
+
+### Understanding the Files
+
+When a spreadsheet is extracted, you'll find:
+
+1. **Table parquet files** (`region_*.parquet`): The actual table data
+   - Columns correspond to spreadsheet columns
+   - Data types are preserved (dates, numbers, strings, booleans)
+
+2. **Metadata parquet files** (`metadata_*.parquet`): Rich cell-level metadata
+   - Formatting: `font_bold`, `font_italic`, `font_size`, `background_color_rgb`
+   - Position: `row_number`, `column_number`, `coordinate` (e.g., "A1")
+   - Type detection: `data_type`, `is_date_like`, `is_percentage`, `is_currency`
+   - Layout: `is_in_first_row`, `is_merged_cell`, `horizontal_alignment`
+   - Content: `cell_value`, `raw_cell_value`
+
+3. **Job metadata JSON** (`job_metadata.json`): Overall extraction results
+   - `regions[]`: List of extracted regions with IDs, locations, and titles/descriptions
+   - `worksheet_metadata[]`: Generated titles and descriptions
+   - `status`: Success/failure status
+
+### Key Principles
+
+1. **Use metadata to understand structure**: Bold cells often indicate headers, colors indicate groupings
+2. **Validate before analysis**: Check data types, look for missing values
+3. **Preserve formatting context**: The metadata tells you what the spreadsheet author emphasized
+4. **Save intermediate results**: Store cleaned data as new parquet files
+
+### Common Patterns
+
+**Loading data:**
+```python
+import pandas as pd
+
+df = pd.read_parquet("data/region_1_Sheet1.parquet")
+meta_df = pd.read_parquet("data/metadata_1_Sheet1.parquet")
+```
+
+**Finding headers:**
+```python
+headers = meta_df[meta_df["font_bold"] == True]["cell_value"].tolist()
+```
+
+**Finding date columns:**
+```python
+date_cols = meta_df[meta_df["is_date_like"] == True]["column_number"].unique()
+```
+
+## Tools Available
+
+- **Python 3.11+**: For data analysis
+- **pandas**: DataFrame manipulation
+- **pyarrow**: Parquet file reading
+- **matplotlib**: Visualization (optional)
+
+## Guidelines
+
+- Always read the job_metadata.json first to understand what was extracted
+- Check both table data and metadata before making assumptions
+- Write reusable functions for common operations
+- Document any data quality issues discovered

examples/sheets/coding-agent-analysis/generate_sample_data.py

@@ -0,0 +1,283 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""
+Generate sample spreadsheets for LlamaSheets + Claude workflows.
+
+This script creates example Excel files that demonstrate different use cases:
+1. Simple data table (for Workflow 1)
+2. Regional sales data (for Workflow 2)
+3. Complex budget with formatting (for Workflow 3)
+4. Weekly sales report (for Workflow 4)
+
+Usage:
+    python generate_sample_data.py
+"""
+
+import random
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pandas as pd
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+
+def generate_workflow_1_data(output_dir: Path) -> None:
+    """Generate simple financial report for Workflow 1."""
+    print("📊 Generating Workflow 1: financial_report_q1.xlsx")
+
+    # Create sample quarterly data
+    months = ["January", "February", "March"]
+    categories = ["Revenue", "Cost of Goods Sold", "Operating Expenses", "Net Income"]
+
+    data = []
+    for category in categories:
+        row: dict[str, str | int] = {"Category": category}
+        for month in months:
+            if category == "Revenue":
+                value = random.randint(80000, 120000)
+            elif category == "Cost of Goods Sold":
+                value = random.randint(30000, 50000)
+            elif category == "Operating Expenses":
+                value = random.randint(20000, 35000)
+            else:  # Net Income
+                value = int(
+                    int(row.get("January", 0))
+                    + int(row.get("February", 0))
+                    + int(row.get("March", 0))
+                )
+                value = random.randint(15000, 40000)
+            row[month] = value
+        data.append(row)
+
+    df = pd.DataFrame(data)
+
+    # Write to Excel
+    output_file = output_dir / "financial_report_q1.xlsx"
+    with pd.ExcelWriter(output_file, engine="openpyxl") as writer:
+        df.to_excel(writer, sheet_name="Q1 Summary", index=False)
+
+        # Format it nicely
+        worksheet = writer.sheets["Q1 Summary"]
+        for cell in worksheet[1]:  # Header row
+            cell.font = Font(bold=True)
+            cell.fill = PatternFill(
+                start_color="4F81BD", end_color="4F81BD", fill_type="solid"
+            )
+            cell.font = Font(color="FFFFFF", bold=True)
+
+    print(f"  ✅ Created {output_file}")
+
+
+def generate_workflow_2_data(output_dir: Path) -> None:
+    """Generate regional sales data for Workflow 2."""
+    print("\n📊 Generating Workflow 2: Regional sales data")
+
+    regions = ["northeast", "southeast", "west"]
+    products = ["Widget A", "Widget B", "Widget C", "Gadget X", "Gadget Y"]
+
+    for region in regions:
+        data = []
+        start_date = datetime(2024, 1, 1)
+
+        # Generate 90 days of sales data
+        for day in range(90):
+            date = start_date + timedelta(days=day)
+            # Random number of sales per day (3-8)
+            for _ in range(random.randint(3, 8)):
+                product = random.choice(products)
+                units_sold = random.randint(1, 20)
+                price_per_unit = random.randint(50, 200)
+                revenue = units_sold * price_per_unit
+
+                data.append(
+                    {
+                        "Date": date.strftime("%Y-%m-%d"),
+                        "Product": product,
+                        "Units_Sold": units_sold,
+                        "Revenue": revenue,
+                    }
+                )
+
+        df = pd.DataFrame(data)
+
+        # Write to Excel
+        output_file = output_dir / f"sales_{region}.xlsx"
+        df.to_excel(output_file, sheet_name="Sales", index=False)
+        print(f"  ✅ Created {output_file} ({len(df)} rows)")
+
+
+def generate_workflow_3_data(output_dir: Path) -> None:
+    """Generate complex budget spreadsheet with formatting for Workflow 3."""
+    print("\n📊 Generating Workflow 3: company_budget_2024.xlsx")
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Budget"
+
+    # Define departments with colors
+    departments = {
+        "Engineering": "C6E0B4",
+        "Marketing": "FFD966",
+        "Sales": "F4B084",
+        "Operations": "B4C7E7",
+    }
+
+    # Define categories
+    categories = {
+        "Personnel": ["Salaries", "Benefits", "Training"],
+        "Infrastructure": ["Office Rent", "Equipment", "Software Licenses"],
+        "Operations": ["Travel", "Supplies", "Miscellaneous"],
+    }
+
+    # Styles
+    header_font = Font(bold=True, size=12)
+    category_font = Font(bold=True, size=11)
+
+    row = 1
+
+    # Title
+    ws.merge_cells(f"A{row}:E{row}")
+    ws[f"A{row}"] = "2024 Annual Budget"
+    ws[f"A{row}"].font = Font(bold=True, size=14)
+    ws[f"A{row}"].alignment = Alignment(horizontal="center")
+    row += 2
+
+    # Headers
+    ws[f"A{row}"] = "Category"
+    ws[f"B{row}"] = "Item"
+    for i, dept in enumerate(departments.keys()):
+        ws.cell(row, 3 + i, dept)
+        ws.cell(row, 3 + i).font = header_font
+
+    for cell in ws[row]:
+        cell.font = header_font
+    row += 1
+
+    # Data
+    for category, items in categories.items():
+        # Category header (bold)
+        ws[f"A{row}"] = category
+        ws[f"A{row}"].font = category_font
+        row += 1
+
+        # Items with department budgets
+        for item in items:
+            ws[f"A{row}"] = ""
+            ws[f"B{row}"] = item
+
+            # Add budget amounts for each department (with color)
+            for i, (dept, color) in enumerate(departments.items()):
+                amount = random.randint(5000, 50000)
+                cell = ws.cell(row, 3 + i, amount)
+                cell.fill = PatternFill(
+                    start_color=color, end_color=color, fill_type="solid"
+                )
+                cell.number_format = "$#,##0"
+
+            row += 1
+
+        row += 1  # Blank row between categories
+
+    # Adjust column widths
+    ws.column_dimensions["A"].width = 20
+    ws.column_dimensions["B"].width = 25
+    for i in range(len(departments)):
+        ws.column_dimensions[chr(67 + i)].width = 15  # C, D, E, F
+
+    output_file = output_dir / "company_budget_2024.xlsx"
+    wb.save(output_file)
+    print(f"  ✅ Created {output_file}")
+    print("     • Bold categories, colored departments, merged title cell")
+
+
+def generate_workflow_4_data(output_dir: Path) -> None:
+    """Generate weekly sales report for Workflow 4."""
+    print("\n📊 Generating Workflow 4: sales_weekly.xlsx")
+
+    products = [
+        "Product A",
+        "Product B",
+        "Product C",
+        "Product D",
+        "Product E",
+        "Product F",
+        "Product G",
+        "Product H",
+    ]
+
+    # Generate one week of data
+    data = []
+    start_date = datetime(2024, 11, 4)  # Monday
+
+    for day in range(7):
+        date = start_date + timedelta(days=day)
+        # Each product has 3-10 transactions per day
+        for product in products:
+            for _ in range(random.randint(3, 10)):
+                units = random.randint(1, 15)
+                price = random.randint(20, 150)
+                revenue = units * price
+
+                data.append(
+                    {
+                        "Date": date.strftime("%Y-%m-%d"),
+                        "Product": product,
+                        "Units": units,
+                        "Revenue": revenue,
+                    }
+                )
+
+    df = pd.DataFrame(data)
+
+    # Write to Excel with some formatting
+    output_file = output_dir / "sales_weekly.xlsx"
+    with pd.ExcelWriter(output_file, engine="openpyxl") as writer:
+        df.to_excel(writer, sheet_name="Weekly Sales", index=False)
+
+        # Format header
+        worksheet = writer.sheets["Weekly Sales"]
+        for cell in worksheet[1]:
+            cell.font = Font(bold=True)
+
+    print(f"  ✅ Created {output_file} ({len(df)} rows)")
+
+
+def main() -> None:
+    """Generate all sample data files."""
+    print("=" * 60)
+    print("Generating Sample Data for LlamaSheets + Coding Agent Workflows")
+    print("=" * 60)
+
+    # Create output directory
+    output_dir = Path("input_data")
+    output_dir.mkdir(exist_ok=True)
+
+    # Generate data for each workflow
+    generate_workflow_1_data(output_dir)
+    generate_workflow_2_data(output_dir)
+    generate_workflow_3_data(output_dir)
+    generate_workflow_4_data(output_dir)
+
+    print("\n" + "=" * 60)
+    print("✅ All sample data generated!")
+    print("=" * 60)
+    print(f"\nFiles created in {output_dir.absolute()}:")
+    print("\nWorkflow 1 (Understanding a New Spreadsheet):")
+    print("  • financial_report_q1.xlsx")
+    print("\nWorkflow 2 (Generating Analysis Scripts):")
+    print("  • sales_northeast.xlsx")
+    print("  • sales_southeast.xlsx")
+    print("  • sales_west.xlsx")
+    print("\nWorkflow 3 (Using Cell Metadata):")
+    print("  • company_budget_2024.xlsx")
+    print("\nWorkflow 4 (Complete Automation):")
+    print("  • sales_weekly.xlsx")
+    print("\nYou can now use these files with the workflows in the documentation!")
+
+
+if __name__ == "__main__":
+    main()

examples/sheets/coding-agent-analysis/requirements.txt

@@ -0,0 +1,5 @@
+llama-cloud-services  # LlamaSheets SDK
+pandas>=2.0.0
+pyarrow>=12.0.0
+openpyxl>=3.0.0       # For Excel file support
+matplotlib>=3.7.0     # For visualizations (optional)

examples/sheets/coding-agent-analysis/scripts/extract.py

@@ -0,0 +1,105 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""Helper script to extract spreadsheets using LlamaSheets."""
+
+import asyncio
+import json
+import os
+import dotenv
+from pathlib import Path
+
+from llama_cloud_services.beta.sheets import LlamaSheets
+from llama_cloud_services.beta.sheets.types import (
+    SpreadsheetParsingConfig,
+    SpreadsheetResultType,
+)
+
+dotenv.load_dotenv()
+
+
+async def extract_spreadsheet(
+    file_path: str, output_dir: str = "data", generate_metadata: bool = True
+) -> dict:
+    """Extract a spreadsheet using LlamaSheets."""
+
+    client = LlamaSheets(
+        base_url="https://api.cloud.llamaindex.ai",
+        api_key=os.getenv("LLAMA_CLOUD_API_KEY"),
+    )
+
+    print(f"Extracting {file_path}...")
+
+    # Extract regions
+    config = SpreadsheetParsingConfig(
+        sheet_names=None,  # Extract all sheets
+        generate_additional_metadata=generate_metadata,
+    )
+
+    job_result = await client.aextract_regions(file_path, config=config)
+
+    print(f"Extracted {len(job_result.regions)} region(s)")
+
+    # Create output directory
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Get base name for files
+    base_name = Path(file_path).stem
+
+    # Save job metadata
+    job_metadata_path = output_path / f"{base_name}_job_metadata.json"
+    with open(job_metadata_path, "w") as f:
+        json.dump(job_result.model_dump(mode="json"), f, indent=2)
+    print(f"Saved job metadata to {job_metadata_path}")
+
+    # Download each region
+    for idx, region in enumerate(job_result.regions, 1):
+        sheet_name = region.sheet_name.replace(" ", "_")
+
+        # Download region data
+        region_bytes = await client.adownload_region_result(
+            job_id=job_result.id,
+            region_id=region.region_id,
+            result_type=region.region_type,
+        )
+
+        region_path = output_path / f"{base_name}_region_{idx}_{sheet_name}.parquet"
+        with open(region_path, "wb") as f:
+            f.write(region_bytes)
+        print(f"  Table {idx}: {region_path}")
+
+        # Download metadata
+        metadata_bytes = await client.adownload_region_result(
+            job_id=job_result.id,
+            region_id=region.region_id,
+            result_type=SpreadsheetResultType.CELL_METADATA,
+        )
+
+        metadata_path = output_path / f"{base_name}_metadata_{idx}_{sheet_name}.parquet"
+        with open(metadata_path, "wb") as f:
+            f.write(metadata_bytes)
+        print(f"  Metadata {idx}: {metadata_path}")
+
+    print(f"\nAll files saved to {output_path}/")
+
+    return job_result.model_dump(mode="json")
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python scripts/extract.py <spreadsheet_file>")
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+
+    if not Path(file_path).exists():
+        print(f"❌ File not found: {file_path}")
+        sys.exit(1)
+
+    result = asyncio.run(extract_spreadsheet(file_path))
+    print(f"\n✅ Extraction complete! Job ID: {result['id']}")

examples/sheets/llama-index-agent/generate_sample_data.py

@@ -0,0 +1,283 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""
+Generate sample spreadsheets for LlamaSheets + LlamaIndex Agent workflows.
+
+This script creates example Excel files that demonstrate different use cases:
+1. Simple data table (for Workflow 1)
+2. Regional sales data (for Workflow 2)
+3. Complex budget with formatting (for Workflow 3)
+4. Weekly sales report (for Workflow 4)
+
+Usage:
+    python generate_sample_data.py
+"""
+
+import random
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pandas as pd
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+
+def generate_workflow_1_data(output_dir: Path) -> None:
+    """Generate simple financial report for Workflow 1."""
+    print("📊 Generating Workflow 1: financial_report_q1.xlsx")
+
+    # Create sample quarterly data
+    months = ["January", "February", "March"]
+    categories = ["Revenue", "Cost of Goods Sold", "Operating Expenses", "Net Income"]
+
+    data = []
+    for category in categories:
+        row: dict[str, str | int] = {"Category": category}
+        for month in months:
+            if category == "Revenue":
+                value = random.randint(80000, 120000)
+            elif category == "Cost of Goods Sold":
+                value = random.randint(30000, 50000)
+            elif category == "Operating Expenses":
+                value = random.randint(20000, 35000)
+            else:  # Net Income
+                value = int(
+                    int(row.get("January", 0))
+                    + int(row.get("February", 0))
+                    + int(row.get("March", 0))
+                )
+                value = random.randint(15000, 40000)
+            row[month] = value
+        data.append(row)
+
+    df = pd.DataFrame(data)
+
+    # Write to Excel
+    output_file = output_dir / "financial_report_q1.xlsx"
+    with pd.ExcelWriter(output_file, engine="openpyxl") as writer:
+        df.to_excel(writer, sheet_name="Q1 Summary", index=False)
+
+        # Format it nicely
+        worksheet = writer.sheets["Q1 Summary"]
+        for cell in worksheet[1]:  # Header row
+            cell.font = Font(bold=True)
+            cell.fill = PatternFill(
+                start_color="4F81BD", end_color="4F81BD", fill_type="solid"
+            )
+            cell.font = Font(color="FFFFFF", bold=True)
+
+    print(f"  ✅ Created {output_file}")
+
+
+def generate_workflow_2_data(output_dir: Path) -> None:
+    """Generate regional sales data for Workflow 2."""
+    print("\n📊 Generating Workflow 2: Regional sales data")
+
+    regions = ["northeast", "southeast", "west"]
+    products = ["Widget A", "Widget B", "Widget C", "Gadget X", "Gadget Y"]
+
+    for region in regions:
+        data = []
+        start_date = datetime(2024, 1, 1)
+
+        # Generate 90 days of sales data
+        for day in range(90):
+            date = start_date + timedelta(days=day)
+            # Random number of sales per day (3-8)
+            for _ in range(random.randint(3, 8)):
+                product = random.choice(products)
+                units_sold = random.randint(1, 20)
+                price_per_unit = random.randint(50, 200)
+                revenue = units_sold * price_per_unit
+
+                data.append(
+                    {
+                        "Date": date.strftime("%Y-%m-%d"),
+                        "Product": product,
+                        "Units_Sold": units_sold,
+                        "Revenue": revenue,
+                    }
+                )
+
+        df = pd.DataFrame(data)
+
+        # Write to Excel
+        output_file = output_dir / f"sales_{region}.xlsx"
+        df.to_excel(output_file, sheet_name="Sales", index=False)
+        print(f"  ✅ Created {output_file} ({len(df)} rows)")
+
+
+def generate_workflow_3_data(output_dir: Path) -> None:
+    """Generate complex budget spreadsheet with formatting for Workflow 3."""
+    print("\n📊 Generating Workflow 3: company_budget_2024.xlsx")
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Budget"
+
+    # Define departments with colors
+    departments = {
+        "Engineering": "C6E0B4",
+        "Marketing": "FFD966",
+        "Sales": "F4B084",
+        "Operations": "B4C7E7",
+    }
+
+    # Define categories
+    categories = {
+        "Personnel": ["Salaries", "Benefits", "Training"],
+        "Infrastructure": ["Office Rent", "Equipment", "Software Licenses"],
+        "Operations": ["Travel", "Supplies", "Miscellaneous"],
+    }
+
+    # Styles
+    header_font = Font(bold=True, size=12)
+    category_font = Font(bold=True, size=11)
+
+    row = 1
+
+    # Title
+    ws.merge_cells(f"A{row}:E{row}")
+    ws[f"A{row}"] = "2024 Annual Budget"
+    ws[f"A{row}"].font = Font(bold=True, size=14)
+    ws[f"A{row}"].alignment = Alignment(horizontal="center")
+    row += 2
+
+    # Headers
+    ws[f"A{row}"] = "Category"
+    ws[f"B{row}"] = "Item"
+    for i, dept in enumerate(departments.keys()):
+        ws.cell(row, 3 + i, dept)
+        ws.cell(row, 3 + i).font = header_font
+
+    for cell in ws[row]:
+        cell.font = header_font
+    row += 1
+
+    # Data
+    for category, items in categories.items():
+        # Category header (bold)
+        ws[f"A{row}"] = category
+        ws[f"A{row}"].font = category_font
+        row += 1
+
+        # Items with department budgets
+        for item in items:
+            ws[f"A{row}"] = ""
+            ws[f"B{row}"] = item
+
+            # Add budget amounts for each department (with color)
+            for i, (dept, color) in enumerate(departments.items()):
+                amount = random.randint(5000, 50000)
+                cell = ws.cell(row, 3 + i, amount)
+                cell.fill = PatternFill(
+                    start_color=color, end_color=color, fill_type="solid"
+                )
+                cell.number_format = "$#,##0"
+
+            row += 1
+
+        row += 1  # Blank row between categories
+
+    # Adjust column widths
+    ws.column_dimensions["A"].width = 20
+    ws.column_dimensions["B"].width = 25
+    for i in range(len(departments)):
+        ws.column_dimensions[chr(67 + i)].width = 15  # C, D, E, F
+
+    output_file = output_dir / "company_budget_2024.xlsx"
+    wb.save(output_file)
+    print(f"  ✅ Created {output_file}")
+    print("     • Bold categories, colored departments, merged title cell")
+
+
+def generate_workflow_4_data(output_dir: Path) -> None:
+    """Generate weekly sales report for Workflow 4."""
+    print("\n📊 Generating Workflow 4: sales_weekly.xlsx")
+
+    products = [
+        "Product A",
+        "Product B",
+        "Product C",
+        "Product D",
+        "Product E",
+        "Product F",
+        "Product G",
+        "Product H",
+    ]
+
+    # Generate one week of data
+    data = []
+    start_date = datetime(2024, 11, 4)  # Monday
+
+    for day in range(7):
+        date = start_date + timedelta(days=day)
+        # Each product has 3-10 transactions per day
+        for product in products:
+            for _ in range(random.randint(3, 10)):
+                units = random.randint(1, 15)
+                price = random.randint(20, 150)
+                revenue = units * price
+
+                data.append(
+                    {
+                        "Date": date.strftime("%Y-%m-%d"),
+                        "Product": product,
+                        "Units": units,
+                        "Revenue": revenue,
+                    }
+                )
+
+    df = pd.DataFrame(data)
+
+    # Write to Excel with some formatting
+    output_file = output_dir / "sales_weekly.xlsx"
+    with pd.ExcelWriter(output_file, engine="openpyxl") as writer:
+        df.to_excel(writer, sheet_name="Weekly Sales", index=False)
+
+        # Format header
+        worksheet = writer.sheets["Weekly Sales"]
+        for cell in worksheet[1]:
+            cell.font = Font(bold=True)
+
+    print(f"  ✅ Created {output_file} ({len(df)} rows)")
+
+
+def main() -> None:
+    """Generate all sample data files."""
+    print("=" * 60)
+    print("Generating Sample Data for LlamaSheets + Coding Agent Workflows")
+    print("=" * 60)
+
+    # Create output directory
+    output_dir = Path("input_data")
+    output_dir.mkdir(exist_ok=True)
+
+    # Generate data for each workflow
+    generate_workflow_1_data(output_dir)
+    generate_workflow_2_data(output_dir)
+    generate_workflow_3_data(output_dir)
+    generate_workflow_4_data(output_dir)
+
+    print("\n" + "=" * 60)
+    print("✅ All sample data generated!")
+    print("=" * 60)
+    print(f"\nFiles created in {output_dir.absolute()}:")
+    print("\nWorkflow 1 (Understanding a New Spreadsheet):")
+    print("  • financial_report_q1.xlsx")
+    print("\nWorkflow 2 (Generating Analysis Scripts):")
+    print("  • sales_northeast.xlsx")
+    print("  • sales_southeast.xlsx")
+    print("  • sales_west.xlsx")
+    print("\nWorkflow 3 (Using Cell Metadata):")
+    print("  • company_budget_2024.xlsx")
+    print("\nWorkflow 4 (Complete Automation):")
+    print("  • sales_weekly.xlsx")
+    print("\nYou can now use these files with the workflows in the documentation!")
+
+
+if __name__ == "__main__":
+    main()

examples/sheets/llama-index-agent/llama_index_example.py

@@ -0,0 +1,297 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""
+LlamaSheets Agent with LlamaIndex
+
+This example shows how to build an agent that can work with spreadsheet data
+extracted by LlamaSheets using Python code execution.
+
+The agent has minimal tools but maximum flexibility - it can execute arbitrary
+pandas code against the extracted data, similar to a coding agent.
+
+NOTE: Code execution should be handled safely in a sandboxed environment for security.
+"""
+
+import io
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import dotenv
+import pandas as pd
+from llama_index.core.agent import FunctionAgent, ToolCall, ToolCallResult, AgentStream
+from llama_index.llms.openai import OpenAI
+from workflows import Context
+
+dotenv.load_dotenv()
+
+# Global context for executed code
+_code_context: Dict[str, Any] = {}
+
+
+# Helper function for initial agent context
+def list_extracted_data(data_dir: str = "data") -> str:
+    """
+    List all regions and metadata files extracted by LlamaSheets.
+
+    This helps discover what data is available to work with.
+
+    Args:
+        data_dir: Directory containing extracted parquet files (default: "data")
+
+    Returns:
+        JSON string with information about available files
+    """
+    data_path = Path(data_dir)
+
+    if not data_path.exists():
+        return json.dumps({"error": f"Data directory '{data_dir}' not found"})
+
+    # Find all parquet and metadata files
+    region_files = list(data_path.glob("*_region_*.parquet"))
+    job_metadata_files = list(data_path.glob("*_job_metadata.json"))
+
+    regions = []
+    for region_file in region_files:
+        # Quick peek at dimensions
+        df = pd.read_parquet(region_file)
+
+        # Find corresponding metadata file
+        base_name = region_file.stem.replace("_region_", "_metadata_")
+        metadata_path = region_file.parent / f"{base_name}.parquet"
+
+        regions.append(
+            {
+                "region_file": str(region_file),
+                "metadata_file": str(metadata_path) if metadata_path.exists() else None,
+                "shape": {"rows": len(df), "columns": len(df.columns)},
+                "columns": list(df.columns),
+            }
+        )
+
+    result = {
+        "data_directory": str(data_path.absolute()),
+        "num_regions": len(regions),
+        "regions": regions,
+        "job_metadata_files": [str(f) for f in job_metadata_files],
+    }
+
+    return json.dumps(result, indent=2)
+
+
+# Agent tool for code execution against dataframes
+def execute_code(code: str) -> str:
+    """
+    Execute Python pandas code against LlamaSheets extracted data.
+
+    This tool allows flexible data analysis by executing arbitrary pandas code.
+    You can load parquet files, manipulate dataframes, and return results.
+
+    The code executes in a context where:
+    - pandas is available as 'pd'
+    - json is available for formatting output
+
+    Args:
+        code: Python code to execute. Any print() statements or stdout/stderr
+                will be captured and returned. Optionally set a 'result' variable
+                for structured output.
+
+    Returns:
+        String containing:
+        - Any stdout/stderr output from the code execution
+        - The 'result' variable if it was set (formatted appropriately)
+        - Error message if execution failed
+
+    Example usage:
+        code = '''
+    # Load and inspect data
+    df = pd.read_parquet("data/sales_region_1.parquet")
+    print(f"Loaded {len(df)} rows")
+
+    result = {
+        "shape": df.shape,
+        "columns": list(df.columns),
+        "sample": df.head(3).to_dict(orient="records")
+    }
+        '''
+    """
+    global _code_context
+
+    # Capture stdout and stderr
+    stdout_capture = io.StringIO()
+    stderr_capture = io.StringIO()
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+
+    try:
+        # Redirect stdout/stderr
+        sys.stdout = stdout_capture
+        sys.stderr = stderr_capture
+
+        # Create execution context with pandas, json, and previously loaded dfs
+        exec_context = {
+            "pd": pd,
+            "json": json,
+            "Path": Path,
+            **_code_context,  # Include previously loaded dataframes
+        }
+
+        # Execute the code
+        exec(code, exec_context)
+
+        # Update global context with any new variables (excluding built-ins and modules)
+        for key, value in exec_context.items():
+            if not key.startswith("_") and key not in ["pd", "json", "Path"]:
+                _code_context[key] = value
+
+        # Restore stdout/stderr
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+        # Collect output
+        stdout_output = stdout_capture.getvalue()
+        stderr_output = stderr_capture.getvalue()
+
+        output_parts = []
+
+        # Add stdout if any
+        if stdout_output:
+            output_parts.append(f"<stdout>{stdout_output}</stdout>")
+
+        # Add stderr if any
+        if stderr_output:
+            output_parts.append(f"<stderr>{stderr_output}</stderr>")
+
+        # Try to get a result (if code set a 'result' variable)
+        if "result" in exec_context:
+            result = exec_context["result"]
+            result_str = None
+
+            if isinstance(result, pd.DataFrame):
+                # Convert DataFrame to readable format
+                result_str = result.to_string()
+            elif isinstance(result, (dict, list)):
+                result_str = json.dumps(result, indent=2, default=str)
+            else:
+                result_str = str(result)
+
+            if result_str:
+                output_parts.append(f"<result_var>{result_str}</result_var>")
+
+        # Return combined output or success message
+        if output_parts:
+            return "\n\n".join(output_parts)
+        else:
+            return "Code executed successfully (no output or result)"
+
+    except Exception as e:
+        # Restore stdout/stderr in case of error
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+        # Get any partial output
+        stdout_output = stdout_capture.getvalue()
+        stderr_output = stderr_capture.getvalue()
+
+        error_parts = []
+        if stdout_output:
+            error_parts.append(f"=== STDOUT (before error) ===\n{stdout_output}")
+        if stderr_output:
+            error_parts.append(f"=== STDERR (before error) ===\n{stderr_output}")
+
+        error_parts.append(f"=== ERROR ===\n{str(e)}")
+        error_parts.append(f"\n=== CODE ===\n{code}")
+
+        return "\n\n".join(error_parts)
+
+
+def create_llamasheets_agent(
+    llm_model: str = "gpt-4.1", api_key: Optional[str] = None
+) -> FunctionAgent:
+    # Initialize LLM
+    llm = OpenAI(model=llm_model, api_key=api_key)
+
+    # Create tools list
+    tools = [execute_code]
+
+    # System prompt to guide the agent
+    available_regions = list_extracted_data()
+    system_prompt = f"""You are an AI assistant that helps analyze spreadsheet data extracted by LlamaSheets.
+
+LlamaSheets extracts messy spreadsheets into clean parquet files with two types of outputs:
+1. Region files (*_region_*.parquet) - The actual data with columns and rows
+2. Metadata files (*_metadata_*.parquet) - Rich cell-level metadata including:
+   - Formatting: font_bold, font_italic, font_size, background_color_rgb
+   - Position: row_number, column_number, coordinate
+   - Type detection: data_type, is_date_like, is_percentage, is_currency
+   - Layout: is_in_first_row, is_merged_cell, horizontal_alignment
+
+You have access to tools that allow you to execute Python pandas code against these files.
+Use these tools to load the parquet files, analyze the data, and return results.
+
+Key tips:
+- Bold cells in metadata often indicate headers
+- Background colors often indicate groupings or departments
+- Load both region and metadata files for complete analysis
+- Write clear pandas code - you have full pandas functionality available
+- Store results in variables for reuse across multiple code executions
+
+Existing Processed Regions:
+{available_regions}
+"""
+
+    # Configure agent
+    return FunctionAgent(tools=tools, llm=llm, system_prompt=system_prompt)
+
+
+async def main():
+    """Example of using the LlamaSheets agent."""
+
+    # Create the agent
+    agent = create_llamasheets_agent()
+    ctx = Context(agent)
+
+    # Example queries the agent can handle:
+    queries = [
+        # Discovery
+        "What spreadsheet data is available?",
+        # Simple analysis
+        "Load the sales data and show me the first few rows with column info",
+        # Using metadata
+        "Find all bold cells in the metadata - these are likely headers",
+    ]
+
+    # Example: Run a query
+    for query in queries:
+        print(f"\n=== Query: {query} ===")
+        handler = agent.run(query, ctx=ctx)
+        async for ev in handler.stream_events():
+            if isinstance(ev, ToolCall):
+                tool_kwargs_str = (
+                    str(ev.tool_kwargs)[:500] + " ..."
+                    if len(str(ev.tool_kwargs)) > 500
+                    else str(ev.tool_kwargs)
+                )
+                print(f"\n[Tool Call] {ev.tool_name} with args:\n{tool_kwargs_str}\n\n")
+            elif isinstance(ev, ToolCallResult):
+                result_str = (
+                    str(ev.tool_output)[:500] + " ..."
+                    if len(str(ev.tool_output)) > 500
+                    else str(ev.tool_output)
+                )
+                print(f"\n[Tool Result] {ev.tool_name}:\n{result_str}\n\n")
+            elif isinstance(ev, AgentStream):
+                print(ev.delta, end="", flush=True)
+
+        _ = await handler
+        print("\n=== End Query ===\n")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())

examples/sheets/llama-index-agent/requirements.txt

@@ -0,0 +1,7 @@
+llama-cloud-services  # LlamaSheets SDK
+llama-index-core
+llama-index-llms-openai
+pandas>=2.0.0
+pyarrow>=12.0.0
+openpyxl>=3.0.0       # For Excel file support
+matplotlib>=3.7.0     # For visualizations (optional)

examples/sheets/llama-index-agent/scripts/extract.py

@@ -0,0 +1,105 @@
+"""
+⚠️ DEPRECATION NOTICE:
+This example uses the deprecated llama-cloud-services package, which will be maintained until May 1, 2026.
+Please migrate to: pip install llama-cloud>=1.0 (https://github.com/run-llama/llama-cloud-py)
+"""
+"""Helper script to extract spreadsheets using LlamaSheets."""
+
+import asyncio
+import json
+import os
+import dotenv
+from pathlib import Path
+
+from llama_cloud_services.beta.sheets import LlamaSheets
+from llama_cloud_services.beta.sheets.types import (
+    SpreadsheetParsingConfig,
+    SpreadsheetResultType,
+)
+
+dotenv.load_dotenv()
+
+
+async def extract_spreadsheet(
+    file_path: str, output_dir: str = "data", generate_metadata: bool = True
+) -> dict:
+    """Extract a spreadsheet using LlamaSheets."""
+
+    client = LlamaSheets(
+        base_url="https://api.cloud.llamaindex.ai",
+        api_key=os.getenv("LLAMA_CLOUD_API_KEY"),
+    )
+
+    print(f"Extracting {file_path}...")
+
+    # Extract regions
+    config = SpreadsheetParsingConfig(
+        sheet_names=None,  # Extract all sheets
+        generate_additional_metadata=generate_metadata,
+    )
+
+    job_result = await client.aextract_regions(file_path, config=config)
+
+    print(f"Extracted {len(job_result.regions)} region(s)")
+
+    # Create output directory
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Get base name for files
+    base_name = Path(file_path).stem
+
+    # Save job metadata
+    job_metadata_path = output_path / f"{base_name}_job_metadata.json"
+    with open(job_metadata_path, "w") as f:
+        json.dump(job_result.model_dump(mode="json"), f, indent=2)
+    print(f"Saved job metadata to {job_metadata_path}")
+
+    # Download each region
+    for idx, region in enumerate(job_result.regions, 1):
+        sheet_name = region.sheet_name.replace(" ", "_")
+
+        # Download region data
+        region_bytes = await client.adownload_region_result(
+            job_id=job_result.id,
+            region_id=region.region_id,
+            result_type=region.region_type,
+        )
+
+        region_path = output_path / f"{base_name}_region_{idx}_{sheet_name}.parquet"
+        with open(region_path, "wb") as f:
+            f.write(region_bytes)
+        print(f"  Table {idx}: {region_path}")
+
+        # Download metadata
+        metadata_bytes = await client.adownload_region_result(
+            job_id=job_result.id,
+            region_id=region.region_id,
+            result_type=SpreadsheetResultType.CELL_METADATA,
+        )
+
+        metadata_path = output_path / f"{base_name}_metadata_{idx}_{sheet_name}.parquet"
+        with open(metadata_path, "wb") as f:
+            f.write(metadata_bytes)
+        print(f"  Metadata {idx}: {metadata_path}")
+
+    print(f"\nAll files saved to {output_path}/")
+
+    return job_result.model_dump(mode="json")
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python scripts/extract.py <spreadsheet_file>")
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+
+    if not Path(file_path).exists():
+        print(f"❌ File not found: {file_path}")
+        sys.exit(1)
+
+    result = asyncio.run(extract_spreadsheet(file_path))
+    print(f"\n✅ Extraction complete! Job ID: {result['id']}")

examples/split/document_splitting/document_splitting.ipynb

@@ -0,0 +1,547 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Document Splitting with LlamaCloud\n",
+    "\n",
+    "This notebook demonstrates how to use the LlamaCloud **Split** API to automatically segment a concatenated PDF into logical document sections based on content categories.\n",
+    "\n",
+    "## Use Case\n",
+    "\n",
+    "When dealing with large PDFs that contain multiple distinct documents or sections (e.g., a bundle of research papers, a collection of reports), you often need to split them into individual segments. The Split API uses AI to:\n",
+    "\n",
+    "1. Analyze each page's content\n",
+    "2. Classify pages into user-defined categories\n",
+    "3. Group consecutive pages of the same category into segments\n",
+    "\n",
+    "## Example Document\n",
+    "\n",
+    "We'll use a PDF containing three concatenated documents:\n",
+    "- **Alan Turing's essay** \"Intelligent Machinery, A Heretical Theory\" (an essay)\n",
+    "- **ImageNet paper** (a research paper)\n",
+    "- **\"Attention is All You Need\"** paper (a research paper)\n",
+    "\n",
+    "We'll split this into segments categorized as either `essay` or `research_paper`.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **⚠️ DEPRECATION NOTICE**>> This example uses the deprecated `llama-cloud-services` package, which will be maintained until **May 1, 2026**.>> **Please migrate to:**> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))> - **New Package Documentation**: https://docs.cloud.llamaindex.ai/>> The new package provides the same functionality with improved performance and support."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Requirement already satisfied: llama-cloud in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (0.1.44)\n",
+      "Requirement already satisfied: python-dotenv in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (1.2.1)\n",
+      "Requirement already satisfied: requests in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (2.32.5)\n",
+      "Requirement already satisfied: certifi>=2024.7.4 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from llama-cloud) (2025.11.12)\n",
+      "Requirement already satisfied: httpx>=0.20.0 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from llama-cloud) (0.28.1)\n",
+      "Requirement already satisfied: pydantic>=1.10 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from llama-cloud) (2.12.5)\n",
+      "Requirement already satisfied: charset_normalizer<4,>=2 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from requests) (3.4.4)\n",
+      "Requirement already satisfied: idna<4,>=2.5 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from requests) (3.11)\n",
+      "Requirement already satisfied: urllib3<3,>=1.21.1 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from requests) (2.5.0)\n",
+      "Requirement already satisfied: anyio in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from httpx>=0.20.0->llama-cloud) (4.11.0)\n",
+      "Requirement already satisfied: httpcore==1.* in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from httpx>=0.20.0->llama-cloud) (1.0.9)\n",
+      "Requirement already satisfied: h11>=0.16 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from httpcore==1.*->httpx>=0.20.0->llama-cloud) (0.16.0)\n",
+      "Requirement already satisfied: annotated-types>=0.6.0 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from pydantic>=1.10->llama-cloud) (0.7.0)\n",
+      "Requirement already satisfied: pydantic-core==2.41.5 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from pydantic>=1.10->llama-cloud) (2.41.5)\n",
+      "Requirement already satisfied: typing-extensions>=4.14.1 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from pydantic>=1.10->llama-cloud) (4.15.0)\n",
+      "Requirement already satisfied: typing-inspection>=0.4.2 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from pydantic>=1.10->llama-cloud) (0.4.2)\n",
+      "Requirement already satisfied: sniffio>=1.1 in /Users/javier/llama_cloud_services/.venv/lib/python3.11/site-packages (from anyio->httpx>=0.20.0->llama-cloud) (1.3.1)\n",
+      "\n",
+      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip is available: \u001b[0m\u001b[31;49m25.0.1\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m25.3\u001b[0m\n",
+      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpip install --upgrade pip\u001b[0m\n",
+      "Note: you may need to restart the kernel to use updated packages.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Install required packages\n",
+    "%pip install llama-cloud python-dotenv requests"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "✅ API configured with base URL: https://api.cloud.llamaindex.ai\n",
+      "✅ Project ID: using default project\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "import time\n",
+    "import requests\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "# Load environment variables\n",
+    "load_dotenv()\n",
+    "\n",
+    "# Configuration\n",
+    "LLAMA_CLOUD_API_KEY = os.environ.get(\"LLAMA_CLOUD_API_KEY\", \"llx-...\")\n",
+    "BASE_URL = os.environ.get(\"LLAMA_CLOUD_BASE_URL\", \"https://api.cloud.llamaindex.ai\")\n",
+    "PROJECT_ID = os.environ.get(\"LLAMA_CLOUD_PROJECT_ID\", None)\n",
+    "\n",
+    "# Headers for API requests\n",
+    "headers = {\n",
+    "    \"Authorization\": f\"Bearer {LLAMA_CLOUD_API_KEY}\",\n",
+    "    \"Content-Type\": \"application/json\",\n",
+    "}\n",
+    "\n",
+    "print(f\"✅ API configured with base URL: {BASE_URL}\")\n",
+    "print(f\"✅ Project ID: {PROJECT_ID or 'using default project'}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 1: Upload the PDF File\n",
+    "\n",
+    "First, we'll upload our concatenated PDF to LlamaCloud using the Files API. This can be done using the `llama-cloud` SDK.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "📤 Uploading ./data/turing+imagenet+attention.pdf...\n",
+      "✅ File uploaded successfully!\n",
+      "   File name: turing+imagenet+attention.pdf\n"
+     ]
+    }
+   ],
+   "source": [
+    "from llama_cloud.client import LlamaCloud\n",
+    "\n",
+    "# Initialize the client\n",
+    "client = LlamaCloud(token=LLAMA_CLOUD_API_KEY, base_url=BASE_URL)\n",
+    "\n",
+    "# Path to the PDF file\n",
+    "pdf_path = \"./data/turing+imagenet+attention.pdf\"\n",
+    "\n",
+    "# Upload the file\n",
+    "print(f\"📤 Uploading {pdf_path}...\")\n",
+    "\n",
+    "with open(pdf_path, \"rb\") as f:\n",
+    "    uploaded_file = client.files.upload_file(upload_file=f, project_id=PROJECT_ID)\n",
+    "\n",
+    "file_id = uploaded_file.id\n",
+    "print(f\"✅ File uploaded successfully!\")\n",
+    "print(f\"   File name: {uploaded_file.name}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 2: Create a Split Job\n",
+    "\n",
+    "Now we'll create a split job using the Split API. Since the Split API is in beta and not yet available in the SDK, we'll use raw HTTP requests.\n",
+    "\n",
+    "We define two categories:\n",
+    "- **essay**: For philosophical or reflective writing\n",
+    "- **research_paper**: For formal academic documents with methodology and citations\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🔄 Creating split job...\n",
+      "✅ Split job created!\n",
+      "   Job ID: spl-zsssb632a742aikliu96pqkb56t5\n",
+      "   Status: pending\n",
+      "   Categories: ['essay', 'research_paper']\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Define the split job request\n",
+    "split_request = {\n",
+    "    \"document_input\": {\n",
+    "        \"type\": \"file_id\",  # only file_id is supported for now\n",
+    "        \"value\": file_id,\n",
+    "    },\n",
+    "    \"categories\": [\n",
+    "        {\n",
+    "            \"name\": \"essay\",\n",
+    "            \"description\": \"A philosophical or reflective piece of writing that presents personal viewpoints, arguments, or thoughts on a topic without strict formal structure\",\n",
+    "        },\n",
+    "        {\n",
+    "            \"name\": \"research_paper\",\n",
+    "            \"description\": \"A formal academic document presenting original research, methodology, experiments, results, and conclusions with citations and references\",\n",
+    "        },\n",
+    "    ],\n",
+    "}\n",
+    "\n",
+    "# Create the split job\n",
+    "print(\"🔄 Creating split job...\")\n",
+    "response = requests.post(\n",
+    "    f\"{BASE_URL}/api/v1/beta/split/jobs\",\n",
+    "    params={\"project_id\": PROJECT_ID},\n",
+    "    headers=headers,\n",
+    "    json=split_request,\n",
+    ")\n",
+    "response.raise_for_status()\n",
+    "\n",
+    "split_job = response.json()\n",
+    "job_id = split_job[\"id\"]\n",
+    "\n",
+    "print(f\"✅ Split job created!\")\n",
+    "print(f\"   Job ID: {job_id}\")\n",
+    "print(f\"   Status: {split_job['status']}\")\n",
+    "print(f\"   Categories: {[c['name'] for c in split_job['categories']]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 3: Poll for Job Completion\n",
+    "\n",
+    "The split job runs asynchronously. We'll poll the job status until it completes.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "⏳ Waiting for split job to complete...\n",
+      "   Status: processing (elapsed: 0s)\n",
+      "   Status: processing (elapsed: 5s)\n",
+      "   Status: processing (elapsed: 11s)\n",
+      "   Status: completed (elapsed: 16s)\n",
+      "\n",
+      "✅ Split job completed successfully!\n"
+     ]
+    }
+   ],
+   "source": [
+    "def poll_split_job(job_id: str, max_wait_seconds: int = 180, poll_interval: int = 5):\n",
+    "    \"\"\"\n",
+    "    Poll a split job until it reaches a terminal state.\n",
+    "\n",
+    "    Args:\n",
+    "        job_id: The split job ID\n",
+    "        max_wait_seconds: Maximum time to wait for completion\n",
+    "        poll_interval: Seconds between poll attempts\n",
+    "\n",
+    "    Returns:\n",
+    "        The completed job response\n",
+    "    \"\"\"\n",
+    "    start_time = time.time()\n",
+    "\n",
+    "    while (time.time() - start_time) < max_wait_seconds:\n",
+    "        response = requests.get(\n",
+    "            f\"{BASE_URL}/api/v1/beta/split/jobs/{job_id}\",\n",
+    "            params={\"project_id\": PROJECT_ID},\n",
+    "            headers=headers,\n",
+    "        )\n",
+    "        response.raise_for_status()\n",
+    "        job = response.json()\n",
+    "\n",
+    "        status = job[\"status\"]\n",
+    "        elapsed = int(time.time() - start_time)\n",
+    "        print(f\"   Status: {status} (elapsed: {elapsed}s)\")\n",
+    "\n",
+    "        if status in [\"completed\", \"failed\"]:\n",
+    "            return job\n",
+    "\n",
+    "        time.sleep(poll_interval)\n",
+    "\n",
+    "    raise TimeoutError(f\"Job did not complete within {max_wait_seconds} seconds\")\n",
+    "\n",
+    "\n",
+    "print(\"⏳ Waiting for split job to complete...\")\n",
+    "completed_job = poll_split_job(job_id)\n",
+    "\n",
+    "if completed_job[\"status\"] == \"completed\":\n",
+    "    print(\"\\n✅ Split job completed successfully!\")\n",
+    "else:\n",
+    "    print(\n",
+    "        f\"\\n❌ Split job failed: {completed_job.get('error_message', 'Unknown error')}\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 4: Analyze the Results\n",
+    "\n",
+    "Let's examine the split results to see how the document was segmented.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "📊 Split Results Summary\n",
+      "==================================================\n",
+      "Total segments found: 3\n",
+      "\n",
+      "Segments by category:\n",
+      "   • essay: 1 segment(s)\n",
+      "   • research_paper: 2 segment(s)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Get the segments from the result\n",
+    "segments = completed_job.get(\"result\", {}).get(\"segments\", [])\n",
+    "\n",
+    "print(f\"📊 Split Results Summary\")\n",
+    "print(f\"=\" * 50)\n",
+    "print(f\"Total segments found: {len(segments)}\")\n",
+    "print()\n",
+    "\n",
+    "# Count by category\n",
+    "category_counts = {}\n",
+    "for segment in segments:\n",
+    "    cat = segment[\"category\"]\n",
+    "    category_counts[cat] = category_counts.get(cat, 0) + 1\n",
+    "\n",
+    "print(\"Segments by category:\")\n",
+    "for cat, count in category_counts.items():\n",
+    "    print(f\"   • {cat}: {count} segment(s)\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "📄 Segment Details\n",
+      "==================================================\n",
+      "\n",
+      "Segment 1:\n",
+      "   Category: essay\n",
+      "   Pages 1-4 (4 pages)\n",
+      "   Confidence: high\n",
+      "\n",
+      "Segment 2:\n",
+      "   Category: research_paper\n",
+      "   Pages 5-13 (9 pages)\n",
+      "   Confidence: high\n",
+      "\n",
+      "Segment 3:\n",
+      "   Category: research_paper\n",
+      "   Pages 14-24 (11 pages)\n",
+      "   Confidence: high\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Display detailed segment information\n",
+    "print(f\"\\n📄 Segment Details\")\n",
+    "print(f\"=\" * 50)\n",
+    "\n",
+    "for i, segment in enumerate(segments, 1):\n",
+    "    category = segment[\"category\"]\n",
+    "    pages = segment[\"pages\"]\n",
+    "    confidence = segment[\"confidence_category\"]\n",
+    "\n",
+    "    # Format page range\n",
+    "    if len(pages) == 1:\n",
+    "        page_range = f\"Page {pages[0]}\"\n",
+    "    else:\n",
+    "        page_range = f\"Pages {min(pages)}-{max(pages)}\"\n",
+    "\n",
+    "    print(f\"\\nSegment {i}:\")\n",
+    "    print(f\"   Category: {category}\")\n",
+    "    print(f\"   {page_range} ({len(pages)} page{'s' if len(pages) > 1 else ''})\")\n",
+    "    print(f\"   Confidence: {confidence}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Expected Results\n",
+    "\n",
+    "Based on our test document, we expect:\n",
+    "- **1 essay segment**: Alan Turing's \"Intelligent Machinery, A Heretical Theory\"\n",
+    "- **2 research paper segments**: ImageNet paper and \"Attention is All You Need\" paper\n",
+    "\n",
+    "The pages should be grouped consecutively, with no overlap between segments.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "✅ Validation\n",
+      "==================================================\n",
+      "Total pages assigned: 24\n",
+      "Unique pages: 24\n",
+      "✅ No page overlap detected - each page belongs to exactly one segment\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Verify no page overlap\n",
+    "all_pages = []\n",
+    "for segment in segments:\n",
+    "    all_pages.extend(segment[\"pages\"])\n",
+    "\n",
+    "unique_pages = set(all_pages)\n",
+    "\n",
+    "print(f\"\\n✅ Validation\")\n",
+    "print(f\"=\" * 50)\n",
+    "print(f\"Total pages assigned: {len(all_pages)}\")\n",
+    "print(f\"Unique pages: {len(unique_pages)}\")\n",
+    "\n",
+    "if len(all_pages) == len(unique_pages):\n",
+    "    print(f\"✅ No page overlap detected - each page belongs to exactly one segment\")\n",
+    "else:\n",
+    "    print(\n",
+    "        f\"⚠️  Page overlap detected - {len(all_pages) - len(unique_pages)} duplicate assignments\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using `allow_uncategorized` Strategy\n",
+    "\n",
+    "You can also use the `allow_uncategorized` splitting strategy. This is useful when you want to capture pages that don't match any defined category.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "📝 With allow_uncategorized=True and only 'essay' category defined,\n",
+      "   pages that don't match 'essay' will be grouped as 'uncategorized'.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Example with allow_uncategorized strategy\n",
+    "split_request_uncategorized = {\n",
+    "    \"document_input\": {\"type\": \"file_id\", \"value\": file_id},\n",
+    "    \"categories\": [\n",
+    "        {\n",
+    "            \"name\": \"essay\",\n",
+    "            \"description\": \"A philosophical or reflective piece of writing that presents personal viewpoints, arguments, or thoughts on a topic\",\n",
+    "        }\n",
+    "        # Note: We only define 'essay' category\n",
+    "        # Research papers will be classified as 'uncategorized'\n",
+    "    ],\n",
+    "    \"splitting_strategy\": {\"allow_uncategorized\": True},\n",
+    "}\n",
+    "\n",
+    "print(\"📝 With allow_uncategorized=True and only 'essay' category defined,\")\n",
+    "print(\"   pages that don't match 'essay' will be grouped as 'uncategorized'.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "The LlamaCloud Split API provides a powerful way to automatically segment concatenated documents based on content categories. This is useful for:\n",
+    "\n",
+    "- **Document processing pipelines**: Automatically separate bundled documents before further processing\n",
+    "- **Content organization**: Categorize and organize mixed document collections\n",
+    "- **Information extraction**: Identify different document types within a single file\n",
+    "\n",
+    "### Key Features\n",
+    "\n",
+    "- **AI-powered classification**: Uses LLMs to understand page content and assign categories\n",
+    "- **Flexible categories**: Define any categories relevant to your use case\n",
+    "- **Confidence scoring**: Each segment includes a confidence level\n",
+    "- **Page-level granularity**: Results include exact page numbers for each segment\n",
+    "\n",
+    "### API Reference\n",
+    "\n",
+    "- **Create Split Job**: `POST /api/v1/beta/split/jobs`\n",
+    "- **Get Split Job**: `GET /api/v1/beta/split/jobs/{job_id}`\n",
+    "- **List Split Jobs**: `GET /api/v1/beta/split/jobs`\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "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": 2
+}

extract.md

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

index.md

@@ -1,86 +0,0 @@
-# LlamaCloud Index + Retriever
-
-LlamaCloud is a new generation of managed parsing, ingestion, and retrieval services, designed to bring production-grade context-augmentation to your LLM and RAG applications.
-
-Currently, LlamaCloud supports
-
-- Managed Ingestion API, handling parsing and document management
-- Managed Retrieval API, configuring optimal retrieval for your RAG system
-
-## Access
-
-We are opening up a private beta to a limited set of enterprise partners for the managed ingestion and retrieval API. If you’re interested in centralizing your data pipelines and spending more time working on your actual RAG use cases, come [talk to us.](https://www.llamaindex.ai/contact)
-
-If you have access to LlamaCloud, you can visit [LlamaCloud](https://cloud.llamaindex.ai) to sign in and get an API key.
-
-## Setup
-
-First, make sure you have the latest LlamaIndex version installed.
-
-```
-pip uninstall llama-index  # run this if upgrading from v0.9.x or older
-pip install -U llama-index --upgrade --no-cache-dir --force-reinstall
-```
-
-The `llama-index-indices-managed-llama-cloud` package is included with the above install, but you can also install directly
-
-```
-pip install -U llama-index-indices-managed-llama-cloud
-```
-
-## Usage
-
-You can create an index on LlamaCloud using the following code. By default, new indexes use managed embeddings (OpenAI text-embedding-3-small, 1536 dimensions, 1 credit/page):
-
-```python
-import os
-
-os.environ[
-    "LLAMA_CLOUD_API_KEY"
-] = "llx-..."  # can provide API-key in env or in the constructor later on
-
-from llama_index.core import SimpleDirectoryReader
-from llama_cloud_services import LlamaCloudIndex
-
-# create a new index (uses managed embeddings by default)
-index = LlamaCloudIndex.from_documents(
-    documents,
-    "my_first_index",
-    project_name="default",
-    api_key="llx-...",
-    verbose=True,
-)
-
-# connect to an existing index
-index = LlamaCloudIndex("my_first_index", project_name="default")
-```
-
-You can also configure a retriever for managed retrieval:
-
-```python
-# from the existing index
-index.as_retriever()
-
-# from scratch
-from llama_index.indices.managed.llama_cloud import LlamaCloudRetriever
-
-retriever = LlamaCloudRetriever("my_first_index", project_name="default")
-```
-
-And of course, you can use other index shortcuts to get use out of your new managed index:
-
-```python
-query_engine = index.as_query_engine(llm=llm)
-
-chat_engine = index.as_chat_engine(llm=llm)
-```
-
-## Retriever Settings
-
-A full list of retriever settings/kwargs is below:
-
-- `dense_similarity_top_k`: Optional[int] -- If greater than 0, retrieve `k` nodes using dense retrieval
-- `sparse_similarity_top_k`: Optional[int] -- If greater than 0, retrieve `k` nodes using sparse retrieval
-- `enable_reranking`: Optional[bool] -- Whether to enable reranking or not. Sacrifices some speed for accuracy
-- `rerank_top_n`: Optional[int] -- The number of nodes to return after reranking initial retrieval results
-- `alpha` Optional[float] -- The weighting between dense and sparse retrieval. 1 = Full dense retrieval, 0 = Full sparse retrieval.

package.json

@@ -19,7 +19,7 @@
   "lint-staged": {
     "ts/llama_cloud_services/src/**/*.{ts,tsx,js,jsx}": [
       "pnpm --filter llama-cloud-services exec eslint --fix",
-      "pnpm --filter llama-cloud-services exec prettier --write"
+      "pnpm --filter llama-cloud-services exec prettier --write src/ tests/"
     ]
   },
   "packageManager": "pnpm@10.11.1+sha512.e519b9f7639869dc8d5c3c5dfef73b3f091094b0a006d7317353c72b124e80e1afd429732e28705ad6bfa1ee879c1fce46c128ccebd3192101f43dd67c667912"

parse.md

@@ -1,163 +0,0 @@
-# LlamaParse
-
-LlamaParse is a **GenAI-native document parser** that can parse complex document data for any downstream LLM use case (RAG, agents).
-
-It is really good at the following:
-
-- ✅ **Broad file type support**: Parsing a variety of unstructured file types (.pdf, .pptx, .docx, .xlsx, .html) with text, tables, visual elements, weird layouts, and more.
-- ✅ **Table recognition**: Parsing embedded tables accurately into text and semi-structured representations.
-- ✅ **Multimodal parsing and chunking**: Extracting visual elements (images/diagrams) into structured formats and return image chunks using the latest multimodal models.
-- ✅ **Custom parsing**: Input custom prompt instructions to customize the output the way you want it.
-
-LlamaParse directly integrates with [LlamaIndex](https://github.com/run-llama/llama_index).
-
-The free plan is up to 1000 pages a day. Paid plan is free 7k pages per week + 0.3c per additional page by default. There is a sandbox available to test the API [**https://cloud.llamaindex.ai/parse ↗**](https://cloud.llamaindex.ai/parse).
-
-Read below for some quickstart information, or see the [full documentation](https://docs.cloud.llamaindex.ai/).
-
-If you're a company interested in enterprise RAG solutions, and/or high volume/on-prem usage of LlamaParse, come [talk to us](https://www.llamaindex.ai/contact).
-
-## Getting Started
-
-First, login and get an api-key from [**https://cloud.llamaindex.ai/api-key ↗**](https://cloud.llamaindex.ai/api-key).
-
-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
-export LLAMA_CLOUD_API_KEY='llx-...'
-
-# output as text
-llama-parse my_file.pdf --result-type text --output-file output.txt
-
-# output as markdown
-llama-parse my_file.pdf --result-type markdown --output-file output.md
-
-# output as raw json
-llama-parse my_file.pdf --output-raw-json --output-file output.json
-```
-
-## Python Usage
-
-You can also create simple scripts:
-
-```python
-from llama_cloud_services import LlamaParse
-
-parser = LlamaParse(
-    api_key="llx-...",  # can also be set in your env as LLAMA_CLOUD_API_KEY
-    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
-result = parser.parse("./my_file.pdf")
-
-# sync batch
-results = parser.parse(["./my_file1.pdf", "./my_file2.pdf"])
-
-# async
-result = await parser.aparse("./my_file.pdf")
-
-# async batch
-results = await parser.aparse(["./my_file1.pdf", "./my_file2.pdf"])
-```
-
-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](./docs/examples-py/parse/demo_json_tour.ipynb).
-
-### Using with file object / bytes
-
-You can parse a file object directly:
-
-```python
-from llama_cloud_services import LlamaParse
-
-parser = LlamaParse(
-    api_key="llx-...",  # can also be set in your env as LLAMA_CLOUD_API_KEY
-    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
-)
-
-file_name = "my_file1.pdf"
-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
-    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
-    result = parser.parse(file_bytes, extra_info=extra_info)
-```
-
-### Using with `SimpleDirectoryReader`
-
-You can also integrate the parser as the default PDF loader in `SimpleDirectoryReader`:
-
-```python
-from llama_cloud_services import LlamaParse
-from llama_index.core import SimpleDirectoryReader
-
-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
-    verbose=True,
-)
-
-file_extractor = {".pdf": parser}
-documents = SimpleDirectoryReader(
-    "./data", file_extractor=file_extractor
-).load_data()
-```
-
-Full documentation for `SimpleDirectoryReader` can be found on the [LlamaIndex Documentation](https://developers.llamaindex.ai/python/framework/module_guides/loading/simpledirectoryreader/).
-
-## Examples
-
-Several end-to-end indexing examples can be found in the examples folder
-
-- [Getting Started](docs/examples-py/parse/demo_basic.ipynb)
-- [Advanced RAG Example](docs/examples-py/parse/demo_advanced.ipynb)
-- [Raw API Usage](docs/examples-py/parse/demo_api.ipynb)
-- [Result Object Tour](docs/examples-py/parse/demo_json_tour.ipynb)
-
-## Documentation
-
-[https://docs.cloud.llamaindex.ai/](https://docs.cloud.llamaindex.ai/)

pnpm-lock.yaml

@@ -60,9 +60,6 @@ importers:
       p-retry:
         specifier: ^6.2.1
         version: 6.2.1
-      zod:
-        specifier: ^3.25.76
-        version: 3.25.76
     devDependencies:
       '@eslint/js':
         specifier: ^9.32.0
@@ -74,23 +71,23 @@ importers:
         specifier: ^0.67.5
         version: 0.67.6(magicast@0.3.5)(typescript@5.9.2)
       '@llamaindex/core':
-        specifier: ^0.6.19
-        version: 0.6.19
+        specifier: ^0.6.22
+        version: 0.6.22
       '@llamaindex/env':
         specifier: ^0.1.30
         version: 0.1.30
       '@llamaindex/workflow-core':
-        specifier: ^0.4.1
-        version: 0.4.6(p-retry@6.2.1)(zod@3.25.76)
+        specifier: ^1.3.3
+        version: 1.3.3(p-retry@6.2.1)(zod@4.1.13)
       '@types/node':
         specifier: ^20.19.9
         version: 20.19.9
       '@typescript-eslint/eslint-plugin':
         specifier: ^8.38.0
-        version: 8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+        version: 8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       '@typescript-eslint/parser':
         specifier: ^8.38.0
-        version: 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+        version: 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       '@vitest/coverage-v8':
         specifier: ^2.0.0
         version: 2.1.9(vitest@2.1.9)
@@ -102,7 +99,7 @@ importers:
         version: 6.6.0(typescript@5.9.2)
       eslint:
         specifier: ^9.32.0
-        version: 9.32.0(jiti@2.5.1)
+        version: 9.32.0(jiti@2.6.1)
       globals:
         specifier: ^16.3.0
         version: 16.3.0
@@ -117,10 +114,13 @@ importers:
         version: 5.9.2
       typescript-eslint:
         specifier: ^8.38.0
-        version: 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+        version: 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       vitest:
         specifier: ^2.0.0
-        version: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)
+        version: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)(lightningcss@1.30.2)
+      zod:
+        specifier: ^4.1.13
+        version: 4.1.13
 
 packages:
 
@@ -401,6 +401,12 @@ packages:
   '@fastify/deepmerge@1.3.0':
     resolution: {integrity: sha512-J8TOSBq3SoZbDhM9+R/u77hP93gz/rajSA+K2kGyijPpORPWUXHUpTaleoj+92As0S9uPRP7Oi8IqMf0u+ro6A==}
 
+  '@finom/zod-to-json-schema@3.24.11':
+    resolution: {integrity: sha512-fL656yBPiWebtfGItvtXLWrFNGlF1NcDFS0WdMQXMs9LluVg0CfT5E2oXYp0pidl0vVG53XkW55ysijNkU5/hA==}
+    deprecated: 'Use https://www.npmjs.com/package/zod-v3-to-json-schema instead. See issue comment for details: https://github.com/StefanTerdell/zod-to-json-schema/issues/178#issuecomment-3533122539'
+    peerDependencies:
+      zod: ^4.0.14
+
   '@hey-api/client-fetch@0.10.2':
     resolution: {integrity: sha512-AGiFYDx+y8VT1wlQ3EbzzZtfU8EfV+hLLRTtr8Y/tjYZaxIECwJagVZf24YzNbtEBXONFV50bwcU1wLVGXe1ow==}
     deprecated: Starting with v0.73.0, this package is bundled directly inside @hey-api/openapi-ts.
@@ -471,8 +477,8 @@ packages:
   '@jsdevtools/ono@7.1.3':
     resolution: {integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==}
 
-  '@llamaindex/core@0.6.19':
-    resolution: {integrity: sha512-TkVnhYRah95bRySo2kSgZIRhqO54fbmppHZI7BBU7RFptKquLe9lASHamjM5cPwlmL1XHZ2cTEof+eRDuGahbQ==}
+  '@llamaindex/core@0.6.22':
+    resolution: {integrity: sha512-/BXyemkvpxMaUhOkbwJ2PTvzKjSWkL8+6QLpz/n+pk8xBwMMe1GVBgli/J57gCyi8GbrlBafBj6GaPOgWub2Eg==}
 
   '@llamaindex/env@0.1.30':
     resolution: {integrity: sha512-y6kutMcCevzbmexUgz+HXf7KiZemzAoFEYSjAILfR+cG6FmYSF8XvLbGOB34Kx8mlRi7EI8rZXpezJ5qCqOyZg==}
@@ -485,15 +491,15 @@ packages:
       gpt-tokenizer:
         optional: true
 
-  '@llamaindex/workflow-core@0.4.6':
-    resolution: {integrity: sha512-SsEgLVR5EfaBcogW1AAy3VJRdPRXo2tYsqQvNWCQF8dS7Uw199MmFyQKzrpeiMBnYPYg8lmLE7HxpStwwdJ3Ng==}
+  '@llamaindex/workflow-core@1.3.3':
+    resolution: {integrity: sha512-WJIcD4K2suGbNkwU5CC70jKKrA5tARba42nMs8Pou1RGzmoxqg+K+b7vyLBmiDtImR8P40YLmkayCIRVQPBmsg==}
     peerDependencies:
       '@modelcontextprotocol/sdk': ^1.7.0
       hono: ^4.7.4
       next: ^15.2.2
       p-retry: ^6.2.1
       rxjs: ^7.8.2
-      zod: ^3.24.2
+      zod: ^3.25.0 || ^4.0.0
     peerDependenciesMeta:
       '@modelcontextprotocol/sdk':
         optional: true
@@ -1133,6 +1139,10 @@ packages:
     resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
     engines: {node: '>=8'}
 
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
   dir-glob@3.0.1:
     resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
     engines: {node: '>=8'}
@@ -1509,8 +1519,8 @@ packages:
   jackspeak@3.4.3:
     resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
 
-  jiti@2.5.1:
-    resolution: {integrity: sha512-twQoecYPiVA5K/h6SxtORw/Bs3ar+mLUtoPSc7iMXzQzK8d7eJ/R09wmTwAjiamETn1cXYPGfNnu7DMoHgu12w==}
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
   js-tiktoken@1.0.20:
@@ -1527,6 +1537,10 @@ packages:
     resolution: {integrity: sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==}
     hasBin: true
 
+  js-yaml@4.1.1:
+    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+    hasBin: true
+
   json-buffer@3.0.1:
     resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
 
@@ -1549,6 +1563,76 @@ packages:
     resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
     engines: {node: '>= 0.8.0'}
 
+  lightningcss-android-arm64@1.30.2:
+    resolution: {integrity: sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.30.2:
+    resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.30.2:
+    resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.30.2:
+    resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.30.2:
+    resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.30.2:
+    resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.30.2:
+    resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.30.2:
+    resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.30.2:
+    resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.30.2:
+    resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.30.2:
+    resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.30.2:
+    resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
+    engines: {node: '>= 12.0.0'}
+
   lilconfig@3.1.3:
     resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
     engines: {node: '>=14'}
@@ -1656,8 +1740,8 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
-  mlly@1.7.4:
-    resolution: {integrity: sha512-qmdSIPC4bDJXgZTCR7XosJiNKySV7O215tsPtDN9iEO/7q/76b/ijtgRu/+epFXSJhijtTCCGp3DWS549P3xKw==}
+  mlly@1.8.0:
+    resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==}
 
   mri@1.2.0:
     resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
@@ -2280,13 +2364,8 @@ packages:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
 
-  zod-to-json-schema@3.24.6:
-    resolution: {integrity: sha512-h/z3PKvcTcTetyjl1fkj79MHNEjm+HpD6NXheWjzOekY7kV+lwDYnHw+ivHkijnCSMz1yJaWBD9vu/Fcmk+vEg==}
-    peerDependencies:
-      zod: ^3.24.1
-
-  zod@3.25.76:
-    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+  zod@4.1.13:
+    resolution: {integrity: sha512-AvvthqfqrAhNH9dnfmrfKzX5upOdjUVJYFqNSlkmGf64gRaTzlPwz99IHYnVs28qYAybvAlBV+H7pn0saFY4Ig==}
 
 snapshots:
 
@@ -2549,9 +2628,9 @@ snapshots:
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
-  '@eslint-community/eslint-utils@4.7.0(eslint@9.32.0(jiti@2.5.1))':
+  '@eslint-community/eslint-utils@4.7.0(eslint@9.32.0(jiti@2.6.1))':
     dependencies:
-      eslint: 9.32.0(jiti@2.5.1)
+      eslint: 9.32.0(jiti@2.6.1)
       eslint-visitor-keys: 3.4.3
 
   '@eslint-community/regexpp@4.12.1': {}
@@ -2595,6 +2674,10 @@ snapshots:
 
   '@fastify/deepmerge@1.3.0': {}
 
+  '@finom/zod-to-json-schema@3.24.11(zod@4.1.13)':
+    dependencies:
+      zod: 4.1.13
+
   '@hey-api/client-fetch@0.10.2(@hey-api/openapi-ts@0.67.6(magicast@0.3.5)(typescript@5.9.2))':
     dependencies:
       '@hey-api/openapi-ts': 0.67.6(magicast@0.3.5)(typescript@5.9.2)
@@ -2603,7 +2686,7 @@ snapshots:
     dependencies:
       '@jsdevtools/ono': 7.1.3
       '@types/json-schema': 7.0.15
-      js-yaml: 4.1.0
+      js-yaml: 4.1.1
       lodash: 4.17.21
 
   '@hey-api/openapi-ts@0.67.6(magicast@0.3.5)(typescript@5.9.2)':
@@ -2663,13 +2746,13 @@ snapshots:
 
   '@jsdevtools/ono@7.1.3': {}
 
-  '@llamaindex/core@0.6.19':
+  '@llamaindex/core@0.6.22':
     dependencies:
+      '@finom/zod-to-json-schema': 3.24.11(zod@4.1.13)
       '@llamaindex/env': 0.1.30
       '@types/node': 24.2.0
       magic-bytes.js: 1.12.1
-      zod: 3.25.76
-      zod-to-json-schema: 3.24.6(zod@3.25.76)
+      zod: 4.1.13
     transitivePeerDependencies:
       - '@huggingface/transformers'
       - gpt-tokenizer
@@ -2680,10 +2763,10 @@ snapshots:
       js-tiktoken: 1.0.20
       pathe: 1.1.2
 
-  '@llamaindex/workflow-core@0.4.6(p-retry@6.2.1)(zod@3.25.76)':
+  '@llamaindex/workflow-core@1.3.3(p-retry@6.2.1)(zod@4.1.13)':
     optionalDependencies:
       p-retry: 6.2.1
-      zod: 3.25.76
+      zod: 4.1.13
 
   '@manypkg/find-root@1.1.0':
     dependencies:
@@ -2930,15 +3013,15 @@ snapshots:
 
   '@types/retry@0.12.2': {}
 
-  '@typescript-eslint/eslint-plugin@8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)':
+  '@typescript-eslint/eslint-plugin@8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)':
     dependencies:
       '@eslint-community/regexpp': 4.12.1
-      '@typescript-eslint/parser': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+      '@typescript-eslint/parser': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       '@typescript-eslint/scope-manager': 8.39.0
-      '@typescript-eslint/type-utils': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
-      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+      '@typescript-eslint/type-utils': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
+      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       '@typescript-eslint/visitor-keys': 8.39.0
-      eslint: 9.32.0(jiti@2.5.1)
+      eslint: 9.32.0(jiti@2.6.1)
       graphemer: 1.4.0
       ignore: 7.0.5
       natural-compare: 1.4.0
@@ -2947,14 +3030,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)':
+  '@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)':
     dependencies:
       '@typescript-eslint/scope-manager': 8.39.0
       '@typescript-eslint/types': 8.39.0
       '@typescript-eslint/typescript-estree': 8.39.0(typescript@5.9.2)
       '@typescript-eslint/visitor-keys': 8.39.0
       debug: 4.4.1
-      eslint: 9.32.0(jiti@2.5.1)
+      eslint: 9.32.0(jiti@2.6.1)
       typescript: 5.9.2
     transitivePeerDependencies:
       - supports-color
@@ -2977,13 +3060,13 @@ snapshots:
     dependencies:
       typescript: 5.9.2
 
-  '@typescript-eslint/type-utils@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)':
+  '@typescript-eslint/type-utils@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)':
     dependencies:
       '@typescript-eslint/types': 8.39.0
       '@typescript-eslint/typescript-estree': 8.39.0(typescript@5.9.2)
-      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       debug: 4.4.1
-      eslint: 9.32.0(jiti@2.5.1)
+      eslint: 9.32.0(jiti@2.6.1)
       ts-api-utils: 2.1.0(typescript@5.9.2)
       typescript: 5.9.2
     transitivePeerDependencies:
@@ -3007,13 +3090,13 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/utils@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)':
+  '@typescript-eslint/utils@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)':
     dependencies:
-      '@eslint-community/eslint-utils': 4.7.0(eslint@9.32.0(jiti@2.5.1))
+      '@eslint-community/eslint-utils': 4.7.0(eslint@9.32.0(jiti@2.6.1))
       '@typescript-eslint/scope-manager': 8.39.0
       '@typescript-eslint/types': 8.39.0
       '@typescript-eslint/typescript-estree': 8.39.0(typescript@5.9.2)
-      eslint: 9.32.0(jiti@2.5.1)
+      eslint: 9.32.0(jiti@2.6.1)
       typescript: 5.9.2
     transitivePeerDependencies:
       - supports-color
@@ -3037,7 +3120,7 @@ snapshots:
       std-env: 3.9.0
       test-exclude: 7.0.1
       tinyrainbow: 1.2.0
-      vitest: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)
+      vitest: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)(lightningcss@1.30.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -3048,13 +3131,13 @@ snapshots:
       chai: 5.2.1
       tinyrainbow: 1.2.0
 
-  '@vitest/mocker@2.1.9(vite@5.4.19(@types/node@20.19.9))':
+  '@vitest/mocker@2.1.9(vite@5.4.19(@types/node@20.19.9)(lightningcss@1.30.2))':
     dependencies:
       '@vitest/spy': 2.1.9
       estree-walker: 3.0.3
       magic-string: 0.30.17
     optionalDependencies:
-      vite: 5.4.19(@types/node@20.19.9)
+      vite: 5.4.19(@types/node@20.19.9)(lightningcss@1.30.2)
 
   '@vitest/pretty-format@2.1.9':
     dependencies:
@@ -3084,7 +3167,7 @@ snapshots:
       sirv: 3.0.1
       tinyglobby: 0.2.14
       tinyrainbow: 1.2.0
-      vitest: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)
+      vitest: 2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)(lightningcss@1.30.2)
 
   '@vitest/utils@2.1.9':
     dependencies:
@@ -3191,8 +3274,8 @@ snapshots:
       defu: 6.1.4
       dotenv: 16.6.1
       giget: 1.2.5
-      jiti: 2.5.1
-      mlly: 1.7.4
+      jiti: 2.6.1
+      mlly: 1.8.0
       ohash: 1.1.6
       pathe: 1.1.2
       perfect-debounce: 1.0.0
@@ -3301,6 +3384,9 @@ snapshots:
 
   detect-indent@6.1.0: {}
 
+  detect-libc@2.1.2:
+    optional: true
+
   dir-glob@3.0.1:
     dependencies:
       path-type: 4.0.0
@@ -3363,9 +3449,9 @@ snapshots:
 
   eslint-visitor-keys@4.2.1: {}
 
-  eslint@9.32.0(jiti@2.5.1):
+  eslint@9.32.0(jiti@2.6.1):
     dependencies:
-      '@eslint-community/eslint-utils': 4.7.0(eslint@9.32.0(jiti@2.5.1))
+      '@eslint-community/eslint-utils': 4.7.0(eslint@9.32.0(jiti@2.6.1))
       '@eslint-community/regexpp': 4.12.1
       '@eslint/config-array': 0.21.0
       '@eslint/config-helpers': 0.3.0
@@ -3401,7 +3487,7 @@ snapshots:
       natural-compare: 1.4.0
       optionator: 0.9.4
     optionalDependencies:
-      jiti: 2.5.1
+      jiti: 2.6.1
     transitivePeerDependencies:
       - supports-color
 
@@ -3700,7 +3786,7 @@ snapshots:
     optionalDependencies:
       '@pkgjs/parseargs': 0.11.0
 
-  jiti@2.5.1: {}
+  jiti@2.6.1: {}
 
   js-tiktoken@1.0.20:
     dependencies:
@@ -3718,6 +3804,10 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
+  js-yaml@4.1.1:
+    dependencies:
+      argparse: 2.0.1
+
   json-buffer@3.0.1: {}
 
   json-schema-traverse@0.4.1: {}
@@ -3739,6 +3829,56 @@ snapshots:
       prelude-ls: 1.2.1
       type-check: 0.4.0
 
+  lightningcss-android-arm64@1.30.2:
+    optional: true
+
+  lightningcss-darwin-arm64@1.30.2:
+    optional: true
+
+  lightningcss-darwin-x64@1.30.2:
+    optional: true
+
+  lightningcss-freebsd-x64@1.30.2:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.30.2:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.30.2:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.30.2:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.30.2:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.30.2:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.30.2:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.30.2:
+    optional: true
+
+  lightningcss@1.30.2:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.30.2
+      lightningcss-darwin-arm64: 1.30.2
+      lightningcss-darwin-x64: 1.30.2
+      lightningcss-freebsd-x64: 1.30.2
+      lightningcss-linux-arm-gnueabihf: 1.30.2
+      lightningcss-linux-arm64-gnu: 1.30.2
+      lightningcss-linux-arm64-musl: 1.30.2
+      lightningcss-linux-x64-gnu: 1.30.2
+      lightningcss-linux-x64-musl: 1.30.2
+      lightningcss-win32-arm64-msvc: 1.30.2
+      lightningcss-win32-x64-msvc: 1.30.2
+    optional: true
+
   lilconfig@3.1.3: {}
 
   lint-staged@15.5.2:
@@ -3850,7 +3990,7 @@ snapshots:
 
   mkdirp@1.0.4: {}
 
-  mlly@1.7.4:
+  mlly@1.8.0:
     dependencies:
       acorn: 8.15.0
       pathe: 2.0.3
@@ -3993,7 +4133,7 @@ snapshots:
   pkg-types@1.3.1:
     dependencies:
       confbox: 0.1.8
-      mlly: 1.7.4
+      mlly: 1.8.0
       pathe: 2.0.3
 
   postcss@8.5.6:
@@ -4282,13 +4422,13 @@ snapshots:
     dependencies:
       prelude-ls: 1.2.1
 
-  typescript-eslint@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2):
+  typescript-eslint@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2):
     dependencies:
-      '@typescript-eslint/eslint-plugin': 8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
-      '@typescript-eslint/parser': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
+      '@typescript-eslint/eslint-plugin': 8.39.0(@typescript-eslint/parser@8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2))(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
+      '@typescript-eslint/parser': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
       '@typescript-eslint/typescript-estree': 8.39.0(typescript@5.9.2)
-      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.5.1))(typescript@5.9.2)
-      eslint: 9.32.0(jiti@2.5.1)
+      '@typescript-eslint/utils': 8.39.0(eslint@9.32.0(jiti@2.6.1))(typescript@5.9.2)
+      eslint: 9.32.0(jiti@2.6.1)
       typescript: 5.9.2
     transitivePeerDependencies:
       - supports-color
@@ -4312,13 +4452,13 @@ snapshots:
     dependencies:
       punycode: 2.3.1
 
-  vite-node@2.1.9(@types/node@20.19.9):
+  vite-node@2.1.9(@types/node@20.19.9)(lightningcss@1.30.2):
     dependencies:
       cac: 6.7.14
       debug: 4.4.1
       es-module-lexer: 1.7.0
       pathe: 1.1.2
-      vite: 5.4.19(@types/node@20.19.9)
+      vite: 5.4.19(@types/node@20.19.9)(lightningcss@1.30.2)
     transitivePeerDependencies:
       - '@types/node'
       - less
@@ -4330,7 +4470,7 @@ snapshots:
       - supports-color
       - terser
 
-  vite@5.4.19(@types/node@20.19.9):
+  vite@5.4.19(@types/node@20.19.9)(lightningcss@1.30.2):
     dependencies:
       esbuild: 0.21.5
       postcss: 8.5.6
@@ -4338,11 +4478,12 @@ snapshots:
     optionalDependencies:
       '@types/node': 20.19.9
       fsevents: 2.3.3
+      lightningcss: 1.30.2
 
-  vitest@2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9):
+  vitest@2.1.9(@types/node@20.19.9)(@vitest/ui@2.1.9)(lightningcss@1.30.2):
     dependencies:
       '@vitest/expect': 2.1.9
-      '@vitest/mocker': 2.1.9(vite@5.4.19(@types/node@20.19.9))
+      '@vitest/mocker': 2.1.9(vite@5.4.19(@types/node@20.19.9)(lightningcss@1.30.2))
       '@vitest/pretty-format': 2.1.9
       '@vitest/runner': 2.1.9
       '@vitest/snapshot': 2.1.9
@@ -4358,8 +4499,8 @@ snapshots:
       tinyexec: 0.3.2
       tinypool: 1.1.1
       tinyrainbow: 1.2.0
-      vite: 5.4.19(@types/node@20.19.9)
-      vite-node: 2.1.9(@types/node@20.19.9)
+      vite: 5.4.19(@types/node@20.19.9)(lightningcss@1.30.2)
+      vite-node: 2.1.9(@types/node@20.19.9)(lightningcss@1.30.2)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 20.19.9
@@ -4426,8 +4567,4 @@ snapshots:
 
   yocto-queue@0.1.0: {}
 
-  zod-to-json-schema@3.24.6(zod@3.25.76):
-    dependencies:
-      zod: 3.25.76
-
-  zod@3.25.76: {}
+  zod@4.1.13: {}

py/CHANGELOG.md

@@ -1,5 +1,108 @@
 # llama-cloud-services-py
 
+## 0.6.94
+
+### Patch Changes
+
+- 232c55b: Include xlsx files in extract input
+
+## 0.6.93
+
+### Patch Changes
+
+- da1916c: Add more warnings
+
+## 0.6.92
+
+### Patch Changes
+
+- 2358df1: add deprecation notices
+
+## 0.6.91
+
+### Patch Changes
+
+- 07ec282: Bump up patch versions for python packages
+- 3040951: Use error description in ExtractedData invalid extraction error
+
+## 0.6.90
+
+### Patch Changes
+
+- 19cbb25: Remove extension filter
+
+## 0.6.89
+
+### Patch Changes
+
+- b9b83c9: Parse bounding boxes from extract jobs results in agent data
+
+## 0.6.88
+
+### Patch Changes
+
+- 71db318: Add tier and version
+
+## 0.6.87
+
+### Patch Changes
+
+- 06c3c55: Update spreadsheet parsing config
+
+## 0.6.86
+
+### Patch Changes
+
+- 1b7198d: Update extract to have confidence scores available in all modes
+
+## 0.6.85
+
+### Patch Changes
+
+- ae30990: Add line-level bbox support
+
+## 0.6.84
+
+### Patch Changes
+
+- 0a110de: Release to re-align versions
+
+## 0.6.83
+
+### Patch Changes
+
+- ca78113: Do not use presigned URLs by default in files client
+
+## 0.6.82
+
+### Patch Changes
+
+- bfaec79: Update for new page number params
+
+## 0.6.81
+
+### Patch Changes
+
+- f3233de: Propagate retrieval metadata to retriever nodes
+
+## 0.6.80
+
+### Patch Changes
+
+- 0506c88: Moved ClassifyClient to LlamaClassify (backward compatible)
+
+## 0.6.79
+
+### Patch Changes
+
+- e020e3e: Remove unneeded organization_id param from beta classifier client
+
+## 0.6.78
+
+### Patch Changes
+
+- 9f1ef4e: Fix extract
+
 ## 0.6.77
 
 ### Patch Changes

py/Makefile

@@ -15,4 +15,4 @@ test:	## Run unit tests via pytest
 
 .PHONY: e2e
 e2e:	## Run all tests. Run with high parallelism using xdist since tests are bottlenecked bound by the slow backend parsing
-	uv run pytest -v -n 32 tests/
+	uv run pytest -v -n 32 --timeout=300 --session-timeout=1740 tests/

py/README.md

@@ -4,6 +4,16 @@
 
 # Llama Cloud Services
 
+> **⚠️ DEPRECATION NOTICE**
+>
+> This repository and its packages are deprecated and will be maintained until **May 1, 2026**.
+>
+> **Please migrate to the new packages:**
+> - **Python**: `pip install llama-cloud>=1.0` ([GitHub](https://github.com/run-llama/llama-cloud-py))
+> - **TypeScript**: `npm install @llamaindex/llama-cloud` ([GitHub](https://github.com/run-llama/llama-cloud-ts))
+>
+> The new packages provide the same functionality with improved performance, better support, and active development.
+
 This repository contains the code for hand-written SDKs and clients for interacting with LlamaCloud.
 
 This includes:

py/llama_cloud_services/__init__.py

@@ -1,3 +1,5 @@
+import warnings
+
 from llama_cloud_services.parse import LlamaParse
 from llama_cloud_services.extract import LlamaExtract, ExtractionAgent
 from llama_cloud_services.utils import SourceText, FileInput
@@ -8,6 +10,16 @@ from llama_cloud_services.index import (
     LlamaCloudRetriever,
 )
 
+# Emit deprecation warning once when package is imported
+warnings.warn(
+    "This package (llama-cloud-services) is deprecated and will be maintained until May 1, 2026. "
+    "Please migrate to the new package: pip install llama-cloud>=1.0 "
+    "(https://github.com/run-llama/llama-cloud-py). "
+    "The new package provides the same functionality with improved performance and support.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 __all__ = [
     "LlamaParse",
     "LlamaExtract",

py/llama_cloud_services/beta/agent_data/__init__.py

@@ -11,6 +11,9 @@ from .schema import (
     InvalidExtractionData,
     ExtractedFieldMetadata,
     ExtractedFieldMetaDataDict,
+    FieldCitation,
+    BoundingBox,
+    PageDimensions,
 )
 from .client import AsyncAgentDataClient
 
@@ -28,4 +31,7 @@ __all__ = [
     "InvalidExtractionData",
     "ExtractedFieldMetadata",
     "ExtractedFieldMetaDataDict",
+    "FieldCitation",
+    "BoundingBox",
+    "PageDimensions",
 ]

py/llama_cloud_services/beta/agent_data/schema.py

@@ -174,6 +174,22 @@ class TypedAgentDataItems(BaseModel, Generic[AgentDataT]):
     )
 
 
+class BoundingBox(BaseModel):
+    """Bounding box coordinates for a citation location on a page."""
+
+    x: float = Field(description="X coordinate of the bounding box origin")
+    y: float = Field(description="Y coordinate of the bounding box origin")
+    w: float = Field(description="Width of the bounding box")
+    h: float = Field(description="Height of the bounding box")
+
+
+class PageDimensions(BaseModel):
+    """Dimensions of a page in the source document."""
+
+    width: float = Field(description="Width of the page")
+    height: float = Field(description="Height of the page")
+
+
 class FieldCitation(BaseModel):
     page: Optional[int] = Field(
         None, description="The page number that the field occurred on"
@@ -182,6 +198,14 @@ class FieldCitation(BaseModel):
         None,
         description="The original text this field's value was derived from",
     )
+    bounding_boxes: Optional[List[BoundingBox]] = Field(
+        None,
+        description="Bounding boxes indicating where the citation appears on the page",
+    )
+    page_dimensions: Optional[PageDimensions] = Field(
+        None,
+        description="Dimensions of the page containing the citation",
+    )
 
 
 class ExtractedFieldMetadata(BaseModel):
@@ -201,6 +225,10 @@ class ExtractedFieldMetadata(BaseModel):
         None,
         description="The confidence score for the field based on the extracted text only",
     )
+    parsing_confidence: Optional[float] = Field(
+        None,
+        description="The confidence score for the field based on the parsing/OCR quality",
+    )
     citation: Optional[List[FieldCitation]] = Field(
         None,
         description="The citation for the field, including page number and matching text",
@@ -447,26 +475,49 @@ class ExtractedData(BaseModel, Generic[ExtractedT]):
                 },
             )
         except ValidationError as e:
+            # Capture the job-level error from the extraction run if available
+            job_error = result.error
+
             invalid_item = ExtractedData[Dict[str, Any]].create(
                 data=result.data or {},
                 status="error",
                 field_metadata=field_metadata,
-                metadata={"extraction_error": str(e), **(metadata or {})},
+                metadata={
+                    "extraction_error": str(e),
+                    **({"job_error": job_error} if job_error else {}),
+                    **(metadata or {}),
+                },
                 file_id=file_id,
                 file_name=file_name,
                 file_hash=file_hash,
             )
-            raise InvalidExtractionData(invalid_item) from e
+            raise InvalidExtractionData(invalid_item, extraction_error=job_error) from e
 
 
 class InvalidExtractionData(Exception):
     """
     Exception raised when the extracted data does not conform to the schema.
+
+    Attributes:
+        invalid_item: The ExtractedData instance containing the invalid data and metadata
+        extraction_error: The error message from the extraction job, if available
     """
 
-    def __init__(self, invalid_item: ExtractedData[Dict[str, Any]]):
+    def __init__(
+        self,
+        invalid_item: ExtractedData[Dict[str, Any]],
+        extraction_error: Optional[str] = None,
+    ):
         self.invalid_item = invalid_item
-        super().__init__("Not able to parse the extracted data, parsed invalid format")
+        self.extraction_error = extraction_error
+
+        # Build an informative error message
+        if extraction_error:
+            message = f"Extraction error: {extraction_error}"
+        else:
+            message = "Not able to parse the extracted data, parsed invalid format"
+
+        super().__init__(message)
 
 
 def calculate_overall_confidence(

py/llama_cloud_services/beta/classifier/__init__.py

@@ -1,8 +1,9 @@
-from llama_cloud_services.beta.classifier.client import ClassifyClient
+from llama_cloud_services.beta.classifier.client import LlamaClassify, ClassifyClient
 from llama_cloud_services.beta.classifier.types import ClassifyJobResultsWithFiles
 from llama_cloud_services.utils import SourceText, FileInput
 
 __all__ = [
+    "LlamaClassify",
     "ClassifyClient",
     "ClassifyJobResultsWithFiles",
     "SourceText",

py/llama_cloud_services/beta/classifier/client.py

@@ -31,7 +31,7 @@ class ClassificationOutput(BaseModel):
     classification: str
 
 
-class ClassifyClient:
+class LlamaClassify:
     """
     Experimental - Client for interacting with the LlamaCloud Classifier API.
     The Classification API is currently in beta and may change in the future without notice.
@@ -39,7 +39,6 @@ class ClassifyClient:
     Args:
         client: The LlamaCloud client to use.
         project_id: The project ID to use.
-        organization_id: The organization ID to use.
         polling_interval: The interval to poll for job completion in seconds.
         polling_timeout: The timeout for the job to complete in seconds.
     """
@@ -48,15 +47,13 @@ class ClassifyClient:
         self,
         client: AsyncLlamaCloud,
         project_id: Optional[str] = None,
-        organization_id: Optional[str] = None,
         polling_interval: float = 1.0,
         polling_timeout: float = POLLING_TIMEOUT_SECONDS,
     ):
         self.client = client
         self.project_id = project_id
-        self.organization_id = organization_id
         self.polling_interval = polling_interval
-        self.file_client = FileClient(client, project_id, organization_id)
+        self.file_client = FileClient(client, project_id)
         self.polling_timeout = polling_timeout
 
     @classmethod
@@ -64,7 +61,6 @@ class ClassifyClient:
         cls,
         api_key: str,
         project_id: Optional[str] = None,
-        organization_id: Optional[str] = None,
         base_url: Optional[str] = None,
     ) -> "ClassifyClient":
         """
@@ -74,7 +70,6 @@ class ClassifyClient:
         return cls(
             client,
             project_id,
-            organization_id,
         )
 
     async def acreate_classify_job(
@@ -101,7 +96,6 @@ class ClassifyClient:
             file_ids=file_ids,
             parsing_configuration=parsing_configuration or OMIT,
             project_id=self.project_id,
-            organization_id=self.organization_id,
         )
 
     def create_classify_job(
@@ -152,7 +146,6 @@ class ClassifyClient:
         results = await self.client.classifier.get_classification_job_results(
             classify_job_with_status.id,
             project_id=self.project_id,
-            organization_id=self.organization_id,
         )
 
         return results
@@ -359,7 +352,7 @@ class ClassifyClient:
             The classify job with status.
         """
         job = await self.client.classifier.get_classify_job(
-            job_id, project_id=self.project_id, organization_id=self.organization_id
+            job_id, project_id=self.project_id
         )
         start_time = time.time()
         while not is_terminal_status(job.status):
@@ -370,6 +363,9 @@ class ClassifyClient:
                 )
             await asyncio.sleep(self.polling_interval)
             job = await self.client.classifier.get_classify_job(
-                job_id, project_id=self.project_id, organization_id=self.organization_id
+                job_id, project_id=self.project_id
             )
         return job
+
+
+ClassifyClient = LlamaClassify

py/llama_cloud_services/beta/sheets/__init__.py

@@ -0,0 +1,43 @@
+"""LlamaCloud Spreadsheet API SDK
+
+This module provides a Python SDK for the LlamaCloud Spreadsheet API.
+"""
+
+from llama_cloud_services.beta.sheets.client import (
+    LlamaSheets,
+    SpreadsheetAPIError,
+    SpreadsheetJobError,
+    SpreadsheetTimeoutError,
+)
+from llama_cloud_services.beta.sheets.types import (
+    ExtractedRegionSummary,
+    FileUploadResponse,
+    JobStatus,
+    PresignedUrlResponse,
+    SpreadsheetJob,
+    SpreadsheetJobResult,
+    SpreadsheetParseResult,
+    SpreadsheetParsingConfig,
+    SpreadsheetResultType,
+    WorksheetMetadata,
+)
+
+__all__ = [
+    # Client
+    "LlamaSheets",
+    # Exceptions
+    "SpreadsheetAPIError",
+    "SpreadsheetJobError",
+    "SpreadsheetTimeoutError",
+    # Types
+    "ExtractedRegionSummary",
+    "FileUploadResponse",
+    "JobStatus",
+    "PresignedUrlResponse",
+    "SpreadsheetJob",
+    "SpreadsheetJobResult",
+    "SpreadsheetParseResult",
+    "SpreadsheetParsingConfig",
+    "SpreadsheetResultType",
+    "WorksheetMetadata",
+]

py/llama_cloud_services/beta/sheets/client.py

@@ -0,0 +1,550 @@
+import asyncio
+import io
+import os
+import time
+from typing import Any, Dict, TYPE_CHECKING
+
+import httpx
+from llama_cloud.client import AsyncLlamaCloud
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from llama_cloud_services.beta.sheets.types import (
+    FileUploadResponse,
+    JobStatus,
+    PresignedUrlResponse,
+    SpreadsheetJob,
+    SpreadsheetJobResult,
+    SpreadsheetParsingConfig,
+    SpreadsheetResultType,
+)
+from llama_cloud_services.constants import BASE_URL
+from llama_cloud_services.files.client import FileClient
+from llama_cloud_services.utils import (
+    augment_async_errors,
+    FileInput,
+)
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def _should_retry_exception(exception: BaseException) -> bool:
+    """Determine if an exception should be retried."""
+    if isinstance(exception, httpx.HTTPStatusError):
+        return exception.response.status_code in (429, 500, 502, 503, 504)
+    return False
+
+
+class SpreadsheetAPIError(Exception):
+    """Base exception for spreadsheet API errors"""
+
+    pass
+
+
+class SpreadsheetJobError(SpreadsheetAPIError):
+    """Exception raised when a spreadsheet job fails"""
+
+    pass
+
+
+class SpreadsheetTimeoutError(SpreadsheetAPIError):
+    """Exception raised when a job times out"""
+
+    pass
+
+
+class LlamaSheets:
+    """Client for the LlamaCloud Spreadsheet API"""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_timeout: int = 300,
+        poll_interval: int = 5,
+        max_retries: int = 3,
+        project_id: str | None = None,
+        organization_id: str | None = None,
+        async_httpx_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Initialize the LlamaSheets client.
+
+        Args:
+            api_key: API key for authentication. If not provided, will use LLAMA_CLOUD_API_KEY env var
+            base_url: Base URL for the API
+            max_timeout: Maximum time to wait for job completion in seconds
+            poll_interval: Interval between status checks in seconds
+            max_retries: Maximum number of retries for failed requests
+            project_id: Project ID for file operations. If not provided, will use LLAMA_CLOUD_PROJECT_ID env var
+            organization_id: Organization ID for file operations. If not provided, will use LLAMA_CLOUD_ORGANIZATION_ID env var
+            async_httpx_client: Optional custom async httpx client
+        """
+        self.api_key = api_key or os.environ.get("LLAMA_CLOUD_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "An API key must be provided either as an argument or via the LLAMA_CLOUD_API_KEY environment variable."
+            )
+
+        base_url = base_url or os.environ.get("LLAMA_CLOUD_BASE_URL", BASE_URL)
+        self.base_url = str(base_url).rstrip("/")
+
+        self.max_timeout = max_timeout
+        self.poll_interval = poll_interval
+        self.max_retries = max_retries
+
+        self.project_id = project_id or os.environ.get("LLAMA_CLOUD_PROJECT_ID")
+        self.organization_id = organization_id or os.environ.get(
+            "LLAMA_CLOUD_ORGANIZATION_ID"
+        )
+
+        self._async_client: httpx.AsyncClient | None = async_httpx_client
+        self._files_client = FileClient(
+            AsyncLlamaCloud(
+                token=self.api_key,
+                base_url=self.base_url,
+                httpx_client=async_httpx_client,
+            ),
+            project_id=self.project_id,
+            organization_id=self.organization_id,
+        )
+
+    def _get_default_params(self) -> dict[str, str]:
+        """Get default query parameters for API requests"""
+        params = {}
+        if self.project_id is not None:
+            params["project_id"] = self.project_id
+        if self.organization_id is not None:
+            params["organization_id"] = self.organization_id
+
+        return params
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        """Get or create the async httpx client"""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                timeout=httpx.Timeout(60.0),
+                follow_redirects=True,
+            )
+        return self._async_client
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get common headers for API requests"""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    # Sync methods
+
+    def upload_file(
+        self, file_obj: FileInput, file_name: str | None = None
+    ) -> FileUploadResponse:
+        """Upload a file to the Files API.
+
+        Args:
+            file_obj: File to upload (path, bytes, or file-like object)
+            file_name: Optional name for the uploaded filename
+
+        Returns:
+            FileUploadResponse with the uploaded file ID
+        """
+        with augment_async_errors():
+            return asyncio.run(self.aupload_file(file_obj))
+
+    def create_job(
+        self,
+        file_id: str,
+        config: dict | SpreadsheetParsingConfig | None = None,
+    ) -> SpreadsheetJob:
+        """Create a new spreadsheet parsing job.
+
+        Args:
+            file_id: ID of the uploaded file
+            config: Parsing configuration
+
+        Returns:
+            SpreadsheetJob with job details
+        """
+        with augment_async_errors():
+            return asyncio.run(self.acreate_job(file_id, config))
+
+    def get_job(
+        self, job_id: str, include_results_metadata: bool = True
+    ) -> SpreadsheetJobResult:
+        """Get the status of a spreadsheet parsing job.
+
+        Args:
+            job_id: ID of the job
+            include_results_metadata: Whether to include results metadata in the response
+
+        Returns:
+            SpreadsheetJobResult with job status and optionally results
+        """
+        with augment_async_errors():
+            return asyncio.run(self.aget_job(job_id, include_results_metadata))
+
+    def wait_for_completion(self, job_id: str) -> SpreadsheetJobResult:
+        """Wait for a job to complete by polling.
+
+        Args:
+            job_id: ID of the job to wait for
+
+        Returns:
+            SpreadsheetJobResult when job is complete
+
+        Raises:
+            SpreadsheetTimeoutError: If job doesn't complete within max_timeout
+            SpreadsheetJobError: If job fails
+        """
+        with augment_async_errors():
+            return asyncio.run(self.await_for_completion(job_id))
+
+    def download_region_result(
+        self,
+        job_id: str,
+        region_id: str,
+        result_type: SpreadsheetResultType = SpreadsheetResultType.TABLE,
+    ) -> bytes:
+        """Download a region result (either region data or cell metadata).
+
+        Args:
+            job_id: ID of the job
+            region_id: ID of the region
+            result_type: Type of result to download (region or cell_metadata)
+
+        Returns:
+            Raw bytes of the parquet file
+        """
+        with augment_async_errors():
+            return asyncio.run(
+                self.adownload_region_result(job_id, region_id, result_type)
+            )
+
+    def download_region_as_dataframe(
+        self,
+        job_id: str,
+        region_id: str,
+        result_type: SpreadsheetResultType = SpreadsheetResultType.TABLE,
+    ) -> "pd.DataFrame":
+        """Download a region result as a pandas DataFrame.
+
+        Args:
+            job_id: ID of the job
+            region_id: ID of the region
+            result_type: Type of result to download (region or cell_metadata)
+
+        Returns:
+            pandas DataFrame
+        """
+        with augment_async_errors():
+            return asyncio.run(
+                self.adownload_region_as_dataframe(job_id, region_id, result_type)
+            )
+
+    def extract_regions(
+        self,
+        file_obj: FileInput,
+        config: dict | SpreadsheetParsingConfig | None = None,
+    ) -> SpreadsheetJobResult:
+        """High-level method to parse a spreadsheet file.
+
+        This method handles the entire workflow:
+        1. Upload the file
+        2. Create a parsing job
+        3. Wait for completion
+        4. Return results
+
+        Args:
+            file_obj: File to parse (path, bytes, or file-like object)
+            config: Parsing configuration
+
+        Returns:
+            SpreadsheetJobResult with parsing results
+        """
+        with augment_async_errors():
+            return asyncio.run(self.aextract_regions(file_obj, config))
+
+    # Async methods
+
+    async def aupload_file(
+        self, file_obj: FileInput, file_name: str | None = None
+    ) -> FileUploadResponse:
+        """Upload a file to the Files API.
+
+        Args:
+            file_obj: File to upload (path, bytes, or file-like object)
+            file_name: Optional name for the uploaded filename
+
+        Returns:
+            FileUploadResponse with the uploaded file ID
+        """
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self.max_retries),
+                wait=wait_exponential(multiplier=1, min=1, max=32),
+                retry=retry_if_exception(_should_retry_exception),
+                reraise=True,
+            ):
+                with attempt:
+                    return await self._files_client.upload_content(
+                        file_obj, external_file_id=file_name
+                    )
+        except Exception as e:
+            raise SpreadsheetAPIError(f"Failed to upload file: {e}") from e
+        raise RuntimeError("Tenacity did not execute")
+
+    async def acreate_job(
+        self,
+        file_id: str,
+        config: dict | SpreadsheetParsingConfig | None = None,
+    ) -> SpreadsheetJob:
+        """Create a new spreadsheet parsing job.
+
+        Args:
+            file_id: ID of the uploaded file
+            config: Parsing configuration
+
+        Returns:
+            SpreadsheetJob with job details
+        """
+        if config is None:
+            config = SpreadsheetParsingConfig()
+        elif isinstance(config, dict):
+            config = SpreadsheetParsingConfig.model_validate(config)
+
+        if not isinstance(config, SpreadsheetParsingConfig):
+            raise ValueError(
+                "config must be a dict or SpreadsheetParsingConfig instance"
+            )
+
+        payload = {
+            "file_id": file_id,
+            "config": config.model_dump(mode="json", exclude_none=True),
+        }
+
+        params = self._get_default_params()
+
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self.max_retries),
+                wait=wait_exponential(multiplier=1, min=1, max=32),
+                retry=retry_if_exception(_should_retry_exception),
+                reraise=True,
+            ):
+                with attempt:
+                    client = self._get_async_client()
+                    response = await client.post(
+                        f"{self.base_url}/api/v1/beta/sheets/jobs",
+                        headers=self._get_headers(),
+                        params=params,
+                        json=payload,
+                    )
+                    response.raise_for_status()
+                    return SpreadsheetJob.model_validate(response.json())
+        except Exception as e:
+            raise SpreadsheetAPIError(f"Failed to create job: {e}") from e
+        raise RuntimeError("Tenacity did not execute")
+
+    async def aget_job(
+        self, job_id: str, include_results_metadata: bool = True
+    ) -> SpreadsheetJobResult:
+        """Get the status of a spreadsheet parsing job.
+
+        Args:
+            job_id: ID of the job
+            include_results_metadata: Whether to include results in the response
+
+        Returns:
+            SpreadsheetJobResult with job status and optionally results
+        """
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self.max_retries),
+                wait=wait_exponential(multiplier=1, min=1, max=32),
+                retry=retry_if_exception(_should_retry_exception),
+                reraise=True,
+            ):
+                with attempt:
+                    client = self._get_async_client()
+                    params: Dict[str, Any] = {
+                        "include_results": include_results_metadata,
+                        **self._get_default_params(),
+                    }
+                    response = await client.get(
+                        f"{self.base_url}/api/v1/beta/sheets/jobs/{job_id}",
+                        headers=self._get_headers(),
+                        params=params,
+                    )
+                    response.raise_for_status()
+
+                    return SpreadsheetJobResult.model_validate(response.json())
+        except Exception as e:
+            raise SpreadsheetAPIError(f"Failed to get job status: {e}") from e
+        raise RuntimeError("Tenacity did not execute")
+
+    async def await_for_completion(self, job_id: str) -> SpreadsheetJobResult:
+        """Wait for a job to complete by polling.
+
+        Args:
+            job_id: ID of the job to wait for
+
+        Returns:
+            SpreadsheetJobResult when job is complete
+
+        Raises:
+            SpreadsheetTimeoutError: If job doesn't complete within max_timeout
+            SpreadsheetJobError: If job fails
+        """
+        start_time = time.time()
+
+        while (time.time() - start_time) < self.max_timeout:
+            job_result = await self.aget_job(job_id, include_results_metadata=True)
+
+            if job_result.status in (
+                JobStatus.SUCCESS,
+                JobStatus.PARTIAL_SUCCESS,
+                JobStatus.ERROR,
+                JobStatus.FAILURE,
+            ):
+                if job_result.status in (JobStatus.SUCCESS, JobStatus.PARTIAL_SUCCESS):
+                    return job_result
+                else:
+                    error_msg = f"Job failed with status: {job_result.status}"
+                    if job_result.errors:
+                        error_msg += f"\nErrors: {', '.join(job_result.errors)}"
+                    raise SpreadsheetJobError(error_msg)
+
+            await asyncio.sleep(self.poll_interval)
+
+        raise SpreadsheetTimeoutError(
+            f"Job did not complete within {self.max_timeout} seconds"
+        )
+
+    async def adownload_region_result(
+        self,
+        job_id: str,
+        region_id: str,
+        result_type: SpreadsheetResultType = SpreadsheetResultType.TABLE,
+    ) -> bytes:
+        """Download a region result (either region data or cell metadata).
+
+        Args:
+            job_id: ID of the job
+            region_id: ID of the region
+            result_type: Type of result to download (region or cell_metadata)
+
+        Returns:
+            Raw bytes of the parquet file
+        """
+        # Get presigned URL
+        presigned_response = None
+        result_type_str = str(result_type)
+        params = self._get_default_params()
+
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self.max_retries),
+                wait=wait_exponential(multiplier=1, min=1, max=32),
+                retry=retry_if_exception(_should_retry_exception),
+                reraise=True,
+            ):
+                with attempt:
+                    client = self._get_async_client()
+                    response = await client.get(
+                        f"{self.base_url}/api/v1/beta/sheets/jobs/{job_id}/regions/{region_id}/result/{result_type_str}",
+                        headers=self._get_headers(),
+                        params=params,
+                    )
+                    response.raise_for_status()
+                    presigned_response = PresignedUrlResponse.model_validate(
+                        response.json()
+                    )
+        except Exception as e:
+            raise SpreadsheetAPIError(f"Failed to get presigned URL: {e}") from e
+
+        # Download using presigned URL
+        if presigned_response is None:
+            raise SpreadsheetAPIError("Failed to obtain presigned URL.")
+
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self.max_retries),
+                wait=wait_exponential(multiplier=1, min=1, max=32),
+                retry=retry_if_exception(_should_retry_exception),
+                reraise=True,
+            ):
+                with attempt:
+                    download_response = await client.get(presigned_response.url)
+                    download_response.raise_for_status()
+                    return download_response.content
+        except Exception as e:
+            raise SpreadsheetAPIError(f"Failed to download result: {e}") from e
+        raise RuntimeError("Tenacity did not execute")
+
+    async def adownload_region_as_dataframe(
+        self,
+        job_id: str,
+        region_id: str,
+        result_type: SpreadsheetResultType = SpreadsheetResultType.TABLE,
+    ) -> "pd.DataFrame":
+        """Download a region result as a pandas DataFrame.
+
+        Args:
+            job_id: ID of the job
+            region_id: ID of the region
+            result_type: Type of result to download (region or cell_metadata)
+
+        Returns:
+            pandas DataFrame
+        """
+        import pandas as pd
+
+        parquet_bytes = await self.adownload_region_result(
+            job_id, region_id, result_type
+        )
+        return pd.read_parquet(io.BytesIO(parquet_bytes))
+
+    async def aextract_regions(
+        self,
+        file_obj: FileInput,
+        config: dict | SpreadsheetParsingConfig | None = None,
+    ) -> SpreadsheetJobResult:
+        """High-level method to parse a spreadsheet file.
+
+        This method handles the entire workflow:
+        1. Upload the file
+        2. Create a parsing job
+        3. Wait for completion
+        4. Return results
+
+        Args:
+            file_obj: File to parse (path, bytes, or file-like object)
+            config: Parsing configuration
+
+        Returns:
+            SpreadsheetJobResult with parsing results
+        """
+        # Upload file
+        file_response = await self.aupload_file(file_obj)
+
+        # Create job
+        job = await self.acreate_job(file_response.id, config)
+
+        # Wait for completion
+        return await self.await_for_completion(job.id)
+
+    async def aclose(self) -> None:
+        """Close all HTTP clients (async)"""
+        if self._async_client:
+            await self._async_client.aclose()
+
+    async def __aenter__(self) -> "LlamaSheets":
+        return self
+
+    async def __aexit__(self, _exc_type, _exc_val, _exc_tb) -> None:  # type: ignore
+        await self.aclose()

py/llama_cloud_services/beta/sheets/types.py

@@ -0,0 +1,167 @@
+from datetime import datetime
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class SpreadsheetResultType(str, Enum):
+    TABLE = "table"
+    EXTRA = "extra"
+    CELL_METADATA = "cell_metadata"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class ExtractedRegionSummary(BaseModel):
+    """A summary of a single extracted region from a spreadsheet"""
+
+    region_id: str = Field(
+        ...,
+        description="Unique identifier for this region within the file",
+    )
+    sheet_name: str = Field(..., description="Worksheet name where region was found")
+    location: str = Field(..., description="Location of the region in the spreadsheet")
+    title: str | None = Field(None, description="Generated title for the region")
+    description: str | None = Field(
+        None, description="Generated description of the region"
+    )
+    region_type: SpreadsheetResultType = Field(
+        ..., description="Type of the extracted region"
+    )
+
+
+class WorksheetMetadata(BaseModel):
+    """Metadata about a worksheet in a spreadsheet"""
+
+    sheet_name: str = Field(..., description="Name of the worksheet")
+    title: str | None = Field(None, description="Generated title for the worksheet")
+    description: str | None = Field(
+        None, description="Generated description of the worksheet"
+    )
+
+
+class SpreadsheetParseResult(BaseModel):
+    """Result of parsing a single spreadsheet file"""
+
+    success: bool = Field(..., description="Whether parsing was successful")
+    file_name: str = Field(..., description="Original filename")
+
+    regions: list[ExtractedRegionSummary] = Field(
+        default_factory=list, description="All successfully extracted regions"
+    )
+    worksheet_metadata: list[WorksheetMetadata] = Field(
+        default_factory=list, description="Metadata for each processed worksheet"
+    )
+
+    # Error information
+    errors: list[str] = Field(
+        default_factory=list, description="Any errors encountered during parsing"
+    )
+
+
+class SpreadsheetParsingConfig(BaseModel):
+    """Configuration for spreadsheet parsing and region extraction"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    sheet_names: list[str] | None = Field(
+        default=None,
+        description="The names of the sheets to extract regions from. If empty, the default sheet is extracted.",
+    )
+    include_hidden_cells: bool = Field(
+        default=True,
+        description="Whether to include hidden cells when extracting regions from the spreadsheet.",
+    )
+    extraction_range: str | None = Field(
+        default=None,
+        description="A1 notation of the range to extract a single region from. If None, the entire sheet is used.",
+    )
+    generate_additional_metadata: bool = Field(
+        default=True,
+        description="Whether to generate additional metadata (title, description) for each extracted region.",
+    )
+    use_experimental_processing: bool = Field(
+        default=False,
+        description="Enables experimental processing. Accuracy may be impacted.",
+    )
+
+    flatten_hierarchical_tables: bool = Field(
+        default=False,
+        description="Return a flattened dataframe when a detected table is recognized as hierarchical.",
+    )
+
+    table_merge_sensitivity: Literal["strong", "weak"] = Field(
+        default="strong",
+        description="Influences how likely similar-looking regions are merged into a single table. Useful for spreadsheets that either have sparse tables (strong merging) or many distinct tables close together (weak merging).",
+    )
+
+
+class SpreadsheetJob(BaseModel):
+    """A spreadsheet parsing job"""
+
+    id: str = Field(..., description="The ID of the job")
+    user_id: str = Field(..., description="The ID of the user")
+    project_id: str = Field(..., description="The ID of the project")
+    file: dict = Field(..., description="The file object being parsed")
+    config: SpreadsheetParsingConfig = Field(
+        ..., description="Configuration for the parsing job"
+    )
+    status: str = Field(..., description="The status of the parsing job")
+    created_at: str = Field(..., description="When the job was created")
+    updated_at: str = Field(..., description="When the job was last updated")
+
+    @field_validator("created_at", "updated_at", mode="before")
+    def validate_dates(cls, v: str) -> str:
+        """Validate that the dates are in the correct format"""
+        if isinstance(v, datetime):
+            return v.isoformat()
+        else:
+            return v
+
+
+class SpreadsheetJobResult(SpreadsheetJob):
+    """A spreadsheet parsing job result."""
+
+    # Results are included when the job is complete
+    success: bool | None = Field(
+        None, description="Whether the job completed successfully"
+    )
+    regions: list[ExtractedRegionSummary] = Field(
+        default_factory=list,
+        description="All extracted regions (populated when job is complete)",
+    )
+    worksheet_metadata: list[WorksheetMetadata] = Field(
+        default_factory=list,
+        description="Metadata for each processed worksheet (populated when job is complete)",
+    )
+    errors: list[str] = Field(
+        default_factory=list, description="Any errors encountered"
+    )
+
+
+class JobStatus(str, Enum):
+    """Status of a spreadsheet parsing job"""
+
+    PENDING = "PENDING"
+    IN_PROGRESS = "IN_PROGRESS"
+    SUCCESS = "SUCCESS"
+    PARTIAL_SUCCESS = "PARTIAL_SUCCESS"
+    ERROR = "ERROR"
+    FAILURE = "FAILURE"
+
+
+class PresignedUrlResponse(BaseModel):
+    """Response containing a presigned URL for downloading results"""
+
+    url: str = Field(..., description="The presigned URL for downloading")
+
+
+class FileUploadResponse(BaseModel):
+    """Response from uploading a file"""
+
+    id: str = Field(..., description="The ID of the uploaded file")
+    name: str = Field(..., description="The name of the file")
+    project_id: str = Field(..., description="The project ID")
+    user_id: str = Field(..., description="The user ID")

py/llama_cloud_services/constants.py

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

py/llama_cloud_services/extract/extract.py

@@ -4,10 +4,11 @@ import os
 import time
 from io import BufferedIOBase, TextIOWrapper
 from pathlib import Path
-from typing import List, Optional, Type, Union, Coroutine, Any, TypeVar
+from typing import Callable, List, Optional, Type, Union, Coroutine, Any, TypeVar
 import warnings
 import httpx
 from pydantic import BaseModel
+from functools import wraps
 from tenacity import (
     retry_if_exception,
     stop_after_attempt,
@@ -54,7 +55,7 @@ DEFAULT_EXTRACT_CONFIG = ExtractConfig(
 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)
+        return exception.status_code in (429, 500, 502, 503, 504, 425, 408)
     elif isinstance(
         exception, (httpx.HTTPStatusError, httpx.RequestError, httpx.TimeoutException)
     ):
@@ -62,6 +63,33 @@ def _is_retryable_error(exception: BaseException) -> bool:
     return False
 
 
+def _async_retry(
+    max_attempts: int = 5,
+    initial_wait: float = 1,
+    max_wait: float = 30,
+    jitter: float = 3,
+) -> Callable:
+    """Decorator for async functions with retry logic for rate limiting and transient errors."""
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            async for attempt in AsyncRetrying(
+                retry=retry_if_exception(_is_retryable_error),
+                stop=stop_after_attempt(max_attempts),
+                wait=wait_exponential_jitter(
+                    initial=initial_wait, max=max_wait, jitter=jitter
+                ),
+                reraise=True,
+            ):
+                with attempt:
+                    return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 async def _validate_schema(
     client: AsyncLlamaCloud, data_schema: SchemaInput
 ) -> JSONObjectType:
@@ -82,50 +110,6 @@ async def _validate_schema(
     return validated_schema.data_schema
 
 
-async def _get_job_with_retry(
-    client: AsyncLlamaCloud,
-    job_id: str,
-    max_attempts: int = 5,
-    initial_wait: float = 1,
-    max_wait: float = 60,
-    jitter: float = 5,
-) -> ExtractJob:
-    """Get extraction job with retry logic."""
-    async for attempt in AsyncRetrying(
-        retry=retry_if_exception(_is_retryable_error),
-        stop=stop_after_attempt(max_attempts),
-        wait=wait_exponential_jitter(initial=initial_wait, max=max_wait, jitter=jitter),
-        reraise=True,
-    ):
-        with attempt:
-            return await client.llama_extract.get_job(job_id=job_id)
-
-
-async def _get_run_with_retry(
-    client: AsyncLlamaCloud,
-    job_id: str,
-    project_id: Optional[str] = None,
-    organization_id: Optional[str] = None,
-    max_attempts: int = 3,
-    initial_wait: float = 1,
-    max_wait: float = 20,
-    jitter: float = 3,
-) -> ExtractRun:
-    """Get extraction run with retry logic."""
-    async for attempt in AsyncRetrying(
-        retry=retry_if_exception(_is_retryable_error),
-        stop=stop_after_attempt(max_attempts),
-        wait=wait_exponential_jitter(initial=initial_wait, max=max_wait, jitter=jitter),
-        reraise=True,
-    ):
-        with attempt:
-            return await client.llama_extract.get_run_by_job_id(
-                job_id=job_id,
-                project_id=project_id,
-                organization_id=organization_id,
-            )
-
-
 async def _wait_for_job_result(
     client: AsyncLlamaCloud,
     job_id: str,
@@ -142,30 +126,33 @@ async def _wait_for_job_result(
     run_jitter: float = 3,
 ) -> Optional[ExtractRun]:
     """Wait for and return the results of an extraction job."""
+
+    @_async_retry(
+        max_attempts=job_retry_attempts, max_wait=job_max_wait, jitter=job_jitter
+    )
+    async def _get_job() -> ExtractJob:
+        return await client.llama_extract.get_job(job_id=job_id)
+
+    @_async_retry(
+        max_attempts=run_retry_attempts, max_wait=run_max_wait, jitter=run_jitter
+    )
+    async def _get_run() -> ExtractRun:
+        return await client.llama_extract.get_run_by_job_id(
+            job_id=job_id,
+            project_id=project_id,
+            organization_id=organization_id,
+        )
+
     start = time.perf_counter()
     poll_count = 0
 
     while True:
         await asyncio.sleep(check_interval)
         poll_count += 1
-        job = await _get_job_with_retry(
-            client,
-            job_id,
-            max_attempts=job_retry_attempts,
-            max_wait=job_max_wait,
-            jitter=job_jitter,
-        )
+        job = await _get_job()
 
         if job.status == StatusEnum.SUCCESS:
-            return await _get_run_with_retry(
-                client,
-                job_id,
-                project_id,
-                organization_id,
-                max_attempts=run_retry_attempts,
-                max_wait=run_max_wait,
-                jitter=run_jitter,
-            )
+            return await _get_run()
         elif job.status == StatusEnum.PENDING:
             end = time.perf_counter()
             if end - start > max_timeout:
@@ -177,15 +164,7 @@ async def _wait_for_job_result(
             warnings.warn(
                 f"Failure in job: {job_id}, status: {job.status}, error: {job.error}"
             )
-            return await _get_run_with_retry(
-                client,
-                job_id,
-                project_id,
-                organization_id,
-                max_attempts=run_retry_attempts,
-                max_wait=run_max_wait,
-                jitter=run_jitter,
-            )
+            return await _get_run()
 
 
 def run_in_thread(
@@ -240,11 +219,6 @@ def _extraction_config_warning(config: ExtractConfig) -> None:
             raise ValueError(
                 "`cite_sources` is only supported with MULTIMODAL or PREMIUM extraction modes."
             )
-    if config.confidence_scores:
-        if config.extraction_mode in (ExtractMode.FAST, ExtractMode.BALANCED):
-            raise ValueError(
-                "`confidence_scores` is only supported with MULTIMODAL or PREMIUM extraction modes."
-            )
 
 
 class ExtractionAgent:
@@ -503,9 +477,12 @@ class ExtractionAgent:
         Args:
             run_id (str): The ID of the extraction run to delete
         """
-        self._run_in_thread(
-            self._client.llama_extract.delete_extraction_run(run_id=run_id)
-        )
+
+        @_async_retry()
+        async def _delete() -> None:
+            return await self._client.llama_extract.delete_extraction_run(run_id=run_id)
+
+        self._run_in_thread(_delete())
 
     def list_extraction_runs(
         self, page: int = 0, limit: int = 100
@@ -515,13 +492,16 @@ class ExtractionAgent:
         Returns:
             PaginatedExtractRunsResponse: Paginated list of extraction runs
         """
-        return self._run_in_thread(
-            self._client.llama_extract.list_extract_runs(
+
+        @_async_retry()
+        async def _list() -> PaginatedExtractRunsResponse:
+            return await self._client.llama_extract.list_extract_runs(
                 extraction_agent_id=self.id,
                 skip=page * limit,
                 limit=limit,
             )
-        )
+
+        return self._run_in_thread(_list())
 
     def __repr__(self) -> str:
         return f"ExtractionAgent(id={self.id}, name={self.name})"
@@ -663,15 +643,17 @@ class LlamaExtract(BaseComponent):
                 "data_schema must be either a dictionary or a Pydantic model"
             )
 
-        agent = self._run_in_thread(
-            self._async_client.llama_extract.create_extraction_agent(
+        @_async_retry()
+        async def _create() -> CloudExtractAgent:
+            return await self._async_client.llama_extract.create_extraction_agent(
                 project_id=self._project_id,
                 organization_id=self._organization_id,
                 name=name,
                 data_schema=data_schema,
                 config=config,
             )
-        )
+
+        agent = self._run_in_thread(_create())
 
         return ExtractionAgent(
             client=self._async_client,
@@ -707,19 +689,27 @@ class LlamaExtract(BaseComponent):
             )
 
         if id:
-            agent = self._run_in_thread(
-                self._async_client.llama_extract.get_extraction_agent(
+
+            @_async_retry()
+            async def _get_by_id() -> CloudExtractAgent:
+                return await self._async_client.llama_extract.get_extraction_agent(
                     extraction_agent_id=id,
                 )
-            )
+
+            agent = self._run_in_thread(_get_by_id())
 
         elif name:
-            agent = self._run_in_thread(
-                self._async_client.llama_extract.get_extraction_agent_by_name(
-                    name=name,
-                    project_id=self._project_id,
+
+            @_async_retry()
+            async def _get_by_name() -> CloudExtractAgent:
+                return (
+                    await self._async_client.llama_extract.get_extraction_agent_by_name(
+                        name=name,
+                        project_id=self._project_id,
+                    )
                 )
-            )
+
+            agent = self._run_in_thread(_get_by_name())
         else:
             raise ValueError("Either name or extraction_agent_id must be provided.")
 
@@ -739,11 +729,14 @@ class LlamaExtract(BaseComponent):
 
     def list_agents(self) -> List[ExtractionAgent]:
         """List all available extraction agents."""
-        agents = self._run_in_thread(
-            self._async_client.llama_extract.list_extraction_agents(
+
+        @_async_retry()
+        async def _list() -> List[CloudExtractAgent]:
+            return await self._async_client.llama_extract.list_extraction_agents(
                 project_id=self._project_id,
             )
-        )
+
+        agents = self._run_in_thread(_list())
 
         return [
             ExtractionAgent(
@@ -768,11 +761,14 @@ class LlamaExtract(BaseComponent):
         Args:
             agent_id (str): ID of the extraction agent to delete
         """
-        self._run_in_thread(
-            self._async_client.llama_extract.delete_extraction_agent(
-                extraction_agent_id=agent_id
+
+        @_async_retry()
+        async def _delete() -> None:
+            return await self._async_client.llama_extract.delete_extraction_agent(
+                extraction_agent_id=agent_id,
             )
-        )
+
+        self._run_in_thread(_delete())
 
     async def _wait_for_job_result(self, job_id: str) -> Optional[ExtractRun]:
         """Wait for and return the results of an extraction job."""
@@ -810,6 +806,7 @@ class LlamaExtract(BaseComponent):
             # Document files
             ".pdf": "application/pdf",
             ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             # Image files
             ".png": "image/png",
             ".jpg": "image/jpeg",

py/llama_cloud_services/files/client.py

@@ -3,7 +3,7 @@ from typing import BinaryIO
 import os
 from pathlib import Path
 from llama_cloud.client import AsyncLlamaCloud
-from llama_cloud.types import File, FileCreate
+from llama_cloud.types import File
 from typing import Optional
 from llama_cloud_services.utils import SourceText, FileInput
 
@@ -11,7 +11,7 @@ from llama_cloud_services.utils import SourceText, FileInput
 class FileClient:
     """
     Higher-level client for interacting with the LlamaCloud Files API.
-    Uses presigned URLs for uploads by default.
+    Optionally uses presigned URLs for uploads.
 
     Args:
         client: The LlamaCloud client to use.
@@ -25,7 +25,7 @@ class FileClient:
         client: AsyncLlamaCloud,
         project_id: Optional[str] = None,
         organization_id: Optional[str] = None,
-        use_presigned_url: bool = True,
+        use_presigned_url: bool = False,
     ):
         self.client = client
         self.project_id = project_id
@@ -73,11 +73,9 @@ class FileClient:
             presigned_url = await self.client.files.generate_presigned_url(
                 project_id=self.project_id,
                 organization_id=self.organization_id,
-                request=FileCreate(
-                    name=name,
-                    external_file_id=external_file_id,
-                    file_size=file_size,
-                ),
+                name=name,
+                external_file_id=external_file_id,
+                file_size=file_size,
             )
             httpx_client = self.client._client_wrapper.httpx_client
             upload_response = await httpx_client.put(
@@ -91,6 +89,10 @@ class FileClient:
                 organization_id=self.organization_id,
             )
         else:
+            # Set buffer.name if not already set, so the upload uses external_file_id
+            # for file type detection
+            if not getattr(buffer, "name", None):
+                setattr(buffer, "name", external_file_id)
             return await self.client.files.upload_file(
                 upload_file=buffer,
                 external_file_id=external_file_id,

py/llama_cloud_services/index/api_utils.py

@@ -258,6 +258,7 @@ def page_screenshot_nodes_to_node_with_score(
     client: LlamaCloud,
     raw_image_nodes: Optional[List[PageScreenshotNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     if not raw_image_nodes:
         return []
@@ -273,6 +274,7 @@ def page_screenshot_nodes_to_node_with_score(
         image_base64 = base64.b64encode(image_bytes).decode("utf-8")
         image_node_metadata: Dict[str, Any] = {
             **(raw_image_node.node.metadata or {}),
+            **(metadata or {}),
             "file_id": raw_image_node.node.file_id,
             "page_index": raw_image_node.node.page_index,
         }
@@ -289,6 +291,7 @@ def image_nodes_to_node_with_score(
     client: LlamaCloud,
     raw_image_nodes: Optional[List[PageScreenshotNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     """
     Legacy method to alias page_screenshot_nodes_to_node_with_score.
@@ -297,7 +300,10 @@ def image_nodes_to_node_with_score(
         return []
 
     return page_screenshot_nodes_to_node_with_score(
-        client=client, raw_image_nodes=raw_image_nodes, project_id=project_id
+        client=client,
+        raw_image_nodes=raw_image_nodes,
+        project_id=project_id,
+        metadata=metadata,
     )
 
 
@@ -305,6 +311,7 @@ def page_figure_nodes_to_node_with_score(
     client: LlamaCloud,
     raw_figure_nodes: Optional[List[PageFigureNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     if not raw_figure_nodes:
         return []
@@ -321,6 +328,7 @@ def page_figure_nodes_to_node_with_score(
         figure_base64 = base64.b64encode(figure_bytes).decode("utf-8")
         figure_node_metadata: Dict[str, Any] = {
             **(raw_figure_node.node.metadata or {}),
+            **(metadata or {}),
             "file_id": raw_figure_node.node.file_id,
             "page_index": raw_figure_node.node.page_index,
             "figure_name": raw_figure_node.node.figure_name,
@@ -337,6 +345,7 @@ async def apage_screenshot_nodes_to_node_with_score(
     client: AsyncLlamaCloud,
     raw_image_nodes: Optional[List[PageScreenshotNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     if not raw_image_nodes:
         return []
@@ -357,6 +366,7 @@ async def apage_screenshot_nodes_to_node_with_score(
         image_base64 = base64.b64encode(image_bytes).decode("utf-8")
         image_node_metadata: Dict[str, Any] = {
             **(raw_image_node.node.metadata or {}),
+            **(metadata or {}),
             "file_id": raw_image_node.node.file_id,
             "page_index": raw_image_node.node.page_index,
         }
@@ -372,6 +382,7 @@ async def aimage_nodes_to_node_with_score(
     client: AsyncLlamaCloud,
     raw_image_nodes: Optional[List[PageScreenshotNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     """
     Legacy method to alias apage_screenshot_nodes_to_node_with_score.
@@ -380,7 +391,10 @@ async def aimage_nodes_to_node_with_score(
         return []
 
     return await apage_screenshot_nodes_to_node_with_score(
-        client=client, raw_image_nodes=raw_image_nodes, project_id=project_id
+        client=client,
+        raw_image_nodes=raw_image_nodes,
+        project_id=project_id,
+        metadata=metadata,
     )
 
 
@@ -388,6 +402,7 @@ async def apage_figure_nodes_to_node_with_score(
     client: AsyncLlamaCloud,
     raw_figure_nodes: Optional[List[PageFigureNodeWithScore]],
     project_id: str,
+    metadata: Optional[dict] = None,
 ) -> List[NodeWithScore]:
     if not raw_figure_nodes:
         return []
@@ -409,6 +424,7 @@ async def apage_figure_nodes_to_node_with_score(
         figure_base64 = base64.b64encode(figure_bytes).decode("utf-8")
         figure_node_metadata: Dict[str, Any] = {
             **(raw_figure_node.node.metadata or {}),
+            **(metadata or {}),
             "file_id": raw_figure_node.node.file_id,
             "page_index": raw_figure_node.node.page_index,
             "figure_name": raw_figure_node.node.figure_name,

py/llama_cloud_services/index/base.py

@@ -19,8 +19,8 @@ from llama_cloud import (
     PipelineCreate,
     PipelineCreateEmbeddingConfig,
     PipelineCreateTransformConfig,
+    PipelineFileCreateCustomMetadataValue,
     PipelineType,
-    ProjectCreate,
     ManagedIngestionStatus,
     CloudDocumentCreate,
     CloudDocument,
@@ -333,7 +333,7 @@ class LlamaCloudIndex(BaseManagedIndex):
         if file_ids:
             self._wait_for_resources(
                 file_ids,
-                lambda fid: self._client.pipelines.get_pipeline_file_status(
+                lambda fid: self._client.pipeline_files.get_pipeline_file_status(
                     pipeline_id=self.pipeline.id, file_id=fid
                 ),
                 resource_name="file",
@@ -420,7 +420,7 @@ class LlamaCloudIndex(BaseManagedIndex):
         if file_ids:
             await self._await_for_resources(
                 file_ids,
-                lambda fid: self._aclient.pipelines.get_pipeline_file_status(
+                lambda fid: self._aclient.pipeline_files.get_pipeline_file_status(
                     pipeline_id=self.pipeline.id, file_id=fid
                 ),
                 resource_name="file",
@@ -506,14 +506,19 @@ class LlamaCloudIndex(BaseManagedIndex):
         client = get_client(api_key, base_url, app_url, timeout)
 
         if project_id is None:
-            # create project if it doesn't exist
-            project = client.projects.upsert_project(
+            # get project by name
+            projects = client.projects.list_projects(
                 organization_id=organization_id,
-                request=ProjectCreate(name=project_name),
+                project_name=project_name,
             )
+            if not projects:
+                raise ValueError(
+                    f"Project '{project_name}' not found. Please create it first in the LlamaCloud UI."
+                )
+            project = projects[0]
             project_id = project.id
             if verbose:
-                print(f"Created project {project_id} with name {project_name}")
+                print(f"Found project {project_id} with name {project_name}")
 
         # create pipeline
         pipeline_create = PipelineCreate(
@@ -562,15 +567,20 @@ class LlamaCloudIndex(BaseManagedIndex):
         app_url = app_url or os.environ.get("LLAMA_CLOUD_APP_URL", DEFAULT_APP_URL)
         aclient = get_aclient(api_key, base_url, app_url, timeout)
 
-        # create project if it doesn't exist
-        project = await aclient.projects.upsert_project(
-            organization_id=organization_id, request=ProjectCreate(name=project_name)
+        # get project by name
+        projects = await aclient.projects.list_projects(
+            organization_id=organization_id, project_name=project_name
         )
+        if not projects:
+            raise ValueError(
+                f"Project '{project_name}' not found. Please create it first in the LlamaCloud UI."
+            )
+        project = projects[0]
         if project.id is None:
-            raise ValueError(f"Failed to create/get project {project_name}")
+            raise ValueError(f"Failed to get project {project_name}")
 
         if verbose:
-            print(f"Created project {project.id} with name {project.name}")
+            print(f"Found project {project.id} with name {project.name}")
 
         # create pipeline
         pipeline_create = PipelineCreate(
@@ -653,6 +663,9 @@ class LlamaCloudIndex(BaseManagedIndex):
             ],
         )
 
+        # Trigger a sync
+        client.pipelines.sync_pipeline(pipeline_id=index.pipeline.id)
+
         doc_ids = [doc.id for doc in upserted_documents]
         index.wait_for_completion(
             doc_ids=doc_ids, verbose=verbose, raise_on_error=raise_on_error
@@ -737,6 +750,10 @@ class LlamaCloudIndex(BaseManagedIndex):
                     )
                 ],
             )
+
+            # Trigger a sync
+            self._client.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             upserted_document = upserted_documents[0]
             self.wait_for_completion(
                 doc_ids=[upserted_document.id], verbose=verbose, raise_on_error=True
@@ -759,6 +776,9 @@ class LlamaCloudIndex(BaseManagedIndex):
                     )
                 ],
             )
+            # Trigger a sync
+            await self._aclient.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             upserted_document = upserted_documents[0]
             await self.await_for_completion(
                 doc_ids=[upserted_document.id], verbose=verbose, raise_on_error=True
@@ -781,6 +801,9 @@ class LlamaCloudIndex(BaseManagedIndex):
                     )
                 ],
             )
+            # Trigger a sync
+            self._client.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             upserted_document = upserted_documents[0]
             self.wait_for_completion(
                 doc_ids=[upserted_document.id], verbose=verbose, raise_on_error=True
@@ -803,6 +826,9 @@ class LlamaCloudIndex(BaseManagedIndex):
                     )
                 ],
             )
+            # Trigger a sync
+            await self._aclient.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             upserted_document = upserted_documents[0]
             await self.await_for_completion(
                 doc_ids=[upserted_document.id], verbose=verbose, raise_on_error=True
@@ -826,6 +852,9 @@ class LlamaCloudIndex(BaseManagedIndex):
                     for doc in documents
                 ],
             )
+            # Trigger a sync
+            self._client.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             doc_ids = [doc.id for doc in upserted_documents]
             self.wait_for_completion(doc_ids=doc_ids, verbose=True, raise_on_error=True)
             return [True] * len(doc_ids)
@@ -848,6 +877,9 @@ class LlamaCloudIndex(BaseManagedIndex):
                     for doc in documents
                 ],
             )
+            # Trigger a sync
+            await self._aclient.pipelines.sync_pipeline(pipeline_id=self.pipeline.id)
+
             doc_ids = [doc.id for doc in upserted_documents]
             await self.await_for_completion(
                 doc_ids=doc_ids, verbose=True, raise_on_error=True
@@ -905,6 +937,9 @@ class LlamaCloudIndex(BaseManagedIndex):
     def upload_file(
         self,
         file_path: str,
+        custom_metadata: Optional[
+            dict[str, Optional[PipelineFileCreateCustomMetadataValue]]
+        ] = None,
         verbose: bool = False,
         wait_for_ingestion: bool = True,
         raise_on_error: bool = False,
@@ -918,8 +953,10 @@ class LlamaCloudIndex(BaseManagedIndex):
                 print(f"Uploaded file {file.id} with name {file.name}")
 
         # Add file to pipeline
-        pipeline_file_create = PipelineFileCreate(file_id=file.id)
-        self._client.pipelines.add_files_to_pipeline_api(
+        pipeline_file_create = PipelineFileCreate(
+            file_id=file.id, custom_metadata=custom_metadata
+        )
+        self._client.pipeline_files.add_files_to_pipeline_api(
             pipeline_id=self.pipeline.id, request=[pipeline_file_create]
         )
 
@@ -932,6 +969,9 @@ class LlamaCloudIndex(BaseManagedIndex):
     async def aupload_file(
         self,
         file_path: str,
+        custom_metadata: Optional[
+            dict[str, Optional[PipelineFileCreateCustomMetadataValue]]
+        ] = None,
         verbose: bool = False,
         wait_for_ingestion: bool = True,
         raise_on_error: bool = False,
@@ -945,8 +985,10 @@ class LlamaCloudIndex(BaseManagedIndex):
                 print(f"Uploaded file {file.id} with name {file.name}")
 
         # Add file to pipeline
-        pipeline_file_create = PipelineFileCreate(file_id=file.id)
-        await self._aclient.pipelines.add_files_to_pipeline_api(
+        pipeline_file_create = PipelineFileCreate(
+            file_id=file.id, custom_metadata=custom_metadata
+        )
+        await self._aclient.pipeline_files.add_files_to_pipeline_api(
             pipeline_id=self.pipeline.id, request=[pipeline_file_create]
         )
 
@@ -961,6 +1003,9 @@ class LlamaCloudIndex(BaseManagedIndex):
         self,
         file_name: str,
         url: str,
+        custom_metadata: Optional[
+            dict[str, Optional[PipelineFileCreateCustomMetadataValue]]
+        ] = None,
         proxy_url: Optional[str] = None,
         request_headers: Optional[Dict[str, str]] = None,
         verify_ssl: bool = True,
@@ -983,8 +1028,10 @@ class LlamaCloudIndex(BaseManagedIndex):
             print(f"Uploaded file {file.id} with ID {file.id}")
 
         # Add file to pipeline
-        pipeline_file_create = PipelineFileCreate(file_id=file.id)
-        self._client.pipelines.add_files_to_pipeline_api(
+        pipeline_file_create = PipelineFileCreate(
+            file_id=file.id, custom_metadata=custom_metadata
+        )
+        self._client.pipeline_files.add_files_to_pipeline_api(
             pipeline_id=self.pipeline.id, request=[pipeline_file_create]
         )
 
@@ -998,6 +1045,9 @@ class LlamaCloudIndex(BaseManagedIndex):
         self,
         file_name: str,
         url: str,
+        custom_metadata: Optional[
+            dict[str, Optional[PipelineFileCreateCustomMetadataValue]]
+        ] = None,
         proxy_url: Optional[str] = None,
         request_headers: Optional[Dict[str, str]] = None,
         verify_ssl: bool = True,
@@ -1020,8 +1070,10 @@ class LlamaCloudIndex(BaseManagedIndex):
             print(f"Uploaded file {file.id} with ID {file.id}")
 
         # Add file to pipeline
-        pipeline_file_create = PipelineFileCreate(file_id=file.id)
-        await self._aclient.pipelines.add_files_to_pipeline_api(
+        pipeline_file_create = PipelineFileCreate(
+            file_id=file.id, custom_metadata=custom_metadata
+        )
+        await self._aclient.pipeline_files.add_files_to_pipeline_api(
             pipeline_id=self.pipeline.id, request=[pipeline_file_create]
         )
 

py/llama_cloud_services/index/retriever.py

@@ -129,11 +129,12 @@ class LlamaCloudRetriever(BaseRetriever):
         )
 
     def _result_nodes_to_node_with_score(
-        self, result_nodes: List[TextNodeWithScore]
+        self, result_nodes: List[TextNodeWithScore], metadata: Optional[dict] = None
     ) -> List[NodeWithScore]:
         nodes = []
         for res in result_nodes:
-            text_node = TextNode.parse_obj(res.node.dict())
+            text_node = TextNode.model_validate(res.node.dict())
+            text_node.metadata.update(metadata or {})
             nodes.append(NodeWithScore(node=text_node, score=res.score))
 
         return nodes
@@ -161,17 +162,25 @@ class LlamaCloudRetriever(BaseRetriever):
             search_filters_inference_schema=search_filters_inference_schema,
         )
 
-        result_nodes = self._result_nodes_to_node_with_score(results.retrieval_nodes)
+        result_nodes = self._result_nodes_to_node_with_score(
+            results.retrieval_nodes, metadata=results.metadata
+        )
         if self._retrieve_page_screenshot_nodes:
             result_nodes.extend(
                 page_screenshot_nodes_to_node_with_score(
-                    self._client, results.image_nodes, self.project.id
+                    self._client,
+                    results.image_nodes,
+                    self.project.id,
+                    metadata=results.metadata,
                 )
             )
         if self._retrieve_page_figure_nodes:
             result_nodes.extend(
                 page_figure_nodes_to_node_with_score(
-                    self._client, results.page_figure_nodes, self.project.id
+                    self._client,
+                    results.page_figure_nodes,
+                    self.project.id,
+                    metadata=results.metadata,
                 )
             )
 
@@ -200,17 +209,25 @@ class LlamaCloudRetriever(BaseRetriever):
             search_filters_inference_schema=search_filters_inference_schema,
         )
 
-        result_nodes = self._result_nodes_to_node_with_score(results.retrieval_nodes)
+        result_nodes = self._result_nodes_to_node_with_score(
+            results.retrieval_nodes, metadata=results.metadata
+        )
         if self._retrieve_page_screenshot_nodes:
             result_nodes.extend(
                 await apage_screenshot_nodes_to_node_with_score(
-                    self._aclient, results.image_nodes, self.project.id
+                    self._aclient,
+                    results.image_nodes,
+                    self.project.id,
+                    metadata=results.metadata,
                 )
             )
         if self._retrieve_page_figure_nodes:
             result_nodes.extend(
                 await apage_figure_nodes_to_node_with_score(
-                    self._aclient, results.page_figure_nodes, self.project.id
+                    self._aclient,
+                    results.page_figure_nodes,
+                    self.project.id,
+                    metadata=results.metadata,
                 )
             )
 

py/llama_cloud_services/parse/base.py

@@ -285,7 +285,7 @@ class LlamaParse(BasePydanticReader):
         description="Note: Non compatible with gpt-4o. If set to true, the parser will use a faster mode to extract text from documents. This mode will skip OCR of images, and table/heading reconstruction.",
     )
 
-    guess_xlsx_sheet_names: Optional[bool] = Field(
+    guess_xlsx_sheet_name: Optional[bool] = Field(
         default=False,
         description="Whether to guess the sheet names of the xlsx file.",
     )
@@ -313,6 +313,10 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="If set to true, the parser will ignore document elements for layout detection and only rely on a vision model.",
     )
+    inline_images_in_markdown: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will inline images in the markdown output.",
+    )
     input_s3_region: Optional[str] = Field(
         default=None,
         description="The region of the input S3 bucket if input_s3_path is specified.",
@@ -329,6 +333,10 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="The maximum timeout in seconds to wait for the parsing to finish. Override default timeout of 30 minutes. Minimum is 120 seconds.",
     )
+    keep_page_separator_when_merging_tables: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will keep the page separator when merging tables across pages.",
+    )
     language: Optional[str] = Field(
         default="en", description="The language of the text to parse."
     )
@@ -400,6 +408,10 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="If set, the parser will try to preserve very small text lines. This can be useful for documents containing vector graphics with very small text lines that may not be recognized by OCR or a vision model (such as in CAD drawings).",
     )
+    presentation_out_of_bounds_content: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will include out-of-bounds content in presentation files.",
+    )
     precise_bounding_box: Optional[bool] = Field(
         default=False,
         description="If set to true, the parser will use a more precise bounding box to extract text from documents. This will increase the accuracy of the parsing job, but reduce the speed.",
@@ -416,6 +428,14 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="A suffix to add after error message in failed pages. If not set, no suffix will be used.",
     )
+    remove_hidden_text: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will remove hidden text from the document.",
+    )
+    save_images: Optional[bool] = Field(
+        default=True,
+        description="If set to true, the parser will save images extracted from the document.",
+    )
     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).",
@@ -440,6 +460,10 @@ class LlamaParse(BasePydanticReader):
         default=False,
         description="If set to true, the parser will use a specialized one-shot chart parsing model to extract data from charts. This model is able to understand the chart type and extract the data accordingly. It is more accurate than the efficient model, but also more expensive.",
     )
+    specialized_image_parsing: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will use a specialized image parsing model to extract data from images.",
+    )
     strict_mode_buggy_font: Optional[bool] = Field(
         default=False,
         description="If set to true, the parser will fail if it can't extract text from a document because of a buggy font.",
@@ -536,6 +560,21 @@ class LlamaParse(BasePydanticReader):
         default=None,
         description="A prefix to add to the page footer in the output markdown.",
     )
+    extract_printed_page_number: Optional[bool] = Field(
+        default=None,
+        description="Whether to extract the printed page numbers from pages in the document.",
+    )
+    line_level_bounding_box: Optional[bool] = Field(
+        default=False,
+        description="If set to true, the parser will include line-level bounding boxes in the result.",
+    )
+    tier: Optional[str] = Field(
+        default=None, description="The tier to use for the parsing job."
+    )
+    version: Optional[str] = Field(
+        default=None,
+        description="The version of the parser to use at the specified tier.",
+    )
 
     # Deprecated
     bounding_box: Optional[str] = Field(
@@ -580,6 +619,23 @@ class LlamaParse(BasePydanticReader):
         description="Automatically check for Python SDK updates.",
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def handle_deprecated_params(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        # Handle deprecated guess_xlsx_sheet_names -> guess_xlsx_sheet_name
+        if "guess_xlsx_sheet_names" in data:
+            warnings.warn(
+                "The parameter 'guess_xlsx_sheet_names' is deprecated and will be removed in a future release. "
+                "Use 'guess_xlsx_sheet_name' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            # Only set the new parameter if it's not already explicitly set
+            if "guess_xlsx_sheet_name" not in data:
+                data["guess_xlsx_sheet_name"] = data["guess_xlsx_sheet_names"]
+            del data["guess_xlsx_sheet_names"]
+        return data
+
     @model_validator(mode="before")
     @classmethod
     def warn_extra_params(cls, data: Dict[str, Any]) -> Dict[str, Any]:
@@ -695,11 +751,9 @@ class LlamaParse(BasePydanticReader):
             file_path = str(file_input)
             file_ext = os.path.splitext(file_path)[1].lower()
             if file_ext not in SUPPORTED_FILE_TYPES:
-                raise Exception(
-                    f"Currently, only the following file types are supported: {SUPPORTED_FILE_TYPES}\n"
-                    f"Current file type: {file_ext}"
-                )
-            mime_type = mimetypes.guess_type(file_path)[0]
+                mime_type = "application/octet-stream"
+            else:
+                mime_type = mimetypes.guess_type(file_path)[0]
             # Open the file here for the duration of the async context
             # load data, set the mime type
             fs = fs or get_default_fs()
@@ -820,8 +874,8 @@ class LlamaParse(BasePydanticReader):
             )
             data["formatting_instruction"] = self.formatting_instruction
 
-        if self.guess_xlsx_sheet_names:
-            data["guess_xlsx_sheet_names"] = self.guess_xlsx_sheet_names
+        if self.guess_xlsx_sheet_name:
+            data["guess_xlsx_sheet_name"] = self.guess_xlsx_sheet_name
 
         if self.html_make_all_elements_visible:
             data["html_make_all_elements_visible"] = self.html_make_all_elements_visible
@@ -845,6 +899,9 @@ class LlamaParse(BasePydanticReader):
                 "ignore_document_elements_for_layout_detection"
             ] = self.ignore_document_elements_for_layout_detection
 
+        if self.inline_images_in_markdown:
+            data["inline_images_in_markdown"] = self.inline_images_in_markdown
+
         if input_url is not None:
             files = None
             data["input_url"] = str(input_url)
@@ -873,6 +930,11 @@ class LlamaParse(BasePydanticReader):
         if self.job_timeout_in_seconds is not None:
             data["job_timeout_in_seconds"] = self.job_timeout_in_seconds
 
+        if self.keep_page_separator_when_merging_tables:
+            data[
+                "keep_page_separator_when_merging_tables"
+            ] = self.keep_page_separator_when_merging_tables
+
         if self.language:
             data["language"] = self.language
 
@@ -951,6 +1013,11 @@ class LlamaParse(BasePydanticReader):
         if self.preserve_very_small_text:
             data["preserve_very_small_text"] = self.preserve_very_small_text
 
+        if self.presentation_out_of_bounds_content:
+            data[
+                "presentation_out_of_bounds_content"
+            ] = self.presentation_out_of_bounds_content
+
         if self.preset is not None:
             data["preset"] = self.preset
 
@@ -970,6 +1037,11 @@ class LlamaParse(BasePydanticReader):
                 "replace_failed_page_with_error_message_suffix"
             ] = self.replace_failed_page_with_error_message_suffix
 
+        if self.remove_hidden_text:
+            data["remove_hidden_text"] = self.remove_hidden_text
+
+        data["save_images"] = self.save_images
+
         if self.skip_diagonal_text:
             data["skip_diagonal_text"] = self.skip_diagonal_text
 
@@ -994,6 +1066,9 @@ class LlamaParse(BasePydanticReader):
         if self.specialized_chart_parsing_plus:
             data["specialized_chart_parsing_plus"] = self.specialized_chart_parsing_plus
 
+        if self.specialized_image_parsing:
+            data["specialized_image_parsing"] = self.specialized_image_parsing
+
         if self.strict_mode_buggy_font:
             data["strict_mode_buggy_font"] = self.strict_mode_buggy_font
 
@@ -1049,6 +1124,18 @@ class LlamaParse(BasePydanticReader):
                 "markdown_table_multiline_header_separator"
             ] = self.markdown_table_multiline_header_separator
 
+        if self.extract_printed_page_number is not None:
+            data["extract_printed_page_number"] = self.extract_printed_page_number
+
+        if self.line_level_bounding_box is not None:
+            data["line_level_bounding_box"] = self.line_level_bounding_box
+
+        if self.tier is not None:
+            data["tier"] = self.tier
+
+        if self.version is not None:
+            data["version"] = self.version
+
         # Deprecated
         if self.bounding_box is not None:
             data["bounding_box"] = self.bounding_box