graphsight-langgraph 0.1.3__tar.gz → 0.2.0__tar.gz

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.1.3
+Version: 0.2.0
 Summary: X-ray for LangGraph retrieval: one callback handler captures every retriever call, score, and relational path — rendered as an interactive graph.
 Author: Arush Karnatak
 License: MIT
@@ -94,29 +94,58 @@ graphsight-github-trace REPO [QUESTION] [options]
 | `--token` | `$GITHUB_TOKEN` | GitHub token. Required for private repositories; raises the rate limit on public ones. |
 | `--prs` | `25` | Recent pull requests to fetch. |
 | `--issues` | `25` | Recent issues to fetch. |
+| `--commits` | `25` | Recent commits to fetch — solo repos with no PRs/issues still produce a full graph. |
 | `--top` | `10` | Items the retrieval keeps. |
 | `--out` | `graphsight_out/` | Output directory for `agent_trace.json` and `trace_state.json`. |
 
 Method note: the CLI builds a corpus with relational edges
-(`person AUTHORED pr`, `pr RESOLVES issue`, `pr TOUCHES repo`) and ranks by
-**lexical overlap with 1-hop graph expansion** — deliberately simple, and
-reported as such. The scores you see are exactly the scores computed;
-nothing is presented as semantic similarity.
+(`person AUTHORED pr/commit`, `pr RESOLVES issue`, `pr TOUCHES repo`) and
+ranks by **lexical overlap with 1-hop graph expansion** — deliberately
+simple, and reported as such. The scores you see are exactly the scores
+computed; nothing is presented as semantic similarity.
+
+Ask it *who / what / when* questions ("who touched auth recently?", "which
+issue needed two attempts?") — that's what commit and PR history can answer.
+*How-does-it-work* questions need semantic retrieval over code and docs,
+which this deliberately simple demo does not pretend to do.
 
 ## Tracing your own agent
 
 The complete integration:
 
 ```python
-from graphsight_langgraph import LangGraphTracer, to_tracestate
+from graphsight_langgraph import LangGraphTracer, capture
 
 tracer = LangGraphTracer()
 result = graph.invoke(inputs, config={"callbacks": [tracer]})
 
-trace = tracer.finish(query="why is checkout failing?", answer=result["answer"])
-to_tracestate(trace)     # viewer-ready dict — json.dump it, then: graphsight trace.json
+capture(tracer, query="why is checkout failing?", answer=result["answer"])
+# -> .graphsight/20260725T071558_why-is-checkout-failing.json
 ```
 
+`capture()` finishes the trace and appends it to a local history directory
+(`./.graphsight/` by default, `$GRAPHSIGHT_DIR` to override) — browse every
+run with `graphsight .graphsight/`. For manual control use
+`tracer.finish()` + `to_tracestate()` / `save_trace()`; `trace.to_dict()`
+gives the framework-neutral `AgentTrace` for your own tooling.
+
+### Retrieved vs. used
+
+When you pass `answer=`, each retrieved item gets an `answer_overlap`
+score — the lexical overlap between the item's content and the final
+answer. In the viewer, items that surfaced in the answer render
+highlighted; items retrieved but unused render dimmed with the label
+*"retrieved, unused."* That splits the two classic retrieval failures at a
+glance:
+
+- **right doc retrieved, ignored by the model** → dimmed node with a high
+  retrieval score
+- **wrong doc trusted** → highlighted node that shouldn't be
+
+The overlap is a lexical heuristic (labeled as such, threshold 0.2) — it is
+never presented as a model-computed relevance judgment. No `answer=` → no
+usage claims; everything renders plain.
+
 ### Configuration propagation (read this once)
 
 LangChain only propagates callbacks into runnables that receive the run's
@@ -138,7 +167,9 @@ retrievals.
 | Name | Description |
 |---|---|
 | `LangGraphTracer()` | `BaseCallbackHandler` subclass. Pass via `config={"callbacks": [tracer]}` to `invoke` / `stream`. Reusable within a single run; create a fresh instance per run. |
-| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency. `query` falls back to the first retriever query seen. |
+| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency and per-item `answer_overlap`. `query` falls back to the first retriever query seen. |
+| `capture(tracer, query=None, answer=None, dir=None) -> Path` | `finish()` + save to the history directory in one call. |
+| `save_trace(trace, dir=None) -> Path` | Writes a finished trace to the history directory (`./.graphsight/` or `$GRAPHSIGHT_DIR`). |
 | `to_tracestate(trace) -> dict` | Maps an `AgentTrace` to the viewer's JSON contract. Serialize with `json.dump`. |
 | `trace.to_dict() -> dict` | The framework-neutral `AgentTrace` (schema v0.1) for your own tooling. |
 | `AgentTrace`, `Span`, `Retrieval`, `RetrievedItem`, `TraceEdge` | Plain dataclasses defining the schema; importable for custom emitters. |
@@ -154,6 +185,7 @@ retrievals.
 | `Document.metadata["edges"]` | relational edges, deduplicated per retrieval |
 | LLM / tool calls | plain spans in the execution timeline |
 | Edges present in a retrieval | `arm = "graph"`, else `"vector"` — detected automatically |
+| The final answer (when passed to `finish`/`capture`) | per-item `answer_overlap` — the retrieved-vs-used signal |
 
 ### Making your retriever graph-aware
 
@@ -192,14 +224,15 @@ else renders as `Document`).
   retriever and were not recomputed — an imported trace never masquerades
   as an engine-computed one.
 
-## Schema (v0.1)
+## Schema (v0.2)
 
 `AgentTrace` is the stable contract. Future adapters (LlamaIndex, raw
-OpenTelemetry) emit the same shape and render in the same viewer.
+OpenTelemetry) emit the same shape and render in the same viewer. v0.2 adds
+`RetrievedItem.answer_overlap` (additive — v0.1 traces stay valid).
 
 ```jsonc
 {
-  "schema_version": "0.1",
+  "schema_version": "0.2",
   "framework": "langgraph",
   "query": "…",
   "spans": [
@@ -213,6 +246,7 @@ OpenTelemetry) emit the same shape and render in the same viewer.
       "items": [
         { "id": "pr_4821", "label": "PR #4821", "kind": "pull_request",
           "score": 0.94, "vector_score": null, "graph_score": null,
+          "answer_overlap": 0.41,                             // null when no answer given
           "content": "…", "source_uri": "https://…", "metadata": {} }
       ],
       "edges": [                                            // optional — the relational view

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/README.md

@@ -67,29 +67,58 @@ graphsight-github-trace REPO [QUESTION] [options]
 | `--token` | `$GITHUB_TOKEN` | GitHub token. Required for private repositories; raises the rate limit on public ones. |
 | `--prs` | `25` | Recent pull requests to fetch. |
 | `--issues` | `25` | Recent issues to fetch. |
+| `--commits` | `25` | Recent commits to fetch — solo repos with no PRs/issues still produce a full graph. |
 | `--top` | `10` | Items the retrieval keeps. |
 | `--out` | `graphsight_out/` | Output directory for `agent_trace.json` and `trace_state.json`. |
 
 Method note: the CLI builds a corpus with relational edges
-(`person AUTHORED pr`, `pr RESOLVES issue`, `pr TOUCHES repo`) and ranks by
-**lexical overlap with 1-hop graph expansion** — deliberately simple, and
-reported as such. The scores you see are exactly the scores computed;
-nothing is presented as semantic similarity.
+(`person AUTHORED pr/commit`, `pr RESOLVES issue`, `pr TOUCHES repo`) and
+ranks by **lexical overlap with 1-hop graph expansion** — deliberately
+simple, and reported as such. The scores you see are exactly the scores
+computed; nothing is presented as semantic similarity.
+
+Ask it *who / what / when* questions ("who touched auth recently?", "which
+issue needed two attempts?") — that's what commit and PR history can answer.
+*How-does-it-work* questions need semantic retrieval over code and docs,
+which this deliberately simple demo does not pretend to do.
 
 ## Tracing your own agent
 
 The complete integration:
 
 ```python
-from graphsight_langgraph import LangGraphTracer, to_tracestate
+from graphsight_langgraph import LangGraphTracer, capture
 
 tracer = LangGraphTracer()
 result = graph.invoke(inputs, config={"callbacks": [tracer]})
 
-trace = tracer.finish(query="why is checkout failing?", answer=result["answer"])
-to_tracestate(trace)     # viewer-ready dict — json.dump it, then: graphsight trace.json
+capture(tracer, query="why is checkout failing?", answer=result["answer"])
+# -> .graphsight/20260725T071558_why-is-checkout-failing.json
 ```
 
+`capture()` finishes the trace and appends it to a local history directory
+(`./.graphsight/` by default, `$GRAPHSIGHT_DIR` to override) — browse every
+run with `graphsight .graphsight/`. For manual control use
+`tracer.finish()` + `to_tracestate()` / `save_trace()`; `trace.to_dict()`
+gives the framework-neutral `AgentTrace` for your own tooling.
+
+### Retrieved vs. used
+
+When you pass `answer=`, each retrieved item gets an `answer_overlap`
+score — the lexical overlap between the item's content and the final
+answer. In the viewer, items that surfaced in the answer render
+highlighted; items retrieved but unused render dimmed with the label
+*"retrieved, unused."* That splits the two classic retrieval failures at a
+glance:
+
+- **right doc retrieved, ignored by the model** → dimmed node with a high
+  retrieval score
+- **wrong doc trusted** → highlighted node that shouldn't be
+
+The overlap is a lexical heuristic (labeled as such, threshold 0.2) — it is
+never presented as a model-computed relevance judgment. No `answer=` → no
+usage claims; everything renders plain.
+
 ### Configuration propagation (read this once)
 
 LangChain only propagates callbacks into runnables that receive the run's
@@ -111,7 +140,9 @@ retrievals.
 | Name | Description |
 |---|---|
 | `LangGraphTracer()` | `BaseCallbackHandler` subclass. Pass via `config={"callbacks": [tracer]}` to `invoke` / `stream`. Reusable within a single run; create a fresh instance per run. |
-| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency. `query` falls back to the first retriever query seen. |
+| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency and per-item `answer_overlap`. `query` falls back to the first retriever query seen. |
+| `capture(tracer, query=None, answer=None, dir=None) -> Path` | `finish()` + save to the history directory in one call. |
+| `save_trace(trace, dir=None) -> Path` | Writes a finished trace to the history directory (`./.graphsight/` or `$GRAPHSIGHT_DIR`). |
 | `to_tracestate(trace) -> dict` | Maps an `AgentTrace` to the viewer's JSON contract. Serialize with `json.dump`. |
 | `trace.to_dict() -> dict` | The framework-neutral `AgentTrace` (schema v0.1) for your own tooling. |
 | `AgentTrace`, `Span`, `Retrieval`, `RetrievedItem`, `TraceEdge` | Plain dataclasses defining the schema; importable for custom emitters. |
@@ -127,6 +158,7 @@ retrievals.
 | `Document.metadata["edges"]` | relational edges, deduplicated per retrieval |
 | LLM / tool calls | plain spans in the execution timeline |
 | Edges present in a retrieval | `arm = "graph"`, else `"vector"` — detected automatically |
+| The final answer (when passed to `finish`/`capture`) | per-item `answer_overlap` — the retrieved-vs-used signal |
 
 ### Making your retriever graph-aware
 
@@ -165,14 +197,15 @@ else renders as `Document`).
   retriever and were not recomputed — an imported trace never masquerades
   as an engine-computed one.
 
-## Schema (v0.1)
+## Schema (v0.2)
 
 `AgentTrace` is the stable contract. Future adapters (LlamaIndex, raw
-OpenTelemetry) emit the same shape and render in the same viewer.
+OpenTelemetry) emit the same shape and render in the same viewer. v0.2 adds
+`RetrievedItem.answer_overlap` (additive — v0.1 traces stay valid).
 
 ```jsonc
 {
-  "schema_version": "0.1",
+  "schema_version": "0.2",
   "framework": "langgraph",
   "query": "…",
   "spans": [
@@ -186,6 +219,7 @@ OpenTelemetry) emit the same shape and render in the same viewer.
       "items": [
         { "id": "pr_4821", "label": "PR #4821", "kind": "pull_request",
           "score": 0.94, "vector_score": null, "graph_score": null,
+          "answer_overlap": 0.41,                             // null when no answer given
           "content": "…", "source_uri": "https://…", "metadata": {} }
       ],
       "edges": [                                            // optional — the relational view

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph/__init__.py

@@ -1,12 +1,14 @@
 """graphsight-langgraph — capture LangGraph runs as Graphsight traces.
 
-    from graphsight_langgraph import LangGraphTracer, to_tracestate
+    from graphsight_langgraph import LangGraphTracer, capture
 
     tracer = LangGraphTracer()
     result = graph.invoke(inputs, config={"callbacks": [tracer]})
-    trace = tracer.finish(query="...", answer=result.get("answer"))
-    studio_json = to_tracestate(trace)   # render in Graphsight Studio
+    capture(tracer, query="...", answer=result.get("answer"))  # -> .graphsight/
+
+Then browse every run: `graphsight .graphsight/`
 """
+from .capture import capture, save_trace
 from .mapper import to_tracestate
 from .schema import (
     SCHEMA_VERSION,
@@ -26,5 +28,7 @@ __all__ = [
     "RetrievedItem",
     "Span",
     "TraceEdge",
+    "capture",
+    "save_trace",
     "to_tracestate",
 ]

graphsight_langgraph-0.2.0/graphsight_langgraph/capture.py

@@ -0,0 +1,43 @@
+"""Local run history: save every finished trace, browse them all later
+with `graphsight .graphsight/`."""
+from __future__ import annotations
+
+import json
+import re
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Union
+
+from .mapper import to_tracestate
+from .schema import AgentTrace
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def _slug(text: str, limit: int = 40) -> str:
+    return _SLUG_RE.sub("-", text.lower()).strip("-")[:limit] or "run"
+
+
+def save_trace(trace: AgentTrace, dir: Union[str, Path, None] = None) -> Path:
+    """Write the trace to the history dir; returns the file path.
+
+    Default dir is $GRAPHSIGHT_DIR or ./.graphsight. Files are
+    <utc-timestamp>_<query-slug>.json in the viewer's TraceState format.
+    """
+    target = Path(dir or os.environ.get("GRAPHSIGHT_DIR") or ".graphsight")
+    target.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
+    path = target / f"{stamp}_{_slug(trace.query)}.json"
+    path.write_text(json.dumps(to_tracestate(trace), indent=2), encoding="utf-8")
+    return path
+
+
+def capture(
+    tracer,
+    query: Optional[str] = None,
+    answer: Optional[str] = None,
+    dir: Union[str, Path, None] = None,
+) -> Path:
+    """finish() + save_trace() in one call."""
+    return save_trace(tracer.finish(query=query, answer=answer), dir=dir)

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph/mapper.py

@@ -40,25 +40,44 @@ def to_tracestate(trace: AgentTrace) -> dict[str, Any]:
     """Return a TraceState-shaped dict ready for the Studio."""
     has_edges = any(r.edges for r in trace.retrievals)
 
+    # retrieved vs used: only meaningful when an answer + overlaps exist
+    has_usage = trace.answer is not None and any(
+        item.answer_overlap is not None for r in trace.retrievals for item in r.items
+    )
+    _USED = 0.2  # lexical-overlap threshold for "surfaced in the answer"
+
     # nodes
     nodes: list[dict[str, Any]] = []
     seen_nodes: set[str] = set()
+    used_ids: set[str] = set()
     for retrieval in trace.retrievals:
         for item in retrieval.items:
             if item.id in seen_nodes:
                 continue
             seen_nodes.add(item.id)
+            if has_usage:
+                used = (item.answer_overlap or 0.0) >= _USED
+                subtitle = (
+                    f"in the answer · via {trace.framework}"
+                    if used
+                    else f"retrieved, unused · via {trace.framework}"
+                )
+            else:
+                used = True  # no answer to compare against — show everything plain
+                subtitle = f"via {trace.framework} · {retrieval.arm} arm"
+            if used:
+                used_ids.add(item.id)
             nodes.append(
                 {
                     "id": item.id,
                     "label": item.label,
                     "type": _KIND_TO_ENTITY.get(item.kind.lower().strip(), "Document"),
-                    "active": True,  # everything retrieved was selected
+                    "active": used,  # unused retrievals render dimmed
                     "position": {"x": 0, "y": 0},  # Studio re-layouts with dagre
                     "similarity": item.vector_score,
                     "score": item.score,
                     "meta": {
-                        "subtitle": f"via {trace.framework} · {retrieval.arm} arm",
+                        "subtitle": subtitle,
                         "snippet": (item.content or "")[:600] or None,
                         "scoreGraph": item.graph_score,
                         "sourceUrl": item.source_uri,
@@ -78,7 +97,7 @@ def to_tracestate(trace: AgentTrace) -> dict[str, Any]:
                     "source": edge.source,
                     "target": edge.target,
                     "confidence": edge.weight if edge.weight is not None else 0.7,
-                    "active": True,
+                    "active": edge.source in used_ids and edge.target in used_ids,
                     "relation": edge.relation,
                 }
             )

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph/schema.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field, asdict
 from typing import Any, Literal, Optional
 
-SCHEMA_VERSION = "0.1"
+SCHEMA_VERSION = "0.2"  # 0.2 adds RetrievedItem.answer_overlap (additive)
 
 SpanKind = Literal["node", "retriever", "llm", "tool"]
 Arm = Literal["vector", "graph", "hybrid", "unknown"]
@@ -37,6 +37,9 @@ class RetrievedItem:
     content: Optional[str] = None
     source_uri: Optional[str] = None
     metadata: dict[str, Any] = field(default_factory=dict)
+    # lexical overlap between this item and the final answer (0..1);
+    # None when no answer was given. A heuristic, labeled as such.
+    answer_overlap: Optional[float] = None
 
 
 @dataclass

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph/tracer.py

@@ -7,6 +7,7 @@ won't reach the tracer (see README).
 from __future__ import annotations
 
 import hashlib
+import re
 import time
 from typing import Any, Optional
 from uuid import UUID
@@ -20,6 +21,27 @@ _SCORE_KEYS = ("score", "relevance_score", "similarity", "_score", "vector_score
 # LangGraph internals that fire chain events but aren't user nodes
 _NOISE_NAMES = {"LangGraph", "RunnableSequence", "RunnableCallable", "ChannelWrite", "__start__", "__end__"}
 
+_WORD_RE = re.compile(r"[a-z0-9][a-z0-9_#-]{2,}")
+_STOP = {
+    "the", "and", "for", "that", "this", "with", "from", "was", "were", "are",
+    "has", "have", "not", "but", "its", "also", "into", "over", "after",
+}
+
+
+def _tokens(text: str) -> set[str]:
+    return {w for w in _WORD_RE.findall(text.lower()) if w not in _STOP}
+
+
+def _answer_overlap(answer_tokens: set[str], content: Optional[str]) -> Optional[float]:
+    # lexical heuristic: how much of the item's vocabulary reached the answer
+    if not answer_tokens or not content:
+        return None
+    item_tokens = _tokens(content)
+    if not item_tokens:
+        return None
+    shared = len(answer_tokens & item_tokens)
+    return round(shared / min(len(item_tokens), len(answer_tokens)), 3)
+
 
 def _doc_id(doc: Document) -> str:
     for key in ("id", "node_id", "doc_id"):
@@ -233,6 +255,12 @@ class LangGraphTracer(BaseCallbackHandler):
                 span.end_ms = self._now_ms()
                 span.status = "ok" if span.status == "running" else span.status
         latency = max((s.end_ms or 0.0) for s in spans) if spans else None
+        if answer:
+            # retrieved vs used: which items actually surfaced in the answer
+            answer_tokens = _tokens(answer)
+            for retrieval in self._retrievals:
+                for item in retrieval.items:
+                    item.answer_overlap = _answer_overlap(answer_tokens, item.content)
         return AgentTrace(
             query=query or self._first_query or "",
             spans=spans,

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.1.3
+Version: 0.2.0
 Summary: X-ray for LangGraph retrieval: one callback handler captures every retriever call, score, and relational path — rendered as an interactive graph.
 Author: Arush Karnatak
 License: MIT
@@ -94,29 +94,58 @@ graphsight-github-trace REPO [QUESTION] [options]
 | `--token` | `$GITHUB_TOKEN` | GitHub token. Required for private repositories; raises the rate limit on public ones. |
 | `--prs` | `25` | Recent pull requests to fetch. |
 | `--issues` | `25` | Recent issues to fetch. |
+| `--commits` | `25` | Recent commits to fetch — solo repos with no PRs/issues still produce a full graph. |
 | `--top` | `10` | Items the retrieval keeps. |
 | `--out` | `graphsight_out/` | Output directory for `agent_trace.json` and `trace_state.json`. |
 
 Method note: the CLI builds a corpus with relational edges
-(`person AUTHORED pr`, `pr RESOLVES issue`, `pr TOUCHES repo`) and ranks by
-**lexical overlap with 1-hop graph expansion** — deliberately simple, and
-reported as such. The scores you see are exactly the scores computed;
-nothing is presented as semantic similarity.
+(`person AUTHORED pr/commit`, `pr RESOLVES issue`, `pr TOUCHES repo`) and
+ranks by **lexical overlap with 1-hop graph expansion** — deliberately
+simple, and reported as such. The scores you see are exactly the scores
+computed; nothing is presented as semantic similarity.
+
+Ask it *who / what / when* questions ("who touched auth recently?", "which
+issue needed two attempts?") — that's what commit and PR history can answer.
+*How-does-it-work* questions need semantic retrieval over code and docs,
+which this deliberately simple demo does not pretend to do.
 
 ## Tracing your own agent
 
 The complete integration:
 
 ```python
-from graphsight_langgraph import LangGraphTracer, to_tracestate
+from graphsight_langgraph import LangGraphTracer, capture
 
 tracer = LangGraphTracer()
 result = graph.invoke(inputs, config={"callbacks": [tracer]})
 
-trace = tracer.finish(query="why is checkout failing?", answer=result["answer"])
-to_tracestate(trace)     # viewer-ready dict — json.dump it, then: graphsight trace.json
+capture(tracer, query="why is checkout failing?", answer=result["answer"])
+# -> .graphsight/20260725T071558_why-is-checkout-failing.json
 ```
 
+`capture()` finishes the trace and appends it to a local history directory
+(`./.graphsight/` by default, `$GRAPHSIGHT_DIR` to override) — browse every
+run with `graphsight .graphsight/`. For manual control use
+`tracer.finish()` + `to_tracestate()` / `save_trace()`; `trace.to_dict()`
+gives the framework-neutral `AgentTrace` for your own tooling.
+
+### Retrieved vs. used
+
+When you pass `answer=`, each retrieved item gets an `answer_overlap`
+score — the lexical overlap between the item's content and the final
+answer. In the viewer, items that surfaced in the answer render
+highlighted; items retrieved but unused render dimmed with the label
+*"retrieved, unused."* That splits the two classic retrieval failures at a
+glance:
+
+- **right doc retrieved, ignored by the model** → dimmed node with a high
+  retrieval score
+- **wrong doc trusted** → highlighted node that shouldn't be
+
+The overlap is a lexical heuristic (labeled as such, threshold 0.2) — it is
+never presented as a model-computed relevance judgment. No `answer=` → no
+usage claims; everything renders plain.
+
 ### Configuration propagation (read this once)
 
 LangChain only propagates callbacks into runnables that receive the run's
@@ -138,7 +167,9 @@ retrievals.
 | Name | Description |
 |---|---|
 | `LangGraphTracer()` | `BaseCallbackHandler` subclass. Pass via `config={"callbacks": [tracer]}` to `invoke` / `stream`. Reusable within a single run; create a fresh instance per run. |
-| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency. `query` falls back to the first retriever query seen. |
+| `tracer.finish(query=None, answer=None) -> AgentTrace` | Assembles the trace after the run: closes dangling spans, computes total latency and per-item `answer_overlap`. `query` falls back to the first retriever query seen. |
+| `capture(tracer, query=None, answer=None, dir=None) -> Path` | `finish()` + save to the history directory in one call. |
+| `save_trace(trace, dir=None) -> Path` | Writes a finished trace to the history directory (`./.graphsight/` or `$GRAPHSIGHT_DIR`). |
 | `to_tracestate(trace) -> dict` | Maps an `AgentTrace` to the viewer's JSON contract. Serialize with `json.dump`. |
 | `trace.to_dict() -> dict` | The framework-neutral `AgentTrace` (schema v0.1) for your own tooling. |
 | `AgentTrace`, `Span`, `Retrieval`, `RetrievedItem`, `TraceEdge` | Plain dataclasses defining the schema; importable for custom emitters. |
@@ -154,6 +185,7 @@ retrievals.
 | `Document.metadata["edges"]` | relational edges, deduplicated per retrieval |
 | LLM / tool calls | plain spans in the execution timeline |
 | Edges present in a retrieval | `arm = "graph"`, else `"vector"` — detected automatically |
+| The final answer (when passed to `finish`/`capture`) | per-item `answer_overlap` — the retrieved-vs-used signal |
 
 ### Making your retriever graph-aware
 
@@ -192,14 +224,15 @@ else renders as `Document`).
   retriever and were not recomputed — an imported trace never masquerades
   as an engine-computed one.
 
-## Schema (v0.1)
+## Schema (v0.2)
 
 `AgentTrace` is the stable contract. Future adapters (LlamaIndex, raw
-OpenTelemetry) emit the same shape and render in the same viewer.
+OpenTelemetry) emit the same shape and render in the same viewer. v0.2 adds
+`RetrievedItem.answer_overlap` (additive — v0.1 traces stay valid).
 
 ```jsonc
 {
-  "schema_version": "0.1",
+  "schema_version": "0.2",
   "framework": "langgraph",
   "query": "…",
   "spans": [
@@ -213,6 +246,7 @@ OpenTelemetry) emit the same shape and render in the same viewer.
       "items": [
         { "id": "pr_4821", "label": "PR #4821", "kind": "pull_request",
           "score": 0.94, "vector_score": null, "graph_score": null,
+          "answer_overlap": 0.41,                             // null when no answer given
           "content": "…", "source_uri": "https://…", "metadata": {} }
       ],
       "edges": [                                            // optional — the relational view

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/graphsight_langgraph.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 graphsight_langgraph/__init__.py
+graphsight_langgraph/capture.py
 graphsight_langgraph/github_ingest.py
 graphsight_langgraph/mapper.py
 graphsight_langgraph/schema.py

{graphsight_langgraph-0.1.3 → graphsight_langgraph-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphsight-langgraph"
-version = "0.1.3"
+version = "0.2.0"
 description = "X-ray for LangGraph retrieval: one callback handler captures every retriever call, score, and relational path — rendered as an interactive graph."
 readme = "README.md"
 requires-python = ">=3.10"