zenith-tagger-api 0.1.1

Dependency-light Python client for Zenith's Furry Artwork Tagger: upload an image, poll for results, get tag dicts (label, confidence).

zenith-tagger-api

A small, dependency-light Python client for Zenith’s Furry Artwork Tagger. 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 2.28+ (declared in package metadata)

Installation

From PyPI (when published):

pip install zenith-tagger-api

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

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

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

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

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 for setup.

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

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
Issue tracker	Issues
Changelog	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.

Copyright (c) 2026 TheBunnieMaster