Tutoriel - Organiser un projet avec des imports purs

Objectif : séparer un projet Touba en plusieurs modules sans créer d’autorité runtime implicite.

Les imports purs (IM-1) couvrent seulement type, define non sensible et function pure.

Les imports locaux de tool, skill, strategy, agent et memory existent dans la tranche effectful du même projet. Ce tutoriel se concentre sur le partage de code pur.

1. Créer le module commun

Terminal

mkdir -p pure-imports/src/examples
cd pure-imports

src/examples/common.tb

module examples.common

type SearchRequest
    query is Text
    rows is Int

define DefaultRows as Int = 5

function NormalizeQuery
    takes query as Text
    gives Text
    do
        give query

2. Créer le module applicatif

src/examples/search.tb

module examples.search

import type SearchRequest from examples.common
import define DefaultRows from examples.common
import function NormalizeQuery from examples.common

function BuildLabel
    takes request as SearchRequest
    gives Text
    do
        NormalizeQuery
            with query as request.query
            into normalized

        give normalized ++ ":" ++ text(DefaultRows)

strategy RunLabel
    takes request as SearchRequest
    gives Text
    uses BuildLabel
    do
        BuildLabel
            with request as request
            into label
        give label

Les imports sont placés après module et avant les déclarations.

3. Préparer le projet

Terminal

touba prepare --profile dev --mode write

Résultat attendu :

• l’AIR projet résout SearchRequest, DefaultRows et NormalizeQuery ;
• aucun manifest n’est créé si aucun tool n’est déclaré ;
• aucun grant, secret, handler ou scope mémoire n’est ajouté par import.

4. Inspecter l’AIR préparé

Terminal

touba inspect .touba/build/dev/air/examples/search.air.json

Vous devez voir les imports et leur statut de résolution.

5. Passer aux imports avec autorité runtime

Un import pur ne crée jamais de manifest, handler, grant, secret, caller ou scope mémoire. Quand vous voulez composer des tools, agents, strategies ou mémoires entre modules, utilisez le guide des imports multi-modules :

• tool importé : le binding manifest reste sur la référence canonique du module déclarant ;
• agent importé : l’appelant doit être explicitement autorisé par callable_by ;
• memory importée : l’owner doit déclarer le scope requis avant d’appeler un tool d’accès.

Contrat Validé

Les imports purs (IM-1) couvrent la partie pure du langage :

• partager des types ;
• partager des constantes non sensibles ;
• partager des fonctions pures ;
• assembler ces éléments dans l’AIR projet ;
• diagnostiquer les imports ambigus ou introuvables.

L’objectif est de structurer le code pur sans déplacer l’autorité d’exécution. Le guide des imports multi-modules montre les cas tool, skill, strategy, agent et memory. La règle reste la même : l’import rend le composant visible, mais le projet lie explicitement manifest, handler, secrets, contraintes, scopes, callers, lock et runtime quand ces autorités sont nécessaires.

Exécuter et vérifier

Terminal

touba run .touba/build/dev/air/examples/search.air.json \
  --entry strategy:examples.search/RunLabel \
  --inputs-json '{"request":{"query":"parks","rows":2}}' --output json > result.json
node --input-type=module -e 'import assert from "node:assert/strict"; import {readFileSync,existsSync} from "node:fs"; const r=JSON.parse(readFileSync("result.json")); assert.equal(r.status,"success"); assert.equal(r.result,"parks:5"); assert.equal(existsSync("touba.manifest.json"),false); console.log("PURE_IMPORTS_EXECUTED_WITHOUT_RUNTIME_GRANTS");'