Metadata-Version: 2.5
Name: kalathos
Version: 0.2.0
Summary: Server SDK for kalathos.ai request reporting and Fetcher Seeds
Project-URL: Homepage, https://kalathos.ai
Project-URL: Documentation, https://kalathos.ai/docs#server
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agents,asgi,kalathos,middleware,web-bot-auth,wsgi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: jsonschema>=4.23; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Description-Content-Type: text/markdown

# kalathos Python SDK

Server middleware for Python (ASGI and WSGI) that reports requests to kalathos.ai and renders **Fetcher Seeds**.

```bash
pip install kalathos
```

Python 3.10 or later. Documentation: [kalathos.ai/docs](https://kalathos.ai/docs#server).

## Request reporting (WSGI)

```python
from kalathos import Kalathos, KalathosConfig
from kalathos.middleware import wsgi_middleware

kalathos = Kalathos(KalathosConfig(
    secret_key=os.environ["KALATHOS_SECRET_KEY"],
    field_id="fld_…",
))
app = wsgi_middleware(kalathos, django_app)
```

## Request reporting (ASGI)

```python
from kalathos.middleware import asgi_middleware, create_kalathos

kalathos = create_kalathos(KalathosConfig(...))
app = asgi_middleware(kalathos)(fastapi_app)
```

## Shutdown

Events are batched in the background; anything still queued when the process exits is lost. The ASGI
middleware flushes automatically on lifespan shutdown (after your app's own shutdown handlers). For
WSGI servers, or ASGI servers run without lifespan, close the reporter yourself:

```python
import atexit
atexit.register(kalathos.close)  # stops the flush timer and sends every queued event
```

## Fetcher Seeds

Fetcher Seeds are part of the Scale and Enterprise plans and take a **secret key** (`kl_sk_…` with
`seeds:read`), which stays on your server. On other plans the resolver answers 402 and nothing is
rendered (request reporting works on every plan). Publishable keys (`kl_pk_…`) only resolve seeds in
the browser, through kalathos.js.

```python
from kalathos import FetcherSeeds, FetcherSeedsConfig, SeedRoute

seeds = FetcherSeeds(FetcherSeedsConfig(
    secret_key=os.environ["KALATHOS_SECRET_KEY"],
    field_id="fld_…",
    routes=[SeedRoute(match="/products/*", goal="purchase")],
))
html = seeds.render("/products/trail-runner")
```

Behavior matches the Node SDK, [`@kalathos/node`](https://www.npmjs.com/package/@kalathos/node).

## License

Apache-2.0. See `LICENSE` and `NOTICE`.
