Metadata-Version: 2.5
Name: abliteration
Version: 0.1.0
Summary: Python client for the abliteration.org catalog API
Project-URL: Homepage, https://abliteration.org/api
Project-URL: Documentation, https://abliteration.org/api
Project-URL: Source Code, https://abliteration.org/api
Project-URL: Issue Tracker, https://abliteration.org/api
Author-email: Catyonic OÜ <contact@catyonic.com>
License: MIT
License-File: LICENSE
Keywords: abliteration,api,catalog,cli,huggingface,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# abliteration

[![PyPI version](https://img.shields.io/pypi/v/abliteration.svg)](https://pypi.org/project/abliteration/)
[![Python versions](https://img.shields.io/pypi/pyversions/abliteration.svg)](https://pypi.org/project/abliteration/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python client for the [abliteration.org](https://abliteration.org) catalog API.

The same data that renders the site — models, datasets, methods, indices, timeline —
served as JSON, with an `httpx`-based client and a small `abl` CLI. Sync only for now.

## Install

```bash
pip install abliteration
```

Python 3.9 or newer. The only runtime dependency is [`httpx`](https://www.python-httpx.org).

## Get a key

Generate a Bearer token at <https://abliteration.org/shop/account#api-keys>.
Then either export it, or pass it to `Client(api_key=...)`:

```bash
export ABLITERATION_API_KEY=abl_live_...
```

## Quick start

```python
from abliteration import Client

with Client() as c:
    for m in c.models(method="M4", limit=5):
        print(m.id, m.downloads)

    m = c.model("mlabonne/Qwen3-30B-A3B-abliterated")
    print(m.author, len(m.files), "files")

    for idx in c.indices():
        print(idx.id, idx.value, idx.unit)
```

Every list endpoint returns `list[SummaryDataclass]`, every single-entity
endpoint returns a `DetailDataclass`. Fields are typed but forgiving —
extra fields the server adds later are ignored rather than raising, so
old client versions keep working.

## Envelope

If you need `cost`, `credits_remaining`, or the rate-limit metadata:

```python
env = c.get_envelope("/api/v1/models", params={"method": "M4", "limit": 3})
print(env.data)              # list of raw dicts
print(env.credits_remaining) # wallet after this call
print(env.rate_limit_remaining, "/", env.rate_limit_limit)
```

## Errors

```python
from abliteration import (
    Client, AuthenticationError, PaymentRequiredError, RateLimitError, APIError
)

try:
    with Client() as c:
        c.models(limit=3)
except AuthenticationError:
    ...  # 401 — bad or missing key
except PaymentRequiredError as e:
    ...  # 402 — wallet empty; e.body["message"] points at top-up
except RateLimitError as e:
    ...  # 429 — after built-in retries; e.retry_after is int seconds
except APIError as e:
    ...  # anything else; e.status_code, e.body, e.request_id
```

By default the client retries `429` up to twice, honoring `retry_after`.
Set `max_retries=0` to opt out.

## CLI

The package installs an `abl` command (with `abliteration` as a longer
alias for the same entry point):

```bash
abl credits
# credits: 9,847
# rate limit: 118/120 left this window

abl models --method M4 --limit 5
# mlabonne/Qwen3-30B-A3B-abliterated                          234,128
# mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF         30,530
# ...

abl model mlabonne/Qwen3-30B-A3B-abliterated
# id:     mlabonne/Qwen3-30B-A3B-abliterated
# author: mlabonne
# name:   Qwen3-30B-A3B-abliterated
# files:  14

abl get /api/v1/methods --json | jq '.data[] | .id'
```

`--json` on any command emits structured output for pipelines.

The richer CLI with browser-based login, keyring integration, and
table formatting lives in [`@abliteration/cli`](https://www.npmjs.com/package/@abliteration/cli)
on npm. This one is deliberately minimal and covers the everyday
scripting case.

## Endpoints covered

- `models(...)`, `model(id)` — models list and detail
- `methods()`, `method(id)` — M1-M9 taxonomy
- `indices()`, `index(id)` — DAI, Freedom Velocity, Weaponization, F2W Latency
- `authors(...)`, `author(id)` — author aggregates
- `datasets(...)`, `dataset(id)` — datasets list and detail
- `timeline(...)` — events

## Documentation

Full API reference: <https://abliteration.org/api>.

## License

MIT.
