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

{graphsight_langgraph-0.2.0 → graphsight_langgraph-0.3.1}/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.2.0 → graphsight_langgraph-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -31,10 +31,13 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/graphsight-langgraph/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/Kcodess2807/graphsight/blob/main/graphsight-langgraph/LICENSE)
 
-**See exactly why your LangGraph agent picked the context it picked.**
+**See which retrieved documents your agent actually used — and which it ignored.**
+
+Retrieval in an agent is a black box: twelve documents go in, an answer comes
+out, and when the answer is wrong you're left guessing which context misled
+it. The nine documents the model ignored still cost you tokens, latency, and
+a wider surface to go wrong on — and nothing tells you which nine.
 
-Retrieval in an agent is a black box: documents go in, an answer comes out,
-and when the answer is wrong you're left guessing which context misled it.
 This package opens the box. One callback handler records a
 [LangGraph](https://github.com/langchain-ai/langgraph) run — every node,
 every retriever call, per-document scores, and (for graph-aware retrievers)
@@ -42,13 +45,18 @@ the relational paths between retrieved entities — and one command renders it
 as an interactive graph in your browser.
 
 ```
-your LangGraph agent ──▶ LangGraphTracer ──▶ AgentTrace (v0.1) ──▶ graphsight viewer
+your LangGraph agent ──▶ LangGraphTracer ──▶ AgentTrace (v0.2) ──▶ graphsight viewer
                           (callbacks)         neutral JSON          interactive graph
 ```
 
 Only dependency: `langchain-core`. No engine, no backend, no account —
 nothing leaves your machine.
 
+![Graphsight showing a retrieved-but-unused document](https://raw.githubusercontent.com/Kcodess2807/graphsight/main/docs/media/retrieved-vs-used.gif)
+
+*A real run. `PR #101` scored **0.910** — the highest of anything retrieved — and the answer
+never used it. `PR #412` scored **0.340** and is the one that answered.*
+
 ## Installation
 
 ```bash
@@ -64,8 +72,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
 
@@ -171,7 +179,7 @@ retrievals.
 | `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. |
+| `trace.to_dict() -> dict` | The framework-neutral `AgentTrace` (schema v0.2) for your own tooling. |
 | `AgentTrace`, `Span`, `Retrieval`, `RetrievedItem`, `TraceEdge` | Plain dataclasses defining the schema; importable for custom emitters. |
 
 ## What gets captured
@@ -214,6 +222,15 @@ Document(
 `repo → Repo`, `library → Library`, `team → Team`, `tool → Tool`; anything
 else renders as `Document`).
 
+> **Both endpoints must be retrieved items.** The viewer can only draw an edge
+> between two nodes it has, so an edge pointing at something you didn't return
+> — `{"source": "person_vishal", "target": "pr_412"}` when no document has
+> `id: "person_vishal"` — is dropped from the rendered graph. (It is preserved
+> in `AgentTrace`, so your own tooling still sees it.) If you want people,
+> services or tickets on the canvas, **return them as documents too**, each
+> with its own `id`, `label` and `kind`. A retriever that emits only PRs and
+> then links them to authors will render a flat graph with no edges at all.
+
 ### Degradation behavior
 
 - **No edges in metadata** → a flat scored-retrieval view instead of
@@ -265,7 +282,7 @@ OpenTelemetry) emit the same shape and render in the same viewer. v0.2 adds
 |---|---|
 | Node spans but no retrievals | Config not propagated into the node's sub-runnables — see [Configuration propagation](#configuration-propagation-read-this-once). |
 | Items without scores | Your retriever doesn't write a recognized score key to `Document.metadata` — add one (`score` is simplest). |
-| Flat graph, no edges | Your retriever doesn't emit `metadata["edges"]` — see [Making your retriever graph-aware](#making-your-retriever-graph-aware). |
+| Flat graph, no edges | Either your retriever doesn't emit `metadata["edges"]`, or the edges point at ids you never returned as documents — both endpoints must be retrieved items. See [Making your retriever graph-aware](#making-your-retriever-graph-aware). |
 | `GitHub API 403` from the CLI | Rate limit (60 requests/hour unauthenticated) — pass `--token` or set `GITHUB_TOKEN`. |
 | Garbled output on Windows consoles | Fixed in ≥ 0.1.1; upgrade. |