Metadata-Version: 2.4
Name: eigenpal
Version: 0.10.2
Summary: Official Python SDK for the EigenPal API
Project-URL: Homepage, https://eigenpal.com
Project-URL: Documentation, https://github.com/eigenpal/sdk-python#readme
Project-URL: Repository, https://github.com/eigenpal/sdk-python
Project-URL: Issues, https://github.com/eigenpal/sdk-python/issues
Project-URL: Changelog, https://github.com/eigenpal/sdk-python/blob/main/CHANGELOG.md
Author-email: EigenPal <support@eigenpal.com>
Maintainer-email: EigenPal <support@eigenpal.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,api,automation,client,document-extraction,document-understanding,eigenpal,llm,ocr,sdk,workflow,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: attrs>=21.3.0
Requires-Dist: httpx<0.30.0,>=0.24.0
Requires-Dist: python-dateutil>=2.8.0
Description-Content-Type: text/markdown

# eigenpal

Trigger and inspect Eigenpal automations from Python.

[![pypi](https://img.shields.io/pypi/v/eigenpal?color=3B5BDB&labelColor=555&label=pypi)](https://pypi.org/project/eigenpal/)
[![downloads](https://img.shields.io/pypi/dm/eigenpal?color=3B5BDB&labelColor=555&label=downloads)](https://pypi.org/project/eigenpal/)
[![license](https://img.shields.io/badge/license-Apache--2.0-3B5BDB?labelColor=555)](https://github.com/eigenpal/sdk-python/blob/main/LICENSE)

## Install

```bash
pip install eigenpal
```

Requires Python 3.9+. Get an API key at **studio.eigenpal.com -> Settings -> API Keys**.

## Quick Start

```python
import os
from pathlib import Path
from eigenpal import EigenpalClient

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

result = client.run_and_wait(
    "workflows.extract-invoice",
    input={"contract_document": Path("contract.pdf")},
)

print(result.finished, result.output)
```

`target` is always typed: `workflows.<slug>` or `agents.<slug>`. That keeps workflow and agent slugs unambiguous.

## Automations

Workflows and agents are exposed as automations.

```python
listing = client.automations.list(search="invoice")
automation = client.automations.get("workflows.extract-invoice")
versions = client.automations.versions("workflows.extract-invoice")
triggers = client.automations.triggers("workflows.extract-invoice")
```

## Runs

```python
started = client.run("agents.invoice-agent", input={"invoice": Path("invoice.pdf")})

run = client.runs.get(started.id, expand=["usage", "execution"])
usage = client.runs.usage(started.id)
steps = client.runs.steps(started.id)
events = client.runs.events(started.id)
trace = client.runs.trace.get(started.id)

client.runs.cancel(started.id)
client.rerun(started.id, wait_for_completion=60)
```

List calls use the same run API for workflows, agents, manual runs, and eval runs:

```python
recent_failures = client.runs.list(
    type="workflow",
    status="failed,cancelled",
    limit=50,
)
```

## Files And Artifacts

Use `client.files` for reusable upload-first blobs. When referenced by a run input, Eigenpal snapshots the file into run-scoped artifacts.

```python
uploaded = client.files.upload(Path("contract.pdf"))

started = client.run(
    "workflows.extract-invoice",
    input={"contract_document": {"fileId": uploaded.id}},
)

artifacts = client.runs.artifacts.list(started.id)
content = client.runs.artifacts.download(started.id, artifacts.artifacts[0].path)
```

You can also pass a `Path`, file handle, or `{"content": bytes, "filename": str, "mime_type": str}` directly to `client.run`; the SDK sends multipart form data automatically.

## Errors

Every non-2xx response raises a typed subclass of `EigenpalError`:

| HTTP    | Class                     |
| ------- | ------------------------- |
| 400     | `EigenpalValidationError` |
| 401     | `EigenpalAuthError`       |
| 403     | `EigenpalForbiddenError`  |
| 404     | `EigenpalNotFoundError`   |
| 429     | `EigenpalRateLimitError`  |
| 5xx     | `EigenpalServerError`     |
| timeout | `EigenpalTimeoutError`    |

## Reference

| Topic                                     | What is in it                                                      |
| ----------------------------------------- | ------------------------------------------------------------------ |
| [Automations](./docs/workflows.md)        | List, inspect, versions, triggers.                                 |
| [Runs](./docs/executions.md)              | Start, poll, cancel, rerun, usage, steps, events, traces, reviews. |
| [File inputs](./docs/files.md)            | Multipart upload from Path, file handle, or bytes.                 |
| [Errors](./docs/errors.md)                | Typed exceptions, retries, request ids.                            |
| [Configuration](./docs/configuration.md)  | API key, base_url, timeouts, headers.                              |
| [Full API reference](./docs/reference.md) | Every method, generated from OpenAPI.                              |

## License

Apache-2.0.
