Module-level API¶

As of v0.1.

The functions below are the primary entry point for most use cases. They share a singleton Resolver created on first call — you don't instantiate anything. Import convention throughout this reference:

import resolvekit as rk

Functions¶

resolve¶

rk.resolve(
    text: str,
    *,
    to: str | None = UNSET,
    as_result: bool = False,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    from_system: str | None = None,
    include_entity: bool = True,
    timeout: float | None = None,
) -> ResolutionResult | Any

Resolve a text string or code against all loaded modules.

Parameters

Returns

• A ResolutionResult when to=None or as_result=True, or when no default_to is configured and to is omitted.
• The pivot value directly (typically str | None) when to is set or a default_to is active.

Example — full result

>>> rk.resolve("Germany")
ResolutionResult(status='resolved', entity_id='country/DEU', confidence=≈0.91, pack_id='geo')

Example — pivot

>>> rk.resolve("DE", from_system="iso2", to="flag")
'🇩🇪'

resolve_id¶

rk.resolve_id(
    text: str,
    *,
    on_ambiguous: Literal["raise", "null", "best"] = "raise",
    from_system: str | None = None,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    timeout: float | None = None,
) -> str | None

Resolve text and return the entity ID string, or None on no match.

Parameters

Returns str | None — entity ID, or None when no match (or ambiguous with on_ambiguous="null").

Raises AmbiguousResolutionError when on_ambiguous="raise" and the query is ambiguous.

Example

>>> rk.resolve_id("United States")
'country/USA'
>>> rk.resolve_id("Cote dIvoire")
'country/CIV'
>>> rk.resolve_id("Congo", on_ambiguous="null")   # ambiguous → None
None
>>> rk.resolve_id("Congo", on_ambiguous="best")
'country/COD'

bulk¶

rk.bulk(
    *,
    values: list | tuple | dict | pd.Series | pl.Series | np.ndarray,
    to: str | None = UNSET,
    on_missing: Literal["raise", "null", "auto"] = UNSET,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    output: Literal["series", "record", "frame"] = "series",
    from_system: str | None = None,
    not_found: str = "null",
    on_error: Literal["raise", "null", "keep"] = "raise",
    on_ambiguous: Literal["null", "raise", "best"] = "null",
    crosswalk: Crosswalk | None = None,
) -> Any

Resolve a collection of values. Identical inputs are deduplicated automatically before the pipeline runs, so repeated values don't multiply the work.

See how to clean a DataFrame column for the automatic path, and how to reconcile a column with a review for the Crosswalk round-trip.

Parameters

Returns

• When to is set: the native shape (e.g. pd.Series, or a same-keyed dict for dict input) of pivot values.
• When to=None: a BulkResult.

Raises CrosswalkError when a crosswalk (built with strict=True, the default) maps a value to an entity ID that no loaded pack carries.

Example — pandas Series with pivot

>>> import pandas as pd
>>> rk.bulk(
...     values=pd.Series(["United States", "Brasil", "Cote dIvoire", "zzznotacountry"]),
...     to="iso3",
... )
0    USA
1    BRA
2    CIV
3    None
dtype: object

Example — list with custom not-found sentinel

>>> rk.bulk(values=["Germany", "zzz"], to="iso3", not_found="UNKNOWN")
['DEU', 'UNKNOWN']

Example — dict input (same keys back)

>>> rk.bulk(values={"hq": "France", "branch": "France", "other": "Germany"}, to="iso3")
{'hq': 'FRA', 'branch': 'FRA', 'other': 'DEU'}

Example — crosswalk overrides

>>> cw = rk.Crosswalk.from_dict({"Congo": "country/COG", "Atlantis": rk.IGNORE})
>>> rk.bulk(values=["Congo", "Atlantis", "France"], to="iso3", crosswalk=cw)
['COG', None, 'FRA']

snap¶

rk.snap(
    *,
    query: str,
    candidates: list[str],
    max_distance: float = 0.5,
    to: Any = None,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
) -> Any

Return the closest matching candidate from a caller-supplied list, or None when nothing clears the threshold.

snap is for constrained matching: you already know the valid options and want to map a messy input onto one of them. It differs from resolve, which searches the full installed catalog.

Parameters

Returns The best matching candidate (entity ID or pivot value), or None when below threshold.

Example

>>> rk.snap(query="Tanzanya", candidates=["country/TZA", "country/ZMB", "country/KEN"])
'country/TZA'
>>> rk.snap(query="Zzzzzzz", candidates=["country/TZA", "country/ZMB", "country/KEN"])
None

entity¶

rk.entity(
    text_or_id: str | None = None,
    *,
    alpha_2: str | None = None,
    alpha_3: str | None = None,
    numeric: str | None = None,
    iso2: str | None = None,
    iso3: str | None = None,
    dcid: str | None = None,
    domain: str | list[str] | None = None,
    **code_kwargs: str,
) -> EntityRecord | None

Look up a fully hydrated EntityRecord by name, entity ID, or code. Returns None when no match is found.

Parameters

Pass exactly one lookup — text_or_id or one code kwarg. Passing two code kwargs raises ValueError.

Returns EntityRecord or None.

Example

>>> rk.entity("France").entity_id
'country/FRA'
>>> rk.entity(iso2="JP").canonical_name
'Japan'
>>> rk.entity(wikidata="Q30").entity_id
'country/USA'

modules¶

rk.modules() -> list[ModuleInfo]

Return the full module catalog, sorted by module_id.

Each entry carries identity metadata and cache state. Bundled modules are always is_available=True. Remote modules are is_available=True only when their data is on disk.

Example

>>> [(m.module_id, m.distribution, m.is_available) for m in rk.modules()]
[
  ('geo.admin1', 'remote', False),
  ('geo.admin2', 'remote', False),
  ...
  ('geo.countries', 'bundled', True),
  ('org.companies', 'bundled', True),
  ...
]

ModuleInfo fields

download¶

rk.download(target: str, *, force: bool = False) -> dict[str, Path]

Download remote module data to the local cache.

Parameters

Returns dict[str, Path] mapping module_id → cache_path for each downloaded module.

See managing data packs for download patterns and offline configuration.

download_all¶

rk.download_all(*, force: bool = False) -> dict[str, Path]

Download all installed remote modules.

Parameters

Returns dict[str, Path] mapping module_id → cache_path.

configure¶

rk.configure(
    *,
    auto_download: bool | None = None,
    cache_dir: str | Path | None = None,
    default_to: str | list[str] | None = None,
    on_missing: Literal["raise", "null", "auto"] = UNSET,
) -> None

Set runtime defaults and discard the singleton resolver so the next call rebuilds with the new configuration.

Parameters

Raises

• UnknownOutputError — When default_to contains a malformed name: grammar token. Also raised immediately when a singleton resolver already exists and default_to names an unknown code system (deferred to next resolver build otherwise).

Example

import resolvekit as rk

rk.configure(default_to="iso3")
rk.resolve("France")         # → "FRA"
rk.bulk(values=["France", "Germany"], to="name")  # per-call to= overrides default

rk.configure(default_to=["iso3", "name"], on_missing="null")
rk.resolve("France")         # → "FRA"
rk.resolve("zzznotacountry") # → None  (no raise)

rk.configure(default_to=None)  # clear — resolves return ResolutionResult again

to¶

rk.to(
    output: str | list[str],
    *,
    on_missing: Literal["raise", "null", "auto"] = "auto",
) -> OutputView

Return an OutputView bound to the given output spec, using the singleton default resolver.

All resolution methods on the returned view apply output automatically — no need to pass to= on every call. The view is a lightweight forwarding object; it holds a reference to the same underlying resolver.

Parameters

Returns — OutputView.

Raises

• UnknownOutputError — When output contains a malformed token or names an unknown code system.

Example

import resolvekit as rk

iso3 = rk.to("iso3")
iso3.resolve("France")          # → "FRA"
iso3.resolve_id("France")       # → "country/FRA"  (entity ID, not pivoted)
iso3.bulk(values=["France", "Germany"])  # → ["FRA", "DEU"]

clear_cache¶

rk.clear_cache(target: str | None = None) -> None

Remove cached module data from disk.

Parameters

reset¶

rk.reset() -> None

Close and discard the singleton resolver. The next call to any resolution function constructs a fresh one via Resolver.auto().

warm¶

rk.warm() -> None

Build all lazily-constructed indexes in the singleton resolver now and block until they are ready. Idempotent — calling it again when indexes are already built returns immediately. Thread-safe.

By default, Resolver construction starts a background daemon thread that pre-builds the SymSpell typo index so the cost does not land on the first query. warm() is for servers and batch jobs that need the resolver to be fully ready before processing begins, rather than relying on background preparation.

Resolver.warm() is the same operation on an explicit resolver instance:

from resolvekit import Resolver

r = Resolver.auto()
r.warm()          # block here until all indexes are ready
r.resolve("France")   # no index-build latency

The module-level call warms the singleton resolver, constructing it first if it hasn't been created yet:

import resolvekit as rk

rk.warm()           # build the singleton resolver and all its indexes
rk.resolve("France")  # ready immediately

To skip background warm-up entirely and keep construction fully lazy, pass warm=False to any constructor:

r = Resolver.auto(warm=False)
r = Resolver.from_modules(module_ids=["geo.countries", "geo.admin1"], warm=False)

The compiled index cache reduces the SymSpell build cost from ~6 s to ~1.4 s on installs with remote data tiers (admin2–admin5, cities). The cache file is stored under <cache-dir>/compiled/ (the same directory as the remote data tiers; see configure(cache_dir=...)), keyed by the dictionary files and symspellpy version. It is generated locally and never downloaded. If the cache directory is read-only, the library silently skips writing it.

default¶

rk.default() -> Resolver

Return the singleton Resolver instance, creating it on first call. The same object is reused until reset() or configure() is called.

suggest¶

rk.suggest(
    prefix: str,
    *,
    top_k: int = 10,
    domain: str | list[str] | None = None,
    entity_type: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    to: str | list[str] | None = None,
    fuzzy: Literal["auto", "always", "never"] = "auto",
    timeout: float | None = None,
) -> list[SuggestionResult]

Return a ranked typeahead suggestion list for prefix. Delegates to Resolver.suggest on the singleton resolver.

Parameters

Returns — list[SuggestionResult], sorted best-first, length at most top_k. Never raises a verdict; an empty list means no suggestions.

Example

import resolvekit as rk

for s in rk.suggest("unit", top_k=3):
    print(s.canonical_name, s.entity_id)

parse¶

rk.parse(
    text: str,
    *,
    to: str | list[str] | None = None,
    include_nil: bool = False,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    confidence_threshold: float | None = None,
    timeout: float | None = None,
) -> ParseResult

Extract and link every pack-known entity mention in free text, returning character offsets and calibrated confidence for each span. Detection is dictionary-first over the loaded packs.

Parameters

Returns ParseResult.

Raises ImportError when the [parsing] extra is not installed.

Example

import resolvekit as rk   # pip install 'resolvekit[parsing]'

result = rk.parse("The summit in Nairobi gathered leaders from Kenya, Uganda and the United States.")
for e in result:
    if e.entity_id:
        print(f"{e.surface!r} [{e.start}:{e.end}] -> {e.entity_id} ({e.entity_type}) {e.confidence:.2f}")
# 'Kenya' [44:49] -> country/KEN (geo.country) 0.91
# 'Uganda' [51:57] -> country/UGA (geo.country) 0.91
# 'the United States' [62:79] -> country/USA (geo.country) 0.91

# Nairobi is NOT detected on a fresh install — cities are a remote pack, not bundled.
[(d.surface, d.reason) for d in result.dropped_spans]   # e.g. [('and', 'code_case_mismatch'), ('in', 'deny_list')]

# Pivot each linked entity to a code:
[(e.surface, e.output) for e in rk.parse("Travel from France to Brazil", to="iso3")]
# [('France', 'FRA'), ('Brazil', 'BRA')]

parse_bulk¶

rk.parse_bulk(
    *,
    values: list[str] | tuple | pd.Series | pl.Series,
    to: str | list[str] | None = None,
    include_nil: bool = False,
    domain: str | list[str] | None = None,
    context: ResolutionContext | dict | None = None,
    confidence_threshold: float | None = None,
    timeout: float | None = None,
) -> ParseResult

Extract entities from a collection of text strings. Each ParsedEntity carries a row_idx field identifying its source row.

Parameters

Returns ParseResult.

Raises

• ImportError — When the [parsing] extra is not installed.
• TypeError — When values is not a list, tuple, pd.Series, or pl.Series.

Example

import resolvekit as rk   # pip install 'resolvekit[parsing]'

df = rk.parse_bulk(values=["Visited Kenya and Peru", "Meeting in Japan"]).to_dataframe()
list(df.columns)
# ['row_idx', 'surface', 'entity_id', 'entity_type', 'pack_id', 'status', 'confidence', 'start', 'end', 'to']

Models¶

ResolutionResult¶

Frozen Pydantic model. Returned by resolve() (when to is not set) and by the Resolver class methods.

Fields

Convenience properties (delegate to entity; return None when entity is not populated)

Methods

Example

>>> r = rk.resolve("United States")
>>> r.status
<ResolutionStatus.RESOLVED: 'resolved'>
>>> r.entity_id
'country/USA'
>>> r.confidence
≈0.91
>>> r.is_resolved
True
>>> r.reasons
(<ReasonCode.EXACT_NAME_MATCH: 'exact_name_match'>,)

Explain

>>> print(r.explain(verbosity="full").as_text())
Resolution Scorecard
============================================================
Query: "United States"
Normalized: "united states"
Status: RESOLVED
Entity: country/USA
Confidence: 93.3%
Reasons: exact_name_match
Pack: geo
Match Tier: exact_name

EntityRecord¶

Frozen Pydantic model. Domain-neutral entity representation.

Fields

Convenience properties

Methods

Example

>>> e = rk.entity("Germany")
>>> e.entity_id
'country/DEU'
>>> e.iso3
'DEU'
>>> e.code("wikidata")
'Q183'
>>> e.aliases[:3]
['Alemanha', 'Alemania', 'Allemagne']
>>> e.attribute("source")
'datacommons'

Reading relations

>>> e = rk.entity("Germany")
>>> [(r.relation_type, r.target_id) for r in e.relations if r.relation_type == "member_of"][:3]
[('member_of', 'EuropeanUnion'), ('member_of', 'groups/NATO'), ('member_of', 'groups/G7')]

Each edge exposes .relation_type, .target_id, .valid_from, and .valid_until (all duck-typed; RelationRecord is not a public import).

Traversing relations

Reading entity.relations and calling rk.entity(rel.target_id) directly can return None — some target_id values (e.g. "WesternEurope", "geoId/06") don't resolve in the bundled packs. Use Resolver.related() to get resolved entities only:

r = rk.default()
parents = r.related("country/DEU", relation="contained_in")
for parent in parents:
    print(parent.canonical_name)

Unresolvable targets are omitted. To see which targets are dangling, use r.diagnostics.unresolved_relations():

for edge in r.diagnostics.unresolved_relations("country/DEU", relation="contained_in"):
    print(edge["target_id"], "is dangling")

See The entity graph for the full edge-type vocabulary and traversal recipes.

OutputView¶

Frozen dataclass. Returned by rk.to() and Resolver.to(). Binds a fixed output spec to a resolver so every call through it returns the configured representation without repeating to=.

from resolvekit import Resolver

view = Resolver.auto().to("iso3")
view.resolve("France")       # → "FRA"
view.resolve_id("France")    # → "country/FRA"  (entity ID, never pivoted)
view.bulk(values=["France", "Germany"])  # → ["FRA", "DEU"]

Methods

OutputView is not exported from resolvekit directly; it is the return type of rk.to() and Resolver.to().

ResolutionContext¶

Frozen Pydantic model. Pass to any resolution function to narrow or constrain matching.

from resolvekit import ResolutionContext

Fields

Methods

Example

>>> from datetime import date
>>> from resolvekit import ResolutionContext
>>> ctx = ResolutionContext(country="US", entity_types={"geo.state"})
>>> ctx.replace(as_of=date(2020, 1, 1))
ResolutionContext(as_of=datetime.date(2020, 1, 1), entity_types=frozenset({'geo.state'}), parent_ids=None, country='US', languages=None, attributes={})

BulkResult¶

Frozen dataclass. Returned by bulk() when to=None.

Attributes

Methods

BulkResult supports len(), iteration, and integer/slice indexing (over source).

Review round-trip

>>> result = rk.bulk(values=["France", "Congo", "Atlantis"], to=None)
>>> result.to_review("review.csv")          # writes Congo (ambiguous) + Atlantis (no_match)
>>> # ... a human fills the `chosen` column ...
>>> crosswalk = result.to_crosswalk(review="review.csv")
>>> rk.bulk(values=["France", "Congo", "Atlantis"], to="iso3", crosswalk=crosswalk)
['FRA', 'COG', None]

See how to reconcile a column with a review for the full workflow and CSV formats.

Example

>>> import pandas as pd
>>> br = rk.bulk(values=pd.Series(["Germany", "France", "zzznotacountry"]), to=None)
>>> br
BulkResult(total=3, resolved=2, no_match=1, ambiguous=0, error=0, kind='pandas')
>>> br.summary()
ResolutionSummary(total=3, resolved=2, ambiguous=0, no_match=1, error=0)
>>> br.unnest()[["status", "entity_id", "confidence"]]
     status    entity_id  confidence
0  resolved  country/DEU       ≈0.91
1  resolved  country/FRA       ≈0.91
2  no_match         None         NaN

Crosswalk¶

Added in v0.1.

Frozen value-object: a complete value → entity_id table that overrides resolution when passed to bulk(crosswalk=…). Build one by hand with from_dict, load a saved one with from_csv, or have BulkResult.to_crosswalk() assemble it from a review round-trip.

from resolvekit import Crosswalk, IGNORE
# or: rk.Crosswalk, rk.IGNORE

Constructors

• Crosswalk.from_dict(mapping, *, strict=True) — mapping is dict[str, str | None] mapping each input value to an entity ID (e.g. "country/COG") or to IGNORE (equivalently None) to map it to no output. Entity IDs are validated structurally (must be pack/code); existence is checked later, at bulk time.
• Crosswalk.from_csv(path, *, strict=True) — load a crosswalk written by to_csv. Columns must be exactly value,entity_id; an IGNORE token or empty entity_id cell is read as ignore.

Parameters

• strict (bool, default True) — carried on the instance and applied when the crosswalk is used. With strict=True, an entity ID that no loaded pack carries raises CrosswalkError at bulk time. With strict=False, such a value becomes a per-value miss (follows not_found).

Methods

Raises

• ValueError — at construction, when an entry's value isn't None/IGNORE or a well-formed pack/code entity ID, or (from from_csv) when columns are missing or a value is duplicated.

Example

>>> cw = rk.Crosswalk.from_dict({"Congo": "country/COG", "Atlantis": rk.IGNORE})
>>> len(cw), "Congo" in cw
(2, True)
>>> cw.to_csv("crosswalk.csv")
>>> rk.Crosswalk.from_csv("crosswalk.csv")  # round-trips, including IGNORE

CSV format written by to_csv:

value,entity_id
Congo,country/COG
Atlantis,IGNORE

See also — BulkResult.to_crosswalk, bulk, how to reconcile a column with a review.

IGNORE¶

Added in v0.1.

Sentinel marking a Crosswalk entry that maps a value to no output (None). Use it in from_dict; in a CSV it's the literal token IGNORE. Importable as rk.IGNORE or from resolvekit import IGNORE.

>>> cw = rk.Crosswalk.from_dict({"placeholder row": rk.IGNORE})
>>> rk.bulk(values=["placeholder row"], to="iso3", crosswalk=cw)
[None]

ParseResult¶

Returned by parse() and parse_bulk(). Iterable over ParsedEntity instances.

Attributes

Methods

ParsedEntity¶

Represents a single entity mention extracted by parse() or parse_bulk().

Fields

ResolutionStatus¶

StrEnum with four values. Every ResolutionResult.status is one of these — it's never None.

SuggestionResult¶

Frozen Pydantic model. One ranked suggestion returned by Resolver.suggest(). suggest() returns a list[SuggestionResult], best-first. Not root-exported; import the type from resolvekit.core.model:

from resolvekit.core.model import SuggestionResult, MatchClass

Fields

Example

>>> from resolvekit import Resolver
>>> r = Resolver.lite()
>>> s = r.suggest("germany", top_k=1)[0]
>>> s.entity_id
'country/DEU'
>>> s.match_class
<MatchClass.EXACT_PREFIX: 'exact_prefix'>
>>> s.ranking_quality
'ranked'
>>> s.display
'Germany'
>>> s.highlight_ranges
[(0, 7)]

MatchClass¶

StrEnum. Reports how a SuggestionResult candidate was matched. Not root-exported:

from resolvekit.core.model import MatchClass

The four values, in ranking order (best first):

suggest() sorts by a lexicographic cascade: (match_class, whole-name match, typo_count, -prominence, name-kind, name length, entity_id). So an exact prefix outranks a fuzzy match; among ties, an entity whose complete name was typed (e.g. an acronym like "EU") wins, then fewer typos, then more-prominent entities (where the tier is ranked).

AugmentResult¶

Returned by Resolver.augment(..., return_report=True). See the Resolver reference for the full augment signature.

Fields

Example

from resolvekit import Resolver

base = Resolver.from_records(
    [{"id": "KE", "label": "Kenya", "iso3": "KEN"},
     {"id": "UG", "label": "Uganda", "iso3": "UGA"}],
    domain="custom", name="label", id="id", codes={"iso3": "iso3"},
)
report = base.augment(
    [{"iso3": "KEN", "pop_m": 55}],
    link_on=["iso3"],
    add_attrs=["pop_m"],
    on_miss="skip",
    return_report=True,
)
report.linked, report.minted, report.skipped, report.ambiguous   # 1, 0, 0, 0
report.resolver.entity("Kenya").attributes["pop_m"]              # 55

Resolver.from_records and Resolver.augment are methods on Resolver, not module-level functions. See the Resolver reference for their full signatures.

SentinelBlocklist¶

from resolvekit import SentinelBlocklist

Immutable set of normalized forms that the resolver rejects before running the pipeline. Blocked inputs return NO_MATCH with reason "sentinel_blocked".

The default set covers common placeholders ("unknown", "n/a", "null", "tbd", …), junk strings ("qwerty", "lorem", …), pure-punctuation sequences ("---", "...", …), and specific pure-digit strings ("000", "999"). Strings longer than 20 characters are never blocked regardless of content.

SentinelBlocklist(
    *,
    extra: frozenset[str] | set[str] | None = None,
    replace: frozenset[str] | set[str] | None = None,
)

Methods

Example

>>> bl = SentinelBlocklist()
>>> "unknown" in bl
True
>>> "Germany" in bl
False

>>> bl2 = SentinelBlocklist(extra={"myplaceholder"})
>>> "myplaceholder" in bl2
True

Pass a custom blocklist to Resolver.auto(sentinel_blocklist=...), or disable blocking entirely with Resolver.auto(sentinel_blocklist=None).

Errors¶

All public errors are importable from resolvekit or the dedicated resolvekit.errors namespace. The errors most callers need:

from resolvekit import (
    ResolverError,
    ResolutionError,
    AmbiguousResolutionError,
    EntityNotFoundError,
    GroupNotFoundError,
    CrosswalkError,
    DataPackNotAvailableError,
    ExplainNotAvailableError,
    NoModulesInstalledError,
    OutputMissingError,
    UnknownCodeSystemError,
    UnknownContextKeyError,
    UnknownDomainError,
    UnknownOutputError,
)

All of the above are also available via resolvekit.errors. The full catalogue of datapack and registry errors (e.g. DataPackRuntimeVersionError, ModuleConflictError) lives exclusively in resolvekit.errors.

ResolverError¶

Base class for all resolvekit errors. Carries an optional .hint attribute (a str | None) surfaced as a PEP 678 __notes__ entry — it appears in tracebacks automatically.

ResolutionError(ResolverError)¶

A resolution attempt did not produce a usable result.

AmbiguousResolutionError(ResolutionError)¶

Raised by resolve_id() (default on_ambiguous="raise") when multiple entities match.

Example

from resolvekit import AmbiguousResolutionError

try:
    rk.resolve_id("Congo")
except AmbiguousResolutionError as e:
    entity_ids = [c.entity_id for c in e.candidates]
    # ['country/COD', 'country/COG']

GroupNotFoundError(ResolutionError)¶

Raised by Resolver.members_of() and Resolver.is_member() when the group string resolves to no entity.

EntityNotFoundError(ResolutionError)¶

Raised by Resolver.related() and Resolver.diagnostics.unresolved_relations() when the string entity_or_id argument matches no entity.

import resolvekit as rk
from resolvekit import EntityNotFoundError

try:
    rk.default().related("NoSuchPlaceXYZ")
except EntityNotFoundError as e:
    print(e)

UnknownOutputError(ValueError, ResolverError)¶

Raised at configuration or compile time when default_to contains a malformed token (including a malformed name: grammar segment in a per-call to=) or names a code system that no loaded pack carries. A per-call to= naming an unknown code system raises UnknownCodeSystemError instead.

from resolvekit import UnknownOutputError  # or: from resolvekit.errors import UnknownOutputError

Carries .hint with difflib did-you-mean suggestions.

UnknownCodeSystemError(ValueError, ResolverError)¶

Raised when a per-call to= (or EntityRecord.to(system)) names a code system that no loaded pack carries, and by Resolver.members_of when the requested as_codes is not loaded.

from resolvekit import UnknownCodeSystemError  # or: from resolvekit.errors import UnknownCodeSystemError

Carries .hint with difflib did-you-mean suggestions.

OutputMissingError(ResolverError)¶

Raised at runtime when a resolved entity (and the full fallback chain) has no value for the requested output, under on_missing="raise" (or on_missing="auto" for scalar resolve()/snap()).

from resolvekit import OutputMissingError  # or: from resolvekit.errors import OutputMissingError

Carries .hint listing the available codes.

UnknownContextKeyError(ValueError, ResolverError)¶

Added in v0.1.3.

Raised when a context= dict contains a key that is not a valid ResolutionContext field.

from resolvekit.errors import UnknownContextKeyError

Carries .hint listing the valid keys.

Example

try:
    rk.resolve("Germany", context={"region": "Europe"})
except UnknownContextKeyError as e:
    print(e.unknown)   # ['region']
    print(e.valid)     # ['as_of', 'attributes', 'country', 'entity_types', 'languages', 'parent_ids']

CrosswalkError(ResolverError)¶

Added in v0.1.

Raised by bulk when a Crosswalk built with strict=True (the default) maps one or more values to entity IDs that no loaded pack carries — typically a crosswalk saved before a data rebuild that changed IDs.

from resolvekit import CrosswalkError  # or: from resolvekit.errors import CrosswalkError

Carries .hint pointing to strict=False as the way to downgrade unknown IDs to per-value misses. Rebuild the crosswalk with Crosswalk.from_dict(..., strict=False) / from_csv(..., strict=False) to apply it.

Next¶

Resolver class reference — constructors (auto, lite, from_modules), concurrency notes, and the full method list including members_of, diagnostics, and context-manager protocol.

Convert between code systems — end-to-end patterns for from_system / to pivots and bulk column normalization.