Premier programme Touba

Ce parcours montre un programme Touba minimal avec show et ask.

Les commandes terminal de ce parcours supposent que la CLI Touba est disponible. Si vous avez seulement installé l’extension VS Code via VSIX, utilisez Touba: Run Current File pour exécuter un fichier .tb simple depuis l’éditeur.

1. Créer le fichier source

Créez un fichier hello.tb :

hello.tb

module examples.hello

strategy RunInteraction
    gives Text
    do
        show
            with message as "Touba ready"

        ask
            with prompt as "Search query?"
            into query

        show
            with message as "Query captured"

        give query

Ce programme :

• affiche un premier message ;
• demande une entrée à l’hôte ;
• affiche un second message ;
• retourne la valeur reçue.

give est un retour terminal : placez les affichages avec show avant le give, puis gardez un seul give par chemin d’exécution.

Dans un projet Touba, le même module suivrait la convention :

Chemin dans un projet

src/examples/hello.tb

Un programme qui ne déclare aucun tool n’a pas besoin de manifest ni de handler.

2. Compiler vers AIR

Terminal

touba compile hello.tb --out hello.air.json

Transformation :

Sortie

hello.tb -> AIR JSON

L’AIR décrit les nœuds exécutables. Il ne contient pas de réponse utilisateur.

3. Exécuter et répondre

Saisie dans le terminal

touba run hello.air.json --interactive-user-inputs

La CLI affiche « Search query? ». Saisissez parks puis validez : le programme affiche « Query captured » et retourne votre réponse. Dans VS Code, Touba: Run Current File ouvre une boîte de saisie pour chaque ask.

Choisir le mode d’entrée

Mode	Commande	Usage
Interactif	touba run hello.air.json --interactive-user-inputs	Répondre dans le terminal
Automatisé	touba run hello.air.json --user-inputs user-inputs.json	Fournir les réponses depuis un fichier
Piloté par l’hôte	touba run hello.air.json	S’arrêter à la demande d’entrée pour que l’application la traite

Fournir les réponses depuis un fichier

Réponses depuis un fichier

touba run hello.air.json --user-inputs user-inputs.json

Le fichier user-inputs.json associe la référence d’interaction à la réponse. Vous le créez manuellement : chaque clé est une interaction_ref issue de l’AIR compilé, visible dans un événement user_interaction_requested d’une trace.

Pour hello.tb, la référence du ask est :

user-inputs.json

{
  "interaction:graph:strategy:examples.hello/RunInteraction:node:graph:strategy:examples.hello/RunInteraction:2": "parks"
}

L’exécution se termine normalement sans aucune saisie interactive.

Pour afficher la valeur retournée par le programme :

Terminal

touba run hello.air.json \
  --user-inputs user-inputs.json \
  --output result

4. Générer la trace

--output contrôle l’affichage dans le terminal. Pour écrire la trace dans un fichier, utilisez --trace-out :

Terminal

touba run hello.air.json \
  --user-inputs user-inputs.json \
  --trace-out trace-success.json

Cela crée trace-success.json dans le répertoire courant.

5. Inspecter la trace

Terminal

touba inspect trace-success.json

L’inspection donne une lecture textuelle des événements : démarrage, affichage, pause, reprise et fin.

À retenir

show et ask sont des interactions hôte. Elles sont autorisées dans les workflows, mais pas dans les function, car une fonction Touba doit rester pure et portable.