leads-cli 0.1.0__py3-none-any.whl

company_discovery/services/evaluator.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+
+from company_discovery.adapters.protocols import StructuredLLM
+from company_discovery.domain.models import CandidateEvaluation, NormalizedCandidate
+from company_discovery.domain.spec import CompanySearchSpec
+from company_discovery.prompts import load_prompt
+
+
+class CandidateEvaluator:
+    def __init__(self, llm: StructuredLLM) -> None:
+        self._llm = llm
+        self._system_prompt = load_prompt("candidate_evaluation")
+
+    def evaluate(
+        self,
+        spec: CompanySearchSpec,
+        candidate: NormalizedCandidate,
+    ) -> CandidateEvaluation:
+        prompt = json.dumps(
+            {
+                "search_spec": spec.model_dump(mode="json"),
+                "candidate": candidate.model_dump(mode="json"),
+            },
+            indent=2,
+        )
+        result = self._llm.generate(
+            system_prompt=self._system_prompt,
+            user_prompt=prompt,
+            response_model=CandidateEvaluation,
+        )
+        if not isinstance(result, CandidateEvaluation):
+            raise TypeError(
+                f"LLM returned {type(result).__name__}, expected CandidateEvaluation"
+            )
+        evaluation = result
+        return evaluation.model_copy(
+            update={"company_name": candidate.company_name, "domain": candidate.domain}
+        )

company_discovery/services/hygiene.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from company_discovery.domain.models import NormalizedCandidate
+
+
+KNOWN_NON_COMPANY_DOMAINS = frozenset(
+    {
+        "bbb.org",
+        "bloomberg.com",
+        "chamberofcommerce.com",
+        "crunchbase.com",
+        "facebook.com",
+        "glassdoor.com",
+        "instagram.com",
+        "linkedin.com",
+        "mapquest.com",
+        "manta.com",
+        "opencorporates.com",
+        "pitchbook.com",
+        "wikipedia.org",
+        "yelp.com",
+        "yellowpages.com",
+        "youtube.com",
+    }
+)
+
+
+@dataclass(frozen=True)
+class HygieneResult:
+    accepted: list[NormalizedCandidate]
+    rejected: list[tuple[NormalizedCandidate, str]]
+
+
+def filter_hygiene(candidates: list[NormalizedCandidate]) -> HygieneResult:
+    accepted: list[NormalizedCandidate] = []
+    rejected: list[tuple[NormalizedCandidate, str]] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        if candidate.domain in seen:
+            rejected.append((candidate, "duplicate_domain"))
+        elif candidate.domain in KNOWN_NON_COMPANY_DOMAINS:
+            rejected.append((candidate, "known_non_company_domain"))
+        elif not candidate.company_name.strip():
+            rejected.append((candidate, "missing_company_name"))
+        else:
+            seen.add(candidate.domain)
+            accepted.append(candidate)
+    return HygieneResult(accepted=accepted, rejected=rejected)
+

company_discovery/services/memory.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from company_discovery.db.repository import MemoryRecord
+from company_discovery.domain.models import FitVerdict
+from company_discovery.domain.spec import CompanySearchSpec, NoveltyMode
+
+
+@dataclass(frozen=True)
+class SkippedMemoryRecord:
+    record: MemoryRecord
+    reason: str
+
+
+@dataclass(frozen=True)
+class MemoryScanResult:
+    matched: int
+    reusable: list[MemoryRecord]
+    recheck: list[MemoryRecord]
+    skipped: list[SkippedMemoryRecord]
+
+
+class MemoryMatcher:
+    def scan(self, spec: CompanySearchSpec, records: list[MemoryRecord]) -> MemoryScanResult:
+        if spec.novelty_mode == NoveltyMode.ONLY_NEW:
+            return MemoryScanResult(
+                matched=0,
+                reusable=[],
+                recheck=[],
+                skipped=[
+                    SkippedMemoryRecord(record, "memory_disabled_only_new") for record in records
+                ],
+            )
+
+        reusable: list[MemoryRecord] = []
+        recheck: list[MemoryRecord] = []
+        skipped: list[SkippedMemoryRecord] = []
+        for record in records:
+            mismatch = self._hard_mismatch(spec, record)
+            if mismatch:
+                skipped.append(SkippedMemoryRecord(record, mismatch))
+                continue
+            if (
+                record.latest_fit == FitVerdict.GOOD.value
+                and record.latest_evaluation is not None
+                and not self._requires_recheck(spec, record)
+            ):
+                reusable.append(record)
+            else:
+                recheck.append(record)
+
+        return MemoryScanResult(
+            matched=len(reusable) + len(recheck),
+            reusable=reusable,
+            recheck=recheck,
+            skipped=skipped,
+        )
+
+    @staticmethod
+    def _hard_mismatch(spec: CompanySearchSpec, record: MemoryRecord) -> str | None:
+        candidate = record.candidate
+        previous = record.latest_spec
+        reason_codes = set(record.latest_reason_codes)
+        if previous is not None:
+            previous_target = (
+                record.latest_evaluation.target_vertical
+                if record.latest_evaluation is not None
+                else None
+            )
+            same_vertical = previous_target == spec.vertical.key or (
+                len(previous.verticals) == 1 and previous.verticals[0] == spec.vertical
+            )
+            if "vertical_mismatch" in reason_codes and same_vertical:
+                return "prior_vertical_mismatch_same_spec"
+            if (
+                "geography_mismatch" in reason_codes
+                and previous.geography == spec.geography
+            ):
+                return "prior_geography_mismatch_same_spec"
+            if "size_mismatch" in reason_codes and previous.company_size == spec.company_size:
+                return "prior_size_mismatch_same_spec"
+            exclusion_codes = {
+                "excluded_ownership",
+                "excluded_keyword",
+                "excluded_company_pattern",
+            }
+            if reason_codes & exclusion_codes and previous.exclude == spec.exclude:
+                return "prior_exclusion_same_spec"
+        if spec.novelty_mode == NoveltyMode.UNUSED_MEMORY and record.ever_selected:
+            return "previously_selected"
+        if candidate.vertical and candidate.vertical != spec.vertical.key:
+            return "vertical_mismatch"
+        if candidate.country and candidate.country.upper() != spec.geography.country:
+            return "country_mismatch"
+        if spec.geography.states and candidate.state and candidate.state.upper() not in spec.geography.states:
+            return "state_mismatch"
+        size = spec.company_size
+        if (
+            size.employee_min is not None
+            and candidate.employee_max is not None
+            and candidate.employee_max < size.employee_min
+        ):
+            return "size_below_minimum"
+        if (
+            size.employee_max is not None
+            and candidate.employee_min is not None
+            and candidate.employee_min > size.employee_max
+        ):
+            return "size_above_maximum"
+        if (
+            candidate.ownership_type
+            and candidate.ownership_type.lower() in spec.exclude.ownership_types
+        ):
+            return "excluded_ownership"
+        searchable = " ".join(
+            [candidate.company_name]
+            + [sighting.title for sighting in candidate.sightings]
+            + [sighting.text or "" for sighting in candidate.sightings]
+        ).lower()
+        if any(keyword in searchable for keyword in spec.exclude.keywords):
+            return "excluded_keyword"
+        return None
+
+    @staticmethod
+    def _requires_recheck(spec: CompanySearchSpec, record: MemoryRecord) -> bool:
+        candidate = record.candidate
+        if candidate.vertical is None or candidate.country is None:
+            return True
+        if spec.geography.states and candidate.state is None:
+            return True
+        if not spec.company_size.is_unbounded and (
+            candidate.employee_min is None or candidate.employee_max is None
+        ):
+            return True
+
+        previous = record.latest_spec
+        if spec.include.keywords or spec.include.subtypes:
+            if previous is None or previous.include != spec.include:
+                return True
+        has_custom_exclusions = any(
+            (
+                spec.exclude.keywords,
+                spec.exclude.ownership_types,
+                spec.exclude.company_patterns,
+            )
+        )
+        if has_custom_exclusions and (previous is None or previous.exclude != spec.exclude):
+            return True
+        return False

company_discovery/services/normalization.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+from datetime import UTC, datetime
+from urllib.parse import urlparse
+
+import tldextract
+
+from company_discovery.domain.models import ExaSearchResult, NormalizedCandidate, SourceSighting
+
+
+_extract_domain = tldextract.TLDExtract(suffix_list_urls=(), cache_dir=None)
+_TITLE_SUFFIX = re.compile(r"\s+[|\-\u2013\u2014]\s+.*$")
+
+
+def canonical_domain(url: str) -> str | None:
+    value = url.strip()
+    if not value:
+        return None
+    if ":" in value and "://" not in value:
+        host, _, port = value.partition(":")
+        if not ("." in host and port.isdigit()):
+            return None
+    parsed = urlparse(value if "://" in value else f"https://{value}")
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        return None
+    extracted = _extract_domain(parsed.hostname.lower())
+    if not extracted.domain or not extracted.suffix:
+        return None
+    return f"{extracted.domain}.{extracted.suffix}"
+
+
+def candidate_name(title: str, domain: str) -> str:
+    cleaned = _TITLE_SUFFIX.sub("", title).strip()
+    if cleaned:
+        return cleaned
+    return domain.split(".", maxsplit=1)[0].replace("-", " ").title()
+
+
+def normalize_results(results: list[ExaSearchResult]) -> list[NormalizedCandidate]:
+    by_domain: OrderedDict[str, NormalizedCandidate] = OrderedDict()
+    now = datetime.now(UTC)
+    for result in results:
+        domain = canonical_domain(result.url)
+        if domain is None:
+            continue
+        sighting = SourceSighting(
+            query=result.query,
+            url=result.url,
+            title=result.title,
+            text=result.text,
+            exa_id=result.exa_id,
+            raw=result.raw,
+        )
+        existing = by_domain.get(domain)
+        if existing is None:
+            entity = _company_entity(result.raw)
+            properties = entity.get("properties", {}) if entity else {}
+            workforce = properties.get("workforce") or {}
+            headquarters = properties.get("headquarters") or {}
+            employee_total = workforce.get("total")
+            if not isinstance(employee_total, int) or employee_total < 1:
+                employee_total = None
+            country = _country_code(headquarters.get("country"))
+            by_domain[domain] = NormalizedCandidate(
+                company_name=properties.get("name") or candidate_name(result.title, domain),
+                domain=domain,
+                dedupe_key=domain,
+                country=country,
+                employee_min=employee_total,
+                employee_max=employee_total,
+                sightings=[sighting],
+                first_seen_at=now,
+                last_seen_at=now,
+            )
+        elif all(item.url != sighting.url for item in existing.sightings):
+            existing.sightings.append(sighting)
+    return list(by_domain.values())
+
+
+def _company_entity(raw: dict) -> dict:
+    entities = raw.get("entities")
+    if not isinstance(entities, list):
+        return {}
+    for entity in entities:
+        if isinstance(entity, dict) and entity.get("type") in {None, "company"}:
+            return entity
+    return {}
+
+
+def _country_code(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip().upper()
+    if normalized in {"UNITED STATES", "UNITED STATES OF AMERICA", "USA"}:
+        return "US"
+    return normalized if len(normalized) == 2 else None