Talking to a hub

Part of SDK Functions. Every call below is shown in each language that has it.

Reuse A Connection And Present Its Skills

All seven managed SDKs expose HubSession and HubSessionPolicy for a reusable connection, retained subscriptions, and configurable reconnect/probe timing. Supply a connected-client factory and close the session when its owner exits. An uncertain Ask or Emit is not replayed automatically: the application decides whether retrying an action is safe. Failed cleanup blocks a replacement until that connection has been retired.

Use Inventory, Skill, and Intent for a presentable view of discovered skills and locale-aware examples. InventoryCache adds optional bounded, private storage with a default one-hour TTL; unknown catalogue language support stays unknown. Explicit language order survives JSON serialization. This view is separate from the native intent-inventory response.

See the managed-session and cache examples for Python, Node, Go, Rust, Kotlin, .NET, and Swift. MCP returns the presentation view within each tool’s identity lease. Embedded C leaves sessions and storage to its caller.

Create A Runtime Client

Use a runtime client after you have identity material.

Keep the SDK’s saved keys in private, persistent storage. Use one identity per client process that runs at the same time. A reconnect authenticates again with the same identity and saved keys; a failed connection is never a reason to delete them. Each SDK page names its storage option.

Python

from thalovant import ThalovantClient

client = ThalovantClient(identity, protocol="wss")
client.connect()
print(client.healthcheck())
client.close()

Node.js

const client = new ThalovantClient(identity, { protocol: "wss" });
await client.connect();
console.log(await client.healthcheck());
await client.close();

Go

client, err := thalovant.NewClientWithOptions(identity, thalovant.ClientOptions{
  Protocol: thalovant.ProtocolWSS,
})
if err != nil {
  log.Fatal(err)
}

if err := client.Connect(ctx); err != nil {
  log.Fatal(err)
}
fmt.Println(client.Healthcheck())
client.Close(ctx)

Rust

use thalovant::{Client, HubProtocol};

let client = Client::with_protocol(identity.clone(), HubProtocol::Wss)?;
client.connect().await?;
println!("{:?}", client.healthcheck().await);
client.close().await?;

Use a context manager, try/finally, or defer so connections close reliably. In Rust, close the client before propagating a request error: ? immediately returns from the current function and does not await connection cleanup. Concurrent callers join authenticated readiness within their own deadlines. A cancelled queued caller must not close the active connection.

Runtime Helper Names

These helpers cover the same workflows in each high-level SDK’s supported transports. Kotlin extension helpers need import com.thalovant.sdk.*.

Workflow	Python	Node.js	Go	Rust	Kotlin / Swift	.NET
Routed query and cascade replies	query	query	Query	query	query	QueryAsync
Reuse a conversational session	conversation	conversation	Conversation	conversation	conversation	Conversation
Wait for a correlated event	wait_for_event	waitForEvent	WaitForEvent	wait_for_event	waitForEvent	WaitForEventAsync
Observe an event stream	listen	on	Listen	listen	listen	ListenAsync
Connect and inspect readiness	connect_with_info	connectWithInfo	ConnectWithInfo	connect_with_info	connectWithInfo	ConnectWithInfoAsync
Ask with language, pipeline and location hints	ask	ask	AskWithOptions	ask_with_hints	askWithHints	AskWithHintsAsync
Build a request location	build_location	buildLocation	BuildLocation	build_location	buildLocation	ThalovantContext.BuildLocation
Render a speakable intent pattern	speakable	speakable	Speakable	speakable	speakable	ThalovantContext.Speakable
Decode one embedded audio event	audio_bytes	audioBytes	AudioBytes	audio_bytes	audioBytes	AudioBytes
Read answering pipeline IDs	reply.pipeline_ids	reply.pipelineIds	reply.PipelineIDs()	reply.pipeline_ids()	reply.pipelineIds	reply.PipelineIds
Read answering skill IDs	reply.skill_ids	reply.skillIds	reply.SkillIDs()	reply.skill_ids()	reply.skillIds	reply.SkillIds
Inspect advisory reply claim	reply.claimed	reply.claimed	reply.Claimed()	reply.claimed()	reply.claimed	reply.Claimed

Kotlin uses a Flow, Swift an AsyncThrowingStream, and .NET an IAsyncEnumerable for listening. Their buffers hold at most 64 events and report overflow explicitly. Cancel or finish the stream to remove its subscription. Swift starts the subscription when listen is called; .NET starts when enumerated. Use each language guide for timeout units and cancellation inputs.

Ask allows bounded delayed speech; Query follows its query ID through cascade replies and waits for completion. A soft intent miss can recover when speech arrives. Hard policy denial and explicit query timeout remain failures, with partial speech preserved. Conversation helpers reuse the session while creating a fresh request ID and merged context per request. A reconnect never automatically replays an application request.

Reply IDs are nonempty strings in first-seen order. A fallback-only successful reply retains its text and success status but reports claimed=false; a successful reply without stage stamps retains legacy claimed behavior. Failed or unhandled replies are never claimed. Claim metadata does not verify peer identity. See reply claims for matching and malformed-stamp behavior.

Embedded C exposes thalovant_ask_event_pipeline_id(), thalovant_ask_event_skill_id() and thalovant_reply_claimed() with caller-owned buffers and ID aggregation. MCP runtime summaries expose pipelineIds, skillIds and claimed through the Node SDK.

Ask A Hub

Use ask for one request-response interaction.

Python

reply = client.ask("What can this hub do?")

print(reply.text)
for item in reply.display_items():
    print(item)

Node.js

const reply = await client.ask("What can this hub do?");

console.log(reply.text);
for (const item of reply.displayItems()) {
  console.log(item);
}

Go

reply, err := client.Ask(ctx, "What can this hub do?", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}

fmt.Println(reply.Text)
for _, item := range reply.DisplayItems(600) {
  fmt.Println(item)
}

Rust

let reply = client
    .ask("What can this hub do?", RequestOptions::default())
    .await?;

println!("{}", reply.text);
for item in reply.display_items(Some(600)) {
    println!("{item:?}");
}

Expected output shape:

{
  "text": "This hub can answer quick joke and trivia requests.",
  "display_items": []
}

List What A Hub Can Be Asked

Use intents when a client should show people what the hub understands, or confirm that a skill registered. The hub answers over the client’s own session with every intent, per language, and the sentences that reach it. No control-plane token is involved. The connection must be allowed to publish ovos.intent.list, and ovos.intent.describe as well when the SDK has to ask for the sentences separately, which a hub that returns them with the listing never makes it do. See What Can My Hub Be Asked?.

Python

from thalovant import ThalovantPolicyDeniedError

try:
    inventory = client.intents(["en-us", "fr-fr"])
except ThalovantPolicyDeniedError as denied:
    print("refused:", denied.denied_type, "allowed:", denied.allowed)
    raise

for intent in inventory.intents:
    print(intent.id, intent.examples("en-us"))

Expected output shape:

{
  "languages": ["en-us", "fr-fr"],
  "source": "intent-manifest",
  "denied": [],
  "skills": [
    {
      "skill_id": "thalovant-skill-weather.thalovant",
      "languages": ["en-us", "fr-fr"],
      "intents": [
        {
          "id": "thalovant-skill-weather.thalovant:current.weather",
          "skill_id": "thalovant-skill-weather.thalovant",
          "name": "current.weather",
          "engine": "padatious",
          "enabled": true,
          "phrases": {
            "en-us": ["what is the weather", "what is the weather in {location}"],
            "fr-fr": ["quel temps fait-il", "quelle est la météo à {location}"]
          }
        }
      ]
    }
  ]
}

A refused query raises the SDK’s policy error at once, naming the message type, instead of waiting for a timeout. When ovos.intent.list is refused and the fallback is on, which is the default, the result carries names only with source set to engine-manifests. A hub that accepts a query and answers it with ok: false is a different case: a failed listing raises the SDK’s runtime error with the hub’s error text, because a failed listing is not an empty hub, while a failed describe leaves that one intent without sentences and raises nothing. Every published SDK ships this recipe under its own spelling; each SDK page gives a working example, and the SDKs page lists the version each one shipped it in.

The current high-level SDKs use the default engine-manifest fallback when ovos.intent.list times out. In that case, denied names the unanswered query and does not prove a policy refusal. Disable fallback to propagate the listing timeout; silent fallback engines still produce a timeout. See intent discovery.

Emit A Raw Event

Use raw events when you already have an event name and a structured payload.

Python

client.emit(
    "thalovant.client.status",
    {"state": "ready"},
    {"source": "checkout-kiosk"},
)

Node.js

await client.emit(
  "thalovant.client.status",
  { state: "ready" },
  { source: "checkout-kiosk" },
);

Go

err := client.Emit(ctx, "thalovant.client.status", map[string]any{
  "state": "ready",
}, map[string]any{
  "source": "checkout-kiosk",
})
if err != nil {
  log.Fatal(err)
}

Rust

use serde_json::json;

let mut data = serde_json::Map::new();
data.insert("state".into(), json!("ready"));

let mut context = serde_json::Map::new();
context.insert("source".into(), json!("checkout-kiosk"));

client
    .emit("thalovant.client.status", data, context)
    .await?;

Send An Utterance

Use an utterance when the input should behave like speech or chat text from a client.

Python

client.send_utterance(
    "What is the status?",
    lang="en-us",
    session_id="status-session",
)

Node.js

await client.sendUtterance("What is the status?", {
  lang: "en-us",
  sessionId: "status-session",
});

Go

err := client.SendUtterance(ctx, "What is the status?", thalovant.RequestOptions{
  Lang:      "en-us",
  SessionID: "status-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_utterance(
        "What is the status?",
        RequestOptions {
            lang: Some("en-us".into()),
            session_id: Some("status-session".into()),
            ..Default::default()
        },
    )
    .await?;

Send An Action

Use actions for buttons, menu picks, confirmations, and tool commands.

Python

client.send_action(
    "/approve invoice-42",
    title="Approve invoice",
    session_id="approval-session",
)

Node.js

await client.sendAction(
  "/approve invoice-42",
  { title: "Approve invoice", sessionId: "approval-session" },
);

Go

err := client.SendAction(ctx, "/approve invoice-42", thalovant.ActionOptions{
  Title:     "Approve invoice",
  SessionID: "approval-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_action(
        "/approve invoice-42",
        ActionOptions {
            title: Some("Approve invoice".into()),
            session_id: Some("approval-session".into()),
            ..Default::default()
        },
    )
    .await?;

Send A Code

Use code input for QR values, barcode scans, serial numbers, short codes, or typed exact values.

Python

client.send_code(
    "INV-2026-001",
    kind="invoice",
    session_id="scan-session",
)

Node.js

await client.sendCode("INV-2026-001", {
  kind: "invoice",
  sessionId: "scan-session",
});

Go

err := client.SendCode(ctx, "INV-2026-001", thalovant.CodeOptions{
  Kind:      "invoice",
  SessionID: "scan-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_code(
        "INV-2026-001",
        CodeOptions {
            kind: Some("invoice".into()),
            session_id: Some("scan-session".into()),
            ..Default::default()
        },
    )
    .await?;

Keep A Conversation

Use a conversation when related turns should share the same session.

Python

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)

Node.js

const convo = client.conversation({ lang: "en-us" });

const first = await convo.ask("Remember that my favorite color is blue.");
const second = await convo.ask("What color did I mention?");
console.log(first.text, second.text);

Go

convo := client.Conversation(thalovant.ConversationOptions{Lang: "en-us"})

first, err := convo.Ask(ctx, "Remember that my favorite color is blue.", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}
second, err := convo.Ask(ctx, "What color did I mention?", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}
fmt.Println(first.Text, second.Text)

Rust

let convo = client.conversation(ConversationOptions {
    lang: Some("en-us".into()),
    ..Default::default()
});

let first = convo
    .ask("Remember that my favorite color is blue.", RequestOptions::default())
    .await?;
let second = convo
    .ask("What color did I mention?", RequestOptions::default())
    .await?;
println!("{} {}", first.text, second.text);

Render Locale-Aware Intent Examples

With the current supported SDK versions, Python uses sentence=True with the optional listing extra. Node accepts { sentence: true } in intent.examples(lang, limit, options). Go uses IntentExampleOptions{Sentence: true} with ExamplesWithOptions; Rust uses IntentExampleOptions with examples_with_listing. Kotlin, Swift and .NET expose examplesWithListing / ExamplesWithListing. MCP exposes sentence on thalovant_intent_inventory.

These renderers use locale slot samples before caller overrides, prefer complete phrases, and count unique nonempty results toward rendered limits. Raw unlimited examples preserve registration order. The managed SDKs bundle the same data used by Python’s listing extra. See each SDK guide for its call signature and custom-rule options.