Skip to content

Add FullEnrich as a second email finder, picked by price among the keyed ones - #3

Closed
matherjo wants to merge 1 commit into
eracle:mainfrom
matherjo:feature/waterfall-finder-choice
Closed

matherjo wants to merge 1 commit into
eracle:mainfrom
matherjo:feature/waterfall-finder-choice

Conversation

@matherjo

Copy link
Copy Markdown

What and why

The email finder was BetterContact or nothing. This adds FullEnrich as a second adapter and lets the pipeline pick whichever keyed finder is cheaper, so an operator holding both keys pays the lower unit cost without changing a command.

openoutfind/enrichment/provider.py now holds the choice: configured() lists the finders that have a key, active() returns the cheapest of them, chain() returns the active finder followed by the rest sorted by cost, and by_name() resolves a name recorded on a deal. Cost comes from each module's UNIT_COST_USD (bettercontact 0.075, fullenrich 0.055), read through getattr with an infinite default so a future adapter that forgets the constant sorts last rather than crashing the selection.

openoutfind/enrichment/fullenrich.py is the new adapter and mirrors the BetterContact surface: start, is_configured, credit_balance, submit, poll_once, FullEnrichUnavailable, SIGNUP_URL, UNIT_COST_USD, a shared RequestBudget, and a retrying session. A bare profile URL is a complete query on FullEnrich's side, so submit takes the URL and nothing else. credit_balance raises, because FullEnrich exposes no balance endpoint; status renders that as unknown rather than inventing a number.

lookup._submit walks provider.chain() instead of calling BetterContact directly. Every ProviderUnavailable is stepped over and the next finder tried, because each typed refusal (401, 402, exhausted 429, transport failure) is a couldn't-run rather than an answer. A terminal miss ends the walk. A hit or a pending job records the finder's NAME on the deal so check_lookup polls the right vendor back.

Spend and data boundaries

  • Discovery stays on the BetterContact key. REQUIRED_DISCOVERY_FIELDS is deliberately unchanged, so a FullEnrich key alone buys email lookups but cannot start the free discovery planner. FullEnrich has no people-search here.
  • A finder is only reached after the free sources miss: the lead's own address, then the hub cross-operator cache. Selecting FullEnrich lowers the price of a paid lookup; it does not make lookups start earlier.
  • The finder is picked by unit cost, so adding a cheaper key reorganizes spend without any editing of the chain. Adding a more expensive key leaves the current order alone.
  • RequestBudget(15, 60.0, label="fullenrich") is shared module state with no exempt request, unlike BetterContact's account read. The per-file autouse fixture clears the window between tests so a slow file cannot leak its spent slots into the next one.
  • poll_once maps the vendor status honestly: RATE_LIMIT and CREDITS_INSUFFICIENT surface as typed refusals, CANCELED is a miss, FINISHED reads contact_info, and anything else including UNKNOWN is still running. Only DELIVERABLE and HIGH_PROBABILITY count as a usable address, so a catch-all is never written to a lead.
  • _request calls raise_for_status(), so a 5xx surfaces as a failure the walk can step over instead of being read as a pending job that is polled forever.

Validation

  • 917 tests passed with .venv/bin/python -m pytest -q (Python 3.13.13), three consecutive runs (172s, 107s, 145s). The 45 warnings are the existing sklearn convergence notices in the walk suite; the slow items are pre-existing.
  • Adapter subset: 53 passed in 2.04s after the shared-window fixture fix, which had made per-file runs stall to 61s or more.
  • Includes 32 new FullEnrich tests (submit, poll, every HTTP refusal, the raising balance, the budget, is_configured, the signup URL), 15 provider tests for the cost ordering and the chain, and 11 additions to the BetterContact tests for the budget label and the exempt account read.
  • CLAUDE.md and ARCHITECTURE.md are synchronized, including the per-file inventory entries for enrichment/fullenrich.py and enrichment/provider.py.
  • No live provider calls and no real credentials used; no FullEnrich or BetterContact key was present. Every HTTP path is mocked.

… holds configured/active/chain/by_name, FullEnrich joins BetterContact as a second adapter whose bare profile URL is a complete query and whose credit_balance raises because the vendor exposes none, and lookup._submit walks the chain with every ProviderUnavailable stepped over, a terminal miss ending it
@matherjo

Copy link
Copy Markdown
Author

Superseded by #4. Its head branch contains this PR's commit as an ancestor, so #4 carries the FullEnrich layer along with LeadMagic and Enrow; merging #4 lands all of it. Closing this one so there is a single diff to review and no risk of merging the same commit twice.

@matherjo matherjo closed this Nov 11, 2026
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