HyPE-VLM/HyPE-detector

HyPE + HyPS — Hyperbolic Prompt Detection and Sanitization

This repository hosts the HyPE harmful-prompt detection checkpoint and usage examples for HyPE (detection) and HyPS (sanitization), introduced in the ICLR 2026 paper Harnessing Hyperbolic Geometry for Harmful Prompt Detection and Sanitization.

• Paper: https://arxiv.org/abs/2604.06285
• Official code and training details: https://github.com/HyPE-VLM/Hyperbolic-Prompt-Detection-and-Sanitization
• Project website: https://hype-vlm.github.io/

Overview

HyPE detects harmful prompts by tokenizing text with CLIP, obtaining hyperbolic text embeddings using the external HySAC encoder, and evaluating the embeddings with a learned Lorentz Hyperbolic SVDD boundary.

HyPS is the accompanying prompt sanitization pipeline. For prompts classified as harmful, it identifies influential words and modifies them according to a selected sanitization strategy. Benign prompts are returned unchanged.

What is actually hosted here? The .pth file contains the trained HyPE detection head. HyPS is implemented in the hype-hyps Python package and uses HyPE; it does not require a second sanitization checkpoint in this repository.

Quick start

Install the official package (Python 3.10+ recommended):

pip install hype-hyps==0.1.1

1. HyPE — Harmful-prompt detection

from hype import inference

prediction = inference("Several birds flying together over a frozen lake.")
print("Benign" if prediction == 1 else "Harmful")

Label mapping: 1 = benign, 0 = harmful, as used in the released implementation. One equation in the paper uses a different convention; use the mapping shown here when working with the released code.

2. HyPS — Prompt sanitization (default: thesaurus_llm)

from hype.pipeline import sanitize

result = sanitize("Your prompt to analyze")  # default: method="thesaurus_llm", k=5
print(result.sanitized_prompt)

HyPS runs only when HyPE classifies the input as harmful. If it is classified as benign, sanitized_prompt is the original prompt.

The supported strategies are:

• thesaurus_llm (default): replace influential harmful words with thesaurus antonyms when available; otherwise use an LLM-based fallback rewrite.
• thesaurus_word_removal: use antonyms when available; otherwise remove the words.
• word_removal: remove influential harmful words without thesaurus or LLM lookup.

The default is k=5, controlling how many top influential words HyPS considers for modification. You can override the defaults, for example: sanitize(prompt, method="word_removal", k=3).

Requirements for the default sanitization method: The thesaurus-based methods need a Merriam-Webster Thesaurus API key. Set MERRIAM_WEBSTER_API_KEY in your environment before running Python:

Windows Command Prompt:

set MERRIAM_WEBSTER_API_KEY=YOUR_KEY_HERE

Linux/macOS:

export MERRIAM_WEBSTER_API_KEY="YOUR_KEY_HERE"

The LLM fallback may require additional model resources and configuration. See the official implementation for setup details. Do not put API keys in public scripts or repositories.

Full inference examples

The short examples above use the installed hype-hyps package. More complete scripts are included in this repository:

• HyPE detection with the Hub checkpoint (examples/detection.py): downloads the checkpoint hosted here and runs it using the original research architecture and HySAC. Follow the script's instructions and install the research-code dependencies.
• HyPS sanitization (examples/sanitize_prompt.py): command-line example for choosing the sanitization method and k.

Checkpoint distinction: In hype-hyps==0.1.1, inference() and the sanitize() pipeline use the detector weights bundled in the PyPI package, not the checkpoint downloaded from this Hub repository. The examples/detection.py script explicitly downloads and loads this Hub checkpoint. The current examples/sanitize_prompt.py uses the packaged weights. Both follow the released HyPE architecture, but these are different loading paths.

To download this repository's checkpoint directly:

from huggingface_hub import hf_hub_download

checkpoint_path = hf_hub_download(
    repo_id="HyPE-VLM/HyPE-detector",
    filename="best_hyperbolic_svdd_model.pth",
)
print(checkpoint_path)

The detector uses a custom PyTorch architecture, not transformers.AutoModelForSequenceClassification. The text-classification tag is for discoverability and does not imply an available hosted inference endpoint.

Repository files

• best_hyperbolic_svdd_model.pth — trained HyPE SVDD detector checkpoint.
• hype_config.json — architecture, dependencies, and label-mapping metadata; not a Transformers AutoConfig.
• examples/detection.py — example loading the Hugging Face checkpoint for detection.
• examples/sanitize_prompt.py — example of the HyPS sanitization pipeline.
• LICENSE.txt — project licensing notice.

Evaluation

See the paper and GitHub repository for the original benchmark definitions, splits, and performance metrics. This Hub release has not been independently re-evaluated.

Limitations

• The reference implementation focuses on harmful prompts in vision-language applications; it is not a general-purpose prompt-injection detector.
• English-language text is the primary research setting.
• Input text is truncated to 77 CLIP tokens.
• Both detection and sanitization can fail under adversarial prompts or distribution shift. Sanitization does not guarantee safe downstream output.
• The package's online word-attribution path defaults to an empty baseline prompt; the paper's experiments used paired benign baselines. This can affect comparisons.
• Consider human oversight and layered defenses for high-stakes moderation.

Licensing

The upstream project is released under CC BY-NC-ND 4.0. The external HySAC model is subject to its own license; consult its model card. Users are responsible for complying with all applicable noncommercial, no-derivatives, and third-party terms.

Citation

@inproceedings{maljkovic2026harnessing,
  title={Harnessing Hyperbolic Geometry for Harmful Prompt Detection and Sanitization},
  author={Igor Maljkovic and Maria Rosaria Briglia and Iacopo Masi and Antonio Emanuele Cin{\`a} and Fabio Roli},
  booktitle={The Fourteenth International Conference on Learning Representations},
  year={2026},
  url={https://openreview.net/forum?id=G8HnUTlMpt}
}