resolvekit 0.0.1__py3-none-any.whl

resolvekit/matchers/README.md

@@ -0,0 +1,77 @@
+# Matchers Module
+
+## Purpose
+
+The matchers module implements the candidate generation cascade - a series of increasingly sophisticated matching strategies applied in sequence until candidates are found.
+
+## Components
+
+### Matcher Classes
+
+1. **ExactCodeMatcher** (`exact_code.py`)
+   - Direct lookup of standardized codes (ISO, M49, NUTS, OCHA P-codes, DCIDs)
+   - Validates code format before lookup
+   - Highest priority matcher (deterministic)
+
+2. **CanonicalNameMatcher** (`canonical_name.py`)
+   - Exact match against normalized canonical entity names
+   - Uses hash table for O(1) lookup
+   - Second-highest priority
+
+3. **AliasExactMatcher** (`alias_exact.py`)
+   - Exact match against normalized aliases
+   - Handles multilingual aliases
+   - Returns all matching entities (may be multiple)
+
+4. **FTSMatcher** (`fts_matcher.py`)
+   - Full-text search using SQLite FTS5
+   - Returns top-K candidates ranked by BM25-like score
+   - Queries across base pack + overlay FTS indexes
+
+5. **FuzzyMatcher** (`fuzzy_matcher.py`)
+   - Bounded fuzzy matching on FTS candidates
+   - Uses edit distance, trigram similarity, Jaccard coefficient
+   - Reduces top-K to top-K' highest-scoring candidates
+
+6. **SemanticMatcher** (`semantic_matcher.py`)
+   - Optional semantic similarity via embeddings
+   - Only invoked on ambiguous cases (low margin or registry hit)
+   - Requires `resolver[semantic]` extra
+
+### Shared Components
+
+- `base.py`: Abstract base class for all matchers
+- `cascade.py`: Orchestrates matcher execution in priority order
+- `candidate.py`: Candidate data structures and scoring
+
+## Matcher Cascade Flow
+
+```
+Input Query
+    ↓
+[1. ExactCodeMatcher] → Found? → Return
+    ↓ Not found
+[2. CanonicalNameMatcher] → Found? → Return
+    ↓ Not found
+[3. AliasExactMatcher] → Found? → Return candidates
+    ↓ Not found or ambiguous
+[4. FTSMatcher] → top-K candidates (K=50)
+    ↓
+[5. FuzzyMatcher] → refine to top-K' (K'=12)
+    ↓
+[6. SemanticMatcher] → re-rank if ambiguous (optional)
+    ↓
+Return ranked candidates
+```
+
+## Design Principles
+
+1. **Fail-fast**: Early matchers return immediately on high-confidence matches
+2. **Bounded computation**: Limit fuzzy/semantic work to top-K candidates
+3. **Pluggable**: Easy to add custom matchers
+4. **Feature extraction**: Each matcher emits features for calibration
+
+## Implementation Priority
+
+**Phase A** - Core resolver (items 1-5)
+**Phase E** - Ambiguity subsystem (item 6)

resolvekit/matchers/__init__.py

@@ -0,0 +1,65 @@
+"""Matcher cascade module for entity resolution."""
+
+from typing import TYPE_CHECKING
+
+# Lazy imports to avoid circular dependency with data.code_repository
+# The code_repository needs code_validators, but if we eagerly import
+# cascade/exact_code here, they will try to import code_repository
+if TYPE_CHECKING:
+    from resolvekit.matchers.alias_exact import AliasExactMatcher
+    from resolvekit.matchers.canonical_name import CanonicalNameMatcher
+    from resolvekit.matchers.cascade import MatcherCascade
+    from resolvekit.matchers.exact_code import ExactCodeMatcher
+    from resolvekit.matchers.fts_matcher import FTSMatcher
+    from resolvekit.matchers.fuzzy_matcher import FuzzyMatcher
+
+# These are safe to import eagerly as they don't depend on data layer
+from resolvekit.matchers.code_validators import CODE_VALIDATORS, get_validator
+from resolvekit.matchers.priorities import InferencePriority
+from resolvekit.matchers.protocols import CodeValidatorProtocol, MatcherProtocol
+from resolvekit.types import Candidate, MatchContext
+
+__all__ = [
+    "CODE_VALIDATORS",
+    "AliasExactMatcher",
+    "Candidate",
+    "CanonicalNameMatcher",
+    "CodeValidatorProtocol",
+    "ExactCodeMatcher",
+    "FTSMatcher",
+    "FuzzyMatcher",
+    "InferencePriority",
+    "MatchContext",
+    "MatcherCascade",
+    "MatcherProtocol",
+    "get_validator",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazy load matcher classes to avoid circular imports."""
+    if name == "AliasExactMatcher":
+        from resolvekit.matchers.alias_exact import AliasExactMatcher
+
+        return AliasExactMatcher
+    elif name == "CanonicalNameMatcher":
+        from resolvekit.matchers.canonical_name import CanonicalNameMatcher
+
+        return CanonicalNameMatcher
+    elif name == "MatcherCascade":
+        from resolvekit.matchers.cascade import MatcherCascade
+
+        return MatcherCascade
+    elif name == "ExactCodeMatcher":
+        from resolvekit.matchers.exact_code import ExactCodeMatcher
+
+        return ExactCodeMatcher
+    elif name == "FTSMatcher":
+        from resolvekit.matchers.fts_matcher import FTSMatcher
+
+        return FTSMatcher
+    elif name == "FuzzyMatcher":
+        from resolvekit.matchers.fuzzy_matcher import FuzzyMatcher
+
+        return FuzzyMatcher
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

resolvekit/matchers/alias_exact.py

@@ -0,0 +1,65 @@
+"""Exact alias matcher for normalized alias lookups."""
+
+from resolvekit.data.alias_repository import AliasRepository
+from resolvekit.types import Candidate, MatchContext, MatcherType
+
+
+class AliasExactMatcher:
+    """
+    Matches exact aliases (normalized).
+
+    Tier 2 matcher: May return multiple candidates (ambiguous).
+    Cascade stops if single match, continues if multiple.
+
+    Matches against normalized aliases using exact lookup.
+    """
+
+    def __init__(self, alias_repo: AliasRepository):
+        """
+        Initialize matcher.
+
+        Args:
+            alias_repo: Alias repository for lookups
+        """
+        self.alias_repo = alias_repo
+
+    def match(
+        self,
+        query: str,
+        normalized_query: str,
+        limit: int = 10,
+        context: MatchContext | None = None,
+    ) -> list[Candidate]:
+        """
+        Find all entities with exact normalized alias match.
+
+        Args:
+            query: Original query string (unused)
+            normalized_query: Normalized query string
+            limit: Maximum candidates to return
+            context: Optional filtering context
+
+        Returns:
+            List of candidates (may be multiple for ambiguous aliases)
+        """
+        # Find all entities with this alias
+        matches = self.alias_repo.find_exact_normalized(normalized_query, context)
+
+        if not matches:
+            return []
+
+        # Convert to candidates
+        candidates = []
+        for entity, matched_alias in matches:
+            candidates.append(
+                Candidate(
+                    entity=entity,
+                    score=1.0,
+                    matcher_type=MatcherType.ALIAS_EXACT,
+                    features={"alias_exact": True, "matched_alias": matched_alias},
+                    matched_alias=matched_alias,
+                )
+            )
+
+        # Limit results
+        return candidates[:limit]

resolvekit/matchers/canonical_name.py

@@ -0,0 +1,62 @@
+"""Canonical name matcher for exact name lookups."""
+
+from resolvekit.data.entity_repository import EntityRepository
+from resolvekit.normalization.normalizer import TextNormalizer
+from resolvekit.types import Candidate, MatchContext, MatcherType
+
+
+class CanonicalNameMatcher:
+    """
+    Matches exact canonical names (normalized).
+
+    Tier 1 matcher: Deterministic, returns single match, stops cascade.
+
+    Matches against normalized canonical names using exact lookup.
+    """
+
+    def __init__(self, entity_repo: EntityRepository, normalizer: TextNormalizer):
+        """
+        Initialize matcher.
+
+        Args:
+            entity_repo: Entity repository for lookups
+            normalizer: Text normalizer (for consistency)
+        """
+        self.entity_repo = entity_repo
+        self.normalizer = normalizer
+
+    def match(
+        self,
+        query: str,
+        normalized_query: str,
+        limit: int = 10,
+        context: MatchContext | None = None,
+    ) -> list[Candidate]:
+        """
+        Lookup by normalized canonical name.
+
+        Args:
+            query: Original query string (unused)
+            normalized_query: Normalized query string
+            limit: Maximum candidates (unused, always returns 0 or 1)
+            context: Optional filtering context
+
+        Returns:
+            List with single candidate if match found, empty list otherwise
+        """
+        # Lookup by normalized canonical name
+        entity = self.entity_repo.find_by_canonical_name(normalized_query, context)
+
+        if not entity:
+            return []
+
+        # Return single candidate
+        return [
+            Candidate(
+                entity=entity,
+                score=1.0,
+                matcher_type=MatcherType.CANONICAL_NAME,
+                features={"canonical_exact": True},
+                matched_alias=None,
+            )
+        ]

resolvekit/matchers/cascade.py

@@ -0,0 +1,127 @@
+"""Matcher cascade orchestrator with tier-based short-circuiting."""
+
+from resolvekit.matchers.alias_exact import AliasExactMatcher
+from resolvekit.matchers.canonical_name import CanonicalNameMatcher
+from resolvekit.matchers.exact_code import ExactCodeMatcher
+from resolvekit.matchers.fts_matcher import FTSMatcher
+from resolvekit.matchers.fuzzy_matcher import FuzzyMatcher
+from resolvekit.normalization.normalizer import TextNormalizer
+from resolvekit.types import Candidate, CodeSystem, MatchContext
+
+
+class MatcherCascade:
+    """
+    Orchestrates matcher execution with tier-based short-circuiting.
+
+    Cascade Tiers:
+        Tier 1 (Deterministic): ExactCode, CanonicalName -> STOP if found
+        Tier 2 (Exact Multi): AliasExact -> STOP if unambiguous
+        Tier 3 (Fuzzy): FTS + Fuzzy -> Return top-K
+
+    Performance Target:
+        - Tier 1: p50 < 10ms (most queries)
+        - Tier 3: p95 < 50ms (complex queries)
+    """
+
+    def __init__(
+        self,
+        exact_code: ExactCodeMatcher,
+        canonical_name: CanonicalNameMatcher,
+        alias_exact: AliasExactMatcher,
+        fts: FTSMatcher,
+        fuzzy: FuzzyMatcher,
+        normalizer: TextNormalizer,
+        code_priority: list[CodeSystem] | None = None,
+    ):
+        """
+        Initialize cascade with all matchers.
+
+        Args:
+            exact_code: Tier 1 exact code matcher
+            canonical_name: Tier 1 canonical name matcher
+            alias_exact: Tier 2 alias exact matcher
+            fts: Tier 3 FTS matcher
+            fuzzy: Tier 3 fuzzy matcher
+            normalizer: Text normalizer
+            code_priority: Optional code system inference priority.
+                         If provided, overrides the exact_code matcher's priority.
+                         Use InferencePriority presets (humanitarian, world_bank, etc.)
+                         or provide a custom list of CodeSystem values.
+        """
+        self.exact_code = exact_code
+        self.canonical_name = canonical_name
+        self.alias_exact = alias_exact
+        self.fts = fts
+        self.fuzzy = fuzzy
+        self.normalizer = normalizer
+
+        # Apply code priority if provided (cascade-level configuration)
+        if code_priority is not None:
+            self.exact_code.priority = code_priority
+
+    def resolve(  # noqa: PLR0911
+        self, query: str, context: MatchContext | None = None, top_k: int = 12
+    ) -> list[Candidate]:
+        """
+        Execute cascade with tier-based short-circuiting.
+
+        Multiple returns are intentional - each tier has early exit conditions
+        for optimal performance (short-circuiting pattern).
+
+        Args:
+            query: Query string to resolve
+            context: Optional filtering context
+            top_k: Maximum candidates to return
+
+        Returns:
+            List of candidates ordered by score (descending)
+        """
+        # Fast reject for empty/whitespace queries
+        if not query or not query.strip():
+            return []
+
+        # Truncate long queries (DoS protection)
+        if len(query) > 1000:
+            query = query[:1000]
+
+        # Normalize once for all matchers
+        normalized = self.normalizer.normalize(query)
+
+        # Empty after normalization? (e.g., only punctuation)
+        if not normalized:
+            return []
+
+        # TIER 1: Deterministic exact matches (STOP if found)
+
+        # Try exact code first (fastest)
+        candidates = self.exact_code.match(query, normalized, context=context)
+        if candidates:
+            return candidates  # Single match, high confidence, STOP
+
+        # Try canonical name
+        candidates = self.canonical_name.match(query, normalized, context=context)
+        if candidates:
+            return candidates  # Single match, high confidence, STOP
+
+        # TIER 2: Exact alias (may be multiple, continue if ambiguous)
+        candidates = self.alias_exact.match(query, normalized, context=context)
+        if len(candidates) == 1:
+            return candidates  # Unambiguous, STOP
+        elif len(candidates) > 1:
+            # Ambiguous - return multiple for calibration to decide
+            return candidates[:top_k]
+
+        # TIER 3: FTS + Fuzzy (ranked candidates)
+
+        # FTS returns top-50
+        fts_candidates = self.fts.match(query, normalized, limit=50, context=context)
+
+        if not fts_candidates:
+            return []  # No matches
+
+        # Fuzzy refines to top-K
+        refined = self.fuzzy.match(
+            query, normalized, limit=top_k, fts_candidates=fts_candidates
+        )
+
+        return refined

resolvekit/matchers/code_validators.py

@@ -0,0 +1,250 @@
+"""Code system validators for format validation and normalization."""
+
+import re
+from typing import TYPE_CHECKING
+
+from resolvekit.types import CodeSystem
+
+if TYPE_CHECKING:
+    from resolvekit.matchers.protocols import CodeValidatorProtocol
+
+
+class ISO2Validator:
+    """Validator for ISO 3166-1 alpha-2 codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate ISO2 format (2 letters)."""
+        if len(value) != 2 or not value.isalpha():
+            return False, "ISO2 must be 2 letters"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class ISO3Validator:
+    """Validator for ISO 3166-1 alpha-3 codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate ISO3 format (3 letters)."""
+        if len(value) != 3 or not value.isalpha():
+            return False, "ISO3 must be 3 letters"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class ISONumericValidator:
+    """Validator for ISO 3166-1 numeric codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate ISO numeric format (3 digits)."""
+        if len(value) != 3 or not value.isdigit():
+            return False, "ISO numeric must be 3 digits"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize preserves digits."""
+        return value
+
+
+class DCIDValidator:
+    """Validator for Data Commons IDs."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate DCID format (prefix/identifier)."""
+        if "/" not in value:
+            return False, "DCID must contain '/'"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """DCIDs are case-sensitive, no normalization."""
+        return value
+
+
+class M49Validator:
+    """Validator for UN M49 region codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate M49 format (3 digits)."""
+        if len(value) != 3 or not value.isdigit():
+            return False, "M49 must be 3 digits"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize preserves digits."""
+        return value
+
+
+class ISO31662Validator:
+    """Validator for ISO 3166-2 subdivision codes."""
+
+    _PATTERN = re.compile(r"^[A-Z]{2}-[A-Z0-9]{1,3}$")
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate ISO 3166-2 format (CC-SSS)."""
+        if not self._PATTERN.match(value.upper()):
+            return False, "ISO3166-2 must be format CC-SSS (e.g., US-CA)"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class NUTSValidator:
+    """Validator for EU NUTS codes."""
+
+    _PATTERN = re.compile(r"^[A-Z]{2}[0-9A-Z]{0,3}$")
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate NUTS format (CC[0-9A-Z]{0,3})."""
+        if not self._PATTERN.match(value.upper()):
+            return False, "NUTS must be format CC[0-9A-Z]{0,3} (e.g., DE3, FR10)"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class LAUValidator:
+    """Validator for EU LAU codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate LAU format (variable by country)."""
+        # LAU format is variable, accept any non-empty string
+        if not value or not value.strip():
+            return False, "LAU code cannot be empty"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class PCodeValidator:
+    """Validator for OCHA P-codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate P-code format (variable format)."""
+        # P-codes have variable format, accept any non-empty alphanumeric
+        if not value or not value.strip():
+            return False, "P-code cannot be empty"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class WikidataValidator:
+    """Validator for Wikidata QIDs."""
+
+    _PATTERN = re.compile(r"^Q[0-9]+$")
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate Wikidata format (Q[0-9]+)."""
+        if not self._PATTERN.match(value.upper()):
+            return False, "Wikidata QID must be format Q[0-9]+ (e.g., Q30)"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class GeoNamesValidator:
+    """Validator for GeoNames IDs."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate GeoNames format (numeric ID)."""
+        if not value.isdigit():
+            return False, "GeoNames ID must be numeric"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize preserves digits."""
+        return value
+
+
+class WorldBankValidator:
+    """Validator for World Bank country codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate World Bank format (2-3 letters)."""
+        if len(value) not in (2, 3) or not value.isalpha():
+            return False, "World Bank code must be 2-3 letters"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+class DACValidator:
+    """Validator for OECD DAC codes."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate DAC format (numeric)."""
+        if not value.isdigit():
+            return False, "DAC code must be numeric"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize preserves digits."""
+        return value
+
+
+class FIPSValidator:
+    """Validator for FIPS codes (deprecated but still used)."""
+
+    def validate(self, value: str) -> tuple[bool, str | None]:
+        """Validate FIPS format (2 letters)."""
+        if len(value) != 2 or not value.isalpha():
+            return False, "FIPS must be 2 letters"
+        return True, None
+
+    def normalize(self, value: str) -> str:
+        """Normalize to uppercase."""
+        return value.upper()
+
+
+# Simple constant dict - no registration ceremony
+# Note: Using object type here to avoid circular import with protocols
+# All validators implement CodeValidatorProtocol structurally
+CODE_VALIDATORS: dict[CodeSystem, object] = {
+    CodeSystem.ISO2: ISO2Validator(),
+    CodeSystem.ISO3: ISO3Validator(),
+    CodeSystem.ISO_NUMERIC: ISONumericValidator(),
+    CodeSystem.DCID: DCIDValidator(),
+    CodeSystem.M49: M49Validator(),
+    CodeSystem.ISO3166_2: ISO31662Validator(),
+    CodeSystem.NUTS: NUTSValidator(),
+    CodeSystem.LAU: LAUValidator(),
+    CodeSystem.PCODE: PCodeValidator(),
+    CodeSystem.WIKIDATA: WikidataValidator(),
+    CodeSystem.GEONAMES: GeoNamesValidator(),
+    CodeSystem.WB: WorldBankValidator(),
+    CodeSystem.DAC: DACValidator(),
+    CodeSystem.FIPS: FIPSValidator(),
+}
+
+
+def get_validator(system: CodeSystem) -> "CodeValidatorProtocol":
+    """
+    Get validator for code system.
+
+    Args:
+        system: Code system enum value
+
+    Returns:
+        Validator instance implementing CodeValidatorProtocol
+
+    Raises:
+        KeyError: If code system not supported
+    """
+    return CODE_VALIDATORS[system]  # type: ignore[return-value]