leads-cli 0.1.0__py3-none-any.whl

company_discovery/domain/models.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class DomainModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class FitVerdict(StrEnum):
+    GOOD = "good_fit"
+    POSSIBLE = "possible_fit"
+    BAD = "bad_fit"
+
+
+class MatchVerdict(StrEnum):
+    YES = "yes"
+    LIKELY = "likely"
+    UNKNOWN = "unknown"
+    NO = "no"
+
+
+class ExclusionVerdict(StrEnum):
+    YES = "yes"
+    POSSIBLE = "possible"
+    NO = "no"
+
+
+class CandidateBucket(StrEnum):
+    SELECTED = "selected"
+    RESERVE = "reserve"
+    REJECTED = "rejected"
+
+
+class QueryPlan(DomainModel):
+    queries: list[str] = Field(min_length=1, max_length=20)
+    rationale: str
+
+
+class ExaSearchResult(DomainModel):
+    query: str
+    position: int = Field(ge=1)
+    title: str
+    url: str
+    text: str | None = None
+    published_date: str | None = None
+    exa_id: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+class SourceSighting(DomainModel):
+    query: str
+    url: str
+    title: str
+    text: str | None = None
+    exa_id: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+class NormalizedCandidate(DomainModel):
+    company_name: str = Field(min_length=1)
+    domain: str = Field(min_length=1)
+    dedupe_key: str = Field(min_length=1)
+    vertical: str | None = None
+    country: str | None = None
+    state: str | None = None
+    employee_min: int | None = Field(default=None, ge=1)
+    employee_max: int | None = Field(default=None, ge=1)
+    ownership_type: str | None = None
+    excluded: bool = False
+    sightings: list[SourceSighting] = Field(default_factory=list)
+    first_seen_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    last_seen_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class CandidateEvaluation(DomainModel):
+    company_name: str
+    domain: str
+    fit: FitVerdict
+    vertical_match: MatchVerdict
+    geography_match: MatchVerdict
+    size_match: MatchVerdict
+    excluded: ExclusionVerdict
+    reason: str = Field(min_length=1)
+    reason_codes: list[str]
+    evidence: list[str]
+    inferred_vertical: str | None
+    inferred_country: str | None
+    inferred_state: str | None
+    inferred_employee_min: int | None = Field(ge=1)
+    inferred_employee_max: int | None = Field(ge=1)
+    inferred_ownership_type: str | None
+    target_vertical: str | None = None
+
+    @model_validator(mode="after")
+    def validate_consistency(self) -> "CandidateEvaluation":
+        hard_mismatch = any(
+            verdict == MatchVerdict.NO
+            for verdict in (self.vertical_match, self.geography_match, self.size_match)
+        )
+        if self.fit == FitVerdict.GOOD and (
+            hard_mismatch or self.excluded != ExclusionVerdict.NO
+        ):
+            raise ValueError("good_fit cannot contain a hard mismatch or exclusion")
+        if self.excluded == ExclusionVerdict.YES and self.fit != FitVerdict.BAD:
+            raise ValueError("an excluded candidate must be bad_fit")
+        if (
+            self.inferred_employee_min is not None
+            and self.inferred_employee_max is not None
+            and self.inferred_employee_min > self.inferred_employee_max
+        ):
+            raise ValueError("inferred employee minimum cannot exceed maximum")
+        return self
+
+
+class BucketedCandidate(DomainModel):
+    candidate: NormalizedCandidate
+    evaluation: CandidateEvaluation
+    bucket: CandidateBucket
+    source: str
+    target_vertical: str | None = None
+
+
+class RunSummary(DomainModel):
+    memory_matched: int = 0
+    memory_reused: int = 0
+    memory_rechecked: int = 0
+    memory_skipped: int = 0
+    external_gap: int = 0
+    queries_generated: int = 0
+    raw_results: int = 0
+    unique_candidates: int = 0
+    hygiene_rejected: int = 0
+    selected: int = 0
+    reserve: int = 0
+    rejected: int = 0
+
+
+class RunResult(DomainModel):
+    run_id: str
+    summary: RunSummary
+    queries: list[str]
+    candidates: list[BucketedCandidate]
+    artifact_paths: dict[str, str] = Field(default_factory=dict)
+
+
+class IndependenceStatus(StrEnum):
+    YES = "yes"
+    NO = "no"
+    UNKNOWN = "unknown"
+
+
+class InheritedFieldStatus(StrEnum):
+    INHERITED = "inherited"
+    CONFIRMED = "confirmed"
+    CONFLICT = "conflict"
+
+
+class EnrichmentOutcome(StrEnum):
+    READY = "enriched_ready"
+    GAPS = "enriched_with_gaps"
+    INDEPENDENCE_UNCONFIRMED = "independence_unconfirmed"
+    IDENTITY_CONFLICT = "identity_conflict"
+    GEOGRAPHY_CONFLICT = "geography_conflict"
+    FIT_CONFLICT = "fit_conflict"
+    FAILED = "enrichment_failed"
+
+
+class WebsitePage(DomainModel):
+    url: str
+    title: str = ""
+    text: str
+    page_type: str = "other"
+    linkedin_urls: list[str] = Field(default_factory=list)
+
+
+class PhoneObservation(DomainModel):
+    value: str
+    label: str | None = None
+    source_url: str
+
+
+class LocationObservation(DomainModel):
+    street_address: str
+    city: str
+    state: str
+    zip: str
+    country: str = "US"
+    label: str | None = None
+    source_url: str
+
+
+class OwnershipSignal(DomainModel):
+    kind: str
+    statement: str
+    source_url: str
+
+
+class LinkedInObservation(DomainModel):
+    url: str
+    source_url: str
+
+
+class EnrichmentExtraction(DomainModel):
+    observed_company_name: str | None = None
+    identity_conflict: bool = False
+    identity_conflict_reason: str | None = None
+    phones: list[PhoneObservation] = Field(default_factory=list)
+    locations: list[LocationObservation] = Field(default_factory=list)
+    ownership_signals: list[OwnershipSignal] = Field(default_factory=list)
+    linkedin_profiles: list[LinkedInObservation] = Field(default_factory=list)
+
+
+class PhoneFact(DomainModel):
+    value: str
+    display_value: str
+    source: str
+    source_url: str
+    observed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class LocationFact(DomainModel):
+    street_address: str
+    city: str
+    state: str
+    zip: str
+    country: str = "US"
+    source: str
+    source_url: str
+    observed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class IndependenceFact(DomainModel):
+    status: IndependenceStatus
+    evidence: list[str] = Field(default_factory=list)
+    source_urls: list[str] = Field(default_factory=list)
+    signal_kinds: list[str] = Field(default_factory=list)
+    observed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class LinkedInFact(DomainModel):
+    url: str
+    source: str
+    source_url: str
+    observed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class EnrichmentProfile(DomainModel):
+    phone: PhoneFact | None = None
+    location: LocationFact | None = None
+    independence: IndependenceFact | None = None
+    linkedin: LinkedInFact | None = None
+
+
+class EnrichmentItem(DomainModel):
+    company_id: int
+    discovery: dict[str, Any]
+    enrichment: EnrichmentProfile
+    inherited_status: dict[str, InheritedFieldStatus]
+    outcome: EnrichmentOutcome
+    conflicts: list[str] = Field(default_factory=list)
+    review_flags: list[str] = Field(default_factory=list)
+    trace: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class EnrichmentSummary(DomainModel):
+    processed: int = 0
+    inherited_facts: int = 0
+    memory_profiles_reused: int = 0
+    websites_fetched: int = 0
+    fallback_searches: int = 0
+    ready: int = 0
+    review: int = 0
+    blocked: int = 0
+    failed: int = 0
+
+
+class EnrichmentRunResult(DomainModel):
+    run_id: str
+    discovery_run_id: str
+    summary: EnrichmentSummary
+    items: list[EnrichmentItem]
+    artifact_paths: dict[str, str] = Field(default_factory=dict)

company_discovery/domain/spec.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import json
+import math
+from enum import StrEnum
+from pathlib import Path
+from typing import Literal
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+US_STATE_CODES = frozenset(
+    {
+        "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA",
+        "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD",
+        "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ",
+        "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC",
+        "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY",
+        "DC",
+    }
+)
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class NoveltyMode(StrEnum):
+    UNUSED_MEMORY = "unused_memory"
+    ONLY_NEW = "only_new"
+    FULL_MEMORY = "full_memory"
+
+
+class BalanceMode(StrEnum):
+    SOFT = "soft"
+    STRICT = "strict"
+    NONE = "none"
+
+
+class VerticalSpec(StrictModel):
+    key: str = Field(min_length=1, pattern=r"^[a-z0-9][a-z0-9_-]*$")
+    label: str = Field(min_length=1)
+    search_terms: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("search_terms", "seed_terms"),
+    )
+    exclude_terms: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("exclude_terms", "anti_terms"),
+    )
+    legacy_mode: str | None = Field(
+        default=None,
+        exclude=True,
+        validation_alias=AliasChoices("legacy_mode", "mode"),
+    )
+
+    @field_validator("key", mode="before")
+    @classmethod
+    def normalize_key(cls, value: str) -> str:
+        return value.strip().lower()
+
+    @field_validator("search_terms", "exclude_terms")
+    @classmethod
+    def normalize_terms(cls, values: list[str]) -> list[str]:
+        return list(dict.fromkeys(value.strip().lower() for value in values if value.strip()))
+
+    @field_validator("legacy_mode")
+    @classmethod
+    def normalize_legacy_mode(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        normalized = value.strip().lower()
+        if normalized not in {"known", "exploratory"}:
+            raise ValueError("legacy vertical mode must be known or exploratory")
+        return normalized
+
+
+class GeographySpec(StrictModel):
+    country: str = Field(default="US", min_length=2, max_length=2)
+    states: list[str] = Field(default_factory=list)
+
+    @field_validator("country")
+    @classmethod
+    def normalize_country(cls, value: str) -> str:
+        return value.upper()
+
+    @field_validator("states")
+    @classmethod
+    def normalize_states(cls, values: list[str]) -> list[str]:
+        return list(dict.fromkeys(value.upper() for value in values))
+
+    @model_validator(mode="after")
+    def validate_states(self) -> "GeographySpec":
+        if self.country == "US":
+            invalid = sorted(set(self.states) - US_STATE_CODES)
+            if invalid:
+                raise ValueError(f"invalid US state codes: {', '.join(invalid)}")
+        return self
+
+
+class CompanySizeSpec(StrictModel):
+    employee_min: int | None = Field(default=None, ge=1)
+    employee_max: int | None = Field(default=None, ge=1)
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "CompanySizeSpec":
+        if (
+            self.employee_min is not None
+            and self.employee_max is not None
+            and self.employee_min > self.employee_max
+        ):
+            raise ValueError("employee_min cannot exceed employee_max")
+        return self
+
+    @property
+    def is_unbounded(self) -> bool:
+        return self.employee_min is None and self.employee_max is None
+
+
+class IncludeSpec(StrictModel):
+    keywords: list[str] = Field(default_factory=list)
+    subtypes: list[str] = Field(default_factory=list)
+
+    @field_validator("keywords", "subtypes")
+    @classmethod
+    def normalize_values(cls, values: list[str]) -> list[str]:
+        return list(dict.fromkeys(value.strip().lower() for value in values if value.strip()))
+
+
+class OwnershipSignalKind(StrEnum):
+    FAMILY_OWNED = "family_owned"
+    FRANCHISE = "franchise"
+    PARENT = "parent"
+    SUBSIDIARY = "subsidiary"
+    DIVISION = "division"
+    ACQUIRED = "acquired"
+
+
+class StructuredExcludeSpec(StrictModel):
+    ownership_signals: list[OwnershipSignalKind] = Field(default_factory=list)
+
+    @field_validator("ownership_signals", mode="before")
+    @classmethod
+    def normalize_ownership_signals(cls, values: object) -> object:
+        if not isinstance(values, list):
+            return values
+        return list(
+            dict.fromkeys(
+                value.strip().lower() if isinstance(value, str) else value
+                for value in values
+            )
+        )
+
+
+class ExcludeSpec(StrictModel):
+    keywords: list[str] = Field(default_factory=list)
+    ownership_types: list[str] = Field(default_factory=list)
+    company_patterns: list[str] = Field(default_factory=list)
+    structured: StructuredExcludeSpec = Field(default_factory=StructuredExcludeSpec)
+
+    @field_validator("keywords", "ownership_types", "company_patterns")
+    @classmethod
+    def normalize_values(cls, values: list[str]) -> list[str]:
+        return list(dict.fromkeys(value.strip().lower() for value in values if value.strip()))
+
+
+class ExternalSearchSpec(StrictModel):
+    exa_searches: int = Field(default=8, ge=1, le=20)
+    results_per_search: int = Field(default=5, ge=1, le=100)
+
+
+class CompanySearchSpec(StrictModel):
+    version: Literal[1]
+    count: int = Field(ge=1, le=1000)
+    verticals: list[VerticalSpec] = Field(
+        min_length=1,
+        validation_alias=AliasChoices("verticals", "vertical"),
+    )
+    geography: GeographySpec = Field(default_factory=GeographySpec)
+    company_size: CompanySizeSpec = Field(default_factory=CompanySizeSpec)
+    include: IncludeSpec = Field(default_factory=IncludeSpec)
+    exclude: ExcludeSpec = Field(default_factory=ExcludeSpec)
+    novelty_mode: NoveltyMode = NoveltyMode.UNUSED_MEMORY
+    reserve_ratio: float = Field(default=0.5, ge=0, le=2)
+    balance_mode: BalanceMode = BalanceMode.SOFT
+    external_search: ExternalSearchSpec = Field(default_factory=ExternalSearchSpec)
+
+    @field_validator("verticals", mode="before")
+    @classmethod
+    def accept_single_vertical(cls, value: object) -> object:
+        return [value] if isinstance(value, dict) else value
+
+    @field_validator("novelty_mode", mode="before")
+    @classmethod
+    def migrate_legacy_novelty_modes(cls, value: object) -> object:
+        # Keep persisted v1 specs and old agent-generated files runnable.
+        return {
+            "prefer_new": NoveltyMode.UNUSED_MEMORY,
+            "allow_known": NoveltyMode.FULL_MEMORY,
+        }.get(value, value)
+
+    @field_validator("verticals")
+    @classmethod
+    def unique_verticals(cls, values: list[VerticalSpec]) -> list[VerticalSpec]:
+        keys = [vertical.key for vertical in values]
+        if len(keys) != len(set(keys)):
+            raise ValueError("vertical keys must be unique")
+        return values
+
+    @classmethod
+    def from_file(cls, path: Path) -> "CompanySearchSpec":
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise ValueError(f"spec file does not exist: {path}") from exc
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"spec is not valid JSON: {exc}") from exc
+        return cls.model_validate(payload)
+
+    @property
+    def is_national(self) -> bool:
+        return not self.geography.states
+
+    @property
+    def reserve_count(self) -> int:
+        if self.reserve_ratio == 0:
+            return 0
+        return math.ceil(self.count * self.reserve_ratio)
+
+    @property
+    def vertical(self) -> VerticalSpec:
+        if len(self.verticals) != 1:
+            raise ValueError("single-vertical operation requires exactly one vertical")
+        return self.verticals[0]
+
+    def lane_spec(self, vertical: VerticalSpec, count: int) -> "CompanySearchSpec":
+        return self.model_copy(update={"verticals": [vertical], "count": max(1, count)})
+
+    @property
+    def vertical_quotas(self) -> dict[str, int]:
+        base, remainder = divmod(self.count, len(self.verticals))
+        return {
+            vertical.key: base + (1 if index < remainder else 0)
+            for index, vertical in enumerate(self.verticals)
+        }
+
+    @property
+    def missing_constraints(self) -> list[str]:
+        missing: list[str] = []
+        if self.is_national:
+            missing.append("national search mode used")
+        if self.company_size.is_unbounded:
+            missing.append("no size filter applied")
+        if not any(
+            (
+                self.exclude.keywords,
+                self.exclude.ownership_types,
+                self.exclude.company_patterns,
+                self.exclude.structured.ownership_signals,
+            )
+        ):
+            missing.append("no custom exclusions applied")
+        return missing