resolvekit 0.1.6__tar.gz → 0.1.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: resolvekit
-Version: 0.1.6
+Version: 0.1.8
 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.6 → resolvekit-0.1.8}/pyproject.toml

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

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/api/containment_api.py

@@ -91,10 +91,12 @@ class ContainmentAPI:
                 break
             frontier = next_frontier
 
-        # Hydrate — drop entities the store can't resolve.
+        # Hydrate in one batch — bulk bypasses the per-entity SQLite LRU cache, which is
+        # acceptable here: within()'s result set is not reused across calls.
+        hydrated = self._runner.bulk_get_entities(result_ids)
         records: list[EntityRecord] = []
-        for eid in result_ids:
-            entity = self._runner.get_entity(eid)
+        for eid in result_ids:  # preserve BFS-collected order pre-sort
+            entity = hydrated.get(eid)  # None-on-missing: absent IDs skipped
             if entity is None:
                 continue
             if entity_type is not None and entity.entity_type not in entity_type:

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/byod/cache.py

@@ -19,11 +19,11 @@ A cache hit is ``dir.exists() and (dir / "metadata.json").exists()``.
 Atomicity and cleanup
 ---------------------
 On a cache miss the build writes to a sibling ``<key>.tmp`` directory, then
-``os.replace(tmp, dir)`` atomically moves it. The superseded temp dir is
-removed with ``shutil.rmtree(tmp, ignore_errors=True)`` (matching the pattern
-in ``composed_sqlite.py:326``).  When ``cache=False``, the build writes to a
-fresh temp directory that is NOT moved into the cache — it is kept for the
-resolver's lifetime.
+``commit_build`` promotes it to the final location (first-writer-wins: if a
+valid pack already exists at the target it is kept and the redundant build is
+discarded; a corrupt leftover without ``metadata.json`` is cleared first).
+When ``cache=False``, the build writes to a fresh temp directory that is NOT
+moved into the cache — it is kept for the resolver's lifetime.
 """
 
 from __future__ import annotations
@@ -168,20 +168,46 @@ def prepare_build_dir(key: str, *, cache: bool) -> tuple[Path, Path | None]:
 
 
 def commit_build(build_dir: Path, final_dir: Path) -> None:
-    """Atomically promote *build_dir* to *final_dir* and clean up.
+    """Promote *build_dir* into *final_dir*, tolerating an existing pack.
 
-    Uses ``os.replace(build_dir, final_dir)`` for an atomic last-writer-wins
-    swap.  If the parent of *final_dir* does not exist it is created first.
+    The cache key is a content hash, so a pack already present at *final_dir* —
+    left by a concurrent build, a retry, or a re-submit of identical content —
+    is equivalent to the one just built. First writer wins: an existing valid
+    pack is kept and *build_dir* is discarded. A corrupt leftover (a directory
+    without ``metadata.json``) is cleared and replaced.
+
+    ``os.replace`` cannot rename a directory onto a non-empty one (POSIX raises
+    ENOTEMPTY / EEXIST), so the swap is attempted optimistically and the
+    populated-target case is recovered below. An ``OSError`` that does not
+    correspond to a populated *final_dir* (e.g. ENOSPC, a permission error) is
+    re-raised rather than silently swallowed.
 
     Args:
         build_dir: Temp directory where the build was written.
         final_dir: Target cache directory (``cached_pack_dir(key)``).
     """
     final_dir.parent.mkdir(parents=True, exist_ok=True)
-    os.replace(build_dir, final_dir)
-    # Belt-and-suspenders cleanup: ``shutil.rmtree`` with ignore_errors=True
-    # handles both cases (build_dir doesn't exist after replace, or final_dir
-    # was clobbered by a concurrent write) without raising.
+    try:
+        os.replace(build_dir, final_dir)
+    except OSError:
+        if is_cache_hit(final_dir):
+            # A concurrent build, retry, or re-submit already committed an
+            # equivalent pack; keep it and drop our redundant build below.
+            pass
+        elif final_dir.exists():
+            # Corrupt/incomplete leftover (no metadata.json): clear it and move
+            # our build in. If another writer races a valid pack into the slot
+            # first, accept that pack rather than surfacing the error.
+            shutil.rmtree(final_dir, ignore_errors=True)
+            try:
+                os.replace(build_dir, final_dir)
+            except OSError:
+                if not is_cache_hit(final_dir):
+                    raise
+        else:
+            # final_dir is absent, so the failure was not "target populated"
+            # (e.g. ENOSPC, EACCES). Surface it instead of hiding it.
+            raise
     shutil.rmtree(build_dir, ignore_errors=True)
 
 

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/engine/interfaces.py

@@ -132,6 +132,10 @@ class ResolverBackend(Protocol):
         """Look up a fully hydrated entity by ID."""
         ...
 
+    def bulk_get_entities(self, entity_ids: list[str]) -> dict[str, EntityRecord]:
+        """Fetch multiple entities by ID; missing IDs are omitted from the result."""
+        ...
+
     def lookup_code(
         self,
         system: str,

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/engine/multi_runner.py

@@ -192,6 +192,10 @@ class MultiPackRunner:
         """Fetch a fully hydrated entity record from any backing store."""
         return self._view.get_entity(entity_id)
 
+    def bulk_get_entities(self, entity_ids: list[str]) -> dict[str, EntityRecord]:
+        """Fetch multiple entities by ID; missing IDs are omitted from the result."""
+        return self._view.bulk_get_entities(entity_ids)
+
     def normalize_code_value(
         self, system: str, value: str, *, pack_filter: frozenset[str] | None = None
     ) -> str:

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/engine/runner.py

@@ -178,6 +178,10 @@ class PipelineRunner:
         """Fetch a fully hydrated entity record from the configured store."""
         return self._view.get_entity(entity_id)
 
+    def bulk_get_entities(self, entity_ids: list[str]) -> dict[str, EntityRecord]:
+        """Fetch multiple entities by ID; missing IDs are omitted from the result."""
+        return self._view.bulk_get_entities(entity_ids)
+
     def normalize_code_value(
         self, system: str, value: str, *, pack_filter: frozenset[str] | None = None
     ) -> str:

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/store/interface.py

@@ -176,6 +176,15 @@ class EntityStore(ABC):
         """
         return frozenset()
 
+    def relation_types(self) -> frozenset[str] | None:
+        """Return the distinct relation types stored, or None if unknown.
+
+        None means "this store cannot characterize its relation types, so callers
+        must not prune it" — the default. SQL backends override with a concrete set
+        (possibly empty, meaning known to hold no relations).
+        """
+        return None
+
     def close(self) -> None:  # noqa: B027
         """Release resources held by this store.
 

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/store/sqlite.py

@@ -494,6 +494,17 @@ class SQLiteEntityStore(EntityStore):
             rows = conn.execute("SELECT DISTINCT system FROM codes").fetchall()
             return frozenset(r["system"] for r in rows)
 
+    @override
+    def relation_types(self) -> frozenset[str]:
+        with self._connection() as conn:
+            try:
+                rows = conn.execute(
+                    "SELECT DISTINCT relation_type FROM relations"
+                ).fetchall()
+            except sqlite3.OperationalError:
+                return frozenset()  # legacy DB with no relations table
+            return frozenset(r["relation_type"] for r in rows)
+
     def lookup_name_exact(
         self, value_norm: str, name_kinds: set[str] | None = None
     ) -> list[str]:

{resolvekit-0.1.6 → resolvekit-0.1.8}/src/resolvekit/core/store/store_view.py

@@ -23,6 +23,9 @@ class StoreView:
 
     def __init__(self, stores: list[tuple[str | None, EntityStore]]) -> None:
         self._stores = stores
+        self._relation_type_index: list[frozenset[str] | None] = [
+            store.relation_types() for _, store in self._stores
+        ]
 
     # ------------------------------------------------------------------
     # Entity fetch — first non-None wins; no dedup needed
@@ -36,6 +39,18 @@ class StoreView:
                 return entity
         return None
 
+    def bulk_get_entities(self, entity_ids: list[str]) -> dict[str, EntityRecord]:
+        """Return entities for *entity_ids*, first store wins per ID; missing IDs omitted."""
+        result: dict[str, EntityRecord] = {}
+        remaining = list(entity_ids)
+        for _, store in self._stores:
+            if not remaining:
+                break
+            found = store.bulk_get_entities(remaining)
+            result.update(found)
+            remaining = [eid for eid in remaining if eid not in result]
+        return result
+
     # ------------------------------------------------------------------
     # Lookups — dedup by entity_id, preserve first-seen order
     # ------------------------------------------------------------------
@@ -118,7 +133,10 @@ class StoreView:
         """
         seen: set[str] = set()
         result: list[str] = []
-        for _, store in self._stores:
+        for i, (_, store) in enumerate(self._stores):
+            rv = self._relation_type_index[i]
+            if rv is not None and relation_type not in rv:
+                continue
             for eid in store.get_reverse_relations(
                 entity_id, relation_type, as_of=as_of
             ):
@@ -136,7 +154,10 @@ class StoreView:
     ) -> frozenset[str]:
         """Return target entity IDs for relations active on *as_of*, unioned."""
         result: set[str] = set()
-        for _, store in self._stores:
+        for i, (_, store) in enumerate(self._stores):
+            rv = self._relation_type_index[i]
+            if rv is not None and relation_type not in rv:
+                continue
             result.update(store.get_relations_as_of(entity_id, relation_type, as_of))
         return frozenset(result)