Kill_LIFE/docs/MASCARADE_BRIDGE.md

Pont Kill_LIFE <-> Mascarade

Ce document rattache les décisions et implémentations produites pendant la session de travail locale au repo Kill_LIFE.

But

Garder une séparation propre entre :

• crazy_life : repo canonique web/devops et release du shell cockpit.
• Kill_LIFE : repo de méthode, specs, gates, evidence packs, workflows hardware/firmware.
• Mascarade : repo compagnon d’exécution locale pour orchestration LLM, distillation/fine-tuning, et outillage CAD conteneurisé.

En local, les trois dépôts sont côte à côte :

• crazy_life : ../crazy_life
• Kill_LIFE : ../Kill_LIFE
• Mascarade : ../mascarade

Règle de bridge retenue :

• crazy_life reste la source canonique pour le shell web et sa release.
• mascarade/web reste un mécanisme de sync et de snapshot local, pas un gate de release.
• Kill_LIFE reste la source de vérité pour le runtime, les workflows JSON, l’evidence, le firmware, le CAD et la compliance.

Ce qui a été mis en place côté Mascarade

1. Stack CAD/EDA locale

La stack CAD/EDA a maintenant été intégrée directement dans Kill_LIFE :

• deploy/cad/docker-compose.yml
• tools/hw/cad_stack.sh

Elle fournit :

• kicad-headless via kicad-cli sur une image KiCad 10 compatible
• kicad-mcp en transport stdio, lancé via tools/hw/run_kicad_mcp.sh
• freecad-headless via FreeCADCmd
• platformio via CLI pio

Le repo Mascarade reste utile comme repo compagnon pour :

• orchestration LLM
• distillation / fine-tuning
• modèles students spécialisés

2. Pipeline local teacher -> student

Le repo compagnon contient aussi un pipeline local de distillation et fine-tuning :

• ../mascarade/finetune/distill_dataset.py
• ../mascarade/finetune/distill_and_train.py
• ../mascarade/finetune/run_local.py
• ../mascarade/finetune/batch_local.py

Domaines déjà traités ou préparés :

• kicad
• freecad
• platformio
• esp32/iot
• spice

Ce pipeline sert à produire de petits modèles spécialisés exploitables localement pour les agents HW, Firmware, Doc et QA.

Répartition recommandée des rôles

Besoin	Repo recommandé	Raison
Shell web, Hono API, publication du cockpit	crazy_life	c’est le repo canonique web/devops
Specs, ADR, gates, evidence packs	Kill_LIFE	c’est la source de vérité méthodologique
Exécution LLM locale et orchestration provider/model	Mascarade	c’est le cockpit d’exécution
KiCad/FreeCAD/PlatformIO en conteneur	Kill_LIFE	stack CAD désormais intégrée localement
Simulation SPICE (ngspice)	Kill_LIFE	MCP ngspice local, circuits dans spice/
Build/test firmware PlatformIO	Kill_LIFE	MCP platformio local, pio dans .pio-venv/
Fetch docs Espressif/KiCad	Kill_LIFE	MCP apify, mode scrape direct
Pipeline RAG (embed + rerank + synthèse)	Mascarade	nomic-embed-text + qwen3:4b + devstral sur RTX 4090
Agents spécialisés avec RAG contextuel	Mascarade	18 agents dont firmware-engineer, spice-expert, openseeker
Datasets, distillation, adapters LoRA/QLoRA	Mascarade	pipeline de training déjà opérationnel
Rapports finaux, runbooks, conformité	Kill_LIFE	cohérence des artefacts et traçabilité

Comment relier les deux dépôts

Le flux web/release reste à part :

1. stabiliser et publier crazy_life depuis son propre repo
2. n'utiliser mascarade/scripts/sync_crazy_life.sh qu'après ce gate
3. ne jamais traiter mascarade/web comme source de vérité de release

Pour le hardware / CAD

Kill_LIFE garde :

• les règles
• les schémas
• les evidence packs
• les handoffs

Kill_LIFE exécute maintenant directement :

• kicad-cli
• le serveur kicad-mcp
• FreeCADCmd
• pio

Le flux recommandé est :

1. préparer la spec et les critères d’acceptation dans Kill_LIFE
2. exécuter les outils CAD/EDA dans Kill_LIFE
3. rapatrier les rapports, exports et décisions dans Kill_LIFE/docs/ et Kill_LIFE/artifacts/

Pour les agents IA spécialisés

Kill_LIFE fournit la matière de domaine :

• specs/
• docs/
• hardware/
• tools/
• conventions et profils compliance

Mascarade transforme cette matière en :

• datasets ShareGPT JSONL
• distillation teacher -> student
• adapters LoRA/QLoRA locaux

Le flux recommandé est :

1. extraire ou générer des datasets depuis Kill_LIFE
2. entraîner les students côté Mascarade
3. réinjecter l’usage de ces students dans les workflows agents de Kill_LIFE

Alignement avec l’état de l’art au 6 mars 2026

Points retenus pendant la recherche :

• kicad-cli est la voie officielle pour le headless KiCad
• pour MCP, stdio reste le bon choix en local
• Streamable HTTP ne doit être ajouté que si on expose un vrai serveur distant
• FreeCADCmd est le mode headless propre pour FreeCAD
• PlatformIO reste le plus simple à conteneuriser via CLI Python

Conséquence pour Kill_LIFE :

• ne pas mélanger la méthode et la couche d’exécution
• documenter Mascarade comme repo compagnon, pas comme dépendance cachée
• garder les evidence packs et la gouvernance dans Kill_LIFE

3. Pipeline RAG agentic (ajouté 2026-03-25)

Mascarade est maintenant le compute backend RAG pour Kill_LIFE :

• Embeddings: nomic-embed-text via mascarade-ollama-runtime (RTX 4090, GPU)
• Reranking: qwen3:4b via Ollama (scoring 0-10)
• Synthèse: devstral:latest via Ollama (code model 4090)
• Stockage vectoriel: Qdrant local dans mascarade-main_mascarade-network

Collections peuplées (2026-03-25) :

Collection	Chunks	Contenu
kb-firmware	~113	Code ESP32-S3, specs, plans firmware
kb-kicad	~119	Docs KiCad, hardware rules, MCP specs
kb-espressif	~146	Docs ESP-IDF live (I2S, WiFi, BLE, GPIO, FreeRTOS, OTA...)
kb-freecad	~11	CAD modeling specs
kb-components	~16	YAML fields, footprints, compliance
kb-spice	~11	4 netlists référence + README

Endpoints RAG (port 8100, pas d’auth requise) :

• POST /v1/rag/ingest — ingestion de textes bruts
• POST /v1/rag/search — recherche sémantique dans une collection
• POST /v1/rag/query — pipeline complet (embed → search → rerank → synthèse)
• POST /v1/agents/openseeker/search — multi-hop fan-out sur N collections

4. Agents spécialisés Mascarade pour Kill_LIFE (2026-03-25)

18 agents enregistrés. Agents avec RAG contextuel automatique:

Agent	Modèle	Collection RAG
firmware-engineer	devstral:latest (Ollama)	kb-firmware + kb-espressif
spice-expert	mistral-large	kb-spice
kicad-designer	mascarade-kicad (Ollama)	kb-kicad
freecad-designer	ollama	kb-freecad
components-expert	ollama	kb-components
openseeker	routellm strong	fan-out sur toutes collections

Appel via POST /v1/agents/{name}/run ou endpoint dédié openseeker/search.

Statut actuel

L’étape d’intégration côté Kill_LIFE est maintenant réalisée.

La couche CAD/EDA locale vit directement dans ce dépôt :

• deploy/cad/docker-compose.yml
• deploy/cad/Dockerfile.kicad-mcp
• deploy/cad/Dockerfile.freecad-headless
• deploy/cad/Dockerfile.platformio
• tools/hw/cad_stack.sh

Intégration actuelle dans Kill_LIFE

Le dépôt Kill_LIFE expose maintenant un launcher local natif :

• tools/hw/cad_stack.sh
• tools/hw/run_kicad_mcp.sh

Ce launcher :

• monte Kill_LIFE comme workspace par défaut
• pilote directement deploy/cad/docker-compose.yml
• évite de cacher une dépendance implicite vers Mascarade
• laisse Mascarade jouer son rôle de repo compagnon pour LLM local et fine-tuning

Exemples :

tools/hw/cad_stack.sh doctor
tools/hw/cad_stack.sh kicad-cli version
tools/hw/cad_stack.sh pio system info
tools/hw/run_kicad_mcp.sh --doctor
tools/hw/cad_stack.sh mcp