eigenpal

Trigger and inspect Eigenpal automations from Python.

Install

pip install eigenpal

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

Quick Start

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 accepts a bare workflow ID such as wf_abc, or a typed target such as workflows.<id-or-slug> or agents.<slug>. Slugs need the prefix because workflow and agent slugs can overlap.

Automations

Workflows and agents are exposed as automations.

listing = client.automations.list(search="invoice", folder_id="fldr_…")
automation = client.automations.get("workflows.extract-invoice")
client.automations.move("workflows.extract-invoice", folder_path="billing/invoices")
client.automations.delete("workflows.extract-invoice")

list(folder_id="null") returns unfiled YAML workflows at the tenant root. Agent automations have no folder model.

Workflow delete archives the automations parent and keeps execution history. Agent delete removes the agent implementation and history, matching the dashboard, with best-effort leftover storage cleanup.

Folders

Workflow and template trees are a first-class resource. Nested agent directories in Git are source organization only.

tree = client.folders.list(type="workflow", tree="true")
folder = client.folders.create(name="invoices", type="workflow")
client.folders.update(folder.id, name="billing")
client.folders.delete(folder.id)  # unfiles workflows; does not delete them

Runs

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:

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.

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. Durable run inputs and dataset examples store scoped {"$file": "input/..."} artifact refs after ingestion.

Errors

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

Reference

License

Apache-2.0.