feat(docs): enhance ResponseMetadata documentation with provider field usage notes (#32472)

libs/core/langchain_core/v1/messages.py

@@ -110,6 +110,22 @@ class ResponseMetadata(TypedDict, total=False):
     The common fields (``model_provider``, ``model_name``) provide a baseline
     contract while preserving flexibility for provider innovations.
 
+    .. note::
+        Not all providers will return the metadata required by this class. In this case,
+        it is acceptable to inject these fields with values at invocation.
+
+        For instance, requests to OpenAI's responses API will not return a provider
+        field in the raw response, as it can be inferred that by making the request, the
+        provider responding is OpenAI. In this case, it is safe to set the
+        ``model_provider`` field to ``'openai'`` when creating the message.
+
+        On the other hand, ``model_name`` is often returned, and in such cases it is
+        expected that you populate this field with the unmodified model name (such as
+        ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+        model name should you artifically set this field - in which case, the value
+        should be set to the ``model`` or ``model_name`` parameter passed in during
+        invocation.
+
     """
 
     model_provider: str

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

@@ -1450,6 +1450,22 @@
                 
                 The common fields (``model_provider``, ``model_name``) provide a baseline
                 contract while preserving flexibility for provider innovations.
+                
+                .. note::
+                    Not all providers will return the metadata required by this class. In this case,
+                    it is acceptable to inject these fields with values at invocation.
+                
+                    For instance, requests to OpenAI's responses API will not return a provider
+                    field in the raw response, as it can be inferred that by making the request, the
+                    provider responding is OpenAI. In this case, it is safe to set the
+                    ``model_provider`` field to ``'openai'`` when creating the message.
+                
+                    On the other hand, ``model_name`` is often returned, and in such cases it is
+                    expected that you populate this field with the unmodified model name (such as
+                    ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+                    model name should you artifically set this field - in which case, the value
+                    should be set to the ``model`` or ``model_name`` parameter passed in during
+                    invocation.
               ''',
               'properties': dict({
                 'model_name': dict({

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

@@ -10455,6 +10455,22 @@
           
           The common fields (``model_provider``, ``model_name``) provide a baseline
           contract while preserving flexibility for provider innovations.
+          
+          .. note::
+              Not all providers will return the metadata required by this class. In this case,
+              it is acceptable to inject these fields with values at invocation.
+          
+              For instance, requests to OpenAI's responses API will not return a provider
+              field in the raw response, as it can be inferred that by making the request, the
+              provider responding is OpenAI. In this case, it is safe to set the
+              ``model_provider`` field to ``'openai'`` when creating the message.
+          
+              On the other hand, ``model_name`` is often returned, and in such cases it is
+              expected that you populate this field with the unmodified model name (such as
+              ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+              model name should you artifically set this field - in which case, the value
+              should be set to the ``model`` or ``model_name`` parameter passed in during
+              invocation.
         ''',
         'properties': dict({
           'model_name': dict({