graphmind-ai 0.2.1__py3-none-any.whl

graphmind/__init__.py

@@ -0,0 +1,188 @@
+"""GraphMind — a live debugger for AI agents.
+
+Phoenix and Langfuse show you what your agent *did*. GraphMind attaches while
+it's happening: an instrumented app streams execution events to a local viewer,
+which renders the run as a live graph and can **hold execution** — before an
+LLM step, before/after a tool call, or on error — then resume with
+``continue`` / ``retry`` / ``inject`` / ``abort``.
+
+Quickstart::
+
+    import graphmind as gm
+    from openai import OpenAI
+
+    client = gm.instrument_openai(OpenAI())
+
+    @gm.tool
+    def search_flights(origin: str, destination: str) -> list[dict]:
+        ...
+
+    with gm.run("handle-ticket"):
+        client.chat.completions.create(model="gpt-5", messages=[...])
+
+Then run ``graphmind serve`` (from the ``graphmind-ai`` npm CLI) and open the
+viewer. With nothing attached, all of the above is a no-op.
+
+Everything fails open: no debugger means near-zero overhead, and a debugger
+that disconnects mid-hold auto-continues every held gate.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from ._version import __version__
+from .api import GraphMind, Span, configure, init, instance, is_configured, reset
+from .env import DEFAULT_URL
+from .errors import GraphMindAbortError, is_abort_error
+from .gate import GateDecision, GateNode
+from .protocol import PROTOCOL_VERSION
+from .session import RunContext, RunScope, Session, SessionStats
+
+__all__ = [
+    "DEFAULT_URL",
+    "PROTOCOL_VERSION",
+    "AsyncGraphMindCallbackHandler",
+    "GateDecision",
+    "GateNode",
+    "GraphMind",
+    "GraphMindAbortError",
+    "GraphMindCallbackHandler",
+    "RunContext",
+    "RunScope",
+    "Session",
+    "SessionStats",
+    "Span",
+    "__version__",
+    "async_callback_handler",
+    "async_handler",
+    "callback_handler",
+    "configure",
+    "dispose",
+    "emit",
+    "graph_hint",
+    "handler",
+    "init",
+    "instance",
+    "instrument_anthropic",
+    "instrument_openai",
+    "is_abort_error",
+    "is_configured",
+    "ready",
+    "ready_async",
+    "reset",
+    "run",
+    "session",
+    "span",
+    "stats",
+    "tool",
+    "wrap_anthropic",
+    "wrap_openai",
+    "wrap_tools",
+]
+
+
+# -- module-level convenience API (delegates to the default instance) ---------
+
+
+def run(name: str, meta: dict[str, Any] | None = None) -> RunScope:
+    """Run boundary. Works as ``with gm.run(...)`` and ``async with gm.run(...)``."""
+    return instance().run(name, meta)
+
+
+def span(name: str, kind: str = "custom", input: Any = None, parent_id: str | None = None) -> Span:
+    """A gated, timed node for code GraphMind cannot see by itself."""
+    return instance().span(name, kind, input, parent_id)
+
+
+def tool(
+    fn: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    kind: str = "tool",
+    parent_id: str | None = None,
+) -> Any:
+    """Decorate a tool function so the debugger can pause, retry and inject it."""
+    return instance().tool(fn, name=name, kind=kind, parent_id=parent_id)
+
+
+def wrap_tools(tools: Any) -> Any:
+    """Wrap a ``{name: fn}`` mapping, a list of callables, or one callable."""
+    return instance().wrap_tools(tools)
+
+
+def instrument_openai(client: Any) -> Any:
+    """Instrument an ``openai`` client in place and return it."""
+    return instance().instrument_openai(client)
+
+
+#: Alias for people used to other tooling's naming.
+wrap_openai = instrument_openai
+
+
+def instrument_anthropic(client: Any) -> Any:
+    """Instrument an ``anthropic`` client in place and return it."""
+    return instance().instrument_anthropic(client)
+
+
+wrap_anthropic = instrument_anthropic
+
+
+def ready(timeout: float = 2.0) -> bool:
+    """Block until a debugger is attached. ``False`` means "carry on detached"."""
+    return instance().ready(timeout)
+
+
+async def ready_async(timeout: float = 2.0) -> bool:
+    """Async twin of :func:`ready`."""
+    return await instance().ready_async(timeout)
+
+
+def emit(type: str, payload: dict[str, Any]) -> None:
+    """Emit a raw protocol event (advanced)."""
+    instance().emit(type, payload)
+
+
+def graph_hint(nodes: Iterable[dict[str, Any]]) -> None:
+    """Pre-announce static graph structure so the viewer renders it grey."""
+    instance().graph_hint(nodes)
+
+
+def stats() -> SessionStats:
+    """Diagnostics snapshot of the default session."""
+    return instance().stats()
+
+
+def session() -> Session:
+    """The default instance's underlying session (advanced)."""
+    return instance().session
+
+
+def dispose() -> None:
+    """Release held gates, flush events, close the socket. Idempotent."""
+    instance().dispose()
+
+
+def callback_handler(**kwargs: Any) -> Any:
+    """A sync LangChain/LangGraph handler bound to the default session."""
+    return instance().callback_handler(**kwargs)
+
+
+def async_callback_handler(**kwargs: Any) -> Any:
+    """An async LangChain/LangGraph handler bound to the default session."""
+    return instance().async_callback_handler(**kwargs)
+
+
+#: Short aliases matching the docs and `graphmind init` scaffolding.
+handler = callback_handler
+async_handler = async_callback_handler
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily expose the LangChain handlers without importing langchain_core."""
+    if name in ("GraphMindCallbackHandler", "AsyncGraphMindCallbackHandler"):
+        from .integrations import langchain
+
+        return getattr(langchain, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

graphmind/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the package version (mirrors pyproject.toml)."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

graphmind/api.py

@@ -0,0 +1,344 @@
+"""The public surface: :class:`GraphMind` plus the module-level default instance.
+
+    import graphmind as gm
+
+    gm.configure(app="support-agent")          # optional
+
+    @gm.tool
+    def search_flights(origin: str, dest: str) -> list[dict]:
+        ...
+
+    client = gm.instrument_openai(OpenAI())
+
+    with gm.run("handle-ticket"):
+        client.chat.completions.create(...)
+
+Everything degrades to a no-op when no debugger is attached, and to literally
+nothing when GraphMind is disabled.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable, Iterable
+from typing import Any, TypeVar
+
+from ._version import __version__
+from .gate import GateDecision, GateNode
+from .ids import next_id
+from .protocol import NODE_KINDS
+from .session import RunContext, RunScope, Session, SessionStats
+from .wrap import ToolsInput, gate_callable
+from .wrap import wrap_tools as _wrap_tools
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class GraphMind:
+    """One debugger attachment point for a process."""
+
+    def __init__(
+        self,
+        *,
+        app: str = "python-app",
+        sdk: dict[str, str] | None = None,
+        **session_options: Any,
+    ) -> None:
+        self.session = Session(
+            app_name=app,
+            sdk=sdk if sdk is not None else {"name": "python", "version": __version__},
+            **session_options,
+        )
+
+    # -- attach ---------------------------------------------------------------
+
+    @property
+    def enabled(self) -> bool:
+        return self.session.enabled
+
+    @property
+    def attached(self) -> bool:
+        return self.session.attached
+
+    def ready(self, timeout: float = 2.0) -> bool:
+        """Block until the debugger handshake completes (breakpoints armed)."""
+        return self.session.ready(timeout)
+
+    async def ready_async(self, timeout: float = 2.0) -> bool:
+        """Async twin of :meth:`ready`."""
+        return await self.session.ready_async(timeout)
+
+    # -- runs & spans ---------------------------------------------------------
+
+    def run(self, name: str, meta: dict[str, Any] | None = None) -> RunScope:
+        """Run boundary; works as ``with`` and ``async with``."""
+        return self.session.run(name, meta)
+
+    def span(
+        self,
+        name: str,
+        kind: str = "custom",
+        input: Any = None,
+        parent_id: str | None = None,
+    ) -> Span:
+        """An arbitrary node on the canvas: gated, timed, sync **and** async.
+
+        Use it for the parts of a graph GraphMind cannot see by itself — a
+        LangGraph node body, a retrieval step, a hand-rolled planner loop.
+        """
+        return Span(self.session, name, kind, input, parent_id)
+
+    def current_run(self) -> RunContext | None:
+        return self.session.current_run()
+
+    # -- tools ----------------------------------------------------------------
+
+    def tool(
+        self,
+        fn: F | None = None,
+        *,
+        name: str | None = None,
+        kind: str = "tool",
+        parent_id: str | None = None,
+    ) -> Any:
+        """Decorator. Usable bare (``@gm.tool``) or called (``@gm.tool(name=...)``)."""
+
+        def decorate(target: F) -> F:
+            return gate_callable(
+                target,
+                lambda: self.session,
+                name=name,
+                kind=kind,
+                parent_id=parent_id,
+            )
+
+        if fn is None:
+            return decorate
+        return decorate(fn)
+
+    def wrap_tools(self, tools: ToolsInput) -> Any:
+        """Wrap a ``{name: fn}`` mapping, a list of callables, or one callable."""
+        return _wrap_tools(tools, lambda: self.session)
+
+    # -- integrations ---------------------------------------------------------
+
+    def instrument_openai(self, client: Any) -> Any:
+        """Instrument an ``openai.OpenAI`` / ``AsyncOpenAI`` client in place."""
+        from .integrations.openai import instrument_openai
+
+        return instrument_openai(client, self.session)
+
+    #: Alias matching the naming other tools use.
+    wrap_openai = instrument_openai
+
+    def instrument_anthropic(self, client: Any) -> Any:
+        """Instrument an ``anthropic.Anthropic`` / ``AsyncAnthropic`` client in place."""
+        from .integrations.anthropic import instrument_anthropic
+
+        return instrument_anthropic(client, self.session)
+
+    wrap_anthropic = instrument_anthropic
+
+    def callback_handler(self, **kwargs: Any) -> Any:
+        """A sync LangChain/LangGraph ``BaseCallbackHandler`` bound to this session."""
+        from .integrations.langchain import GraphMindCallbackHandler
+
+        return GraphMindCallbackHandler(session=self.session, **kwargs)
+
+    def async_callback_handler(self, **kwargs: Any) -> Any:
+        """An async LangChain/LangGraph ``AsyncCallbackHandler`` bound to this session."""
+        from .integrations.langchain import AsyncGraphMindCallbackHandler
+
+        return AsyncGraphMindCallbackHandler(session=self.session, **kwargs)
+
+    #: Short aliases: the names the docs and `graphmind init` scaffolding use.
+    handler = callback_handler
+    async_handler = async_callback_handler
+
+    # -- low level ------------------------------------------------------------
+
+    def emit(self, type: str, payload: dict[str, Any]) -> None:
+        self.session.emit(type, payload)
+
+    def gate(self, point: str, node: GateNode) -> GateDecision:
+        return self.session.gate(point, node)
+
+    async def gate_async(self, point: str, node: GateNode) -> GateDecision:
+        return await self.session.gate_async(point, node)
+
+    def graph_hint(self, nodes: Iterable[dict[str, Any]]) -> None:
+        """Pre-announce static graph structure so the viewer renders it grey."""
+        self.session.graph_hint(nodes)
+
+    def stats(self) -> SessionStats:
+        return self.session.stats()
+
+    def dispose(self) -> None:
+        """Release held gates, flush events, close the socket. Idempotent."""
+        self.session.dispose()
+
+    def __enter__(self) -> GraphMind:
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.dispose()
+
+
+class Span:
+    """A user-declared node, gated like a tool. ``with`` and ``async with``."""
+
+    __slots__ = (
+        "_done",
+        "_input",
+        "_instance_id",
+        "_kind",
+        "_name",
+        "_node",
+        "_output",
+        "_parent_id",
+        "_session",
+        "_started",
+    )
+
+    def __init__(
+        self,
+        session: Session,
+        name: str,
+        kind: str,
+        input: Any,
+        parent_id: str | None,
+    ) -> None:
+        self._session = session
+        self._name = name
+        self._kind = kind if kind in NODE_KINDS else "custom"
+        self._input = input
+        self._parent_id = parent_id
+        self._node = GateNode(f"{self._kind}:{name}", self._kind, name)
+        self._instance_id = ""
+        self._started = 0.0
+        self._output: Any = None
+        self._done = False
+
+    @property
+    def node_id(self) -> str:
+        return self._node.node_id
+
+    def set_output(self, output: Any) -> None:
+        """Record what this span produced (shown on the node in the viewer)."""
+        self._output = output
+
+    def __enter__(self) -> Span:
+        self._begin()
+        decision = self._session.gate("before", self._node)
+        self._check(decision)
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self._end(exc)
+
+    async def __aenter__(self) -> Span:
+        self._begin()
+        decision = await self._session.gate_async("before", self._node)
+        self._check(decision)
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self._end(exc)
+
+    def _begin(self) -> None:
+        self._instance_id = next_id("span")
+        self._started = time.monotonic()
+        self._session.start_node(
+            node_id=self._node.node_id,
+            kind=self._kind,
+            name=self._name,
+            instance_id=self._instance_id,
+            parent_id=self._parent_id,
+            input=self._input,
+        )
+
+    def _check(self, decision: GateDecision) -> None:
+        if decision.action == "abort":
+            self._finish(None, "aborted")
+            raise self._session.abort_error()
+        if decision.action == "inject":
+            # A span owns no return value, so an injected one is surfaced as
+            # the span's output rather than silently dropped.
+            self._output = decision.output
+
+    def _end(self, error: BaseException | None) -> None:
+        from .errors import is_abort_error
+
+        if error is not None:
+            status = "aborted" if is_abort_error(error) else "error"
+            if status == "error":
+                self._session.error_node(self._node.node_id, self._instance_id, error)
+            self._finish(self._output, status)
+            return
+        self._finish(self._output, "ok")
+
+    def _finish(self, output: Any, status: str) -> None:
+        if self._done:
+            return
+        self._done = True
+        self._session.finish_node(
+            node_id=self._node.node_id,
+            instance_id=self._instance_id,
+            duration_ms=(time.monotonic() - self._started) * 1000.0,
+            status=status,
+            output=output,
+        )
+
+
+# -- module-level default instance -------------------------------------------
+
+_default: GraphMind | None = None
+_default_lock = threading.Lock()
+
+
+def configure(**options: Any) -> GraphMind:
+    """Create (or replace) the process-wide default instance.
+
+    Accepts everything :class:`GraphMind` accepts: ``app``, ``sdk``, ``url``,
+    ``enabled``, ``meta``, ``connect_timeout``, ``handshake_timeout``,
+    ``retry_interval``, ``buffer_size``, ``pause_timeout``, ``token_interval``,
+    ``env``, ``logger``.
+    """
+    global _default
+    with _default_lock:
+        previous = _default
+        _default = GraphMind(**options)
+    if previous is not None:
+        previous.dispose()
+    return _default
+
+
+def instance() -> GraphMind:
+    """The default instance, created with defaults on first use."""
+    global _default
+    current = _default
+    if current is not None:
+        return current
+    with _default_lock:
+        if _default is None:
+            _default = GraphMind()
+        return _default
+
+
+#: `init` is the name the docs and `graphmind init` scaffolding use.
+init = configure
+
+
+def is_configured() -> bool:
+    return _default is not None
+
+
+def reset() -> None:
+    """Dispose and forget the default instance (mainly for tests)."""
+    global _default
+    with _default_lock:
+        current = _default
+        _default = None
+    if current is not None:
+        current.dispose()

graphmind/env.py

@@ -0,0 +1,74 @@
+"""Kill switches and environment-derived defaults.
+
+Precedence for "is GraphMind enabled" (mirrors ``packages/client/src/env.ts``,
+with a Python-flavoured production check because there is no ``NODE_ENV``):
+
+1. ``GRAPHMIND_DISABLED=1``  -> disabled, always. Ops-level kill switch; beats
+   an explicit ``enabled=True`` passed in code.
+2. explicit ``enabled=`` argument -> as given.
+3. **looks like production** -> disabled unless ``GRAPHMIND=1``.
+4. otherwise -> enabled.
+
+"Looks like production" is deliberately a *documented, boring* rule: the first
+variable that is set out of ``GRAPHMIND_ENV``, ``ENVIRONMENT``, ``APP_ENV``,
+``PYTHON_ENV``, ``ENV``, ``DJANGO_ENV``, ``FLASK_ENV``, ``NODE_ENV`` decides,
+and it counts as production when its value is ``production``/``prod``
+(case-insensitive). No heuristics over hostnames, cloud metadata or TTYs — a
+debugger that silently turns itself off for surprising reasons is worse than
+one you must switch on.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+EnvLike = Mapping[str, str]
+
+DEFAULT_URL = "ws://127.0.0.1:4747/ingest"
+
+#: Checked in order; the first one that is *set* decides the environment.
+ENV_VARS = (
+    "GRAPHMIND_ENV",
+    "ENVIRONMENT",
+    "APP_ENV",
+    "PYTHON_ENV",
+    "ENV",
+    "DJANGO_ENV",
+    "FLASK_ENV",
+    "NODE_ENV",
+)
+
+_PRODUCTION_VALUES = frozenset({"production", "prod"})
+
+
+def _env(env: EnvLike | None) -> EnvLike:
+    return os.environ if env is None else env
+
+
+def looks_like_production(env: EnvLike | None = None) -> bool:
+    """True when the first set environment variable in :data:`ENV_VARS` is production."""
+    source = _env(env)
+    for key in ENV_VARS:
+        value = source.get(key)
+        if value is None or value == "":
+            continue
+        return value.strip().lower() in _PRODUCTION_VALUES
+    return False
+
+
+def resolve_enabled(explicit: bool | None = None, env: EnvLike | None = None) -> bool:
+    """Apply the kill-switch precedence documented in this module."""
+    source = _env(env)
+    if source.get("GRAPHMIND_DISABLED") == "1":
+        return False
+    if explicit is not None:
+        return explicit
+    return not (looks_like_production(source) and source.get("GRAPHMIND") != "1")
+
+
+def resolve_url(explicit: str | None = None, env: EnvLike | None = None) -> str:
+    """Viewer endpoint: explicit argument, then ``GRAPHMIND_URL``, then the default."""
+    if explicit is not None:
+        return explicit
+    return _env(env).get("GRAPHMIND_URL") or DEFAULT_URL

graphmind/errors.py

@@ -0,0 +1,66 @@
+"""Abort plumbing and error serialization.
+
+Mirrors ``packages/client/src/errors.ts``. The debugger's ``abort`` action
+must surface as an error the host's SDK treats as *terminal* — never as a
+transient failure that provider retry logic will re-issue. In Python there is
+no ``AbortController``; the run context carries a flag plus an event, and
+instrumentation raises :class:`GraphMindAbortError`.
+"""
+
+from __future__ import annotations
+
+import traceback
+from typing import Any
+
+# Names that mean "this was cancelled on purpose, do not retry". The TS client
+# recognises the same two, plus Python's own cancellation exceptions.
+_ABORT_NAMES = frozenset({"AbortError", "GraphMindAbortError", "CancelledError"})
+
+
+class GraphMindAbortError(Exception):
+    """Raised into the host when the debugger resolves a gate with ``abort``.
+
+    ``.name`` is ``"AbortError"`` so wire payloads match what the TypeScript
+    client emits for the same situation.
+    """
+
+    name = "AbortError"
+
+    def __init__(self, message: str = "Run aborted by GraphMind debugger") -> None:
+        super().__init__(message)
+
+
+def is_abort_error(error: BaseException | None) -> bool:
+    """True for GraphMind aborts and for stdlib cancellation exceptions."""
+    if error is None:
+        return False
+    if isinstance(error, GraphMindAbortError):
+        return True
+    # asyncio.CancelledError inherits BaseException on 3.8+, so name-match too.
+    return type(error).__name__ in _ABORT_NAMES
+
+
+def _short_stack(error: BaseException, limit: int = 4096) -> str | None:
+    try:
+        text = "".join(traceback.format_exception(type(error), error, error.__traceback__))
+    except Exception:  # pragma: no cover - formatting a broken traceback
+        return None
+    if not text:
+        return None
+    return text[:limit]
+
+
+def to_error_info(error: Any) -> dict[str, Any]:
+    """Serialize any raised object into the wire ``ErrorInfo`` shape."""
+    if isinstance(error, BaseException):
+        # A custom `.name` (GraphMindAbortError) wins over the class name so
+        # the viewer shows "AbortError" like the TypeScript client does.
+        name = getattr(error, "name", None)
+        if not isinstance(name, str) or not name:
+            name = type(error).__name__
+        info: dict[str, Any] = {"name": name, "message": str(error)}
+        stack = _short_stack(error)
+        if stack is not None:
+            info["stack"] = stack
+        return info
+    return {"name": "Error", "message": str(error)}