agentship-langgraph 0.0.1__py3-none-any.whl

agentship_langgraph/__init__.py

@@ -0,0 +1,17 @@
+"""The LangGraph engine package — AgentShip's default real-model engine.
+
+:class:`~agentship_langgraph.engine.LangGraphEngine` builds the agent — either its
+own default single-agent graph (system prompt + user input → chat model → answer)
+or, when a developer subclasses :class:`~agentship_langgraph.agent.LangGraphAgent`
+and implements ``build_graph(model, tools)``, that author's native graph — over a
+LiteLLM-backed model resolved by :mod:`agentship_langgraph.models`. It ships as the
+``agentship-langgraph`` dist and is discovered via the ``agentship.engines``
+entry-point group, so ``engine: langgraph`` in a spec resolves here.
+"""
+
+from __future__ import annotations
+
+from .agent import LangGraphAgent
+from .engine import LangGraphEngine
+
+__all__ = ["LangGraphAgent", "LangGraphEngine"]

agentship_langgraph/agent.py

@@ -0,0 +1,77 @@
+"""The custom-authoring base class: :class:`LangGraphAgent`.
+
+This is the answer to CRUX 1 (DESIGN §4.3): *"how do I build a custom LangGraph
+agent while still getting AgentShip's wired services?"* A developer subclasses
+:class:`LangGraphAgent` and writes native LangGraph in :meth:`build_graph` — nodes,
+edges, conditional routing, subgraphs, anything LangGraph does. The engine's
+``build(spec)`` resolves the ``model`` and ``tools`` and hands them to
+``build_graph`` as plain, already-wired params; the author never wires a vendor
+themselves and never loses native power. Per-request services (memory recall,
+tracing, caller identity) are read from ``RunContext`` inside the nodes, not passed
+in a bundle — there is deliberately no ``EngineKit``.
+
+The author points a spec's ``code:`` at a factory that returns a configured
+subclass instance (which carries its own ``.spec``); the core threads that object
+to :meth:`~agentship_langgraph.engine.LangGraphEngine.build`, which calls
+``build_graph``. Every LangChain/LangGraph type stays inside this adapter — the
+vendor-neutral core never sees one.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from agentship.errors import CapabilityError
+
+if TYPE_CHECKING:
+    from agentship.spec import AgentSpec
+    from langchain_core.language_models.chat_models import BaseChatModel
+    from langchain_core.tools import BaseTool
+    from langgraph.graph import StateGraph
+
+
+class LangGraphAgent(ABC):
+    """Base class a developer subclasses to author a native LangGraph agent.
+
+    A subclass implements :meth:`build_graph` in native LangGraph; the engine
+    binding is fixed to ``"langgraph"`` and ``run``/``stream``/``resume`` are
+    provided by the engine adapter (the author never writes them). Construct one
+    with its :class:`~agentship.spec.AgentSpec`; the spec's ``engine`` must be
+    ``"langgraph"`` or construction fails fast with a
+    :class:`~agentship.errors.CapabilityError` (never a silent mis-bind).
+    """
+
+    #: The engine this agent is bound to. Fixed for every LangGraph agent so the
+    #: subclass never has to restate it; the spec's ``engine`` must still match.
+    engine_name = "langgraph"
+
+    def __init__(self, spec: AgentSpec) -> None:
+        """Bind ``spec`` to this agent, asserting its engine is ``langgraph``.
+
+        The custom-authoring path only makes sense when the spec targets this
+        engine; a spec whose ``engine`` is anything else is a misconfiguration, so
+        it fails fast here (declare, don't fake) rather than compiling a graph the
+        wrong engine would try to drive.
+        """
+        if spec.engine != self.engine_name:
+            raise CapabilityError(
+                f"{type(self).__name__} is a LangGraph agent, but its spec sets "
+                f"engine: {spec.engine!r} — set engine: {self.engine_name!r} or use the "
+                f"matching engine's agent base class."
+            )
+        self.spec = spec
+
+    @abstractmethod
+    def build_graph(self, model: BaseChatModel, tools: list[BaseTool]) -> StateGraph:
+        """Return a native LangGraph ``StateGraph`` built over the wired pieces.
+
+        The engine passes ``model`` (a LiteLLM-backed, cost-traced chat model it
+        resolved from the spec / ``RunContext.routed_model``) and ``tools`` (adapted
+        MCP/python tools — an empty list until Phase 03 wires tool execution). Build
+        and return your graph using them; the engine compiles it (attaching the
+        checkpointer/store it resolved, plus callbacks) and drives ``run``/``stream``.
+        You may return an already-compiled graph — the engine detects that and reuses
+        it. Read per-request services (memory, tracing, caller identity) from
+        ``RunContext`` via ``get_run_context()`` inside your nodes.
+        """

agentship_langgraph/durability.py

@@ -0,0 +1,58 @@
+"""The durable-checkpointer substrate for the LangGraph engine (Phase 02 · C4).
+
+One decision lives here: which LangGraph checkpointer a run uses. With no database configured
+(dev, tests, the Week-1 slice) it is an in-memory saver; with ``AGENT_SESSION_STORE_URI`` set it
+is a real ``AsyncPostgresSaver`` whose per-node checkpoints survive a crash so ``engine.resume``
+can continue from the frontier. Because the Postgres saver owns a live connection pool that must
+stay open for as long as the graph runs, this is exposed as an **async context manager**, not a
+factory that returns a bare object.
+
+``setup=True`` runs the saver's schema DDL. That is a migration, so per the project's "never migrate
+silently" policy the caller opts in — it is invoked from ``agentship doctor`` / first-boot, never on
+every process start. See phase 02 §C4 and DESIGN §6/§13.6.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from langgraph.checkpoint.memory import InMemorySaver
+
+if TYPE_CHECKING:  # only for typing; the Postgres saver is imported lazily so a bare install works
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+
+#: One process-wide in-memory saver for the no-database path. It must be **shared** across
+#: ``open_checkpointer`` calls so an in-process ``run`` then ``resume`` see the same checkpoints
+#: (a fresh saver per call would forget them). Entries are keyed by ``thread_id`` internally, so
+#: distinct runs never collide. This is single-process only — real cross-process durability needs
+#: the Postgres saver.
+_MEMORY_SAVER = InMemorySaver()
+
+
+@asynccontextmanager
+async def open_checkpointer(
+    conninfo: str | None, *, setup: bool = False
+) -> AsyncIterator[BaseCheckpointSaver]:
+    """Yield the checkpointer for this environment, holding its resources for the ``with`` body.
+
+    ``conninfo`` is the Postgres connection string (typically ``AGENT_SESSION_STORE_URI``). Blank
+    or ``None`` → an :class:`InMemorySaver` (no cross-process durability, fine for dev/tests). A
+    real connection string → an ``AsyncPostgresSaver`` bound to a live pool that is opened on enter
+    and closed on exit. ``setup=True`` runs the saver's table DDL first (gated migration; Postgres
+    only — the in-memory saver needs no schema).
+    """
+    if not conninfo:
+        # Shared, not fresh — so an in-process run→resume sees the same checkpoints.
+        yield _MEMORY_SAVER
+        return
+
+    # Imported lazily: psycopg + langgraph-checkpoint-postgres are the optional [postgres] extra,
+    # so a bare install that never touches durability does not need them present.
+    from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+    async with AsyncPostgresSaver.from_conn_string(conninfo) as saver:
+        if setup:
+            await saver.setup()
+        yield saver