engine/INTEGRATION_GUIDE.md

🚀 Rust Asset Generator - Integration Guide

Pour ton Dashboard

✅ Prerequis

Tu as besoin:

1. Rust installé (https://rustup.rs/)
2. Smart Router fonctionnel (http://localhost:8000)
3. Variables d'env configurées

---

1️⃣ Build le Binary

cd Engine

# Build en release (optimisé)
cargo build --release

# Résultat: ./target/release/asset_generator.exe (Windows)
# ou        ./target/release/asset_generator (Linux/Mac)

Temps: ~2-3 minutes première fois, <10sec après

---

2️⃣ Configure tes Variables d'Env

Crée un fichier .env à la racine du projet:

# Requis
AI_SMART_ROUTER_URL=http://localhost:8000
API_SECRET=ta_clé_secrète

# Optional
OPENROUTER_API_KEY=clé_fallback_optionnelle
IMAGE_GEN_MODE=api

# Logging
RUST_LOG=info

---

3️⃣ Utilise avec ton Dashboard

Option A: Appel depuis Python

import subprocess
import json
from pathlib import Path

# Lancer le moteur Rust
result = subprocess.run([
    "./Engine/target/release/asset_generator",
    "--story", "rimouski"
], capture_output=True, text=True)

if result.returncode == 0:
    print("✅ Génération réussie!")
else:
    print(f"❌ Erreur: {result.stderr}")

# Les fichiers générés sont dans:
# stories/rimouski/assets/images/
# stories/rimouski/assets/depths/
# stories/rimouski/assets/scenes/

Option B: Appel depuis Dashboard Node

const { spawn } = require('child_process');

function generateAssets(storyId) {
    return new Promise((resolve, reject) => {
        const process = spawn('./Engine/target/release/asset_generator',
            ['--story', storyId]
        );

        let output = '';
        process.stdout.on('data', (data) => {
            output += data;
            console.log(`[Generator] ${data}`);
        });

        process.on('close', (code) => {
            if (code === 0) {
                resolve(output);
            } else {
                reject(new Error(`Generator failed with code ${code}`));
            }
        });
    });
}

// Utilise
generateAssets('rimouski')
    .then(() => console.log('✅ Assets générés'))
    .catch(err => console.error('❌', err));

---

4️⃣ Résultats Générés

Après exécution, tu auras:

stories/[story-id]/assets/
├── images/
│   ├── scene_1.png      ✅ Image générée
│   ├── scene_2.png
│   └── ...
├── depths/
│   ├── scene_1.png      (Depth map)
│   └── ...
├── scenes/
│   ├── scene_1.txt      (Prompt original)
│   └── ...
├── on-screen text/
│   ├── scene_1.txt      (Texte overlay)
│   └── ...
└── sounds/              (À remplir manuellement)

---

5️⃣ Intégration avec Progress Tracking

Le moteur écrit la progression dans current_task.json:

import json
import time

def monitor_progress(content_root):
    """Surveille la génération en temps réel"""
    task_file = Path(content_root) / "current_task.json"

    while task_file.exists():
        try:
            with open(task_file, 'r') as f:
                progress = json.load(f)
                print(f"📊 {progress['story']}: {progress['step']} ({progress['progress']}%)")
        except:
            pass
        time.sleep(1)

# Utilise dans ton dashboard
monitor_progress('./stories')

---

6️⃣ Commandes Disponibles

# Générer une seule histoire
./asset_generator --story rimouski

# Générer TOUTES les histoires
./asset_generator --all

# Forcer la régénération (ignorer les existants)
./asset_generator --story rimouski --force

# Voir l'aide
./asset_generator --help

---

7️⃣ Gestion des Erreurs

Si ça crash/fail

Le moteur crée .generation_checkpoint.json pour reprendre:

# Relance = reprend automatiquement du dernier succès
./asset_generator --story rimouski

Si tu veux forcer un reset

rm stories/rimouski/.generation_checkpoint.json
./asset_generator --story rimouski --force

---

8️⃣ Performance Tips

Situation	Action
Lent sur API	Use local Smart Router si possible
Crash mémoire	Baisse max_cache_mb dans optimization.rs (ligne ~20)
Images manquantes	Utilise --force pour régénérer
Reprendre après crash	Relance juste, utilise checkpoint automatiquement

---

9️⃣ Dépannage

❌ "Binary not found"

cd Engine
cargo build --release

❌ "Smart Router not responding"

# Vérifier Smart Router
curl http://localhost:8000/api/image

# Ou checker variables
echo $AI_SMART_ROUTER_URL

❌ "API_SECRET missing"

# Ajoute au .env
echo "API_SECRET=your_secret" >> .env

❌ "Out of memory"

→ Le moteur nettoie automatiquement → Attend quelques secondes entre scènes

---

🔟 Exemple Complet pour Dashboard

#!/usr/bin/env python3
"""Intégration Rust Generator avec Dashboard"""

import subprocess
import json
from pathlib import Path
import time

class RustAssetGenerator:
    def __init__(self, engine_path="./Engine"):
        self.binary = Path(engine_path) / "target/release/asset_generator"
        self.progress_file = Path("stories/../current_task.json")

    def build_if_needed(self):
        """Build le binary s'il existe pas"""
        if not self.binary.exists():
            print("🔨 Building Rust generator...")
            subprocess.run(["cargo", "build", "--release"], cwd="Engine", check=True)

    def generate(self, story_id, force=False):
        """Générer les assets pour une histoire"""
        self.build_if_needed()

        cmd = [str(self.binary), "--story", story_id]
        if force:
            cmd.append("--force")

        print(f"🎬 Generating {story_id}...")

        # Monitor progress
        process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)

        while process.poll() is None:
            if self.progress_file.exists():
                try:
                    with open(self.progress_file) as f:
                        progress = json.load(f)
                        print(f"   📊 {progress['step']} ({progress['progress']}%)")
                except:
                    pass
            time.sleep(1)

        if process.returncode == 0:
            print(f"✅ {story_id} completed!")
            return True
        else:
            print(f"❌ {story_id} failed!")
            print(process.stderr.read())
            return False

# Utilise
if __name__ == "__main__":
    gen = RustAssetGenerator()
    gen.generate("rimouski", force=False)

---

📋 Checklist d'Intégration

• Rust installé (rustup --version)
• Smart Router fonctionnel sur localhost:8000
• Variables d'env configurées (.env créé)
• Binary buildé (cargo build --release)
• Test manuel (./target/release/asset_generator --story rimouski)
• Intégration au dashboard
• Test avec vrai story
• Progress tracking activé
• Error recovery testé

---

🎁 C'est Tout!

Le moteur Rust est prêt à utiliser. Il faut juste:

1. Build une fois
2. Appeler le binary depuis ton dashboard
3. Attendre les images dans assets/images/

Aucun Python à modifier, aucune dépendance supplémentaire. Juste un binary très efficace qui utilise peu de RAM! 🚀