SDK Node

Utilisez le SDK Node lorsque votre client ou votre agent s’exécute en JavaScript ou en TypeScript.

Le nom du paquet est @thalovant/sdk. Node.js 20 ou une version plus récente est requis.

Installation

Installez le paquet avec npm install @thalovant/sdk :

npm

npm i @thalovant/sdk

pnpm

pnpm add @thalovant/sdk

yarn

yarn add @thalovant/sdk

Épinglez la version lorsque vous avez besoin d’une compilation reproductible. La version actuelle figure dans Versions prises en charge.

Première requête

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();

const publicHubs = await api.listPublicHubs({ limit: 1 });
const [hub] = publicHubs.data as Array<{ id: string; slug: string; title: string }>;
console.log(hub.title, hub.slug);

await api.login("[email protected]", "password");

const result = await api.createClientIdentity(hub.id, {
  name: "node-demo-client",
  preferredProtocols: ["wss", "https", "mqtt"],
});

const client = new ThalovantClient(result.identity, { protocol: "wss" });
try {
  const reply = await client.ask("Tell me a short clean joke.");
  console.log(reply.text);
} finally {
  await client.close();
}

new ThalovantControlPlane() utilise https://api.thalovant.com par défaut.

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. Sans l’un ou l’autre, l’API refuse la connexion avec une erreur HTTP 401 et le code mfa_required. Chaque option n’est envoyée que si elle est fournie. La prise en charge de l’AMF exige le SDK 0.2.23 ou une version plus récente.

await api.login("[email protected]", "password", { otpCode: "123456" });

// Or use a one-time recovery code instead:
await api.login("[email protected]", "password", { recoveryCode: "abcd-efgh-ijkl" });

Se connecter sans mot de passe

La connexion par appareil demande à votre navigateur d’approuver la connexion : vos scripts, bots 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 0.2.25 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.

// Prints: To sign in, visit https://dash.thalovant.com/activate and enter the code XXXX-XXXX
const token = await api.loginWithBrowser({ clientName: "my-laptop" });

// api.accessToken is now set, exactly like after api.login(...).
const page = await api.listHubs({ limit: 50 });

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.

const api = new ThalovantControlPlane("https://api.thalovant.com", {
  accessToken: process.env.THALOVANT_API_TOKEN,
});

// Ready immediately; no login call needed.
const page = await api.listHubs({ limit: 50 });

Utiliser le SDK dans un navigateur

Le SDK fonctionne aussi dans les navigateurs, derrière un outil de regroupement (bundler). Il faut pour cela le SDK 0.2.24 ou une version plus récente.

Le plan de contrôle, y compris login, listPublicHubs, createClientIdentity, la mémoire et les analyses, utilise le fetch global. ThalovantClient fonctionne avec les protocoles wss et https au moyen du WebSocket global.

Le paquet fournit une table browser à côté de son entrée exports. Les outils de regroupement comme esbuild, webpack, Vite et Rollup choisissent donc automatiquement les modules compatibles avec les navigateurs et n’intègrent jamais ws, mqtt ni les modules intégrés node: dans les paquets web. Regroupez-le comme n’importe quelle autre dépendance :

esbuild app.js --bundle --platform=browser --outfile=dist/app.js

// app.js — runs in the browser after bundling
import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();
await api.login(email, password);
const result = await api.createClientIdentity(hubId, { name: "web-kiosk" });

const client = new ThalovantClient(result.identity, { protocol: "wss" });
try {
  const reply = await client.ask("Hello from the browser.");
  console.log(reply.text);
} finally {
  await client.close();
}

Mises en garde pour les navigateurs :

• Le protocole mqtt reste réservé à Node. Construire le transport MQTT dans un navigateur lève ThalovantUnsupportedProtocolError avec un message clair; utilisez plutôt wss ou https.
• Les fichiers d’identité et les configurations YAML restent réservés à Node. ThalovantIdentity.fromFile(), fromConfig() et defaultConfigPath() lèvent une erreur dans les navigateurs; construisez ThalovantIdentity à partir d’un objet en mémoire, comme le résultat de createClientIdentity.
• Dans les navigateurs, le SDK conserve ses clés dans localStorage, sous l’espace de noms thalovant:noise par défaut. Tout ce qui y est stocké peut être lu par les scripts de cette origine. Conservez cet état d’un chargement de page à l’autre, et utilisez un espace de noms et une identité distincts pour chaque onglet actif de façon indépendante. La file d’attente du navigateur ne coordonne qu’une seule page; elle ne sérialise pas les modifications entre les onglets. Si le stockage du navigateur n’est pas disponible ou qu’une écriture échoue, le nouvel état ne dure que le temps de cette page. Un chargement ultérieur peut alors être refusé par un hub qui a épinglé la clé précédente du client. Restaurez l’état d’origine ou provisionnez une identité de client de remplacement au lieu de réinitialiser automatiquement les épinglages.
• Une identité de client reste secrète, même pour un hub public. Obtenez-la au moment de l’exécution pour l’utilisateur ou l’appareil autorisé; n’intégrez jamais une identité partagée, un jeton d’API ou un mot de passe dans le paquet JavaScript livré. Demandez une origine SDK approuvée avant d’appeler l’API à partir d’un domaine de navigateur appartenant à un client.

Utiliser une identité enregistrée

import { ThalovantClient } from "@thalovant/sdk";

const client = await ThalovantClient.fromConfig({ profile: "prod", protocol: "wss" });
try {
  const reply = await client.ask("What can this hub do?");
  console.log(reply.text);
} finally {
  await client.close();
}

Les fichiers d’identité bruts fonctionnent aussi :

import { ThalovantClient } from "@thalovant/sdk";

const client = await ThalovantClient.fromIdentityFile("_identity.json");
try {
  const reply = await client.ask("What can this hub do?");
  console.log(reply.text);
} finally {
  await client.close();
}

Les variables d’environnement fonctionnent aussi :

import { ThalovantClient } from "@thalovant/sdk";

const client = ThalovantClient.fromEnv();

Où le SDK conserve ses clés

Dans Node.js, le SDK se connecte par WSS, par HTTPS ou par MQTT sur TLS; les versions pour navigateur utilisent WSS et HTTPS. Chaque connexion est chiffrée et authentifiée avant l’envoi de quoi que ce soit.

L’option facultative noiseStateDir est acceptée par le constructeur du client ainsi que par fromIdentityFile, fromConfig et fromEnv. Dans Node.js, elle désigne le répertoire privé où le SDK conserve ses clés et les identités de hub qu’il a enregistrées; conservez-le d’un redémarrage à l’autre. Dans les navigateurs, la même option nomme un espace de noms localStorage plutôt qu’un chemin. Utilisez une identité distincte pour chaque processus client qui s’exécute en même temps.

MQTT exige un point de terminaison TLS. Régler tls: true fait passer mqtt:// à mqtts:// et ws:// à wss://; les schémas effectifs non pris en charge ou en clair sont refusés avant l’envoi des identifiants du courtier (broker). La connexion MQTT, l’abonnement, l’authentification et la présence en ligne partagent le délai de connexion. Le nettoyage après un échec HTTPS reste lui aussi dans les limites du délai de connexion d’origine.

const client = await ThalovantClient.fromIdentityFile("identity.json", {
  protocol: "https",
  noiseStateDir: "/path/to/private/persistent/sdk-state",
});

HTTPS conserve sa session d’une reconnexion à l’autre et nettoie sa connexion précédente avant d’en ouvrir une nouvelle. Après la perte de la connexion au courtier, MQTT s’authentifie de nouveau. healthcheck().handshakeComplete reste à false tant que l’authentification n’est pas terminée; un socket ouvert ou une réponse HTTP réussie ne suffit pas à lui seul.

connect(timeoutMs?, signal?) utilise une seule échéance pour le nettoyage en file d’attente, l’établissement de la connexion et la disponibilité authentifiée, avec une valeur par défaut de 6 000 ms. close(timeoutMs?) limite l’attente de l’appelant avec la même valeur par défaut. Si la fermeture dépasse le délai, le nettoyage conserve la maîtrise de la connexion. await client.waitForClosed() observe le nettoyage réel le plus récent, sans délai d’expiration, et en conserve l’échec éventuel. Attendez la fin de ce nettoyage avant de réutiliser l’identité.

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.

Node écrit ses clés enregistrées de façon atomique entre les processus. Des clés enregistrées endommagées arrêtent l’opération sans réinitialiser ce qui a été enregistré. Si un processus qui a planté laisse .noise-state.lock derrière lui, confirmez que le processus est bien arrêté avant de supprimer uniquement le fichier de verrou, et gardez les fichiers de clés. Ce verrou ne coordonne ni les sessions de hub actives ni les onglets de navigateur.

Choisir un protocole

const identity = result.identity;

console.log(identity.enabledProtocols());
console.log(identity.endpointFor("wss"));
console.log(identity.endpointFor("https"));
console.log(identity.endpointFor("mqtt"));

for (const protocol of ["wss", "https", "mqtt"] as const) {
  if (!identity.supportsProtocol(protocol)) continue;
  if (protocol === "mqtt" && !identity.mqtt) continue;

  const client = new ThalovantClient(identity, { protocol });
  try {
    const reply = await client.ask(`Reply over ${protocol}.`);
    console.log(protocol, reply.text);
  } finally {
    await client.close();
  }
}

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

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

Ajouter du contexte

import { buildClientContext } from "@thalovant/sdk";

const context = buildClientContext({}, {
  userId: "user-42",
  userName: "Ada",
  source: "checkout-kiosk",
  platform: "kiosk",
  locale: "en-US",
  channel: "chat",
});

const reply = await client.ask("Show the next instruction.", { context });
console.log(reply.text);

Écouter les événements

import { EVENT_SPEAK } from "@thalovant/sdk";

const sub = client.on(EVENT_SPEAK, event => {
  console.log(event.text);
});

try {
  await client.ask("Say the current status.");
} finally {
  sub.close();
}

Enregistrez l’écouteur avant l’envoi pour qu’il puisse observer les réponses rapides. ask() corrèle aussi sa propre réponse; l’abonnement observe les événements du bus correspondants pendant l’exécution de la requête.

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 0.2.38, les appels sont client.intents(languages, options), qui renvoie l’inventaire regroupé par compétence, client.listIntents(lang, options), qui renvoie les lignes d’enregistrement, et client.describeIntent(skillId, intentName, lang, options), qui renvoie les définitions derrière une intention.

import { ThalovantClient, ThalovantPolicyDeniedError } from "@thalovant/sdk";

const client = await ThalovantClient.fromIdentityFile("_identity.json");
try {
  const inventory = await client.intents(["en-us", "fr-fr"]);
  console.log(inventory.source, inventory.languages);
  for (const skill of inventory.skills) {
    for (const intent of skill.intents) {
      console.log(intent.id, intent.engine, intent.examples("fr-fr"));
    }
  }
} catch (error) {
  if (error instanceof ThalovantPolicyDeniedError) {
    console.error("refused:", error.deniedType, "allowed:", error.allowed);
  }
  throw error;
} finally {
  await client.close();
}

intents() interroge ovos.intent.list une fois par langue, puis complète les phrases que la liste ne contenait pas. { describe: 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, et inventory.asObject() est prêt pour JSON.stringify. 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.

Un hub qui refuse une requête la rejette immédiatement avec ThalovantPolicyDeniedError, une ThalovantRuntimeError qui porte deniedType, code, reason et allowed. Avec la valeur par défaut { fallback: true }, un ovos.intent.list refusé ou resté sans réponse renvoie plutôt les noms seulement : inventory.source vaut "engine-manifests", inventory.denied vaut ["ovos.intent.list"] et inventory.hasPhrases vaut false. Un hub qui accepte la demande de liste et y répond avec ok: false provoque un rejet avec ThalovantRuntimeError, qui porte le texte d’erreur propre au hub, car une liste en échec n’est pas un hub vide. Depuis la version 0.2.39, ce rejet 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.

waitForEvent

Attendez un événement du hub correspondant, avec un délai d’expiration.

sendAction

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

sendCode

Envoyez un code-barres, une valeur QR, un numéro de série ou une valeur exacte saisie.

Pour la liste complète des méthodes, consultez Fonctions des SDK. Utilisez api.getOperation(operationId) pour suivre une commande acceptée; consultez Opérations.

Provisionner des hubs

Depuis le SDK 0.2.28, 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.

const group = await api.createRuntimeGroup({ name: "kiosks" });
let hub = await api.createHub({ name: "joke-garden", runtimeGroupId: group.id as string, spec: {} });

hub = await api.getHub(hub.id as string);
await api.updateHub(hub.id as string, { active: false }, { etag: hub.etag as string });

updateHub et deleteHub exigent l’etag actuel du hub. Consultez Provisionner des hubs pour le déroulement complet, les champs immuables et le tableau des erreurs.

À partir du SDK 0.3.15, listHubSkills, installHubSkill, updateHubSkill et removeHubSkill gèrent les compétences d’un hub désigné par son identifiant. listHubSkills se résout avec { data, source, observed_at, ... } (for (const skill of (await api.listHubSkills("hub-id")).data)), les écritures se résolvent avec une HubSkillOperation, et { wait: true } interroge cette opération avec un budget d’interrogation par défaut de 120 secondes (timeoutMs). Consultez Ajouter une compétence à un hub.

Aucune nouvelle lecture d’état ne démarre à l’échéance d’interrogation ou après; cette échéance n’annule pas une requête HTTP déjà en cours. Si une lecture d’état échoue, l’erreur conserve l’identifiant de l’opération acceptée : vous pouvez ainsi reprendre avec getOperation sans répéter l’écriture. Une erreur d’API sous-jacente, assainie, est conservée comme cause; les exceptions inattendues sont omises de la chaîne affichée.

Problèmes courants

Symptôme	Vérification
Jeton d’accès manquant	Appelez api.login(...) ou api.loginWithBrowser(...) avant les actions d’API privées, ou passez accessToken à ThalovantControlPlane.
HTTP 401 avec le code mfa_required	Passez otpCode ou recoveryCode dans les options de connexion.
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 mqtt et que le client ne s’exécute pas dans un paquet pour navigateur.

Découverte des gestionnaires de repli

L’inventaire comprend fallbacks et fallbacksKnown. Utilisez inventory.mayAnswer("en-us") pour une vérification prudente de la langue : un hub dont la prise en charge du repli est inconnue peut quand même répondre. La sonde prend au plus 1,5 seconde, connexion, envoi et attente compris. Un résultat vide confirmé se distingue d’un refus, d’un échec, d’une absence de réponse ou d’une enveloppe de réponse mal formée. Les tableaux acceptés conservent les gestionnaires utilisables et ignorent les lignes invalides. Consultez la découverte des gestionnaires de repli.

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.

Passez un AbortSignal comme signal dans les options de ask, query et waitForEvent, ou comme deuxième argument de connect. L’annulation met fin à l’attente de l’appelant; tout travail de transport déjà accepté en garde la maîtrise jusqu’à ce qu’il se termine ou échoue sans danger. Les requêtes ne sont pas rejouées automatiquement. Ask utilise des fenêtres fixes pour la première parole et pour les réponses vides, à l’intérieur de son échéance d’origine; Query se termine sur son événement final.

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 l’option d’attente existante pour suivre l’opération acceptée. Un échec d’interrogation conserve l’identifiant de son opération; consultez cette opération au lieu de répéter l’écriture.

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

Disponible depuis la version 0.5.1.

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.

const location = buildLocation({ city: "Montréal", country: "CA", latitude: 45.5, longitude: -73.5 });
const reply = await client.ask("Quel temps fait-il ?", { sttLang: "fr-ca", location });
for (const event of reply.mediaEvents ?? []) if (event.isAudio) play(event.audioBytes());
const sentences = intent.examples("en-us", 2, { speakable: true, slots: { location: "Montréal" } });
await api.updateRuntimeGroupConfig(groupId, { tts: { module: "piper" } });
// Explicit full replacement:
await api.updateRuntimeGroupConfig(groupId, fullConfig, { merge: false });

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.

Les fusions protégées rejettent, avant l’écriture, les entiers situés hors de la plage sûre de JavaScript : la lecture et la fusion ne peuvent donc pas arrondir en silence une valeur de configuration non modifiée. Cette validation couvre aussi les personas fournis. Les valeurs non finies et les exposants numériques stockés qui dépassent la capacité des nombres JavaScript sont rejetés, ce qui empêche leur conversion en null lors de la sérialisation. Représentez les grands identifiants sous forme de chaînes ou utilisez un SDK qui gère les entiers sans perte.

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

Disponible depuis la version 0.6.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.

import { asSentence, speakable } from "@thalovant/sdk";
const examples = intent.examples("fr-CA", 2, { sentence: true });
const text = asSentence("what time is it", "en-US");
const sample = speakable("play {song}", {}, "en-US");

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.

import { HubSession } from "@thalovant/sdk";

const session = new HubSession(connectClient, { warm: false });
try {
  const reply = await session.ask("What is the weather?");
} finally {
  await session.close();
}

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. Dans les navigateurs, Node utilise un stockage local à l’origine; ne partagez pas cet espace de noms de stockage entre des utilisateurs sans lien entre eux.

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.