contexttrace 1.1.0__tar.gz → 1.3.0__tar.gz

contexttrace-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContextTrace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{contexttrace-1.1.0 → contexttrace-1.3.0}/MANIFEST.in

@@ -1,4 +1,5 @@
 include README.md
+include LICENSE
 include pyproject.toml
 include setup.py
 include contexttrace/py.typed

{contexttrace-1.1.0 → contexttrace-1.3.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: contexttrace
-Version: 1.1.0
+Version: 1.3.0
 Summary: Local-first evidence-chain debugger for RAG and AI agent claim grounding, citation checks, root-cause diagnosis, and regression tests.
-Author: ContextTrace contributors
+Author: Samarth Vinayaka
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/samarth1412/Context-Trace
 Project-URL: Documentation, https://github.com/samarth1412/Context-Trace/tree/main/docs
@@ -21,6 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: typing-extensions>=4.9
@@ -32,11 +33,11 @@ Provides-Extra: local
 Provides-Extra: local-ml
 Requires-Dist: sentence-transformers>=2.7; extra == "local-ml"
 Provides-Extra: nli
-Requires-Dist: torch>=2.0; extra == "nli"
-Requires-Dist: transformers>=4.41; extra == "nli"
+Requires-Dist: torch<3,>=2.0; extra == "nli"
+Requires-Dist: transformers<6,>=4.41; extra == "nli"
 Provides-Extra: nli-onnx
 Requires-Dist: onnxruntime>=1.17; extra == "nli-onnx"
-Requires-Dist: transformers>=4.41; extra == "nli-onnx"
+Requires-Dist: transformers<6,>=4.41; extra == "nli-onnx"
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.110; extra == "fastapi"
 Provides-Extra: langgraph
@@ -58,8 +59,8 @@ Requires-Dist: langgraph>=0.2; extra == "all"
 Requires-Dist: llama-index-core>=0.10; extra == "all"
 Requires-Dist: opentelemetry-api>=1.24; extra == "all"
 Requires-Dist: sentence-transformers>=2.7; extra == "all"
-Requires-Dist: torch>=2.0; extra == "all"
-Requires-Dist: transformers>=4.41; extra == "all"
+Requires-Dist: torch<3,>=2.0; extra == "all"
+Requires-Dist: transformers<6,>=4.41; extra == "all"
 Requires-Dist: onnxruntime>=1.17; extra == "all"
 Provides-Extra: test
 Requires-Dist: jsonschema>=4.22; extra == "test"
@@ -70,6 +71,7 @@ Requires-Dist: mypy>=1.10; extra == "quality"
 Requires-Dist: pip-audit>=2.7; extra == "quality"
 Requires-Dist: pytest-cov>=5.0; extra == "quality"
 Requires-Dist: ruff>=0.5; extra == "quality"
+Dynamic: license-file
 
 # ContextTrace
 
@@ -104,6 +106,12 @@ contexttrace demo --dataset refund_policy
 contexttrace report --last --open
 ```
 
+Learn the workflow through
+[six reproducible failure investigations](https://github.com/samarth1412/Context-Trace/tree/main/examples/investigations),
+then run the
+[LangChain and LlamaIndex regression gates](https://github.com/samarth1412/Context-Trace/tree/main/examples/integrations).
+The public examples use fictional data and need no model API.
+
 Default local storage:
 
 ```text
@@ -141,6 +149,63 @@ ContextTrace classifies each claim as `supported`, `partially_supported`, `unsup
 
 Important: `supported` means grounded by the selected evidence span. It does not mean independently true, current, or authoritative.
 
+### Audit evidence transformations
+
+Instrument a selector or chunker with captured source lineage, then check
+whether it dropped a linked answer, declared qualifier, condition, or value:
+
+```python
+from contexttrace import build_evidence_lineage, capture_rag_trace
+
+source = "Question: When? Answer: After approval."
+lineage = build_evidence_lineage(
+    source_unit_id="refund_qa",
+    source_text=source,
+    linked_parts=[
+        {"id": "question", "role": "question", "text": "Question: When?"},
+        {"id": "answer", "role": "answer", "text": "Answer: After approval."},
+    ],
+)
+trace = capture_rag_trace(
+    query="When?",
+    answer="After approval.",
+    contexts=[{"id": "selected", "text": "Question: When?", "metadata": lineage}],
+)
+```
+
+At a framework selection boundary, clone and bind the selected object directly:
+
+```python
+from contexttrace import (
+    bind_langchain_evidence_lineage,
+    bind_llamaindex_evidence_lineage,
+)
+
+selected_document = bind_langchain_evidence_lineage(
+    selected_document,
+    source_document=parent_document,
+    material_spans=declared_material_spans,
+)
+selected_node = bind_llamaindex_evidence_lineage(
+    selected_node,
+    source_node=parent_node,
+    material_spans=declared_material_spans,
+)
+```
+
+Both helpers preserve the original object and existing callback paths carry the
+lineage metadata into ContextTrace.
+
+```bash
+contexttrace inspect trace.json --fail-on evidence_integrity
+contexttrace repair trace.json --out repair.md
+```
+
+The audit runs locally with no model or network calls. Missing lineage stays
+unknown, and the stable claim verifier remains unchanged. See the
+[evidence-integrity contract](../../docs/evidence-integrity-v1.3.md) and
+[offline examples](../../examples/evidence_integrity/README.md).
+
 ## Diagnose An Agent Trace
 
 `diagnose` also accepts agent step traces and localizes tool/final-answer
@@ -263,6 +328,26 @@ Common root causes include `retrieval_miss`, `reranking_failure`, `chunking_issu
 
 Source metadata can include `source_authority`, `source_timestamp`, `source_version`, `canonical`, or `canonical_source`. ContextTrace uses those local fields to flag `grounded_but_stale`, `grounded_but_conflicted`, `grounded_by_low_authority_source`, or `supported_by_canonical_source`.
 
+The experimental, opt-in `hybrid_v2` verifier can also infer dated/versioned
+source relationships from observable document text when those metadata fields
+are absent. It reports the inference basis, distinguishes historical questions
+from current operational guidance, preserves unresolved source disagreement,
+and marks relevant evidence that lacks the requested fact as `unverifiable`
+instead of treating absence as proof. The default `verify_trace` path remains
+the frozen `semantic_v1_calibrated` verifier.
+
+```python
+from contexttrace.verify import verify_trace_hybrid_v2
+
+result = verify_trace_hybrid_v2(trace, mode="semantic")
+```
+
+`hybrid_v2` is an experimental API. In a frozen controlled study it caught more
+faults but produced substantially more false alarms and underperformed the stable
+default on the balanced release-gate measure. Calibrate it on your target system
+before using it as a blocking gate. Its diagnostics do not certify real-world
+truth.
+
 ## Capture Existing Systems
 
 Capture one live endpoint response:

{contexttrace-1.1.0 → contexttrace-1.3.0}/README.md

@@ -31,6 +31,12 @@ contexttrace demo --dataset refund_policy
 contexttrace report --last --open
 ```
 
+Learn the workflow through
+[six reproducible failure investigations](https://github.com/samarth1412/Context-Trace/tree/main/examples/investigations),
+then run the
+[LangChain and LlamaIndex regression gates](https://github.com/samarth1412/Context-Trace/tree/main/examples/integrations).
+The public examples use fictional data and need no model API.
+
 Default local storage:
 
 ```text
@@ -68,6 +74,63 @@ ContextTrace classifies each claim as `supported`, `partially_supported`, `unsup
 
 Important: `supported` means grounded by the selected evidence span. It does not mean independently true, current, or authoritative.
 
+### Audit evidence transformations
+
+Instrument a selector or chunker with captured source lineage, then check
+whether it dropped a linked answer, declared qualifier, condition, or value:
+
+```python
+from contexttrace import build_evidence_lineage, capture_rag_trace
+
+source = "Question: When? Answer: After approval."
+lineage = build_evidence_lineage(
+    source_unit_id="refund_qa",
+    source_text=source,
+    linked_parts=[
+        {"id": "question", "role": "question", "text": "Question: When?"},
+        {"id": "answer", "role": "answer", "text": "Answer: After approval."},
+    ],
+)
+trace = capture_rag_trace(
+    query="When?",
+    answer="After approval.",
+    contexts=[{"id": "selected", "text": "Question: When?", "metadata": lineage}],
+)
+```
+
+At a framework selection boundary, clone and bind the selected object directly:
+
+```python
+from contexttrace import (
+    bind_langchain_evidence_lineage,
+    bind_llamaindex_evidence_lineage,
+)
+
+selected_document = bind_langchain_evidence_lineage(
+    selected_document,
+    source_document=parent_document,
+    material_spans=declared_material_spans,
+)
+selected_node = bind_llamaindex_evidence_lineage(
+    selected_node,
+    source_node=parent_node,
+    material_spans=declared_material_spans,
+)
+```
+
+Both helpers preserve the original object and existing callback paths carry the
+lineage metadata into ContextTrace.
+
+```bash
+contexttrace inspect trace.json --fail-on evidence_integrity
+contexttrace repair trace.json --out repair.md
+```
+
+The audit runs locally with no model or network calls. Missing lineage stays
+unknown, and the stable claim verifier remains unchanged. See the
+[evidence-integrity contract](../../docs/evidence-integrity-v1.3.md) and
+[offline examples](../../examples/evidence_integrity/README.md).
+
 ## Diagnose An Agent Trace
 
 `diagnose` also accepts agent step traces and localizes tool/final-answer
@@ -190,6 +253,26 @@ Common root causes include `retrieval_miss`, `reranking_failure`, `chunking_issu
 
 Source metadata can include `source_authority`, `source_timestamp`, `source_version`, `canonical`, or `canonical_source`. ContextTrace uses those local fields to flag `grounded_but_stale`, `grounded_but_conflicted`, `grounded_by_low_authority_source`, or `supported_by_canonical_source`.
 
+The experimental, opt-in `hybrid_v2` verifier can also infer dated/versioned
+source relationships from observable document text when those metadata fields
+are absent. It reports the inference basis, distinguishes historical questions
+from current operational guidance, preserves unresolved source disagreement,
+and marks relevant evidence that lacks the requested fact as `unverifiable`
+instead of treating absence as proof. The default `verify_trace` path remains
+the frozen `semantic_v1_calibrated` verifier.
+
+```python
+from contexttrace.verify import verify_trace_hybrid_v2
+
+result = verify_trace_hybrid_v2(trace, mode="semantic")
+```
+
+`hybrid_v2` is an experimental API. In a frozen controlled study it caught more
+faults but produced substantially more false alarms and underperformed the stable
+default on the balanced release-gate measure. Calibrate it on your target system
+before using it as a blocking gate. Its diagnostics do not certify real-world
+truth.
+
 ## Capture Existing Systems
 
 Capture one live endpoint response:

{contexttrace-1.1.0 → contexttrace-1.3.0}/contexttrace/__init__.py

@@ -12,10 +12,17 @@ from contexttrace.errors import (
     ContextTraceHTTPError,
     ContextTraceLocalError,
 )
+from contexttrace.evidence_integrity import audit_evidence_integrity, build_evidence_lineage
 from contexttrace.integrations.fastapi import ContextTraceFastAPIMiddleware
-from contexttrace.integrations.langchain import ContextTraceCallbackHandler
+from contexttrace.integrations.langchain import (
+    ContextTraceCallbackHandler,
+    bind_langchain_evidence_lineage,
+)
 from contexttrace.integrations.langgraph import ContextTraceLangGraphTracer
-from contexttrace.integrations.llamaindex import ContextTraceLlamaIndexCallbackHandler
+from contexttrace.integrations.llamaindex import (
+    ContextTraceLlamaIndexCallbackHandler,
+    bind_llamaindex_evidence_lineage,
+)
 from contexttrace.integrations.opentelemetry import OpenTelemetryExporter, export_contexttrace_trace
 from contexttrace.privacy import PrivacyPolicy, TextCipher
 from contexttrace.reliability import ReliabilityScore, ReliabilityScorer
@@ -47,7 +54,11 @@ __all__ = [
     "capture_response_trace",
     "build_repair_plan",
     "build_regression_case",
+    "build_evidence_lineage",
+    "bind_langchain_evidence_lineage",
+    "bind_llamaindex_evidence_lineage",
     "diagnose_payload",
+    "audit_evidence_integrity",
     "diagnose_trace_file",
     "write_diagnosis_regression_test",
     "export_contexttrace_trace",

contexttrace-1.3.0/contexttrace/_version.py

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

{contexttrace-1.1.0 → contexttrace-1.3.0}/contexttrace/cli.py

@@ -17,7 +17,7 @@ from contexttrace.capture import write_rag_trace
 from contexttrace.capture_endpoint import capture_endpoint_trace, capture_response_trace
 from contexttrace.client import ContextTrace
 from contexttrace.config import ContextTraceConfig, load_config, write_default_config
-from contexttrace.demo import run_demo_dataset
+from contexttrace.demo import run_demo_dataset, run_groundedness_gap_demo
 from contexttrace.demo_data import list_demo_datasets
 from contexttrace.diagnose import (
     DiagnoseInputError,
@@ -53,7 +53,7 @@ from contexttrace.verify.benchmark import run_verify_benchmark, write_verify_ben
 from contexttrace.verify.audit_benchmark import run_audit_benchmark, write_audit_benchmark_report
 from contexttrace.verify.audit_report import AuditReportGenerator
 from contexttrace.verify.compare_report import CompareReportGenerator
-from contexttrace.verify.qa import qa_failures, qa_trace
+from contexttrace.verify.qa import QA_VERIFIERS, qa_failures, qa_trace
 from contexttrace.verify.qa_report import QAReportGenerator
 from contexttrace.verify.report import VerifyReportGenerator
 from contexttrace.verify.suite import (
@@ -70,7 +70,14 @@ from contexttrace.verify.suite import (
     write_suite_result,
 )
 from contexttrace.verify.suite_report import SuiteReportGenerator
+from contexttrace.verify.semantic_core_v2 import build_pinned_nli
+from contexttrace.verify.semantic_core_v2_1 import (
+    DETERMINISTIC_ONLY_V2_1_PROFILE,
+    SELECTIVE_V2_1_PROFILE,
+    verify_trace_v2_1,
+)
 from contexttrace.verify.trace_inspect import inspect_trace
+from contexttrace.verify.triage import render_triage_summary
 from contexttrace.viewer import serve_viewer
 
 
@@ -255,6 +262,7 @@ def report(
 @cli.command("verify")
 @click.argument("trace_json")
 @click.option("--json", "json_output", is_flag=True, help="Print the full verification result as JSON.")
+@click.option("--format", "output_format", default="text", show_default=True, type=click.Choice(["text", "json", "triage"]), help="Console output format.")
 @click.option("--report", is_flag=True, help="Generate a local HTML verification 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(JUDGE_VERIFY_MODES), help="Evidence scoring mode.")
@@ -268,6 +276,7 @@ def verify_command(
     ctx: click.Context,
     trace_json: str,
     json_output: bool,
+    output_format: str,
     report: bool,
     out: Optional[str],
     mode: str,
@@ -305,16 +314,104 @@ def verify_command(
     )
     return _print_verify_result(
         result,
-        json_output=json_output,
+        json_output=json_output or output_format == "json",
+        triage_output=output_format == "triage",
         written_report=written_report,
         fail_on=fail_on,
     )
 
 
+@cli.command("verify-v2")
+@click.argument("trace_json")
+@click.option(
+    "--profile",
+    "profile_name",
+    default="deterministic",
+    show_default=True,
+    type=click.Choice(["deterministic", "selective"]),
+    help="Use deterministic-only verification or the pinned selective NLI cascade.",
+)
+@click.option(
+    "--model-path",
+    default=None,
+    envvar="CONTEXTTRACE_NLI_MODEL_PATH",
+    help="Local pinned NLI directory; required for --profile selective.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Print the full v2 result as JSON.")
+@click.option("--output", default=None, help="Optional path for the v2 result JSON.")
+@click.option(
+    "--fail-on",
+    multiple=True,
+    type=click.Choice(["warning", "abstained", "non_green", "any_failure"]),
+    help="Return non-zero for selected result states.",
+)
+def verify_v2_command(
+    trace_json: str,
+    profile_name: str,
+    model_path: Optional[str],
+    json_output: bool,
+    output: Optional[str],
+    fail_on: tuple[str, ...],
+) -> int:
+    """Run the opt-in safety verifier without changing stable v1 behavior."""
+
+    try:
+        trace = load_trace_file(trace_json)
+        if profile_name == "selective":
+            if not model_path:
+                raise click.ClickException(
+                    "--model-path or CONTEXTTRACE_NLI_MODEL_PATH is required for the selective profile."
+                )
+            nli = build_pinned_nli(model_path)
+            profile = SELECTIVE_V2_1_PROFILE
+        else:
+            nli = None
+            profile = DETERMINISTIC_ONLY_V2_1_PROFILE
+        result = verify_trace_v2_1(trace, profile=profile, nli=nli)
+    except VerificationInputError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except (OSError, RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    rendered = json.dumps(result, indent=2, sort_keys=True) + "\n"
+    if output:
+        output_path = Path(output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+
+    if json_output:
+        click.echo(rendered, nl=False)
+    else:
+        summary = result["summary"]
+        click.echo("Profile: %s" % result["profile_id"])
+        click.echo("Claims: %s" % summary["total_claims"])
+        click.echo("Status: %s" % summary["overall_status"])
+        click.echo("Green claims: %s" % summary["green_claims"])
+        click.echo("Diagnostic abstentions: %s" % summary["diagnostic_abstentions"])
+        click.echo("NLI invocations: %s" % summary["nli_invocations"])
+        if output:
+            click.echo("Result: %s" % output)
+
+    status = str(result["summary"]["overall_status"])
+    should_fail = bool(
+        "any_failure" in fail_on and status != "green"
+        or "non_green" in fail_on and status != "green"
+        or "warning" in fail_on and status == "warning"
+        or "abstained" in fail_on and status == "abstained"
+    )
+    return 1 if should_fail else 0
+
+
 @cli.command("inspect")
 @click.argument("trace_json")
 @click.option("--json", "json_output", is_flag=True, help="Print trace inspection as JSON.")
-def inspect_command(trace_json: str, json_output: bool) -> int:
+@click.option(
+    "--fail-on",
+    multiple=True,
+    type=click.Choice(["warning", "evidence_integrity", "unknown_integrity"]),
+    help="Exit nonzero on trace warnings, observed evidence-integrity issues, or uncaptured lineage.",
+)
+def inspect_command(trace_json: str, json_output: bool, fail_on: tuple[str, ...]) -> int:
     """Inspect portable RAG trace shape before verification."""
 
     try:
@@ -325,7 +422,7 @@ def inspect_command(trace_json: str, json_output: bool) -> int:
     result = inspect_trace(trace, trace_path=trace_json)
     if json_output:
         click.echo(json.dumps(result, indent=2))
-        return 0
+        return _inspect_exit_code(result, fail_on)
 
     click.echo("Trace: %s" % trace_json)
     click.echo("Query: %s" % result["query"])
@@ -349,6 +446,21 @@ def inspect_command(trace_json: str, json_output: bool) -> int:
     if result["metadata_keys"]:
         click.echo("Metadata keys: %s" % ", ".join(result["metadata_keys"]))
 
+    integrity = result["evidence_integrity"]
+    integrity_summary = integrity["summary"]
+    click.echo(
+        "Evidence integrity: %s (%s issues, %s assessed, %s unknown)"
+        % (
+            integrity["status"],
+            integrity_summary["issue_count"],
+            integrity_summary["assessed_contexts"],
+            integrity_summary["unknown_contexts"],
+        )
+    )
+    for issue in integrity["issues"]:
+        detail = issue.get("item_role") or issue.get("observed")
+        click.echo("- %s [%s]: %s" % (issue["type"], issue["selected_context_id"], detail))
+
     warnings = result["warnings"]
     if warnings:
         click.echo("Warnings:")
@@ -358,7 +470,20 @@ def inspect_command(trace_json: str, json_output: bool) -> int:
     click.echo("Suggested next commands:")
     for command in result["suggested_next_commands"]:
         click.echo("- %s" % command)
-    return 0
+    return _inspect_exit_code(result, fail_on)
+
+
+def _inspect_exit_code(result: dict[str, object], fail_on: tuple[str, ...]) -> int:
+    integrity = result.get("evidence_integrity") or {}
+    summary = (integrity.get("summary") or {}) if isinstance(integrity, dict) else {}
+    issue_count = int(summary.get("issue_count") or 0) if isinstance(summary, dict) else 0
+    unknown_count = int(summary.get("unknown_contexts") or 0) if isinstance(summary, dict) else 0
+    should_fail = (
+        "warning" in fail_on and bool(result.get("warnings"))
+        or "evidence_integrity" in fail_on and issue_count > 0
+        or "unknown_integrity" in fail_on and unknown_count > 0
+    )
+    return 1 if should_fail else 0
 
 
 @cli.command("diagnose")
@@ -563,12 +688,14 @@ def suite_group() -> None:
 @click.argument("trace_json", nargs=-1, required=True)
 @click.option("--out", default="contexttrace-suite.json", show_default=True, help="Suite JSON file to write.")
 @click.option("--name", default=None, help="Suite name.")
+@click.option("--verifier", default="semantic_v1_calibrated", show_default=True, type=click.Choice(QA_VERIFIERS), help="Verifier saved in the suite. hybrid_v2 is experimental and opt-in.")
 @click.option("--mode", default="lexical", show_default=True, type=click.Choice(BASIC_VERIFY_MODES), help="Evidence scoring mode for baseline QA.")
 @click.option("--corpus", "corpus_path", default=None, help="Optional local corpus directory or file for baseline retrieval/corpus audit.")
 def suite_create_command(
     trace_json: tuple[str, ...],
     out: str,
     name: Optional[str],
+    verifier: str,
     mode: str,
     corpus_path: Optional[str],
 ) -> int:
@@ -578,6 +705,7 @@ def suite_create_command(
         suite = create_suite_from_trace_files(
             trace_json,
             name=name,
+            verifier=verifier,
             mode=mode,
             corpus_path=corpus_path,
         )
@@ -587,6 +715,8 @@ def suite_create_command(
 
     click.echo("Suite: %s" % written)
     click.echo("Cases: %s" % len(suite.get("cases") or []))
+    if suite.get("verifier") == "hybrid_v2":
+        click.echo("Verifier: hybrid_v2 (experimental; retained for add and run)")
     click.echo("Policy: saved cases must pass on replay")
     return 0
 
@@ -1582,10 +1712,18 @@ def _print_verify_result(
     result: dict,
     *,
     json_output: bool,
+    triage_output: bool = False,
     written_report: Optional[str],
     fail_on: tuple[str, ...] = (),
 ) -> int:
     fail_messages = _verify_failures(result, fail_on)
+    if triage_output:
+        click.echo(render_triage_summary(result))
+        if written_report:
+            click.echo("Report: %s" % written_report)
+        for message in fail_messages:
+            click.echo("Verification failed: %s" % message, err=True)
+        return 1 if fail_messages else 0
     if json_output:
         if written_report:
             click.echo("Report: %s" % written_report, err=True)
@@ -1755,10 +1893,41 @@ def eval_command(
 
 
 @cli.command()
+@click.argument("scenario", required=False)
 @click.option("--dataset", default="refund_policy", show_default=True, help="Demo dataset name or path.")
 @click.option("--strategy", default="adaptive", show_default=True, help="Demo retrieval strategy.")
 @click.pass_context
-def demo(ctx: click.Context, dataset: str, strategy: str) -> None:
+def demo(ctx: click.Context, scenario: Optional[str], dataset: str, strategy: str) -> None:
+    if scenario:
+        normalized = scenario.strip().lower().replace("_", "-")
+        if normalized != "groundedness-gap":
+            raise click.UsageError("Unknown demo scenario %r. Use 'groundedness-gap'." % scenario)
+        groundedness_demo = run_groundedness_gap_demo()
+        rag = groundedness_demo.result.get("rag") or {}
+        claim = ((rag.get("claims") or [{}])[0])
+        summary = rag.get("summary") or {}
+        abstention = rag.get("abstention") or {}
+        root = claim.get("root_cause") or {}
+        trace_payload = json.loads(Path(groundedness_demo.trace_path).read_text(encoding="utf-8"))
+        click.echo("Query: %s" % rag.get("query"))
+        click.echo("Answer: %s" % rag.get("answer"))
+        for context in trace_payload.get("contexts") or []:
+            metadata = context.get("metadata") or {}
+            condition = metadata.get("freshness") or "unknown"
+            click.echo(
+                "Retrieved source [%s, %s]: %s"
+                % (context.get("id"), condition, context.get("text"))
+            )
+        click.echo("Citation: atlas_policy_2024")
+        click.echo("Support verdict: %s" % claim.get("verdict"))
+        click.echo("Citation status: %s" % claim.get("citation_status"))
+        click.echo("Source condition: %s" % claim.get("source_status"))
+        click.echo("Abstain: %s" % str(bool(abstention.get("should_abstain"))).lower())
+        click.echo("Root cause: %s" % root.get("label"))
+        click.echo("Repair: %s" % (root.get("suggested_fix") or summary.get("suggested_fix")))
+        click.echo("Trace: %s" % groundedness_demo.trace_path)
+        click.echo("Regression test: %s" % groundedness_demo.regression_test_path)
+        return
     client = _client(ctx)
     config = _load(ctx)
     report_path = Path(config.local_store_dir) / "reports" / ("%s_demo.html" % Path(dataset).name)
@@ -1878,6 +2047,8 @@ def _print_suite_result(
 ) -> None:
     summary = result.get("summary") or {}
     click.echo("Suite: %s" % result.get("suite_name"))
+    if result.get("verifier") == "hybrid_v2":
+        click.echo("Verifier: hybrid_v2 (experimental)")
     click.echo("Status: %s" % summary.get("status"))
     click.echo("Cases: %s" % summary.get("total_cases"))
     click.echo("Passed: %s" % summary.get("passed"))

{contexttrace-1.1.0 → contexttrace-1.3.0}/contexttrace/contracts.py

@@ -19,6 +19,7 @@ DEFAULT_PROFILE_ID = "full_v1"
 SCHEMA_FILES = {
     "TraceV1": "trace-v1.schema.json",
     "ClaimVerificationV1": "claim-verification-v1.schema.json",
+    "ClaimVerificationHybridV2": "claim-verification-hybrid-v2.schema.json",
     "DiagnosisV1": "diagnosis-v1.schema.json",
     "RepairPlanV1": "repair-plan-v1.schema.json",
     "RegressionCaseV1": "regression-case-v1.schema.json",