deepagent-hermes 0.1.0__py3-none-any.whl

deepagent_hermes/__init__.py

@@ -0,0 +1,32 @@
+"""deepagent-hermes — closed-loop reflection / skill-creation agent on LangGraph + deepagents.
+
+Faithful reproduction of Nous Research's Hermes Agent design ideas. See SPEC.md and NOTICE.
+"""
+
+__version__ = "0.1.0"
+
+# Re-exports populated by submodule integration (see agent.py).
+# Subagents wire these in; importing here would create circular deps during build.
+__all__ = [
+    "HermesConfig",
+    "HermesState",
+    "__version__",
+    "create_hermes_agent",
+]
+
+
+def __getattr__(name: str):
+    """Lazy re-export to defer heavy imports until first access."""
+    if name == "create_hermes_agent":
+        from deepagent_hermes.agent import create_hermes_agent
+
+        return create_hermes_agent
+    if name == "HermesConfig":
+        from deepagent_hermes.config import HermesConfig
+
+        return HermesConfig
+    if name == "HermesState":
+        from deepagent_hermes.state import HermesState
+
+        return HermesState
+    raise AttributeError(f"module 'deepagent_hermes' has no attribute {name!r}")

deepagent_hermes/agent.py

@@ -0,0 +1,294 @@
+"""The compiled Hermes agent.
+
+This module is the entry point hosts target via
+``DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph``. It owns the
+**middleware stack ordering** (see SPEC §4) and is the only place that
+knows how the subsystems fit together.
+
+Two public surfaces:
+
+* :func:`create_hermes_agent` — build a fresh compiled graph from a
+  :class:`~deepagent_hermes.config.HermesConfig`. Each call returns an
+  independent ``CompiledStateGraph`` with its own checkpointer + store
+  references; callers can swap models or workspaces per agent.
+* :data:`graph` — a module-level instance built from
+  ``HermesConfig.resolve()`` for hosts that want a ready-to-use graph.
+  Constructed lazily on first attribute access so ``import``-time has
+  no side effects.
+
+Per SPEC §1 (D8), we deliberately do NOT use ``deepagents.create_deep_agent``
+because it appends user middleware *after* the defaults and always prepends
+``BASE_AGENT_PROMPT``. We need to own the middleware list end-to-end and
+own the system prompt, so we call ``langchain.agents.create_agent`` directly
+and assemble the middleware ourselves.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from pathlib import Path
+from typing import Any
+
+from deepagent_hermes.budget import IterationBudgetMiddleware
+from deepagent_hermes.caching import AnthropicCachingS3Middleware
+from deepagent_hermes.compression import HermesCompressionMiddleware
+from deepagent_hermes.config import HermesConfig
+from deepagent_hermes.curator import CuratorMiddleware
+from deepagent_hermes.memory.provider import get_provider
+from deepagent_hermes.memory.tool import MemoryToolMiddleware
+from deepagent_hermes.plugins.event_bus import PluginEventBus
+from deepagent_hermes.prompts import PromptAssemblyMiddleware
+from deepagent_hermes.reflection import ReflectionMiddleware, build_review_subagent
+from deepagent_hermes.search.session_search import make_session_search_tool
+from deepagent_hermes.skills.library import SkillLibrary
+from deepagent_hermes.skills.loader import SkillLoaderMiddleware
+from deepagent_hermes.skills.tools import make_skill_tools
+from deepagent_hermes.store.recorder import HermesStateRecorderMiddleware
+from deepagent_hermes.store.sqlite_fts import SqliteFtsStore
+from deepagent_hermes.tools.toolsets import resolve_enabled
+
+log = logging.getLogger(__name__)
+
+
+def _default_skill_dirs(cfg: HermesConfig) -> list[Path]:
+    """Resolution order matches SPEC §10.2 — later wins on name collision."""
+    dirs: list[Path] = []
+    # Bundled (shipped with the package; usually empty in v0.1.0a0).
+    pkg_root = Path(__file__).resolve().parent.parent.parent
+    bundled = pkg_root / "skills"
+    if bundled.is_dir():
+        dirs.append(bundled)
+    # User-global.
+    dirs.append(cfg.hermes_home / "skills")
+    # Project shadow.
+    project = Path.cwd() / ".deepagent-hermes" / "skills"
+    if project.is_dir():
+        dirs.append(project)
+    # Extra dirs from config.
+    for extra in cfg.skills_external_dirs:
+        dirs.append(Path(extra).expanduser())
+    return dirs
+
+
+def _init_chat_model(model_id: str | None) -> Any:
+    """Wrap ``langchain.chat_models.init_chat_model`` so a ``None`` returns a sentinel default."""
+    from langchain.chat_models import init_chat_model
+
+    if not model_id:
+        model_id = "anthropic:claude-sonnet-4-5-20250929"
+    return init_chat_model(model_id)
+
+
+def create_hermes_agent(
+    config: HermesConfig | None = None,
+    *,
+    workspace: str | Path | None = None,
+    session_id: str | None = None,
+    extra_middleware: list[Any] | None = None,
+) -> Any:
+    """Build a fresh Hermes agent graph.
+
+    Args:
+        config: Resolved configuration; defaults to ``HermesConfig.resolve()``.
+        workspace: Filesystem root for the file toolset; defaults to ``cwd``.
+        session_id: Optional session id; auto-generated UUID if not provided.
+        extra_middleware: Additional middleware appended after the standard
+            stack — useful for hosts that want to inject tracing or auth.
+
+    Returns:
+        A compiled LangGraph ``CompiledStateGraph`` ready for ``.invoke()`` /
+        ``.stream()``. The graph carries a SQLite checkpointer and FTS5 store
+        rooted at ``<HERMES_HOME>/state.db``.
+    """
+    from langchain.agents import create_agent
+    from langgraph.checkpoint.sqlite import SqliteSaver
+
+    cfg = config or HermesConfig.resolve()
+    sid = session_id or f"sess-{uuid.uuid4().hex[:12]}"
+    ws = Path(workspace).resolve() if workspace else Path.cwd()
+
+    # ── shared resources ─────────────────────────────────────────────────
+    db_path = cfg.hermes_home / "state.db"
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    store = SqliteFtsStore(db_path=str(db_path))
+    library = SkillLibrary(_default_skill_dirs(cfg))
+
+    main_model = _init_chat_model(cfg.model_default)
+    aux_model = _init_chat_model(cfg.model_aux) if cfg.model_aux else main_model
+
+    # ── memory provider plugin (single-select) ───────────────────────────
+    provider_name = cfg.memory_provider or ""
+    provider_cls = get_provider(provider_name)
+    provider = provider_cls() if provider_cls else None
+
+    # ── enabled toolsets (after disabled_toolsets filter) ────────────────
+    enabled_toolsets = resolve_enabled(
+        disabled_toolsets=set(cfg.agent_disabled_toolsets),
+        platform=os.getenv("HERMES_PLATFORM", "cli"),
+    )
+
+    # ── tools (kept as a flat list; deepagents'/langchain's create_agent merges from middleware too) ──
+    skill_tools = make_skill_tools(library)
+    session_search_tool = make_session_search_tool(store, current_session_id_getter=lambda: sid)
+    # FilesystemBackend tools come in via the FilesystemMiddleware (below).
+    tools: list[Any] = [*skill_tools, session_search_tool]
+
+    # ── deepagents middleware (filesystem + subagents + todos) ───────────
+    from deepagents.backends.filesystem import FilesystemBackend
+    from deepagents.middleware.filesystem import FilesystemMiddleware
+    from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
+    from deepagents.middleware.subagents import SubAgentMiddleware
+    from langchain.agents.middleware import HumanInTheLoopMiddleware, TodoListMiddleware
+
+    # virtual_mode=True so the agent's '/workspace/foo.py' (its natural
+    # absolute-path convention from the system prompt) resolves under our
+    # configured root rather than literal C:\workspace\foo.py. Without this,
+    # the agent silently writes to / reads from a path the user can't
+    # introspect — surfaced in the 2026-06-02 dogfood when reported file
+    # writes didn't appear on disk.
+    fs_backend = FilesystemBackend(root_dir=str(ws), virtual_mode=True)
+
+    # ── review subagent (reflection target) ──────────────────────────────
+    # Wire the memory + skill_manage tools so the review fork can actually
+    # write — without these, the subagent runs but has no way to act on its
+    # conclusions, and the closed loop never closes.
+    _memory_mw_for_tools = MemoryToolMiddleware(
+        memory_char_limit=cfg.memory_char_limit,
+        user_char_limit=cfg.memory_user_char_limit,
+    )
+    review_tools = [*skill_tools, *_memory_mw_for_tools.tools]
+    review_subagent = build_review_subagent(
+        library=library, store=store, aux_model=aux_model, tools=review_tools
+    )
+
+    # ── compose the middleware stack (SPEC §4 order) ─────────────────────
+    # Note: deepagents inserts TodoList + Filesystem + SubAgent earlier in
+    # its own create_deep_agent; we do it ourselves to control ordering.
+    middleware: list[Any] = [
+        # PluginEventBus is OUTERMOST so plugin hooks see the unmodified
+        # request and the final response (per its module docstring).
+        PluginEventBus(),
+        # Budget next — it can short-circuit before anything else runs.
+        IterationBudgetMiddleware(max_iterations=cfg.agent_max_iterations),
+        # Prompt assembly owns the system prompt (outermost wrap so the
+        # skill loader's mutation lands on top of the assembled prompt).
+        PromptAssemblyMiddleware(
+            enabled_toolsets=list(enabled_toolsets),
+            platform=os.getenv("HERMES_PLATFORM", "cli"),
+            workspace_root=ws,
+        ),
+        SkillLoaderMiddleware(library),
+        # Memory snapshot loader / writer.
+        MemoryToolMiddleware(
+            memory_char_limit=cfg.memory_char_limit,
+            user_char_limit=cfg.memory_user_char_limit,
+        ),
+        # FTS5 recorder — writes every turn to the SQLite store.
+        HermesStateRecorderMiddleware(store=store),
+        # Reflection — counts tool calls, spawns review subagent on threshold.
+        ReflectionMiddleware(
+            skill_nudge_interval=cfg.skills_creation_nudge_interval,
+            memory_nudge_interval=cfg.memory_nudge_interval,
+            library=library,
+            store=store,
+            model=main_model,
+            aux_model=aux_model,
+        ),
+        # Curator — runs on session start if idle gates open.
+        CuratorMiddleware(
+            library,
+            store,
+            interval_hours=cfg.curator_interval_hours,
+            min_idle_hours=cfg.curator_min_idle_hours,
+            stale_days=cfg.curator_stale_after_days,
+            archive_days=cfg.curator_archive_after_days,
+            enabled=cfg.curator_enabled,
+        ),
+        # Deepagents built-ins.
+        TodoListMiddleware(),
+        FilesystemMiddleware(backend=fs_backend),
+        SubAgentMiddleware(
+            backend=fs_backend,
+            subagents=[review_subagent],
+        ),
+        # Compression near the end so it sees the fully-assembled prompt + state.
+        HermesCompressionMiddleware(
+            model=main_model,
+            aux_model=aux_model,
+            threshold_percent=cfg.compression_threshold,
+            protect_first_n=cfg.compression_protect_first_n,
+            protect_last_n=cfg.compression_protect_last_n,
+            summary_target_ratio=cfg.compression_target_ratio,
+            abort_on_summary_failure=cfg.compression_abort_on_summary_failure,
+        ),
+        # Caching wraps the actual model call — must be near the inner edge.
+        AnthropicCachingS3Middleware(ttl="5m"),
+        # PatchToolCalls fixes orphaned tool_call ids after interrupted runs.
+        PatchToolCallsMiddleware(),
+    ]
+
+    # Optional human-in-the-loop (only added if any tool is gated).
+    # Hosts can override via DEEPAGENT_HERMES_INTERRUPT_ON env (CSV of tool names).
+    interrupt_csv = os.getenv("DEEPAGENT_HERMES_INTERRUPT_ON", "")
+    if interrupt_csv:
+        interrupt_on = {name.strip(): True for name in interrupt_csv.split(",") if name.strip()}
+        middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))
+
+    if extra_middleware:
+        middleware.extend(extra_middleware)
+
+    # ── checkpointer ─────────────────────────────────────────────────────
+    # Shares the state.db file with the FTS store (disjoint table namespaces).
+    # We hold a long-lived connection ourselves rather than using
+    # ``SqliteSaver.from_conn_string`` (which is a context manager and would
+    # close the connection on GC of the temporary). ``check_same_thread=False``
+    # lets the graph stream from a different thread than the constructor.
+    import sqlite3
+
+    saver_conn = sqlite3.connect(str(db_path), check_same_thread=False)
+    checkpointer = SqliteSaver(saver_conn)
+
+    # ── compile ──────────────────────────────────────────────────────────
+    # System prompt is set by PromptAssemblyMiddleware via wrap_model_call,
+    # so we pass an empty string here — the middleware will replace it.
+    compiled = create_agent(
+        main_model,
+        system_prompt="",
+        tools=tools,
+        middleware=middleware,
+        checkpointer=checkpointer,
+        store=store,
+    ).with_config({"recursion_limit": 1000, "configurable": {"thread_id": sid}})
+
+    # Attach references the hosts may want to introspect.
+    compiled.deepagent_hermes_config = cfg  # type: ignore[attr-defined]
+    compiled.deepagent_hermes_session_id = sid  # type: ignore[attr-defined]
+    compiled.deepagent_hermes_store = store  # type: ignore[attr-defined]
+    compiled.deepagent_hermes_library = library  # type: ignore[attr-defined]
+    compiled.deepagent_hermes_provider = provider  # type: ignore[attr-defined]
+    # Keep the checkpointer connection alive for the lifetime of the graph.
+    compiled._deepagent_hermes_saver_conn = saver_conn  # type: ignore[attr-defined]
+
+    return compiled
+
+
+# ── module-level lazy graph for host adoption ────────────────────────────
+
+
+_graph: Any = None
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy ``graph`` instantiation so ``import deepagent_hermes.agent`` is cheap.
+
+    Hosts using ``DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph`` will
+    trigger the build on first attribute access.
+    """
+    global _graph
+    if name == "graph":
+        if _graph is None:
+            _graph = create_hermes_agent()
+        return _graph
+    raise AttributeError(f"module 'deepagent_hermes.agent' has no attribute {name!r}")

deepagent_hermes/budget.py

@@ -0,0 +1,222 @@
+"""``IterationBudgetMiddleware`` — per-thread iteration cap (SPEC §8).
+
+Hermes tracks budget as ``IterationBudget`` instance attrs on each ``AIAgent``
+(parent = 90, subagent = 50). In ``deepagents``, middleware is stateless, so
+the counter lives in ``HermesState["iteration_budget_remaining"]`` — that field
+is the per-thread persistence boundary.
+
+Hooks:
+
+* ``before_agent`` — seed the counter if missing (idempotent).
+* ``before_model`` — gated by ``@hook_config(can_jump_to=["end"])``: when the
+  remaining budget is ``<= 0`` we append a final ``AIMessage`` describing the
+  exhaustion and return ``{"jump_to": "end"}``.
+* ``wrap_tool_call`` — runs the tool first, then decrements the counter via
+  a ``Command(update=...)`` unless the tool name is in ``refund_tools``
+  (``execute_code`` by default — programmatic calls are refunded so they
+  don't eat the agent's budget).
+
+The decrement happens AFTER the tool returns so a failing tool also costs a
+budget unit (matches Hermes's ``IterationBudget.consume()`` semantics —
+consumption is unconditional, refund is an explicit opt-in for known
+programmatic tools).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Annotated, Any, NotRequired
+
+from langchain.agents.middleware import hook_config
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+)
+from langchain_core.messages import AIMessage, ToolMessage
+from langgraph.runtime import Runtime
+from langgraph.types import Command
+
+_DEFAULT_REFUND_TOOLS: tuple[str, ...] = ("execute_code",)
+
+
+def _take_last_int(_existing: int | None, new: int | None) -> int | None:
+    """Last-write-wins reducer. LangGraph calls reducers with ``(None, None)``
+    to derive the initial value, so we must return ``None`` (not 0) for that
+    case or the seed turns into "budget exhausted" before the first turn —
+    surfaced live during the 2026-06-02 dogfood run.
+
+    Parallel decrements (parent + subagent in the same superstep) compose to
+    the last write; a brief over-spend by 1-2 iterations is acceptable in
+    exchange for not crashing the agent.
+    """
+    return new
+
+
+class _BudgetStateExt(AgentState):
+    """Declare ``iteration_budget_remaining`` on the merged graph state schema
+    so the middleware's seed + decrement actually persist across hooks.
+
+    Reducer-annotated to tolerate parallel writes from parent + subagent
+    paths in the same LangGraph superstep.
+    """
+
+    iteration_budget_remaining: NotRequired[Annotated[int, _take_last_int]]
+
+
+def _state_get(state: Any, key: str, default: Any = None) -> Any:
+    if state is None:
+        return default
+    if isinstance(state, dict):
+        return state.get(key, default)
+    return getattr(state, key, default)
+
+
+class IterationBudgetMiddleware(AgentMiddleware):
+    """Decrement-on-tool-call iteration budget with end-jump on exhaustion.
+
+    Args:
+        max_iterations: Initial budget seeded on the first agent invocation.
+            Default 90 (Hermes parent). For subagents pass ``50``.
+        refund_tools: Tool names that DON'T consume the budget. Default
+            ``("execute_code",)`` — programmatic loops shouldn't eat the
+            outer agent's per-turn cap.
+    """
+
+    state_schema = _BudgetStateExt
+
+    def __init__(
+        self,
+        max_iterations: int = 90,
+        *,
+        refund_tools: tuple[str, ...] = _DEFAULT_REFUND_TOOLS,
+    ) -> None:
+        super().__init__()
+        self.max_iterations = max_iterations
+        self.refund_tools = tuple(refund_tools)
+
+    # ── before_agent: seed counter ───────────────────────────────────
+
+    def before_agent(
+        self, state: Any, runtime: Runtime[Any] | None = None
+    ) -> dict[str, Any] | None:
+        """Seed ``iteration_budget_remaining`` to ``max_iterations`` when
+        the current value is missing, None, or 0.
+
+        LangGraph's schema-merge step coerces ``NotRequired[int]`` to 0 on the
+        first invocation in some configurations, which made the strict
+        ``current is None`` check skip seeding and immediately exhaust the
+        budget. Treating 0 as "unset" is safe because a real prior session
+        that genuinely exhausted will be re-seeded on the next agent run —
+        the right behaviour for a fresh invocation, not a regression.
+        """
+        current = _state_get(state, "iteration_budget_remaining", None)
+        if not current:  # None, 0, or missing
+            return {"iteration_budget_remaining": self.max_iterations}
+        return None
+
+    async def abefore_agent(
+        self, state: Any, runtime: Runtime[Any] | None = None
+    ) -> dict[str, Any] | None:
+        return self.before_agent(state, runtime)
+
+    # ── before_model: check + jump-to-end on exhaustion ──────────────
+
+    @hook_config(can_jump_to=["end"])
+    def before_model(
+        self, state: Any, runtime: Runtime[Any] | None = None
+    ) -> dict[str, Any] | None:
+        """If budget is exhausted, append a final ``AIMessage`` and jump to end."""
+        remaining = _state_get(state, "iteration_budget_remaining", self.max_iterations)
+        if remaining is None:
+            remaining = self.max_iterations
+        if remaining > 0:
+            return None
+
+        final = AIMessage(
+            content=f"[budget_exhausted: max_iterations={self.max_iterations} reached]"
+        )
+        return {"messages": [final], "jump_to": "end"}
+
+    @hook_config(can_jump_to=["end"])
+    async def abefore_model(
+        self, state: Any, runtime: Runtime[Any] | None = None
+    ) -> dict[str, Any] | None:
+        return self.before_model(state, runtime)
+
+    # ── wrap_tool_call: decrement after the tool runs ────────────────
+
+    def wrap_tool_call(
+        self,
+        request: Any,
+        handler: Callable[[Any], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
+        """Run the tool, then decrement the budget unless the tool is refunded."""
+        result = handler(request)
+        return self._maybe_decrement(request, result)
+
+    async def awrap_tool_call(
+        self,
+        request: Any,
+        handler: Callable[[Any], Awaitable[ToolMessage | Command[Any]]],
+    ) -> ToolMessage | Command[Any]:
+        result = await handler(request)
+        return self._maybe_decrement(request, result)
+
+    # ── private ──────────────────────────────────────────────────────
+
+    def _maybe_decrement(
+        self,
+        request: Any,
+        result: ToolMessage | Command[Any],
+    ) -> ToolMessage | Command[Any]:
+        """Apply the decrement to the result if this tool isn't refunded.
+
+        We attach the decrement as a state update on the returned ``Command``
+        (or wrap a plain ``ToolMessage`` in one). ``langgraph`` merges the
+        update into the running state, so the next ``before_model`` reads the
+        new value.
+        """
+        tool_name = self._tool_name(request)
+        if tool_name in self.refund_tools:
+            return result
+
+        # Read the live remaining from the request's state snapshot.
+        state = getattr(request, "state", None)
+        remaining = _state_get(state, "iteration_budget_remaining", self.max_iterations)
+        if remaining is None:
+            remaining = self.max_iterations
+        new_remaining = max(0, int(remaining) - 1)
+
+        # If the handler returned a Command, fold our update into it.
+        if isinstance(result, Command):
+            existing_update = result.update or {}
+            if isinstance(existing_update, dict):
+                merged = {**existing_update, "iteration_budget_remaining": new_remaining}
+                # ``Command`` is a dataclass-ish wrapper — easiest to rebuild it.
+                return Command(
+                    update=merged,
+                    goto=result.goto,
+                    graph=result.graph,
+                    resume=result.resume,
+                )
+            # Non-dict update — leave as-is (shouldn't happen in practice).
+            return result
+
+        # Plain ToolMessage: wrap in a Command carrying both the message and
+        # the decrement so the langgraph state merge picks up both.
+        return Command(
+            update={
+                "messages": [result],
+                "iteration_budget_remaining": new_remaining,
+            }
+        )
+
+    @staticmethod
+    def _tool_name(request: Any) -> str:
+        tc = getattr(request, "tool_call", None) or {}
+        if isinstance(tc, dict):
+            return str(tc.get("name") or "")
+        return str(getattr(tc, "name", "") or "")
+
+
+__all__ = ["IterationBudgetMiddleware"]