FAQ

Produit

À quoi sert Touba ?

Touba sert à écrire, préparer, exécuter, tracer et auditer des workflows agentiques gouvernés. Le langage .tb décrit l’orchestration et les autorités ; l’AIR, le manifest, le runtime, les handlers, les locks et les traces rendent l’exécution observable.

Composition et reprise multi-agent

Peut-on exécuter plusieurs agents en parallèle ?

Oui. Une stratégie déclare parallel AgentName sur une liste typée, avec max_concurrency, max_items et un résultat into ordonné. Les agents importés avec signature explicite sont acceptés ; chaque branche conserve son caller et ses scopes, et toutes partagent les budgets. Un agent peut aussi sélectionner une stratégie autorisée contenant ce groupe. Voir Strategy.

Une approbation autorise-t-elle toutes les branches ou toutes les itérations ?

Non. Chaque décision vise une occurrence précise. La reprise conserve les piles, branches terminées et budgets sans répéter les appels acquis. Un checkpoint humain, un checkpoint de groupe et la reprise d'opération séquentielle ont des périmètres distincts : voir le guide de reprise.

Pourquoi Touba met-il l’accent sur des artefacts explicites ?

Parce qu’un workflow agentique doit pouvoir expliquer qui a appelé quoi, avec quelles capacités, quels secrets, quelles mémoires, quelles limites et quelles traces. Touba privilégie donc des artefacts concrets : source .tb, AIR, manifest, run plan, lock supply chain, traces et rapports.

Touba vise-t-il seulement la recherche ?

Non. Probabilistic Agentic Programming donne le cadre scientifique, mais Touba vise des workflows agentiques robustes pour des équipes réelles. Touba impose des contrats explicites sur les tools, handlers, secrets, agents, mémoires, triggers, budgets, audits et refus avant effet externe.

Langage

Pourquoi ne pas mettre du JavaScript ou du Python directement dans .tb ?

Parce que .tb reste le langage d'orchestration gouvernée. Le code qui réalise un effet externe vit dans un handler hôte relié explicitement par manifest. Cette séparation protège AIR comme contrat multi-runtime et évite de transformer Touba en fichier polyglotte difficile à analyser.

Quelle est la différence entre fichier et module ?

Le fichier est l'artefact physique. Le module est l'identité logique déclarée dans la source. Dans un projet Touba, un fichier comme src/examples/search.tb peut déclarer module examples.search. Le module sert ensuite à qualifier les références AIR.

Un fichier .tb a-t-il toujours besoin d'un handler ?

Non. Un fichier Touba sans tool peut contenir des fonctions pures, interactions, skills, agents ou strategies sans handler. Un handler devient nécessaire quand un tool doit réaliser un effet externe : réseau, base de données, LLM, système métier ou autre intégration hôte.

Un fichier .tb a-t-il toujours besoin d'un manifest ?

Non. Le manifest devient nécessaire quand le programme relie un tool, un trigger, un resource binding, un profil d'exécution ou une autre autorité runtime explicite. Un programme simple sans effet externe peut être compilé et exécuté sans manifest de binding.

Peut-on importer tool, skill, agent, strategy et memory ?

Oui. L'import rend une déclaration disponible pour composition, mais il n'accorde jamais de handler, grant, secret, scope mémoire, caller d'agent, trigger actif ou autorité runtime. Le projet qui importe reste responsable du manifest, des profils, du run plan, du lock supply chain et des traces.

Pourquoi show et ask sont interdits dans function ?

Une function Touba reste pure. show et ask sont des interactions observables avec l'utilisateur ; elles appartiennent donc à des blocs effectifs comme skill, agent ou strategy.

Comment afficher une valeur dans un message show ?

Utilisez une expression de texte avec concaténation et conversion explicite :

show
    with message as "Age prochain: " ++ text(next_age)

Vous pouvez aussi écrire f"Age: {text(age)}". Le préfixe f active l’interpolation ; text(...) rend la conversion explicite. Voir la syntaxe.

Pourquoi ask ne lit pas toujours le terminal automatiquement ?

Pour garder l'exécution explicite et rejouable. En CLI, l'hôte peut fournir les réponses avec --user-inputs ou demander un mode interactif avec --interactive-user-inputs. Dans VS Code ou une application hôte, la surface doit fournir l'entrée utilisateur au runtime au lieu de la laisser implicite.

Pourquoi deux give successifs ne retournent-ils pas deux résultats ?

Un give termine le bloc courant. Les instructions placées après un give, un stop ou une branche terminale sont inatteignables et doivent être refusées par les diagnostics Touba. Si vous voulez retourner plusieurs informations, définissez un type résultat qui contient plusieurs champs, puis retournez une seule valeur structurée.

Runtime, manifest et préparation projet

Le manifest est-il découvert automatiquement par le runtime ?

Non. Le runtime ne scanne pas le projet pour deviner un manifest. Le manifest est fourni explicitement, souvent après génération ou mise à jour par touba prepare ou touba manifest generate.

À quoi sert touba prepare ?

touba prepare prépare les artefacts de projet sans exécuter de handler : AIR, manifest assemblé, run plan, fragments de bindings, profils dev/prod et squelettes de handlers selon les options utilisées. Il sert à réduire la configuration manuelle sans déplacer l'autorité vers une découverte implicite.

Qu'est-ce qu'un run plan ?

Un run plan décrit explicitement comment un projet doit être exécuté : module, entrée, profils, manifest, secrets, lock ou autres artefacts attendus. Il ne doit pas contenir de secret ni de payload sensible.

Qu'est-ce qu'un binding fragment ?

Un binding fragment décrit une partie du wiring d'un projet, par exemple un handler ou une ressource. Il doit être assemblé dans un manifest avant runtime. Le runtime refuse les fragments non assemblés comme source d'autorité directe.

grants veut-il dire sandbox ?

Non. Un grant est une autorisation de contrat vérifiée par Touba Engine avant dispatch. Un binding peut exiger séparément sandbox.required: true : le runtime applique un backend OS disponible et compatible avec la politique, ou refuse le lancement. Voir les prérequis par OS. Les grants seuls restent des contrôles logiques d'admission, pas une isolation OS.

À quoi servent les contraintes de payload ?

Les contraintes de payload (PC-1 / PC-2) ajoutent des règles portables dans le manifest : valeurs non vides, longueurs, bornes numériques et valeurs autorisées. Le runtime peut refuser une entrée ou une sortie avant handler ou avant publication du résultat.

À quoi sert la vérification supply chain des handlers ?

La vérification supply chain des handlers (SC-1 / SC-2 / SC-3) vérifie la cohérence entre AIR, manifest, handlers, metadata SDK et identité handler_package par lock explicite. Elle peut aussi couvrir les fichiers de paquet handler, les artefacts de dépendances déclarés, la provenance et la revue déclarée. C'est un garde-fou contre le drift de wiring et l’absence de discipline de revue ; ce n'est pas une signature ou une certification.

Handlers et SDK

Le handler est-il la source principale de sécurité ?

Non. Le handler exécute le code métier. Touba Engine doit refuser avant handler quand le tool, le grant, le secret, le scope mémoire, le payload, le caller ou le lock requis sont invalides. Le handler peut refaire des vérifications comme défense en profondeur, mais il n'est pas l'autorité principale.

Un squelette de handler est-il un SDK ?

Non. Un squelette est un fichier de départ généré pour aider le développement. Le SDK est la bibliothèque qui masque le protocole handler, expose defineTool, fournit ToubaEngine et aide à écrire un provider de décision structuré.

Le SDK remplace-t-il le runtime Touba ?

Le SDK facilite l’intégration JavaScript ou Python. Le runtime reste l'autorité sur l'AIR, les manifests, les secrets, les scopes, les payloads, les décisions agentiques, les budgets, les triggers et les traces.

Quel SDK utiliser ?

Choisissez le langage de votre application : JavaScript avec @touba/sdk, ou Python avec touba_sdk. Les deux proposent handlers, ToubaEngine, providers et helpers de test.

Secrets et agents

Les agents voient-ils les secrets ?

Non. Les agents et les prompts ne doivent pas recevoir les valeurs de secrets. Le runtime résout les handles, injecte seulement les secrets accordés dans l'environnement minimal du handler autorisé et trace les noms de handles, jamais les valeurs.

Faut-il exporter toutes les clés à chaque test ?

Non. Le fichier de résolution des secrets indique où chercher chaque handle : env, dotenv ou touba_store. Le profil dev peut recommander touba_store ou .env, tandis qu'un profil prod peut pointer vers env ou un autre mécanisme cadré plus tard. Touba ne devine pas automatiquement dev/prod.

Faut-il une clé OpenAI pour utiliser Touba ?

Vous choisissez le fournisseur de votre application : OpenAI, Anthropic, Gemini ou un provider adapté à votre infrastructure. La compilation et les workflows déterministes fonctionnent sans clé de modèle. Voir les interfaces de décision.

Un agent peut-il choisir plusieurs ressources ?

Oui, dans une boucle séquentielle bornée quand un provider de décision est configuré. Le runtime expose les ressources déclarées dans uses, vérifie ou refuse chaque choix, exécute la capacité autorisée, puis renvoie une observation structurée au provider si la boucle continue.

Quelle est la différence entre human.approve et un review demandé par agent ?

human.approve est une barrière écrite dans le programme. Un review demandé par agent est une action dynamique proposée par le provider pendant l'exécution. Dans les deux cas, le runtime trace la pause et ne reprend qu'avec une décision explicite.

Mémoire et ressources

Une memory est-elle une base de données ?

Non. Une memory est une ressource logique Touba. Une base PostgreSQL, un service HTTP ou un autre backend peut réaliser l'accès mémoire via des handlers autorisés et un resource binding explicite.

PostgreSQL est-il un backend mémoire natif Touba ?

Non. Le scénario PostgreSQL montre l'intégration contrôlée d'un backend hôte réel : scopes lecture/écriture, resource binding, secret handle, handler SDK, refus avant effet externe et traces. Une memory Touba reste une ressource logique ; PostgreSQL reste un backend hôte relié par handler.

Les droits de lecture et d'écriture mémoire sont-ils séparés ?

Oui. Les scopes read et write sont séparés. Un agent ou un tool autorisé à lire ne reçoit pas automatiquement le droit d'écrire.

Triggers

Les triggers sont-ils réels ?

Oui. Touba couvre schedule -> strategy avec runner foreground explicite et request -> strategy avec service webhook, queue durable, payload typé et signature HMAC optionnelle. Les deux chemins passent par AIR, manifest, limites, état TD-1 et traces trigger_*.

Les triggers couvrent-ils déjà webhooks, queues ou daemon permanent ?

Oui pour le webhook, la queue durable touba-trigger-queue-v1, les retries bornés et le service explicite lancé par touba trigger serve. Les schedulers distribués, queues distribuées, ingress cloud et supervision système sont des couches de déploiement séparées.

Documentation et surfaces

VS Code est-il l'unique manière d'utiliser Touba ?

Non. VS Code est une surface pratique pour éditer, diagnostiquer et inspecter. La CLI et les artefacts Touba restent le chemin de référence pour compiler, préparer, exécuter, auditer et valider.