Référence AIR

Le contrat machine courant est touba-air-v1, avec les profils touba-air-capabilities-v1 et touba-air-json-canonical-v1. Une version, un profil ou une extension racine inconnus sont refusés avant exécution.

Cette page aide à lire l'AIR produit par le compilateur. L'AIR est le contrat d'exécution Touba entre source, manifest, runtime et traces.

Produire un AIR

Terminal

touba compile source.tb --out program.air.json

Champs principaux

Champ	Rôle
air_schema_version	touba-air-v1
air_capability_profile	touba-air-capabilities-v1
air_json_profile	touba-air-json-canonical-v1
module	Module Touba compilé
imports	Imports déclarés dans le module courant : types, constantes et composants exécutables
definitions.constants	Constantes de module issues de define
definitions.types	Types de module et champs
definitions.functions	Fonctions pures
definitions.tools	Tools, signatures et requirements
definitions.skills	Skills et graphes associés
definitions.agents	Agents, signature directe optionnelle, description informative, responsibility source obligatoire, uses, callable_by, scopes
definitions.strategies	Stratégies exécutables
definitions.triggers	Entrées événementielles gouvernées
budgets.run	Budgets de run quand ils sont présents dans l’AIR
execution_graphs	Nœuds exécutables et transitions
trace_points	Ancres utiles aux traces

Références qualifiées

Les références qualifiées relient AIR, manifest et traces.

Références AIR

tool:examples.search/SearchDatasets
agent:examples.search/Researcher
strategy:examples.search/RunDatasetResearch
trigger:examples.daily_research/DailyResearchSchedule

Imports

Un AIR peut porter des imports explicites :

AIR extrait

{
  "imports": [
    {
      "kind": "function",
      "name": "NormalizeQuery",
      "from_module": "examples.common",
      "target_ref": "function:examples.common/NormalizeQuery"
    }
  ]
}

L’import garde la référence canonique du module source. Il ne crée pas de grant, de secret, de scope mémoire, de caller d’agent, de manifest ou de handler.

Un AIR préparé contient les définitions résolues nécessaires aux imports : types, constantes, fonctions, tools, skills, agents, stratégies et mémoires. Le runtime exécute cet AIR préparé ; le compilateur résout les sources.

Tools

Un tool AIR peut porter :

• signature.inputs
• signature.output_type
• required_capabilities
• required_secrets
• memory_accesses

Le handler n'est pas dans l'AIR. Le chemin du handler vit dans le manifest.

Agents typés

AirAgent.signature, lorsqu’elle est présente, porte inputs et output_type. Un call_agent typé réutilise arguments et result_binding : les arguments viennent uniquement des clauses with, et le binding uniquement de into. Le runtime valide les valeurs d’entrée et la sortie finale sans écrire leur contenu brut dans les événements agent_interface_*.

L’absence de signature désigne un agent sans interface typée explicite : elle ne permet pas de reconstruire un contrat depuis uses. Les appels enrichis exigent une signature explicite résolue, locale ou importée depuis les sources du projet. L’import ne change ni l’identité du spécialiste, ni les règles callable_by.

Appels de stratégies

call_strategy cible une stratégie avec signature explicite. Les arguments sont ordonnés selon takes et le résultat est validé contre gives. Le runtime refuse les arguments incompatibles avant d’entrer dans le sous-workflow. Le nœud conserve target_ref, arguments et result_binding ; il ne crée ni nouveau run, ni nouveau budget, ni nouveau droit.

Triggers

Un trigger AIR porte :

• son trigger_ref ;
• la famille d’événement, par exemple schedule ;
• la stratégie cible ;
• les arguments statiques ;
• le contrat payload pour les mappings JSON déclarés par un trigger request, le cas échéant ;
• les limites max_runs_per_day et timeout_ms.

L’AIR peut décrire quels champs JSON alimentent les arguments d’une stratégie, mais il ne contient jamais le payload brut. Il ne dit pas non plus que le trigger est actif dans l’environnement courant : l’activation vit dans le manifest.

Budgets de run

Le bloc source limits run produit budgets.run. Chaque entrée contient value et le source_ref complet de la limite. L’extrait abrège ces localisations ; ne l’utilisez pas comme AIR exécutable. Les plafonds des modules importés sont combinés par minimum, avec la provenance de la limite retenue.

AIR extrait

{
  "budgets": {
    "run": {
      "max_steps": { "value": 100 },
      "max_tool_calls": { "value": 20 },
      "max_provider_calls": { "value": 4 }
    }
  }
}

Le manifest peut restreindre ces limites avec run_limits. Il ne peut pas les élargir silencieusement.

Ces budgets restent des limites runtime. Ils ne mesurent pas les tokens, les coûts fournisseur ou les quotas distribués.

Graphes

Les graphes portent des nœuds comme :

• Binding local immuable
• Appel de fonction
• Appel de tool
• Appel de skill
• Appel d'agent
• Branche
• Boucle
• give
• Validation humaine
• Interaction utilisateur

Les arguments explicites viennent de with. Les bindings de résultat viennent de into. Les valeurs locales immuables viennent de bind.

Constantes et bindings locaux

define apparaît dans definitions.constants. La valeur y est un littéral typé, jamais un secret.

bind apparaît comme un nœud de graphe kind = "bind". Le nœud évalue une expression AIR et crée un nom local pour les nœuds suivants.

Le runtime peut tracer la création d'un binding, mais la valeur exacte n'est pas exposée par défaut.

Listes et texte

Source	Expression AIR	Opérandes
[valeur for item in liste if condition]	list_comprehension	Liste, valeur, condition facultative
concat(a, b)	list_concat	Deux listes de type compatible
join(textes, séparateur)	text_join	Liste de textes, séparateur texte

La compréhension porte un binding local value_ref et un résultat typé list:…. Le filtre est évalué avant la valeur produite. L'ordre est conservé ; les listes d'entrée restent inchangées. Le runtime contrôle les types et la limite d'itérations. text_join retourne builtin:Text.

Records nominaux purs

Une expression source record TypeName { ... } devient une expression AIR kind = "construct_record". Elle porte le type_ref nominal et une liste record_fields de couples name / value_ref, unique, complète et triée par nom. Le runtime résout ces références et crée une valeur JSON neuve ; il n'interprète jamais du texte source ni du code hôte.

Ce que l'AIR ne contient pas

info

• Valeurs de secrets
• Valeurs d'environnement
• Réponses utilisateur ask
• Décisions humaines fournies à l'exécution
• Code des handlers
• Contenu brut de mémoire
• Payload externe brut d’un trigger
• Preuve Verified / Unverified

Nœud parallèle

parallel_call conserve target_ref, collection_ref, item_binding, arguments, max_concurrency, max_items, result_binding et source_ref. Il appartient à une skill ou stratégie ; sa cible a une sortie explicite. Le contrat machine refuse les bornes absentes ou invalides, les champs inconnus et les arguments incompatibles. Les branches réutilisent le graphe de la cible, sans duplication de code. La jointure publie une liste complète ordonnée. Le runtime de référence minimal ne prend pas en charge ce profil concurrent ; le runtime Touba natif le prend en charge.