ki-fwi/tools/assets/README.md

# Pipeline d'assets — filière B (décor)

> **Filière B uniquement.** Rien de ce qui sort d'ici ne peut servir à identifier une
> espèce. Fonds, sprites du mode arcade, badges, écrans de titre, iconographie — jamais
> une épreuve, jamais un indice (ADR 0004).
>
> La séparation n'est pas une consigne : `npm run validate:data` fait échouer le build si
> un média de filière B porte un usage identifiant, et `npm run test:porte` le prouve.

## Pourquoi cette séparation existe

Les modèles de diffusion connaissent mal le corossol, à peine la quenette, presque pas le
zikak. Sur ces espèces, ils ne refusent pas : ils produisent un fruit **plausible et faux**.
Un enfant qui apprend dessus apprend l'hallucination d'un modèle.

Le décor, lui, n'a rien à enseigner. C'est là que la génération a sa place.

## Où ComfyUI écrit

Le dossier `output/` de l'installation ComfyUI, sous-dossier `ki-fwi/` (fixé par
`filename_prefix` dans le workflow). Le client rapatrie les images par l'API
`/view`, ce qui fonctionne aussi si ComfyUI tourne ailleurs — mais inspecter ce dossier
reste le seul moyen de savoir si une génération a **réellement** eu lieu.

## Utilisation

```bash
# Vérifier que les seeds sont bien déterministes (aucun serveur requis)
python3 comfyui_client.py --verifier

# Test de reproductibilité RÉEL : génère, vide le cache, régénère, compare
python3 comfyui_client.py --workflow workflows/decor-sdxl.json \
                          --plan plan-assets.json --reproductibilite

# Calculer les seeds d'un plan sans rien générer
python3 comfyui_client.py --workflow workflows/decor.json --plan plan-assets.json --sec

# Générer, ComfyUI devant tourner en local
python3 comfyui_client.py --workflow workflows/decor.json --plan plan-assets.json
```

Aucune dépendance n'est nécessaire : le client n'utilise que la bibliothèque standard.

## Les trois défauts du pack d'origine, corrigés

### 1. Les seeds n'étaient pas reproductibles

Le pack faisait `hash(fruit["id"] + asset_type) % 2**32` en vendant l'argument « même seed
= même style ». Or `hash()` sur une chaîne est **randomisé à chaque exécution** depuis
Python 3.3 (`PYTHONHASHSEED`) : les seeds changeaient d'un lancement à l'autre, exactement
l'inverse de ce qui était annoncé.

Remplacé par `zlib.crc32(clé.encode()) & 0xFFFFFFFF`. Vérifié empiriquement — deux
processus avec des `PYTHONHASHSEED` différents produisent les mêmes valeurs :

```
kowosol:fond      1368899280
zikak:sprite      4184016363
mansiniye:badge   1009059342
lakou:titre       4201979101
```

### 2. `json.loads(json.dumps(x))` pour copier

Remplacé par `copy.deepcopy(x)` : même effet, sans aller-retour par une sérialisation qui
écrase les types non JSON.

### 3. La licence de `rembg` n'était pas vérifiée

Le paquet est sous MIT, mais **les poids** du modèle qu'il télécharge ne suivent pas
nécessairement cette licence. `requirements.txt` porte l'avertissement, et `rembg` reste
commenté : à n'installer qu'après vérification des poids, pas du paquet.

## Format du plan

```json
{
  "noeud_seed": "4",
  "noeud_prompt": "6",
  "assets": [
    { "id": "lakou", "type": "fond", "prompt": "jaden créole au petit matin, …" }
  ]
}
```

La clé de seed est `<id>:<type>`. Elle ne doit jamais changer une fois un asset retenu :
c'est elle qui garantit qu'une régénération donne la même image.

## Ce que le pipeline ne fait pas

Il ne valide rien. Tout asset sort en `valide: false` et le reste jusqu'à ce qu'un humain
tranche — comme pour les photographies. La différence est qu'un asset de filière B, même
validé, ne pourra jamais porter une épreuve.

## Piège du cache d'exécution

**ComfyUI met en cache le résultat d'un graphe identique.** Relancer le même workflow ne
recalcule rien : aucune image n'est écrite, et l'API renvoie la sortie précédente.

Conséquence : comparer deux « exécutions » sans vider le cache ne prouve rien sur la
reproductibilité — cela prouve seulement que le cache fonctionne. C'est l'erreur commise
puis corrigée en session 3.

`--reproductibilite` appelle `POST /free` entre les deux générations. Pour vérifier à la
main, regarder si un nouveau fichier est apparu dans le dossier de sortie : s'il n'y en a
pas, rien n'a été calculé.