Python SDK

Use the Python SDK when your client or agent runs in Python.

The package name is thalovant.

Install

Install with pip install thalovant.

pip install thalovant

First Request

This flow discovers a public hub, creates a client identity, and sends one request.

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()

public_hubs = api.list_public_hubs(limit=12)
for hub in public_hubs["data"]:
    print(hub["id"], hub["slug"], hub["title"])

api.login("[email protected]", "password")

result = api.create_client_identity(
    "hub-id",
    name="python-demo-client",
    preferred_protocols=("wss", "https", "mqtt"),
)

with ThalovantClient(result.identity, protocol="wss") as client:
    reply = client.ask("Tell me a short clean joke.")
    print(reply.text)

ThalovantControlPlane() uses https://api.thalovant.com by default.

Caution

Keep result.identity secret. Authenticated API actions require API access on the workspace.

Use A Saved Identity

Use this when the identity was downloaded from Thalovant, stored in a secret volume, or saved in your protected SDK config.

from thalovant import ThalovantClient

with ThalovantClient.from_config(profile="prod", protocol="wss") as client:
    reply = client.ask("What can this hub do?")
    print(reply.text)

from thalovant import ThalovantClient

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask("What can this hub do?")
    print(reply.text)

Environment variables work too:

from thalovant import ThalovantClient

with ThalovantClient.from_env(protocol="https") as client:
    print(client.ask("Say hello.").text)

Choose A Protocol

identity = result.identity

print(identity.enabled_protocols())
print(identity.endpoint_for("wss"))
print(identity.endpoint_for("https"))
print(identity.endpoint_for("mqtt"))

for protocol in ("wss", "https", "mqtt"):
    if not identity.supports_protocol(protocol):
        continue
    if protocol == "mqtt" and identity.mqtt is None:
        continue

    with ThalovantClient(identity, protocol=protocol) as client:
        print(protocol, client.ask(f"Reply over {protocol}.").text)

MQTT requires the identity.mqtt broker credentials returned for that client.

For broker details, see MQTT.

Add A Conversation

Use a conversation when related turns should share one session.

with ThalovantClient.from_identity_file("_identity.json") as client:
    with client.conversation(lang="en-us") as convo:
        print(convo.ask("Remember that my favorite color is blue.").text)
        print(convo.ask("What color did I mention?").text)

Add Context

from thalovant import ThalovantClient, build_client_context

context = build_client_context(
    user_id="user-42",
    user_name="Ada",
    source="checkout-kiosk",
    platform="kiosk",
    locale="en-US",
    metadata={"trace_id": "req-2026-06-09-001"},
)

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask("Show the next instruction.", context=context)
    print(reply.text)

Listen For Events

from thalovant import EVENT_SPEAK, ThalovantClient

with ThalovantClient.from_identity_file("_identity.json", protocol="wss") as client:
    client.send_utterance("Say the current status.")
    for event in client.listen(EVENT_SPEAK, timeout=10, max_events=1):
        print(event.text)

Useful Helpers

ask

Send one request and receive a normalized reply.

listen

Wait for hub events with a timeout.

send_action

Send a button, menu, or tool action.

send_code

Send a QR value, serial number, barcode, or typed code.

For the full method list, see SDK Functions.

Common Issues

Symptom	Check
Missing Thalovant API access token	Call api.login(...) before private API actions.
API access requires a paid plan	Upgrade the workspace before provisioning private resources through the API.
Unsupported protocol	Enable that protocol on the hub and create a fresh identity.
MQTT fails immediately	Confirm the identity has mqtt broker credentials.

1. Start with WSS.
2. Add HTTPS only for request-response clients.
3. Add MQTT only when the client needs broker-mediated traffic.