Metadata-Version: 2.4
Name: sempite
Version: 0.1.0
Summary: Python client for the SEMPITE AI Search Visibility API — check whether ChatGPT, Google AI, Perplexity, Gemini, and Claude know your brand.
Project-URL: Homepage, https://sempite.com/ai-search-visibility-api/
Project-URL: Documentation, https://sempite.com/api/v1/docs
Project-URL: Repository, https://github.com/SEMPITEHQ/sempite-python
Author-email: SEMPITE <hello@sempite.com>
License: MIT
License-File: LICENSE
Keywords: aeo,ai-search,brand-monitoring,chatgpt,geo,llm,perplexity,seo,visibility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sempite-python

Python client for the [SEMPITE AI Search Visibility API](https://sempite.com/ai-search-visibility-api/) — check whether AI engines (ChatGPT, Google AI, Perplexity, Gemini, Claude) know your brand, and whether they cite your website.

Zero dependencies (standard library only). Python 3.8+.

## Install

```bash
pip install sempite
```

Or just copy `src/sempite/__init__.py` into your project — it's one file.

## Get a key

Free plan — 10 checks/month, no card:

```python
from sempite import SempiteClient
SempiteClient.request_free_key("you@company.com")   # key arrives by email
```

or sign up at [sempite.com/ai-search-visibility-api](https://sempite.com/ai-search-visibility-api/).

## Quickstart

```python
from sempite import SempiteClient

client = SempiteClient("sk_live_...")   # or set the SEMPITE_API_KEY env var

result = client.check("Acme Coffee Roasters", domain="acmecoffee.com")

print(result["visibility_score"])              # 0-100, share of engines that know the brand
for engine, r in result["engines"].items():
    print(f"{engine}: present={r.get('present')} cites_site={r.get('cites_site')}")
    # r["snippet"] holds the first 400 chars of the engine's actual answer
```

### Custom prompt, market, engine subset

```python
result = client.check(
    "Acme Coffee Roasters",
    domain="acmecoffee.com",
    market="uk",                          # us (default), es, mx, uk
    prompt="Best specialty coffee roasters in London?",
    engines=["chatgpt", "perplexity"],    # default: every engine your plan includes
)
```

### Usage / quota

```python
print(client.usage())
# {'plan': 'starter', 'month': '2026-07', 'checks_used': 12,
#  'checks_quota': 250, 'checks_remaining': 238}
```

## Engines & plans

| Engine | Key | Free | Starter / Pro |
|---|---|---|---|
| Google AI Mode | `google_ai` | ✅ | ✅ |
| ChatGPT | `chatgpt` | ✅ | ✅ |
| Perplexity | `perplexity` | — | ✅ |
| Gemini | `gemini` | — | ✅ |
| Claude | `claude` | — | ✅ |

Free = 10 checks/month · Starter ($29/mo) = 250 · Pro ($99/mo) = 1,000. Rate limit: 10 requests/minute per key.

## Errors

```python
from sempite import SempiteClient, AuthError, QuotaError, RateLimitError, SempiteError

try:
    result = client.check("Acme")
except QuotaError as e:        # 402 — quota reached or engine needs a paid plan
    print(e, "→", e.upgrade_url)
except RateLimitError:         # 429 — slow down (10 req/min)
    ...
except AuthError:              # 401 — bad or revoked key
    ...
except SempiteError as e:      # anything else; e.status, e.payload
    ...
```

## Response shape

```json
{
  "brand": "Acme Coffee Roasters",
  "domain": "acmecoffee.com",
  "market": "us",
  "prompt": "Who is Acme Coffee Roasters?",
  "engines": {
    "google_ai": {"present": true, "cites_site": true, "snippet": "Acme Coffee Roasters is..."},
    "chatgpt":   {"present": true, "cites_site": false, "snippet": "..."}
  },
  "visibility_score": 100,
  "checks_used": 3,
  "checks_quota": 10,
  "plan": "free",
  "checked_at": "2026-07-19T15:04:05Z"
}
```

`visibility_score` = share of successfully-queried engines that recognized the brand (name present, no refusal). `cites_site` = the engine's answer mentioned your domain.

## Links

[API docs](https://sempite.com/api/v1/docs) · [Pricing](https://sempite.com/ai-search-visibility-api/) · [Free visibility check (no key)](https://sempite.com/free-check) · [AI Visibility Index — monthly research](https://sempite.com/research/ai-visibility-index/) · [SEMPITE](https://sempite.com)

## License

MIT
