leadintel 0.3.0__py3-none-any.whl

leadintel/tools/find_business_website.py

@@ -0,0 +1,66 @@
+"""
+MCP Tool: find_business_website
+
+Discovers and validates the official website of a business entity.
+Uses OpenStreetMap data first, followed by free web search lookup and validation.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from .website_finder import find_website_for_business
+
+
+def register(mcp: MCPServer) -> None:
+    """Register find_business_website tool on the MCP server."""
+
+    @mcp.tool()
+    async def find_business_website(
+        business_name: str,
+        location: Optional[str] = None,
+        business_id: Optional[str] = None,
+    ) -> dict:
+        """
+        Find and verify the official website of a business.
+
+        Searches local knowledge providers and free web search (no paid API key required).
+        Filters out directories, social media links, and aggregators to isolate the primary domain.
+
+        Args:
+            business_name: Name of the business (e.g. 'Blue Bottle Coffee', 'Acme Corp').
+            location: Optional location context (e.g. 'San Francisco', 'London').
+            business_id: Optional unique LeadIntel/OSM ID (e.g. 'osm_node_123', 'demo_001').
+
+        Returns:
+            Dict containing:
+              - found (bool): True if an official website was identified
+              - business_name (str): Input business name
+              - location (str|null): Input location
+              - website (str|null): Discovered website URL
+              - discovery_method (str): Method used ('provider:openstreetmap', 'duckduckgo_lite', etc.)
+              - note (str|null): Informative status note
+        """
+        website_url, method = await find_website_for_business(
+            business_name=business_name,
+            location=location,
+            business_id=business_id,
+        )
+
+        found = bool(website_url)
+
+        return {
+            "found": found,
+            "business_name": business_name,
+            "location": location,
+            "business_id": business_id,
+            "website": website_url,
+            "discovery_method": method,
+            "note": (
+                f"Discovered website via {method}."
+                if found
+                else "Could not locate a verified official website."
+            ),
+        }

leadintel/tools/find_competitors.py

@@ -0,0 +1,75 @@
+"""
+MCP Tool: find_competitors
+
+Discovers relevant industry competitors using OpenStreetMap and semantic taxonomy matching,
+classifies them as direct vs indirect, and assesses digital footprints.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.competitor_research import find_industry_competitors
+
+
+def register(mcp: MCPServer) -> None:
+    """Register find_competitors tool on the MCP server."""
+
+    @mcp.tool()
+    async def find_competitors(
+        business_name: str,
+        business_category: Optional[str] = None,
+        city: Optional[str] = None,
+        state: Optional[str] = None,
+        country: Optional[str] = None,
+        website: Optional[str] = None,
+        max_competitors: int = 5,
+        enrich_websites: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Discover and analyze competitors of a target business.
+
+        Finds industry rivals using OpenStreetMap and semantic taxonomy rules.
+        Distinguishes direct competitors (exact specialization overlap) from
+        indirect competitors (broader category overlap), explaining confidence levels.
+
+        Features:
+        - Filters out unrelated businesses (does not mistake mere geographical proximity for competition).
+        - Identifies competitor websites, contact info, ratings, and reviews.
+        - Analyzes digital presence (website status, mobile readiness, social media footprint).
+        - Zero paid API keys required; respects OpenStreetMap ODbL attribution.
+
+        Args:
+            business_name: Name of the target business (e.g. 'Acme Tech Solutions', 'Blue Bottle Coffee').
+            business_category: Industry/category of the business (e.g. 'Software Development', 'Cafe').
+            city: Optional city (e.g. 'San Francisco', 'London').
+            state: Optional state/province (e.g. 'CA', 'TX').
+            country: Optional country (e.g. 'US', 'UK').
+            website: Optional target company website URL.
+            max_competitors: Maximum competitors to return (1-20, default 5).
+            enrich_websites: If True, tests competitor websites for availability and digital channels.
+
+        Returns:
+            Structured competitor research report.
+        """
+        limit = max(1, min(int(max_competitors), 20))
+        try:
+            return await find_industry_competitors(
+                business_name=business_name,
+                business_category=business_category,
+                city=city,
+                state=state,
+                country=country,
+                website=website,
+                max_competitors=limit,
+                enrich_websites=enrich_websites,
+            )
+        except Exception as exc:
+            return {
+                "error": str(exc),
+                "target_business": {"name": business_name, "category": business_category},
+                "total_competitors_found": 0,
+                "competitors": [],
+            }

leadintel/tools/find_social_profiles.py

@@ -0,0 +1,85 @@
+"""
+MCP Tool: find_social_profiles
+
+Scans a company's website to extract and verify official social media profiles.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+from ..services.robots_checker import RobotsChecker
+from ..services.social_finder import extract_social_profiles
+from ..services.url_validator import validate_and_normalize_url
+
+USER_AGENT = "LeadIntel/0.1 (Business Intelligence Researcher; +https://github.com/example/leadintel; respectful crawler)"
+
+
+def register(mcp: MCPServer) -> None:
+    """Register find_social_profiles tool on the MCP server."""
+
+    @mcp.tool()
+    async def find_social_profiles(
+        url: str,
+    ) -> dict[str, Any]:
+        """
+        Extract verified official social media profiles from a business website.
+
+        Discovers:
+        - LinkedIn (company / personal)
+        - Facebook
+        - Instagram
+        - Twitter / X
+        - YouTube
+        - Pinterest
+
+        Filters out share/dialog widgets, intent links, and irrelevant external domains.
+
+        Security & Privacy:
+        - Prevents SSRF attacks.
+        - Respects robots.txt rules.
+        - Only extracts publicly linked B2B / official brand profiles.
+
+        Args:
+            url: The business website URL (e.g. 'https://acme.example').
+
+        Returns:
+            Dict containing detected profiles by platform and total count.
+        """
+        try:
+            norm_url = validate_and_normalize_url(url)
+            robots = RobotsChecker()
+            can_fetch, reason = await robots.can_fetch(norm_url)
+            if not can_fetch:
+                return {
+                    "url": norm_url,
+                    "status": "blocked_by_robots",
+                    "error": reason or "Blocked by website robots.txt policy.",
+                    "profiles": {},
+                    "total_profiles_found": 0,
+                }
+
+            async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+                resp = await client.get(norm_url, headers={"User-Agent": USER_AGENT})
+                resp.raise_for_status()
+
+            profiles = extract_social_profiles(resp.text, base_url=str(resp.url))
+            total_found = sum(len(items) for items in profiles.values())
+
+            return {
+                "url": str(resp.url),
+                "status": "success",
+                "profiles": profiles,
+                "total_profiles_found": total_found,
+            }
+        except Exception as exc:
+            return {
+                "url": url,
+                "status": "error",
+                "error": str(exc),
+                "profiles": {},
+                "total_profiles_found": 0,
+            }

leadintel/tools/generate_business_insights.py

@@ -0,0 +1,93 @@
+"""
+MCP Tool: generate_business_insights
+
+Generates strategic AI business intelligence and opportunity explanations
+using a local Ollama model without external cloud API dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.ai_business_insights import generate_ai_business_insights
+from ..services.local_ai import LocalAIClient, OllamaError, OllamaUnavailableError
+
+
+def register(mcp: MCPServer) -> None:
+    """Register generate_business_insights tool on the MCP server."""
+
+    @mcp.tool()
+    async def generate_business_insights(
+        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,
+        lead_score_data: Optional[dict[str, Any]] = None,
+        contact_info: Optional[dict[str, Any]] = None,
+        model: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Generate evidence-based strategic business insights using local Ollama AI.
+
+        Synthesizes technical audits, competitor benchmarks, and lead scores to provide:
+        - Executive summary of digital maturity
+        - Clear explanations for digital marketing and SEO opportunities
+        - Strategic interpretation of the deterministic lead score
+        - Grounded competitor insights
+        - Actionable service recommendations (Web Dev, SEO, Social, Marketing)
+
+        Ethical & Operational Safeguards:
+        - Connects to local Ollama (http://localhost:11434). Zero cloud AI calls or tokens used.
+        - Grounded strictly in provided evidence; never invents revenue, budgets, or purchasing intent.
+        - If Ollama is not installed or running, returns a clean informative error without crashing.
+
+        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).
+            lead_score_data: Results from score_lead tool (optional).
+            contact_info: Available contact details (optional).
+            model: Optional Ollama model override (default: configured OLLAMA_MODEL, e.g. 'llama3').
+
+        Returns:
+            Structured AI insights grounded in verified facts.
+        """
+        client = LocalAIClient(model=model) if model else None
+        try:
+            return await generate_ai_business_insights(
+                business_name=business_name,
+                business_category=business_category,
+                website_analysis=website_analysis,
+                seo_audit=seo_audit,
+                social_profiles=social_profiles,
+                competitor_comparison=competitor_comparison,
+                lead_score_data=lead_score_data,
+                contact_info=contact_info,
+                ai_client=client,
+            )
+        except OllamaUnavailableError as e:
+            return {
+                "error": "Ollama server is unavailable.",
+                "message": str(e),
+                "business_name": business_name,
+                "suggestion": "Ensure Ollama is installed and running locally with 'ollama serve'.",
+            }
+        except OllamaError as e:
+            return {
+                "error": "Ollama generation failed.",
+                "message": str(e),
+                "business_name": business_name,
+            }
+        except Exception as exc:
+            return {
+                "error": "Failed to generate business insights.",
+                "message": str(exc),
+                "business_name": business_name,
+            }

leadintel/tools/generate_business_report.py

@@ -0,0 +1,92 @@
+"""
+MCP Tool: generate_business_report
+
+Synthesizes complete business intelligence into comprehensive multi-section reports
+available in Markdown, HTML, or structured JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.business_report import generate_comprehensive_business_report
+
+
+def register(mcp: MCPServer) -> None:
+    """Register generate_business_report tool on the MCP server."""
+
+    @mcp.tool()
+    async def generate_business_report(
+        business_info: dict[str, Any],
+        website_analysis: Optional[dict[str, Any]] = None,
+        seo_audit: Optional[dict[str, Any]] = None,
+        social_profiles: Optional[dict[str, Any]] = None,
+        competitor_research: Optional[dict[str, Any]] = None,
+        lead_score_data: Optional[dict[str, Any]] = None,
+        ai_insights: Optional[dict[str, Any]] = None,
+        output_format: Literal["markdown", "html", "json"] = "markdown",
+    ) -> dict[str, Any]:
+        """
+        Generate a comprehensive 12-section business intelligence report.
+
+        Synthesizes technical audits, SEO evaluations, social presence scans,
+        competitor benchmarks, lead scores, and optional AI strategic insights.
+
+        Report Sections:
+        1. Executive Summary
+        2. Business Overview
+        3. Digital Presence Assessment
+        4. Website Technical Audit
+        5. SEO Analysis
+        6. Social Media Analysis
+        7. Competitor Benchmarking
+        8. Lead Qualification & Scoring
+        9. Identified Digital Opportunities
+        10. Recommended Service Packages
+        11. Suggested Multi-Channel Outreach
+        12. Data Sources, Attributions & Limitations
+
+        Features:
+        - Works completely offline without AI or external paid APIs.
+        - Outputs in Markdown, HTML, or structured JSON.
+        - Accurately references OpenStreetMap ODbL attributions.
+
+        Args:
+            business_info: Dict containing at least 'name', plus optional 'category', 'city', 'website'.
+            website_analysis: Output from analyze_website tool (optional).
+            seo_audit: Output from check_seo tool (optional).
+            social_profiles: Output from find_social_profiles tool (optional).
+            competitor_research: Output from find_competitors tool (optional).
+            lead_score_data: Output from score_lead tool (optional).
+            ai_insights: Output from generate_business_insights or generate_outreach tool (optional).
+            output_format: 'markdown' (default), 'html', or 'json'.
+
+        Returns:
+            Dict containing the rendered report content, format, and metadata.
+        """
+        try:
+            report_result = generate_comprehensive_business_report(
+                business_info=business_info,
+                website_analysis=website_analysis,
+                seo_audit=seo_audit,
+                social_profiles=social_profiles,
+                competitor_research=competitor_research,
+                lead_score_data=lead_score_data,
+                ai_insights=ai_insights,
+                output_format=output_format,
+            )
+
+            return {
+                "business_name": business_info.get("name"),
+                "format": output_format.lower(),
+                "report": report_result,
+            }
+        except Exception as exc:
+            return {
+                "error": str(exc),
+                "business_name": business_info.get("name") if isinstance(business_info, dict) else str(business_info),
+                "format": output_format.lower(),
+                "report": f"Report generation failed: {exc}",
+            }

leadintel/tools/generate_outreach.py

@@ -0,0 +1,153 @@
+"""
+MCP Tool: generate_outreach
+
+Synthesizes tailored, respectful B2B outreach messaging (Email, LinkedIn, WhatsApp)
+using local Ollama models grounded in verified technical findings and website opportunities.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..models.business import Business
+from ..services.ai_business_insights import generate_ai_outreach
+from ..services.local_ai import LocalAIClient, OllamaError, OllamaUnavailableError
+from ..storage.db import get_business
+
+logger = logging.getLogger(__name__)
+
+
+def register(mcp: MCPServer) -> None:
+    """Register generate_outreach tool on the MCP server."""
+
+    @mcp.tool()
+    async def generate_outreach(
+        business_name: str,
+        business_id: Optional[str] = None,
+        business: Optional[dict[str, Any]] = None,
+        business_category: Optional[str] = None,
+        website_status: Optional[str] = None,
+        website_opportunity_score: Optional[float] = None,
+        website_opportunity_explanation: Optional[str] = None,
+        detected_cms: Optional[str] = None,
+        has_contact_route: Optional[bool] = 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,
+        lead_score_data: Optional[dict[str, Any]] = None,
+        contact_info: Optional[dict[str, Any]] = None,
+        agency_name: str = "Our Agency",
+        sender_name: str = "Lead Specialist",
+        model: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Generate personalized, multi-channel B2B outreach messages using local Ollama AI.
+
+        Produces ready-to-use drafts across 3 channels:
+        - Email pitch: Structured subject line + 3-paragraph value-first pitch referencing verified findings.
+        - LinkedIn message: Concise connection request (< 300 characters).
+        - WhatsApp Business: Respectful, direct conversational pitch (< 120 words).
+
+        Ethical & Operational Safeguards:
+        - Uses local Ollama model (no third-party cloud data transfer).
+        - Grounded exclusively in verified technical data.
+        - Does not invent fake claims, guarantees, or assume prospect budgets.
+        - Strict guardrails: "Do not fabricate business data or website problems. Base the outreach strictly on the provided website_opportunity_explanation. If the site is missing (website_not_found_after_research), pitch a new build. If a CMS is detected or a contact route is missing, mention it as a specific reason for outreach."
+
+        Args:
+            business_name: Target company name (required).
+            business_id: Optional business ID to automatically retrieve stored business from SQLite.
+            business: Optional dictionary representation of a Business instance.
+            business_category: Business industry/category.
+            website_status: Status of the business website (e.g. 'website_not_found_after_research').
+            website_opportunity_score: Deterministic 0–100 score prioritizing website opportunity.
+            website_opportunity_explanation: Evidence-based explanation of the website opportunity.
+            detected_cms: Detected CMS (WordPress, Shopify, Wix, Squarespace).
+            has_contact_route: Boolean indicating presence of contact form/mailto route.
+            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).
+            lead_score_data: Results from score_lead tool (optional).
+            contact_info: Contact details dictionary (optional).
+            agency_name: Your digital agency or company name.
+            sender_name: Name of the person/role sending the message.
+            model: Optional Ollama model override.
+
+        Returns:
+            Dict containing multi-channel outreach drafts.
+        """
+        # Retrieve or reconstruct Business object if available
+        biz_obj: Optional[Business] = None
+        if business_id:
+            biz_obj = get_business(business_id)
+        elif business:
+            try:
+                biz_obj = Business.model_validate(business)
+            except Exception:
+                pass
+        if not biz_obj and business_name:
+            biz_obj = get_business(business_name)
+
+        if biz_obj:
+            if not business_category and biz_obj.category:
+                business_category = biz_obj.category
+            website_status = website_status or biz_obj.website_status
+            if website_opportunity_score is None:
+                website_opportunity_score = biz_obj.website_opportunity_score
+            website_opportunity_explanation = (
+                website_opportunity_explanation or biz_obj.website_opportunity_explanation
+            )
+            detected_cms = detected_cms or biz_obj.detected_cms
+            if has_contact_route is None:
+                has_contact_route = biz_obj.has_contact_route
+            if not contact_info:
+                contact_info = {
+                    "city": biz_obj.city,
+                    "phone": biz_obj.phone,
+                    "email": biz_obj.email,
+                }
+
+        client = LocalAIClient(model=model) if model else None
+        try:
+            return await generate_ai_outreach(
+                business_name=business_name,
+                business_category=business_category,
+                website_status=website_status,
+                website_opportunity_score=website_opportunity_score,
+                website_opportunity_explanation=website_opportunity_explanation,
+                detected_cms=detected_cms,
+                has_contact_route=has_contact_route,
+                website_analysis=website_analysis,
+                seo_audit=seo_audit,
+                social_profiles=social_profiles,
+                competitor_comparison=competitor_comparison,
+                lead_score_data=lead_score_data,
+                contact_info=contact_info,
+                agency_name=agency_name,
+                sender_name=sender_name,
+                ai_client=client,
+            )
+        except OllamaUnavailableError as e:
+            return {
+                "error": "Ollama server is unavailable.",
+                "message": str(e),
+                "business_name": business_name,
+                "suggestion": "Ensure Ollama is installed and running locally with 'ollama serve'.",
+            }
+        except OllamaError as e:
+            return {
+                "error": "Ollama outreach generation failed.",
+                "message": str(e),
+                "business_name": business_name,
+            }
+        except Exception as exc:
+            return {
+                "error": "Failed to generate outreach drafts.",
+                "message": str(exc),
+                "business_name": business_name,
+            }

leadintel/tools/get_business_details.py

@@ -0,0 +1,96 @@
+"""
+MCP Tool: get_business_details
+
+Fetches complete and enriched information for a single business entity,
+using OpenStreetMap / Overpass data, local demo fallback, and website resolution.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from ..config import settings
+from ..models.business import Business
+from ..providers import build_registry
+from .website_finder import find_website_for_business
+
+OSM_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0 — https://www.openstreetmap.org/copyright"
+
+_registry = build_registry(settings)
+
+
+def register(mcp: MCPServer) -> None:
+    """Register get_business_details tool on the MCP server."""
+
+    @mcp.tool()
+    async def get_business_details(
+        business_id: str,
+        auto_enrich_website: bool = True,
+    ) -> dict:
+        """
+        Retrieve enriched details for a specific business by ID.
+
+        Looks up the entity across all available providers (OpenStreetMap, demo fixtures).
+        If the business is missing a website and `auto_enrich_website` is True,
+        attempts to discover its official website.
+
+        Args:
+            business_id: Unique identifier (e.g. 'osm_node_12345', 'osm_way_67890', or 'demo_001').
+            auto_enrich_website: If True, search for missing official website if not present in OSM tags.
+
+        Returns:
+            Dict containing:
+              - found (bool): Whether the business was resolved
+              - business (dict|null): Enriched business record
+              - provider (str): Source of the data
+              - attribution (str|null): Mandatory attribution notice if source is OSM
+              - enriched_fields (list[str]): Fields added or updated via enrichment
+
+        Compliance:
+            - Respects OSM ODbL attribution.
+            - Does not scrape private personal information.
+        """
+        enriched_fields: list[str] = []
+
+        biz, provider_name = await _registry.get_details(business_id)
+
+        if not biz:
+            return {
+                "found": False,
+                "business_id": business_id,
+                "business": None,
+                "provider": provider_name,
+                "attribution": None,
+                "enriched_fields": [],
+                "note": f"Business ID '{business_id}' not found.",
+            }
+
+        # Auto-enrich website if absent
+        if auto_enrich_website and not biz.website and biz.name:
+            discovered_url, _ = await find_website_for_business(
+                business_name=biz.name,
+                location=biz.city,
+                business_id=biz.id,
+            )
+            if discovered_url:
+                # Update website field
+                biz_dict = biz.model_dump()
+                biz_dict["website"] = discovered_url
+                biz = Business(**biz_dict)
+                enriched_fields.append("website")
+
+        is_osm = provider_name == "openstreetmap" or biz.source == "openstreetmap"
+        attribution = OSM_ATTRIBUTION if is_osm else None
+
+        return {
+            "found": True,
+            "business_id": business_id,
+            "business": biz.model_dump(mode="json"),
+            "provider": provider_name,
+            "attribution": attribution,
+            "enriched_fields": enriched_fields,
+            "note": (
+                "Enriched via LeadIntel free intelligence. "
+                + (f"Attribution: {OSM_ATTRIBUTION}" if is_osm else "")
+            ).strip(),
+        }