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 doctorchecks identity shape, endpoint selection, authentication, handshake and transport health.
Development
pip install -e ".[dev]"
pytest
Security
See SECURITY.md.
Licence
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for thalovant 0.9.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| thalovant-0.9.5.tar.gz | 515.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| thalovant-0.9.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 758.2 kB
Release files / thalovant-0.9.5.tar.gz
| Download URL | thalovant-0.9.5.tar.gz |
|---|---|
| Size | 515.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b3082e8299c813605805d374e0f4aab058c4881d8450b913536ea631f5a183e
|
|
BLAKE2b-256 checksum How to use checksums |
4233c8d86c86b101797250d23bf35471825448b582ebd81ec1ef27a524976f46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / thalovant-0.9.5-py3-none-any.whl
| Download URL | thalovant-0.9.5-py3-none-any.whl |
|---|---|
| Size | 243.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
869005dc76592bf8f05b11e312bd6017326db7c0cae4f848cc7a6263017f9482
|
|
BLAKE2b-256 checksum How to use checksums |
9f363c63c8fc11c7308fa9a66c08d93a252b1d1049d30bd258b8b5b66fff663c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
