SDK Contract

The SDK contract defines the behavior each language SDK should expose, even when method names follow local language style.

Use this page when adding a new language SDK, reviewing a release, or checking whether an integration can move between SDKs.

At A Glance

Area	Contract
Control plane	Discover public hubs, list authenticated hubs, and create client identities.
Identity	Load the same identity fields in every SDK.
Protocols	Support WSS, HTTPS, and MQTT over TLS when the identity and hub allow them.
Requests	Support natural language, action payloads, exact codes, sessions, and context.
Replies	Normalize text, speech, display items, policy state, and raw event data.

Required Capabilities

Public discovery

List public hubs without requiring an access token.

Authenticated hubs

List hubs visible to the signed-in workspace when API access is allowed.

Identity provisioning

Create a client identity and preserve returned protocol metadata.

Protocol selection

Select WSS, HTTPS, or MQTT explicitly and fail clearly when unavailable.

Health

Check that the endpoint, identity, and transport are usable.

Ask

Send one request and return a normalized reply object.

Action

Send a structured command or UI selection without turning it into prose.

Code

Send exact input such as scanned values, serial numbers, or typed codes.

Shared Identity Shape

Every SDK should understand these fields:

Field	Meaning
`access_key`	Client identifier used during hub auth.
`password`	Client secret used during hub auth.
`crypto_key`	Optional shared payload encryption key.
`site_id`	Stable client, service, device, or runtime label.
`data_plane_endpoints`	Explicit WSS, HTTPS, and MQTT endpoints.
`protocols`	Hub protocol flags returned with the identity.
`mqtt`	Per-client MQTT broker credentials and topic scope.

SDKs should load ~/.config/thalovant/config.yaml by default for local development, honor XDG_CONFIG_HOME, support named profiles, and reject group-readable or world-readable config files on Linux and macOS.

Shared Response Shape

Every SDK should expose these concepts:

Field	Meaning
`text`	Plain fallback answer for chat, logs, and tests.
`speech`	Speakable answer text after markup cleanup.
`display_items`	Structured UI items such as choices, tables, images, and attachments.
`session_id`	Session used by the request or returned by the hub.
`request_id`	Request trace key when provided or generated.
`policy_denied`	True when access policy blocked the request.
`raw_event`	Original event payload for advanced integrations.

Compatibility Rules

Rule	Why it matters
Unknown identity fields should be ignored.	New fields must not break older clients.
Unknown display items should be ignored.	New UI outputs must not break older apps.
Missing optional metadata should use defaults.	Small clients should not need every field.
Method names should feel native.	Python, Node, Go, and Rust should match their language norms.
Error objects should include context.	Callers need endpoint, status, request ID, and policy details when available.
Runtime protocol defaults should be predictable.	Prefer WSS, then HTTPS, then MQTT when broker credentials exist.
MQTT requires client-scoped credentials.	Broker access must stay limited to one client and its topics.

Security Contract

Area	Requirement
API tokens	Send only as authorization headers. Do not put tokens in URLs.
Identity output	Redact passwords, broker passwords, and crypto keys by default.
Local config	Require owner-only permissions for `~/.config/thalovant/config.yaml` on Linux and macOS.
TLS	Honor `mqtt.tls: true` even when the endpoint scheme is not already `mqtts://`.
Public endpoints	Prefer `https://`, `wss://`, and `mqtts://` in examples and generated identities.
MQTT topics	Use returned client topics or derive topics inside the client scope only.
Timeouts	Bound connect, send, and wait operations so clients fail clearly.

Release Contract

Rule	Why it matters
Code changes require a version bump.	CI publishes existing versions, it does not invent new ones.
Tests cover protocol selection.	Every SDK must reject unavailable protocols clearly.
Tests cover secret redaction.	SDKs must not leak credentials in normal summaries.
Docs update with new features.	Users should not need source code to discover supported behavior.

Language Naming

Capability	Python	Node	Go	Rust
Ask	`ask`	`ask`	`Ask`	`ask`
Context	`build_client_context`	`buildClientContext`	`BuildClientContext`	`build_client_context`
Action	`send_action`	`sendAction`	`SendAction`	`send_action`
Code	`send_code`	`sendCode`	`SendCode`	`send_code`
Protocol check	`supports_protocol`	`supportsProtocol`	`SupportsProtocol`	`supports_protocol`