Developers
Put the assistant in your own software.
Everything FAC Cloud does is available from Python. Stream a conversation, search the knowledge base, run a workflow, read usage — the same API the FAC Chat client uses.
pip install assistant-runtime-sdk — version 1.9.0, AGPL-3.0.
from assistant_runtime_sdk import AssistantRuntimeClient
client = AssistantRuntimeClient(
tenant_id="your-tenant-id",
tenant_secret="your-secret",
ar_url="https://api.fac-cloud.com",
)
for event in client.stream_chat(
session_id="session-123",
message="Which invoices are overdue this week?",
user_id="[email protected]",
model_id="auto",
):
if event["event"] == "stream_chunk":
print(event["data"].get("content", ""), end="", flush=True)Quick start
Three steps from nothing to a verified connection. The full documentation covers everything past that.
-
Install the package
Python 3.10+. The async client is an optional extra.
pip install assistant-runtime-sdk -
Add your credentials
Issued when your site is connected to the hosted service. Keep the secret out of source control — the sample below reads them from the environment.
export AR_TENANT_ID="your-tenant-id" export AR_TENANT_SECRET="your-secret" -
Make your first request
Confirms the credentials and the connection in one call, without spending credits on a model.
import os from assistant_runtime_sdk import AssistantRuntimeClient client = AssistantRuntimeClient( tenant_id=os.environ["AR_TENANT_ID"], tenant_secret=os.environ["AR_TENANT_SECRET"], ar_url="https://api.fac-cloud.com", ) print(client.get_tenant_info())
Where the SDK sits
Your code talks to the hosted service. The ERP tools come from the app on your own site, so the SDK sees exactly what the chat client sees.
The package
Everything on this page is checkable in about ten seconds, which is why it is stated rather than described.
| Package | assistant-runtime-sdk. | Import as assistant_runtime_sdk. |
|---|---|---|
| Licence | AGPL-3.0. | Open source. |
| Python | 3.10+. | Tested on current releases. |
| SDK source | buildswithpaul/assistant_runtime_sdk. | The client you import. |
| App source | buildswithpaul/Frappe_Assistant_Core. | A different repository: the app your site installs. |
How it authenticates
| Authentication | HMAC over your tenant secret. | There is no bearer token to leak. |
|---|---|---|
| Model selection | model_id="auto". | The runtime picks the model for the question. |
| Async | AsyncAssistantRuntimeClient. | The same surface, for use inside an event loop. |
What the client covers
| Chat and streaming | Send a message and read the reply as it is generated, including tool calls as they run. |
|---|---|
| Conversations | List, read and manage sessions and their message history. |
| Knowledge base | Upload documents, search them, and manage what the assistant can draw on. |
| Memory | Read and write the long-term facts the assistant keeps about a user. |
| Workflows | Trigger workflows and read their runs. |
| Users | Add and remove members, and set per-person credit limits. |
| Billing and usage | Read plans, credit balances and consumption. |
Install
Two extras, one package. The async client shares the sync client's surface.
pip install assistant-runtime-sdk # sync client
pip install "assistant-runtime-sdk[async]" # with async supportBefore you start
Getting credentials
The SDK authenticates as a tenant: you need a tenant ID and secret, which are issued when your site is connected to FAC Cloud. If you are already running FAC Chat, you have them. If not, get in touch and we will set you up.
Costs are the same
Calls made through the SDK draw on the same credit allowance as the chat client, and appear in the same usage breakdown. See the plans.
Four more calls
Past streaming: a file upload, a trigger, a read and an administrative write. The reference has the rest.
Add a document to the knowledge base
Uploaded once, then available to every conversation on your tenant. Public here means your whole team, not the internet.
client.upload_document(
file_path="handbook.pdf",
user_id="[email protected]",
visibility="public",
)Run a workflow
Triggers a workflow by its document name and returns the run.
client.execute_workflow(
name="WF-00001",
input_data="{\"customer\": \"Acme Corp\"}",
user_id="[email protected]",
)Read what has been spent
A daily credit rollup grouped by source, for the last thirty days.
client.get_consumption_breakdown(days=30)Cap one person's monthly spend
Zero means no personal cap: that user draws on the shared pool.
client.set_user_credit_limit(
user_id="[email protected]",
monthly_credit_limit=500,
acted_by="[email protected]",
)When it goes wrong
Every one of these subclasses ARError, so a single except
clause catches the lot while these five tell you what to do about it.
| Exception | When | What to do |
|---|---|---|
ARAuthenticationError | The tenant ID or secret is wrong, or the tenant is not connected. | Check both values, then confirm the site is still connected. |
ARRateLimitError | Too many requests in the window. | Back off and retry; the exception carries the retry hint. |
ARBillingUnavailableError | The credit allowance is exhausted, or billing is not reachable. | Check the balance before retrying — a retry will not succeed on its own. |
ARTimeoutError | The request exceeded its timeout. | Raise the client timeout for long generations, or stream instead. |
ARConnectionError | The hosted service could not be reached at all. | A network or DNS problem rather than a credentials one. |
Build on it
Install the app on your site, then work against the Python SDK from your own code. Both are open source.