graphsight 0.3.1__tar.gz → 0.3.3__tar.gz

{graphsight-0.3.1 → graphsight-0.3.3}/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-0.3.1 → graphsight-0.3.3}/MANIFEST.in

@@ -1,2 +1,2 @@
-recursive-include graphsight/dist *
-include LICENSE
+recursive-include graphsight/dist *
+include LICENSE

{graphsight-0.3.1/graphsight.egg-info → graphsight-0.3.3}/PKG-INFO

@@ -1,204 +1,236 @@
-Metadata-Version: 2.4
-Name: graphsight
-Version: 0.3.1
-Summary: See why your AI agent retrieved what it did — interactive graph viewer for agent retrieval traces. One command, zero dependencies, nothing leaves your machine.
-Author: Arush Karnatak
-License: MIT
-Project-URL: Repository, https://github.com/Kcodess2807/graphsight
-Project-URL: Documentation, https://github.com/Kcodess2807/graphsight/tree/main/graphsight
-Keywords: tracing,observability,rag,retrieval,agents,visualization,langgraph
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Debuggers
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# graphsight
-
-[![PyPI](https://img.shields.io/pypi/v/graphsight.svg)](https://pypi.org/project/graphsight/)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/graphsight/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/Kcodess2807/graphsight/blob/main/graphsight/LICENSE)
-
-**See which retrieved documents your agent actually used — and which it ignored.**
-
-Your agent answered a question. Which documents did it actually pull? Which
-of those did the answer come from? What scores did they get, and how are they
-connected? Most stacks make you dig through logs. Graphsight renders the run
-as an **interactive graph in your browser** — one command, zero dependencies,
-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.*
-
-```bash
-pip install graphsight
-graphsight path/to/trace_state.json
-```
-
-## Retrieved vs. used
-
-The signal that isn't in your logs. When a trace carries the final answer,
-every retrieved item is scored by lexical overlap against it and rendered
-either **highlighted** (surfaced in the answer) or **dimmed** with the label
-*"retrieved, unused."* That splits the two classic retrieval failures at a
-glance:
-
-- **Right document retrieved, ignored by the model** → a dimmed node with a
-  high retrieval score. Your retriever worked; your prompt or context order
-  didn't.
-- **Wrong document trusted** → a highlighted node that shouldn't be.
-
-The overlap is a lexical heuristic, labeled as such (threshold 0.2). No LLM
-re-reads your evidence, and no score is invented — a trace with no answer
-attached makes no usage claims at all.
-
-## What else you get
-
-- **Every retrieved item as a typed node** — PR, Service, Person, Ticket,
-  Document, Repo, Library, Team, Tool — with its retrieval score.
-- **Relational paths between results** — *person → authored → PR →
-  resolves → issue* — the chain of evidence, not just a ranked list.
-- **An inspector on every node**: underlying content, score, source link.
-- **The execution timeline** of the run: each agent step, each retriever
-  call, per-span timings, and which retrieval arm (vector / graph) produced
-  the results.
-
-## Requirements
-
-| | |
-|---|---|
-| Python | ≥ 3.10 |
-| Runtime dependencies | **none** (stdlib only) |
-| Platforms | Windows, macOS, Linux |
-| Browser | any modern browser |
-
-## Usage
-
-```
-graphsight [trace] [--port PORT] [--no-browser]
-```
-
-| Argument | Default | Description |
-|---|---|---|
-| `trace` | — | A `trace_state.json` file, **or a directory of them** (e.g. `.graphsight/`) to browse run history. Optional — omit to open the import page and drag-and-drop or paste JSON instead. |
-| `--port` | `4630` | Local port to serve on. |
-| `--no-browser` | off | Start the server without opening a browser window. |
-
-The server binds to `127.0.0.1` only and runs until you press `Ctrl+C`.
-
-## Run history
-
-Point `graphsight` at a directory and it becomes a run browser — every
-trace listed by query and time, one click to open:
-
-```bash
-graphsight .graphsight/
-```
-
-The [graphsight-langgraph](https://pypi.org/project/graphsight-langgraph/)
-`capture()` helper appends every agent run there automatically, so your
-debugging history accumulates with zero ceremony — no setup, no database.
-
-Because the history is a directory of plain files, you can **compare two
-runs side by side**: what the retrieval returned before a prompt change and
-after it, which items appeared or vanished, and which flipped between used
-and ignored. That is usually the fastest way to answer "what did my edit
-actually do to retrieval?"
-
-## Sharing traces with your team
-
-A trace is one self-contained JSON file — no account or backend needed to
-share it:
-
-- **Send the file.** A teammate with `graphsight` installed runs
-  `graphsight trace.json`. Works in a DM, a ticket attachment, a CI
-  artifact.
-- **Link it.** A deployed Graphsight frontend opens any publicly reachable
-  trace via `…/memory/import?src=<url-to-json>` — host the JSON on a gist
-  or artifact store and share the link. (The host must allow cross-origin
-  GETs; raw gists do.)
-- **Commit it.** Trace files in the repo next to the incident or PR they
-  explain make retrieval debugging part of the review record.
-
-## Producing traces
-
-Graphsight renders any file matching its trace JSON contract. Current
-producers:
-
-- **[graphsight-langgraph](https://pypi.org/project/graphsight-langgraph/)** —
-  instrument any [LangGraph](https://github.com/langchain-ai/langgraph)
-  agent with a single callback handler, or trace a GitHub repository in one
-  command:
-
-  ```bash
-  pip install "graphsight-langgraph[example]"
-  graphsight-github-trace langchain-ai/langgraph "who fixed the recent streaming bugs?"
-  graphsight graphsight_out/trace_state.json
-  ```
-
-- **The Graphsight graph-memory engine** — the backend this project grew out
-  of: GitHub events become a live knowledge graph with typed, timestamped
-  edges (`AUTHORED`, `RESOLVES`, `TOUCHES`), queried by a hybrid
-  vector + graph router. Its `/api/trace` responses are the same shape. See
-  the [main repository](https://github.com/Kcodess2807/graphsight).
-
-Adapters for LlamaIndex and raw OpenTelemetry spans are planned; all
-producers emit the same schema and render in this same viewer.
-
-### Writing your own producer
-
-The minimum contract is small — a JSON object with:
-
-```jsonc
-{
-  "query": "the question that was asked",          // required, string
-  "graph": {
-    "nodes": [{ "id", "label", "type", "score", "meta": { "snippet", "sourceUrl" } }],
-    "edges": [{ "id", "source", "target", "relation", "confidence" }]
-  },
-  "steps":   [ /* execution timeline, optional */ ],
-  "metrics": { "queryTimeSec": 0.004 }             // optional
-}
-```
-
-Node positions are computed client-side; emitters never deal with layout.
-The complete schema and a reference emitter live in the
-[graphsight-langgraph source](https://github.com/Kcodess2807/graphsight/tree/main/graphsight-langgraph).
-
-## Security and privacy
-
-- The dependency list is empty by design: the UI is a bundled static build
-  (Vite + React + React Flow) served by Python's stdlib `http.server`.
-- Binds to `127.0.0.1` — not reachable from other machines.
-- No accounts, no telemetry, no outbound network calls. Your traces stay on
-  your disk.
-
-## Troubleshooting
-
-| Symptom | Cause / fix |
-|---|---|
-| `Address already in use` | Another process holds the port — pass `--port 4631`. |
-| Browser doesn't open | Some environments (SSH, WSL, containers) can't launch one — start with `--no-browser` and open the printed URL yourself. |
-| `Bundled UI missing` error | Broken installation — `pip install --force-reinstall graphsight`. |
-| Page loads but trace doesn't | The JSON didn't match the contract — the import page shows the specific validation error. |
-
-## Links
-
-- Source & issue tracker: [github.com/Kcodess2807/graphsight](https://github.com/Kcodess2807/graphsight)
-- LangGraph adapter: [graphsight-langgraph on PyPI](https://pypi.org/project/graphsight-langgraph/)
-- Beta test script: [BETA.md](https://github.com/Kcodess2807/graphsight/blob/main/BETA.md)
-
-## License
-
-MIT © Arush Karnatak
+Metadata-Version: 2.4
+Name: graphsight
+Version: 0.3.3
+Summary: See why your AI agent retrieved what it did — interactive graph viewer for agent retrieval traces. One command, zero dependencies, nothing leaves your machine.
+Author: Arush Karnatak
+License: MIT
+Project-URL: Repository, https://github.com/Kcodess2807/graphsight
+Project-URL: Documentation, https://github.com/Kcodess2807/graphsight/tree/main/graphsight
+Keywords: tracing,observability,rag,retrieval,agents,visualization,langgraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# graphsight
+
+[![PyPI](https://img.shields.io/pypi/v/graphsight.svg)](https://pypi.org/project/graphsight/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/graphsight/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/Kcodess2807/graphsight/blob/main/graphsight/LICENSE)
+
+**See which retrieved documents your agent actually used, and which it ignored.**
+
+Your agent answered a question. Which documents did it actually pull? Which
+of those did the answer come from? What scores did they get, and how are they
+connected? Most stacks make you dig through logs. Graphsight renders the run
+as an **interactive graph in your browser**, one command, zero dependencies,
+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.*
+
+**Jump to:** [start here](#start-here) ·
+[retrieved vs. used](#retrieved-vs-used) ·
+[usage](#usage) ·
+[producing traces](#producing-traces) ·
+[troubleshooting](#troubleshooting)
+
+## Start here
+
+**New to Graphsight? Read [Your first trace](https://github.com/Kcodess2807/graphsight/blob/main/docs/FIRST_TRACE.md)**,
+a 10-minute walkthrough with a complete runnable example.
+
+`graphsight` is the **viewer**. It needs a trace to open, and the tracer is a separate
+package, so the full path from nothing is three steps:
+
+```bash
+pip install graphsight graphsight-langgraph
+```
+
+```python
+from graphsight_langgraph import LangGraphTracer, capture
+
+tracer = LangGraphTracer()
+result = graph.invoke(inputs, config={"callbacks": [tracer]})
+capture(tracer, query="why is checkout failing?", answer=result["answer"])
+```
+
+```bash
+graphsight .graphsight/          # opens every run you've captured
+```
+
+Passing `answer=` is what unlocks the used/ignored split below. Without it, every item
+renders plain and no usage is claimed.
+
+**Already have a trace file?** `graphsight path/to/trace_state.json` opens it directly.
+**Want to see it work before writing any code?** `graphsight-github-trace` builds a real
+trace from any public GitHub repo, see [Producing traces](#producing-traces).
+
+## Retrieved vs. used
+
+The signal that isn't in your logs. When a trace carries the final answer,
+every retrieved item is scored by lexical overlap against it and rendered
+either **highlighted** (*"overlaps the answer"*) or **dimmed** (*"no lexical
+trace in answer"*). The label states what was measured rather than what it
+implies, because a chunk the model used as a negative constraint leaves no
+words behind. Read that way, it splits the two classic retrieval failures at a
+glance:
+
+- **Right document retrieved, ignored by the model** → a dimmed node with a
+  high retrieval score. Your retriever worked; your prompt or context order
+  didn't.
+- **Wrong document trusted** → a highlighted node that shouldn't be.
+
+The overlap is a lexical heuristic, labeled as such (threshold 0.2). No LLM
+re-reads your evidence, and no score is invented. A trace with no answer
+attached makes no usage claims at all.
+
+## What else you get
+
+- **Every retrieved item as a typed node**, PR, Service, Person, Ticket,
+  Document, Repo, Library, Team, Tool, with its retrieval score.
+- **Relational paths between results**, *person → authored → PR →
+  resolves → issue*, the chain of evidence, not just a ranked list.
+- **An inspector on every node**: underlying content, score, source link.
+- **The question and the answer**, with every node marked as overlapping the
+  answer or not.
+
+## Requirements
+
+| | |
+|---|---|
+| Python | ≥ 3.10 |
+| Runtime dependencies | **none** (stdlib only) |
+| Platforms | Windows, macOS, Linux |
+| Browser | any modern browser |
+
+## Usage
+
+```
+graphsight [trace] [--port PORT] [--no-browser]
+```
+
+| Argument | Default | Description |
+|---|---|---|
+| `trace` | none | A `trace_state.json` file, **or a directory of them** (e.g. `.graphsight/`) to browse run history. Optional, omit to open the import page and drag-and-drop or paste JSON instead. |
+| `--port` | `4630` | Local port to serve on. |
+| `--no-browser` | off | Start the server without opening a browser window. |
+
+The server binds to `127.0.0.1` only and runs until you press `Ctrl+C`.
+
+## Run history
+
+Point `graphsight` at a directory and it becomes a run browser, every
+trace listed by query and time, one click to open:
+
+```bash
+graphsight .graphsight/
+```
+
+The [graphsight-langgraph](https://pypi.org/project/graphsight-langgraph/)
+`capture()` helper appends every agent run there automatically, so your
+debugging history accumulates with zero ceremony, no setup, no database.
+
+Because the history is a directory of plain files, you can **compare two
+runs side by side**: what the retrieval returned before a prompt change and
+after it, which items appeared or vanished, and which flipped between used
+and ignored. That is usually the fastest way to answer "what did my edit
+actually do to retrieval?"
+
+## Sharing traces with your team
+
+A trace is one self-contained JSON file, no account or backend needed to
+share it:
+
+- **Send the file.** A teammate with `graphsight` installed runs
+  `graphsight trace.json`. Works in a DM, a ticket attachment, a CI
+  artifact.
+- **Link it.** A deployed Graphsight frontend opens any publicly reachable
+  trace via `…/memory/import?src=<url-to-json>`, host the JSON on a gist
+  or artifact store and share the link. (The host must allow cross-origin
+  GETs; raw gists do.)
+- **Commit it.** Trace files in the repo next to the incident or PR they
+  explain make retrieval debugging part of the review record.
+
+## Producing traces
+
+Graphsight renders any file matching its trace JSON contract. Current
+producers:
+
+- **[graphsight-langgraph](https://pypi.org/project/graphsight-langgraph/)**
+  instruments any [LangGraph](https://github.com/langchain-ai/langgraph)
+  agent with a single callback handler, or trace a GitHub repository in one
+  command:
+
+  ```bash
+  pip install "graphsight-langgraph[example]"
+  graphsight-github-trace langchain-ai/langgraph "who fixed the recent streaming bugs?"
+  graphsight graphsight_out/trace_state.json
+  ```
+
+- **The Graphsight graph-memory engine**, the backend this project grew out
+  of: GitHub PRs, issues, and commits become a knowledge graph with typed, timestamped
+  edges (`AUTHORED`, `RESOLVES`, `TOUCHES`), queried by a hybrid
+  vector + graph router. Its `/api/trace` responses are the same shape. See
+  the [main repository](https://github.com/Kcodess2807/graphsight).
+
+Adapters for LlamaIndex and raw OpenTelemetry spans are planned; all
+producers emit the same schema and render in this same viewer.
+
+### Writing your own producer
+
+The minimum contract is small, a JSON object with:
+
+```jsonc
+{
+  "query": "the question that was asked",          // required, string
+  "graph": {
+    "nodes": [{ "id", "label", "type", "score", "meta": { "snippet", "sourceUrl" } }],
+    "edges": [{ "id", "source", "target", "relation", "confidence" }]
+  },
+  "metrics": { "queryTimeSec": 0.004 }             // optional
+}
+```
+
+Node positions are computed client-side; emitters never deal with layout.
+The complete schema and a reference emitter live in the
+[graphsight-langgraph source](https://github.com/Kcodess2807/graphsight/tree/main/graphsight-langgraph).
+
+## Security and privacy
+
+- The dependency list is empty by design: the UI is a bundled static build
+  (Vite + React + React Flow) served by Python's stdlib `http.server`.
+- Binds to `127.0.0.1`, not reachable from other machines.
+- No accounts, no telemetry, no outbound network calls. Your traces stay on
+  your disk.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `Address already in use` | Another process holds the port, pass `--port 4631`. |
+| Browser doesn't open | Some environments (SSH, WSL, containers) can't launch one, start with `--no-browser` and open the printed URL yourself. |
+| `Bundled UI missing` error | Broken installation, `pip install --force-reinstall graphsight`. |
+| Page loads but trace doesn't | The JSON didn't match the contract, the import page shows the specific validation error. |
+
+## Links
+
+- Source & issue tracker: [github.com/Kcodess2807/graphsight](https://github.com/Kcodess2807/graphsight)
+- LangGraph adapter: [graphsight-langgraph on PyPI](https://pypi.org/project/graphsight-langgraph/)
+- Beta test script: [BETA.md](https://github.com/Kcodess2807/graphsight/blob/main/BETA.md)
+
+## License
+
+MIT © Arush Karnatak