leadintel 0.3.0__py3-none-any.whl

leadintel/providers/registry.py

@@ -0,0 +1,151 @@
+"""
+Provider registry — selects and chains providers at runtime.
+
+Priority order (highest → lowest):
+  1. OverpassProvider   (free, OSM-backed, requires network)
+  2. DemoProvider       (always available, synthetic data)
+
+Future providers (OpenStreetMapNominatim, custom) slot in without touching
+any tool code.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..models.business import Business
+from .base import BusinessProvider
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+class ProviderRegistry:
+    """Ordered list of providers with automatic fallback."""
+
+    def __init__(self, providers: list[BusinessProvider]) -> None:
+        if not providers:
+            raise ValueError("ProviderRegistry requires at least one provider.")
+        self._providers = providers
+        self.last_error: str | None = None
+        self.last_search_center: dict[str, float] | None = None
+        self.last_radius_meters: int | None = None
+
+    @property
+    def primary(self) -> BusinessProvider:
+        return self._providers[0]
+
+    @property
+    def all_providers(self) -> list[BusinessProvider]:
+        return list(self._providers)
+
+    def provider_names(self) -> list[str]:
+        return [p.name for p in self._providers]
+
+    async def search(
+        self,
+        query: str,
+        location: str | None = None,
+        category: str | None = None,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> tuple[list[Business], str]:
+        """
+        Try providers in order, return first non-empty result.
+
+        Returns:
+            (businesses, provider_name) — the name of the provider that
+            actually returned data.
+        """
+        self.last_error = None
+        self.last_search_center = None
+        self.last_radius_meters = None
+
+        for provider in self._providers:
+            # If a location or explicit coords were provided for live search, do not fall back to demo data
+            has_explicit_loc = bool(location or kwargs.get("latitude") is not None)
+            if has_explicit_loc and provider.name == "demo" and len(self._providers) > 1:
+                logger.debug(
+                    "Skipping DemoProvider for live search with location '%s'.", location
+                )
+                continue
+
+            try:
+                sig = inspect.signature(provider.search)
+                if any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()):
+                    call_kwargs = kwargs
+                else:
+                    call_kwargs = {k: v for k, v in kwargs.items() if k in sig.parameters}
+
+                results = await provider.search(
+                    query=query,
+                    location=location,
+                    category=category,
+                    limit=limit,
+                    **call_kwargs,
+                )
+
+                if hasattr(provider, "last_search_center"):
+                    self.last_search_center = getattr(provider, "last_search_center", None)
+                if hasattr(provider, "last_radius_meters"):
+                    self.last_radius_meters = getattr(provider, "last_radius_meters", None)
+
+                if results:
+                    logger.debug(
+                        "Provider '%s' returned %d result(s).",
+                        provider.name,
+                        len(results),
+                    )
+                    return results, provider.name
+
+                # If a live provider successfully executed search and found 0 results for a location,
+                # do not fall through to demo data — report 0 live results.
+                if has_explicit_loc and provider.name != "demo":
+                    logger.debug(
+                        "Live provider '%s' returned 0 results for location '%s'.",
+                        provider.name,
+                        location,
+                    )
+                    return [], provider.name
+
+                logger.debug("Provider '%s' returned 0 results, trying next.", provider.name)
+            except Exception as exc:  # noqa: BLE001
+                self.last_error = str(exc)
+                logger.warning("Provider '%s' failed: %s", provider.name, exc)
+                # In live mode with a location, do not swallow the error into demo data
+                if has_explicit_loc and provider.name != "demo":
+                    return [], provider.name
+
+        return [], self._providers[-1].name
+
+    async def get_details(
+        self, business_id: str
+    ) -> tuple[Business | None, str]:
+        """
+        Try providers in order for a single business lookup.
+
+        Returns:
+            (business_or_none, provider_name)
+        """
+        self.last_error = None
+        for provider in self._providers:
+            # Route by ID prefix when known
+            if business_id.startswith("osm_") and provider.name == "demo":
+                continue
+            if business_id.startswith("demo_") and provider.name != "demo":
+                continue
+
+            try:
+                result = await provider.get_details(business_id)
+                if result is not None:
+                    return result, provider.name
+            except Exception as exc:  # noqa: BLE001
+                self.last_error = str(exc)
+                logger.warning(
+                    "Provider '%s' get_details failed: %s", provider.name, exc
+                )
+        return None, self._providers[-1].name

leadintel/server.py

@@ -0,0 +1,61 @@
+"""
+LeadIntel MCP Server
+====================
+Free, open-source MCP server for B2B lead generation and business intelligence.
+
+Data sources:
+  - OpenStreetMap / Overpass API (free, ODbL licence)
+  - Demo data (always available, no network required)
+
+Entry point — run with:
+    uv run python -m leadintel.server
+or for interactive MCP Inspector:
+    uv run mcp dev src/leadintel/server.py
+"""
+
+from __future__ import annotations
+
+import logging
+
+from mcp.server.mcpserver import MCPServer
+
+from .config import settings
+from .storage.db import init_db
+from .tools import register_all
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level=getattr(logging, settings.log_level.upper(), logging.INFO),
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger("leadintel")
+
+# ── Initialize Storage ────────────────────────────────────────────────────────
+try:
+    init_db()
+except Exception as exc:
+    logger.warning("Failed to initialize database during startup: %s", exc)
+
+# ── MCP Server ────────────────────────────────────────────────────────────────
+mcp = MCPServer(
+    name="leadintel",
+    version="0.3.0",
+    instructions=(
+        "LeadIntel is a free, open-source MCP server for B2B lead generation "
+        "and business intelligence. It uses OpenStreetMap (free, no API key "
+        "required) for live business discovery. Use search_businesses to find "
+        "businesses in any city, export_leads to save results, and the "
+        "upcoming tools (analyze_website, score_lead, etc.) for enrichment. "
+        "When source is 'openstreetmap', you MUST display the attribution: "
+        "'Data © OpenStreetMap contributors, ODbL 1.0'."
+    ),
+)
+
+# Register all tools
+register_all(mcp)
+
+logger.info("LeadIntel MCP server initialised. Config: %s", settings.safe_dict())
+
+# ── Entrypoint ────────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    mcp.run()

leadintel/services/__init__.py

@@ -0,0 +1,48 @@
+"""LeadIntel modular service package."""
+
+from .ai_business_insights import generate_ai_business_insights, generate_ai_outreach
+from .business_comparison import compare_target_against_competitors
+from .business_report import generate_comprehensive_business_report
+from .competitor_research import calculate_competitor_relevance, find_industry_competitors
+from .lead_scoring import score_business_lead
+from .local_ai import (
+    LocalAIClient,
+    OllamaError,
+    OllamaModelNotFoundError,
+    OllamaUnavailableError,
+    local_ai_client,
+)
+from .robots_checker import RobotsChecker
+from .seo_auditor import audit_html_seo, run_full_seo_audit
+from .social_finder import extract_social_profiles
+from .url_validator import (
+    SecurityValidationError,
+    create_safe_client,
+    validate_and_normalize_url,
+    validate_redirect_hook,
+)
+from .website_analyzer import analyze_target_website
+
+__all__ = [
+    "SecurityValidationError",
+    "validate_and_normalize_url",
+    "create_safe_client",
+    "validate_redirect_hook",
+    "RobotsChecker",
+    "extract_social_profiles",
+    "audit_html_seo",
+    "run_full_seo_audit",
+    "analyze_target_website",
+    "calculate_competitor_relevance",
+    "find_industry_competitors",
+    "compare_target_against_competitors",
+    "score_business_lead",
+    "LocalAIClient",
+    "OllamaError",
+    "OllamaUnavailableError",
+    "OllamaModelNotFoundError",
+    "local_ai_client",
+    "generate_ai_business_insights",
+    "generate_ai_outreach",
+    "generate_comprehensive_business_report",
+]

leadintel/services/ai_business_insights.py

@@ -0,0 +1,310 @@
+"""
+AI Business Insights & Outreach Generation Service.
+
+Bridges deterministic LeadIntel intelligence (website analysis, SEO audits, competitor benchmarks, lead scores)
+with local Ollama inference.
+
+Strict Ethical Rules:
+- NEVER fabricates business revenue, marketing budgets, purchasing intent, or competitor weaknesses.
+- Labels all AI-generated synthesis clearly as `is_ai_generated: true` while preserving verified factual sources.
+- Grounded strictly in provided evidence: if data is absent, notes it explicitly rather than hallucinating.
+- Generates high-impact B2B outreach across Email, LinkedIn, and WhatsApp Business.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from .local_ai import LocalAIClient, local_ai_client
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT_INSIGHTS = """You are a senior business intelligence and digital strategy analyst.
+Your job is to provide objective, evidence-based insights for a business based EXCLUSIVELY on provided verified technical data.
+
+STRICT CONSTRAINTS:
+1. NEVER invent or assume company revenue, marketing budget, or customer purchasing intent.
+2. Ground all recommendations strictly in observable digital defects and gaps (e.g. missing SSL, slow response, missing H1, poor mobile viewport, lack of social links).
+3. Distinguish verified facts from AI strategic interpretations.
+4. Output valid JSON when requested.
+"""
+
+SYSTEM_PROMPT_OUTREACH = """You are an expert B2B digital agency consultant writing personalized, respectful, and highly specific outreach messages to a business decision maker.
+
+STRICT CONSTRAINTS & GUARDRAILS:
+1. Do not fabricate business data or website problems. Base the outreach strictly on the provided website_opportunity_explanation.
+2. If the site is missing (website_not_found_after_research), pitch a new build.
+3. If a CMS is detected or a contact route is missing, mention it as a specific reason for outreach.
+4. Do not use generic buzzwords or clickbait claims.
+5. Propose a collaborative, value-first conversation without assuming their budget or readiness to buy.
+6. Generate three distinct channels: Email Pitch, LinkedIn Message, and WhatsApp Business message.
+7. Output valid JSON.
+"""
+
+
+def _build_context_summary(
+    business_name: str,
+    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,
+) -> dict[str, Any]:
+    """Compile structured verified facts to ground AI synthesis."""
+    verified_facts: dict[str, Any] = {
+        "business_name": business_name,
+        "category": business_category or "Unspecified",
+    }
+
+    website_opp: dict[str, Any] = {}
+    if website_status:
+        website_opp["website_status"] = website_status
+    if website_opportunity_score is not None:
+        website_opp["website_opportunity_score"] = website_opportunity_score
+    if website_opportunity_explanation:
+        website_opp["website_opportunity_explanation"] = website_opportunity_explanation
+    if detected_cms:
+        website_opp["detected_cms"] = detected_cms
+    if has_contact_route is not None:
+        website_opp["has_contact_route"] = has_contact_route
+
+    if website_opp:
+        verified_facts["website_opportunity_and_tech"] = website_opp
+
+    if contact_info:
+        verified_facts["contact"] = {
+            "city": contact_info.get("city"),
+            "has_phone": bool(contact_info.get("phone")),
+            "has_email": bool(contact_info.get("email")),
+        }
+
+    if website_analysis:
+        verified_facts["website"] = {
+            "url": website_analysis.get("url"),
+            "available": website_analysis.get("available"),
+            "is_https": website_analysis.get("protocol", {}).get("is_https"),
+            "response_time_seconds": website_analysis.get("response_time_seconds"),
+            "mobile_viewport_configured": website_analysis.get("metadata", {}).get("has_mobile_viewport"),
+            "has_contact_form": website_analysis.get("contact_detection", {}).get("has_contact_form"),
+        }
+
+    if seo_audit:
+        verified_facts["seo"] = {
+            "score": seo_audit.get("seo_score"),
+            "issues_sample": [iss.get("message") for iss in seo_audit.get("issues", [])][:4],
+        }
+
+    if social_profiles:
+        profiles_dict = social_profiles.get("profiles", social_profiles)
+        active = [plat for plat, links in profiles_dict.items() if isinstance(links, list) and len(links) > 0]
+        verified_facts["social_media"] = {
+            "active_channels": active,
+            "channel_count": len(active),
+        }
+
+    if competitor_comparison:
+        verified_facts["competitor_context"] = {
+            "competitors_compared": competitor_comparison.get("competitors_compared_count", 0),
+            "strengths_sample": competitor_comparison.get("strengths", [])[:2],
+            "weaknesses_sample": competitor_comparison.get("weaknesses", [])[:2],
+        }
+
+    if lead_score_data:
+        verified_facts["lead_score"] = {
+            "overall_score": lead_score_data.get("overall_lead_score"),
+            "priority": lead_score_data.get("priority_classification"),
+            "service_opportunities": lead_score_data.get("service_opportunities"),
+            "recommended_package": lead_score_data.get("recommended_service_package"),
+            "verified_issues": lead_score_data.get("verified_issues", [])[:5],
+        }
+
+    return verified_facts
+
+
+async def generate_ai_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,
+    ai_client: Optional[LocalAIClient] = None,
+    http_client: Optional[httpx.AsyncClient] = None,
+) -> dict[str, Any]:
+    """
+    Generate evidence-based strategic business insights using local Ollama.
+    """
+    if not business_name or not business_name.strip():
+        raise ValueError("business_name must be a non-empty string.")
+
+    client = ai_client or local_ai_client
+    verified_data = _build_context_summary(
+        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,
+    )
+
+    prompt = f"""Analyze the verified business data below and produce a structured strategic insight report in JSON format.
+
+VERIFIED DATA:
+{json.dumps(verified_data, indent=2)}
+
+Required JSON schema:
+{{
+  "executive_summary": "string summarizing digital maturity and key findings",
+  "opportunity_explanation": "string explaining why specific digital opportunities exist based on the evidence",
+  "lead_score_interpretation": "string contextualizing the deterministic lead score without altering it",
+  "competitor_insights": "string comparing their posture against market peers",
+  "service_recommendations": [
+    {{
+      "service": "Website Development | SEO | Social Media Management | Digital Marketing",
+      "rationale": "specific evidence-backed reason",
+      "priority": "High | Medium | Low"
+    }}
+  ]
+}}
+"""
+
+    raw_response = await client.generate(
+        prompt=prompt,
+        system_prompt=SYSTEM_PROMPT_INSIGHTS,
+        format_json=True,
+        client=http_client,
+    )
+
+    try:
+        parsed_insights = json.loads(raw_response)
+    except json.JSONDecodeError:
+        parsed_insights = {
+            "executive_summary": raw_response,
+            "opportunity_explanation": "Extracted from local AI response.",
+            "lead_score_interpretation": "See deterministic lead score report.",
+            "competitor_insights": "Refer to competitor comparison matrix.",
+            "service_recommendations": [],
+        }
+
+    return {
+        "business_name": business_name,
+        "is_ai_generated": True,
+        "ai_model_used": client.model,
+        "verified_facts_grounding": verified_data,
+        "ai_insights": parsed_insights,
+        "disclaimer": (
+            "Observations under 'ai_insights' were synthesized by a local AI model grounded strictly in verified data. "
+            "No assumptions regarding customer budget or revenue were made."
+        ),
+    }
+
+
+async def generate_ai_outreach(
+    business_name: str,
+    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",
+    ai_client: Optional[LocalAIClient] = None,
+    http_client: Optional[httpx.AsyncClient] = None,
+) -> dict[str, Any]:
+    """
+    Generate tailored B2B outreach messages across Email, LinkedIn, and WhatsApp Business.
+    """
+    if not business_name or not business_name.strip():
+        raise ValueError("business_name must be a non-empty string.")
+
+    client = ai_client or local_ai_client
+    verified_data = _build_context_summary(
+        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,
+    )
+
+    prompt = f"""Generate personalized, professional B2B outreach messages for {business_name} in JSON format.
+Sender: {sender_name} representing {agency_name}.
+
+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.
+
+VERIFIED CONTEXT:
+{json.dumps(verified_data, indent=2)}
+
+Required JSON schema:
+{{
+  "email_pitch": {{
+    "subject": "Clear, curiosity-inducing subject line",
+    "body": "Professional 3-paragraph email referencing 1-2 verified technical findings and a low-friction call-to-action."
+  }},
+  "linkedin_message": {{
+    "message": "Concise connection message (under 300 characters) referencing their business and specific digital insight."
+  }},
+  "whatsapp_message": {{
+    "message": "Polite, direct WhatsApp Business message (under 120 words) with clear value proposition and polite sign-off."
+  }}
+}}
+"""
+
+    raw_response = await client.generate(
+        prompt=prompt,
+        system_prompt=SYSTEM_PROMPT_OUTREACH,
+        format_json=True,
+        client=http_client,
+    )
+
+    try:
+        parsed_outreach = json.loads(raw_response)
+    except json.JSONDecodeError:
+        parsed_outreach = {
+            "email_pitch": {"subject": f"Quick thought regarding {business_name}", "body": raw_response},
+            "linkedin_message": {"message": raw_response[:280]},
+            "whatsapp_message": {"message": raw_response[:300]},
+        }
+
+    return {
+        "business_name": business_name,
+        "is_ai_generated": True,
+        "ai_model_used": client.model,
+        "outreach_campaign": parsed_outreach,
+        "disclaimer": (
+            "These outreach drafts were synthesized by local AI using verified evidence. "
+            "Review and adapt messages before sending to prospects."
+        ),
+    }