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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.3.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
@@ -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. |
 

{graphsight_langgraph-0.3.0 → graphsight_langgraph-0.3.1}/README.md

@@ -4,10 +4,13 @@
 [![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)
@@ -15,13 +18,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
@@ -144,7 +152,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
@@ -187,6 +195,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
@@ -238,7 +255,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. |
 

{graphsight_langgraph-0.3.0 → graphsight_langgraph-0.3.1}/graphsight_langgraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight-langgraph
-Version: 0.3.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
@@ -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. |
 

{graphsight_langgraph-0.3.0 → graphsight_langgraph-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphsight-langgraph"
-version = "0.3.0"
+version = "0.3.1"
 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"