feat(interpretation-in-map): judge a customer interpretation within the map (step 5)

Thin adapter — it judges the customer's reading WITHIN the already-built RegulatoryMap, it does not assess abstract legal questions and it is not RCI. - Reuses the existing assess_interpretation (no new legal reasoning); the 6 verdicts (plausible/too_narrow/too_broad/partially_correct/unsupported/uncertain) pass through unchanged. - Restricts affected_regulations/affected_obligations to those present in the map (intersection); links to the map's uncertain regulations. - Touched unsupported domains (wastewater/chemicals/...) are reported as future_corpus_domains (future_corpus_needed) — never pseudo-evaluated. - Customer-readable explanation ("Ihre Interpretation ist wahrscheinlich zu eng. … Betroffen in Ihrer Map: CRA."). - POST /reasoning/interpretation-in-map (renders the map, then interprets). - 7 tests; 63 green (existing reasoning MVP stays green), mypy clean, LOC ok. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-26 10:58:00 +02:00
parent 9312ad18ef
commit 50ae9e94d1
5 changed files with 297 additions and 0 deletions
@@ -9,12 +9,18 @@ pure deterministic rule evaluation.
    POST /reasoning/interpretation-assessment  -> verdict on a customer interpretation
    POST /reasoning/product-scope              -> gate on facts, else run discover_scope once
    POST /reasoning/regulatory-map             -> customer-readable read-model over the scope
+    POST /reasoning/interpretation-in-map      -> judge a customer interpretation within the map
 """

 from __future__ import annotations

 from fastapi import APIRouter

+from compliance.interpretation_map import (
+    InterpretationInMapRequest,
+    InterpretationInMapResult,
+    interpret_in_map,
+)
 from compliance.product_scope import (
    ProductScopeRequest,
    ProductScopeResponse,
@@ -71,6 +77,12 @@ def regulatory_map(req: RegulatoryMapRequest) -> RegulatoryMap:
    return render_regulatory_map(req.product_profile)


+@router.post("/interpretation-in-map", response_model=InterpretationInMapResult)
+def interpretation_in_map(req: InterpretationInMapRequest) -> InterpretationInMapResult:
+    reg_map = render_regulatory_map(req.product_profile)
+    return interpret_in_map(reg_map, req.customer_interpretation)
+
+
@router.post("/interpretation-assessment", response_model=InterpretationResponse)
 def interpretation_assessment(req: InterpretationRequest) -> InterpretationResponse:
    result = assess_interpretation(req.customer_interpretation, req.product_profile)
@@ -0,0 +1,18 @@
+"""Interpretation-in-Map — evaluate a customer interpretation within the map.
+
+Thin adapter over the existing `assess_interpretation`: it judges the customer's
+reading against the regulations/obligations actually present in the product's
+RegulatoryMap, and flags touched unsupported domains as future_corpus_needed
+instead of pseudo-evaluating them. No new legal reasoning, no RCI, no UI.
+"""
+
+from __future__ import annotations
+
+from .adapter import interpret_in_map
+from .schemas import InterpretationInMapRequest, InterpretationInMapResult
+
+__all__ = [
+    "interpret_in_map",
+    "InterpretationInMapRequest",
+    "InterpretationInMapResult",
+]
@@ -0,0 +1,90 @@
+"""Interpretation-in-Map adapter (step 5).
+
+Evaluates a customer interpretation WITHIN the already-built RegulatoryMap. It
+reuses the existing `assess_interpretation` (no new legal engine), restricts the
+affected regulations/obligations to those present in the map, and reports any
+touched unsupported domain (wastewater/chemicals/...) as future_corpus_needed
+rather than pseudo-evaluating it.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from compliance.reasoning.enums import InterpretationVerdict
+from compliance.reasoning.interpretation_engine import assess_interpretation
+from compliance.regulatory_map.schemas import RegulatoryMap
+
+from .schemas import InterpretationInMapResult
+
+_LABEL: Dict[InterpretationVerdict, str] = {
+    InterpretationVerdict.PLAUSIBLE: "plausibel",
+    InterpretationVerdict.TOO_NARROW: "zu eng",
+    InterpretationVerdict.TOO_BROAD: "zu weit",
+    InterpretationVerdict.PARTIALLY_CORRECT: "teilweise korrekt",
+    InterpretationVerdict.UNSUPPORTED: "nicht belegt",
+    InterpretationVerdict.UNCERTAIN: "unsicher",
+}
+
+# domain -> keywords that signal the interpretation is ABOUT that (uncovered) domain.
+_ENV_KEYWORDS: Dict[str, List[str]] = {
+    "environment_water": ["abwasser", "wastewater", "gewässer", "gewaesser", "einleitung", "abfluss"],
+    "chemicals": ["chemikalie", "reach", "clp", "reinigungsmittel", "biozid", "gefahrstoff", "detergenz", "lösemittel", "loesemittel"],
+    "environment_air": ["luft", "emission", "voc", "immission", "abluft", "verbrennung"],
+    "waste": ["abfall", "entsorgung", "weee", "recycling"],
+    "energy_resources": ["energie", "ökodesign", "oekodesign", "verbrauch"],
+}
+
+
+def _touches(text: str, domain: str) -> bool:
+    low = text.lower()
+    return any(kw in low for kw in _ENV_KEYWORDS.get(domain, []))
+
+
+def _explain(label: str, detail: str, affected_regs: List[str], future_domains: List[str], in_scope: bool) -> str:
+    base = "Ihre Interpretation ist wahrscheinlich %s." % label
+    if detail:
+        base += " " + detail
+    if affected_regs:
+        base += " Betroffen in Ihrer Map: %s." % ", ".join(affected_regs)
+    if future_domains:
+        base += (
+            " Für %s liegt noch kein Regelkorpus vor — diese Aspekte werden nicht bewertet (future_corpus_needed)."
+            % ", ".join(future_domains)
+        )
+    if not in_scope and not future_domains:
+        base += " Diese Auslegung betrifft kein Regelwerk Ihrer aktuellen Produkt-Map."
+    return base
+
+
+def interpret_in_map(reg_map: RegulatoryMap, interpretation: str) -> InterpretationInMapResult:
+    a = assess_interpretation(interpretation)  # existing engine — no new reasoning
+
+    map_reg_ids = (
+        {v.regulation_id for v in reg_map.applicable_regulations}
+        | {v.regulation_id for v in reg_map.uncertain_regulations}
+        | {v.regulation_id for v in reg_map.excluded_regulations}
+    )
+    map_ob_ids = {o.obligation_id for v in reg_map.applicable_regulations for o in v.obligations}
+    uncertain_ids = {v.regulation_id for v in reg_map.uncertain_regulations}
+
+    affected_regs = [r for r in a.affected_regulations if r in map_reg_ids]
+    affected_obs = [o for o in a.affected_obligations if o in map_ob_ids]
+    related_unc = [r for r in a.affected_regulations if r in uncertain_ids]
+    future = [d for d in reg_map.unsupported_domains if _touches(interpretation, d.domain)]
+    in_scope = bool(affected_regs or affected_obs)
+
+    return InterpretationInMapResult(
+        raw_interpretation=interpretation,
+        assessment=a.assessment,
+        in_scope_of_map=in_scope,
+        affected_regulations=affected_regs,
+        affected_obligations=affected_obs,
+        related_uncertainties=related_unc,
+        future_corpus_domains=future,
+        corrected_interpretation=a.corrected_interpretation,
+        risks=a.risks,
+        legal_basis_refs=a.legal_basis_refs,
+        explanation=_explain(_LABEL[a.assessment], a.explanation, affected_regs, [d.domain for d in future], in_scope),
+        confidence=a.confidence,
+    )
@@ -0,0 +1,36 @@
+"""Schemas for Interpretation-in-Map (step 5).
+
+A thin adapter that evaluates a customer interpretation WITHIN the already-built
+RegulatoryMap — it does not assess abstract legal questions. Application types
+only; no compliance-meta-model classes (freeze v1.0 untouched).
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+from compliance.product_scope.schemas import UnsupportedDomain
+from compliance.profile.canonical import CanonicalProductRegulatoryProfile
+from compliance.reasoning.enums import Confidence, InterpretationVerdict
+
+
+class InterpretationInMapRequest(BaseModel):
+    product_profile: CanonicalProductRegulatoryProfile
+    customer_interpretation: str
+
+
+class InterpretationInMapResult(BaseModel):
+    raw_interpretation: str
+    assessment: InterpretationVerdict
+    in_scope_of_map: bool  # True if it touches a regulation/obligation present in the map
+    affected_regulations: List[str] = Field(default_factory=list)  # intersected with the map
+    affected_obligations: List[str] = Field(default_factory=list)  # intersected (registry-linked)
+    related_uncertainties: List[str] = Field(default_factory=list)  # map-uncertain regs it touches
+    future_corpus_domains: List[UnsupportedDomain] = Field(default_factory=list)  # NOT evaluated
+    corrected_interpretation: str = ""
+    risks: List[str] = Field(default_factory=list)
+    legal_basis_refs: List[str] = Field(default_factory=list)
+    explanation: str = ""
+    confidence: Confidence = Confidence.MEDIUM