SDK Go

Utilisez le SDK Go lorsque votre client a besoin d’un service compact, d’une passerelle, d’un outil en ligne de commande ou d’un processus d’agent.

Le chemin du module est github.com/thalovant/thalovant-go-sdk.

Les versions actuelles du SDK Go exigent Go 1.26 ou une version plus récente. Mettez à jour le compilateur avant de passer d’une version de la série v0.4.x à celle-ci.

Installation

Ajoutez le module avec go get github.com/thalovant/thalovant-go-sdk :

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

Il s’agit d’un module public : vous n’avez besoin ni d’identifiants GitHub ni d’une dérogation GOPRIVATE. go get récupère la dernière version publiée; ajoutez @<version> lorsque vous avez besoin d’une compilation reproductible, et prenez la version actuelle dans Versions prises en charge.

Première requête

package main

import (
  "context"
  "fmt"
  "log"

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

func main() {
  ctx := context.Background()
  control := thalovant.NewDefaultControlPlane("")

  _, err := control.Login(ctx, "[email protected]", "password", "")
  if err != nil {
    log.Fatal(err)
  }

  result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
    Name: "go-demo-client",
    PreferredProtocols: []thalovant.HubProtocol{
      thalovant.ProtocolWSS,
      thalovant.ProtocolHTTPS,
      thalovant.ProtocolMQTT,
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{
    Protocol: thalovant.ProtocolWSS,
  })
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close(ctx)

  reply, err := client.Ask(ctx, "Tell me a short clean joke.", thalovant.RequestOptions{})
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(reply.Text)
}

NewDefaultControlPlane utilise https://api.thalovant.com. N’utilisez NewControlPlane que pour le développement local ou pour un plan de contrôle auto-hébergé.

Attention

Gardez result.Identity secret. Les actions d’API authentifiées exigent que l’accès à l’API soit activé dans l’espace de travail.

Se connecter avec l’authentification multifacteur

Les comptes où l’authentification multifacteur (AMF) est activée doivent fournir un code TOTP ou un code de récupération à usage unique lors de la connexion. Un simple appel à Login est refusé avec une erreur HTTP 401 et le code mfa_required. Utilisez LoginWithOptions; les champs ne sont envoyés que s’ils sont renseignés. La prise en charge de l’AMF exige le SDK v0.3.2 ou une version plus récente.

_, err := control.LoginWithOptions(ctx, "[email protected]", "password", thalovant.LoginOptions{
  OTPCode: "123456",
})

// Or use a one-time recovery code instead:
_, err = control.LoginWithOptions(ctx, "[email protected]", "password", thalovant.LoginOptions{
  RecoveryCode: "abcd-efgh-ijkl",
})

Se connecter sans mot de passe

La connexion par appareil demande à votre navigateur d’approuver la connexion : vos outils en ligne de commande, services et agents ne manipulent donc jamais votre mot de passe. Le SDK affiche un code court et l’adresse https://dash.thalovant.com/activate, ouvre cette page lorsqu’il le peut, puis attend que vous approuviez la demande dans le tableau de bord avec votre connexion habituelle, y compris la connexion Google ou l’AMF. Une fois la demande approuvée, le SDK détient un jeton d’API révocable, limité à certaines portées.

La connexion par appareil exige le SDK v0.3.3 ou une version plus récente. Pour approuver la demande, l’espace de travail doit avoir un forfait payant; un forfait gratuit reçoit une erreur HTTP 402.

token, err := control.LoginWithBrowser(ctx, thalovant.DeviceLoginOptions{
  Scopes:     []string{"hubs:read", "clients:write"}, // optional
  ClientName: "my-cli",                               // optional label in the dashboard
})
if err != nil {
  log.Fatal(err)
}
fmt.Println("signed in, token id:", token["token_id"])

Gérez le jeton obtenu sur la page API Tokens du tableau de bord.

S’authentifier avec un jeton d’API

Passez un jeton d’API enregistré lorsque le processus doit démarrer déjà authentifié, par exemple pour les tâches d’intégration continue et les services. Créez-en un sur la page API Tokens ou avec LoginWithBrowser. Cette page affiche les portées, l’expiration et la dernière utilisation, et permet de révoquer le jeton à tout moment.

control := thalovant.NewDefaultControlPlane(os.Getenv("THALOVANT_API_TOKEN"))

page, err := control.ListHubs(ctx, 50, "", "")

Utiliser une identité enregistrée

client, err := thalovant.NewClientFromConfig("", "prod")
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

Les fichiers d’identité bruts fonctionnent aussi :

client, err := thalovant.NewClientFromFile("_identity.json")
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

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

Les variables d’environnement fonctionnent aussi :

client, err := thalovant.NewClientFromEnv()
if err != nil {
  log.Fatal(err)
}

Où le SDK conserve ses clés

Le SDK se connecte par WSS, par HTTPS ou par MQTT sur TLS. Chaque connexion est chiffrée et authentifiée avant l’envoi de quoi que ce soit.

Utilisez le champ NoiseStateDir du transport pour choisir le répertoire privé et persistant où le SDK conserve ses clés et les identités de hub qu’il a enregistrées; RemoteStaticKey expose la clé du hub authentifié. Partagez le même répertoire lorsqu’une identité passe d’un transport à un autre. Utilisez une identité distincte pour chaque processus client qui s’exécute en même temps, et confirmez auprès du propriétaire du hub toute identité de hub modifiée avant de l’accepter.

Définissez le répertoire avant de vous connecter. Par exemple, avec WSS :

transport := thalovant.NewWSSTransport(identity)
transport.NoiseStateDir = "/path/to/private/persistent/sdk-state"
client := &thalovant.Client{Identity: identity, Transport: transport}

HTTPS conserve sa session d’une reconnexion à l’autre et nettoie une connexion périmée avant de se reconnecter après une interrogation échouée. MQTT exige TLS et accepte une TLSConfig personnalisée pour les autorités de certification privées. Après la perte de la connexion au courtier (broker), appelez de nouveau Connect avant d’envoyer quoi que ce soit.

Utilisez de nouveaux identifiants de demande (request IDs) pour Ask et de nouveaux identifiants d’interrogation (query IDs) pour Query; des identifiants générés sont utilisés par défaut. Un collecteur concurrent qui porte le même identifiant est refusé sur le même client. Les espaces de noms sont indépendants. Ne réutilisez pas un identifiant pour une opération logique ultérieure, même après une annulation : une réponse retardée peut encore le porter. Réutilisez un identifiant de session pour conserver le contexte de la conversation.

Choisir un protocole

identity := result.Identity

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

for _, protocol := range []thalovant.HubProtocol{
  thalovant.ProtocolWSS,
  thalovant.ProtocolHTTPS,
  thalovant.ProtocolMQTT,
} {
  if !identity.SupportsProtocol(protocol) {
    continue
  }
  if protocol == thalovant.ProtocolMQTT && identity.MQTT == nil {
    continue
  }

  client, err := thalovant.NewClientWithOptions(identity, thalovant.ClientOptions{Protocol: protocol})
  if err != nil {
    log.Fatal(err)
  }
  reply, err := client.Ask(ctx, fmt.Sprintf("Reply over %s.", protocol), thalovant.RequestOptions{})
  _ = client.Close(ctx)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(protocol, reply.Text)
}

MQTT exige les identifiants de courtier Identity.MQTT renvoyés pour ce client.

NewClientWithOptions sans protocole explicite, ainsi que les fonctions basées sur un fichier, une configuration ou l’environnement, choisissent WSS, puis HTTPS, puis MQTT. L’ancien constructeur NewClient(identity) choisit HTTPS; utilisez le constructeur à options lorsque vous voulez la sélection du protocole.

Pour les détails sur le courtier, consultez MQTT.

Ajouter du contexte

requestContext := thalovant.BuildClientContext(nil, thalovant.ClientContextOptions{
  UserID:       "user-42",
  UserName:     "Ada",
  AuthProvider: "oidc",
  Source:       "checkout-kiosk",
  Platform:     "kiosk",
  Locale:       "en-US",
  Channel:      "chat",
})

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

Écouter les événements

events := client.Transport.Events()

if err := client.SendUtterance(ctx, "Say the current status.", thalovant.RequestOptions{}); err != nil {
  log.Fatal(err)
}

select {
case event := <-events:
  fmt.Println(event.Name, event.Text())
case <-time.After(12 * time.Second):
  log.Fatal("timed out waiting for a hub event")
}

Lister ce qu’on peut demander au hub

Un client connecté peut lister chaque intention à laquelle son hub répond, par langue, avec les phrases qu’une personne prononce pour atteindre chacune d’elles. Il le fait dans sa propre session, sans jeton du plan de contrôle. Consultez Que peut-on demander à mon hub? pour savoir ce que le hub renvoie, quels types de messages la connexion doit être autorisée à publier et à quoi ressemblent un refus ou une liste en échec.

Depuis le SDK v0.3.13, les appels sont client.Intents(ctx, languages, opts...), qui renvoie l’inventaire regroupé par compétence, client.ListIntents(ctx, lang, opts...), qui renvoie les lignes d’enregistrement, et client.DescribeIntent(ctx, skillID, intentName, lang, opts...), qui renvoie les définitions derrière une intention. L’argument des options est variadique : omettez-le pour utiliser les valeurs par défaut.

inventory, err := client.Intents(ctx, []string{"en-us", "fr-fr"})
if err != nil {
  var denied *thalovant.PolicyDeniedError
  if errors.As(err, &denied) {
    log.Fatalf("refused %s; allowed %v", denied.DeniedType, denied.Allowed)
  }
  log.Fatal(err)
}

fmt.Println(inventory.Source, inventory.Languages)
for _, skill := range inventory.Skills {
  for _, intent := range skill.Intents {
    fmt.Println(intent.ID(), intent.Engine, intent.Examples("fr-fr", 2))
  }
}

Intents interroge ovos.intent.list une fois par langue, puis complète les phrases que la liste ne contenait pas. IntentOptions règle l’appel : Timeout limite la durée de chaque requête envoyée au hub (cinq secondes lorsqu’il vaut zéro), et Describe, réglé sur un pointeur vers false, s’arrête aux noms, aux moteurs et à l’état d’activation. Examples(lang, limit) préfère les phrases complètes à celles qui contiennent un {slot}, puis les formulations les plus complètes, jusqu’à huit mots; PhrasesFor(lang) les renvoie toutes. Les étiquettes de langue se comparent sans tenir compte de la casse ni de la différence entre _ et - : fr-fr et fr_FR constituent donc une seule et même demande. Les transports intégrés donnent à ces appels des abonnements indépendants. Un abonné lent reçoit une erreur de débordement explicite sans consommer les réponses d’une autre requête. Les transports personnalisés hérités qui n’exposent que des canaux partagés doivent sérialiser leurs appelants.

Un hub qui refuse une requête renvoie immédiatement une *PolicyDeniedError, que errors.As déballe pour exposer DeniedType, Code, Reason et Allowed. Avec la valeur par défaut de Fallback, un ovos.intent.list refusé ou resté sans réponse renvoie plutôt les noms seulement : inventory.Source vaut engine-manifests, inventory.Denied nomme la requête indisponible sans prouver un refus de politique, et HasPhrases() vaut false. Un hub qui accepte la demande de liste et y répond avec ok: false renvoie une erreur qui enveloppe ErrRuntime et porte le texte d’erreur propre au hub, car une liste en échec n’est pas un hub vide. Depuis la version v0.3.14, cette erreur remplace la liste vide que le SDK renvoyait auparavant.

Fonctions utiles

Ask

Envoyez une requête et recevez du texte, de la parole et des éléments d’affichage normalisés.

Conversation

Gardez les échanges liés dans une même session.

SendAction

Envoyez une action de bouton, de menu ou d’outil.

SendCode

Envoyez une valeur numérisée, un numéro de série, une valeur QR ou un code saisi.

Pour la liste complète des méthodes, consultez Fonctions des SDK. Utilisez control.GetOperation(ctx, operationID) pour suivre une commande acceptée; consultez Opérations.

Provisionner des hubs

Depuis le SDK v0.3.6, le plan de contrôle peut créer des hubs, des groupes de runtime et des installations de compétences. Parcourir le catalogue avec ListMarketplaceSkills exige hubs:read et fonctionne avec tous les forfaits. CreateHub, CreateRuntimeGroup, InstallRuntimeGroupSkill, ReleaseHub et ReleaseRuntimeGroup exigent hubs:write et un forfait payant.

group, err := api.CreateRuntimeGroup(ctx, map[string]any{"name": "kiosks"})
hub, err := api.CreateHub(ctx, map[string]any{
  "name":             "joke-garden",
  "runtime_group_id": group["id"].(string),
  "spec":             map[string]any{},
}, thalovant.HubCreateOptions{})

hub, err = api.GetHub(ctx, hub["id"].(string))
hub, err = api.UpdateHub(ctx, hub["id"].(string), map[string]any{"active": false}, hub["etag"].(string))

UpdateHub et DeleteHub prennent l’etag actuel du hub comme argument obligatoire. Consultez Provisionner des hubs pour le déroulement complet, les champs immuables et le tableau des erreurs.

Problèmes courants

Symptôme	Vérification
Jeton d’accès manquant	Appelez control.Login(...) ou control.LoginWithBrowser(...) avant les actions d’API privées, ou passez un jeton à NewDefaultControlPlane.
HTTP 401 avec le code mfa_required	Utilisez control.LoginWithOptions(...) avec un OTPCode ou un RecoveryCode.
L’accès à l’API exige un forfait payant	Passez l’espace de travail à un forfait supérieur avant de provisionner des ressources privées au moyen de l’API.
Protocole non pris en charge	Activez ce protocole sur le hub et créez une nouvelle identité.
MQTT échoue immédiatement	Confirmez que l’identité possède des identifiants de courtier Identity.MQTT.

Capacités de repli et échéances des requêtes

Utilisez l’enveloppe de capacités, qui s’ajoute à l’existant, pour décider si un hub peut répondre dans une langue. La forme actuelle de HubIntentInventory reste compatible :

capabilities, err := client.IntentsWithCapabilities(ctx, []string{"en-us"}, thalovant.IntentOptions{})
if err != nil { return err }
fmt.Println(capabilities.Inventory.Source, capabilities.FallbacksKnown)
fmt.Println(capabilities.MayAnswer("en-us"))

ListFallbacks(ctx, timeout) renvoie nil lorsque la prise en charge est inconnue et une tranche vide non nulle pour un résultat vide confirmé. Les appels directs respectent le délai positif fourni, cinq secondes par défaut. La sonde automatique de IntentsWithCapabilities inclut la connexion, l’envoi et l’attente en 1,5 seconde au plus. Consultez la découverte des gestionnaires de repli.

AskWithOptions prend des AskOptions, qui intègrent les RequestOptions existantes ainsi que ReplySettle et EmptyReplyWait. Les valeurs par défaut accordent 250 ms aux fragments adjacents et cinq secondes à la parole retardée après un échec léger, à l’intérieur de l’échéance globale de la requête. Query attend son achèvement corrélé; un événement de parole ultérieur peut rattraper une intention non reconnue. Un refus de politique ou un délai de requête explicite dépassé conserve une réponse partielle en échec.

Les échéances de connexion et de nettoyage incluent le temps passé en file d’attente derrière une opération antérieure. Un appelant dont le délai a expiré ne peut pas s’emparer du transport d’une autre opération. Continuez d’utiliser le même client jusqu’à la fin du nettoyage en cours; ne créez pas de clients concurrents avec la même identité. Ne copiez pas un Client après sa première utilisation. Sous Windows, stockez les clés enregistrées du SDK dans un répertoire privé à l’application, avec des listes de contrôle d’accès (ACL) héritées restrictives; les bits de mode POSIX n’établissent pas le contrôle d’accès de Windows.

Les redirections du plan de contrôle sont refusées. Les appels d’API authentifiés et les corps de requête exigent HTTPS, sauf pour les points de terminaison de développement explicitement en boucle locale (loopback). Consultez la sécurité des identifiants d’API.

Attentes et flux d’événements

WaitForEvent(ctx, name, EventOptions) attend un événement corrélé, avec un budget par défaut de douze secondes. Listen(ctx, name, ListenOptions) renvoie un Subscription[Event] borné. Les options permettent de choisir le délai d’expiration, le contexte, l’identifiant de session, l’identifiant de requête et le prédicat; les options d’écoute permettent aussi de choisir MaxEvents et Capacity.

Annulez le contexte ou fermez l’abonnement pour vous désabonner. Le débordement et la déconnexion sont des erreurs explicites. Un abonné annulé ou lent ne consomme pas les réponses d’un autre appelant et ne ferme pas la connexion partagée. Listen n’a aucune limite de durée ni de nombre à moins que vous n’en fixiez une, mais sa file d’attente reste bornée.

Gérer les compétences par l’intermédiaire d’un hub

Le SDK peut lister, installer, mettre à jour et retirer les compétences du groupe de runtime d’un hub, et en consulter l’historique. Tous les hubs qui partagent ce groupe de runtime sont touchés. L’UUID d’un hub sélectionne le groupe; il ne crée pas d’installation isolée pour ce hub. Un jeton restreint doit couvrir tous les hubs que sert le groupe.

Les lectures exigent hubs:inspect (hubs:read l’inclut). Les écritures exigent hubs:write, un forfait payant admissible et la propriété. Utilisez latest ou une version publiée précise pour l’installation et les mises à jour. Une écriture acceptée renvoie un operation_id; l’acceptation ne signifie pas que le runtime a fini d’installer la compétence.

Action	Méthode
Lister	ListHubSkills
Historique	ListHubSkillHistory
Installer	InstallHubSkill
Mettre à jour	UpdateHubSkill
Retirer	RemoveHubSkill

L’historique renvoie l’enveloppe JSON de l’API avec des entrées event et operation, de la plus récente à la plus ancienne, en conservant les champs d’acteur et de version qui peuvent être nuls. La limite est de 1 à 200.

Utilisez HubSkillWaitOptions pour activer l’attente de l’opération (120 secondes, avec une interrogation toutes les deux secondes par défaut). Pour les appels sensibles à l’annulation, soumettez d’abord la demande sans attendre, conservez la réponse d’acceptation, puis appelez WaitForHubSkillOperation. Annuler l’attente n’annule pas l’opération acceptée sur le serveur. Les échecs d’interrogation conservent l’identifiant de l’opération dans l’erreur; consultez cette opération au lieu de répéter l’écriture. L’échéance d’attente empêche de nouvelles interrogations, mais n’annule pas une requête déjà en cours.

Fonctions de requête et mises à jour sûres de la configuration

Disponible depuis la version 0.7.0.

AskOptions et Reply reçoivent de nouveaux champs dans cette version. Utilisez des littéraux de structure à champs nommés lorsque vous mettez à jour du code qui construisait ces types de façon positionnelle.

Les indications de requête transmettent une langue reconnue, un pipeline d’intentions ordonné et l’emplacement de l’appelant, sans modifier le contexte de l’appelant. Les indications vides sont omises. La fonction d’emplacement exige une ville et omet les coordonnées invalides ou égales à zéro/zéro. Le hub valide les indications de langue par rapport aux langues configurées.

Les réponses exposent leur langue déclarée, leurs événements de parole et d’audio ordonnés et le nombre de médias abandonnés. Les extraits intégrés par les compétences sont limités à 4 Mio chacun et à 16 Mio par réponse, vérifiés avant la conservation et le décodage. L’audio ne prolonge pas la fenêtre de stabilisation de la réponse. Le décodage accepte des octets hexadécimaux séparés par des espaces ASCII; il ne récupère jamais une URL ni un chemin de fichier fournis par une compétence. La lecture relève de l’application. Toute fonction play ou Play ci-dessous appartient à votre application.

location := thalovant.BuildLocation(thalovant.LocationOptions{City: "Montréal", Country: "CA"})
reply, err := client.AskWithOptions(ctx, "Quel temps fait-il ?", thalovant.AskOptions{
    STTLang: "fr-ca", Location: location,
})
// Check err before reading reply. AudioBytes returns ([]byte, error).
examples := intent.ExamplesWithOptions("en-us", 2, thalovant.IntentExampleOptions{Speakable: true})
delta := map[string]any{"lang": "en-us"}
_, err = control.UpdateRuntimeGroupConfig(ctx, groupID, delta, thalovant.RuntimeGroupConfigOptions{})
// Explicit full replacement:
fullConfig := map[string]any{"lang": "en-us"}
_, err = control.ReplaceRuntimeGroupConfig(ctx, groupID, fullConfig, thalovant.RuntimeGroupConfigOptions{})

La fusion protégée exige les portées hubs:read et hubs:write et un forfait payant. La fusion sûre exige une API dont le GET de configuration renvoie une revision valide et dont le PUT de configuration vérifie expected_revision. Le SDK relit la configuration et réapplique le delta d’origine seulement après une erreur HTTP 412, avec au plus trois tentatives. Les tableaux et les valeurs scalaires sont remplacés; les objets sont fusionnés récursivement. Les personas ne sont remplacés que s’ils sont fournis explicitement. Les échecs de connexion, les redirections, les autres états et les résultats d’écriture ambigus ne font jamais l’objet d’une nouvelle tentative. Aucun repli PATCH non sûr n’est utilisé. Les remplacements inconditionnels doivent tout de même être coordonnés avec les autres processus qui écrivent.

Utilisez l’opération de remplacement explicite montrée ci-dessus lorsque vous voulez un remplacement complet, y compris avec une API plus ancienne. Le code existant qui compte sur le remplacement doit l’activer explicitement lors de la mise à jour. Les motifs d’intention bruts restent la valeur par défaut; les exemples prononçables retirent les parties facultatives, choisissent parmi les variantes et substituent les valeurs d’emplacement fournies par l’appelant, tout en gardant la priorité aux phrases complètes.

Les limites audio s’appliquent à des bornes supérieures calculées sur la longueur encodée avant le décodage : les espaces de mise en forme consomment donc aussi le budget. Comme avec bytes.fromhex de Python, des espaces ASCII seuls se décodent en zéro octet. Les extraits mal formés, mais dans les limites, restent disponibles comme métadonnées d’événement et échouent au décodage; ils ne sont jamais récupérés ni lus automatiquement. Des événements audio distincts peuvent volontairement répéter un contenu sonore identique. Seule la livraison répétée du même objet événement est supprimée, lorsque l’identité de l’objet est disponible, sans être comptée comme un extrait abandonné. Le classement des exemples rendus tient compte de la présence d’emplacements dans le motif d’origine, même lorsque des valeurs d’exemple sont fournies.

Listes d’intentions adaptées aux paramètres régionaux

Disponible depuis la version 0.8.1.

Les listes de phrases utilisent les données groupées thalovant-languages 0.2.1 et correspondent à Python 0.6.8 avec son extra de listes. La sélection de la langue suit les distances régionales d’OVOS : une demande pour fr-CA peut donc utiliser des paramètres régionaux fr-FR enregistrés.

examples := intent.ExamplesWithOptions("fr-CA", 2, thalovant.IntentExampleOptions{Sentence: true})
text := thalovant.AsSentence("what time is it", "en-US")
sample := thalovant.SpeakableWithLanguage("play {song}", nil, "en-US")

AsSentence(text, lang string) string produit le rendu d’une phrase. SpeakableWithLanguage(pattern string, slots map[string]string, lang string) string utilise les exemples d’emplacements régionaux avant les valeurs explicites qui les remplacent.

Le rendu en phrase implique le rendu prononçable. Les valeurs d’emplacement explicites l’emportent sur les exemples régionaux. Les phrases complètes sont classées avant les préfixes et les motifs à emplacements; les exemples rendus vides ou en double ne comptent pas dans la limite. Sans limite, les exemples bruts gardent l’ordre d’enregistrement. Pour des paramètres régionaux inconnus, le texte brut et les noms d’emplacements sont conservés.

Les méthodes d’exemples existantes restent disponibles. Utilisez ListingRules pour fournir un instantané complet de données personnalisées ou choisir un rendu brut sans données régionales. Aucune requête réseau n’est nécessaire pour charger les règles groupées. Consultez le README du dépôt pour la construction de règles personnalisées et la gestion des erreurs d’expressions régulières.

Les données de listes décrivent maintenant 270 langues, y compris les variantes régionales. L’espagnol qué hora es devient Qué hora es?, et le français coupe le son devient Coupe le son.. Les langues sans règles, comme tlh, restent brutes.

Sessions gérées et caches d’inventaire

HubSession gère une connexion au hub réutilisable. Fournissez une fabrique qui renvoie un client connecté et qui nettoie toute tentative de connexion échouée ou annulée. Les abonnements aux événements survivent au remplacement du client. Go et Rust exposent un flux d’événements persistant; les autres SDK gérés exposent des descripteurs d’abonnement. Fermez la session lorsque son propriétaire s’arrête; la fermeture attend les opérations acceptées et est définitive.

Les tentatives de connexion en arrière-plan s’espacent de 10, 20, 40, 80, puis 120 secondes. Les appels au premier plan peuvent réessayer immédiatement. La planification des sondes relève de votre application : utilisez le délai de sonde indiqué (60 secondes en état retenu, 5 secondes en état hors service). Le SDK ne rejoue jamais un Ask ou un Emit accepté après une réponse perdue, car un Ask peut déclencher une action. Le délai d’expiration d’une requête s’applique à l’opération sous-jacente; l’attente de la session et votre fabrique de connexions ont des budgets distincts.

session, err := thalovant.NewHubSession(connectClient, thalovant.DefaultHubSessionPolicy())
if err != nil { return err }
defer session.Close(context.Background())
reply, err := session.Ask(ctx, "What is the weather?", thalovant.AskOptions{})

Inventory, Skill et Intent offrent une vue présentable, distincte de l’inventaire d’intentions natif du runtime. Les paramètres régionaux inconnus du catalogue restent inconnus; des phrases observées pour une langue ne prouvent pas que le catalogue la prend en charge. Les exemples choisissent les paramètres régionaux pris en charge les plus proches. Une limite nulle ou négative renvoie l’ensemble brut des phrases (Rust utilise zéro pour sa limite non signée). Le JSON du cache inclut l’ordre explicite des langues des intentions, pour que la sérialisation ne puisse pas changer la langue par défaut des exemples.

InventoryCache est facultatif, a une durée de vie (TTL) d’une heure par défaut et signale une absence pour les données invalides, expirées ou illisibles. Les écritures utilisent des fichiers temporaires privés et uniques et un remplacement atomique. Sous POSIX, les fichiers de cache sont lisibles et modifiables par leur propriétaire seulement; Windows utilise les listes de contrôle d’accès (ACL) du répertoire de l’utilisateur. Les clés de cache distinguent le mode, le chemin de l’identité et le nom d’hôte complet et normalisé du hub. N’utilisez jamais les caches d’inventaire pour stocker des identifiants.

OriginPreference accorde à une adresse préférée son propre budget de connexion court et la met en pause après un échec. Dans les SDK autres que Python, la fabrique doit mettre en œuvre la liaison à l’adresse dans son propre transport, conserver l’hôte public pour TLS/SNI et terminer le nettoyage des tentatives échouées avant de rendre la main. Les restrictions du transport et de la plateforme s’appliquent toujours. Cette fonction ne modifie pas le DNS global et ne désactive pas la validation TLS.

Revendication des réponses

Une réponse expose reply.PipelineIDs(), reply.SkillIDs() et reply.Claimed().

Les identifiants de pipeline et de compétence sont des chaînes non vides, dans l’ordre de leur première apparition, sans doublons. Une réponse réussie dont les seuls identifiants de pipeline contiennent le texte fallback (sensible à la casse) est signalée comme non revendiquée. Toute étape autre que le repli rend revendiquée une réponse réussie. Les réponses réussies de hubs plus anciens, sans marques d’étape, restent revendiquées. Les réponses en échec ou non traitées ne sont jamais revendiquées. Les marques mal formées qui ne sont pas des chaînes sont ignorées.

Servez-vous-en comme d’un indice pour décider de poursuivre ou non une conversation. Le texte de repli et l’état de réussite existant sont conservés. Ces marques ne constituent pas une identité de pair vérifiée et ne doivent pas autoriser d’actions.