langchain-core 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

langchain_core/agents.py

@@ -52,31 +52,33 @@ class AgentAction(Serializable):
     """The input to pass in to the Tool."""
     log: str
     """Additional information to log about the action.
-    This log can be used in a few ways. First, it can be used to audit
-    what exactly the LLM predicted to lead to this (tool, tool_input).
-    Second, it can be used in future iterations to show the LLMs prior
-    thoughts. This is useful when (tool, tool_input) does not contain
-    full information about the LLM prediction (for example, any `thought`
-    before the tool/tool_input)."""
+
+    This log can be used in a few ways. First, it can be used to audit what exactly the
+    LLM predicted to lead to this `(tool, tool_input)`.
+
+    Second, it can be used in future iterations to show the LLMs prior thoughts. This is
+    useful when `(tool, tool_input)` does not contain full information about the LLM
+    prediction (for example, any `thought` before the tool/tool_input).
+    """
     type: Literal["AgentAction"] = "AgentAction"
 
     # Override init to support instantiation by position for backward compat.
     def __init__(self, tool: str, tool_input: str | dict, log: str, **kwargs: Any):
-        """Create an AgentAction.
+        """Create an `AgentAction`.
 
         Args:
             tool: The name of the tool to execute.
-            tool_input: The input to pass in to the Tool.
+            tool_input: The input to pass in to the `Tool`.
             log: Additional information to log about the action.
         """
         super().__init__(tool=tool, tool_input=tool_input, log=log, **kwargs)
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """AgentAction is serializable.
+        """`AgentAction` is serializable.
 
         Returns:
-            True
+            `True`
         """
         return True
 
@@ -98,19 +100,23 @@ class AgentAction(Serializable):
 class AgentActionMessageLog(AgentAction):
     """Representation of an action to be executed by an agent.
 
-    This is similar to AgentAction, but includes a message log consisting of
-    chat messages. This is useful when working with ChatModels, and is used
-    to reconstruct conversation history from the agent's perspective.
+    This is similar to `AgentAction`, but includes a message log consisting of
+    chat messages.
+
+    This is useful when working with `ChatModels`, and is used to reconstruct
+    conversation history from the agent's perspective.
     """
 
     message_log: Sequence[BaseMessage]
-    """Similar to log, this can be used to pass along extra
-    information about what exact messages were predicted by the LLM
-    before parsing out the (tool, tool_input). This is again useful
-    if (tool, tool_input) cannot be used to fully recreate the LLM
-    prediction, and you need that LLM prediction (for future agent iteration).
+    """Similar to log, this can be used to pass along extra information about what exact
+    messages were predicted by the LLM before parsing out the `(tool, tool_input)`.
+
+    This is again useful if `(tool, tool_input)` cannot be used to fully recreate the
+    LLM prediction, and you need that LLM prediction (for future agent iteration).
+
     Compared to `log`, this is useful when the underlying LLM is a
-    chat model (and therefore returns messages rather than a string)."""
+    chat model (and therefore returns messages rather than a string).
+    """
     # Ignoring type because we're overriding the type from AgentAction.
     # And this is the correct thing to do in this case.
     # The type literal is used for serialization purposes.
@@ -132,19 +138,22 @@ class AgentStep(Serializable):
 
 
 class AgentFinish(Serializable):
-    """Final return value of an ActionAgent.
+    """Final return value of an `ActionAgent`.
 
-    Agents return an AgentFinish when they have reached a stopping condition.
+    Agents return an `AgentFinish` when they have reached a stopping condition.
     """
 
     return_values: dict
     """Dictionary of return values."""
     log: str
     """Additional information to log about the return value.
+
     This is used to pass along the full LLM prediction, not just the parsed out
-    return value. For example, if the full LLM prediction was
-    `Final Answer: 2` you may want to just return `2` as a return value, but pass
-    along the full string as a `log` (for debugging or observability purposes).
+    return value.
+
+    For example, if the full LLM prediction was `Final Answer: 2` you may want to just
+    return `2` as a return value, but pass along the full string as a `log` (for
+    debugging or observability purposes).
     """
     type: Literal["AgentFinish"] = "AgentFinish"
 
@@ -154,7 +163,7 @@ class AgentFinish(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod
@@ -202,7 +211,7 @@ def _convert_agent_observation_to_messages(
         observation: Observation to convert to a message.
 
     Returns:
-        AIMessage that corresponds to the original tool invocation.
+        `AIMessage` that corresponds to the original tool invocation.
     """
     if isinstance(agent_action, AgentActionMessageLog):
         return [_create_function_message(agent_action, observation)]
@@ -225,7 +234,7 @@ def _create_function_message(
         observation: the result of the tool invocation.
 
     Returns:
-        FunctionMessage that corresponds to the original tool invocation.
+        `FunctionMessage` that corresponds to the original tool invocation.
     """
     if not isinstance(observation, str):
         try:

langchain_core/callbacks/base.py

@@ -5,13 +5,12 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
-from typing_extensions import Self
-
 if TYPE_CHECKING:
     from collections.abc import Sequence
     from uuid import UUID
 
     from tenacity import RetryCallState
+    from typing_extensions import Self
 
     from langchain_core.agents import AgentAction, AgentFinish
     from langchain_core.documents import Document

langchain_core/callbacks/manager.py

@@ -39,7 +39,6 @@ from langchain_core.tracers.context import (
     tracing_v2_callback_var,
 )
 from langchain_core.tracers.langchain import LangChainTracer
-from langchain_core.tracers.schemas import Run
 from langchain_core.tracers.stdout import ConsoleCallbackHandler
 from langchain_core.utils.env import env_var_is_set
 
@@ -52,6 +51,7 @@ if TYPE_CHECKING:
     from langchain_core.documents import Document
     from langchain_core.outputs import ChatGenerationChunk, GenerationChunk, LLMResult
     from langchain_core.runnables.config import RunnableConfig
+    from langchain_core.tracers.schemas import Run
 
 logger = logging.getLogger(__name__)
 
@@ -229,7 +229,24 @@ def shielded(func: Func) -> Func:
 
     @functools.wraps(func)
     async def wrapped(*args: Any, **kwargs: Any) -> Any:
-        return await asyncio.shield(func(*args, **kwargs))
+        # Capture the current context to preserve context variables
+        ctx = copy_context()
+
+        # Create the coroutine
+        coro = func(*args, **kwargs)
+
+        # For Python 3.11+, create task with explicit context
+        # For older versions, fallback to original behavior
+        try:
+            # Create a task with the captured context to preserve context variables
+            task = asyncio.create_task(coro, context=ctx)  # type: ignore[call-arg, unused-ignore]
+            # `call-arg` used to not fail 3.9 or 3.10 tests
+            return await asyncio.shield(task)
+        except TypeError:
+            # Python < 3.11 fallback - create task normally then shield
+            # This won't preserve context perfectly but is better than nothing
+            task = asyncio.create_task(coro)
+            return await asyncio.shield(task)
 
     return cast("Func", wrapped)
 

langchain_core/callbacks/usage.py

@@ -43,7 +43,7 @@ class UsageMetadataCallbackHandler(BaseCallbackHandler):
           'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}
         ```
 
-    !!! version-added "Added in version 0.3.49"
+    !!! version-added "Added in `langchain-core` 0.3.49"
 
     """
 
@@ -134,7 +134,7 @@ def get_usage_metadata_callback(
         }
         ```
 
-    !!! version-added "Added in version 0.3.49"
+    !!! version-added "Added in `langchain-core` 0.3.49"
 
     """
     usage_metadata_callback_var: ContextVar[UsageMetadataCallbackHandler | None] = (

langchain_core/documents/base.py

@@ -114,11 +114,11 @@ class Blob(BaseMedia):
     data: bytes | str | None = None
     """Raw data associated with the `Blob`."""
     mimetype: str | None = None
-    """MimeType not to be confused with a file extension."""
+    """MIME type, not to be confused with a file extension."""
     encoding: str = "utf-8"
     """Encoding to use if decoding the bytes into a string.
 
-    Use `utf-8` as default encoding, if decoding to string.
+    Uses `utf-8` as default encoding if decoding to string.
     """
     path: PathLike | None = None
     """Location where the original content was found."""
@@ -134,7 +134,7 @@ class Blob(BaseMedia):
 
         If a path is associated with the `Blob`, it will default to the path location.
 
-        Unless explicitly set via a metadata field called `"source"`, in which
+        Unless explicitly set via a metadata field called `'source'`, in which
         case that value will be used instead.
         """
         if self.metadata and "source" in self.metadata:
@@ -309,7 +309,7 @@ class Document(BaseMedia):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod
@@ -322,10 +322,10 @@ class Document(BaseMedia):
         return ["langchain", "schema", "document"]
 
     def __str__(self) -> str:
-        """Override __str__ to restrict it to page_content and metadata.
+        """Override `__str__` to restrict it to page_content and metadata.
 
         Returns:
-            A string representation of the Document.
+            A string representation of the `Document`.
         """
         # The format matches pydantic format for __str__.
         #

langchain_core/example_selectors/length_based.py

@@ -29,7 +29,7 @@ class LengthBasedExampleSelector(BaseExampleSelector, BaseModel):
     max_length: int = 2048
     """Max length for the prompt, beyond which examples are cut."""
 
-    example_text_lengths: list[int] = Field(default_factory=list)  # :meta private:
+    example_text_lengths: list[int] = Field(default_factory=list)
     """Length of each example."""
 
     def add_example(self, example: dict[str, str]) -> None:

langchain_core/indexing/api.py

@@ -6,16 +6,9 @@ import hashlib
 import json
 import uuid
 import warnings
-from collections.abc import (
-    AsyncIterable,
-    AsyncIterator,
-    Callable,
-    Iterable,
-    Iterator,
-    Sequence,
-)
 from itertools import islice
 from typing import (
+    TYPE_CHECKING,
     Any,
     Literal,
     TypedDict,
@@ -29,6 +22,16 @@ from langchain_core.exceptions import LangChainException
 from langchain_core.indexing.base import DocumentIndex, RecordManager
 from langchain_core.vectorstores import VectorStore
 
+if TYPE_CHECKING:
+    from collections.abc import (
+        AsyncIterable,
+        AsyncIterator,
+        Callable,
+        Iterable,
+        Iterator,
+        Sequence,
+    )
+
 # Magic UUID to use as a namespace for hashing.
 # Used to try and generate a unique UUID for each document
 # from hashing the document content and metadata.
@@ -298,7 +301,7 @@ def index(
     For the time being, documents are indexed using their hashes, and users
     are not able to specify the uid of the document.
 
-    !!! warning "Behavior changed in 0.3.25"
+    !!! warning "Behavior changed in `langchain-core` 0.3.25"
         Added `scoped_full` cleanup mode.
 
     !!! warning
@@ -349,7 +352,7 @@ def index(
         key_encoder: Hashing algorithm to use for hashing the document content and
             metadata. Options include "blake2b", "sha256", and "sha512".
 
-            !!! version-added "Added in version 0.3.66"
+            !!! version-added "Added in `langchain-core` 0.3.66"
 
         key_encoder: Hashing algorithm to use for hashing the document.
             If not provided, a default encoder using SHA-1 will be used.
@@ -366,7 +369,7 @@ def index(
             method of the `VectorStore` or the upsert method of the DocumentIndex.
             For example, you can use this to specify a custom vector_field:
             upsert_kwargs={"vector_field": "embedding"}
-            !!! version-added "Added in version 0.3.10"
+            !!! version-added "Added in `langchain-core` 0.3.10"
 
     Returns:
         Indexing result which contains information about how many documents
@@ -636,7 +639,7 @@ async def aindex(
     For the time being, documents are indexed using their hashes, and users
     are not able to specify the uid of the document.
 
-    !!! warning "Behavior changed in 0.3.25"
+    !!! warning "Behavior changed in `langchain-core` 0.3.25"
         Added `scoped_full` cleanup mode.
 
     !!! warning
@@ -687,7 +690,7 @@ async def aindex(
         key_encoder: Hashing algorithm to use for hashing the document content and
             metadata. Options include "blake2b", "sha256", and "sha512".
 
-            !!! version-added "Added in version 0.3.66"
+            !!! version-added "Added in `langchain-core` 0.3.66"
 
         key_encoder: Hashing algorithm to use for hashing the document.
             If not provided, a default encoder using SHA-1 will be used.
@@ -704,7 +707,7 @@ async def aindex(
             method of the `VectorStore` or the upsert method of the DocumentIndex.
             For example, you can use this to specify a custom vector_field:
             upsert_kwargs={"vector_field": "embedding"}
-            !!! version-added "Added in version 0.3.10"
+            !!! version-added "Added in `langchain-core` 0.3.10"
 
     Returns:
         Indexing result which contains information about how many documents

langchain_core/language_models/_utils.py

@@ -139,7 +139,7 @@ def _normalize_messages(
             directly; this may change in the future
     - LangChain v0 standard content blocks for backward compatibility
 
-    !!! warning "Behavior changed in 1.0.0"
+    !!! warning "Behavior changed in `langchain-core` 1.0.0"
         In previous versions, this function returned messages in LangChain v0 format.
         Now, it returns messages in LangChain v1 format, which upgraded chat models now
         expect to receive when passing back in message history. For backward

langchain_core/language_models/base.py

@@ -131,14 +131,19 @@ class BaseLanguageModel(
 
     Caching is not currently supported for streaming methods of models.
     """
+
     verbose: bool = Field(default_factory=_get_verbosity, exclude=True, repr=False)
     """Whether to print out response text."""
+
     callbacks: Callbacks = Field(default=None, exclude=True)
     """Callbacks to add to the run trace."""
+
     tags: list[str] | None = Field(default=None, exclude=True)
     """Tags to add to the run trace."""
+
     metadata: dict[str, Any] | None = Field(default=None, exclude=True)
     """Metadata to add to the run trace."""
+
     custom_get_token_ids: Callable[[str], list[int]] | None = Field(
         default=None, exclude=True
     )
@@ -195,15 +200,22 @@ class BaseLanguageModel(
             type (e.g., pure text completion models vs chat models).
 
         Args:
-            prompts: List of `PromptValue` objects. A `PromptValue` is an object that
-                can be converted to match the format of any language model (string for
-                pure text generation models and `BaseMessage` objects for chat models).
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            callbacks: `Callbacks` to pass through. Used for executing additional
-                functionality, such as logging or streaming, throughout generation.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
+            prompts: List of `PromptValue` objects.
+
+                A `PromptValue` is an object that can be converted to match the format
+                of any language model (string for pure text generation models and
+                `BaseMessage` objects for chat models).
+            stop: Stop words to use when generating.
+
+                Model output is cut off at the first occurrence of any of these
+                substrings.
+            callbacks: `Callbacks` to pass through.
+
+                Used for executing additional functionality, such as logging or
+                streaming, throughout generation.
+            **kwargs: Arbitrary additional keyword arguments.
+
+                These are usually passed to the model provider API call.
 
         Returns:
             An `LLMResult`, which contains a list of candidate `Generation` objects for
@@ -232,15 +244,22 @@ class BaseLanguageModel(
             type (e.g., pure text completion models vs chat models).
 
         Args:
-            prompts: List of `PromptValue` objects. A `PromptValue` is an object that
-                can be converted to match the format of any language model (string for
-                pure text generation models and `BaseMessage` objects for chat models).
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            callbacks: `Callbacks` to pass through. Used for executing additional
-                functionality, such as logging or streaming, throughout generation.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
+            prompts: List of `PromptValue` objects.
+
+                A `PromptValue` is an object that can be converted to match the format
+                of any language model (string for pure text generation models and
+                `BaseMessage` objects for chat models).
+            stop: Stop words to use when generating.
+
+                Model output is cut off at the first occurrence of any of these
+                substrings.
+            callbacks: `Callbacks` to pass through.
+
+                Used for executing additional functionality, such as logging or
+                streaming, throughout generation.
+            **kwargs: Arbitrary additional keyword arguments.
+
+                These are usually passed to the model provider API call.
 
         Returns:
             An `LLMResult`, which contains a list of candidate `Generation` objects for
@@ -280,6 +299,9 @@ class BaseLanguageModel(
 
         Useful for checking if an input fits in a model's context window.
 
+        This should be overridden by model-specific implementations to provide accurate
+        token counts via model-specific tokenizers.
+
         Args:
             text: The string input to tokenize.
 
@@ -298,9 +320,17 @@ class BaseLanguageModel(
 
         Useful for checking if an input fits in a model's context window.
 
+        This should be overridden by model-specific implementations to provide accurate
+        token counts via model-specific tokenizers.
+
         !!! note
-            The base implementation of `get_num_tokens_from_messages` ignores tool
-            schemas.
+
+            * The base implementation of `get_num_tokens_from_messages` ignores tool
+                schemas.
+            * The base implementation of `get_num_tokens_from_messages` adds additional
+                prefixes to messages in represent user roles, which will add to the
+                overall token count. Model-specific implementations may choose to
+                handle this differently.
 
         Args:
             messages: The message inputs to tokenize.

langchain_core/language_models/chat_models.py

@@ -91,7 +91,10 @@ def _generate_response_from_error(error: BaseException) -> list[ChatGeneration]:
             try:
                 metadata["body"] = response.json()
             except Exception:
-                metadata["body"] = getattr(response, "text", None)
+                try:
+                    metadata["body"] = getattr(response, "text", None)
+                except Exception:
+                    metadata["body"] = None
         if hasattr(response, "headers"):
             try:
                 metadata["headers"] = dict(response.headers)
@@ -332,7 +335,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
     [`langchain-openai`](https://pypi.org/project/langchain-openai)) can also use this
     field to roll out new content formats in a backward-compatible way.
 
-    !!! version-added "Added in version 1.0"
+    !!! version-added "Added in `langchain-core` 1.0"
 
     """
 
@@ -845,16 +848,21 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
         Args:
             messages: List of list of messages.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            callbacks: `Callbacks` to pass through. Used for executing additional
-                functionality, such as logging or streaming, throughout generation.
+            stop: Stop words to use when generating.
+
+                Model output is cut off at the first occurrence of any of these
+                substrings.
+            callbacks: `Callbacks` to pass through.
+
+                Used for executing additional functionality, such as logging or
+                streaming, throughout generation.
             tags: The tags to apply.
             metadata: The metadata to apply.
             run_name: The name of the run.
             run_id: The ID of the run.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
+            **kwargs: Arbitrary additional keyword arguments.
+
+                These are usually passed to the model provider API call.
 
         Returns:
             An `LLMResult`, which contains a list of candidate `Generations` for each
@@ -963,16 +971,21 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
         Args:
             messages: List of list of messages.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            callbacks: `Callbacks` to pass through. Used for executing additional
-                functionality, such as logging or streaming, throughout generation.
+            stop: Stop words to use when generating.
+
+                Model output is cut off at the first occurrence of any of these
+                substrings.
+            callbacks: `Callbacks` to pass through.
+
+                Used for executing additional functionality, such as logging or
+                streaming, throughout generation.
             tags: The tags to apply.
             metadata: The metadata to apply.
             run_name: The name of the run.
             run_id: The ID of the run.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
+            **kwargs: Arbitrary additional keyword arguments.
+
+                These are usually passed to the model provider API call.
 
         Returns:
             An `LLMResult`, which contains a list of candidate `Generations` for each
@@ -1505,10 +1518,10 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         Args:
             schema: The output schema. Can be passed in as:
 
-                - an OpenAI function/tool schema,
-                - a JSON Schema,
-                - a `TypedDict` class,
-                - or a Pydantic class.
+                - An OpenAI function/tool schema,
+                - A JSON Schema,
+                - A `TypedDict` class,
+                - Or a Pydantic class.
 
                 If `schema` is a Pydantic class then the model output will be a
                 Pydantic instance of that class, and the model-generated fields will be
@@ -1520,11 +1533,15 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                 when specifying a Pydantic or `TypedDict` class.
 
             include_raw:
-                If `False` then only the parsed structured output is returned. If
-                an error occurs during model output parsing it will be raised. If `True`
-                then both the raw model response (a `BaseMessage`) and the parsed model
-                response will be returned. If an error occurs during output parsing it
-                will be caught and returned as well.
+                If `False` then only the parsed structured output is returned.
+
+                If an error occurs during model output parsing it will be raised.
+
+                If `True` then both the raw model response (a `BaseMessage`) and the
+                parsed model response will be returned.
+
+                If an error occurs during output parsing it will be caught and returned
+                as well.
 
                 The final output is always a `dict` with keys `'raw'`, `'parsed'`, and
                 `'parsing_error'`.
@@ -1629,8 +1646,8 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         # }
         ```
 
-        !!! warning "Behavior changed in 0.2.26"
-            Added support for TypedDict class.
+        !!! warning "Behavior changed in `langchain-core` 0.2.26"
+            Added support for `TypedDict` class.
 
         """  # noqa: E501
         _ = kwargs.pop("method", None)
@@ -1676,9 +1693,8 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
     def profile(self) -> ModelProfile:
         """Return profiling information for the model.
 
-        This property will relies on the `langchain-model-profiles` package to
-        retrieve chat model capabilities, such as context window sizes and supported
-        features.
+        This property relies on the `langchain-model-profiles` package to retrieve chat
+        model capabilities, such as context window sizes and supported features.
 
         Raises:
             ImportError: If `langchain-model-profiles` is not installed.
@@ -1764,9 +1780,12 @@ def _gen_info_and_msg_metadata(
     }
 
 
+_MAX_CLEANUP_DEPTH = 100
+
+
 def _cleanup_llm_representation(serialized: Any, depth: int) -> None:
     """Remove non-serializable objects from a serialized object."""
-    if depth > 100:  # Don't cooperate for pathological cases
+    if depth > _MAX_CLEANUP_DEPTH:  # Don't cooperate for pathological cases
         return
 
     if not isinstance(serialized, dict):