langchain-core 1.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

langchain_core/prompts/structured.py

@@ -104,19 +104,23 @@ class StructuredPrompt(ChatPromptTemplate):
             )
             ```
         Args:
-            messages: sequence of message representations.
+            messages: Sequence of message representations.
+
                 A message can be represented using the following formats:
-                (1) BaseMessagePromptTemplate, (2) BaseMessage, (3) 2-tuple of
-                (message type, template); e.g., ("human", "{user_input}"),
-                (4) 2-tuple of (message class, template), (5) a string which is
-                shorthand for ("human", template); e.g., "{user_input}"
-            schema: a dictionary representation of function call, or a Pydantic model.
+
+                1. `BaseMessagePromptTemplate`
+                2. `BaseMessage`
+                3. 2-tuple of `(message type, template)`; e.g.,
+                    `("human", "{user_input}")`
+                4. 2-tuple of `(message class, template)`
+                5. A string which is shorthand for `("human", template)`; e.g.,
+                    `"{user_input}"`
+            schema: A dictionary representation of function call, or a Pydantic model.
             **kwargs: Any additional kwargs to pass through to
                 `ChatModel.with_structured_output(schema, **kwargs)`.
 
         Returns:
-            a structured prompt template
-
+            A structured prompt template
         """
         return cls(messages, schema, **kwargs)
 

langchain_core/retrievers.py

@@ -50,65 +50,65 @@ class LangSmithRetrieverParams(TypedDict, total=False):
 
 
 class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
-    """Abstract base class for a Document retrieval system.
+    """Abstract base class for a document retrieval system.
 
     A retrieval system is defined as something that can take string queries and return
-    the most 'relevant' Documents from some source.
+    the most 'relevant' documents from some source.
 
     Usage:
 
-    A retriever follows the standard Runnable interface, and should be used
-    via the standard Runnable methods of `invoke`, `ainvoke`, `batch`, `abatch`.
+    A retriever follows the standard `Runnable` interface, and should be used via the
+    standard `Runnable` methods of `invoke`, `ainvoke`, `batch`, `abatch`.
 
     Implementation:
 
-    When implementing a custom retriever, the class should implement
-    the `_get_relevant_documents` method to define the logic for retrieving documents.
+    When implementing a custom retriever, the class should implement the
+    `_get_relevant_documents` method to define the logic for retrieving documents.
 
     Optionally, an async native implementations can be provided by overriding the
     `_aget_relevant_documents` method.
 
-    Example: A retriever that returns the first 5 documents from a list of documents
+    !!! example "Retriever that returns the first 5 documents from a list of documents"
 
-    ```python
-    from langchain_core.documents import Document
-    from langchain_core.retrievers import BaseRetriever
+        ```python
+        from langchain_core.documents import Document
+        from langchain_core.retrievers import BaseRetriever
 
-    class SimpleRetriever(BaseRetriever):
-        docs: list[Document]
-        k: int = 5
+        class SimpleRetriever(BaseRetriever):
+            docs: list[Document]
+            k: int = 5
 
-        def _get_relevant_documents(self, query: str) -> list[Document]:
-            \"\"\"Return the first k documents from the list of documents\"\"\"
-            return self.docs[:self.k]
+            def _get_relevant_documents(self, query: str) -> list[Document]:
+                \"\"\"Return the first k documents from the list of documents\"\"\"
+                return self.docs[:self.k]
 
-        async def _aget_relevant_documents(self, query: str) -> list[Document]:
-            \"\"\"(Optional) async native implementation.\"\"\"
-            return self.docs[:self.k]
-    ```
+            async def _aget_relevant_documents(self, query: str) -> list[Document]:
+                \"\"\"(Optional) async native implementation.\"\"\"
+                return self.docs[:self.k]
+        ```
 
-    Example: A simple retriever based on a scikit-learn vectorizer
+    !!! example "Simple retriever based on a scikit-learn vectorizer"
 
-    ```python
-    from sklearn.metrics.pairwise import cosine_similarity
+        ```python
+        from sklearn.metrics.pairwise import cosine_similarity
 
 
-    class TFIDFRetriever(BaseRetriever, BaseModel):
-        vectorizer: Any
-        docs: list[Document]
-        tfidf_array: Any
-        k: int = 4
+        class TFIDFRetriever(BaseRetriever, BaseModel):
+            vectorizer: Any
+            docs: list[Document]
+            tfidf_array: Any
+            k: int = 4
 
-        class Config:
-            arbitrary_types_allowed = True
+            class Config:
+                arbitrary_types_allowed = True
 
-        def _get_relevant_documents(self, query: str) -> list[Document]:
-            # Ip -- (n_docs,x), Op -- (n_docs,n_Feats)
-            query_vec = self.vectorizer.transform([query])
-            # Op -- (n_docs,1) -- Cosine Sim with each doc
-            results = cosine_similarity(self.tfidf_array, query_vec).reshape((-1,))
-            return [self.docs[i] for i in results.argsort()[-self.k :][::-1]]
-    ```
+            def _get_relevant_documents(self, query: str) -> list[Document]:
+                # Ip -- (n_docs,x), Op -- (n_docs,n_Feats)
+                query_vec = self.vectorizer.transform([query])
+                # Op -- (n_docs,1) -- Cosine Sim with each doc
+                results = cosine_similarity(self.tfidf_array, query_vec).reshape((-1,))
+                return [self.docs[i] for i in results.argsort()[-self.k :][::-1]]
+        ```
     """
 
     model_config = ConfigDict(
@@ -119,15 +119,19 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
     _expects_other_args: bool = False
     tags: list[str] | None = None
     """Optional list of tags associated with the retriever.
+
     These tags will be associated with each call to this retriever,
     and passed as arguments to the handlers defined in `callbacks`.
+
     You can use these to eg identify a specific instance of a retriever with its
     use case.
     """
     metadata: dict[str, Any] | None = None
     """Optional metadata associated with the retriever.
+
     This metadata will be associated with each call to this retriever,
     and passed as arguments to the handlers defined in `callbacks`.
+
     You can use these to eg identify a specific instance of a retriever with its
     use case.
     """

langchain_core/runnables/base.py

@@ -147,11 +147,11 @@ class Runnable(ABC, Generic[Input, Output]):
     the `input_schema` property, the `output_schema` property and `config_schema`
     method.
 
-    LCEL and Composition
-    ====================
+    Composition
+    ===========
+
+    Runnable objects can be composed together to create chains in a declarative way.
 
-    The LangChain Expression Language (LCEL) is a declarative way to compose
-    `Runnable` objectsinto chains.
     Any chain constructed this way will automatically have sync, async, batch, and
     streaming support.
 
@@ -235,21 +235,21 @@ class Runnable(ABC, Generic[Input, Output]):
 
     You can set the global debug flag to True to enable debug output for all chains:
 
-        ```python
-        from langchain_core.globals import set_debug
+    ```python
+    from langchain_core.globals import set_debug
 
-        set_debug(True)
-        ```
+    set_debug(True)
+    ```
 
     Alternatively, you can pass existing or custom callbacks to any given chain:
 
-        ```python
-        from langchain_core.tracers import ConsoleCallbackHandler
+    ```python
+    from langchain_core.tracers import ConsoleCallbackHandler
 
-        chain.invoke(..., config={"callbacks": [ConsoleCallbackHandler()]})
-        ```
+    chain.invoke(..., config={"callbacks": [ConsoleCallbackHandler()]})
+    ```
 
-    For a UI (and much more) checkout [LangSmith](https://docs.smith.langchain.com/).
+    For a UI (and much more) checkout [LangSmith](https://docs.langchain.com/langsmith/home).
 
     """
 
@@ -3500,7 +3500,7 @@ class RunnableParallel(RunnableSerializable[Input, dict[str, Any]]):
 
     Returns a mapping of their outputs.
 
-    `RunnableParallel` is one of the two main composition primitives for the LCEL,
+    `RunnableParallel` is one of the two main composition primitives,
     alongside `RunnableSequence`. It invokes `Runnable`s concurrently, providing the
     same input to each.
 

langchain_core/runnables/configurable.py

@@ -475,11 +475,11 @@ _enums_for_spec_lock = threading.Lock()
 class RunnableConfigurableAlternatives(DynamicRunnable[Input, Output]):
     """Runnable that can be dynamically configured.
 
-    A RunnableConfigurableAlternatives should be initiated using the
+    A `RunnableConfigurableAlternatives` should be initiated using the
     `configurable_alternatives` method of a Runnable or can be
     initiated directly as well.
 
-    Here is an example of using a RunnableConfigurableAlternatives that uses
+    Here is an example of using a `RunnableConfigurableAlternatives` that uses
     alternative prompts to illustrate its functionality:
 
         ```python
@@ -506,7 +506,7 @@ class RunnableConfigurableAlternatives(DynamicRunnable[Input, Output]):
         chain.with_config(configurable={"prompt": "poem"}).invoke({"topic": "bears"})
         ```
 
-    Equivalently, you can initialize RunnableConfigurableAlternatives directly
+    Equivalently, you can initialize `RunnableConfigurableAlternatives` directly
     and use in LCEL in the same way:
 
         ```python

langchain_core/runnables/graph.py

@@ -132,7 +132,7 @@ class Branch(NamedTuple):
     condition: Callable[..., str]
     """A callable that returns a string representation of the condition."""
     ends: dict[str, str] | None
-    """Optional dictionary of end node ids for the branches. """
+    """Optional dictionary of end node IDs for the branches. """
 
 
 class CurveStyle(Enum):
@@ -706,8 +706,10 @@ class Graph:
 def _first_node(graph: Graph, exclude: Sequence[str] = ()) -> Node | None:
     """Find the single node that is not a target of any edge.
 
-    Exclude nodes/sources with ids in the exclude list.
+    Exclude nodes/sources with IDs in the exclude list.
+
     If there is no such node, or there are multiple, return `None`.
+
     When drawing the graph, this node would be the origin.
     """
     targets = {edge.target for edge in graph.edges if edge.source not in exclude}
@@ -722,8 +724,10 @@ def _first_node(graph: Graph, exclude: Sequence[str] = ()) -> Node | None:
 def _last_node(graph: Graph, exclude: Sequence[str] = ()) -> Node | None:
     """Find the single node that is not a source of any edge.
 
-    Exclude nodes/targets with ids in the exclude list.
+    Exclude nodes/targets with IDs in the exclude list.
+
     If there is no such node, or there are multiple, return `None`.
+
     When drawing the graph, this node would be the destination.
     """
     sources = {edge.source for edge in graph.edges if edge.target not in exclude}

langchain_core/tools/base.py

@@ -707,6 +707,35 @@ class ChildTool(BaseTool):
             kwargs["run_manager"] = kwargs["run_manager"].get_sync()
         return await run_in_executor(None, self._run, *args, **kwargs)
 
+    def _filter_injected_args(self, tool_input: dict) -> dict:
+        """Filter out injected tool arguments from the input dictionary.
+
+        Injected arguments are those annotated with InjectedToolArg or its
+        subclasses, or arguments in FILTERED_ARGS like run_manager and callbacks.
+
+        Args:
+            tool_input: The tool input dictionary to filter.
+
+        Returns:
+            A filtered dictionary with injected arguments removed.
+        """
+        # Start with filtered args from the constant
+        filtered_keys = set[str](FILTERED_ARGS)
+
+        # If we have an args_schema, use it to identify injected args
+        if self.args_schema is not None:
+            try:
+                annotations = get_all_basemodel_annotations(self.args_schema)
+                for field_name, field_type in annotations.items():
+                    if _is_injected_arg_type(field_type):
+                        filtered_keys.add(field_name)
+            except Exception:  # noqa: S110
+                # If we can't get annotations, just use FILTERED_ARGS
+                pass
+
+        # Filter out the injected keys from tool_input
+        return {k: v for k, v in tool_input.items() if k not in filtered_keys}
+
     def _to_args_and_kwargs(
         self, tool_input: str | dict, tool_call_id: str | None
     ) -> tuple[tuple, dict]:
@@ -794,17 +823,29 @@ class ChildTool(BaseTool):
             self.metadata,
         )
 
+        # Filter out injected arguments from callback inputs
+        filtered_tool_input = (
+            self._filter_injected_args(tool_input)
+            if isinstance(tool_input, dict)
+            else None
+        )
+
+        # Use filtered inputs for the input_str parameter as well
+        tool_input_str = (
+            tool_input
+            if isinstance(tool_input, str)
+            else str(
+                filtered_tool_input if filtered_tool_input is not None else tool_input
+            )
+        )
+
         run_manager = callback_manager.on_tool_start(
             {"name": self.name, "description": self.description},
-            tool_input if isinstance(tool_input, str) else str(tool_input),
+            tool_input_str,
             color=start_color,
             name=run_name,
             run_id=run_id,
-            # Inputs by definition should always be dicts.
-            # For now, it's unclear whether this assumption is ever violated,
-            # but if it is we will send a `None` value to the callback instead
-            # TODO: will need to address issue via a patch.
-            inputs=tool_input if isinstance(tool_input, dict) else None,
+            inputs=filtered_tool_input,
             **kwargs,
         )
 
@@ -905,17 +946,30 @@ class ChildTool(BaseTool):
             metadata,
             self.metadata,
         )
+
+        # Filter out injected arguments from callback inputs
+        filtered_tool_input = (
+            self._filter_injected_args(tool_input)
+            if isinstance(tool_input, dict)
+            else None
+        )
+
+        # Use filtered inputs for the input_str parameter as well
+        tool_input_str = (
+            tool_input
+            if isinstance(tool_input, str)
+            else str(
+                filtered_tool_input if filtered_tool_input is not None else tool_input
+            )
+        )
+
         run_manager = await callback_manager.on_tool_start(
             {"name": self.name, "description": self.description},
-            tool_input if isinstance(tool_input, str) else str(tool_input),
+            tool_input_str,
             color=start_color,
             name=run_name,
             run_id=run_id,
-            # Inputs by definition should always be dicts.
-            # For now, it's unclear whether this assumption is ever violated,
-            # but if it is we will send a `None` value to the callback instead
-            # TODO: will need to address issue via a patch.
-            inputs=tool_input if isinstance(tool_input, dict) else None,
+            inputs=filtered_tool_input,
             **kwargs,
         )
         content = None

langchain_core/tools/convert.py

@@ -89,6 +89,7 @@ def tool(
         runnable: Optional runnable to convert to a tool. Must be provided as a
             positional argument.
         description: Optional description for the tool.
+
             Precedence for the tool description value is as follows:
 
             - `description` argument
@@ -105,11 +106,13 @@ def tool(
         infer_schema: Whether to infer the schema of the arguments from
             the function's signature. This also makes the resultant tool
             accept a dictionary input to its `run()` function.
-        response_format: 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 two-tuple
-            corresponding to the `(content, artifact)` of a `ToolMessage`.
-        parse_docstring: if `infer_schema` and `parse_docstring`, will attempt to
+        response_format: 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 two-tuple corresponding to the `(content, artifact)` of a
+            `ToolMessage`.
+        parse_docstring: If `infer_schema` and `parse_docstring`, will attempt to
             parse parameter descriptions from Google Style function docstrings.
         error_on_invalid_docstring: if `parse_docstring` is provided, configure
             whether to raise `ValueError` on invalid Google Style docstrings.

langchain_core/tools/retriever.py

@@ -83,11 +83,12 @@ def create_retriever_tool(
             model, so should be descriptive.
         document_prompt: The prompt to use for the document.
         document_separator: The separator to use between documents.
-        response_format: 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 two-tuple
-            corresponding to the `(content, artifact)` of a `ToolMessage` (artifact
-            being a list of documents in this case).
+        response_format: 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 two-tuple corresponding to the `(content, artifact)` of a `ToolMessage`
+            (artifact being a list of documents in this case).
 
     Returns:
         Tool class to pass to an agent.

langchain_core/tools/structured.py

@@ -151,11 +151,13 @@ class StructuredTool(BaseTool):
             return_direct: Whether to return the result directly or as a callback.
             args_schema: The schema of the tool's input arguments.
             infer_schema: Whether to infer the schema from the function's signature.
-            response_format: 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 two-tuple
-                corresponding to the `(content, artifact)` of a `ToolMessage`.
-            parse_docstring: if `infer_schema` and `parse_docstring`, will attempt
+            response_format: 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 two-tuple corresponding to the `(content, artifact)`
+                of a `ToolMessage`.
+            parse_docstring: If `infer_schema` and `parse_docstring`, will attempt
                 to parse parameter descriptions from Google Style function docstrings.
             error_on_invalid_docstring: if `parse_docstring` is provided, configure
                 whether to raise `ValueError` on invalid Google Style docstrings.

langchain_core/tracers/log_stream.py

@@ -96,10 +96,10 @@ class RunLogPatch:
     """Patch to the run log."""
 
     ops: list[dict[str, Any]]
-    """List of jsonpatch operations, which describe how to create the run state
+    """List of JSONPatch operations, which describe how to create the run state
     from an empty dict. This is the minimal representation of the log, designed to
     be serialized as JSON and sent over the wire to reconstruct the log on the other
-    side. Reconstruction of the state can be done with any jsonpatch-compliant library,
+    side. Reconstruction of the state can be done with any JSONPatch-compliant library,
     see https://jsonpatch.com for more information."""
 
     def __init__(self, *ops: dict[str, Any]) -> None:

langchain_core/utils/strings.py

@@ -30,10 +30,7 @@ def stringify_dict(data: dict) -> str:
     Returns:
         The stringified dictionary.
     """
-    text = ""
-    for key, value in data.items():
-        text += key + ": " + stringify_value(value) + "\n"
-    return text
+    return "".join(f"{key}: {stringify_value(value)}\n" for key, value in data.items())
 
 
 def comma_list(items: list[Any]) -> str:

langchain_core/utils/utils.py

@@ -218,7 +218,7 @@ def _build_model_kwargs(
     values: dict[str, Any],
     all_required_field_names: set[str],
 ) -> dict[str, Any]:
-    """Build "model_kwargs" param from Pydantic constructor values.
+    """Build `model_kwargs` param from Pydantic constructor values.
 
     Args:
         values: All init args passed in by user.
@@ -228,8 +228,8 @@ def _build_model_kwargs(
         Extra kwargs.
 
     Raises:
-        ValueError: If a field is specified in both values and extra_kwargs.
-        ValueError: If a field is specified in model_kwargs.
+        ValueError: If a field is specified in both `values` and `extra_kwargs`.
+        ValueError: If a field is specified in `model_kwargs`.
     """
     extra_kwargs = values.get("model_kwargs", {})
     for field_name in list(values):
@@ -267,6 +267,10 @@ def build_extra_kwargs(
 ) -> dict[str, Any]:
     """Build extra kwargs from values and extra_kwargs.
 
+    !!! danger "DON'T USE"
+        Kept for backwards-compatibility but should never have been public. Use the
+        internal `_build_model_kwargs` function instead.
+
     Args:
         extra_kwargs: Extra kwargs passed in by user.
         values: Values passed in by user.
@@ -276,9 +280,10 @@ def build_extra_kwargs(
         Extra kwargs.
 
     Raises:
-        ValueError: If a field is specified in both values and extra_kwargs.
-        ValueError: If a field is specified in model_kwargs.
+        ValueError: If a field is specified in both `values` and `extra_kwargs`.
+        ValueError: If a field is specified in `model_kwargs`.
     """
+    # DON'T USE! Kept for backwards-compatibility but should never have been public.
     for field_name in list(values):
         if field_name in extra_kwargs:
             msg = f"Found {field_name} supplied twice."
@@ -292,6 +297,7 @@ def build_extra_kwargs(
             )
             extra_kwargs[field_name] = values.pop(field_name)
 
+    # DON'T USE! Kept for backwards-compatibility but should never have been public.
     invalid_model_kwargs = all_required_field_names.intersection(extra_kwargs.keys())
     if invalid_model_kwargs:
         msg = (
@@ -300,6 +306,7 @@ def build_extra_kwargs(
         )
         raise ValueError(msg)
 
+    # DON'T USE! Kept for backwards-compatibility but should never have been public.
     return extra_kwargs