feat(api): exposer l'API publique du Cercle 1 au niveau racine

Avant ce commit, ``import picarones`` n'exposait que ``__version__``.
Un utilisateur tiers devait connaître les chemins internes pour
importer les abstractions principales (``from picarones.core.corpus
import Corpus``). C'est une UX cassée pour une plateforme à vocation
institutionnelle.

Ce commit ré-exporte au niveau ``picarones.*`` les ~30 symboles
stables du Cercle 1 :

>>> from picarones import Corpus, Document, BaseModule, ArtifactType
>>> from picarones import BenchmarkResult, EngineReport, DocumentResult
>>> from picarones import MetricsResult, aggregate_metrics
>>> from picarones import Fact, FactType, FactImportance, DetectorRegistry
>>> from picarones import PipelineRunner, PipelineSpec, PipelineStep
>>> from picarones import MetricSpec, register_metric, compute_at_junction

Le contrat de stabilité documenté dans ``docs/api-stable.md``
s'applique à ces noms : pas de breaking change entre versions
mineures (semver ``1.x.0``).

Pour les implémentations (calcul, runner, adapters), l'utilisateur
continue d'utiliser les sous-packages explicites :

>>> from picarones.measurements.runner import run_benchmark
>>> from picarones.measurements.metrics import compute_metrics
>>> from picarones.engines.tesseract import TesseractEngine

``picarones/core/__init__.py`` est aussi étoffé avec une docstring
qui liste les 8 modules cercle 1 et rappelle la règle de dépendance.

https://claude.ai/code/session_01Hsd7kL8yeCbXn1mA7GQK9L

picarones/__init__.py

@@ -1,13 +1,114 @@
-"""
-Picarones — Plateforme de comparaison de moteurs OCR pour documents patrimoniaux.
+"""Picarones — Plateforme de benchmark OCR/HTR pour documents patrimoniaux.
 
 Licence Apache 2.0.
+
+API publique du Cercle 1 (abstractions stables) ré-exportée ici pour
+permettre :
+
+>>> from picarones import Corpus, Document, BaseModule, ArtifactType
+>>> from picarones import BenchmarkResult, EngineReport, DocumentResult
+
+Pour les implémentations (calcul de métriques, runner, adapters OCR…),
+utiliser les sous-packages explicites :
+
+>>> from picarones.measurements.runner import run_benchmark
+>>> from picarones.measurements.metrics import compute_metrics
+>>> from picarones.engines.tesseract import TesseractEngine
+
+Voir ``docs/architecture.md`` pour la cartographie complète des
+3 cercles, et ``docs/api-stable.md`` pour le contrat de stabilité.
 """
 
+from __future__ import annotations
+
+# Version (lecture dynamique depuis le package metadata après ``pip install -e .``)
 try:
     from importlib.metadata import version as _get_version
     __version__ = _get_version("picarones")
-except Exception:
+except Exception:  # noqa: BLE001
     __version__ = "1.0.0"
 
 __author__ = "Picarones contributors"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# API publique — Cercle 1 uniquement
+# ──────────────────────────────────────────────────────────────────────────
+
+from picarones.core.corpus import (
+    Corpus,
+    Document,
+    GTLevel,
+    TextGT,
+    AltoGT,
+    PageGT,
+    EntitiesGT,
+    ReadingOrderGT,
+    load_corpus_from_directory,
+)
+from picarones.core.modules import ArtifactType, BaseModule
+from picarones.core.results import (
+    BenchmarkResult,
+    DocumentResult,
+    EngineReport,
+)
+from picarones.core.metrics import MetricsResult, aggregate_metrics
+from picarones.core.facts import (
+    DetectorRegistry,
+    Fact,
+    FactImportance,
+    FactType,
+)
+from picarones.core.pipeline import (
+    PipelineResult,
+    PipelineRunner,
+    PipelineSpec,
+    PipelineStep,
+    StepResult,
+)
+from picarones.core.metric_registry import (
+    MetricSpec,
+    compute_at_junction,
+    register_metric,
+    select_metrics,
+)
+
+__all__ = [
+    "__version__",
+    "__author__",
+    # Corpus
+    "Corpus",
+    "Document",
+    "GTLevel",
+    "TextGT",
+    "AltoGT",
+    "PageGT",
+    "EntitiesGT",
+    "ReadingOrderGT",
+    "load_corpus_from_directory",
+    # Modules génériques (BaseModule)
+    "ArtifactType",
+    "BaseModule",
+    # Résultats
+    "BenchmarkResult",
+    "DocumentResult",
+    "EngineReport",
+    "MetricsResult",
+    "aggregate_metrics",
+    # Moteur narratif (modèle de données)
+    "DetectorRegistry",
+    "Fact",
+    "FactImportance",
+    "FactType",
+    # Pipelines composées (axe B)
+    "PipelineResult",
+    "PipelineRunner",
+    "PipelineSpec",
+    "PipelineStep",
+    "StepResult",
+    # Registre de métriques typées
+    "MetricSpec",
+    "compute_at_junction",
+    "register_metric",
+    "select_metrics",
+]

picarones/core/__init__.py

@@ -1 +1,26 @@
-"""Core modules : corpus, métriques, résultats, orchestration."""
+"""Picarones — Cercle 1 : abstractions de domaine.
+
+Ce package contient **uniquement des contrats** : dataclasses du
+domaine, types d'artefacts, interfaces abstraites, registres, modèle
+narratif. Pas de logique métier, pas de calcul, pas d'I/O.
+
+Règle de dépendance : un module du cercle 1 peut importer un autre
+module du cercle 1. Il ne peut **rien** importer des cercles 2 ou 3
+(``measurements``, ``engines``, ``llm``, ``pipelines``, ``modules``,
+``extras``, ``report``, ``cli``, ``web``).
+
+Modules
+-------
+- :mod:`corpus`           Document, Corpus, GTLevel + payloads typés
+- :mod:`modules`          BaseModule, ArtifactType
+- :mod:`results`          DocumentResult, EngineReport, BenchmarkResult
+- :mod:`metrics`          MetricsResult (dataclass), aggregate_metrics
+- :mod:`metric_registry`  MetricSpec, register_metric, compute_at_junction
+- :mod:`metric_hooks`     register_document_metric, register_corpus_aggregator
+- :mod:`pipeline`         PipelineRunner, PipelineSpec, PipelineStep
+- :mod:`facts`            Fact, FactType, FactImportance, DetectorRegistry
+
+Voir :doc:`docs/architecture.md` pour le manifeste complet et
+:doc:`docs/api-stable.md` pour le contrat de stabilité de chaque
+nom exporté.
+"""