rag-wright 0.1.0__py3-none-any.whl

rag_wright/ontology/clause_template.py

@@ -0,0 +1,964 @@
+"""
+Closed-vocab bridge: FOLIO clause types + ODRL rights/duties + PROV-O provenance.
+
+Key entities:
+- Clause (root): One operative contract clause.
+- Jurisdiction: The governing-law jurisdiction(s): the name plus whether one or multiple laws govern.
+
+Key relationships:
+- Clause --BOUNDED_BY--> TemporalConstraint
+- Clause --HAS_CAPS--> CapConstraint
+- Clause --GOVERNED_BY--> Jurisdiction
+
+Generated by docling-graph template generation from src/rag_wright/ontology/contract_bridge.ttl.
+
+AUTHORITATIVE ARTIFACT — do NOT blindly regenerate (ADR-0037). This file was generated ONCE as a bootstrap and
+is now HAND-MAINTAINED. It carries load-bearing EXTRACTION-PROMPT ENGINEERING that the ontology/spec cannot
+express and that regeneration would clobber: the LLM-guiding field descriptions, brevity instructions, `examples`,
+`max_length` guards, and the `_normalize_enum` validators. It may also DEVIATE from the ontology for extraction
+reasons (see `document_reference` below). The `.ttl`/spec are the ontology (domain) source of truth and the
+one-time bootstrap; this `.py` is the source of truth for the extraction template. If you must regenerate,
+regenerate to a scratch file and hand-port every refinement here.
+"""
+
+import logging
+import re
+from enum import Enum
+from typing import Any, List, Optional, Type
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from typing_extensions import Self
+
+from rag_wright.ontology._generated_template_meta import DESCRIPTIONS, EXAMPLES
+
+logger = logging.getLogger(__name__)
+
+
+def _d(key: str) -> str:
+    """ADR-0066 P1b-2 (Rule 3): the field's LOOK-FOR description, GENERATED from the ttl (empty string if the ttl
+    has no definition for it -- the 10 TODO gaps, filled later in P1b-3). Edit the ttl, not this file."""
+    return DESCRIPTIONS.get(key, "")
+
+
+def _ex(key: str) -> list[str]:
+    """ADR-0066 P1b-2 (Rule 3): the field's examples, GENERATED from the ttl."""
+    return list(EXAMPLES.get(key, ()))
+
+
+# -----------------------------------------------------------------------------
+# Docling Graph edge helper
+# -----------------------------------------------------------------------------
+def edge(
+    label: str,
+    default: Any = None,
+    *,
+    reference: bool = False,
+    closed_catalog: bool = False,
+    **kwargs: Any,
+) -> Any:
+    """
+    Declare a field as a graph edge for Docling-Graph via json_schema_extra.
+
+    ``reference=True`` marks an identity-ONLY link (graph_reference): the field
+    carries id-only references to entities described in full elsewhere in the
+    schema. In dense extraction these references are filled by the PARENT's own
+    fill call (never discovered separately), which preserves per-parent
+    membership lists and avoids phantom parents.
+
+    ``closed_catalog=True`` (reference_closed_catalog) declares that the targets
+    form a CLOSED catalog defined elsewhere in the document: a target that only
+    exists through this field (never instantiated or referenced otherwise) is a
+    hallucinated member — the converter then drops the edge (and the orphaned
+    target), unless that would wipe more than half of the target class.
+    """
+    json_schema_extra = dict(kwargs.pop("json_schema_extra", {}) or {})
+    json_schema_extra["edge_label"] = label
+    if reference:
+        json_schema_extra["graph_reference"] = True
+    if closed_catalog:
+        json_schema_extra["reference_closed_catalog"] = True
+
+    if "default_factory" in kwargs:
+        default_factory = kwargs.pop("default_factory")
+        return Field(default_factory=default_factory, json_schema_extra=json_schema_extra, **kwargs)
+
+    return Field(default, json_schema_extra=json_schema_extra, **kwargs)
+
+
+# -----------------------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------------------
+_KEYWORD_MIN_LEN = 5  # issue 0033: a value token must be this long to be matched as a substring (avoid noise)
+
+
+def _match_enum_keyword(enum_cls: Type[Enum], key: str) -> Any:
+    """issue 0033: a keyword fallback for a value-bearing LIST enum -- when the model echoed the clause
+    verbatim ("Except in respect of the Supplier's INDEMNIFICATION obligations...") instead of the canonical
+    token, map on the member VALUE appearing as a substring of the collapsed input. The LONGEST value wins (so
+    a specific value beats a prefix of it), OTHER is never a keyword, and short tokens (< 5 chars) are ignored
+    to avoid spurious hits. Returns the member or None (caller then falls back to OTHER)."""
+    best = None
+    best_len = 0
+    for member in enum_cls:
+        if member.name == "OTHER":
+            continue
+        token = re.sub(r"[^A-Za-z0-9]+", "", str(member.value)).lower()
+        if len(token) >= _KEYWORD_MIN_LEN and token in key and len(token) > best_len:
+            best, best_len = member, len(token)
+    return best
+
+
+def _normalize_enum(enum_cls: Type[Enum], v: Any, *, keyword_fallback: bool = False) -> Any:
+    """
+    Accept enum instances, value strings, or member names.
+    Handles various formats: 'VALUE', 'value', 'Value', 'VALUE_NAME'.
+    Falls back to the OTHER member instead of rejecting (never raises).
+
+    issue 0033: with `keyword_fallback=True` (the value-bearing LIST dims -- carve_out / covered_subject /
+    damage_type), an input that is not an exact match but CONTAINS a canonical value token maps to that value
+    before falling back to OTHER. This recovers the document-side case where the extractor quotes the clause
+    (e.g. an indemnification carve-out stated as a full "Except in respect of ..." phrase) instead of emitting
+    the bare token as it does on the short query side. These dims are lexically grounded (ADR-0028), so a
+    spurious keyword hit whose cue is absent from the text is still downgraded by the grounding gate.
+    """
+    if isinstance(v, enum_cls):
+        return v
+    if isinstance(v, str):
+        key = re.sub(r"[^A-Za-z0-9]+", "", v).lower()
+        mapping: dict[str, Any] = {}
+        for member in enum_cls:
+            mapping[re.sub(r"[^A-Za-z0-9]+", "", member.name).lower()] = member
+            mapping[re.sub(r"[^A-Za-z0-9]+", "", str(member.value)).lower()] = member
+        if key in mapping:
+            return mapping[key]
+        if keyword_fallback:
+            hit = _match_enum_keyword(enum_cls, key)
+            if hit is not None:
+                return hit
+    if "OTHER" in enum_cls.__members__:
+        logger.warning("Unmapped enum value %r for %s; falling back to OTHER", v, enum_cls.__name__)
+        return enum_cls.OTHER
+    return v
+
+
+_OPEN_LIST_MAX_CHARS = 120  # a subject/carve-out/damage value is a short phrase; longer = leaked prose -> dropped
+
+
+def _clean_open_list(v: Any) -> list[str]:
+    """issue 0037: capture the OPEN descriptive list-dims (covered_subject / carve_out / damage_type) VERBATIM
+    rather than collapsing out-of-vocab items to OTHER (which discarded them). Coerce an enum member to its value,
+    strip, drop empties / leaked prose (too long or containing an XML tag). Canonicalization onto the closed vocab
+    happens at the assertion boundary (`clause_kg_extractor`), which keeps the verbatim phrase when nothing matches."""
+    items = v if isinstance(v, list) else [v]
+    out: list[str] = []
+    for item in items:
+        s = (str(item.value) if isinstance(item, Enum) else str(item)).strip()
+        if s and len(s) <= _OPEN_LIST_MAX_CHARS and "<" not in s:
+            out.append(s)
+    return out
+
+
+# -----------------------------------------------------------------------------
+# Enums
+# -----------------------------------------------------------------------------
+class Subject(str, Enum):
+    """Controlled vocabulary for subject values. Unmapped values normalize to OTHER."""
+
+    IP_INFRINGEMENT = "ip_infringement"
+    TRADEMARK = "trademark"
+    COPYRIGHT = "copyright"
+    VIOLATION_OF_LAW = "violation_of_law"
+    FRAUD = "fraud"
+    GROSS_NEGLIGENCE = "gross_negligence"
+    OTHER = "Other"
+
+
+class PartyScope(str, Enum):
+    """Controlled vocabulary for party_scope values. Unmapped values normalize to OTHER."""
+
+    AFFILIATES = "affiliates"
+    LICENSOR_AFFILIATES = "licensor_affiliates"
+    LICENSEE_AFFILIATES = "licensee_affiliates"
+    OTHER = "Other"
+
+
+class ExceptionModel(str, Enum):
+    """Controlled vocabulary for exception_model values. Unmapped values normalize to OTHER."""
+
+    INDEMNIFICATION = "indemnification"
+    CONFIDENTIALITY = "confidentiality"
+    THIRD_PARTY_IP_INFRINGEMENT = "third_party_ip_infringement"
+    FRAUD = "fraud"
+    GROSS_NEGLIGENCE = "gross_negligence"
+    WILLFUL_MISCONDUCT = "willful_misconduct"
+    BODILY_INJURY = "bodily_injury"
+    APPLICABLE_LAW = "applicable_law"
+    OTHER = "Other"
+
+
+class AssignmentConsent(str, Enum):
+    """Controlled vocabulary for assignment_consent values. Unmapped values normalize to OTHER."""
+
+    CONSENT_REQUIRED = "consent_required"
+    NOTICE_ONLY = "notice_only"
+    FREE = "free"
+    OTHER = "Other"
+
+
+class Asymmetry(str, Enum):
+    """Controlled vocabulary for asymmetry values. Unmapped values normalize to OTHER."""
+
+    SYMMETRIC = "symmetric"
+    DIFFERENT_PER_PARTY = "different_per_party"
+    OTHER = "Other"
+
+
+class ClaimScope(str, Enum):
+    """Controlled vocabulary for claim_scope values. Unmapped values normalize to OTHER."""
+
+    FIRST_PARTY = "first_party"
+    THIRD_PARTY = "third_party"
+    BROAD_BASED = "broad_based"
+    OTHER = "Other"
+
+
+class CocConsent(str, Enum):
+    """Controlled vocabulary for coc_consent values. Unmapped values normalize to OTHER."""
+
+    CONSENT_REQUIRED = "consent_required"
+    NOTICE_ONLY = "notice_only"
+    UNRESTRICTED = "unrestricted"
+    OTHER = "Other"
+
+
+class EscrowReleaseTrigger(str, Enum):
+    """Controlled vocabulary for escrow_release_trigger values. Unmapped values normalize to OTHER."""
+
+    BANKRUPTCY = "bankruptcy"
+    BREACH = "breach"
+    DISCONTINUANCE = "discontinuance"
+    OTHER = "Other"
+
+
+class ExclusivityType(str, Enum):
+    """Controlled vocabulary for exclusivity_type values. Unmapped values normalize to OTHER."""
+
+    EXCLUSIVE = "exclusive"
+    SOLE = "sole"
+    NON_EXCLUSIVE = "non_exclusive"
+    OTHER = "Other"
+
+
+class Favorability(str, Enum):
+    """Controlled vocabulary for favorability values. Unmapped values normalize to OTHER."""
+
+    BUYER_FAVORABLE = "buyer_favorable"
+    SELLER_FAVORABLE = "seller_favorable"
+    OTHER = "Other"
+
+
+class IpOwnership(str, Enum):
+    """Controlled vocabulary for ip_ownership values. Unmapped values normalize to OTHER."""
+
+    ASSIGNED = "assigned"
+    JOINT = "joint"
+    RETAINED = "retained"
+    OTHER = "Other"
+
+
+class MfnScope(str, Enum):
+    """Controlled vocabulary for mfn_scope values. Unmapped values normalize to OTHER."""
+
+    PRICE = "price"
+    TERMS = "terms"
+    PRICE_AND_TERMS = "price_and_terms"
+    OTHER = "Other"
+
+
+class Mutuality(str, Enum):
+    """Controlled vocabulary for mutuality values. Unmapped values normalize to OTHER."""
+
+    MUTUAL = "mutual"
+    UNILATERAL = "unilateral"
+    OTHER = "Other"
+
+
+class RenewalMechanism(str, Enum):
+    """Controlled vocabulary for renewal_mechanism values. Unmapped values normalize to OTHER."""
+
+    AUTO = "auto"
+    REQUIRES_NOTICE = "requires_notice"
+    OTHER = "Other"
+
+
+class RestrictionScope(str, Enum):
+    """Controlled vocabulary for restriction_scope values. Unmapped values normalize to OTHER."""
+
+    GEOGRAPHIC = "geographic"
+    ACTIVITY = "activity"
+    GEOGRAPHIC_AND_ACTIVITY = "geographic_and_activity"
+    OTHER = "Other"
+
+
+class RightOfFirstType(str, Enum):
+    """Controlled vocabulary for right_of_first_type values. Unmapped values normalize to OTHER."""
+
+    ROFR = "rofr"
+    ROFO = "rofo"
+    ROFN = "rofn"
+    OTHER = "Other"
+
+
+class TerminationRight(str, Enum):
+    """Controlled vocabulary for termination_right values. Unmapped values normalize to OTHER."""
+
+    EITHER_PARTY = "either_party"
+    ONE_PARTY = "one_party"
+    OTHER = "Other"
+
+
+class WarrantyScope(str, Enum):
+    """Controlled vocabulary for warranty_scope values. Unmapped values normalize to OTHER."""
+
+    IMPLIED = "implied"
+    EXPRESS = "express"
+    AS_IS = "as_is"
+    NON_RELIANCE = "non_reliance"
+    OTHER = "Other"
+
+
+class DamageType(str, Enum):
+    """Controlled vocabulary for damage_type values. Unmapped values normalize to OTHER."""
+
+    INDIRECT = "indirect"
+    CONSEQUENTIAL = "consequential"
+    INCIDENTAL = "incidental"
+    PUNITIVE = "punitive"
+    SPECIAL = "special"
+    OTHER = "Other"
+
+
+class NonsolicitTarget(str, Enum):
+    """Controlled vocabulary for nonsolicit_target values. Unmapped values normalize to OTHER."""
+
+    EMPLOYEES = "employees"
+    CUSTOMERS = "customers"
+    OTHER = "Other"
+
+
+class ProceduralDuty(str, Enum):
+    """Controlled vocabulary for procedural_duty values. Unmapped values normalize to OTHER."""
+
+    DUTY_TO_DEFEND = "duty_to_defend"
+    CONTROL_OF_DEFENSE = "control_of_defense"
+    OTHER = "Other"
+
+
+class CapBasis(str, Enum):
+    """Controlled vocabulary for cap_basis values. Unmapped values normalize to OTHER."""
+
+    FIXED_FEE = "fixed_fee"
+    MULTIPLE_OF_FEES = "multiple_of_fees"
+    CAP_OTHER = "cap_other"
+    OTHER = "Other"
+
+
+class LawMultiplicity(str, Enum):
+    """Controlled vocabulary for law_multiplicity values. Unmapped values normalize to OTHER."""
+
+    SINGLE = "single"
+    MULTIPLE = "multiple"
+    OTHER = "Other"
+
+
+# -----------------------------------------------------------------------------
+# Components
+# -----------------------------------------------------------------------------
+class CapConstraint(BaseModel):
+    """
+    The liability cap: its basis plus the open quantum (e.g. '12 months of fees', '$1,000,000').
+    """
+
+    model_config = ConfigDict(is_entity=False)
+
+    cap_basis: CapBasis = Field(
+        CapBasis.OTHER,
+        description=_d("CapConstraint.cap_basis"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    cap_operator: Optional[str] = Field(
+        None,
+        max_length=40,
+        description=_d("CapConstraint.cap_operator"),
+    )
+
+    cap_quantum: Optional[str] = Field(
+        None,
+        max_length=160,  # ADR-0081 caps tightening: allow phrase-form caps ('the greater of X or Y', 'the fees paid ...')
+        description=_d("CapConstraint.cap_quantum"),
+    )
+
+    @field_validator("cap_basis", mode="before")
+    @classmethod
+    def _normalize_cap_basis(cls, v: Any) -> Any:
+        """Map free-text values onto CapBasis members (falls back to OTHER)."""
+        return _normalize_enum(CapBasis, v)
+
+    def __str__(self) -> str:
+        parts = [self.cap_operator, self.cap_quantum]
+        return " ".join(str(p) for p in parts if p) or "Unknown"
+
+
+class TemporalConstraint(BaseModel):
+    """A time bound on the clause: a term/duration or a notice period."""
+
+    model_config = ConfigDict(is_entity=False)
+
+    temporal_duration: Optional[str] = Field(
+        None,
+        max_length=60,
+        description=_d("TemporalConstraint.temporal_duration"),
+    )
+
+    temporal_kind: Optional[str] = Field(
+        None,
+        max_length=40,
+        description=_d("TemporalConstraint.temporal_kind"),
+    )
+
+    temporal_operator: Optional[str] = Field(
+        None,
+        max_length=40,
+        description=_d("TemporalConstraint.temporal_operator"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    def __str__(self) -> str:
+        parts = [self.temporal_duration, self.temporal_kind]
+        return " ".join(str(p) for p in parts if p) or "Unknown"
+
+
+# -----------------------------------------------------------------------------
+# Entities
+# -----------------------------------------------------------------------------
+class Jurisdiction(BaseModel):
+    """The governing-law jurisdiction(s): the name plus whether one or multiple laws govern."""
+
+    model_config = ConfigDict(graph_id_fields=["jurisdiction_name"])
+
+    jurisdiction_name: str = Field(
+        ...,
+        max_length=100,
+        description=_d("Jurisdiction.jurisdiction_name"),
+        examples=_ex("Jurisdiction.jurisdiction_name"),
+    )
+
+    law_multiplicity: LawMultiplicity = Field(
+        LawMultiplicity.OTHER,
+        description=_d("Jurisdiction.law_multiplicity"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    @field_validator("law_multiplicity", mode="before")
+    @classmethod
+    def _normalize_law_multiplicity(cls, v: Any) -> Any:
+        """Map free-text values onto LawMultiplicity members (falls back to OTHER)."""
+        return _normalize_enum(LawMultiplicity, v)
+
+    def __str__(self) -> str:
+        parts = [self.jurisdiction_name]
+        return " ".join(str(p) for p in parts if p) or "Unknown"
+
+
+class DisputeMethod(str, Enum):
+    """Controlled vocabulary for dispute_method values (ADR-0049 (2)). Unmapped values normalize to OTHER."""
+
+    ARBITRATION = "arbitration"
+    LITIGATION = "litigation"
+    MEDIATION = "mediation"
+    EXPERT_DETERMINATION = "expert_determination"
+    NEGOTIATION = "negotiation"
+    OTHER = "Other"
+
+
+class CollateralType(str, Enum):
+    """Controlled vocabulary for collateral_type values (ADR-0049 (2), UCC Article 9 aligned). Unmapped -> OTHER."""
+
+    ACCOUNTS_RECEIVABLE = "accounts_receivable"
+    INVENTORY = "inventory"
+    EQUIPMENT = "equipment"
+    FIXTURES = "fixtures"
+    IP = "ip"
+    REAL_PROPERTY = "real_property"
+    DEPOSIT_ACCOUNTS = "deposit_accounts"
+    GENERAL_INTANGIBLES = "general_intangibles"
+    ALL_ASSETS = "all_assets"
+    OTHER = "Other"
+
+
+class ForceMajeureEvent(str, Enum):
+    """Controlled vocabulary for force_majeure_event values (ADR-0049 (2)). Unmapped -> OTHER."""
+
+    ACT_OF_GOD = "act_of_god"
+    WAR = "war"
+    PANDEMIC = "pandemic"
+    GOVERNMENT_ACTION = "government_action"
+    LABOR_DISPUTE = "labor_dispute"
+    SUPPLY_FAILURE = "supply_failure"
+    NATURAL_DISASTER = "natural_disaster"
+    OTHER = "Other"
+
+
+class RoyaltyBasis(str, Enum):
+    """Controlled vocabulary for royalty_basis values (ADR-0049 (2)). Unmapped -> OTHER."""
+
+    PCT_NET_SALES = "pct_net_sales"
+    PCT_GROSS_SALES = "pct_gross_sales"
+    PER_UNIT = "per_unit"
+    FIXED = "fixed"
+    TIERED = "tiered"
+    OTHER = "Other"
+
+
+class ConfidentialityException(str, Enum):
+    """Controlled vocabulary for confidentiality_exception values (ADR-0049 (2), standard NDA carve-outs)."""
+
+    REQUIRED_BY_LAW = "required_by_law"
+    PUBLICLY_AVAILABLE = "publicly_available"
+    INDEPENDENTLY_DEVELOPED = "independently_developed"
+    PRIOR_POSSESSION = "prior_possession"
+    THIRD_PARTY_SOURCE = "third_party_source"
+    OTHER = "Other"
+
+
+class ConditionType(str, Enum):
+    """Controlled vocabulary for condition_type values (ADR-0049 (2), broadened via corpus check). Unmapped -> OTHER."""
+
+    REGULATORY_APPROVAL = "regulatory_approval"
+    FINANCING = "financing"
+    THIRD_PARTY_CONSENT = "third_party_consent"
+    DUE_DILIGENCE = "due_diligence"
+    BOARD_APPROVAL = "board_approval"
+    NO_MATERIAL_ADVERSE_CHANGE = "no_material_adverse_change"
+    COURT_APPROVAL = "court_approval"
+    CLOSING_CONDITION = "closing_condition"
+    OTHER = "Other"
+
+
+# -----------------------------------------------------------------------------
+# Root document
+# -----------------------------------------------------------------------------
+class Clause(BaseModel):
+    """
+    One operative contract clause. Its function/type is known from the classifier; this template
+    extracts the clause's typed properties, each read verbatim from the clause text.
+    """
+
+    model_config = ConfigDict(graph_id_fields=["document_reference"])
+
+    # DEVIATION from the ontology (ADR-0037): the domain says a clause HAS a reference (required), but the LLM
+    # cannot reliably extract one and, when forced, dumps a verbatim clause quote here -- ballooning the JSON
+    # past max_tokens and truncating the whole record (INGEST-REFACTOR). Since we DISCARD this field (clause
+    # identity is our deterministic chunk_id, not this), we make it Optional/null-permitted to stop the runaway.
+    document_reference: Optional[str] = Field(
+        None,
+        max_length=80,
+        description=(
+            _d("Clause.document_reference")
+        ),
+        examples=_ex("Clause.document_reference"),
+    )
+
+    audit_frequency: Optional[str] = Field(
+        None,
+        max_length=60,
+        description=(
+            _d("Clause.audit_frequency")
+        ),
+    )
+
+    clause_type: Optional[str] = Field(
+        None,
+        max_length=80,
+        description=(
+            _d("Clause.clause_type")
+        ),
+    )
+
+    collateral_type: List[CollateralType] = Field(
+        default_factory=list,
+        description=(
+            _d("Clause.collateral_type")
+        ),
+    )
+
+    commitment_quantum: Optional[str] = Field(
+        None,
+        max_length=80,
+        description=(
+            _d("Clause.commitment_quantum")
+        ),
+    )
+
+    condition_type: ConditionType = Field(
+        ConditionType.OTHER,
+        description=(
+            _d("Clause.condition_type")
+        ),
+    )
+
+    confidentiality_exception: List[ConfidentialityException] = Field(
+        default_factory=list,
+        description=(
+            _d("Clause.confidentiality_exception")
+        ),
+    )
+
+    force_majeure_event: List[ForceMajeureEvent] = Field(
+        default_factory=list,
+        description=(
+            _d("Clause.force_majeure_event")
+        ),
+    )
+
+    royalty_basis: RoyaltyBasis = Field(
+        RoyaltyBasis.OTHER,
+        description=(
+            _d("Clause.royalty_basis")
+        ),
+    )
+
+    covers: List[Subject] = Field(  # issue 0040: CLOSED conduct vocab (fraud/gross_negligence/...) -- NOT open;
+        default_factory=list,       # an out-of-vocab value ('API', a party name) is noise, dropped (not retained)
+        description=_d("Clause.covers"),
+    )
+
+    covers_party_scope: PartyScope = Field(
+        PartyScope.OTHER,
+        description=_d("Clause.covers_party_scope"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    dispute_method: DisputeMethod = Field(
+        DisputeMethod.OTHER,
+        description=(
+            _d("Clause.dispute_method")
+        ),
+    )
+
+    excepts: List[str] = Field(  # issue 0037: OPEN capture -- verbatim carve-outs; canonicalized at the KG boundary
+        default_factory=list,
+        description=_d("Clause.excepts"),
+    )
+
+    has_assignment_consent: AssignmentConsent = Field(
+        AssignmentConsent.OTHER,
+        description=_d("Clause.has_assignment_consent"),
+    )
+
+    has_asymmetry: Asymmetry = Field(
+        Asymmetry.OTHER,
+        description=_d("Clause.has_asymmetry"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    has_claim_scope: ClaimScope = Field(
+        ClaimScope.OTHER,
+        description=_d("Clause.has_claim_scope"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    has_coc_consent: CocConsent = Field(
+        CocConsent.OTHER,
+        description=(
+            _d("Clause.has_coc_consent")
+        ),
+    )
+
+    has_escrow_release_trigger: EscrowReleaseTrigger = Field(
+        EscrowReleaseTrigger.OTHER,
+        description=(
+            _d("Clause.has_escrow_release_trigger")
+        ),
+    )
+
+    has_exclusivity_type: ExclusivityType = Field(
+        ExclusivityType.OTHER,
+        description=(
+            _d("Clause.has_exclusivity_type")
+        ),
+    )
+
+    has_favorability: Favorability = Field(
+        Favorability.OTHER,
+        description=_d("Clause.has_favorability"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    has_ip_ownership: IpOwnership = Field(
+        IpOwnership.OTHER,
+        description=_d("Clause.has_ip_ownership"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    has_mfn_scope: MfnScope = Field(
+        MfnScope.OTHER,
+        description=_d("Clause.has_mfn_scope"),
+    )
+
+    has_mutuality: Mutuality = Field(
+        Mutuality.OTHER,
+        description=(
+            _d("Clause.has_mutuality")
+        ),
+    )
+
+    has_renewal: RenewalMechanism = Field(
+        RenewalMechanism.OTHER,
+        description=_d("Clause.has_renewal"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    has_restriction_scope: RestrictionScope = Field(
+        RestrictionScope.OTHER,
+        description=_d("Clause.has_restriction_scope"),
+    )
+
+    has_right_of_first_type: RightOfFirstType = Field(
+        RightOfFirstType.OTHER,
+        description=(
+            _d("Clause.has_right_of_first_type")
+        ),
+    )
+
+    has_termination_right: TerminationRight = Field(
+        TerminationRight.OTHER,
+        description=_d("Clause.has_termination_right"),
+    )
+
+    has_warranty_scope: WarrantyScope = Field(
+        WarrantyScope.OTHER,
+        description=_d("Clause.has_warranty_scope"),  # TODO(docling-graph): add a 1-3 sentence LOOK-FOR description
+    )
+
+    ld_trigger: Optional[str] = Field(
+        None,
+        description=_d("Clause.ld_trigger"),
+    )
+
+    prohibits_damage: List[str] = Field(  # issue 0037: OPEN capture -- verbatim; canonicalized at the KG boundary
+        default_factory=list,
+        description=_d("Clause.prohibits_damage"),
+    )
+
+    prohibits_solicit: NonsolicitTarget = Field(
+        NonsolicitTarget.OTHER,
+        description=_d("Clause.prohibits_solicit"),
+    )
+
+    requires_duty: ProceduralDuty = Field(
+        ProceduralDuty.OTHER,
+        description=_d("Clause.requires_duty"),
+    )
+
+    bounded_by: Optional[TemporalConstraint] = edge(
+        label="BOUNDED_BY",
+        description=_d("Clause.bounded_by"),
+    )
+
+    caps: Optional[CapConstraint] = edge(
+        label="HAS_CAPS",
+        description=_d("Clause.caps"),
+    )
+
+    governed_by: Optional[Jurisdiction] = edge(
+        label="GOVERNED_BY",
+        description=_d("Clause.governed_by"),
+    )
+
+    @field_validator("covers", mode="before")
+    @classmethod
+    def _normalize_covers(cls, v: Any) -> Any:
+        """issue 0040: `covered_subject` is a CLOSED conduct vocabulary (Subject: fraud / gross_negligence /
+        ip_infringement / ...), NOT an open descriptive dim like carve_out. Map each item onto a Subject member
+        (keyword fallback recovers a quoted conduct phrase); an out-of-vocab value -> OTHER, dropped downstream.
+        Reverts the 0037 verbatim-retention for THIS dim only: retaining 'API'/party-names as AMBIGUOUS filled it
+        with 99.7% noise (354:1) because 'what does this cover?' is asked of every provision. carve_out/damage_type
+        stay open (their tails are real)."""
+        if isinstance(v, list):
+            return [_normalize_enum(Subject, item, keyword_fallback=True) for item in v]
+        return _normalize_enum(Subject, v, keyword_fallback=True)
+
+    @field_validator("covers_party_scope", mode="before")
+    @classmethod
+    def _normalize_covers_party_scope(cls, v: Any) -> Any:
+        """Map free-text values onto PartyScope members (falls back to OTHER)."""
+        return _normalize_enum(PartyScope, v)
+
+    @field_validator("excepts", mode="before")
+    @classmethod
+    def _normalize_excepts(cls, v: Any) -> Any:
+        """issue 0037: capture carve-outs VERBATIM (open dim); canonicalized onto `ExceptionModel` at the KG
+        boundary, keeping the phrase when no vocab value matches (was: collapse to OTHER -> discarded)."""
+        return _clean_open_list(v)
+
+    @field_validator("has_assignment_consent", mode="before")
+    @classmethod
+    def _normalize_has_assignment_consent(cls, v: Any) -> Any:
+        """Map free-text values onto AssignmentConsent members (falls back to OTHER)."""
+        return _normalize_enum(AssignmentConsent, v)
+
+    @field_validator("has_asymmetry", mode="before")
+    @classmethod
+    def _normalize_has_asymmetry(cls, v: Any) -> Any:
+        """Map free-text values onto Asymmetry members (falls back to OTHER)."""
+        return _normalize_enum(Asymmetry, v)
+
+    @field_validator("has_claim_scope", mode="before")
+    @classmethod
+    def _normalize_has_claim_scope(cls, v: Any) -> Any:
+        """Map free-text values onto ClaimScope members (falls back to OTHER)."""
+        return _normalize_enum(ClaimScope, v)
+
+    @field_validator("has_coc_consent", mode="before")
+    @classmethod
+    def _normalize_has_coc_consent(cls, v: Any) -> Any:
+        """Map free-text values onto CocConsent members (falls back to OTHER)."""
+        return _normalize_enum(CocConsent, v)
+
+    @field_validator("has_escrow_release_trigger", mode="before")
+    @classmethod
+    def _normalize_has_escrow_release_trigger(cls, v: Any) -> Any:
+        """Map free-text values onto EscrowReleaseTrigger members (falls back to OTHER)."""
+        return _normalize_enum(EscrowReleaseTrigger, v)
+
+    @field_validator("has_exclusivity_type", mode="before")
+    @classmethod
+    def _normalize_has_exclusivity_type(cls, v: Any) -> Any:
+        """Map free-text values onto ExclusivityType members (falls back to OTHER)."""
+        return _normalize_enum(ExclusivityType, v)
+
+    @field_validator("has_favorability", mode="before")
+    @classmethod
+    def _normalize_has_favorability(cls, v: Any) -> Any:
+        """Map free-text values onto Favorability members (falls back to OTHER)."""
+        return _normalize_enum(Favorability, v)
+
+    @field_validator("has_ip_ownership", mode="before")
+    @classmethod
+    def _normalize_has_ip_ownership(cls, v: Any) -> Any:
+        """Map free-text values onto IpOwnership members (falls back to OTHER)."""
+        return _normalize_enum(IpOwnership, v)
+
+    @field_validator("has_mfn_scope", mode="before")
+    @classmethod
+    def _normalize_has_mfn_scope(cls, v: Any) -> Any:
+        """Map free-text values onto MfnScope members (falls back to OTHER)."""
+        return _normalize_enum(MfnScope, v)
+
+    @field_validator("has_mutuality", mode="before")
+    @classmethod
+    def _normalize_has_mutuality(cls, v: Any) -> Any:
+        """Map free-text values onto Mutuality members (falls back to OTHER)."""
+        return _normalize_enum(Mutuality, v)
+
+    @field_validator("has_renewal", mode="before")
+    @classmethod
+    def _normalize_has_renewal(cls, v: Any) -> Any:
+        """Map free-text values onto RenewalMechanism members (falls back to OTHER)."""
+        return _normalize_enum(RenewalMechanism, v)
+
+    @field_validator("has_restriction_scope", mode="before")
+    @classmethod
+    def _normalize_has_restriction_scope(cls, v: Any) -> Any:
+        """Map free-text values onto RestrictionScope members (falls back to OTHER)."""
+        return _normalize_enum(RestrictionScope, v)
+
+    @field_validator("has_right_of_first_type", mode="before")
+    @classmethod
+    def _normalize_has_right_of_first_type(cls, v: Any) -> Any:
+        """Map free-text values onto RightOfFirstType members (falls back to OTHER)."""
+        return _normalize_enum(RightOfFirstType, v)
+
+    @field_validator("has_termination_right", mode="before")
+    @classmethod
+    def _normalize_has_termination_right(cls, v: Any) -> Any:
+        """Map free-text values onto TerminationRight members (falls back to OTHER)."""
+        return _normalize_enum(TerminationRight, v)
+
+    @field_validator("has_warranty_scope", mode="before")
+    @classmethod
+    def _normalize_has_warranty_scope(cls, v: Any) -> Any:
+        """Map free-text values onto WarrantyScope members (falls back to OTHER)."""
+        return _normalize_enum(WarrantyScope, v)
+
+    @field_validator("prohibits_damage", mode="before")
+    @classmethod
+    def _normalize_prohibits_damage(cls, v: Any) -> Any:
+        """issue 0037: capture damage types VERBATIM (open dim); canonicalized onto `DamageType` (+ skos:broader
+        synonyms) at the KG boundary, keeping the phrase when nothing matches (was: collapse to OTHER -> discarded)."""
+        return _clean_open_list(v)
+
+    @field_validator("prohibits_solicit", mode="before")
+    @classmethod
+    def _normalize_prohibits_solicit(cls, v: Any) -> Any:
+        """Map free-text values onto NonsolicitTarget members (falls back to OTHER)."""
+        return _normalize_enum(NonsolicitTarget, v)
+
+    @field_validator("requires_duty", mode="before")
+    @classmethod
+    def _normalize_requires_duty(cls, v: Any) -> Any:
+        """Map free-text values onto ProceduralDuty members (falls back to OTHER)."""
+        return _normalize_enum(ProceduralDuty, v)
+
+    @model_validator(mode="after")
+    def _deduplicate_covers(self) -> Self:
+        """Keep first occurrence per key (removes duplicates from chunked extraction)."""
+        if not self.covers:
+            return self
+        seen: set[str] = set()
+        unique: list[Any] = []
+        for item in self.covers:
+            key = str(item).strip().lower()
+            if key not in seen:
+                seen.add(key)
+                unique.append(item)
+        object.__setattr__(self, "covers", unique)
+        return self
+
+    @model_validator(mode="after")
+    def _deduplicate_excepts(self) -> Self:
+        """Keep first occurrence per key (removes duplicates from chunked extraction)."""
+        if not self.excepts:
+            return self
+        seen: set[str] = set()
+        unique: list[Any] = []
+        for item in self.excepts:
+            key = str(item).strip().lower()
+            if key not in seen:
+                seen.add(key)
+                unique.append(item)
+        object.__setattr__(self, "excepts", unique)
+        return self
+
+    @model_validator(mode="after")
+    def _deduplicate_prohibits_damage(self) -> Self:
+        """Keep first occurrence per key (removes duplicates from chunked extraction)."""
+        if not self.prohibits_damage:
+            return self
+        seen: set[str] = set()
+        unique: list[Any] = []
+        for item in self.prohibits_damage:
+            key = str(item).strip().lower()
+            if key not in seen:
+                seen.add(key)
+                unique.append(item)
+        object.__setattr__(self, "prohibits_damage", unique)
+        return self
+
+    def __str__(self) -> str:
+        parts = [self.document_reference, self.audit_frequency]
+        return " ".join(str(p) for p in parts if p) or "Unknown"
+
+
+# -----------------------------------------------------------------------------
+# Verification
+# -----------------------------------------------------------------------------
+# This template passed generation gates V1-V6 (parse, import allowlist,
+# load, structured-output schema, dense catalog walk, graph-shape smoke
+# test). Comments never reach extraction prompts — only class docstrings
+# and field descriptions do. After hand edits, re-verify with:
+#
+#     docling-graph template lint <module.path.Clause>