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) orAsyncAssistantRuntimeClient(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 isassistant_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
License
GNU Affero General Public License v3.0
Copyright (C) 2025 Paul Clinton
Metadata
Release files for assistant-runtime-sdk 1.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| assistant_runtime_sdk-1.14.0.tar.gz | 75.6 kB | Without provenance | Details for assistant_runtime_sdk-1.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| assistant_runtime_sdk-1.14.0-py3-none-any.whl | Python 3 | none | any | Details for assistant_runtime_sdk-1.14.0-py3-none-any.whl |
Total release size: 153.6 kB
Release files / assistant_runtime_sdk-1.14.0.tar.gz
| Download URL | assistant_runtime_sdk-1.14.0.tar.gz |
|---|---|
| Size | 75.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5ca90f82440459e2aa19dfe5bbe342605ca14a082b4e3bf38ac98fc846c1a10
|
|
BLAKE2b-256 checksum How to use checksums |
bf272dd34a856bbc0b7374dc0834489ff2cc5293d4c35b536120b84a99a9cd64
|
| 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.14.0-py3-none-any.whl
| Download URL | assistant_runtime_sdk-1.14.0-py3-none-any.whl |
|---|---|
| Size | 78.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9d4fdac6eb8e744f7a0ba07739311dd54ccddc67b042e441dd6ac96a79121e7
|
|
BLAKE2b-256 checksum How to use checksums |
e84ebfea213608548e1335b04debd444a97482a40515edfadf3c8dc69a8ccd4a
|
| 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.14.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.