openleads 2.0.0__tar.gz

openleads-2.0.0/LICENSE

@@ -0,0 +1,133 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all your
+licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to
+do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only distribute the software
+according to [Distribution License](#distribution-license) and
+make changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software. Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the
+software from you also gets a copy of these terms or the URL for
+them above, as well as copies of any plain-text lines beginning
+with `Required Notice:` that the licensor provided with the
+software. For example:
+
+> Required Notice: Copyright 2026 Samyar Shafiee / NGN Hacks (https://ngnhacks.ca)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make
+changes and new works based on the software for any permitted
+purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able to
+license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the
+benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application, is
+use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose regardless
+of the source of funding or obligations resulting from the
+funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law.
+These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply any
+other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated
+any of these terms, or done anything with the software not
+covered by your licenses, your licenses can nonetheless continue
+if you come into full compliance with these terms, and take
+practical steps to correct past violations, within 32 days of
+receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable to
+you for any damages arising out of these terms or the use or
+nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship, or
+other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one of
+your licenses.
+
+---
+
+Required Notice: Copyright 2026 Samyar Shafiee / NGN Hacks (https://ngnhacks.ca)

openleads-2.0.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: openleads
+Version: 2.0.0
+Summary: Free, open-source Apollo alternative: a universal entity→verified-email engine with pluggable free data sources (founders, developers, doctors, researchers) and an interactive chat CLI.
+Author: Samyar Shafiee
+License: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/Samyrrrrrr990/openleads
+Project-URL: Repository, https://github.com/Samyrrrrrr990/openleads
+Project-URL: Issues, https://github.com/Samyrrrrrr990/openleads/issues
+Project-URL: Changelog, https://github.com/Samyrrrrrr990/openleads/blob/main/CHANGELOG.md
+Keywords: lead-generation,email-finder,apollo-alternative,sales,cli,prospecting,cold-email,smtp-verification,yc,founders,osint,doctors,researchers,developers,data-enrichment
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Communications :: Email
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: chat
+Requires-Dist: rich>=13.0; extra == "chat"
+Requires-Dist: prompt_toolkit>=3.0; extra == "chat"
+Provides-Extra: campaign
+Requires-Dist: requests>=2.31.0; extra == "campaign"
+Requires-Dist: python-dotenv>=1.0.0; extra == "campaign"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: rich>=13.0; extra == "all"
+Requires-Dist: prompt_toolkit>=3.0; extra == "all"
+Requires-Dist: requests>=2.31.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+# 🧲 OpenLeads
+
+### The free, open-source Apollo alternative — for *everyone*.
+
+**Find founders, developers, doctors, researchers — anyone — and verify their emails, using only free, public data. No paid APIs. No API keys. No seat fees. Now with an interactive chat CLI.**
+
+[![License: PolyForm NC](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg)](./LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![Zero-dependency core](https://img.shields.io/badge/core-zero%20dependencies-success.svg)](#-how-it-works)
+[![PyPI](https://img.shields.io/badge/pip-install%20openleads-blue.svg)](https://pypi.org/project/openleads/)
+[![CI](https://github.com/Samyrrrrrr990/openleads/actions/workflows/ci.yml/badge.svg)](https://github.com/Samyrrrrrr990/openleads/actions/workflows/ci.yml)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+[![Stars](https://img.shields.io/github/stars/Samyrrrrrr990/openleads?style=social)](https://github.com/Samyrrrrrr990/openleads/stargazers)
+
+</div>
+
+---
+
+Apollo, Hunter, RocketReach, and ZoomInfo all sell the same two things: **a contact database** and **email verification**. Their moat is the database. **OpenLeads inverts it.**
+
+> OpenLeads is a **universal `entity → verified email` engine**, fed by a registry of **pluggable, free, keyless public data sources.**
+
+The email engine doesn't care *who* you're looking for. So coverage grows by adding small **source plugins**, not by paying for a database. v2.0 ships sources for **startup founders, open-source developers, U.S. doctors, and academic researchers** — and you can add any vertical (lawyers, podcasters, real-estate agents…) by dropping a single `.py` file in a folder.
+
+All for **$0**, in code you can read in one sitting.
+
+```text
+openleads> find 25 AI founders, verified emails only
+  plan  source=yc  count=25  filter=AI  verified-only  parser=rule
+  ┏━━━┳━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┓
+  ┃ # ┃ ✓  ┃ Email           ┃ Name         ┃ Title   ┃ Org     ┃ Score ┃
+  ┡━━━╇━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━┩
+  │ 1 │ OK │ ada@acme.ai     │ Ada Lovelace │ Founder │ Acme    │  96   │
+  │ 2 │ ~CA│ grace@cobol.dev │ Grace Hopper │ CEO     │ COBOLwx │  71   │
+  └───┴────┴─────────────────┴──────────────┴─────────┴─────────┴───────┘
+  25 leads · 18 verified · /export FILE to save
+```
+
+> `OK` = SMTP-verified · `~CA` = catch-all best-guess · `~PG` = MX-only pattern guess · **Score** = 0–100 confidence
+
+---
+
+## ✨ Why OpenLeads
+
+| | OpenLeads | Apollo / Hunter (free tier) |
+| --- | --- | --- |
+| **Cost** | $0, forever | Credit-limited, then paid |
+| **API key required** | ❌ None | ✅ Required |
+| **Who you can find** | Founders, devs, doctors, researchers, **+ any vertical you plug in** | Their database only |
+| **Email verification** | ✅ Live SMTP `RCPT` + 0–100 score | Paid feature |
+| **Catch-all detection** | ✅ Yes | Sometimes |
+| **Interactive chat CLI** | ✅ Yes (`openleads chat`) | ❌ |
+| **You own the code** | ✅ Readable, hackable, extensible | ❌ Black box |
+| **Output** | ✅ CSV / JSON / NDJSON | Often gated |
+| **Core dependencies** | **Zero** (stdlib only) | — |
+
+## 🚀 Install
+
+```bash
+# Python (recommended) — zero-dependency engine + plain CLI
+pip install openleads
+
+# …with the pretty interactive chat TUI
+pip install "openleads[chat]"
+
+# …with the cold-email companion too
+pip install "openleads[all]"
+```
+
+Prefer Node? A thin wrapper lets you run it with **npx** (it installs the Python package on first use):
+
+```bash
+npx openleads find "50 fintech founders verified only"
+# or: npm i -g openleads
+```
+
+## ⚡ Quickstart
+
+```bash
+# Launch the interactive chat — just type what you want
+openleads
+
+# Or go one-shot, non-interactive:
+openleads find "50 fintech founders, verified only" --out leads.csv
+openleads find --source npi --keyword pediatric --location CA --format json
+openleads find "rust developers in Berlin" --source github --format ndjson --out devs.ndjson
+
+# Verify specific addresses
+openleads verify ada@acme.io grace@cobol.dev
+
+# See what you can search
+openleads sources
+```
+
+No signup, no key, no database fees.
+
+## 💬 The chat CLI
+
+`openleads chat` (or just `openleads`) opens a Claude-Code-style REPL. Type requests in plain English and refine conversationally:
+
+```text
+openleads> pediatricians in California
+openleads> only verified
+openleads> /source github
+openleads> machine learning researchers as ndjson
+openleads> /export leads.ndjson
+```
+
+- **Works fully offline.** A rule-based intent parser understands counts, verticals, locations, filters, and `verified only` — **no API key needed.**
+- **Optionally smarter.** Set `OPENROUTER_API_KEY` (a free model works) and free-form input is parsed by an LLM. The active mode is always shown.
+- **Slash commands** for precision: `/source`, `/count`, `/verified`, `/format`, `/export`, `/sources`, `/cache`, `/help`, `/quit`.
+
+## 🧩 Sources (and adding your own)
+
+```bash
+$ openleads sources
+  github       [people ] developers & open-source orgs
+  npi          [people ] U.S. doctors & healthcare providers
+  openalex     [people ] researchers & academics
+  producthunt  [company] trending products & startups
+  yc           [company] startup founders (Y Combinator)
+```
+
+All are **keyless and free**. Want a vertical we don't ship — recruiters, lawyers, real-estate agents, your CRM export? Drop a `*.py` file in `~/.openleads/sources/`:
+
+```python
+from openleads.sources.base import Source
+from openleads.models import Entity, Query
+
+class LawyersSource(Source):
+    name = "lawyers"
+    kind = "people"
+    vertical = "attorneys"
+    description = "State bar directory."
+
+    def search(self, query: Query):
+        for row in fetch_from_some_free_directory(query):
+            yield Entity(full_name=row["name"], organization=row["firm"],
+                         domain=row["firm_domain"], source=self.name)
+```
+
+Run `openleads sources` and it's there. The email engine handles the rest. Full guide: [`docs/sources.md`](./docs/sources.md).
+
+## 📦 Output formats
+
+```bash
+openleads find "20 founders" --format csv     # default; CRM/mail-merge ready
+openleads find "20 founders" --format json    # array, includes score + signals
+openleads find "20 founders" --format ndjson  # one lead per line, streamable
+openleads find "20 founders" --format json --out -   # write to stdout
+```
+
+The CSV schema is a superset of v1's, so the cold-email companion and any existing tooling keep working.
+
+## 🔍 How it works
+
+```mermaid
+flowchart LR
+    Q[Your request<br/>chat or CLI] --> I[Intent parser<br/>rule-based ± LLM]
+    I --> S[Source plugin<br/>yc · github · npi · openalex · …]
+    S --> E[Email engine<br/>multi-resolver MX → permutations → SMTP RCPT]
+    E --> C[Confidence score 0–100<br/>+ honest label]
+    C --> O[CSV · JSON · NDJSON]
+    E <--> K[(SQLite cache<br/>MX · SMTP · datasets)]
+```
+
+The crown jewel is the **email engine** ([deep dive](./docs/how-it-works.md)): MX cross-checked across **two DNS-over-HTTPS resolvers**, common name permutations, and a real SMTP `RCPT` probe (no message is ever sent) with **catch-all detection**. Results carry an explainable **0–100 score**. A **SQLite cache** avoids re-probing domains and mail servers between runs.
+
+> 📡 SMTP verification needs outbound **port 25**. Works on most servers; some home ISPs block it, in which case OpenLeads gracefully falls back to MX-validated pattern guesses.
+
+## 📨 Bonus: cold-email companion
+
+`openleads campaign` turns `leads.csv` into personalized outreach — LLM-drafted (free OpenRouter models supported), clean formatting, placeholder guards, sends over **your own** SMTP, and saves a copy to Sent. Dry-run by default; `--live` to send.
+
+```bash
+pip install "openleads[campaign]"
+cp .env.example .env        # add your SMTP + OpenRouter creds
+openleads campaign          # dry run (preview)
+openleads campaign --live   # send for real
+```
+
+> ⚠️ This is the only part that touches your mailbox. The lead engine never sends anything.
+
+## 🧭 Responsible use
+
+OpenLeads is for legitimate outreach, recruiting, research, and prospecting. Some verticals carry extra weight — e.g. healthcare providers (NPI) and academics — so please read [`docs/responsible-use.md`](./docs/responsible-use.md). **You** are responsible for anti-spam law (CAN-SPAM, GDPR, CASL) and each source's terms.
+
+## 🗺️ What's new in v2.0
+
+- ✅ Installable package + **`openleads` CLI** (pip & npx)
+- ✅ **Interactive chat REPL** (rule-based, LLM-optional)
+- ✅ **Pluggable sources** + 4 new keyless verticals (GitHub, NPI, OpenAlex, ProductHunt)
+- ✅ **Confidence scoring (0–100)** with multi-resolver MX cross-checks
+- ✅ **SQLite caching** layer
+- ✅ **`--format json/ndjson`** output
+
+See the full [CHANGELOG](./CHANGELOG.md).
+
+## 🤝 Contributing
+
+PRs very welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). The easiest high-impact contribution is **a new source plugin** ([guide](./docs/sources.md)) — that's literally how OpenLeads becomes "Apollo for everyone."
+
+## 📄 License
+
+[PolyForm Noncommercial 1.0.0](./LICENSE) — free for personal, research, educational, and nonprofit use. Commercial use? See [COMMERCIAL-LICENSE.md](./COMMERCIAL-LICENSE.md).
+
+## 🙏 Acknowledgements
+
+[`yc-oss/api`](https://github.com/yc-oss/api) · [OpenAlex](https://openalex.org) · [NPI Registry](https://npiregistry.cms.hhs.gov/) · GitHub & ProductHunt public data · and everyone who has ever rage-quit a "request a demo" button.
+
+<div align="center">
+
+**If OpenLeads saved you a subscription, consider leaving a ⭐ — it genuinely helps.**
+
+</div>

openleads-2.0.0/README.md

@@ -0,0 +1,217 @@
+<div align="center">
+
+# 🧲 OpenLeads
+
+### The free, open-source Apollo alternative — for *everyone*.
+
+**Find founders, developers, doctors, researchers — anyone — and verify their emails, using only free, public data. No paid APIs. No API keys. No seat fees. Now with an interactive chat CLI.**
+
+[![License: PolyForm NC](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg)](./LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![Zero-dependency core](https://img.shields.io/badge/core-zero%20dependencies-success.svg)](#-how-it-works)
+[![PyPI](https://img.shields.io/badge/pip-install%20openleads-blue.svg)](https://pypi.org/project/openleads/)
+[![CI](https://github.com/Samyrrrrrr990/openleads/actions/workflows/ci.yml/badge.svg)](https://github.com/Samyrrrrrr990/openleads/actions/workflows/ci.yml)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+[![Stars](https://img.shields.io/github/stars/Samyrrrrrr990/openleads?style=social)](https://github.com/Samyrrrrrr990/openleads/stargazers)
+
+</div>
+
+---
+
+Apollo, Hunter, RocketReach, and ZoomInfo all sell the same two things: **a contact database** and **email verification**. Their moat is the database. **OpenLeads inverts it.**
+
+> OpenLeads is a **universal `entity → verified email` engine**, fed by a registry of **pluggable, free, keyless public data sources.**
+
+The email engine doesn't care *who* you're looking for. So coverage grows by adding small **source plugins**, not by paying for a database. v2.0 ships sources for **startup founders, open-source developers, U.S. doctors, and academic researchers** — and you can add any vertical (lawyers, podcasters, real-estate agents…) by dropping a single `.py` file in a folder.
+
+All for **$0**, in code you can read in one sitting.
+
+```text
+openleads> find 25 AI founders, verified emails only
+  plan  source=yc  count=25  filter=AI  verified-only  parser=rule
+  ┏━━━┳━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┓
+  ┃ # ┃ ✓  ┃ Email           ┃ Name         ┃ Title   ┃ Org     ┃ Score ┃
+  ┡━━━╇━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━┩
+  │ 1 │ OK │ ada@acme.ai     │ Ada Lovelace │ Founder │ Acme    │  96   │
+  │ 2 │ ~CA│ grace@cobol.dev │ Grace Hopper │ CEO     │ COBOLwx │  71   │
+  └───┴────┴─────────────────┴──────────────┴─────────┴─────────┴───────┘
+  25 leads · 18 verified · /export FILE to save
+```
+
+> `OK` = SMTP-verified · `~CA` = catch-all best-guess · `~PG` = MX-only pattern guess · **Score** = 0–100 confidence
+
+---
+
+## ✨ Why OpenLeads
+
+| | OpenLeads | Apollo / Hunter (free tier) |
+| --- | --- | --- |
+| **Cost** | $0, forever | Credit-limited, then paid |
+| **API key required** | ❌ None | ✅ Required |
+| **Who you can find** | Founders, devs, doctors, researchers, **+ any vertical you plug in** | Their database only |
+| **Email verification** | ✅ Live SMTP `RCPT` + 0–100 score | Paid feature |
+| **Catch-all detection** | ✅ Yes | Sometimes |
+| **Interactive chat CLI** | ✅ Yes (`openleads chat`) | ❌ |
+| **You own the code** | ✅ Readable, hackable, extensible | ❌ Black box |
+| **Output** | ✅ CSV / JSON / NDJSON | Often gated |
+| **Core dependencies** | **Zero** (stdlib only) | — |
+
+## 🚀 Install
+
+```bash
+# Python (recommended) — zero-dependency engine + plain CLI
+pip install openleads
+
+# …with the pretty interactive chat TUI
+pip install "openleads[chat]"
+
+# …with the cold-email companion too
+pip install "openleads[all]"
+```
+
+Prefer Node? A thin wrapper lets you run it with **npx** (it installs the Python package on first use):
+
+```bash
+npx openleads find "50 fintech founders verified only"
+# or: npm i -g openleads
+```
+
+## ⚡ Quickstart
+
+```bash
+# Launch the interactive chat — just type what you want
+openleads
+
+# Or go one-shot, non-interactive:
+openleads find "50 fintech founders, verified only" --out leads.csv
+openleads find --source npi --keyword pediatric --location CA --format json
+openleads find "rust developers in Berlin" --source github --format ndjson --out devs.ndjson
+
+# Verify specific addresses
+openleads verify ada@acme.io grace@cobol.dev
+
+# See what you can search
+openleads sources
+```
+
+No signup, no key, no database fees.
+
+## 💬 The chat CLI
+
+`openleads chat` (or just `openleads`) opens a Claude-Code-style REPL. Type requests in plain English and refine conversationally:
+
+```text
+openleads> pediatricians in California
+openleads> only verified
+openleads> /source github
+openleads> machine learning researchers as ndjson
+openleads> /export leads.ndjson
+```
+
+- **Works fully offline.** A rule-based intent parser understands counts, verticals, locations, filters, and `verified only` — **no API key needed.**
+- **Optionally smarter.** Set `OPENROUTER_API_KEY` (a free model works) and free-form input is parsed by an LLM. The active mode is always shown.
+- **Slash commands** for precision: `/source`, `/count`, `/verified`, `/format`, `/export`, `/sources`, `/cache`, `/help`, `/quit`.
+
+## 🧩 Sources (and adding your own)
+
+```bash
+$ openleads sources
+  github       [people ] developers & open-source orgs
+  npi          [people ] U.S. doctors & healthcare providers
+  openalex     [people ] researchers & academics
+  producthunt  [company] trending products & startups
+  yc           [company] startup founders (Y Combinator)
+```
+
+All are **keyless and free**. Want a vertical we don't ship — recruiters, lawyers, real-estate agents, your CRM export? Drop a `*.py` file in `~/.openleads/sources/`:
+
+```python
+from openleads.sources.base import Source
+from openleads.models import Entity, Query
+
+class LawyersSource(Source):
+    name = "lawyers"
+    kind = "people"
+    vertical = "attorneys"
+    description = "State bar directory."
+
+    def search(self, query: Query):
+        for row in fetch_from_some_free_directory(query):
+            yield Entity(full_name=row["name"], organization=row["firm"],
+                         domain=row["firm_domain"], source=self.name)
+```
+
+Run `openleads sources` and it's there. The email engine handles the rest. Full guide: [`docs/sources.md`](./docs/sources.md).
+
+## 📦 Output formats
+
+```bash
+openleads find "20 founders" --format csv     # default; CRM/mail-merge ready
+openleads find "20 founders" --format json    # array, includes score + signals
+openleads find "20 founders" --format ndjson  # one lead per line, streamable
+openleads find "20 founders" --format json --out -   # write to stdout
+```
+
+The CSV schema is a superset of v1's, so the cold-email companion and any existing tooling keep working.
+
+## 🔍 How it works
+
+```mermaid
+flowchart LR
+    Q[Your request<br/>chat or CLI] --> I[Intent parser<br/>rule-based ± LLM]
+    I --> S[Source plugin<br/>yc · github · npi · openalex · …]
+    S --> E[Email engine<br/>multi-resolver MX → permutations → SMTP RCPT]
+    E --> C[Confidence score 0–100<br/>+ honest label]
+    C --> O[CSV · JSON · NDJSON]
+    E <--> K[(SQLite cache<br/>MX · SMTP · datasets)]
+```
+
+The crown jewel is the **email engine** ([deep dive](./docs/how-it-works.md)): MX cross-checked across **two DNS-over-HTTPS resolvers**, common name permutations, and a real SMTP `RCPT` probe (no message is ever sent) with **catch-all detection**. Results carry an explainable **0–100 score**. A **SQLite cache** avoids re-probing domains and mail servers between runs.
+
+> 📡 SMTP verification needs outbound **port 25**. Works on most servers; some home ISPs block it, in which case OpenLeads gracefully falls back to MX-validated pattern guesses.
+
+## 📨 Bonus: cold-email companion
+
+`openleads campaign` turns `leads.csv` into personalized outreach — LLM-drafted (free OpenRouter models supported), clean formatting, placeholder guards, sends over **your own** SMTP, and saves a copy to Sent. Dry-run by default; `--live` to send.
+
+```bash
+pip install "openleads[campaign]"
+cp .env.example .env        # add your SMTP + OpenRouter creds
+openleads campaign          # dry run (preview)
+openleads campaign --live   # send for real
+```
+
+> ⚠️ This is the only part that touches your mailbox. The lead engine never sends anything.
+
+## 🧭 Responsible use
+
+OpenLeads is for legitimate outreach, recruiting, research, and prospecting. Some verticals carry extra weight — e.g. healthcare providers (NPI) and academics — so please read [`docs/responsible-use.md`](./docs/responsible-use.md). **You** are responsible for anti-spam law (CAN-SPAM, GDPR, CASL) and each source's terms.
+
+## 🗺️ What's new in v2.0
+
+- ✅ Installable package + **`openleads` CLI** (pip & npx)
+- ✅ **Interactive chat REPL** (rule-based, LLM-optional)
+- ✅ **Pluggable sources** + 4 new keyless verticals (GitHub, NPI, OpenAlex, ProductHunt)
+- ✅ **Confidence scoring (0–100)** with multi-resolver MX cross-checks
+- ✅ **SQLite caching** layer
+- ✅ **`--format json/ndjson`** output
+
+See the full [CHANGELOG](./CHANGELOG.md).
+
+## 🤝 Contributing
+
+PRs very welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). The easiest high-impact contribution is **a new source plugin** ([guide](./docs/sources.md)) — that's literally how OpenLeads becomes "Apollo for everyone."
+
+## 📄 License
+
+[PolyForm Noncommercial 1.0.0](./LICENSE) — free for personal, research, educational, and nonprofit use. Commercial use? See [COMMERCIAL-LICENSE.md](./COMMERCIAL-LICENSE.md).
+
+## 🙏 Acknowledgements
+
+[`yc-oss/api`](https://github.com/yc-oss/api) · [OpenAlex](https://openalex.org) · [NPI Registry](https://npiregistry.cms.hhs.gov/) · GitHub & ProductHunt public data · and everyone who has ever rage-quit a "request a demo" button.
+
+<div align="center">
+
+**If OpenLeads saved you a subscription, consider leaving a ⭐ — it genuinely helps.**
+
+</div>

openleads-2.0.0/automation.py

@@ -0,0 +1,14 @@
+"""
+Back-compat shim. The outreach companion moved to ``openleads.campaign`` in v2.0.
+
+    python automation.py            # dry-run preview (was the old behavior)
+    python automation.py --live     # send
+
+Prefer: ``openleads campaign`` / ``openleads campaign --live``.
+"""
+import sys
+
+from openleads.campaign import main
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

openleads-2.0.0/lead_engine.py

@@ -0,0 +1,48 @@
+"""
+Back-compat shim for OpenLeads v1.
+
+The engine moved into the installable ``openleads`` package in v2.0. This module
+re-exports the v1 public helpers and forwards the old CLI to ``openleads find``
+so existing scripts keep working. Prefer the new entry point:
+
+    openleads find "20 founders"        # or: python -m openleads find ...
+"""
+from __future__ import annotations
+
+import sys
+
+# Re-export the v1 public API from its new homes (behavior unchanged).
+from openleads.emails.permute import (  # noqa: F401
+    candidate_emails,
+    domain_of,
+    name_parts,
+)
+from openleads.emails.resolve import find_email  # noqa: F401
+from openleads.sources.yc import (  # noqa: F401
+    pick_exec,
+    split_location,
+)
+
+
+def _translate(argv: list[str]) -> list[str]:
+    """Map v1 flags onto the new ``find`` subcommand."""
+    out: list[str] = []
+    for a in argv:
+        if a == "--no-write":
+            out += ["--out", "-"]   # v1 'print only' ≈ write CSV to stdout
+        else:
+            out.append(a)
+    return out
+
+
+def main() -> int:
+    sys.stderr.write(
+        "[deprecation] `lead_engine.py` is now a shim. Use `openleads find ...` "
+        "(or `python -m openleads find ...`).\n"
+    )
+    from openleads.cli import main as cli_main
+    return cli_main(["find"] + _translate(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())