# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

InkFlow transforme un **EPUB** en **livre audio** (1 dossier/livre, 1 MP3/chapitre, tags ID3 + cover), 100 % en local sur Mac Apple Silicon via **MLX**. Analyse de texte par **Gemma** (`mlx-lm`), synthèse vocale par backend pluggable **Kokoro** (rapide, previews/mono-narrateur) ou **Qwen3-TTS** (qualité + clonage, rendu final multi-voix). Optimisé pour le **français**.

## Commandes

```bash
# Installation (Python >= 3.11, macOS arm64)
brew install ffmpeg espeak-ng           # prérequis système
python3.13 -m venv .venv && source .venv/bin/activate
pip install -e backend                  # installe le package `inkflow`
python backend/scripts/setup_models.py  # vérifie l'env + télécharge les modèles MLX

# Pipeline CLI (point d'entrée : `inkflow`, défini dans backend/inkflow/cli.py)
inkflow parse "samples/livre.epub"          # EPUB -> data/<slug>/{book.json, chapters/}
inkflow analyze <slug> --chapter 5          # un chapitre ; sans --chapter = tous
inkflow analyze <slug> --force              # ré-analyse même si l'artefact existe
inkflow cast <slug> --dedup                 # voicebank + auto-assignation des voix
inkflow pronounce <slug>                    # dictionnaire de prononciation (Gemma)
inkflow render <slug> 5 --backend kokoro            # rendu rapide mono-narrateur
inkflow render <slug> 5 --backend qwen3 --no-mono   # rendu final multi-voix
inkflow render <slug> 5 --max-paragraphs 10         # test rapide (tronque)
inkflow info <slug>                          # structure d'un livre parsé
inkflow serve                                # API + UI sur http://127.0.0.1:8000

# Sans `pip install -e`, lancer depuis backend/ : python -m inkflow.cli ...

# Tests (pytest ; lancer depuis backend/ pour résoudre l'import `inkflow`)
cd backend && python -m pytest                          # toute la suite
cd backend && python -m pytest tests/test_incises.py    # un fichier
cd backend && python -m pytest tests/test_incises.py::test_inversion_au_milieu  # un test

# Frontend (React + Vite + Tailwind)
cd frontend && npm install && npm run build   # build -> dist/ (servi par `inkflow serve`)
cd frontend && npm run dev                    # dev sur :5173, proxy /api+/ws vers :8000
```

Le développement frontend nécessite `inkflow serve` (backend :8000) **et** `npm run dev` (UI :5173) en parallèle. En production, `inkflow serve` sert `frontend/dist/` sur le même port que l'API.

## Architecture

### Pipeline orienté artefacts (reprenable)

Chaque étape lit l'artefact JSON de la précédente et écrit le sien dans `data/<slug>/`. Le contrat entre étapes = les modèles pydantic v2 de `backend/inkflow/models.py` (sérialisés tels quels). C'est **ce qui rend le pipeline reprenable** : l'existence d'un fichier signale qu'une étape est faite.

```
parse → book.json + chapters/chNN.json   (epub/parser.py)
analyze → analysis/chNN.json + cast.json (analysis/segmenter.py)
cast → cast.json enrichi (voix)          (casting/assign.py + voicebank.py)
pronounce → pronunciation.json           (analysis/pronunciation.py)
render → output/<titre>/NN-....mp3        (pipeline/render.py + audio/postprocess.py)
```

`store/artifacts.py` centralise toute lecture/écriture de ces artefacts (`load_*`/`save_*`). Ne pas lire/écrire ces JSON ailleurs.

### Deux niveaux de configuration (distinction importante)

- **`config.py`** : constantes figées lues à l'import, surchargeables **uniquement** par variables d'environnement au démarrage (`INKFLOW_*`). Chemins, IDs de modèles MLX par défaut, params audio.
- **`settings.py`** : objet `Settings` **persisté** dans `data/settings.json`, éditable au runtime depuis l'UI. Contient aussi les **prompts système Gemma** (éditables). Le pipeline consulte `get_settings()` au moment de l'exécution. `save_settings()` invalide les caches modèles (`get_backend.cache_clear()`, `analysis.llm.factory.reset_llm_cache()`) pour appliquer les changements **sans redémarrage**.

### Orchestration (UI temps réel)

`pipeline/orchestrator.py` expose un singleton `orchestrator` avec un **unique worker thread** (un Mac = une charge MLX à la fois) : les jobs sont enfilés et rendent la main immédiatement à l'API. L'état (`ProjectState`) est persisté dans `data/<slug>/state.json` et diffusé par WebSocket à chaque changement via un `broadcaster` injecté par la couche API (l'orchestrateur reste indépendant de FastAPI).

`load_state()` appelle `_reconcile()` : il **réaligne l'état sur les artefacts présents sur disque**, donc le travail fait en CLI (ou après redémarrage) est reflété dans l'UI sans le rejouer. Quand on ajoute une étape, penser à étendre `_reconcile()`.

`api/app.py` : routes lourdes (analyze/cast/pronounce/render) → `orchestrator.run_*` (enfilées, renvoient `{queued: True}`) ; routes rapides (preview de voix) → threadpool ; lecture/écriture directe pour cast/pronunciation/settings. WebSocket sur `/ws/{slug}`.

### Détection d'incises — déterministe et cast-aware (cœur de l'attribution)

`analysis/segmenter.py` est le module le plus subtil. La segmentation narration/dialogue est déterministe (un paragraphe commençant par cadratin `—` est une réplique). L'attribution du locuteur est **hybride** :

1. **Détection d'incises déterministe** (`detect_incises`) : deux passes regex — inversion verbe-pronom (`dit-il`) et nominale consciente du casting (`compatit Holden`, `informa le soldat`). Les incises sont des **bornes** (offsets) annotées sur la réplique persistée entière, **non destructif** ; le découpage en voix narrateur/personnage se fait au rendu (`iter_incise_pieces`).
2. **Seeding** : une incise nominale qui nomme un personnage **fixe le locuteur avant l'appel LLM** (corrige les ratés du petit modèle).
3. **Attribution LLM** (`attribute_speakers`) : Gemma résout les répliques restantes par chunks, avec contexte narratif avant/après et confidence.
4. **Passe rétroactive** (`_refine_unknown_speakers`) : re-résout les répliques `inconnu`/`low` via l'alternance des tours. Coût nul s'il ne reste aucun doute.

Cette logique est **pure et testée** (`tests/test_incises.py`, 30+ cas sans Gemma). **Toute modification des regexes/verbes/rôles doit garder ces tests verts.** Préférer rater une incise qu'en inventer une (les listes `_SPEECH_VERBS`/`_ROLE_NOUNS` sont curées en ce sens).

### TTS pluggable

`tts/base.py` définit `TTSBackend.synthesize(text, VoiceSpec) -> (audio mono float32, sample_rate)` et `VoiceSpec` (preset pour Kokoro, ref_audio/ref_text pour le clonage Qwen3). `tts/factory.get_backend(name)` est `lru_cache` par **nom** (pas par id de modèle — d'où l'invalidation explicite dans settings). `pipeline/render.py` construit des `RenderUnit` (mono ou multi-voix), où `glued_to_prev` réduit le silence pour les incises rattachées à la réplique précédente.

### LLM d'analyse pluggable

`analysis/llm/` suit le **même pattern que le TTS**. La façade `client.LLM` (anciennement `Gemma`) expose `generate`/`generate_json` consommés par tout le pipeline ; elle porte toute la logique agnostique du moteur (calcul des params depuis `Settings`, retrait de la pensée des modèles à raisonnement, extraction JSON tolérante — helpers dans `_text.py`, testés purs dans `tests/test_gemma_reasoning.py`). Sous elle, `base.LLMBackend.complete(messages, ...) -> str` (texte brut) a deux implémentations : **`mlx_backend`** (mlx-lm, défaut) et **`lmstudio_backend`** (API OpenAI locale de LM Studio, sert GGUF *et* MLX). Sélection par nom via `factory.get_llm_backend(backend, model_ref)` (`lru_cache`, `reset_llm_cache()` pour invalider). Backend choisi dans `settings.gemma_backend` (`mlx`/`lmstudio`), surchargeable par `--backend`/`--model` sur les commandes CLI `analyze`/`pronounce`/`cast`/`benchmark`. LM Studio doit tourner avec son serveur local actif (onglet Developer).

**Qui possède la config de génération ?** Les réglages `gemma_temperature`/`gemma_max_tokens`/`gemma_reasoning*` pilotent le backend **MLX** (seule source de config pour `mlx-lm`). Pour **LM Studio**, c'est la config du modèle **dans LM Studio** qui prime : par défaut (`settings.lmstudio_defer_config=True`) le backend **n'impose ni `temperature` ni `max_tokens`** dans la requête — imposer `max_tokens` tronquait la réponse des modèles à raisonnement (pensée non terminée → « aucun JSON »). Le **contexte** se règle aussi côté LM Studio (au chargement : `lms load <m> --context-length N` ou l'UI) — InkFlow ne peut pas le porter, d'où l'erreur « context length » si le modèle est JIT-chargé avec un contexte trop court pour un chapitre. Mettre `lmstudio_defer_config=False` pour réimposer les réglages InkFlow (benchmarks reproductibles). LM Studio sépare déjà la pensée (`reasoning_content`) de la réponse (`content`) : le backend ne renvoie que `content`.

## Fichiers de référence (vérité terrain pour l'attribution)

`data/<slug>/reference/chNN.json` contient des **versions corrigées à la main** de la sortie d'analyse `analysis/chNN.json` — **même schéma `ChapterAnalysis`** (`index`, `title`, `segments` avec `type`/`text`/`speaker`/`incises`). Ce sont des **fixtures de vérité terrain** servant à juger la qualité de la segmentation, des incises et de l'attribution des locuteurs : on compare la sortie réelle du pipeline à la référence.

- Fixture canonique : `data/la-colere-de-tiamat/reference/ch05.json` (PROLOGUE - HOLDEN), plus `ch06.json`.
- **Aucun code ne les charge** : ce sont des références manuelles, distinctes des tests unitaires purs de `tests/test_incises.py`. Elles vérifient le comportement **bout-en-bout avec Gemma**, que les tests purs ne couvrent pas.
- Sous `data/` → **git-ignored** : présents localement, non versionnés. Les régénérer/corriger à la main quand on retravaille la logique d'attribution, puis comparer manuellement à `analyze --force`.

## Pièges d'environnement

- **espeak-ng** : Kokoro en français en dépend via phonemizer. `config.setup_espeak()` localise automatiquement `libespeak-ng.dylib` (homebrew) ; sinon exporter `PHONEMIZER_ESPEAK_LIBRARY`.
- **Modèle Gemma = goulot d'étranglement** : `gemma-3-4b-it-4bit` par défaut. C'est le petit modèle qui rate des attributions — d'où le seeding déterministe et la dedup heuristique-first.
- **`dedup_use_gemma = False` par défaut** : la dedup du casting est heuristique (sûre) ; la passe Gemma (opt-in `--llm`) rattache les variantes non évidentes mais produit des fusions erronées avec un petit modèle local.
- **Encodage MP3 via ffmpeg CLI** (pas pydub pour l'encodage final) ; tags/cover via mutagen.
- Les répertoires `data/`, `output/`, `samples/`, `node_modules/` sont git-ignored. `voicebank/` (clips de référence) est versionné.