Skip to content

Add Client.resolve_activities, concurrent batch name resolution - #225

Merged
ccomb merged 1 commit into
mainfrom
pyvolca-resolve-activities
Jul 15, 2026
Merged

Add Client.resolve_activities, concurrent batch name resolution#225
ccomb merged 1 commit into
mainfrom
pyvolca-resolve-activities

Conversation

@ccomb

@ccomb ccomb commented Jul 15, 2026

Copy link
Copy Markdown
Owner

Why

Scripts that need process ids for a list of names keep reinventing the same two workarounds: downloading the entire database (limit=200000) to build a name→process_id dict, or hand-rolled thread pools issuing one search_activities per name.

What

Client.resolve_activities(names, *, by="name"|"product", geo=, exact=True, limit=5, workers=8) resolves a batch of names concurrently and returns {name: [matches]}:

  • The mapping is total: a name that doesn't resolve maps to [] instead of disappearing — misses stay visible.
  • One match = unambiguous; several = ambiguous (same name across geographies), disambiguate with geo= or inspect the candidates.
  • exact=False returns relevance-ranked candidates, best first.
  • Duplicated input names are searched once; errors propagate instead of degrading to empty results.

With exact=True the client re-checks equality on the returned matches (same casefold rule as the engine): engines whose product filter ignores exact= return substring matches, and a near-miss must never resolve silently. A separate engine PR fixes that filter at the source.

Verification

  • 10 offline orchestration tests (mapping totality, dedup, argument passthrough, exactness guard, fail-loud).
  • End-to-end against a local engine build: exact hit, miss, fuzzy ranking, by="product", and a deduplicated batch.
  • README API reference regenerated (drift test green).

@ccomb
ccomb force-pushed the pyvolca-resolve-activities branch 2 times, most recently from 0b4c7ef to 611cfe8 Compare July 15, 2026 21:28
Scripts kept hand-rolling the same two patterns to map names to
process ids: downloading the whole database to build a lookup dict,
and per-name thread pools over search_activities. One helper replaces
both: one search per unique name, fanned out over a thread pool, with
a total result mapping so a name that resolves to nothing is an empty
list rather than a silently missing key.

When exact=True the client re-checks equality (same casefold rule as
the engine) on the returned matches: engines released before the
product filter honored exact= return substring matches, and a
near-miss must not resolve silently.
@ccomb
ccomb force-pushed the pyvolca-resolve-activities branch from 611cfe8 to 4fede25 Compare July 15, 2026 21:36
@ccomb
ccomb merged commit 0c50a76 into main Jul 15, 2026
11 checks passed
@ccomb
ccomb deleted the pyvolca-resolve-activities branch July 15, 2026 21:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant