Metadata-Version: 2.4
Name: zenith-tagger-api
Version: 0.1.1
Summary: Dependency-light Python client for Zenith's Furry Artwork Tagger: upload an image, poll for results, get tag dicts (label, confidence).
Author-email: TheBunnieMaster <social@bunnie.top>
License: MIT
Project-URL: Source, https://codeberg.org/TheBunnieMaster/zenith-tagger-api
Project-URL: Bug Tracker, https://codeberg.org/TheBunnieMaster/zenith-tagger-api/issues
Project-URL: Changelog, https://codeberg.org/TheBunnieMaster/zenith-tagger-api/src/branch/main/CHANGELOG.md
Keywords: furry,furries,lgbt,lgbtq,gay,gooner,zenith,tagger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# zenith-tagger-api

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

A small, dependency-light Python client for **[Zenith’s Furry Artwork Tagger](https://pawgge.rs)**. It uploads a local image, polls for inference results, and returns a list of tag dictionaries (`label`, `confidence`).

**PyPI package:** `zenith-tagger-api` · **Import name:** `zenith_tagger`

---

## Features

- **Simple API** — one class, `ZenithTagger`, with `tag_image()` for end-to-end tagging
- **Persistent `requests.Session`** — connection reuse and a clear `User-Agent`
- **Typed exceptions** — `ZenithUploadError`, `ZenithTimeoutError`, `ZenithAPIError`, all subclassing `ZenithError`
- **Configurable** — custom base URL (e.g. mirrors or future deployments)
- **Logging** — uses the standard library `logging` namespace `zenith_tagger.client`

## Requirements

- Python **3.7+**
- **[requests](https://requests.readthedocs.io/)** 2.28+ (declared in package metadata)

## Installation

From [PyPI](https://pypi.org/project/zenith-tagger-api/) (when published):

```bash
pip install zenith-tagger-api
```

From a clone of this repository (editable install for development):

```bash
git clone https://codeberg.org/TheBunnieMaster/zenith-tagger-api.git
cd zenith-tagger-api
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
```

## Quick start

```python
from zenith_tagger import ZenithTagger

tagger = ZenithTagger()
tags = tagger.tag_image("/path/to/image.png")

for tag in tags:
    print(tag["label"], tag["confidence"])
```

Each element of `tags` is a `dict` with at least `label` and `confidence` (see the live API for the exact schema).

## Configuration

### Default service

By default the client uses `https://pawgge.rs` (trailing slashes are normalized).

### Custom base URL

```python
tagger = ZenithTagger(base_url="https://your-mirror.example.com")
```

### Polling

`tag_image()` uploads, then polls `GET /api/result?file_md5=…` until tags appear or limits are hit:

| Argument       | Default | Purpose                                      |
|----------------|---------|----------------------------------------------|
| `retry_delay`  | `1.5`   | Seconds between polls                        |
| `max_retries`  | `10`    | Maximum poll attempts after upload           |

Increase `max_retries` or `retry_delay` if the service is slow under load.

### Logging

```python
import logging

logging.basicConfig(level=logging.INFO)  # or logging.DEBUG for poll details
```

Logger name: `zenith_tagger.client`.

## Exceptions

| Exception            | When it occurs                                      |
|----------------------|-----------------------------------------------------|
| `FileNotFoundError`  | The given image path does not exist                 |
| `ZenithUploadError`  | Network/upload failure during `POST /api/image`    |
| `ZenithAPIError`     | JSON response without `file_md5` (API error field)  |
| `ZenithTimeoutError` | No tags after `max_retries` polls                  |

All custom errors subclass `ZenithError`.

## Development

See **[CONTRIBUTING.md](CONTRIBUTING.md)** for setup.

**Quick path:** install dev tools, then run the full check (format, lint, tests, build, metadata):

```bash
pip install -e ".[dev]"   # or: pip install -r requirements-dev.txt
make verify               # or: make install-dev && make check
```

If you do not use Make, the same commands are written out in CONTRIBUTING.md.

## Project links

| Resource   | URL |
|------------|-----|
| Source     | [codeberg.org/TheBunnieMaster/zenith-tagger-api](https://codeberg.org/TheBunnieMaster/zenith-tagger-api) |
| Issue tracker | [Issues](https://codeberg.org/TheBunnieMaster/zenith-tagger-api/issues) |
| Changelog  | [CHANGELOG.md](https://codeberg.org/TheBunnieMaster/zenith-tagger-api/src/branch/main/CHANGELOG.md) |

## Disclaimer

This library is an independent HTTP client. It is not affiliated with the operators of the tagging service. Use the public API in line with their terms, acceptable use, and any rate or capacity limits. Model output is provided by a third-party service; the authors of this package do not control availability, accuracy, or policy changes.

## License

MIT — see [LICENSE](LICENSE).

Copyright (c) 2026 TheBunnieMaster
