Skip to main content

akribes

Pythonic async client for the Akribes workflow server.

Requires Python 3.10+.

Install

pip install akribes
# or with optional OpenTelemetry support:
pip install 'akribes[otel]'

Quick start

import asyncio
from akribes_sdk import AkribesClient

async def main():
    async with AkribesClient("https://akribes.example.com", token="akribes_tk_...") as client:
        proj = client.project(2)
        output = await proj.script("summarize").run_and_await(brief="explain quantum")
        print(output.execution_id, output.result)

asyncio.run(main())

Construction

import os
from datetime import timedelta
from akribes_sdk import AkribesClient, RetryPolicy

client = AkribesClient(
    "https://akribes.example.com",
    token=os.environ["AKRIBES_TOKEN"],
    timeout=timedelta(seconds=30),
    retry=RetryPolicy(max_attempts=4),      # retries transients + 429 by default
    otel=True,                               # opt-in OTel auto-instrumentation
)

Project handles

proj = client.project(2)                              # sync, lazy
proj = await client.get_project("podesta-staging")    # async, resolves name → id
sandbox = await client.sandbox()                       # per-user sandbox project

Typed inputs (codegen)

Generate typed ScriptType[I, O] stubs from a live server:

akribes types pull --project podesta --lang python --out src/akribes_types/

Then:

from akribes_types.podesta import summarize   # ScriptType[I, O] with typed input/output

out = await proj.run(summarize, brief="hi", tone="formal")
# IDE knows brief: str, tone: Literal["formal","casual"]
print(out.execution_id, out.result)

Streaming

run = await proj.executions.run_stream("summarize", brief="hi")
async for evt in run:
    match evt.kind:
        case "agent_chunk": print(evt.chunk, end="")
        case "task_end":    print(f"\n[task {evt.task!r} done]")
        case "error":       print(f"\n[error {evt.message}]")
output = await run.output()

Document ingest

from pathlib import Path

# One-liner
result = await proj.documents.ingest_and_wait(Path("invoice.pdf"))

# With progress
handle = proj.documents.ingest(Path("invoice.pdf"))
async for evt in handle:
    print(evt)
result = await handle.result()

Subscribe (long-lived events)

async with proj.events.subscribe(interests=[{"script_name": "summarize"}]) as sub:
    async for evt in sub:
        print(evt)

Heartbeat runs for the lifetime of the subscription only — not automatically on client construction.

Pagination

async for script in proj.scripts.list():
    print(script.name)

# Or materialise
scripts = await proj.scripts.list().to_list()
first   = await proj.scripts.list().first()
top10   = await proj.scripts.list().take(10)

Error handling

from akribes_sdk import (
    AkribesError, AuthError, NotFoundError, TransientError,
    RateLimitError, ScriptError, AkribesTimeoutError,
)

try:
    output = await proj.run_and_await("summarize", brief="hi")
except AuthError:        # 401/403
    ...
except NotFoundError:    # 404
    ...
except TransientError:   # 502/503 (retried by default)
    ...
except RateLimitError:   # 429 (retried by default, respects Retry-After)
    ...
except ScriptError as e: # workflow failed; e.error_kind, e.execution_id
    ...

Tokens

from datetime import timedelta
minted = await client.tokens.mint(
    scopes={"projects": "*", "role": "admin"},
    expires_in=timedelta(hours=8),
    label="web-session",
    user_email="alice@acme.com",
)
print(minted.token)   # ship to the browser

Authentication

AkribesClient accepts either a service token (long-lived, set via AKRIBES_SERVICE_TOKEN_<NAME>=<scope>:<secret> on the server) or a scoped token (akribes_tk_... — legacy aura_tk_... still accepted — minted via client.tokens.mint(...)).

Prefer Authorization: Bearer over ?token=… (#789)

AkribesClient always sends the token in the Authorization header for HTTP requests and WebSocket upgrades. The ?token=… query-string form exists only because browser EventSource / WebSocket constructors cannot set arbitrary headers — treat it as a browser-only escape hatch.

For CLIs, scripts, and backend services, avoid ?token=… because:

  • Reverse proxies, ingress controllers, and CDNs log the full URL (including the token) in access logs by default.
  • CI runners (Forgejo Actions, GitHub Actions) echo curl commands into job logs.
  • Browsers leak ?token= in the Referer header on cross-origin sub-resource requests.

The server stamps X-Token-Source: query-param on responses to any request that used the query fallback so operators can chart adoption.


See examples/ for runnable end-to-end demos.

Upgrading from v0.20.x? See MIGRATION-0.21.md.

License

MIT

Metadata

Release files for akribes 0.26.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for akribes 0.26.2
File Size Uploaded Provenance Actions
akribes-0.26.2.tar.gz 170.0 kB Without provenance Details for akribes-0.26.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for akribes 0.26.2
File Interpreter ABI Platform Actions
akribes-0.26.2-py3-none-any.whl Python 3 none any Details for akribes-0.26.2-py3-none-any.whl

Total release size: 283.2 kB

Release files / akribes-0.26.2.tar.gz

Download URL akribes-0.26.2.tar.gz
Size 170.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2b0bf2176ff5154ddcca6f463e00859e2e613c31ac6149ce239f3a4bf9e89153
BLAKE2b-256 checksum
How to use checksums
6ef22266de99cc3dddad88e018e93c930b2bd87fa81e009a82e6556e8ac3ac7d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / akribes-0.26.2-py3-none-any.whl

Download URL akribes-0.26.2-py3-none-any.whl
Size 113.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce59af7eb3f488eafe236e1184e6c2e1f26b18c0f3d4aacd8e2093dceca4d102
BLAKE2b-256 checksum
How to use checksums
e839a6881e584ec69b764321ddfb5440e74674d6b615dc9fcc2310101e572894
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for akribes 0.26.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page