leadgen-ai 1.2.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,6 @@
+"""LeadGen AI — keyword lead search with any AI API. Developed by Gyan Ranjan."""
+
+from .pipeline import LeadAgent
+from .branding import APP_NAME, CREDIT, DEVELOPER, VERSION
+
+__all__ = ["LeadAgent", "APP_NAME", "CREDIT", "DEVELOPER", "VERSION"]

agent/branding.py

@@ -0,0 +1,15 @@
+"""Product branding — LeadGen AI by Gyan Ranjan."""
+
+APP_NAME = "LeadGen AI"
+APP_TAGLINE = "Search any keywords → get real sales leads (any AI API)"
+DEVELOPER = "Gyan Ranjan"
+CREDIT = f"Developed by {DEVELOPER}"
+VERSION = "1.2.0"
+
+
+def banner_lines() -> str:
+    return (
+        f"[bold cyan]{APP_NAME}[/]  v{VERSION}\n"
+        f"[dim]{APP_TAGLINE}[/]\n"
+        f"[magenta]{CREDIT}[/]"
+    )

agent/config.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .models_catalog import FAMOUS_MODELS, PROVIDERS
+
+_ROOT = Path(__file__).resolve().parent.parent
+load_dotenv(_ROOT / ".env")
+load_dotenv()
+
+
+def _first_env(*names: str) -> str:
+    for name in names:
+        val = os.getenv(name, "").strip()
+        if val:
+            return val
+    return ""
+
+
+def resolve_api_key(provider: str) -> str:
+    """Accept any common API key env var so users can plug any provider."""
+    meta = PROVIDERS.get(provider, PROVIDERS["custom"])
+    # provider-specific first, then generic aliases
+    return _first_env(
+        meta["key_env"],
+        "LEADGEN_API_KEY",
+        "API_KEY",
+        "OPENAI_API_KEY",
+        "XAI_API_KEY",
+        "GROQ_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "GEMINI_API_KEY",
+        "GOOGLE_API_KEY",
+        "DEEPSEEK_API_KEY",
+        "OPENROUTER_API_KEY",
+        "TOGETHER_API_KEY",
+        "MISTRAL_API_KEY",
+    )
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str
+    base_url: str
+    model: str
+    provider: str = "openai"
+    default_lead_count: int = 10
+    min_score: int = 50
+    use_web_search: bool = True
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        provider: str | None = None,
+        model: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> "Settings":
+        # CLI / env overrides
+        model_name = (model or os.getenv("LEADGEN_MODEL") or os.getenv("MODEL") or "").strip()
+        provider_name = (provider or os.getenv("LEADGEN_PROVIDER") or os.getenv("PROVIDER") or "").strip().lower()
+
+        # Resolve famous model shortcuts → provider + model id
+        if model_name and model_name.lower() in FAMOUS_MODELS:
+            auto_provider, auto_model = FAMOUS_MODELS[model_name.lower()]
+            if not provider_name:
+                provider_name = auto_provider
+            model_name = auto_model
+
+        if not provider_name:
+            # Auto-detect from which key is set
+            for p, meta in PROVIDERS.items():
+                if p == "custom":
+                    continue
+                if os.getenv(meta["key_env"], "").strip():
+                    provider_name = p
+                    break
+            if not provider_name:
+                provider_name = "openai"
+
+        if provider_name not in PROVIDERS:
+            provider_name = "custom"
+
+        meta = PROVIDERS[provider_name]
+        resolved_base = (
+            (base_url or "").strip()
+            or os.getenv("LEADGEN_BASE_URL", "").strip()
+            or os.getenv("OPENAI_BASE_URL", "").strip()
+            or meta["base_url"]
+        )
+        if not resolved_base:
+            resolved_base = "https://api.openai.com/v1"
+
+        if not model_name:
+            model_name = (
+                os.getenv("LEADGEN_MODEL", "").strip()
+                or meta["default_model"]
+            )
+
+        key = (api_key or "").strip() or resolve_api_key(provider_name)
+        if not key:
+            raise RuntimeError(
+                "Missing API key. Set any of these in .env or environment:\n"
+                "  OPENAI_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY,\n"
+                "  OPENROUTER_API_KEY, MISTRAL_API_KEY, XAI_API_KEY, LEADGEN_API_KEY, API_KEY\n\n"
+                "Examples:\n"
+                "  set OPENAI_API_KEY=sk-...\n"
+                "  leadgen search \"dental clinics Mumbai\" --model gpt-4o\n"
+                "  leadgen search \"gyms Delhi\" --provider groq --model llama-3.3-70b\n"
+                "  leadgen models   # list popular models\n"
+            )
+
+        web = os.getenv("LEADGEN_WEB_SEARCH", "1").strip().lower() not in {
+            "0",
+            "false",
+            "no",
+            "off",
+        }
+
+        return cls(
+            api_key=key,
+            base_url=resolved_base.rstrip("/"),
+            model=model_name,
+            provider=provider_name,
+            default_lead_count=int(os.getenv("DEFAULT_LEAD_COUNT", "10")),
+            min_score=int(os.getenv("MIN_LEAD_SCORE", "50")),
+            use_web_search=web,
+        )

agent/export.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import csv
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+
+from .models import Lead, LeadRunResult
+
+CSV_FIELDS = [
+    "company_name",
+    "website",
+    "industry",
+    "company_size",
+    "location",
+    "description",
+    "contact_name",
+    "contact_title",
+    "contact_email",
+    "linkedin_url",
+    "source_url",
+    "buying_signals",
+    "fit_score",
+    "fit_reason",
+    "outreach_subject",
+    "outreach_email",
+    "next_action",
+]
+
+
+def default_output_dir() -> Path:
+    root = Path(__file__).resolve().parent.parent / "output"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+
+
+def _lead_to_row(lead: Lead) -> dict:
+    row = lead.model_dump()
+    signals = row.get("buying_signals") or []
+    if isinstance(signals, list):
+        row["buying_signals"] = "; ".join(str(s) for s in signals)
+    return row
+
+
+def export_csv(leads: list[Lead], path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=CSV_FIELDS, extrasaction="ignore")
+        writer.writeheader()
+        for lead in leads:
+            writer.writerow(_lead_to_row(lead))
+    return path
+
+
+def export_json(result: LeadRunResult, path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(result.model_dump_json(indent=2), encoding="utf-8")
+    return path
+
+
+def _normalize_key(name: str, website: str | None = None) -> str:
+    base = (name or "").strip().lower()
+    site = (website or "").strip().lower().removeprefix("https://").removeprefix("http://").removeprefix("www.")
+    site = site.rstrip("/")
+    return f"{base}|{site}"
+
+
+def load_csv_rows(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    with path.open(newline="", encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def merge_lead_rows(rows: Iterable[dict]) -> list[dict]:
+    """Dedupe by company+website, keep highest fit_score."""
+    best: dict[str, dict] = {}
+    for row in rows:
+        name = (row.get("company_name") or "").strip()
+        if not name:
+            continue
+        key = _normalize_key(name, row.get("website"))
+        try:
+            score = int(float(row.get("fit_score") or 0))
+        except (TypeError, ValueError):
+            score = 0
+        row = {**row, "fit_score": score}
+        prev = best.get(key)
+        if prev is None:
+            best[key] = row
+            continue
+        try:
+            prev_score = int(float(prev.get("fit_score") or 0))
+        except (TypeError, ValueError):
+            prev_score = 0
+        if score >= prev_score:
+            best[key] = row
+    merged = list(best.values())
+    merged.sort(key=lambda r: int(r.get("fit_score") or 0), reverse=True)
+    return merged
+
+
+def write_rows_csv(rows: list[dict], path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=CSV_FIELDS, extrasaction="ignore")
+        writer.writeheader()
+        for row in rows:
+            out = {k: row.get(k, "") for k in CSV_FIELDS}
+            writer.writerow(out)
+    return path
+
+
+def merge_all_csvs(out_dir: Path | None = None) -> Path:
+    """Merge every leads_*.csv in output/ into all_leads.csv (deduped)."""
+    out = out_dir or default_output_dir()
+    rows: list[dict] = []
+    for path in sorted(out.glob("leads_*.csv")):
+        rows.extend(load_csv_rows(path))
+    # Also include existing master if present
+    master = out / "all_leads.csv"
+    if master.is_file():
+        rows.extend(load_csv_rows(master))
+    merged = merge_lead_rows(rows)
+    return write_rows_csv(merged, master)
+
+
+def append_to_master(leads: list[Lead], out_dir: Path | None = None) -> Path:
+    out = out_dir or default_output_dir()
+    master = out / "all_leads.csv"
+    existing = load_csv_rows(master)
+    new_rows = [_lead_to_row(lead) for lead in leads]
+    merged = merge_lead_rows(existing + new_rows)
+    return write_rows_csv(merged, master)
+
+
+def export_all(result: LeadRunResult, out_dir: Path | None = None) -> dict[str, Path]:
+    out = out_dir or default_output_dir()
+    ts = stamp()
+    csv_path = export_csv(result.leads, out / f"leads_{ts}.csv")
+    json_path = export_json(result, out / f"leads_{ts}.json")
+    master_path = append_to_master(result.leads, out)
+    return {"csv": csv_path, "json": json_path, "all": master_path}

agent/llm.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Type, TypeVar
+
+from openai import OpenAI
+from pydantic import BaseModel
+
+from .config import Settings
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LLM:
+    """OpenAI-compatible client — works with OpenAI, Groq, Gemini, DeepSeek, OpenRouter, xAI, custom."""
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.client = OpenAI(
+            api_key=settings.api_key,
+            base_url=settings.base_url,
+        )
+
+    def complete(
+        self,
+        system: str,
+        user: str,
+        *,
+        use_web_search: bool = False,
+        temperature: float = 0.3,
+    ) -> str:
+        # use_web_search is handled upstream via agent/search.py for all providers
+        _ = use_web_search
+        kwargs: dict[str, Any] = {
+            "model": self.settings.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "temperature": temperature,
+        }
+        # Some reasoning models reject temperature
+        try:
+            response = self.client.chat.completions.create(**kwargs)
+        except Exception:
+            kwargs.pop("temperature", None)
+            response = self.client.chat.completions.create(**kwargs)
+
+        choice = response.choices[0].message
+        content = choice.content
+        if isinstance(content, str) and content.strip():
+            return content.strip()
+        return str(content or "").strip()
+
+    def complete_json(
+        self,
+        system: str,
+        user: str,
+        schema: Type[T],
+        *,
+        use_web_search: bool = False,
+        temperature: float = 0.2,
+    ) -> T:
+        schema_hint = json.dumps(schema.model_json_schema(), indent=2)
+        full_system = (
+            f"{system}\n\n"
+            "Return ONLY valid JSON matching this JSON Schema. "
+            "No markdown fences, no commentary.\n\n"
+            f"{schema_hint}"
+        )
+        raw = self.complete(
+            full_system,
+            user,
+            use_web_search=use_web_search,
+            temperature=temperature,
+        )
+        data = _parse_json(raw)
+        return schema.model_validate(data)
+
+
+def _parse_json(text: str) -> Any:
+    text = text.strip()
+    fence = re.search(r"```(?:json)?\s*([\s\S]*?)```", text)
+    if fence:
+        text = fence.group(1).strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        for pattern in (r"\{[\s\S]*\}", r"\[[\s\S]*\]"):
+            match = re.search(pattern, text)
+            if match:
+                return json.loads(match.group(0))
+        raise

agent/models.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class IdealCustomerProfile(BaseModel):
+    """Structured ideal customer profile derived from the user's product pitch."""
+
+    product_summary: str = Field(description="What you sell, in 1-2 sentences")
+    target_industries: list[str] = Field(default_factory=list)
+    company_sizes: list[str] = Field(
+        default_factory=list,
+        description="e.g. startup, SMB, mid-market, enterprise",
+    )
+    geographies: list[str] = Field(default_factory=list)
+    buyer_titles: list[str] = Field(
+        default_factory=list,
+        description="Decision-maker roles to target",
+    )
+    pain_points: list[str] = Field(default_factory=list)
+    buying_signals: list[str] = Field(
+        default_factory=list,
+        description="Public signals that indicate a good fit",
+    )
+    disqualifiers: list[str] = Field(default_factory=list)
+    search_queries: list[str] = Field(
+        default_factory=list,
+        description="Web search queries to find matching companies",
+    )
+    value_proposition: str = ""
+
+
+class Lead(BaseModel):
+    company_name: str
+    website: Optional[str] = None
+    industry: Optional[str] = None
+    company_size: Optional[str] = None
+    location: Optional[str] = None
+    description: Optional[str] = None
+    contact_name: Optional[str] = None
+    contact_title: Optional[str] = None
+    contact_email: Optional[str] = None
+    linkedin_url: Optional[str] = None
+    source_url: Optional[str] = None
+    buying_signals: list[str] = Field(default_factory=list)
+    fit_score: int = Field(ge=0, le=100, default=0)
+    fit_reason: str = ""
+    outreach_subject: str = ""
+    outreach_email: str = ""
+    next_action: str = ""
+
+
+class LeadBatch(BaseModel):
+    leads: list[Lead] = Field(default_factory=list)
+    research_notes: str = ""
+
+
+class LeadRunResult(BaseModel):
+    icp: IdealCustomerProfile
+    leads: list[Lead]
+    research_notes: str = ""
+    query: str = ""

agent/models_catalog.py

@@ -0,0 +1,97 @@
+"""Popular models users can pick with --model or LEADGEN_MODEL."""
+
+from __future__ import annotations
+
+# name -> (base_url, default_api_key_env, notes)
+PROVIDERS: dict[str, dict[str, str]] = {
+    "openai": {
+        "base_url": "https://api.openai.com/v1",
+        "key_env": "OPENAI_API_KEY",
+        "default_model": "gpt-4o",
+    },
+    "xai": {
+        "base_url": "https://api.x.ai/v1",
+        "key_env": "XAI_API_KEY",
+        "default_model": "grok-3",
+    },
+    "groq": {
+        "base_url": "https://api.groq.com/openai/v1",
+        "key_env": "GROQ_API_KEY",
+        "default_model": "llama-3.3-70b-versatile",
+    },
+    "deepseek": {
+        "base_url": "https://api.deepseek.com/v1",
+        "key_env": "DEEPSEEK_API_KEY",
+        "default_model": "deepseek-chat",
+    },
+    "openrouter": {
+        "base_url": "https://openrouter.ai/api/v1",
+        "key_env": "OPENROUTER_API_KEY",
+        "default_model": "openai/gpt-4o-mini",
+    },
+    "together": {
+        "base_url": "https://api.together.xyz/v1",
+        "key_env": "TOGETHER_API_KEY",
+        "default_model": "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
+    },
+    "mistral": {
+        "base_url": "https://api.mistral.ai/v1",
+        "key_env": "MISTRAL_API_KEY",
+        "default_model": "mistral-large-latest",
+    },
+    "gemini": {
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+        "key_env": "GEMINI_API_KEY",
+        "default_model": "gemini-2.0-flash",
+    },
+    "custom": {
+        "base_url": "",  # set via LEADGEN_BASE_URL
+        "key_env": "LEADGEN_API_KEY",
+        "default_model": "gpt-4o",
+    },
+}
+
+# Famous models shortcut → (provider, model_id)
+FAMOUS_MODELS: dict[str, tuple[str, str]] = {
+    # OpenAI
+    "gpt-4o": ("openai", "gpt-4o"),
+    "gpt-4o-mini": ("openai", "gpt-4o-mini"),
+    "gpt-4.1": ("openai", "gpt-4.1"),
+    "gpt-4.1-mini": ("openai", "gpt-4.1-mini"),
+    "o3-mini": ("openai", "o3-mini"),
+    "o4-mini": ("openai", "o4-mini"),
+    # Google
+    "gemini-2.0-flash": ("gemini", "gemini-2.0-flash"),
+    "gemini-1.5-pro": ("gemini", "gemini-1.5-pro"),
+    "gemini-2.5-pro": ("gemini", "gemini-2.5-pro"),
+    # Meta via Groq
+    "llama-3.3-70b": ("groq", "llama-3.3-70b-versatile"),
+    "llama-3.1-70b": ("groq", "llama-3.3-70b-versatile"),
+    "mixtral-8x7b": ("groq", "mixtral-8x7b-32768"),
+    # DeepSeek
+    "deepseek-chat": ("deepseek", "deepseek-chat"),
+    "deepseek-v3": ("deepseek", "deepseek-chat"),
+    # Mistral
+    "mistral-large": ("mistral", "mistral-large-latest"),
+    "mistral-small": ("mistral", "mistral-small-latest"),
+    # xAI (optional)
+    "grok-3": ("xai", "grok-3"),
+    "grok-4": ("xai", "grok-4"),
+    "grok-4.5": ("xai", "grok-4.5"),
+    # OpenRouter popular
+    "claude-3.5-sonnet": ("openrouter", "anthropic/claude-3.5-sonnet"),
+    "claude-sonnet-4": ("openrouter", "anthropic/claude-sonnet-4"),
+    "claude-3-haiku": ("openrouter", "anthropic/claude-3-haiku"),
+}
+
+
+def list_models_help() -> str:
+    lines = ["Popular models (use --model NAME):"]
+    for name in sorted(FAMOUS_MODELS.keys()):
+        provider, mid = FAMOUS_MODELS[name]
+        lines.append(f"  {name:22} → {provider:12} {mid}")
+    lines.append("")
+    lines.append("Providers (use --provider NAME + your API key):")
+    for p, meta in PROVIDERS.items():
+        lines.append(f"  {p:12} key={meta['key_env']}  default={meta['default_model']}")
+    return "\n".join(lines)