Events and Rich Output

SDK responses may contain more than plain text. A reply can include speech, display items, event metadata, or policy information.

Build clients so they can read the normalized response first, then inspect richer fields when the app needs them.

At a Glance

Output	Use it for
`text`	Plain answer text for logs, chat, tests, and fallback displays.
`speech`	Speakable text after SSML and markup cleanup.
`display_items`	Cards, choices, tables, images, and attachments.
`raw_event`	Advanced integrations that need the original event payload.
`policy_denied`	User-safe handling when access blocks a request.

Event Names

Use SDK constants when a language exposes them. The underlying event names stay stable across SDKs.

Event	Meaning
`recognizer_loop:utterance`	A client sends a user utterance.
`speak`	The hub returns speech or reply text.
`complete_intent_failure`	A request could not be matched to an available skill.
`hive.policy.denied`	Access policy blocked the request.
`mycroft.skill.handler.start`	A skill handler started.
`mycroft.skill.handler.complete`	A skill handler finished.

Display Items

Display items let apps show structured results without reverse-engineering the text.

Text

A paragraph, title, subtitle, or status message.

Choice

A selectable option that can map back to send_action.

Table

Rows and columns for comparison, status, or inventory style output.

Image

A URL or attachment reference that the client can render.

Python Example

from thalovant import ThalovantClient

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask("Show the next maintenance steps.")

print(reply.text)

for item in reply.display_items:
    print(item.kind, item.title, item.payload)

Client Behavior

Case	Recommended handling
`text` is present	Show it as the fallback user-visible answer.
`speech` is present	Speak it in voice clients after local safety checks.
`display_items` is present	Render the items the client understands and ignore unknown kinds.
`policy_denied` is true	Show a safe denied message and log the request ID.
No useful output	Treat it as an empty reply and include the raw event in diagnostics.