Search for businesses matching a query using free, open data sources.

    Uses OpenStreetMap / Overpass API for live discovery (no API key required).
    Falls back to demo data when the network is unavailable or DEMO_MODE=true.

    Args:
        query:    Free-text search term, e.g. "coffee shop", "software company",
                  "law firm", "restaurant". Pass "*" for a broad sweep.
        location: City, region, or "lat,lon" coordinates to centre the search,
                  e.g. "London", "Austin, TX", "48.8566,2.3522".
                  Required for live OSM search — omitting it falls back to demo data.
        category: Optional industry hint, e.g. "Technology", "Healthcare",
                  "Food & Beverage". Narrows the Overpass tag filter.
        limit:    Maximum results to return (1–50, default 10).

    Returns:
        dict with keys:
          query, location, category  — echoed inputs
          total_found (int)          — number of matching results
          businesses (list[dict])    — business records
          provider (str)             — data source used
          retrieved_at (str)         — ISO-8601 timestamp
          attribution (str|null)     — ODbL attribution (show this when displaying OSM data)
          note (str|null)            — caveat about data quality or mode

    Attribution:
        When provider is "openstreetmap", you MUST display the attribution string
        "Data © OpenStreetMap contributors, ODbL 1.0" wherever results appear.

    Compliance:
        - OpenStreetMap data is used under the ODbL licence.
        - No data is sent to third parties.
        - is_ai_generated=False for all records from this tool.
    

    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.
    

    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
    

    Analyze a business website for technical readiness, structure, and contacts.

    Performs non-invasive examination of the target website:
    - HTTP/HTTPS status and SSL verification.
    - Title, meta description, and mobile viewport configuration.
    - H1/H2 heading hierarchy and image alt tag presence.
    - Public email addresses, telephone numbers, and contact forms.
    - Linked social media profiles.
    - Sampled check for broken internal links.

    Security & Compliance:
    - Respects robots.txt directives before scraping.
    - Protects against SSRF (blocks localhost, private networks, cloud metadata).
    - Enforces request timeouts and max page size limits.
    - Does not scrape private or sensitive personal info.

    Args:
        url: The target website URL (e.g. 'https://example.com').
        check_broken_links: If True, spot-checks up to 10 internal links for broken status (default: True).

    Returns:
        Structured diagnostic dictionary.
    

    Run a technical on-page SEO audit on a business website.

    Evaluates fundamental search engine optimization signals:
    - Missing or duplicate title tags and length bounds.
    - Missing or suboptimal meta descriptions.
    - Missing H1 or multiple H1 heading tags.
    - Missing image alt attributes and overall image alt coverage percentage.
    - Canonical URL link specification.
    - Meta robots directives (noindex/nofollow).
    - Availability of robots.txt and sitemap.xml.
    - Open Graph tags for social preview readiness.
    - Internal link count and page weight.

    Output:
    - SEO score from 0 to 100.
    - Detailed checklist breakdown.
    - Specific prioritized issues (errors, warnings, info).
    - Actionable recommendations.

    Notice:
    This is an on-page technical SEO diagnostic tool and not an official
    Google ranking assessment or proprietary PageRank score.

    Args:
        url: The target website URL (e.g. 'https://example.com').

    Returns:
        Structured SEO audit report.
    

    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.
    

    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.
    

    Compare a target business against a list of competitor businesses.

    Benchmarks organizations across critical digital and operational dimensions:
    - Website availability & response time
    - Technical SEO score (0-100)
    - HTTPS/SSL security configuration
    - Mobile viewport readiness
    - Social media footprint (channels active)
    - Contact accessibility (forms, direct email, direct phone)
    - Public reviews and ratings where available

    Outputs:
    - Structured comparison table matrix
    - High-confidence strengths
    - Critical digital weaknesses
    - High-leverage growth opportunities
    - Executive competitive positioning summary

    Args:
        target_business: Dict representing target company. Must include 'name', optional 'website', 'category', 'city'.
        competitor_businesses: List of dicts representing competitor companies to benchmark against.

    Returns:
        Comprehensive competitive intelligence comparison report.
    

    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.
    

    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.
    

    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.

    Args:
        business_name: Target company name (required).
        business_category: Business industry/category.
        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.
    

    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.
    

    Search for businesses and export results to an Excel (.xlsx), CSV, or JSON file.

    Features:
    - Excel: Creates a multi-sheet workbook with frozen headers, auto-filters, and clean styling.
    - CSV: Standard tabular spreadsheet export.
    - JSON: Complete structured lead metadata with timestamps and attribution.

    Args:
        query: Free-text search term (e.g. 'cafe', 'software').
        location: City, region, or coordinates.
        category: Industry or category filter.
        limit: Max number of leads to export (1-200, default 50).
        format: 'excel' (or 'xlsx'), 'csv' (default), or 'json'.
        output_path: Destination file path (optional).

    Returns:
        Dict containing output_path, row_count, format, and data attribution.