leads-cli 0.1.0__py3-none-any.whl

leads_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: leads-cli
+Version: 0.1.0
+Summary: Agent-first company and contact discovery for outbound lead generation.
+Author: Paolo Auletta
+License: Proprietary
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: platformdirs>=4.3.6
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: sqlalchemy>=2.0.38
+Requires-Dist: tldextract>=5.1.3
+Requires-Dist: typer>=0.15.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Leads
+
+An agent-first, memory-first company and contact research engine. Strict JSON specs drive
+deterministic memory retrieval, focused Exa searches, structured LLM evaluation, targeted
+official-site enrichment, persistence, and reviewable CSV/Markdown/JSON artifacts.
+
+Design and rebuild notes live in [`NOTES/`](./NOTES/README.md).
+
+## Install
+
+The canonical install path is `pipx`. The package is published as `leads-cli` because `leads`
+is already taken on PyPI, but it still installs the `leads` command. The installer scripts are
+thin convenience wrappers around `pipx install leads-cli` or `pipx upgrade leads-cli`, followed
+by `leads init`.
+
+### macOS and Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/paoloauletta/leads/main/install.sh | bash
+```
+
+### Windows PowerShell
+
+```powershell
+irm https://raw.githubusercontent.com/paoloauletta/leads/main/install.ps1 | iex
+```
+
+### Direct pipx install
+
+```bash
+pipx install leads-cli
+leads init
+```
+
+Use `LEADS_SKIP_INIT=1` with either installer when you want to install first and run onboarding
+later.
+
+## Onboarding
+
+Run:
+
+```bash
+leads init
+```
+
+The wizard creates one local workspace, stores config and secrets, initializes the SQLite database,
+and installs bundled skills into the agent targets you choose, such as Codex, Claude Code, or
+OpenCode. After setup, use one of those agents to create a spec, run discovery, and summarize the
+selected leads.
+
+Runtime data defaults to the OS-appropriate Leads application data folder. Override it with
+`LEADS_HOME=/path/to/data` when needed.
+
+`LLM_RESPONSE_FORMAT=auto` uses strict JSON Schema with OpenAI and validated JSON Object mode
+with DeepSeek or other compatible providers. Override it only when a provider documents support
+for a different mode.
+
+## Workspace Layout
+
+`leads init` creates one workspace root with these top-level directories:
+
+```text
+backups/
+config/
+data/
+logs/
+runs/
+skills/
+specs/
+```
+
+`config/` contains local settings, secrets, and runtime metadata. `data/company_memory.db` is the
+SQLite memory database. `specs/companies/` and `specs/contacts/` are where agent-created specs
+belong. `runs/` contains discovery and enrichment artifacts. `backups/` stores migration and reset
+backups. `skills/` stores bundled skill copies and install metadata. `logs/leads.log` is a CLI
+diagnostic log for troubleshooting; it is not lead evidence or a run artifact.
+
+## Commands
+
+```bash
+leads init
+leads doctor
+leads init-db
+leads version
+leads update --check
+leads migrate --check
+leads config show
+leads skills status
+leads companies discover --spec company_search_spec.json
+leads companies enrich DISCOVERY_RUN_ID
+leads companies show-run RUN_ID
+leads companies inspect RUN_ID --domain example.com
+leads companies export RUN_ID
+leads companies rerun RUN_ID
+leads companies show-enrichment ENRICHMENT_RUN_ID
+leads companies inspect-enrichment ENRICHMENT_RUN_ID --domain example.com
+leads companies export-enrichment ENRICHMENT_RUN_ID
+leads contacts validate-spec --spec contact_search_spec.json
+leads contacts discover --spec contact_search_spec.json
+leads contacts enrich CONTACT_DISCOVERY_RUN_ID
+leads contacts show-run CONTACT_DISCOVERY_RUN_ID
+leads contacts inspect CONTACT_DISCOVERY_RUN_ID --person "Jane Smith"
+leads contacts export CONTACT_DISCOVERY_RUN_ID
+leads contacts show-enrichment CONTACT_ENRICHMENT_RUN_ID
+leads contacts inspect-enrichment CONTACT_ENRICHMENT_RUN_ID --person "Jane Smith"
+leads contacts export-enrichment CONTACT_ENRICHMENT_RUN_ID
+```
+
+`leads init-db` creates `company_memory.db` and its schema. If the database already exists, it
+asks before resetting it. An accepted reset moves the existing `runs/` directory to a timestamped
+archive such as `runs-previousdb-20260622T184500Z/`, then creates a new empty `runs/` directory.
+
+`leads migrate --check` is read-only. `leads migrate --apply` creates a timestamped backup before
+supported structural schema changes and refuses unknown migration paths.
+
+Use `--verbose` on `discover` to print generated queries and candidate-level decisions.
+
+## Development Setup
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/leads init
+```
+
+For a local smoke test, create or copy a company spec, configure provider keys during onboarding,
+then run:
+
+```bash
+leads companies discover --spec company_search_spec.json
+```
+
+## Multiple verticals
+
+Use `verticals` to request OR semantics: companies may match construction, healthcare, or
+engineering; they do not need to match all three. Each vertical gets an independent memory scan,
+gap calculation, Exa query plan, and evaluation lane.
+
+Each vertical now uses one simple shape: `key`, `label`, and optional query hints. Use
+`search_terms` when the label alone is too broad or niche, and `exclude_terms` when a vertical
+needs a few search-time negatives. Old specs that still contain `mode`, `seed_terms`, or
+`anti_terms` remain readable and normalize to the new shape.
+
+`balance_mode` controls final selection. `soft` (the default) fills an equal quality-gated floor
+per vertical, then reallocates unused slots to good companies from stronger lanes. `strict` keeps
+equal caps and may return fewer companies. `none` selects good companies in discovery order.
+
+The legacy single `vertical` object remains accepted for existing specs.
+
+## Memory policy
+
+`novelty_mode` controls whether saved companies can enter a run:
+
+- `unused_memory` (default) searches memory first and only considers companies never selected before.
+- `only_new` skips memory candidates and removes externally rediscovered domains already in memory.
+- `full_memory` searches all matching memory, including companies selected in previous runs.
+
+Old `prefer_new` and `allow_known` specs remain readable and normalize to `unused_memory` and
+`full_memory`, respectively.
+
+## Enrichment
+
+Enrichment is always a separate command run after discovery completes:
+
+```bash
+leads companies discover --spec company_search_spec.json
+leads companies enrich DISCOVERY_RUN_ID
+```
+
+It consumes selected companies directly from the completed discovery run. It retains company
+name, root domain, target vertical, geography, employee estimate, ownership type, and discovery
+evidence, then finds only the missing LinkedIn company profile, phone, complete in-scope address,
+and independence status.
+
+Each enrichment execution gets a random run ID such as `company-enrich-a1b2c3d4e5f6`. That ID is
+used both for CLI follow-up commands and the enrich artifact folder under the source discovery run.
+
+Fresh enrichment facts are reused by company/domain before any website request. The bounded website
+pass reads the homepage and best contact/location/about pages; unresolved fields can use a narrow
+Exa corroboration search. Output is split into `enriched.csv`, `review.csv`, and `blocked.csv`, while
+the enrichment `run.json` keeps field provenance, conflicts, and the per-company trace.
+
+LinkedIn enrichment first checks company-profile links exposed by the official website, including
+footer icon links. Only `/company/...` URLs are accepted; personal profiles, jobs, and posts are
+discarded. If the official site has no profile link, enrichment performs a narrow LinkedIn company
+search. The normalized URL and its source page are saved in enrichment memory and exported as
+`linkedin_url`.
+
+By default, complete profiles with unknown independence remain in review. Add
+`--allow-unknown-independence` only when that uncertainty is acceptable. Generic values such as
+`privately_held` never count as proof of independence.
+
+To exclude family businesses during enrichment, add this to the discovery spec:
+
+```json
+"exclude": {
+  "structured": {"ownership_signals": ["family_owned"]}
+}
+```
+
+Enrichment still records the company as independent, but sends it to `blocked.csv` with a
+`fit_conflict` and `excluded_family_owned` flag. The ownership signal is retained in enrichment
+memory, so the same rule applies when a later run reuses fresh facts.
+
+## Contact Discovery
+
+Contact discovery is a separate phase after company enrichment. It starts from a completed
+`company-enrich-<id>`, uses only its ready companies by default, and finds current people matching
+structured role targets.
+
+```bash
+cp examples/contact_search_spec.json contact_search_spec.json
+leads contacts validate-spec --spec contact_search_spec.json
+leads contacts discover --spec contact_search_spec.json
+```
+
+For every company and role, the command reuses accepted contact memory from the last 30 days, then
+uses one Exa people-index query plus one official-domain evidence query for each remaining
+per-company gap. The LLM evaluates identity, current employment at the exact target company, and
+requested-title fit. A model cannot force an acceptance when those explicit checks are not
+satisfied.
+
+Artifacts are split into `accepted.csv`, `review.csv`, and `rejected.csv`. All three use the same
+client-facing columns:
+
+```text
+company_name, company_domain, contact_name, title, linkedin_url,
+email, phone, status, notes
+```
+
+`email` and `phone` are intentionally blank during discovery. Full queries, raw Exa results,
+evidence, role keys, verdict details, and memory/live source decisions are retained in `run.json`.
+
+## Contact Enrichment
+
+Contact enrichment is a separate Apollo-backed command after contact discovery:
+
+```bash
+leads contacts enrich contact-discover-a1b2c3d4e5f6
+```
+
+Only accepted contacts enter enrichment. Live-web discovery remains authoritative for the person's
+identity, current company, title, role, and LinkedIn URL; Apollo can add email and phone channels
+but cannot overwrite those facts. Exact identity and company/email-domain checks classify each
+person as `ready`, `review`, or `blocked`, with raw Apollo trace and flags retained in `run.json`.
+
+Apollo bulk requests are sent in groups of 10. Phone and waterfall requests are asynchronous, so
+the default email-and-phone command requires `APOLLO_WEBHOOK_URL` and polls Apollo's request result
+until completion. Use `--no-phone` for an email-only run when a webhook is unavailable. Fresh
+Apollo results are reused for 14 days unless `--refresh` is supplied.
+
+Artifacts live below the source contact run in
+`contacts/contact-discover-<id>/enrich/contact-enrich-<id>/` and retain the same compact
+client columns used by discovery. Output is split into `ready.csv`, `review.csv`, and `blocked.csv`.

leads_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,72 @@
+company_discovery/__init__.py,sha256=5qc9XN4-aqsC00Q2hX_yVr1RhLH1LFdJXLXc-8UvCd4,97
+company_discovery/cli.py,sha256=gR9uVj7gEh0V9BiaOrhXlDanAGR83XSCHST_-5Cflr0,69585
+company_discovery/migrations.py,sha256=7ETyxn5eklOK5ijkpjaNuXRgvxij6_tcS1D_nqWznHc,7101
+company_discovery/release_manifest.json,sha256=0t7-y5CYMr36LUbxS9DS7gC4nSRwWDNDmzgZJGTSR2s,143
+company_discovery/runtime.py,sha256=HjjhEAdKja69jf4TKvoKMjx009o6R3a7FQ2q6R-BgyA,10610
+company_discovery/settings.py,sha256=yJN6BmXYrx3bvt9hYszbNZdiGuhN7GW5p0Ew57PUkWY,5241
+company_discovery/skill_installer.py,sha256=yophXF4YoZgaa06Yye8BJqF43sHYyuuEvCOQdODbeto,6036
+company_discovery/update_plan.py,sha256=2-im-7_BI0nMH49lqwhjbz3ZVO-O92tHidHUVllhhT8,3253
+company_discovery/adapters/__init__.py,sha256=27v0-0JsAk9RZthfaj2WT0Hb92NBfkXfRY9ZYQcVOhQ,165
+company_discovery/adapters/apollo.py,sha256=vcPSWFAp1z-fnXUNOrY9Ok80o3YmleTMAj8SnB-Ix-I,8137
+company_discovery/adapters/exa.py,sha256=n1_Fef_T7qsywkpsF8Wn8CitGbwupQWH8njmTuER7rU,4343
+company_discovery/adapters/llm.py,sha256=UNGF7fiI9bK-AESnYNC7E_YwmKqH8Kla9F0Z_bw7s9I,4716
+company_discovery/adapters/protocols.py,sha256=_Xzuc31w4lq31sb0Ale8UgoutIBuL5cfjPxHJrZ-sos,1417
+company_discovery/adapters/website.py,sha256=981EwCxPcqmWo9yD8U1aNCYof03AOjtzF3fEEg1tHCc,5624
+company_discovery/bundled_skills/__init__.py,sha256=uik9j7pIHijtEAABtmGwH6cSJJ8vt5N6aiciUlQI0jQ,55
+company_discovery/bundled_skills/company-discovery-operator/SKILL.md,sha256=KlFj2DUKOUKqs96OSlZ35W4gwoIPYHzfbiUzQIj7bXU,4492
+company_discovery/bundled_skills/company-discovery-operator/agents/openai.yaml,sha256=EBtEZWnB__j-nN--NEDvXIv7vvEdmDgwZ6m0YA4uY3g,236
+company_discovery/bundled_skills/company-enrichment-operator/SKILL.md,sha256=xwZJM4eEwK6b8aYEXZcyFpZLrNI2NtfPQrWKKkczhzk,5375
+company_discovery/bundled_skills/company-enrichment-operator/agents/openai.yaml,sha256=L_V39cdOFpyM8OY5Y_RykW1XIrCwaYW9pRVYK_B7B4A,283
+company_discovery/bundled_skills/company-search-spec-writer/SKILL.md,sha256=4nNR6Z9-Mq2fTv4zat100gKPOAginCDtMuAIt-U6BO0,5923
+company_discovery/bundled_skills/company-search-spec-writer/agents/openai.yaml,sha256=gaSYZfstyqiTmJqy81G-6Hg1BCEpbX9VOXgHtWmJbNY,244
+company_discovery/bundled_skills/contact-discovery-operator/SKILL.md,sha256=217Jj8BslLYfarxpC_C-x-bsI8sj-OXPTiIB8PZyuEA,4389
+company_discovery/bundled_skills/contact-discovery-operator/agents/openai.yaml,sha256=lEm-N0gmJgFo3O_u5p6c3UwdhmcLe8RNu5Xa14Rax08,232
+company_discovery/bundled_skills/contact-enrichment-operator/SKILL.md,sha256=XCMUF9zikAIRraNcucvA2tLfH5HoTejFadJJwQoH41U,4603
+company_discovery/bundled_skills/contact-enrichment-operator/agents/openai.yaml,sha256=Br7UAmgIQqdlULI-Gq2iFvsD4ayNld2lwyqJO413vSU,249
+company_discovery/bundled_skills/contact-search-spec-writer/SKILL.md,sha256=vmxc6PxT_HBoUQvGG4owNSELCX2wKZWBx0I5Clu_N50,3695
+company_discovery/bundled_skills/contact-search-spec-writer/agents/openai.yaml,sha256=JDOJzchfjkzk5A6sHO3I6uodYhIBA5LV0PoSzmDnOJI,231
+company_discovery/bundled_skills/leads-update-operator/SKILL.md,sha256=ASxkDDyU-op5w7fv9zTR2PqfTlFCGwcOWSEQxrk0XaM,3189
+company_discovery/bundled_skills/leads-update-operator/agents/openai.yaml,sha256=zMnWmQuK0GOwhDqN5kPUpJyVDGo2V_wdKT1d8vlxQac,284
+company_discovery/db/__init__.py,sha256=Tf8z4nXIEIP8GHq5zB6cCeeA6pcjdVS0sP8cbF0DFXM,162
+company_discovery/db/contact_enrichment_repository.py,sha256=HdGL5gXIWpfeF1agDBDRYu3uqnLSYt4bHSUT3Fli0nE,11163
+company_discovery/db/contact_repository.py,sha256=1lSaXKIJuL5LPeQtCI0YXC6ggurHjTc3vxzLwZkJAwM,15203
+company_discovery/db/enrichment_repository.py,sha256=9Ecm3fjly9-J1bSQfs0YmDz-Xl7O7yEUgFo2ANoA9sA,8704
+company_discovery/db/models.py,sha256=JVlSVuaVM9D_CY7HKJHBQkFaf9D_2uPCr8Xmh_fcpQE,17466
+company_discovery/db/repository.py,sha256=JTQD_PYmF5HeJADQWPx5d3JUyMDE_3zc3A2tve_yyNQ,14549
+company_discovery/db/session.py,sha256=DNsRkAvQQYFBo5fUF2thIw1-fbYoQ1gemFfRkxpkBKU,1470
+company_discovery/domain/__init__.py,sha256=JRuWH0ctxeOerFHH2eHb0IyeD8MX3uf97iWUjVTkK10,477
+company_discovery/domain/contact_models.py,sha256=ksj8MVqcj3h7DO3zPaTksR0NBNnCMb7Uer5huXGpp2U,4800
+company_discovery/domain/contact_spec.py,sha256=szIG16DIOXobuNsM0vUOH71oRKF23M-cHHOIDVeGppw,3088
+company_discovery/domain/models.py,sha256=beTwmij5hVAkk2a0we2A9mOW10CtuwzvwfMF9J4JYS0,7767
+company_discovery/domain/spec.py,sha256=aRm3pHRipV8dAV-rgSMtp8a_gjvnj0xZksDKgzhu-iM,9040
+company_discovery/prompts/__init__.py,sha256=7zfBw353QRmxhpdWnWPqL4o012SLuXhZYJW3ZgVr_h8,234
+company_discovery/prompts/candidate_evaluation/system.md,sha256=bErTiDYq0X-q3A_EFthvqXtDS-366OJriZxLbW7V9WE,902
+company_discovery/prompts/company_enrichment/system.md,sha256=JSRS2PQKDl7Aux9DEySJcCv1utx8oWoDtMNK4BIr51g,2284
+company_discovery/prompts/contact_evaluation/system.md,sha256=g1kM6fOP_pcJkAfihqc7Lr8HQjWS9pwCdBBMuvhie38,994
+company_discovery/prompts/query_generation/system.md,sha256=5xL9ES1YFJzB-HRYFSU9XHTbsICGuu7h1ojqCcPRgPQ,654
+company_discovery/reports/__init__.py,sha256=nG--6ITyepPkDWKEB7IeIQPkEypZeHD6RmNNwbAuKwU,97
+company_discovery/reports/contact_enrichment_exporter.py,sha256=LekU9ia7uiJbcPLooN3Hj8Bket94Md90XReJ8f8JU7g,4117
+company_discovery/reports/contact_exporter.py,sha256=ElJ70yLHrExzk_NOt-TE4aP7aFuqF2I_tltppeFhK10,5147
+company_discovery/reports/enrichment_exporter.py,sha256=cLBr3N_jpbWX7EuMi1Y2t6E0AVphVF1fBRB41RB1PQU,5239
+company_discovery/reports/exporter.py,sha256=JL8HpM005idjE3jTs0YFmOEOKREMYH2sbGJeX6RW4X4,5625
+company_discovery/services/__init__.py,sha256=X_b-8NwIk39K0Uegi3NuVpIKGrv-luJZNQSnsriX6es,100
+company_discovery/services/contact_enrichment_pipeline.py,sha256=WKaneiO-wcnItqhB-CTWK_nFHq9bGSzCzI3dFmesyJg,13774
+company_discovery/services/contact_enrichment_progress.py,sha256=hp5DBISwVhvmbTujiftFjObWAUbavNwnqlfCo278QmM,998
+company_discovery/services/contact_evaluator.py,sha256=9Vt1_2RYzP3p2Wv9VCVhx2dEstWb3XBLjWZ2QKWYmlY,3808
+company_discovery/services/contact_pipeline.py,sha256=c0ig6nTDOQTFjYtk0kUsEd2xIEiI3joy3fWjtOGSpk4,11935
+company_discovery/services/contact_progress.py,sha256=3gsqz_y1mPy1usUxObxHM8H41Oe4cvoCMqSjctGzMB8,1127
+company_discovery/services/enrichment_extractor.py,sha256=DuBKi8SNyyE1oD-JRdEQhZj8hgszb96lt8YQ5rmf7NU,2021
+company_discovery/services/enrichment_pipeline.py,sha256=PYhfv2tsq_yL7xPb7uEfam9zzylwx8lEGecHtDgegDY,21244
+company_discovery/services/enrichment_progress.py,sha256=tzMfaX7iSfZt6CLHbFnUZU1hB6NTeqGDqiQQq9qBc5k,603
+company_discovery/services/enrichment_resolver.py,sha256=U963WmkTvN4pvZXwYK1P1ZRCr4-cZPHPYAnTGZxRBJ0,5535
+company_discovery/services/evaluator.py,sha256=R_7gN7Wp2UxmQpF3nZez_hRyBXwyHzawAips28Jufnc,1351
+company_discovery/services/hygiene.py,sha256=kDe4biQ74mhaIP14oB1jdhZeZgli1tPCYbTO1zeE7to,1462
+company_discovery/services/memory.py,sha256=rfDkNT3wr0SI6QoMWBq1h7-FHk4zE0AOJOMpsaRs15g,5739
+company_discovery/services/normalization.py,sha256=3PcMx2Hga1qHJqgzBV8lSTLM42OeqjLjdi63iYoxwPw,3502
+company_discovery/services/pipeline.py,sha256=whV2Ez1dRJt-yvGNYYgiQXKrYt2qVY3_Sp7KD6MyR2A,26294
+company_discovery/services/progress.py,sha256=Ku5oz4GrqtqeTO-To0qYF2srE1ayB-xPNkSWNx3hbbM,1136
+company_discovery/services/query_planner.py,sha256=LZT7mFCmmdYUWF34fZJKQUP36aj4xHsnIwcNEpNXgKA,1858
+leads_cli-0.1.0.dist-info/METADATA,sha256=vYbVuquXn36hbPoKFVHBxtxXekqPhsqUA9sU5KLtxRs,11102
+leads_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+leads_cli-0.1.0.dist-info/entry_points.txt,sha256=YibLqTZ6DQNv-gtwKa82spvsl3i7q9vQjPetVzIBGoo,52
+leads_cli-0.1.0.dist-info/RECORD,,

leads_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

leads_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+leads = company_discovery.cli:app