chore(langchain): add mypy warn_unreachable setting (#32529)

cbornet · mdrxy · web-flow · commit 791d309c0658 · 2025-08-15T23:03:53.000Z
See https://mypy.readthedocs.io/en/stable/config_file.html#confval-warn_unreachable --------- Co-authored-by: Mason Daugherty <github@mdrxy.com>
diff --git a/libs/langchain/langchain/agents/agent.py b/libs/langchain/langchain/agents/agent.py
@@ -1375,7 +1375,7 @@ def _iter_next_step(
             elif callable(self.handle_parsing_errors):
                 observation = self.handle_parsing_errors(e)
             else:
-                msg = "Got unexpected type of `handle_parsing_errors`"
+                msg = "Got unexpected type of `handle_parsing_errors`"  # type: ignore[unreachable]
                 raise ValueError(msg) from e  # noqa: TRY004
             output = AgentAction("_Exception", observation, text)
             if run_manager:
@@ -1514,7 +1514,7 @@ async def _aiter_next_step(
             elif callable(self.handle_parsing_errors):
                 observation = self.handle_parsing_errors(e)
             else:
-                msg = "Got unexpected type of `handle_parsing_errors`"
+                msg = "Got unexpected type of `handle_parsing_errors`"  # type: ignore[unreachable]
                 raise ValueError(msg) from e  # noqa: TRY004
             output = AgentAction("_Exception", observation, text)
             tool_run_kwargs = self._action_agent.tool_run_logging_kwargs()
diff --git a/libs/langchain/langchain/agents/format_scratchpad/openai_functions.py b/libs/langchain/langchain/agents/format_scratchpad/openai_functions.py
@@ -1,5 +1,6 @@
 import json
 from collections.abc import Sequence
+from typing import Any
 
 from langchain_core.agents import AgentAction, AgentActionMessageLog
 from langchain_core.messages import AIMessage, BaseMessage, FunctionMessage
@@ -30,7 +31,7 @@ def _convert_agent_action_to_messages(
 
 def _create_function_message(
     agent_action: AgentAction,
-    observation: str,
+    observation: Any,
 ) -> FunctionMessage:
     """Convert agent action and observation into a function message.
     Args:
diff --git a/libs/langchain/langchain/agents/format_scratchpad/tools.py b/libs/langchain/langchain/agents/format_scratchpad/tools.py
@@ -1,5 +1,6 @@
 import json
 from collections.abc import Sequence
+from typing import Any
 
 from langchain_core.agents import AgentAction
 from langchain_core.messages import (
@@ -13,7 +14,7 @@
 
 def _create_tool_message(
     agent_action: ToolAgentAction,
-    observation: str,
+    observation: Any,
 ) -> ToolMessage:
     """Convert agent action and observation into a tool message.
 
diff --git a/libs/langchain/langchain/agents/mrkl/base.py b/libs/langchain/langchain/agents/mrkl/base.py
@@ -170,7 +170,7 @@ def _validate_tools(cls, tools: Sequence[BaseTool]) -> None:
             raise ValueError(msg)
         for tool in tools:
             if tool.description is None:
-                msg = (
+                msg = (  # type: ignore[unreachable]
                     f"Got a tool {tool.name} without a description. For this agent, "
                     f"a description must always be provided."
                 )
diff --git a/libs/langchain/langchain/agents/output_parsers/json.py b/libs/langchain/langchain/agents/output_parsers/json.py
@@ -45,9 +45,9 @@ class JSONAgentOutputParser(AgentOutputParser):
     def parse(self, text: str) -> Union[AgentAction, AgentFinish]:
         try:
             response = parse_json_markdown(text)
-            if isinstance(response, list):
+            if isinstance(response, list):  # type: ignore[unreachable]
                 # gpt turbo frequently ignores the directive to emit a single action
-                logger.warning("Got multiple action responses: %s", response)
+                logger.warning("Got multiple action responses: %s", response)  # type: ignore[unreachable]
                 response = response[0]
             if response["action"] == "Final Answer":
                 return AgentFinish({"output": response["action_input"]}, text)
diff --git a/libs/langchain/langchain/chains/base.py b/libs/langchain/langchain/chains/base.py
@@ -286,7 +286,7 @@ def input_keys(self) -> list[str]:
     def output_keys(self) -> list[str]:
         """Keys expected to be in the chain output."""
 
-    def _validate_inputs(self, inputs: dict[str, Any]) -> None:
+    def _validate_inputs(self, inputs: Any) -> None:
         """Check that all inputs are present."""
         if not isinstance(inputs, dict):
             _input_keys = set(self.input_keys)
diff --git a/libs/langchain/langchain/chains/conversational_retrieval/base.py b/libs/langchain/langchain/chains/conversational_retrieval/base.py
@@ -54,7 +54,7 @@ def _get_chat_history(chat_history: list[CHAT_TURN_TYPE]) -> str:
             ai = "Assistant: " + dialogue_turn[1]
             buffer += f"\n{human}\n{ai}"
         else:
-            msg = (
+            msg = (  # type: ignore[unreachable]
                 f"Unsupported chat history format: {type(dialogue_turn)}."
                 f" Full chat history: {chat_history} "
             )
diff --git a/libs/langchain/langchain/chains/query_constructor/parser.py b/libs/langchain/langchain/chains/query_constructor/parser.py
@@ -9,6 +9,8 @@
 try:
     check_package_version("lark", gte_version="1.1.5")
     from lark import Lark, Transformer, v_args
+
+    _HAS_LARK = True
 except ImportError:
 
     def v_args(*_: Any, **__: Any) -> Any:  # type: ignore[misc]
@@ -17,6 +19,7 @@ def v_args(*_: Any, **__: Any) -> Any:  # type: ignore[misc]
 
     Transformer = object  # type: ignore[assignment,misc]
     Lark = object  # type: ignore[assignment,misc]
+    _HAS_LARK = False
 
 from langchain_core.structured_query import (
     Comparator,
@@ -260,8 +263,7 @@ def get_parser(
     Returns:
         Lark parser for the query language.
     """
-    # QueryTransformer is None when Lark cannot be imported.
-    if QueryTransformer is None:
+    if not _HAS_LARK:
         msg = "Cannot import lark, please install it with 'pip install lark'."
         raise ImportError(msg)
     transformer = QueryTransformer(
diff --git a/libs/langchain/langchain/chains/structured_output/base.py b/libs/langchain/langchain/chains/structured_output/base.py
@@ -439,7 +439,7 @@ class Dog(BaseModel):
             output_parser=output_parser,
             **kwargs,
         )
-    msg = (
+    msg = (  # type: ignore[unreachable]
         f"Invalid mode {mode}. Expected one of 'openai-tools', 'openai-functions', "
         f"'openai-json'."
     )
diff --git a/libs/langchain/langchain/embeddings/cache.py b/libs/langchain/langchain/embeddings/cache.py
@@ -336,7 +336,7 @@ def from_bytes_store(
                 )
                 raise ValueError(msg)
         else:
-            msg = (
+            msg = (  # type: ignore[unreachable]
                 "key_encoder must be either 'blake2b', 'sha1', 'sha256', 'sha512' "
                 "or a callable that encodes keys."
             )
diff --git a/libs/langchain/langchain/memory/vectorstore_token_buffer_memory.py b/libs/langchain/langchain/memory/vectorstore_token_buffer_memory.py
@@ -9,7 +9,7 @@
 
 import warnings
 from datetime import datetime
-from typing import Any
+from typing import Any, Optional
 
 from langchain_core.messages import BaseMessage
 from langchain_core.prompts.chat import SystemMessagePromptTemplate
@@ -109,7 +109,7 @@ class ConversationVectorStoreTokenBufferMemory(ConversationTokenBufferMemory):
     previous_history_template: str = DEFAULT_HISTORY_TEMPLATE
     split_chunk_size: int = 1000
 
-    _memory_retriever: VectorStoreRetrieverMemory = PrivateAttr(default=None)  # type: ignore[assignment]
+    _memory_retriever: Optional[VectorStoreRetrieverMemory] = PrivateAttr(default=None)
     _timestamps: list[datetime] = PrivateAttr(default_factory=list)
 
     @property
diff --git a/libs/langchain/langchain/model_laboratory.py b/libs/langchain/langchain/model_laboratory.py
@@ -34,7 +34,7 @@ def __init__(self, chains: Sequence[Chain], names: Optional[list[str]] = None):
         """
         for chain in chains:
             if not isinstance(chain, Chain):
-                msg = (
+                msg = (  # type: ignore[unreachable]
                     "ModelLaboratory should now be initialized with Chains. "
                     "If you want to initialize with LLMs, use the `from_llms` method "
                     "instead (`ModelLaboratory.from_llms(...)`)"
diff --git a/libs/langchain/langchain/retrievers/document_compressors/base.py b/libs/langchain/langchain/retrievers/document_compressors/base.py
@@ -47,7 +47,7 @@ def compress_documents(
             elif isinstance(_transformer, BaseDocumentTransformer):
                 documents = _transformer.transform_documents(documents)
             else:
-                msg = f"Got unexpected transformer type: {_transformer}"
+                msg = f"Got unexpected transformer type: {_transformer}"  # type: ignore[unreachable]
                 raise ValueError(msg)  # noqa: TRY004
         return documents
 
@@ -77,6 +77,6 @@ async def acompress_documents(
             elif isinstance(_transformer, BaseDocumentTransformer):
                 documents = await _transformer.atransform_documents(documents)
             else:
-                msg = f"Got unexpected transformer type: {_transformer}"
+                msg = f"Got unexpected transformer type: {_transformer}"  # type: ignore[unreachable]
                 raise ValueError(msg)  # noqa: TRY004
         return documents
diff --git a/libs/langchain/langchain/retrievers/ensemble.py b/libs/langchain/langchain/retrievers/ensemble.py
@@ -236,7 +236,7 @@ def rank_fusion(
         # Enforce that retrieved docs are Documents for each list in retriever_docs
         for i in range(len(retriever_docs)):
             retriever_docs[i] = [
-                Document(page_content=cast("str", doc)) if isinstance(doc, str) else doc
+                Document(page_content=cast("str", doc)) if isinstance(doc, str) else doc  # type: ignore[unreachable]
                 for doc in retriever_docs[i]
             ]
 
diff --git a/libs/langchain/langchain/smith/evaluation/runner_utils.py b/libs/langchain/langchain/smith/evaluation/runner_utils.py
@@ -238,7 +238,7 @@ def _wrap_in_chain_factory(
             return lambda: RunnableLambda(constructor)
         # Typical correct case
         return constructor
-    return llm_or_chain_factory
+    return llm_or_chain_factory  # type: ignore[unreachable]
 
 
 def _get_prompt(inputs: dict[str, Any]) -> str:
@@ -679,7 +679,7 @@ def _load_run_evaluators(
         elif callable(custom_evaluator):
             run_evaluators.append(run_evaluator_dec(custom_evaluator))
         else:
-            msg = (
+            msg = (  # type: ignore[unreachable]
                 f"Unsupported custom evaluator: {custom_evaluator}."
                 f" Expected RunEvaluator or StringEvaluator."
             )
diff --git a/libs/langchain/langchain/smith/evaluation/string_run_evaluator.py b/libs/langchain/langchain/smith/evaluation/string_run_evaluator.py
@@ -4,7 +4,7 @@
 
 import uuid
 from abc import abstractmethod
-from typing import Any, Optional
+from typing import Any, Optional, Union, cast
 
 from langchain_core.callbacks.manager import (
     AsyncCallbackManagerForChainRun,
@@ -55,16 +55,20 @@ def __call__(self, run: Run) -> dict[str, str]:
 class LLMStringRunMapper(StringRunMapper):
     """Extract items to evaluate from the run object."""
 
-    def serialize_chat_messages(self, messages: list[dict]) -> str:
+    def serialize_chat_messages(
+        self, messages: Union[list[dict], list[list[dict]]]
+    ) -> str:
         """Extract the input messages from the run."""
         if isinstance(messages, list) and messages:
             if isinstance(messages[0], dict):
-                chat_messages = _get_messages_from_run_dict(messages)
+                chat_messages = _get_messages_from_run_dict(
+                    cast("list[dict]", messages)
+                )
             elif isinstance(messages[0], list):
                 # Runs from Tracer have messages as a list of lists of dicts
                 chat_messages = _get_messages_from_run_dict(messages[0])
             else:
-                msg = f"Could not extract messages to evaluate {messages}"
+                msg = f"Could not extract messages to evaluate {messages}"  # type: ignore[unreachable]
                 raise ValueError(msg)
             return get_buffer_string(chat_messages)
         msg = f"Could not extract messages to evaluate {messages}"
@@ -107,11 +111,11 @@ def serialize_outputs(self, outputs: dict) -> str:
         if not outputs.get("generations"):
             msg = "Cannot evaluate LLM Run without generations."
             raise ValueError(msg)
-        generations: list[dict] = outputs["generations"]
+        generations: Union[list[dict], list[list[dict]]] = outputs["generations"]
         if not generations:
             msg = "Cannot evaluate LLM run with empty generations."
             raise ValueError(msg)
-        first_generation: dict = generations[0]
+        first_generation: Union[dict, list[dict]] = generations[0]
         if isinstance(first_generation, list):
             # Runs from Tracer have generations as a list of lists of dicts
             # Whereas Runs from the API have a list of dicts
@@ -450,7 +454,7 @@ def from_run_and_data_type(
         ):
             example_mapper = StringExampleMapper(reference_key=reference_key)
         elif evaluator.requires_reference:
-            msg = (
+            msg = (  # type: ignore[unreachable]
                 f"Evaluator {evaluator.evaluation_name} requires a reference"
                 " example from the dataset. Please specify the reference key from"
                 " amongst the dataset outputs keys."
diff --git a/libs/langchain/langchain/storage/_lc_store.py b/libs/langchain/langchain/storage/_lc_store.py
@@ -1,6 +1,6 @@
 """Create a key-value store for any langchain serializable object."""
 
-from typing import Callable, Optional
+from typing import Any, Callable, Optional
 
 from langchain_core.documents import Document
 from langchain_core.load import Serializable, dumps, loads
@@ -14,7 +14,7 @@ def _dump_as_bytes(obj: Serializable) -> bytes:
     return dumps(obj).encode("utf-8")
 
 
-def _dump_document_as_bytes(obj: Document) -> bytes:
+def _dump_document_as_bytes(obj: Any) -> bytes:
     """Return a bytes representation of a document."""
     if not isinstance(obj, Document):
         msg = "Expected a Document instance"
diff --git a/libs/langchain/pyproject.toml b/libs/langchain/pyproject.toml
@@ -129,6 +129,7 @@ strict_bytes = "True"
 ignore_missing_imports = "True"
 enable_error_code = "deprecated"
 report_deprecated_as_note = "True"
+warn_unreachable = "True"
 
 # TODO: activate for 'strict' checking
 disallow_untyped_calls = "False"
diff --git a/libs/langchain/tests/unit_tests/agents/test_agent.py b/libs/langchain/tests/unit_tests/agents/test_agent.py
@@ -514,20 +514,20 @@ def fake_parse(_: dict) -> Union[AgentFinish, AgentAction]:
     ]
 
     # stream log
-    results: list[RunLogPatch] = [  # type: ignore[no-redef]
+    log_results: list[RunLogPatch] = [
         r async for r in executor.astream_log({"question": "hello"})
     ]
     # # Let's stream just the llm tokens.
     messages = []
-    for log_record in results:
-        for op in log_record.ops:  # type: ignore[attr-defined]
+    for log_record in log_results:
+        for op in log_record.ops:
             if op["op"] == "add" and isinstance(op["value"], AIMessageChunk):
                 messages.append(op["value"])  # noqa: PERF401
 
     assert messages != []
 
     # Aggregate state
-    run_log = reduce(operator.add, results)
+    run_log = reduce(operator.add, log_results)
 
     assert isinstance(run_log, RunLog)
 
diff --git a/libs/langchain/tests/unit_tests/agents/test_structured_chat.py b/libs/langchain/tests/unit_tests/agents/test_structured_chat.py
@@ -23,7 +23,7 @@ def get_action_and_input(text: str) -> tuple[str, str]:
         return output.tool, str(output.tool_input)
     if isinstance(output, AgentFinish):
         return output.return_values["output"], output.log
-    msg = "Unexpected output type"
+    msg = "Unexpected output type"  # type: ignore[unreachable]
     raise ValueError(msg)
 
 
diff --git a/libs/langchain/tests/unit_tests/chains/query_constructor/test_parser.py b/libs/langchain/tests/unit_tests/chains/query_constructor/test_parser.py
@@ -1,6 +1,6 @@
 """Test LLM-generated structured query parsing."""
 
-from typing import Any, cast
+from typing import Any, Optional, cast
 
 import lark
 import pytest
@@ -149,7 +149,7 @@ def test_parse_date_value(x: str) -> None:
         ),
     ],
 )
-def test_parse_datetime_value(x: str, expected: dict) -> None:
+def test_parse_datetime_value(x: str, expected: Optional[dict[str, str]]) -> None:
     """Test parsing of datetime values with ISO 8601 format."""
     try:
         parsed = cast("Comparison", DEFAULT_PARSER.parse(f'eq("publishedAt", {x})'))
diff --git a/libs/langchain/tests/unit_tests/llms/fake_chat_model.py b/libs/langchain/tests/unit_tests/llms/fake_chat_model.py
@@ -107,7 +107,7 @@ def _stream(
             **kwargs,
         )
         if not isinstance(chat_result, ChatResult):
-            msg = (
+            msg = (  # type: ignore[unreachable]
                 f"Expected generate to return a ChatResult, "
                 f"but got {type(chat_result)} instead."
             )
diff --git a/libs/langchain/uv.lock b/libs/langchain/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -170,7 +170,7 @@ def _validate_tools(cls, tools: Sequence[BaseTool]) -> None:`
`170`	`170`	`raise ValueError(msg)`
`171`	`171`	`for tool in tools:`
`172`	`172`	`if tool.description is None:`
`173`		`- msg = (`
	`173`	`+ msg = ( # type: ignore[unreachable]`
`174`	`174`	`f"Got a tool {tool.name} without a description. For this agent, "`
`175`	`175`	`f"a description must always be provided."`
`176`	`176`	`)`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ def _get_chat_history(chat_history: list[CHAT_TURN_TYPE]) -> str:`
`54`	`54`	`ai = "Assistant: " + dialogue_turn[1]`
`55`	`55`	`buffer += f"\n{human}\n{ai}"`
`56`	`56`	`else:`
`57`		`- msg = (`
	`57`	`+ msg = ( # type: ignore[unreachable]`
`58`	`58`	`f"Unsupported chat history format: {type(dialogue_turn)}."`
`59`	`59`	`f" Full chat history: {chat_history} "`
`60`	`60`	`)`
Original file line number	Diff line number	Diff line change
`@@ -439,7 +439,7 @@ class Dog(BaseModel):`
`439`	`439`	`output_parser=output_parser,`
`440`	`440`	`**kwargs,`
`441`	`441`	`)`
`442`		`- msg = (`
	`442`	`+ msg = ( # type: ignore[unreachable]`
`443`	`443`	`f"Invalid mode {mode}. Expected one of 'openai-tools', 'openai-functions', "`
`444`	`444`	`f"'openai-json'."`
`445`	`445`	`)`
Original file line number	Diff line number	Diff line change
`@@ -336,7 +336,7 @@ def from_bytes_store(`
`336`	`336`	`)`
`337`	`337`	`raise ValueError(msg)`
`338`	`338`	`else:`
`339`		`- msg = (`
	`339`	`+ msg = ( # type: ignore[unreachable]`
`340`	`340`	`"key_encoder must be either 'blake2b', 'sha1', 'sha256', 'sha512' "`
`341`	`341`	`"or a callable that encodes keys."`
`342`	`342`	`)`