Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 34 additions & 14 deletions ARCHITECTURE.md

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions CLAUDE.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ There is no promotional campaign sent from your mailbox and no "Sent with" line
| # | What | Example |
|---|------|---------|
| 1 | **An LLM API key** | OpenAI, Anthropic, or any OpenAI-compatible endpoint |
| 2 | **An email-finder API key** ([BetterContact](https://bettercontact.rocks?fpr=openoutreach)) | **Free account: 40 credits, no card.** Powers **both** discovery (Lead Finder, billed nothing) and enrichment (one credit per verified work email, only with `--emails`) |
| 2 | **An email-finder API key** ([BetterContact](https://bettercontact.rocks?fpr=openoutreach)) | **Free account: 50 credits, no card.** Powers **both** discovery (Lead Finder, billed nothing) and enrichment (one credit per verified work email, only with `--emails`) |
| 3 | **A product description + target market** | "We sell cloud cost optimization for DevOps teams at mid-market SaaS companies" |

That's it. **No mailbox**, no social-network account, no spreadsheets, no lead databases, no scraping setup. The BetterContact key is required because it drives discovery *and* enrichment — note the barrier is an **account, not a bill**, since searching the index costs nothing and only resolving an address spends a credit.
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ things before it starts working.
| `OPENOUTFIND_AI_MODEL` | llm | `provider:model`, e.g. `anthropic:claude-sonnet-4-5-20250929`; bare `gpt-*`/`claude-*`/`gemini-*` are auto-prefixed. Providers: openai/anthropic/google/groq/mistral/cohere/openai_compatible |
| `OPENOUTFIND_LLM_API_KEY` | llm | **verified by one live ping before every run** — a key rotated out from under a timer fails before a lead is chosen, not mid-pass |
| `OPENOUTFIND_LLM_API_BASE` | llm | required for `openai_compatible:*`, ignored otherwise |
| `OPENOUTFIND_BETTERCONTACT_API_KEY` | bettercontact | [free account, 40 credits, no card](https://bettercontact.rocks?fpr=openoutreach) (affiliate link, no markup to you). Powers **both** Lead Finder discovery (billed nothing) **and** work-email enrichment (one credit per verified address, only with `--emails`) |
| `OPENOUTFIND_BETTERCONTACT_API_KEY` | bettercontact | [free account, 50 credits, no card](https://bettercontact.rocks?fpr=openoutreach) (affiliate link, no markup to you). Powers **both** Lead Finder discovery (billed nothing) **and** work-email enrichment (one credit per verified address, only with `--emails`) |
| `OPENOUTFIND_OPERATOR_EMAIL` | account | optional. Your own inbox — the contacts-store key. Unset, the operator row is named `operator` and the install never talks to the hub (no free cached addresses, no give-back). Fills a blank row once; never replaces an email already there |
| `OPENOUTFIND_OPERATOR_COUNTRY` | account | optional. ISO 3166 alpha-2, e.g. `US` — **your jurisdiction**, not your target market. Unset, the install contributes to the contacts store |
| `OPENOUTFIND_CONTACTS_API_TOKEN` | hub | optional. Without a token a run registers for one and keeps it for the length of the process; `register` is idempotent, so nothing is lost by not storing it |
Expand Down
16 changes: 16 additions & 0 deletions openoutfind/core/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,22 @@ class SiteConfig:
# paid email lookup behind `--emails`.
bettercontact_api_key: str = ""

# FullEnrich's key powers the paid email lookup behind `--emails` and nothing else.
# Discovery stays on BetterContact's Lead Finder, so a FullEnrich-only install can
# resolve an address but cannot search (core/readiness.py: REQUIRED_DISCOVERY_FIELDS).
fullenrich_api_key: str = ""

# LeadMagic's key powers the paid email lookup behind `--emails` and nothing else.
# A single synchronous call where the others run a job, so a hit lands without the
# lead ever parking on a vendor-held handle.
leadmagic_api_key: str = ""

# Enrow's key powers the paid email lookup behind `--emails` and nothing else.
# Asynchronous like the waterfalls, and the cheapest address per hit on the entry
# plan ($17 buys 1,000 credits), so `provider.active()` reaches for it first when
# it is keyed.
enrow_api_key: str = ""

# The operator's own ISO-3166 alpha-2 jurisdiction — not to be confused with
# `Lead.country_code`, the per-lead target country an ICP search surfaced someone
# under. Optional: an EEA/UK/CH country turns the contacts-store give-back off
Expand Down
20 changes: 15 additions & 5 deletions openoutfind/core/status.py
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,12 @@ def _credits() -> dict:
return {"balance": finder.credit_balance(), "provider": finder.NAME, "error": None}
except provider.ProviderUnavailable as exc:
logger.debug("Could not read the credit balance: %s", exc)
return {"balance": None, "error": exc.error_type, "detail": str(exc)}
return {
"balance": None,
"provider": finder.NAME,
"error": exc.error_type,
"detail": str(exc),
}


def _signup_url() -> str:
Expand Down Expand Up @@ -203,25 +208,30 @@ def _blocked(config: dict, credits: dict, totals: dict) -> list[dict]:
"message": "this run was not given: " + ", ".join(config["missing"]),
})

# The finder that actually ran is the one an operator has to act on. When no key is
# set there is no finder to name, so the sentence describes the missing piece instead
# of picking a vendor the install never configured.
finder = credits.get("provider") or "the email finder"

if credits["error"] == ErrorType.NO_CREDENTIAL:
blocked.append({
"type": ErrorType.NO_CREDENTIAL,
"message": "no BetterContact key — discovery and email finding are both off",
"message": "no email-finder key set: discovery and email finding are both off",
})
elif credits["error"] == ErrorType.PROVIDER_AUTH:
blocked.append({
"type": ErrorType.PROVIDER_AUTH,
"message": "BetterContact rejected the API key",
"message": f"{finder} rejected the API key",
})
elif credits["error"] == ErrorType.PROVIDER_OUT_OF_CREDITS:
blocked.append({
"type": ErrorType.PROVIDER_OUT_OF_CREDITS,
"message": "BetterContact reports the credits are exhausted",
"message": f"{finder} reports the credits are exhausted",
})
elif credits["error"] == ErrorType.PROVIDER_RATE_LIMITED:
blocked.append({
"type": ErrorType.PROVIDER_RATE_LIMITED,
"message": "BetterContact is rate-limiting this client — the run is backing off",
"message": f"{finder} is rate-limiting this client, the run is backing off",
})
elif credits["balance"] == 0 and totals["ranked_for_lookup"]:
blocked.append({
Expand Down
22 changes: 20 additions & 2 deletions openoutfind/enrichment/bettercontact.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,14 @@
REQUESTS_PER_MINUTE = 15
_BUDGET_WINDOW_S = 60.0

# **What one credit costs on the entry plan, used only to rank finders against each
# other.** Starter is $15 for 200 credits, so $0.075 a hit; the rate falls as the plan
# grows (their ladder runs to $0.02 at volume), and a bigger plan reorders the waterfall.
# So this is an anchor for the cheapest paid tier, not a measurement of what an
# operator's own account charges — the seam picks the cheapest *listed* finder and the
# prices are re-checked when a plan changes.
UNIT_COST_USD = 0.075

# **A 429 is backed off, never retried at speed** — their docs warn that a client which
# keeps firing through one can get the *account* blocked, which costs the operator far
# more than the throttled call was worth. urllib3 already does this correctly: waits of
Expand Down Expand Up @@ -108,11 +116,19 @@ class RequestBudget:
spend about 12, a later round's one about 3, so a run rarely waits.
"""

def __init__(self, limit: int, window: float, clock=time.monotonic, sleep=time.sleep):
def __init__(
self,
limit: int,
window: float,
clock=time.monotonic,
sleep=time.sleep,
label: str = NAME,
):
self._limit = limit
self._window = window
self._clock = clock
self._sleep = sleep
self._label = label
self._sent: deque[float] = deque()
self._lock = threading.Lock()

Expand All @@ -126,7 +142,9 @@ def take(self) -> None:
self._sent.append(now)
return
wait = self._window - (now - self._sent[0])
logger.debug("bettercontact: request budget full — waiting %.1fs", wait)
logger.debug(
"%s: request budget full, waiting %.1fs", self._label, wait
)
self._sleep(wait)


Expand Down
Loading