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.12.1

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.12.1
File Size Uploaded Provenance Actions
assistant_runtime_sdk-1.12.1.tar.gz 74.3 kB Without provenance Details for assistant_runtime_sdk-1.12.1.tar.gz

Built distribution (wheel)

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

Total release size: 151.0 kB

Release files / assistant_runtime_sdk-1.12.1.tar.gz

Download URL assistant_runtime_sdk-1.12.1.tar.gz
Size 74.3 kB
Tags Source
SHA-256 checksum
How to use checksums
47b59a6b396acad6ae044c593016134209eaaaa89b292efd25484c9c7ae2af6b
BLAKE2b-256 checksum
How to use checksums
791fb36881bda43df21c84e3c9336fec5db40a3a91ee9f970092360abd2529aa
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.12.1-py3-none-any.whl

Download URL assistant_runtime_sdk-1.12.1-py3-none-any.whl
Size 76.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7ae047daf0fa787fd4bcc097fe31a410b3c5132c3a9410929f2e0eee106bd960
BLAKE2b-256 checksum
How to use checksums
ab04b2ccc636b503f0b08a2f3c0f84c01c1fe80984d6d7182a45bb6e09c46f26
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.12.1

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