# SDK Go

> Installez le SDK Go de Thalovant pour vos services, passerelles, outils en ligne de commande et agents de longue durée.

Source: https://docs.thalovant.com/fr/developers/sdks/go/

---
{/* Last Edit: Claude Opus 5.5 - 2026-09-28 - Motive: Canadian French translation of developers/sdks/go.mdx; terms per docs/french-glossary.md (AMF, serveur), and review fixes. */}

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` :

```bash
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](/fr/developers/sdks/#versions-prises-en-charge).

## Première requête

```go
package main

	"context"
	"fmt"
	"log"

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

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

	_, err := control.Login(ctx, "you@example.com", "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é.

  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.

```go
_, err := control.LoginWithOptions(ctx, "you@example.com", "password", thalovant.LoginOptions{
	OTPCode: "123456",
})

// Or use a one-time recovery code instead:
_, err = control.LoginWithOptions(ctx, "you@example.com", "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.

```go
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](/fr/account/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](/fr/account/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.

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

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

## Utiliser une identité enregistrée

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

Les fichiers d'identité bruts fonctionnent aussi :

```go
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 :

```go
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 :

```go
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

```go
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](/fr/developers/mqtt/).

## Ajouter du contexte

```go
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

```go
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?](/fr/concepts/hub-intents/) 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.

```go
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

  
    Envoyez une requête et recevez du texte, de la parole et des éléments d'affichage normalisés.
  
  
    Gardez les échanges liés dans une même session.
  
  
    Envoyez une action de bouton, de menu ou d'outil.
  
  
    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](/fr/developers/sdk-functions/).
Utilisez `control.GetOperation(ctx, operationID)` pour suivre une commande acceptée; consultez [Opérations](/fr/developers/operations/).

## 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.

```go
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](/fr/developers/provisioning/) 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 :

```go
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](/fr/concepts/hub-intents/#gestionnaires-de-repli-et-disponibilité-des-langues).

`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](/fr/developers/sdks/#sécurité-des-identifiants-dapi).

## 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.

```go
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.

```go
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.

```go
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.