LLM-Eval-Guard

A CI/CD quality gate for LLM and RAG applications — scores outputs against quality, schema, and security metrics, and fails a pull request when thresholds aren't met.

Status: feature-complete for v0.1.0 (pre-release). Charter: VISION.md · roadmap: plan.md.

Why

A bad prompt edit, a broken retrieval step or a regressed output schema merges silently, because nothing fails CI. LLM-Eval-Guard is that missing gate: pytest --cov discipline for model outputs.

It's a gating and reporting layer on top of DeepEval, not a replacement. What it adds:

• One Metric interface over engine scores — metrics/
• $0 local judge by default (Ollama); OpenAI/Anthropic only as bring-your-own-key
• Judge calibration against human labels — docs/judge-calibration.md
• Schema/contract testing, strict or lenient — schema/
• Prompt-drift snapshots for Jinja2 templates — prompts/
• Red-team suite: prompt injection, jailbreak, PII, toxicity — security/
• CI gating + reporting: leg run exit code, job-summary report — ci.yml
• Test strategy: risk → check, and what's left out on purpose — docs/test-strategy.md

Quickstart

pip install "llm-eval-guard[deepeval]"
ollama pull qwen2.5:7b          # local, $0-cost calibrated judge

leg init                        # scaffolds leg.config.yaml + a sample dataset + example test
leg run                         # full suite, scored by the local Ollama judge
leg run --fast                  # schema/prompt-drift/rule checks only, no network call

From Python, or inside a pytest test via the judge_llm fixture:

from llm_eval_guard.core import EvalCase
from llm_eval_guard.metrics.deepeval_adapter import faithfulness_metric

case = EvalCase(
    input="What's the storage limit on the Free plan?",
    actual_output="The Free plan includes 5GB of storage.",
    retrieval_context=["Free plan limits: 5GB total storage, 2GB max file size per upload."],
)
result = faithfulness_metric(threshold=0.8).evaluate(case)  # pass model=judge_llm in pytest
print(result.score, result.passed, result.reason)

Full pytest pattern: tests/integration/test_faithfulness.py. A paid judge is opt-in: pass any DeepEval model, e.g. model=OpenAIModel(model="gpt-4o-mini").

Configuration

leg.config.yaml at the project root drives every leg run:

suites:
  quality:
    dataset: datasets/golden/sample_rag_qa.jsonl
    metrics:
      - name: faithfulness
        threshold: 0.6        # calibrated judge cutoff
judge:
  model: qwen2.5:7b           # calibrated judge
judge_profiles:
  ci:
    model: qwen2.5:0.5b       # fast, uncalibrated: `leg run --judge ci`

• Every key: docs/architecture.md
• Why these thresholds: docs/thresholds.md
• Custom metric, schema or prompt source: docs/architecture.md
• New red-team entry: datasets/redteam/README.md

What a CI run looks like

leg run --report-dir reports/ writes report.md into the GitHub Actions job summary:

# LLM-Eval-Guard Report

**✅ PASS** — 12/12 cases passed (100%)

## Per-metric summary

- **quality / faithfulness** — 6/6 passed (100%), avg score 0.95
- **security / compliance** — 6/6 passed (100%), avg score 1.00

Security failures get their own section, sorted by severity — see docs/security.md.

A caught regression

The gate also runs against a real (tiny) RAG app, examples/demo_rag. PR #2 changes TOP_K = 3 → 1 ("one chunk is enough") and CI goes red (run).

• CI gate (context_recall): 12/12 → 8/12, exit 1 — every multi-hop question loses a fact. Deterministic, so no judge noise.
• Calibrated judge: 20/24 → 19/24. "The context doesn't say" is faithful, so judge metrics barely move — why the gate checks retrieval directly.
• PR #2 stays open, never merged, as evidence. Red-team results for the same app: docs/security.md.

Development

make install && poetry run pre-commit install && make test

• Prerequisites and workflow: CONTRIBUTING.md
• Judge trust: the default judge agrees with human labels 82% (relevancy) and 71% (faithfulness) held-out — read docs/judge-calibration.md before trusting scores

Docs

• architecture — data flow, config keys, extension points
• thresholds — every cutoff and why
• datasets — golden dataset schema and labeling rules
• prompt-testing — prompt contracts and drift snapshots
• security — red-team metrics and findings
• ci-setup — CI jobs, branch protection, release
• judge-calibration — how far to trust the judge
• test-strategy — risks, checks, and gaps