Merge branch 'master' into langchain-ruff-arg

Author: mdrxy

.github/copilot-instructions.md

@@ -0,0 +1,151 @@
+### 1. Avoid Breaking Changes (Stable Public Interfaces)
+
+* Carefully preserve **function signatures**, argument positions, and names for any exported/public methods.
+* Be cautious when **renaming**, **removing**, or **reordering** arguments — even small changes can break downstream consumers.
+* Use keyword-only arguments or clearly mark experimental features to isolate unstable APIs.
+
+Bad:
+
+```python
+def get_user(id, verbose=False):  # Changed from `user_id`
+```
+
+Good:
+
+```python
+def get_user(user_id: str, verbose: bool = False):  # Maintains stable interface
+```
+
+🧠 *Ask yourself:* “Would this change break someone's code if they used it last week?”
+
+---
+
+### 2. Simplify Code and Use Clear Variable Names
+
+* Prefer descriptive, **self-explanatory variable names**. Avoid overly short or cryptic identifiers.
+* Break up overly long or deeply nested functions for **readability and maintainability**.
+* Avoid unnecessary abstraction or premature optimization.
+* All generated Python code must include type hints.
+
+Bad:
+
+```python
+def p(u, d):
+    return [x for x in u if x not in d]
+```
+
+Good:
+
+```python
+def filter_unknown_users(users: List[str], known_users: Set[str]) -> List[str]:
+    return [user for user in users if user not in known_users]
+```
+
+---
+
+### 3. Ensure Unit Tests Cover New and Updated Functionality
+
+* Every new feature or bugfix should be **covered by a unit test**.
+* Test edge cases and failure conditions.
+* Use `pytest`, `unittest`, or the project’s existing framework consistently.
+
+Checklist:
+
+* [ ] Does the test suite fail if your new logic is broken?
+* [ ] Are all expected behaviors exercised (happy path, invalid input, etc)?
+* [ ] Do tests use fixtures or mocks where needed?
+
+---
+
+### 4. Look for Suspicious or Risky Code
+
+* Watch out for:
+
+  * Use of `eval()`, `exec()`, or `pickle` on user-controlled input.
+  * Silent failure modes (`except: pass`).
+  * Unreachable code or commented-out blocks.
+  * Race conditions or resource leaks (file handles, sockets, threads).
+
+Bad:
+
+```python
+def load_config(path):
+    with open(path) as f:
+        return eval(f.read())  # ⚠️ Never eval config
+```
+
+Good:
+
+```python
+import json
+
+def load_config(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+```
+
+---
+
+### 5. Use Google-Style Docstrings (with Args section)
+
+* All public functions should include a **Google-style docstring**.
+* Include an `Args:` section where relevant.
+* Types should NOT be written in the docstring — use type hints instead.
+
+Bad:
+
+```python
+def send_email(to, msg):
+    """Send an email to a recipient."""
+```
+
+Good:
+
+```python
+def send_email(to: str, msg: str) -> None:
+    """
+    Sends an email to a recipient.
+
+    Args:
+        to: The email address of the recipient.
+        msg: The message body.
+    """
+```
+
+📌 *Tip:* Keep descriptions concise but clear. Only document return values if non-obvious.
+
+---
+
+### 6. Propose Better Designs When Applicable
+
+* If there's a **cleaner**, **more scalable**, or **simpler** design, highlight it.
+* Suggest improvements, even if they require some refactoring — especially if the new code would:
+
+  * Reduce duplication
+  * Make unit testing easier
+  * Improve separation of concerns
+  * Add clarity without adding complexity
+
+Instead of:
+
+```python
+def save(data, db_conn):
+    # manually serializes fields
+```
+
+You might suggest:
+
+```python
+# Suggest using dataclasses or Pydantic for automatic serialization and validation
+```
+
+### 7. Misc
+
+* When suggesting package installation commands, use `uv pip install` as this project uses `uv`.
+* When creating tools for agents, use the @tool decorator from langchain_core.tools. The tool's docstring serves as its functional description for the agent.
+* Avoid suggesting deprecated components, such as the legacy LLMChain.
+* We use Conventional Commits format for pull request titles. Example PR titles:
+    * feat(core): add multi‐tenant support
+    * fix(cli): resolve flag parsing error
+    * docs: update API usage examples
+    * docs(openai): update API usage examples

.github/workflows/_release.yml

@@ -340,7 +340,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        partner: [openai, anthropic]
+        partner: [openai]
       fail-fast: false  # Continue testing other partners if one fails
     env:
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

docs/docs/how_to/custom_chat_model.ipynb

@@ -18,7 +18,7 @@
     "\n",
     "Wrapping your LLM with the standard [`BaseChatModel`](https://python.langchain.com/api_reference/core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html) interface allow you to use your LLM in existing LangChain programs with minimal code modifications!\n",
     "\n",
-    "As an bonus, your LLM will automatically become a LangChain [Runnable](/docs/concepts/runnables/) and will benefit from some optimizations out of the box (e.g., batch via a threadpool), async support, the `astream_events` API, etc.\n",
+    "As a bonus, your LLM will automatically become a LangChain [Runnable](/docs/concepts/runnables/) and will benefit from some optimizations out of the box (e.g., batch via a threadpool), async support, the `astream_events` API, etc.\n",
     "\n",
     "## Inputs and outputs\n",
     "\n",

docs/docs/integrations/text_embedding/azureopenai.ipynb

@@ -131,7 +131,7 @@
       "source": [
         "## Indexing and Retrieval\n",
         "\n",
-        "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/).\n",
+        "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/rag).\n",
         "\n",
         "Below, see how to index and retrieve data using the `embeddings` object we initialized above. In this example, we will index and retrieve a sample document in the `InMemoryVectorStore`."
       ]

docs/docs/integrations/text_embedding/google_generative_ai.ipynb

@@ -173,7 +173,7 @@
    "source": [
     "## Indexing and Retrieval\n",
     "\n",
-    "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/).\n",
+    "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/rag).\n",
     "\n",
     "Below, see how to index and retrieve data using the `embeddings` object we initialized above. In this example, we will index and retrieve a sample document in the `InMemoryVectorStore`."
    ]

docs/docs/integrations/text_embedding/google_vertex_ai_palm.ipynb

@@ -167,7 +167,7 @@
       "source": [
         "## Indexing and Retrieval\n",
         "\n",
-        "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/).\n",
+        "Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our [RAG tutorials](/docs/tutorials/rag).\n",
         "\n",
         "Below, see how to index and retrieve data using the `embeddings` object we initialized above. In this example, we will index and retrieve a sample document in the `InMemoryVectorStore`."
       ]

libs/core/langchain_core/language_models/fake_chat_models.py

@@ -36,6 +36,8 @@ def _generate(
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
+        if self.sleep is not None:
+            time.sleep(self.sleep)
         response = self.responses[self.i]
         if self.i < len(self.responses) - 1:
             self.i += 1
@@ -61,9 +63,9 @@ class FakeListChatModel(SimpleChatModel):
     """List of responses to **cycle** through in order."""
     sleep: Optional[float] = None
     i: int = 0
-    """List of responses to **cycle** through in order."""
-    error_on_chunk_number: Optional[int] = None
     """Internally incremented after every model invocation."""
+    error_on_chunk_number: Optional[int] = None
+    """If set, raise an error on the specified chunk number during streaming."""
 
     @property
     @override
@@ -79,6 +81,8 @@ def _call(
         **kwargs: Any,
     ) -> str:
         """First try to lookup in queries, else return 'foo' or 'bar'."""
+        if self.sleep is not None:
+            time.sleep(self.sleep)
         response = self.responses[self.i]
         if self.i < len(self.responses) - 1:
             self.i += 1

libs/core/langchain_core/output_parsers/openai_tools.py

@@ -234,23 +234,53 @@ def parse_result(self, result: list[Generation], *, partial: bool = False) -> An
         Returns:
             The parsed tool calls.
         """
-        parsed_result = super().parse_result(result, partial=partial)
-
+        generation = result[0]
+        if not isinstance(generation, ChatGeneration):
+            msg = "This output parser can only be used with a chat generation."
+            raise OutputParserException(msg)
+        message = generation.message
+        if isinstance(message, AIMessage) and message.tool_calls:
+            parsed_tool_calls = [dict(tc) for tc in message.tool_calls]
+            for tool_call in parsed_tool_calls:
+                if not self.return_id:
+                    _ = tool_call.pop("id")
+        else:
+            try:
+                raw_tool_calls = copy.deepcopy(message.additional_kwargs["tool_calls"])
+            except KeyError:
+                if self.first_tool_only:
+                    return None
+                return []
+            parsed_tool_calls = parse_tool_calls(
+                raw_tool_calls,
+                partial=partial,
+                strict=self.strict,
+                return_id=self.return_id,
+            )
+        # For backwards compatibility
+        for tc in parsed_tool_calls:
+            tc["type"] = tc.pop("name")
         if self.first_tool_only:
+            parsed_result = list(
+                filter(lambda x: x["type"] == self.key_name, parsed_tool_calls)
+            )
             single_result = (
-                parsed_result
-                if parsed_result and parsed_result["type"] == self.key_name
+                parsed_result[0]
+                if parsed_result and parsed_result[0]["type"] == self.key_name
                 else None
             )
             if self.return_id:
                 return single_result
             if single_result:
                 return single_result["args"]
             return None
-        parsed_result = [res for res in parsed_result if res["type"] == self.key_name]
-        if not self.return_id:
-            parsed_result = [res["args"] for res in parsed_result]
-        return parsed_result
+        return (
+            [res for res in parsed_tool_calls if res["type"] == self.key_name]
+            if self.return_id
+            else [
+                res["args"] for res in parsed_tool_calls if res["type"] == self.key_name
+            ]
+        )
 
 
 # Common cause of ValidationError is truncated output due to max_tokens.

libs/core/langchain_core/outputs/__init__.py

@@ -1,24 +1,23 @@
 """Output classes.
 
-**Output** classes are used to represent the output of a language model call
-and the output of a chat.
+Used to represent the output of a language model call and the output of a chat.
 
-The top container for information is the `LLMResult` object. `LLMResult` is used by
-both chat models and LLMs. This object contains the output of the language
-model and any additional information that the model provider wants to return.
+The top container for information is the `LLMResult` object. `LLMResult` is used by both
+chat models and LLMs. This object contains the output of the language model and any
+additional information that the model provider wants to return.
 
 When invoking models via the standard runnable methods (e.g. invoke, batch, etc.):
+
 - Chat models will return `AIMessage` objects.
 - LLMs will return regular text strings.
 
 In addition, users can access the raw output of either LLMs or chat models via
-callbacks. The on_chat_model_end and on_llm_end callbacks will return an
+callbacks. The ``on_chat_model_end`` and ``on_llm_end`` callbacks will return an
 LLMResult object containing the generated outputs and any additional information
 returned by the model provider.
 
-In general, if information is already available
-in the AIMessage object, it is recommended to access it from there rather than
-from the `LLMResult` object.
+In general, if information is already available in the AIMessage object, it is
+recommended to access it from there rather than from the `LLMResult` object.
 """
 
 from typing import TYPE_CHECKING

libs/core/langchain_core/outputs/chat_generation.py

@@ -27,7 +27,11 @@ class ChatGeneration(Generation):
     """
 
     text: str = ""
-    """*SHOULD NOT BE SET DIRECTLY* The text contents of the output message."""
+    """The text contents of the output message.
+
+    .. warning::
+        SHOULD NOT BE SET DIRECTLY!
+    """
     message: BaseMessage
     """The message output by the chat model."""
     # Override type to be ChatGeneration, ignore mypy error as this is intentional