The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
fix(core): python 3.14 hardening around `inspect.signature` (#41059)
ccurmedc3a689fc3b6
diff --git a/libs/core/langchain_core/_api/deprecation.py b/libs/core/langchain_core/_api/deprecation.pyindex 1492e21780..8127cdcc49 100644--- a/libs/core/langchain_core/_api/deprecation.py+++ b/libs/core/langchain_core/_api/deprecation.py@@ -36,10 +36,9 @@ if TYPE_CHECKING:def _is_pydantic_v1_field_info(obj: Any) -> TypeGuard["FieldInfoV1"]:"""Check if `obj` is a `pydantic.v1.fields.FieldInfo` without forcing import.- Importing `pydantic.v1` emits a `UserWarning` on Python 3.14+. Skipping the- import entirely when no caller has constructed a v1 `FieldInfo` keeps that- warning out of `langchain_core`'s import path. If a caller did construct one,- `pydantic.v1.fields` is already in `sys.modules` and isinstance is safe.+ Avoids importing `pydantic.v1`, which emits a `UserWarning` on Python 3.14++ with Pydantic 2.12. A v1 `FieldInfo` can only exist once a caller has imported+ `pydantic.v1.fields`, so this check consults it only if it is already loaded."""mod = sys.modules.get("pydantic.v1.fields")if mod is None:diff --git a/libs/core/langchain_core/language_models/chat_models.py b/libs/core/langchain_core/language_models/chat_models.pyindex 3058ddaa8e..abae783db8 100644--- a/libs/core/langchain_core/language_models/chat_models.py+++ b/libs/core/langchain_core/language_models/chat_models.py@@ -5,7 +5,6 @@ from __future__ import annotationsimport asyncioimport builtins # noqa: TC003 # runtime-evaluated; subclass `dict()` shadows the builtinimport contextlib-import inspectimport jsonfrom abc import ABC, abstractmethodfrom collections.abc import AsyncIterator, Callable, Iterator, Sequence@@ -91,6 +90,7 @@ from langchain_core.utils._gateway import (GATEWAY_METADATA_RESPONSE_KEY,_parse_gateway_metadata,)+from langchain_core.utils._signature import _signature_parametersfrom langchain_core.utils.function_calling import (convert_to_json_schema,convert_to_openai_tool,@@ -2018,7 +2018,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):run_manager.on_llm_new_token("", chunk=chunk)chunks.append(chunk)result = generate_from_stream(iter(chunks))- elif inspect.signature(self._generate).parameters.get("run_manager"):+ elif _signature_parameters(self._generate).get("run_manager"):result = self._generate(messages, stop=stop, run_manager=run_manager, **kwargs)@@ -2175,7 +2175,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):await run_manager.on_llm_new_token("", chunk=chunk)chunks.append(chunk)result = generate_from_stream(iter(chunks))- elif inspect.signature(self._agenerate).parameters.get("run_manager"):+ elif _signature_parameters(self._agenerate).get("run_manager"):result = await self._agenerate(messages, stop=stop, run_manager=run_manager, **kwargs)diff --git a/libs/core/langchain_core/language_models/llms.py b/libs/core/langchain_core/language_models/llms.pyindex 7903eec452..6dee2d66f7 100644--- a/libs/core/langchain_core/language_models/llms.py+++ b/libs/core/langchain_core/language_models/llms.py@@ -8,7 +8,6 @@ from __future__ import annotationsimport asyncioimport builtinsimport functools-import inspectimport jsonimport loggingfrom abc import ABC, abstractmethod@@ -58,6 +57,7 @@ from langchain_core.outputs import Generation, GenerationChunk, LLMResult, RunInfrom langchain_core.prompt_values import ChatPromptValue, PromptValue, StringPromptValuefrom langchain_core.runnables import RunnableConfig, ensure_config, get_config_listfrom langchain_core.runnables.config import run_in_executor+from langchain_core.utils._signature import _signature_parametersif TYPE_CHECKING:import builtins@@ -1006,9 +1006,7 @@ class BaseLLM(BaseLanguageModel[str], ABC):missing_prompt_idxs,missing_prompts,) = get_prompts(params, prompts, self.cache)- new_arg_supported = inspect.signature(self._generate).parameters.get(- "run_manager"- )+ new_arg_supported = _signature_parameters(self._generate).get("run_manager")if (self.cache is None and get_llm_cache() is None) or self.cache is False:run_managers = [callback_manager.on_llm_start(@@ -1281,9 +1279,7 @@ class BaseLLM(BaseLanguageModel[str], ABC):# Verify whether the cache is set, and if the cache is set,# verify whether the cache is available.- new_arg_supported = inspect.signature(self._agenerate).parameters.get(- "run_manager"- )+ new_arg_supported = _signature_parameters(self._agenerate).get("run_manager")if (self.cache is None and get_llm_cache() is None) or self.cache is False:run_managers = await asyncio.gather(*[@@ -1540,7 +1536,7 @@ class LLM(BaseLLM):) -> LLMResult:# TODO: add caching here.generations = []- new_arg_supported = inspect.signature(self._call).parameters.get("run_manager")+ new_arg_supported = _signature_parameters(self._call).get("run_manager")for prompt in prompts:text = (self._call(prompt, stop=stop, run_manager=run_manager, **kwargs)@@ -1558,7 +1554,7 @@ class LLM(BaseLLM):**kwargs: Any,) -> LLMResult:generations = []- new_arg_supported = inspect.signature(self._acall).parameters.get("run_manager")+ new_arg_supported = _signature_parameters(self._acall).get("run_manager")for prompt in prompts:text = (await self._acall(prompt, stop=stop, run_manager=run_manager, **kwargs)diff --git a/libs/core/langchain_core/retrievers.py b/libs/core/langchain_core/retrievers.pyindex caaad5005a..439cfb226d 100644--- a/libs/core/langchain_core/retrievers.py+++ b/libs/core/langchain_core/retrievers.py@@ -8,7 +8,6 @@ the backbone of a retriever, but there are other types of retrievers as well.from __future__ import annotationsfrom abc import ABC, abstractmethod-from inspect import signaturefrom typing import TYPE_CHECKING, Anyfrom pydantic import ConfigDict@@ -23,6 +22,7 @@ from langchain_core.runnables import (ensure_config,)from langchain_core.runnables.config import run_in_executor+from langchain_core.utils._signature import _signature_parametersif TYPE_CHECKING:from langchain_core.callbacks.manager import (@@ -145,7 +145,7 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):@overridedef __init_subclass__(cls, **kwargs: Any) -> None:super().__init_subclass__(**kwargs)- parameters = signature(cls._get_relevant_documents).parameters+ parameters = _signature_parameters(cls._get_relevant_documents)cls._new_arg_supported = parameters.get("run_manager") is not Noneif (not cls._new_arg_supporteddiff --git a/libs/core/langchain_core/runnables/base.py b/libs/core/langchain_core/runnables/base.pyindex 446de50b90..8ba8d3e8da 100644--- a/libs/core/langchain_core/runnables/base.py+++ b/libs/core/langchain_core/runnables/base.py@@ -96,6 +96,7 @@ from langchain_core.tracers.root_listeners import (AsyncRootListenersTracer,RootListenersTracer,)+from langchain_core.utils._signature import _signature_parametersfrom langchain_core.utils.aiter import aclosing, ateefrom langchain_core.utils.iter import safeteefrom langchain_core.utils.pydantic import (@@ -6550,7 +6551,7 @@ class RunnableBinding(RunnableBindingBase[Input, Output]): # type: ignore[no-reattr = getattr(self.bound, name)if callable(attr) and (- config_param := inspect.signature(attr).parameters.get("config")+ config_param := _signature_parameters(attr).get("config")):if config_param.kind == inspect.Parameter.KEYWORD_ONLY:@@ -6564,7 +6565,7 @@ class RunnableBinding(RunnableBindingBase[Input, Output]): # type: ignore[no-rereturn wrapperif config_param.kind == inspect.Parameter.POSITIONAL_OR_KEYWORD:- idx = list(inspect.signature(attr).parameters).index("config")+ idx = list(_signature_parameters(attr)).index("config")@wraps(attr)def wrapper(*args: Any, **kwargs: Any) -> Any:diff --git a/libs/core/langchain_core/runnables/history.py b/libs/core/langchain_core/runnables/history.pyindex df2022fd98..d0f8361786 100644--- a/libs/core/langchain_core/runnables/history.py+++ b/libs/core/langchain_core/runnables/history.py@@ -24,6 +24,7 @@ from langchain_core.runnables.utils import (Output,get_unique_config_specs,)+from langchain_core.utils._signature import _signature_parametersfrom langchain_core.utils.pydantic import create_model_v2if TYPE_CHECKING:@@ -627,5 +628,4 @@ class RunnableWithMessageHistory(RunnableBindingBase[Any, Any]): # type: ignoredef _get_parameter_names(callable_: GetSessionHistoryCallable) -> list[str]:"""Get the parameter names of the `Callable`."""- sig = inspect.signature(callable_)- return list(sig.parameters.keys())+ return list(_signature_parameters(callable_))diff --git a/libs/core/langchain_core/runnables/utils.py b/libs/core/langchain_core/runnables/utils.pyindex 0bc6b0780a..a4c212fdeb 100644--- a/libs/core/langchain_core/runnables/utils.py+++ b/libs/core/langchain_core/runnables/utils.py@@ -12,7 +12,6 @@ import textwrap# RunnableConfigurableFields.from collections.abc import Mapping, Sequence # noqa: TC003from functools import lru_cache-from inspect import signaturefrom itertools import groupbyfrom typing import (TYPE_CHECKING,@@ -25,6 +24,8 @@ from typing import (from typing_extensions import override+from langchain_core.utils._signature import _signature_parameters+# Re-export create-model for backwards compatibilityfrom langchain_core.utils.pydantic import create_model # noqa: F401@@ -92,7 +93,7 @@ def accepts_run_manager(callable: Callable[..., Any]) -> bool: # noqa: A002`True` if the callable accepts a run_manager argument, `False` otherwise."""try:- return signature(callable).parameters.get("run_manager") is not None+ return _signature_parameters(callable).get("run_manager") is not Noneexcept ValueError:return False@@ -107,7 +108,7 @@ def accepts_config(callable: Callable[..., Any]) -> bool: # noqa: A002`True` if the callable accepts a config argument, `False` otherwise."""try:- return signature(callable).parameters.get("config") is not None+ return _signature_parameters(callable).get("config") is not Noneexcept ValueError:return False@@ -122,7 +123,7 @@ def accepts_context(callable: Callable[..., Any]) -> bool: # noqa: A002`True` if the callable accepts a context argument, `False` otherwise."""try:- return signature(callable).parameters.get("context") is not None+ return _signature_parameters(callable).get("context") is not Noneexcept ValueError:return Falsediff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.pyindex 69020241cd..449579c297 100644--- a/libs/core/langchain_core/tools/base.py+++ b/libs/core/langchain_core/tools/base.py@@ -10,7 +10,6 @@ import typingimport warningsfrom abc import ABC, abstractmethodfrom collections.abc import Callable, Mapping, Sequence-from inspect import signaturefrom typing import (TYPE_CHECKING,Annotated,@@ -54,6 +53,7 @@ from langchain_core.runnables import ()from langchain_core.runnables.config import set_config_contextfrom langchain_core.runnables.utils import coro_with_context+from langchain_core.utils._signature import _signature_parametersfrom langchain_core.utils.function_calling import (_parse_google_docstring,_py_38_safe_origin,@@ -925,7 +925,7 @@ class ChildTool(BaseTool):Returns:The result of the tool execution."""- if kwargs.get("run_manager") and signature(self._run).parameters.get(+ if kwargs.get("run_manager") and _signature_parameters(self._run).get("run_manager"):kwargs["run_manager"] = kwargs["run_manager"].get_sync()@@ -1091,7 +1091,7 @@ class ChildTool(BaseTool):tool_args, tool_kwargs = self._to_args_and_kwargs(tool_input, tool_call_id)- if signature(self._run).parameters.get("run_manager"):+ if _signature_parameters(self._run).get("run_manager"):tool_kwargs |= {"run_manager": run_manager}if config_param := _get_runnable_config_param(self._run):tool_kwargs |= {config_param: config}@@ -1219,7 +1219,7 @@ class ChildTool(BaseTool):func_to_check = (self._run if self.__class__._arun is BaseTool._arun else self._arun # noqa: SLF001)- if signature(func_to_check).parameters.get("run_manager"):+ if _signature_parameters(func_to_check).get("run_manager"):tool_kwargs["run_manager"] = run_managerif config_param := _get_runnable_config_param(func_to_check):tool_kwargs[config_param] = config@@ -1639,7 +1639,7 @@ def _get_injected_args_keys_from_signature(func: Callable[..., Any]) -> frozenseReturns:`frozenset` of parameter names annotated as injected arguments."""- params = signature(func).parameters+ params = _signature_parameters(func)hint_source = _get_type_hints_source(func)hints = (_get_type_hints(hint_source, include_extras=True)diff --git a/libs/core/langchain_core/tools/simple.py b/libs/core/langchain_core/tools/simple.pyindex 502960ce1f..33ffd24bc0 100644--- a/libs/core/langchain_core/tools/simple.py+++ b/libs/core/langchain_core/tools/simple.py@@ -3,7 +3,6 @@from __future__ import annotationsfrom collections.abc import Awaitable, Callable-from inspect import signaturefrom typing import (TYPE_CHECKING,Any,@@ -23,6 +22,7 @@ from langchain_core.tools.base import (ToolException,_get_runnable_config_param,)+from langchain_core.utils._signature import _signature_parametersif TYPE_CHECKING:from langchain_core.messages import ToolCall@@ -115,7 +115,7 @@ class Tool(BaseTool):The result of the tool execution"""if self.func:- if run_manager and signature(self.func).parameters.get("callbacks"):+ if run_manager and _signature_parameters(self.func).get("callbacks"):kwargs["callbacks"] = run_manager.get_child()if config_param := _get_runnable_config_param(self.func):kwargs[config_param] = config@@ -142,7 +142,7 @@ class Tool(BaseTool):The result of the tool execution"""if self.coroutine:- if run_manager and signature(self.coroutine).parameters.get("callbacks"):+ if run_manager and _signature_parameters(self.coroutine).get("callbacks"):kwargs["callbacks"] = run_manager.get_child()if config_param := _get_runnable_config_param(self.coroutine):kwargs[config_param] = configdiff --git a/libs/core/langchain_core/tools/structured.py b/libs/core/langchain_core/tools/structured.pyindex e6d8e769f6..7d577384b1 100644--- a/libs/core/langchain_core/tools/structured.py+++ b/libs/core/langchain_core/tools/structured.py@@ -5,7 +5,6 @@ from __future__ import annotationsimport functoolsimport textwrapfrom collections.abc import Awaitable, Callable-from inspect import signaturefrom typing import (TYPE_CHECKING,Annotated,@@ -31,6 +30,7 @@ from langchain_core.tools.base import (_get_runnable_config_param,create_schema_from_function,)+from langchain_core.utils._signature import _signature_parametersfrom langchain_core.utils.pydantic import is_basemodel_subclass, model_json_schemaif TYPE_CHECKING:@@ -145,7 +145,7 @@ class StructuredTool(BaseTool):The result of the tool execution"""if self.func:- if run_manager and signature(self.func).parameters.get("callbacks"):+ if run_manager and _signature_parameters(self.func).get("callbacks"):kwargs["callbacks"] = run_manager.get_child()if config_param := _get_runnable_config_param(self.func):kwargs[config_param] = config@@ -172,7 +172,7 @@ class StructuredTool(BaseTool):The result of the tool execution"""if self.coroutine:- if run_manager and signature(self.coroutine).parameters.get("callbacks"):+ if run_manager and _signature_parameters(self.coroutine).get("callbacks"):kwargs["callbacks"] = run_manager.get_child()if config_param := _get_runnable_config_param(self.coroutine):kwargs[config_param] = configdiff --git a/libs/core/langchain_core/utils/_signature.py b/libs/core/langchain_core/utils/_signature.pynew file mode 100644index 0000000000..63ec3b7876--- /dev/null+++ b/libs/core/langchain_core/utils/_signature.py@@ -0,0 +1,29 @@+"""Signature inspection that does not evaluate annotations."""++import inspect+import sys+from collections.abc import Callable, Mapping+from typing import Any++if sys.version_info >= (3, 14):+ from annotationlib import Format+++def _signature_parameters(obj: Callable[..., Any]) -> Mapping[str, inspect.Parameter]:+ """Get the parameters of a callable without evaluating its annotations.++ On Python 3.14+, annotations are evaluated lazily, so `inspect.signature` raises+ `NameError` for annotations that reference names imported only under+ `TYPE_CHECKING`. Use this when only parameter names or kinds are needed.++ Args:+ obj: The callable to inspect.++ Returns:+ The callable's parameters, keyed by name.+ """+ if sys.version_info >= (3, 14):+ signature = inspect.signature(obj, annotation_format=Format.FORWARDREF)+ else:+ signature = inspect.signature(obj)+ return signature.parametersdiff --git a/libs/core/tests/unit_tests/utils/_type_checking_annotations.py b/libs/core/tests/unit_tests/utils/_type_checking_annotations.pynew file mode 100644index 0000000000..d79bb64106--- /dev/null+++ b/libs/core/tests/unit_tests/utils/_type_checking_annotations.py@@ -0,0 +1,127 @@+"""Callables annotated with names that are only imported for type checking.++Deliberately omits `from __future__ import annotations`, so on Python 3.14+ these+annotations are evaluated lazily and raise `NameError` when evaluated. Importing+this module requires Python 3.14+.+"""++# ruff: noqa: TC004++from typing import TYPE_CHECKING, Any++from pydantic import BaseModel+from typing_extensions import override++from langchain_core.chat_history import InMemoryChatMessageHistory+from langchain_core.documents import Document+from langchain_core.language_models import LLM, BaseChatModel+from langchain_core.messages import AIMessage+from langchain_core.outputs import ChatGeneration, ChatResult+from langchain_core.retrievers import BaseRetriever+from langchain_core.tools import BaseTool++if TYPE_CHECKING:+ from collections.abc import AsyncIterator, Iterator++ from langchain_core.callbacks import (+ CallbackManagerForLLMRun,+ CallbackManagerForRetrieverRun,+ CallbackManagerForToolRun,+ )+ from langchain_core.chat_history import BaseChatMessageHistory+ from langchain_core.messages import BaseMessage+ from langchain_core.runnables import RunnableConfig+++def add_one(x: int, config: RunnableConfig) -> int: # noqa: ARG001+ return x + 1+++async def aadd_one(x: int, config: RunnableConfig) -> int: # noqa: ARG001+ return x + 1+++def get_content(message: AIMessage) -> str:+ return message.text+++def upper(chunks: Iterator[str]) -> Iterator[str]:+ for chunk in chunks:+ yield chunk.upper()+++async def aupper(chunks: AsyncIterator[str]) -> AsyncIterator[str]:+ async for chunk in chunks:+ yield chunk.upper()+++_histories: dict[str, InMemoryChatMessageHistory] = {}+++def get_session_history(session_id: str) -> BaseChatMessageHistory:+ return _histories.setdefault(session_id, InMemoryChatMessageHistory())+++class FakeChatModel(BaseChatModel):+ @override+ def _generate(+ self,+ messages: list[BaseMessage],+ stop: list[str] | None = None,+ run_manager: CallbackManagerForLLMRun | None = None,+ **kwargs: Any,+ ) -> ChatResult:+ return ChatResult(generations=[ChatGeneration(message=AIMessage("hello"))])++ @property+ @override+ def _llm_type(self) -> str:+ return "fake"++ def describe(self, *, config: RunnableConfig) -> list[str]:+ return config.get("tags", [])+++class FakeLLM(LLM):+ @override+ def _call(+ self,+ prompt: str,+ stop: list[str] | None = None,+ run_manager: CallbackManagerForLLMRun | None = None,+ **kwargs: Any,+ ) -> str:+ return "hello"++ @property+ @override+ def _llm_type(self) -> str:+ return "fake"+++def define_retriever() -> type[BaseRetriever]:+ # `BaseRetriever` inspects `_get_relevant_documents` on subclass definition.+ class FakeRetriever(BaseRetriever):+ @override+ def _get_relevant_documents(+ self, query: str, *, run_manager: CallbackManagerForRetrieverRun+ ) -> list[Document]:+ return [Document(page_content=query)]++ return FakeRetriever+++class EchoInput(BaseModel):+ text: str+++class EchoTool(BaseTool):+ name: str = "echo"+ description: str = "Echo the input."+ args_schema: type[BaseModel] = EchoInput++ @override+ def _run(+ self, text: str, run_manager: CallbackManagerForToolRun | None = None+ ) -> str:+ return textdiff --git a/libs/core/tests/unit_tests/utils/test_signature.py b/libs/core/tests/unit_tests/utils/test_signature.pynew file mode 100644index 0000000000..8b3a2ddfda--- /dev/null+++ b/libs/core/tests/unit_tests/utils/test_signature.py@@ -0,0 +1,84 @@+"""Public APIs accept callables annotated with names imported under `TYPE_CHECKING`."""++import inspect+import sys+from typing import TYPE_CHECKING++import pytest++from langchain_core.messages import AIMessage, BaseMessage, HumanMessage+from langchain_core.runnables import RunnableGenerator, RunnableLambda+from langchain_core.runnables.history import RunnableWithMessageHistory++pytestmark = pytest.mark.skipif(+ sys.version_info < (3, 14), reason="Requires lazily evaluated annotations."+)++if TYPE_CHECKING or sys.version_info >= (3, 14):+ from tests.unit_tests.utils import _type_checking_annotations as annotated+++def test_annotations_are_unresolvable() -> None:+ with pytest.raises(NameError):+ inspect.signature(annotated.add_one)+++def test_runnable_lambda() -> None:+ runnable = RunnableLambda(annotated.add_one)+ assert runnable.invoke(1) == 2+ assert runnable.batch([1, 2]) == [2, 3]+ assert list(runnable.stream(1)) == [2]+++async def test_runnable_lambda_async() -> None:+ runnable = RunnableLambda(annotated.add_one, afunc=annotated.aadd_one)+ assert await runnable.ainvoke(1) == 2+++def test_runnable_generator() -> None:+ runnable = RunnableGenerator(annotated.upper)+ assert "".join(runnable.stream("ab")) == "AB"+++async def test_runnable_generator_async() -> None:+ runnable = RunnableGenerator(annotated.upper, annotated.aupper)+ assert "".join([chunk async for chunk in runnable.astream("ab")]) == "AB"+++def test_chat_model() -> None:+ model = annotated.FakeChatModel()+ assert model.invoke("hi").content == "hello"+ chain = model | RunnableLambda(annotated.get_content)+ assert chain.invoke("hi") == "hello"+++def test_runnable_binding_injects_config() -> None:+ model = annotated.FakeChatModel().with_config(tags=["a"])+ assert model.describe() == ["a"] # type: ignore[attr-defined]+++def test_llm() -> None:+ assert annotated.FakeLLM().invoke("hi") == "hello"+++def test_retriever() -> None:+ docs = annotated.define_retriever()().invoke("query")+ assert [doc.page_content for doc in docs] == ["query"]+++def test_tool() -> None:+ assert annotated.EchoTool().invoke({"text": "hi"}) == "hi"+++ "ignore::langchain_core._api.deprecation.LangChainDeprecationWarning"+)+def test_runnable_with_message_history() -> None:+ def respond(_: list[BaseMessage]) -> AIMessage:+ return AIMessage("hello")++ runnable = RunnableWithMessageHistory(+ RunnableLambda(respond), annotated.get_session_history+ )+ runnable.invoke([HumanMessage("hi")], config={"configurable": {"session_id": "1"}})+ assert len(annotated.get_session_history("1").messages) == 2