botvisibility 0.1.0__py3-none-any.whl

botvisibility/__init__.py

@@ -0,0 +1,29 @@
+"""BotVisibility — Python SDK.
+
+Lighthouse for AI agents. Scan any URL across 58 checks and 5 levels
+(Discoverable, Usable, Optimized, Indexable, Agent-Native) for AI-agent
+readiness. See https://botvisibility.com/docs
+"""
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, Client, __version__
+from .errors import (
+    APIError,
+    BotVisibilityError,
+    InvalidURLError,
+    PaymentRequiredError,
+)
+from .models import Check, ScanResult, Score
+
+__all__ = [
+    "Client",
+    "ScanResult",
+    "Score",
+    "Check",
+    "BotVisibilityError",
+    "APIError",
+    "InvalidURLError",
+    "PaymentRequiredError",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

botvisibility/cli.py

@@ -0,0 +1,64 @@
+"""Command-line interface: ``botvisibility <url>``."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from .client import Client
+from .errors import BotVisibilityError, PaymentRequiredError
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="botvisibility",
+        description="Scan a URL for AI agent readiness (BotVisibility).",
+    )
+    parser.add_argument("url", help="URL to scan, e.g. stripe.com")
+    parser.add_argument("--json", action="store_true", help="Print the raw JSON report")
+    parser.add_argument("--base-url", default=None, help="Override the API base URL")
+    parser.add_argument("--api-key", default=None, help="X-API-Key for a higher rate limit")
+    args = parser.parse_args(argv)
+
+    kwargs = {}
+    if args.base_url:
+        kwargs["base_url"] = args.base_url
+    if args.api_key:
+        kwargs["api_key"] = args.api_key
+
+    try:
+        with Client(**kwargs) as client:
+            result = client.scan(args.url)
+    except PaymentRequiredError as e:
+        print("Payment required: {0} (pay at {1})".format(e, e.paid_endpoint), file=sys.stderr)
+        return 2
+    except BotVisibilityError as e:
+        print("Error: {0}".format(e), file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(result.raw, indent=2))
+        return 0
+
+    s = result.score
+    print("BotVisibility — {0}".format(result.url))
+    print("  Level {0}: {1}  ({2})".format(s.level, s.level_name, s.grade))
+    print(
+        "  {0} passed / {1} failed / {2} partial / {3} n/a  (of {4})".format(
+            s.passed, s.failed, s.partial, s.na, s.total
+        )
+    )
+    fails = result.failing()
+    if fails:
+        print("  Top failures:")
+        for c in fails[:5]:
+            line = "    - [{0}] {1}".format(c.id, c.name)
+            if c.recommendation:
+                line += " → " + c.recommendation
+            print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

botvisibility/client.py

@@ -0,0 +1,120 @@
+"""Synchronous BotVisibility API client."""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .errors import APIError, InvalidURLError, PaymentRequiredError
+from .models import ScanResult
+
+DEFAULT_BASE_URL = "https://botvisibility.com"
+__version__ = "0.1.0"
+
+
+class Client:
+    """A thin, typed client over the BotVisibility REST API.
+
+    Example::
+
+        from botvisibility import Client
+
+        with Client() as bv:
+            result = bv.scan("stripe.com")
+            print(result.level_name, result.grade)
+            for c in result.failing():
+                print(c.id, c.name, "->", c.recommendation)
+
+    Args:
+        base_url: API origin. Defaults to https://botvisibility.com.
+        api_key: Optional ``X-API-Key`` for a higher rate limit.
+        token: Optional OAuth 2.0 bearer token (``scan:read`` scope).
+        timeout: Per-request timeout in seconds. Scans can take a while.
+        transport: Optional httpx transport (used for testing).
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: float = 60.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": "botvisibility-python/" + __version__,
+        }
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if token:
+            headers["Authorization"] = "Bearer " + token
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # --- lifecycle ---
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # --- API ---
+    def scan(self, url: str) -> ScanResult:
+        """Scan a single URL and return the full report.
+
+        Raises:
+            InvalidURLError: the URL was rejected (HTTP 400).
+            PaymentRequiredError: daily free allowance exceeded (HTTP 402).
+            APIError: any other non-2xx response.
+        """
+        resp = self._client.get("/api/scan", params={"url": url, "format": "json"})
+        return self._handle_scan(resp)
+
+    def compare(self, urls: Iterable[str]) -> List[ScanResult]:
+        """Scan several URLs and return their results in order."""
+        return [self.scan(u) for u in urls]
+
+    def badge_url(self, url: str) -> str:
+        """Return the SVG badge URL for a site (no request is made)."""
+        return self.base_url + "/api/badge?url=" + quote(url, safe="")
+
+    # --- internals ---
+    def _handle_scan(self, resp: httpx.Response) -> ScanResult:
+        if resp.status_code == 200:
+            return ScanResult.from_dict(resp.json())
+
+        body = self._safe_json(resp)
+        detail = (body or {}) if isinstance(body, dict) else {}
+
+        if resp.status_code == 400:
+            raise InvalidURLError(detail.get("message") or detail.get("error") or "Invalid URL")
+        if resp.status_code == 402:
+            raise PaymentRequiredError(
+                detail.get("message") or "Daily free allowance exceeded",
+                paid_endpoint=detail.get("paid_endpoint"),
+                limit=detail.get("limit"),
+                protocol=detail.get("protocol"),
+                body=body,
+            )
+        raise APIError(
+            "BotVisibility API error " + str(resp.status_code),
+            status=resp.status_code,
+            body=body,
+        )
+
+    @staticmethod
+    def _safe_json(resp: httpx.Response) -> Optional[Dict[str, Any]]:
+        try:
+            return resp.json()
+        except Exception:
+            return None

botvisibility/errors.py

@@ -0,0 +1,42 @@
+"""Typed exceptions raised by the BotVisibility client."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BotVisibilityError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(BotVisibilityError):
+    """The API returned an unexpected (non-2xx, non-handled) status."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class InvalidURLError(BotVisibilityError):
+    """The URL passed to scan() was rejected (HTTP 400)."""
+
+
+class PaymentRequiredError(BotVisibilityError):
+    """The daily free allowance was exceeded (HTTP 402).
+
+    Carries the x402 payment pointer so callers can settle and retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        paid_endpoint: Optional[str] = None,
+        limit: Optional[int] = None,
+        protocol: Optional[str] = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.paid_endpoint = paid_endpoint
+        self.limit = limit
+        self.protocol = protocol
+        self.body = body

botvisibility/models.py

@@ -0,0 +1,110 @@
+"""Typed models for BotVisibility scan results.
+
+Mirrors the JSON returned by GET /api/scan?format=json. Every model keeps the
+original ``raw`` dict so callers can reach fields the SDK doesn't surface yet.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Check:
+    """A single agent-readiness check result."""
+
+    id: str
+    name: str
+    status: str  # "pass" | "fail" | "partial" | "na"
+    passed: bool
+    level: int
+    category: Optional[str] = None
+    message: Optional[str] = None
+    recommendation: Optional[str] = None
+    details: Optional[str] = None
+    found_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Check":
+        return cls(
+            id=str(d.get("id", "")),
+            name=d.get("name", ""),
+            status=d.get("status", ""),
+            passed=bool(d.get("passed", False)),
+            level=int(d.get("level", 0) or 0),
+            category=d.get("category"),
+            message=d.get("message"),
+            recommendation=d.get("recommendation"),
+            details=d.get("details"),
+            found_at=d.get("foundAt"),
+            raw=d,
+        )
+
+
+@dataclass
+class Score:
+    """Top-level summary optimized for agents."""
+
+    passed: int
+    failed: int
+    partial: int
+    na: int
+    total: int
+    level: int
+    level_name: str
+    grade: str  # "perfect" | "good" | "fair" | "needs-work"
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Score":
+        return cls(
+            passed=int(d.get("passed", 0) or 0),
+            failed=int(d.get("failed", 0) or 0),
+            partial=int(d.get("partial", 0) or 0),
+            na=int(d.get("na", 0) or 0),
+            total=int(d.get("total", 0) or 0),
+            level=int(d.get("level", 0) or 0),
+            level_name=d.get("levelName", ""),
+            grade=d.get("grade", ""),
+            raw=d,
+        )
+
+
+@dataclass
+class ScanResult:
+    """A full BotVisibility scan of a single URL."""
+
+    url: str
+    score: Score
+    current_level: int
+    checks: List[Check]
+    timestamp: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "ScanResult":
+        return cls(
+            url=d.get("url", ""),
+            score=Score.from_dict(d.get("score", {}) or {}),
+            current_level=int(d.get("currentLevel", 0) or 0),
+            checks=[Check.from_dict(c) for c in d.get("checks", []) or []],
+            timestamp=d.get("timestamp"),
+            raw=d,
+        )
+
+    # --- convenience accessors ---
+    @property
+    def grade(self) -> str:
+        return self.score.grade
+
+    @property
+    def level_name(self) -> str:
+        return self.score.level_name
+
+    def failing(self) -> List[Check]:
+        """Checks that failed outright (status == 'fail')."""
+        return [c for c in self.checks if c.status == "fail"]
+
+    def passing(self) -> List[Check]:
+        return [c for c in self.checks if c.status == "pass"]

botvisibility-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: botvisibility
+Version: 0.1.0
+Summary: Python SDK for BotVisibility — Lighthouse for AI agents. Scan any URL across 58 checks and 5 levels for AI-agent readiness.
+Project-URL: Homepage, https://botvisibility.com
+Project-URL: Documentation, https://botvisibility.com/docs
+Project-URL: Source, https://github.com/jjanisheck/botvisibility
+Author: Joey Janisheck
+License: MIT
+License-File: LICENSE
+Keywords: aeo,agent-readiness,agents,ai,botvisibility,geo,llms.txt,mcp,openapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# botvisibility (Python SDK)
+
+Python client for [**BotVisibility**](https://botvisibility.com) — Lighthouse
+for AI agents. Scan any URL across 58 checks and 5 levels (Discoverable, Usable,
+Optimized, Indexable, Agent-Native) to see how ready it is for AI agents like
+Claude and GPT.
+
+## Install
+
+```bash
+pip install botvisibility
+```
+
+## Quick start
+
+```python
+from botvisibility import Client
+
+with Client() as bv:
+    result = bv.scan("stripe.com")
+
+    print(result.url, "->", f"Level {result.score.level}: {result.level_name} ({result.grade})")
+    print(f"{result.score.passed} passed / {result.score.failed} failed")
+
+    for check in result.failing():
+        print(f"  [{check.id}] {check.name} → {check.recommendation}")
+```
+
+### Compare sites
+
+```python
+with Client() as bv:
+    for r in bv.compare(["stripe.com", "twilio.com"]):
+        print(r.url, r.level_name, r.grade)
+```
+
+### Badge URL
+
+```python
+Client().badge_url("stripe.com")
+# -> "https://botvisibility.com/api/badge?url=stripe.com"
+```
+
+## Authentication
+
+Public access needs no credentials. To raise your daily allowance, pass an
+OAuth 2.0 `scan:read` bearer token or an API key:
+
+```python
+Client(token="…")     # Authorization: Bearer …
+Client(api_key="…")   # X-API-Key: …
+```
+
+See <https://botvisibility.com/auth.md>.
+
+## Errors
+
+```python
+from botvisibility import Client, PaymentRequiredError, InvalidURLError, APIError
+
+try:
+    Client().scan("example.com")
+except PaymentRequiredError as e:
+    # Over the free allowance — settle via x402 and retry.
+    print("Pay at", e.paid_endpoint)
+except InvalidURLError:
+    ...
+except APIError as e:
+    print(e.status, e.body)
+```
+
+## CLI
+
+```bash
+botvisibility stripe.com          # human-readable summary
+botvisibility stripe.com --json   # raw JSON report
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © Joey Janisheck. Not affiliated with any third party; see
+<https://botvisibility.com>.

botvisibility-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+botvisibility/__init__.py,sha256=ojvuXlYAZwey2CbB1EUBWRVe1tLqJFI_sict1hecEUg,682
+botvisibility/cli.py,sha256=ODh8TzNg_7ZFZYW6NQdja7x66eUXW0LKAhzeUcYWz7g,2061
+botvisibility/client.py,sha256=---Df_RgJ_Ex4saocRj8x64Pd3YnaZGhlCx6Q5CqcVE,3932
+botvisibility/errors.py,sha256=_j2s15Ix7fhTLcDV7zFuAkcijs67e1FXEYu8WT6W8DA,1156
+botvisibility/models.py,sha256=lttLJZMSF1kiLvesPg7GZEd1MkVPYPhSacDiRcupcEU,3232
+botvisibility-0.1.0.dist-info/METADATA,sha256=SD9tPN-Scow5i3jIUqwJHnVz8ONf2iWb9slBjhUpwnI,3176
+botvisibility-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+botvisibility-0.1.0.dist-info/entry_points.txt,sha256=Qn6bG-bVw12FhxBAslb4aMLrWtyHaprucZnabkczp7A,57
+botvisibility-0.1.0.dist-info/licenses/LICENSE,sha256=zCf50UN-W74S2is6L6qaRW41XUzgcXspoMOTf4Q7rI4,1071
+botvisibility-0.1.0.dist-info/RECORD,,

botvisibility-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

botvisibility-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+botvisibility = botvisibility.cli:main

botvisibility-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Janisheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.