style(langchain): fix some middleware ref syntax (#33988)

Author: mdrxy

libs/langchain_v1/langchain/agents/middleware/file_search.py

@@ -120,9 +120,9 @@ def __init__(
 
         Args:
             root_path: Root directory to search.
-            use_ripgrep: Whether to use ripgrep for search.
+            use_ripgrep: Whether to use `ripgrep` for search.
 
-                Falls back to Python if ripgrep unavailable.
+                Falls back to Python if `ripgrep` unavailable.
             max_file_size_mb: Maximum file size to search in MB.
         """
         self.root_path = Path(root_path).resolve()

libs/langchain_v1/langchain/agents/middleware/model_call_limit.py

@@ -133,6 +133,7 @@ def __init__(
 
                 `None` means no limit.
             exit_behavior: What to do when limits are exceeded.
+
                 - `'end'`: Jump to the end of the agent execution and
                     inject an artificial AI message indicating that the limit was
                     exceeded.

libs/langchain_v1/langchain/agents/middleware/shell_tool.py

@@ -389,7 +389,7 @@ def __init__(
         shell_command: Sequence[str] | str | None = None,
         env: Mapping[str, Any] | None = None,
     ) -> None:
-        """Initialize the middleware.
+        """Initialize an instance of `ShellToolMiddleware`.
 
         Args:
             workspace_root: Base directory for the shell session.

libs/langchain_v1/langchain/agents/middleware/summarization.py

@@ -87,18 +87,27 @@ def __init__(
 
         Args:
             model: The language model to use for generating summaries.
-            trigger: One or more thresholds that trigger summarization. Provide a single
-                `ContextSize` tuple or a list of tuples, in which case summarization runs
-                when any threshold is breached. Examples: `("messages", 50)`, `("tokens", 3000)`,
-                `[("fraction", 0.8), ("messages", 100)]`.
-            keep: Context retention policy applied after summarization. Provide a
-                `ContextSize` tuple to specify how much history to preserve. Defaults to
-                keeping the most recent 20 messages. Examples: `("messages", 20)`,
-                `("tokens", 3000)`, or `("fraction", 0.3)`.
+            trigger: One or more thresholds that trigger summarization.
+
+                Provide a single `ContextSize` tuple or a list of tuples, in which case
+                summarization runs when any threshold is breached.
+
+                Examples: `("messages", 50)`, `("tokens", 3000)`, `[("fraction", 0.8),
+                    ("messages", 100)]`.
+            keep: Context retention policy applied after summarization.
+
+                Provide a `ContextSize` tuple to specify how much history to preserve.
+
+                Defaults to keeping the most recent 20 messages.
+
+                Examples: `("messages", 20)`, `("tokens", 3000)`, or
+                    `("fraction", 0.3)`.
             token_counter: Function to count tokens in messages.
             summary_prompt: Prompt template for generating summaries.
-            trim_tokens_to_summarize: Maximum tokens to keep when preparing messages for the
-                summarization call. Pass `None` to skip trimming entirely.
+            trim_tokens_to_summarize: Maximum tokens to keep when preparing messages for
+                the summarization call.
+
+                Pass `None` to skip trimming entirely.
         """
         # Handle deprecated parameters
         if "max_tokens_before_summary" in deprecated_kwargs:
@@ -354,7 +363,7 @@ def _find_safe_cutoff(self, messages: list[AnyMessage], messages_to_keep: int) -
         """Find safe cutoff point that preserves AI/Tool message pairs.
 
         Returns the index where messages can be safely cut without separating
-        related AI and Tool messages. Returns 0 if no safe cutoff is found.
+        related AI and Tool messages. Returns `0` if no safe cutoff is found.
         """
         if len(messages) <= messages_to_keep:
             return 0

libs/langchain_v1/langchain/agents/middleware/todo.py

@@ -150,10 +150,6 @@ class TodoListMiddleware(AgentMiddleware):
 
         print(result["todos"])  # Array of todo items with status tracking
         ```
-
-    Args:
-        system_prompt: Custom system prompt to guide the agent on using the todo tool.
-        tool_description: Custom description for the write_todos tool.
     """
 
     state_schema = PlanningState

libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py

@@ -153,38 +153,46 @@ class ToolCallLimitMiddleware(
                 are other pending tool calls (due to parallel tool calling).
 
     Examples:
-        ```python title="Continue execution with blocked tools (default)"
-        from langchain.agents.middleware.tool_call_limit import ToolCallLimitMiddleware
-        from langchain.agents import create_agent
-
-        # Block exceeded tools but let other tools and model continue
-        limiter = ToolCallLimitMiddleware(
-            thread_limit=20,
-            run_limit=10,
-            exit_behavior="continue",  # default
-        )
+        !!! example "Continue execution with blocked tools (default)"
+
+            ```python
+            from langchain.agents.middleware.tool_call_limit import ToolCallLimitMiddleware
+            from langchain.agents import create_agent
+
+            # Block exceeded tools but let other tools and model continue
+            limiter = ToolCallLimitMiddleware(
+                thread_limit=20,
+                run_limit=10,
+                exit_behavior="continue",  # default
+            )
 
-        agent = create_agent("openai:gpt-4o", middleware=[limiter])
-        ```
+            agent = create_agent("openai:gpt-4o", middleware=[limiter])
+            ```
 
-        ```python title="Stop immediately when limit exceeded"
-        # End execution immediately with an AI message
-        limiter = ToolCallLimitMiddleware(run_limit=5, exit_behavior="end")
+        !!! example "Stop immediately when limit exceeded"
 
-        agent = create_agent("openai:gpt-4o", middleware=[limiter])
-        ```
+            ```python
+            # End execution immediately with an AI message
+            limiter = ToolCallLimitMiddleware(run_limit=5, exit_behavior="end")
 
-        ```python title="Raise exception on limit"
-        # Strict limit with exception handling
-        limiter = ToolCallLimitMiddleware(tool_name="search", thread_limit=5, exit_behavior="error")
+            agent = create_agent("openai:gpt-4o", middleware=[limiter])
+            ```
 
-        agent = create_agent("openai:gpt-4o", middleware=[limiter])
+        !!! example "Raise exception on limit"
 
-        try:
-            result = await agent.invoke({"messages": [HumanMessage("Task")]})
-        except ToolCallLimitExceededError as e:
-            print(f"Search limit exceeded: {e}")
-        ```
+            ```python
+            # Strict limit with exception handling
+            limiter = ToolCallLimitMiddleware(
+                tool_name="search", thread_limit=5, exit_behavior="error"
+            )
+
+            agent = create_agent("openai:gpt-4o", middleware=[limiter])
+
+            try:
+                result = await agent.invoke({"messages": [HumanMessage("Task")]})
+            except ToolCallLimitExceededError as e:
+                print(f"Search limit exceeded: {e}")
+            ```
 
     """
 
@@ -208,6 +216,7 @@ def __init__(
             run_limit: Maximum number of tool calls allowed per run.
                 `None` means no limit.
             exit_behavior: How to handle when limits are exceeded.
+
                 - `'continue'`: Block exceeded tools with error messages, let other
                     tools continue. Model decides when to end.
                 - `'error'`: Raise a `ToolCallLimitExceededError` exception
@@ -218,7 +227,7 @@ def __init__(
 
         Raises:
             ValueError: If both limits are `None`, if `exit_behavior` is invalid,
-                or if `run_limit` exceeds thread_limit.
+                or if `run_limit` exceeds `thread_limit`.
         """
         super().__init__()
 

libs/langchain_v1/langchain/agents/middleware/tool_emulator.py

@@ -25,34 +25,42 @@ class LLMToolEmulator(AgentMiddleware):
     This middleware allows selective emulation of tools for testing purposes.
 
     By default (when `tools=None`), all tools are emulated. You can specify which
-    tools to emulate by passing a list of tool names or BaseTool instances.
+    tools to emulate by passing a list of tool names or `BaseTool` instances.
 
     Examples:
-        ```python title="Emulate all tools (default behavior)"
-        from langchain.agents.middleware import LLMToolEmulator
+        !!! example "Emulate all tools (default behavior)"
 
-        middleware = LLMToolEmulator()
+            ```python
+            from langchain.agents.middleware import LLMToolEmulator
 
-        agent = create_agent(
-            model="openai:gpt-4o",
-            tools=[get_weather, get_user_location, calculator],
-            middleware=[middleware],
-        )
-        ```
+            middleware = LLMToolEmulator()
 
-        ```python title="Emulate specific tools by name"
-        middleware = LLMToolEmulator(tools=["get_weather", "get_user_location"])
-        ```
+            agent = create_agent(
+                model="openai:gpt-4o",
+                tools=[get_weather, get_user_location, calculator],
+                middleware=[middleware],
+            )
+            ```
 
-        ```python title="Use a custom model for emulation"
-        middleware = LLMToolEmulator(
-            tools=["get_weather"], model="anthropic:claude-sonnet-4-5-20250929"
-        )
-        ```
+        !!! example "Emulate specific tools by name"
+
+            ```python
+            middleware = LLMToolEmulator(tools=["get_weather", "get_user_location"])
+            ```
+
+        !!! example "Use a custom model for emulation"
+
+            ```python
+            middleware = LLMToolEmulator(
+                tools=["get_weather"], model="anthropic:claude-sonnet-4-5-20250929"
+            )
+            ```
+
+        !!! example "Emulate specific tools by passing tool instances"
 
-        ```python title="Emulate specific tools by passing tool instances"
-        middleware = LLMToolEmulator(tools=[get_weather, get_user_location])
-        ```
+            ```python
+            middleware = LLMToolEmulator(tools=[get_weather, get_user_location])
+            ```
     """
 
     def __init__(