Merge branch 'master' into docs/qwen3-think-mode

Author: Pranav-d33

docs/docs/integrations/chat/anthropic.ipynb

@@ -568,6 +568,26 @@
     "    ```\n",
     "    and specifying `\"cache_control\": {\"type\": \"ephemeral\", \"ttl\": \"1h\"}`.\n",
     "\n",
+    "    Details of cached token counts will be included on the `InputTokenDetails` of response's `usage_metadata`:\n",
+    "\n",
+    "    ```python\n",
+    "    response = llm.invoke(messages)\n",
+    "    response.usage_metadata\n",
+    "    ```\n",
+    "    ```\n",
+    "    {\n",
+    "        \"input_tokens\": 1500,\n",
+    "        \"output_tokens\": 200,\n",
+    "        \"total_tokens\": 1700,\n",
+    "        \"input_token_details\": {\n",
+    "            \"cache_read\": 0,\n",
+    "            \"cache_creation\": 1000,\n",
+    "            \"ephemeral_1h_input_tokens\": 750,\n",
+    "            \"ephemeral_5m_input_tokens\": 250,\n",
+    "        }\n",
+    "    }\n",
+    "    ```\n",
+    "\n",
     ":::"
    ]
   },

docs/docs/integrations/chat/groq.ipynb

@@ -58,7 +58,9 @@
       "cell_type": "markdown",
       "id": "72ee0c4b-9764-423a-9dbf-95129e185210",
       "metadata": {},
-      "source": "To enable automated tracing of your model calls, set your [LangSmith](https://docs.smith.langchain.com/) API key:"
+      "source": [
+        "To enable automated tracing of your model calls, set your [LangSmith](https://docs.smith.langchain.com/) API key:"
+      ]
     },
     {
       "cell_type": "code",
@@ -98,22 +100,30 @@
       "source": [
         "## Instantiation\n",
         "\n",
-        "Now we can instantiate our model object and generate chat completions:"
+        "Now we can instantiate our model object and generate chat completions. \n",
+        "\n",
+        "\n",
+        ":::note Reasoning Format\n",
+        "\n",
+        "If you choose to set a `reasoning_format`, you must ensure that the model you are using supports it. You can find a list of supported models in the [Groq documentation](https://console.groq.com/docs/reasoning).\n",
+        "\n",
+        ":::"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": 1,
+      "execution_count": 6,
       "id": "cb09c344-1836-4e0c-acf8-11d13ac1dbae",
       "metadata": {},
       "outputs": [],
       "source": [
         "from langchain_groq import ChatGroq\n",
         "\n",
         "llm = ChatGroq(\n",
-        "    model=\"llama-3.1-8b-instant\",\n",
+        "    model=\"deepseek-r1-distill-llama-70b\",\n",
         "    temperature=0,\n",
         "    max_tokens=None,\n",
+        "    reasoning_format=\"parsed\",\n",
         "    timeout=None,\n",
         "    max_retries=2,\n",
         "    # other params...\n",
@@ -130,7 +140,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 2,
+      "execution_count": 7,
       "id": "62e0dbc3",
       "metadata": {
         "tags": []
@@ -139,10 +149,10 @@
         {
           "data": {
             "text/plain": [
-              "AIMessage(content='The translation of \"I love programming\" to French is:\\n\\n\"J\\'adore le programmation.\"', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 22, 'prompt_tokens': 55, 'total_tokens': 77, 'completion_time': 0.029333333, 'prompt_time': 0.003502892, 'queue_time': 0.553054073, 'total_time': 0.032836225}, 'model_name': 'llama-3.1-8b-instant', 'system_fingerprint': 'fp_a491995411', 'finish_reason': 'stop', 'logprobs': None}, id='run-2b2da04a-993c-40ab-becc-201eab8b1a1b-0', usage_metadata={'input_tokens': 55, 'output_tokens': 22, 'total_tokens': 77})"
+              "AIMessage(content=\"J'aime la programmation.\", additional_kwargs={'reasoning_content': 'Okay, so I need to translate the sentence \"I love programming.\" into French. Let me think about how to approach this. \\n\\nFirst, I know that \"I\" in French is \"Je.\" That\\'s straightforward. Now, the verb \"love\" in French is \"aime\" when referring to oneself. So, \"I love\" would be \"J\\'aime.\" \\n\\nNext, the word \"programming.\" In French, programming is \"la programmation.\" But wait, in French, when you talk about loving an activity, you often use the definite article. So, it would be \"la programmation.\" \\n\\nPutting it all together, \"I love programming\" becomes \"J\\'aime la programmation.\" That sounds right. I think that\\'s the correct translation. \\n\\nI should double-check to make sure I\\'m not missing anything. Maybe I can think of similar phrases. For example, \"I love reading\" is \"J\\'aime lire,\" but when it\\'s a noun, like \"I love music,\" it\\'s \"J\\'aime la musique.\" So, yes, using \"la programmation\" makes sense here. \\n\\nI don\\'t think I need to change anything else. The sentence structure in French is Subject-Verb-Object, just like in English, so \"J\\'aime la programmation\" should be correct. \\n\\nI guess another way to say it could be \"J\\'adore la programmation,\" using \"adore\" instead of \"aime,\" but \"aime\" is more commonly used in this context. So, sticking with \"J\\'aime la programmation\" is probably the best choice.\\n'}, response_metadata={'token_usage': {'completion_tokens': 346, 'prompt_tokens': 23, 'total_tokens': 369, 'completion_time': 1.447541218, 'prompt_time': 0.000983386, 'queue_time': 0.009673684, 'total_time': 1.448524604}, 'model_name': 'deepseek-r1-distill-llama-70b', 'system_fingerprint': 'fp_e98d30d035', 'finish_reason': 'stop', 'logprobs': None}, id='run--5679ae4f-f4e8-4931-bcd5-7304223832c0-0', usage_metadata={'input_tokens': 23, 'output_tokens': 346, 'total_tokens': 369})"
             ]
           },
-          "execution_count": 2,
+          "execution_count": 7,
           "metadata": {},
           "output_type": "execute_result"
         }
@@ -161,17 +171,15 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 3,
+      "execution_count": 8,
       "id": "d86145b3-bfef-46e8-b227-4dda5c9c2705",
       "metadata": {},
       "outputs": [
         {
           "name": "stdout",
           "output_type": "stream",
           "text": [
-            "The translation of \"I love programming\" to French is:\n",
-            "\n",
-            "\"J'adore le programmation.\"\n"
+            "J'aime la programmation.\n"
           ]
         }
       ],
@@ -191,17 +199,17 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 4,
+      "execution_count": 9,
       "id": "e197d1d7-a070-4c96-9f8a-a0e86d046e0b",
       "metadata": {},
       "outputs": [
         {
           "data": {
             "text/plain": [
-              "AIMessage(content='Ich liebe Programmieren.', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 6, 'prompt_tokens': 50, 'total_tokens': 56, 'completion_time': 0.008, 'prompt_time': 0.003337935, 'queue_time': 0.20949214500000002, 'total_time': 0.011337935}, 'model_name': 'llama-3.1-8b-instant', 'system_fingerprint': 'fp_a491995411', 'finish_reason': 'stop', 'logprobs': None}, id='run-e33b48dc-5e55-466e-9ebd-7b48c81c3cbd-0', usage_metadata={'input_tokens': 50, 'output_tokens': 6, 'total_tokens': 56})"
+              "AIMessage(content='The translation of \"I love programming\" into German is \"Ich liebe das Programmieren.\" \\n\\n**Step-by-Step Explanation:**\\n\\n1. **Subject Pronoun:** \"I\" translates to \"Ich.\"\\n2. **Verb Conjugation:** \"Love\" becomes \"liebe\" (first person singular of \"lieben\").\\n3. **Gerund Translation:** \"Programming\" is translated using the infinitive noun \"Programmieren.\"\\n4. **Article Usage:** The definite article \"das\" is included before the infinitive noun for natural phrasing.\\n\\nThus, the complete and natural translation is:\\n\\n**Ich liebe das Programmieren.**', additional_kwargs={'reasoning_content': 'Okay, so I need to translate the sentence \"I love programming.\" into German. Hmm, let\\'s break this down. \\n\\nFirst, \"I\" in German is \"Ich.\" That\\'s straightforward. Now, \"love\" translates to \"liebe.\" Wait, but in German, the verb conjugation depends on the subject. Since it\\'s \"I,\" the verb would be \"liebe\" because \"lieben\" is the infinitive, and for first person singular, it\\'s \"liebe.\" \\n\\nNext, \"programming\" is a gerund in English, which is the -ing form. In German, the equivalent would be the present participle, which is \"programmierend.\" But wait, sometimes in German, they use the noun form instead of the gerund. So maybe it\\'s better to say \"Ich liebe das Programmieren.\" Because \"Programmieren\" is the infinitive noun form, and it\\'s commonly used in such contexts. \\n\\nLet me think again. \"I love programming\" could be directly translated as \"Ich liebe Programmieren,\" but I\\'ve heard both \"Programmieren\" and \"programmierend\" used. However, \"Ich liebe das Programmieren\" sounds more natural because it uses the definite article \"das\" before the infinitive noun. \\n\\nAlternatively, if I use \"programmieren\" without the article, it\\'s still correct but maybe a bit less common. So, to make it sound more natural and fluent, including the article \"das\" would be better. \\n\\nTherefore, the correct translation should be \"Ich liebe das Programmieren.\" That makes sense because it\\'s similar to saying \"I love (the act of) programming.\" \\n\\nI think that\\'s the most accurate and natural way to express it in German. Let me double-check some examples. If someone says \"I love reading,\" in German it\\'s \"Ich liebe das Lesen.\" So yes, using \"das\" before the infinitive noun is the correct structure. \\n\\nSo, putting it all together, \"I love programming\" becomes \"Ich liebe das Programmieren.\" That should be the right translation.\\n'}, response_metadata={'token_usage': {'completion_tokens': 569, 'prompt_tokens': 18, 'total_tokens': 587, 'completion_time': 2.511255685, 'prompt_time': 0.001466702, 'queue_time': 0.009628211, 'total_time': 2.512722387}, 'model_name': 'deepseek-r1-distill-llama-70b', 'system_fingerprint': 'fp_87eae35036', 'finish_reason': 'stop', 'logprobs': None}, id='run--4d5ee86d-5eec-495c-9c4e-261526cf6e3d-0', usage_metadata={'input_tokens': 18, 'output_tokens': 569, 'total_tokens': 587})"
             ]
           },
-          "execution_count": 4,
+          "execution_count": 9,
           "metadata": {},
           "output_type": "execute_result"
         }
@@ -236,7 +244,7 @@
       "source": [
         "## API reference\n",
         "\n",
-        "For detailed documentation of all ChatGroq features and configurations head to the API reference: https://python.langchain.com/api_reference/groq/chat_models/langchain_groq.chat_models.ChatGroq.html"
+        "For detailed documentation of all ChatGroq features and configurations head to the [API reference](https://python.langchain.com/api_reference/groq/chat_models/langchain_groq.chat_models.ChatGroq.html)."
       ]
     }
   ],

libs/core/langchain_core/messages/ai.py

@@ -55,6 +55,8 @@ class InputTokenDetails(TypedDict, total=False):
             }
 
     .. versionadded:: 0.3.9
+
+    May also hold extra provider-specific keys.
     """
 
     audio: int

libs/core/tests/unit_tests/prompts/__snapshots__/test_chat.ambr

@@ -702,6 +702,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -2132,6 +2134,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({

libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr

@@ -1105,6 +1105,8 @@
                         }
 
                 .. versionadded:: 0.3.9
+                
+                May also hold extra provider-specific keys.
               ''',
               'properties': dict({
                 'audio': dict({

libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr

@@ -2650,6 +2650,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -4124,6 +4126,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -5629,6 +5633,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -7009,6 +7015,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -8525,6 +8533,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -9950,6 +9960,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -11374,6 +11386,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({
@@ -12840,6 +12854,8 @@
                   }
 
           .. versionadded:: 0.3.9
+          
+          May also hold extra provider-specific keys.
         ''',
         'properties': dict({
           'audio': dict({

libs/partners/anthropic/langchain_anthropic/chat_models.py

@@ -955,6 +955,8 @@ class Joke(BaseModel):
 
         .. dropdown:: Extended caching
 
+            .. versionadded:: 0.3.15
+
             The cache lifetime is 5 minutes by default. If this is too short, you can
             apply one hour caching by enabling the ``"extended-cache-ttl-2025-04-11"``
             beta header:
@@ -968,6 +970,28 @@ class Joke(BaseModel):
 
             and specifying ``"cache_control": {"type": "ephemeral", "ttl": "1h"}``.
 
+            Details of cached token counts will be included on the ``InputTokenDetails``
+            of response's ``usage_metadata``:
+
+            .. code-block:: python
+
+                response = llm.invoke(messages)
+                response.usage_metadata
+
+            .. code-block:: python
+
+                {
+                    "input_tokens": 1500,
+                    "output_tokens": 200,
+                    "total_tokens": 1700,
+                    "input_token_details": {
+                        "cache_read": 0,
+                        "cache_creation": 1000,
+                        "ephemeral_1h_input_tokens": 750,
+                        "ephemeral_5m_input_tokens": 250,
+                    }
+                }
+
             See `Claude documentation <https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#1-hour-cache-duration-beta>`_
             for detail.
 

libs/partners/groq/langchain_groq/chat_models.py

@@ -168,6 +168,9 @@ class ChatGroq(BaseChatModel):
             'logprobs': None}, id='run-ecc71d70-e10c-4b69-8b8c-b8027d95d4b8-0')
 
     Stream:
+
+        Streaming `text` for each content chunk received:
+
         .. code-block:: python
 
             for chunk in llm.stream(messages):
@@ -185,6 +188,8 @@ class ChatGroq(BaseChatModel):
             content='' response_metadata={'finish_reason': 'stop'}
             id='run-4e9f926b-73f5-483b-8ef5-09533d925853
 
+        Reconstructing a full response:
+
         .. code-block:: python
 
             stream = llm.stream(messages)
@@ -196,16 +201,15 @@ class ChatGroq(BaseChatModel):
         .. code-block:: python
 
             AIMessageChunk(content='The English sentence "I love programming"
-            can be translated to French as "J\'aime programmer".
-            Here\'s the breakdown of the sentence:\n\n* "J\'aime" is the
-            French equivalent of "I love"\n* "programmer" is the French
-            infinitive for "to program"\n\nSo, the literal translation
-            is "I love to program". However, in English we often omit the
-            "to" when talking about activities we love, and the same applies
-            to French. Therefore, "J\'aime programmer" is the correct and
-            natural way to express "I love programming" in French.',
-            response_metadata={'finish_reason': 'stop'},
-            id='run-a3c35ac4-0750-4d08-ac55-bfc63805de76')
+            can be translated to French as "J\'aime programmer". Here\'s the
+            breakdown of the sentence: "J\'aime" is the French equivalent of "
+            I love", and "programmer" is the French infinitive for "to program".
+            So, the literal translation is "I love to program". However, in
+            English we often omit the "to" when talking about activities we
+            love, and the same applies to French. Therefore, "J\'aime
+            programmer" is the correct and natural way to express "I love
+            programming" in French.', response_metadata={'finish_reason':
+            'stop'}, id='run-a3c35ac4-0750-4d08-ac55-bfc63805de76')
 
     Async:
         .. code-block:: python