graphviagent 0.1.0__py3-none-any.whl

graphviagent/__init__.py

@@ -0,0 +1,5 @@
+"""GraphVIAgent — local viewer for LangGraph pipelines."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

graphviagent/cli.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from graphviagent.discover import discover_pipelines
+from graphviagent.load import load_pipeline
+from graphviagent.server import serve
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    serve_mode = False
+    if argv and argv[0] == "serve":
+        serve_mode = True
+        argv = argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="graphviagent",
+        description="GraphVIAgent — inspect and replay LangGraph *_pipeline.py files",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="folder to scan")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args(argv)
+    root = Path(args.path).resolve()
+    if not root.exists():
+        raise SystemExit(f"path not found: {root}")
+
+    if serve_mode:
+        serve(root, host=args.host, port=args.port)
+        return
+
+    found = discover_pipelines(root)
+    if not found:
+        print(f"no *_pipeline.py under {root}")
+        return
+    for path in found:
+        loaded = load_pipeline(path)
+        rel = path.relative_to(root)
+        if loaded.error:
+            print(f"{rel}  ERROR  {loaded.error}")
+        else:
+            print(f"{rel}  ok  examples={len(loaded.examples)}")
+
+
+if __name__ == "__main__":
+    main()

graphviagent/discover.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+SKIP_DIRS = {
+    ".venv",
+    "venv",
+    ".graphviagent",
+    ".git",
+    "__pycache__",
+    "node_modules",
+    ".mypy_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+}
+
+
+def discover_pipelines(root: Path) -> list[Path]:
+    root = root.resolve()
+    found: list[Path] = []
+    for path in sorted(root.rglob("*_pipeline.py")):
+        if any(part in SKIP_DIRS or part.endswith(".egg-info") for part in path.parts):
+            continue
+        found.append(path)
+    return found

graphviagent/load.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+FACTORY_NAMES = ("build_graph", "get_graph", "create_graph")
+
+
+@dataclass
+class LoadedPipeline:
+    path: Path
+    stem: str
+    app: Any = None
+    examples: list[dict] = field(default_factory=list)
+    error: str | None = None
+    has_checkpointer: bool = False
+    module: Any = None
+
+
+def _is_runnable(obj: Any) -> bool:
+    return hasattr(obj, "stream") and hasattr(obj, "invoke")
+
+
+def _compile_if_needed(obj: Any) -> tuple[Any, bool]:
+    if _is_runnable(obj):
+        checkpointer = getattr(obj, "checkpointer", None)
+        return obj, checkpointer not in (None, False)
+    compile_fn = getattr(obj, "compile", None)
+    if callable(compile_fn):
+        try:
+            from langgraph.checkpoint.memory import MemorySaver
+
+            app = compile_fn(checkpointer=MemorySaver())
+            return app, True
+        except TypeError:
+            return compile_fn(), False
+    raise TypeError("object is not a compiled graph or StateGraph")
+
+
+def load_module(path: Path) -> Any:
+    path = path.resolve()
+    key = hashlib.md5(str(path).encode(), usedforsecurity=False).hexdigest()
+    name = f"graphviagent_pipe_{key}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot import {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_pipeline(path: Path) -> LoadedPipeline:
+    path = path.resolve()
+    loaded = LoadedPipeline(path=path, stem=path.stem)
+    try:
+        module = load_module(path)
+        loaded.module = module
+        examples = getattr(module, "EXAMPLES", None)
+        if isinstance(examples, list):
+            loaded.examples = [item for item in examples if isinstance(item, dict)]
+
+        candidate = None
+        for attr in ("GRAPH", "app"):
+            obj = getattr(module, attr, None)
+            if obj is not None and (_is_runnable(obj) or hasattr(obj, "compile")):
+                candidate = obj
+                break
+        if candidate is None:
+            factory_name = getattr(module, "__graph__", None)
+            names = [factory_name] if isinstance(factory_name, str) else []
+            names.extend(FACTORY_NAMES)
+            for name in names:
+                fn = getattr(module, name, None)
+                if callable(fn):
+                    candidate = fn()
+                    break
+        if candidate is None:
+            raise AttributeError(
+                "need GRAPH, app, or build_graph()/get_graph()/create_graph()"
+            )
+        loaded.app, loaded.has_checkpointer = _compile_if_needed(candidate)
+    except Exception as exc:
+        loaded.error = f"{type(exc).__name__}: {exc}"
+    return loaded

graphviagent/record.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any
+from uuid import uuid4
+
+
+def _elapsed_ms(started: float) -> float:
+    return round((time.perf_counter() - started) * 1000, 2)
+
+
+def jsonable(obj: Any) -> Any:
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, dict):
+        return {str(key): jsonable(value) for key, value in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [jsonable(item) for item in obj]
+    return str(obj)
+
+
+def merge_state(current: dict, update: dict) -> dict:
+    merged = copy.deepcopy(current)
+    for key, value in update.items():
+        if isinstance(value, list) and isinstance(merged.get(key), list):
+            merged[key] = list(merged[key]) + list(value)
+        else:
+            merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def _format_error(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {exc}"
+
+
+def _branch_hints(update: dict) -> list[str]:
+    hints: list[str] = []
+    for key in ("path", "choice", "loop_choice"):
+        value = update.get(key)
+        if isinstance(value, str):
+            hints.append(value)
+    decisions = update.get("decisions") or []
+    if decisions and isinstance(decisions[0], dict):
+        choice = decisions[0].get("choice")
+        if isinstance(choice, str):
+            hints.append(choice)
+    return hints
+
+
+def _guess_failed_node(raw_events: list[tuple[str, dict, float]], edges: list[tuple[str, str]]) -> str | None:
+    if not raw_events:
+        starts = [target for source, target in edges if source in {"__start__", "START"}]
+        return starts[0] if starts else None
+    last, last_update, _ = raw_events[-1]
+    nxt = [
+        target
+        for source, target in edges
+        if source == last and target not in {"__end__", "END", "__start__", "START"}
+    ]
+    if not nxt:
+        return last
+    if len(nxt) == 1:
+        return nxt[0]
+    if isinstance(last_update, dict):
+        for hint in _branch_hints(last_update):
+            if hint in nxt:
+                return hint
+    return nxt[0]
+
+
+def extract_reason(update: dict) -> str:
+    if not isinstance(update, dict):
+        return ""
+    if isinstance(update.get("error"), str):
+        return update["error"]
+    if isinstance(update.get("reason"), str):
+        return update["reason"]
+    if update.get("choice") is not None and not update.get("decisions"):
+        return str(update["choice"])
+    decisions = update.get("decisions") or []
+    if decisions and isinstance(decisions[0], dict):
+        return str(decisions[0].get("reason") or decisions[0].get("choice") or "")
+    return ""
+
+
+def extract_decisions(update: dict) -> list[dict]:
+    if not isinstance(update, dict):
+        return []
+    decisions = update.get("decisions")
+    if isinstance(decisions, list):
+        return [item for item in decisions if isinstance(item, dict)]
+    if update.get("reason") or update.get("choice") is not None:
+        return [
+            {
+                "step": update.get("step") or "",
+                "choice": update.get("choice"),
+                "reason": update.get("reason") or str(update.get("choice")),
+            }
+        ]
+    return []
+
+
+def graph_edges(app: Any) -> list[tuple[str, str]]:
+    try:
+        graph = app.get_graph()
+    except Exception:
+        return []
+    edges: list[tuple[str, str]] = []
+    for edge in getattr(graph, "edges", []) or []:
+        source = getattr(edge, "source", None)
+        target = getattr(edge, "target", None)
+        if source is None and isinstance(edge, (tuple, list)) and len(edge) >= 2:
+            source, target = edge[0], edge[1]
+        if source is None or target is None:
+            continue
+        edges.append((str(source), str(target)))
+    return edges
+
+
+def unused_targets(node: str, next_node: str | None, edges: list[tuple[str, str]]) -> list[str]:
+    unused: list[str] = []
+    for source, target in edges:
+        if source != node:
+            continue
+        if target in {"__end__", "END", "__start__", "START"}:
+            if next_node is None and target in {"__end__", "END"}:
+                continue
+        if next_node and target == next_node:
+            continue
+        if next_node is None and target in {"__end__", "END"}:
+            continue
+        unused.append(target)
+    return unused
+
+
+def invoke_node(app: Any, node_name: str, state: dict) -> dict:
+    node = app.nodes[node_name]
+    if hasattr(node, "invoke"):
+        result = node.invoke(state)
+        return result if isinstance(result, dict) else {"result": result}
+    bound = getattr(node, "bound", None) or getattr(node, "runnable", None)
+    if bound is not None and hasattr(bound, "invoke"):
+        result = bound.invoke(state)
+        return result if isinstance(result, dict) else {"result": result}
+    raise RuntimeError(f"cannot invoke node {node_name!r}")
+
+
+def record_run(
+    app: Any,
+    user_input: dict,
+    *,
+    thread_id: str | None = None,
+    has_checkpointer: bool = False,
+) -> dict:
+    run_id = thread_id or uuid4().hex
+    config = {"configurable": {"thread_id": run_id}} if has_checkpointer else {}
+    state = copy.deepcopy(user_input)
+    steps: list[dict] = []
+    visits: dict[str, int] = {}
+    edges = graph_edges(app)
+
+    stream = app.stream(user_input, config) if config else app.stream(user_input)
+    raw_events: list[tuple[str, dict, float]] = []
+    run_error: str | None = None
+    started = time.perf_counter()
+    try:
+        for event in stream:
+            if not isinstance(event, dict) or not event:
+                continue
+            node, update = next(iter(event.items()))
+            if not isinstance(update, dict):
+                update = {"value": update}
+            raw_events.append((str(node), update, _elapsed_ms(started)))
+            started = time.perf_counter()
+    except Exception as exc:
+        run_error = _format_error(exc)
+        failed = _guess_failed_node(raw_events, edges)
+        if failed:
+            raw_events.append((failed, {"error": run_error}, _elapsed_ms(started)))
+
+    for index, (node, update, elapsed_ms) in enumerate(raw_events):
+        visits[node] = visits.get(node, 0) + 1
+        next_node = raw_events[index + 1][0] if index + 1 < len(raw_events) else None
+        state_in = copy.deepcopy(state)
+        failed = isinstance(update, dict) and update.get("error")
+        state_out = copy.deepcopy(state_in) if failed else merge_state(state, update)
+        step = {
+            "step_id": f"{node}#{visits[node]}",
+            "index": index,
+            "node": node,
+            "update": jsonable(update),
+            "state_in": jsonable(state_in),
+            "state_out": jsonable(state_out),
+            "reason": extract_reason(update),
+            "decisions": jsonable(extract_decisions(update)),
+            "unused": unused_targets(node, next_node, edges),
+            "elapsed_ms": elapsed_ms,
+        }
+        if failed:
+            step["error"] = str(update.get("error"))
+        steps.append(step)
+        state = state_out
+
+    return {
+        "id": run_id,
+        "input": jsonable(user_input),
+        "steps": steps,
+        "result": jsonable(state),
+        "has_checkpointer": has_checkpointer,
+        "thread_id": run_id if has_checkpointer else None,
+        "elapsed_ms": round(sum(step.get("elapsed_ms") or 0 for step in steps), 2),
+        "error": run_error,
+    }
+
+
+def _incoming_state(
+    step: dict, state_patch: dict | None = None, state_in: dict | None = None
+) -> dict:
+    if state_in is not None:
+        if not isinstance(state_in, dict):
+            return {"value": state_in}
+        return copy.deepcopy(state_in)
+    return merge_state(copy.deepcopy(step.get("state_in") or {}), state_patch or {})
+
+
+def replay_step(
+    app: Any,
+    run: dict,
+    step_id: str,
+    state_patch: dict | None = None,
+    state_in: dict | None = None,
+) -> dict:
+    step = _find_step(run, step_id)
+    state_in = _incoming_state(step, state_patch, state_in)
+    started = time.perf_counter()
+    try:
+        update = invoke_node(app, step["node"], state_in)
+        if not isinstance(update, dict):
+            update = {"value": update}
+        run_error = None
+    except Exception as exc:
+        run_error = _format_error(exc)
+        update = {"error": run_error}
+    elapsed_ms = _elapsed_ms(started)
+    state_out = copy.deepcopy(state_in) if run_error else merge_state(state_in, update)
+    new_step = {
+        "step_id": f"{step['node']}#replay",
+        "index": 0,
+        "node": step["node"],
+        "update": jsonable(update),
+        "state_in": jsonable(state_in),
+        "state_out": jsonable(state_out),
+        "reason": extract_reason(update),
+        "decisions": jsonable(extract_decisions(update)),
+        "unused": [],
+        "elapsed_ms": elapsed_ms,
+    }
+    if run_error:
+        new_step["error"] = run_error
+    return {
+        "id": uuid4().hex,
+        "input": jsonable(state_in),
+        "steps": [new_step],
+        "result": jsonable(state_out),
+        "has_checkpointer": False,
+        "thread_id": None,
+        "parent_id": run["id"],
+        "mode": "replay",
+        "from_step": step_id,
+        "elapsed_ms": elapsed_ms,
+        "error": run_error,
+    }
+
+
+def resume_from_step(
+    app: Any,
+    run: dict,
+    step_id: str,
+    state_patch: dict | None = None,
+    state_in: dict | None = None,
+) -> dict:
+    step = _find_step(run, step_id)
+    start = step["index"]
+    remaining = run["steps"][start:]
+    state = _incoming_state(step, state_patch, state_in)
+    steps: list[dict] = []
+    visits: dict[str, int] = {}
+    edges = graph_edges(app)
+
+    if run.get("has_checkpointer") and run.get("thread_id"):
+        try:
+            return _resume_with_checkpointer(app, run, step, state)
+        except Exception:
+            pass
+
+    raw: list[tuple[str, dict, float]] = []
+    current = state
+    run_error: str | None = None
+    for recorded in remaining:
+        started = time.perf_counter()
+        try:
+            update = invoke_node(app, recorded["node"], current)
+            if not isinstance(update, dict):
+                update = {"value": update}
+        except Exception as exc:
+            run_error = _format_error(exc)
+            update = {"error": run_error}
+            raw.append((recorded["node"], update, _elapsed_ms(started)))
+            break
+        raw.append((recorded["node"], update, _elapsed_ms(started)))
+        current = merge_state(current, update)
+
+    current = copy.deepcopy(state)
+    for index, (node, update, elapsed_ms) in enumerate(raw):
+        visits[node] = visits.get(node, 0) + 1
+        next_node = raw[index + 1][0] if index + 1 < len(raw) else None
+        state_in = copy.deepcopy(current)
+        failed = isinstance(update, dict) and update.get("error")
+        state_out = copy.deepcopy(state_in) if failed else merge_state(current, update)
+        step = {
+            "step_id": f"{node}#{visits[node]}",
+            "index": index,
+            "node": node,
+            "update": jsonable(update),
+            "state_in": jsonable(state_in),
+            "state_out": jsonable(state_out),
+            "reason": extract_reason(update),
+            "decisions": jsonable(extract_decisions(update)),
+            "unused": unused_targets(node, next_node, edges),
+            "elapsed_ms": elapsed_ms,
+        }
+        if failed:
+            step["error"] = str(update.get("error"))
+        steps.append(step)
+        current = state_out
+
+    return {
+        "id": uuid4().hex,
+        "input": jsonable(state),
+        "steps": steps,
+        "result": jsonable(current),
+        "has_checkpointer": False,
+        "thread_id": None,
+        "parent_id": run["id"],
+        "mode": "replay_from",
+        "from_step": step_id,
+        "elapsed_ms": round(sum(item.get("elapsed_ms") or 0 for item in steps), 2),
+        "error": run_error,
+    }
+
+
+def _resume_with_checkpointer(app: Any, run: dict, step: dict, state_in: dict) -> dict:
+    config = {"configurable": {"thread_id": run["thread_id"]}}
+    update = invoke_node(app, step["node"], state_in)
+    if not isinstance(update, dict):
+        update = {"value": update}
+    app.update_state(config, update, as_node=step["node"])
+    app.invoke(None, config)
+    return record_run(
+        app,
+        run["input"],
+        thread_id=uuid4().hex,
+        has_checkpointer=True,
+    )
+
+
+def _find_step(run: dict, step_id: str) -> dict:
+    for step in run.get("steps") or []:
+        if step.get("step_id") == step_id:
+            return step
+    raise KeyError(f"unknown step {step_id}")

graphviagent/render.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+
+def _reason(step: dict) -> str:
+    return step.get("reason") or ""
+
+
+def format_elapsed(ms: object) -> str:
+    try:
+        value = float(ms)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return ""
+    if value < 1000:
+        text = f"{value:.1f}ms"
+        return text.replace(".0ms", "ms")
+    return f"{value / 1000:.2f}s"
+
+
+def _detail(step: dict) -> str:
+    update = step.get("update") or {}
+    if not isinstance(update, dict):
+        return str(update)
+    reason = _reason(step)
+    if reason:
+        return reason
+    for key in ("greeting", "shout", "polished", "output", "result"):
+        if update.get(key) not in (None, ""):
+            return str(update[key])
+    if not update:
+        return ""
+    parts = [f"{key}={update[key]}" for key in list(update)[:3]]
+    return ", ".join(parts)
+
+
+def ascii_tree(title: str, steps: list[dict]) -> str:
+    lines = [title]
+    indent = 0
+    for step in steps:
+        extra = _detail(step)
+        elapsed = format_elapsed(step.get("elapsed_ms"))
+        bits = [part for part in (extra, elapsed) if part]
+        suffix = f"  {'  '.join(bits)}" if bits else ""
+        lines.append(f"{'   ' * indent}└─ {step['node']}{suffix}")
+        indent += 1
+    if steps:
+        lines.append(f"{'   ' * indent}└─ END")
+    return "\n".join(lines)
+
+
+def _esc(text: str) -> str:
+    return (
+        text.replace('"', "#quot;")
+        .replace("<", " ")
+        .replace(">", " ")
+        .replace("\n", "<br/>")
+    )
+
+
+def unrolled_mermaid(steps: list[dict]) -> str:
+    lines = ["flowchart TD", "    startNode([START])"]
+    prev = "startNode"
+    for index, step in enumerate(steps):
+        nid = f"n{index}"
+        detail = _detail(step)
+        label = f"{step['node']}<br/>{detail}" if detail else step["node"]
+        lines.append(f'    {nid}["{_esc(label)}"]')
+        lines.append(f"    {prev} --> {nid}")
+        for unused_i, unused in enumerate(step.get("unused") or []):
+            other_id = f"{nid}u{unused_i}"
+            lines.append(f'    {other_id}["{_esc(str(unused))}<br/>not taken"]:::skipped')
+            lines.append(f"    {nid} -.-> {other_id}")
+        prev = nid
+    lines.append("    endNode([END])")
+    lines.append(f"    {prev} --> endNode")
+    lines.append("    classDef skipped fill:#1c1c22,stroke:#3a3a44,color:#8b8b96")
+    return "\n".join(lines)