chore: trim narrative comments and docstrings

surfsense_backend/app/agents/multi_agent_chat/main_agent/graph/middleware/deepagent_stack.py

@@ -210,10 +210,8 @@ def build_main_agent_deepagent_middleware(
         )
         gp_middleware.insert(_patch_idx, subagent_deny_permission_mw)
 
-    # Defined here (instead of further down with the other ``wrap_model_call``
-    # middlewares) so subagents share the same instances as the parent —
-    # otherwise a connector subagent would die on the first provider hiccup
-    # while the parent stays resilient.
+    # Defined early so the same instances reach both gp_middleware and
+    # subagent_extra_middleware below.
     retry_mw = (
         RetryAfterMiddleware(max_retries=3)
         if flags.enable_retry_after and not flags.disable_new_agent_stack
@@ -230,9 +228,7 @@ def build_main_agent_deepagent_middleware(
             logging.warning("ScopedModelFallbackMiddleware init failed; skipping.")
             fallback_mw = None
 
-    # Cost / loop ceiling shared with subagents. ``state_schema`` of these
-    # middlewares is per-agent; counts are not summed across parent + sub —
-    # the cap acts as a safety net per agent, not a global budget.
+    # Per-agent caps; counts are not summed across parent + subagents.
     model_call_limit_mw = (
         ModelCallLimitMiddleware(
             thread_limit=120,
@@ -250,9 +246,8 @@ def build_main_agent_deepagent_middleware(
         else None
     )
 
-    # Mirror the parent's ordering: retry / fallback / limits wrap caching,
-    # which wraps the model. ``gp_middleware`` is held by reference inside
-    # ``general_purpose_spec`` so this insertion propagates into the spec.
+    # gp_middleware is held by reference inside general_purpose_spec, so
+    # mutating it here propagates into the spec.
     _gp_resilience: list[Any] = [
         m
         for m in (retry_mw, fallback_mw, model_call_limit_mw, tool_call_limit_mw)

surfsense_backend/app/agents/new_chat/middleware/scoped_model_fallback.py

@@ -1,17 +1,4 @@
-"""Fallback only on provider/network errors; let programming bugs raise.
-
-Upstream :class:`langchain.agents.middleware.ModelFallbackMiddleware` catches
-every ``Exception``. With a non-provider bug (``KeyError``, ``TypeError``,
-``AttributeError`` from middleware/state), every fallback model in the chain
-hits the same bug — burning latency and tokens before the real cause finally
-surfaces. Scoping the catch to provider-style exception types lets bugs fail
-fast with clean tracebacks.
-
-Class-name matching (instead of ``isinstance`` against imported provider
-types) keeps the dependency surface flat: openai, anthropic, google,
-mistral, etc. all ship their own ``RateLimitError`` and we don't want to
-import them all.
-"""
+"""Fallback only on provider/network errors; let programming bugs raise."""
 
 from __future__ import annotations
 
@@ -26,17 +13,16 @@ if TYPE_CHECKING:
     from langchain_core.messages import AIMessage
 
 
+# Matched by class name across the MRO so we don't have to import every
+# provider SDK (openai/anthropic/google/...). Extend as new providers ship.
 _FALLBACK_ELIGIBLE_NAMES: frozenset[str] = frozenset(
     {
-        # Rate / quota
         "RateLimitError",
-        # Server-side
         "APIStatusError",
         "InternalServerError",
         "ServiceUnavailableError",
         "BadGatewayError",
         "GatewayTimeoutError",
-        # Network
         "APIConnectionError",
         "APITimeoutError",
         "ConnectError",
@@ -45,18 +31,16 @@ _FALLBACK_ELIGIBLE_NAMES: frozenset[str] = frozenset(
         "RemoteProtocolError",
         "TimeoutError",
         "TimeoutException",
-        # Can be extended to other exceptions in the future
     }
 )
 
 
 def _is_fallback_eligible(exc: BaseException) -> bool:
-    """Eligible if the exception or any base in its MRO matches by class name."""
     return any(cls.__name__ in _FALLBACK_ELIGIBLE_NAMES for cls in type(exc).__mro__)
 
 
 class ScopedModelFallbackMiddleware(ModelFallbackMiddleware):
-    """``ModelFallbackMiddleware`` that re-raises non-provider exceptions."""
+    """Re-raise non-provider exceptions instead of walking the fallback chain."""
 
     def wrap_model_call(  # type: ignore[override]
         self,