HaloGuard

A local-first hallucination firewall for LLM applications. HaloGuard sits between an LLM and the application consuming its output, scoring every response for hallucination risk before it reaches a user. Everything runs on the caller's machine -- no prompt, response, or context ever leaves the device.

Scoring modes

• Entailment mode (RAG-style): scores whether the response is supported by supplied source context, using an NLI cross-encoder (DeBERTa-v3-small, ONNX, quantized).
• Consistency mode (no context): scores whether the response is internally consistent, cross-checking its own claims with the same NLI model.

Mode is selected automatically by input shape (auto), or set explicitly.

Install

pip install haloguard

One-time model setup (builds the ONNX artifact into your local cache):

pip install "haloguard[export]"
python scripts/export_onnx.py

SDK quickstart

from haloguard import Firewall

fw = Firewall()  # threshold=0.7, block_threshold=0.9, mode="auto"

# Entailment mode: context supplied
result = fw.check(
    prompt="Where is the Eiffel Tower?",
    response="The Eiffel Tower is in Paris.",
    context="The Eiffel Tower is located in Paris and was completed in 1889.",
)
print(result.verdict, result.score, result.reason)

# Consistency mode: no context
result = fw.check(
    prompt="When is the meeting?",
    response="The meeting is on Tuesday. The meeting is on Friday.",
)

Every check returns a FirewallResult. Also available: acheck() (async), check_batch() (many items over one loaded session).

CLI

haloguard check --prompt "..." --response "..."                 # consistency mode
haloguard check --prompt "..." --response "..." --context FILE  # entailment mode
haloguard check ... --json                                      # machine-readable
haloguard version

Exit codes: 0 PASS / 1 FLAG / 4 BLOCK / 3 internal error (incl. UNKNOWN).

Framework hooks

# LangChain:  pip install "haloguard[langchain]"
from haloguard.integrations.langchain_handler import HaloGuardCallbackHandler
handler = HaloGuardCallbackHandler(context_provider=lambda _text: retrieved_context)

# LlamaIndex-style query responses (duck-typed, no hard dependency)
from haloguard.integrations.llamaindex_handler import HaloGuardQueryHook
result = HaloGuardQueryHook().check_response(query_response)

# Any client SDK: adapt to generate(prompt) -> str, then score
from haloguard.integrations.raw_wrappers import guarded_call, openai_generate
response, result = guarded_call(openai_generate(client), prompt, context=context)

Verdicts

• score -- 0.0-1.0 hallucination risk (higher = more likely hallucinated)
• verdict -- PASS (risk < threshold), FLAG (threshold <= risk < block_threshold), BLOCK (risk >= block_threshold), UNKNOWN (scoring failed, fail-open)
• reason, mode_used, latency_ms

UNKNOWN is the fail-open verdict returned when scoring itself fails and strict_mode=False (the default). Set strict_mode=True to fail closed instead.

Honest limitations

HaloGuard is defense-in-depth, not a guarantee. An adversarially crafted response can read as entailed/consistent to any NLI model while still being false. The measured false-negative rate on the golden benchmark is the real accuracy statement; treat HaloGuard as one layer in a safety stack, not the only one.

Development

pip install -e ".[dev]"
pytest tests -v        # unit tests always; integration tests need model artifacts
ruff check src tests scripts
mypy

Integration tests run real inference against tests/golden_dataset/labeled_pairs.jsonl and are skipped automatically when model artifacts are absent.

License

MIT