rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/disambiguation.py

@@ -0,0 +1,163 @@
+"""Entity disambiguation and canonicalization (FR-C.7, T23b): normalize, reject, cluster.
+
+The stage between recognition (T23) and closed-world linking (T24). It takes the raw `EntityMention`
+stream from graph extraction and turns it into canonical mention clusters, each a proposal a human
+verifies before T24 links it to an EDGAR CIK. Three deterministic stages (ADR-0004): normalize surface
+variants to one key, reject non-entities, cluster survivors by key. Two things this capability adds on
+top of the T10 rules it reuses (`corpus.canonicalize`): it carries `chunk_id` provenance and confidence
+onto each cluster, and it applies the conservative-merge bias (ADR-0004 C3/C4) by FLAGGING ambiguous
+near-duplicates (parent/subsidiary or shared-token pairs) for a human decision rather than merging them
+— a false merge is a silent, invisible error, worse than a false split the human can see.
+
+Full coreference (pronouns, definite descriptions like "the Company" bound to a party) is deferred
+behind the `CoreferenceResolver` seam, the same discipline as OpenIE at T5: a stable interface
+additional resolvers bind later, with nothing here reopened.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.registry import CapabilityRegistry
+from rag_wright.contracts.extraction import ExtractionResult
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.corpus.canonicalize import is_entity, normalize_entity_name
+
+# Confidence weakness rank: a cluster carries the WEAKEST tag among its mentions (a cluster is only as
+# trustworthy as its least-certain member).
+_CONFIDENCE_RANK = {ConfidenceTag.EXTRACTED: 0, ConfidenceTag.INFERRED: 1, ConfidenceTag.AMBIGUOUS: 2}
+_RANK_TO_CONFIDENCE = {rank: tag for tag, rank in _CONFIDENCE_RANK.items()}
+
+# Stopwords dropped only for the near-duplicate token comparison (not for the clustering key), so
+# "Bank of America" vs "Bank of England" are not flagged on the shared "bank"/"of".
+_NEAR_DUP_STOPWORDS = frozenset({"of", "the", "and", "for", "a", "an"})
+
+
+class MentionCluster(BaseModel):
+    """One candidate real-world entity: a human-verifiable proposal, never an auto-committed merge.
+
+    Carries `chunk_id` provenance and confidence (FR-S.4). `ambiguous_with` lists the keys of near-
+    duplicate clusters flagged for a human to decide off the contract language (ADR-0004 C4); it is the
+    conservative-merge bias made visible — these are NOT merged automatically.
+    """
+
+    key: str  # the normalized clustering key
+    representative: str  # the longest surface form, for display + registry matching
+    variants: list[str]
+    entity_type: str  # opaque domain entity type (DD-5); carried through from the mention
+    confidence: ConfidenceTag  # weakest over the clustered mentions
+    chunk_ids: list[str]  # provenance: the chunks the mentions came from
+    ambiguous_with: list[str] = []  # keys of flagged near-duplicate clusters (human decides)
+
+
+class DisambiguationResult(BaseModel):
+    """The capability's output: canonical clusters (proposals) plus the rejected surface forms (audit)."""
+
+    clusters: list[MentionCluster]
+    rejected: list[str]
+
+
+@runtime_checkable
+class CoreferenceResolver(Protocol):
+    """The deferred full-coreference seam (ADR-0004): additional resolvers (pronoun / definite-
+    description coreference) bind this later and rewrite the cluster set; nothing here changes. A
+    resolver returns the (possibly merged) clusters. Default: no resolvers — clustering is by surface
+    form only."""
+
+    name: str
+
+    def resolve(self, clusters: list[MentionCluster]) -> list[MentionCluster]: ...
+
+
+def _weakest(confidences: list[ConfidenceTag]) -> ConfidenceTag:
+    return _RANK_TO_CONFIDENCE[max(_CONFIDENCE_RANK[c] for c in confidences)]
+
+
+def _near_duplicate(key_a: str, key_b: str) -> bool:
+    """Two cluster keys are ambiguous near-duplicates (flag, do not merge): one key's significant
+    tokens are a proper subset of the other's (parent/subsidiary, extra-qualifier), or they share a
+    first token and overlap substantially (shared-token pair). Biased to over-flag (human decides)."""
+    tokens_a = [t for t in key_a.split() if t not in _NEAR_DUP_STOPWORDS]
+    tokens_b = [t for t in key_b.split() if t not in _NEAR_DUP_STOPWORDS]
+    set_a, set_b = set(tokens_a), set(tokens_b)
+    if not set_a or not set_b or set_a == set_b:
+        return False
+    if set_a < set_b or set_b < set_a:  # proper token subset
+        return True
+    if tokens_a[0] == tokens_b[0]:  # shared first token + substantial overlap
+        return len(set_a & set_b) / len(set_a | set_b) >= 0.5
+    return False
+
+
+def disambiguate(
+    results: Sequence[ExtractionResult],
+    *,
+    coreference_resolvers: Sequence[CoreferenceResolver] = (),
+) -> DisambiguationResult:
+    """Normalize, reject, and cluster the extracted entity mentions into human-verifiable proposals.
+
+    Mentions are collected across the extraction results (their `chunk_id` is provenance), non-entities
+    are rejected (never reach T24), survivors are clustered by (normalized key, type), each cluster
+    carries its provenance and weakest confidence, deferred coreference resolvers (if any) rewrite the
+    clusters, and ambiguous near-duplicates are flagged for human decision (never merged).
+    """
+    groups: dict[tuple[str, str], dict] = {}  # (normalized key, entity_type) -> cluster accumulator
+    rejected: list[str] = []
+    for result in results:
+        chunk_id = result.chunk_id.value
+        for mention in result.entity_mentions:
+            if not is_entity(mention.text):
+                rejected.append(mention.text)
+                continue
+            key = normalize_entity_name(mention.text)
+            group = groups.setdefault(
+                (key, mention.entity_type),
+                {"variants": [], "confidences": [], "chunk_ids": set()},
+            )
+            if mention.text not in group["variants"]:
+                group["variants"].append(mention.text)
+            group["confidences"].append(mention.confidence)
+            group["chunk_ids"].add(chunk_id)
+
+    clusters = [
+        MentionCluster(
+            key=key,
+            representative=max(group["variants"], key=len),
+            variants=sorted(group["variants"]),
+            entity_type=entity_type,
+            confidence=_weakest(group["confidences"]),
+            chunk_ids=sorted(group["chunk_ids"]),
+        )
+        for (key, entity_type), group in groups.items()
+    ]
+
+    for resolver in coreference_resolvers:  # deferred seam (default: none)
+        clusters = resolver.resolve(clusters)
+
+    _flag_near_duplicates(clusters)
+    clusters.sort(key=lambda c: c.key)
+    return DisambiguationResult(clusters=clusters, rejected=rejected)
+
+
+def _flag_near_duplicates(clusters: list[MentionCluster]) -> None:
+    """Set each cluster's `ambiguous_with` (symmetric) for same-type near-duplicate pairs (ADR-0004 C4)."""
+    for i, a in enumerate(clusters):
+        for b in clusters[i + 1 :]:
+            if a.entity_type == b.entity_type and _near_duplicate(a.key, b.key):
+                a.ambiguous_with.append(b.key)
+                b.ambiguous_with.append(a.key)
+    for cluster in clusters:
+        cluster.ambiguous_with.sort()
+
+
+def register_entity_disambiguation(registry: CapabilityRegistry) -> None:
+    """Register under FR-C.7 (`entity_disambiguation`, an in-process `function`)."""
+    registry.register(
+        "entity_disambiguation",
+        contract=DisambiguationResult,
+        kind="function",
+        display_name="Entity disambiguation (normalize / reject / cluster)",
+    )

rag_wright/capabilities/document_parse.py

@@ -0,0 +1,87 @@
+"""Generic document-parse surface (EP-API-6b): the corpus-seam `SourceDocument` contract + the docling-parse
+helpers that build one from raw bytes.
+
+DOMAIN-FREE on purpose. It uses only the generic docling parser (`capabilities.parsing`) and the generic text
+extraction (`corpus.document_parser`) -- nothing contract/clause/edgar -- so the engine's public parse API
+(`api.parse_document`) depends on THIS, not on the contract ingestion pipeline (which would drag the whole
+contract reference pack into any caller just to parse a PDF). A byte-source corpus adapter for ANY domain builds
+a structure-bearing `SourceDocument` the same way. (Relocated out of `subgraphs/contract_ingestion_pipeline`,
+which now re-exports these for its existing importers.)
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.parsing import ParsedDocument
+
+_INGEST_PARSE_DEADLINE_S = 600.0  # per-document parse ceiling (a degraded multi-page doc escalated to the VLM)
+
+
+class SourceDocument(BaseModel):
+    """One document to ingest: its canonical `source_doc_id` (HYG-1), its already-parsed text, and optional
+    per-corpus metadata (e.g. CUAD annotated parties, ACORD pre-segmented spans) the stages may consult."""
+
+    source_doc_id: str
+    text: str
+    metadata: dict = {}
+    # CHUNK-7 (ADR-0058, issue 0004): the REAL docling parse (structure preserved), set by a BYTE-source adapter
+    # (or `parsed_source_document`). When present, the chunk stage uses it so the structural pass fires on the
+    # document's actual headings; when None (genuinely text-only input) the chunker falls back to a text parse.
+    parsed: Optional[ParsedDocument] = None
+    # 0009-WIRE2: pages the tiered OCR could not read even after VLM escalation (a degraded scan) -- surfaced as an
+    # `ocr` PARTIAL in the IngestionReport, never silently ingested as gibberish.
+    ocr_unreadable_pages: list[int] = []
+
+
+def parsed_source_document(
+    source_doc_id: str, name: str, data: bytes, *, cache_dir: Any, metadata: Optional[dict] = None
+) -> SourceDocument:
+    """Build a STRUCTURE-BEARING `SourceDocument` from raw document BYTES (PDF/DOCX/HTML/MD): docling-parse ONCE
+    (content-hash gated + cached), carry the `DoclingDocument` on `.parsed` (so the chunker's structural pass
+    fires on real headings), and set `.text` to the flattened text (for the text-consuming stages). This is how a
+    byte-source corpus adapter -- or the product (RuleWright), which hand-builds its ingest -- feeds a real
+    document to the engine; a plain-text `SourceDocument` (no `.parsed`) still uses the text fallback."""
+    import hashlib
+    import json
+    from pathlib import Path
+
+    from rag_wright.capabilities.parsing import TieredOCRParser, load_document
+    from rag_wright.corpus.document_parser import document_to_text, parse_document_bytes
+
+    cache_dir = Path(cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    content_hash = hashlib.sha256(data).hexdigest()
+    manifest_path = cache_dir / f"{source_doc_id}.{content_hash[:16]}.json"
+    ocr_sidecar = cache_dir / f"{source_doc_id}.{content_hash[:16]}.ocr.json"  # the OCR verdict, cached alongside
+    parsed = ParsedDocument(
+        source_doc_id=source_doc_id, content_hash=content_hash, manifest_path=str(manifest_path))
+    if manifest_path.exists():  # content-hash gate: parse once (restore the OCR verdict from the sidecar)
+        document = load_document(parsed)
+        unreadable = json.loads(ocr_sidecar.read_text()) if ocr_sidecar.exists() else []
+    else:  # 0009-WIRE2: tiered OCR -- capture which pages stayed unreadable even after VLM, so they surface PARTIAL
+        tiered = TieredOCRParser()
+        document = parse_document_bytes(name, data, parser=tiered)
+        document.save_as_json(manifest_path)
+        unreadable = list(tiered.report.unreadable_pages)
+        ocr_sidecar.write_text(json.dumps(unreadable))
+    return SourceDocument(
+        source_doc_id=source_doc_id, text=document_to_text(document), parsed=parsed, metadata=metadata or {},
+        ocr_unreadable_pages=unreadable)
+
+
+async def aparsed_source_document(
+    source_doc_id: str, name: str, data: bytes, *, cache_dir: Any, metadata: Optional[dict] = None,
+    deadline_s: float = _INGEST_PARSE_DEADLINE_S,
+) -> SourceDocument:
+    """The ASYNC, deadline-bounded twin of `parsed_source_document` (ADR-0057) -- STABLE PUBLIC API. Runs the sync
+    build (docling parse + the tiered OCR/VLM escalation, the slowest call in the pipeline) OFF the event loop
+    (`to_thread`) under an `asyncio.timeout`, so a hand-built async ingest can parse a document into the
+    structure-bearing `SourceDocument` the chunker needs WITHOUT reimplementing the wrapper (or blocking the loop).
+    Same caveat as every `to_thread` bound: the deadline unblocks the CALLER; the docling worker thread finishes in
+    the background (true cancellation would route the vision call through the async model seam)."""
+    async with asyncio.timeout(deadline_s):
+        return await asyncio.to_thread(
+            parsed_source_document, source_doc_id, name, data, cache_dir=cache_dir, metadata=metadata)

rag_wright/capabilities/document_scope.py

@@ -0,0 +1,49 @@
+"""Issue 0031: a workspace document scope for corpus-wide retrieval.
+
+A `documents` list narrows a corpus-wide query (span retrieval, graph traversal) to a subset of the store's
+source documents, applied IN THE STORE so out-of-scope content is never pooled, embedded against, judged, or
+cited (the same argument issue 0007 settled for compliance `sources`). This module holds the shared
+validation both consumers use: an unknown document id RAISES rather than silently matching nothing (a filter
+that quietly matches nothing is indistinguishable from an empty workspace -- the exact failure this scope
+exists to prevent).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class UnknownDocumentError(ValueError):
+    """A `documents` scope named a document id that was never ingested into the store (issue 0031). Mirrors
+    compliance's `UnknownComplianceSourceError` (issue 0007): naming a document that does not exist is a
+    caller error, surfaced explicitly rather than silently returning empty. Carries `.unknown` (the offending
+    ids) and `.present` (the FULL known-document set) as structured attributes; the message names every
+    unknown id but samples `.present`, which can run to thousands of documents in a real store."""
+
+    _PRESENT_SAMPLE = 20
+
+    def __init__(self, unknown: list[str], present: list[str]) -> None:
+        self.unknown = unknown
+        self.present = present  # full set, for programmatic inspection
+        if len(present) > self._PRESENT_SAMPLE:
+            shown = f"{present[:self._PRESENT_SAMPLE]} ... (+{len(present) - self._PRESENT_SAMPLE} more)"
+        else:
+            shown = str(present)
+        super().__init__(f"unknown document id(s): {unknown}; present in store: {shown}")
+
+
+def validate_documents(store: Any, documents: Optional[list[str]]) -> None:
+    """Validate a `documents` scope against `store.known_document_ids()` BEFORE any retrieval spends (mirrors
+    issue 0007's `_validate_sources`). `None` (whole store) is not validated. `[]` (scope-to-nothing) is a
+    valid empty scope, not an error -- the retrieval surfaces short-circuit it. A non-empty list with any id
+    absent from the store raises `UnknownDocumentError`. A store without `known_document_ids` (a minimal fake)
+    is treated as un-validatable and passes through."""
+    if not documents:  # None or [] -> nothing to validate
+        return
+    known = getattr(store, "known_document_ids", None)
+    if known is None:
+        return
+    present = known()
+    unknown = sorted(set(documents) - present)
+    if unknown:
+        raise UnknownDocumentError(unknown, sorted(present))

rag_wright/capabilities/embedding.py

@@ -0,0 +1,164 @@
+"""Embedding capability (FR-C.2, FR-I.3): dense over the summary, native sparse over the full text.
+
+From one BGE-M3 model, produce a dense vector over the chunk summary and a native sparse vector over
+the full chunk text. The dense-over-summary + sparse-over-full-text split is the summary-miss
+mitigation (a detail dropped from the summary is still recoverable through the sparse leg). Output
+shapes match the T3 chunk-record contract (dense length `BGE_M3_DENSE_DIM`; sparse `dict[int, float]`,
+BGE-M3's string token-id keys converted to ints).
+
+FR-I.6 decoupling: embedding is a GPU-calling capability, so it is built to be called concurrently
+and non-blocking. `embed_chunks` is async; each encode goes through `asyncio.to_thread` (a poolable
+inference boundary, not a hardcoded synchronous call), and a semaphore applies backpressure so bulk
+mode can saturate the GPU without unbounded in-flight work. Grounded on `FlagEmbedding.BGEM3FlagModel`
+(the public BGE-M3 class; its inference engine is `M3Embedder`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import threading
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, field_validator
+
+from rag_wright.capabilities.rlm_chunking import Chunk
+from rag_wright.contracts.chunk import BGE_M3_DENSE_DIM
+
+DEFAULT_MAX_CONCURRENCY = 4  # in-flight encode budget (backpressure); tune per GPU at deploy
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """The BGE-M3 inference seam: dense and native-sparse encoders."""
+
+    def encode_dense(self, text: str) -> list[float]: ...
+    def encode_sparse(self, text: str) -> dict[int, float]: ...
+
+
+class ChunkEmbedding(BaseModel):
+    """The embedding capability's output: one chunk's dense and sparse vectors."""
+
+    model_config = {"frozen": True}
+
+    chunk_id: str
+    dense_vector: list[float]  # over the summary; length BGE_M3_DENSE_DIM
+    sparse_vector: dict[int, float]  # over the full text; token-id -> non-negative weight
+
+    @field_validator("dense_vector")
+    @classmethod
+    def _check_dense(cls, v: list[float]) -> list[float]:
+        if len(v) != BGE_M3_DENSE_DIM:
+            raise ValueError(f"dense_vector must have length {BGE_M3_DENSE_DIM}, got {len(v)}")
+        if not all(math.isfinite(x) for x in v):
+            raise ValueError("dense_vector must contain only finite values")
+        return v
+
+    @field_validator("sparse_vector")
+    @classmethod
+    def _check_sparse(cls, v: dict[int, float]) -> dict[int, float]:
+        if any(weight < 0 for weight in v.values()):
+            raise ValueError("sparse_vector weights must be non-negative")
+        return v
+
+
+def _resolve_device(device: str | None) -> str:
+    """The device to run BGE-M3 on: explicit arg, else `EMBED_DEVICE`, else auto (Metal `mps` when available,
+    else `cpu`). Auto-MPS offloads embedding from the CPU (freeing it for LegalBERT + extraction during ingest)
+    and is ~2x faster; the vectors are bit-for-bit equivalent to CPU (verified cosine 1.0), so it is a pure
+    speed choice, not a semantic one."""
+    import os
+
+    chosen = device or os.environ.get("EMBED_DEVICE")
+    if chosen:
+        return chosen
+    try:
+        import torch
+
+        if torch.backends.mps.is_available():
+            return "mps"
+        if torch.cuda.is_available():  # a GPU box (e.g. the bulk-ingestion VM) -> use the GPU
+            return "cuda"
+    except Exception:  # noqa: BLE001 - torch/device probing must never break model construction
+        pass
+    return "cpu"
+
+
+class BGEM3Embedder:
+    """The real embedder: BGE-M3 via `FlagEmbedding.BGEM3FlagModel` (model loaded lazily).
+
+    THREAD-SAFE (engine issue 0016): FlagEmbedding mutates the model IN PLACE on every `encode`
+    (`self.model.float()` / `.to(device)` / `.eval()`), and those C++ conversions release the GIL, so two threads
+    driving one shared model swap the same parameter-tensor storage under each other and SEGFAULT the interpreter
+    (not a catchable exception). The engine SHARES one `Embedder` across concurrent-document ingestion
+    (`run_job(max_concurrency=...)` -> per-document `encode_batch`) and across `embed_chunks`' per-chunk thread
+    fan-out. So every model call is serialized by an instance lock. The lock guards ONLY `self._model.encode`
+    (the numpy results are per-call, thread-local); the serialized section is the CPU/GPU encode, which is a small
+    slice of ingest time -- the concurrency worth overlapping is the network-bound extraction, not the encode."""
+
+    def __init__(self, model_name: str = "BAAI/bge-m3", *, use_fp16: bool = False,
+                 device: str | None = None, batch_size: int = 64, model: object | None = None) -> None:
+        self._batch_size = batch_size  # cross-item independent, so batching never changes a vector, only speed
+        self._lock = threading.Lock()  # issue 0016: serialize the in-place-mutating BGE-M3 encode across threads
+        if model is not None:  # injected (hermetic tests) -- avoids loading the real model
+            self._model = model
+        else:
+            from FlagEmbedding import BGEM3FlagModel
+
+            self._model = BGEM3FlagModel(model_name, use_fp16=use_fp16, devices=_resolve_device(device))
+
+    def encode_dense(self, text: str) -> list[float]:
+        with self._lock:  # issue 0016
+            out = self._model.encode([text], return_dense=True, return_sparse=False)
+        return out["dense_vecs"][0].tolist()
+
+    def encode_sparse(self, text: str) -> dict[int, float]:
+        with self._lock:  # issue 0016
+            out = self._model.encode([text], return_dense=False, return_sparse=True)
+        # lexical_weights is a Dict[str, float] keyed by string token ids; convert to int keys (T3).
+        return {int(k): float(v) for k, v in out["lexical_weights"][0].items()}
+
+    def encode_batch(self, texts: list[str]) -> tuple[list[list[float]], list[dict[int, float]]]:
+        """Batched dense+sparse over many texts in ONE model call (the ingestion/population path):
+        same per-text format as `encode_dense`/`encode_sparse`, amortizing the model overhead."""
+        if not texts:
+            return [], []
+        with self._lock:  # issue 0016: serialize the shared-model encode across concurrent-document threads
+            out = self._model.encode(texts, return_dense=True, return_sparse=True, batch_size=self._batch_size)
+        dense = [v.tolist() for v in out["dense_vecs"]]
+        sparse = [{int(k): float(v) for k, v in lw.items()} for lw in out["lexical_weights"]]
+        return dense, sparse
+
+
+async def embed_chunks(
+    chunks: list[Chunk],
+    *,
+    embedder: Embedder,
+    max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
+) -> list[ChunkEmbedding]:
+    """Embed chunks concurrently (dense over summary, sparse over full text), backpressured.
+
+    Each chunk's encodes run in a thread (the poolable inference boundary); a semaphore bounds the
+    in-flight work so bulk mode saturates the GPU without unbounded concurrency.
+    """
+    semaphore = asyncio.Semaphore(max_concurrency)
+
+    async def _embed(chunk: Chunk) -> ChunkEmbedding:
+        async with semaphore:  # backpressure
+            dense = await asyncio.to_thread(embedder.encode_dense, chunk.summary)
+            sparse = await asyncio.to_thread(embedder.encode_sparse, chunk.text)
+        return ChunkEmbedding(chunk_id=chunk.chunk_id, dense_vector=dense, sparse_vector=sparse)
+
+    return list(await asyncio.gather(*(_embed(chunk) for chunk in chunks)))
+
+
+def embed_chunks_sync(
+    chunks: list[Chunk],
+    *,
+    embedder: Embedder,
+    max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
+) -> list[ChunkEmbedding]:
+    """Synchronous convenience for callers not already in an event loop."""
+    return asyncio.run(embed_chunks(chunks, embedder=embedder, max_concurrency=max_concurrency))
+
+

rag_wright/capabilities/embedding_profiles.py

@@ -0,0 +1,43 @@
+"""EP-API-4b (ADR-0117): embedding profiles -- the single place an embedding profile alias maps to its embedders.
+
+A product selects a profile via `EngineConfig.embeddings["text"]`; the engine resolves it to the right QUERY-side
+encoder (retrieval) and INGEST-side SPAN encoder (the index's `encode_batch`). `bge-m3` is the default BGE-M3
+family (the query encoder + the batch SPAN encoder). Adding a profile is one entry in each registry here, invisible
+to the product -- so BGE-M3 is no longer hardcoded in the workspace / the ingestion pipeline. Builders import their
+heavy impls LAZILY, so importing this module (and passing a profile string around) stays cheap."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+def _bge_m3_query() -> Any:
+    from rag_wright.capabilities.remote_encoders import query_embedder
+
+    return query_embedder()
+
+
+def _bge_m3_ingest() -> Any:
+    from rag_wright.capabilities.embedding import BGEM3Embedder
+
+    return BGEM3Embedder()
+
+
+# profile alias -> builder. A new embedder family = one entry in each (same alias).
+_QUERY_BUILDERS: dict[str, Callable[[], Any]] = {"bge-m3": _bge_m3_query}
+_INGEST_BUILDERS: dict[str, Callable[[], Any]] = {"bge-m3": _bge_m3_ingest}
+
+
+def build_query_embedder(profile: str = "bge-m3") -> Any:
+    """The retrieval-side embedder for `profile` (default BGE-M3). Raises `ValueError` for an unknown profile."""
+    builder = _QUERY_BUILDERS.get(profile)
+    if builder is None:
+        raise ValueError(f"unsupported embedding profile {profile!r} (known: {sorted(_QUERY_BUILDERS)})")
+    return builder()
+
+
+def build_ingest_embedder(profile: str = "bge-m3") -> Any:
+    """The ingest-side SPAN embedder for `profile` (default BGE-M3; `encode_batch`). Raises on an unknown profile."""
+    builder = _INGEST_BUILDERS.get(profile)
+    if builder is None:
+        raise ValueError(f"unsupported embedding profile {profile!r} (known: {sorted(_INGEST_BUILDERS)})")
+    return builder()

rag_wright/capabilities/entity_resolution.py

@@ -0,0 +1,154 @@
+"""Entity resolution (FR-C.7, T24): link canonical mention clusters to a canonical-id registry (closed-world).
+
+The closed-world linking stage after canonicalization (T23b). It resolves each `MentionCluster` to its
+canonical `entity_id` (the registry's canonical id) against the injected registry, and resolves the relationship endpoints
+(the `RelationshipFact` `source_ref`/`target_ref` refs) as the SAME stream, so an entity that appears
+both as a standalone mention and as a relationship endpoint lands on one node, not two (FR-C.7, ADR-0004).
+
+Matching strategy (§16.3, ADR-0013): exact normalized-surface-form match against the registry,
+closed-world — an unknown surface form resolves to `None` (unlinked), never a fabricated id. No fuzzy /
+embedding / LLM matching: a wrong fuzzy link is a silent false merge onto a canonical entity, worse than
+leaving a cluster unlinked (which the human sees), and T23b already collapsed the surface variants, so
+exact-normalized is high-recall for entities the registry knows. Two post-resolution invariants live
+here, not in the T4 contract, because both need resolved ids: a relationship whose two refs resolve to
+the SAME entity_id is dropped as a self-loop, and the two mention channels are deduped across each other.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+from typing import Optional
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.disambiguation import DisambiguationResult, MentionCluster
+from rag_wright.capabilities.registry import CapabilityRegistry
+from rag_wright.contracts.extraction import ExtractionResult
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.corpus.canonicalize import is_entity, normalize_entity_name
+from rag_wright.ontology.registry import EntityResolver
+
+
+class ResolvedEntity(BaseModel):
+    """A mention cluster linked (or not) to a canonical registry id. `entity_id is None` = unlinked
+    (closed-world: not in the registry — expected for private/unknown entities — never fabricated)."""
+
+    key: str
+    representative: str
+    entity_type: str  # opaque domain entity type (DD-5); carried through from the cluster
+    entity_id: Optional[str]  # the registry's canonical id, or None (unlinked)
+    confidence: ConfidenceTag
+    chunk_ids: list[str]
+
+
+class ResolvedRelationship(BaseModel):
+    """A relationship whose endpoints are resolved to canonical ids (or None). Self-loops are dropped
+    before this is emitted (a relationship whose refs resolve to the same entity_id)."""
+
+    source_ref: str
+    target_ref: str
+    source_id: Optional[str]
+    target_id: Optional[str]
+    relationship_type: str  # opaque domain edge type (DD-5); carried through from the fact
+    confidence: ConfidenceTag
+    chunk_id: str
+
+
+class ResolutionResult(BaseModel):
+    """The capability's output: resolved entities and relationships (self-loops removed)."""
+
+    entities: list[ResolvedEntity]
+    relationships: list[ResolvedRelationship]
+
+
+def _resolve_cluster(cluster: MentionCluster, resolver: EntityResolver) -> Optional[str]:
+    """Resolve a cluster to a canonical id: the first of its surface forms the resolver knows (closed-world)."""
+    for surface in (cluster.representative, *cluster.variants):
+        entity_id = resolver.resolve(surface)
+        if entity_id is not None:
+            return entity_id.value
+    return None
+
+
+def resolve_entities(
+    clusters: DisambiguationResult,
+    results: Sequence[ExtractionResult],
+    *,
+    resolver: EntityResolver,
+) -> ResolutionResult:
+    """Link clusters to canonical ids and resolve relationship endpoints as one stream (self-loops dropped).
+
+    Each cluster resolves to a canonical id (or None) via the injected `EntityResolver` seam (DD-3) — the
+    resolution STRATEGY is the domain's concern, not this capability's. A relationship ref resolves by matching
+    a cluster key first — so a ref that is the same entity as a standalone mention takes that cluster's id (the
+    two-channel dedup, ADR-0004) — falling back to a direct resolver lookup only for a ref with no cluster. A
+    relationship whose two refs resolve to the same non-None id is dropped (self-loop). These invariants are
+    domain-neutral and stay here; only the surface-form lookup is delegated to the resolver.
+    """
+    entities: list[ResolvedEntity] = []
+    key_to_id: dict[str, Optional[str]] = {}
+    for cluster in clusters.clusters:
+        entity_id = _resolve_cluster(cluster, resolver)
+        key_to_id[cluster.key] = entity_id  # channel-unification map (may be None: same unlinked entity)
+        entities.append(
+            ResolvedEntity(
+                key=cluster.key, representative=cluster.representative,
+                entity_type=cluster.entity_type, entity_id=entity_id,
+                confidence=cluster.confidence, chunk_ids=cluster.chunk_ids,
+            )
+        )
+
+    def _resolve_ref(ref: str) -> Optional[str]:
+        if not is_entity(ref):
+            return None
+        key = normalize_entity_name(ref)
+        if key in key_to_id:  # same entity as a standalone mention -> its id (even if None)
+            return key_to_id[key]
+        resolved = resolver.resolve(ref)
+        return resolved.value if resolved is not None else None
+
+    relationships: list[ResolvedRelationship] = []
+    for result in results:
+        chunk_id = result.chunk_id.value
+        for fact in result.relationship_facts:
+            source_id = _resolve_ref(fact.source_ref)
+            target_id = _resolve_ref(fact.target_ref)
+            if source_id is not None and source_id == target_id:
+                continue  # post-resolution self-loop: two distinct mentions, one entity -> dropped
+            relationships.append(
+                ResolvedRelationship(
+                    source_ref=fact.source_ref, target_ref=fact.target_ref,
+                    source_id=source_id, target_id=target_id,
+                    relationship_type=fact.relationship_type, confidence=fact.confidence,
+                    chunk_id=chunk_id,
+                )
+            )
+    return ResolutionResult(entities=entities, relationships=relationships)
+
+
+def fragmentation_rate(result: ResolutionResult, gold_by_key: dict[str, str]) -> float:
+    """Residual fragmentation after resolution (risk 5), measured against gold entity labels: the
+    fraction of true entities that end as more than one node. Resolution reduces fragmentation when the
+    registry links surface variants T23b's exact-key clustering left separate (e.g. an acronym alias) to
+    the same canonical id. A cluster is a node by its `entity_id` if linked, else by its own key (unlinked)."""
+    nodes_per_entity: dict[str, set[str]] = defaultdict(set)
+    for entity in result.entities:
+        gold = gold_by_key.get(entity.key)
+        if gold is None:
+            continue
+        nodes_per_entity[gold].add(entity.entity_id or f"unlinked:{entity.key}")
+    if not nodes_per_entity:
+        return 0.0
+    fragmented = sum(1 for nodes in nodes_per_entity.values() if len(nodes) > 1)
+    return fragmented / len(nodes_per_entity)
+
+
+def register_entity_resolution(registry: CapabilityRegistry) -> None:
+    """Register under FR-C.7 (`entity_resolution`, an in-process `function`)."""
+    registry.register(
+        "entity_resolution",
+        contract=ResolutionResult,
+        kind="function",
+        display_name="Entity resolution (closed-world to a canonical-id registry)",
+    )