# web-distiller

Python client for the [Distiller](https://webdistiller.dev) API — agent-ready web extraction with AI cleaning.

`pip install web-distiller` installs the client for the hosted Distiller API. It does not install or run the Distiller server.

Use it with:
- free-tier API keys (Trafilatura cleaning),
- the Starter paid plan (Stripe-backed AI cleaning),
- or alternate x402 payment-compatible deployments.

## Install

```bash
pip install web-distiller
set DISTILLER_API_BASE=https://webdistiller.dev
```

## Quick start

```python
from distiller_client import DistillerClient

client = DistillerClient(api_key="your-key")
result = client.markdown("https://example.com")
print(result["cleaned_markdown"])
```

Or as a one-liner:

```python
import distiller_client

print(distiller_client.markdown("https://example.com")["cleaned_markdown"])
```

## CLI

```bash
web-distiller https://example.com
web-distiller https://example.com --format text
web-distiller https://example.com --use-browser
web-distiller https://example.com --force-refresh
```

## Configuration

| Env var | Purpose |
|---------|---------|
| `DISTILLER_API_BASE` | API base URL (default: production) |
| `DISTILLER_API_KEY` | Bearer token for authenticated access |
| `DISTILLER_REFERRER_TOKEN` | Referral attribution token |

All env vars can also be passed as constructor arguments.

Typical flow:
- use `web-distiller` without an API key for open/demo deployments,
- register for an API key when you want the free 1,000-call tier,
- upgrade that account to Starter through Stripe when you want AI cleaning and `/extract`.

## Releases

`web-distiller` is released to PyPI from GitHub Actions via Trusted Publishing.

- Use the `.github/workflows/publish-web-distiller.yml` workflow for manual publishes.
- Or push a tag in the format `web-distiller-vX.Y.Z` after updating `distiller-client/pyproject.toml`.
