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

# Python SDK

> Trigger EigenPal workflows and agents from Python with the eigenpal package.

`eigenpal` is the official Python SDK. It is a typed wrapper over the EigenPal
API, generated from the OpenAPI spec. Source is open at
[github.com/eigenpal/sdk-python](https://github.com/eigenpal/sdk-python).

## Install

```bash theme={null}
pip install eigenpal
```

Requires Python 3.9+. Get an API key from the dashboard under
**Settings → API Keys**.

## Quick start

```python theme={null}
import os
from pathlib import Path
from eigenpal import EigenpalClient, EigenpalValidationError

client = EigenpalClient(api_key=os.environ["EIGENPAL_API_KEY"])

# Pass a Path / file handle / { content, filename, mime_type }. The SDK uploads
# the request as multipart/form-data, no base64 needed. `wait_for_completion`
# holds the request open (up to N seconds) and returns the finished run.
result = client.run(
    "workflows.extract-invoice",
    input={"contract_document": Path("contract.pdf")},
    wait_for_completion=60,
)

print(result["finished"], result["output"])
```

## Authentication

Pass the key explicitly, or set `EIGENPAL_API_KEY` and let the SDK pick it up:

```python theme={null}
client = EigenpalClient(api_key=os.environ["EIGENPAL_API_KEY"])
```

The `api_key` argument always wins over the environment fallback.

## Starting runs

`client.run(target, input=None, ...)` starts a workflow or agent. Targets are
strings like `workflows.extract-invoice` or `agents.invoice-agent`. Pass
`wait_for_completion=<seconds>` (or use `client.run_and_wait(...)`) to block until
the run finishes and return its result; omit it to enqueue and poll later with
`client.runs.get(id)`.

## Self-hosted

Point the SDK at your own deployment:

```python theme={null}
client = EigenpalClient(
    api_key=os.environ["EIGENPAL_API_KEY"],
    base_url=os.environ.get("EIGENPAL_BASE_URL", "https://eigenpal.acme.internal"),
)
```

`base_url` wins over the `EIGENPAL_BASE_URL` fallback and defaults to the hosted
cloud.

## Errors

Catch `EigenpalValidationError` when inputs do not match the workflow schema; it
carries the field-level detail so you can surface it to the caller.

See the [API reference](/api-reference) for the endpoints the SDK calls.