soothe-deepagents 0.7.16__py3-none-any.whl

soothe_deepagents/__init__.py

@@ -0,0 +1,50 @@
+"""Deep Agents package."""
+
+from soothe_deepagents._version import __version__
+from soothe_deepagents.graph import (
+    DeepAgentState,
+    SystemPromptConfig,
+    create_deep_agent,
+)
+from soothe_deepagents.middleware.async_subagents import AsyncSubAgent, AsyncSubAgentMiddleware
+from soothe_deepagents.middleware.filesystem import FilesystemMiddleware, FilesystemPermission, FsToolName
+from soothe_deepagents.middleware.memory import MemoryMiddleware
+from soothe_deepagents.middleware.rubric import RubricMiddleware
+from soothe_deepagents.middleware.subagents import (
+    CompiledSubAgent,
+    SubAgent,
+    SubAgentMiddleware,
+)
+from soothe_deepagents.profiles.harness.harness_profiles import (
+    GeneralPurposeSubagentProfile,
+    HarnessProfile,
+    HarnessProfileConfig,
+    register_harness_profile,
+)
+from soothe_deepagents.profiles.provider.provider_profiles import (
+    ProviderProfile,
+    register_provider_profile,
+)
+
+__all__ = [
+    "AsyncSubAgent",
+    "AsyncSubAgentMiddleware",
+    "CompiledSubAgent",
+    "DeepAgentState",
+    "FilesystemMiddleware",
+    "FilesystemPermission",
+    "FsToolName",
+    "GeneralPurposeSubagentProfile",
+    "HarnessProfile",
+    "HarnessProfileConfig",
+    "MemoryMiddleware",
+    "ProviderProfile",
+    "RubricMiddleware",
+    "SubAgent",
+    "SubAgentMiddleware",
+    "SystemPromptConfig",
+    "__version__",
+    "create_deep_agent",
+    "register_harness_profile",
+    "register_provider_profile",
+]

soothe_deepagents/_api/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helpers for `soothe_deepagents`.
+
+Modules under this package are private. Their API is allowed to change between
+minor releases without deprecation.
+"""

soothe_deepagents/_api/deprecation.py

@@ -0,0 +1,131 @@
+"""Adapter for `langchain_core`'s private deprecation helpers.
+
+Centralizes the import surface so an upstream rename or move is a one-file
+change.
+
+Re-exports:
+- `deprecated`: decorator for callables, classes, and properties.
+- `warn_deprecated`: helper for parameter/value-level deprecations where the
+    callable itself isn't being deprecated. Wraps the upstream helper to
+    accept a `stacklevel` argument (the upstream version hardcodes
+    `stacklevel=4`, which mis-attributes warnings emitted directly from a
+    deprecated method body).
+- `suppress_langchain_deprecation_warning`: context manager that silences
+    emissions from this module's helpers (use sparingly — it is type-wide).
+- `LangChainDeprecationWarning`: warning class emitted by the helpers above
+    (subclass of `DeprecationWarning`).
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from langchain_core._api.deprecation import (
+    LangChainDeprecationWarning,
+    deprecated,
+    suppress_langchain_deprecation_warning,
+    warn_deprecated as _lc_warn_deprecated,
+)
+
+__all__ = [
+    "LangChainDeprecationWarning",
+    "deprecated",
+    "reset_deprecation_dedupe",
+    "suppress_langchain_deprecation_warning",
+    "warn_deprecated",
+]
+
+
+def warn_deprecated(
+    since: str,
+    *,
+    message: str = "",
+    name: str = "",
+    alternative: str = "",
+    alternative_import: str = "",
+    pending: bool = False,
+    obj_type: str = "",
+    addendum: str = "",
+    removal: str = "",
+    package: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning with caller-controlled stack attribution.
+
+    `langchain_core.warn_deprecated` formats a standard message but hardcodes
+    `stacklevel=4` in its internal `warnings.warn` call. That value targets a
+    decorator-wrapped frame layout; when called directly from a deprecated
+    method's body the warning is attributed one frame too high (above the
+    user's call site). This wrapper captures the formatted upstream warning
+    and re-emits it with an explicit `stacklevel`, so the warning points at
+    the user's call site.
+
+    Args:
+        since: Release at which this API became deprecated.
+        message: Override the default deprecation message. See upstream
+            `langchain_core.warn_deprecated` for supported format specifiers.
+        name: Name of the deprecated object.
+        alternative: Alternative API the user may use instead.
+        alternative_import: Alternative import path the user may use instead.
+        pending: If `True`, uses a `PendingDeprecationWarning` instead of a
+            `DeprecationWarning`. Cannot be combined with `removal`.
+        obj_type: Object type label (e.g., `"function"`, `"class"`).
+        addendum: Additional text appended to the final message.
+        removal: Expected removal version. Cannot be combined with `pending`.
+        package: Package name attribution for the deprecation message.
+        stacklevel: Frames above this call to attribute the warning to,
+            using the same convention as `warnings.warn` (`1` = this call,
+            `2` = the caller of the method body that invoked us, etc.).
+    """
+    with warnings.catch_warnings(record=True) as captured:
+        warnings.simplefilter("always")
+        _lc_warn_deprecated(
+            since,
+            message=message,
+            name=name,
+            alternative=alternative,
+            alternative_import=alternative_import,
+            pending=pending,
+            obj_type=obj_type,
+            addendum=addendum,
+            removal=removal,
+            package=package,
+        )
+    if not captured:
+        return
+    record = captured[0]
+    warnings.warn(record.message, category=record.category, stacklevel=stacklevel + 1)
+
+
+def reset_deprecation_dedupe(*targets: object) -> None:
+    """Reset the `@deprecated` decorator's dedupe flag for testing.
+
+    The langchain_core `@deprecated` decorator emits each warning at most once
+    per process via a closure-bound `warned` flag. Tests that assert per-call
+    emission must reset that flag between cases — otherwise the assertions
+    become reorder-sensitive (notably under `pytest -n auto`).
+
+    Accepts decorated functions, methods, and `property` objects (in which
+    case the `fget` closure is reset). Targets without the expected `warned`
+    freevar are silently skipped, so passing non-decorated callables is safe.
+
+    Args:
+        *targets: Decorated callables (or properties wrapping them) to reset.
+    """
+    for target in targets:
+        fn = target.fget if isinstance(target, property) else target
+        code = getattr(fn, "__code__", None)
+        closure = getattr(fn, "__closure__", None)
+        if code is None or closure is None:
+            continue
+        try:
+            index = code.co_freevars.index("warned")
+        except ValueError:
+            continue
+        cell = closure[index]
+        try:
+            current = cell.cell_contents
+        except ValueError:  # empty cell
+            continue
+        if isinstance(current, bool):
+            cell.cell_contents = False

soothe_deepagents/_excluded_middleware.py

@@ -0,0 +1,225 @@
+"""Filtering helpers for `HarnessProfile.excluded_middleware`.
+
+These functions validate, apply, and audit exclusions against assembled
+middleware stacks. The set of *required scaffolding* — classes/names that
+must remain in the stack for the agent to function — is owned by
+`soothe_deepagents.graph` and threaded through as parameters so that policy stays
+next to `create_deep_agent`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from langchain.agents.middleware.types import AgentMiddleware
+
+    from soothe_deepagents.profiles import HarnessProfile
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_excluded_middleware_config(
+    profile: HarnessProfile,
+    *,
+    required_classes: frozenset[type[AgentMiddleware[Any, Any, Any]]],
+    required_names: frozenset[str],
+) -> None:
+    """Validate stack-independent guards on `profile.excluded_middleware`.
+
+    Rejects required-scaffolding entries (class or the equivalent `.name`
+    string). Grammar-level checks (empty strings, multi-colon, underscore
+    prefix on plain names) already fire at `HarnessProfile` construction;
+    this function focuses on the assembly-time invariant that scaffolding
+    middleware must remain present for the agent to function.
+
+    Args:
+        profile: Profile whose `excluded_middleware` is validated.
+        required_classes: Scaffolding classes that must not be excluded.
+        required_names: Scaffolding `.name` values that must not be excluded.
+
+    Raises:
+        ValueError: If any entry is required scaffolding.
+    """
+    excluded = profile.excluded_middleware
+    if not excluded:
+        return
+
+    excluded_classes: set[type[AgentMiddleware[Any, Any, Any]]] = set()
+    excluded_names: set[str] = set()
+    for entry in excluded:
+        if isinstance(entry, type):
+            excluded_classes.add(entry)
+        else:
+            excluded_names.add(entry)
+
+    forbidden_classes = excluded_classes & required_classes
+    forbidden_names = excluded_names & required_names
+    if forbidden_classes or forbidden_names:
+        # Lazy import: harness_profiles owns the per-class guidance text.
+        from soothe_deepagents.profiles.harness.harness_profiles import _format_scaffolding_rejection  # noqa: PLC0415
+
+        labels = [cls.__name__ for cls in forbidden_classes] + [f"{name!r} (string)" for name in forbidden_names]
+        raise ValueError(_format_scaffolding_rejection(labels))
+
+
+def _raise_on_name_collisions(
+    name_matched_types: dict[str, set[type[AgentMiddleware[Any, Any, Any]]]],
+) -> None:
+    """Raise `ValueError` if any string exclusion matched multiple distinct classes.
+
+    A string entry that drops instances of more than one concrete class is
+    almost always a surprise — e.g. a user middleware whose `.name`
+    accidentally collides with a built-in alias. Force the caller to use a
+    class-form exclusion via the runtime `HarnessProfile` to disambiguate.
+    """
+    collisions = {name: classes for name, classes in name_matched_types.items() if len(classes) > 1}
+    if not collisions:
+        return
+    labels = sorted(f"{name!r} matched {sorted(cls.__name__ for cls in classes)}" for name, classes in collisions.items())
+    msg = (
+        "HarnessProfile.excluded_middleware name entry matched multiple "
+        "distinct middleware classes within a single stack: "
+        f"{'; '.join(labels)}. Use a class-form exclusion via the runtime "
+        "`HarnessProfile` to disambiguate."
+    )
+    raise ValueError(msg)
+
+
+def _apply_excluded_middleware(
+    stack: list[AgentMiddleware[Any, Any, Any]],
+    profile: HarnessProfile,
+    *,
+    matched_classes: set[type[AgentMiddleware[Any, Any, Any]]] | None = None,
+    matched_names: set[str] | None = None,
+) -> list[AgentMiddleware[Any, Any, Any]]:
+    """Drop middleware in the stack matched by `profile.excluded_middleware`.
+
+    Class entries match on exact type (not `isinstance`), mirroring the
+    slot-identity semantics of `_merge_middleware` so a subclass introduced
+    by the caller is preserved when the profile excludes the base class.
+    String entries match `AgentMiddleware.name` exactly — defaults to the
+    class's `__name__` but is overridable when the public alias differs from
+    the impl class (e.g. `SummarizationMiddleware` for
+    `_DeepAgentsSummarizationMiddleware`).
+
+    When `matched_classes` / `matched_names` are supplied, matches are
+    recorded there so `_verify_excluded_middleware_coverage` can confirm
+    every entry matched *somewhere* across the stacks the profile applies to
+    (main agent + GP subagent). Per-stack checking would be too strict —
+    a profile legitimately targets middleware only one stack carries. Omit
+    the sets for single-stack filters where aggregation isn't meaningful.
+
+    Args:
+        stack: Fully assembled middleware list for a single agent/subagent.
+        profile: Profile whose `excluded_middleware` drives the filter.
+        matched_classes: Optional mutable set recording class matches across
+            calls for the same profile.
+        matched_names: Optional mutable set recording name matches, same
+            lifetime semantics as `matched_classes`.
+
+    Returns:
+        A new list with excluded entries removed. Always a fresh list, even
+            when no exclusions apply, so callers can mutate the result freely.
+    """
+    excluded = profile.excluded_middleware
+    if not excluded:
+        return list(stack)
+
+    excluded_classes: set[type[AgentMiddleware[Any, Any, Any]]] = set()
+    excluded_names: set[str] = set()
+    for entry in excluded:
+        if isinstance(entry, type):
+            excluded_classes.add(entry)
+        else:
+            excluded_names.add(entry)
+
+    filtered: list[AgentMiddleware[Any, Any, Any]] = []
+    name_matched_types: dict[str, set[type[AgentMiddleware[Any, Any, Any]]]] = {}
+    for mw in stack:
+        mw_type = type(mw)
+        mw_name = mw.name
+        if mw_type in excluded_classes:
+            if matched_classes is not None:
+                matched_classes.add(mw_type)
+            continue
+        if mw_name in excluded_names:
+            name_matched_types.setdefault(mw_name, set()).add(mw_type)
+            if matched_names is not None:
+                matched_names.add(mw_name)
+            continue
+        filtered.append(mw)
+
+    _raise_on_name_collisions(name_matched_types)
+
+    removed_count = len(stack) - len(filtered)
+    if removed_count:
+        logger.debug(
+            "Dropped %d middleware instance(s) from stack per profile.excluded_middleware=%r (matched classes=%s, names=%s)",
+            removed_count,
+            sorted(repr(entry) for entry in profile.excluded_middleware),
+            sorted(cls.__name__ for cls in excluded_classes),
+            sorted(excluded_names),
+        )
+    return filtered
+
+
+def _verify_excluded_middleware_coverage(
+    profile: HarnessProfile,
+    matched_classes: set[type[AgentMiddleware[Any, Any, Any]]],
+    matched_names: set[str],
+    *,
+    required_classes: frozenset[type[AgentMiddleware[Any, Any, Any]]],
+    required_names: frozenset[str],
+) -> None:
+    """Raise `ValueError` if any `profile.excluded_middleware` entry matched nothing.
+
+    Run after every stack has been filtered so the accumulated `matched_*`
+    sets reflect matches anywhere. An entry that matched nothing is almost
+    always a typo or stale profile. Required-scaffolding and `_`-prefixed
+    entries are skipped — rejected earlier by
+    `_validate_excluded_middleware_config`.
+
+    Args:
+        profile: Profile whose `excluded_middleware` is being audited.
+        matched_classes: Accumulated class matches across filter calls.
+        matched_names: Accumulated name matches across filter calls.
+        required_classes: Scaffolding classes; subtracted from unmatched so
+            scaffolding exclusions (already rejected upstream) don't surface
+            here as defense-in-depth.
+        required_names: Scaffolding `.name` values; same purpose as
+            `required_classes`.
+
+    Raises:
+        ValueError: If any entry is missing from the corresponding `matched_*` set.
+    """
+    excluded = profile.excluded_middleware
+    if not excluded:
+        return
+
+    excluded_classes: set[type[AgentMiddleware[Any, Any, Any]]] = set()
+    excluded_names: set[str] = set()
+    for entry in excluded:
+        if isinstance(entry, type):
+            excluded_classes.add(entry)
+        else:
+            excluded_names.add(entry)
+
+    unmatched_classes = excluded_classes - matched_classes - required_classes
+    unmatched_names = excluded_names - matched_names - required_names
+    # Private-prefix names are rejected by the config guard; skip them here
+    # so the coverage error stays focused on legitimate "didn't match" cases.
+    unmatched_names = {name for name in unmatched_names if not name.startswith("_")}
+    if not unmatched_classes and not unmatched_names:
+        return
+
+    labels = sorted({cls.__name__ for cls in unmatched_classes} | {f"{name!r} (string)" for name in unmatched_names})
+    msg = (
+        f"HarnessProfile.excluded_middleware entries matched no middleware "
+        f"across any assembled stack: {', '.join(labels)}. Typo or stale "
+        f"profile — every exclusion must correspond to a middleware actually "
+        f"present at runtime. (Tip: use class-form exclusion when the class "
+        f"is available to catch typos at import time.)"
+    )
+    raise ValueError(msg)

soothe_deepagents/_messages_reducer.py

@@ -0,0 +1,90 @@
+"""Local `DeltaChannel` reducer for the messages key.
+
+Adapted from langgraph's `_messages_delta_reducer` (PR #7729). The upstream
+version coerces `BaseMessageChunk` writes to full messages for parity with
+`add_messages`. Deepagents never writes chunks to the messages channel —
+`langchain.agents.create_agent` appends full `AIMessage` objects, and
+streaming via `astream_events` operates on the output side, not the state
+side — so we skip the per-message coercion.
+
+ID assignment is intentionally absent here. LangGraph's `ensure_message_ids`
+stamps stable UUIDs onto all `BaseMessage` writes before they are serialised
+to the checkpoint, so by the time the reducer sees a message it already has a
+stable ID. Assigning IDs in the reducer would be both redundant and fragile
+(a reducer runs on replay too, where a randomly-assigned ID would differ from
+the one stored in the checkpoint).
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from langchain_core.messages import (
+    AnyMessage,
+    BaseMessage,
+    RemoveMessage,
+    convert_to_messages,
+)
+from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+
+def _messages_delta_reducer(  # noqa: C901, PLR0912
+    state: list[AnyMessage] | None, writes: list[list[AnyMessage]]
+) -> list[AnyMessage]:
+    """Batch reducer for use with `DeltaChannel` on the messages key.
+
+    Dedups by ID, tombstones via `RemoveMessage`, resets on
+    `REMOVE_ALL_MESSAGES`. IDs are expected to be pre-assigned by LangGraph's
+    `ensure_message_ids` hook; id=None messages are appended as-is.
+
+    Raw dict / string / tuple inputs are coerced to typed `BaseMessage` so
+    HTTP-driven graphs work without a separate coercion step.
+    """
+    # Each write is either a list of message-likes or a single message-like
+    # (BaseMessage / dict / str / tuple). Only lists flatten; everything
+    # else is one message.
+    flat: list[Any] = []
+    for w in writes:
+        if isinstance(w, list):
+            flat.extend(w)
+        else:
+            flat.append(w)
+    # Steady state: the reducer's own output is already typed BaseMessages,
+    # so skip convert_to_messages on the fast path. Only raw input (initial
+    # dicts, deserialized blobs) hits the slow path. `state` is `None` on
+    # `DeltaChannel.replay_writes` for threads whose earliest checkpoint did
+    # not seed `messages: []`; treat that as the empty list so the slow path
+    # doesn't pass `None` into `convert_to_messages`.
+    state_msgs = state if state and isinstance(state[0], BaseMessage) else cast("list[AnyMessage]", convert_to_messages(state or []))
+    msgs = cast("list[AnyMessage]", convert_to_messages(flat))
+
+    # REMOVE_ALL_MESSAGES resets everything; find the last sentinel and
+    # discard all state plus all writes before it.
+    remove_all_idx = None
+    for idx, m in enumerate(msgs):
+        if isinstance(m, RemoveMessage) and m.id == REMOVE_ALL_MESSAGES:
+            remove_all_idx = idx
+    if remove_all_idx is not None:
+        state_msgs = []
+        msgs = msgs[remove_all_idx + 1 :]
+
+    result: list[AnyMessage | None] = []
+    index: dict[str, int] = {}
+    for m in state_msgs:
+        if m.id is not None:
+            index[m.id] = len(result)
+        result.append(m)
+    for msg in msgs:
+        mid = msg.id
+        if mid is None:
+            result.append(msg)
+        elif isinstance(msg, RemoveMessage):
+            if mid in index:
+                result[index[mid]] = None
+                del index[mid]
+        elif mid in index:
+            result[index[mid]] = msg
+        else:
+            index[mid] = len(result)
+            result.append(msg)
+    return [m for m in result if m is not None]