agentdeck-sdk 3.1.0__py3-none-any.whl

agentdeck/README.md

@@ -0,0 +1,50 @@
+# `agentdeck/`
+
+Declarative layer over the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
+and [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+agentdeck owns **configuration** — settings, tools and MCP servers, skill disclosure, graph
+compilation, plug-in discovery. Execution stays in the SDK / LangGraph.
+
+```text
+agentdeck/
+    core/          # event schema and ports — stdlib + pydantic only
+    runtime/       # settings, plugin discovery, the Runtime's own primitives
+    authoring/     # Agent/Workflow: the declarative construction API, compiles to InvocableSpec
+    skills/        # Skills: SKILL.md discovery, validation, disclosure text
+    adapters/      # engines (openai-agents, langgraph), event stores, control ports, tool sources
+    surfaces/      # thin readers over the canonical event stream (HTTP compat, CLI)
+    deck.py        # Deck: the composition root — build a catalog, open it, run turns on it
+    mcp.py         # MCP: .mcp.json parsing and validation
+    serve.py       # the FastAPI app agentdeck-serve runs
+```
+
+`Deck` is the one class application code needs directly — see the top-level
+[README](../README.md) for how to use it, and [`docs-site/`](../docs-site/) for the full guide.
+The rest of this package is composition plumbing `Deck` wires together; nothing else here is
+meant to be imported on its own except `agentdeck.authoring` (`Agent`, `Workflow`, and the
+node/declaration types they compile from).
+
+## Plug-in discovery
+
+`agentdeck.runtime.registry.PluginRegistry` walks `<package>/<type_dir>/<bundle>/<module>.py` and
+indexes every module-level *instance* of a base class (`Agent`, `Workflow`) — not subclasses; an
+`Agent`/`Workflow` is a value, not something to subclass. `Deck.from_project()` builds one
+registry each for `agents/` and `workflows/`. A pre-0.3 project dir without the `agents/`/
+`workflows/` type subdirectory raises a `ConfigError` pointing at the current layout instead of
+silently discovering nothing.
+
+## Settings
+
+Layered Pydantic-Settings models. See [`runtime/settings.py`](runtime/settings.py) for
+definitions, or the generated `docs-site/content/reference/settings.mdx` for every
+`AGENTDECK_*`/`OPENAI_*`/`TAVILY_*` env var.
+
+```python
+from agentdeck.runtime.settings import get_settings
+
+s = get_settings()  # cached
+s.openai.model
+s.runner.max_turns
+s.checkpoint.url  # e.g. "sqlite://.agentdeck/checkpoints.sqlite3" — the scheme names the backend
+```

agentdeck/__init__.py

@@ -0,0 +1,51 @@
+"""agentdeck — declarative framework over the OpenAI Agents SDK and LangGraph.
+
+Owns *configuration* (settings, capabilities, runner glue, graph compilation,
+plug-in discovery) so the underlying engines own *execution*.
+:class:`agentdeck.Deck` is the composition root — either constructed directly
+from :class:`agentdeck.Agent`/:class:`agentdeck.Workflow` declarations, or
+discovered from a project directory (``Deck.from_project()``).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from agentdeck.authoring import Agent, Workflow
+from agentdeck.core.context import Context
+from agentdeck.deck import Deck, TurnResult
+from agentdeck.errors import (
+    AgentdeckError,
+    ConfigError,
+    ContextTypeError,
+    NotFoundError,
+    SessionBusyError,
+    SkillError,
+    StoreError,
+)
+
+try:
+    # The *distribution* is `agentdeck-sdk`; the import package is `agentdeck`. They differ
+    # because PyPI refuses `agentdeck` as too similar to the squatted `agent-deck` placeholder.
+    # Passing the import name here returns nothing and falls through to "0+unknown" — a silently
+    # wrong version, which is the exact failure #176 added `__version__` to prevent.
+    __version__ = _version("agentdeck-sdk")
+except PackageNotFoundError:
+    # Running from a source checkout with no installed distribution (e.g. no `pip install -e .`
+    # yet) — a version string is still expected of every attribute lookup, not a raise.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "Agent",
+    "AgentdeckError",
+    "ConfigError",
+    "Context",
+    "ContextTypeError",
+    "Deck",
+    "NotFoundError",
+    "SessionBusyError",
+    "SkillError",
+    "StoreError",
+    "TurnResult",
+    "Workflow",
+    "__version__",
+]

agentdeck/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Ring 2 — one directory per external system, each behind a core port.
+
+Nothing outside an adapter directory may import that system, and no adapter imports
+another: deleting one must break nothing but itself.
+"""

agentdeck/adapters/control/__init__.py

@@ -0,0 +1 @@
+"""Run control — implementations of ``ControlPort``."""

agentdeck/adapters/control/memory/__init__.py

@@ -0,0 +1,5 @@
+"""``ControlPort`` in a dict."""
+
+from agentdeck.adapters.control.memory.port import MemoryControlPort
+
+__all__ = ["MemoryControlPort"]

agentdeck/adapters/control/memory/port.py

@@ -0,0 +1,25 @@
+"""In-process ``ControlPort``: a dict keyed by ``run_id``. Dev and single-process tests
+only — process exit loses every pending signal, same posture as ``stores.memory``.
+"""
+
+from __future__ import annotations
+
+from agentdeck.core.control import ControlSignal, Signal
+from agentdeck.core.ports.control import ControlPort
+
+
+class MemoryControlPort(ControlPort):
+    """One signal per run, held in memory. Overwriting a run's signal is intentional: only
+    the latest one matters, which is also how ``RESUME`` lifts a pending ``PAUSE``."""
+
+    def __init__(self) -> None:
+        self._signals: dict[str, ControlSignal] = {}
+
+    async def signal(self, run_id: str, sig: Signal, reason: str | None = None) -> None:
+        self._signals[run_id] = ControlSignal(verb=sig, reason=reason)
+
+    async def poll(self, run_id: str) -> ControlSignal | None:
+        return self._signals.get(run_id)
+
+
+__all__ = ["MemoryControlPort"]

agentdeck/adapters/control/sqlite/__init__.py

@@ -0,0 +1,5 @@
+"""``ControlPort`` in SQLite."""
+
+from agentdeck.adapters.control.sqlite.port import SqliteControlPort
+
+__all__ = ["SqliteControlPort"]

agentdeck/adapters/control/sqlite/port.py

@@ -0,0 +1,111 @@
+"""``ControlPort`` in SQLite: one row per ``run_id``, durable enough that a second OS
+process — opening the same file, never sharing a connection or any Python state — can
+signal a run it never held a reference to. This is what makes cross-process cancel real
+instead of theoretical; Redis is the multi-worker upgrade, deferred to Story 3.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from contextlib import suppress
+from functools import partial
+from typing import TYPE_CHECKING
+
+from agentdeck.core.control import ControlSignal, Signal
+from agentdeck.core.ports.control import ControlPort
+from agentdeck.errors import StoreError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+# ponytail: the signals table grows one row per signaled run, never pruned — add a
+# prune-on-terminal or TTL sweep when signal volume matters.
+_SCHEMA = "CREATE TABLE IF NOT EXISTS signals (run_id TEXT PRIMARY KEY, signal TEXT NOT NULL, reason TEXT);"
+
+# A file written before signals carried a reason has no such column, and reading one is how
+# the caller finds out. Added in place instead: a pending cancel is state worth keeping.
+_ADD_REASON = "ALTER TABLE signals ADD COLUMN reason TEXT"
+
+# Same as the event log's: long enough to wait a peer's write out, short enough that a wedged
+# holder surfaces as an error rather than a hang.
+_BUSY_TIMEOUT_MS = 5_000
+
+
+def _connect(db_path: str) -> sqlite3.Connection:
+    """Open the signal table in WAL with an explicit busy timeout, so a run polling for a
+    signal is not blocked by another process writing one, and a cancel is not refused because
+    a poll happened to be reading.
+
+    The timeout is set first so the mode switch can wait a peer's transaction out, and the
+    switch is skipped when the file is already in WAL — re-asking is free there, but the
+    conversion itself needs an exclusive lock that a peer's open write denies outright. A
+    file that cannot be converted right now keeps the mode it has: slower under contention,
+    never wrong. ``:memory:`` reports ``memory`` and stays there.
+    """
+    try:
+        conn = sqlite3.connect(db_path, check_same_thread=False)
+        conn.execute(f"PRAGMA busy_timeout = {_BUSY_TIMEOUT_MS}")
+        if conn.execute("PRAGMA journal_mode").fetchone()[0] != "wal":
+            # ponytail: silent, like the event store's — log it if an operator ever has to
+            # find out why one process came up without WAL.
+            with suppress(sqlite3.OperationalError):
+                conn.execute("PRAGMA journal_mode = WAL")
+        conn.executescript(_SCHEMA)
+        if not any(row[1] == "reason" for row in conn.execute("PRAGMA table_info(signals)")):
+            conn.execute(_ADD_REASON)
+        conn.commit()
+    except sqlite3.Error as exc:
+        raise StoreError(f"cannot open the control signals at {db_path!r}: {exc}") from exc
+    return conn
+
+
+class SqliteControlPort(ControlPort):
+    """One connection, serialized by a lock — same posture as ``stores.sqlite`` and for
+    the same reason: ``sqlite3`` is stdlib but not coroutine-safe. Failures reach the caller
+    as ``StoreError`` rather than as a ``sqlite3`` exception, and the same WAL caveats apply:
+    ``-wal``/``-shm`` files sit beside this database, and it belongs on local disk because
+    WAL is unreliable on network filesystems.
+    """
+
+    def __init__(self, db_path: str | Path = ":memory:") -> None:
+        self._conn = _connect(str(db_path))
+        self._lock = asyncio.Lock()
+
+    async def _run[T](self, work: Callable[[], T], op: str) -> T:
+        """Every statement goes through here — one caller at a time, off the event loop, and
+        no library exception escaping the port."""
+        async with self._lock:
+            try:
+                return await asyncio.to_thread(work)
+            except sqlite3.Error as exc:
+                raise StoreError(f"control signal {op} failed: {exc}") from exc
+
+    async def signal(self, run_id: str, sig: Signal, reason: str | None = None) -> None:
+        await self._run(partial(self._write, run_id, sig.value, reason), "signal")
+
+    async def poll(self, run_id: str) -> ControlSignal | None:
+        row = await self._run(partial(self._read, run_id), "poll")
+        return ControlSignal(verb=Signal(row[0]), reason=row[1]) if row is not None else None
+
+    def _write(self, run_id: str, sig: str, reason: str | None) -> None:
+        self._conn.execute(
+            "INSERT INTO signals (run_id, signal, reason) VALUES (?, ?, ?) "
+            "ON CONFLICT(run_id) DO UPDATE SET signal = excluded.signal, reason = excluded.reason",
+            (run_id, sig, reason),
+        )
+        self._conn.commit()
+
+    def _read(self, run_id: str) -> tuple[str, str | None] | None:
+        row = self._conn.execute("SELECT signal, reason FROM signals WHERE run_id = ?", (run_id,)).fetchone()
+        return (row[0], row[1]) if row else None
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except sqlite3.Error as exc:
+            raise StoreError(f"closing the control signals failed: {exc}") from exc
+
+
+__all__ = ["SqliteControlPort"]

agentdeck/adapters/engines/__init__.py

@@ -0,0 +1 @@
+"""Execution engines — implementations of ``EnginePort``, one directory per SDK."""

agentdeck/adapters/engines/langgraph/__init__.py

@@ -0,0 +1,8 @@
+"""The langgraph engine adapter: ``EnginePort`` over a compiled ``StateGraph``."""
+
+from __future__ import annotations
+
+from agentdeck.adapters.engines.langgraph.checkpointer import resolve_checkpointer
+from agentdeck.adapters.engines.langgraph.engine import DURABLE_KEY, REPORTER_KEY, LangGraphEngine
+
+__all__ = ["DURABLE_KEY", "REPORTER_KEY", "LangGraphEngine", "resolve_checkpointer"]

agentdeck/adapters/engines/langgraph/checkpointer.py

@@ -0,0 +1,205 @@
+"""Resolve a LangGraph checkpointer for the langgraph engine's runs.
+
+Relocated from ``agentdeck.runtime.checkpointer``, which was written for v1's
+``BaseWorkflow`` durability but holds exactly the state a checkpointer engine must keep
+private to its own adapter (ADR-D5: execution state belongs to the engine that produced
+it, never shared or derived by an outer ring) — the same relationship ``sessions.py`` has
+to the openai-agents adapter. ``agentdeck.authoring.compile.compile_workflow`` (a durable
+``Workflow``'s direct-call path) imports this module directly and translates
+``CheckpointSettings`` into the plain ``(backend, url)`` this function takes. ``memory``
+ships with core ``langgraph`` and needs nothing extra;
+``sqlite`` / ``postgres`` live in the optional ``[durability]`` extra
+(``langgraph-checkpoint-sqlite`` / ``langgraph-checkpoint-postgres``) and are imported
+lazily, only when actually requested, with a clear install hint if the extra is missing.
+
+Connection lifecycle: one saver per backend+url **per event loop**, so repeated calls
+against the same file reuse the same connection instead of opening one per compile, without
+handing a second loop a saver that is bound to the first (see ``_per_loop``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+import threading
+from functools import cache, partial
+from typing import TYPE_CHECKING, Any, TypeVar
+from weakref import WeakKeyDictionary
+
+from agentdeck.errors import StoreError
+
+if TYPE_CHECKING:
+    from asyncio import AbstractEventLoop
+    from collections.abc import Callable, Coroutine, MutableMapping
+
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+
+_DURABILITY_HINT = 'install the "durability" extra: pip install "agentdeck[durability]"'
+
+_T = TypeVar("_T")
+
+_savers: MutableMapping[AbstractEventLoop, dict[tuple[str, str], BaseCheckpointSaver]] = WeakKeyDictionary()
+
+
+def _per_loop(backend: str, url: str, build: Callable[[], BaseCheckpointSaver]) -> BaseCheckpointSaver:
+    """Cache ``build``'s saver against the running event loop rather than the process.
+
+    The async sqlite and postgres savers hold asyncio primitives — a ``Lock``, and under it a
+    connection — that bind to the first loop to *contend* for them. A process-wide cache
+    therefore hands a second loop a saver the first one owns, and the second loop's first
+    concurrent access dies with "bound to a different event loop": fine for a server, which
+    is one loop for its lifetime, and broken for anything that runs more than one.
+
+    Resolved with no loop running (a script that compiles its graph before ``asyncio.run``),
+    nothing is cached: there is no loop to key on, and the saver will bind to whichever one
+    first uses it — so caching it is precisely how the same breakage would come back. That
+    costs one connection per resolution on a path that resolves once.
+
+    What the weak keying does *not* buy: a saver ends up referencing the loop it bound to
+    (through that same lock), so each entry keeps its own key alive and nothing is collected
+    until ``_savers`` itself is. A process that runs many loops in a row therefore accumulates
+    one connection and one aiosqlite thread per loop — the wrong half of a trade whose right
+    half is a saver that works on the second loop. Zero effect on a server. ponytail: bounding
+    it means closing the savers at loop shutdown, i.e. owning their lifecycle — worth doing
+    when something long-lived actually runs loops in a row.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return build()
+    per_loop = _savers.setdefault(loop, {})
+    key = (backend, url)
+    if key not in per_loop:
+        per_loop[key] = build()
+    return per_loop[key]
+
+
+def _run_sync(coro: Coroutine[None, None, _T]) -> _T:
+    """Run ``coro`` to completion, whether or not an event loop is already running.
+
+    The engine may resolve a checkpointer lazily from *inside* an async ``start()`` call,
+    so plain ``asyncio.run`` would collide with the running loop. The one-shot bootstrap
+    connection (aiosqlite's async handshake) is cheap enough to hand to a throwaway
+    thread+loop in that case; all later query traffic runs on the caller's own loop.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    result: list[_T] = []
+    error: list[BaseException] = []
+
+    def _runner() -> None:
+        try:
+            result.append(asyncio.run(coro))
+        except BaseException as exc:  # noqa: BLE001 — re-raised on the calling thread below
+            error.append(exc)
+
+    thread = threading.Thread(target=_runner, daemon=True)
+    thread.start()
+    thread.join()
+    if error:
+        raise error[0]
+    return result[0]
+
+
+def resolve_checkpointer(backend: str, url: str = "") -> BaseCheckpointSaver:
+    """Build the checkpointer named by ``backend`` (``memory`` / ``sqlite`` / ``postgres``).
+
+    ``url`` is the sqlite file path or the Postgres DSN — primitives, not a settings
+    object, so this adapter takes core plus langgraph and nothing else. Raises
+    ``ValueError`` for an unknown backend, ``ImportError`` (with an install hint) when
+    ``sqlite``/``postgres`` is requested but the ``[durability]`` extra isn't installed,
+    and ``StoreError`` when the backend cannot open its connection at all, naming
+    ``AGENTDECK_CHECKPOINT`` — and, for sqlite, the resolved file path; a Postgres DSN is
+    not named, since it can carry a password — with the driver exception chained on as
+    ``__cause__``. A driver error raised mid-run, after the connection opened, is not a
+    configuration answer and is left as it is.
+    """
+    normalized = backend.strip().lower()
+    if normalized == "memory":
+        return _memory_saver()
+    if normalized == "sqlite":
+        return _sqlite_saver(url)
+    if normalized == "postgres":
+        return _postgres_saver(url)
+    raise ValueError(f"unknown checkpoint backend {backend!r}; expected sqlite, postgres, or memory")
+
+
+@cache
+def _memory_saver() -> BaseCheckpointSaver:
+    """Process-wide on purpose, unlike the durable two: ``MemorySaver`` is plain dicts with
+    no loop-bound primitive, and sharing it is what lets ``durable = True`` on the memory
+    backend resume across two ``asyncio.run`` calls at all — its threads live nowhere else."""
+    from langgraph.checkpoint.memory import MemorySaver
+
+    return MemorySaver()
+
+
+def _sqlite_saver(url: str) -> BaseCheckpointSaver:
+    """``AsyncSqliteSaver`` for ``url``, one connection per event loop (see ``_per_loop``)."""
+    return _per_loop("sqlite", url, partial(_build_sqlite_saver, url))
+
+
+def _build_sqlite_saver(url: str) -> BaseCheckpointSaver:
+    try:
+        import aiosqlite  # ty: ignore[unresolved-import] — [durability] extra
+        from langgraph.checkpoint.sqlite import aio as sqlite_aio  # ty: ignore[unresolved-import] — [durability] extra
+    except ImportError as exc:
+        raise ImportError(
+            f"checkpoint backend 'sqlite' needs langgraph-checkpoint-sqlite — {_DURABILITY_HINT}"
+        ) from exc
+
+    # AsyncSqliteSaver.__init__ needs a running loop — build it inside _run_sync, matching postgres.
+    path = url or ".agentdeck/checkpoints.sqlite3"
+
+    async def _connect_and_build() -> BaseCheckpointSaver:
+        try:
+            conn = aiosqlite.connect(path)
+            # aiosqlite's per-connection worker thread is non-daemon, and nothing ever closes a
+            # cached connection, so a normal exit would hang forever joining it.
+            conn._thread.daemon = True  # noqa: SLF001 — aiosqlite exposes no public way to set this
+            await conn
+            saver = sqlite_aio.AsyncSqliteSaver(conn)
+            await saver.setup()
+        except sqlite3.Error as exc:
+            raise StoreError(f"cannot open the workflow checkpoint at {path!r} (AGENTDECK_CHECKPOINT): {exc}") from exc
+        return saver
+
+    saver: Any = _run_sync(_connect_and_build())
+    return saver
+
+
+def _postgres_saver(url: str) -> BaseCheckpointSaver:
+    """``AsyncPostgresSaver`` for ``url``, one connection per event loop (see ``_per_loop``)."""
+    if not url:
+        raise ValueError("checkpoint backend 'postgres' needs a DSN")
+    return _per_loop("postgres", url, partial(_build_postgres_saver, url))
+
+
+def _build_postgres_saver(url: str) -> BaseCheckpointSaver:
+    try:
+        from langgraph.checkpoint.postgres.aio import (  # ty: ignore[unresolved-import] — [durability] extra
+            AsyncPostgresSaver,
+        )
+    except ImportError as exc:
+        raise ImportError(
+            f"checkpoint backend 'postgres' needs langgraph-checkpoint-postgres — {_DURABILITY_HINT}",
+        ) from exc
+    import psycopg  # ty: ignore[unresolved-import] — [durability] extra
+
+    # Async saver, same reason as sqlite: the engine always calls ``ainvoke``/``astream``.
+    # ``from_conn_string`` is an async contextmanager owning the connection; we enter it
+    # manually and let the caller cache the saver.
+    try:
+        saver: Any = _run_sync(AsyncPostgresSaver.from_conn_string(url).__aenter__())
+        _run_sync(saver.setup())
+    except psycopg.Error as exc:
+        # No DSN in the message, unlike the sqlite branch: a DSN can carry a password, and
+        # unlike a filesystem path, that is a secret. Matches how the networked event stores
+        # already word this (postgres/store.py, redis/store.py) — neither names its URL either.
+        raise StoreError(f"cannot open the workflow checkpoint (AGENTDECK_CHECKPOINT): {exc}") from exc
+    return saver
+
+
+__all__ = ["resolve_checkpointer"]