leadintel 0.3.0__py3-none-any.whl

leadintel/__init__.py

@@ -0,0 +1,6 @@
+"""LeadIntel — open-source MCP server for B2B lead generation."""
+
+from .storage.db import init_db
+
+__version__ = "0.3.0"
+__all__ = ["init_db", "__version__"]

leadintel/__main__.py

@@ -0,0 +1,6 @@
+"""Module entrypoint: python -m leadintel"""
+
+from .server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

leadintel/config.py

@@ -0,0 +1,165 @@
+"""
+LeadIntel configuration loaded from environment variables.
+
+Core principle: ZERO mandatory API keys.
+All external services are free and optional.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+# Load .env with intelligent path resolution (handles cwd, repo root, Claude Desktop launch)
+def _load_env_configuration() -> None:
+    # 1. Explicit path in env var
+    custom_path = os.environ.get("LEADINTEL_ENV_FILE")
+    if custom_path:
+        p = Path(custom_path).expanduser().resolve()
+        if p.is_file():
+            load_dotenv(p)
+            return
+
+    # 2. Current working directory
+    cwd_env = Path.cwd() / ".env"
+    if cwd_env.is_file():
+        load_dotenv(cwd_env)
+        return
+
+    # 3. Project root (relative to this file: src/leadintel/config.py -> repo root)
+    repo_root_env = Path(__file__).resolve().parent.parent.parent / ".env"
+    if repo_root_env.is_file():
+        load_dotenv(repo_root_env)
+        return
+
+    # 4. Search upward from current working directory
+    for parent in Path.cwd().parents:
+        candidate = parent / ".env"
+        if candidate.is_file():
+            load_dotenv(candidate)
+            return
+
+
+_load_env_configuration()
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable configuration object for LeadIntel."""
+
+    # ── Overpass / OpenStreetMap ──────────────────────────────────────────────
+    overpass_endpoint: str = field(
+        default_factory=lambda: os.environ.get(
+            "OVERPASS_ENDPOINT", "https://overpass-api.de/api/interpreter"
+        )
+    )
+    # Search radius in metres around a geocoded point
+    overpass_radius_m: int = field(
+        default_factory=lambda: int(os.environ.get("OVERPASS_RADIUS_M", "5000"))
+    )
+
+    # ── Ollama (optional local AI) ────────────────────────────────────────────
+    ollama_enabled: bool = field(
+        default_factory=lambda: os.environ.get("OLLAMA_ENABLED", "false").lower()
+        in ("true", "1", "yes")
+    )
+    ollama_base_url: str = field(
+        default_factory=lambda: os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+    )
+    ollama_model: str = field(
+        default_factory=lambda: os.environ.get("OLLAMA_MODEL", "llama3")
+    )
+
+    # ── Storage ───────────────────────────────────────────────────────────────
+    database_path: str = field(
+        default_factory=lambda: os.environ.get("LEADINTEL_DB_PATH", "leadintel.db")
+    )
+
+    # ── HTTP / cache ──────────────────────────────────────────────────────────
+    # In-process result cache TTL in seconds (max 604 800 = 7 days per OSM policy)
+    cache_ttl: int = field(
+        default_factory=lambda: int(os.environ.get("CACHE_TTL", "3600"))
+    )
+    # HTTP request timeout for external calls (seconds)
+    request_timeout: float = field(
+        default_factory=lambda: float(os.environ.get("REQUEST_TIMEOUT", "30.0"))
+    )
+    # Respect robots.txt during website analysis
+    respect_robots: bool = field(
+        default_factory=lambda: os.environ.get("RESPECT_ROBOTS", "true").lower()
+        not in ("false", "0", "no")
+    )
+
+    # ── Logging ───────────────────────────────────────────────────────────────
+    log_level: str = field(
+        default_factory=lambda: os.environ.get("LOG_LEVEL", "INFO")
+    )
+
+    # ── Demo mode ─────────────────────────────────────────────────────────────
+    # When True, the DemoProvider is the ONLY provider (no network calls).
+    # When False, live providers (Overpass, etc.) are tried first with demo fallback.
+    demo_mode: bool = field(
+        default_factory=lambda: os.environ.get("DEMO_MODE", "false").lower()
+        in ("true", "1", "yes")
+    )
+
+    # ── Legacy / optional third-party keys (kept for future providers) ────────
+    # These are never required; presence enables richer optional features.
+    google_places_api_key: str = field(
+        default_factory=lambda: os.environ.get("GOOGLE_PLACES_API_KEY", ""),
+        repr=False,
+    )
+    pagespeed_api_key: str = field(
+        default_factory=lambda: os.environ.get("PAGESPEED_API_KEY", ""),
+        repr=False,
+    )
+    gemini_api_key: str = field(
+        default_factory=lambda: os.environ.get("GEMINI_API_KEY", ""),
+        repr=False,
+    )
+
+    def __repr__(self) -> str:
+        """Safe string representation masking all sensitive tokens."""
+        return f"Settings({self.safe_dict()})"
+
+    # ── Derived properties ────────────────────────────────────────────────────
+
+    @property
+    def has_ollama(self) -> bool:
+        return self.ollama_enabled
+
+    @property
+    def has_google_places(self) -> bool:
+        return bool(self.google_places_api_key)
+
+    @property
+    def has_gemini(self) -> bool:
+        return bool(self.gemini_api_key)
+
+    def safe_dict(self) -> dict:
+        """Return config as dict with secrets redacted (safe for logging)."""
+        return {
+            "overpass_endpoint": self.overpass_endpoint,
+            "overpass_radius_m": self.overpass_radius_m,
+            "ollama_enabled": self.ollama_enabled,
+            "ollama_base_url": self.ollama_base_url,
+            "ollama_model": self.ollama_model,
+            "database_path": self.database_path,
+            "cache_ttl": self.cache_ttl,
+            "request_timeout": self.request_timeout,
+            "respect_robots": self.respect_robots,
+            "log_level": self.log_level,
+            "demo_mode": self.demo_mode,
+            # Third-party keys — never log the actual value
+            "google_places_api_key": "***" if self.google_places_api_key else "(not set)",
+            "pagespeed_api_key": "***" if self.pagespeed_api_key else "(not set)",
+            "gemini_api_key": "***" if self.gemini_api_key else "(not set)",
+        }
+
+
+# Module-level singleton imported throughout the codebase
+settings = Settings()

leadintel/data/__init__.py

@@ -0,0 +1 @@
+"""Data package init."""

leadintel/data/demo.py

@@ -0,0 +1,315 @@
+"""Demo data for development and testing — no real API calls."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.business import Business
+
+DEMO_BUSINESSES: list[Business] = [
+    Business(
+        id="demo_001",
+        name="Acme Tech Solutions",
+        category="Software Development",
+        address="100 Innovation Drive, San Francisco, CA 94105, USA",
+        city="San Francisco",
+        state="CA",
+        country="US",
+        postal_code="94105",
+        latitude=37.7749,
+        longitude=-122.4194,
+        phone="+1-415-555-0101",
+        email="hello@acmetech.example",
+        website="https://acmetech.example",
+        linkedin_url="https://linkedin.com/company/acmetech-example",
+        rating=4.5,
+        review_count=128,
+        employee_count_estimate="50–200",
+        source="demo",
+    ),
+    Business(
+        id="demo_002",
+        name="BrightSpark Digital",
+        category="Digital Marketing",
+        address="200 Market Street, New York, NY 10001, USA",
+        city="New York",
+        state="NY",
+        country="US",
+        postal_code="10001",
+        latitude=40.7128,
+        longitude=-74.0060,
+        phone="+1-212-555-0202",
+        email="info@brightsparkdigital.example",
+        website="https://brightsparkdigital.example",
+        twitter_url="https://twitter.com/brightsparkdigital",
+        rating=4.2,
+        review_count=89,
+        employee_count_estimate="10–50",
+        source="demo",
+    ),
+    Business(
+        id="demo_003",
+        name="GreenLeaf Consulting",
+        category="Management Consulting",
+        address="300 Michigan Avenue, Chicago, IL 60601, USA",
+        city="Chicago",
+        state="IL",
+        country="US",
+        postal_code="60601",
+        latitude=41.8827,
+        longitude=-87.6233,
+        phone="+1-312-555-0303",
+        email="contact@greenleafconsulting.example",
+        website="https://greenleafconsulting.example",
+        linkedin_url="https://linkedin.com/company/greenleaf-consulting-example",
+        facebook_url="https://facebook.com/greenleafconsulting.example",
+        rating=4.8,
+        review_count=54,
+        employee_count_estimate="10–50",
+        source="demo",
+    ),
+    Business(
+        id="demo_004",
+        name="Nexus Cloud Systems",
+        category="Cloud Computing",
+        address="400 Congress Avenue, Austin, TX 78701, USA",
+        city="Austin",
+        state="TX",
+        country="US",
+        postal_code="78701",
+        latitude=30.2672,
+        longitude=-97.7431,
+        phone="+1-512-555-0404",
+        website="https://nexuscloud.example",
+        rating=4.0,
+        review_count=210,
+        employee_count_estimate="200–500",
+        source="demo",
+    ),
+    Business(
+        id="demo_005",
+        name="Pinnacle HR Partners",
+        category="Human Resources",
+        address="500 Peachtree Street NE, Atlanta, GA 30308, USA",
+        city="Atlanta",
+        state="GA",
+        country="US",
+        postal_code="30308",
+        latitude=33.7490,
+        longitude=-84.3880,
+        phone="+1-404-555-0505",
+        email="team@pinnacleHR.example",
+        website="https://pinnacleHR.example",
+        rating=3.9,
+        review_count=37,
+        employee_count_estimate="10–50",
+        source="demo",
+    ),
+    # Pune Central Businesses (Core Urban Area: Shivajinagar, FC Road, Deccan, Koregaon Park, Kothrud)
+    Business(
+        id="demo_pune_001",
+        name="Vaishali Restaurant",
+        category="Food & Beverage",
+        address="FC Road, Shivajinagar, Pune, Maharashtra 411004, India",
+        city="Pune",
+        state="MH",
+        country="IN",
+        postal_code="411004",
+        latitude=18.5246,
+        longitude=73.8415,
+        phone="+91-20-25531244",
+        website=None,
+        rating=4.6,
+        review_count=12500,
+        employee_count_estimate="50–100",
+        source="demo",
+    ),
+    Business(
+        id="demo_pune_002",
+        name="Cafe Goodluck",
+        category="Food & Beverage",
+        address="Deccan Gymkhana, Pune, Maharashtra 411004, India",
+        city="Pune",
+        state="MH",
+        country="IN",
+        postal_code="411004",
+        latitude=18.5168,
+        longitude=73.8415,
+        phone="+91-20-25676893",
+        website=None,
+        rating=4.4,
+        review_count=8900,
+        employee_count_estimate="20–50",
+        source="demo",
+    ),
+    Business(
+        id="demo_pune_003",
+        name="German Bakery",
+        category="Food & Beverage",
+        address="North Main Road, Koregaon Park, Pune, Maharashtra 411001, India",
+        city="Pune",
+        state="MH",
+        country="IN",
+        postal_code="411001",
+        latitude=18.5362,
+        longitude=73.8940,
+        phone="+91-20-26156543",
+        website="https://germanbakerypune.example",
+        rating=4.3,
+        review_count=4200,
+        employee_count_estimate="20–50",
+        source="demo",
+    ),
+    Business(
+        id="demo_pune_004",
+        name="Kothrud Software Labs",
+        category="Technology",
+        address="Paud Road, Kothrud, Pune, Maharashtra 411038, India",
+        city="Pune",
+        state="MH",
+        country="IN",
+        postal_code="411038",
+        latitude=18.5074,
+        longitude=73.8077,
+        website="https://kothrudsoftware.example",
+        rating=4.5,
+        review_count=180,
+        employee_count_estimate="10–50",
+        source="demo",
+    ),
+    # Pune Outlying / Distant Municipalities (Outside Central Core > 6km)
+    Business(
+        id="demo_pune_dist_001",
+        name="Alandi Pilgrim Refreshments",
+        category="Food & Beverage",
+        address="Temple Road, Alandi, Pune District, Maharashtra 412105, India",
+        city="Alandi",
+        state="MH",
+        country="IN",
+        postal_code="412105",
+        latitude=18.6775,
+        longitude=73.8967,
+        website=None,
+        rating=4.0,
+        review_count=310,
+        employee_count_estimate="5–20",
+        source="demo",
+    ),
+    Business(
+        id="demo_pune_dist_002",
+        name="Pimpri Auto Spare Parts",
+        category="Automotive",
+        address="Old Mumbai-Pune Highway, Pimpri, Maharashtra 411018, India",
+        city="Pimpri-Chinchwad",
+        state="MH",
+        country="IN",
+        postal_code="411018",
+        latitude=18.6279,
+        longitude=73.8009,
+        website="https://pimpriauto.example",
+        rating=4.1,
+        review_count=520,
+        employee_count_estimate="10–50",
+        source="demo",
+    ),
+]
+
+
+def search_demo_businesses(
+    query: str,
+    location: str | None = None,
+    category: str | None = None,
+    limit: int | None = None,
+    latitude: float | None = None,
+    longitude: float | None = None,
+    radius_meters: int | None = None,
+    wider_metro: bool = False,
+    **kwargs: Any,
+) -> list[Business]:
+    """Filter demo businesses by query / location / category and enforce geographic distance."""
+    from ..providers.overpass_provider import haversine_distance_meters
+
+    q = (query or "").lower().strip()
+    results = []
+
+    # Center coordinates resolution
+    center_lat: float | None = None
+    center_lon: float | None = None
+    if latitude is not None and longitude is not None:
+        center_lat, center_lon = float(latitude), float(longitude)
+    elif location:
+        loc_lower = location.lower().strip()
+        if "pune" in loc_lower:
+            center_lat, center_lon = 18.5204, 73.8567
+        elif "san francisco" in loc_lower or "sf" in loc_lower:
+            center_lat, center_lon = 37.7749, -122.4194
+        elif "new york" in loc_lower or "nyc" in loc_lower:
+            center_lat, center_lon = 40.7128, -74.0060
+
+    eff_radius = (
+        (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)
+    )
+
+    for biz in DEMO_BUSINESSES:
+        name_match = not q or q == "*" or q in biz.name.lower()
+        cat_match = not q or (biz.category and q in biz.category.lower())
+
+        # Location filtering
+        loc_match = True
+        if location and biz.city:
+            loc_l = location.lower()
+            # If searching for "pune", exclude separate municipalities like Alandi or Pimpri unless wider_metro
+            if "pune" in loc_l and not wider_metro:
+                loc_match = biz.city.lower() == "pune"
+            else:
+                loc_match = loc_l in biz.city.lower() or loc_l in (biz.address or "").lower()
+
+        filter_cat = (
+            not category
+            or (biz.category and category.lower() in biz.category.lower())
+        )
+        filter_loc = not location or loc_match
+
+        if (name_match or cat_match) and filter_cat and filter_loc:
+            # Clone model for annotation
+            b_copy = biz.model_copy()
+            if center_lat is not None and center_lon is not None and b_copy.latitude and b_copy.longitude:
+                dist_m = haversine_distance_meters(center_lat, center_lon, b_copy.latitude, b_copy.longitude)
+                b_copy.distance_meters = round(dist_m, 1)
+                b_copy.distance_km = round(dist_m / 1000.0, 2)
+                if not wider_metro and dist_m > eff_radius:
+                    continue  # Strict radius exclusion
+            results.append(b_copy)
+
+    # If no results matched query text, fallback to location/category matches
+    if not results and (location or category):
+        for biz in DEMO_BUSINESSES:
+            loc_match = not location or (
+                biz.city and location.lower() in biz.city.lower()
+            )
+            cat_match = not category or (
+                biz.category and category.lower() in biz.category.lower()
+            )
+            if loc_match and cat_match:
+                b_copy = biz.model_copy()
+                if center_lat is not None and center_lon is not None and b_copy.latitude and b_copy.longitude:
+                    dist_m = haversine_distance_meters(center_lat, center_lon, b_copy.latitude, b_copy.longitude)
+                    b_copy.distance_meters = round(dist_m, 1)
+                    b_copy.distance_km = round(dist_m / 1000.0, 2)
+                    if not wider_metro and dist_m > eff_radius:
+                        continue
+                results.append(b_copy)
+
+    if limit is not None:
+        return results[:limit]
+    return results
+
+
+def get_demo_business(business_id: str) -> Business | None:
+    """Return a single demo business by id."""
+    for biz in DEMO_BUSINESSES:
+        if biz.id == business_id:
+            return biz
+    return None

leadintel/exporters/__init__.py

@@ -0,0 +1,6 @@
+"""Exporters package — CSV, Excel, and JSON lead export tools."""
+
+from .csv_exporter import export_to_csv
+from .excel_exporter import export_to_excel, sanitize_excel_cell
+
+__all__ = ["export_to_csv", "export_to_excel", "sanitize_excel_cell"]

leadintel/exporters/csv_exporter.py

@@ -0,0 +1,113 @@
+"""CSV export for business lead lists."""
+
+from __future__ import annotations
+
+import csv
+import io
+import os
+from datetime import datetime
+from typing import Any, Optional
+
+from ..models.business import Business
+from ..storage.path_validator import validate_safe_export_path
+
+# Columns written to CSV (in order)
+_COLUMNS = [
+    "id",
+    "name",
+    "category",
+    "address",
+    "city",
+    "state",
+    "country",
+    "postal_code",
+    "phone",
+    "email",
+    "website",
+    "website_status",
+    "website_opportunity_score",
+    "detected_cms",
+    "has_contact_route",
+    "distance_km",
+    "linkedin_url",
+    "twitter_url",
+    "facebook_url",
+    "rating",
+    "review_count",
+    "employee_count_estimate",
+    "source",
+    "retrieved_at",
+    "is_ai_generated",
+]
+
+DANGEROUS_PREFIXES = ("=", "+", "-", "@", "\t", "\r")
+
+
+def sanitize_csv_cell(val: Any) -> Any:
+    """
+    Protect against CSV/spreadsheet formula injection.
+    Prefixes values starting with '=', '+', '-', '@', '\\t', '\\r' with a single quote.
+    """
+    if val is None:
+        return ""
+    if isinstance(val, (int, float, bool)):
+        return val
+    raw = str(val)
+    if raw.startswith(("\t", "\r")):
+        return "'" + raw
+    s = raw.strip()
+    if s.startswith(("=", "+", "-", "@")):
+        return "'" + s
+    return s
+
+
+def _business_to_row(biz: Business) -> dict:
+    """Convert a Business model to a flat, sanitized CSV-safe dict."""
+    data = biz.model_dump()
+    # Flatten datetime
+    data["retrieved_at"] = (
+        data["retrieved_at"].isoformat()
+        if isinstance(data["retrieved_at"], datetime)
+        else data["retrieved_at"]
+    )
+    # Drop geo fields (not useful in a spreadsheet view)
+    data.pop("latitude", None)
+    data.pop("longitude", None)
+    return {col: sanitize_csv_cell(data.get(col, "")) for col in _COLUMNS}
+
+
+def export_to_csv(
+    businesses: list[Business],
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Serialise a list of Business objects to CSV.
+
+    Args:
+        businesses: List of Business instances to export.
+        output_path: If provided, safely validate and write to this file path and return the path.
+                     If None, return the CSV content as a string.
+
+    Returns:
+        Absolute file path (when output_path is given) or raw CSV string.
+
+    Raises:
+        SecurityValidationError: If output_path violates path safety rules.
+        OSError: If writing to output_path fails.
+    """
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=_COLUMNS, extrasaction="ignore")
+    writer.writeheader()
+    for biz in businesses:
+        writer.writerow(_business_to_row(biz))
+
+    csv_content = buf.getvalue()
+
+    if output_path:
+        safe_path = validate_safe_export_path(output_path, allowed_extensions={"csv"})
+        os.makedirs(os.path.dirname(safe_path) or ".", exist_ok=True)
+        with open(safe_path, "w", newline="", encoding="utf-8") as f:
+            f.write(csv_content)
+        return safe_path
+
+    return csv_content