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(), rate_answer(), withdraw_answer_feedback(), get_answer_ratings(), 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.16.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.16.0
File Size Uploaded Provenance Actions
assistant_runtime_sdk-1.16.0.tar.gz 76.5 kB Without provenance Details for assistant_runtime_sdk-1.16.0.tar.gz

Built distribution (wheel)

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

Total release size: 155.4 kB

Release files / assistant_runtime_sdk-1.16.0.tar.gz

Download URL assistant_runtime_sdk-1.16.0.tar.gz
Size 76.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fcf96279ba773a7a64ea3896535510a9f9cacda61b43d4dafac33e1e3c02d4e3
BLAKE2b-256 checksum
How to use checksums
87e774257a4086bfc55034693c5c99ff10963c6b0974fc18b3a43566fdfe5efd
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.16.0-py3-none-any.whl

Download URL assistant_runtime_sdk-1.16.0-py3-none-any.whl
Size 78.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
92b9b3ca3f1f71abd9d70dbe7bff024499ce71b4529af3404633f131736f622d
BLAKE2b-256 checksum
How to use checksums
991722f67dad2665984f51d4536da0c7285f05fd08e055599f617bb124ef2132
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.16.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