HyVis is a vibecoded local autotagging utility with optional desktop interface for your Hydrus client. It pairs vision transformer classification models with customizable tag filtering to automatically tag files and push them to Hydrus.

HyVis reads files directly from your disk using paths retrieved from Hydrus file metadata, so it must run on the same machine (or have direct storage access) as your Hydrus client (I don't have a setup to test if files being saved on a NAS or similar works or not). Downloading files over API would be inefficient, so it's not implemented, but if needed, you can open an issue - I may or may not give it a try

• Some Key Features
  • Showcase
• Installation
• Updating
• Usage
  • Desktop Interface (GUI)
  • HyVis CLI
  • Configuration
    • Supported and Recommended Models
  • Useful CLI Flags

• Desktop GUI (hyvis-gui): PySide6 (Qt) based UI for creating/editing HyVis TOML configuration files - with live Hydrus service sync and real-time validation; Should be a decent UX boost over editing TOMLs directly
• File Fetching: Fetch files from Hydrus using open pages (practically WYSIWYG), tag search queries, or by supplying --extra-hash-file (for wd-e621-hydrus-tagger compatibility)
• Client Previews: Preview files that are about to be processed (or were rejected) in Hydrus before tagging begins.
• Multi-Model Support: Run multiple models sequentially with global or per-model filter overrides
• Output Filtering: Comprehensive settings for confidence thresholds, namespace prefix mappings, replacements, subset limits, and category filtering

• GUI

Main Page	Models Page

Output Filter + Error	Launch Dialog

• CLI

• git | Installation Guide
• Python 3.11 or higher | Python 3.12 is recommended and tested
• Local Hydrus client to connect to with Client API enabled.

git clone https://github.com/DraconicDragon/HyVis.git
cd HyVis

python -m venv .venv

• Linux/macOS: source .venv/bin/activate
• Windows (CMD): .venv\Scripts\activate.bat
• Windows (PowerShell): .venv\Scripts\Activate.ps1

Install HyVis and its core dependencies:

# Core CLI only
pip install .

# With Desktop GUI
pip install ".[gui]"

HyVis supports PyTorch and ONNX backends. You do not need to install both; choose the one that matches the models you plan to run if you want to save space. PyTorch is recommended for broader model compatibility.

Hardware Support Note: HyVis is made and tested on Nvidia hardware. AMD ROCm and Intel GPU configurations are untested since I don't have the respective hardware. If you run HyVis on these platforms, you may need to install the corresponding backend packages manually (e.g., onnxruntime-rocm). It is possible that a few-line code change may or may not be needed to support other hardware-specific libraries.
Feedback on alternative hardware configurations is welcome.

• CPU Only:

  pip install "torch>=2.7.1" "safetensors>=0.6.2" "timm>=1.0.22" "transformers>=5.10.0" "einops>=0.8.0"

• NVIDIA GPU (CUDA):

  pip install "torch>=2.7.1" "safetensors>=0.6.2" "timm>=1.0.22" "transformers>=5.10.0" "einops>=0.8.0" --index-url https://download.pytorch.org/whl/cu128 --extra-index-url https://pypi.org/simple

NOTE: If you have a Maxwell (eg: GTX 9xx), Pascal (GTX 10xx/Tesla P100/P40) or Volta (V100) GPU (or older), then you MUST switch out cu128 in the install command above to cu126 or cu124.
cu128 dropped support for sm_50, sm_60 and sm_70. Otherwise your GPU should support cu128 and you may even increase value to cu130 or cu132 - if your drivers are up to date (I don't know about any practical differences)

Note: Some models, such as JTP-3 / Hydra 3.5 or animetimm's dbv4 ConvNeXt v2 Huge, are not available in ONNX format.

• CPU Only:

  pip install "onnxruntime>=1.17.3"

• NVIDIA GPU:

  pip install "onnxruntime-gpu>=1.17.3"

On Linux you may need to install CUDA and cuDNN manually through your package manager or whatever the correct method is for your distro.

You can update HyVis by using the commands below or use the update.sh script (Linux/macOS) or update.bat (Windows) in the repository root.

cd HyVis
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate.bat      # Windows CMD
# .venv\Scripts\Activate.ps1      # Windows PowerShell

git pull
pip install .

You can launch the desktop configurator to visually configure settings, inspect candidate files, and launch tasks. While the venv is activated:

# Without TOML
hyvis-gui

# With TOML
hyvis-gui path/to/config.toml

Two things you may want to know about:

• Tooltips are on practically every element and show on mouse hover
• You can interact with the issue items in the issues panel though left-clicking, which will take you to the erroneous page/widget
  • Right-clicking will allow you to copy the issue message

You can run the HyVis CLI utility through hyvis and by passing the path to your configured TOML file:

hyvis path/to/config.toml

HyVis uses TOML configuration files to define your Hydrus API connection, search rules, models and output filtering.

To get started you can create a copy of one of the examples in the config_examples/ directory and modify the copy to your liking.

For a comprehensive list of all configuration options, see the Configuration Guide. You may want to have this open while checking the example configs and editing/creating your own.

Available example configs:

• config.example.toml - Example config file with pretty much all available options + some comments. Reading the configuration guide over the comments is preferred though

• tagging_example.toml - Generic example config for general tagging of files using a model with basic default settings - likely a good starting point for most users

• dan_rating_only.toml - Example config that utilizes output filter options to only send the rating tag with the highest confidence score

• tagging_multi_model.toml - A more advanced example config that uses 2 models (one outputting Danbooru tags, the other E621 tags) to tag files and puts each model's output in separate tag services

Please see SUPPORTED_MODELS.md

• -h, --help Show the help message and all available CLI flags.
• -y, --yes Skip all interactive confirmation prompts.
• -f, --force Ignore the local database cache and re-process all matching files.
• --infer-only Run model inference and save results to the database cache, but do not send any tags to Hydrus.
• --no-preview Skip any configured page previews.
• --push-only Skip file queries and inference; immediately push any pending tags sitting in the local database queue to Hydrus.
• --clear-cache Clear the raw prediction cache from the database and run VACUUM to reclaim disk space.
• --no-wait Do not wait for Hydrus if it is offline/unreachable; fail fast instead.
• --api-url / --api-key Override the connection parameters specified in your TOML config. Useful for running the same config against multiple Hydrus clients.
• --extra-hash-file PATH For compatibility with wd-e621-hydrus-tagger Process a text file containing one SHA256 hash per line.