agentship-langgraph 0.0.1__tar.gz

agentship_langgraph-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets — never commit
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Docs build
+site/

agentship_langgraph-0.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: agentship-langgraph
+Version: 0.0.1
+Summary: AgentShip LangGraph engine — the default real-model runtime, with a LiteLLM model source that routes one `model:` string to any provider.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: agentship-core==0.0.1
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-litellm>=0.1
+Requires-Dist: langgraph>=0.2
+Provides-Extra: autonomous
+Requires-Dist: deepagents==0.6.12; extra == 'autonomous'
+Provides-Extra: mcp
+Requires-Dist: cryptography>=42; extra == 'mcp'
+Requires-Dist: langchain-mcp-adapters>=0.3; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.28; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# agentship-langgraph
+
+The default real-model engine for AgentShip: a single-agent LangGraph graph over a LiteLLM-backed model. Registers the `langgraph` engine via the `agentship.engines` entry point. Import as `agentship_langgraph`.

agentship_langgraph-0.0.1/README.md

@@ -0,0 +1,3 @@
+# agentship-langgraph
+
+The default real-model engine for AgentShip: a single-agent LangGraph graph over a LiteLLM-backed model. Registers the `langgraph` engine via the `agentship.engines` entry point. Import as `agentship_langgraph`.

agentship_langgraph-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentship-langgraph"
+version = "0.0.1"
+description = "AgentShip LangGraph engine — the default real-model runtime, with a LiteLLM model source that routes one `model:` string to any provider."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "agentship-core==0.0.1",
+    "langgraph>=0.2",
+    "langchain-core>=0.3",
+    "langchain-litellm>=0.1",  # the default model source: one `model:` string routes to any provider
+]
+
+# The `autonomous` template is opt-in: `pip install agentship-langgraph[autonomous]`.
+# It wraps the `deepagents` library, pinned to 0.6.12 (pre-1.0) because
+# create_deep_agent's signature can drift; the template imports it lazily, so the base
+# engine installs and runs without it, and `agentship doctor` flags a version mismatch
+# (see templates/autonomous_tpl.py).
+[project.optional-dependencies]
+autonomous = ["deepagents==0.6.12"]
+# MCP tools (Phase 03 §C3): consume the OSS client stack — do NOT hand-roll it.
+# `langchain-mcp-adapters` (MultiServerMCPClient) connects to local stdio + remote streamable-HTTP
+# MCP servers and returns LangChain tools the engine binds. `mcp` is pinned <2 because v2 reshaped
+# the client API the adapters target. Opt-in: a bare install runs without MCP; imported lazily.
+mcp = ["langchain-mcp-adapters>=0.3", "mcp>=1.28,<2", "cryptography>=42"]
+# Durable checkpointing (Phase 02 §C4): the AsyncPostgresSaver + its psycopg driver.
+# Opt-in so a bare install runs on the in-memory saver; `pip install agentship-langgraph[postgres]`
+# turns on crash-durable, resumable runs. Pairs with agentship-core[postgres] (the ThreadLock).
+postgres = ["langgraph-checkpoint-postgres>=2.0", "psycopg[binary]>=3.1"]
+
+# Registers the LangGraph engine with the core harness (discovered via importlib.metadata),
+# so `engine: langgraph` in a spec resolves here.
+[project.entry-points."agentship.engines"]
+langgraph = "agentship_langgraph.engine:LangGraphEngine"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentship_langgraph"]

agentship_langgraph-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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