# 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 :

```bash
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
```