leadintel 0.3.0__py3-none-any.whl

leadintel/exporters/excel_exporter.py

@@ -0,0 +1,123 @@
+"""
+Excel export for business lead lists.
+
+Generates a formatted 3-worksheet Excel workbook:
+1. All Leads
+2. High Website Opportunity (opportunity score >= 50)
+3. Data Quality Summary
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import openpyxl
+from openpyxl.styles import Font
+
+from ..models.business import Business
+
+
+def _sanitize(value: Any) -> Any:
+    """Prevent spreadsheet formula injection."""
+    if value is None:
+        return ""
+    if isinstance(value, str) and value.startswith(("=", "+", "-", "@")):
+        return "'" + value
+    return value
+
+
+# Backwards compatibility alias
+sanitize_excel_cell = _sanitize
+
+
+def _to_business(item: Any) -> Business:
+    """Ensure lead item is a Business instance."""
+    if isinstance(item, Business):
+        return item
+    if isinstance(item, dict):
+        d = dict(item)
+        if "id" not in d:
+            d["id"] = "lead_" + str(hash(str(d.get("name", ""))))
+        if "name" not in d:
+            d["name"] = "Unknown Business"
+        try:
+            return Business.model_validate(d)
+        except Exception:
+            valid_fields = {k: v for k, v in d.items() if hasattr(Business, k)}
+            return Business(id=d.get("id", "lead_temp"), name=d.get("name", "Unknown"), **valid_fields)
+    return Business(id="lead_unknown", name=str(item))
+
+
+def export_to_excel(
+    businesses: Optional[list[Any]] = None,
+    output_path: str | Path = "leads.xlsx",
+    **kwargs: Any,
+) -> str:
+    """
+    Export business leads to a 3-sheet Excel workbook.
+
+    Worksheets:
+    1. All Leads
+    2. High Website Opportunity (Score >= 50)
+    3. Data Quality Summary
+    """
+    businesses = [_to_business(b) for b in (businesses or [])]
+
+    wb = openpyxl.Workbook()
+
+    headers = [
+        "Business Name", "Category", "Address", "City", "Phone", "Email", "Website",
+        "Website Status", "Website Opportunity Score", "Score Explanation",
+        "Latitude", "Longitude", "Distance (km)", "Data Confidence", "Source", "Research Timestamp"
+    ]
+
+    # Worksheet 1: All Leads
+    ws_all = wb.active
+    ws_all.title = "All Leads"
+    ws_all.append(headers)
+    for cell in ws_all[1]:
+        cell.font = Font(bold=True)
+    ws_all.freeze_panes = "A2"
+
+    # Worksheet 2: High Website Opportunity
+    ws_high = wb.create_sheet("High Website Opportunity")
+    ws_high.append(headers)
+    for cell in ws_high[1]:
+        cell.font = Font(bold=True)
+    ws_high.freeze_panes = "A2"
+
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    for b in businesses:
+        row = [
+            b.name, b.category, b.address, b.city, b.phone, b.email, b.website,
+            b.website_status, b.website_opportunity_score, b.website_opportunity_explanation,
+            b.latitude, b.longitude, b.distance_km, b.data_confidence, b.source, timestamp
+        ]
+        sanitized_row = [_sanitize(c) for c in row]
+        ws_all.append(sanitized_row)
+
+        if b.website_opportunity_score is not None and b.website_opportunity_score >= 50:
+            ws_high.append(sanitized_row)
+
+    # Worksheet 3: Data Quality Summary
+    ws_summary = wb.create_sheet("Data Quality Summary")
+    ws_summary.append(["Metric", "Count"])
+    for cell in ws_summary[1]:
+        cell.font = Font(bold=True)
+
+    ws_summary.append(["Total Leads", len(businesses)])
+    ws_summary.append(["With Phone Numbers", sum(1 for b in businesses if b.phone)])
+    ws_summary.append(["With Email Addresses", sum(1 for b in businesses if b.email)])
+    ws_summary.append(["Verified Websites", sum(1 for b in businesses if b.website_status == "website_verified")])
+    ws_summary.append(["No Verified Official Website", sum(1 for b in businesses if b.website_status == "website_not_found_after_research")])
+    ws_summary.append(["Social Media Presence", sum(1 for b in businesses if b.facebook_url or getattr(b, "instagram_url", None) or b.linkedin_url)])
+    ws_summary.append(["Uncertain Information", sum(1 for b in businesses if b.website_status == "website_unverified")])
+    ws_summary.append(["Missing Contact Details", sum(1 for b in businesses if not b.phone and not b.email)])
+
+    out_path = Path(output_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(out_path)
+    return str(out_path.absolute())

leadintel/models/__init__.py

@@ -0,0 +1,6 @@
+"""Pydantic models for LeadIntel data structures."""
+
+from .business import Business, BusinessSearchResult, LeadScore
+from .report import BusinessReport
+
+__all__ = ["Business", "BusinessSearchResult", "LeadScore", "BusinessReport"]

leadintel/models/business.py

@@ -0,0 +1,203 @@
+"""Business data models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+WebsiteStatus = Literal[
+    "website_verified",
+    "website_not_found_after_research",
+    "website_unverified",
+    "website_broken",
+    "website_not_checked",
+]
+
+
+class Business(BaseModel):
+    """Represents a single business entity."""
+
+    # Identity
+    id: str = Field(description="Stable unique identifier (e.g. 'osm_node_12345' or slug)")
+    name: str = Field(description="Business name")
+    category: Optional[str] = Field(default=None, description="Primary industry / category")
+
+    # Location
+    address: Optional[str] = Field(default=None, description="Full formatted address")
+    city: Optional[str] = Field(default=None)
+    state: Optional[str] = Field(default=None)
+    country: Optional[str] = Field(default=None)
+    postal_code: Optional[str] = Field(default=None)
+    latitude: Optional[float] = Field(default=None)
+    longitude: Optional[float] = Field(default=None)
+    distance_meters: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Calculated distance in metres from the search center coordinates",
+    )
+    distance_km: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Calculated distance in kilometres from search center",
+    )
+
+    # Contact & Digital Presence
+    phone: Optional[str] = Field(default=None)
+    email: Optional[str] = Field(default=None)
+    website: Optional[str] = Field(default=None)
+    website_status: WebsiteStatus = Field(
+        default="website_not_checked",
+        description=(
+            "Verification status of the business website. One of: "
+            "'website_verified', 'website_not_found_after_research', "
+            "'website_unverified', 'website_broken', 'website_not_checked'."
+        ),
+    )
+    website_opportunity_score: Optional[float] = Field(
+        default=None,
+        ge=0,
+        le=100,
+        description="Deterministic 0–100 score prioritizing web dev opportunity for agencies",
+    )
+    website_opportunity_explanation: Optional[str] = Field(
+        default=None,
+        description="Evidence-based explanation of the website opportunity score",
+    )
+    detected_cms: Optional[str] = Field(
+        default=None,
+        description="Detected CMS like WordPress, Shopify, Wix",
+    )
+    has_contact_route: Optional[bool] = Field(
+        default=None,
+        description="True if a contact page or mailto link was found",
+    )
+
+    # Social
+    linkedin_url: Optional[str] = Field(default=None)
+    twitter_url: Optional[str] = Field(default=None)
+    facebook_url: Optional[str] = Field(default=None)
+    instagram_url: Optional[str] = Field(default=None)
+
+    # Metrics
+    rating: Optional[float] = Field(default=None, ge=0, le=5)
+    review_count: Optional[int] = Field(default=None, ge=0)
+    employee_count_estimate: Optional[str] = Field(
+        default=None, description="Rough headcount range, e.g. '10–50'"
+    )
+
+    # Provenance — every record must carry this for compliance
+    source: str = Field(
+        default="demo",
+        description=(
+            "Data source identifier. "
+            "'openstreetmap' → ODbL licence applies; "
+            "'demo' → synthetic data."
+        ),
+    )
+    attribution: Optional[str] = Field(
+        default=None,
+        description=(
+            "Required attribution string when source is 'openstreetmap'. "
+            "Must be displayed wherever data is shown or exported."
+        ),
+    )
+    retrieved_at: datetime = Field(default_factory=datetime.utcnow)
+    is_ai_generated: bool = Field(
+        default=False,
+        description="True when any field value was produced by an AI model",
+    )
+    data_confidence: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="Confidence indicator for data completeness and verification",
+    )
+    osm_tags: Optional[dict[str, str]] = Field(
+        default=None,
+        description="Preserved raw OpenStreetMap tags for transparency and auditability",
+    )
+    ranking_explanation: Optional[str] = Field(
+        default=None,
+        description="Human-readable explanation of why this business was ranked in this search position",
+    )
+
+    model_config = ConfigDict()
+
+    @field_serializer("retrieved_at")
+    def serialise_retrieved_at(self, v: datetime) -> str:
+        return v.isoformat()
+
+    @property
+    def osm_id(self) -> Optional[str]:
+        """Return the raw OSM element ID string if this record came from OSM."""
+        if self.id.startswith("osm_"):
+            return self.id
+        return None
+
+    @property
+    def requires_attribution(self) -> bool:
+        """True when the ODbL attribution string must be displayed."""
+        return self.source == "openstreetmap"
+
+
+class BusinessSearchResult(BaseModel):
+    """Wrapper returned by search_businesses."""
+
+    query: str
+    location: Optional[str] = None
+    category: Optional[str] = None
+    search_center: Optional[dict[str, float]] = Field(
+        default=None,
+        description="Resolved search center coordinates {'latitude': lat, 'longitude': lon}",
+    )
+    radius_meters: Optional[int] = Field(
+        default=None,
+        description="Search radius in metres applied around search center",
+    )
+    sort_by: Optional[str] = Field(
+        default=None,
+        description="Applied ranking criterion (e.g. 'highest_website_opportunity', 'closest')",
+    )
+    total_found: int = 0
+    businesses: list[Business] = Field(default_factory=list)
+    source: str = "demo"
+    provider: str = "demo"
+    retrieved_at: datetime = Field(default_factory=datetime.utcnow)
+    note: Optional[str] = Field(
+        default=None,
+        description="Human-readable note about data quality, limits, or caveats",
+    )
+    attribution: Optional[str] = Field(
+        default=None,
+        description="Attribution string — required when source is 'openstreetmap'.",
+    )
+    error: Optional[str] = Field(
+        default=None,
+        description="Error details if the search provider encountered an issue",
+    )
+
+    @field_serializer("retrieved_at")
+    def serialise_retrieved_at(self, v: datetime) -> str:
+        return v.isoformat()
+
+
+class LeadScore(BaseModel):
+    """Lead quality score for a business."""
+
+    business_id: str
+    business_name: str
+    score: float = Field(ge=0, le=100, description="0–100 lead quality score")
+    grade: str = Field(description="A / B / C / D / F")
+    factors: dict[str, float] = Field(
+        default_factory=dict,
+        description="Breakdown of individual scoring dimensions",
+    )
+    recommendation: str = Field(default="", description="Short actionable text")
+    scored_at: datetime = Field(default_factory=datetime.utcnow)
+    is_ai_generated: bool = False
+
+    @field_serializer("scored_at")
+    def serialise_scored_at(self, v: datetime) -> str:
+        return v.isoformat()

leadintel/models/report.py

@@ -0,0 +1,31 @@
+"""Business report model."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .business import Business, LeadScore
+
+
+class BusinessReport(BaseModel):
+    """Structured intelligence report for a single business."""
+
+    business: Business
+    lead_score: Optional[LeadScore] = None
+    summary: str = Field(default="", description="Executive summary")
+    strengths: list[str] = Field(default_factory=list)
+    weaknesses: list[str] = Field(default_factory=list)
+    opportunities: list[str] = Field(default_factory=list)
+    threats: list[str] = Field(default_factory=list)
+    competitors: list[str] = Field(default_factory=list, description="Competitor names")
+    generated_at: datetime = Field(default_factory=datetime.utcnow)
+    is_ai_generated: bool = False
+    disclaimer: str = Field(
+        default=(
+            "This report was generated from publicly available data. "
+            "Verify all facts independently before making business decisions."
+        )
+    )

leadintel/providers/__init__.py

@@ -0,0 +1,51 @@
+"""
+Providers package — exports the registry factory and all providers.
+
+Usage:
+    from leadintel.providers import build_registry
+
+    registry = build_registry(settings)
+    businesses, source = await registry.search(...)
+"""
+
+from __future__ import annotations
+
+from ..config import Settings
+from .base import BusinessProvider
+from .demo_provider import DemoProvider
+from .overpass_provider import OverpassProvider
+from .registry import ProviderRegistry
+
+
+def build_registry(cfg: Settings) -> ProviderRegistry:
+    """
+    Construct the provider registry from application settings.
+
+    Providers are listed in priority order (first = highest priority).
+    DemoProvider is always appended last as a guaranteed fallback.
+    """
+    providers: list[BusinessProvider] = []  # type: ignore[type-arg]
+
+    if not cfg.demo_mode:
+        # Live providers — ordered by reliability and data quality
+        providers.append(
+            OverpassProvider(
+                endpoint=cfg.overpass_endpoint,
+                radius_m=cfg.overpass_radius_m,
+                cache_ttl=cfg.cache_ttl,
+            )
+        )
+
+    # Demo is always last so the server works with zero configuration
+    providers.append(DemoProvider())  # type: ignore[arg-type]
+
+    return ProviderRegistry(providers)
+
+
+__all__ = [
+    "BusinessProvider",
+    "DemoProvider",
+    "OverpassProvider",
+    "ProviderRegistry",
+    "build_registry",
+]

leadintel/providers/base.py

@@ -0,0 +1,54 @@
+"""
+Provider base protocol.
+
+Every data provider must implement BusinessProvider.  Tools import the
+registry and call `registry.search(...)` — they never import a specific
+provider directly, so swapping or adding providers requires zero tool changes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from ..models.business import Business
+
+
+@runtime_checkable
+class BusinessProvider(Protocol):
+    """Protocol that every LeadIntel data provider must satisfy."""
+
+    #: Human-readable name shown in tool responses and logs
+    name: str
+
+    #: True when the provider can be used without any API key or auth
+    requires_auth: bool
+
+    async def search(
+        self,
+        query: str,
+        location: str | None = None,
+        category: str | None = None,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> list[Business]:
+        """
+        Search for businesses.
+
+        Args:
+            query:    Free-text keyword.  Pass "*" for a broad sweep.
+            location: City / region name or "lat,lon" coordinate string.
+            category: Industry hint (e.g. "restaurant", "software").
+            limit:    Max results to return.
+
+        Returns:
+            List of Business instances, possibly empty.
+        """
+        ...
+
+    async def get_details(self, business_id: str) -> Business | None:
+        """
+        Fetch enriched details for a known business ID.
+
+        Returns None if the ID is unknown to this provider.
+        """
+        ...

leadintel/providers/demo_provider.py

@@ -0,0 +1,65 @@
+"""
+DemoProvider — always-available fallback using synthetic fixture data.
+
+Returns the same 5 sample businesses as Phase 1.  No network required.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..data.demo import get_demo_business, search_demo_businesses
+from ..models.business import Business
+from .base import BusinessProvider
+
+
+class DemoProvider:
+    """Synthetic demo data provider.  Zero dependencies, always works."""
+
+    name: str = "demo"
+    requires_auth: bool = False
+
+    def __init__(self) -> None:
+        self.last_search_center: dict[str, float] | None = None
+        self.last_radius_meters: int | None = None
+
+    async def search(
+        self,
+        query: str,
+        location: str | None = None,
+        category: str | None = None,
+        limit: int = 10,
+        latitude: float | None = None,
+        longitude: float | None = None,
+        radius_meters: int | None = None,
+        wider_metro: bool = False,
+        **kwargs: Any,
+    ) -> list[Business]:
+        if latitude is not None and longitude is not None:
+            self.last_search_center = {"latitude": float(latitude), "longitude": float(longitude)}
+        elif location and "pune" in location.lower():
+            self.last_search_center = {"latitude": 18.5204, "longitude": 73.8567}
+        self.last_radius_meters = (
+            (radius_meters if radius_meters is not None else 25_000)
+            if wider_metro
+            else (radius_meters if radius_meters is not None else 6_000)
+        )
+
+        return search_demo_businesses(
+            query=query,
+            location=location,
+            category=category,
+            limit=limit,
+            latitude=latitude,
+            longitude=longitude,
+            radius_meters=radius_meters,
+            wider_metro=wider_metro,
+            **kwargs,
+        )
+
+    async def get_details(self, business_id: str) -> Business | None:
+        return get_demo_business(business_id)
+
+
+# Satisfy the protocol at import time (structural subtyping check)
+_: BusinessProvider = DemoProvider()  # type: ignore[assignment]