resolvekit 0.1.8__tar.gz → 0.1.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: resolvekit
-Version: 0.1.8
+Version: 0.1.9
 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
@@ -14,6 +14,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Scientific/Engineering :: GIS
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
@@ -49,6 +50,14 @@ Description-Content-Type: text/markdown
 
 # resolvekit
 
+[![PyPI version](https://img.shields.io/pypi/v/resolvekit.svg)](https://pypi.org/project/resolvekit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/resolvekit.svg)](https://pypi.org/project/resolvekit/)
+[![License: MIT](https://img.shields.io/pypi/l/resolvekit.svg)](https://github.com/jm-rivera/resolvekit/blob/main/LICENSE)
+[![Tests](https://github.com/jm-rivera/resolvekit/actions/workflows/test.yml/badge.svg)](https://github.com/jm-rivera/resolvekit/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-jm--rivera.github.io-blue.svg)](https://jm-rivera.github.io/resolvekit/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 Resolve messy place and entity strings — and codes — to canonical entity IDs, offline and deterministically. Feed it `"Brasil"`, `"Cote dIvoire"`, or `"Republic of Korea"` and get back `country/BRA`, `country/CIV`, `country/KOR`.
 
 - **Offline and deterministic.** No network call, no LLM, no external service at resolution time. The same input gives the same output, today and next year.

{resolvekit-0.1.8 → resolvekit-0.1.9}/README.md

@@ -1,5 +1,13 @@
 # resolvekit
 
+[![PyPI version](https://img.shields.io/pypi/v/resolvekit.svg)](https://pypi.org/project/resolvekit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/resolvekit.svg)](https://pypi.org/project/resolvekit/)
+[![License: MIT](https://img.shields.io/pypi/l/resolvekit.svg)](https://github.com/jm-rivera/resolvekit/blob/main/LICENSE)
+[![Tests](https://github.com/jm-rivera/resolvekit/actions/workflows/test.yml/badge.svg)](https://github.com/jm-rivera/resolvekit/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-jm--rivera.github.io-blue.svg)](https://jm-rivera.github.io/resolvekit/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 Resolve messy place and entity strings — and codes — to canonical entity IDs, offline and deterministically. Feed it `"Brasil"`, `"Cote dIvoire"`, or `"Republic of Korea"` and get back `country/BRA`, `country/CIV`, `country/KOR`.
 
 - **Offline and deterministic.** No network call, no LLM, no external service at resolution time. The same input gives the same output, today and next year.

{resolvekit-0.1.8 → resolvekit-0.1.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "resolvekit"
-version = "0.1.8"
+version = "0.1.9"
 description = "Entity and place resolution system that maps messy place/entity strings and codes to canonical entities"
 requires-python = ">=3.12"
 
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3 :: Only",
     "Topic :: Scientific/Engineering :: GIS",
     "Topic :: Scientific/Engineering :: Information Analysis",
@@ -158,6 +159,8 @@ dev = [
     "ruff>=0.15.12",
     "ty>=0.0.32",
     "pandas-stubs>=3.0.0.260204",
+    "pandas>=2.0",
+    "polars>=1.40.1",
 ]
 test = [
     "pytest>=9.0.3",

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/_polars_integration.py

@@ -203,14 +203,14 @@ def register() -> None:
             struct_expr = pl.struct([self._expr.alias("__value__"), *ctx_exprs])
 
             def _apply_struct(struct_series: pl.Series) -> pl.Series:
-                # Unpack struct fields back into individual Series.
-                rows = struct_series.to_list()  # list[dict]
-                value_list = [r["__value__"] for r in rows]
+                # Unpack struct fields column-oriented; avoids materialising N dicts.
+                unpacked = struct_series.to_frame("__s").unnest("__s")
+                value_list = unpacked["__value__"].to_list()
 
                 # Build a per-row context dict where per-row keys map to lists.
                 per_row_ctx: dict[str, object] = dict(_scalar_ctx)
                 for k in ctx_field_names:
-                    per_row_ctx[k] = [r[f"__ctx_{k}"] for r in rows]
+                    per_row_ctx[k] = unpacked[f"__ctx_{k}"].to_list()
 
                 result = _bulk_dispatch(
                     resolver=resolver,

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/core/api/bulk.py

@@ -839,23 +839,23 @@ def _bulk_dispatch(
     # Warn only when the column is wholly empty among resolved rows — a partial
     # miss (some resolved rows have a value) is not warned.
     if spec_active and effective_spec is not None:
-        resolved_indices = [
-            i for i, r in enumerate(out_source) if r.status == ResolutionStatus.RESOLVED
-        ]
-        if resolved_indices:
-            n_missing = sum(1 for i in resolved_indices if out_values[i] is None)
-            if n_missing > 0 and n_missing == len(resolved_indices):
-                chain_repr = [t.raw for t in effective_spec.chain]
-                # stacklevel=4 points at Resolver.bulk for the direct path;
-                # the module-level resolvekit.bulk convenience adds one more frame.
-                warnings.warn(
-                    f"default output {chain_repr!r}: {n_missing} resolved value(s) "
-                    f"had no output (column wholly empty among resolved rows)",
-                    UserWarning,
-                    stacklevel=4,
-                )
+        n_resolved = n_missing = 0
+        for r, v in zip(out_source, out_values, strict=True):
+            if r.status == ResolutionStatus.RESOLVED:
+                n_resolved += 1
+                if v is None:
+                    n_missing += 1
+        if n_resolved > 0 and n_missing == n_resolved:
+            chain_repr = [t.raw for t in effective_spec.chain]
+            # stacklevel=4 points at Resolver.bulk for the direct path;
+            # the module-level resolvekit.bulk convenience adds one more frame.
+            warnings.warn(
+                f"default output {chain_repr!r}: {n_missing} resolved value(s) "
+                f"had no output (column wholly empty among resolved rows)",
+                UserWarning,
+                stacklevel=4,
+            )
 
-    # Return a native series (not BulkResult) when pivoting and output="series".
     scalar_to = (has_pivot or spec_active) and output == "series"
 
     if scalar_to:
@@ -886,12 +886,9 @@ def _bulk_dispatch(
         return BulkResult(values=native, source=out_source, kind=kind)
 
     if output == "frame":
-        # Flat DataFrame: one column per record field.
-        records = [
-            _record_from_result(r, v)
-            for r, v in zip(out_source, out_values, strict=True)
-        ]
-        native = _build_frame_native(records, kind, orig_index=orig_index)
+        # Flat DataFrame: one column per record field, built column-oriented.
+        frame_cols = _frame_columns_from_output(out_source, out_values)
+        native = _build_frame_native(frame_cols, kind, orig_index=orig_index)
         return BulkResult(values=native, source=out_source, kind=kind)
 
     # Default: wrap the native series of pivot/result values in BulkResult.
@@ -964,27 +961,65 @@ def _build_records_native(
     return records
 
 
+def _frame_columns_from_output(
+    out_source: list[ResolutionResult],
+    out_values: list[Any],
+) -> dict[str, list[Any]]:
+    """Build column-oriented data for ``output='frame'`` without a N-dict intermediate."""
+    col_value: list[Any] = []
+    col_status: list[Any] = []
+    col_entity_id: list[Any] = []
+    col_confidence: list[Any] = []
+    col_pack_id: list[Any] = []
+    col_query_text: list[Any] = []
+    for r, v in zip(out_source, out_values, strict=True):
+        if isinstance(v, ResolutionResult):
+            col_value.append(v.entity_id)
+        else:
+            col_value.append(v)
+        col_status.append(r.status.value)
+        col_entity_id.append(r.entity_id)
+        col_confidence.append(r.confidence)
+        col_pack_id.append(r.pack_id)
+        col_query_text.append(r.query_text)
+    return {
+        "value": col_value,
+        "status": col_status,
+        "entity_id": col_entity_id,
+        "confidence": col_confidence,
+        "pack_id": col_pack_id,
+        "query_text": col_query_text,
+    }
+
+
 def _build_frame_native(
-    records: list[dict[str, Any]],
+    columns: dict[str, list[Any]],
     kind: _InputKind,
     *,
     orig_index: Any,
 ) -> Any:
     """DataFrame assembly for ``output='frame'``.
 
+    Accepts column-oriented data (dict of column-name → value list) rather than
+    a list-of-dicts, so no N-dict intermediate is ever allocated.
+
     For pandas/polars, returns a DataFrame.  For non-DataFrame inputs (list,
-    tuple, numpy), falls back to the same list-of-dicts representation as
-    ``output='record'``.
+    tuple, numpy), falls back to a list-of-dicts to preserve existing behaviour.
     """
     if kind == "pandas":
         import pandas as pd
 
-        return pd.DataFrame.from_records(records, index=orig_index)
+        return pd.DataFrame(columns, index=orig_index)
     if kind == "polars":
         import polars as pl
 
-        return pl.DataFrame(records)
-    return records
+        return pl.DataFrame(columns)
+    # Non-DataFrame kinds: reconstruct list-of-dicts for backward compatibility.
+    col_names = list(columns)
+    col_lists = [columns[k] for k in col_names]
+    return [
+        dict(zip(col_names, row, strict=True)) for row in zip(*col_lists, strict=True)
+    ]
 
 
 def _build_native(

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/core/engine/_stages.py

@@ -299,7 +299,7 @@ def add_evidence_to_candidates(
         if candidate is None:
             continue
 
-        candidate.sources = [*candidate.sources, ev]
+        candidate.sources.append(ev)
         merged_signals = {**candidate.retrieval.signals, **ev.signals}
 
         # Check if new evidence has better score
@@ -384,7 +384,7 @@ def should_stop_generation(
     Returns:
         True if pipeline should stop generating candidates.
     """
-    if not config:
+    if not config or not config.stop_conditions:
         return False
 
     candidate_count = len(evidence_by_entity)

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

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 import time
 import traceback
-from collections import defaultdict
+from collections import OrderedDict, defaultdict
 from collections.abc import Callable
 from datetime import date
 from typing import TYPE_CHECKING, Literal
@@ -46,6 +46,11 @@ from resolvekit.core.store.store_view import StoreView
 
 logger = logging.getLogger(__name__)
 
+# Maximum number of distinct entity_type_prefixes filter keys retained in the
+# per-runner suggest-names LRU cache.  Each slot can hold ~1-7 MB of name
+# tuples; 8 slots is well under typical process RSS budgets.
+_SUGGEST_NAMES_CACHE_MAX = 8
+
 
 class PipelineRunner:
     """The core resolution pipeline runner.
@@ -114,11 +119,12 @@ class PipelineRunner:
             country_relation_prefixes=country_relation_prefixes,
         )
         self._view = StoreView([(pack_id, store)] if store is not None else [])
-        # Lazy cache for suggest_prefix: maps entity_type_prefixes key → name list.
-        # Built on first suggest call; never warmed in __init__ (cold-start is measured).
-        self._suggest_names_cache: dict[
+        # Bounded LRU cache for suggest names: maps entity_type_prefixes key →
+        # name list. Capped at _SUGGEST_NAMES_CACHE_MAX entries; oldest entry
+        # evicted when full. Each entry holds up to ~25k tuples (~1-7 MB).
+        self._suggest_names_cache: OrderedDict[
             frozenset[str] | None, list[tuple[str, str, str, bool, str]]
-        ] = {}
+        ] = OrderedDict()
 
     def warm(self) -> None:
         """Eagerly build all lazily-constructed source indexes.
@@ -486,7 +492,7 @@ class PipelineRunner:
                             # store's entity_type_exclude_prefixes parameter
                             # so the size check reflects only fuzzy-eligible
                             # name rows.
-                            self._suggest_names_cache[names_key] = list(
+                            _names = list(
                                 store.iter_suggest_names(
                                     entity_type_exclude_prefixes=FUZZY_DENYLIST_PREFIXES
                                 )
@@ -495,20 +501,30 @@ class PipelineRunner:
                             # Store doesn't support the exclude param — fall
                             # back to unfiltered.  This means auto-fuzzy will
                             # be suppressed on packs with > 20k total names.
-                            self._suggest_names_cache[names_key] = list(
+                            _names = list(
                                 store.iter_suggest_names(entity_type_prefixes=None)
                             )
+                        self._suggest_names_cache[names_key] = _names
+                        if len(self._suggest_names_cache) > _SUGGEST_NAMES_CACHE_MAX:
+                            self._suggest_names_cache.popitem(last=False)
+                    else:
+                        self._suggest_names_cache.move_to_end(names_key)
                 else:
                     names_key = entity_type_prefixes
                     if names_key not in self._suggest_names_cache:
                         try:
-                            self._suggest_names_cache[names_key] = list(
+                            _names = list(
                                 store.iter_suggest_names(
                                     entity_type_prefixes=entity_type_prefixes
                                 )
                             )
                         except NotImplementedError:
-                            self._suggest_names_cache[names_key] = []
+                            _names = []
+                        self._suggest_names_cache[names_key] = _names
+                        if len(self._suggest_names_cache) > _SUGGEST_NAMES_CACHE_MAX:
+                            self._suggest_names_cache.popitem(last=False)
+                    else:
+                        self._suggest_names_cache.move_to_end(names_key)
                 names_list = self._suggest_names_cache[names_key]
 
                 run_fuzzy = fuzzy == "always" or (

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/core/parse/offsets.py

@@ -69,6 +69,9 @@ from resolvekit.core.util.normalization import (
 _WHITESPACE: re.Pattern[str] = re.compile(r"\s+")
 _PUNCTUATION: re.Pattern[str] = re.compile(r"[^\w\s\-']")
 _DIGITS: re.Pattern[str] = re.compile(r"\d")
+_HTML_ENTITY_RE: re.Pattern[str] = re.compile(
+    r"&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);"
+)
 
 
 def _assert_supported_profile(profile: NormalizationProfile) -> None:
@@ -162,12 +165,11 @@ def _apply_html_unescape(text: str, starts: list[int], ends: list[int]) -> _Stat
     Each entity (``&``, ``'``, etc.) decodes to one or more chars that
     all carry the raw span of the whole entity token.
     """
-    _entity_re = re.compile(r"&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);")
 
     def _decode(m: re.Match[str]) -> str:
         return html.unescape(m.group(0))
 
-    return _apply_regex_sub(text, starts, ends, _entity_re, _decode)
+    return _apply_regex_sub(text, starts, ends, _HTML_ENTITY_RE, _decode)
 
 
 def _apply_markdown_strip(text: str, starts: list[int], ends: list[int]) -> _State:

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

@@ -403,7 +403,9 @@ class SQLiteEntityStore(EntityStore):
                 return None
 
             name_rows = conn.execute(
-                "SELECT * FROM names WHERE entity_id = ?", (entity_id,)
+                "SELECT value, value_norm, name_kind, lang, is_preferred"
+                " FROM names WHERE entity_id = ?",
+                (entity_id,),
             ).fetchall()
 
             names = [
@@ -451,10 +453,9 @@ class SQLiteEntityStore(EntityStore):
                 for r in relation_rows
             ]
 
-            # Parse attrs_json if present
+            # Parse attrs_json if present (column absent in older stores).
             attrs: dict[str, Any] = {}
-            row_dict = dict(row)
-            if attrs_json := row_dict.get("attrs_json"):
+            if "attrs_json" in row.keys() and (attrs_json := row["attrs_json"]):  # noqa: SIM118 — sqlite3.Row iterates values, not keys
                 with contextlib.suppress(json.JSONDecodeError):
                     attrs = json.loads(attrs_json)
 
@@ -604,7 +605,8 @@ class SQLiteEntityStore(EntityStore):
                 ).fetchall()
 
                 name_rows = conn.execute(
-                    f"SELECT * FROM names WHERE entity_id IN ({placeholders})",
+                    f"SELECT entity_id, value, value_norm, name_kind, lang,"
+                    f" is_preferred FROM names WHERE entity_id IN ({placeholders})",
                     chunk,
                 ).fetchall()
 
@@ -661,10 +663,9 @@ class SQLiteEntityStore(EntityStore):
                         for r in relations_by_entity.get(eid, [])
                     ]
 
-                    # Parse attrs_json if present
+                    # Parse attrs_json if present (column absent in older stores).
                     attrs: dict[str, Any] = {}
-                    row_dict = dict(row)
-                    if attrs_json := row_dict.get("attrs_json"):
+                    if "attrs_json" in row.keys() and (attrs_json := row["attrs_json"]):  # noqa: SIM118 — sqlite3.Row iterates values, not keys
                         with contextlib.suppress(json.JSONDecodeError):
                             attrs = json.loads(attrs_json)
 

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/packs/geo/sources/fuzzy_retrieval.py

@@ -1,5 +1,7 @@
 """Fuzzy retrieval source for geo entities."""
 
+from typing import override
+
 from resolvekit.core.model import CandidateEvidence, GenerationContext, MatchTier
 from resolvekit.packs.geo.sources._short_input import short_input_blocked
 from resolvekit.packs.geo.sources.symspell import _is_small_only_entity_types
@@ -39,6 +41,15 @@ class GeoFuzzyRetrievalSource(FuzzyRetrievalSource):
         )
         self._large_tier = large_tier
 
+    @override
+    def warm(self) -> None:
+        # The LARGE tier (admin2-5 / cities) is built lazily on first use; eagerly
+        # warming it loads ~800 MB for workloads that never issue a LARGE-tier
+        # query. SMALL tier is cheap and warms normally.
+        if self._large_tier:
+            return
+        super().warm()
+
     def generate(self, ctx: GenerationContext) -> list[CandidateEvidence]:
         """Skip retrieval for degenerate inputs that should never match a geo
         entity (single letters, lowercase short alpha, ``#N/A``-style noise).

{resolvekit-0.1.8 → resolvekit-0.1.9}/src/resolvekit/packs/geo/sources/symspell.py

@@ -216,6 +216,15 @@ class GeoSymSpellSource(SymSpellSource):
             )
         return records
 
+    @override
+    def warm(self) -> None:
+        # The LARGE tier (admin2-5 / cities) is built lazily on first use; eagerly
+        # warming it loads ~800 MB for workloads that never issue a LARGE-tier
+        # query. SMALL tier is cheap and warms normally.
+        if self._large_tier:
+            return
+        super().warm()
+
     def generate(self, ctx: GenerationContext) -> list[CandidateEvidence]:
         """Skip typo correction for obvious code-like inputs and degenerate
         short/noise inputs (single letters, ``#N/A``).