Skip to content

feat(python): add AsyncInkbox awaitable client - #147

Open
ron-42 wants to merge 1 commit into
inkbox-ai:mainfrom
ron-42:feat/python-async-inkbox
Open

feat(python): add AsyncInkbox awaitable client#147
ron-42 wants to merge 1 commit into
inkbox-ai:mainfrom
ron-42:feat/python-async-inkbox

Conversation

@ron-42

@ron-42 ron-42 commented Aug 9, 2026

Copy link
Copy Markdown

Fixes #146

The gap

The Python SDK is sync-only (httpx.Client). TypeScript is natively await. Async Python agents — FastAPI webhooks, ASGI tunnels, browser-use — wrap every call by hand:

await asyncio.to_thread(identity.send_email, ...)

Miss one site and the event loop blocks. In-repo examples already do this boilerplate (examples/use-inkbox-browser-use).

What this PR adds

AsyncInkbox / AsyncAgentIdentity — same constructor kwargs and public surface as sync Inkbox / AgentIdentity, but awaitable:

from inkbox import AsyncInkbox

async with AsyncInkbox(api_key="ApiKey_...") as inkbox:
    identity = await inkbox.create_identity("support-bot")
    await identity.send_email(
        to=["user@example.com"],
        subject="Hello",
        body_text="Hi",
    )
  • Resource accessors (inkbox.messages, inkbox.vault, …) and nested objects return awaitable proxies.
  • Sync iterators (iter_emails, …) are drained off the event loop and returned as lists.
  • Escape hatches: inkbox.sync / identity.sync.
  • Signup classmethods (signup, verify_signup, …) are awaitable on AsyncInkbox.

Implementation note. REST still uses the sync client via asyncio.to_thread, so the event loop does not block without cloning every resource onto httpx.AsyncClient. True async I/O is a follow-up if thread-pool load becomes a problem (called out in the module docstring). Sync Inkbox is unchanged.

Verification

pytest tests/test_async_client.py
# 7 passed

Live smoke against a real org (admin key): whoami, get_identity, send_email (to self), iter_unread_emails, get_message, mark_emails_read, list_identities, messages.list, vault.info — all via await.

Mirrors sync Inkbox/AgentIdentity for asyncio agents without
blocking the event loop (to_thread hop; same public surface).
@ron-42

ron-42 commented Aug 14, 2026

Copy link
Copy Markdown
Author

Hi, @alex-w-99 @dimavrem22. Kindly review the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Python SDK needs an awaitable AsyncInkbox client

1 participant