langchain-core 1.2.5__tar.gz → 1.2.7__tar.gz

{langchain_core-1.2.5 → langchain_core-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-core
-Version: 1.2.5
+Version: 1.2.7
 Summary: Building applications with LLMs through composability
 Project-URL: Homepage, https://docs.langchain.com/
 Project-URL: Documentation, https://reference.langchain.com/python/langchain_core/

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/_api/__init__.py

@@ -58,6 +58,20 @@ _dynamic_imports = {
 
 
 def __getattr__(attr_name: str) -> object:
+    """Dynamically import and return an attribute from a submodule.
+
+    This function enables lazy loading of API functions from submodules, reducing
+    initial import time and circular dependency issues.
+
+    Args:
+        attr_name: Name of the attribute to import.
+
+    Returns:
+        The imported attribute object.
+
+    Raises:
+        AttributeError: If the attribute is not a valid dynamic import.
+    """
     module_name = _dynamic_imports.get(attr_name)
     result = import_attr(attr_name, module_name, __spec__.parent)
     globals()[attr_name] = result
@@ -65,4 +79,9 @@ def __getattr__(attr_name: str) -> object:
 
 
 def __dir__() -> list[str]:
+    """Return a list of available attributes for this module.
+
+    Returns:
+        List of attribute names that can be imported from this module.
+    """
     return list(__all__)

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/_api/internal.py

@@ -1,4 +1,5 @@
 import inspect
+from typing import cast
 
 
 def is_caller_internal(depth: int = 2) -> bool:
@@ -16,7 +17,7 @@ def is_caller_internal(depth: int = 2) -> bool:
                 return False
         # Directly access the module name from the frame's global variables
         module_globals = frame.f_globals
-        caller_module_name = module_globals.get("__name__", "")
+        caller_module_name = cast("str", module_globals.get("__name__", ""))
         return caller_module_name.startswith("langchain")
     finally:
         del frame

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/caches.py

@@ -3,6 +3,7 @@
 Distinct from provider-based [prompt caching](https://docs.langchain.com/oss/python/langchain/models#prompt-caching).
 
 !!! warning "Beta feature"
+
     This is a beta feature. Please be wary of deploying experimental code to production
     unless you've taken appropriate precautions.
 

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/callbacks/base.py

@@ -960,28 +960,29 @@ class BaseCallbackManager(CallbackManagerMixin):
                 #    ['tag2', 'tag1']
             ```
         """  # noqa: E501
-        manager = self.__class__(
+        # Combine handlers and inheritable_handlers separately, using sets
+        # to deduplicate (order not preserved)
+        combined_handlers = list(set(self.handlers) | set(other.handlers))
+        combined_inheritable = list(
+            set(self.inheritable_handlers) | set(other.inheritable_handlers)
+        )
+
+        return self.__class__(
             parent_run_id=self.parent_run_id or other.parent_run_id,
-            handlers=[],
-            inheritable_handlers=[],
+            handlers=combined_handlers,
+            inheritable_handlers=combined_inheritable,
             tags=list(set(self.tags + other.tags)),
             inheritable_tags=list(set(self.inheritable_tags + other.inheritable_tags)),
             metadata={
                 **self.metadata,
                 **other.metadata,
             },
+            inheritable_metadata={
+                **self.inheritable_metadata,
+                **other.inheritable_metadata,
+            },
         )
 
-        handlers = self.handlers + other.handlers
-        inheritable_handlers = self.inheritable_handlers + other.inheritable_handlers
-
-        for handler in handlers:
-            manager.add_handler(handler)
-
-        for handler in inheritable_handlers:
-            manager.add_handler(handler, inherit=True)
-        return manager
-
     @property
     def is_async(self) -> bool:
         """Whether the callback manager is async."""

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/callbacks/manager.py

@@ -12,7 +12,6 @@ from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import copy_context
 from typing import TYPE_CHECKING, Any, TypeVar, cast
-from uuid import UUID
 
 from langsmith.run_helpers import get_tracing_context
 from typing_extensions import Self, override
@@ -44,6 +43,7 @@ from langchain_core.utils.uuid import uuid7
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Coroutine, Generator, Sequence
+    from uuid import UUID
 
     from tenacity import RetryCallState
 

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/document_loaders/langsmith.py

@@ -11,6 +11,7 @@ from typing_extensions import override
 
 from langchain_core.document_loaders.base import BaseLoader
 from langchain_core.documents import Document
+from langchain_core.tracers._compat import pydantic_to_dict
 
 
 class LangSmithLoader(BaseLoader):
@@ -118,14 +119,14 @@ class LangSmithLoader(BaseLoader):
             for key in self.content_key:
                 content = content[key]
             content_str = self.format_content(content)
-            metadata = example.dict()
+            metadata = pydantic_to_dict(example)
             # Stringify datetime and UUID types.
             for k in ("dataset_id", "created_at", "modified_at", "source_run_id", "id"):
                 metadata[k] = str(metadata[k]) if metadata[k] else metadata[k]
             yield Document(content_str, metadata=metadata)
 
 
-def _stringify(x: str | dict) -> str:
+def _stringify(x: str | dict[str, Any]) -> str:
     if isinstance(x, str):
         return x
     try:

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/indexing/api.py

@@ -242,6 +242,17 @@ def _delete(
     vector_store: VectorStore | DocumentIndex,
     ids: list[str],
 ) -> None:
+    """Delete documents from a vector store or document index by their IDs.
+
+    Args:
+        vector_store: The vector store or document index to delete from.
+        ids: List of document IDs to delete.
+
+    Raises:
+        IndexingException: If the delete operation fails.
+        TypeError: If the `vector_store` is neither a `VectorStore` nor a
+            `DocumentIndex`.
+    """
     if isinstance(vector_store, VectorStore):
         delete_ok = vector_store.delete(ids)
         if delete_ok is not None and delete_ok is False:

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/language_models/base.py

@@ -12,13 +12,14 @@ from typing import (
     Literal,
     TypeAlias,
     TypeVar,
+    cast,
 )
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from typing_extensions import TypedDict, override
 
-from langchain_core.caches import BaseCache
-from langchain_core.callbacks import Callbacks
+from langchain_core.caches import BaseCache  # noqa: TC001
+from langchain_core.callbacks import Callbacks  # noqa: TC001
 from langchain_core.globals import get_verbose
 from langchain_core.messages import (
     AIMessage,
@@ -86,13 +87,28 @@ def get_tokenizer() -> Any:
     return GPT2TokenizerFast.from_pretrained("gpt2")
 
 
+_GPT2_TOKENIZER_WARNED = False
+
+
 def _get_token_ids_default_method(text: str) -> list[int]:
-    """Encode the text into token IDs."""
-    # get the cached tokenizer
+    """Encode the text into token IDs using the fallback GPT-2 tokenizer."""
+    global _GPT2_TOKENIZER_WARNED  # noqa: PLW0603
+    if not _GPT2_TOKENIZER_WARNED:
+        warnings.warn(
+            "Using fallback GPT-2 tokenizer for token counting. "
+            "Token counts may be inaccurate for non-GPT-2 models. "
+            "For accurate counts, use a model-specific method if available.",
+            stacklevel=3,
+        )
+        _GPT2_TOKENIZER_WARNED = True
+
     tokenizer = get_tokenizer()
 
-    # tokenize the text using the GPT-2 tokenizer
-    return tokenizer.encode(text)
+    # Pass verbose=False to suppress the "Token indices sequence length is longer than
+    # the specified maximum sequence length" warning from HuggingFace. This warning is
+    # about GPT-2's 1024 token context limit, but we're only using the tokenizer for
+    # counting, not for model input.
+    return cast("list[int]", tokenizer.encode(text, verbose=False))
 
 
 LanguageModelInput = PromptValue | str | Sequence[MessageLikeRepresentation]

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/language_models/chat_models.py

@@ -341,6 +341,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
     """Profile detailing model capabilities.
 
     !!! warning "Beta feature"
+
         This is a beta feature. The format of model profiles is subject to change.
 
     If not specified, automatically loaded from the provider package on initialization
@@ -358,7 +359,10 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
     @cached_property
     def _serialized(self) -> dict[str, Any]:
-        return dumpd(self)
+        # self is always a Serializable object in this case, thus the result is
+        # guaranteed to be a dict since dumps uses the default callback, which uses
+        # obj.to_json which always returns TypedDict subclasses
+        return cast("dict[str, Any]", dumpd(self))
 
     # --- Runnable methods ---
 
@@ -461,7 +465,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
         # Check if a runtime streaming flag has been passed in.
         if "stream" in kwargs:
-            return kwargs["stream"]
+            return bool(kwargs["stream"])
 
         if "streaming" in self.model_fields_set:
             streaming_value = getattr(self, "streaming", None)
@@ -1144,7 +1148,15 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         if check_cache:
             if llm_cache:
                 llm_string = self._get_llm_string(stop=stop, **kwargs)
-                prompt = dumps(messages)
+                normalized_messages = [
+                    (
+                        msg.model_copy(update={"id": None})
+                        if getattr(msg, "id", None) is not None
+                        else msg
+                    )
+                    for msg in messages
+                ]
+                prompt = dumps(normalized_messages)
                 cache_val = llm_cache.lookup(prompt, llm_string)
                 if isinstance(cache_val, list):
                     converted_generations = self._convert_cached_generations(cache_val)
@@ -1262,7 +1274,15 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         if check_cache:
             if llm_cache:
                 llm_string = self._get_llm_string(stop=stop, **kwargs)
-                prompt = dumps(messages)
+                normalized_messages = [
+                    (
+                        msg.model_copy(update={"id": None})
+                        if getattr(msg, "id", None) is not None
+                        else msg
+                    )
+                    for msg in messages
+                ]
+                prompt = dumps(normalized_messages)
                 cache_val = await llm_cache.alookup(prompt, llm_string)
                 if isinstance(cache_val, list):
                     converted_generations = self._convert_cached_generations(cache_val)

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/language_models/llms.py

@@ -301,7 +301,10 @@ class BaseLLM(BaseLanguageModel[str], ABC):
 
     @functools.cached_property
     def _serialized(self) -> dict[str, Any]:
-        return dumpd(self)
+        # self is always a Serializable object in this case, thus the result is
+        # guaranteed to be a dict since dumps uses the default callback, which uses
+        # obj.to_json which always returns TypedDict subclasses
+        return cast("dict[str, Any]", dumpd(self))
 
     # --- Runnable methods ---
 

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/language_models/model_profile.py

@@ -7,6 +7,7 @@ class ModelProfile(TypedDict, total=False):
     """Model profile.
 
     !!! warning "Beta feature"
+
         This is a beta feature. The format of model profiles is subject to change.
 
     Provides information about chat model capabilities, such as context window sizes

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/load/load.py

@@ -490,17 +490,23 @@ def loads(
     core LangChain types (messages, prompts, documents, etc.). See
     `langchain_core.load.mapping` for the full list.
 
+    !!! warning "Beta feature"
+
+        This is a beta feature. Please be wary of deploying experimental code to
+        production unless you've taken appropriate precautions.
+
     Args:
         text: The string to load.
         allowed_objects: Allowlist of classes that can be deserialized.
 
             - `'core'` (default): Allow classes defined in the serialization mappings
-                for langchain_core.
+                for `langchain_core`.
             - `'all'`: Allow classes defined in the serialization mappings.
 
                 This includes core LangChain types (messages, prompts, documents, etc.)
                 and trusted partner integrations. See `langchain_core.load.mapping` for
                 the full list.
+
             - Explicit list of classes: Only those specific classes are allowed.
             - `[]`: Disallow all deserialization (will raise on any object).
         secrets_map: A map of secrets to load.
@@ -522,8 +528,9 @@ def loads(
             If provided, this function is called with `(class_path, kwargs)` where
             `class_path` is the class path tuple and `kwargs` is the kwargs dict.
             The validator should raise an exception if the object should not be
-            deserialized, otherwise return `None`. Defaults to
-            `default_init_validator` which blocks jinja2 templates.
+            deserialized, otherwise return `None`.
+
+            Defaults to `default_init_validator` which blocks jinja2 templates.
 
     Returns:
         Revived LangChain objects.
@@ -566,17 +573,23 @@ def load(
     core LangChain types (messages, prompts, documents, etc.). See
     `langchain_core.load.mapping` for the full list.
 
+    !!! warning "Beta feature"
+
+        This is a beta feature. Please be wary of deploying experimental code to
+        production unless you've taken appropriate precautions.
+
     Args:
         obj: The object to load.
         allowed_objects: Allowlist of classes that can be deserialized.
 
             - `'core'` (default): Allow classes defined in the serialization mappings
-                for langchain_core.
+                for `langchain_core`.
             - `'all'`: Allow classes defined in the serialization mappings.
 
                 This includes core LangChain types (messages, prompts, documents, etc.)
                 and trusted partner integrations. See `langchain_core.load.mapping` for
                 the full list.
+
             - Explicit list of classes: Only those specific classes are allowed.
             - `[]`: Disallow all deserialization (will raise on any object).
         secrets_map: A map of secrets to load.
@@ -598,8 +611,9 @@ def load(
             If provided, this function is called with `(class_path, kwargs)` where
             `class_path` is the class path tuple and `kwargs` is the kwargs dict.
             The validator should raise an exception if the object should not be
-            deserialized, otherwise return `None`. Defaults to
-            `default_init_validator` which blocks jinja2 templates.
+            deserialized, otherwise return `None`.
+
+            Defaults to `default_init_validator` which blocks jinja2 templates.
 
     Returns:
         Revived LangChain objects.

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/load/serializable.py

@@ -92,11 +92,12 @@ class Serializable(BaseModel, ABC):
 
     It relies on the following methods and properties:
 
-    - `is_lc_serializable`: Is this class serializable?
+    - [`is_lc_serializable`][langchain_core.load.serializable.Serializable.is_lc_serializable]: Is this class serializable?
+
         By design, even if a class inherits from `Serializable`, it is not serializable
         by default. This is to prevent accidental serialization of objects that should
         not be serialized.
-    - `get_lc_namespace`: Get the namespace of the LangChain object.
+    - [`get_lc_namespace`][langchain_core.load.serializable.Serializable.get_lc_namespace]: Get the namespace of the LangChain object.
 
         During deserialization, this namespace is used to identify
         the correct class to instantiate.
@@ -105,10 +106,10 @@ class Serializable(BaseModel, ABC):
         During deserialization an additional mapping is handle classes that have moved
         or been renamed across package versions.
 
-    - `lc_secrets`: A map of constructor argument names to secret ids.
-    - `lc_attributes`: List of additional attribute names that should be included
+    - [`lc_secrets`][langchain_core.load.serializable.Serializable.lc_secrets]: A map of constructor argument names to secret ids.
+    - [`lc_attributes`][langchain_core.load.serializable.Serializable.lc_attributes]: List of additional attribute names that should be included
         as part of the serialized representation.
-    """
+    """  # noqa: E501
 
     # Remove default BaseModel init docstring.
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -132,12 +133,12 @@ class Serializable(BaseModel, ABC):
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the LangChain object.
 
-        For example, if the class is `langchain.llms.openai.OpenAI`, then the
-        namespace is `["langchain", "llms", "openai"]`
+        For example, if the class is [`langchain.llms.openai.OpenAI`][langchain_openai.OpenAI],
+        then the namespace is `["langchain", "llms", "openai"]`
 
         Returns:
             The namespace.
-        """
+        """  # noqa: E501
         return cls.__module__.split(".")
 
     @property

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/messages/ai.py

@@ -1,12 +1,13 @@
 """AI message."""
 
+import itertools
 import json
 import logging
 import operator
 from collections.abc import Sequence
 from typing import Any, Literal, cast, overload
 
-from pydantic import model_validator
+from pydantic import Field, model_validator
 from typing_extensions import NotRequired, Self, TypedDict, override
 
 from langchain_core.messages import content as types
@@ -166,10 +167,10 @@ class AIMessage(BaseMessage):
     (e.g., tool calls, usage metadata) added by the LangChain framework.
     """
 
-    tool_calls: list[ToolCall] = []
+    tool_calls: list[ToolCall] = Field(default_factory=list)
     """If present, tool calls associated with the message."""
 
-    invalid_tool_calls: list[InvalidToolCall] = []
+    invalid_tool_calls: list[InvalidToolCall] = Field(default_factory=list)
     """If present, tool calls with parsing errors associated with the message."""
 
     usage_metadata: UsageMetadata | None = None
@@ -394,7 +395,7 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     type: Literal["AIMessageChunk"] = "AIMessageChunk"  # type: ignore[assignment]
     """The type of the message (used for deserialization)."""
 
-    tool_call_chunks: list[ToolCallChunk] = []
+    tool_call_chunks: list[ToolCallChunk] = Field(default_factory=list)
     """If provided, tool call chunks associated with the message."""
 
     chunk_position: Literal["last"] | None = None
@@ -651,29 +652,28 @@ def add_ai_message_chunks(
     else:
         usage_metadata = None
 
+    # Ranks are defined by the order of preference. Higher is better:
+    # 2. Provider-assigned IDs (non lc_* and non lc_run-*)
+    # 1. lc_run-* IDs
+    # 0. lc_* and other remaining IDs
+    best_rank = -1
     chunk_id = None
-    candidates = [left.id] + [o.id for o in others]
-    # first pass: pick the first provider-assigned id (non-run-* and non-lc_*)
+    candidates = itertools.chain([left.id], (o.id for o in others))
+
     for id_ in candidates:
-        if (
-            id_
-            and not id_.startswith(LC_ID_PREFIX)
-            and not id_.startswith(LC_AUTO_PREFIX)
-        ):
+        if not id_:
+            continue
+
+        if not id_.startswith(LC_ID_PREFIX) and not id_.startswith(LC_AUTO_PREFIX):
             chunk_id = id_
+            # Highest rank, return instantly
             break
-    else:
-        # second pass: prefer lc_run-* IDs over lc_* IDs
-        for id_ in candidates:
-            if id_ and id_.startswith(LC_ID_PREFIX):
-                chunk_id = id_
-                break
-        else:
-            # third pass: take any remaining ID (auto-generated lc_* IDs)
-            for id_ in candidates:
-                if id_:
-                    chunk_id = id_
-                    break
+
+        rank = 1 if id_.startswith(LC_ID_PREFIX) else 0
+
+        if rank > best_rank:
+            best_rank = rank
+            chunk_id = id_
 
     chunk_position: Literal["last"] | None = (
         "last" if any(x.chunk_position == "last" for x in [left, *others]) else None

{langchain_core-1.2.5 → langchain_core-1.2.7}/langchain_core/messages/base.py

@@ -266,6 +266,9 @@ class BaseMessage(Serializable):
 
         Can be used as both property (`message.text`) and method (`message.text()`).
 
+        Handles both string and list content types (e.g. for content blocks). Only
+        extracts blocks with `type: 'text'`; other block types are ignored.
+
         !!! deprecated
             As of `langchain-core` 1.0.0, calling `.text()` as a method is deprecated.
             Use `.text` as a property instead. This method will be removed in 2.0.0.
@@ -277,7 +280,7 @@ class BaseMessage(Serializable):
         if isinstance(self.content, str):
             text_value = self.content
         else:
-            # must be a list
+            # Must be a list
             blocks = [
                 block
                 for block in self.content
@@ -302,7 +305,7 @@ class BaseMessage(Serializable):
         from langchain_core.prompts.chat import ChatPromptTemplate  # noqa: PLC0415
 
         prompt = ChatPromptTemplate(messages=[self])
-        return prompt + other
+        return prompt.__add__(other)
 
     def pretty_repr(
         self,