rag-wright 0.1.0__py3-none-any.whl

rag_wright/spans/dim_fleet.json

@@ -0,0 +1,411 @@
+{
+  "assignment_consent": {
+    "floor": 0.88,
+    "framework": "laya",
+    "model": "A_thematic__temporal_consents",
+    "question": {
+      "criteria": {
+        "consent_required": "assignment requires the other party's prior consent / approval before it is effective",
+        "free": "assignment is permitted freely \u2014 no consent and no notice required",
+        "notice_only": "assignment is permitted without consent, but the assigning party must give notice to the other"
+      },
+      "instructions": "May a party assign this agreement, and under what condition?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "cap_basis": {
+    "floor": 0.5,
+    "framework": "setfit",
+    "model": "setfit_all_all-mpnet-base-v2_dim_cap_basis__silver_mpnet",
+    "top_k": 2
+  },
+  "carve_out": {
+    "floor": 0.67,
+    "framework": "setfit",
+    "model": "setfit_all_legal-bert-base-uncased_dim_carve_out__silver_v1",
+    "top_k": 3
+  },
+  "claim_scope": {
+    "floor": 0.923,
+    "framework": "laya",
+    "model": "A_thematic__scope_claims",
+    "question": {
+      "criteria": {
+        "broad_based": "covers claims broadly \u2014 both first-party and third-party, or all claims without limitation",
+        "first_party": "covers claims between the contracting parties themselves (direct / first-party claims)",
+        "third_party": "covers claims brought by third parties (outside the contract) against a party"
+      },
+      "instructions": "What scope of claims does this clause cover?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "coc_consent": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "B_mixed__mix4",
+    "question": {
+      "criteria": {
+        "consent_required": "a change of control requires the other party's consent, or triggers a right to approve or terminate",
+        "notice_only": "a change of control requires only notice to the other party, not consent",
+        "unrestricted": "a change of control is unrestricted \u2014 no consent and no notice required"
+      },
+      "instructions": "On a change of control, what is required of the affected party?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "collateral_type": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "collateral_type__abstain",
+    "question": {
+      "criteria": {
+        "accounts_receivable": "accounts receivable / receivables are the collateral",
+        "all_assets": "a blanket lien on substantially all assets",
+        "deposit_accounts": "deposit accounts are the collateral",
+        "equipment": "equipment is the collateral",
+        "fixtures": "fixtures are the collateral",
+        "general_intangibles": "general intangibles are the collateral",
+        "inventory": "inventory is the collateral",
+        "ip": "intellectual property is the collateral",
+        "none": "this provision does not state what collateral secures an interest",
+        "real_property": "real property / real estate is the collateral"
+      },
+      "instructions": "What collateral secures the interest in this provision?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "condition_type": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "condition_type__abstain",
+    "question": {
+      "criteria": {
+        "closing_condition": "a condition that must be satisfied before closing (a closing condition)",
+        "none": "this provision does not state a condition-precedent type"
+      },
+      "instructions": "What kind of condition precedent does this provision state?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "confidentiality_exception": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "confidentiality_exception__abstain",
+    "question": {
+      "criteria": {
+        "independently_developed": "information independently developed without use of the disclosure",
+        "none": "this provision does not state a confidentiality exception",
+        "prior_possession": "information already in the recipient's possession before disclosure",
+        "publicly_available": "information that is or becomes publicly available",
+        "required_by_law": "disclosure required by law or a court/government order",
+        "third_party_source": "information rightfully received from a third party"
+      },
+      "instructions": "Which exception to confidentiality does this provision state?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "covered_parties": {
+    "floor": 0.73,
+    "framework": "setfit",
+    "model": "setfit_all_legal-bert-base-uncased_dim_covered_parties__v2",
+    "top_k": 2
+  },
+  "covered_subject": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__scope_claims",
+    "question": {
+      "criteria": {
+        "copyright": "copyright infringement or copyright-related claims",
+        "fraud": "fraud or fraudulent conduct",
+        "gross_negligence": "gross negligence",
+        "ip_infringement": "intellectual-property infringement generally (patent / IP rights, not specifically copyright or trademark)",
+        "trademark": "trademark infringement or trademark-related claims",
+        "violation_of_law": "violation of law or non-compliance with legal requirements"
+      },
+      "instructions": "What subject matter does this indemnity or coverage concern?",
+      "type": "choice"
+    },
+    "top_k": 3
+  },
+  "damage_type": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__scope_claims",
+    "question": {
+      "criteria": {
+        "consequential": "consequential damages \u2014 losses flowing indirectly from the breach (e.g. lost profits, lost business)",
+        "incidental": "incidental damages \u2014 costs incurred incidental to the breach",
+        "indirect": "indirect damages \u2014 not the direct or immediate result of the breach",
+        "punitive": "punitive or exemplary damages \u2014 awarded to punish, beyond compensation",
+        "special": "special damages \u2014 arising from special or particular circumstances"
+      },
+      "instructions": "Which category of damages does this clause address (e.g. exclude or waive)?",
+      "type": "choice"
+    },
+    "top_k": 3
+  },
+  "dispute_method": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "dispute_method__abstain",
+    "question": {
+      "criteria": {
+        "arbitration": "disputes are resolved by binding arbitration",
+        "litigation": "disputes are resolved by litigation in the courts",
+        "none": "this provision does not specify how disputes are resolved"
+      },
+      "instructions": "How are disputes resolved under this provision?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "escrow_release_trigger": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "escrow_release_trigger__abstain",
+    "question": {
+      "criteria": {
+        "bankruptcy": "the depositor's bankruptcy or insolvency triggers release",
+        "breach": "a material breach by the depositor triggers release",
+        "discontinuance": "discontinuance of the product or support triggers release",
+        "none": "this provision does not state an escrow release trigger"
+      },
+      "instructions": "What triggers release from escrow in this provision?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "exclusivity_type": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__ip_restrictions",
+    "question": {
+      "criteria": {
+        "exclusive": "an exclusive right \u2014 granted to the grantee to the exclusion of everyone, including the grantor",
+        "non_exclusive": "a non-exclusive right \u2014 the grantor may grant the same right to others as well",
+        "sole": "a sole right \u2014 granted to the grantee and the grantor keeps rights, but no other third party is granted it"
+      },
+      "instructions": "What kind of license or right does this clause grant?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "favorability": {
+    "floor": 0.667,
+    "framework": "laya",
+    "model": "B_mixed__mix1",
+    "question": {
+      "criteria": {
+        "buyer_favorable": "terms tilt toward the buyer / licensee / customer / receiving party \u2014 limiting their liability or obligations, or expanding their rights/remedies",
+        "seller_favorable": "terms tilt toward the seller / licensor / provider / vendor / disclosing party \u2014 limiting their liability or obligations, or expanding their rights/remedies"
+      },
+      "instructions": "Which side does this clause favor?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "force_majeure_event": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "force_majeure_event__abstain",
+    "question": {
+      "criteria": {
+        "act_of_god": "acts of God",
+        "government_action": "government action, regulation, or acts of a governmental authority",
+        "labor_dispute": "labor disputes or strikes",
+        "natural_disaster": "natural disasters (flood, earthquake, fire, storm)",
+        "none": "this provision does not enumerate a force majeure event",
+        "pandemic": "pandemic, epidemic, or disease outbreak",
+        "supply_failure": "supplier or utility failure",
+        "war": "war, terrorism, or civil unrest"
+      },
+      "instructions": "Which force majeure event does this provision enumerate?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "ip_ownership": {
+    "floor": 0.96,
+    "framework": "laya",
+    "model": "B_mixed__mix1",
+    "question": {
+      "criteria": {
+        "assigned": "IP is assigned or transferred to the other party \u2014 ownership moves away from the creator",
+        "joint": "IP is jointly owned by both parties",
+        "retained": "the creating / original party retains ownership of the IP"
+      },
+      "instructions": "Who owns the intellectual property under this clause?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "law_multiplicity": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__temporal_consents",
+    "question": {
+      "criteria": {
+        "multiple": "multiple governing laws / jurisdictions apply (e.g. different laws for different parts, parties, or matters)",
+        "single": "a single governing law / jurisdiction governs the agreement"
+      },
+      "instructions": "Does this governing-law clause name one governing law or several?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "mfn_scope": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "B_mixed__mix3",
+    "question": {
+      "criteria": {
+        "price": "the MFN applies to price only \u2014 the best price given to others must be extended here",
+        "price_and_terms": "the MFN applies to both price and terms",
+        "terms": "the MFN applies to terms or conditions only, not price"
+      },
+      "instructions": "What does this most-favored-nation (MFN) clause cover?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "mutuality": {
+    "floor": 0.67,
+    "framework": "setfit",
+    "model": "setfit_all_legal-bert-base-uncased_dim_mutuality__silver_v1",
+    "top_k": 1
+  },
+  "nonsolicit_target": {
+    "floor": 0.68,
+    "framework": "setfit",
+    "model": "setfit_all_legal-bert-base-uncased_dim_nonsolicit_target__v2",
+    "top_k": 1
+  },
+  "party_asymmetry": {
+    "floor": 0.727,
+    "framework": "laya",
+    "model": "B_mixed__mix3",
+    "question": {
+      "criteria": {
+        "different_per_party": "the obligation or its terms differ by party (one party bears more, or different, terms than the other)",
+        "symmetric": "both parties bear the same obligation, liability, or terms equally / reciprocally"
+      },
+      "instructions": "Does this clause impose the SAME obligations/terms on both parties, or DIFFERENT ones per party?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "procedural": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "B_mixed__mix4",
+    "question": {
+      "criteria": {
+        "control_of_defense": "the clause allocates control of the defense \u2014 who directs the litigation and any settlement",
+        "duty_to_defend": "the indemnifying party has a duty to defend \u2014 it must provide or assume the legal defense of the claim"
+      },
+      "instructions": "What indemnification procedure does this clause specify?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "renewal_mechanism": {
+    "floor": 0.533,
+    "framework": "laya",
+    "model": "C_singleton__renewal_mechanism",
+    "question": {
+      "criteria": {
+        "auto": "the term renews automatically (auto-renewal / evergreen) unless a party gives notice of non-renewal",
+        "requires_notice": "renewal requires an affirmative act \u2014 a party must give notice, or elect, to renew for the term to extend"
+      },
+      "instructions": "How does this agreement's term renew?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "restriction_scope": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__ip_restrictions",
+    "question": {
+      "criteria": {
+        "activity": "restricted by activity or line of business only",
+        "geographic": "restricted by geography or territory only",
+        "geographic_and_activity": "restricted by both geography and activity"
+      },
+      "instructions": "How is this restrictive covenant (e.g. non-compete) scoped?",
+      "type": "choice"
+    },
+    "top_k": 2
+  },
+  "right_of_first_type": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "right_of_first_type__abstain",
+    "question": {
+      "criteria": {
+        "none": "this provision does not state a right-of-first type",
+        "rofn": "a right of first negotiation (ROFN): the right to negotiate first",
+        "rofo": "a right of first offer (ROFO): the right to receive the first offer before others",
+        "rofr": "a right of first refusal (ROFR): the right to match a third party's offer"
+      },
+      "instructions": "Which kind of 'right of first ...' does this provision grant?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "royalty_basis": {
+    "abstain": true,
+    "framework": "laya",
+    "model": "royalty_basis__abstain",
+    "question": {
+      "criteria": {
+        "fixed": "a fixed royalty amount",
+        "none": "this provision does not state a royalty basis",
+        "pct_gross_sales": "a percentage of gross sales / gross revenue",
+        "pct_net_sales": "a percentage of net sales / net revenue",
+        "per_unit": "a per-unit royalty",
+        "tiered": "a tiered or graduated royalty schedule"
+      },
+      "instructions": "How is the royalty computed in this provision?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "termination_right": {
+    "floor": 0.84,
+    "framework": "laya",
+    "model": "A_thematic__temporal_consents",
+    "question": {
+      "criteria": {
+        "either_party": "both parties have the right to terminate the agreement (mutual / either-side termination right)",
+        "one_party": "only one specified party has the right to terminate (a unilateral termination right; the other party cannot)"
+      },
+      "instructions": "Which party has the right to terminate this agreement?",
+      "type": "choice"
+    },
+    "top_k": 1
+  },
+  "warranty_scope": {
+    "floor": 1.0,
+    "framework": "laya",
+    "model": "A_thematic__ip_restrictions",
+    "question": {
+      "criteria": {
+        "as_is": "goods or services are provided 'AS IS', with warranties disclaimed",
+        "express": "provides an express warranty \u2014 an affirmatively stated warranty",
+        "implied": "concerns implied warranties (e.g. merchantability, fitness for purpose) \u2014 extending or disclaiming them",
+        "non_reliance": "a non-reliance provision \u2014 the party did not rely on representations made outside the contract"
+      },
+      "instructions": "What does this warranty clause do?",
+      "type": "choice"
+    },
+    "top_k": 2
+  }
+}

rag_wright/spans/function_classifier.py

@@ -0,0 +1,77 @@
+"""T56 (FR-R, ADR-0025): local single-label clause-function classifier.
+
+A linear head over frozen dense embeddings of an operative span, predicting one of the 41 CUAD clause types
+(`ClauseCategory`) or NONE. Trained on CUAD gold spans (segmented to operative-span granularity, T55), applied
+at inference to ACORD operative spans. Inference is a matmul -- local, deterministic, no LLM call, categorically
+more scalable than an LLM routing call per clause. If the per-type F1 lags, the plan escalates the feature side
+to a fine-tuned encoder (LegalBERT); the head/contract here stay the same.
+
+The embedder is an injected seam (`DenseEmbedder`), so training and inference share one representation and the
+hermetic tests run with a stub -- no model load.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+import joblib
+from sklearn.linear_model import LogisticRegression
+
+NONE_LABEL = "NONE"  # the span is none of the 41 CUAD clause types (boilerplate / recital / definition)
+
+
+@runtime_checkable
+class DenseEmbedder(Protocol):
+    """The dense-embedding seam (the T5 `Embedder`'s dense leg): span text -> a fixed-length vector."""
+
+    def encode_dense(self, text: str) -> list[float]: ...
+
+
+class FunctionClassifier:
+    """A fitted single-label function classifier over span dense embeddings (predicts a CUAD type or NONE)."""
+
+    def __init__(self, model: LogisticRegression) -> None:
+        self._model = model
+
+    @classmethod
+    def train_on_features(
+        cls, features: list[list[float]], labels: list[str], **model_kwargs: Any
+    ) -> "FunctionClassifier":
+        """Fit the linear head on precomputed dense features (the batch path -- callers batch-embed first).
+        `class_weight='balanced'` offsets the heavy NONE class; dimension-agnostic (fits the feature width)."""
+        if len(features) != len(labels):
+            raise ValueError("features and labels must be the same length")
+        if not features:
+            raise ValueError("need at least one training example")
+        params: dict[str, Any] = {"max_iter": 2000, "class_weight": "balanced"}
+        params.update(model_kwargs)
+        return cls(LogisticRegression(**params).fit(features, labels))
+
+    @classmethod
+    def train(
+        cls, texts: list[str], labels: list[str], *, embedder: DenseEmbedder, **model_kwargs: Any
+    ) -> "FunctionClassifier":
+        """Convenience: embed `texts` one-by-one via the seam, then fit (used by tests / small sets)."""
+        if len(texts) != len(labels):
+            raise ValueError("texts and labels must be the same length")
+        return cls.train_on_features([embedder.encode_dense(t) for t in texts], labels, **model_kwargs)
+
+    def classify_features(self, features: list[list[float]]) -> list[str]:
+        """One label per precomputed feature vector (a CUAD type or NONE). Empty input -> empty output."""
+        if not features:
+            return []
+        return [str(y) for y in self._model.predict(features)]
+
+    def classify(self, texts: list[str], *, embedder: DenseEmbedder) -> list[str]:
+        """Convenience: embed `texts` via the seam, then classify. Empty input -> empty output."""
+        if not texts:
+            return []
+        return self.classify_features([embedder.encode_dense(t) for t in texts])
+
+    def save(self, path: Path) -> None:
+        joblib.dump(self._model, path)
+
+    @classmethod
+    def load(cls, path: Path) -> "FunctionClassifier":
+        return cls(joblib.load(path))

rag_wright/spans/function_families.py

@@ -0,0 +1,62 @@
+"""Step-5b: confusable-clause FAMILIES for the LLM-hybrid classifier. Derived data-drivenly from the
+LegalBERT model's holdout confusion (>=0.12 of a class's gold spans predicted as the sibling; connected
+components). `ROUTE_FAMILIES` is the dev-validated subset where an LLM (Gemma) beats LegalBERT at the
+sibling distinction -- only these route to the LLM; the rest keep LegalBERT (which is stronger on them, e.g.
+Cap-vs-Uncapped, which Gemma craters). Labels are canonical `FUNCTION_LABELS`; membership is canonicalized
+so it matches the classifier's CUAD-cased output too."""
+
+from __future__ import annotations
+
+from rag_wright.contracts.function import canonical_function
+
+# All confusable families (from the confusion graph). Kept for reference / diagnostics.
+CONFUSABLE_FAMILIES: tuple[tuple[str, ...], ...] = (
+    ("Affiliate License-Licensee", "Competitive Restriction Exception", "Exclusivity",
+     "Irrevocable Or Perpetual License", "License Grant", "Non-Transferable License"),
+    ("Anti-Assignment", "Change Of Control"),
+    ("Effective Date", "Expiration Date"),
+    ("Unlimited/All-You-Can-Eat-License", "Volume Restriction"),
+    ("Affiliate License-Licensor", "IP Ownership Assignment", "Joint IP Ownership"),
+    ("Notice Period To Terminate Renewal", "Price Restrictions", "Renewal Term", "Termination For Convenience"),
+    ("Most Favored Nation", "No-Solicit Of Customers", "Non-Compete"),
+    ("Cap On Liability", "Uncapped Liability"),
+    ("Liquidated Damages", "Revenue/Profit Sharing"),
+    ("Indemnification", "No-Solicit Of Employees", "Third Party Beneficiary"),
+)
+
+# The dev-validated LLM-winning subset: route ONLY these to Gemma (test-half mean non-NONE recall
+# 0.627 -> 0.641; fixes Notice-Period 0->0.33, Irrevocable 0->0.50, No-Solicit 0.17->0.50). The excluded
+# families (liability, control, dates, ...) keep LegalBERT, which is stronger there.
+ROUTE_FAMILIES: tuple[tuple[str, ...], ...] = (
+    ("Affiliate License-Licensee", "Competitive Restriction Exception", "Exclusivity",
+     "Irrevocable Or Perpetual License", "License Grant", "Non-Transferable License"),
+    ("Affiliate License-Licensor", "IP Ownership Assignment", "Joint IP Ownership"),
+    ("Notice Period To Terminate Renewal", "Price Restrictions", "Renewal Term", "Termination For Convenience"),
+    ("Most Favored Nation", "No-Solicit Of Customers", "Non-Compete"),
+    ("Liquidated Damages", "Revenue/Profit Sharing"),
+)
+
+# The rare, low-recall classes (all in a ROUTE family) worth rescuing with the LLM. TARGETED routing fires
+# only when one of these is in the LegalBERT top-2 -- so the common/strong classes never route (zero risk to
+# them), and only a fraction of a percent of spans hit the LLM. These went from ~0 to 0.33-0.67 with routing.
+RARE_TARGETS: frozenset[str] = frozenset({
+    "Irrevocable Or Perpetual License", "Notice Period To Terminate Renewal", "No-Solicit Of Customers",
+    "Non-Transferable License", "Competitive Restriction Exception", "Price Restrictions",
+    "Affiliate License-Licensee",
+})
+
+for _fam in CONFUSABLE_FAMILIES:  # canonical-guard the labels at import
+    assert all(canonical_function(c) for c in _fam), f"non-canonical label in family {_fam}"
+assert all(canonical_function(c) for c in RARE_TARGETS), "non-canonical label in RARE_TARGETS"
+
+_ROUTE_OF: dict[str, tuple[str, ...]] = {
+    canonical_function(c): tuple(canonical_function(x) for x in fam)
+    for fam in ROUTE_FAMILIES
+    for c in fam
+}
+
+
+def route_family(label: str) -> tuple[str, ...] | None:
+    """The route-family (canonical labels) that `label` belongs to, or None if `label` is not in a routed
+    family (case-insensitive: the classifier's CUAD-cased output maps in too). None => keep LegalBERT."""
+    return _ROUTE_OF.get(canonical_function(label or ""))

rag_wright/spans/hybrid_classifier.py

@@ -0,0 +1,103 @@
+"""Step-5b: the LLM-hybrid function classifier. LegalBERT predicts every span (fast, local); when its top-2
+are confusable SIBLINGS in a dev-validated ROUTE family, the span is routed to a Gemma confirm among that
+family (the LLM distinguishes those clause types better -- Notice-Period, Irrevocable, No-Solicit went from
+~0 to 0.33-0.67). Non-routed spans keep LegalBERT (stronger on the other families, e.g. Cap-vs-Uncapped).
+Only ~3% of spans route, so the LLM cost is small. Confirmer defaults to GEMMA (benchmarked); injectable for
+tests. The routed LLM calls in one `classify` batch run CONCURRENTLY (the standing eval/serve concurrency rule).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.function import canonical_function
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_structured
+from rag_wright.spans.function_families import route_family
+
+NONE_LABEL = "NONE"
+
+
+class _FamilyLabel(BaseModel):
+    label: str
+
+
+_PROMPT = (
+    "A clause classifier is unsure which of these RELATED clause types a span is:\n- {opts}\n\n"
+    "Decide which ONE it actually is by its operative meaning, or NONE if it is none of them. Respond with "
+    "EXACTLY one of the type strings above, or NONE.\n\nSpan:\n{text}"
+)
+
+
+@runtime_checkable
+class FamilyConfirmer(Protocol):
+    def __call__(self, text: str, candidates: tuple[str, ...]) -> str: ...
+
+
+class SeamFamilyConfirmer:
+    """The real confirmer: structured output on GENERAL (Gemma). Returns a validated family label or NONE
+    (an off-family / hallucinated answer -> NONE). Retries a transient bare `None`."""
+
+    def __init__(self, model_id: Optional[str] = None, *, retries: int = 3) -> None:
+        self._runnable = build_structured(model_id or model_for(ModelRole.GENERAL), _FamilyLabel)
+        self._retries = retries
+
+    def __call__(self, text: str, candidates: tuple[str, ...]) -> str:
+        prompt = _PROMPT.format(opts="\n- ".join(candidates), text=text[:2000])
+        for _ in range(self._retries):
+            try:
+                v = self._runnable.invoke(prompt)
+            except Exception:  # noqa: BLE001 - transient provider/parse error; retry
+                continue
+            if v is not None:
+                canon = canonical_function(v.label)
+                return canon if canon in candidates else NONE_LABEL
+        return NONE_LABEL
+
+
+class HybridFunctionClassifier:
+    """LegalBERT + selective LLM fallback on confusable-sibling spans. `classify` returns canonical labels.
+
+    `targets` (optional) narrows routing to TARGETED mode: route only when a target class is in the LegalBERT
+    top-2 (and the top-2 are siblings in a route family). This rescues the rare targets while leaving the
+    common/strong classes untouched -- fewer LLM calls, zero risk to what already works. `targets=None` routes
+    every sibling-ambiguous span in a route family."""
+
+    def __init__(self, bert_classifier, confirmer: Optional[FamilyConfirmer] = None, *,
+                 targets: Optional[frozenset[str]] = None, concurrency: int = 8):
+        self._bert = bert_classifier
+        self._confirm = confirmer if confirmer is not None else SeamFamilyConfirmer()
+        self._targets = targets
+        self._concurrency = concurrency
+
+    def classify(self, texts: list[str], *, batch_size: int = 32) -> list[str]:
+        if not texts:
+            return []
+        topk = self._bert.classify_topk(texts, k=2, batch_size=batch_size)
+        labels = [canonical_function(row[0]) or row[0] for row in topk]  # LegalBERT top-1 (canonical)
+        routed = []  # (index, family) where the top-2 are siblings in a ROUTE family
+        for i, row in enumerate(topk):
+            fam = route_family(labels[i])
+            top2 = canonical_function(row[1]) if len(row) > 1 else None
+            if fam is not None and top2 in fam:
+                if self._targets is not None and labels[i] not in self._targets and top2 not in self._targets:
+                    continue  # TARGETED: skip unless a rare target is one of the top-2
+                routed.append((i, fam))
+        if not routed:
+            return labels
+
+        async def _run():
+            sem = asyncio.Semaphore(self._concurrency)
+
+            async def _one(i, fam):
+                async with sem:
+                    return i, await asyncio.to_thread(self._confirm, texts[i], fam)
+
+            return await asyncio.gather(*[_one(i, fam) for i, fam in routed])
+
+        for i, lab in asyncio.run(_run()):
+            labels[i] = lab
+        return labels