Metadata-Version: 2.5
Name: thalovant
Version: 0.9.6
Summary: Python SDK and CLI for direct Thalovant hub data-plane clients and agents
Project-URL: Homepage, https://thalovant.com
Project-URL: Documentation, https://docs.thalovant.com/developers/sdks/python/
Project-URL: Repository, https://github.com/thalovant/thalovant-python-sdk
Project-URL: Issues, https://github.com/thalovant/thalovant-python-sdk/issues
Author: Thalovant
Maintainer: Thalovant
License-Expression: MIT
License-File: LICENSE
License-File: LICENSE-langcodes
Keywords: agent,assistant,iot,sdk,thalovant,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.11
Requires-Dist: cryptography<49.0.0,>=48.0.1; sys_platform == 'darwin' and platform_machine == 'x86_64'
Requires-Dist: cryptography>=48.0.1; sys_platform != 'darwin' or platform_machine != 'x86_64'
Provides-Extra: dev
Requires-Dist: bitstring<5,>=4.1.1; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: certifi; extra == 'dev'
Requires-Dist: hivemind-bus-client>=1.1.9a1; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: noiseprotocol>=0.3.1; extra == 'dev'
Requires-Dist: ovos-spec-tools[langcodes]>=1.10.5a1; extra == 'dev'
Requires-Dist: paho-mqtt>=2.1.0; extra == 'dev'
Requires-Dist: poorman-handshake>=2.0.0a3; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0.2; extra == 'dev'
Requires-Dist: requests>=2.33.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: thalovant-languages>=0.3.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Requires-Dist: pymdown-extensions>=11.0.1; extra == 'docs'
Provides-Extra: listing
Requires-Dist: thalovant-languages>=0.3.0; extra == 'listing'
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.1.0; extra == 'mqtt'
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == 'publish'
Requires-Dist: twine>=7.0; extra == 'publish'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.2; extra == 'yaml'
Description-Content-Type: text/markdown

# Thalovant Python SDK

[![PyPI](https://img.shields.io/pypi/v/thalovant)](https://pypi.org/project/thalovant/) [![CI](https://github.com/thalovant/thalovant-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/thalovant/thalovant-python-sdk/actions/workflows/ci.yml) [![Licence](https://img.shields.io/github/license/thalovant/thalovant-python-sdk)](LICENSE) [![Docs](https://img.shields.io/badge/docs-docs.thalovant.com-5c6bc0)](https://docs.thalovant.com/developers/sdks/python/)

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.

```text
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

```bash
pip install thalovant
```

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

## Quick start

```python
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](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

```bash
pip install -e ".[dev]"
pytest
```

## Security

See [SECURITY.md](SECURITY.md).

## Licence

MIT. See [LICENSE](LICENSE).
