leads-cli 0.1.0__py3-none-any.whl

company_discovery/__init__.py

@@ -0,0 +1,4 @@
+"""Memory-first company discovery."""
+
+__distribution_name__ = "leads-cli"
+__version__ = "0.1.0"

company_discovery/adapters/__init__.py

@@ -0,0 +1,5 @@
+from company_discovery.adapters.exa import ExaClient
+from company_discovery.adapters.llm import OpenAICompatibleLLM
+
+__all__ = ["ExaClient", "OpenAICompatibleLLM"]
+

company_discovery/adapters/apollo.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from company_discovery.domain.contact_models import (
+    ApolloBatchResult,
+    ApolloPersonMatch,
+    ApolloPersonRequest,
+)
+from company_discovery.services.normalization import canonical_domain
+from company_discovery.settings import Settings
+
+
+class ApolloClient:
+    """Apollo people-enrichment adapter with bounded retry and async-result support."""
+
+    MAX_BATCH_SIZE = 10
+
+    def __init__(self, settings: Settings, client: httpx.Client | None = None) -> None:
+        if not settings.apollo_api_key:
+            raise ValueError("APOLLO_API_KEY is required for contact enrichment")
+        self._settings = settings
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=settings.apollo_base_url.rstrip("/"),
+            headers={
+                "X-Api-Key": settings.apollo_api_key,
+                "Content-Type": "application/json",
+                "Cache-Control": "no-cache",
+            },
+            timeout=settings.apollo_timeout_seconds,
+        )
+        self._pending_people: dict[str, list[ApolloPersonRequest]] = {}
+
+    def enrich_people(
+        self,
+        people: list[ApolloPersonRequest],
+        *,
+        reveal_email: bool,
+        reveal_phone: bool,
+    ) -> ApolloBatchResult:
+        if not people:
+            return ApolloBatchResult()
+        if len(people) > self.MAX_BATCH_SIZE:
+            raise ValueError(f"Apollo bulk enrichment accepts at most {self.MAX_BATCH_SIZE} people")
+        if reveal_phone and not self._settings.apollo_webhook_url:
+            raise ValueError(
+                "APOLLO_WEBHOOK_URL is required when phone enrichment is enabled; "
+                "use --no-phone for synchronous email-only enrichment"
+            )
+
+        payload: dict[str, Any] = {
+            "details": [self._person_payload(person) for person in people],
+            "reveal_personal_emails": False,
+            "reveal_phone_number": reveal_phone,
+            # Standard work email is synchronous. Waterfall email becomes useful only when
+            # Apollo has a webhook destination for its asynchronous completion payload.
+            "run_waterfall_email": reveal_email and bool(self._settings.apollo_webhook_url),
+            "run_waterfall_phone": reveal_phone,
+        }
+        if self._settings.apollo_webhook_url:
+            payload["webhook_url"] = self._settings.apollo_webhook_url
+        response = self._request("POST", "/api/v1/people/bulk_match", json=payload)
+        data = response.json()
+        result = self._parse(data, people)
+        if result.request_id:
+            self._pending_people[result.request_id] = people
+        return result
+
+    def poll(self, request_id: str) -> ApolloBatchResult:
+        response = self._request("GET", f"/api/v1/webhook_result/{request_id}")
+        data = response.json()
+        result = self._parse(data, self._pending_people.get(request_id, []))
+        if not result.request_id:
+            result = result.model_copy(update={"request_id": request_id})
+        if not result.pending:
+            self._pending_people.pop(request_id, None)
+        return result
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        for attempt in range(3):
+            response = self._client.request(method, path, **kwargs)
+            if response.status_code != 429 and response.status_code < 500:
+                response.raise_for_status()
+                return response
+            if attempt == 2:
+                response.raise_for_status()
+            retry_after = response.headers.get("retry-after")
+            delay = float(retry_after) if retry_after else float(2**attempt)
+            time.sleep(delay)
+        raise RuntimeError("Apollo request retry loop exited unexpectedly")
+
+    @staticmethod
+    def _person_payload(person: ApolloPersonRequest) -> dict[str, str]:
+        payload = {
+            "first_name": person.first_name,
+            "last_name": person.last_name,
+            "name": person.full_name,
+            "organization_name": person.company_name,
+            "domain": person.company_domain,
+        }
+        if person.linkedin_url:
+            payload["linkedin_url"] = person.linkedin_url
+        return payload
+
+    @classmethod
+    def _parse(
+        cls, payload: dict[str, Any], requested: list[ApolloPersonRequest]
+    ) -> ApolloBatchResult:
+        request_id = cls._request_id(payload)
+        status = str(payload.get("status") or payload.get("state") or "").lower()
+        pending = status in {"pending", "processing", "queued", "running"}
+        source = payload.get("data") if isinstance(payload.get("data"), dict) else payload
+        records = source.get("matches") or source.get("people") or source.get("results") or []
+        if isinstance(records, dict):
+            records = records.get("matches") or records.get("people") or records.get("results") or []
+        if not isinstance(records, list):
+            records = []
+        if request_id and not records and status not in {"complete", "completed", "success", "succeeded"}:
+            pending = True
+
+        matches: list[ApolloPersonMatch] = []
+        for index, requested_person in enumerate(requested):
+            raw = records[index] if index < len(records) and isinstance(records[index], dict) else {}
+            person = raw.get("person") if isinstance(raw.get("person"), dict) else raw
+            found = bool(person) and not bool(raw.get("error"))
+            organization = person.get("organization") if isinstance(person.get("organization"), dict) else {}
+            phones = cls._phones(person)
+            raw_domain = (
+                organization.get("primary_domain")
+                or organization.get("website_url")
+                or person.get("organization_domain")
+            )
+            matches.append(
+                ApolloPersonMatch(
+                    candidate_id=requested_person.candidate_id,
+                    person_found=found,
+                    full_name=person.get("name") or cls._joined_name(person),
+                    linkedin_url=person.get("linkedin_url"),
+                    title=person.get("title"),
+                    organization_name=organization.get("name") or person.get("organization_name"),
+                    organization_domain=canonical_domain(str(raw_domain)) if raw_domain else None,
+                    email=person.get("email"),
+                    email_status=person.get("email_status"),
+                    phones=phones,
+                    apollo_person_id=person.get("id"),
+                    raw=raw,
+                )
+            )
+        return ApolloBatchResult(matches=matches, request_id=request_id, pending=pending)
+
+    @staticmethod
+    def _request_id(payload: dict[str, Any]) -> str | None:
+        direct = payload.get("request_id") or payload.get("requestId")
+        if direct:
+            return str(direct)
+        data = payload.get("data")
+        if isinstance(data, dict):
+            nested = data.get("request_id") or data.get("requestId")
+            return str(nested) if nested else None
+        return None
+
+    @staticmethod
+    def _joined_name(person: dict[str, Any]) -> str | None:
+        name = " ".join(
+            part for part in (person.get("first_name"), person.get("last_name")) if part
+        )
+        return name or None
+
+    @staticmethod
+    def _phones(person: dict[str, Any]) -> list[str]:
+        values: list[str] = []
+        for phone in person.get("phone_numbers") or []:
+            if not isinstance(phone, dict):
+                continue
+            value = phone.get("sanitized_number") or phone.get("raw_number") or phone.get("number")
+            if value and value not in values:
+                values.append(str(value))
+        direct = person.get("phone") or person.get("mobile_phone")
+        if direct and str(direct) not in values:
+            values.append(str(direct))
+        return values
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()

company_discovery/adapters/exa.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from company_discovery.domain.models import ExaSearchResult
+from company_discovery.settings import Settings
+
+
+class ExaClient:
+    """Minimal Exa company-search adapter that preserves each provider payload."""
+
+    def __init__(self, settings: Settings, client: httpx.Client | None = None) -> None:
+        if not settings.exa_api_key:
+            raise ValueError("EXA_API_KEY is required for external discovery")
+        self._settings = settings
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=settings.exa_base_url.rstrip("/"),
+            headers={"x-api-key": settings.exa_api_key, "content-type": "application/json"},
+            timeout=settings.exa_timeout_seconds,
+        )
+        self._last_cost_dollars = 0.0
+        self._last_request_at: float | None = None
+
+    @property
+    def last_cost_dollars(self) -> float:
+        return self._last_cost_dollars
+
+    def search(self, query: str, *, country: str, num_results: int) -> list[ExaSearchResult]:
+        return self._search(query, country=country, num_results=num_results, category="company")
+
+    def search_people(
+        self, query: str, *, country: str, num_results: int
+    ) -> list[ExaSearchResult]:
+        return self._search(query, country=country, num_results=num_results, category="people")
+
+    def search_contact_evidence(
+        self, query: str, *, country: str, num_results: int
+    ) -> list[ExaSearchResult]:
+        return self._search(query, country=country, num_results=num_results, category=None)
+
+    def _search(
+        self, query: str, *, country: str, num_results: int, category: str | None
+    ) -> list[ExaSearchResult]:
+        payload = {
+            "query": query,
+            "numResults": max(1, min(num_results, 100)),
+            "type": "auto",
+            "userLocation": country.upper(),
+            "contents": {"text": {"maxCharacters": 3000}},
+        }
+        if category is not None:
+            payload["category"] = category
+        if category == "company":
+            payload["systemPrompt"] = (
+                "Return official operating-company websites. Avoid directories, associations, "
+                "marketplaces, news pages, and duplicate companies."
+            )
+        response = self._post_with_retry(payload)
+        data = response.json()
+        self._last_cost_dollars = self._read_cost(data)
+        return [
+            ExaSearchResult(
+                query=query,
+                position=index,
+                title=item.get("title") or "",
+                url=item.get("url") or "",
+                text=item.get("text"),
+                published_date=item.get("publishedDate"),
+                exa_id=item.get("id"),
+                raw=item,
+            )
+            for index, item in enumerate(data.get("results", []), start=1)
+        ]
+
+    def _post_with_retry(self, payload: dict[str, Any]) -> httpx.Response:
+        for attempt in range(3):
+            self._pace_request()
+            response = self._client.post("/search", json=payload)
+            self._last_request_at = time.monotonic()
+            if response.status_code != 429 and response.status_code < 500:
+                response.raise_for_status()
+                return response
+            if attempt == 2:
+                response.raise_for_status()
+            retry_after = response.headers.get("retry-after")
+            delay = float(retry_after) if retry_after and retry_after.isdigit() else 2**attempt
+            time.sleep(delay)
+        raise RuntimeError("Exa request retry loop exited unexpectedly")
+
+    def _pace_request(self) -> None:
+        if self._last_request_at is None:
+            return
+        remaining = 0.21 - (time.monotonic() - self._last_request_at)
+        if remaining > 0:
+            time.sleep(remaining)
+
+    @staticmethod
+    def _read_cost(payload: dict[str, Any]) -> float:
+        cost = payload.get("costDollars")
+        if isinstance(cost, dict) and isinstance(cost.get("total"), (int, float)):
+            return float(cost["total"])
+        if isinstance(cost, (int, float)):
+            return float(cost)
+        return 0.0
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()

company_discovery/adapters/llm.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import time
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from company_discovery.settings import Settings
+
+
+class OpenAICompatibleLLM:
+    """Structured-output client for OpenAI-compatible chat completion APIs."""
+
+    def __init__(self, settings: Settings, client: httpx.Client | None = None) -> None:
+        if not settings.llm_api_key:
+            raise ValueError("LLM_API_KEY is required for query generation and evaluation")
+        self._settings = settings
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=settings.llm_base_url.rstrip("/"),
+            headers={
+                "Authorization": f"Bearer {settings.llm_api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=settings.llm_timeout_seconds,
+        )
+
+    def generate(
+        self,
+        *,
+        system_prompt: str,
+        user_prompt: str,
+        response_model: type[BaseModel],
+    ) -> BaseModel:
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+        schema = response_model.model_json_schema()
+        response_format = self._response_format(response_model, schema)
+        if self._settings.resolved_llm_response_format == "json_object":
+            messages[0]["content"] = (
+                f"{system_prompt}\n\n"
+                "Return JSON only. The JSON must match this exact JSON Schema:\n"
+                f"{json.dumps(schema, ensure_ascii=True)}"
+            )
+        for attempt in range(2):
+            payload = {
+                "model": self._settings.llm_model,
+                "messages": messages,
+                "max_tokens": self._settings.llm_max_tokens,
+                "response_format": response_format,
+            }
+            response = self._post_with_retry(payload)
+            message = response.json()["choices"][0]["message"]
+            if message.get("refusal"):
+                raise ValueError(f"LLM refused structured generation: {message['refusal']}")
+            content = message.get("content") or ""
+            if not isinstance(content, str):
+                content = ""
+            try:
+                return response_model.model_validate_json(content)
+            except (ValidationError, json.JSONDecodeError) as exc:
+                if attempt == 1:
+                    raise ValueError(f"LLM returned invalid {response_model.__name__}: {exc}") from exc
+                messages.extend(
+                    [
+                        {"role": "assistant", "content": content},
+                        {
+                            "role": "user",
+                            "content": (
+                                "Correct the response to satisfy the supplied JSON Schema. "
+                                f"Validation error: {exc}. Return JSON only."
+                            ),
+                        },
+                    ]
+                )
+        raise RuntimeError("structured generation exhausted retries")
+
+    def _response_format(self, response_model: type[BaseModel], schema: dict) -> dict:
+        if self._settings.resolved_llm_response_format == "json_object":
+            return {"type": "json_object"}
+        return {
+            "type": "json_schema",
+            "json_schema": {
+                "name": response_model.__name__.lower(),
+                "strict": True,
+                "schema": schema,
+            },
+        }
+
+    def _post_with_retry(self, payload: dict) -> httpx.Response:
+        for attempt in range(3):
+            try:
+                response = self._client.post("/chat/completions", json=payload)
+            except httpx.TransportError:
+                if attempt == 2:
+                    raise
+                time.sleep(2**attempt)
+                continue
+            if response.status_code != 429 and response.status_code < 500:
+                if response.is_error:
+                    detail = response.text.strip()[:1000]
+                    raise ValueError(
+                        f"LLM API returned HTTP {response.status_code}: {detail or 'no error body'}"
+                    )
+                return response
+            if attempt == 2:
+                response.raise_for_status()
+            retry_after = response.headers.get("retry-after")
+            delay = float(retry_after) if retry_after and retry_after.isdigit() else 2**attempt
+            time.sleep(delay)
+        raise RuntimeError("LLM request retry loop exited unexpectedly")
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()

company_discovery/adapters/protocols.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from pydantic import BaseModel
+
+from company_discovery.domain.contact_models import ApolloBatchResult, ApolloPersonRequest
+from company_discovery.domain.models import ExaSearchResult
+
+
+class StructuredLLM(Protocol):
+    def generate(
+        self,
+        *,
+        system_prompt: str,
+        user_prompt: str,
+        response_model: type[BaseModel],
+    ) -> BaseModel: ...
+
+    def close(self) -> None: ...
+
+
+class CompanySearchProvider(Protocol):
+    @property
+    def last_cost_dollars(self) -> float: ...
+
+    def search(self, query: str, *, country: str, num_results: int) -> list[ExaSearchResult]: ...
+
+    def close(self) -> None: ...
+
+
+class ContactSearchProvider(Protocol):
+    @property
+    def last_cost_dollars(self) -> float: ...
+
+    def search_people(
+        self, query: str, *, country: str, num_results: int
+    ) -> list[ExaSearchResult]: ...
+
+    def search_contact_evidence(
+        self, query: str, *, country: str, num_results: int
+    ) -> list[ExaSearchResult]: ...
+
+    def close(self) -> None: ...
+
+
+class ContactEnrichmentProvider(Protocol):
+    def enrich_people(
+        self,
+        people: list[ApolloPersonRequest],
+        *,
+        reveal_email: bool,
+        reveal_phone: bool,
+    ) -> ApolloBatchResult: ...
+
+    def poll(self, request_id: str) -> ApolloBatchResult: ...
+
+    def close(self) -> None: ...

company_discovery/adapters/website.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from company_discovery.domain.models import WebsitePage
+from company_discovery.services.normalization import canonical_domain
+from company_discovery.services.enrichment_resolver import normalize_linkedin_company_url
+
+
+class _PageParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.text: list[str] = []
+        self.links: list[tuple[str, str]] = []
+        self.title = ""
+        self._hidden = 0
+        self._in_title = False
+        self._anchor_href: str | None = None
+        self._anchor_text: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attributes = dict(attrs)
+        if tag in {"script", "style", "noscript", "svg"}:
+            self._hidden += 1
+        if tag == "title":
+            self._in_title = True
+        if tag == "a":
+            self._anchor_href = attributes.get("href")
+            self._anchor_text = []
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in {"script", "style", "noscript", "svg"} and self._hidden:
+            self._hidden -= 1
+        if tag == "title":
+            self._in_title = False
+        if tag == "a" and self._anchor_href:
+            self.links.append((self._anchor_href, " ".join(self._anchor_text)))
+            self._anchor_href = None
+
+    def handle_data(self, data: str) -> None:
+        value = " ".join(data.split())
+        if not value:
+            return
+        if self._in_title:
+            self.title = f"{self.title} {value}".strip()
+        if self._anchor_href is not None:
+            self._anchor_text.append(value)
+        if not self._hidden:
+            self.text.append(value)
+
+
+class WebsiteClient:
+    """Fetch a small official-site page pack anchored to a known root domain."""
+
+    PAGE_TERMS = {
+        "contact": ("contact", "locations", "location", "offices"),
+        "about": ("about", "company", "who-we-are", "our-story", "ownership"),
+    }
+
+    def __init__(
+        self,
+        *,
+        timeout_seconds: float = 20.0,
+        max_pages: int = 4,
+        max_characters: int = 16000,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            follow_redirects=True,
+            timeout=timeout_seconds,
+            headers={"User-Agent": "CompanyEnrichmentBot/1.0 (+business-information-research)"},
+        )
+        self._max_pages = max_pages
+        self._max_characters = max_characters
+
+    def fetch(self, domain: str) -> list[WebsitePage]:
+        homepage = self._fetch_homepage(domain)
+        if homepage is None:
+            return []
+        page, links = homepage
+        pages = [page]
+        for url, page_type in self._rank_links(page.url, domain, links):
+            if len(pages) >= self._max_pages:
+                break
+            fetched = self._fetch_page(url, page_type)
+            if fetched is not None and fetched.url not in {item.url for item in pages}:
+                pages.append(fetched)
+        return pages
+
+    def _fetch_homepage(self, domain: str) -> tuple[WebsitePage, list[tuple[str, str]]] | None:
+        for scheme in ("https", "http"):
+            result = self._request(f"{scheme}://{domain}", "homepage")
+            if result is not None:
+                return result
+        return None
+
+    def _fetch_page(self, url: str, page_type: str) -> WebsitePage | None:
+        result = self._request(url, page_type)
+        return result[0] if result else None
+
+    def _request(self, url: str, page_type: str) -> tuple[WebsitePage, list[tuple[str, str]]] | None:
+        try:
+            response = self._client.get(url)
+            response.raise_for_status()
+        except (httpx.HTTPError, ValueError):
+            return None
+        content_type = response.headers.get("content-type", "")
+        if "html" not in content_type.lower():
+            return None
+        parser = _PageParser()
+        parser.feed(response.text)
+        text = "\n".join(parser.text)[: self._max_characters]
+        linkedin_urls = list(
+            dict.fromkeys(
+                normalized
+                for href, _ in parser.links
+                if (normalized := normalize_linkedin_company_url(urljoin(str(response.url), href)))
+            )
+        )
+        return (
+            WebsitePage(
+                url=str(response.url),
+                title=parser.title,
+                text=text,
+                page_type=page_type,
+                linkedin_urls=linkedin_urls,
+            ),
+            parser.links,
+        )
+
+    def _rank_links(
+        self, base_url: str, domain: str, links: list[tuple[str, str]]
+    ) -> list[tuple[str, str]]:
+        ranked: list[tuple[int, str, str]] = []
+        seen: set[str] = set()
+        for href, label in links:
+            url = urljoin(base_url, href).split("#", 1)[0]
+            if url in seen or canonical_domain(urlparse(url).hostname or "") != domain:
+                continue
+            haystack = f"{urlparse(url).path} {label}".lower()
+            for priority, (page_type, terms) in enumerate(self.PAGE_TERMS.items()):
+                if any(term in haystack for term in terms):
+                    seen.add(url)
+                    ranked.append((priority, url, page_type))
+                    break
+        return [(url, page_type) for _, url, page_type in sorted(ranked)]
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()

company_discovery/bundled_skills/__init__.py

@@ -0,0 +1 @@
+"""Bundled agent skills installed by the leads CLI."""