> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landing.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Library

> Process documents using the ADE Python library.

export const adePythonLibrary = 'ade-python';

export const dpt3pro = 'DPT-3 Pro';

export const ade = 'Agentic Document Extraction';

The [{adePythonLibrary}](https://github.com/landing-ai/ade-python) library wraps the {ade} APIs so you can parse and extract documents from Python. The library is published as the `landingai-ade` package and generated from the API specification.

The v2 APIs live under the `client.v2` sub-client (for example, `client.v2.parse`).

## Install the Library

Requires Python 3.9 or later.

```bash theme={null}
pip install landingai-ade
```

## Set Your API Key

The library reads your API key from the `VISION_AGENT_API_KEY` environment variable. [Generate an API key](./agentic-api-key) first, then set it using any of the methods below. Do not hard-code your API key in source files.

### Method 1: Set the API Key as an Environment Variable

1. Set the environment variable. To persist the key across sessions on macOS or Linux, add the `export` command to your shell profile (`.zshrc` or `.bashrc`), then run `source ~/.zshrc`.

   <CodeGroup>
     ```bash macOS/Linux theme={null}
     export VISION_AGENT_API_KEY="<your-api-key>"
     ```

     ```cmd Windows (Command Prompt) theme={null}
     set "VISION_AGENT_API_KEY=<your-api-key>"
     ```

     ```powershell Windows (PowerShell) theme={null}
     $env:VISION_AGENT_API_KEY="<your-api-key>"
     ```
   </CodeGroup>
2. Initialize the client. It reads the `VISION_AGENT_API_KEY` environment variable automatically:
   ```python theme={null}
   from landingai_ade import LandingAIADE

   client = LandingAIADE()
   ```

### Method 2: Store the API Key in a .env File

Store your API key in a `.env` file. The library reads the key from the environment; it does not load `.env` files on its own, so use `python-dotenv` to load the file.

1. Install the `python-dotenv` package:
   ```bash theme={null}
   pip install python-dotenv
   ```
2. Create a `.env` file in your project root and add your API key:
   ```bash theme={null}
   VISION_AGENT_API_KEY=<your-api-key>
   ```
3. Load the `.env` file before you initialize the client:
   ```python theme={null}
   from dotenv import load_dotenv
   from landingai_ade import LandingAIADE

   load_dotenv()  # Populates the environment from .env.

   client = LandingAIADE()
   ```

### Method 3: Set the API Key in a Notebook

In IPython-based notebooks (Jupyter, JupyterLab, Google Colab, or Kaggle), set the key for the current session with the `%env` magic command. The key is cleared when the kernel restarts, and it is visible in the notebook file if you share or commit it.

1. In a notebook cell, set the environment variable:
   ```python theme={null}
   %env VISION_AGENT_API_KEY=<your-api-key>
   ```
2. Initialize the client in a later cell:
   ```python theme={null}
   from landingai_ade import LandingAIADE

   client = LandingAIADE()
   ```

### API Key Precedence

If the API key is set in more than one place, the library resolves it in this order (the first match wins):

1. The `apikey` passed to the client constructor.
2. The `VISION_AGENT_API_KEY` environment variable, whether you set it directly or loaded it from a `.env` file. A value already set in your environment is not overridden by a `.env` file.

For help with missing-key errors, keys that fail to load, or keys that resolve to the wrong account, see [Troubleshoot API Key Issues](./agentic-api-key#troubleshoot-api-key-issues).

## Initialize the Client

Create a client. It reads `VISION_AGENT_API_KEY` from the environment automatically.

```python theme={null}
from landingai_ade import LandingAIADE

client = LandingAIADE()
```

By default, the library uses the US endpoints. If your API key is from the EU region, set the `environment` parameter to `eu`. API keys are region-specific: an EU key works only with the EU environment.

```python theme={null}
from landingai_ade import LandingAIADE

client = LandingAIADE(environment="eu")
```

For more about using {ade} in the EU, see [European Union (EU)](./eu).

## Parse a Document

Use `client.v2.parse` to convert a document into Markdown, a structure tree, and per-element grounding. Pass a local file as a `Path` with the `document` parameter, or a remote file with `document_url`.

```python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

response = client.v2.parse(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
)
print(response.markdown)
```

The response is a `V2ParseResponse` with `markdown`, `structure`, and `metadata`. For the full parameters and response shape, see [Parse Documents](./parse).

## Extract Data

Use `client.v2.extract` to pull structured fields from parsed Markdown. Provide the Markdown as a string with `markdown` (or a remote URL with `markdown_url`) and a schema. The `schema` parameter accepts a Pydantic model, a dictionary, or a JSON string.

```python theme={null}
from pathlib import Path
from pydantic import BaseModel, Field
from landingai_ade import LandingAIADE

class Financials(BaseModel):
    revenue: str = Field(description="Q1 2024 revenue")

client = LandingAIADE()

# Parse first to get Markdown, then extract.
parse_response = client.v2.parse(document=Path("document.pdf"), model="dpt-3-pro-latest")

extract_response = client.v2.extract(
    markdown=parse_response.markdown,
    schema=Financials,
)
print(extract_response.extraction)
```

The response is a `V2ExtractResult` with `extraction`, `extraction_metadata`, `markdown`, and `metadata`. For the full parameters and response shape, see [Extract Data](./extract).

## Process Documents Asynchronously

For large documents or long-running work, use the async jobs interface. The client exposes `parse_jobs` and `extract_jobs`, each with `create`, `get`, `list`, and `wait` methods. The `wait` method polls until the job reaches a terminal state and returns the finished job.

```python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(document=Path("document.pdf"))
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```

Set the optional `service_tier` parameter on `create` to `"priority"` for faster turnaround, or omit it to run on the `standard` tier. For the full workflow, service tiers, and saving output to a URL, see [Parse Asynchronously](./parse-async) and [Asynchronous Extraction](./extract-async).

## Set the Model Version

The `model` parameter is optional. When you omit it, the API uses the latest {dpt3pro} model. To pin a specific version, pass a model string such as `dpt-3-pro-latest` or a dated snapshot. See [Model Version](./parse-input#model-version).

```python theme={null}
from pathlib import Path

response = client.v2.parse(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
)
```

## Save Output to a File

Pass the optional `save_to` parameter on `parse` or `extract` to write the full response to a JSON file. Pass a directory to use an auto-generated file name, or a path ending in `.json` to choose the exact file. The async job `create` methods do not accept `save_to`.

```python theme={null}
from pathlib import Path

response = client.v2.parse(
    document=Path("document.pdf"),
    save_to="./output",
)
```

## Handle Errors

The synchronous `parse` and `extract` methods raise `V2SyncTimeoutError` if the request exceeds the server's synchronous time limit (HTTP 504). For large documents, use the async jobs interface instead.

When a parse partially succeeds (some pages fail), the API returns the full response with an HTTP 206 status, and the failed pages are listed in `metadata`. See [Troubleshoot Parsing](./parse-troubleshoot).

The job `wait` method returns the finished job regardless of outcome, so check `job.status`. To raise instead when a job fails, pass `raise_on_failure=True`, which raises `JobFailedError`. If a job does not finish within the `timeout`, `wait` raises `JobWaitTimeoutError`.

```python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE
from landingai_ade.lib.v2_errors import JobFailedError, JobWaitTimeoutError

client = LandingAIADE()

job = client.v2.parse_jobs.create(document=Path("document.pdf"))
try:
    done = client.v2.parse_jobs.wait(job.job_id, timeout=600, raise_on_failure=True)
    print(done.result.markdown)
except JobFailedError as error:
    print(f"Job failed: {error}")
except JobWaitTimeoutError:
    print("Job did not finish in time; poll again with parse_jobs.get().")
```

## Additional Resources

* [Python library on GitHub](https://github.com/landing-ai/ade-python). The README covers client configuration not documented here, including retries, timeouts, the async client, logging, raw response access, and custom requests.
* [API reference](https://docs.landing.ai/api-reference/parse/ade-parse)
* [Parse Documents](./parse) and [Extract Data](./extract)