Skip to main content

Assistant Runtime SDK

Python SDK for FAC Cloud — the AI assistant backend powering chat, streaming tool execution, memory, billing and workflows.

Features

  • Sync and async clients — AssistantRuntimeClient (requests) or AsyncAssistantRuntimeClient (aiohttp)
  • SSE streaming — real-time responses with live tool execution
  • HMAC authentication — signed requests, no bearer tokens to leak
  • Auto model selection — routing with cross-provider fallback
  • Broad API coverage — chat, conversations, billing, memory, documents, workflows, users
  • Full type hints — annotated throughout for IDE support

Installation

pip install assistant-runtime-sdk           # sync client
pip install "assistant-runtime-sdk[async]"  # with async support
pip install "assistant-runtime-sdk[all]"    # everything, including dev tools

Requires Python 3.10+.

The distribution is named assistant-runtime-sdk; the import name is assistant_runtime_sdk. PyPI normalises underscores to hyphens, so both spellings resolve on install.

Quick start

Sync client

from assistant_runtime_sdk import AssistantRuntimeClient

client = AssistantRuntimeClient(
    tenant_id="your-tenant-id",
    tenant_secret="your-secret",
    ar_url="https://api.fac-cloud.com",
)

models = client.list_available_models()
for model in models.get("models", []):
    print(f"{model['model_id']} - {model['display_name']}")

for event in client.stream_chat(
    session_id="session-123",
    message="What can you help me with?",
    user_id="user@example.com",
    model_id="auto",
):
    if event["event"] == "stream_chunk":
        print(event["data"].get("content", ""), end="", flush=True)
    elif event["event"] == "stream_complete":
        print(f"\n\nTokens used: {event['data'].get('tokens_used')}")

Async client

import asyncio
from assistant_runtime_sdk import AsyncAssistantRuntimeClient

async def main():
    async with AsyncAssistantRuntimeClient(
        tenant_id="your-tenant-id",
        tenant_secret="your-secret",
        ar_url="https://api.fac-cloud.com",
    ) as client:
        async for event in client.stream_chat(
            session_id="session-123",
            message="Hello!",
            user_id="user@example.com",
        ):
            if event["event"] == "stream_chunk":
                print(event["data"].get("content", ""), end="")

asyncio.run(main())

Custom logger

import logging
from assistant_runtime_sdk import AssistantRuntimeClient

logging.basicConfig(level=logging.DEBUG)

client = AssistantRuntimeClient(
    tenant_id="your-tenant-id",
    tenant_secret="your-secret",
    logger=logging.getLogger("my_app.assistant"),
)

SSE event types

Event Description
stream_start Stream initialised
stream_chunk Text chunk from the model
stream_complete Full response with metrics
stream_error Error occurred
thinking Reasoning content
tool_call_start Tool execution beginning
tool_call_result Tool execution complete
approval_required Human approval needed
tool_cancelled Tool was rejected
model_fallback Auto mode selected a different model
rate_limited All models rate limited

API reference

AssistantRuntimeClient and AsyncAssistantRuntimeClient expose the same surface. A representative selection:

Chat — stream_chat(session_id, message, user_id, context=None, model_id=None, attachments=None, ...)

Models — list_available_models(), get_available_models(), set_preferred_model(model_id)

Tenant — get_tenant_info(), get_terms_status(), accept_terms(...), heartbeat()

Conversations — list_conversations(), get_conversation(), get_messages(), create_message(), update_conversation(), delete_conversation(), delete_message()

Billing — get_plan_comparison(), get_usage_dashboard(), get_usage_history(), get_credit_balance(), initiate_checkout(), create_hosted_checkout(), get_checkout_session_status(), verify_checkout(), upgrade_plan(), cancel_subscription(), get_invoices(), get_payment_instrument(), update_payment_method()

Users & seats — register_user(), get_user(), list_users(), invite_user(), add_user_seat(), set_user_credit_limit(), get_user_auth_status()

MCP servers & tools — get_user_mcp_servers(), add_user_mcp_server(), update_mcp_server_tokens(), remove_user_mcp_server(), list_tools(), set_tool_preference()

Memory & documents — list_memories(), update_memory(), delete_memory(), upload_document(), list_documents(), get_document_content(), get_storage_info()

Workflows — list_workflows(), create_workflow(), execute_workflow(), list_workflow_runs(), set_workflow_schedule()

Support & feedback — create_ticket(), list_tickets(), get_ticket_thread(), reply_to_ticket(), upload_ticket_attachment(), submit_feedback(), list_feedback(user_id)

Prompts — list_prompts(user_id), get_prompt(prompt_name, arguments=None)

See docs/ for the full reference.

Standalone functions

from assistant_runtime_sdk import get_terms, register_tenant

terms = get_terms("https://api.fac-cloud.com")

result = register_tenant(
    ar_url="https://api.fac-cloud.com",
    site_url="https://mysite.example.com",
    owner_email="admin@example.com",
    application_id="your-application-id",
    terms_accepted=True,
    terms_version="1.0",
    accepted_by="admin@example.com",
)

Exceptions

from assistant_runtime_sdk import (
    ARError,                    # base exception
    ARAuthenticationError,      # HMAC signature rejected
    ARRateLimitError,           # rate limited (carries retry_after)
    ARStreamError,              # SSE streaming failure
    ARConfigurationError,       # invalid configuration
    ARConnectionError,          # transport failure
    ARTimeoutError,             # request timed out
    ARAPIError,                 # non-2xx API response
    ARBillingUnavailableError,  # billing companion not installed
)

Using it from a Frappe app

The SDK is plain Python with no Frappe dependency. To use it inside a Frappe application, wrap it in a thin adapter that supplies credentials and a logger:

import frappe
from assistant_runtime_sdk import AssistantRuntimeClient

class FrappeLogger:
    def error(self, msg, *args, **kwargs):
        frappe.log_error(msg, kwargs.get("category", "Assistant Runtime"))

def get_client(settings):
    return AssistantRuntimeClient(
        tenant_id=settings.tenant_id,
        tenant_secret=settings.get_password("tenant_secret"),
        ar_url=settings.ar_url,
        logger=FrappeLogger(),
    )

Releasing

See docs/guides/releasing.md.

License

GNU Affero General Public License v3.0

Copyright (C) 2025 Paul Clinton

Metadata

Release files for assistant-runtime-sdk 1.15.0

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

Source distribution (sdist)

Source distribution for assistant-runtime-sdk 1.15.0
File Size Uploaded Provenance Actions
assistant_runtime_sdk-1.15.0.tar.gz 75.7 kB Without provenance Details for assistant_runtime_sdk-1.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for assistant-runtime-sdk 1.15.0
File Interpreter ABI Platform Actions
assistant_runtime_sdk-1.15.0-py3-none-any.whl Python 3 none any Details for assistant_runtime_sdk-1.15.0-py3-none-any.whl

Total release size: 153.8 kB

Release files / assistant_runtime_sdk-1.15.0.tar.gz

Download URL assistant_runtime_sdk-1.15.0.tar.gz
Size 75.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c56ea73241f332b09ee93516f92eb176d6646e9862d7972e8d14ebc24962d674
BLAKE2b-256 checksum
How to use checksums
9f59d7209c3746bda1a6a2a9fc4495e5bcb41c0b58f85b31e6215c89493fe8b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Release files / assistant_runtime_sdk-1.15.0-py3-none-any.whl

Download URL assistant_runtime_sdk-1.15.0-py3-none-any.whl
Size 78.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e0c76197cbebe9438c14a200ed51e70d0a4cfa7bc7f263a6b651129f53fb173
BLAKE2b-256 checksum
How to use checksums
8d2106f38c75208eb1d5015360761cf1f4c571d397b413f884e71b4fc4b3577e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Security for assistant-runtime-sdk 1.15.0

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