Skip to content

Add FullEnrich, LeadMagic and Enrow as three more email finders, cheapest first - #4

Open
matherjo wants to merge 4 commits into
eracle:mainfrom
matherjo:feature/leadmagic-finder
Open

matherjo wants to merge 4 commits into
eracle:mainfrom
matherjo:feature/leadmagic-finder

Conversation

@matherjo

@matherjo matherjo commented Nov 11, 2026 •

Copy link
Copy Markdown

Supersedes #3. This branch carries that PR's commit plus two more, so the whole stack lands or falls together and #3 can be closed.

What and why

The waterfall had two finders behind a provider seam whose only job was to pick one. This branch makes the seam do three things: choose by price, admit a finder that answers in one request, and admit a cheaper asynchronous one.

Three commits, in order:

  1. The finder is chosen by price among the keyed ones. provider.py grows _providers() and sorts the keyed adapters by UNIT_COST_USD, so active() selects the cheapest that has a key and the rest of the chain follows. FullEnrich arrives as the second asynchronous adapter at 0.055 per contact. This is the pricing seam, not an architecture change, which is the point of it.
  2. LeadMagic joins as the third finder and the only synchronous one. 0.0198 per hit, so it sorts ahead of FullEnrich. openoutfind/enrichment/leadmagic.py makes start the whole lookup: one POST returns a Lookup carrying a terminated PollOutcome, a hit lands on RESOLVED without the deal entering FINDING_EMAIL, and nothing parks on a handle a vendor could strand. There is deliberately no poll_once, and a test asserts it is absent so a later edit cannot reintroduce a poll a synchronous vendor will never answer.
  3. Enrow joins as the fourth finder and the cheapest address per hit. 0.017, so it now sorts first. openoutfind/enrichment/enrow.py is asynchronous and polled: POST /email/find/single with only the profile URL returns a handle, GET /email/find/single?id=… answers 202 while running and 200 with the address and qualification when done.

The resulting chain by price is enrow 0.017, leadmagic 0.0198, fullenrich 0.055, bettercontact 0.075. provider.chain() walks it, so an install holding every key tries the cheapest first and steps over a finder that cannot run.

Enrow's answer is three-sided, and the adapter keeps the sides apart

Enrow distinguishes "no address exists" from "we could not look". Collapsing them would burn the deal, so they are mapped separately:

  • qualification: "valid" is an address. Anything else, including invalid, is a miss.
  • linkedin_status: "lookup_failed" is transient and free, so it raises EnrowUnavailable and the deal is deferred to the next walk rather than marked as having no address.
  • profile_not_found, no_current_company and email_not_found are real misses.
  • Enrow never returns 404; an unknown or expired handle comes back as 500, which is read as "not settled yet" and deferred.
  • 401 is PROVIDER_AUTH, 402 is PROVIDER_OUT_OF_CREDITS, 429 backs off exponentially. Each is a couldn't-run the walk steps over, so the next finder is tried rather than the deal being failed.

Spend and data boundaries

  • Discovery stays on the BetterContact key. REQUIRED_DISCOVERY_FIELDS is unchanged, so a LeadMagic-only or Enrow-only install can resolve a known profile URL but cannot search.
  • Every UNIT_COST_USD on this branch is the price of a hit, not of an attempt. Enrow bills one credit for a found address, a quarter credit for a LinkedIn search that finds nothing, and nothing when its own lookup fails. LeadMagic bills only on a valid address and nothing on 429.
  • credit_balance is a real read of a free endpoint in both new adapters (GET /v1/credits for LeadMagic, GET /account/info for Enrow), floored to an int and exempt from the request budget because the vendor documents those calls as free. status therefore shows a true number instead of unknown.
  • The rate limits are courtesies, not vendor numbers presented as limits: 60 per minute for LeadMagic against the 300 the entry plan publishes, 120 per minute for Enrow against its documented 10 per second on the single-search POST. Both windows are shared module state and are cleared between tests.
  • openoutfind/core/config.py gains leadmagic_api_key and enrow_api_key.

Validation

  • 990 tests passed with .venv/bin/python -m pytest -q (Python 3.13.13) in 260.38s, no failures. The 45 warnings are the existing sklearn convergence notices in the walk suite.
  • The 32 LeadMagic tests cover the terminated outcome from start, the absence of poll_once, that only the profile URL is sent, every HTTP refusal, the floored and exempt balance, the request budget, is_configured and the signup URL.
  • The 37 Enrow tests cover the handle coming back from start, 202 read as still running, linkedin_status: "lookup_failed" as a deferral and not a miss, the three real misses, 500 on an unknown handle, 401 and 402, the balanced credit count, the request budget with the free account read exempt, is_configured and the signup URL.
  • tests/test_provider.py asserts the real roster and its price order, that the chain skips adapters without a key, and that active() lands on Enrow when every key is present.
  • CLAUDE.md and ARCHITECTURE.md are synchronized, including the per-file inventory entries for enrichment/leadmagic.py and enrichment/enrow.py, the env keys, the status-table credits row and the budget sizes.
  • No live provider calls and no real credentials were used; no LeadMagic or Enrow 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
…rt is the whole lookup and returns a finished outcome so a hit never parks on a handle a vendor could strand, one POST carries nothing but the profile URL, its balance is a real read of the free credits endpoint, and its sixty-a-minute budget is a courtesy fifth of the three hundred the entry plan publishes per organisation
…art posts one linkedin_url and returns the vendor's id, poll_once reads it back while the search runs at 202, only valid and invalid settle a lookup, a lookup_failed LinkedIn status defers because the vendor bills nothing for it, an unknown or expired handle answers 500 rather than 404 so it defers too, and its hundred-and-twenty-a-minute budget leaves the free account read outside it while status shows a real balance
@matherjo matherjo changed the title Add LeadMagic as a third email finder, the only synchronous one Add FullEnrich, LeadMagic and Enrow as three more email finders, cheapest first Nov 11, 2026
…gainst the vendor's own homepage today, which says fifty credits free and no credit card, so the README, the configuration table and the find-leads skill all carry the number an operator will actually see after signing up

This branch has not been deployed

No deployments
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