teuthis-cms 0.1.0__py3-none-any.whl

app/ai/__init__.py

@@ -0,0 +1,58 @@
+"""Socle IA — Epic E8 (CDC §14, jalon M8a).
+
+**Ce que cet Epic livre : de quoi appeler une IA correctement. Pas une seule
+fonction éditoriale.** Le texte alternatif, l'extraction documentaire, le
+RAG, la détection d'obsolescence et la classification SVE sont l'Epic E9
+(M8b) ; ils s'appuient sur ce qui est ici, et n'y sont pas — ils vivent dans
+**`app/ai_editorial`**, un paquet distinct qui importe celui-ci et jamais
+l'inverse. Un test de recette d'E9 vérifie que le socle ne nomme aucune
+tâche éditoriale : c'est ce qui rend la séparation entre « savoir appeler un
+modèle correctement » et « savoir quoi lui demander » vérifiable plutôt que
+déclarative.
+
+| Module | Ce qu'il porte |
+|---|---|
+| `capabilities` | Les cinq capacités typées, et la traduction depuis le vocabulaire d'E7 |
+| `registry` | Le Model Registry — entrées déclaratives **YAML**, validées par Pydantic |
+| `tasks` | Les tâches du Core et leur régime de sortie (`required` / `optional` / `none`) |
+| `sovereignty` | Le mode d'installation (`restricted` par défaut) et ce qu'il autorise |
+| `policies` | La résolution `(tâche, tenant, contexte) → modèle` |
+| `administration` | Enregistrer fournisseur, modèle (avec sa déclaration), politique |
+| `ports` | Cinq ports typés — jamais une interface `AIProvider` fourre-tout |
+| `providers` | Les adaptateurs. Un seul livré ici : un fournisseur hors-ligne, pour la recette |
+| `breaker` | Le disjoncteur par `(tenant, modèle)` |
+| `journal` | `ai_jobs` : modèle, jetons, latence, coût, **sortie de données oui/non** |
+| `suggestions` | `ai_suggestions` : la seule porte de sortie d'une production d'IA |
+| `embeddings` | Isolation multi-tenant des vecteurs, garde-fou de réindexation |
+| `manager` | Le Provider Manager : le point de passage unique |
+| `runtime` | Le gestionnaire du processus — absent par défaut |
+
+**Les quatre règles qui n'admettent aucune exception**, répétées ici parce
+qu'elles se vérifient dans plusieurs modules à la fois :
+
+1. *Aucune fonctionnalité du Core ne dépend d'un appel IA pour aboutir*
+   (CDC §14.4). `invoke()` ne lève pas sur panne, la base n'accepte que
+   `on_failure='degrade'`, et un test structurel vérifie qu'aucun module
+   d'API du Core n'importe ce paquet.
+2. *Toute production d'IA passe par `ai_suggestions`* — sauf les sorties
+   structurelles (embeddings, extraction), qui n'ont rien à faire valider.
+3. *`data_leaves_infrastructure` est déclaré, jamais déduit.*
+4. *Changer de modèle d'embedding est une migration*, refusée
+   techniquement tant qu'une réindexation n'est pas planifiée (ADR-0004,
+   dont la décision de fond — quel modèle par défaut — reste ouverte : ce
+   socle n'en élit aucun).
+
+**Le CMS n'affirme aucune conformité réglementaire.** Ce qui est vérifiable
+ici, et vérifié, c'est où partent les données, qui l'a déclaré, et ce que
+chaque appel a consommé.
+
+**Ce paquet ne réexporte rien, contrairement à `app/plugins`.** Ce n'est pas
+un oubli : `app/models/ai.py` a besoin du type `vector`
+(`app.ai.vector`), et `app.ai.capabilities` a besoin du vocabulaire des
+plugins (`app.plugins.manifest`), lequel finit par importer `app.models`.
+Un `__init__` qui importerait le gestionnaire refermerait cette boucle et
+rendrait l'ordre des imports significatif — le genre de dépendance qui
+casse un jour, dans un module qui n'a rien demandé. Les appelants importent
+donc le sous-module dont ils ont besoin : `from app.ai.manager import
+ProviderManager`. La table ci-dessus dit lequel.
+"""

app/ai/administration.py

@@ -0,0 +1,326 @@
+"""Enregistrer un fournisseur, un modèle, une politique — Epic E8 (CDC §14.3).
+
+**Ces trois écritures sont des actes d'administration, pas des réglages.**
+Enregistrer un modèle, c'est déclarer où partent des données ; poser une
+politique, c'est décider qui, sur quel site, peut demander quoi à ce modèle.
+Ce module les traite comme telles : chaque écriture exige un `*_login`, la
+déclaration de sortie de données n'a **aucune valeur par défaut** dans la
+signature — il faut la dire — et les refus sont collectés puis levés d'un
+bloc, comme partout dans ce dépôt depuis E2.
+
+**Pourquoi des fonctions de service et pas des routes HTTP ?** L'écran
+d'administration IA appartient au front d'administration, qui n'est pas au
+périmètre de ce jalon ; y adosser des routes maintenant aurait exigé une
+permission `ai.manage` dans le catalogue RBAC (E6) au moment où personne ne
+peut encore l'exercer depuis une interface. Ces fonctions sont le
+comportement que ces routes appelleront ; elles sont testées comme telles.
+
+**Ce que ce module refuse, et pourquoi ce n'est pas de la rigidité.**
+
+- Un modèle dont l'entrée de catalogue est inconnue : sans elle, on ne sait
+  ni quel nom de runtime envoyer ni quel protocole parler. Inventer aurait
+  produit un appel qui échoue chez le fournisseur, après la sortie des
+  données.
+- Un modèle servi par un point d'accès déclaré tiers, mais déclaré comme ne
+  faisant pas sortir les données. L'inverse reste permis : un point d'accès
+  interne *peut* relayer vers un tiers, et l'administrateur doit pouvoir le
+  déclarer sortant.
+- Une déclaration qui contredit l'indication du catalogue **sans
+  justification écrite**. Le CMS n'a pas les moyens de trancher, mais il a
+  ceux d'exiger que la contradiction soit assumée par écrit et attribuée.
+- Un changement de modèle d'embedding sans réindexation planifiée
+  (ADR-0004). Refus opposé ici *et* à l'écriture des vecteurs : le premier
+  empêche la faute de se configurer, le second empêche un chemin de code de
+  la contourner.
+"""
+
+import uuid
+from decimal import Decimal
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.ai.capabilities import ModelCapability
+from app.ai.embeddings import EmbeddingModelChangeRefused, assert_embedding_model_allowed
+from app.ai.registry import ModelRegistry, default_registry
+from app.ai.tasks import OutputRegime, effective_regime
+from app.models.ai import AiModel, AiPolicy, AiProvider
+
+HOSTING_SELF = "self_hosted"
+HOSTING_THIRD_PARTY = "third_party"
+
+
+class AiConfigurationError(ValueError):
+    """Écriture refusée — toutes les fautes trouvées sont rassemblées."""
+
+    def __init__(self, errors: list[str]) -> None:
+        self.errors = errors
+        super().__init__(" ; ".join(errors))
+
+
+def _tarif(valeur: float | None) -> Decimal | None:
+    """Convertit un tarif en `Decimal` sans passer par la binaire du flottant."""
+    return None if valeur is None else Decimal(str(valeur))
+
+
+async def register_provider(
+    db: AsyncSession,
+    *,
+    tenant_id: uuid.UUID,
+    key: str,
+    registry_key: str,
+    label: str,
+    declared_by_login: str,
+    hosting: str | None = None,
+    endpoint_url: str | None = None,
+    credential_env: str | None = None,
+    config: dict | None = None,
+    registry: ModelRegistry | None = None,
+) -> AiProvider:
+    """Active un fournisseur sur un tenant.
+
+    `hosting` peut être déduit de l'indication du catalogue quand celle-ci
+    est nette (`self_hosted` ou `third_party`), mais **jamais** quand elle
+    vaut `unknown` — cas du point d'accès « custom », précisément celui où
+    deviner serait faux. Là, l'administrateur déclare.
+    """
+    registry = registry or default_registry()
+    errors: list[str] = []
+    entry = registry.provider(registry_key)
+    if entry is None:
+        raise AiConfigurationError(
+            [
+                f"fournisseur '{registry_key}' inconnu du catalogue : ajoutez-le en "
+                "YAML (AI_MODEL_REGISTRY_DIR) avant de l'activer sur un tenant"
+            ]
+        )
+    if hosting is None:
+        if entry.hosting_hint == "unknown":
+            errors.append(
+                f"le catalogue ne dit pas où '{registry_key}' est hébergé : "
+                "l'administrateur doit déclarer 'self_hosted' ou 'third_party'"
+            )
+        else:
+            hosting = entry.hosting_hint
+    elif hosting not in (HOSTING_SELF, HOSTING_THIRD_PARTY):
+        errors.append(
+            f"hébergement '{hosting}' inconnu : 'self_hosted' ou 'third_party'"
+        )
+    if not declared_by_login:
+        errors.append("une déclaration de fournisseur doit nommer son auteur")
+    if errors:
+        raise AiConfigurationError(errors)
+
+    provider = AiProvider(
+        tenant_id=tenant_id,
+        key=key,
+        registry_key=registry_key,
+        label=label,
+        hosting=hosting,
+        endpoint_url=endpoint_url,
+        credential_env=credential_env or entry.credential_env,
+        config=config,
+        declared_by_login=declared_by_login,
+    )
+    db.add(provider)
+    await db.flush()
+    return provider
+
+
+async def register_model(
+    db: AsyncSession,
+    *,
+    tenant_id: uuid.UUID,
+    provider: AiProvider,
+    key: str,
+    registry_key: str,
+    data_leaves_infrastructure: bool,
+    declared_by_login: str,
+    label: str | None = None,
+    declaration_note: str | None = None,
+    cost_input_per_1k: float | None = None,
+    cost_output_per_1k: float | None = None,
+    cost_currency: str | None = None,
+    timeout_seconds: int | None = None,
+    registry: ModelRegistry | None = None,
+) -> AiModel:
+    """Enregistre un modèle **avec la déclaration de sortie de données**.
+
+    `data_leaves_infrastructure` est un argument obligatoire et sans valeur
+    par défaut : l'appelant ne peut pas l'oublier. C'est une déclaration
+    d'administrateur, datée et attribuée — le CMS ne l'infère pas, ne la
+    teste pas et ne la corrige pas, parce qu'un point d'accès « custom » sur
+    le réseau interne peut être un proxy vers un tiers et que rien dans une
+    requête HTTP ne permet de l'exclure.
+    """
+    registry = registry or default_registry()
+    errors: list[str] = []
+    entry = registry.model(registry_key)
+    if entry is None:
+        raise AiConfigurationError(
+            [
+                f"modèle '{registry_key}' inconnu du catalogue : sans entrée, ni le "
+                "nom de runtime ni le protocole ne sont connus"
+            ]
+        )
+    if entry.provider != provider.registry_key:
+        errors.append(
+            f"le modèle '{registry_key}' appartient au fournisseur "
+            f"'{entry.provider}', pas à '{provider.registry_key}'"
+        )
+    if provider.tenant_id != tenant_id:
+        errors.append("le fournisseur désigné appartient à un autre tenant")
+    if provider.hosting == HOSTING_THIRD_PARTY and not data_leaves_infrastructure:
+        errors.append(
+            f"le point d'accès '{provider.key}' est déclaré tiers : un modèle qu'il "
+            "sert ne peut pas être déclaré comme gardant les données dans "
+            "l'infrastructure"
+        )
+    provider_entry = registry.provider(provider.registry_key)
+    hint = provider_entry.hosting_hint if provider_entry is not None else "unknown"
+    if hint == "third_party" and not data_leaves_infrastructure and not declaration_note:
+        errors.append(
+            f"le catalogue indique '{provider.registry_key}' comme tiers et la "
+            "déclaration dit le contraire : cette contradiction doit être justifiée "
+            "par écrit (declaration_note) — le CMS ne peut pas la vérifier, il exige "
+            "qu'elle soit assumée"
+        )
+    if not declared_by_login:
+        errors.append(
+            "une déclaration de sortie de données doit nommer son auteur : c'est un "
+            "engagement, pas une case à cocher"
+        )
+    if errors:
+        raise AiConfigurationError(errors)
+
+    model = AiModel(
+        tenant_id=tenant_id,
+        provider_id=provider.id,
+        key=key,
+        registry_key=registry_key,
+        label=label or entry.label,
+        capability=entry.capability,
+        hosting=provider.hosting,
+        data_leaves_infrastructure=data_leaves_infrastructure,
+        declared_by_login=declared_by_login,
+        declaration_note=declaration_note,
+        embedding_dimensions=registry.embedding_dimensions(registry_key),
+        # `Decimal` et non `float` : un tarif est une somme d'argent, et la
+        # colonne est un `NUMERIC`. Convertir depuis la chaîne évite
+        # d'inscrire en base l'approximation binaire d'un flottant.
+        cost_input_per_1k=_tarif(cost_input_per_1k),
+        cost_output_per_1k=_tarif(cost_output_per_1k),
+        cost_currency=cost_currency,
+        timeout_seconds=timeout_seconds,
+    )
+    db.add(model)
+    await db.flush()
+    return model
+
+
+async def set_policy(
+    db: AsyncSession,
+    *,
+    tenant_id: uuid.UUID,
+    task_key: str,
+    capability: ModelCapability,
+    updated_by_login: str,
+    model: AiModel | None = None,
+    fallback: AiModel | None = None,
+    site_id: uuid.UUID | None = None,
+    output_regime: OutputRegime | None = None,
+    allow_personal_data: bool = False,
+    allow_data_leaving: bool = False,
+    timeout_seconds: int | None = None,
+    max_attempts: int = 2,
+    enabled: bool = True,
+) -> AiPolicy:
+    """Pose (ou remplace) la politique d'une tâche, pour un tenant ou un site.
+
+    Le régime de sortie est **plafonné par le Core** : `effective_regime`
+    retient toujours le plus exigeant entre ce que le CDC impose à la tâche
+    et ce que le tenant demande. Un tenant peut donc exiger une validation
+    humaine là où le Core ne l'exigeait pas ; il ne peut pas la retirer.
+    """
+    errors: list[str] = []
+    if model is not None:
+        if model.tenant_id != tenant_id:
+            errors.append("le modèle désigné appartient à un autre tenant")
+        if model.capability != capability:
+            errors.append(
+                f"le modèle '{model.key}' sert la capacité '{model.capability}', la "
+                f"politique porte '{capability}'"
+            )
+    if fallback is not None:
+        if fallback.tenant_id != tenant_id:
+            errors.append("le modèle de repli appartient à un autre tenant")
+        if fallback.capability != capability:
+            errors.append(
+                f"le repli '{fallback.key}' sert la capacité '{fallback.capability}', "
+                f"la politique porte '{capability}'"
+            )
+    if not updated_by_login:
+        errors.append("une politique IA doit nommer qui l'a posée")
+    if errors:
+        raise AiConfigurationError(errors)
+
+    # Garde-fou ADR-0004 : désigner un autre modèle d'embedding est une
+    # migration. Le refus est opposé **avant** l'écriture de la politique,
+    # sinon la configuration serait acceptée et la première indexation
+    # échouerait chez quelqu'un d'autre, plus tard.
+    if capability == "embedding" and model is not None:
+        dimensions = model.embedding_dimensions
+        if dimensions is None:
+            raise AiConfigurationError(
+                [
+                    f"le modèle '{model.key}' ne déclare aucune dimension "
+                    "d'embedding : il ne peut pas porter une politique de "
+                    "vectorisation"
+                ]
+            )
+        try:
+            await assert_embedding_model_allowed(
+                db, tenant_id=tenant_id, model_key=model.key, dimensions=dimensions
+            )
+        except EmbeddingModelChangeRefused as exc:
+            raise AiConfigurationError([str(exc)]) from exc
+
+    regime = effective_regime(task_key, capability, output_regime)
+    stmt = select(AiPolicy).where(
+        AiPolicy.tenant_id == tenant_id,
+        AiPolicy.task_key == task_key,
+    )
+    stmt = (
+        stmt.where(AiPolicy.site_id.is_(None))
+        if site_id is None
+        else stmt.where(AiPolicy.site_id == site_id)
+    )
+    policy = (await db.execute(stmt)).scalar_one_or_none()
+    if policy is None:
+        policy = AiPolicy(tenant_id=tenant_id, site_id=site_id, task_key=task_key)
+        db.add(policy)
+    policy.capability = capability
+    policy.model_id = model.id if model is not None else None
+    policy.fallback_model_id = fallback.id if fallback is not None else None
+    policy.output_regime = regime
+    policy.allow_personal_data = allow_personal_data
+    policy.allow_data_leaving = allow_data_leaving
+    policy.enabled = enabled
+    policy.timeout_seconds = timeout_seconds
+    policy.max_attempts = max(1, max_attempts)
+    policy.updated_by_login = updated_by_login
+    # `degrade` est la seule valeur acceptée par la base : aucune politique
+    # ne peut rendre un échec IA bloquant pour le Core (CDC §14.4).
+    policy.on_failure = "degrade"
+    await db.flush()
+    return policy
+
+
+__all__ = [
+    "HOSTING_SELF",
+    "HOSTING_THIRD_PARTY",
+    "AiConfigurationError",
+    "register_model",
+    "register_provider",
+    "set_policy",
+]

app/ai/breaker.py

@@ -0,0 +1,84 @@
+"""Disjoncteur par modèle — Epic E8 (CDC §14.1, §14.4).
+
+**Ce que le disjoncteur protège, ce n'est pas le fournisseur : c'est le
+CMS.** Quand un point d'accès ne répond plus, chaque appel coûte le délai
+d'attente complet avant d'échouer. Sans disjoncteur, une page qui propose
+trois textes alternatifs met trois fois ce délai à s'afficher — pour finir
+par ne rien proposer de toute façon. Après quelques échecs consécutifs, on
+cesse d'essayer : la fonctionnalité disparaît **immédiatement** de l'écran,
+et c'est exactement ce que `on_failure: degrade` promet.
+
+**En mémoire de processus, et c'est un choix.** Un disjoncteur partagé
+(Redis) donnerait une vue commune à tous les travailleurs — au prix d'une
+dépendance de plus sur le chemin d'un appel IA, et d'une question
+désagréable : que fait le CMS quand le magasin du disjoncteur est lui-même
+indisponible ? Ici, chaque processus constate la panne pour son compte,
+au pire une fois par travailleur, et rien de tout cela ne peut empêcher le
+Core de fonctionner. La perte d'information à un redémarrage est sans
+conséquence : le premier appel rouvrira le circuit ou le refermera.
+
+**La clé est `(tenant, modèle)`, jamais le seul modèle.** Deux
+collectivités peuvent employer le même modèle chez deux fournisseurs
+différents — ou le même fournisseur avec des quotas différents. Faire
+tomber la fonction de l'une parce que le compte de l'autre est épuisé
+aurait été une fuite d'état entre tenants, de la même famille que celles
+qu'E6 et E7 refusent ailleurs.
+"""
+
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _State:
+    failures: int = 0
+    opened_at: float | None = None
+
+
+@dataclass
+class CircuitBreaker:
+    """Compte les échecs consécutifs et ouvre le circuit au-delà du seuil."""
+
+    failure_threshold: int = 3
+    reset_after_seconds: float = 60.0
+    # Source de temps injectable : un test de disjoncteur qui attendrait
+    # soixante secondes ne serait pas exécuté, donc pas fiable.
+    time_source: Callable[[], float] = time.monotonic
+    _states: dict[tuple[uuid.UUID, str], _State] = field(default_factory=dict)
+
+    def _now(self) -> float:
+        return float(self.time_source())
+
+    def is_open(self, tenant_id: uuid.UUID, model_key: str) -> bool:
+        """Le circuit est-il ouvert *maintenant* ?
+
+        Referme de lui-même après `reset_after_seconds` : un fournisseur
+        rétabli ne doit pas rester coupé jusqu'à un redémarrage, sans quoi le
+        disjoncteur deviendrait une panne à son tour.
+        """
+        state = self._states.get((tenant_id, model_key))
+        if state is None or state.opened_at is None:
+            return False
+        if self._now() - state.opened_at >= self.reset_after_seconds:
+            self._states.pop((tenant_id, model_key), None)
+            return False
+        return True
+
+    def record_failure(self, tenant_id: uuid.UUID, model_key: str) -> None:
+        state = self._states.setdefault((tenant_id, model_key), _State())
+        state.failures += 1
+        if state.failures >= self.failure_threshold and state.opened_at is None:
+            state.opened_at = self._now()
+
+    def record_success(self, tenant_id: uuid.UUID, model_key: str) -> None:
+        """Un succès efface le compteur : ce sont les échecs *consécutifs*
+        qui signalent une panne, pas un total cumulé depuis le démarrage."""
+        self._states.pop((tenant_id, model_key), None)
+
+    def reset(self) -> None:
+        self._states.clear()
+
+
+__all__ = ["CircuitBreaker"]

app/ai/capabilities.py

@@ -0,0 +1,101 @@
+"""Capacités typées du Model Registry — Epic E8 (CDC §14.1, §14.2).
+
+**Cinq capacités, pas une interface fourre-tout.** Le CDC nomme
+`LLM · Embedding · Vision · OCR · STT` et le fait exprès : ces cinq
+traitements n'ont ni les mêmes entrées, ni les mêmes sorties, ni les mêmes
+unités de coût, ni les mêmes conséquences en cas de panne. Une interface
+unique `AIProvider.call(payload) -> payload` aurait rendu ces différences
+invisibles au typage, donc reportées à l'exécution : un modèle d'embedding
+appelé pour rédiger un texte alternatif n'aurait échoué qu'au moment de
+l'appel, chez un fournisseur, avec des données déjà sorties. Ici, chaque
+capacité a son port (`app/ai/ports.py`) et sa paire requête/résultat.
+
+**Deux vocabulaires existent déjà, et il fallait les raccorder plutôt que
+les faire coexister.** L'Epic E7 a figé, dans `app/plugins/manifest.py`, un
+vocabulaire *fermé* de ce qu'un plugin peut demander — `text_generation`,
+`embedding`, `vision`, `transcription`, `classification` — en écrivant
+explicitement que la liste « s'étendra avec E8, de façon additive ». Le
+présent module ne crée donc pas un second vocabulaire concurrent : il pose
+les capacités **techniques** d'un modèle et déclare, dans
+`PLUGIN_CAPABILITY_TO_MODEL_CAPABILITY`, la correspondance vers celles-ci.
+Les deux listes ne se recouvrent pas à moitié, elles se traduisent
+entièrement — et un test de recette vérifie mécaniquement que **toute**
+capacité déclarable par un plugin a une traduction.
+
+Deux points de cette correspondance méritent d'être dits plutôt que subis :
+
+- `classification` → `llm`. Classer une demande de saisine dans une famille
+  de service, c'est demander à un modèle de langue de choisir une étiquette.
+  Inventer une capacité `classifier` distincte aurait supposé des modèles
+  dédiés que le registre n'a aucune raison de distinguer aujourd'hui.
+- `transcription` → `stt`. Même traitement, deux noms : celui du CDC pour le
+  registre, celui d'E7 pour ce qu'un plugin déclare. La traduction est ici,
+  en un seul endroit.
+
+**`ocr` est ajouté au vocabulaire d'E7 par cet Epic**, exactement comme E7
+l'avait prévu : l'extraction documentaire est nommée par le CDC §14.9 comme
+une fonction de priorité 1, et sans capacité `ocr` déclarable, un plugin
+d'extraction n'aurait pas eu de mot pour dire ce qu'il fait — il aurait
+déclaré `vision`, c'est-à-dire autre chose.
+
+**Le type `AiCapability` n'est importé qu'à la vérification de types, pas à
+l'exécution.** Deux raisons, dans cet ordre. La première est un sens de
+dépendance : le socle IA ne doit pas dépendre du Plugin SDK — c'est le SDK
+qui s'adresse au socle (`app/plugins/ai.py`), jamais l'inverse. La seconde
+est mécanique : `app.plugins` importe `app.plugins.ai`, qui importe le
+Provider Manager, qui passe par ce module ; un import d'exécution refermerait
+la boucle et rendrait l'ordre des imports significatif. Le prix à payer
+serait que les deux vocabulaires puissent diverger sans que rien ne le
+signale — c'est pourquoi un test de recette compare mécaniquement les clés de
+`PLUGIN_CAPABILITY_TO_MODEL_CAPABILITY` à `get_args(AiCapability)`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, get_args
+
+if TYPE_CHECKING:  # pragma: no cover - cf. docstring de module
+    from app.plugins.manifest import AiCapability
+
+# Ce qu'un **modèle** sait faire. Vocabulaire du CDC §14.2, fermé : le
+# Provider Manager route une capacité vers un port typé, et une chaîne libre
+# ne se route nulle part.
+ModelCapability = Literal["llm", "embedding", "vision", "ocr", "stt"]
+
+ALL_MODEL_CAPABILITIES: tuple[ModelCapability, ...] = get_args(ModelCapability)
+
+# La traduction, en un seul endroit (cf. docstring de module).
+PLUGIN_CAPABILITY_TO_MODEL_CAPABILITY: dict[AiCapability, ModelCapability] = {
+    "text_generation": "llm",
+    "classification": "llm",
+    "embedding": "embedding",
+    "vision": "vision",
+    "ocr": "ocr",
+    "transcription": "stt",
+}
+
+# Les capacités dont la sortie est **structurelle** et non éditoriale : un
+# vecteur ou un texte extrait d'un document ne se « valide » pas, il se
+# recalcule. Elles relèvent du régime `none` (cf. `app/ai/tasks.py`), et
+# c'est la seule raison pour laquelle cette liste existe ici : le régime de
+# sortie par défaut d'une tâche inconnue en dépend.
+STRUCTURAL_CAPABILITIES: frozenset[ModelCapability] = frozenset({"embedding", "ocr"})
+
+
+def model_capability_for_plugin(capability: AiCapability) -> ModelCapability:
+    """Traduit une capacité déclarée par un plugin (E7) en capacité de modèle.
+
+    Lève `KeyError` sur une capacité inconnue plutôt que de retomber sur
+    `llm` : une capacité ajoutée à E7 et oubliée ici doit se voir, pas se
+    faire router au hasard vers un modèle de langue.
+    """
+    return PLUGIN_CAPABILITY_TO_MODEL_CAPABILITY[capability]
+
+
+__all__ = [
+    "ALL_MODEL_CAPABILITIES",
+    "PLUGIN_CAPABILITY_TO_MODEL_CAPABILITY",
+    "STRUCTURAL_CAPABILITIES",
+    "ModelCapability",
+    "model_capability_for_plugin",
+]