logimage-generator/docs/superpowers/specs/2026-05-20-logimage-generator-design.md

# Logimage Generator — Design Spec

Date: 2026-05-20

## Résumé

Outil CLI Python qui génère des nonogrammes (logimages) en PDF prêts à imprimer. Le programme récupère automatiquement des images depuis Unsplash, les convertit en grilles noir/blanc optimisées pour la jouabilité, calcule les indices lignes/colonnes, et produit un PDF A4 avec une grille centrée par page.

---

## 1. Comportement utilisateur

### Invocation

```bash
# Mode minimal — 1 grille, thème aléatoire, difficulté medium
logimage

# Avec options
logimage \
  --theme "animals" \
  --difficulty medium \
  --size 20x15 \
  --count 5 \
  --solution \
  --output puzzles.pdf
```

### Paramètres CLI

| Flag | Défaut | Description |
|------|--------|-------------|
| `--theme TEXT` | aléatoire | Mot-clé pour la recherche d'images Unsplash |
| `--difficulty easy\|medium\|hard` | `medium` | 10×10 / 15×15 / 20×20 |
| `--size NxM` | — | Taille libre ; écrase `--difficulty` si fourni |
| `--count N` | `1` | Nombre de grilles dans le PDF |
| `--solution` | off | Ajoute une page solution après chaque grille |
| `--output PATH` | `puzzles.pdf` | Chemin du fichier PDF de sortie |

### Configuration

Clé API Unsplash via variable d'environnement ou fichier `.env` à la racine :
```
UNSPLASH_ACCESS_KEY=xxx
```

### Format PDF

- Format A4 portrait, une grille par page
- Mise en page : titre en haut, grille centrée, thème en bas
- Grille vierge (cases à colorier), indices lignes à gauche, indices colonnes en haut
- Si `--solution` : page solution insérée après chaque grille (grille pré-remplie)

---

## 2. Architecture (Clean Architecture)

La règle de dépendance est stricte : les couches internes ne connaissent jamais les couches externes.

```
domain ← application ← infrastructure ← cli
```

### Structure des fichiers

```
src/logimage/
├── domain/
│   ├── entities/
│   │   └── puzzle.py          # NonogramPuzzle
│   ├── value_objects/
│   │   ├── grid.py            # Grid (immuable)
│   │   └── clue.py            # Clue (immuable)
│   └── ports/
│       ├── image_source.py    # ImageSource (ABC)
│       ├── image_converter.py # ImageConverter (ABC)
│       └── pdf_exporter.py    # PdfExporter (ABC)
│
├── application/
│   └── use_cases/
│       └── generate_puzzles.py  # GeneratePuzzlesUseCase
│
├── infrastructure/
│   ├── image/
│   │   ├── unsplash_source.py   # UnsplashImageSource
│   │   └── pillow_converter.py  # PillowImageConverter
│   └── pdf/
│       └── reportlab_exporter.py
│
└── cli/
    └── main.py                  # Composition root + argparse

tests/
├── domain/
├── application/
├── infrastructure/              # @pytest.mark.integration
└── fakes/                       # FakeImageSource, FakeImageConverter, FakePdfExporter
```

---

## 3. Modèle du domaine

### Value objects

**`Grid`**
- Données : `tuple[tuple[bool]]` (immuable)
- Contraintes : largeur et hauteur entre 5 et 50
- Lève `ValueError` si les contraintes ne sont pas respectées

**`Clue`**
- Séquence immuable d'entiers positifs représentant les blocs d'une ligne ou colonne
- Ligne vide → `Clue([])`
- Exemple : `[T,T,F,T,F,F,T,T,T]` → `Clue([2, 1, 3])`

### Entité

**`NonogramPuzzle`**
- `grid: Grid` — la solution
- `row_clues: tuple[Clue]` — calculées à la construction
- `col_clues: tuple[Clue]` — calculées à la construction
- `title: str` — thème ou nom de l'image source
- Fabriqué via `NonogramPuzzle.from_grid(grid, title)` qui calcule les clues

### Ports (interfaces)

```python
class ImageSource(ABC):
    def fetch(self, theme: str | None = None) -> bytes: ...

class ImageConverter(ABC):
    def to_grid(self, image_bytes: bytes, width: int, height: int) -> Grid: ...

class PdfExporter(ABC):
    def export(
        self,
        puzzles: list[NonogramPuzzle],
        path: Path,
        with_solution: bool = False,
    ) -> None: ...
```

---

## 4. Use case

**`GeneratePuzzlesUseCase`**

Dépendances injectées : `ImageSource`, `ImageConverter`, `PdfExporter`

Séquence d'exécution :
1. Valider les paramètres (taille, count)
2. Pour chaque grille à générer :
   a. `image_source.fetch(theme)` → `bytes`
   b. `image_converter.to_grid(bytes, width, height)` → `Grid`
   c. `NonogramPuzzle.from_grid(grid, title)` → `NonogramPuzzle`
3. `pdf_exporter.export(puzzles, path, with_solution)`

---

## 5. Infrastructure

### `UnsplashImageSource`
- Utilise `httpx` pour appeler l'API Unsplash (`/photos/random?query=<theme>`)
- Clé API lue depuis `UNSPLASH_ACCESS_KEY`
- Télécharge l'image en JPEG (taille raisonnable, ~800px)

### `PillowImageConverter`
- Redimensionne l'image à `width × height` pixels
- Conversion en niveaux de gris
- Détection de contours avec OpenCV (Canny) pour favoriser les formes reconnaissables
- Seuillage adaptatif pour maximiser la jouabilité (pas trop de cases noires, pas trop peu)
- Retourne un `Grid`

### `ReportLabPdfExporter`
- Format A4 portrait
- Grille rendue avec `reportlab` (rectangles, texte pour les indices)
- Indices colonnes en haut (empilés verticalement si plusieurs chiffres), indices lignes à gauche
- Marquage de groupes de 5 cases (bords plus épais) pour faciliter le comptage
- Page solution : même layout, cases noires pré-remplies

---

## 6. Stratégie de test (TDD)

### Tests domain (purs, aucun mock)

```
test_clue_from_consecutive_cells()
test_clue_empty_row()
test_clue_single_cell()
test_puzzle_computes_row_and_col_clues()
test_grid_rejects_width_below_minimum()
test_grid_rejects_height_above_maximum()
test_grid_is_immutable()
```

### Tests application (mocks des ports via fakes)

```
test_generate_single_puzzle_calls_fetch_once()
test_generate_count_5_calls_fetch_5_times()
test_solution_flag_forwarded_to_exporter()
test_invalid_size_raises_value_error()
test_size_from_difficulty_easy_is_10x10()
test_size_from_difficulty_hard_is_20x20()
```

### Tests d'intégration (`@pytest.mark.integration`, réseau réel)

```
test_unsplash_returns_valid_jpeg_bytes()
test_pillow_converter_output_matches_requested_size()
test_reportlab_creates_nonempty_pdf_file()
```

### Exécution

```bash
pytest tests/domain tests/application        # rapide, CI toujours
pytest -m integration                        # ponctuel, nécessite UNSPLASH_ACCESS_KEY
pytest --cov=logimage --cov-report=term-missing
```

Couverture cible : ≥ 90% sur `domain/` et `application/`.

---

## 7. Dépendances

| Rôle | Bibliothèque |
|------|-------------|
| Traitement image | `Pillow` |
| Détection contours | `opencv-python-headless` |
| Génération PDF | `reportlab` |
| HTTP | `httpx` |
| Variables d'env | `python-dotenv` |
| Tests | `pytest`, `pytest-cov` |
| Lint + format | `ruff` |
| Typage statique | `mypy` |

Python ≥ 3.11 requis.

### `pyproject.toml` (structure)

```toml
[project]
name = "logimage-generator"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "Pillow", "opencv-python-headless", "reportlab",
    "httpx", "python-dotenv",
]

[project.optional-dependencies]
dev = ["pytest", "pytest-cov", "ruff", "mypy"]

[project.scripts]
logimage = "logimage.cli.main:main"

[tool.pytest.ini_options]
markers = ["integration: tests requiring network and API keys"]

[tool.ruff]
line-length = 88

[tool.mypy]
strict = true
```

---

## 8. Ce qui est hors scope

- Interface graphique ou web
- Éditeur interactif de grille
- Validation de l'unicité de la solution (problème NP-difficile pour les grandes grilles)
- Cache local des images téléchargées (peut être ajouté plus tard)
- Support des nonogrammes en couleur