graphsight-langgraph 0.1.4__tar.gz → 0.3.0__tar.gz

{graphsight_langgraph-0.1.4 → graphsight_langgraph-0.3.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Arush Karnatak
-
-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.
+MIT License
+
+Copyright (c) 2026 Arush Karnatak
+
+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.

{graphsight_langgraph-0.1.4 → graphsight_langgraph-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.1.4
+Version: 0.3.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
@@ -64,8 +64,8 @@ pip install graphsight                      # the local viewer (recommended)
 | Python | ≥ 3.10 |
 | `langchain-core` | ≥ 0.3 (verified against 1.5.0) |
 | `langgraph` | any recent version; only needed for the `[example]` extra |
-| Sync (`invoke` / `stream`) | verified |
-| Async (`ainvoke` / `astream`) | same callback events; not yet covered by the verification run |
+| Sync (`invoke` / `stream`) | verified, covered by the test suite |
+| Async (`ainvoke` / `astream`) | verified, covered by the test suite |
 
 ## Quickstart: trace a GitHub repo in 60 seconds
 
@@ -114,15 +114,38 @@ which this deliberately simple demo does not pretend to do.
 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
@@ -144,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. |
@@ -160,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
 
@@ -198,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": [
@@ -219,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