leadintel 0.3.0__py3-none-any.whl

leadintel/tools/get_saved_leads.py

@@ -0,0 +1,58 @@
+"""
+MCP Tool: get_saved_leads
+
+Retrieves previously researched and stored business leads from the local SQLite database.
+Supports filtering by minimum website opportunity score and configurable record limits.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..storage.db import get_all_businesses
+
+logger = logging.getLogger(__name__)
+
+
+def register(mcp: MCPServer) -> None:
+    """Register get_saved_leads tool on the MCP server."""
+
+    @mcp.tool()
+    async def get_saved_leads(
+        min_opportunity_score: Optional[float] = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """
+        Retrieve previously researched businesses saved in the local LeadIntel SQLite database.
+
+        Allows filtering leads by minimum website opportunity score, making it easy
+        to fetch high-priority web development or digital agency prospects.
+
+        Args:
+            min_opportunity_score: Optional minimum website opportunity score (0–100) to filter by.
+            limit: Maximum number of businesses to return (default: 50, max: 200).
+
+        Returns:
+            Dict containing retrieved leads, count, and applied query filters.
+        """
+        clamped_limit = max(1, min(limit, 200))
+        try:
+            businesses = get_all_businesses(min_score=min_opportunity_score, limit=clamped_limit)
+            return {
+                "total_retrieved": len(businesses),
+                "min_opportunity_score": min_opportunity_score,
+                "limit": clamped_limit,
+                "businesses": [b.model_dump(mode="json") for b in businesses],
+            }
+        except Exception as exc:
+            logger.warning("Failed to retrieve saved leads from database: %s", exc)
+            return {
+                "error": "Failed to retrieve saved leads from local database.",
+                "message": str(exc),
+                "total_retrieved": 0,
+                "businesses": [],
+            }
+

leadintel/tools/score_lead.py

@@ -0,0 +1,88 @@
+"""
+MCP Tool: score_lead
+
+Evaluates and qualifies a business lead for digital service providers
+using deterministic, multi-dimensional evidence scoring.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.lead_scoring import score_business_lead
+
+
+def register(mcp: MCPServer) -> None:
+    """Register score_lead tool on the MCP server."""
+
+    @mcp.tool()
+    async def score_lead(
+        business_name: str,
+        business_category: Optional[str] = None,
+        website_analysis: Optional[dict[str, Any]] = None,
+        seo_audit: Optional[dict[str, Any]] = None,
+        social_profiles: Optional[dict[str, Any]] = None,
+        competitor_comparison: Optional[dict[str, Any]] = None,
+        contact_info: Optional[dict[str, Any]] = None,
+        weights: Optional[dict[str, float]] = None,
+    ) -> dict[str, Any]:
+        """
+        Evaluate and score a business lead for digital services suitability.
+
+        Calculates a deterministic 0-100 overall prospect score based on:
+        1. Website quality (max 20 pts)
+        2. Technical SEO (max 20 pts)
+        3. Social media presence (max 15 pts)
+        4. Contact accessibility (max 10 pts)
+        5. Mobile readiness (max 10 pts)
+        6. Digital presence gaps vs competitors (max 15 pts)
+        7. Business relevance & localization (max 10 pts)
+
+        Opportunity Analysis:
+        Provides specialized opportunity scores (0-100) for:
+        - Website Development
+        - SEO Services
+        - Social Media Management
+        - Digital Marketing
+
+        Compliance & Ethics:
+        - Missing inputs reduce confidence and evidence completeness, avoiding arbitrary score penalties.
+        - Verified defects are separated from missing information.
+        - Does not speculate on customer purchasing budget or guarantee conversion.
+        - Uses zero paid APIs or tokens.
+
+        Args:
+            business_name: Name of the business (required).
+            business_category: Industry/category description.
+            website_analysis: Results from analyze_website tool (optional).
+            seo_audit: Results from check_seo tool (optional).
+            social_profiles: Results from find_social_profiles tool (optional).
+            competitor_comparison: Results from compare_businesses tool (optional).
+            contact_info: Available phone, email, or address dictionary (optional).
+            weights: Optional custom weight overrides for the 7 categories.
+
+        Returns:
+            Structured lead evaluation report including overall score, priority tier,
+            service opportunities, and recommended package.
+        """
+        try:
+            return score_business_lead(
+                business_name=business_name,
+                business_category=business_category,
+                website_analysis=website_analysis,
+                seo_audit=seo_audit,
+                social_profiles=social_profiles,
+                competitor_comparison=competitor_comparison,
+                contact_info=contact_info,
+                weights=weights,
+            )
+        except Exception as exc:
+            return {
+                "error": str(exc),
+                "business_name": business_name,
+                "overall_lead_score": 0.0,
+                "priority_classification": "Low Priority",
+                "explanation": f"Lead scoring failed: {exc}",
+            }

leadintel/tools/search_businesses.py

@@ -0,0 +1,305 @@
+"""MCP tool: search_businesses — powered by the provider registry and website opportunity engine."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..config import settings
+from ..models.business import Business, BusinessSearchResult
+from ..providers import build_registry
+from ..services.website_opportunity import batch_evaluate_websites
+
+logger = logging.getLogger(__name__)
+
+OSM_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0 — https://www.openstreetmap.org/copyright"
+
+_registry = build_registry(settings)
+
+
+def _compute_data_confidence(b: Business) -> float:
+    """Calculate an evidence-based confidence indicator (0.0 to 1.0) for a business record."""
+    points = 0.0
+    # Location certainty
+    if b.latitude is not None and b.longitude is not None:
+        points += 0.25
+    elif b.address:
+        points += 0.15
+
+    # Category classification
+    if b.category:
+        points += 0.20
+
+    # Contact accessibility
+    if b.phone:
+        points += 0.15
+    if b.email:
+        points += 0.10
+
+    # Website verification completeness
+    if b.website_status in ("website_verified", "website_not_found_after_research", "website_broken"):
+        points += 0.20
+    elif b.website_status == "website_unverified":
+        points += 0.10
+
+    # OpenStreetMap provenance
+    if b.osm_tags:
+        points += 0.10
+
+    return round(min(1.0, max(0.2, points)), 2)
+
+
+def _apply_ranking(
+    businesses: list[Business],
+    sort_by: str,
+) -> list[Business]:
+    """Sort businesses by selected criterion and generate ranking_explanation for each."""
+    sort_strategy = (sort_by or "highest_website_opportunity").lower().strip()
+
+    if sort_strategy == "closest":
+        businesses.sort(
+            key=lambda b: (
+                b.distance_meters if b.distance_meters is not None else 999_999_999,
+                -(b.website_opportunity_score or 0.0),
+            )
+        )
+    elif sort_strategy == "highest_lead_score":
+        # Score based on commercial visibility and review count
+        businesses.sort(
+            key=lambda b: (
+                -(b.review_count or 0),
+                -(b.rating or 0.0),
+                b.distance_meters if b.distance_meters is not None else 999_999,
+            )
+        )
+    elif sort_strategy == "best_seo_opportunity":
+        businesses.sort(
+            key=lambda b: (
+                -(b.website_opportunity_score or 0.0),
+                b.distance_meters if b.distance_meters is not None else 999_999,
+            )
+        )
+    else:
+        # Default: highest_website_opportunity
+        # Prioritize:
+        # 1. No website found after research (90-100)
+        # 2. Broken websites (75-89)
+        # 3. Weak / outdated websites (50-74)
+        # 4. Significant SEO problems (30-49)
+        # 5. Good websites (5-29)
+        # Tie-breaker: distance to search center
+        businesses.sort(
+            key=lambda b: (
+                -(b.website_opportunity_score if b.website_opportunity_score is not None else -1.0),
+                b.distance_meters if b.distance_meters is not None else 999_999_999,
+                -(b.data_confidence or 0.0),
+            )
+        )
+
+    # Populate ranking_explanation
+    for idx, b in enumerate(businesses, 1):
+        dist_str = f"{b.distance_km} km away" if b.distance_km is not None else "distance uncalculated"
+        opp_score_str = (
+            f"Opportunity score: {b.website_opportunity_score:.1f}/100"
+            if b.website_opportunity_score is not None
+            else "Opportunity unassessed"
+        )
+
+        if b.website_status == "website_not_found_after_research":
+            explanation = (
+                f"Ranked #{idx}: High-priority web development opportunity. "
+                f"No official website found after thorough web research ({opp_score_str}, {dist_str})."
+            )
+        elif b.website_status == "website_broken":
+            explanation = (
+                f"Ranked #{idx}: Broken website detected ({opp_score_str}, {dist_str}). "
+                f"Immediate redesign or technical repair required."
+            )
+        elif b.website_status == "website_unverified":
+            explanation = (
+                f"Ranked #{idx}: Unverified website ({opp_score_str}, {dist_str}). "
+                f"Domain cannot be reliably matched to the business name."
+            )
+        elif b.website_status == "website_verified":
+            if (b.website_opportunity_score or 0) >= 50:
+                explanation = (
+                    f"Ranked #{idx}: Outdated website presence ({opp_score_str}, {dist_str}). "
+                    f"Active site lacks mobile responsiveness or HTTPS encryption."
+                )
+            elif (b.website_opportunity_score or 0) >= 30:
+                explanation = (
+                    f"Ranked #{idx}: Active website with SEO/performance deficiencies ({opp_score_str}, {dist_str})."
+                )
+            else:
+                explanation = (
+                    f"Ranked #{idx}: Established digital presence ({opp_score_str}, {dist_str}). "
+                    f"Fast, secure, and mobile-friendly."
+                )
+        else:
+            explanation = (
+                f"Ranked #{idx}: Website uninspected ({opp_score_str}, {dist_str})."
+            )
+
+        b.ranking_explanation = explanation
+
+    return businesses
+
+
+def register(mcp: MCPServer) -> None:
+    """Register search_businesses tool on the MCP server."""
+
+    @mcp.tool()
+    async def search_businesses(
+        query: str,
+        location: Optional[str] = None,
+        category: Optional[str] = None,
+        limit: int = 10,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+        radius_meters: Optional[int] = None,
+        sort_by: Optional[str] = "highest_website_opportunity",
+        research_websites: bool = True,
+        wider_metro: bool = False,
+    ) -> dict:
+        """
+        Search for local businesses and identify high-value website development opportunities.
+
+        Features:
+        - Geographic precision: strictly limits searches to the requested radius around city/coords.
+        - Distance calculation: provides exact distance from search centre for every business.
+        - Website opportunity intelligence: researches missing websites, verifies domain ownership,
+          detects broken sites, and scores web dev opportunity (0–100 scale).
+        - Multi-criteria ranking: prioritizes businesses without websites by default.
+
+        Args:
+            query:              Free-text search term, e.g. "coffee shop", "restaurants",
+                                "law firm", "software". Pass "*" for a broad sweep.
+            location:           City, neighbourhood, or "lat,lon" coordinates, e.g. "Pune",
+                                "Shivajinagar, Pune", "London", "Austin, TX".
+            category:           Optional industry hint, e.g. "Food & Beverage", "Technology",
+                                "Healthcare". Narrows OSM tag filters.
+            limit:              Maximum results to return (1–50, default 10).
+            latitude:           Optional explicit latitude coordinate to center the search.
+            longitude:          Optional explicit longitude coordinate to center the search.
+            radius_meters:      Configurable search radius in metres (default: 6000m / 6km).
+            sort_by:            Ranking criterion: 'highest_website_opportunity' (default),
+                                'closest', 'highest_lead_score', 'best_seo_opportunity'.
+            research_websites:  If True (default), performs web research on businesses missing
+                                an OSM website to verify if they genuinely lack an official site.
+            wider_metro:        If True, expands search radius to metropolitan boundaries (25km)
+                                instead of strictly limiting to the urban core.
+
+        Returns:
+            dict containing:
+              query, location, category, search_center, radius_meters, sort_by
+              total_found (int)
+              businesses (list[dict]):
+                - name, category, address, phone, email, website
+                - distance_meters, distance_km
+                - website_status ('website_verified', 'website_not_found_after_research',
+                                  'website_unverified', 'website_broken', 'website_not_checked')
+                - website_opportunity_score (0–100)
+                - website_opportunity_explanation
+                - data_confidence (0.0–1.0)
+                - ranking_explanation
+                - osm_tags
+              provider, attribution, retrieved_at, note, error
+        """
+        try:
+            limit = max(1, min(limit, 50))
+
+            raw_businesses, provider_name = await _registry.search(
+                query=query,
+                location=location,
+                category=category,
+                limit=limit,
+                latitude=latitude,
+                longitude=longitude,
+                radius_meters=radius_meters,
+                wider_metro=wider_metro,
+            )
+
+            is_osm = provider_name == "openstreetmap"
+            is_demo = provider_name == "demo"
+
+            # 1. Evaluate website opportunity and verify presence
+            evaluated_businesses = await batch_evaluate_websites(
+                businesses=raw_businesses,
+                location=location,
+                research_missing=research_websites,
+                max_concurrent=5,
+            )
+
+            # 2. Compute data confidence for each record
+            for b in evaluated_businesses:
+                b.data_confidence = _compute_data_confidence(b)
+
+            # 3. Apply multi-criteria ranking and populate explanations
+            ranked_businesses = _apply_ranking(
+                businesses=evaluated_businesses,
+                sort_by=sort_by or "highest_website_opportunity",
+            )
+
+            note: Optional[str] = None
+            error: Optional[str] = None
+
+            if is_demo:
+                note = (
+                    "ℹ️ Demo data returned. "
+                    "Provide a 'location' parameter to enable live OpenStreetMap search "
+                    "(no API key required)."
+                )
+            elif is_osm:
+                if getattr(_registry, "last_error", None):
+                    error = _registry.last_error
+                    note = f"⚠️ OpenStreetMap live search encountered an issue: {_registry.last_error}"
+                elif len(ranked_businesses) == 0:
+                    note = f"No businesses found matching your criteria in OpenStreetMap near '{location}'."
+                else:
+                    note = (
+                        f"✅ Live data from OpenStreetMap with website opportunity intelligence. "
+                        f"Attribution required: {OSM_ATTRIBUTION}"
+                    )
+
+            # Safely save leads to SQLite
+            try:
+                from ..storage.db import save_businesses
+                save_businesses(ranked_businesses)
+            except Exception as db_err:
+                logger.error(f"Failed to save leads to SQLite: {db_err}")
+
+            serialized_businesses = [b.model_dump(mode="json") for b in ranked_businesses]
+
+            result = BusinessSearchResult(
+                query=query,
+                location=location,
+                category=category,
+                search_center=_registry.last_search_center,
+                radius_meters=_registry.last_radius_meters,
+                sort_by=sort_by or "highest_website_opportunity",
+                total_found=len(ranked_businesses),
+                businesses=ranked_businesses,
+                source=provider_name,
+                provider=provider_name,
+                attribution=OSM_ATTRIBUTION if is_osm else None,
+                note=note,
+                error=error,
+            )
+
+            result_dict = result.model_dump(mode="json")
+            result_dict["businesses"] = serialized_businesses
+            return result_dict
+
+        except Exception as e:
+            import traceback
+            logger.error(f"Fatal error in search_businesses: {e}\n{traceback.format_exc()}")
+            return {
+                "query": query,
+                "location": location,
+                "error": f"Internal execution error: {str(e)}",
+                "note": "A fatal error occurred during search execution.",
+                "total_found": 0,
+                "businesses": [],
+            }

leadintel/tools/website_finder.py

@@ -0,0 +1,147 @@
+"""
+Website Finder & Search Utilities.
+
+Provides free, open discovery of a business's official website using:
+1. Provider registry lookup (e.g. OSM tags `website`, `contact:website`, `url`).
+2. DuckDuckGo HTML / Instant Answers (completely free, no API key required).
+3. Fallback demo data resolver.
+
+Compliance:
+- Respects robots policies and rate limiting.
+- Avoids scraping protected personal data.
+- Never sends telemetry or sensitive data to third-party providers.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Optional
+from urllib.parse import parse_qs, quote, unquote, urlparse
+
+import httpx
+
+from ..config import settings
+from ..providers import build_registry
+from ..services.website_opportunity import (
+    DIRECTORY_AND_AGGREGATOR_DOMAINS,
+    SOCIAL_DOMAINS,
+    is_directory_or_social_domain,
+)
+
+logger = logging.getLogger(__name__)
+
+USER_AGENT = "LeadIntel/0.2.0 (Business Intelligence Researcher; open-source; respectful crawler)"
+_registry = build_registry(settings)
+
+# Domains to ignore when seeking a company's direct website
+IGNORED_DOMAINS = DIRECTORY_AND_AGGREGATOR_DOMAINS | SOCIAL_DOMAINS
+
+
+def _clean_url(url: str) -> Optional[str]:
+    """Sanitize and validate extracted URL."""
+    if not url:
+        return None
+    url = url.strip()
+    if not (url.startswith("http://") or url.startswith("https://")):
+        url = "https://" + url
+
+    try:
+        parsed = urlparse(url)
+        domain = parsed.netloc.lower()
+        if not domain or "." not in domain:
+            return None
+        if is_directory_or_social_domain(domain) or domain in IGNORED_DOMAINS:
+            return None
+        return f"{parsed.scheme}://{parsed.netloc}{parsed.path}".rstrip("/")
+    except Exception:
+        return None
+
+
+async def find_website_for_business(
+    business_name: str,
+    location: Optional[str] = None,
+    business_id: Optional[str] = None,
+) -> tuple[Optional[str], str]:
+    """
+    Locate official website for a business name / location or business_id.
+
+    Returns:
+        tuple (website_url, source_method)
+    """
+    # 1. Check if business_id is provided and known to provider registry
+    if business_id:
+        biz, provider_name = await _registry.get_details(business_id)
+        if biz and biz.website:
+            return biz.website, f"provider:{provider_name}"
+
+    # 2. Check demo fixtures if offline/demo
+    demo_biz = None
+    if business_id:
+        from ..data.demo import get_demo_business
+        demo_biz = get_demo_business(business_id)
+    if not demo_biz and business_name:
+        from ..data.demo import search_demo_businesses
+        matches = search_demo_businesses(query=business_name, location=location, limit=1)
+        if matches:
+            demo_biz = matches[0]
+    if demo_biz and demo_biz.website and (settings.demo_mode or not business_name):
+        return demo_biz.website, "demo_fixture"
+
+    # 3. DuckDuckGo HTML Lite free lookup
+    query = f"{business_name} {location or ''}".strip()
+    if not query:
+        return None, "empty_query"
+
+    try:
+        url = await _search_duckduckgo_html(query)
+        if url:
+            return url, "duckduckgo_lite"
+    except Exception as exc:
+        logger.debug("DuckDuckGo lookup failed for %s: %s", query, exc)
+
+    # 4. Fallback to demo fixture if available as last resort
+    if demo_biz and demo_biz.website:
+        return demo_biz.website, "demo_fallback"
+
+    return None, "not_found"
+
+
+async def _search_duckduckgo_html(query: str) -> Optional[str]:
+    """
+    Query DuckDuckGo HTML Lite (no JS, no API key) for first organic non-directory link.
+    """
+    search_url = f"https://html.duckduckgo.com/html/?q={quote(query)}"
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "text/html,application/xhtml+xml",
+        "Accept-Language": "en-US,en;q=0.9",
+    }
+
+    async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
+        resp = await client.get(search_url, headers=headers)
+        if resp.status_code != 200:
+            return None
+
+        # DuckDuckGo HTML links format: <a class="result__url" href="/l/?uddg=URL..."> or similar
+        content = resp.text
+        # Extract hrefs
+        matches = re.findall(r'href=["\'](/l/\?uddg=[^"\']+)["\']', content)
+        for m in matches:
+            parsed = parse_qs(urlparse(m).query)
+            uddg = parsed.get("uddg")
+            if uddg:
+                raw_url = unquote(uddg[0])
+                cleaned = _clean_url(raw_url)
+                if cleaned:
+                    return cleaned
+
+        # Fallback regex for standard a tags
+        links = re.findall(r'class="result__snippet"[^>]*>.*?</a>|<a[^>]+class="result__url"[^>]+href=["\']([^"\']+)["\']', content, re.DOTALL)
+        for link in links:
+            if isinstance(link, str) and link.startswith("http"):
+                cleaned = _clean_url(link)
+                if cleaned:
+                    return cleaned
+
+    return None