graphviagent 0.1.0__tar.gz

graphviagent-0.1.0/LICENSE

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

graphviagent-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include examples *.py

graphviagent-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: graphviagent
+Version: 0.1.0
+Summary: Local Graph-View-Agent for inspecting and replaying LangGraph pipelines
+Author: antsticky
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/antsticky/graphviagent
+Project-URL: Repository, https://github.com/antsticky/graphviagent
+Project-URL: Issues, https://github.com/antsticky/graphviagent/issues
+Keywords: langgraph,langchain,observability,debugger,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langgraph>=0.2
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# GraphVIAgent
+
+Local Graph-View-Agent for LangGraph. Scan `*_pipeline.py` files, record runs under `.graphviagent/`, and inspect them in a browser UI.
+
+Pipeline files do not import GraphVIAgent. Only runs started from the UI or CLI are stored.
+
+## Install
+
+```bash
+pip install graphviagent
+```
+
+From a clone:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## List pipelines
+
+```bash
+graphviagent .
+```
+
+## Open the UI
+
+```bash
+graphviagent serve .
+```
+
+Then open [http://127.0.0.1:8765](http://127.0.0.1:8765).
+
+- **Trace** — run a pipeline, inspect the unrolled graph, replay a node
+- **Pipelines** — Airflow-style grid of recent runs
+
+Replay and Call node invoke the node again. Side effects will fire.
+
+## Pipeline contract
+
+A file is viewable if it is named `*_pipeline.py` and exposes one of:
+
+- `build_graph()` / `get_graph()` / `create_graph()`
+- compiled `GRAPH` or `app`
+- `__graph__ = "factory_name"`
+
+Optional: `EXAMPLES = [{"some": "input"}]` to prefill the form.
+
+If a node update includes `decisions`, `reason`, or `choice`, the UI labels the branch. That is optional.
+
+## Examples
+
+This repo includes sample graphs:
+
+```bash
+graphviagent serve examples
+```
+
+- `examples/dummy_pipeline.py` — name-length branch and a polish loop
+- `examples/echo_pipeline.py` — reverse a `text` field
+- `examples/math_pipeline.py` — add or divide; `{a: 12, b: 0, op: "div"}` raises
+- `examples/ratio_pipeline.py` — part / total; `total: 0` raises
+- `examples/stats_pipeline.py` — mean of a list; empty `values` raises
+- `examples/grade_pipeline.py` — score / max; `maximum: 0` raises
+- `examples/convert_pipeline.py` — unit conversion; `per_unit` with `value: 0` or an unknown unit raises
+
+Failed runs are saved. The failing node is marked on the graph and shows as a red cell on the Pipelines grid.
+
+## Publish to PyPI
+
+```bash
+pip install -e ".[dev]"
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+Create the GitHub repo at [antsticky/graphviagent](https://github.com/antsticky/graphviagent) before the first upload.

graphviagent-0.1.0/README.md

@@ -0,0 +1,79 @@
+# GraphVIAgent
+
+Local Graph-View-Agent for LangGraph. Scan `*_pipeline.py` files, record runs under `.graphviagent/`, and inspect them in a browser UI.
+
+Pipeline files do not import GraphVIAgent. Only runs started from the UI or CLI are stored.
+
+## Install
+
+```bash
+pip install graphviagent
+```
+
+From a clone:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## List pipelines
+
+```bash
+graphviagent .
+```
+
+## Open the UI
+
+```bash
+graphviagent serve .
+```
+
+Then open [http://127.0.0.1:8765](http://127.0.0.1:8765).
+
+- **Trace** — run a pipeline, inspect the unrolled graph, replay a node
+- **Pipelines** — Airflow-style grid of recent runs
+
+Replay and Call node invoke the node again. Side effects will fire.
+
+## Pipeline contract
+
+A file is viewable if it is named `*_pipeline.py` and exposes one of:
+
+- `build_graph()` / `get_graph()` / `create_graph()`
+- compiled `GRAPH` or `app`
+- `__graph__ = "factory_name"`
+
+Optional: `EXAMPLES = [{"some": "input"}]` to prefill the form.
+
+If a node update includes `decisions`, `reason`, or `choice`, the UI labels the branch. That is optional.
+
+## Examples
+
+This repo includes sample graphs:
+
+```bash
+graphviagent serve examples
+```
+
+- `examples/dummy_pipeline.py` — name-length branch and a polish loop
+- `examples/echo_pipeline.py` — reverse a `text` field
+- `examples/math_pipeline.py` — add or divide; `{a: 12, b: 0, op: "div"}` raises
+- `examples/ratio_pipeline.py` — part / total; `total: 0` raises
+- `examples/stats_pipeline.py` — mean of a list; empty `values` raises
+- `examples/grade_pipeline.py` — score / max; `maximum: 0` raises
+- `examples/convert_pipeline.py` — unit conversion; `per_unit` with `value: 0` or an unknown unit raises
+
+Failed runs are saved. The failing node is marked on the graph and shows as a red cell on the Pipelines grid.
+
+## Publish to PyPI
+
+```bash
+pip install -e ".[dev]"
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+Create the GitHub repo at [antsticky/graphviagent](https://github.com/antsticky/graphviagent) before the first upload.

graphviagent-0.1.0/examples/convert_pipeline.py

@@ -0,0 +1,87 @@
+from typing import Literal, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [
+    {"value": 100, "unit": "c_to_f"},
+    {"value": 32, "unit": "f_to_c"},
+    {"value": 0, "unit": "per_unit"},
+    {"value": 21, "unit": "kelvin"},
+]
+
+
+class ConvertState(TypedDict):
+    value: float
+    unit: str
+    path: str
+    result: float
+    label: str
+
+
+def parse(state: ConvertState) -> dict:
+    return {"value": float(state["value"]), "unit": str(state.get("unit") or "")}
+
+
+def choose_unit(state: ConvertState) -> dict:
+    unit = state["unit"]
+    known = {"c_to_f": "c_to_f", "f_to_c": "f_to_c", "per_unit": "per_unit"}
+    if unit not in known:
+        raise ValueError(f"unknown unit {unit!r}; use c_to_f, f_to_c, or per_unit")
+    path = known[unit]
+    return {
+        "path": path,
+        "decisions": [
+            {
+                "step": "choose_unit",
+                "choice": path,
+                "reason": f"unit={unit!r}",
+            }
+        ],
+    }
+
+
+def c_to_f(state: ConvertState) -> dict:
+    return {"result": state["value"] * 9 / 5 + 32}
+
+
+def f_to_c(state: ConvertState) -> dict:
+    return {"result": (state["value"] - 32) * 5 / 9}
+
+
+def per_unit(state: ConvertState) -> dict:
+    return {"result": 100 / state["value"]}
+
+
+def label(state: ConvertState) -> dict:
+    names = {
+        "c_to_f": f"{state['value']}°C = {state['result']}°F",
+        "f_to_c": f"{state['value']}°F = {state['result']}°C",
+        "per_unit": f"100 / {state['value']} = {state['result']}",
+    }
+    return {"label": names[state["path"]]}
+
+
+def route_unit(state: ConvertState) -> Literal["c_to_f", "f_to_c", "per_unit"]:
+    return state["path"]  # type: ignore[return-value]
+
+
+def build_graph():
+    graph = StateGraph(ConvertState)
+    graph.add_node("parse", parse)
+    graph.add_node("choose_unit", choose_unit)
+    graph.add_node("c_to_f", c_to_f)
+    graph.add_node("f_to_c", f_to_c)
+    graph.add_node("per_unit", per_unit)
+    graph.add_node("label", label)
+    graph.add_edge(START, "parse")
+    graph.add_edge("parse", "choose_unit")
+    graph.add_conditional_edges(
+        "choose_unit",
+        route_unit,
+        {"c_to_f": "c_to_f", "f_to_c": "f_to_c", "per_unit": "per_unit"},
+    )
+    graph.add_edge("c_to_f", "label")
+    graph.add_edge("f_to_c", "label")
+    graph.add_edge("per_unit", "label")
+    graph.add_edge("label", END)
+    return graph.compile()

graphviagent-0.1.0/examples/dummy_pipeline.py

@@ -0,0 +1,142 @@
+from operator import add
+from typing import Annotated, Literal, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [
+    {"name": "Ada"},
+    {"name": "Bo"},
+    {"name": "Ada Lovelace"},
+    {"name": "Grace"},
+]
+
+
+# Shared state. Each node returns only the keys it updates; LangGraph merges them in.
+# `decisions` appends so every branch/loop choice stays visible in the final state.
+class PipelineState(TypedDict):
+    name: str
+    greeting: str
+    shout: str
+    polished: str
+    passes: int
+    path: str
+    loop_choice: str
+    decisions: Annotated[list[dict], add]
+
+
+def greet(state: PipelineState) -> dict:
+    return {
+        "greeting": f"Hello, {state['name']}!",
+        "passes": 0,
+        "shout": "",
+        "polished": "",
+    }
+
+
+def choose_path(state: PipelineState) -> dict:
+    """Visible decision node: short names shout, longer names skip."""
+    name = state["name"]
+    length = len(name)
+    threshold = 3
+    path = "shout" if length <= threshold else "skip"
+    if path == "shout":
+        reason = f"len({name!r}) = {length} <= {threshold} → shout"
+    else:
+        reason = f"len({name!r}) = {length} > {threshold} → skip"
+    return {
+        "path": path,
+        "decisions": [
+            {
+                "step": "choose_path",
+                "choice": path,
+                "reason": reason,
+                "facts": {"name": name, "name_length": length, "threshold": threshold},
+            }
+        ],
+    }
+
+
+def shout(state: PipelineState) -> dict:
+    return {"shout": state["greeting"].upper()}
+
+
+def skip_shout(state: PipelineState) -> dict:
+    return {"shout": state["greeting"]}
+
+
+def polish(state: PipelineState) -> dict:
+    passes = state["passes"] + 1
+    return {
+        "passes": passes,
+        "polished": f"{state['shout']} (pass {passes})",
+    }
+
+
+def check_loop(state: PipelineState) -> dict:
+    """Visible decision node: keep polishing until 2 passes."""
+    passes = state["passes"]
+    required = 2
+    if passes < required:
+        choice = "polish"
+        reason = f"passes = {passes} < {required} → polish again"
+    else:
+        choice = "done"
+        reason = f"passes = {passes} >= {required} → stop"
+    return {
+        "loop_choice": choice,
+        "decisions": [
+            {
+                "step": "check_loop",
+                "choice": choice,
+                "reason": reason,
+                "facts": {"passes": passes, "required": required},
+            }
+        ],
+    }
+
+
+def route_after_choice(state: PipelineState) -> Literal["shout", "skip"]:
+    return state["path"]  # type: ignore[return-value]
+
+
+def route_after_loop(state: PipelineState) -> Literal["polish", "done"]:
+    return state["loop_choice"]  # type: ignore[return-value]
+
+
+def build_graph():
+    graph = StateGraph(PipelineState)
+
+    graph.add_node("greet", greet)
+    graph.add_node("choose_path", choose_path)
+    graph.add_node("shout", shout)
+    graph.add_node("skip", skip_shout)
+    graph.add_node("polish", polish)
+    graph.add_node("check_loop", check_loop)
+
+    graph.add_edge(START, "greet")
+    graph.add_edge("greet", "choose_path")
+
+    graph.add_conditional_edges(
+        "choose_path",
+        route_after_choice,
+        {"shout": "shout", "skip": "skip"},
+    )
+
+    graph.add_edge("shout", "polish")
+    graph.add_edge("skip", "polish")
+    graph.add_edge("polish", "check_loop")
+
+    graph.add_conditional_edges(
+        "check_loop",
+        route_after_loop,
+        {"polish": "polish", "done": END},
+    )
+
+    return graph.compile()
+
+
+if __name__ == "__main__":
+    app = build_graph()
+    for example in EXAMPLES[:2]:
+        print(example, "->", app.invoke(example))
+    print("\nInspect with: graphviagent serve examples")

graphviagent-0.1.0/examples/echo_pipeline.py

@@ -0,0 +1,36 @@
+"""Minimal second pipeline so discovery is not dummy-only."""
+
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [{"text": "hello"}, {"text": "GraphVIAgent"}]
+
+
+class EchoState(TypedDict):
+    text: str
+    echoed: str
+    length: int
+
+
+def echo(state: EchoState) -> dict:
+    text = state["text"]
+    return {
+        "echoed": text[::-1],
+        "length": len(text),
+        "decisions": [
+            {
+                "step": "echo",
+                "choice": "reverse",
+                "reason": f"reversed {len(text)} chars",
+            }
+        ],
+    }
+
+
+def build_graph():
+    graph = StateGraph(EchoState)
+    graph.add_node("echo", echo)
+    graph.add_edge(START, "echo")
+    graph.add_edge("echo", END)
+    return graph.compile()

graphviagent-0.1.0/examples/grade_pipeline.py

@@ -0,0 +1,60 @@
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [
+    {"score": 18, "maximum": 20},
+    {"score": 18, "maximum": 0},
+    {"score": 7, "maximum": 10},
+]
+
+
+class GradeState(TypedDict):
+    score: float
+    maximum: float
+    percent: float
+    letter: str
+
+
+def normalize(state: GradeState) -> dict:
+    return {"score": float(state["score"]), "maximum": float(state["maximum"])}
+
+
+def score_percent(state: GradeState) -> dict:
+    return {"percent": 100 * state["score"] / state["maximum"]}
+
+
+def letter(state: GradeState) -> dict:
+    percent = state["percent"]
+    if percent >= 90:
+        grade = "A"
+    elif percent >= 80:
+        grade = "B"
+    elif percent >= 70:
+        grade = "C"
+    elif percent >= 60:
+        grade = "D"
+    else:
+        grade = "F"
+    return {
+        "letter": grade,
+        "decisions": [
+            {
+                "step": "letter",
+                "choice": grade,
+                "reason": f"{percent:.1f}% → {grade}",
+            }
+        ],
+    }
+
+
+def build_graph():
+    graph = StateGraph(GradeState)
+    graph.add_node("normalize", normalize)
+    graph.add_node("percent", score_percent)
+    graph.add_node("letter", letter)
+    graph.add_edge(START, "normalize")
+    graph.add_edge("normalize", "percent")
+    graph.add_edge("percent", "letter")
+    graph.add_edge("letter", END)
+    return graph.compile()

graphviagent-0.1.0/examples/math_pipeline.py

@@ -0,0 +1,78 @@
+from typing import Literal, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [
+    {"a": 12, "b": 3, "op": "div"},
+    {"a": 12, "b": 0, "op": "div"},
+    {"a": 7, "b": 5, "op": "add"},
+]
+
+
+class MathState(TypedDict):
+    a: float
+    b: float
+    op: str
+    path: str
+    result: float
+    summary: str
+
+
+def parse(state: MathState) -> dict:
+    a = float(state["a"])
+    b = float(state["b"])
+    op = str(state.get("op") or "div").lower()
+    return {"a": a, "b": b, "op": op}
+
+
+def choose_op(state: MathState) -> dict:
+    op = state["op"]
+    path = "add" if op == "add" else "div"
+    if path == "add":
+        reason = f"op={op!r} → add {state['a']} + {state['b']}"
+    else:
+        reason = f"op={op!r} → divide {state['a']} / {state['b']}"
+    return {
+        "path": path,
+        "decisions": [
+            {
+                "step": "choose_op",
+                "choice": path,
+                "reason": reason,
+                "facts": {"a": state["a"], "b": state["b"], "op": op},
+            }
+        ],
+    }
+
+
+def add(state: MathState) -> dict:
+    return {"result": state["a"] + state["b"]}
+
+
+def divide(state: MathState) -> dict:
+    return {"result": state["a"] / state["b"]}
+
+
+def format_result(state: MathState) -> dict:
+    symbol = "+" if state["path"] == "add" else "/"
+    return {"summary": f"{state['a']} {symbol} {state['b']} = {state['result']}"}
+
+
+def route_op(state: MathState) -> Literal["add", "div"]:
+    return state["path"]  # type: ignore[return-value]
+
+
+def build_graph():
+    graph = StateGraph(MathState)
+    graph.add_node("parse", parse)
+    graph.add_node("choose_op", choose_op)
+    graph.add_node("add", add)
+    graph.add_node("div", divide)
+    graph.add_node("format", format_result)
+    graph.add_edge(START, "parse")
+    graph.add_edge("parse", "choose_op")
+    graph.add_conditional_edges("choose_op", route_op, {"add": "add", "div": "div"})
+    graph.add_edge("add", "format")
+    graph.add_edge("div", "format")
+    graph.add_edge("format", END)
+    return graph.compile()

graphviagent-0.1.0/examples/ratio_pipeline.py

@@ -0,0 +1,52 @@
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+EXAMPLES = [
+    {"part": 3, "total": 10},
+    {"part": 3, "total": 0},
+    {"part": 25, "total": 40},
+]
+
+
+class RatioState(TypedDict):
+    part: float
+    total: float
+    ratio: float
+    percent: float
+    label: str
+
+
+def read_values(state: RatioState) -> dict:
+    return {"part": float(state["part"]), "total": float(state["total"])}
+
+
+def compute_ratio(state: RatioState) -> dict:
+    return {"ratio": state["part"] / state["total"]}
+
+
+def to_percent(state: RatioState) -> dict:
+    percent = state["ratio"] * 100
+    return {
+        "percent": percent,
+        "label": f"{state['part']} of {state['total']} = {percent:.1f}%",
+        "decisions": [
+            {
+                "step": "to_percent",
+                "choice": "scale",
+                "reason": f"ratio {state['ratio']} × 100",
+            }
+        ],
+    }
+
+
+def build_graph():
+    graph = StateGraph(RatioState)
+    graph.add_node("read", read_values)
+    graph.add_node("ratio", compute_ratio)
+    graph.add_node("percent", to_percent)
+    graph.add_edge(START, "read")
+    graph.add_edge("read", "ratio")
+    graph.add_edge("ratio", "percent")
+    graph.add_edge("percent", END)
+    return graph.compile()