contexttrace 1.1.0__tar.gz → 1.2.0__tar.gz

contexttrace-1.2.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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contexttrace
-Version: 1.1.0
+Version: 1.2.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
 License-Expression: MIT
@@ -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
@@ -263,6 +271,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.2.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
@@ -190,6 +196,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.2.0/contexttrace/_version.py

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

{contexttrace-1.1.0 → contexttrace-1.2.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,12 +314,94 @@ 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.")
@@ -563,12 +654,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 +671,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 +681,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 +1678,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 +1859,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 +2013,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.2.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",

{contexttrace-1.1.0 → contexttrace-1.2.0}/contexttrace/demo.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -8,6 +9,7 @@ from typing import Any, Iterable
 from contexttrace.client import ContextTrace
 from contexttrace.demo_data import load_demo_dataset
 from contexttrace.report import ReportGenerator
+from contexttrace.diagnose import diagnose_payload, write_diagnosis_regression_test
 
 
 STRATEGY_TOP_K = {
@@ -32,6 +34,71 @@ class DemoRun:
     summary: dict[str, Any]
 
 
+@dataclass(frozen=True)
+class GroundednessGapDemo:
+    trace_path: str
+    regression_test_path: str
+    result: dict[str, Any]
+
+
+def run_groundedness_gap_demo(
+    *, output_dir: str | Path = ".contexttrace/demo/groundedness-gap"
+) -> GroundednessGapDemo:
+    """Run the paper's grounded-but-stale example without network access."""
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+    trace = {
+        "query": "What is Atlas's current cancellation window?",
+        "answer": "Atlas allows cancellation within 43 days.",
+        "contexts": [
+            {
+                "id": "atlas_policy_2024",
+                "text": "Atlas allows cancellation within 43 days.",
+                "metadata": {
+                    "canonical": False,
+                    "freshness": "stale",
+                    "source_group": "atlas_cancellation_policy",
+                    "source_version": "2024.1",
+                },
+            },
+            {
+                "id": "atlas_policy_2026",
+                "text": "The current Atlas policy allows cancellation within 42 days.",
+                "metadata": {
+                    "canonical": True,
+                    "freshness": "current",
+                    "source_authority": "official",
+                    "source_group": "atlas_cancellation_policy",
+                    "source_version": "2026.1",
+                },
+            },
+        ],
+        "citations": [
+            {
+                "claim": "Atlas allows cancellation within 43 days.",
+                "source_id": "atlas_policy_2024",
+            }
+        ],
+        "metadata": {"demo": "groundedness-gap", "synthetic": True},
+    }
+    trace_path = output / "groundedness_gap_trace.json"
+    trace_path.write_text(json.dumps(trace, indent=2) + "\n", encoding="utf-8")
+    result = diagnose_payload(trace, mode="semantic", trace_path=str(trace_path))
+    test_path = output / "test_groundedness_gap_diagnosis.py"
+    write_diagnosis_regression_test(
+        trace_path,
+        result,
+        output_path=test_path,
+        mode="semantic",
+        overwrite=True,
+    )
+    return GroundednessGapDemo(
+        trace_path=str(trace_path),
+        regression_test_path=str(test_path),
+        result=result,
+    )
+
+
 def run_demo_dataset(
     *,
     dataset: str,

contexttrace-1.2.0/contexttrace/schemas/claim-verification-hybrid-v2.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contexttrace.dev/schemas/claim-verification-hybrid-v2.schema.json",
+  "title": "ClaimVerificationHybridV2",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "taxonomy_version",
+    "verifier_version",
+    "profile_id",
+    "diagnostic_reasoner_version",
+    "experimental",
+    "query",
+    "answer",
+    "summary",
+    "claims",
+    "abstention",
+    "diagnostics",
+    "capabilities",
+    "limitations",
+    "truncation"
+  ],
+  "properties": {
+    "schema_version": {"const": "2.0"},
+    "taxonomy_version": {"const": "contexttrace-hybrid-v2.0"},
+    "verifier_version": {"const": "hybrid_v2"},
+    "profile_id": {"type": "string", "pattern": "^hybrid_v2"},
+    "diagnostic_reasoner_version": {"const": "evidence_chain_v2"},
+    "experimental": {"const": true},
+    "query": {"type": "string"},
+    "answer": {"type": "string"},
+    "summary": {"type": "object"},
+    "claims": {"type": "array", "items": {"type": "object"}},
+    "abstention": {"type": "object"},
+    "diagnostics": {"type": "object"},
+    "metadata": {"type": "object"},
+    "verification_profile": {"type": "object"},
+    "capabilities": {"type": "object"},
+    "limitations": {"type": "array", "items": {"type": "string"}},
+    "truncation": {"type": "object"}
+  },
+  "additionalProperties": false
+}