### Adding and running examples

Source: https://github.com/landing-ai/ade-python/blob/main/CONTRIBUTING.md

Example of how to add and run a new example script.

```py
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```sh
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Parse with Custom Prompts Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of parsing a document with custom prompts for figures.

```python
response = client.parse(
    document=Path("document.pdf"),
    model="dpt-2-latest",
    custom_prompts={"figure": "Extract detailed descriptions of all diagrams"}
)
```

--------------------------------

### Generate Schema from Examples

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of how to generate a schema from markdown files using the client.extract_build_schema method.

```python
response = client.extract_build_schema(
    markdowns=[
        Path("invoice_example1.md"),
        Path("invoice_example2.md")
    ],
    prompt="Extract invoice details including number, date, and total",
    model="extract-latest"
)

schema_json = response.extraction_schema
print(schema_json)  # Use this with client.extract()
```

--------------------------------

### Install from Git

Source: https://github.com/landing-ai/ade-python/blob/main/CONTRIBUTING.md

Command to install the repository directly from a Git URL.

```sh
$ pip install git+ssh://git@github.com/landing-ai/ade-python.git
```

--------------------------------

### Using with_raw_response

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example demonstrating how to use the `with_raw_response` property to get the raw httpx.Response object, including headers and status codes, and then parse the response.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()
response = client.with_raw_response.parse(document=Path("file.pdf"), model="dpt-2-latest")
print(response.headers.get('X-My-Header'))
parsed_result = response.parse()  # Get the parsed response object
```

--------------------------------

### Parse Local File Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of parsing a local PDF file and saving the output.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Parse local file
response = client.parse(
    document=Path("invoice.pdf"),
    model="dpt-2-latest",
    save_to="./output"  # Saves to ./output/invoice_parse_output.json
)
print(response.markdown)
print(response.chunks)
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

A comprehensive example illustrating various configuration options for the LandingAIADE client, including authentication, environment, timeouts, retries, HTTP client with proxy, default headers, and response validation.

```python
from pathlib import Path
from landingai_ade import LandingAIADE
import httpx

# Production setup with all options
client = LandingAIADE(
    # Authentication
    apikey="prod-api-key-123",
    
    # API endpoint
    environment="eu",
    
    # Timeouts and retries
    timeout=httpx.Timeout(
        timeout=60.0,
        read=120.0,
        write=30.0,
        connect=10.0
    ),
    max_retries=3,
    
    # HTTP client with proxy
    http_client=DefaultHttpxClient(
        proxy="http://corporate-proxy.com:8080"
    ),
    
    # Default headers for compliance/tracking
    default_headers={
        "X-Organization": "acme-corp",
        "X-Batch-ID": "batch-123"
    },
    
    # Response validation
    _strict_response_validation=False
)

# Use client
response = client.parse(
    document=Path("invoice.pdf"),
    model="dpt-2-latest",
    save_to="./results"
)
```

--------------------------------

### Extract Build Schema Method Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

An example demonstrating the initialization of the LandingAIADE client, which is a prerequisite for using methods like `extract_build_schema`.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()
```

--------------------------------

### Build and Install from Source

Source: https://github.com/landing-ai/ade-python/blob/main/CONTRIBUTING.md

Commands to build the package from source and install the wheel file.

```sh
$ rye build
# or
$ python -m build
```

```sh
$ pip install ./path-to-wheel-file.whl
```

--------------------------------

### Parse with Page Split Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of parsing a multi-page PDF with the 'page' split option.

```python
response = client.parse(
    document=Path("multipage.pdf"),
    model="dpt-2-latest",
    split="page"
)
for split in response.splits:
    print(f"Page {split.pages}: {len(split.chunks)} chunks")
```

--------------------------------

### Setup with Rye

Source: https://github.com/landing-ai/ade-python/blob/main/CONTRIBUTING.md

Commands to set up the development environment using Rye.

```sh
$ ./scripts/bootstrap
```

```sh
$ rye sync --all-features
```

```sh
# Activate the virtual environment - https://docs.python.org/3/library/venv.html#how-venvs-work
$ source .venv/bin/activate

# now you can omit the `rye run` prefix
$ python script.py
```

--------------------------------

### Install the SDK

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/README.md

Command to install the LandingAI ADE Python SDK.

```bash
pip install landingai-ade
```

--------------------------------

### Async usage example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/parse_jobs.md

Provides an example of using the `AsyncParseJobsResource` for asynchronous operations.

```python
import asyncio
from pathlib import Path
from landingai_ade import AsyncLandingAIADE

async def main():
    async with AsyncLandingAIADE() as client:
        # Create job
        job = await client.parse_jobs.create(
            document=Path("file.pdf"),
            model="dpt-2-latest"
        )
        print(f"Job: {job.job_id}")
        
        # Get status
        status = await client.parse_jobs.get(job.job_id)
        print(f"Status: {status.status}")
        
        # List jobs
        jobs = await client.parse_jobs.list(status="completed")
        for j in jobs.jobs:
            print(f"- {j.job_id}: {j.status}")

asyncio.run(main())
```

--------------------------------

### Async Parse Job Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of creating, getting status, and listing asynchronous parse jobs.

```python
import os
from pathlib import Path
from landingai_ade import LandingAIADE

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

# Create an async parse job
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}")

# Get job status
job_status = client.parse_jobs.get(job.job_id)
print(f"Status: {job_status.status}")

# List all jobs (with optional filtering)
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}")
```

--------------------------------

### Setup without Rye

Source: https://github.com/landing-ai/ade-python/blob/main/CONTRIBUTING.md

Commands to set up the development environment using pip.

```sh
$ pip install -r requirements-dev.lock
```

--------------------------------

### AsyncLandingAIADE Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Demonstrates the usage of the asynchronous client for parsing documents.

```python
import asyncio
from pathlib import Path
from landingai_ade import AsyncLandingAIADE

async def main():
    async with AsyncLandingAIADE() as client:
        response = await client.parse(
            document=Path("file.pdf"),
            model="dpt-2-latest"
        )
        print(response.markdown)

asyncio.run(main())

```

--------------------------------

### Configuration Precedence Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Illustrates the order of precedence for configuration settings, from highest to lowest priority.

```python
# Constructor default: timeout=480
client = LandingAIADE()

# with_options override: timeout=300
result1 = client.with_options(timeout=300).parse(...)

# Per-request override: timeout=100
result2 = client.parse(
    document=Path("file.pdf"),
    timeout=100
)

# Constructor persists, others are per-request
result3 = client.parse(...)  # Uses 480 seconds
```

--------------------------------

### Extract Method Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

An example demonstrating how to use the `extract` method to extract invoice details from a Markdown file using a Pydantic model to define the schema.

```python
import json
from pathlib import Path
from landingai_ade import LandingAIADE
from landingai_ade.lib import pydantic_to_json_schema
from pydantic import BaseModel, Field

class Invoice(BaseModel):
    invoice_number: str = Field(description="Invoice number")
    total_amount: float = Field(description="Total amount due")
    vendor_name: str = Field(description="Vendor/seller name")

client = LandingAIADE()
schema_json = pydantic_to_json_schema(Invoice)

response = client.extract(
    schema=schema_json,
    markdown=Path("invoice.md"),
    model="extract-latest",
    save_to="./output"
)

print(response.extraction)  # {"invoice_number": "INV-001", "total_amount": 500.0, ...}
```

--------------------------------

### Install from PyPI

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Installs the landingai-ade library from the Python Package Index.

```sh
# install from PyPI
pip install landingai-ade
```

--------------------------------

### List Parse Jobs Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to list all parse jobs associated with an API key, with options for filtering and pagination.

```bash
curl -X GET "https://api.va.landing.ai/v1/ade/parse/jobs?status=completed&page=0&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### File Uploads Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example showing how to pass file uploads as bytes, PathLike, or tuples.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

client.parse(
    document=Path("/path/to/file"),
)
```

--------------------------------

### Authentication Header Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of the required Authorization header for API requests.

```text
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Advanced: Custom HTTP Clients - Using httpx Directly

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Example of creating a custom httpx client and passing it to the LandingAIADE SDK.

```python
import httpx
from landingai_ade import LandingAIADE, DefaultHttpxClient

# Create custom httpx client
httpx_client = httpx.Client(
    timeout=60.0,
    limits=httpx.Limits(
        max_connections=100,
        max_keepalive_connections=20
    ),
    follow_redirects=True,
    verify=True,  # Verify SSL certificates
)

# Pass to SDK
client = LandingAIADE(http_client=httpx_client)

# Close when done
client.close()
```

--------------------------------

### Split Document Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of splitting a document using the client.split method.

```python
import os
from pathlib import Path
from landingai_ade import LandingAIADE

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

# Access the splits
split_response = client.split(
    split_class=json.dumps(split_class),
    markdown=parse_response.markdown,  # Pass Markdown string directly
    model="split-latest"
)

for split in split_response.splits:
    print(f"Classification: {split.classification}")
    print(f"Identifier: {split.identifier}")
    print(f"Pages: {split.pages}")
```

--------------------------------

### Async Configuration

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Example of configuring and using the asynchronous client with aiohttp backend for better concurrency.

```python
import asyncio
from pathlib import Path
from landingai_ade import AsyncLandingAIADE, DefaultAioHttpClient

async def main():
    # Async client with aiohttp backend for better concurrency
    async with AsyncLandingAIADE(
        apikey="your-api-key",
        environment="production",
        timeout=600.0,
        max_retries=3,
        http_client=DefaultAioHttpClient()  # Use aiohttp instead of httpx
    ) as client:
        response = await client.parse(
            document=Path("file.pdf"),
            model="dpt-2-latest"
        )
        print(response.markdown)

asyncio.run(main())
```

--------------------------------

### Nested Parameters Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example demonstrating the use of nested parameters (TypedDicts) in requests.

```python
from landingai_ade import LandingAIADE

client = LandingAIADE()

response = client.parse(
    custom_prompts={},
)
print(response.custom_prompts)
```

--------------------------------

### Split Document Sections

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of how to use the client.split method to classify document sections.

```python
import json
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

split_classes = [
    {
        "name": "Bank Statement",
        "description": "Document summarizing account activity over a period"
    },
    {
        "name": "Pay Stub",
        "description": "Document detailing earnings and deductions",
        "identifier": "Pay Stub Date"
    }
]

response = client.split(
    split_class=split_classes,
    markdown=Path("document.md"),
    model="split-latest",
    save_to="./output"
)

for split in response.splits:
    print(f"Classification: {split.classification}")
    print(f"Pages: {split.pages}")
    print(f"Content: {split.markdowns[0][:100]}...")
```

--------------------------------

### POST /v1/ade/parse cURL Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to use the POST /v1/ade/parse endpoint with cURL to upload a PDF document and specify a model.

```bash
curl -X POST https://api.va.landing.ai/v1/ade/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@/path/to/document.pdf" \
  -F "model=dpt-2-latest"
```

--------------------------------

### Classify Document Pages

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of how to use the client.classify method to classify pages of a document.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

classes = [
    {"class": "Invoice", "description": "An invoice document"},
    {"class": "Receipt", "description": "A receipt or proof of purchase"},
    {"class": "Other"}
]

response = client.classify(
    classes=classes,
    document=Path("batch_of_documents.pdf")
)

for classification in response.classification:
    print(f"Page {classification.page}: {classification.class_}")
```

--------------------------------

### Catching LandingAiadeError

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of how to catch the base LandingAiadeError for any SDK-related errors.

```python
from landingai_ade import LandingAiadeError

try:
    response = client.parse(document=Path("file.pdf"))
except LandingAiadeError as e:
    print(f"SDK error: {e}")
```

--------------------------------

### Using with_streaming_response

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example showing how to use the `with_streaming_response` property to stream the response body, iterating over lines and accessing headers.

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()
with client.with_streaming_response.parse(document=Path("file.pdf"), model="dpt-2-latest") as response:
    print(response.headers.get("X-My-Header"))
    for line in response.iter_lines():
        print(line)
```

--------------------------------

### Configure timeout

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Examples of configuring timeouts globally, per-request, or with fine-grained settings.

```python
# Global timeout for all requests
client = LandingAIADE(timeout=1200.0)  # 20 minutes

# Per-request timeout
client.with_options(timeout=600.0).parse(...)

# Fine-grained timeout (connect, read, write, pool)
import httpx
client = LandingAIADE(
    timeout=httpx.Timeout(60.0, read=120.0, write=30.0)
)
```

--------------------------------

### Accessing Parse Jobs Resource

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Example of how to access the `parse_jobs` resource to create and retrieve document parsing jobs.

```python
from landingai_ade import LandingAIADE

client = LandingAIADE()
job = client.parse_jobs.create(document=Path("document.pdf"), model="dpt-2-latest")
status = client.parse_jobs.get(job.job_id)
```

--------------------------------

### Create and monitor job

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/parse_jobs.md

Example of creating a parse job, monitoring its status, and retrieving results upon completion.

```python
from pathlib import Path
from landingai_ade import LandingAIADE
import time

client = LandingAIADE()

# Create and monitor job
job = client.parse_jobs.create(
    document=Path("large.pdf"),
    model="dpt-2-latest"
)
job_id = job.job_id

# Poll for completion
while True:
    job_status = client.parse_jobs.get(job_id)
    print(f"Status: {job_status.status}, Progress: {job_status.progress*100:.1f}%")
    
    if job_status.status == "completed":
        print(f"Chunks: {job_status.data.chunks}")
        print(f"Markdown length: {len(job_status.data.markdown)} characters")
        break
    elif job_status.status in ["failed", "cancelled"]:
        break
    
    time.sleep(5)  # Wait before next check
```

--------------------------------

### Async Client Usage

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of using the asynchronous client with default httpx.

```python
import os
import asyncio
from pathlib import Path
from landingai_ade import AsyncLandingAIADE

client = AsyncLandingAIADE(
    apikey=os.environ.get("VISION_AGENT_API_KEY"),  # This is the default and can be omitted
    # defaults to "production".
    environment="eu",
)


async def main() -> None:
    response = await client.parse(
        document=Path("path/to/file"),
        model="dpt-2-latest",
    )
    print(response.chunks)


asyncio.run(main())
```

--------------------------------

### NotFoundError Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Shows how to catch and handle a NotFoundError (404) when a requested resource, like a job ID, does not exist or has been deleted.

```python
class NotFoundError(APIStatusError):
    status_code: Literal[404] = 404
```

```python
from landingai_ade import NotFoundError

job_id = "invalid-job-id"
try:
    status = client.parse_jobs.get(job_id)
except NotFoundError as e:
    print(f"Job {job_id} not found")
    # List jobs to find valid IDs
    jobs = client.parse_jobs.list()
```

--------------------------------

### Custom Content-Type Handling

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to specify a custom MIME type for file uploads.

```python
client.parse(document=("file.bin", file_contents, "application/octet-stream"))
```

--------------------------------

### Parse a document

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of how to use the LandingAIADE client to parse a local document.

```python
import os
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE(
    apikey=os.environ.get("VISION_AGENT_API_KEY"),  # This is the default and can be omitted
    # defaults to "production".
    environment="eu",
)

response = client.parse(
    # use document= for local files, document_url= for remote URLs
    document=Path("path/to/file"),
    model="dpt-2-latest",
    save_to="./output_folder",  # optional: saves as {input_file}_parse_output.json
)
print(response.chunks)
```

--------------------------------

### RateLimitError Example with Backoff

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Demonstrates how to handle a RateLimitError (429) by implementing an exponential backoff strategy for retries.

```python
class RateLimitError(APIStatusError):
    status_code: Literal[429] = 429
```

```python
from landingai_ade import RateLimitError
import time

def parse_with_backoff(file_path, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.parse(document=file_path, model="dpt-2-latest")
        except RateLimitError as e:
            if attempt < max_retries - 1:
                # Exponential backoff: 2s, 4s, 8s, 16s
                wait_time = 2 ** (attempt + 1)
                print(f"Rate limited. Waiting {wait_time}s before retry...")
                time.sleep(wait_time)
            else:
                raise

response = parse_with_backoff(Path("file.pdf"))
```

--------------------------------

### Example: InvoiceData schema conversion and extraction

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/lib.md

Demonstrates defining a Pydantic model for invoice data, converting it to a JSON schema, and using it with the ADE extract endpoint.

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

# Define your data schema
class InvoiceData(BaseModel):
    invoice_number: str = Field(description="Invoice identifier")
    vendor_name: str = Field(description="Company or person issuing invoice")
    total_amount: float = Field(description="Total amount in currency")
    due_date: str = Field(description="Date payment is due (YYYY-MM-DD format)")
    line_items: list[str] = Field(description="List of itemized charges")

# Convert to JSON schema
schema_json = pydantic_to_json_schema(InvoiceData)
print(schema_json)
# Output: {"type": "object", "properties": {"invoice_number": {...}, ...}, ...}

# Use with extract endpoint
client = LandingAIADE()
response = client.extract(
    schema=schema_json,
    markdown=Path("invoice.md"),
    model="extract-latest"
)

# Results are validated against your schema
data = response.extraction  # Dict with keys matching InvoiceData fields
```

--------------------------------

### Async Client with aiohttp

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of using the asynchronous client with aiohttp as the HTTP backend.

```sh
# install from PyPI
pip install landingai-ade[aiohttp]
```

```python
import os
import asyncio
from pathlib import Path
from landingai_ade import DefaultAioHttpClient
from landingai_ade import AsyncLandingAIADE


async def main() -> None:
    async with AsyncLandingAIADE(
        apikey=os.environ.get("VISION_AGENT_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.parse(
            document=Path("path/to/file"),
            model="dpt-2-latest",
        )
        print(response.chunks)


asyncio.run(main())
```

--------------------------------

### Streaming Response Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Demonstrates how to use `.with_streaming_response` to stream the response body and iterate over lines.

```python
with client.with_streaming_response.parse() as response:
    print(response.headers.get("X-My-Header"))

    for line in response.iter_lines():
        print(line)
```

--------------------------------

### Split a document

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of how to use the LandingAIADE client to parse a document and then define split rules.

```python
import json
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Parse the document
parse_response = client.parse(
    document=Path("/path/to/document.pdf"),
    model="dpt-2-latest"
)

# Define Split Rules
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"
    }
]
```

--------------------------------

### PermissionDeniedError Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle a PermissionDeniedError (403) when an API key lacks necessary permissions or violates organizational policies.

```python
class PermissionDeniedError(APIStatusError):
    status_code: Literal[403] = 403
```

```python
from landingai_ade import PermissionDeniedError

try:
    response = client.extract_build_schema(...)
except PermissionDeniedError as e:
    print("Permission denied. This feature may not be enabled for your account.")
    print("Contact support: support@landing.ai")
```

--------------------------------

### Schema Resolution Example with Nested Models

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/lib.md

Illustrates how `pydantic_to_json_schema` resolves nested Pydantic models into a flat JSON schema.

```python
from pydantic import BaseModel, Field

class Address(BaseModel):
    street: str
    city: str
    zip_code: str

class Person(BaseModel):
    name: str = Field(description="Full name")
    age: int = Field(ge=0, le=150)
    address: Address = Field(description="Residential address")

schema_json = pydantic_to_json_schema(Person)
# The returned schema has Address fully expanded inline, not as a $ref
```

--------------------------------

### Copy / Clone Client with Different Options

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Shows how to create new client instances with modified options based on an existing client.

```python
from landingai_ade import LandingAIADE

# Original client
client = LandingAIADE(apikey="key1", environment="production")

# Create variant with different timeout
fast_client = client.with_options(timeout=30.0)
slow_client = client.with_options(timeout=1200.0)

# Create variant with different API key
test_client = client.with_options(apikey="test-key")

# Create variant with different environment
eu_client = client.with_options(environment="eu")

# Chain multiple options
special_client = client.with_options(
    timeout=600.0,
    max_retries=5,
    default_headers={"X-Special": "true"}
)
```

--------------------------------

### Using .env File for Configuration

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Demonstrates how to use a .env file to load environment variables for SDK configuration.

```dotenv
VISION_AGENT_API_KEY=your-api-key-123
LANDINGAI_ADE_BASE_URL=https://api.va.eu-west-1.landing.ai
LANDINGAI_ADE_LOG=debug
```

```python
from dotenv import load_dotenv
from landingai_ade import LandingAIADE

load_dotenv()  # Reads .env file
client = LandingAIADE()  # Uses environment variables
```

--------------------------------

### Extract Data Example

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Example of extracting data based on a Pydantic schema.

```python
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 schema
class Person(BaseModel):
    name: str = Field(description="Person's name")
    age: int = Field(description="Person's age")

# Convert to JSON schema
schema = pydantic_to_json_schema(Person)
# Use with the SDK
client = LandingAIADE(apikey=os.environ.get("VISION_AGENT_API_KEY"))
response = client.extract(
    schema=schema,
    # use markdown= for local files, markdown_url= for remote URLs
    markdown=Path("path/to/file.md"),
    save_to="./output_folder",  # optional: saves as {input_file}_extract_output.json
)
```

--------------------------------

### Client Copy/WithOptions

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Creates a new client instance with modified options.

```python
def copy(
    self,
    *,
    apikey: str | None = None,
    environment: Literal["production", "eu"] | None = None,
    base_url: str | httpx.URL | None = None,
    timeout: float | Timeout | None | NotGiven = not_given,
    http_client: httpx.Client | None = None,
    max_retries: int | NotGiven = not_given,
    default_headers: Mapping[str, str] | None = None,
    set_default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    set_default_query: Mapping[str, object] | None = None,
) -> LandingAIADE

```

```python
client = LandingAIADE()

# Higher timeout for large files
large_file_client = client.with_options(timeout=600.0)
response = large_file_client.parse(document=Path("large.pdf"), model="dpt-2-latest")

# Different retry settings
no_retry_client = client.with_options(max_retries=0)

```

--------------------------------

### LandingAIADE Constructor

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Demonstrates different ways to initialize the LandingAIADE client, including using environment variables, explicit API keys, specifying the environment, and setting custom timeouts and retry counts.

```python
from landingai_ade import LandingAIADE

# Basic initialization with environment variable
client = LandingAIADE()

# Or with explicit API key
client = LandingAIADE(apikey="your-api-key")

# Use EU endpoint
client = LandingAIADE(apikey="your-api-key", environment="eu")

# Custom timeout and retries
client = LandingAIADE(apikey="your-api-key", timeout=30.0, max_retries=5)
```

--------------------------------

### Determining Installed Version

Source: https://github.com/landing-ai/ade-python/blob/main/README.md

Provides the code to check the currently installed version of the landingai_ade library.

```python
import landingai_ade
print(landingai_ade.__version__)
```

--------------------------------

### Using Environment Variables Directly

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Shows how to set environment variables directly in the shell for SDK configuration.

```bash
export VISION_AGENT_API_KEY="your-api-key"
export LANDINGAI_ADE_BASE_URL="https://api.va.eu-west-1.landing.ai"
python your_script.py
```

--------------------------------

### Retrieve Specific Parse Job Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to retrieve the status and results of a specific parse job using its job ID.

```bash
curl -X GET https://api.va.landing.ai/v1/ade/parse/jobs/job-12345 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Context Manager Support

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Shows how to use the client with a context manager for automatic resource cleanup.

```python
from landingai_ade import LandingAIADE

with LandingAIADE() as client:
    response = client.parse(document=Path("file.pdf"), model="dpt-2-latest")
    # HTTP connections closed automatically on exit

```

--------------------------------

### Logging Configuration

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Shows how to enable SDK logging, either through an environment variable or programmatically.

```python
import logging
import os

# Enable SDK logging
os.environ["LANDINGAI_ADE_LOG"] = "info"

# Or configure logging programmatically
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("landingai_ade")
logger.setLevel(logging.DEBUG)

from landingai_ade import LandingAIADE
client = LandingAIADE()
response = client.parse(...)  # Logs all requests/responses
```

--------------------------------

### Prefix any method call to get the raw httpx.Response object instead of parsed content.

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/parse_jobs.md

Demonstrates how to use `with_raw_response` to get the raw HTTP response object.

```python
from landingai_ade import LandingAIADE

client = LandingAIADE()
raw_response = client.parse_jobs.with_raw_response.get("job-123")
print(raw_response.status_code)
print(raw_response.headers)
parsed = raw_response.parse()  # Get parsed response
```

--------------------------------

### POST /v1/ade/extract cURL Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to use the POST /v1/ade/extract endpoint with cURL to extract structured data from Markdown using a JSON schema.

```bash
curl -X POST https://api.va.landing.ai/v1/ade/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'schema={"type":"object","properties":{"name":{"type":"string"}}}' \
  -F "markdown=@/path/to/document.md"
```

--------------------------------

### Version Detection

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Shows how to retrieve the SDK version and perform runtime version checks.

```python
import landingai_ade

# Get SDK version
print(landingai_ade.__version__)  # e.g., "1.12.0"
print(landingai_ade.__title__)    # "landingai-ade"

# Check version at runtime
from packaging import version
min_version = version.parse("1.10.0")
current = version.parse(landingai_ade.__version__)
if current < min_version:
    print("Update SDK to use this feature")
```

--------------------------------

### UnprocessableEntityError Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Provides an example of catching an UnprocessableEntityError (422), typically raised when schema validation fails or unsupported fields are used with strict mode enabled.

```python
class UnprocessableEntityError(APIStatusError):
    status_code: Literal[422] = 422
```

```python
from landingai_ade import UnprocessableEntityError

try:
    response = client.extract(
        schema='{"type":"object","properties":{"id":{"type":"string"}}}',
        markdown=Path("file.md"),
        strict=True
    )
except UnprocessableEntityError as e:
    print(f"Schema validation failed: {e.message}")
    # Try with strict=False to allow missing fields
    response = client.extract(
        schema=schema,
        markdown=Path("file.md"),
        strict=False  # Prune unsupported fields
    )
```

--------------------------------

### APIConnectionError handling

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of how to catch and handle `APIConnectionError`.

```python
from landingai_ade import APIConnectionError

try:
    response = client.parse(document=Path("file.pdf"))
except APIConnectionError as e:
    print(f"Connection failed: {e.message}")
    print("Check your internet connection and firewall settings")
    # Can retry
    import time
    time.sleep(5)
    response = client.parse(document=Path("file.pdf"))
```

--------------------------------

### Context Manager / Resource Management

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Illustrates using the LandingAIADE client as a context manager for automatic cleanup of HTTP connections, and also shows manual closing.

```python
from landingai_ade import LandingAIADE
from pathlib import Path

# Automatic cleanup with context manager
with LandingAIADE() as client:
    response = client.parse(
        document=Path("file.pdf"),
        model="dpt-2-latest"
    )
# HTTP connections closed automatically

# Or manually close
client = LandingAIADE()
try:
    response = client.parse(
        document=Path("file.pdf"),
        model="dpt-2-latest"
    )
finally:
    client.close()  # Explicitly close connections
```

--------------------------------

### Using aiohttp for Async

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Demonstrates how to use aiohttp for asynchronous HTTP requests with the AsyncLandingAIADE client.

```python
import asyncio
from landingai_ade import AsyncLandingAIADE, DefaultAioHttpClient

async def main():
    # aiohttp client for better async concurrency
    async with AsyncLandingAIADE(
        http_client=DefaultAioHttpClient()
    ) as client:
        response = await client.parse(...)

asyncio.run(main())
```

--------------------------------

### Configure Client

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/README.md

Initialize the LandingAIADE client with custom API key, environment, timeout, and maximum retries.

```python
client = LandingAIADE(
    apikey="your-key",
    environment="eu",
    timeout=600.0,
    max_retries=5
)
```

--------------------------------

### Import and Initialize

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/README.md

Import the LandingAIADE client and initialize it. By default, it uses the VISION_AGENT_API_KEY environment variable for authentication.

```python
from landingai_ade import LandingAIADE
from pathlib import Path

client = LandingAIADE()  # Uses VISION_AGENT_API_KEY env var
```

--------------------------------

### Basic Configuration

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Minimal configuration using environment variables or an explicit API key.

```python
from landingai_ade import LandingAIADE

# Minimal - uses VISION_AGENT_API_KEY environment variable
client = LandingAIADE()

# Explicit API key
client = LandingAIADE(apikey="your-api-key")
```

--------------------------------

### Response Validation

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Demonstrates how to enable strict response validation when initializing the LandingAIADE client.

```python
from landingai_ade import LandingAIADE, APIResponseValidationError

# Enable strict response validation
client = LandingAIADE(_strict_response_validation=True)

try:
    response = client.parse(document=Path("file.pdf"))
except APIResponseValidationError as e:
    print(f"Response validation failed: {e.message}")
```

--------------------------------

### APITimeoutError handling

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of how to catch and handle `APITimeoutError` and retry with an increased timeout.

```python
from landingai_ade import APITimeoutError

try:
    response = client.parse(document=Path("large_file.pdf"))
except APITimeoutError as e:
    print("Request timed out. Trying with longer timeout...")
    # Retry with increased timeout
    response = client.with_options(timeout=1800.0).parse(
        document=Path("large_file.pdf")
    )
```

--------------------------------

### InternalServerError (5xx)

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of how to catch and handle `InternalServerError` with custom retry logic.

```python
from landingai_ade import InternalServerError
import time

def parse_with_retry(file_path, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.parse(document=file_path, model="dpt-2-latest")
        except InternalServerError as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"Server error. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                print("Server error persists. Try again later.")
                raise

response = parse_with_retry(Path("file.pdf"))
```

--------------------------------

### Providing API Key

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Demonstrates three methods for providing the API key to the LandingAIADE client.

```python
# Method 1: Constructor parameter
from landingai_ade import LandingAIADE
client = LandingAIADE(apikey="your-api-key")

# Method 2: Environment variable
import os
os.environ["VISION_AGENT_API_KEY"] = "your-api-key"
client = LandingAIADE()  # Reads from env

# Method 3: .env file with python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = LandingAIADE()
```

--------------------------------

### Async Context Manager

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Demonstrates using the AsyncLandingAIADE client as an asynchronous context manager for automatic connection cleanup.

```python
import asyncio
from pathlib import Path
from landingai_ade import AsyncLandingAIADE

async def main():
    async with AsyncLandingAIADE() as client:
        response = await client.parse(
            document=Path("file.pdf"),
            model="dpt-2-latest"
        )
    # Connections closed automatically

asyncio.run(main())
```

--------------------------------

### AsyncLandingAIADE with aiohttp

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Configures the asynchronous client to use aiohttp for better concurrency.

```python
from landingai_ade import AsyncLandingAIADE, DefaultAioHttpClient

async def main():
    async with AsyncLandingAIADE(
        http_client=DefaultAioHttpClient()
    ) as client:
        response = await client.parse(document=Path("file.pdf"), model="dpt-2-latest")

```

--------------------------------

### Increasing Request Timeout

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/endpoints.md

Example of how to increase the default request timeout for large documents.

```python
client = LandingAIADE(timeout=1200.0)  # 20 minutes
```

--------------------------------

### Environment Selection

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/configuration.md

Selecting between production and EU environments, or overriding the base URL.

```python
from landingai_ade import LandingAIADE

# Use EU endpoint
client = LandingAIADE(environment="eu")

# Use production (default)
client = LandingAIADE(environment="production")

# Override base URL entirely
client = LandingAIADE(base_url="https://custom.api.example.com")
```

--------------------------------

### Handling AuthenticationError

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of catching AuthenticationError and providing fallback mechanisms for API key provision.

```python
from landingai_ade import AuthenticationError, LandingAiadeError

try:
    client = LandingAIADE(apikey="invalid-key")
    response = client.parse(document=Path("file.pdf"))
except AuthenticationError as e:
    print("Authentication failed. Check your API key.")
    print(f"Details: {e.message}")
except LandingAiadeError as e:
    if "apikey" in str(e).lower():
        print("API key must be provided")
        # Get from environment or config
```

--------------------------------

### Handling BadRequestError

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/errors.md

Example of catching BadRequestError and checking for specific causes like missing parameters.

```python
from landingai_ade import BadRequestError
from pathlib import Path

try:
    # Missing document parameter
    response = client.parse(model="dpt-2-latest")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
    # Check request validation:
    if "document" in e.message:
        print("Provide either document or document_url")
```

--------------------------------

### Section API

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/client.md

Parses Markdown into a hierarchical table of contents.

```python
def section(
    *,
    guidelines: Optional[str] | Omit = omit,
    markdown: Union[FileTypes, str, None] | Omit = omit,
    markdown_url: Optional[str] | Omit = omit,
    model: Optional[str] | Omit = omit,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> SectionResponse

```

```python
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Get table of contents from parsed markdown
parse_response = client.parse(document=Path("document.pdf"), model="dpt-2-latest")

section_response = client.section(
    markdown=parse_response.markdown,
    guidelines="Group by main topics, then subtopics"
)

for toc in section_response.table_of_contents:
    indent = "  " * (toc.level - 1)
    print(f"{indent}[{toc.section_number}] {toc.title}")

```

--------------------------------

### Type Validation Example

Source: https://github.com/landing-ai/ade-python/blob/main/_autodocs/api-reference/lib.md

Demonstrates the type validation performed by `pydantic_to_json_schema`.

```python
# This works
class MySchema(BaseModel):
    field: str

schema_json = pydantic_to_json_schema(MySchema)  # ✓

# This fails
schema_json = pydantic_to_json_schema(dict)  # ✗ TypeError
```