langchain-core 1.0.7__py3-none-any.whl → 1.2.1__py3-none-any.whl

langchain_core/runnables/base.py

@@ -94,7 +94,7 @@ from langchain_core.tracers.root_listeners import (
     AsyncRootListenersTracer,
     RootListenersTracer,
 )
-from langchain_core.utils.aiter import aclosing, atee, py_anext
+from langchain_core.utils.aiter import aclosing, atee
 from langchain_core.utils.iter import safetee
 from langchain_core.utils.pydantic import create_model_v2
 
@@ -127,10 +127,10 @@ class Runnable(ABC, Generic[Input, Output]):
     Key Methods
     ===========
 
-    - **`invoke`/`ainvoke`**: Transforms a single input into an output.
-    - **`batch`/`abatch`**: Efficiently transforms multiple inputs into outputs.
-    - **`stream`/`astream`**: Streams output from a single input as it's produced.
-    - **`astream_log`**: Streams output and selected intermediate results from an
+    - `invoke`/`ainvoke`: Transforms a single input into an output.
+    - `batch`/`abatch`: Efficiently transforms multiple inputs into outputs.
+    - `stream`/`astream`: Streams output from a single input as it's produced.
+    - `astream_log`: Streams output and selected intermediate results from an
         input.
 
     Built-in optimizations:
@@ -707,51 +707,53 @@ class Runnable(ABC, Generic[Input, Output]):
     def pick(self, keys: str | list[str]) -> RunnableSerializable[Any, Any]:
         """Pick keys from the output `dict` of this `Runnable`.
 
-        Pick a single key:
+        !!! example "Pick a single key"
 
-        ```python
-        import json
+            ```python
+            import json
 
-        from langchain_core.runnables import RunnableLambda, RunnableMap
+            from langchain_core.runnables import RunnableLambda, RunnableMap
 
-        as_str = RunnableLambda(str)
-        as_json = RunnableLambda(json.loads)
-        chain = RunnableMap(str=as_str, json=as_json)
+            as_str = RunnableLambda(str)
+            as_json = RunnableLambda(json.loads)
+            chain = RunnableMap(str=as_str, json=as_json)
 
-        chain.invoke("[1, 2, 3]")
-        # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]}
+            chain.invoke("[1, 2, 3]")
+            # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]}
 
-        json_only_chain = chain.pick("json")
-        json_only_chain.invoke("[1, 2, 3]")
-        # -> [1, 2, 3]
-        ```
+            json_only_chain = chain.pick("json")
+            json_only_chain.invoke("[1, 2, 3]")
+            # -> [1, 2, 3]
+            ```
 
-        Pick a list of keys:
+        !!! example "Pick a list of keys"
 
-        ```python
-        from typing import Any
+            ```python
+            from typing import Any
 
-        import json
+            import json
 
-        from langchain_core.runnables import RunnableLambda, RunnableMap
+            from langchain_core.runnables import RunnableLambda, RunnableMap
 
-        as_str = RunnableLambda(str)
-        as_json = RunnableLambda(json.loads)
+            as_str = RunnableLambda(str)
+            as_json = RunnableLambda(json.loads)
 
 
-        def as_bytes(x: Any) -> bytes:
-            return bytes(x, "utf-8")
+            def as_bytes(x: Any) -> bytes:
+                return bytes(x, "utf-8")
 
 
-        chain = RunnableMap(str=as_str, json=as_json, bytes=RunnableLambda(as_bytes))
+            chain = RunnableMap(
+                str=as_str, json=as_json, bytes=RunnableLambda(as_bytes)
+            )
 
-        chain.invoke("[1, 2, 3]")
-        # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"}
+            chain.invoke("[1, 2, 3]")
+            # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"}
 
-        json_and_bytes_chain = chain.pick(["json", "bytes"])
-        json_and_bytes_chain.invoke("[1, 2, 3]")
-        # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"}
-        ```
+            json_and_bytes_chain = chain.pick(["json", "bytes"])
+            json_and_bytes_chain.invoke("[1, 2, 3]")
+            # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"}
+            ```
 
         Args:
             keys: A key or list of keys to pick from the output dict.
@@ -1372,48 +1374,50 @@ class Runnable(ABC, Generic[Input, Output]):
         ).with_config({"run_name": "my_template", "tags": ["my_template"]})
         ```
 
-        For instance:
+        !!! example
 
-        ```python
-        from langchain_core.runnables import RunnableLambda
+            ```python
+            from langchain_core.runnables import RunnableLambda
 
 
-        async def reverse(s: str) -> str:
-            return s[::-1]
+            async def reverse(s: str) -> str:
+                return s[::-1]
 
 
-        chain = RunnableLambda(func=reverse)
+            chain = RunnableLambda(func=reverse)
 
-        events = [event async for event in chain.astream_events("hello", version="v2")]
+            events = [
+                event async for event in chain.astream_events("hello", version="v2")
+            ]
 
-        # Will produce the following events
-        # (run_id, and parent_ids has been omitted for brevity):
-        [
-            {
-                "data": {"input": "hello"},
-                "event": "on_chain_start",
-                "metadata": {},
-                "name": "reverse",
-                "tags": [],
-            },
-            {
-                "data": {"chunk": "olleh"},
-                "event": "on_chain_stream",
-                "metadata": {},
-                "name": "reverse",
-                "tags": [],
-            },
-            {
-                "data": {"output": "olleh"},
-                "event": "on_chain_end",
-                "metadata": {},
-                "name": "reverse",
-                "tags": [],
-            },
-        ]
-        ```
+            # Will produce the following events
+            # (run_id, and parent_ids has been omitted for brevity):
+            [
+                {
+                    "data": {"input": "hello"},
+                    "event": "on_chain_start",
+                    "metadata": {},
+                    "name": "reverse",
+                    "tags": [],
+                },
+                {
+                    "data": {"chunk": "olleh"},
+                    "event": "on_chain_stream",
+                    "metadata": {},
+                    "name": "reverse",
+                    "tags": [],
+                },
+                {
+                    "data": {"output": "olleh"},
+                    "event": "on_chain_end",
+                    "metadata": {},
+                    "name": "reverse",
+                    "tags": [],
+                },
+            ]
+            ```
 
-        ```python title="Example: Dispatch Custom Event"
+        ```python title="Dispatch custom event"
         from langchain_core.callbacks.manager import (
             adispatch_custom_event,
         )
@@ -1447,10 +1451,13 @@ class Runnable(ABC, Generic[Input, Output]):
         Args:
             input: The input to the `Runnable`.
             config: The config to use for the `Runnable`.
-            version: The version of the schema to use either `'v2'` or `'v1'`.
+            version: The version of the schema to use, either `'v2'` or `'v1'`.
+
                 Users should use `'v2'`.
+
                 `'v1'` is for backwards compatibility and will be deprecated
                 in `0.4.0`.
+
                 No default will be assigned until the API is stabilized.
                 custom events will only be surfaced in `'v2'`.
             include_names: Only include events from `Runnable` objects with matching names.
@@ -1460,6 +1467,7 @@ class Runnable(ABC, Generic[Input, Output]):
             exclude_types: Exclude events from `Runnable` objects with matching types.
             exclude_tags: Exclude events from `Runnable` objects with matching tags.
             **kwargs: Additional keyword arguments to pass to the `Runnable`.
+
                 These will be passed to `astream_log` as this implementation
                 of `astream_events` is built on top of `astream_log`.
 
@@ -2369,7 +2377,7 @@ class Runnable(ABC, Generic[Input, Output]):
         # tee the input so we can iterate over it twice
         input_for_tracing, input_for_transform = atee(inputs, 2)
         # Start the input iterator to ensure the input Runnable starts before this one
-        final_input: Input | None = await py_anext(input_for_tracing, None)
+        final_input: Input | None = await anext(input_for_tracing, None)
         final_input_supported = True
         final_output: Output | None = None
         final_output_supported = True
@@ -2409,7 +2417,7 @@ class Runnable(ABC, Generic[Input, Output]):
                     iterator = iterator_
                 try:
                     while True:
-                        chunk = await coro_with_context(py_anext(iterator), context)
+                        chunk = await coro_with_context(anext(iterator), context)
                         yield chunk
                         if final_output_supported:
                             if final_output is None:
@@ -2476,82 +2484,82 @@ class Runnable(ABC, Generic[Input, Output]):
         Returns:
             A `BaseTool` instance.
 
-        Typed dict input:
+        !!! example "`TypedDict` input"
 
-        ```python
-        from typing_extensions import TypedDict
-        from langchain_core.runnables import RunnableLambda
+            ```python
+            from typing_extensions import TypedDict
+            from langchain_core.runnables import RunnableLambda
 
 
-        class Args(TypedDict):
-            a: int
-            b: list[int]
+            class Args(TypedDict):
+                a: int
+                b: list[int]
 
 
-        def f(x: Args) -> str:
-            return str(x["a"] * max(x["b"]))
+            def f(x: Args) -> str:
+                return str(x["a"] * max(x["b"]))
 
 
-        runnable = RunnableLambda(f)
-        as_tool = runnable.as_tool()
-        as_tool.invoke({"a": 3, "b": [1, 2]})
-        ```
+            runnable = RunnableLambda(f)
+            as_tool = runnable.as_tool()
+            as_tool.invoke({"a": 3, "b": [1, 2]})
+            ```
 
-        `dict` input, specifying schema via `args_schema`:
+        !!! example "`dict` input, specifying schema via `args_schema`"
 
-        ```python
-        from typing import Any
-        from pydantic import BaseModel, Field
-        from langchain_core.runnables import RunnableLambda
+            ```python
+            from typing import Any
+            from pydantic import BaseModel, Field
+            from langchain_core.runnables import RunnableLambda
 
-        def f(x: dict[str, Any]) -> str:
-            return str(x["a"] * max(x["b"]))
+            def f(x: dict[str, Any]) -> str:
+                return str(x["a"] * max(x["b"]))
 
-        class FSchema(BaseModel):
-            \"\"\"Apply a function to an integer and list of integers.\"\"\"
+            class FSchema(BaseModel):
+                \"\"\"Apply a function to an integer and list of integers.\"\"\"
 
-            a: int = Field(..., description="Integer")
-            b: list[int] = Field(..., description="List of ints")
+                a: int = Field(..., description="Integer")
+                b: list[int] = Field(..., description="List of ints")
 
-        runnable = RunnableLambda(f)
-        as_tool = runnable.as_tool(FSchema)
-        as_tool.invoke({"a": 3, "b": [1, 2]})
-        ```
+            runnable = RunnableLambda(f)
+            as_tool = runnable.as_tool(FSchema)
+            as_tool.invoke({"a": 3, "b": [1, 2]})
+            ```
 
-        `dict` input, specifying schema via `arg_types`:
+        !!! example "`dict` input, specifying schema via `arg_types`"
 
-        ```python
-        from typing import Any
-        from langchain_core.runnables import RunnableLambda
+            ```python
+            from typing import Any
+            from langchain_core.runnables import RunnableLambda
 
 
-        def f(x: dict[str, Any]) -> str:
-            return str(x["a"] * max(x["b"]))
+            def f(x: dict[str, Any]) -> str:
+                return str(x["a"] * max(x["b"]))
 
 
-        runnable = RunnableLambda(f)
-        as_tool = runnable.as_tool(arg_types={"a": int, "b": list[int]})
-        as_tool.invoke({"a": 3, "b": [1, 2]})
-        ```
+            runnable = RunnableLambda(f)
+            as_tool = runnable.as_tool(arg_types={"a": int, "b": list[int]})
+            as_tool.invoke({"a": 3, "b": [1, 2]})
+            ```
 
-        `str` input:
+        !!! example "`str` input"
 
-        ```python
-        from langchain_core.runnables import RunnableLambda
+            ```python
+            from langchain_core.runnables import RunnableLambda
 
 
-        def f(x: str) -> str:
-            return x + "a"
+            def f(x: str) -> str:
+                return x + "a"
 
 
-        def g(x: str) -> str:
-            return x + "z"
+            def g(x: str) -> str:
+                return x + "z"
 
 
-        runnable = RunnableLambda(f) | g
-        as_tool = runnable.as_tool()
-        as_tool.invoke("b")
-        ```
+            runnable = RunnableLambda(f) | g
+            as_tool = runnable.as_tool()
+            as_tool.invoke("b")
+            ```
         """
         # Avoid circular import
         from langchain_core.tools import convert_runnable_to_tool  # noqa: PLC0415
@@ -2603,29 +2611,33 @@ class RunnableSerializable(Serializable, Runnable[Input, Output]):
         Returns:
             A new `Runnable` with the fields configured.
 
-        ```python
-        from langchain_core.runnables import ConfigurableField
-        from langchain_openai import ChatOpenAI
+        !!! example
 
-        model = ChatOpenAI(max_tokens=20).configurable_fields(
-            max_tokens=ConfigurableField(
-                id="output_token_number",
-                name="Max tokens in the output",
-                description="The maximum number of tokens in the output",
+            ```python
+            from langchain_core.runnables import ConfigurableField
+            from langchain_openai import ChatOpenAI
+
+            model = ChatOpenAI(max_tokens=20).configurable_fields(
+                max_tokens=ConfigurableField(
+                    id="output_token_number",
+                    name="Max tokens in the output",
+                    description="The maximum number of tokens in the output",
+                )
             )
-        )
 
-        # max_tokens = 20
-        print("max_tokens_20: ", model.invoke("tell me something about chess").content)
+            # max_tokens = 20
+            print(
+                "max_tokens_20: ", model.invoke("tell me something about chess").content
+            )
 
-        # max_tokens = 200
-        print(
-            "max_tokens_200: ",
-            model.with_config(configurable={"output_token_number": 200})
-            .invoke("tell me something about chess")
-            .content,
-        )
-        ```
+            # max_tokens = 200
+            print(
+                "max_tokens_200: ",
+                model.with_config(configurable={"output_token_number": 200})
+                .invoke("tell me something about chess")
+                .content,
+            )
+            ```
         """
         # Import locally to prevent circular import
         from langchain_core.runnables.configurable import (  # noqa: PLC0415
@@ -2664,29 +2676,31 @@ class RunnableSerializable(Serializable, Runnable[Input, Output]):
         Returns:
             A new `Runnable` with the alternatives configured.
 
-        ```python
-        from langchain_anthropic import ChatAnthropic
-        from langchain_core.runnables.utils import ConfigurableField
-        from langchain_openai import ChatOpenAI
+        !!! example
 
-        model = ChatAnthropic(
-            model_name="claude-sonnet-4-5-20250929"
-        ).configurable_alternatives(
-            ConfigurableField(id="llm"),
-            default_key="anthropic",
-            openai=ChatOpenAI(),
-        )
+            ```python
+            from langchain_anthropic import ChatAnthropic
+            from langchain_core.runnables.utils import ConfigurableField
+            from langchain_openai import ChatOpenAI
+
+            model = ChatAnthropic(
+                model_name="claude-sonnet-4-5-20250929"
+            ).configurable_alternatives(
+                ConfigurableField(id="llm"),
+                default_key="anthropic",
+                openai=ChatOpenAI(),
+            )
 
-        # uses the default model ChatAnthropic
-        print(model.invoke("which organization created you?").content)
+            # uses the default model ChatAnthropic
+            print(model.invoke("which organization created you?").content)
 
-        # uses ChatOpenAI
-        print(
-            model.with_config(configurable={"llm": "openai"})
-            .invoke("which organization created you?")
-            .content
-        )
-        ```
+            # uses ChatOpenAI
+            print(
+                model.with_config(configurable={"llm": "openai"})
+                .invoke("which organization created you?")
+                .content
+            )
+            ```
         """
         # Import locally to prevent circular import
         from langchain_core.runnables.configurable import (  # noqa: PLC0415
@@ -4011,7 +4025,7 @@ class RunnableParallel(RunnableSerializable[Input, dict[str, Any]]):
 
         # Wrap in a coroutine to satisfy linter
         async def get_next_chunk(generator: AsyncIterator) -> Output | None:
-            return await py_anext(generator)
+            return await anext(generator)
 
         # Start the first iteration of each generator
         tasks = {

langchain_core/runnables/branch.py

@@ -303,7 +303,7 @@ class RunnableBranch(RunnableSerializable[Input, Output]):
 
         Args:
             input: The input to the `Runnable`.
-            config: The configuration for the Runna`ble.
+            config: The configuration for the `Runnable`.
             **kwargs: Additional keyword arguments to pass to the `Runnable`.
 
         Yields:

langchain_core/runnables/config.py

@@ -47,54 +47,59 @@ class EmptyDict(TypedDict, total=False):
 
 
 class RunnableConfig(TypedDict, total=False):
-    """Configuration for a Runnable."""
+    """Configuration for a `Runnable`.
 
-    tags: list[str]
+    See the [reference docs](https://reference.langchain.com/python/langchain_core/runnables/#langchain_core.runnables.RunnableConfig)
+    for more details.
     """
-    Tags for this call and any sub-calls (eg. a Chain calling an LLM).
+
+    tags: list[str]
+    """Tags for this call and any sub-calls (e.g. a Chain calling an LLM).
+
     You can use these to filter calls.
     """
 
     metadata: dict[str, Any]
-    """
-    Metadata for this call and any sub-calls (eg. a Chain calling an LLM).
+    """Metadata for this call and any sub-calls (e.g. a Chain calling an LLM).
+
     Keys should be strings, values should be JSON-serializable.
     """
 
     callbacks: Callbacks
-    """
-    Callbacks for this call and any sub-calls (eg. a Chain calling an LLM).
+    """Callbacks for this call and any sub-calls (e.g. a Chain calling an LLM).
+
     Tags are passed to all callbacks, metadata is passed to handle*Start callbacks.
     """
 
     run_name: str
-    """
-    Name for the tracer run for this call. Defaults to the name of the class.
-    """
+    """Name for the tracer run for this call.
+
+    Defaults to the name of the class."""
 
     max_concurrency: int | None
-    """
-    Maximum number of parallel calls to make. If not provided, defaults to
-    `ThreadPoolExecutor`'s default.
+    """Maximum number of parallel calls to make.
+
+    If not provided, defaults to `ThreadPoolExecutor`'s default.
     """
 
     recursion_limit: int
-    """
-    Maximum number of times a call can recurse. If not provided, defaults to `25`.
+    """Maximum number of times a call can recurse.
+
+    If not provided, defaults to `25`.
     """
 
     configurable: dict[str, Any]
-    """
-    Runtime values for attributes previously made configurable on this `Runnable`,
+    """Runtime values for attributes previously made configurable on this `Runnable`,
     or sub-Runnables, through `configurable_fields` or `configurable_alternatives`.
+
     Check `output_schema` for a description of the attributes that have been made
     configurable.
     """
 
     run_id: uuid.UUID | None
-    """
-    Unique identifier for the tracer run for this call. If not provided, a new UUID
-    will be generated.
+    """Unique identifier for the tracer run for this call.
+
+    If not provided, a new UUID will be generated.
     """
 
 

langchain_core/runnables/fallbacks.py

@@ -28,7 +28,6 @@ from langchain_core.runnables.utils import (
     coro_with_context,
     get_unique_config_specs,
 )
-from langchain_core.utils.aiter import py_anext
 
 if TYPE_CHECKING:
     from langchain_core.callbacks.manager import AsyncCallbackManagerForChainRun
@@ -563,7 +562,7 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
                         child_config,
                         **kwargs,
                     )
-                    chunk = await coro_with_context(py_anext(stream), context)
+                    chunk = await coro_with_context(anext(stream), context)
             except self.exceptions_to_handle as e:
                 first_error = e if first_error is None else first_error
                 last_error = e

langchain_core/runnables/passthrough.py

@@ -33,7 +33,7 @@ from langchain_core.runnables.utils import (
     AddableDict,
     ConfigurableFieldSpec,
 )
-from langchain_core.utils.aiter import atee, py_anext
+from langchain_core.utils.aiter import atee
 from langchain_core.utils.iter import safetee
 from langchain_core.utils.pydantic import create_model_v2
 
@@ -614,7 +614,7 @@ class RunnableAssign(RunnableSerializable[dict[str, Any], dict[str, Any]]):
         )
         # start map output stream
         first_map_chunk_task: asyncio.Task = asyncio.create_task(
-            py_anext(map_output, None),  # type: ignore[arg-type]
+            anext(map_output, None),
         )
         # consume passthrough stream
         async for chunk in for_passthrough:

langchain_core/tools/base.py

@@ -496,6 +496,24 @@ class ChildTool(BaseTool):
     two-tuple corresponding to the `(content, artifact)` of a `ToolMessage`.
     """
 
+    extras: dict[str, Any] | None = None
+    """Optional provider-specific extra fields for the tool.
+
+    This is used to pass provider-specific configuration that doesn't fit into
+    standard tool fields.
+
+    Example:
+        Anthropic-specific fields like [`cache_control`](https://docs.langchain.com/oss/python/integrations/chat/anthropic#prompt-caching),
+        [`defer_loading`](https://docs.langchain.com/oss/python/integrations/chat/anthropic#tool-search),
+        or `input_examples`.
+
+        ```python
+        @tool(extras={"defer_loading": True, "cache_control": {"type": "ephemeral"}})
+        def my_tool(x: str) -> str:
+            return x
+        ```
+    """
+
     def __init__(self, **kwargs: Any) -> None:
         """Initialize the tool.
 
@@ -696,7 +714,9 @@ class ChildTool(BaseTool):
                 k: getattr(result, k) for k in result_dict if k in tool_input
             }
             for k in self._injected_args_keys:
-                if k == "tool_call_id":
+                if k in tool_input:
+                    validated_input[k] = tool_input[k]
+                elif k == "tool_call_id":
                     if tool_call_id is None:
                         msg = (
                             "When tool includes an InjectedToolCallId "
@@ -707,9 +727,6 @@ class ChildTool(BaseTool):
                         )
                         raise ValueError(msg)
                     validated_input[k] = tool_call_id
-                if k in tool_input:
-                    injected_val = tool_input[k]
-                    validated_input[k] = injected_val
             return validated_input
         return tool_input
 
@@ -878,6 +895,7 @@ class ChildTool(BaseTool):
             name=run_name,
             run_id=run_id,
             inputs=filtered_tool_input,
+            tool_call_id=tool_call_id,
             **kwargs,
         )
 
@@ -1005,6 +1023,7 @@ class ChildTool(BaseTool):
             name=run_name,
             run_id=run_id,
             inputs=filtered_tool_input,
+            tool_call_id=tool_call_id,
             **kwargs,
         )
         content = None