[namirali]

What and why

CompanyEnrich is a B2B company and people data API covering company enrichment, account search, similar companies, professional profiles and workforce research. This contribution adds a useful native finder workflow: one explicitly authorized people-search page feeds OpenOutFind's existing local qualification and CSV/JSON export.

Related to #1. The default BetterContact free discovery is unchanged. A configured CompanyEnrich key alone is inert. The paid path requires all of:

outfind find 5 --companyenrich-query people.json \
  --companyenrich-request-id founders-page-1 --discovery-credit-budget 20

The query supports domain/title/location/seniority/department/date/education filters, exclusions and explicit pagination. Size defaults to ten and caps at 100; the required local credit reservation is twice page size at the published current 2-credit/profile rate. There is one request at most, no automatic extra page and no email discovery. Compound company lookup/search, expansions and other paid operations are intentionally excluded from this contract.

Spend and data boundaries

• A separate invocation-scoped discovery interface keeps the paid source out of the free lattice and its cost assumptions. It does not change email-purchase opt-in.
• CompanyEnrichPage commits a unique request-ID reservation before HTTP and stores the complete response before embedding. Resuming reuses data; unknown outcomes never replay automatically. New IDs are explicit new authorizations, not provider-side idempotency.
• Fixed HTTPS endpoint, bounded body/timeouts, no retries/redirects, schema validation before spending, no provider error bodies or credentials in errors.
• Lead.discovery_source preserves local-only hub policy across runs and duplicates. CompanyEnrich pages, employers, embeddings, later email give-back and hub lookups are excluded. Later free-provider pages cannot override that policy, including alternate URL spellings. The operator's configured LLM and directed exports still receive profiles through the existing workflow.
• Names, current employment and exact integer IDs come from provider fields; emails and historical-as-current employers are never invented. Full response/page metadata remains in the local record.

Validation

• 816 tests passed with .venv/bin/python -m pytest -q (Python 3.13, Django 6.1.2); 35 existing sklearn convergence warnings in the walk suite.
• Includes 46 synthetic CompanyEnrich tests: exact HTTP/schema, refusal/redaction/no retry, credit gates, default source unchanged, real CLI-to-CSV flow with fixture verdict, zero-goal no purchase, request replay protection, interrupted embedding recovery, persisted hub exclusion and URL variants.
• makemigrations --check --dry-run reports no changes.
• Distribution wheel builds and includes client, schema and both generated migrations.
• No live provider/LLM calls or real API credentials used.
• GitHub's Tests workflow is currently action_required with no jobs started; upstream workflow approval is pending.

Setup, query examples, deliberate endpoint scope and limitations are in docs/companyenrich.md; README, architecture, contributor/agent instructions, shipped skill and data-handling notices are synchronized. Existing installations receive two additive migrations.

Ready for review of the optional paid-source interface and durable data policy.