contexttrace 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: contexttrace
-Version: 0.5.0
+Version: 0.7.0
 Summary: Local-first SDK and CLI for RAG and agent reliability tracing, citation checks, and failure diagnosis.
 Author: ContextTrace contributors
 License: MIT
@@ -119,7 +119,31 @@ with ct.trace(query="What is the refund policy?") as trace:
 
 ## BYO RAG Endpoint
 
-Evaluate a running local or hosted RAG API without adding SDK code:
+Capture and verify one live response from a running local or hosted RAG API without adding SDK code:
+
+```bash
+contexttrace capture endpoint \
+  --endpoint http://localhost:8000/query \
+  --query "What is the refund policy?" \
+  --answer-path $.answer \
+  --contexts-path $.contexts \
+  --citations-path $.citations \
+  --out traces/refund_trace.json \
+  --verify \
+  --report
+```
+
+If you already have a saved endpoint response:
+
+```bash
+contexttrace capture response response.json \
+  --query "What is the refund policy?" \
+  --out traces/refund_trace.json \
+  --verify \
+  --report
+```
+
+Evaluate a dataset through the same endpoint when you are ready to regression test:
 
 ```bash
 contexttrace eval \
@@ -139,6 +163,8 @@ Verify a portable RAG trace artifact without a hosted dashboard:
 
 ```bash
 contexttrace verify-demo unsupported_claim --report
+contexttrace inspect trace.json
+contexttrace qa trace.json --corpus docs/ --report
 contexttrace verify trace.json
 contexttrace verify trace.json --json
 contexttrace verify trace.json --report --out reports/example.html
@@ -150,26 +176,47 @@ 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 suite create traces/*.json --out contexttrace-suite.json
+contexttrace suite add contexttrace-suite.json traces/new_failure.json
+contexttrace suite list contexttrace-suite.json
+contexttrace suite run contexttrace-suite.json --endpoint http://localhost:8000/query --report
+contexttrace suite prune contexttrace-suite.json --results .contexttrace/suites/contexttrace-regression-suite_results.json
+contexttrace suite report .contexttrace/suites/contexttrace-regression-suite_results.json
 contexttrace audit trace.json --corpus docs/
 contexttrace audit trace.json --corpus docs/ --report
 contexttrace audit trace.json --corpus docs/ --fail-on retrieval_miss
+contexttrace audit-benchmark --case-set real --mode semantic
+contexttrace audit-benchmark --case-set real --mode semantic --report
 ```
 
 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.
 
 `verify-demo` uses bundled demo traces, so it works immediately after `pip install contexttrace`. Available demos include `unsupported_claim`, `partial_support`, `citation_mismatch`, `should_abstain`, and `supported_answer`.
 
-Use `--mode semantic` for local paraphrase-aware matching, and `verify-benchmark` to inspect bundled precision/recall metrics. The default benchmark includes 32 real ContextTrace docs and release-artifact cases. `--case-set external` adds public OSS documentation and GitHub issue cases from Qdrant, Chroma, Haystack, and LangChain, while `--case-set all` runs both packs. `--report` writes an HTML report with misses to inspect.
+Use `--mode semantic` for local paraphrase-aware matching, and `verify-benchmark` to inspect bundled precision/recall metrics. The default benchmark includes 32 ContextTrace docs and release-artifact cases. `--case-set external` adds public OSS documentation and GitHub issue cases from Qdrant, Chroma, Haystack, and LangChain, while `--case-set all` runs both packs. `--report` writes an HTML report with misses to inspect.
 
 Verification output includes evidence span offsets, stable span hashes, multiple supporting spans, typed matched/missing facts, and claim-level root causes so partial support failures are easier to inspect.
 
 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.
 
+Use the capture helper when you have RAG artifacts in memory:
+
+```python
+from contexttrace import capture_rag_trace, write_rag_trace
+
+trace = capture_rag_trace(query=question, answer=answer, contexts=retrieved_docs)
+write_rag_trace(trace, "trace.json")
+```
+
 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.
+Use `contexttrace suite create`, `suite add`, and `suite run` to turn saved failures into replayable endpoint tests. Suite runs call your current RAG endpoint with the saved query, verify the new answer, compare it with the baseline trace, and exit non-zero when a saved failure still reproduces or a good case regresses. Use `suite list`, `suite remove`, and `suite prune` to manage the suite as failures are fixed or retired.
+
+Use `contexttrace audit trace.json --corpus docs/` to diagnose whether an unsupported claim failed because retrieval missed evidence, reranking buried it, chunking omitted the supporting span, the corpus lacks coverage, or generation overclaimed. Audit output includes failure stages, diagnostic signals, and prioritized next actions.
+
+Use `contexttrace audit-benchmark --case-set real --mode semantic` to test retrieval-audit labels against bundled public OSS documentation and GitHub issue snippets from Qdrant, Chroma, Haystack, LangChain, and ContextTrace docs.
 
-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.
+The v0.7.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-0.7.0}/README.md

@@ -1,135 +1,182 @@
-# ContextTrace
-
-**Debug RAG failures before users find them.**
-
-ContextTrace is a local-first Python SDK and CLI for evaluating existing RAG and AI agent systems. It records retrieved chunks, selected context, answer claims, citations, token usage, latency, and agent events, then writes local traces and HTML reports without requiring a hosted dashboard.
-
-## Install
-
-```bash
-pip install contexttrace
-contexttrace --version
-contexttrace init
-```
-
-Optional integrations:
-
-```bash
-pip install "contexttrace[langchain]"
-pip install "contexttrace[llamaindex]"
-pip install "contexttrace[fastapi]"
-pip install "contexttrace[langgraph]"
-pip install "contexttrace[otel]"
-pip install "contexttrace[all]"
-```
-
-## Quickstart
-
-```bash
-contexttrace init
-contexttrace demo --dataset refund_policy
-contexttrace report --last
-contexttrace doctor
-```
-
-By default, traces are stored locally in:
-
-```text
-.contexttrace/contexttrace.db
-```
-
-## SDK Example
-
-```python
-from contexttrace import ContextTrace
-
-ct = ContextTrace(project="support-rag")
-
-with ct.trace(query="What is the refund policy?") as trace:
-    chunks = retriever.search("What is the refund policy?")
-    trace.log_retrieval(chunks)
-    trace.log_context(chunks[:5])
-
-    answer = llm.generate("What is the refund policy?", chunks[:5])
-    trace.log_answer(answer, usage={"total_tokens": 1200})
-    trace.log_citations([
-        {"claim": "Refunds are available within 30 days.", "source_chunk_id": "chunk_12"}
-    ])
-
-    result = trace.evaluate()
-    print(result["failure"]["failure_type"])
-```
-
-## BYO RAG Endpoint
-
-Evaluate a running local or hosted RAG API without adding SDK code:
-
-```bash
-contexttrace eval \
-  --dataset evals/questions.json \
-  --endpoint http://localhost:8000/query \
-  --method POST \
-  --input-key question \
-  --answer-path $.answer \
-  --contexts-path $.contexts \
-  --citations-path $.citations \
-  --fail-on "failure_rate>0.25"
-```
-
-## Claim-Level Evidence Verification
-
-Verify a portable RAG trace artifact without a hosted dashboard:
-
-```bash
-contexttrace verify-demo unsupported_claim --report
-contexttrace verify trace.json
-contexttrace verify trace.json --json
-contexttrace verify trace.json --report --out reports/example.html
-contexttrace verify trace.json --mode semantic
-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
+
+**Debug RAG failures before users find them.**
+
+ContextTrace is a local-first Python SDK and CLI for evaluating existing RAG and AI agent systems. It records retrieved chunks, selected context, answer claims, citations, token usage, latency, and agent events, then writes local traces and HTML reports without requiring a hosted dashboard.
+
+## Install
+
+```bash
+pip install contexttrace
+contexttrace --version
+contexttrace init
+```
+
+Optional integrations:
+
+```bash
+pip install "contexttrace[langchain]"
+pip install "contexttrace[llamaindex]"
+pip install "contexttrace[fastapi]"
+pip install "contexttrace[langgraph]"
+pip install "contexttrace[otel]"
+pip install "contexttrace[all]"
+```
+
+## Quickstart
+
+```bash
+contexttrace init
+contexttrace demo --dataset refund_policy
+contexttrace report --last
+contexttrace doctor
+```
+
+By default, traces are stored locally in:
+
+```text
+.contexttrace/contexttrace.db
+```
+
+## SDK Example
+
+```python
+from contexttrace import ContextTrace
+
+ct = ContextTrace(project="support-rag")
+
+with ct.trace(query="What is the refund policy?") as trace:
+    chunks = retriever.search("What is the refund policy?")
+    trace.log_retrieval(chunks)
+    trace.log_context(chunks[:5])
+
+    answer = llm.generate("What is the refund policy?", chunks[:5])
+    trace.log_answer(answer, usage={"total_tokens": 1200})
+    trace.log_citations([
+        {"claim": "Refunds are available within 30 days.", "source_chunk_id": "chunk_12"}
+    ])
+
+    result = trace.evaluate()
+    print(result["failure"]["failure_type"])
+```
+
+## BYO RAG Endpoint
+
+Capture and verify one live response from a running local or hosted RAG API without adding SDK code:
+
+```bash
+contexttrace capture endpoint \
+  --endpoint http://localhost:8000/query \
+  --query "What is the refund policy?" \
+  --answer-path $.answer \
+  --contexts-path $.contexts \
+  --citations-path $.citations \
+  --out traces/refund_trace.json \
+  --verify \
+  --report
+```
+
+If you already have a saved endpoint response:
+
+```bash
+contexttrace capture response response.json \
+  --query "What is the refund policy?" \
+  --out traces/refund_trace.json \
+  --verify \
+  --report
+```
+
+Evaluate a dataset through the same endpoint when you are ready to regression test:
+
+```bash
+contexttrace eval \
+  --dataset evals/questions.json \
+  --endpoint http://localhost:8000/query \
+  --method POST \
+  --input-key question \
+  --answer-path $.answer \
+  --contexts-path $.contexts \
+  --citations-path $.citations \
+  --fail-on "failure_rate>0.25"
+```
+
+## Claim-Level Evidence Verification
+
+Verify a portable RAG trace artifact without a hosted dashboard:
+
+```bash
+contexttrace verify-demo unsupported_claim --report
+contexttrace inspect trace.json
+contexttrace qa trace.json --corpus docs/ --report
+contexttrace verify trace.json
+contexttrace verify trace.json --json
+contexttrace verify trace.json --report --out reports/example.html
+contexttrace verify trace.json --mode semantic
+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 suite create traces/*.json --out contexttrace-suite.json
+contexttrace suite add contexttrace-suite.json traces/new_failure.json
+contexttrace suite list contexttrace-suite.json
+contexttrace suite run contexttrace-suite.json --endpoint http://localhost:8000/query --report
+contexttrace suite prune contexttrace-suite.json --results .contexttrace/suites/contexttrace-regression-suite_results.json
+contexttrace suite report .contexttrace/suites/contexttrace-regression-suite_results.json
 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.
-
-`verify-demo` uses bundled demo traces, so it works immediately after `pip install contexttrace`. Available demos include `unsupported_claim`, `partial_support`, `citation_mismatch`, `should_abstain`, and `supported_answer`.
-
-Use `--mode semantic` for local paraphrase-aware matching, and `verify-benchmark` to inspect bundled precision/recall metrics. The default benchmark includes 32 real ContextTrace docs and release-artifact cases. `--case-set external` adds public OSS documentation and GitHub issue cases from Qdrant, Chroma, Haystack, and LangChain, while `--case-set all` runs both packs. `--report` writes an HTML report with misses to inspect.
-
-Verification output includes evidence span offsets, stable span hashes, multiple supporting spans, typed matched/missing facts, and claim-level root causes so partial support failures are easier to inspect.
-
-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.
+contexttrace audit-benchmark --case-set real --mode semantic
+contexttrace audit-benchmark --case-set real --mode semantic --report
+```
+
+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.
+
+`verify-demo` uses bundled demo traces, so it works immediately after `pip install contexttrace`. Available demos include `unsupported_claim`, `partial_support`, `citation_mismatch`, `should_abstain`, and `supported_answer`.
+
+Use `--mode semantic` for local paraphrase-aware matching, and `verify-benchmark` to inspect bundled precision/recall metrics. The default benchmark includes 32 ContextTrace docs and release-artifact cases. `--case-set external` adds public OSS documentation and GitHub issue cases from Qdrant, Chroma, Haystack, and LangChain, while `--case-set all` runs both packs. `--report` writes an HTML report with misses to inspect.
+
+Verification output includes evidence span offsets, stable span hashes, multiple supporting spans, typed matched/missing facts, and claim-level root causes so partial support failures are easier to inspect.
+
+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.
+
+Use the capture helper when you have RAG artifacts in memory:
+
+```python
+from contexttrace import capture_rag_trace, write_rag_trace
+
+trace = capture_rag_trace(query=question, answer=answer, contexts=retrieved_docs)
+write_rag_trace(trace, "trace.json")
+```
 
 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
-
-- `retrieval_miss`
-- `citation_mismatch`
-- `unsupported_answer`
-- `contradicted_answer`
-- `conflicting_sources`
-- `should_have_abstained`
-- agent failures such as `stale_memory_used` and `tool_error`
-
-## Privacy
-
-Local mode is the default. ContextTrace makes no network calls unless you configure an LLM judge provider or evaluate a RAG endpoint you provide.
-
-## Links
-
-- Repository: https://github.com/samarth1412/Context-Trace
-- Documentation: https://github.com/samarth1412/Context-Trace/tree/main/docs
-- Issues: https://github.com/samarth1412/Context-Trace/issues
+Use `contexttrace suite create`, `suite add`, and `suite run` to turn saved failures into replayable endpoint tests. Suite runs call your current RAG endpoint with the saved query, verify the new answer, compare it with the baseline trace, and exit non-zero when a saved failure still reproduces or a good case regresses. Use `suite list`, `suite remove`, and `suite prune` to manage the suite as failures are fixed or retired.
+
+Use `contexttrace audit trace.json --corpus docs/` to diagnose whether an unsupported claim failed because retrieval missed evidence, reranking buried it, chunking omitted the supporting span, the corpus lacks coverage, or generation overclaimed. Audit output includes failure stages, diagnostic signals, and prioritized next actions.
+
+Use `contexttrace audit-benchmark --case-set real --mode semantic` to test retrieval-audit labels against bundled public OSS documentation and GitHub issue snippets from Qdrant, Chroma, Haystack, LangChain, and ContextTrace docs.
+
+The v0.7.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
+
+- `retrieval_miss`
+- `citation_mismatch`
+- `unsupported_answer`
+- `contradicted_answer`
+- `conflicting_sources`
+- `should_have_abstained`
+- agent failures such as `stale_memory_used` and `tool_error`
+
+## Privacy
+
+Local mode is the default. ContextTrace makes no network calls unless you configure an LLM judge provider or evaluate a RAG endpoint you provide.
+
+## Links
+
+- Repository: https://github.com/samarth1412/Context-Trace
+- Documentation: https://github.com/samarth1412/Context-Trace/tree/main/docs
+- Issues: https://github.com/samarth1412/Context-Trace/issues

{contexttrace-0.5.0 → contexttrace-0.7.0}/contexttrace/__init__.py

@@ -1,36 +1,44 @@
-from contexttrace._version import __version__
-from contexttrace.client import AsyncContextTrace, ContextTrace
-from contexttrace.config import ContextTraceConfig
-from contexttrace.errors import (
-    ContextTraceConfigError,
-    ContextTraceError,
-    ContextTraceHTTPError,
-    ContextTraceLocalError,
-)
-from contexttrace.integrations.fastapi import ContextTraceFastAPIMiddleware
-from contexttrace.integrations.langchain import ContextTraceCallbackHandler
-from contexttrace.integrations.langgraph import ContextTraceLangGraphTracer
-from contexttrace.integrations.llamaindex import ContextTraceLlamaIndexCallbackHandler
-from contexttrace.integrations.opentelemetry import OpenTelemetryExporter, export_contexttrace_trace
-from contexttrace.reliability import ReliabilityScore, ReliabilityScorer
-from contexttrace.report import ReportGenerator
-
-__all__ = [
-    "AsyncContextTrace",
-    "ContextTrace",
-    "ContextTraceConfig",
-    "ContextTraceConfigError",
-    "ContextTraceCallbackHandler",
-    "ContextTraceError",
-    "ContextTraceFastAPIMiddleware",
-    "ContextTraceHTTPError",
-    "ContextTraceLocalError",
-    "ContextTraceLangGraphTracer",
-    "ContextTraceLlamaIndexCallbackHandler",
-    "OpenTelemetryExporter",
-    "ReliabilityScore",
-    "ReliabilityScorer",
-    "ReportGenerator",
-    "export_contexttrace_trace",
-    "__version__",
-]
+from contexttrace._version import __version__
+from contexttrace.capture import capture_rag_trace, langchain_documents_to_contexts, write_rag_trace
+from contexttrace.capture_endpoint import EndpointCapture, capture_endpoint_trace, capture_response_trace
+from contexttrace.client import AsyncContextTrace, ContextTrace
+from contexttrace.config import ContextTraceConfig
+from contexttrace.errors import (
+    ContextTraceConfigError,
+    ContextTraceError,
+    ContextTraceHTTPError,
+    ContextTraceLocalError,
+)
+from contexttrace.integrations.fastapi import ContextTraceFastAPIMiddleware
+from contexttrace.integrations.langchain import ContextTraceCallbackHandler
+from contexttrace.integrations.langgraph import ContextTraceLangGraphTracer
+from contexttrace.integrations.llamaindex import ContextTraceLlamaIndexCallbackHandler
+from contexttrace.integrations.opentelemetry import OpenTelemetryExporter, export_contexttrace_trace
+from contexttrace.reliability import ReliabilityScore, ReliabilityScorer
+from contexttrace.report import ReportGenerator
+
+__all__ = [
+    "AsyncContextTrace",
+    "ContextTrace",
+    "ContextTraceConfig",
+    "ContextTraceConfigError",
+    "ContextTraceCallbackHandler",
+    "ContextTraceError",
+    "ContextTraceFastAPIMiddleware",
+    "ContextTraceHTTPError",
+    "ContextTraceLocalError",
+    "ContextTraceLangGraphTracer",
+    "ContextTraceLlamaIndexCallbackHandler",
+    "EndpointCapture",
+    "OpenTelemetryExporter",
+    "ReliabilityScore",
+    "ReliabilityScorer",
+    "ReportGenerator",
+    "capture_rag_trace",
+    "capture_endpoint_trace",
+    "capture_response_trace",
+    "export_contexttrace_trace",
+    "langchain_documents_to_contexts",
+    "write_rag_trace",
+    "__version__",
+]

contexttrace-0.7.0/contexttrace/_version.py

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

contexttrace-0.7.0/contexttrace/capture.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+from contexttrace.verify.schema import RAGTrace, TraceCitation, TraceContext, load_trace
+
+
+def capture_rag_trace(
+    *,
+    query: str,
+    answer: str,
+    contexts: Iterable[Any],
+    citations: Iterable[Any] | None = None,
+    metadata: dict[str, Any] | None = None,
+    context_id_prefix: str = "context",
+) -> RAGTrace:
+    """Create a portable ContextTrace verification trace from common RAG artifacts."""
+
+    payload = {
+        "query": query,
+        "answer": answer,
+        "contexts": [
+            context_to_trace_context(context, index=index, id_prefix=context_id_prefix).to_dict()
+            for index, context in enumerate(contexts)
+        ],
+        "citations": [
+            citation_to_trace_citation(citation).to_dict()
+            for citation in (citations or [])
+        ],
+        "metadata": dict(metadata or {}),
+    }
+    return load_trace(payload, source="captured RAG trace")
+
+
+def write_rag_trace(trace: RAGTrace, path: str | Path) -> str:
+    """Write a portable RAG trace JSON file that works with `contexttrace verify`."""
+
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(trace.to_dict(), indent=2), encoding="utf-8")
+    return str(output_path)
+
+
+def context_to_trace_context(
+    context: Any,
+    *,
+    index: int = 0,
+    id_prefix: str = "context",
+) -> TraceContext:
+    """Convert dicts, LangChain Documents, or document-like objects to TraceContext."""
+
+    if isinstance(context, TraceContext):
+        return context
+
+    if isinstance(context, dict):
+        text = _first_present(context, ("text", "content", "page_content"))
+        metadata = dict(context.get("metadata") or {})
+        context_id = _first_present(
+            context,
+            ("id", "chunk_id", "source_id", "source_chunk_id", "document_id"),
+        )
+        source = context.get("source")
+        score = context.get("score", context.get("relevance_score"))
+    else:
+        text = getattr(context, "page_content", None) or getattr(context, "text", None)
+        metadata = dict(getattr(context, "metadata", None) or {})
+        context_id = getattr(context, "id", None) or metadata.get("chunk_id") or metadata.get("id")
+        source = metadata.get("source")
+        score = getattr(context, "score", None) or metadata.get("score") or metadata.get("relevance_score")
+
+    context_text = str(text or "").strip()
+    if not context_text:
+        raise ValueError("Captured context %s did not include text/content/page_content." % index)
+
+    if source is not None and "source" not in metadata:
+        metadata["source"] = source
+    if score is not None and "score" not in metadata and "relevance_score" not in metadata:
+        metadata["score"] = score
+
+    resolved_id = _context_id(
+        context_id=context_id,
+        metadata=metadata,
+        id_prefix=id_prefix,
+        index=index,
+    )
+    return TraceContext(id=resolved_id, text=context_text, metadata=metadata)
+
+
+def citation_to_trace_citation(citation: Any) -> TraceCitation:
+    if isinstance(citation, TraceCitation):
+        return citation
+
+    if isinstance(citation, dict):
+        claim = citation.get("claim")
+        source_id = citation.get("source_id") or citation.get("source_chunk_id") or citation.get("chunk_id")
+        metadata = dict(citation.get("metadata") or {})
+    else:
+        claim = getattr(citation, "claim", None)
+        source_id = (
+            getattr(citation, "source_id", None)
+            or getattr(citation, "source_chunk_id", None)
+            or getattr(citation, "chunk_id", None)
+        )
+        metadata = dict(getattr(citation, "metadata", None) or {})
+
+    if not str(claim or "").strip():
+        raise ValueError("Captured citation did not include claim.")
+    if not str(source_id or "").strip():
+        raise ValueError("Captured citation did not include source_id/source_chunk_id/chunk_id.")
+    return TraceCitation(claim=str(claim).strip(), source_id=str(source_id).strip(), metadata=metadata)
+
+
+def langchain_documents_to_contexts(
+    documents: Iterable[Any],
+    *,
+    id_prefix: str = "langchain_doc",
+) -> list[TraceContext]:
+    return [
+        context_to_trace_context(document, index=index, id_prefix=id_prefix)
+        for index, document in enumerate(documents)
+    ]
+
+
+def _first_present(payload: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    for key in keys:
+        value = payload.get(key)
+        if value is not None and str(value).strip() != "":
+            return value
+    return None
+
+
+def _context_id(
+    *,
+    context_id: Any,
+    metadata: dict[str, Any],
+    id_prefix: str,
+    index: int,
+) -> str:
+    if context_id is not None and str(context_id).strip():
+        return str(context_id).strip()
+    source = metadata.get("source")
+    chunk_marker = (
+        metadata.get("chunk_id")
+        or metadata.get("chunk_index")
+        or metadata.get("page")
+        or metadata.get("start_index")
+    )
+    if source is not None and str(source).strip() and chunk_marker is not None:
+        return "%s:%s" % (str(source).strip(), str(chunk_marker).strip())
+    if source is not None and str(source).strip():
+        return "%s:%s" % (str(source).strip(), index + 1)
+    return "%s_%s" % (id_prefix, index + 1)