Thalovant Python SDK

Python SDK for connecting apps, services, kiosks, and agents to Thalovant hubs.

The control API is used to discover hubs and provision a client identity. After that, the SDK talks directly to the hub data plane over HTTPS, WSS, or MQTTS.

Thalovant API      -> discover hubs, create client identity
Python SDK         -> connect to the hub data plane
Hub runtime        -> skills, events, replies

The SDK is asyncio at its core. AsyncThalovantClient and AsyncThalovantControlPlane are the implementation; ThalovantClient and ThalovantControlPlane run the same code on a private event-loop thread, so a script, a CLI or a voice satellite can call them without an event loop of its own.

Requirements

Python 3.10 or newer.
A Thalovant account with API access for authenticated control-plane actions.
A hub id or slug, and a client identity for that hub. You can create one through the API or use one downloaded from the dashboard.

Install

pip install thalovant

Optional extras: thalovant[mqtt], thalovant[yaml] and thalovant[listing]. The documentation says what each one adds.

Quick start

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()

# Public hub discovery does not require auth.
public_hubs = api.list_public_hubs(limit=12)
for hub in public_hubs["data"]:
    print(hub["id"], hub["slug"], hub["title"])

# Auth is required when creating a client identity.
api.login("you@example.com", "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:
    info = client.connection_info()
    print("connected in", info.connect_ms, "ms")
    reply = client.ask("Tell me a short clean joke.")
    print(reply.text)

Keep result secret: result.identity and the raw result.client API resource carry the client credentials. result.as_dict() redacts every secret and is safe to log; result.as_dict(include_secrets=True) returns the real credentials, so use it only to save the identity and never log it.

Documentation

Topic	Link
Python SDK: install, sign-in, identities, protocols, conversations, events, asyncio, Home Assistant, provisioning, errors, upgrading to 0.9	https://docs.thalovant.com/developers/sdks/python/
The Thalovant product	https://docs.thalovant.com

Not yet in the online documentation

These parts of the old README have no counterpart on the documentation page. They are described in the docs/ folder of this repository and in CHANGELOG.md.

Listing your hubs, workspace analytics and durable memory.
Rich responses (reply.display_items) and skill sounds (reply.media_events).
Actions and exact inputs (send_action, send_code).
Reading an API error and the API shape overview.
CLI diagnostics: thalovant --identity _identity.json doctor checks identity shape, endpoint selection, authentication, handshake and transport health.

Development

pip install -e ".[dev]"
pytest

Security

See SECURITY.md.

Licence

MIT. See LICENSE.

Metadata

Release files for thalovant 0.9.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for thalovant 0.9.4
File	Size	Uploaded
thalovant-0.9.4.tar.gz	514.3 kB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for thalovant 0.9.4
File	Interpreter	ABI	Platform	Reset
thalovant-0.9.4-py3-none-any.whl 242.9 kB Oct 2, 2026	Python 3	none	any	Details

Total release size: 757.1 kB

Release files / thalovant-0.9.4.tar.gz

Download URL	thalovant-0.9.4.tar.gz
Size	514.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`c05dc39d21f783ce210b85aa0bda99603775cf16a5b4b1a32a8528659ce4a8ec`
BLAKE2b-256 checksum How to use checksums	`98d1bb94bfa4f1a7c7c93404f51df227acf2538954de1f522f555f7d0132f41a`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / thalovant-0.9.4-py3-none-any.whl

Download URL	thalovant-0.9.4-py3-none-any.whl
Size	242.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1ee6bab44c112e7f88f9d0c0deb86dbf7f1d8f731154ef1541d9a3f4525f4ab7`
BLAKE2b-256 checksum How to use checksums	`dea67bda75eadd780e005268a32c287357e8917defe03271ea9b901e25823b47`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`