graphsight 0.2.0__tar.gz → 0.3.1__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphsight
-Version: 0.2.0
+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
@@ -28,20 +28,42 @@ Dynamic: license-file
 [![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 exactly why your AI agent retrieved what it did.**
+**See which retrieved documents your agent actually used — and which it ignored.**
 
-Your agent answered a question. Which documents did it actually pull? What
-scores did they get? How are they connected to each other? Most stacks make
-you dig through logs to answer that. Graphsight renders the run as an
-**interactive graph in your browser** — one command, zero dependencies,
+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
 ```
 
-## What you get
+## 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.
@@ -86,10 +108,13 @@ 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. Traces render with the
-**retrieved vs. used** split: items that surfaced in the answer highlighted,
-items retrieved but ignored dimmed — the two classic retrieval failures,
-visible at a glance.
+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
 
@@ -122,8 +147,11 @@ producers:
   graphsight graphsight_out/trace_state.json
   ```
 
-- **The TraceRAG engine** — the graph-memory backend this project grew out
-  of; its `/api/trace` responses are the same shape.
+- **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.

{graphsight-0.2.0 → graphsight-0.3.1}/README.md

@@ -1,152 +1,180 @@
-# 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 exactly why your AI agent retrieved what it did.**
-
-Your agent answered a question. Which documents did it actually pull? What
-scores did they get? How are they connected to each other? Most stacks make
-you dig through logs to answer that. Graphsight renders the run as an
-**interactive graph in your browser** — one command, zero dependencies,
-nothing leaves your machine.
-
-```bash
-pip install graphsight
-graphsight path/to/trace_state.json
-```
-
-## What 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. Traces render with the
-**retrieved vs. used** split: items that surfaced in the answer highlighted,
-items retrieved but ignored dimmed — the two classic retrieval failures,
-visible at a glance.
-
-## 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 TraceRAG engine** — the graph-memory backend this project grew out
-  of; its `/api/trace` responses are the same shape.
-
-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
+# 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

{graphsight-0.2.0 → graphsight-0.3.1}/graphsight/__init__.py

@@ -1,11 +1,11 @@
-"""graphsight — local viewer for agent retrieval traces.
-
-Usage:
-
-    graphsight path/to/trace_state.json
-
-Serves the bundled Graphsight Studio UI locally and opens the trace in the
-browser. No backend, no accounts, no network calls beyond localhost.
-"""
-
-__version__ = "0.2.0"
+"""graphsight — local viewer for agent retrieval traces.
+
+Usage:
+
+    graphsight path/to/trace_state.json
+
+Serves the bundled Graphsight Studio UI locally and opens the trace in the
+browser. No backend, no accounts, no network calls beyond localhost.
+"""
+
+__version__ = "0.3.1"

{graphsight-0.2.0 → graphsight-0.3.1}/graphsight/cli.py

@@ -1,66 +1,66 @@
-"""graphsight CLI — open a trace (or a whole run history) in the bundled UI."""
-from __future__ import annotations
-
-import argparse
-import sys
-import webbrowser
-from pathlib import Path
-from typing import Optional
-
-from .server import RUNS_ROUTE, TRACE_ROUTE, make_server
-
-
-def main(argv: Optional[list[str]] = None) -> None:
-    for stream in (sys.stdout, sys.stderr):
-        try:
-            stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
-        except (AttributeError, OSError):
-            pass
-
-    parser = argparse.ArgumentParser(
-        prog="graphsight",
-        description="Open a trace_state.json — or a history directory like .graphsight/ — in your browser.",
-    )
-    parser.add_argument("trace", nargs="?", type=Path,
-                        help="a trace_state.json, or a directory of them (e.g. .graphsight/); "
-                             "omit to open the import page")
-    parser.add_argument("--port", type=int, default=4630, help="port to serve on (default 4630)")
-    parser.add_argument("--no-browser", action="store_true", help="don't open the browser")
-    args = parser.parse_args(argv)
-
-    trace_path: Optional[Path] = None
-    history_dir: Optional[Path] = None
-    if args.trace is not None:
-        target = args.trace.resolve()
-        if target.is_dir():
-            history_dir = target
-        elif target.is_file():
-            trace_path = target
-        else:
-            parser.error(f"not found: {target}")
-
-    server = make_server(args.port, trace_path=trace_path, history_dir=history_dir)
-    url = f"http://127.0.0.1:{args.port}/memory/import"
-    if trace_path is not None:
-        url += f"?src={TRACE_ROUTE}"
-    elif history_dir is not None:
-        url += f"?runs={RUNS_ROUTE}"
-
-    print(f"graphsight serving at {url}")
-    if trace_path is not None:
-        print(f"trace: {trace_path}")
-    if history_dir is not None:
-        print(f"history: {history_dir}")
-    print("Ctrl+C to stop")
-    if not args.no_browser:
-        webbrowser.open(url)
-    try:
-        server.serve_forever()
-    except KeyboardInterrupt:
-        print("\nbye")
-    finally:
-        server.server_close()
-
-
-if __name__ == "__main__":
-    main()
+"""graphsight CLI — open a trace (or a whole run history) in the bundled UI."""
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+from .server import RUNS_ROUTE, TRACE_ROUTE, make_server
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        except (AttributeError, OSError):
+            pass
+
+    parser = argparse.ArgumentParser(
+        prog="graphsight",
+        description="Open a trace_state.json — or a history directory like .graphsight/ — in your browser.",
+    )
+    parser.add_argument("trace", nargs="?", type=Path,
+                        help="a trace_state.json, or a directory of them (e.g. .graphsight/); "
+                             "omit to open the import page")
+    parser.add_argument("--port", type=int, default=4630, help="port to serve on (default 4630)")
+    parser.add_argument("--no-browser", action="store_true", help="don't open the browser")
+    args = parser.parse_args(argv)
+
+    trace_path: Optional[Path] = None
+    history_dir: Optional[Path] = None
+    if args.trace is not None:
+        target = args.trace.resolve()
+        if target.is_dir():
+            history_dir = target
+        elif target.is_file():
+            trace_path = target
+        else:
+            parser.error(f"not found: {target}")
+
+    server = make_server(args.port, trace_path=trace_path, history_dir=history_dir)
+    url = f"http://127.0.0.1:{args.port}/memory/import"
+    if trace_path is not None:
+        url += f"?src={TRACE_ROUTE}"
+    elif history_dir is not None:
+        url += f"?runs={RUNS_ROUTE}"
+
+    print(f"graphsight serving at {url}")
+    if trace_path is not None:
+        print(f"trace: {trace_path}")
+    if history_dir is not None:
+        print(f"history: {history_dir}")
+    print("Ctrl+C to stop")
+    if not args.no_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nbye")
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()