contexttrace 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: contexttrace
-Version: 1.2.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
@@ -149,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

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

@@ -74,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

{contexttrace-1.2.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.2.0 → contexttrace-1.3.0}/contexttrace/cli.py

@@ -405,7 +405,13 @@ def verify_v2_command(
 @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:
@@ -416,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"])
@@ -440,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:")
@@ -449,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")

contexttrace-1.3.0/contexttrace/evidence_integrity.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any, Iterable
+
+from contexttrace.verify.schema import RAGTrace, TraceContext
+
+
+EVIDENCE_METADATA_KEY = "contexttrace_evidence"
+
+LINKED_PART_DROPPED = "linked_part_dropped"
+MATERIAL_SPAN_DROPPED = "material_span_dropped"
+SELECTED_TEXT_NOT_IN_SOURCE = "selected_text_not_in_source"
+INVALID_LINEAGE = "invalid_lineage"
+
+
+def build_evidence_lineage(
+    *,
+    source_unit_id: str,
+    source_text: str,
+    linked_parts: Iterable[dict[str, Any]] | None = None,
+    material_spans: Iterable[dict[str, Any]] | None = None,
+    transformation: str | None = None,
+) -> dict[str, Any]:
+    """Build namespaced metadata for deterministic source-to-selection checks."""
+
+    unit_id = _required_text(source_unit_id, "source_unit_id")
+    text = _required_text(source_text, "source_text")
+    lineage: dict[str, Any] = {
+        "schema_version": "1.0",
+        "source_unit_id": unit_id,
+        "source_text": text,
+    }
+    if linked_parts is not None:
+        lineage["linked_parts"] = _build_parts(linked_parts, text, "linked_parts")
+    if material_spans is not None:
+        lineage["material_spans"] = _build_parts(material_spans, text, "material_spans")
+    if transformation is not None:
+        lineage["transformation"] = _required_text(transformation, "transformation")
+    return {EVIDENCE_METADATA_KEY: lineage}
+
+
+def audit_evidence_integrity(trace: RAGTrace) -> dict[str, Any]:
+    """Report observed evidence loss from explicitly captured lineage metadata."""
+
+    assessments = [_assess_context(context) for context in trace.contexts]
+    captured = [item for item in assessments if item["capture_status"] == "captured"]
+    unknown = [item for item in assessments if item["capture_status"] != "captured"]
+    issues = [issue for item in captured for issue in item["issues"]]
+    if not captured:
+        status = "not_captured"
+    elif issues:
+        status = "issues_found"
+    elif unknown:
+        status = "partial"
+    else:
+        status = "complete"
+    counts: dict[str, int] = {}
+    for issue in issues:
+        issue_type = str(issue["type"])
+        counts[issue_type] = counts.get(issue_type, 0) + 1
+    return {
+        "schema_version": "1.0",
+        "status": status,
+        "summary": {
+            "total_contexts": len(trace.contexts),
+            "assessed_contexts": len(captured),
+            "unknown_contexts": len(unknown),
+            "issue_count": len(issues),
+            "issue_types": counts,
+        },
+        "issues": issues,
+        "contexts": assessments,
+        "network_calls": 0,
+        "model_calls": 0,
+    }
+
+
+def _assess_context(context: TraceContext) -> dict[str, Any]:
+    raw = context.metadata.get(EVIDENCE_METADATA_KEY)
+    if raw is None:
+        return {
+            "selected_context_id": context.id,
+            "capture_status": "not_captured",
+            "reason": "No contexttrace_evidence lineage metadata was captured.",
+            "issues": [],
+        }
+    if not isinstance(raw, dict):
+        return _invalid_context(context.id, "contexttrace_evidence must be an object.")
+    source_unit_id = _clean(raw.get("source_unit_id"))
+    source_text = _clean(raw.get("source_text"))
+    if not source_unit_id or not source_text:
+        return _invalid_context(
+            context.id,
+            "Captured lineage must include non-empty source_unit_id and source_text.",
+        )
+
+    selected = _normalize(context.text)
+    source = _normalize(source_text)
+    linked_parts, invalid_parts = _parts(raw.get("linked_parts"), source_text, "linked_parts")
+    material_spans, invalid_spans = _parts(
+        raw.get("material_spans"), source_text, "material_spans"
+    )
+    if invalid_parts or invalid_spans:
+        return _invalid_context(context.id, "; ".join(invalid_parts + invalid_spans))
+
+    issues: list[dict[str, Any]] = []
+    if selected not in source:
+        issues.append(
+            _issue(
+                issue_type=SELECTED_TEXT_NOT_IN_SOURCE,
+                severity="high",
+                context_id=context.id,
+                source_unit_id=source_unit_id,
+                observed="Selected text is not a normalized verbatim span of the captured source unit.",
+            )
+        )
+    else:
+        present_parts = [
+            part
+            for part in linked_parts
+            if part["required"] and _normalize(part["text"]) in selected
+        ]
+        for part in linked_parts:
+            if not part["required"] or _normalize(part["text"]) in selected:
+                continue
+            if present_parts:
+                issues.append(
+                    _issue(
+                        issue_type=LINKED_PART_DROPPED,
+                        severity="high",
+                        context_id=context.id,
+                        source_unit_id=source_unit_id,
+                        observed="A required linked part is present in the source unit but absent from the selected text.",
+                        item=part,
+                    )
+                )
+        for span in material_spans:
+            if span["required"] and _normalize(span["text"]) not in selected:
+                issues.append(
+                    _issue(
+                        issue_type=MATERIAL_SPAN_DROPPED,
+                        severity="high",
+                        context_id=context.id,
+                        source_unit_id=source_unit_id,
+                        observed="A declared material span is present in the source unit but absent from the selected text.",
+                        item=span,
+                    )
+                )
+
+    return {
+        "selected_context_id": context.id,
+        "source_unit_id": source_unit_id,
+        "transformation": _clean(raw.get("transformation")) or None,
+        "capture_status": "captured",
+        "issues": issues,
+    }
+
+
+def _parts(value: Any, source_text: str, field: str) -> tuple[list[dict[str, Any]], list[str]]:
+    if value is None:
+        return [], []
+    if not isinstance(value, list):
+        return [], ["%s must be a list." % field]
+    parts: list[dict[str, Any]] = []
+    invalid: list[str] = []
+    for index, item in enumerate(value):
+        try:
+            part = _part(item, index, field)
+        except ValueError as exc:
+            invalid.append(str(exc))
+            continue
+        if _normalize(part["text"]) not in _normalize(source_text):
+            invalid.append("%s[%s].text is not present in source_text." % (field, index))
+        parts.append(part)
+    return parts, invalid
+
+
+def _build_parts(
+    values: Iterable[dict[str, Any]], source_text: str, field: str
+) -> list[dict[str, Any]]:
+    parts = [_part(value, index, field) for index, value in enumerate(values)]
+    for index, part in enumerate(parts):
+        if _normalize(part["text"]) not in _normalize(source_text):
+            raise ValueError("%s[%s].text must be present in source_text." % (field, index))
+    return parts
+
+
+def _part(value: Any, index: int, field: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("%s[%s] must be an object." % (field, index))
+    required = value.get("required", True)
+    if not isinstance(required, bool):
+        raise ValueError("%s[%s].required must be a boolean." % (field, index))
+    return {
+        "id": _required_text(value.get("id"), "%s[%s].id" % (field, index)),
+        "role": _required_text(value.get("role"), "%s[%s].role" % (field, index)),
+        "text": _required_text(value.get("text"), "%s[%s].text" % (field, index)),
+        "required": required,
+    }
+
+
+def _issue(
+    *,
+    issue_type: str,
+    severity: str,
+    context_id: str,
+    source_unit_id: str,
+    observed: str,
+    item: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "type": issue_type,
+        "status": "observed",
+        "severity": severity,
+        "selected_context_id": context_id,
+        "source_unit_id": source_unit_id,
+        "observed": observed,
+    }
+    if item is not None:
+        result.update(
+            {
+                "item_id": item["id"],
+                "item_role": item["role"],
+                "missing_text": item["text"],
+            }
+        )
+    return result
+
+
+def _invalid_context(context_id: str, reason: str) -> dict[str, Any]:
+    return {
+        "selected_context_id": context_id,
+        "capture_status": INVALID_LINEAGE,
+        "reason": reason,
+        "issues": [],
+    }
+
+
+def _required_text(value: Any, field: str) -> str:
+    if not isinstance(value, str):
+        raise ValueError("%s must be a non-empty string." % field)
+    text = value.strip()
+    if not text:
+        raise ValueError("%s must be a non-empty string." % field)
+    return text
+
+
+def _clean(value: Any) -> str:
+    return "" if value is None else str(value).strip()
+
+
+def _normalize(value: str) -> str:
+    text = unicodedata.normalize("NFKC", value)
+    text = text.translate(str.maketrans("“”‘’", "\"\"''"))
+    return re.sub(r"\s+", " ", text).strip().casefold()

{contexttrace-1.2.0 → contexttrace-1.3.0}/contexttrace/integrations/__init__.py

@@ -1,7 +1,13 @@
 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
 
 __all__ = [
@@ -9,6 +15,8 @@ __all__ = [
     "ContextTraceFastAPIMiddleware",
     "ContextTraceLangGraphTracer",
     "ContextTraceLlamaIndexCallbackHandler",
+    "bind_langchain_evidence_lineage",
+    "bind_llamaindex_evidence_lineage",
     "OpenTelemetryExporter",
     "export_contexttrace_trace",
 ]

contexttrace-1.3.0/contexttrace/integrations/_lineage.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from copy import copy
+from typing import Any
+
+
+def clone_with_updates(value: Any, **updates: Any) -> Any:
+    """Clone a framework value without mutating the application-owned object."""
+
+    if isinstance(value, dict):
+        cloned = dict(value)
+        cloned.update(updates)
+        return cloned
+
+    model_copy = getattr(value, "model_copy", None)
+    if callable(model_copy):
+        return model_copy(update=updates)
+
+    legacy_copy = getattr(value, "copy", None)
+    if callable(legacy_copy):
+        try:
+            return legacy_copy(update=updates)
+        except TypeError:
+            pass
+
+    try:
+        cloned = copy(value)
+        for key, item in updates.items():
+            setattr(cloned, key, item)
+    except (AttributeError, TypeError) as exc:
+        raise TypeError(
+            "Could not clone %s with evidence-lineage metadata." % type(value).__name__
+        ) from exc
+    return cloned

{contexttrace-1.2.0 → contexttrace-1.3.0}/contexttrace/integrations/langchain.py

@@ -7,6 +7,8 @@ from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, Iterable, Optional
 
 from contexttrace.client import ContextTrace
+from contexttrace.evidence_integrity import build_evidence_lineage
+from contexttrace.integrations._lineage import clone_with_updates
 
 try:
     from langchain_core.callbacks import BaseCallbackHandler
@@ -436,6 +438,50 @@ def langchain_document_to_chunk(document: Any, index: int = 0) -> dict[str, Any]
     }
 
 
+def bind_langchain_evidence_lineage(
+    selected_document: Any,
+    *,
+    source_document: Any,
+    source_unit_id: str | None = None,
+    linked_parts: Iterable[dict[str, Any]] | None = None,
+    material_spans: Iterable[dict[str, Any]] | None = None,
+    transformation: str = "langchain_document_selection",
+) -> Any:
+    """Clone a selected LangChain document with its captured source lineage."""
+
+    source_chunk = langchain_document_to_chunk(source_document)
+    selected_chunk = langchain_document_to_chunk(selected_document)
+    resolved_source_id = source_unit_id or _langchain_document_id(source_document)
+    if not resolved_source_id:
+        raise ValueError(
+            "source_unit_id is required when the source document has no chunk_id, id, or doc_id."
+        )
+    lineage = build_evidence_lineage(
+        source_unit_id=str(resolved_source_id),
+        source_text=str(source_chunk["content"]),
+        linked_parts=linked_parts,
+        material_spans=material_spans,
+        transformation=transformation,
+    )
+    metadata = dict(selected_chunk["metadata"])
+    metadata.update(lineage)
+    return clone_with_updates(selected_document, metadata=metadata)
+
+
+def _langchain_document_id(document: Any) -> Any:
+    metadata = getattr(document, "metadata", None) or {}
+    if isinstance(document, dict):
+        metadata = document.get("metadata") or metadata
+    if not isinstance(metadata, dict):
+        metadata = {}
+    return (
+        metadata.get("chunk_id")
+        or metadata.get("id")
+        or metadata.get("doc_id")
+        or getattr(document, "id", None)
+    )
+
+
 def _extract_query(inputs: Any) -> Optional[str]:
     if isinstance(inputs, str):
         return inputs

{contexttrace-1.2.0 → contexttrace-1.3.0}/contexttrace/integrations/llamaindex.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, Iterable, Optional
 
 from contexttrace.client import ContextTrace
+from contexttrace.evidence_integrity import build_evidence_lineage
+from contexttrace.integrations._lineage import clone_with_updates
 
 try:
     from llama_index.core.callbacks.base_handler import BaseCallbackHandler
@@ -365,6 +367,54 @@ def llamaindex_node_to_chunk(node_or_node_with_score: Any, index: int = 0) -> di
     }
 
 
+def bind_llamaindex_evidence_lineage(
+    selected_node: Any,
+    *,
+    source_node: Any,
+    source_unit_id: str | None = None,
+    linked_parts: Iterable[dict[str, Any]] | None = None,
+    material_spans: Iterable[dict[str, Any]] | None = None,
+    transformation: str = "llamaindex_node_postprocessor",
+) -> Any:
+    """Clone a selected LlamaIndex node with its captured source lineage."""
+
+    source_chunk = llamaindex_node_to_chunk(source_node)
+    selected_chunk = llamaindex_node_to_chunk(selected_node)
+    resolved_source_id = source_unit_id or _llamaindex_node_id(source_node)
+    if not resolved_source_id:
+        raise ValueError(
+            "source_unit_id is required when the source node has no chunk_id, id, doc_id, or node_id."
+        )
+    lineage = build_evidence_lineage(
+        source_unit_id=str(resolved_source_id),
+        source_text=str(source_chunk["content"]),
+        linked_parts=linked_parts,
+        material_spans=material_spans,
+        transformation=transformation,
+    )
+    metadata = dict(selected_chunk["metadata"])
+    metadata.update(lineage)
+
+    selected_value = getattr(selected_node, "node", selected_node)
+    cloned_node = clone_with_updates(selected_value, metadata=metadata)
+    if selected_value is selected_node:
+        return cloned_node
+    return clone_with_updates(selected_node, node=cloned_node)
+
+
+def _llamaindex_node_id(node_or_node_with_score: Any) -> Any:
+    node = getattr(node_or_node_with_score, "node", node_or_node_with_score)
+    metadata = _node_metadata(node)
+    return (
+        metadata.get("chunk_id")
+        or metadata.get("id")
+        or metadata.get("doc_id")
+        or getattr(node, "node_id", None)
+        or getattr(node, "id_", None)
+        or getattr(node, "id", None)
+    )
+
+
 def _node_metadata(node: Any) -> dict[str, Any]:
     metadata = getattr(node, "metadata", None)
     if metadata is None: