langchain 1.0.4__py3-none-any.whl → 1.2.3__py3-none-any.whl

langchain/__init__.py

@@ -1,3 +1,3 @@
 """Main entrypoint into LangChain."""
 
-__version__ = "1.0.4"
+__version__ = "1.2.3"

langchain/agents/__init__.py

@@ -1,10 +1,4 @@
-"""Entrypoint to building [Agents](https://docs.langchain.com/oss/python/langchain/agents) with LangChain.
-
-!!! warning "Reference docs"
-    This page contains **reference documentation** for Agents. See
-    [the docs](https://docs.langchain.com/oss/python/langchain/agents) for conceptual
-    guides, tutorials, and examples on using Agents.
-"""  # noqa: E501
+"""Entrypoint to building [Agents](https://docs.langchain.com/oss/python/langchain/agents) with LangChain."""  # noqa: E501
 
 from langchain.agents.factory import create_agent
 from langchain.agents.middleware.types import AgentState

langchain/agents/factory.py

@@ -20,9 +20,7 @@ from langgraph._internal._runnable import RunnableCallable
 from langgraph.constants import END, START
 from langgraph.graph.state import StateGraph
 from langgraph.prebuilt.tool_node import ToolCallWithContext, ToolNode
-from langgraph.runtime import Runtime  # noqa: TC002
 from langgraph.types import Command, Send
-from langgraph.typing import ContextT  # noqa: TC002
 from typing_extensions import NotRequired, Required, TypedDict
 
 from langchain.agents.middleware.types import (
@@ -56,13 +54,27 @@ if TYPE_CHECKING:
     from langchain_core.runnables import Runnable
     from langgraph.cache.base import BaseCache
     from langgraph.graph.state import CompiledStateGraph
+    from langgraph.runtime import Runtime
     from langgraph.store.base import BaseStore
     from langgraph.types import Checkpointer
+    from langgraph.typing import ContextT
 
     from langchain.agents.middleware.types import ToolCallRequest, ToolCallWrapper
 
 STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
 
+FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT = [
+    # if model profile data are not available, these models are assumed to support
+    # structured output
+    "grok",
+    "gpt-5",
+    "gpt-4.1",
+    "gpt-4o",
+    "gpt-oss",
+    "o3-pro",
+    "o3-mini",
+]
+
 
 def _normalize_to_model_response(result: ModelResponse | AIMessage) -> ModelResponse:
     """Normalize middleware return value to ModelResponse."""
@@ -302,7 +314,7 @@ def _resolve_schema(schemas: set[type], schema_name: str, omit_flag: str | None
 def _extract_metadata(type_: type) -> list:
     """Extract metadata from a field type, handling Required/NotRequired and Annotated wrappers."""
     # Handle Required[Annotated[...]] or NotRequired[Annotated[...]]
-    if get_origin(type_) in (Required, NotRequired):
+    if get_origin(type_) in {Required, NotRequired}:
         inner_type = get_args(type_)[0]
         if get_origin(inner_type) is Annotated:
             return list(get_args(inner_type)[1:])
@@ -349,11 +361,13 @@ def _get_can_jump_to(middleware: AgentMiddleware[Any, Any], hook_name: str) -> l
     return []
 
 
-def _supports_provider_strategy(model: str | BaseChatModel) -> bool:
+def _supports_provider_strategy(model: str | BaseChatModel, tools: list | None = None) -> bool:
     """Check if a model supports provider-specific structured output.
 
     Args:
         model: Model name string or `BaseChatModel` instance.
+        tools: Optional list of tools provided to the agent. Needed because some models
+            don't support structured output together with tool calling.
 
     Returns:
         `True` if the model supports provider-specific structured output, `False` otherwise.
@@ -362,11 +376,23 @@ def _supports_provider_strategy(model: str | BaseChatModel) -> bool:
     if isinstance(model, str):
         model_name = model
     elif isinstance(model, BaseChatModel):
-        model_name = getattr(model, "model_name", None)
+        model_name = (
+            getattr(model, "model_name", None)
+            or getattr(model, "model", None)
+            or getattr(model, "model_id", "")
+        )
+        model_profile = model.profile
+        if (
+            model_profile is not None
+            and model_profile.get("structured_output")
+            # We make an exception for Gemini models, which currently do not support
+            # simultaneous tool use with structured output
+            and not (tools and isinstance(model_name, str) and "gemini" in model_name.lower())
+        ):
+            return True
 
     return (
-        "grok" in model_name.lower()
-        or any(part in model_name for part in ["gpt-5", "gpt-4.1", "gpt-oss", "o3-pro", "o3-mini"])
+        any(part in model_name.lower() for part in FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT)
         if model_name
         else False
     )
@@ -512,11 +538,11 @@ def _chain_async_tool_call_wrappers(
     return result
 
 
-def create_agent(  # noqa: PLR0915
+def create_agent(
     model: str | BaseChatModel,
     tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
     *,
-    system_prompt: str | None = None,
+    system_prompt: str | SystemMessage | None = None,
     middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),
     response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None,
     state_schema: type[AgentState[ResponseT]] | None = None,
@@ -537,42 +563,64 @@ def create_agent(  # noqa: PLR0915
     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
-            (e.g., `"openai:gpt-4"`) or a direct chat model instance (e.g.,
-            [`ChatOpenAI`][langchain_openai.ChatOpenAI] or other another
-            [chat model](https://docs.langchain.com/oss/python/integrations/chat)).
+        model: The language model for the agent.
+
+            Can be a string identifier (e.g., `"openai:gpt-4"`) or a direct chat model
+            instance (e.g., [`ChatOpenAI`][langchain_openai.ChatOpenAI] or other another
+            [LangChain chat model](https://docs.langchain.com/oss/python/integrations/chat)).
 
             For a full list of supported model strings, see
             [`init_chat_model`][langchain.chat_models.init_chat_model(model_provider)].
-        tools: A list of tools, `dicts`, or `Callable`.
+
+            !!! tip ""
+
+                See the [Models](https://docs.langchain.com/oss/python/langchain/models)
+                docs for more information.
+        tools: A list of tools, `dict`, or `Callable`.
 
             If `None` or an empty list, the agent will consist of a model node without a
             tool calling loop.
+
+
+            !!! tip ""
+
+                See the [Tools](https://docs.langchain.com/oss/python/langchain/tools)
+                docs for more information.
         system_prompt: An optional system prompt for the LLM.
 
-            Prompts are converted to a
-            [`SystemMessage`][langchain.messages.SystemMessage] and added to the
-            beginning of the message list.
+            Can be a `str` (which will be converted to a `SystemMessage`) or a
+            `SystemMessage` instance directly. The system message is added to the
+            beginning of the message list when calling the model.
         middleware: A sequence of middleware instances to apply to the agent.
 
-            Middleware can intercept and modify agent behavior at various stages. See
-            the [full guide](https://docs.langchain.com/oss/python/langchain/middleware).
+            Middleware can intercept and modify agent behavior at various stages.
+
+            !!! tip ""
+
+                See the [Middleware](https://docs.langchain.com/oss/python/langchain/middleware)
+                docs for more information.
         response_format: An optional configuration for structured responses.
 
             Can be a `ToolStrategy`, `ProviderStrategy`, or a Pydantic model class.
 
             If provided, the agent will handle structured output during the
-            conversation flow. Raw schemas will be wrapped in an appropriate strategy
-            based on model capabilities.
+            conversation flow.
+
+            Raw schemas will be wrapped in an appropriate strategy based on model
+            capabilities.
+
+            !!! tip ""
+
+                See the [Structured output](https://docs.langchain.com/oss/python/langchain/structured-output)
+                docs for more information.
         state_schema: An optional `TypedDict` schema that extends `AgentState`.
 
             When provided, this schema is used instead of `AgentState` as the base
             schema for merging with middleware state schemas. This allows users to
             add custom state fields without needing to create custom middleware.
+
             Generally, it's recommended to use `state_schema` extensions via middleware
             to keep relevant extensions scoped to corresponding hooks / tools.
-
-            The schema must be a subclass of `AgentState[ResponseT]`.
         context_schema: An optional schema for runtime context.
         checkpointer: An optional checkpoint saver object.
 
@@ -637,6 +685,14 @@ def create_agent(  # noqa: PLR0915
     if isinstance(model, str):
         model = init_chat_model(model)
 
+    # Convert system_prompt to SystemMessage if needed
+    system_message: SystemMessage | None = None
+    if system_prompt is not None:
+        if isinstance(system_prompt, SystemMessage):
+            system_message = system_prompt
+        else:
+            system_message = SystemMessage(content=system_prompt)
+
     # Handle tools being None or empty
     if tools is None:
         tools = []
@@ -735,9 +791,9 @@ def create_agent(  # noqa: PLR0915
         default_tools = list(built_in_tools)
 
     # validate middleware
-    assert len({m.name for m in middleware}) == len(middleware), (  # noqa: S101
-        "Please remove duplicate middleware instances."
-    )
+    if len({m.name for m in middleware}) != len(middleware):
+        msg = "Please remove duplicate middleware instances."
+        raise AssertionError(msg)
     middleware_w_before_agent = [
         m
         for m in middleware
@@ -830,12 +886,12 @@ def create_agent(  # noqa: PLR0915
                 )
                 try:
                     structured_response = provider_strategy_binding.parse(output)
-                except Exception as exc:  # noqa: BLE001
+                except Exception as exc:
                     schema_name = getattr(
                         effective_response_format.schema_spec.schema, "__name__", "response_format"
                     )
                     validation_error = StructuredOutputValidationError(schema_name, exc, output)
-                    raise validation_error
+                    raise validation_error from exc
                 else:
                     return {"messages": [output], "structured_response": structured_response}
             return {"messages": [output]}
@@ -881,8 +937,7 @@ def create_agent(  # noqa: PLR0915
 
                     tool_message_content = (
                         effective_response_format.tool_message_content
-                        if effective_response_format.tool_message_content
-                        else f"Returning structured response: {structured_response}"
+                        or f"Returning structured response: {structured_response}"
                     )
 
                     return {
@@ -896,13 +951,13 @@ def create_agent(  # noqa: PLR0915
                         ],
                         "structured_response": structured_response,
                     }
-                except Exception as exc:  # noqa: BLE001
+                except Exception as exc:
                     exception = StructuredOutputValidationError(tool_call["name"], exc, output)
                     should_retry, error_message = _handle_structured_output_error(
                         exception, effective_response_format
                     )
                     if not should_retry:
-                        raise exception
+                        raise exception from exc
 
                     return {
                         "messages": [
@@ -966,7 +1021,7 @@ def create_agent(  # noqa: PLR0915
         effective_response_format: ResponseFormat | None
         if isinstance(request.response_format, AutoStrategy):
             # User provided raw schema via AutoStrategy - auto-detect best strategy based on model
-            if _supports_provider_strategy(request.model):
+            if _supports_provider_strategy(request.model, tools=request.tools):
                 # Model supports provider strategy - use it
                 effective_response_format = ProviderStrategy(schema=request.response_format.schema)
             else:
@@ -987,7 +1042,7 @@ def create_agent(  # noqa: PLR0915
 
         # Bind model based on effective response format
         if isinstance(effective_response_format, ProviderStrategy):
-            # Use provider-specific structured output
+            # (Backward compatibility) Use OpenAI format structured output
             kwargs = effective_response_format.to_model_kwargs()
             return (
                 request.model.bind_tools(
@@ -1040,10 +1095,12 @@ def create_agent(  # noqa: PLR0915
         # Get the bound model (with auto-detection if needed)
         model_, effective_response_format = _get_bound_model(request)
         messages = request.messages
-        if request.system_prompt:
-            messages = [SystemMessage(request.system_prompt), *messages]
+        if request.system_message:
+            messages = [request.system_message, *messages]
 
         output = model_.invoke(messages)
+        if name:
+            output.name = name
 
         # Handle model output to get messages and structured_response
         handled_output = _handle_model_output(output, effective_response_format)
@@ -1060,7 +1117,7 @@ def create_agent(  # noqa: PLR0915
         request = ModelRequest(
             model=model,
             tools=default_tools,
-            system_prompt=system_prompt,
+            system_message=system_message,
             response_format=initial_response_format,
             messages=state["messages"],
             tool_choice=None,
@@ -1093,10 +1150,12 @@ def create_agent(  # noqa: PLR0915
         # Get the bound model (with auto-detection if needed)
         model_, effective_response_format = _get_bound_model(request)
         messages = request.messages
-        if request.system_prompt:
-            messages = [SystemMessage(request.system_prompt), *messages]
+        if request.system_message:
+            messages = [request.system_message, *messages]
 
         output = await model_.ainvoke(messages)
+        if name:
+            output.name = name
 
         # Handle model output to get messages and structured_response
         handled_output = _handle_model_output(output, effective_response_format)
@@ -1113,7 +1172,7 @@ def create_agent(  # noqa: PLR0915
         request = ModelRequest(
             model=model,
             tools=default_tools,
-            system_prompt=system_prompt,
+            system_message=system_message,
             response_format=initial_response_format,
             messages=state["messages"],
             tool_choice=None,
@@ -1420,7 +1479,7 @@ def create_agent(  # noqa: PLR0915
         debug=debug,
         name=name,
         cache=cache,
-    )
+    ).with_config({"recursion_limit": 10_000})
 
 
 def _resolve_jump(

langchain/agents/middleware/__init__.py

@@ -1,21 +1,17 @@
-"""Entrypoint to using [Middleware](https://docs.langchain.com/oss/python/langchain/middleware) plugins with [Agents](https://docs.langchain.com/oss/python/langchain/agents).
-
-!!! warning "Reference docs"
-    This page contains **reference documentation** for Middleware. See
-    [the docs](https://docs.langchain.com/oss/python/langchain/middleware) for conceptual
-    guides, tutorials, and examples on using Middleware.
-"""  # noqa: E501
+"""Entrypoint to using [middleware](https://docs.langchain.com/oss/python/langchain/middleware) plugins with [Agents](https://docs.langchain.com/oss/python/langchain/agents)."""  # noqa: E501
 
 from .context_editing import (
     ClearToolUsesEdit,
     ContextEditingMiddleware,
 )
+from .file_search import FilesystemFileSearchMiddleware
 from .human_in_the_loop import (
     HumanInTheLoopMiddleware,
     InterruptOnConfig,
 )
 from .model_call_limit import ModelCallLimitMiddleware
 from .model_fallback import ModelFallbackMiddleware
+from .model_retry import ModelRetryMiddleware
 from .pii import PIIDetectionError, PIIMiddleware
 from .shell_tool import (
     CodexSandboxExecutionPolicy,
@@ -52,6 +48,7 @@ __all__ = [
     "CodexSandboxExecutionPolicy",
     "ContextEditingMiddleware",
     "DockerExecutionPolicy",
+    "FilesystemFileSearchMiddleware",
     "HostExecutionPolicy",
     "HumanInTheLoopMiddleware",
     "InterruptOnConfig",
@@ -61,6 +58,7 @@ __all__ = [
     "ModelFallbackMiddleware",
     "ModelRequest",
     "ModelResponse",
+    "ModelRetryMiddleware",
     "PIIDetectionError",
     "PIIMiddleware",
     "RedactionRule",

langchain/agents/middleware/_execution.py

@@ -56,11 +56,12 @@ class BaseExecutionPolicy(abc.ABC):
     """Configuration contract for persistent shell sessions.
 
     Concrete subclasses encapsulate how a shell process is launched and constrained.
+
     Each policy documents its security guarantees and the operating environments in
-    which it is appropriate. Use :class:`HostExecutionPolicy` for trusted, same-host
-    execution; :class:`CodexSandboxExecutionPolicy` when the Codex CLI sandbox is
-    available and you want additional syscall restrictions; and
-    :class:`DockerExecutionPolicy` for container-level isolation using Docker.
+    which it is appropriate. Use `HostExecutionPolicy` for trusted, same-host execution;
+    `CodexSandboxExecutionPolicy` when the Codex CLI sandbox is available and you want
+    additional syscall restrictions; and `DockerExecutionPolicy` for container-level
+    isolation using Docker.
     """
 
     command_timeout: float = 30.0
@@ -91,13 +92,13 @@ class HostExecutionPolicy(BaseExecutionPolicy):
 
     This policy is best suited for trusted or single-tenant environments (CI jobs,
     developer workstations, pre-sandboxed containers) where the agent must access the
-    host filesystem and tooling without additional isolation. It enforces optional CPU
-    and memory limits to prevent runaway commands but offers **no** filesystem or network
+    host filesystem and tooling without additional isolation. Enforces optional CPU and
+    memory limits to prevent runaway commands but offers **no** filesystem or network
     sandboxing; commands can modify anything the process user can reach.
 
-    On Linux platforms resource limits are applied with ``resource.prlimit`` after the
-    shell starts. On macOS, where ``prlimit`` is unavailable, limits are set in a
-    ``preexec_fn`` before ``exec``. In both cases the shell runs in its own process group
+    On Linux platforms resource limits are applied with `resource.prlimit` after the
+    shell starts. On macOS, where `prlimit` is unavailable, limits are set in a
+    `preexec_fn` before `exec`. In both cases the shell runs in its own process group
     so timeouts can terminate the full subtree.
     """
 
@@ -199,9 +200,9 @@ class CodexSandboxExecutionPolicy(BaseExecutionPolicy):
     (Linux) profiles. Commands still run on the host, but within the sandbox requested by
     the CLI. If the Codex binary is unavailable or the runtime lacks the required
     kernel features (e.g., Landlock inside some containers), process startup fails with a
-    :class:`RuntimeError`.
+    `RuntimeError`.
 
-    Configure sandbox behaviour via ``config_overrides`` to align with your Codex CLI
+    Configure sandbox behavior via `config_overrides` to align with your Codex CLI
     profile. This policy does not add its own resource limits; combine it with
     host-level guards (cgroups, container resource limits) as needed.
     """
@@ -271,17 +272,17 @@ class DockerExecutionPolicy(BaseExecutionPolicy):
     """Run the shell inside a dedicated Docker container.
 
     Choose this policy when commands originate from untrusted users or you require
-    strong isolation between sessions. By default the workspace is bind-mounted only when
-    it refers to an existing non-temporary directory; ephemeral sessions run without a
-    mount to minimise host exposure. The container's network namespace is disabled by
-    default (``--network none``) and you can enable further hardening via
-    ``read_only_rootfs`` and ``user``.
+    strong isolation between sessions. By default the workspace is bind-mounted only
+    when it refers to an existing non-temporary directory; ephemeral sessions run
+    without a mount to minimise host exposure. The container's network namespace is
+    disabled by default (`--network none`) and you can enable further hardening via
+    `read_only_rootfs` and `user`.
 
     The security guarantees depend on your Docker daemon configuration. Run the agent on
-    a host where Docker is locked down (rootless mode, AppArmor/SELinux, etc.) and review
-    any additional volumes or capabilities passed through ``extra_run_args``. The default
-    image is ``python:3.12-alpine3.19``; supply a custom image if you need preinstalled
-    tooling.
+    a host where Docker is locked down (rootless mode, AppArmor/SELinux, etc.) and
+    review any additional volumes or capabilities passed through ``extra_run_args``. The
+    default image is `python:3.12-alpine3.19`; supply a custom image if you need
+    preinstalled tooling.
     """
 
     binary: str = "docker"

langchain/agents/middleware/_redaction.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import ipaddress
+import operator
 import re
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
@@ -127,7 +128,7 @@ def detect_url(content: str) -> list[PIIMatch]:
     for match in re.finditer(scheme_pattern, content):
         url = match.group()
         result = urlparse(url)
-        if result.scheme in ("http", "https") and result.netloc:
+        if result.scheme in {"http", "https"} and result.netloc:
             matches.append(
                 PIIMatch(
                     type="url",
@@ -179,11 +180,14 @@ BUILTIN_DETECTORS: dict[str, Detector] = {
 }
 """Registry of built-in detectors keyed by type name."""
 
+_CARD_NUMBER_MIN_DIGITS = 13
+_CARD_NUMBER_MAX_DIGITS = 19
+
 
 def _passes_luhn(card_number: str) -> bool:
     """Validate credit card number using the Luhn checksum."""
     digits = [int(d) for d in card_number if d.isdigit()]
-    if not 13 <= len(digits) <= 19:
+    if not _CARD_NUMBER_MIN_DIGITS <= len(digits) <= _CARD_NUMBER_MAX_DIGITS:
         return False
 
     checksum = 0
@@ -191,7 +195,7 @@ def _passes_luhn(card_number: str) -> bool:
         value = digit
         if index % 2 == 1:
             value *= 2
-            if value > 9:
+            if value > 9:  # noqa: PLR2004
                 value -= 9
         checksum += value
     return checksum % 10 == 0
@@ -199,24 +203,28 @@ def _passes_luhn(card_number: str) -> bool:
 
 def _apply_redact_strategy(content: str, matches: list[PIIMatch]) -> str:
     result = content
-    for match in sorted(matches, key=lambda item: item["start"], reverse=True):
+    for match in sorted(matches, key=operator.itemgetter("start"), reverse=True):
         replacement = f"[REDACTED_{match['type'].upper()}]"
         result = result[: match["start"]] + replacement + result[match["end"] :]
     return result
 
 
+_UNMASKED_CHAR_NUMBER = 4
+_IPV4_PARTS_NUMBER = 4
+
+
 def _apply_mask_strategy(content: str, matches: list[PIIMatch]) -> str:
     result = content
-    for match in sorted(matches, key=lambda item: item["start"], reverse=True):
+    for match in sorted(matches, key=operator.itemgetter("start"), reverse=True):
         value = match["value"]
         pii_type = match["type"]
         if pii_type == "email":
             parts = value.split("@")
-            if len(parts) == 2:
+            if len(parts) == 2:  # noqa: PLR2004
                 domain_parts = parts[1].split(".")
                 masked = (
                     f"{parts[0]}@****.{domain_parts[-1]}"
-                    if len(domain_parts) >= 2
+                    if len(domain_parts) > 1
                     else f"{parts[0]}@****"
                 )
             else:
@@ -225,12 +233,15 @@ def _apply_mask_strategy(content: str, matches: list[PIIMatch]) -> str:
             digits_only = "".join(c for c in value if c.isdigit())
             separator = "-" if "-" in value else " " if " " in value else ""
             if separator:
-                masked = f"****{separator}****{separator}****{separator}{digits_only[-4:]}"
+                masked = (
+                    f"****{separator}****{separator}****{separator}"
+                    f"{digits_only[-_UNMASKED_CHAR_NUMBER:]}"
+                )
             else:
-                masked = f"************{digits_only[-4:]}"
+                masked = f"************{digits_only[-_UNMASKED_CHAR_NUMBER:]}"
         elif pii_type == "ip":
             octets = value.split(".")
-            masked = f"*.*.*.{octets[-1]}" if len(octets) == 4 else "****"
+            masked = f"*.*.*.{octets[-1]}" if len(octets) == _IPV4_PARTS_NUMBER else "****"
         elif pii_type == "mac_address":
             separator = ":" if ":" in value else "-"
             masked = (
@@ -239,14 +250,18 @@ def _apply_mask_strategy(content: str, matches: list[PIIMatch]) -> str:
         elif pii_type == "url":
             masked = "[MASKED_URL]"
         else:
-            masked = f"****{value[-4:]}" if len(value) > 4 else "****"
+            masked = (
+                f"****{value[-_UNMASKED_CHAR_NUMBER:]}"
+                if len(value) > _UNMASKED_CHAR_NUMBER
+                else "****"
+            )
         result = result[: match["start"]] + masked + result[match["end"] :]
     return result
 
 
 def _apply_hash_strategy(content: str, matches: list[PIIMatch]) -> str:
     result = content
-    for match in sorted(matches, key=lambda item: item["start"], reverse=True):
+    for match in sorted(matches, key=operator.itemgetter("start"), reverse=True):
         digest = hashlib.sha256(match["value"].encode()).hexdigest()[:8]
         replacement = f"<{match['type']}_hash:{digest}>"
         result = result[: match["start"]] + replacement + result[match["end"] :]