foidfinder: Open‑Source Tool to Identify Anime Characters and Series from Images

Overview

foidfinder is a free, open‑source application that tags anime images with the characters and series they contain. It leverages PixAI Tagger v1.0 (trained on Danbooru data up to May 2026) and can run on either Apple‑silicon (MLX) or NVIDIA GPUs (CUDA).

How it Works

• The tool receives an image via a JSON API and returns a list of tags, each with a confidence score.
• Tags are generated by the PixAI model, which operates on 72 × 72 pixel patches arranged in 3 × 3 windows of 24 × 24 pixels. No image is ever written to disk; uploads stay in memory only.
• Errors follow a simple schema, e.g. `{"error": {"code": 400, "message": "Invalid image"}}`.

Deployment Options

• Container image: The first run pulls the INT8 checkpoint `alpindale/PixAI‑v1.0‑INT8` (≈0.6 GB) into a Docker volume.
• CUDA specifics: The checkpoint is quantized at start‑up, needing ~3.3 GB VRAM (vs. 0.9 GB for INT8). The model uses int8 GEMM, fp16 tensor‑core attention, and a single CUDA graph per batch.
• MLX specifics: Loads the official checkpoint directly; matches the reference implementation within 1e‑5 (fp32) and 0.003 (fp16).

Running Behind a Proxy

For security, the Docker compose file publishes the service on loopback only. A reverse proxy (e.g., Caddy) with TLS and rate‑limiting should sit in front. If the GPU host cannot store TLS or Cloudflare credentials, it can connect to a proxy over SSH using a restricted `foidfinder‑tunnel` user.

Performance & Accuracy

• Tested on 588 Danbooru posts (July‑Oct 2026) at PixAI’s thresholds (character 0.27, copyright 0.24).
• Top‑1 accuracy: 345 of those posts were correctly tagged with the primary character.
• The MLX backend reproduces the official model’s outputs to within 1e‑5 (fp32) and 0.003 (fp16).

Licensing

The code is released under the Apache‑2.0 license. PixAI Tagger v1.0, which foidfinder bundles, is also Apache‑2.0.

Practical Implications

• For developers: You can embed foidfinder in a web service, Discord bot, or personal collection manager without paying for a commercial API.
• For privacy‑concerned users: Images never touch a third‑party server; they stay on your own hardware.
• Verification: Clone the repository, inspect `compose.yaml` and `deploy/tunnel.compose.yaml`, and compare the model card (`config.json`) with the official PixAI release on Hugging Face.

Getting Started

```bash git clone https://github.com/AlpinDale/foidfinder.git cd foidfinder

Choose backend via environment variable or flag, e.g.

FOIDFINDER_BACKEND=mlx docker compose up -d ```

Visit the reverse‑proxy URL (e.g., `https://your‑domain.com/foidfinder`) and POST an image to `/identify`.

--- *All statements are derived from the project's README and source files; no external claims are added.*