Skip to main content

llm-layered-defense

DOI

A small, dependency-light framework and experiment harness for the paper "A Layered Defense Framework for Mitigating Hallucinations in Large Language Models" (Govindarajan, 2026). It implements the four security layers as composable pieces and runs the cumulative ablation of Table 5 against any OpenAI-compatible chat endpoint.

Layer Module What it does
L1 verifier layered_defense.pipeline.DefensePipeline.verify LLM-as-a-Judge extracts atomic claims, labels them supported / contradicted / unverifiable and rewrites the draft.
L2 metadata-filtered RAG layered_defense.corpus Lexical top-k retrieval over a document store; a MetadataPolicy (domain, recency, trust score) is applied as a hard filter before re-ranking. A poisoned index with 5 % adversarial documents is supported for the context-poisoning experiment.
L3 prompt engineering layered_defense.prompts System instruction, 3-shot grounded examples and negative constraints (context-aware: closed-book prompts get anti-fabrication constraints instead of a forced refusal).
L4 alignment layered_defense.prompts.ALIGNMENT_PERSONAS + --base-model/--aligned-model Approximated on hosted models by persona + temperature, or faithfully by pointing each level at a different checkpoint.

The harness never simulates model output. A failed provider call is recorded on the run with an error field and excluded from every statistic. An offline mock provider exists for tests and dry runs; its results are tagged and refused by the LaTeX reporter unless --allow-mock is passed.

Use it inside your agent

from layered_defense import LayeredDefense, GuardPolicy

# any LLM: "openrouter:google/gemini-2.5-flash", "openai:gpt-4o", "custom:model"
# (with base_url), a callable fn(messages) -> str, OpenAILLM(client, model),
# AnthropicLLM(client, model) or LangChainLLM(chat_model)
guard = LayeredDefense("openrouter:google/gemini-2.5-flash",
                       verifier="openrouter:anthropic/claude-sonnet-4.5",
                       system_prompt="You are the support assistant for ACME.")

out = guard.answer("Is this customer eligible for a refund?",
                   context=[kb_passage, crm_ticket])   # tool outputs as evidence
out.text      # grounded answer (rewritten / refused / flagged per policy)
out.action    # accepted | rewritten | refused | flagged | unverified
out.claims    # [Claim(text, judgment, evidence_ids), ...]

await guard.aanswer(...)                 # async
for ev in guard.stream(...): ...         # token events, then verify/decision/answer
guard.verify(question, answer, context)  # audit an answer produced elsewhere

GuardPolicy(on_contradicted="refuse", on_unverifiable="flag", allow_parametric=True, verify_when=lambda q, docs: is_high_risk(q)) controls what happens per claim class and when the verifier runs. Pass a retriever= (any retrieve(query, k=, domain=) object or fn(query, k)), metadata_policy= for Layer 2 filtering, and on_event= for tracing. Tool-calling adapters live in layered_defense.adapters (OPENAI_VERIFY_TOOL, ANTHROPIC_VERIFY_TOOL, make_verify_tool(guard), as_runnable(guard) for LangChain/LangGraph).

Install

pip install llm-layered-defense

Requires Python 3.10+. A bundled synthetic corpus (120 documents) and QA set (500 questions, six domains) ship with the package, so no download is needed.

Quick start

# offline dry run with the deterministic mock provider
layered-defense demo --n-per-domain 2 --ablation extended

# live run through OpenRouter
export OPENROUTER_API_KEY=...
layered-defense run --provider openrouter --model google/gemini-2.5-flash \
    --verifier-model anthropic/claude-sonnet-4.5 --n-per-domain 5 --out results.json

# any OpenAI-compatible server (vLLM, Ollama, LM Studio, a local proxy, ...)
layered-defense run --provider custom --base-url http://127.0.0.1:8787/v1 \
    --api-key "$LLM_API_KEY" --model my-model --pricing my-model=1:5

# render LaTeX tables (+ data-driven observations) or a Markdown summary
layered-defense report results.json --out results_tables.tex
layered-defense report results.json --format markdown

Providers: openrouter, openai, gemini (OpenAI-compatible endpoint), groq, ollama, local ($LOCAL_LLM_BASE_URL / $LOCAL_LLM_API_KEY), custom (--base-url), mock. A .env file in the working directory is loaded automatically.

Ablations

--ablation table5 runs the five cumulative rows of the paper. --ablation extended adds two Layer-2 controls between rows 1 and 2, vanilla RAG on a clean index and vanilla RAG on the poisoned index, so the context-poisoning effect that motivates metadata filtering is measured rather than assumed. --attack-strength (0..1) sets how retrieval-optimised the adversarial documents are; at 1 they tie with the best clean document.

What a results file contains

provenance (models, seed, policy, pricing, timestamps), summary (per row: n, errors, hallucination rate with a 95 % Wilson interval, refusal rate, verifier-correction rate, share of prompts that contained an adversarial document, mean latency, cost per 1k queries, mean helpfulness) and raw_runs (every prompt's context ids, draft, final answer, verifier claims, judge verdict and rationale).

Library use

from layered_defense import DefensePipeline, DocCorpus, LayerConfig, MetadataPolicy, make_provider

corpus = DocCorpus.from_csv("documents_corpus.csv").inject_adversarial()
llm = make_provider("openrouter", model="google/gemini-2.5-flash")
pipe = DefensePipeline(corpus, llm, policy=MetadataPolicy(min_quality=0.7, recency_years=5))
full_stack = LayerConfig("full", rag="filtered", prompt="full", alignment="aligned", verifier=True)
result = pipe.answer("What is inflation?", "Finance", full_stack)
print(result.final_answer, result.corrected, result.latency_s, result.cost_usd)

Honest scope

  • Layer 4 cannot fine-tune anything. With a single hosted model the "base" and "aligned" rows differ only by system prompt and temperature. Use --base-model / --aligned-model with real base vs. instruct checkpoints for a faithful L4 comparison.
  • Hallucination is judged by an LLM, not by human annotators. Use a judge at least as strong as the generator and a different model where possible.
  • Retrieval is lexical (token overlap with stop-word removal), not embedding based. Swap DocCorpus.retrieve for your own retriever if needed.
  • Small samples give wide intervals. The reporter prints the Wilson interval and refuses to claim a trend the data do not show.

Paper

Preprint: Govindarajan, R. (2026). A Layered Defense Framework for Mitigating Hallucinations in Large Language Models. Zenodo. https://doi.org/10.5281/zenodo.23768596

paper.tex includes results_tables.tex, which layered-defense report generates from results.json. Build with latexmk -pdf paper.tex.

Development

uv venv && uv pip install -e ".[dev]"
pytest
ruff check src tests
python -m build && twine check dist/*

License

MIT. The bundled corpus and QA set are synthetic (CC0-style educational use).

Metadata

Release files for llm-layered-defense 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llm-layered-defense 0.2.0
File Size Uploaded Provenance Actions
llm_layered_defense-0.2.0.tar.gz 70.1 kB Without provenance Details for llm_layered_defense-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llm-layered-defense 0.2.0
File Interpreter ABI Platform Actions
llm_layered_defense-0.2.0-py3-none-any.whl Python 3 none any Details for llm_layered_defense-0.2.0-py3-none-any.whl

Total release size: 142.4 kB

Release files / llm_layered_defense-0.2.0.tar.gz

Download URL llm_layered_defense-0.2.0.tar.gz
Size 70.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e8bc754b35ef44a8575322fa0a51da95e8099d2308512d99ddb61f57dee5415f
BLAKE2b-256 checksum
How to use checksums
58deabc74ad65af3530daa2f3d6ed122f62432c615bf082c29e628110f2ded04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Release files / llm_layered_defense-0.2.0-py3-none-any.whl

Download URL llm_layered_defense-0.2.0-py3-none-any.whl
Size 72.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a059708acd7d67aa1888c7d0a13b11f95bd58b4eabfd6e03e823d42c9303929
BLAKE2b-256 checksum
How to use checksums
68bda1f097e724d45392b6b50bb8ffb2cd8630b3e6a8675b8cd1fec75f226f58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Security for llm-layered-defense 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page