contexttrace 0.3.0__tar.gz → 0.5.0__tar.gz

{contexttrace-0.3.0 → contexttrace-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: contexttrace
-Version: 0.3.0
+Version: 0.5.0
 Summary: Local-first SDK and CLI for RAG and agent reliability tracing, citation checks, and failure diagnosis.
 Author: ContextTrace contributors
 License: MIT
@@ -147,6 +147,12 @@ contexttrace verify trace.json --fail-on unsupported --fail-on citation_mismatch
 contexttrace verify-benchmark --mode semantic
 contexttrace verify-benchmark --mode semantic --report
 contexttrace verify-benchmark --case-set external --mode semantic --report
+contexttrace compare baseline.json current.json
+contexttrace compare baseline.json current.json --report
+contexttrace compare baseline.json current.json --fail-on new_failure
+contexttrace audit trace.json --corpus docs/
+contexttrace audit trace.json --corpus docs/ --report
+contexttrace audit trace.json --corpus docs/ --fail-on retrieval_miss
 ```
 
 Input requires `query`, `answer`, and `contexts` with `id` and `text`. Optional `citations` are checked to catch cited sources that do not actually support the matched claim.
@@ -159,7 +165,11 @@ Verification output includes evidence span offsets, stable span hashes, multiple
 
 ContextTrace verifies whether each generated claim is actually supported by retrieved evidence. Instead of only showing a trace or a score, it tells you where the evidence chain broke: unsupported claim, citation mismatch, retrieval miss, answer overreach, conflicting context, or should-have-abstained.
 
-The v0.3.0 verifier uses local lexical heuristics by default. Claim extraction is rule-based, contradiction detection is conservative, and semantic or LLM-judge support can be added later.
+Use `contexttrace compare baseline.json current.json` to diff two portable traces or saved `verify --json` outputs. It reports support-rate deltas, new unsupported claims, citation regressions, should-abstain flips, and new root causes, with `--fail-on` gates for CI.
+
+Use `contexttrace audit trace.json --corpus docs/` to diagnose whether an unsupported claim failed because retrieval missed evidence, chunking omitted the supporting span, the corpus lacks coverage, or generation overclaimed.
+
+The v0.5.0 verifier uses local lexical heuristics by default. Claim extraction is rule-based, contradiction detection is conservative, and semantic or LLM-judge support can be added later.
 
 ## What It Catches
 

{contexttrace-0.3.0 → contexttrace-0.5.0}/README.md

@@ -90,6 +90,12 @@ contexttrace verify trace.json --fail-on unsupported --fail-on citation_mismatch
 contexttrace verify-benchmark --mode semantic
 contexttrace verify-benchmark --mode semantic --report
 contexttrace verify-benchmark --case-set external --mode semantic --report
+contexttrace compare baseline.json current.json
+contexttrace compare baseline.json current.json --report
+contexttrace compare baseline.json current.json --fail-on new_failure
+contexttrace audit trace.json --corpus docs/
+contexttrace audit trace.json --corpus docs/ --report
+contexttrace audit trace.json --corpus docs/ --fail-on retrieval_miss
 ```
 
 Input requires `query`, `answer`, and `contexts` with `id` and `text`. Optional `citations` are checked to catch cited sources that do not actually support the matched claim.
@@ -102,7 +108,11 @@ Verification output includes evidence span offsets, stable span hashes, multiple
 
 ContextTrace verifies whether each generated claim is actually supported by retrieved evidence. Instead of only showing a trace or a score, it tells you where the evidence chain broke: unsupported claim, citation mismatch, retrieval miss, answer overreach, conflicting context, or should-have-abstained.
 
-The v0.3.0 verifier uses local lexical heuristics by default. Claim extraction is rule-based, contradiction detection is conservative, and semantic or LLM-judge support can be added later.
+Use `contexttrace compare baseline.json current.json` to diff two portable traces or saved `verify --json` outputs. It reports support-rate deltas, new unsupported claims, citation regressions, should-abstain flips, and new root causes, with `--fail-on` gates for CI.
+
+Use `contexttrace audit trace.json --corpus docs/` to diagnose whether an unsupported claim failed because retrieval missed evidence, chunking omitted the supporting span, the corpus lacks coverage, or generation overclaimed.
+
+The v0.5.0 verifier uses local lexical heuristics by default. Claim extraction is rule-based, contradiction detection is conservative, and semantic or LLM-judge support can be added later.
 
 ## What It Catches
 

contexttrace-0.5.0/contexttrace/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

{contexttrace-0.3.0 → contexttrace-0.5.0}/contexttrace/cli.py

@@ -24,12 +24,18 @@ from contexttrace.storage import SQLiteTraceStore
 from contexttrace.thresholds import parse_thresholds, threshold_failures
 from contexttrace.verify import (
     VerificationInputError,
+    audit_failures,
+    audit_trace,
+    compare_failures,
+    compare_trace_files,
     list_verify_demos,
     load_trace_file,
     load_verify_demo,
     verify_trace,
 )
 from contexttrace.verify.benchmark import run_verify_benchmark, write_verify_benchmark_report
+from contexttrace.verify.audit_report import AuditReportGenerator
+from contexttrace.verify.compare_report import CompareReportGenerator
 from contexttrace.verify.report import VerifyReportGenerator
 from contexttrace.viewer import serve_viewer
 
@@ -340,6 +346,124 @@ def verify_benchmark_command(mode: str, case_set: str, json_output: bool, report
     return 0
 
 
+@cli.command("compare")
+@click.argument("baseline_json")
+@click.argument("current_json")
+@click.option("--json", "json_output", is_flag=True, help="Print the full comparison result as JSON.")
+@click.option("--report", is_flag=True, help="Generate a local HTML regression report.")
+@click.option("--out", default=None, help="HTML report path. Implies --report when provided.")
+@click.option("--mode", default="lexical", show_default=True, type=click.Choice(["lexical", "semantic"]), help="Evidence scoring mode for raw trace inputs.")
+@click.option("--fail-on", multiple=True, help="Fail on new_failure, new_unsupported, new_citation_mismatch, should_abstain_flip, support_rate_drop, new_root_cause, or any_regression.")
+def compare_command(
+    baseline_json: str,
+    current_json: str,
+    json_output: bool,
+    report: bool,
+    out: Optional[str],
+    mode: str,
+    fail_on: tuple[str, ...],
+) -> int:
+    """Compare two portable RAG traces or verification JSON outputs."""
+
+    try:
+        result = compare_trace_files(baseline_json, current_json, mode=mode)
+    except VerificationInputError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    written_report = None
+    if report or out:
+        default_name = "%s_vs_%s_compare.html" % (Path(baseline_json).stem, Path(current_json).stem)
+        output_path = out or str(Path(".contexttrace") / "reports" / default_name)
+        written_report = CompareReportGenerator().generate(result, path=output_path)
+
+    fail_messages = compare_failures(result, fail_on)
+    if json_output:
+        if written_report:
+            click.echo("Report: %s" % written_report, err=True)
+        click.echo(json.dumps(result, indent=2))
+        for message in fail_messages:
+            click.echo("Comparison failed: %s" % message, err=True)
+        return 1 if fail_messages else 0
+
+    summary = result["summary"]
+    click.echo("Regression: %s" % str(summary["regression"]).lower())
+    click.echo("Support rate: %.3f -> %.3f (%+.3f)" % (
+        float(summary.get("support_rate_before") or 0.0),
+        float(summary.get("support_rate_after") or 0.0),
+        float(summary.get("support_rate_delta") or 0.0),
+    ))
+    click.echo("Unsupported claim rate delta: %+.3f" % float(summary.get("unsupported_claim_rate_delta") or 0.0))
+    click.echo("Citation mismatch delta: %+d" % int(summary.get("citation_mismatch_delta") or 0))
+    click.echo("New failures: %s" % summary["new_failures"])
+    click.echo("Resolved failures: %s" % summary["resolved_failures"])
+    click.echo("Added claims: %s" % summary["added_claims"])
+    click.echo("Removed claims: %s" % summary["removed_claims"])
+    click.echo("Changed claims: %s" % summary["changed_claims"])
+    click.echo("New root causes: %s" % (", ".join(summary.get("new_root_causes") or []) or "none"))
+    if written_report:
+        click.echo("Report: %s" % written_report)
+    for message in fail_messages:
+        click.echo("Comparison failed: %s" % message, err=True)
+    return 1 if fail_messages else 0
+
+
+@cli.command("audit")
+@click.argument("trace_json")
+@click.option("--corpus", "corpus_path", required=True, help="Local corpus directory or file to search for supporting evidence.")
+@click.option("--json", "json_output", is_flag=True, help="Print the full audit result as JSON.")
+@click.option("--report", is_flag=True, help="Generate a local HTML retrieval audit report.")
+@click.option("--out", default=None, help="HTML report path. Implies --report when provided.")
+@click.option("--mode", default="lexical", show_default=True, type=click.Choice(["lexical", "semantic"]), help="Evidence scoring mode.")
+@click.option("--fail-on", multiple=True, help="Fail on retrieval_miss, reranking_failure, chunking_issue, corpus_gap, answer_overreach, stale_source, insufficient_context, or any_failure.")
+def audit_command(
+    trace_json: str,
+    corpus_path: str,
+    json_output: bool,
+    report: bool,
+    out: Optional[str],
+    mode: str,
+    fail_on: tuple[str, ...],
+) -> int:
+    """Audit a verified trace against a broader local corpus."""
+
+    try:
+        trace = load_trace_file(trace_json)
+        result = audit_trace(trace, corpus_path=corpus_path, mode=mode)
+    except VerificationInputError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    written_report = None
+    if report or out:
+        default_name = "%s_audit.html" % Path(trace_json).stem
+        output_path = out or str(Path(".contexttrace") / "reports" / default_name)
+        written_report = AuditReportGenerator().generate(result, trace, path=output_path)
+
+    fail_messages = audit_failures(result, fail_on)
+    if json_output:
+        if written_report:
+            click.echo("Report: %s" % written_report, err=True)
+        click.echo(json.dumps(result, indent=2))
+        for message in fail_messages:
+            click.echo("Audit failed: %s" % message, err=True)
+        return 1 if fail_messages else 0
+
+    summary = result["summary"]
+    click.echo("Primary audit label: %s" % summary["primary_audit_label"])
+    click.echo("Claims audited: %s" % summary["total_claims"])
+    click.echo("Corpus documents: %s" % summary["corpus_documents"])
+    click.echo("Retrieval misses: %s" % summary["retrieval_miss"])
+    click.echo("Chunking issues: %s" % summary["chunking_issue"])
+    click.echo("Reranking failures: %s" % summary["reranking_failure"])
+    click.echo("Corpus gaps: %s" % summary["corpus_gap"])
+    click.echo("Answer overreach: %s" % summary["answer_overreach"])
+    click.echo("Insufficient context: %s" % summary["insufficient_context"])
+    if written_report:
+        click.echo("Report: %s" % written_report)
+    for message in fail_messages:
+        click.echo("Audit failed: %s" % message, err=True)
+    return 1 if fail_messages else 0
+
+
 def _write_verify_report(
     result: dict,
     trace: object,

{contexttrace-0.3.0 → contexttrace-0.5.0}/contexttrace/verify/__init__.py

@@ -1,4 +1,6 @@
 from contexttrace.verify.runner import verify_trace, verify_trace_file
+from contexttrace.verify.audit import audit_failures, audit_trace, audit_trace_file, load_corpus
+from contexttrace.verify.compare import compare_failures, compare_trace_files, compare_verifications
 from contexttrace.verify.schema import (
     RAGTrace,
     TraceCitation,
@@ -13,7 +15,14 @@ __all__ = [
     "TraceCitation",
     "TraceContext",
     "VerificationInputError",
+    "audit_failures",
+    "audit_trace",
+    "audit_trace_file",
+    "compare_failures",
+    "compare_trace_files",
+    "compare_verifications",
     "list_verify_demos",
+    "load_corpus",
     "load_trace_file",
     "load_verify_demo",
     "verify_trace",

contexttrace-0.5.0/contexttrace/verify/audit.py

@@ -0,0 +1,449 @@
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from contexttrace.verify.claims import Claim
+from contexttrace.verify.evidence import find_best_evidence
+from contexttrace.verify.runner import verify_trace
+from contexttrace.verify.schema import RAGTrace, TraceContext, VerificationInputError, load_trace_file
+from contexttrace.verify.verdicts import classify_claim
+
+
+NO_FAILURE = "no_failure_detected"
+RETRIEVAL_MISS = "retrieval_miss"
+RERANKING_FAILURE = "reranking_failure"
+CHUNKING_ISSUE = "chunking_issue"
+CORPUS_GAP = "corpus_gap"
+ANSWER_OVERREACH = "answer_overreach"
+STALE_SOURCE = "stale_source"
+INSUFFICIENT_CONTEXT = "insufficient_context"
+
+AUDIT_FAILURE_LABELS = {
+    RETRIEVAL_MISS,
+    RERANKING_FAILURE,
+    CHUNKING_ISSUE,
+    CORPUS_GAP,
+    ANSWER_OVERREACH,
+    STALE_SOURCE,
+    INSUFFICIENT_CONTEXT,
+}
+BAD_CITATIONS = {
+    "cited_source_missing",
+    "cited_source_does_not_support_claim",
+    "claim_supported_by_different_source",
+}
+SUPPORTED_VERDICTS = {"supported"}
+CORPUS_EXTENSIONS = {
+    ".csv",
+    ".html",
+    ".json",
+    ".jsonl",
+    ".md",
+    ".markdown",
+    ".rst",
+    ".text",
+    ".tsv",
+    ".txt",
+    ".yaml",
+    ".yml",
+}
+SKIP_DIRECTORIES = {
+    ".contexttrace",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".svn",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+MAX_FILE_BYTES = 1_000_000
+RERANKING_CUTOFF = 3
+
+
+def audit_trace_file(
+    trace_path: str | Path,
+    *,
+    corpus_path: str | Path,
+    mode: str = "lexical",
+) -> dict[str, Any]:
+    trace = load_trace_file(trace_path)
+    return audit_trace(trace, corpus_path=corpus_path, mode=mode)
+
+
+def audit_trace(
+    trace: RAGTrace,
+    *,
+    corpus_path: str | Path,
+    mode: str = "lexical",
+) -> dict[str, Any]:
+    corpus_contexts = load_corpus(corpus_path)
+    verification = verify_trace(trace, mode=mode)
+    claim_audits = [
+        _audit_claim(claim, trace, corpus_contexts, mode=mode)
+        for claim in verification.get("claims") or []
+    ]
+    summary = _summary(claim_audits, verification, corpus_contexts, mode=mode)
+    return {
+        "query": trace.query,
+        "answer": trace.answer,
+        "summary": summary,
+        "claims": claim_audits,
+        "verification": {
+            "summary": verification.get("summary") or {},
+            "abstention": verification.get("abstention") or {},
+            "diagnostics": verification.get("diagnostics") or {},
+        },
+        "corpus": {
+            "path": str(Path(corpus_path)),
+            "documents": len(corpus_contexts),
+        },
+        "metadata": dict(trace.metadata),
+    }
+
+
+def load_corpus(corpus_path: str | Path) -> list[TraceContext]:
+    root = Path(corpus_path)
+    if not root.exists():
+        raise VerificationInputError("Corpus path %s does not exist." % root)
+
+    files = [root] if root.is_file() else _corpus_files(root)
+    contexts: list[TraceContext] = []
+    for path in files:
+        text = _read_text(path)
+        if not text.strip():
+            continue
+        context_id = _context_id(path, root)
+        contexts.append(
+            TraceContext(
+                id=context_id,
+                text=text,
+                metadata={
+                    "path": str(path),
+                    "source": context_id,
+                    "size_bytes": path.stat().st_size,
+                    "kind": "corpus_document",
+                },
+            )
+        )
+
+    if not contexts:
+        raise VerificationInputError("Corpus path %s did not contain readable text documents." % root)
+    return contexts
+
+
+def audit_failures(result: dict[str, Any], fail_on: tuple[str, ...]) -> list[str]:
+    if not fail_on:
+        return []
+    summary = result.get("summary") or {}
+    messages = []
+    for raw_rule in fail_on:
+        rule = raw_rule.strip().lower().replace("-", "_")
+        if rule == "any_failure" and bool(summary.get("has_audit_failures")):
+            messages.append("audit failure detected")
+        elif rule == "retrieval_miss" and int(summary.get(RETRIEVAL_MISS) or 0) > 0:
+            messages.append("retrieval miss detected")
+        elif rule == "reranking_failure" and int(summary.get(RERANKING_FAILURE) or 0) > 0:
+            messages.append("reranking failure detected")
+        elif rule == "chunking_issue" and int(summary.get(CHUNKING_ISSUE) or 0) > 0:
+            messages.append("chunking issue detected")
+        elif rule == "corpus_gap" and int(summary.get(CORPUS_GAP) or 0) > 0:
+            messages.append("corpus gap detected")
+        elif rule == "answer_overreach" and int(summary.get(ANSWER_OVERREACH) or 0) > 0:
+            messages.append("answer overreach detected")
+        elif rule == "stale_source" and int(summary.get(STALE_SOURCE) or 0) > 0:
+            messages.append("stale source detected")
+        elif rule == "insufficient_context" and int(summary.get(INSUFFICIENT_CONTEXT) or 0) > 0:
+            messages.append("insufficient context detected")
+        elif rule not in AUDIT_FAILURE_LABELS and rule != "any_failure":
+            messages.append("unknown --fail-on rule %s" % raw_rule)
+    return messages
+
+
+def _audit_claim(
+    claim: dict[str, Any],
+    trace: RAGTrace,
+    corpus_contexts: list[TraceContext],
+    *,
+    mode: str,
+) -> dict[str, Any]:
+    claim_text = str(claim.get("claim") or "")
+    claim_id = str(claim.get("claim_id") or "")
+    corpus_match = find_best_evidence(claim_text, corpus_contexts, mode=mode)
+    corpus_verification = classify_claim(
+        Claim(id=claim_id or "claim", text=claim_text),
+        corpus_match,
+        has_contexts=bool(corpus_contexts),
+    )
+    diagnosis = _diagnose(claim, trace, corpus_match, corpus_verification)
+    return {
+        "claim_id": claim_id,
+        "claim": claim_text,
+        "audit_label": diagnosis["label"],
+        "confidence": diagnosis["confidence"],
+        "reason": diagnosis["reason"],
+        "suggested_fix": diagnosis["suggested_fix"],
+        "retrieved": {
+            "verdict": claim.get("verdict"),
+            "best_context_id": claim.get("best_context_id"),
+            "best_score": claim.get("best_score"),
+            "evidence": claim.get("evidence"),
+            "matched_terms": list(claim.get("matched_terms") or []),
+            "root_cause": (claim.get("root_cause") or {}).get("label"),
+            "citation_status": claim.get("citation_status"),
+        },
+        "corpus": {
+            "verdict": corpus_verification.verdict,
+            "best_document_id": corpus_match.context_id,
+            "best_score": corpus_match.score,
+            "evidence": corpus_match.snippet,
+            "matched_terms": list(corpus_match.matched_terms),
+            "evidence_span": corpus_match.span_dict(),
+            "supporting_spans": list(corpus_match.supporting_spans or []),
+            "required_facts": list(corpus_verification.required_facts),
+            "matched_facts": list(corpus_verification.matched_facts),
+            "missing_facts": list(corpus_verification.missing_facts),
+            "conflicting_facts": list(corpus_verification.conflicting_facts),
+        },
+    }
+
+
+def _diagnose(
+    claim: dict[str, Any],
+    trace: RAGTrace,
+    corpus_match: object,
+    corpus_verification: object,
+) -> dict[str, Any]:
+    verdict = str(claim.get("verdict") or "")
+    root_label = str((claim.get("root_cause") or {}).get("label") or NO_FAILURE)
+    citation_status = str(claim.get("citation_status") or "")
+    corpus_verdict = str(getattr(corpus_verification, "verdict", ""))
+    corpus_score = float(getattr(corpus_match, "score", 0.0) or 0.0)
+    same_source_rank = _same_source_retrieved_rank(str(getattr(corpus_match, "context_id", "") or ""), trace)
+
+    if _is_citation_only_failure(claim):
+        return _result(
+            NO_FAILURE,
+            0.92,
+            "The claim is supported by retrieved evidence; the remaining issue is citation-level, not a retrieval or corpus failure.",
+            "Fix the claim-level citation, but do not treat this as a retrieval miss.",
+        )
+
+    if not _is_failure(claim):
+        return _result(
+            NO_FAILURE,
+            0.99,
+            "The claim is already supported by the retrieved contexts.",
+            "No fix needed for this claim.",
+        )
+
+    if verdict == "contradicted" or corpus_verdict == "contradicted" or root_label in {"stale_context", "conflicting_contexts"}:
+        return _result(
+            STALE_SOURCE,
+            0.86,
+            "The claim appears to conflict with retrieved or corpus evidence.",
+            "Resolve stale or conflicting sources before allowing the answer to use this fact.",
+        )
+
+    if corpus_verdict in SUPPORTED_VERDICTS:
+        if same_source_rank is None:
+            return _result(
+                RETRIEVAL_MISS,
+                max(0.82, min(0.98, corpus_score + 0.12)),
+                "The broader corpus contains evidence for this claim, but the retrieved contexts did not include it.",
+                "Improve retrieval recall, filters, query rewriting, or top_k so this source is retrieved.",
+            )
+        if same_source_rank >= RERANKING_CUTOFF:
+            return _result(
+                RERANKING_FAILURE,
+                max(0.78, min(0.95, corpus_score + 0.08)),
+                "A related source was retrieved, but it appeared too low in the retrieved context list for reliable generation.",
+                "Add a reranker or raise high-evidence chunks from this source before generation.",
+            )
+        return _result(
+            CHUNKING_ISSUE,
+            max(0.78, min(0.95, corpus_score + 0.08)),
+            "The retrieved source appears related, but the retrieved chunk omitted the supporting span found in the corpus.",
+            "Adjust chunk boundaries, overlap, or parent-document retrieval so the answerable span is included.",
+        )
+
+    if root_label == "answer_overreach" or verdict == "partially_supported":
+        return _result(
+            ANSWER_OVERREACH,
+            0.82,
+            "The evidence supports part of the claim, but not every required fact.",
+            "Remove unsupported details or retrieve evidence that explicitly supports each detail.",
+        )
+
+    if corpus_verdict == "partially_supported":
+        return _result(
+            ANSWER_OVERREACH,
+            0.78,
+            "The corpus supports only part of the claim, so the answer likely added unsupported detail.",
+            "Split the claim and require support for every required fact before answering.",
+        )
+
+    if corpus_verdict == "unverifiable" or verdict == "unverifiable":
+        return _result(
+            INSUFFICIENT_CONTEXT,
+            0.72,
+            "The closest corpus evidence is related but too weak or ambiguous to verify the claim.",
+            "Retrieve more specific evidence or force the model to qualify/abstain.",
+        )
+
+    if citation_status in BAD_CITATIONS and corpus_score >= 0.35:
+        return _result(
+            INSUFFICIENT_CONTEXT,
+            0.7,
+            "The claim has a citation problem and the broader corpus evidence is still not strong enough.",
+            "Regenerate claim-level citations and require cited sources to cover all required facts.",
+        )
+
+    return _result(
+        CORPUS_GAP,
+        max(0.7, min(0.95, 1.0 - corpus_score)),
+        "Neither the retrieved contexts nor the broader corpus provide enough support for this claim.",
+        "Add the missing source to the corpus or make the answer abstain when the corpus lacks this fact.",
+    )
+
+
+def _summary(
+    claim_audits: list[dict[str, Any]],
+    verification: dict[str, Any],
+    corpus_contexts: list[TraceContext],
+    *,
+    mode: str,
+) -> dict[str, Any]:
+    counts = Counter(str(claim.get("audit_label") or NO_FAILURE) for claim in claim_audits)
+    labels = [NO_FAILURE] + sorted(AUDIT_FAILURE_LABELS)
+    failure_count = sum(counts[label] for label in AUDIT_FAILURE_LABELS)
+    return {
+        "mode": mode,
+        "total_claims": len(claim_audits),
+        "audited_claims": len([claim for claim in claim_audits if claim.get("audit_label") != NO_FAILURE]),
+        "corpus_documents": len(corpus_contexts),
+        "has_audit_failures": failure_count > 0,
+        "primary_audit_label": _primary_label(counts),
+        "verification_failure_type": (verification.get("summary") or {}).get("failure_type"),
+        "verification_primary_root_cause": (verification.get("summary") or {}).get("primary_root_cause"),
+        **{label: counts[label] for label in labels},
+    }
+
+
+def _primary_label(counts: Counter) -> str:
+    failures = {label: counts[label] for label in AUDIT_FAILURE_LABELS if counts[label]}
+    if not failures:
+        return NO_FAILURE
+    priority = [
+        RETRIEVAL_MISS,
+        CHUNKING_ISSUE,
+        RERANKING_FAILURE,
+        CORPUS_GAP,
+        ANSWER_OVERREACH,
+        STALE_SOURCE,
+        INSUFFICIENT_CONTEXT,
+    ]
+    return max(
+        failures,
+        key=lambda label: (
+            failures[label],
+            -priority.index(label) if label in priority else -len(priority),
+        ),
+    )
+
+
+def _is_failure(claim: dict[str, Any]) -> bool:
+    return (
+        str(claim.get("verdict") or "") not in SUPPORTED_VERDICTS
+        or str(claim.get("citation_status") or "") in BAD_CITATIONS
+        or str((claim.get("root_cause") or {}).get("label") or NO_FAILURE) != NO_FAILURE
+    )
+
+
+def _is_citation_only_failure(claim: dict[str, Any]) -> bool:
+    return (
+        str(claim.get("verdict") or "") in SUPPORTED_VERDICTS
+        and str(claim.get("citation_status") or "") in BAD_CITATIONS
+        and str((claim.get("root_cause") or {}).get("label") or NO_FAILURE)
+        in {"wrong_source_cited", "missing_cited_source", NO_FAILURE}
+    )
+
+
+def _same_source_retrieved_rank(corpus_context_id: str, trace: RAGTrace) -> int | None:
+    corpus_key = _source_key(corpus_context_id)
+    if not corpus_key:
+        return None
+    for index, context in enumerate(trace.contexts):
+        candidates = [
+            context.id,
+            context.metadata.get("source"),
+            context.metadata.get("path"),
+            context.metadata.get("file"),
+            context.metadata.get("document"),
+        ]
+        if any(_sources_match(corpus_key, _source_key(value)) for value in candidates):
+            return index
+    return None
+
+
+def _sources_match(left: str, right: str) -> bool:
+    if not left or not right:
+        return False
+    if left == right:
+        return True
+    return Path(left).name == Path(right).name
+
+
+def _source_key(value: Any) -> str:
+    text = str(value or "").strip().replace("\\", "/").lower()
+    return text.strip("./")
+
+
+def _result(label: str, confidence: float, reason: str, suggested_fix: str) -> dict[str, Any]:
+    return {
+        "label": label,
+        "confidence": round(confidence, 3),
+        "reason": reason,
+        "suggested_fix": suggested_fix,
+    }
+
+
+def _corpus_files(root: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in SKIP_DIRECTORIES for part in path.parts):
+            continue
+        if path.suffix.lower() not in CORPUS_EXTENSIONS:
+            continue
+        if path.stat().st_size > MAX_FILE_BYTES:
+            continue
+        files.append(path)
+    return sorted(files, key=lambda item: str(item).lower())
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        try:
+            return path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            return ""
+    except OSError:
+        return ""
+
+
+def _context_id(path: Path, root: Path) -> str:
+    if root.is_file():
+        return path.name
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.name