thalovant

package module
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 19 Imported by: 0

README

Thalovant Go SDK

Go SDK for direct Thalovant hub data-plane clients and agents.

Full documentation: https://docs.thalovant.com/developers/sdks/go/

go get github.com/thalovant/thalovant-go-sdk

package main

import (
	"context"
	"fmt"

	thalovant "github.com/thalovant/thalovant-go-sdk"
)

func main() {
	client, err := thalovant.NewClientFromFile("_identity.json")
	if err != nil {
		panic(err)
	}
	reply, err := client.Ask(context.Background(), "Tell me a short clean joke.", thalovant.RequestOptions{})
	if err != nil {
		panic(err)
	}
	fmt.Println(reply.Text)
}

Status

This is an alpha SDK scaffold with identity, event, session, conversation, AES-GCM preshared-key helpers, protocol endpoint helpers, and an HTTP transport shape compatible with the Thalovant SDK contract. The live transport targets the preshared-key HTTPS HTTP-protocol path used by Thalovant public hubs.

Protocols

Identity or hub payloads may include data_plane_endpoints for https, wss, and mqtt, plus protocols.wss/http/mqtt.enabled flags. When MQTT is enabled for the hub, identity payloads may also include a client-scoped mqtt block with endpoint, username, password, and topic_prefix.

identity, err := thalovant.IdentityFromFile("_identity.json")
if err != nil {
	panic(err)
}

fmt.Println(identity.EnabledProtocols())
fmt.Println(identity.EndpointFor(thalovant.ProtocolHTTPS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolWSS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolMQTT))

You can also create a hub client through the Thalovant API:

control := thalovant.NewControlPlane("https://dash.thalovant.com/api", "")
_, _ = control.Login(ctx, "you@example.com", "password", "")

result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
	Name: "kiosk-1",
})
if err != nil {
	panic(err)
}

client := thalovant.NewClient(result.Identity)

The SDK generates apiKey, password, and cryptoKey locally and sends them to the API once. The API can store them in Vault and return only secret references. When MQTT is enabled, result.Identity.MQTT contains the broker credentials returned by the API. Do not log result.Summary(true).

Generic Client Context

context := thalovant.BuildClientContext(nil, thalovant.ClientContextOptions{
	UserID:       "user-42",
	UserName:     "Ada",
	AuthProvider: "oidc",
	Roles:        []string{"member"},
	Platform:     "kiosk",
	Source:       "checkout-kiosk",
	Channel:      "chat",
})

reply, err := client.Ask(ctx, "Show the next instruction.", thalovant.RequestOptions{Context: context})

Actions, Codes, And Rich Output

conversation := client.Conversation(thalovant.ConversationOptions{SessionID: "work-session"})

_ = conversation.SendAction(ctx, `/choose{"id":"42"}`, thalovant.ActionOptions{Title: "Choose item"})
_ = conversation.SendCode(ctx, "SN-001-XYZ", thalovant.CodeOptions{Kind: "qr", Label: "serial"})

items := reply.DisplayItems(600)

Identity files may include default_path for hubs exposed behind a reverse proxy path, for example /public. Newer identities should prefer explicit data_plane_endpoints when the API provides them.

Development

go test ./...

Documentation

Index

Constants

View Source 
const (
	EventRecognizerLoopUtterance = "recognizer_loop:utterance"
	EventSpeak                   = "speak"
	EventUtteranceHandled        = "ovos.utterance.handled"
	EventIntentFailure           = "complete_intent_failure"
	EventPolicyDenied            = "hive.policy.denied"
	DefaultUserAgent             = "ThalovantGoSDK/0.2.2"
)
View Source 
const DefaultControlUserAgent = "ThalovantGoSDK/0.2.3"

Variables

View Source 
var (
	ErrIdentity   = errors.New("thalovant identity error")
	ErrConnection = errors.New("thalovant connection error")
	ErrTimeout    = errors.New("thalovant timeout")
	ErrRuntime    = errors.New("thalovant runtime error")
	ErrAPI        = errors.New("thalovant api error")
	ErrProtocol   = errors.New("thalovant unsupported protocol")
)
View Source 
var DefaultProtocolPreference = []HubProtocol{ProtocolHTTPS, ProtocolWSS, ProtocolMQTT}

Functions

func DecryptFromJSON 

func DecryptFromJSON(key string, raw string) (string, error)

func EncryptAsJSON 

func EncryptAsJSON(key string, plaintext string) (string, error)

func EndpointFromDomain added in v0.2.1 

func EndpointFromDomain(domain string, protocol HubProtocol) string

func EventMatchesContext 

func EventMatchesContext(event Event, expected Context) bool

func NewRequestID 

func NewRequestID() string

func NewSessionID 

func NewSessionID() string

func RequestIDFromContext 

func RequestIDFromContext(context Context) string

func RichMediaFromData 

func RichMediaFromData(data Data) map[string]any

func RuntimeCryptoKey 

func RuntimeCryptoKey(raw string) []byte

func SessionIDFromContext 

func SessionIDFromContext(context Context) string

func StripSSML 

func StripSSML(text string) string

Types

type ActionOptions 

type ActionOptions struct {
	Title     string
	Lang      string
	Context   Context
	SessionID string
	RequestID string
}

type BootstrapIdentityOptions added in v0.2.2 

type BootstrapIdentityOptions struct {
	Name               string
	SiteID             string
	Spec               map[string]any
	OwnerID            string
	Active             *bool
	PreferredProtocols []HubProtocol
	IdempotencyKey     string
}

type BootstrapIdentityResult added in v0.2.2 

type BootstrapIdentityResult struct {
	Identity Identity
	Hub      map[string]any
	Client   map[string]any
	Endpoint *SelectedHubEndpoint
}

func (BootstrapIdentityResult) SelectedProtocol added in v0.2.2 

func (r BootstrapIdentityResult) SelectedProtocol() HubProtocol

func (BootstrapIdentityResult) Summary added in v0.2.2 

func (r BootstrapIdentityResult) Summary(includeSecrets bool) map[string]any

type Client 

type Client struct {
	Identity  Identity
	Transport *HTTPTransport
}

func NewClient 

func NewClient(identity Identity) *Client

func NewClientFromEnv 

func NewClientFromEnv() (*Client, error)

func NewClientFromFile 

func NewClientFromFile(path string) (*Client, error)

func NewClientWithOptions added in v0.2.2 

func NewClientWithOptions(identity Identity, opts ClientOptions) (*Client, error)

func (*Client) Ask 

func (c *Client) Ask(ctx context.Context, text string, opts RequestOptions) (Reply, error)

func (*Client) Close 

func (c *Client) Close(ctx context.Context) error

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context) error

func (*Client) Conversation 

func (c *Client) Conversation(opts ConversationOptions) Conversation

func (*Client) Emit 

func (c *Client) Emit(ctx context.Context, eventType string, data Data, eventContext Context) error

func (*Client) Healthcheck 

func (c *Client) Healthcheck() TransportHealth

func (*Client) SendAction 

func (c *Client) SendAction(ctx context.Context, payload string, opts ActionOptions) error

func (*Client) SendCode 

func (c *Client) SendCode(ctx context.Context, value string, opts CodeOptions) error

func (*Client) SendUtterance 

func (c *Client) SendUtterance(ctx context.Context, text string, opts RequestOptions) error

type ClientContextOptions 

type ClientContextOptions struct {
	UserID       string
	UserName     string
	AuthToken    string
	AuthProvider string
	AuthClaims   map[string]any
	Roles        []string
	Platform     string
	Source       string
	Destination  string
	Channel      string
	DeviceID     string
	Locale       string
	Metadata     map[string]any
	SessionID    string
}

type ClientOptions added in v0.2.2 

type ClientOptions struct {
	Protocol HubProtocol
}

type CodeOptions 

type CodeOptions struct {
	Kind      string
	Label     string
	Lang      string
	Context   Context
	SessionID string
	RequestID string
}

type Context 

type Context map[string]any

func BuildClientContext 

func BuildClientContext(base Context, opts ClientContextOptions) Context

func ContextWithCorrelation 

func ContextWithCorrelation(raw Context, sessionID, siteID, lang, requestID string) Context

func MergeContext 

func MergeContext(base, extra Context) Context

type ControlPlane added in v0.2.2 

type ControlPlane struct {
	APIURL      string
	AccessToken string
	UserAgent   string
	HTTPClient  *http.Client
}

func NewControlPlane added in v0.2.2 

func NewControlPlane(apiURL string, accessToken string) *ControlPlane

func (*ControlPlane) CreateClient added in v0.2.2 

func (c *ControlPlane) CreateClient(ctx context.Context, payload map[string]any, idempotencyKey string) (map[string]any, error)

func (*ControlPlane) CreateClientIdentity added in v0.2.2 

func (c *ControlPlane) CreateClientIdentity(ctx context.Context, hub map[string]any, opts BootstrapIdentityOptions) (BootstrapIdentityResult, error)

func (*ControlPlane) CreateClientIdentityForHubID added in v0.2.2 

func (c *ControlPlane) CreateClientIdentityForHubID(ctx context.Context, hubID string, opts BootstrapIdentityOptions) (BootstrapIdentityResult, error)

func (*ControlPlane) GetHub added in v0.2.2 

func (c *ControlPlane) GetHub(ctx context.Context, hubID string) (map[string]any, error)

func (*ControlPlane) ListHubs added in v0.2.2 

func (c *ControlPlane) ListHubs(ctx context.Context, limit int, cursor string, ownerID string) (map[string]any, error)

func (*ControlPlane) Login added in v0.2.2 

func (c *ControlPlane) Login(ctx context.Context, email string, password string, scope string) (map[string]any, error)

func (*ControlPlane) RequireRuntimeProtocol added in v0.2.2 

func (c *ControlPlane) RequireRuntimeProtocol(result BootstrapIdentityResult, protocol HubProtocol) (*SelectedHubEndpoint, error)

type Conversation 

type Conversation struct {
	Client  *Client
	Options ConversationOptions
}

func (Conversation) Ask 

func (c Conversation) Ask(ctx context.Context, text string, opts RequestOptions) (Reply, error)

func (Conversation) SendAction 

func (c Conversation) SendAction(ctx context.Context, payload string, opts ActionOptions) error

func (Conversation) SendCode 

func (c Conversation) SendCode(ctx context.Context, value string, opts CodeOptions) error

func (Conversation) SendUtterance 

func (c Conversation) SendUtterance(ctx context.Context, text string, opts RequestOptions) error

type ConversationOptions 

type ConversationOptions struct {
	SessionID string
	Lang      string
	Context   Context
}

type Data 

type Data map[string]any

func UtterancePayload 

func UtterancePayload(text, lang string) Data

type DisplayItem 

type DisplayItem struct {
	Kind    string
	Text    string
	Data    any
	Title   string
	Payload string
	URL     string
	Silent  bool
}

func DisplayItemsFromEventData 

func DisplayItemsFromEventData(data Data, eventName string, maxTextChars int) []DisplayItem

type Event 

type Event struct {
	Name    string
	Data    Data
	Context Context
	Raw     any
}

func (Event) DisplayItems 

func (e Event) DisplayItems(maxTextChars int) []DisplayItem

func (Event) DisplayText 

func (e Event) DisplayText() string

func (Event) IsFailure 

func (e Event) IsFailure() bool

func (Event) RequestID 

func (e Event) RequestID() string

func (Event) RichMedia 

func (e Event) RichMedia() map[string]any

func (Event) SessionID 

func (e Event) SessionID() string

func (Event) Text 

func (e Event) Text() string

func (Event) Utterances 

func (e Event) Utterances() []string

type HTTPTransport 

type HTTPTransport struct {
	Identity     Identity
	UserAgent    string
	PollInterval time.Duration
	HTTPClient   *http.Client
	BusEvents    chan Event
	// contains filtered or unexported fields
}

func NewHTTPTransport 

func NewHTTPTransport(identity Identity) *HTTPTransport

func (*HTTPTransport) Authorization 

func (t *HTTPTransport) Authorization() string

func (*HTTPTransport) BaseURL 

func (t *HTTPTransport) BaseURL() string

func (*HTTPTransport) Connect 

func (t *HTTPTransport) Connect(ctx context.Context) error

func (*HTTPTransport) Disconnect 

func (t *HTTPTransport) Disconnect(ctx context.Context) error

func (*HTTPTransport) EmitBus 

func (t *HTTPTransport) EmitBus(ctx context.Context, eventType string, data Data, eventContext Context) error

func (*HTTPTransport) Healthcheck 

func (t *HTTPTransport) Healthcheck() TransportHealth

func (*HTTPTransport) IsHandshakeComplete 

func (t *HTTPTransport) IsHandshakeComplete() bool

func (*HTTPTransport) PollOnce 

func (t *HTTPTransport) PollOnce(ctx context.Context) error

type HiveMessage 

type HiveMessage struct {
	MsgType      string         `json:"msg_type"`
	Payload      map[string]any `json:"payload"`
	Metadata     map[string]any `json:"metadata"`
	Route        []any          `json:"route"`
	Node         any            `json:"node"`
	TargetSiteID any            `json:"target_site_id"`
	TargetPubKey any            `json:"target_pubkey"`
	SourcePeer   any            `json:"source_peer"`
}

type HubDataPlaneEndpoints added in v0.2.1 

type HubDataPlaneEndpoints struct {
	HTTPS string `json:"https,omitempty"`
	WSS   string `json:"wss,omitempty"`
	MQTT  string `json:"mqtt,omitempty"`
}

func DataPlaneEndpointsFromHub added in v0.2.1 

func DataPlaneEndpointsFromHub(hub map[string]any) HubDataPlaneEndpoints

func DataPlaneEndpointsFromMap added in v0.2.1 

func DataPlaneEndpointsFromMap(values map[string]any) HubDataPlaneEndpoints

func (HubDataPlaneEndpoints) EndpointFor added in v0.2.1 

func (e HubDataPlaneEndpoints) EndpointFor(protocol HubProtocol) string

func (HubDataPlaneEndpoints) HTTPBase added in v0.2.1 

func (e HubDataPlaneEndpoints) HTTPBase(fallbackMaster string, fallbackPort int, fallbackPath string) string

func (HubDataPlaneEndpoints) Map added in v0.2.1 

func (e HubDataPlaneEndpoints) Map(redactCredentials bool) map[string]string

type HubProtocol added in v0.2.1 

type HubProtocol string
const (
	ProtocolWSS   HubProtocol = "wss"
	ProtocolHTTPS HubProtocol = "https"
	ProtocolMQTT  HubProtocol = "mqtt"
)

type HubProtocolSettings added in v0.2.1 

type HubProtocolSettings struct {
	WSS  bool `json:"wss"`
	HTTP bool `json:"http"`
	MQTT bool `json:"mqtt"`
}

func DefaultHubProtocolSettings added in v0.2.1 

func DefaultHubProtocolSettings() HubProtocolSettings

func ProtocolSettingsFromMap added in v0.2.1 

func ProtocolSettingsFromMap(values map[string]any) HubProtocolSettings

func (HubProtocolSettings) EnabledProtocols added in v0.2.1 

func (s HubProtocolSettings) EnabledProtocols() []HubProtocol

func (HubProtocolSettings) IsEnabled added in v0.2.1 

func (s HubProtocolSettings) IsEnabled(protocol HubProtocol) bool

func (HubProtocolSettings) SpecMap added in v0.2.1 

func (s HubProtocolSettings) SpecMap() map[string]any

type Identity 

type Identity struct {
	AccessKey          string                 `json:"access_key"`
	Password           string                 `json:"password"`
	CryptoKey          string                 `json:"crypto_key,omitempty"`
	SiteID             string                 `json:"site_id"`
	DefaultMaster      string                 `json:"default_master"`
	DefaultPort        int                    `json:"default_port"`
	DefaultPath        string                 `json:"default_path,omitempty"`
	PublicKey          string                 `json:"public_key,omitempty"`
	DataPlaneEndpoints HubDataPlaneEndpoints  `json:"data_plane_endpoints,omitempty"`
	Protocols          HubProtocolSettings    `json:"protocols,omitempty"`
	MQTT               *MqttBrokerCredentials `json:"mqtt,omitempty"`
}

func IdentityFromEnv 

func IdentityFromEnv(prefix string) (Identity, error)

func IdentityFromFile 

func IdentityFromFile(path string) (Identity, error)

func IdentityFromMap 

func IdentityFromMap(values map[string]any) (Identity, error)

func (Identity) EnabledProtocols added in v0.2.1 

func (i Identity) EnabledProtocols() []HubProtocol

func (Identity) EndpointBase 

func (i Identity) EndpointBase() string

func (Identity) EndpointFor added in v0.2.1 

func (i Identity) EndpointFor(protocol HubProtocol) string

func (Identity) Summary 

func (i Identity) Summary() map[string]any

func (Identity) SupportsProtocol added in v0.2.1 

func (i Identity) SupportsProtocol(protocol HubProtocol) bool

type MqttBrokerCredentials added in v0.2.3 

type MqttBrokerCredentials struct {
	Endpoint    string `json:"endpoint"`
	Username    string `json:"username"`
	Password    string `json:"password"`
	TopicPrefix string `json:"topic_prefix,omitempty"`
	TLS         bool   `json:"tls"`
}

func MqttBrokerCredentialsFromMap added in v0.2.3 

func MqttBrokerCredentialsFromMap(raw any) *MqttBrokerCredentials

func (MqttBrokerCredentials) Map added in v0.2.3 

func (m MqttBrokerCredentials) Map(includeSecrets bool) map[string]any

type Reply 

type Reply struct {
	Text         string
	Utterances   []string
	Handled      bool
	OK           bool
	SessionID    string
	RequestID    string
	Events       []Event
	FailureEvent *Event
}

func (Reply) DisplayItems 

func (r Reply) DisplayItems(maxTextChars int) []DisplayItem

func (Reply) DisplayText 

func (r Reply) DisplayText() string

type RequestOptions 

type RequestOptions struct {
	Timeout   time.Duration
	Lang      string
	Context   Context
	SessionID string
	RequestID string
}

type SelectedHubEndpoint added in v0.2.2 

type SelectedHubEndpoint struct {
	Protocol HubProtocol `json:"protocol"`
	Endpoint string      `json:"endpoint"`
}

func SelectDataPlaneEndpoint added in v0.2.2 

func SelectDataPlaneEndpoint(endpoints HubDataPlaneEndpoints, protocols HubProtocolSettings, preferred []HubProtocol) *SelectedHubEndpoint

type TransportHealth 

type TransportHealth struct {
	Connected         bool
	HandshakeComplete bool
	TransportAlive    bool
	LastError         string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.