Caméléon CVM — Guide Utilisateur v0.21.6-dev

1. Introduction

Caméléon est un orchestrateur de workflows IA dont le moteur d'exécution — la CVM (Caméléon Virtual Machine) — repose sur la théorie des réseaux de Petri.

Le POC v0.12 est une démonstration visuelle et interactive de ce moteur, entièrement en HTML/JS pur, sans framework ni dépendance externe.

Mapping Petri net → Caméléon

Le modèle Caméléon est une transposition directe du formalisme des réseaux de Petri :

Réseau de Petri	Modèle Caméléon
Place	Connexion (lien entre un plug output et un plug input)
Transition	Opérateur
Token	Donnée en transit sur une connexion
Arc place → transition	Plug input de l'opérateur
Arc transition → place	Plug output de l'opérateur

Fig. 1 — Correspondance Réseau de Petri ↔ Modèle Caméléon

Principe fondamental : l'état du système est porté par les connexions (= places), pas par les opérateurs (= transitions). C'est la bijection exacte avec le marquage d'un réseau de Petri.

2. Interface

Layout 5 zones

L'interface est organisée en 5 zones autour du canvas central :

Fig. 2 — Layout général de l'interface v0.12

Zone	Position	Contenu
Header	Haut	Logo, barre de progression, mode switcher, contrôles CVM, scrubber
Catalogue	Gauche (200px)	Future bibliothèque d'opérateurs (placeholder)
Canvas	Centre (flex)	Vue visuelle SVG, vue code .cm, ou les deux (split)
Vue / Propriété / Contrôleur	Droite (260px)	Vue (plug view), Propriété (config editor), Contrôleur (human/live interaction)
Panneau bas	Bas (160px)	Connexions (places), Opérateurs (transitions), CVM Log

Panneaux redimensionnables

Les trois panneaux latéraux (gauche, droite, bas) sont redimensionnables par drag sur les séparateurs situés entre les zones.

Curseur col-resize sur les séparateurs horizontaux (gauche/droite)
Curseur row-resize sur le séparateur vertical (bas)
Taille minimum : 80px (latéraux), 60px (bas)

Panneaux masquables

Chaque panneau peut être caché ou montré via les rails situés sur les bords du canvas (style VS Code). Ce sont des bandes fines qui s'élargissent au survol et révèlent une icône flèche.

Rail	Position	Action
Rail gauche	Bord gauche du canvas	Masque / affiche le panneau Catalogue
Rail droit	Bord droit du canvas	Masque / affiche le panneau Vue / Propriété / Contrôleur
Rail bas	Bord bas du canvas	Masque / affiche le panneau d'informations

Note : la taille d'un panneau est mémorisée lorsqu'il est masqué et restaurée lorsqu'il est réaffiché.

3. Lire la composition

Anatomie d'un opérateur

Chaque opérateur est représenté par un cercle avec un gradient radial. Il possède un label (nom), un numéro d'instance, et change de couleur selon son état.

Fig. 3 — Les trois états visuels d'un opérateur

Anatomie d'un plug

Les plugs sont les points d'entrée (inputs) et de sortie (outputs) des opérateurs. Ils orbitent autour du cercle de l'opérateur.

Fig. 4 — Plugs input vs output

Types de données

Type	Couleur	Description
`Binary`	`#a0b0c8`	Données binaires brutes
`DataString`	`#4f8aff`	Chaîne de caractères
`DataJSON`	`#a78bfa`	Structure JSON
`DataBool`	`#f4845f`	Booléen
`DataChunk`	`#00e5a0`	Fragment de texte extrait

États des connexions

Fig. 5 — Les quatre rendus visuels d'une connexion

4. Contrôles CVM

Barre de commandes

Les boutons de contrôle se trouvent dans le header, à droite du mode switcher :

Bouton	Couleur	Action
← Back	signal `#4f8aff`	Recule d'un pas dans l'historique (annule le dernier tir)
Fwd →	go `#00b4d8`	Avance d'un pas : tire le prochain opérateur éligible
▶ Run	cvm `#00e5a0`	Exécution automatique jusqu'à Completed ou Deadlock
⏸ Pause	amber `#ffb547`	Interrompt l'exécution automatique
⏮ Rwd	signal `#4f8aff`	Rewind automatique jusqu'au début
↻	dim	Reset : remet le système à l'état initial
Ann.	amber `#ffb547`	Toggle annotations (labels et types des plugs)

Scrubber

Le scrubber dans le header (à gauche de Rwd) permet de naviguer dans l'historique d'exécution. Le badge 3 / 7 indique la position courante / nombre total d'étapes.

Règles de tir

Source (opérateur sans inputs) : READY si toutes ses connexions sortantes sont EMPTY
Opérateur normal : READY si toutes ses connexions entrantes sont NEW
Fire : connexions entrantes → OLD, connexions sortantes → NEW

Conditions terminales

État	Condition	Couleur
Completed	Plus aucune connexion `NEW` et aucun opérateur ne peut tirer	cvm (vert) `#00e5a0`
Deadlock	Des connexions `NEW` ou `EMPTY` restent mais aucun opérateur ne peut tirer	rust (rouge) `#f4845f`

Cycle d'exécution

Fig. 6 — Cycle de vie d'une connexion (= place)

5. Modes Visual / Code / Split

Le mode switcher est centré dans le header. Il permet de basculer entre trois vues du canvas :

Fig. 7 — Mode switcher dans le header (Visual actif)

Mode	Raccourci	Description
Visual	`Ctrl+1`	Vue par défaut : graphe SVG interactif avec les opérateurs, plugs et connexions
Code	`Ctrl+2`	Affiche le code source `.cm` de la composition (YAML, lecture seule pour l'instant)
Split	`Ctrl+3`	Vue divisée : graphe visuel à gauche, code à droite, séparateur redimensionnable

Mode Visual

C'est la vue principale. Le canvas SVG occupe tout l'espace central. Toutes les interactions (drag, zoom, pan, tooltips) sont disponibles.

Mode Code

Le graphe SVG est masqué. Un éditeur affiche le fichier .cm en syntaxe YAML avec le header exemple.cm. Le code est en lecture seule dans cette version.

Roadmap : dans une version future, le code sera éditable et les modifications se répercuteront en temps réel sur le graphe visuel (bijection code ↔ visuel).

Mode Split

Les deux vues sont affichées côte à côte : visuel à gauche, code à droite. Un séparateur draggable permet d'ajuster les proportions (minimum 120px par côté).

Fig. 8 — Mode Split : visuel à gauche, code à droite

6. Interactions souris

Drag & drop des opérateurs

Clic gauche + drag sur un opérateur : déplace l'opérateur. Toutes les connexions (courbes Bézier), les plugs et les annotations sont recalculés en temps réel.

Fig. 9 — Drag & drop d'un opérateur

Drag & drop des plugs

Clic gauche + drag sur un plug : le plug tourne librement sur son orbite autour de l'opérateur. L'angle choisi est mémorisé et persisté même si l'opérateur est ensuite déplacé.

Fig. 10 — Rotation libre d'un plug sur son orbite

Zoom

Plateforme	Geste
Mac / PC	`Shift` + molette

Zoom centré sur la position du curseur
Plage : ×0.2 à ×5, incréments de 0.1
La grille de fond s'adapte au niveau de zoom

Fig. 11 — Zoom centré sur le curseur

Pan (déplacement de la vue)

Geste	Action
`Shift` + clic gauche + drag	Déplace la vue (translation du viewport)

Tooltips

Au survol d'un opérateur ou d'un plug, une infobulle affiche le label, le type, la direction et l'état courant.

7. Raccourcis clavier

Raccourci	Action
`Ctrl+1`	Mode Visual
`Ctrl+2`	Mode Code
`Ctrl+3`	Mode Split
`Shift` + molette	Zoom in / out (centré curseur)
`Shift` + clic gauche + drag	Pan (déplacer la vue)

8. Charte visuelle

Palette

Couleur	Hex	Usage
void	`#04060a`	Fond principal
deep	`#090d14`	Surfaces secondaires
ice	`#e8f0ff`	Texte principal
go	`#00b4d8`	Forward
cvm	`#00e5a0`	NEW, Run
rust	`#f4845f`	Deadlock
amber	`#ffb547`	Firing
signal	`#4f8aff`	Back, Rwd

Polices

Police	Usage
IBM Plex Mono	Interface, code, labels, annotations
Fraunces (italic)	Nom de marque « Caméléon »

Logo

Fig. 12 — Logo Caméléon : anneau externe, cercle central, trois satellites

9. Pipeline de démo

Schéma global

La composition de démonstration est un pipeline RAG avec 7 opérateurs :

Fig. 13 — Pipeline RAG de démonstration — 7 opérateurs, 7 connexions

Walkthrough : exécution pas à pas

Étape 0 — État initial

Toutes les connexions sont EMPTY. Les deux sources (PDF Loader et User Input) sont READY car leurs sorties sont vides.

Étape 1 — Fwd : PDF Loader tire

La connexion c0 (PDF Loader → Converter) passe à NEW.

Étape 2 — Fwd : User Input tire

La connexion c2 (User Input → GPT4Call) passe à NEW.

Étape 3 — Fwd : Converter tire

c0 passe à OLD. c1 (Converter → GPT4Call) passe à NEW. GPT4Call a maintenant ses deux entrées NEW : il devient READY.

Étape 4 — Fwd : GPT4Call tire

c1 et c2 passent à OLD. Les sorties c3 et c4 passent à NEW.

Étape 5 — Fwd : ValidJson tire

c4 passe à OLD. c5 passe à NEW. FormatResponse a ses deux entrées NEW.

Étape 6 — Fwd : FormatResponse tire

c3 et c5 passent à OLD. c6 passe à NEW.

Étape 7 — Fwd : PrintString tire

c6 passe à OLD. Plus aucune connexion NEW : état Completed.

Astuce : utilisez ▶ Run pour l'exécution complète, puis ⏮ Rwd pour rembobiner et observer chaque étape. Ou passez en mode Split (Ctrl+3) pour voir le code et le graphe simultanément.

Caméléon — shinoe — Guide v0.21.6-dev — 20/03/2026