graphsight-langgraph 0.1.0__py3-none-any.whl

graphsight_langgraph/__init__.py

@@ -0,0 +1,30 @@
+"""graphsight-langgraph — capture LangGraph runs as Graphsight traces.
+
+    from graphsight_langgraph import LangGraphTracer, to_tracestate
+
+    tracer = LangGraphTracer()
+    result = graph.invoke(inputs, config={"callbacks": [tracer]})
+    trace = tracer.finish(query="...", answer=result.get("answer"))
+    studio_json = to_tracestate(trace)   # render in Graphsight Studio
+"""
+from .mapper import to_tracestate
+from .schema import (
+    SCHEMA_VERSION,
+    AgentTrace,
+    Retrieval,
+    RetrievedItem,
+    Span,
+    TraceEdge,
+)
+from .tracer import LangGraphTracer
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "AgentTrace",
+    "LangGraphTracer",
+    "Retrieval",
+    "RetrievedItem",
+    "Span",
+    "TraceEdge",
+    "to_tracestate",
+]

graphsight_langgraph/github_ingest.py

@@ -0,0 +1,286 @@
+"""graphsight-github-trace: GitHub repo -> traced agent run -> trace_state.json.
+
+Fetches recent PRs/issues, runs a small traced LangGraph agent over them,
+writes graphsight_out/. Needs the `example` extra for LangGraph.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Optional
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+
+from .mapper import to_tracestate
+from .tracer import LangGraphTracer
+
+_API = "https://api.github.com"
+_RESOLVE_RE = re.compile(r"(?:fix(?:es|ed)?|close[sd]?|resolve[sd]?)\s+#(\d+)", re.IGNORECASE)
+_WORD_RE = re.compile(r"[a-z0-9_#-]+")
+_STOP = {
+    "the", "a", "an", "and", "or", "of", "in", "on", "to", "for", "is", "are",
+    "was", "were", "it", "this", "that", "with", "by", "at", "from", "what",
+    "who", "which", "how", "why", "when", "did", "do", "does", "recently",
+    "recent", "latest", "github", "user", "author",
+}
+
+# tie-break on equal lexical score: substantive artifacts over boilerplate
+_KIND_PRIORITY = {"pull_request": 3, "ticket": 2, "repo": 1, "person": 0}
+
+
+# github fetch, stdlib only
+def _get(path: str, token: Optional[str]) -> Any:
+    req = urllib.request.Request(
+        f"{_API}{path}",
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "graphsight-github-trace/0.1",
+            **({"Authorization": f"Bearer {token}"} if token else {}),
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as err:
+        if err.code in (401, 403):
+            raise SystemExit(
+                f"GitHub API {err.code} for {path}. Private repo or rate limit — "
+                "pass --token or set GITHUB_TOKEN."
+            ) from err
+        if err.code == 404:
+            raise SystemExit(f"GitHub API 404 for {path} — is the repo name right?") from err
+        raise SystemExit(f"GitHub API error {err.code} for {path}.") from err
+
+
+def _excerpt(text: Optional[str], limit: int = 400) -> str:
+    return re.sub(r"\s+", " ", text or "").strip()[:limit]
+
+
+# corpus
+def build_corpus(repo: str, token: Optional[str], n_prs: int, n_issues: int) -> list[Document]:
+    owner_name = repo.split("/")[-1]
+    meta = _get(f"/repos/{repo}", token)
+    repo_id = f"repo_{owner_name}"
+    docs: list[Document] = [
+        Document(
+            page_content=_excerpt(
+                f"{repo}: {meta.get('description') or 'no description'}. "
+                f"Primary language {meta.get('language') or 'n/a'}, "
+                f"{meta.get('stargazers_count', 0)} stars, "
+                f"{meta.get('open_issues_count', 0)} open issues."
+            ),
+            metadata={
+                "id": repo_id, "label": owner_name, "kind": "repo",
+                "source": meta.get("html_url"),
+            },
+        )
+    ]
+
+    prs = _get(f"/repos/{repo}/pulls?state=all&sort=updated&direction=desc&per_page={n_prs}", token)
+    authored: dict[str, list[str]] = {}
+    for pr in prs:
+        num, login = pr["number"], (pr.get("user") or {}).get("login") or "unknown"
+        pr_id = f"pr_{num}"
+        edges = [{"source": pr_id, "target": repo_id, "relation": "TOUCHES", "weight": 0.7},
+                 {"source": f"person_{login}", "target": pr_id, "relation": "AUTHORED", "weight": 0.9}]
+        for ref in _RESOLVE_RE.findall(pr.get("body") or ""):
+            edges.append({"source": pr_id, "target": f"tkt_{ref}", "relation": "RESOLVES", "weight": 0.85})
+        state = "merged" if pr.get("merged_at") else pr.get("state", "open")
+        docs.append(Document(
+            page_content=_excerpt(f"PR #{num} '{pr['title']}' by {login} ({state}). {pr.get('body') or ''}"),
+            metadata={"id": pr_id, "label": f"PR #{num}", "kind": "pull_request",
+                      "source": pr.get("html_url"), "edges": edges},
+        ))
+        authored.setdefault(login, []).append(pr_id)
+
+    issues = _get(f"/repos/{repo}/issues?state=all&sort=updated&direction=desc&per_page={n_issues}", token)
+    for issue in issues:
+        if "pull_request" in issue:  # the issues API also returns PRs; skip those
+            continue
+        num, login = issue["number"], (issue.get("user") or {}).get("login") or "unknown"
+        tkt_id = f"tkt_{num}"
+        docs.append(Document(
+            page_content=_excerpt(
+                f"Issue #{num} '{issue['title']}' by {login} ({issue.get('state', 'open')}). "
+                f"{issue.get('body') or ''}"
+            ),
+            metadata={"id": tkt_id, "label": f"Issue #{num}", "kind": "ticket",
+                      "source": issue.get("html_url"),
+                      "edges": [{"source": tkt_id, "target": repo_id,
+                                 "relation": "REPORTS_ON", "weight": 0.6}]},
+        ))
+        authored.setdefault(login, [])
+
+    for login, pr_ids in authored.items():
+        docs.append(Document(
+            page_content=f"GitHub user {login} — authored {len(pr_ids)} of the "
+                         f"last {len(prs)} pull requests in {repo}.",
+            metadata={"id": f"person_{login}", "label": login, "kind": "person",
+                      "source": f"https://github.com/{login}",
+                      # carried on both endpoints; the tracer dedups per retrieval
+                      "edges": [{"source": f"person_{login}", "target": pid,
+                                 "relation": "AUTHORED", "weight": 0.9} for pid in pr_ids]},
+        ))
+    return docs
+
+
+# retrieval
+def _tokens(text: str) -> set[str]:
+    return {w for w in _WORD_RE.findall(text.lower()) if w not in _STOP}
+
+
+class LexicalGraphRetriever(BaseRetriever):
+    """Lexical seeds + 1-hop edge neighbors, capped at k.
+
+    Neighbors keep their own (often lower) lexical score. Edges are only
+    emitted when both endpoints made the cut.
+    """
+
+    corpus: list[Document]
+    k: int = 10
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        q = _tokens(query) or {"?"}
+        scored = sorted(
+            ((round(len(q & _tokens(d.page_content)) / len(q), 3), d) for d in self.corpus),
+            key=lambda pair: (pair[0], _KIND_PRIORITY.get(pair[1].metadata["kind"], 0)),
+            reverse=True,
+        )
+        by_id = {d.metadata["id"]: (s, d) for s, d in scored}
+
+        # lexical seeds first
+        kept: dict[str, tuple[float, Document]] = {
+            d.metadata["id"]: (s, d) for s, d in scored[: max(3, self.k // 2)]
+        }
+        # then their 1-hop neighbors
+        for _, doc in list(kept.values()):
+            for edge in doc.metadata.get("edges", []):
+                for nid in (edge["source"], edge["target"]):
+                    if len(kept) >= self.k:
+                        break
+                    if nid not in kept and nid in by_id:
+                        kept[nid] = by_id[nid]
+        # fill spare slots
+        for s, d in scored:
+            if len(kept) >= self.k:
+                break
+            kept.setdefault(d.metadata["id"], (s, d))
+
+        out = []
+        for score, doc in sorted(kept.values(), key=lambda pair: pair[0], reverse=True):
+            edges = [e for e in doc.metadata.get("edges", [])
+                     if e["source"] in kept and e["target"] in kept]
+            out.append(Document(
+                page_content=doc.page_content,
+                metadata={**{k: v for k, v in doc.metadata.items() if k != "edges"},
+                          "score": score, "edges": edges},
+            ))
+        return out
+
+
+# the traced agent
+def run_traced(corpus: list[Document], question: str, repo: str, k: int):
+    try:
+        from langgraph.graph import END, START, StateGraph
+    except ImportError:
+        raise SystemExit(
+            'LangGraph is required for the demo agent: pip install "graphsight-langgraph[example]"'
+        )
+    from typing import TypedDict
+
+    retriever = LexicalGraphRetriever(corpus=corpus, k=k)
+
+    class State(TypedDict):
+        question: str
+        docs: list[Document]
+        answer: str
+
+    def retrieve(state: State, config) -> dict:
+        return {"docs": retriever.invoke(state["question"], config=config)}
+
+    def answer(state: State, config) -> dict:
+        docs = state["docs"]
+        top = docs[0]
+        kinds = {}
+        for d in docs:
+            kinds[d.metadata["kind"]] = kinds.get(d.metadata["kind"], 0) + 1
+        parts = ", ".join(f"{v} {k.replace('_', ' ')}(s)" for k, v in sorted(kinds.items()))
+        return {"answer": (
+            f"Top match in {repo}: {top.metadata['label']} — "
+            f"{top.page_content[:160]}… Retrieved {len(docs)} items ({parts}); "
+            "open the graph to see who and what they connect to."
+        )}
+
+    graph = (StateGraph(State)
+             .add_node("retrieve", retrieve)
+             .add_node("answer", answer)
+             .add_edge(START, "retrieve")
+             .add_edge("retrieve", "answer")
+             .add_edge("answer", END)
+             .compile())
+
+    tracer = LangGraphTracer()
+    result = graph.invoke({"question": question}, config={"callbacks": [tracer]})
+    return tracer.finish(query=question, answer=result["answer"])
+
+
+# cli
+def main(argv: Optional[list[str]] = None) -> None:
+    # windows consoles default to cp1252
+    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-github-trace",
+        description="GitHub repo → traced LangGraph run → Studio-ready trace_state.json",
+    )
+    parser.add_argument("repo", help="owner/name, e.g. langchain-ai/langgraph")
+    parser.add_argument("question", nargs="?", default=None,
+                        help='the question to trace (default: "what changed recently and who drove it?")')
+    parser.add_argument("--token", default=os.environ.get("GITHUB_TOKEN"),
+                        help="GitHub token (or set GITHUB_TOKEN); needed for private repos")
+    parser.add_argument("--prs", type=int, default=25, help="recent PRs to fetch (default 25)")
+    parser.add_argument("--issues", type=int, default=25, help="recent issues to fetch (default 25)")
+    parser.add_argument("--top", type=int, default=10, help="items to retrieve (default 10)")
+    parser.add_argument("--out", type=Path, default=Path("graphsight_out"), help="output directory")
+    args = parser.parse_args(argv)
+
+    if "/" not in args.repo:
+        parser.error("repo must be owner/name")
+    question = args.question or f"What changed recently in {args.repo}, and who drove it?"
+
+    print(f"fetching {args.repo} (last {args.prs} PRs, {args.issues} issues)…", file=sys.stderr)
+    corpus = build_corpus(args.repo, args.token, args.prs, args.issues)
+    print(f"corpus   : {len(corpus)} documents", file=sys.stderr)
+
+    trace = run_traced(corpus, question, args.repo, args.top)
+
+    args.out.mkdir(parents=True, exist_ok=True)
+    (args.out / "agent_trace.json").write_text(
+        json.dumps(trace.to_dict(), indent=2), encoding="utf-8")
+    (args.out / "trace_state.json").write_text(
+        json.dumps(to_tracestate(trace), indent=2), encoding="utf-8")
+
+    items = sum(len(r.items) for r in trace.retrievals)
+    edges = sum(len(r.edges) for r in trace.retrievals)
+    arm = trace.retrievals[0].arm if trace.retrievals else "n/a"
+    print(f"answer   : {trace.answer}")
+    print(f"retrieved: {items} items · {edges} edges · arm={arm} · {trace.latency_ms:.1f}ms")
+    print(f"wrote    : {args.out / 'agent_trace.json'}")
+    print(f"wrote    : {args.out / 'trace_state.json'}  ← drop into the Studio at /memory/import")
+
+
+if __name__ == "__main__":
+    main()

graphsight_langgraph/mapper.py

@@ -0,0 +1,138 @@
+"""Map an AgentTrace onto the Studio's TraceState (frontend/src/types/trace.ts).
+Positions are {0,0} on purpose; the Studio re-layouts client-side."""
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from .schema import AgentTrace
+
+# free-form kinds -> the Studio's entity types
+_KIND_TO_ENTITY = {
+    "pr": "PR",
+    "pull_request": "PR",
+    "pullrequest": "PR",
+    "service": "Service",
+    "person": "Person",
+    "user": "Person",
+    "author": "Person",
+    "document": "Document",
+    "doc": "Document",
+    "chunk": "Document",
+    "repo": "Repo",
+    "repository": "Repo",
+    "branch": "Repo",
+    "library": "Library",
+    "package": "Library",
+    "ticket": "Ticket",
+    "issue": "Ticket",
+    "jira": "Ticket",
+    "team": "Team",
+    "tool": "Tool",
+}
+
+_MAX_CONTEXT_CHARS = 8000
+
+
+def to_tracestate(trace: AgentTrace) -> dict[str, Any]:
+    """Return a TraceState-shaped dict ready for the Studio."""
+    has_edges = any(r.edges for r in trace.retrievals)
+
+    # nodes
+    nodes: list[dict[str, Any]] = []
+    seen_nodes: set[str] = set()
+    for retrieval in trace.retrievals:
+        for item in retrieval.items:
+            if item.id in seen_nodes:
+                continue
+            seen_nodes.add(item.id)
+            nodes.append(
+                {
+                    "id": item.id,
+                    "label": item.label,
+                    "type": _KIND_TO_ENTITY.get(item.kind.lower().strip(), "Document"),
+                    "active": True,  # everything retrieved was selected
+                    "position": {"x": 0, "y": 0},  # Studio re-layouts with dagre
+                    "similarity": item.vector_score,
+                    "score": item.score,
+                    "meta": {
+                        "subtitle": f"via {trace.framework} · {retrieval.arm} arm",
+                        "snippet": (item.content or "")[:600] or None,
+                        "scoreGraph": item.graph_score,
+                        "sourceUrl": item.source_uri,
+                    },
+                }
+            )
+
+    # edges (only between retrieved nodes)
+    edges: list[dict[str, Any]] = []
+    for retrieval in trace.retrievals:
+        for i, edge in enumerate(retrieval.edges):
+            if edge.source not in seen_nodes or edge.target not in seen_nodes:
+                continue
+            edges.append(
+                {
+                    "id": f"e_{retrieval.span_id[:8]}_{i}",
+                    "source": edge.source,
+                    "target": edge.target,
+                    "confidence": edge.weight if edge.weight is not None else 0.7,
+                    "active": True,
+                    "relation": edge.relation,
+                }
+            )
+
+    # execution steps from spans
+    ordered = sorted(trace.spans, key=lambda s: s.start_ms)
+    steps = []
+    for index, span in enumerate(ordered):
+        duration = (span.end_ms - span.start_ms) if span.end_ms is not None else None
+        step = {
+            "id": span.id,
+            "index": index,
+            "title": span.name,
+            "detail": f"{span.kind} · {span.status}",
+            "status": "complete" if span.status == "ok" else "pending",
+            "badge": span.kind,
+            "durationMs": round(duration, 1) if duration is not None else None,
+        }
+        if span.kind == "retriever":
+            arm = next((r.arm for r in trace.retrievals if r.span_id == span.id), None)
+            if arm in ("vector", "graph"):
+                step["arm"] = arm
+        steps.append(step)
+
+    # context for downstream answer generation
+    context = "\n\n".join(
+        item.content for r in trace.retrievals for item in r.items if item.content
+    )[:_MAX_CONTEXT_CHARS] or None
+
+    scores = [item.score for r in trace.retrievals for item in r.items if item.score is not None]
+
+    return {
+        "id": f"trace_lg_{int(time.time() * 1000)}",
+        "query": trace.query,
+        "computedAt": datetime.now(timezone.utc).isoformat(),
+        "weights": {
+            # honest split: this router didn't run, so weights describe the
+            # observed arms, not a fusion decision
+            "vector": 0.5 if has_edges else 1.0,
+            "graph": 0.5 if has_edges else 0.0,
+            "intent": "relational" if has_edges else "conceptual",
+        },
+        "confidence": {
+            "score": round(sum(scores) / len(scores), 3) if scores else 0.0,
+            "uncertainty": 0.0,
+            "rationale": (
+                f"External {trace.framework} trace — scores reported by the "
+                "retriever; Graphsight does not recompute them."
+            ),
+        },
+        "steps": steps,
+        "metrics": {
+            "queryTimeSec": round((trace.latency_ms or 0.0) / 1000.0, 3),
+            "nodesEvaluated": len(nodes),
+        },
+        "graph": {"nodes": nodes, "edges": edges},
+        "context": context,
+    }

graphsight_langgraph/schema.py

@@ -0,0 +1,76 @@
+"""AgentTrace: the framework-neutral trace contract. Plain dataclasses,
+zero deps, JSON-ready via asdict."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Literal, Optional
+
+SCHEMA_VERSION = "0.1"
+
+SpanKind = Literal["node", "retriever", "llm", "tool"]
+Arm = Literal["vector", "graph", "hybrid", "unknown"]
+
+
+@dataclass
+class Span:
+    """One unit of agent execution (a LangGraph node, a retriever call, ...)."""
+
+    id: str
+    name: str
+    kind: SpanKind
+    parent_id: Optional[str] = None
+    start_ms: float = 0.0
+    end_ms: Optional[float] = None
+    status: Literal["ok", "error", "running"] = "running"
+
+
+@dataclass
+class RetrievedItem:
+    """One retrieved chunk/entity with its provenance."""
+
+    id: str
+    label: str
+    kind: str = "document"  # free-form; mapper folds it into the Studio's types
+    score: Optional[float] = None
+    vector_score: Optional[float] = None
+    graph_score: Optional[float] = None
+    content: Optional[str] = None
+    source_uri: Optional[str] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TraceEdge:
+    """Optional relational structure between retrieved items (graph retrievers)."""
+
+    source: str
+    target: str
+    relation: Optional[str] = None
+    weight: Optional[float] = None
+
+
+@dataclass
+class Retrieval:
+    """One retrieval event inside the run."""
+
+    span_id: str
+    query: str
+    arm: Arm = "unknown"
+    items: list[RetrievedItem] = field(default_factory=list)
+    edges: list[TraceEdge] = field(default_factory=list)
+
+
+@dataclass
+class AgentTrace:
+    """The full trace of one agent run."""
+
+    query: str
+    framework: str = "langgraph"
+    schema_version: str = SCHEMA_VERSION
+    spans: list[Span] = field(default_factory=list)
+    retrievals: list[Retrieval] = field(default_factory=list)
+    answer: Optional[str] = None
+    latency_ms: Optional[float] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

graphsight_langgraph/tracer.py

@@ -0,0 +1,242 @@
+"""Callback handler that captures a LangGraph run as an AgentTrace.
+
+Pass it via config={"callbacks": [tracer]}, then call tracer.finish().
+Remember to pass the node's config into sub-runnables or their events
+won't reach the tracer (see README).
+"""
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Any, Optional
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.documents import Document
+
+from .schema import AgentTrace, Retrieval, RetrievedItem, Span, TraceEdge
+
+_SCORE_KEYS = ("score", "relevance_score", "similarity", "_score", "vector_score")
+# LangGraph internals that fire chain events but aren't user nodes
+_NOISE_NAMES = {"LangGraph", "RunnableSequence", "RunnableCallable", "ChannelWrite", "__start__", "__end__"}
+
+
+def _doc_id(doc: Document) -> str:
+    for key in ("id", "node_id", "doc_id"):
+        if doc.metadata.get(key):
+            return str(doc.metadata[key])
+    if getattr(doc, "id", None):
+        return str(doc.id)
+    return "doc_" + hashlib.sha1(doc.page_content.encode("utf-8")).hexdigest()[:10]
+
+
+def _doc_score(doc: Document) -> Optional[float]:
+    for key in _SCORE_KEYS:
+        value = doc.metadata.get(key)
+        if isinstance(value, (int, float)):
+            return float(value)
+    return None
+
+
+class LangGraphTracer(BaseCallbackHandler):
+    """Collects spans + retrievals from a LangGraph (or any LangChain) run."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._t0 = time.monotonic()
+        self._spans: dict[str, Span] = {}
+        self._order: list[str] = []
+        self._retrievals: list[Retrieval] = []
+        self._first_query: Optional[str] = None
+
+    # span bookkeeping
+    def _now_ms(self) -> float:
+        return (time.monotonic() - self._t0) * 1000.0
+
+    def _open_span(
+        self,
+        run_id: UUID,
+        parent_run_id: Optional[UUID],
+        name: str,
+        kind: str,
+    ) -> Span:
+        span = Span(
+            id=str(run_id),
+            name=name,
+            kind=kind,  # type: ignore[arg-type]
+            parent_id=str(parent_run_id) if parent_run_id else None,
+            start_ms=self._now_ms(),
+        )
+        self._spans[span.id] = span
+        self._order.append(span.id)
+        return span
+
+    def _close_span(self, run_id: UUID, status: str = "ok") -> None:
+        span = self._spans.get(str(run_id))
+        if span is not None:
+            span.end_ms = self._now_ms()
+            span.status = status  # type: ignore[assignment]
+
+    @staticmethod
+    def _resolve_name(
+        serialized: Optional[dict[str, Any]],
+        metadata: Optional[dict[str, Any]],
+        kwargs: dict[str, Any],
+        fallback: str,
+    ) -> str:
+        return (
+            kwargs.get("name")
+            or (serialized or {}).get("name")
+            or (metadata or {}).get("langgraph_node")
+            or fallback
+        )
+
+    # chain events -> node spans
+    def on_chain_start(
+        self,
+        serialized: Optional[dict[str, Any]],
+        inputs: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        name = self._resolve_name(serialized, metadata, kwargs, "chain")
+        node = (metadata or {}).get("langgraph_node")
+        # keep exactly one span per user node execution; skip framework noise
+        if name in _NOISE_NAMES or node is None or name != node:
+            return
+        self._open_span(run_id, parent_run_id, name, "node")
+
+    def on_chain_end(self, outputs: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id, status="error")
+
+    # retriever events -> spans + retrievals
+    def on_retriever_start(
+        self,
+        serialized: Optional[dict[str, Any]],
+        query: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        if self._first_query is None:
+            self._first_query = query
+        name = self._resolve_name(serialized, metadata, kwargs, "retriever")
+        span = self._open_span(run_id, parent_run_id, name, "retriever")
+        self._retrievals.append(Retrieval(span_id=span.id, query=query))
+
+    def on_retriever_end(
+        self, documents: list[Document], *, run_id: UUID, **kwargs: Any
+    ) -> None:
+        self._close_span(run_id)
+        retrieval = next(
+            (r for r in reversed(self._retrievals) if r.span_id == str(run_id)), None
+        )
+        if retrieval is None:
+            return
+        seen_edges: set[tuple[str, str, str]] = set()
+        for doc in documents:
+            item_id = _doc_id(doc)
+            retrieval.items.append(
+                RetrievedItem(
+                    id=item_id,
+                    label=str(doc.metadata.get("label") or doc.metadata.get("title") or item_id),
+                    kind=str(doc.metadata.get("kind") or doc.metadata.get("type") or "document"),
+                    score=_doc_score(doc),
+                    vector_score=_doc_score(doc),
+                    content=doc.page_content,
+                    source_uri=doc.metadata.get("source") or doc.metadata.get("source_uri"),
+                    metadata={
+                        k: v
+                        for k, v in doc.metadata.items()
+                        if k not in ("edges",) and isinstance(v, (str, int, float, bool))
+                    },
+                )
+            )
+            # optional relational structure carried on the document
+            for edge in doc.metadata.get("edges") or []:
+                key = (str(edge.get("source")), str(edge.get("target")), str(edge.get("relation")))
+                if key in seen_edges or not edge.get("source") or not edge.get("target"):
+                    continue
+                seen_edges.add(key)
+                retrieval.edges.append(
+                    TraceEdge(
+                        source=str(edge["source"]),
+                        target=str(edge["target"]),
+                        relation=edge.get("relation"),
+                        weight=edge.get("weight"),
+                    )
+                )
+        retrieval.arm = "graph" if retrieval.edges else "vector"
+
+    def on_retriever_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id, status="error")
+
+    # llm / tool events -> plain spans
+    def on_llm_start(
+        self,
+        serialized: Optional[dict[str, Any]],
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._open_span(
+            run_id, parent_run_id, self._resolve_name(serialized, metadata, kwargs, "llm"), "llm"
+        )
+
+    def on_llm_end(self, response: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id)
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id, status="error")
+
+    def on_tool_start(
+        self,
+        serialized: Optional[dict[str, Any]],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._open_span(
+            run_id, parent_run_id, self._resolve_name(serialized, metadata, kwargs, "tool"), "tool"
+        )
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._close_span(run_id, status="error")
+
+    # result
+    def finish(self, query: Optional[str] = None, answer: Optional[str] = None) -> AgentTrace:
+        """Assemble the AgentTrace after the run completes."""
+        spans = [self._spans[sid] for sid in self._order]
+        for span in spans:  # close anything left dangling
+            if span.end_ms is None:
+                span.end_ms = self._now_ms()
+                span.status = "ok" if span.status == "running" else span.status
+        latency = max((s.end_ms or 0.0) for s in spans) if spans else None
+        return AgentTrace(
+            query=query or self._first_query or "",
+            spans=spans,
+            retrievals=self._retrievals,
+            answer=answer,
+            latency_ms=latency,
+        )

graphsight_langgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: graphsight-langgraph
+Version: 0.1.0
+Summary: Capture LangGraph agent runs as Graphsight traces — see exactly what your agent retrieved and why.
+Author: Arush Karnatak
+License: MIT
+Project-URL: Repository, https://github.com/Kcodess2807/graphsight
+Project-URL: Documentation, https://github.com/Kcodess2807/graphsight/tree/main/graphsight-langgraph
+Keywords: langgraph,langchain,tracing,observability,rag,retrieval,agents
+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
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: example
+Requires-Dist: langgraph>=0.2; extra == "example"
+Dynamic: license-file
+
+# graphsight-langgraph
+
+**See exactly why your LangGraph agent picked the context it picked.**
+
+One callback handler captures a [LangGraph](https://github.com/langchain-ai/langgraph)
+run — every node, every retriever call, per-document scores, and (for
+graph-aware retrievers) the relational paths between retrieved entities — as a
+framework-neutral `AgentTrace`. One function maps it to a JSON file the
+[Graphsight Studio](../frontend) renders with **zero backend**.
+
+```
+your LangGraph agent ──▶ LangGraphTracer ──▶ AgentTrace (v0.1) ──▶ to_tracestate() ──▶ Studio /memory/import
+                          (callbacks)         neutral JSON           Studio JSON          full canvas render
+```
+
+This package is standalone. It does **not** require the TraceRAG engine,
+database, or SaaS stack — its only dependency is `langchain-core`.
+
+## Install
+
+```bash
+pip install -e .            # the tracer (depends only on langchain-core)
+pip install -e ".[example]" # + langgraph, to run the demo agent
+```
+
+Python ≥ 3.10. Verified against `langchain-core 1.5.0` + current `langgraph`.
+
+## Quickstart
+
+```python
+from graphsight_langgraph import LangGraphTracer, to_tracestate
+
+tracer = LangGraphTracer()
+result = graph.invoke(inputs, config={"callbacks": [tracer]})
+
+trace = tracer.finish(
+    query="why is checkout failing?",
+    answer=result["answer"],
+)
+
+trace.to_dict()          # framework-neutral AgentTrace (schema v0.1)
+to_tracestate(trace)     # Studio-ready JSON → drop into /memory/import
+```
+
+That's the whole API surface: construct, pass as a callback, `finish()`, map.
+
+### ⚠ The one gotcha: config propagation
+
+LangChain only propagates callbacks into runnables that receive the run's
+config. Inside a LangGraph node, **pass the node's config through** to
+sub-runnables, or the tracer will see the node but not what happened inside it:
+
+```python
+def retrieve(state, config):                               # ① accept config
+    docs = retriever.invoke(state["q"], config=config)     # ② pass it through
+    return {"docs": docs}
+```
+
+If your trace shows node spans but no retrievals, this is why.
+
+## Try it in 60 seconds (offline, no API keys)
+
+```bash
+python example/demo_agent.py
+```
+
+This builds and runs a real two-node LangGraph agent (`retrieve → answer`)
+over an in-memory "codebase memory" corpus — a PR, a service, a person, and a
+ticket, connected by edges — and traces it:
+
+```
+answer   : The regression traces to PR #4821 in checkout-service, authored by Priya N. …
+spans    : 3 (retrieve, CodebaseMemoryRetriever, answer)
+retrieved: 4 items · 4 edges · arm=graph
+latency  : 3.9ms
+```
+
+Two files land in `example/out/`:
+
+| File | What it is |
+|---|---|
+| `agent_trace.json` | the neutral `AgentTrace` — what any consumer would ingest |
+| `trace_state.json` | Studio-ready — drag-and-drop (or paste) into `http://localhost:5173/memory/import` |
+
+In the Studio you'll see the full canvas: four typed entity nodes with score
+chips, the traced relational path (person → PR → service, PR → ticket), the
+execution timeline with per-span timings, and the retriever's arm.
+
+Tip: with [`graphsight`](../graphsight) installed, skip the manual
+drop — `graphsight example/out/trace_state.json` serves the UI locally
+and opens the trace directly.
+
+## Trace your own GitHub repo
+
+The package ships a dead-simple ingest CLI — one command from repo to trace:
+
+```bash
+graphsight-github-trace langchain-ai/langgraph "who fixed the recent streaming bugs?"
+graphsight graphsight_out/trace_state.json
+```
+
+It fetches recent PRs + issues (public repos need no token; `--token` /
+`GITHUB_TOKEN` for private), builds a corpus with relational edges
+(`person AUTHORED pr`, `pr RESOLVES issue`, `pr TOUCHES repo`), and runs a
+traced two-node LangGraph agent over it. Retrieval is two-arm in miniature:
+lexical seeds + 1-hop graph expansion along the edges — simple on purpose,
+and the scores shown are exactly the lexical scores computed, nothing
+dressed up as semantic. Requires the `example` extra (`langgraph`).
+
+## What gets captured
+
+| Source in the run | Captured as |
+|---|---|
+| Each LangGraph node execution | `Span(kind="node")` with monotonic-clock timing |
+| Framework internals (`RunnableSequence`, `ChannelWrite`, `__start__`, …) | **filtered out** — one span per user node, no noise |
+| `on_retriever_end` documents | one `RetrievedItem` per doc: id, label, kind, score, content, source |
+| `Document.metadata` score keys (`score`, `relevance_score`, `similarity`, …) | item scores |
+| `Document.metadata["edges"]` = `[{source, target, relation, weight}]` | relational edges (deduplicated) |
+| LLM / tool calls | plain spans in the execution timeline |
+| Edges present in a retrieval? | `arm = "graph"`, else `"vector"` — auto-detected |
+
+### Honest degradation — stated plainly
+
+- **Vector-only retriever** (no edges in metadata) → the Studio renders a flat
+  scored-retrieval view instead of relational path highlighting. Still useful;
+  just not graph-aware.
+- **No score keys** → scores stay `None` and no score chips render.
+  **Nothing is ever fabricated.**
+- The emitted `confidence.rationale` explicitly says scores came from *your*
+  retriever and Graphsight does not recompute them — an imported trace never
+  masquerades as an engine-computed one.
+
+## Schema (v0.1)
+
+`AgentTrace` is the stable contract; future adapters (LlamaIndex, raw OTel)
+emit the same shape.
+
+```jsonc
+{
+  "schema_version": "0.1",
+  "framework": "langgraph",
+  "query": "…",
+  "spans": [
+    { "id": "…", "name": "retrieve", "kind": "node",       // node | retriever | llm | tool | chain
+      "parent_id": null, "start_ms": 0.0, "end_ms": 0.3, "status": "ok" }
+  ],
+  "retrievals": [
+    {
+      "span_id": "…", "query": "…",
+      "arm": "graph",                                       // "vector" | "graph" (auto: edges present?)
+      "items": [
+        { "id": "pr_4821", "label": "PR #4821", "kind": "pull_request",
+          "score": 0.94, "vector_score": null, "graph_score": null,
+          "content": "…", "source_uri": "https://…", "metadata": {} }
+      ],
+      "edges": [                                            // optional — the graph-aware view
+        { "source": "pr_4821", "target": "svc_checkout", "relation": "TOUCHES", "weight": 0.9 }
+      ]
+    }
+  ],
+  "answer": "…",
+  "latency_ms": 3.9
+}
+```
+
+`to_tracestate()` maps this onto the Studio's `TraceState`
+([frontend/src/types/trace.ts](../frontend/src/types/trace.ts)). Free-form
+`kind` strings are normalized to Studio entity types
+(`pull_request → PR`, `service → Service`, `person/author → Person`,
+`ticket/issue/jira → Ticket`, … fallback `Document`). Node positions are
+recomputed client-side by the Studio's layout engine, so emitters never deal
+with coordinates.
+
+## Package layout
+
+```
+graphsight-langgraph/
+├── graphsight_langgraph/
+│   ├── schema.py         # AgentTrace v0.1 — zero-dependency dataclasses
+│   ├── tracer.py         # LangGraphTracer (BaseCallbackHandler)
+│   ├── mapper.py         # to_tracestate() — AgentTrace → Studio TraceState
+│   └── github_ingest.py  # `graphsight-github-trace` CLI (repo → trace)
+├── example/
+│   └── demo_agent.py     # offline end-to-end demo (writes example/out/*.json)
+└── pyproject.toml
+```
+
+## Status & roadmap
+
+**v0.1** — verified end-to-end against `langchain-core 1.5.0` + current
+`langgraph`: spans, scored items, edges, and arm detection all captured from a
+real run and rendered in the Studio.
+
+Known limits, honestly:
+
+- Score-key coverage is the pragmatic short list above; real-world retrievers
+  vary, and unrecognized keys degrade to `None` (visible, not wrong).
+- Edges are read from a documented metadata convention
+  (`metadata["edges"]`) — retrievers must opt in to the graph-aware view.
+- Async (`ainvoke` / `astream`) uses the same callback events but hasn't been
+  exercised in the verification run yet.
+
+Planned next, in order: **LlamaIndex adapter** emitting the same
+`AgentTrace`, then a raw **OTel span** ingestor. The schema is the contract;
+the adapters are thin.

graphsight_langgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+graphsight_langgraph/__init__.py,sha256=aDkf8Yw9kXbQDyuPgn4hI1IJo2ptk6mwHU1GU2OZzdk,738
+graphsight_langgraph/github_ingest.py,sha256=xoI4ORIIYyxeWh-cwfIHTlJ_7-XxnUi_VkX8i9MmRkI,12049
+graphsight_langgraph/mapper.py,sha256=rawV9V0rZHc5qgh4VVd5KBQ2blb7s7l19yrSOoGu5wo,4947
+graphsight_langgraph/schema.py,sha256=k8c5hVG28Z5J14y3wReiZQ_8q4ktw8FP4eh5uho8gTY,2012
+graphsight_langgraph/tracer.py,sha256=As0QWJ0GlmARAzWhP0YRnrqi314oqXMnQXJ6az3n0lc,8882
+graphsight_langgraph-0.1.0.dist-info/licenses/LICENSE,sha256=BBF3PPfyR6ahuORavA-9uyS5VNJijJP-EibBsfWofJc,1071
+graphsight_langgraph-0.1.0.dist-info/METADATA,sha256=CfiLKC7ONYfJFM1LdoPLqldMC-5X_8RFIKeT1lW0X58,9613
+graphsight_langgraph-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+graphsight_langgraph-0.1.0.dist-info/entry_points.txt,sha256=bbm3x_Uqh5YHukz6I85wprPwTmpos4IEyVtZo4PFnLo,84
+graphsight_langgraph-0.1.0.dist-info/top_level.txt,sha256=TTw8Df4JLlu0DCHjnAEXznT61NtnA-1mH51ISR6Xq1M,21
+graphsight_langgraph-0.1.0.dist-info/RECORD,,

graphsight_langgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

graphsight_langgraph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+graphsight-github-trace = graphsight_langgraph.github_ingest:main

graphsight_langgraph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +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.

graphsight_langgraph-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graphsight_langgraph