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>.
