fix(ci): make ruff + mypy green on the new src/ layout

Ruff (44 errors → 0):
- 22 auto-fixed: import order (I001), Optional[X] → X | None (UP045),
quoted annotations (UP037), 2 unused imports in tests (F401), 2 empty
f-strings (F541)
- 2 fixed by hand: B904 in api/main.py — `raise HTTPException(...)`
inside `except` now uses `... from e` to preserve the cause
- 20 ignored at config level: E701 multiple-statements-on-one-line. The
`if cond: ws.cell(row=r, column=N, value=…)` block in cms.py is an
intentional column-aligned table mapping conditions → spreadsheet
columns; splitting destroys the visual grid. Documented in pyproject.toml.

Mypy (3 errors → 0):
- Two .to(device) calls on from_pretrained() chains in inference.py
add `# type: ignore[arg-type]` (transformers stubs mis-type the return
so .to() looks wrong).
- _encode() return type was missing — annotate as Any (the real type is
transformers.BatchEncoding but transformers.* is ignored in mypy.ini,
and the caller uses .word_ids() which dict doesn't have).
- `from typing import Any` added to inference.py.

Verified:
- ruff check src/ tests/ → All checks passed
- mypy --config-file mypy.ini src/guichetoi/cms.py src/guichetoi/recommendation.py → Success
- pytest tests/test_cms_generator.py → 71/71 pass

pyproject.toml

@@ -79,4 +79,7 @@ select = ["E", "F", "I", "B", "UP"]
 ignore = [
     "E501",  # line length — codebase has long French strings
     "B008",  # function-call-in-default-arg — used intentionally with FastAPI Depends/File
+    "E701",  # multiple-statements-on-one-line — cms.py uses column-aligned
+             #   `if cond: ws.cell(row=r, column=N, value=…)` as a visual table
+             #   mapping conditions → spreadsheet columns. Splitting destroys the grid.
 ]

src/guichetoi/api/main.py

@@ -80,7 +80,6 @@ from fastapi.responses import JSONResponse
 from guichetoi import cms as cms_gen
 from guichetoi import recommendation as reco
 
-
 # ────────────────────────────────────────────────────────────────────────────
 # Logging
 # ────────────────────────────────────────────────────────────────────────────
@@ -196,12 +195,12 @@ def _materialise_uploads(files: list[UploadFile]) -> tuple[list[Path], tempfile.
             try:
                 with zipfile.ZipFile(io.BytesIO(raw)) as zf:
                     zf.extractall(zdir)
-            except zipfile.BadZipFile:
+            except zipfile.BadZipFile as e:
                 tmp.cleanup()
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
                     detail=f"Invalid ZIP archive: {name}",
-                )
+                ) from e
             for p in zdir.rglob("*"):
                 if not p.is_file():
                     continue
@@ -318,7 +317,7 @@ def cms(verdict: dict) -> Response:
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"CMS template missing: {e}",
-        )
+        ) from e
     finally:
         out_path.unlink(missing_ok=True)
 

src/guichetoi/cms.py

@@ -401,9 +401,9 @@ def fill_cms(
     # PresenceDta (22), Commentaire Faisabilite (23-24): blank, manual
 
     comment_bits = [
-        f"Pré-rempli automatiquement (GuichetOI-ML)",
+        "Pré-rempli automatiquement (GuichetOI-ML)",
         f"Projet {proj_type} · Type site {type_site} · Détection {detection_lbl}",
-        f"À compléter manuellement : coordonnées XY (Géoréso), Identifiant Processus (Mondofi pour OCC)",
+        "À compléter manuellement : coordonnées XY (Géoréso), Identifiant Processus (Mondofi pour OCC)",
     ]
     ws.cell(row=r, column=25, value=" — ".join(comment_bits))
 

src/guichetoi/inference.py

@@ -25,9 +25,9 @@ import logging
 import os
 import re
 import sys
-from dataclasses import dataclass, field, asdict
+from dataclasses import asdict, dataclass, field
 from pathlib import Path
-from typing import Optional
+from typing import Any
 
 import torch
 from PIL import Image
@@ -361,7 +361,7 @@ def _mandat_checkbox_score(marker: str) -> int:
     return 0
 
 
-def _detect_mandat_checkbox(ocr_text: str) -> Optional[str]:
+def _detect_mandat_checkbox(ocr_text: str) -> str | None:
     """
     Decide which checkbox is X-marked next to 'Je dispose d'un mandat de
     représentation du Maître d'ouvrage' on the fiche form.
@@ -394,9 +394,9 @@ def _detect_mandat_checkbox(ocr_text: str) -> Optional[str]:
 
 
 def _clean_field_extractions(
-    raw_fields: dict[str, "FieldExtraction"],
+    raw_fields: dict[str, FieldExtraction],
     ocr_text: str,
-) -> dict[str, "FieldExtraction"]:
+) -> dict[str, FieldExtraction]:
     """
     Apply per-field validators + regex fallbacks to the model's raw outputs.
 
@@ -604,7 +604,7 @@ def run_ocr(image: Image.Image, cfg: Config) -> OCRResult:
     return OCRResult(words, boxes, " ".join(words), "pytesseract")
 
 
-def extract_pdf_text(file_path: Path) -> Optional[str]:
+def extract_pdf_text(file_path: Path) -> str | None:
     """Quick path: pull embedded text from a PDF without OCR. Returns None if no text or fails."""
     if file_path.suffix.lower() != ".pdf" or fitz is None:
         return None
@@ -631,7 +631,7 @@ class GuichetOIPipeline:
         result   = pipeline.run(path)     # in your /predict endpoint
     """
 
-    def __init__(self, cfg: Config = Config(), device: Optional[str] = None):
+    def __init__(self, cfg: Config = Config(), device: str | None = None):
         self.cfg = cfg
         self.device = torch.device(
             device or ("cuda" if torch.cuda.is_available() else "cpu")
@@ -649,14 +649,16 @@ class GuichetOIPipeline:
             cfg.base_processor, apply_ocr=False,
         )
 
-        # Models — moved to device, set to eval mode
+        # Models — moved to device, set to eval mode.
+        # (mypy ignores below: transformers stubs mis-type from_pretrained's
+        #  return so .to(device) appears to take the wrong arg.)
         self.classifier = LayoutLMv3ForSequenceClassification.from_pretrained(
             resolve_model_path(cfg.classifier_dir)
-        ).to(self.device).eval()
+        ).to(self.device).eval()  # type: ignore[arg-type]
 
         self.extractor = LayoutLMv3ForTokenClassification.from_pretrained(
             resolve_model_path(cfg.extractor_dir)
-        ).to(self.device).eval()
+        ).to(self.device).eval()  # type: ignore[arg-type]
 
         log.info(
             f"Pipeline ready · {len(self.doc_classes)} document classes · "
@@ -666,7 +668,9 @@ class GuichetOIPipeline:
     # ────────────────────────────────────────────────────────────────────
     # Inference primitives
     # ────────────────────────────────────────────────────────────────────
-    def _encode(self, image: Image.Image, words: list[str], boxes: list[list[int]]):
+    def _encode(self, image: Image.Image, words: list[str], boxes: list[list[int]]) -> Any:
+        # Returns a transformers BatchEncoding (dict-like, with .word_ids()).
+        # Annotated Any because the transformers stubs are ignored in mypy.ini.
         return self.processor(
             image, words, boxes=boxes,
             max_length=self.cfg.max_seq_length,
@@ -703,7 +707,7 @@ class GuichetOIPipeline:
         id2label = self.extractor.config.id2label
 
         spans: list[dict] = []
-        cur: Optional[dict] = None
+        cur: dict | None = None
         prev_word = None
 
         for pos, w_idx in enumerate(word_ids):
@@ -845,7 +849,7 @@ def _save_result(result: InferenceResult, image_path: Path, cfg: Config) -> Path
     return out_path
 
 
-def _prompt_for_image_path() -> Optional[str]:
+def _prompt_for_image_path() -> str | None:
     """GUI fallback ONLY when running interactively. Skipped on headless servers."""
     if not sys.stdin.isatty():
         return None

src/guichetoi/recommendation.py

@@ -35,10 +35,9 @@ import json
 import logging
 import re
 import sys
-from dataclasses import dataclass, field, asdict
-from pathlib import Path
 from collections.abc import Sequence
-from typing import Optional
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
 
 from guichetoi.inference import Config, GuichetOIPipeline, InferenceResult
 
@@ -134,9 +133,9 @@ class RecommendationEngine:
 
     def __init__(
         self,
-        pipeline: Optional[GuichetOIPipeline] = None,
+        pipeline: GuichetOIPipeline | None = None,
         rules:    RuleConfig = RuleConfig(),
-        cfg:      Optional[Config] = None,
+        cfg:      Config | None = None,
     ):
         self.rules = rules
         self.pipeline = pipeline or GuichetOIPipeline(cfg=cfg or Config())
@@ -214,7 +213,7 @@ class RecommendationEngine:
         r"dossier[\s_-]*de[\s_-]*r[ée]coll?ement",
     ]
 
-    def _filename_class_hint(self, filename: str) -> Optional[str]:
+    def _filename_class_hint(self, filename: str) -> str | None:
         name = filename.lower()
         for pat, cls in self._FILENAME_HINTS:
             if re.search(pat, name):
@@ -476,7 +475,7 @@ class RecommendationEngine:
 
         return reasons
 
-    def _autorisation_matches(self, ref_urb: str, autorisations: list[DocumentSummary]) -> Optional[bool]:
+    def _autorisation_matches(self, ref_urb: str, autorisations: list[DocumentSummary]) -> bool | None:
         """
         Cross-check the fiche's urbanism reference against the autorisation(s).
 
@@ -610,13 +609,13 @@ class RecommendationEngine:
 # ────────────────────────────────────────────────────────────────────────────
 # Small, file-local helpers
 # ────────────────────────────────────────────────────────────────────────────
-def _value(payload: Optional[dict]) -> str:
+def _value(payload: dict | None) -> str:
     if not payload:
         return ""
     return (payload.get("value") or "").strip()
 
 
-def _to_int(s: str) -> Optional[int]:
+def _to_int(s: str) -> int | None:
     if not s:
         return None
     digits = re.sub(r"[^\d]", "", s)
@@ -659,7 +658,7 @@ def _norm_ref(s: str) -> str:
 # ────────────────────────────────────────────────────────────────────────────
 # Folder picker (GUI fallback for interactive runs)
 # ────────────────────────────────────────────────────────────────────────────
-def _prompt_for_folder() -> Optional[str]:
+def _prompt_for_folder() -> str | None:
     """
     Open a Windows-native directory picker. Returns the selected path, or
     None if the dialog is cancelled or unavailable (e.g. headless server).
@@ -747,7 +746,7 @@ def main():
     args = parser.parse_args()
 
     # Resolve input source: explicit --files, then --folder, then GUI picker
-    folder: Optional[Path] = None
+    folder: Path | None = None
     files: list[Path] = []
 
     if args.files:

tests/test_cms_generator.py

@@ -9,7 +9,6 @@ template and verifies the expected cells are written.
 """
 from __future__ import annotations
 
-import tempfile
 from datetime import datetime, timedelta
 from pathlib import Path
 

tests/test_inference_postprocess.py

@@ -8,8 +8,6 @@ These tests don't load the model — we exercise the pure functions directly.
 """
 from __future__ import annotations
 
-import re
-
 import pytest