Stop Wrestling with PDFs! Use ade-python Instead

What if I told you that developers are still burning hours manually parsing PDFs, wrestling with inconsistent OCR outputs, and writing brittle regex patterns that break the moment a document format changes? Here's the painful truth: traditional document extraction is fundamentally broken. It's a graveyard of abandoned scripts, frustrated data scientists, and pipeline failures that only surface at 2 AM.

But what if documents could understand themselves? What if instead of forcing rigid templates onto chaotic file formats, you could deploy an intelligent agent that reads, reasons, and returns precisely the structured data you need?

Enter ade-python — LandingAI's Agentic Document Extraction Python library. This isn't just another PDF parser. It's a fully-typed, production-ready SDK that transforms document chaos into clean, structured outputs through the power of agentic AI workflows. Built for Python 3.9+ and generated with Stainless for maximum reliability, ade-python is quietly becoming the secret weapon that top ML engineers are deploying in production pipelines.

Ready to stop fighting your documents and start extracting value from them? Let's dive deep.

What is ade-python?

ade-python is the official Python SDK for LandingAI's Agentic Document Extraction (ADE) REST API. Created by LandingAI — the computer vision company founded by AI legend Andrew Ng — this library represents a paradigm shift in how developers approach document processing.

Unlike traditional OCR tools that blindly extract text, ADE leverages agentic workflows: AI systems that can reason about document structure, understand context, and make intelligent decisions about what information to extract and how to organize it. The "agentic" approach means the system doesn't just read your documents — it comprehends them.

The library is generated with Stainless, a modern SDK generator that ensures type safety, consistent patterns, and automatic updates as the API evolves. This matters enormously in production environments where breaking changes can cascade through entire data pipelines.

Why is it trending now? Three forces are converging:

• The explosion of unstructured enterprise data — companies are drowning in PDFs, scans, and mixed-format documents
• The rise of LLM-powered agents — developers now expect AI systems to handle complexity, not just pattern matching
• The demand for typed, reliable SDKs — the era of loose JSON parsing is ending; Pydantic models are becoming the standard

With features like sync/async clients, pluggable HTTP backends, automatic retries with exponential backoff, and seamless file uploads, ade-python isn't just keeping pace with modern Python development — it's defining what a document extraction SDK should look like in 2024.

Key Features That Make ade-python Insane

Let's unpack what makes this library genuinely powerful for production use:

✅ Fully-Typed SDK with Pydantic Response Models

Every response is a Pydantic model, not a raw dictionary. This means autocomplete in your IDE, runtime validation, and automatic serialization. No more KeyError surprises at 3 AM when an API response shape changes slightly.

⚡️ Sync & Async Clients

Whether you're processing a single invoice or building a high-throughput pipeline handling thousands of documents, ade-python has you covered. The LandingAIADE client handles synchronous operations, while AsyncLandingAIADE with httpx or aiohttp backends unlocks serious concurrency.

📄 Large Document Processing via Async Jobs

Some documents are too massive for synchronous processing. The parse_jobs API lets you create, monitor, and retrieve asynchronous extraction jobs — perfect for batch processing or handling enterprise-scale files without blocking your application.

🔁 Built-in Retries with Exponential Backoff

Network hiccups? API rate limits? The SDK automatically retries transient failures 2 times by default with intelligent backoff. Configure max_retries globally or per-request for fine-grained control.

🔐 Secure API Key Handling

Never hardcode secrets. The SDK reads VISION_AGENT_API_KEY from environment variables by default, with seamless .env file support via python-dotenv.

📦 Seamless File Uploads

Pass Path objects, raw bytes, or (filename, contents, media_type) tuples. The async client reads files asynchronously automatically — no manual file handle management required.

🧩 Schema-Based Data Extraction

Define your output structure with Pydantic models, convert to JSON Schema, and let the agent extract exactly what you need. This is extraction-as-code, not extraction-as-hope.

🔌 Pluggable HTTP Backends

Default httpx not cutting it for your concurrency needs? Swap in aiohttp with a single parameter. The abstraction layer means your business logic stays identical regardless of transport.

💾 Optional save_to Parameter

Automatically persist responses to disk with auto-generated filenames like {input_file}_parse_output.json. Perfect for debugging, audit trails, or building reproducible pipelines.

5 Real-World Use Cases Where ade-python Dominates

1. Financial Document Processing at Scale

Banks and fintechs process millions of statements, tax forms, and loan applications. Traditional OCR fails when formats vary between institutions. With ade-python's schema-based extraction, define a LoanApplication Pydantic model and extract structured data regardless of whether the source is a scanned PDF, digital form, or fax image.

2. Healthcare Record Digitization

Medical records combine structured forms, free-text notes, and mixed layouts. The split functionality lets you classify document sections ("Lab Results", "Prescription", "Patient History") before extraction, ensuring each section gets appropriate processing logic.

3. Legal Contract Analysis

Law firms and compliance teams need to extract clauses, dates, parties, and obligations from contracts with 100% accuracy requirements. The agentic approach understands context — distinguishing between "termination for convenience" and "termination for cause" — something template-based systems miss constantly.

4. Supply Chain Invoice Automation

Vendors submit invoices in dozens of formats. Instead of maintaining fragile parsing rules per vendor, deploy ade-python with a unified Invoice schema. The async jobs API handles bulk processing during month-end close without overwhelming your systems.

5. MCP-Powered AI Assistants

The included MCP Server enables Cursor, VS Code, and other AI assistants to directly interact with your document extraction API. Your AI coding partner can now explore endpoints, test requests, and help integrate ADE into your application — meta-automation for the win.

Step-by-Step Installation & Setup Guide

Getting started with ade-python takes under five minutes. Here's the complete setup:

Prerequisites

• Python 3.9 or higher
• A LandingAI API key (get one at va.landing.ai)

Installation

# Install the base package from PyPI
pip install landingai-ade

# For enhanced async performance with aiohttp backend
pip install landingai-ade[aiohttp]

Environment Configuration

Create a .env file in your project root (never commit this!):

VISION_AGENT_API_KEY="your-actual-api-key-here"

Load it in your application:

from dotenv import load_dotenv
load_dotenv()  # Now os.environ.get("VISION_AGENT_API_KEY") works

Basic Client Initialization

from landingai_ade import LandingAIADE

# Minimal setup — reads API key from environment automatically
client = LandingAIADE()

# Or explicitly configure for EU data residency
client = LandingAIADE(
    apikey="your-key",  # Optional if env var is set
    environment="eu",   # Options: "production" (default), "eu"
)

Async Client Setup

from landingai_ade import AsyncLandingAIADE

# Default httpx backend
async_client = AsyncLandingAIADE()

# Or with aiohttp for maximum concurrency
from landingai_ade import DefaultAioHttpClient
async_client = AsyncLandingAIADE(
    http_client=DefaultAioHttpClient()
)

Verification

import landingai_ade
print(landingai_ade.__version__)  # Confirm you're on the latest

REAL Code Examples from the Repository

Let's examine production-ready patterns using actual code from the ade-python README, with detailed explanations of what each snippet accomplishes.

Example 1: Basic Document Parsing with Save-to-Disk

This is your bread-and-butter extraction pattern — parse a local file and optionally persist results:

import os
from pathlib import Path
from landingai_ade import LandingAIADE

# Initialize client with explicit EU region (GDPR compliance)
client = LandingAIADE(
    apikey=os.environ.get("VISION_AGENT_API_KEY"),  # Reads from .env automatically
    environment="eu",  # Data stays in European infrastructure
)

# Parse a document — the agent analyzes layout, structure, and content
response = client.parse(
    document=Path("path/to/file"),           # Local file via Path object
    model="dpt-2-latest",                     # Latest document parsing model
    save_to="./output_folder",                # Auto-saves as {filename}_parse_output.json
)

# Access structured chunks — each chunk has metadata about its document region
print(response.chunks)

What's happening here? The parse method sends your document to LandingAI's agentic API. The "dpt-2-latest" model performs layout analysis, OCR, and semantic chunking. The response contains chunks — discrete text segments with positional and typographical metadata. The save_to parameter is a killer feature for debugging: it automatically serializes the full response to JSON, naming it intelligently based on the input filename.

Example 2: Intelligent Document Splitting with Classification

Real-world documents often contain multiple logical documents in one physical file. A PDF might contain 12 months of bank statements, or a closing package might mix deeds, insurance policies, and inspection reports. The split method solves this:

import json
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Step 1: Parse to get Markdown representation
parse_response = client.parse(
    document=Path("/path/to/document.pdf"),
    model="dpt-2-latest"
)

# Step 2: Define what document types to look for
# Each class has a name, description, and optional identifier field
split_class = [
    {
        "name": "Bank Statement",
        "description": "Document from a bank that summarizes all account activity over a period of time."
    },
    {
        "name": "Pay Stub",
        "description": "Document that details an employee's earnings, deductions, and net pay for a specific pay period.",
        "identifier": "Pay Stub Date"  # Extract this field to distinguish instances
    }
]

# Step 3: Split using the Markdown — the agent reasons about boundaries
split_response = client.split(
    split_class=json.dumps(split_class),      # Must be JSON string
    markdown=parse_response.markdown,          # Pass parsed content directly
    model="split-latest"                       # Specialized splitting model
)

# Step 4: Process each logical document independently
for split in split_response.splits:
    print(f"Classification: {split.classification}")  # "Bank Statement" or "Pay Stub"
    print(f"Identifier: {split.identifier}")          # e.g., "2024-01-15" for pay stub date
    print(f"Pages: {split.pages}")                    # Which physical pages contain this document

Why this matters: Without splitting, you'd need manual pre-processing or fragile page-range heuristics. The agentic approach understands document boundaries based on content, not just page breaks. The identifier field is particularly powerful — it lets you extract a distinguishing value (like a date or account number) to name and organize split outputs automatically.

Example 3: Schema-Based Structured Extraction with Pydantic

This is where ade-python transcends traditional OCR. Instead of getting raw text, you define exactly what you want:

import os
from pathlib import Path
from landingai_ade import LandingAIADE
from landingai_ade.lib import pydantic_to_json_schema
from pydantic import BaseModel, Field

# Define your domain model with rich descriptions — the agent uses these!
class Person(BaseModel):
    name: str = Field(description="Person's full legal name")
    age: int = Field(description="Person's age in years")

# Convert Pydantic model to JSON Schema for the API
schema = pydantic_to_json_schema(Person)

# Initialize and extract
client = LandingAIADE(apikey=os.environ.get("VISION_AGENT_API_KEY"))
response = client.extract(
    schema=schema,                              # Your structured output definition
    markdown=Path("path/to/file.md"),           # Or markdown_url for remote files
    save_to="./output_folder",                  # Persist for audit trail
)

# response now contains validated Person instances, not raw text

The magic here: The description fields in your Pydantic model aren't just documentation — they're instructions to the agent. "Full legal name" tells the system to prefer "Robert Jones Jr." over "Bob" if both appear. The pydantic_to_json_schema utility handles the conversion, and the response is automatically validated against your model. Invalid or missing fields raise clear errors, not silent data corruption.

Example 4: Async Job Processing for Enterprise Scale

When documents are hundreds of pages or you're processing backlogs, synchronous calls won't cut it:

import os
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE(apikey=os.environ.get("VISION_AGENT_API_KEY"))

# Create job — returns immediately, processing happens server-side
job = client.parse_jobs.create(
    document=Path("path/to/large_file.pdf"),
    model="dpt-2-latest",
)
print(f"Job created with ID: {job.job_id}")  # Save this for status polling

# Check status anytime
job_status = client.parse_jobs.get(job.job_id)
print(f"Status: {job_status.status}")  # "pending", "processing", "completed", "failed"

# List and filter all jobs — great for dashboards
response = client.parse_jobs.list(
    status="completed",
    page=0,
    page_size=10,
)
for job in response.jobs:
    print(f"Job {job.job_id}: {job.status}")

Architecture insight: This pattern decouples document submission from result retrieval. Your application can enqueue jobs, return immediately to users, and poll or webhook for completion. The list method with filtering lets you build monitoring dashboards without external infrastructure.

Advanced Usage & Best Practices

Optimize Concurrency with aiohttp

For high-throughput applications, the default httpx async client may become a bottleneck. The aiohttp backend offers superior connection pooling:

import asyncio
from landingai_ade import AsyncLandingAIADE, DefaultAioHttpClient

async def process_batch(files):
    async with AsyncLandingAIADE(
        http_client=DefaultAioHttpClient(),  # Swap backend here
    ) as client:
        tasks = [client.parse(document=f, model="dpt-2-latest") for f in files]
        return await asyncio.gather(*tasks)

Implement Robust Error Handling

Production code must handle every failure mode gracefully:

import landingai_ade
from landingai_ade import LandingAIADE

client = LandingAIADE(max_retries=3)  # Increase from default 2

try:
    response = client.parse(document=Path("critical_file.pdf"))
except landingai_ade.AuthenticationError:
    # Rotate API key, alert ops team
    raise SystemExit("Invalid API key — check VISION_AGENT_API_KEY")
except landingai_ade.RateLimitError:
    # Implement exponential backoff with jitter
    time.sleep(random.uniform(1, 5))
    retry_later()
except landingai_ade.APIStatusError as e:
    # Log for debugging, surface user-friendly message
    logger.error(f"API error {e.status_code}: {e.response}")
    raise

Leverage Streaming for Memory Efficiency

For extremely large responses, avoid loading everything into memory:

with client.with_streaming_response.parse(document=Path("huge_file.pdf")) as response:
    for line in response.iter_lines():
        process_incrementally(line)  # Handle chunk-by-chunk

Enable Debug Logging

export LANDINGAI_ADE_LOG=debug  # or "info" for less verbosity

Comparison with Alternatives

Verdict: Choose ade-python when you need intelligent extraction with modern Python patterns. For simple text extraction on air-gapped systems, local libraries still have a place. But for production document AI, the agentic approach is becoming unbeatable.

FAQ

What is agentic document extraction?

Agentic extraction uses AI systems that can reason about document structure, understand context, and make intelligent decisions — not just apply OCR. The "agent" analyzes layout, classifies content, and extracts data based on semantic understanding, not just positional rules.

Is ade-python free to use?

The SDK is open-source and free to install. However, it requires API calls to LandingAI's hosted service, which has usage-based pricing. Check LandingAI's pricing for current rates.

Can I use ade-python without internet access?

No — ade-python is a client for LandingAI's cloud API. For fully offline processing, you'd need a different solution. The trade-off is access to state-of-the-art models without managing infrastructure.

How does schema-based extraction differ from traditional OCR?

Traditional OCR returns raw text. Schema-based extraction lets you define a Pydantic model (like Invoice or PatientRecord), and the agent returns structured, validated data matching that schema. No post-processing regex required.

What's the maximum document size?

For very large documents, use the parse_jobs async API. Synchronous parse has limits based on API configuration. The jobs system handles enterprise-scale files gracefully.

Can I contribute to ade-python?

Absolutely! See the contributing documentation in the repository. Issues and PRs are welcome.

How do I migrate from another document extraction solution?

Start with the parse method to get Markdown output, then layer on split for multi-document files and extract for structured data. The Pydantic types make integration with existing data pipelines straightforward.

Conclusion

Document extraction doesn't have to be a nightmare of brittle regex, format-specific parsers, and 2 AM debugging sessions. ade-python represents a genuine leap forward — bringing agentic AI, modern Python typing, and production-hardened reliability to a problem space that's been stuck in the dark ages.

The combination of Pydantic-powered schema extraction, intelligent document splitting, and flexible async processing makes this the most compelling document AI SDK I've evaluated this year. Whether you're building fintech pipelines, healthcare digitization systems, or legal analysis tools, ade-python deserves a serious look.

My recommendation? Install it today, run the parse example on your most problematic document, and watch an agent do in seconds what used to take hours of custom code. The future of document processing is agentic — and ade-python is your on-ramp.

👉 Star the repo, install the package, and start extracting intelligently:

pip install landingai-ade

Then head to github.com/landing-ai/ade-python for the full documentation and MCP server setup. Your documents are waiting to be understood.