style: more refs polishing (#33601)

Author: mdrxy

libs/core/langchain_core/caches.py

@@ -1,4 +1,6 @@
-"""`caches` provides an optional caching layer for language models.
+"""Optional caching layer for language models.
+
+Distinct from provider-based [prompt caching](https://docs.langchain.com/oss/python/langchain/models#prompt-caching).
 
 !!! warning
     This is a beta feature! Please be wary of deploying experimental code to production

libs/core/langchain_core/tools/base.py

@@ -483,7 +483,7 @@ class ChildTool(BaseTool):
     """The tool response format.
 
     If `"content"` then the output of the tool is interpreted as the contents of a
-    ToolMessage. If `"content_and_artifact"` then the output is expected to be a
+    `ToolMessage`. If `"content_and_artifact"` then the output is expected to be a
     two-tuple corresponding to the (content, artifact) of a `ToolMessage`.
     """
 

libs/core/langchain_core/utils/json_schema.py

@@ -226,7 +226,7 @@ def dereference_refs(
         ... }
         >>> result = dereference_refs(schema)  # Won't cause infinite recursion
 
-    Note:
+    !!! note
         - Circular references are handled gracefully by breaking cycles
         - Mixed $ref objects (with both $ref and other properties) are supported
         - Additional properties in mixed $refs override resolved properties

libs/langchain/langchain_classic/embeddings/base.py

@@ -137,20 +137,34 @@ def init_embeddings(
         installed.
 
     Args:
-        model: Name of the model to use. Can be either:
+        model: Name of the model to use.
+
+            Can be either:
+
             - A model string like `"openai:text-embedding-3-small"`
-            - Just the model name if provider is specified
-        provider: Optional explicit provider name. If not specified,
-            will attempt to parse from the model string. Supported providers
-            and their required packages:
+            - Just the model name if the provider is specified separately or can be
+                inferred.
+
+            See supported providers under the `provider` arg description.
+        provider: Optional explicit provider name. If not specified, will attempt to
+            parse from the model string in the `model` arg.
+
+            Supported providers:
 
-            {_get_provider_list()}
+            - `openai`                  -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `azure_openai`            -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `bedrock`                 -> [`langchain-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `cohere`                  -> [`langchain-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+            - `google_vertexai`         -> [`langchain-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `huggingface`             -> [`langchain-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+            - `mistraiai`               -> [`langchain-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+            - `ollama`                  -> [`langchain-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
 
         **kwargs: Additional model-specific parameters passed to the embedding model.
             These vary by provider, see the provider-specific documentation for details.
 
     Returns:
-        An Embeddings instance that can generate embeddings for text.
+        An `Embeddings` instance that can generate embeddings for text.
 
     Raises:
         ValueError: If the model provider is not supported or cannot be determined

libs/langchain_v1/langchain/agents/factory.py

@@ -525,7 +525,7 @@ def create_agent(  # noqa: PLR0915
     """Creates an agent graph that calls tools in a loop until a stopping condition is met.
 
     For more details on using `create_agent`,
-    visit [Agents](https://docs.langchain.com/oss/python/langchain/agents) documentation.
+    visit the [Agents](https://docs.langchain.com/oss/python/langchain/agents) docs.
 
     Args:
         model: The language model for the agent. Can be a string identifier

libs/langchain_v1/langchain/embeddings/base.py

@@ -133,20 +133,34 @@ def init_embeddings(
         installed.
 
     Args:
-        model: Name of the model to use. Can be either:
+        model: Name of the model to use.
+
+            Can be either:
+
             - A model string like `"openai:text-embedding-3-small"`
-            - Just the model name if provider is specified
-        provider: Optional explicit provider name. If not specified,
-            will attempt to parse from the model string. Supported providers
-            and their required packages:
+            - Just the model name if the provider is specified separately or can be
+                inferred.
+
+            See supported providers under the `provider` arg description.
+        provider: Optional explicit provider name. If not specified, will attempt to
+            parse from the model string in the `model` arg.
+
+            Supported providers:
 
-            {_get_provider_list()}
+            - `openai`                  -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `azure_openai`            -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `bedrock`                 -> [`langchain-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `cohere`                  -> [`langchain-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+            - `google_vertexai`         -> [`langchain-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `huggingface`             -> [`langchain-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+            - `mistraiai`               -> [`langchain-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+            - `ollama`                  -> [`langchain-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
 
         **kwargs: Additional model-specific parameters passed to the embedding model.
             These vary by provider, see the provider-specific documentation for details.
 
     Returns:
-        An Embeddings instance that can generate embeddings for text.
+        An `Embeddings` instance that can generate embeddings for text.
 
     Raises:
         ValueError: If the model provider is not supported or cannot be determined

libs/langchain_v1/langchain/tools/tool_node.py

@@ -13,10 +13,10 @@
 - Command-based state updates for advanced control flow
 
 Key Components:
-    ToolNode: Main class for executing tools in LangGraph workflows
-    InjectedState: Annotation for injecting graph state into tools
-    InjectedStore: Annotation for injecting persistent store into tools
-    tools_condition: Utility function for conditional routing based on tool calls
+    `ToolNode`: Main class for executing tools in LangGraph workflows
+    `InjectedState`: Annotation for injecting graph state into tools
+    `InjectedStore`: Annotation for injecting persistent store into tools
+    `tools_condition`: Utility function for conditional routing based on tool calls
 
 Typical Usage:
     ```python
@@ -123,11 +123,11 @@ class ToolCallRequest:
     Attributes:
         tool_call: Tool call dict with name, args, and id from model output.
         tool: BaseTool instance to be invoked, or None if tool is not
-            registered with the ToolNode. When tool is None, interceptors can
-            handle the request without validation. If the interceptor calls execute(),
+            registered with the `ToolNode`. When tool is `None`, interceptors can
+            handle the request without validation. If the interceptor calls `execute()`,
             validation will occur and raise an error for unregistered tools.
-        state: Agent state (dict, list, or BaseModel).
-        runtime: LangGraph runtime context (optional, None if outside graph).
+        state: Agent state (`dict`, `list`, or `BaseModel`).
+        runtime: LangGraph runtime context (optional, `None` if outside graph).
     """
 
     tool_call: ToolCall
@@ -178,7 +178,7 @@ def override(self, **overrides: Unpack[_ToolCallRequestOverrides]) -> ToolCallRe
 with potentially modified requests each time. Each call to execute
 is independent and stateless.
 
-Note:
+!!! note
     When implementing middleware for `create_agent`, use
     `AgentMiddleware.wrap_tool_call` which provides properly typed
     state parameter for better type safety.
@@ -247,7 +247,7 @@ def handler(request, execute):
 class ToolCallWithContext(TypedDict):
     """ToolCall with additional context for graph state.
 
-    This is an internal data structure meant to help the ToolNode accept
+    This is an internal data structure meant to help the `ToolNode` accept
     tool calls with additional context (e.g. state) when dispatched using the
     Send API.
 
@@ -268,16 +268,16 @@ class ToolCallWithContext(TypedDict):
 
 
 def msg_content_output(output: Any) -> str | list[dict]:
-    """Convert tool output to ToolMessage content format.
+    """Convert tool output to `ToolMessage` content format.
 
-    Handles str, list[dict] (content blocks), and arbitrary objects by attempting
+    Handles `str`, `list[dict]` (content blocks), and arbitrary objects by attempting
     JSON serialization with fallback to str().
 
     Args:
         output: Tool execution output of any type.
 
     Returns:
-        String or list of content blocks suitable for ToolMessage.content.
+        String or list of content blocks suitable for `ToolMessage.content`.
     """
     if isinstance(output, str) or (
         isinstance(output, list)
@@ -297,7 +297,7 @@ def msg_content_output(output: Any) -> str | list[dict]:
 class ToolInvocationError(ToolException):
     """An error occurred while invoking a tool due to invalid arguments.
 
-    This exception is only raised when invoking a tool using the ToolNode!
+    This exception is only raised when invoking a tool using the `ToolNode`!
     """
 
     def __init__(
@@ -338,7 +338,7 @@ def _handle_tool_error(
     """Generate error message content based on exception handling configuration.
 
     This function centralizes error message generation logic, supporting different
-    error handling strategies configured via the ToolNode's handle_tool_errors
+    error handling strategies configured via the `ToolNode`'s `handle_tool_errors`
     parameter.
 
     Args:
@@ -350,12 +350,12 @@ def _handle_tool_error(
             - tuple: Not used in this context (handled by caller)
 
     Returns:
-        A string containing the error message to include in the ToolMessage.
+        A string containing the error message to include in the `ToolMessage`.
 
     Raises:
         ValueError: If flag is not one of the supported types.
 
-    Note:
+    !!! note
         The tuple case is handled by the caller through exception type checking,
         not by this function directly.
     """
@@ -392,9 +392,9 @@ def _infer_handled_types(handler: Callable[..., str]) -> tuple[type[Exception],
 
     Raises:
         ValueError: If the handler's annotation contains non-Exception types or
-                   if Union types contain non-Exception types.
+            if Union types contain non-Exception types.
 
-    Note:
+    !!! note
         This function supports both single exception types and Union types for
         handlers that need to handle multiple exception types differently.
     """
@@ -560,7 +560,7 @@ def __init__(
         wrap_tool_call: ToolCallWrapper | None = None,
         awrap_tool_call: AsyncToolCallWrapper | None = None,
     ) -> None:
-        """Initialize ToolNode with tools and configuration.
+        """Initialize `ToolNode` with tools and configuration.
 
         Args:
             tools: Sequence of tools to make available for execution.
@@ -1181,11 +1181,11 @@ def _inject_tool_args(
 
         Raises:
             ValueError: If a tool requires store injection but no store is provided,
-                       or if state injection requirements cannot be satisfied.
+                or if state injection requirements cannot be satisfied.
 
-        Note:
+        !!! note
             This method is called automatically during tool execution. It should not
-            be called from outside the ToolNode.
+            be called from outside the `ToolNode`.
         """
         if tool_call["name"] not in self.tools_by_name:
             return tool_call
@@ -1329,9 +1329,9 @@ def custom_condition(state):
             return tools_condition(state, messages_key="chat_history")
         ```
 
-    Note:
-        This function is designed to work seamlessly with ToolNode and standard
-        LangGraph patterns. It expects the last message to be an AIMessage when
+    !!! note
+        This function is designed to work seamlessly with `ToolNode` and standard
+        LangGraph patterns. It expects the last message to be an `AIMessage` when
         tool calls are present, which is the standard output format for tool-calling
         language models.
     """
@@ -1353,16 +1353,16 @@ def custom_condition(state):
 class ToolRuntime(_DirectlyInjectedToolArg, Generic[ContextT, StateT]):
     """Runtime context automatically injected into tools.
 
-    When a tool function has a parameter named 'tool_runtime' with type hint
-    'ToolRuntime', the tool execution system will automatically inject
-    an instance containing:
+    When a tool function has a parameter named `tool_runtime` with type hint
+    `ToolRuntime`, the tool execution system will automatically inject an instance
+    containing:
 
-    - state: The current graph state
-    - tool_call_id: The ID of the current tool call
-    - config: RunnableConfig for the current execution
-    - context: Runtime context (from langgraph Runtime)
-    - store: BaseStore instance for persistent storage (from langgraph Runtime)
-    - stream_writer: StreamWriter for streaming output (from langgraph Runtime)
+    - `state`: The current graph state
+    - `tool_call_id`: The ID of the current tool call
+    - `config`: `RunnableConfig` for the current execution
+    - `context`: Runtime context (from langgraph `Runtime`)
+    - `store`: `BaseStore` instance for persistent storage (from langgraph `Runtime`)
+    - `stream_writer`: `StreamWriter` for streaming output (from langgraph `Runtime`)
 
     No `Annotated` wrapper is needed - just use `runtime: ToolRuntime`
     as a parameter.
@@ -1396,7 +1396,7 @@ def my_tool(x: int, runtime: ToolRuntime) -> str:
             return f"Processed {x}"
         ```
 
-    Note:
+    !!! note
         This is a marker class used for type checking and detection.
         The actual runtime object will be constructed during tool execution.
     """
@@ -1470,7 +1470,7 @@ def foo_tool(x: int, foo: Annotated[str, InjectedState("foo")]) -> str:
         ]
         ```
 
-    Note:
+    !!! note
         - `InjectedState` arguments are automatically excluded from tool schemas
             presented to language models
         - `ToolNode` handles the injection process during execution
@@ -1550,7 +1550,7 @@ def get_preference(
         result2 = graph.invoke({"messages": [HumanMessage("What's my favorite color?")]})
         ```
 
-    Note:
+    !!! note
         - `InjectedStore` arguments are automatically excluded from tool schemas
             presented to language models
         - The store instance is automatically injected by `ToolNode` during execution