resolvekit 0.1.4__tar.gz → 0.1.6__tar.gz

{resolvekit-0.1.4 → resolvekit-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: resolvekit
-Version: 0.1.4
+Version: 0.1.6
 Summary: Entity and place resolution system that maps messy place/entity strings and codes to canonical entities
 Keywords: entity-resolution,geocoding,place-names,data-commons,iso-codes,offline,disambiguation,normalization
 Author: Jorge Rivera

{resolvekit-0.1.4 → resolvekit-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "resolvekit"
-version = "0.1.4"
+version = "0.1.6"
 description = "Entity and place resolution system that maps messy place/entity strings and codes to canonical entities"
 requires-python = ">=3.12"
 

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/core/api/loading/module_catalog.py

@@ -134,41 +134,26 @@ def _load_and_separate_datapacks(
     return base_packs, overlay_packs
 
 
-def _remote_dependency_uncached(
-    module_id: str,
-    available: dict[str, Path],
-    manifest_overrides: dict[str, dict[str, object]],
-) -> bool:
-    """Return True if ``module_id`` is a remote-distribution module whose data
-    is not in the local cache.
-
-    Such a dependency may be absent from a load set without error: remote
-    packs the user hasn't downloaded are not hard errors (partial caches are
-    first-class, and ``Resolver.auto()`` never triggers a network fetch).
-    Bundled dependencies and unknown module ids stay hard errors.
-    """
-    from resolvekit.core.module_registry import load_module_metadata
-    from resolvekit.core.remote import is_cached
-
-    if module_id not in available:
-        return False
-    path = available[module_id]
-    if not (path / "metadata.json").exists():
-        return False
-    metadata = load_module_metadata(module_id, path, overrides=manifest_overrides)
-    return metadata.distribution == "remote" and not is_cached(metadata)
-
-
 def _validate_module_dependencies(
     base_packs: dict[str, LoadedDataPack],
     overlay_packs: dict[str, LoadedDataPack],
     pack_filter: set[str],
 ) -> None:
-    from resolvekit.core.module_registry import get_manifest_overrides
-
+    """Log any declared ``module_dependencies`` absent from the load set.
+
+    ``module_dependencies`` are advisory cross-reference links, not hard load
+    requirements. An explicit selection is authoritative and ``auto()`` loads
+    whatever is locally available, so a declared dependency not being in the
+    load set is expected — partial loads are first-class, a deployed image may
+    ship a subset, and a dependency may simply not be installed in this
+    environment. None of that is an error here; it is logged for diagnostics.
+
+    (Naming an unknown module in the *request* is a different matter — that
+    raises ``DataModuleNotFoundError`` from :func:`_resolve_requested_module_paths`.
+    Hard structural requirements, overlay → base, are enforced separately by
+    :func:`_validate_overlay_relationships`.)
+    """
     available_module_ids = set(base_packs) | set(overlay_packs)
-    registry: dict[str, Path] | None = None
-    manifest_overrides: dict[str, dict[str, object]] | None = None
     for loaded in [*base_packs.values(), *overlay_packs.values()]:
         if pack_filter and loaded.pack_id not in pack_filter:
             continue
@@ -179,23 +164,12 @@ def _validate_module_dependencies(
             if module_id not in available_module_ids
         ]
         if missing:
-            # An absent dependency is only a hard error when its data could
-            # have been loaded — a declared dep on a remote pack the user
-            # hasn't downloaded is skipped, mirroring the auto-mode intent in
-            # _resolve_requested_module_paths.
-            if registry is None:
-                registry = list_available_modules()
-                manifest_overrides = get_manifest_overrides()
-            assert manifest_overrides is not None
-            missing = [
-                module_id
-                for module_id in missing
-                if not _remote_dependency_uncached(
-                    module_id, registry, manifest_overrides
-                )
-            ]
-        if missing:
-            raise MissingModuleDependencyError(loaded.module_id, missing)
+            logger.debug(
+                "Module %s declares dependencies absent from the load set: %s "
+                "(advisory; honoring authoritative selection)",
+                loaded.module_id,
+                ", ".join(sorted(missing)),
+            )
 
 
 def _validate_overlay_relationships(
@@ -290,29 +264,23 @@ def _resolve_requested_module_paths(
         resolved[module_id] = path
 
         metadata = load_module_metadata(module_id, path, overrides=manifest_overrides)
-        for dependency in metadata.module_dependencies:
-            if dependency in resolved:
-                continue
-            # In auto mode, silently skip dependencies whose data isn't
-            # locally available (remote packs the user hasn't downloaded
-            # are not hard errors — see v1-scope §225). In explicit mode,
-            # likewise skip remote-uncached dependencies so requesting one
-            # module never transitively forces sibling downloads; unknown
-            # module ids are still queued so the queue-loop's own
-            # ``module_id not in available`` check raises
-            # ``DataModuleNotFoundError``.
-            if auto_mode and (
-                dependency not in available
-                or not _module_data_locally_available(
+        # ``module_dependencies`` are advisory cross-reference links, not load
+        # requirements. Expand them only in auto() mode, where the load set is
+        # "everything locally available" anyway (silently skipping remote packs
+        # the user hasn't downloaded — see v1-scope §225). Explicit ``module_ids``
+        # are AUTHORITATIVE: the load set is exactly what the caller named (plus
+        # overlay bases, which are structural), independent of cache or on-disk
+        # state — so resolution is identical on a dev box with extra packs
+        # downloaded and on a lean deployment that bakes only the named modules.
+        if auto_mode:
+            for dependency in metadata.module_dependencies:
+                if dependency in resolved:
+                    continue
+                if dependency not in available or not _module_data_locally_available(
                     dependency, available[dependency], manifest_overrides
-                )
-            ):
-                continue
-            if not auto_mode and _remote_dependency_uncached(
-                dependency, available, manifest_overrides
-            ):
-                continue
-            queue.append(dependency)
+                ):
+                    continue
+                queue.append(dependency)
         if metadata.is_overlay:
             for dependency in metadata.base_module_ids or []:
                 if dependency in resolved:

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/core/api/resolver.py

@@ -882,7 +882,16 @@ class Resolver:
 
         Args:
             module_ids: Specific module IDs to load (e.g. ``["geo.countries"]``).
-                Pass ``None`` to load all installed modules (same as ``auto()``).
+                Authoritative: the load set is exactly these modules. Declared
+                ``module_dependencies`` are advisory cross-references and are
+                NOT auto-loaded — name every module you want (e.g.
+                ``["geo.cities", "geo.countries"]`` for city resolution backed
+                by country context). The load set therefore depends only on this
+                argument, never on which packs happen to be cached or shipped,
+                so resolution is identical on a dev box and a lean deployment.
+                Overlay base modules are the one exception (an overlay is not a
+                standalone dataset, so its base is always pulled in). Pass
+                ``None`` to load all installed modules (same as ``auto()``).
             domains: Which domain packs to enable (default: all in modules).
             routing_mode: How to route queries (see ``Resolver.__init__`` for full docs).
             trace: Whether to collect trace events.
@@ -1032,8 +1041,9 @@ class Resolver:
         )
 
     # -- Country-level geo module IDs for the lite preset --
-    # Deliberately excludes geo.admin1 and deeper tiers whose dependency
-    # chains (admin2, admin3, cities …) trigger heavy SQLite composition.
+    # Deliberately excludes geo.admin1 and the deeper admin / cities tiers to
+    # keep cold-start time and resident memory small. Selection is authoritative,
+    # so the load set is exactly these IDs — naming a tier loads only that tier.
     # To add admin-1 coverage, pass module_ids=["geo.countries", "geo.admin1"].
     _LITE_GEO_MODULE_IDS: tuple[str, ...] = (
         "geo.countries",

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/core/engine/suggest_rank.py

@@ -236,6 +236,7 @@ def fuzzy_candidates(
     names: list[tuple[str, str, str, bool, str]],
     *,
     top_k: int,
+    choices: list[str] | None = None,
 ) -> list[SuggestCandidate]:
     """Run brute-force RapidFuzz over a pre-materialized name list.
 
@@ -252,6 +253,12 @@ def fuzzy_candidates(
             value)`` 5-tuples — typically the memoized output of
             ``store.iter_suggest_names()``.
         top_k: Number of results the caller ultimately wants.
+        choices: Optional pre-extracted list of ``value_norm`` strings
+            (``[row[0] for row in names]``).  When provided, the per-call
+            list comprehension is skipped — callers that memoize the name list
+            should also memoize and pass ``choices`` to avoid a 25k-string
+            rebuild on every query.  When ``None`` (default), the list is
+            built from ``names`` as before (backward-compatible).
 
     Returns:
         List of ``SuggestCandidate`` objects (one per distinct matched name row,
@@ -268,8 +275,9 @@ def fuzzy_candidates(
 
     fuzzy_pool = min(max(top_k * 5, 50), 500)
 
-    # Extract just the value_norm strings for RapidFuzz.
-    choices = [row[0] for row in names]
+    # Use caller-supplied choices when available to avoid a per-call rebuild.
+    if choices is None:
+        choices = [row[0] for row in names]
 
     raw_hits = process.extract(
         query_norm,

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/packs/custom/pack.py

@@ -21,6 +21,7 @@ from resolvekit.packs.custom.sources import (
     CustomExactCodeSource,
     CustomExactNameSource,
     CustomFTSSource,
+    CustomFuzzyRetrievalSource,
     CustomFuzzySource,
 )
 
@@ -44,13 +45,22 @@ class GenericPack:
     custom entities, etc.).
 
     Sources (in pipeline order):
-    1. CustomExactCodeSource  — catch-all ``lookup_code_any``; raw 1.0
-    2. CustomExactNameSource  — canonical raw 1.0, alias raw 0.95
-    3. CustomFTSSource        — BM25 ranked FTS
-    4. CustomFuzzySource      — reranks existing candidates (requires_existing_candidates)
-
-    No SymSpell source: custom packs are built programmatically; the fuzzy
-    reranking over FTS/exact candidates serves as the fuzzy story.
+    1. CustomExactCodeSource        — catch-all ``lookup_code_any``; raw 1.0
+    2. CustomExactNameSource        — canonical raw 1.0, alias raw 0.95
+    3. CustomFTSSource              — BM25 ranked FTS
+    4. CustomFuzzyRetrievalSource   — generating brute-force RapidFuzz over the
+                                      store's materialized name list; emits
+                                      FUZZY-tier evidence so typo'd queries that
+                                      FTS cannot tokenize-match still produce
+                                      candidates.  Free on exact-name queries
+                                      (engine fuzzy-skip guard bypasses it when
+                                      a confident EXACT_NAME candidate is present).
+                                      Callers needing stricter precision can raise
+                                      ``confidence_threshold`` above the 0.89 FUZZY
+                                      cap to suppress fuzzy-tier results.
+    5. CustomFuzzySource            — reranks existing candidates with
+                                      ``fuzzy_edit_sim`` / ``fuzzy_token_sim``
+                                      signals (requires_existing_candidates)
 
     Args:
         symspell_dict_path: Accepted but ignored to satisfy factory introspection.
@@ -70,6 +80,7 @@ class GenericPack:
             CustomExactCodeSource(),
             CustomExactNameSource(),
             CustomFTSSource(),
+            CustomFuzzyRetrievalSource(),
             CustomFuzzySource(),
         ]
 

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/packs/custom/sources/__init__.py

@@ -4,10 +4,12 @@ from resolvekit.packs.custom.sources.exact_code import CustomExactCodeSource
 from resolvekit.packs.custom.sources.exact_name import CustomExactNameSource
 from resolvekit.packs.custom.sources.fts import CustomFTSSource
 from resolvekit.packs.custom.sources.fuzzy import CustomFuzzySource
+from resolvekit.packs.custom.sources.fuzzy_retrieval import CustomFuzzyRetrievalSource
 
 __all__ = [
     "CustomExactCodeSource",
     "CustomExactNameSource",
     "CustomFTSSource",
+    "CustomFuzzyRetrievalSource",
     "CustomFuzzySource",
 ]

resolvekit-0.1.6/src/resolvekit/packs/custom/sources/fuzzy_retrieval.py

@@ -0,0 +1,17 @@
+"""Brute-force fuzzy retrieval source for custom entities."""
+
+from resolvekit.shared.sources import FuzzyRetrievalBruteSource
+
+
+class CustomFuzzyRetrievalSource(FuzzyRetrievalBruteSource):
+    """Generating fuzzy source for the custom domain.
+
+    Materializes the store's name list once and runs brute-force
+    RapidFuzz over it — no prebuilt SymSpell dictionary required.
+    Ordered before the rerank ``CustomFuzzySource`` so the engine
+    enriches its FUZZY-tier candidates with ``fuzzy_edit_sim`` /
+    ``fuzzy_token_sim`` signals before scoring.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(name="custom_fuzzy_retrieval", domain="custom")

{resolvekit-0.1.4 → resolvekit-0.1.6}/src/resolvekit/shared/sources/__init__.py

@@ -4,11 +4,15 @@ from resolvekit.shared.sources.code_helpers import evidence_from_code_hits
 from resolvekit.shared.sources.fts_base import BM25ScoreTiers, FTSSource
 from resolvekit.shared.sources.fuzzy_base import FuzzySource
 from resolvekit.shared.sources.fuzzy_retrieval_base import FuzzyRetrievalSource
+from resolvekit.shared.sources.fuzzy_retrieval_brute_base import (
+    FuzzyRetrievalBruteSource,
+)
 from resolvekit.shared.sources.symspell_base import SymSpellSource
 
 __all__ = [
     "BM25ScoreTiers",
     "FTSSource",
+    "FuzzyRetrievalBruteSource",
     "FuzzyRetrievalSource",
     "FuzzySource",
     "SymSpellSource",