Vue d'ensemble de l'architecture¶
Diapason est un cadre de recherche pour l'étude des systèmes d'IA qui tournent sur la machine. Son architecture s'organise autour de cinq abstractions fondamentales — Intelligence, Moteur, Logique agentique, Mémoire et Apprentissage — qui travaillent ensemble par une boucle de retour pilotée par les traces.

Description des primitives¶
Intelligence¶
La primitive Intelligence s'occupe de la définition des modèles et du catalogue. Elle tient un catalogue des modèles connus (BUILTIN_MODELS) avec leurs métadonnées : nombre de paramètres, longueur de contexte, VRAM nécessaire et moteurs pris en charge. L'IntelligenceConfig porte l'identité complète du modèle configuré — le chemin de ses poids, son format de quantification, son moteur préféré, sa chaîne de repli et ses réglages de génération par défaut (temperature, max_tokens, top_p, top_k, repetition_penalty, stop_sequences).
Les modèles découverts à l'exécution auprès des moteurs en marche sont fusionnés d'office dans le ModelRegistry : le système garde ainsi une vue à jour de ce qui est disponible. L'aiguillage des questions est passé dans la primitive Apprentissage — voir la documentation Apprentissage et traces.
Moteur¶
La primitive Moteur fournit l'exécution de l'inférence — la couche qui fait réellement tourner les modèles de langage. Tous les moteurs implémentent la classe abstraite InferenceEngine et offrent la même interface : generate(), stream(), list_models() et health(). Parmi les moteurs pris en charge : Ollama, vLLM, SGLang, llama.cpp et Cloud (OpenAI, Anthropic, Google).
Chaque moteur se configure dans sa propre sous-section de config.toml ([engine.ollama], [engine.vllm], [engine.llamacpp], par exemple). La découverte des moteurs sonde la santé de tous les moteurs enregistrés et rend ceux qui répondent, classés avec ton moteur par défaut en tête. Si le moteur préféré est injoignable, le système bascule tout seul sur n'importe quel moteur disponible.
Logique agentique¶
La primitive Logique agentique implémente des agents interchangeables qui traitent les questions avec des degrés de sophistication variables. La hiérarchie des agents s'organise autour de BaseAgent (classe abstraite, avec des méthodes concrètes d'aide) et de ToolUsingAgent (base intermédiaire pour les agents qui acceptent des outils, avec accepts_tools = True). Neuf types d'agents existent : SimpleAgent (un seul tour, sans outils), OrchestratorAgent (boucle d'appel d'outils multi-tours, modes function_calling et structured), NativeReActAgent (boucle Pensée-Action-Observation), NativeOpenHandsAgent (exécution de code façon CodeAct), RLMAgent (modèle de langage récursif, avec REPL persistant), OpenHandsAgent (enveloppe le vrai openhands-sdk), ClaudeCodeAgent (le SDK d'agent Claude, par un sous-processus Node.js), OperativeAgent (agent planifié persistant, avec gestion d'état) et MonitorOperativeAgent (agent à longue portée, avec des axes de stratégie configurables).
Le module bac à sable (diapason.sandbox) ajoute une enveloppe SandboxedAgent, qui fait tourner n'importe quel BaseAgent dans un conteneur Docker ou Podman en imposant la sécurité des montages, et un ContainerRunner, qui gère le cycle de vie du conteneur.
Le comportement des agents se règle par [agent], dans config.toml : l'agent par défaut, la limite de tours, la liste d'outils, un prompt système facultatif et le drapeau context_from_memory (autrefois context_injection), qui commande l'injection automatique du contexte mémoire. La configuration du bac à sable vit dans [sandbox]. Tous les agents implémentent la classe abstraite BaseAgent avec une méthode run(), et s'enregistrent par @AgentRegistry.register("name").
Mémoire¶
La primitive Mémoire fournit un stockage persistant et interrogeable pour les documents et les connaissances. Cinq moteurs existent : SQLite/FTS5 (le défaut, sans aucune dépendance), FAISS (recherche par vecteurs denses), ColBERTv2 (interaction tardive), BM25 (fréquence des termes, la méthode classique) et Hybrid (fusion par rang réciproque du creux et du dense). Les moteurs de stockage se configurent sous [tools.storage] dans config.toml (la section [memory] reste acceptée comme alias de compatibilité).
La chaîne de la mémoire comprend l'ingestion des documents, leur découpage en morceaux, le calcul des plongements et l'injection du contexte. Quand tu envoies une question et que agent.context_from_memory est actif, les documents pertinents sont retrouvés et placés en tête du prompt, avec l'indication de leur source.
Apprentissage et traces¶
Le système d'apprentissage est la cinquième primitive : il relie les quatre autres par une boucle de retour pilotée par les traces. Chaque interaction d'agent peut produire une Trace qui capture la suite complète des étapes — les décisions d'aiguillage, les recherches en mémoire, les appels d'inférence, les appels d'outils et les réponses finales. Le TraceAnalyzer calcule des statistiques à partir des traces accumulées, et la TraceDrivenPolicy s'en sert pour apprendre quelles combinaisons modèle/agent/outil donnent les meilleurs résultats selon le type de question.
Le système d'apprentissage se configure par des sous-sections imbriquées de config.toml : [learning.routing] commande la politique d'aiguillage (heuristic, learned, sft, grpo), [learning.intelligence] la politique d'apprentissage au niveau du modèle, [learning.agent] les politiques du conseiller d'agent et du metteur à jour ICL, et [learning.metrics] fixe les poids de la fonction de récompense composite. Ce pilier comprend aussi la recherche de spécifications guidée par un LLM, une boucle pilotée par un modèle de frontière qui améliore le harnais local — voir L'architecture de l'apprentissage : la recherche de spécifications guidée par un LLM.
Le motif du registre¶
Tous les composants extensibles de Diapason passent par un registre à décorateurs pour être trouvés à l'exécution. Le motif est implémenté dans RegistryBase[T], une classe de base générique qui donne un stockage isolé à chaque sous-classe typée.
from diapason.core.registry import EngineRegistry
@EngineRegistry.register("ollama")
class OllamaEngine(InferenceEngine):
...
Chaque registre fournit :
| Méthode | Description |
|---|---|
register(key) |
Décorateur qui enregistre une classe sous une clé |
register_value(key, value) |
Enregistrement impératif |
get(key) |
Récupère par clé (lève KeyError si elle manque) |
create(key, *args, **kwargs) |
Cherche puis instancie |
items() |
Toutes les paires (key, entry) |
keys() |
Toutes les clés enregistrées |
contains(key) |
Dit si la clé existe |
clear() |
Vide toutes les entrées (pour les tests) |
Les registres typés du système :
| Registre | Paramètre de type | Rôle |
|---|---|---|
ModelRegistry |
Any (ModelSpec) |
Les métadonnées des modèles |
EngineRegistry |
Type[InferenceEngine] |
Les moteurs d'inférence |
MemoryRegistry |
Type[MemoryBackend] |
Les moteurs de mémoire |
AgentRegistry |
Type[BaseAgent] |
Les implémentations d'agents |
ToolRegistry |
Any (classes BaseTool) |
Les implémentations d'outils |
RouterPolicyRegistry |
Any (classes RouterPolicy) |
Les politiques d'aiguillage |
BenchmarkRegistry |
Any (classes BaseBenchmark) |
Les implémentations de bancs d'essai |
ChannelRegistry |
Any (classes BaseChannel) |
Les implémentations de canaux |
Ajouter un nouveau composant
Pour ajouter un moteur, implémente la classe abstraite qui convient et décore-la avec le décorateur du registre correspondant. Aucune fabrique n'est à modifier — le composant devient trouvable tout seul à l'exécution.
L'arborescence des sources¶
src/diapason/
core/ L'infrastructure commune à toutes les primitives
registry.py RegistryBase[T] et les registres typés qui en dérivent
types.py Message, ModelSpec, Trace, TelemetryRecord, etc.
config.py DiapasonConfig, détection du matériel, lecture du TOML
events.py Le bus d'événements pub/sub (EventType, Event)
intelligence/ Primitive Intelligence -- définition et catalogue des modèles
model_catalog.py La liste BUILTIN_MODELS, merge_discovered_models()
_stubs.py (cale de compatibilité -- ré-exporte learning._stubs)
router.py (cale de compatibilité -- ré-exporte learning.router)
engine/ Primitive Moteur -- l'exécution de l'inférence
_stubs.py La classe abstraite InferenceEngine
_base.py EngineConnectionError, messages_to_dicts()
_openai_compat.py Base commune aux moteurs compatibles OpenAI
_discovery.py discover_engines(), discover_models(), get_engine()
ollama.py Moteur Ollama (API HTTP native)
openai_compat_engines.py Enregistrement piloté par les données (vLLM, SGLang, llama.cpp, MLX, LM Studio)
cloud.py Moteur distant (SDK OpenAI, Anthropic, Google)
agents/ Primitive Logique agentique -- les agents interchangeables
_stubs.py BaseAgent (classe abstraite), ToolUsingAgent, AgentContext, AgentResult
simple.py SimpleAgent (un seul tour, sans outils)
orchestrator.py OrchestratorAgent (boucle d'outils multi-tours, function_calling + structured)
native_react.py NativeReActAgent (boucle Pensée-Action-Observation)
native_openhands.py NativeOpenHandsAgent (exécution de code façon CodeAct)
rlm.py RLMAgent (modèle de langage récursif, REPL persistant)
openhands.py OpenHandsAgent (enveloppe le vrai openhands-sdk)
react.py Cale de compatibilité (ré-exporte NativeReActAgent sous ReActAgent)
claude_code.py ClaudeCodeAgent (SDK d'agent Claude, par un sous-processus Node.js)
claude_code_runner/ Le lanceur Node.js embarqué pour le SDK d'agent Claude
sandbox/ Bac à sable en conteneur, pour isoler l'exécution des agents
runner.py ContainerRunner (cycle de vie Docker/Podman), enveloppe SandboxedAgent
mount_security.py MountAllowlist, validate_mounts() (sécurité des chemins)
memory/ Primitive Mémoire -- stockage persistant et interrogeable
_stubs.py MemoryBackend (classe abstraite), RetrievalResult
sqlite.py Moteur SQLite/FTS5 (le défaut, sans dépendance)
faiss_backend.py Moteur FAISS, recherche dense
colbert_backend.py Moteur ColBERTv2, interaction tardive
bm25.py Moteur BM25 (Okapi), fréquence des termes
hybrid.py Moteur hybride, fusion RRF
chunking.py ChunkConfig, Chunk, chunk_text()
ingest.py Ingestion des documents (lecture des fichiers, parcours des dossiers)
context.py Injection du contexte (inject_context, attribution des sources)
embeddings.py Embedder (classe abstraite), SentenceTransformerEmbedder
learning/ Système d'apprentissage -- politiques d'aiguillage et récompenses
_stubs.py Classes abstraites RouterPolicy, QueryAnalyzer, RewardFunction, RoutingContext
router.py HeuristicRouter, DefaultQueryAnalyzer, build_routing_context()
heuristic_policy.py Branche HeuristicRouter dans le RouterPolicyRegistry
trace_policy.py TraceDrivenPolicy (apprend du résultat des traces)
grpo_policy.py GRPORouterPolicy (ébauche pour un futur apprentissage par renforcement)
heuristic_reward.py HeuristicRewardFunction (latence/coût/efficacité)
traces/ Système de traces -- l'enregistrement des interactions
store.py TraceStore (persistance SQLite)
collector.py TraceCollector (enveloppe les agents, enregistre les traces)
analyzer.py TraceAnalyzer (statistiques agrégées)
tools/ Système d'outils -- les implémentations interchangeables
_stubs.py BaseTool (classe abstraite), ToolSpec, ToolExecutor
calculator.py CalculatorTool (évaluation sûre, fondée sur l'AST)
think.py ThinkTool (brouillon de raisonnement)
retrieval.py RetrievalTool (recherche en mémoire)
llm.py LLMTool (appels à un sous-modèle)
file_read.py FileReadTool (lecture de fichier sûre)
telemetry/ Télémétrie -- l'enregistrement des mesures d'inférence
store.py TelemetryStore (SQLite, abonné au bus d'événements)
aggregator.py TelemetryAggregator (statistiques par modèle/moteur)
wrapper.py L'enveloppe instrumented_generate()
server/ Serveur d'API -- API HTTP compatible OpenAI
app.py La fabrique d'application FastAPI
routes.py /v1/chat/completions, /v1/models, /health
bench/ Cadre de bancs d'essai
_stubs.py BaseBenchmark (classe abstraite), BenchmarkSuite
latency.py LatencyBenchmark (latence par appel)
throughput.py ThroughputBenchmark (jetons par seconde)
security/ Les garde-fous de sécurité
_stubs.py La classe abstraite BaseScanner
types.py ThreatLevel, RedactionMode, ScanFinding, ScanResult
scanner.py SecretScanner, PIIScanner
guardrails.py GuardrailsEngine (enveloppe InferenceEngine)
file_policy.py is_sensitive_file(), DEFAULT_SENSITIVE_PATTERNS
audit.py AuditLogger (événements de sécurité, en SQLite)
channels/ La messagerie par canaux
_stubs.py BaseChannel (classe abstraite), ChannelMessage, ChannelStatus
whatsapp_baileys.py WhatsAppBaileysChannel (protocole Baileys, par une passerelle Node.js)
whatsapp_baileys_bridge/ La passerelle Baileys Node.js embarquée
scheduler/ Le système de planification des tâches
scheduler.py TaskScheduler (cron/intervalle/une fois, scrutation en tâche de fond)
store.py SchedulerStore (persistance SQLite + journaux d'exécution)
tools.py Outils MCP du planificateur (schedule_task, list, pause, resume, cancel)
cli/ Les commandes de la CLI (bâties sur Click)
ask.py diapason ask -- interroger l'assistant
serve.py diapason serve -- démarrer le serveur d'API
sdk.py La classe Diapason -- le SDK Python de haut niveau
mcp/ La couche MCP (Model Context Protocol)
Comment les primitives s'articulent¶
Le bus d'événements : le tissu conjonctif¶
Toutes les primitives communiquent par un bus d'événements pub/sub sûr entre fils d'exécution, défini dans core/events.py. La distribution est synchrone : les abonnés sont appelés dans l'ordre de leur inscription, à l'intérieur du fil qui publie.
Les types d'événements du système :
| Événement | Publié par | Rôle |
|---|---|---|
INFERENCE_START / INFERENCE_END |
Moteur / Agent | Suivre les appels d'inférence |
TOOL_CALL_START / TOOL_CALL_END |
ToolExecutor | Suivre l'usage des outils |
MEMORY_STORE / MEMORY_RETRIEVE |
Moteurs de mémoire | Suivre les opérations de mémoire |
AGENT_TURN_START / AGENT_TURN_END |
Agents | Suivre le cycle de vie des agents |
TELEMETRY_RECORD |
TelemetryStore | Publier les relevés de télémétrie |
TRACE_STEP / TRACE_COMPLETE |
TraceCollector | Les étapes du cycle de vie d'une trace |
CHANNEL_MESSAGE_RECEIVED / CHANNEL_MESSAGE_SENT |
WhatsAppBaileysChannel | Suivre la messagerie par canaux |
SECURITY_SCAN / SECURITY_ALERT / SECURITY_BLOCK |
GuardrailsEngine | Suivre l'analyse de sécurité |
scheduler_task_start / scheduler_task_end |
TaskScheduler | Suivre l'exécution des tâches planifiées |
Le sens des dépendances¶
Les primitives forment un graphe de dépendances orienté :
- La logique agentique dépend du Moteur (pour l'inférence) et de la Mémoire (pour le contexte)
- L'Intelligence fournit aux agents le choix du modèle, par les politiques d'Apprentissage
- L'Apprentissage lit les traces, que produit la logique agentique
- La Mémoire est indépendante, mais consommée par les agents et les outils
- Le Moteur est indépendant, mais consommé par les agents et le SDK
Cela crée une boucle de retour : les agents produisent des traces, les traces nourrissent l'apprentissage, l'apprentissage améliore l'aiguillage, et un meilleur aiguillage améliore les performances des agents.