fix: standardize finish_reason fallback to empty string across OpenAI, Anthropic, LangChain

Aligns all packages with the Bedrock convention: when finish_reason is
unknown/None, use "" (empty string) instead of fabricating "stop" (OpenAI)
or omitting the key entirely (Anthropic, LangChain).

- OpenAI chat_wrappers: `or "stop"` → `or ""`
- OpenAI completion_wrappers: `or "stop"` → `or ""`
- Anthropic span_utils: conditional `if mapped` → always set with `""` fallback (3 spots)
- LangChain span_utils: conditional `if fr` → always include `finish_reason` with `""` fallback
- Updated tests in all three packages to verify the new behavior

Author: max-deygin-traceloop

packages/opentelemetry-instrumentation-anthropic/opentelemetry/instrumentation/anthropic/span_utils.py

@@ -257,8 +257,7 @@ def _build_output_messages_from_content(response):
             "parts": [{"type": "text", "content": response.get("completion")}],
         }
         mapped = _map_finish_reason(response.get("stop_reason"))
-        if mapped:
-            msg["finish_reason"] = mapped
+        msg["finish_reason"] = mapped if mapped else ""
         return [msg]
 
     if not response.get("content"):
@@ -296,8 +295,7 @@ def _build_output_messages_from_content(response):
         "parts": parts,
     }
     mapped = _map_finish_reason(response.get("stop_reason"))
-    if mapped:
-        msg["finish_reason"] = mapped
+    msg["finish_reason"] = mapped if mapped else ""
     return [msg]
 
 
@@ -449,8 +447,7 @@ def set_streaming_response_attributes(span, complete_response_events):
             "role": "assistant",
             "parts": parts,
         }
-        if finish_reasons:
-            msg["finish_reason"] = finish_reasons[-1]
+        msg["finish_reason"] = finish_reasons[-1] if finish_reasons else ""
         output_messages = [msg]
         set_span_attribute(
             span,

packages/opentelemetry-instrumentation-anthropic/tests/test_semconv_span_attrs.py

@@ -375,6 +375,34 @@ def test_streaming_finish_reasons_set_when_content_tracing_disabled():
     assert GenAIAttributes.GEN_AI_OUTPUT_MESSAGES not in span.attributes
 
 
+def test_finish_reason_empty_string_when_none():
+    """finish_reason must be '' (not omitted) when stop_reason is None (Bedrock convention)."""
+    span = make_span()
+    response = _make_response([_make_text_block("Hello")], stop_reason=None)
+    set_response_attributes(span, response)
+
+    output = json.loads(span.attributes[GenAIAttributes.GEN_AI_OUTPUT_MESSAGES])
+    assert len(output) == 1
+    assert "finish_reason" in output[0], "finish_reason key must always be present"
+    assert output[0]["finish_reason"] == "", (
+        f"Expected '' for missing stop_reason, got '{output[0]['finish_reason']}'"
+    )
+
+
+def test_streaming_finish_reason_empty_string_when_none():
+    """Streaming: finish_reason must be '' when no finish_reason in events."""
+    span = make_span()
+    events = [{"type": "text", "text": "Hello", "index": 0}]
+    set_streaming_response_attributes(span, events)
+
+    raw = span.attributes.get(GenAIAttributes.GEN_AI_OUTPUT_MESSAGES)
+    if raw:
+        output = json.loads(raw)
+        assert output[0]["finish_reason"] == "", (
+            f"Expected '' for missing streaming finish_reason, got '{output[0]['finish_reason']}'"
+        )
+
+
 def test_output_messages_tool_use_response():
     """Tool use in the response should appear as tool_call parts."""
     span = make_span()
@@ -1009,8 +1037,8 @@ def test_image_without_upload_produces_blob_part():
 
 
 def test_streaming_finish_reason_null_omitted_from_json():
-    """When no finish_reason is available, the key must be omitted from
-    gen_ai.output.messages JSON — NOT serialized as null."""
+    """When no finish_reason is available, the key must be present with empty
+    string value — NOT serialized as null, NOT omitted (Bedrock convention)."""
     span = make_span()
     # Event with no finish_reason key at all
     events = [{"type": "text", "text": "Hello world", "index": 0}]
@@ -1020,8 +1048,8 @@ def test_streaming_finish_reason_null_omitted_from_json():
     assert len(output) == 1
     assert output[0]["role"] == "assistant"
     assert output[0]["parts"] == [{"type": "text", "content": "Hello world"}]
-    # finish_reason key must be absent, not null
-    assert "finish_reason" not in output[0]
+    # finish_reason key must be present with empty string fallback
+    assert output[0]["finish_reason"] == ""
 
 
 def test_streaming_finish_reason_none_does_not_set_span_attr():

packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py

@@ -369,9 +369,7 @@ def set_chat_response(span: Span, response: LLMResult) -> None:
                 if tool_calls and isinstance(tool_calls, list):
                     parts.extend(_tool_calls_to_parts(tool_calls))
 
-            msg_obj = {"role": role, "parts": parts}
-            if fr:
-                msg_obj["finish_reason"] = fr
+            msg_obj = {"role": role, "parts": parts, "finish_reason": fr if fr else ""}
             output_messages.append(msg_obj)
 
     if output_messages:

packages/opentelemetry-instrumentation-langchain/tests/test_finish_reasons.py

@@ -111,7 +111,7 @@ def test_no_finish_reason_omits_attribute(self, mock_span, monkeypatch):
         assert GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS not in mock_span.attributes
 
         output = json.loads(mock_span.attributes[GenAIAttributes.GEN_AI_OUTPUT_MESSAGES])
-        assert "finish_reason" not in output[0]
+        assert output[0]["finish_reason"] == ""
 
     def test_empty_generation_info_omits_attribute(self, mock_span, monkeypatch):
         monkeypatch.setattr(

packages/opentelemetry-instrumentation-openai/opentelemetry/instrumentation/openai/shared/chat_wrappers.py

@@ -603,7 +603,7 @@ def _set_output_messages(span, choices):
                     "name": fc_name,
                     "arguments": _parse_arguments(fc_args),
                 })
-        fr = _map_finish_reason(choice.get("finish_reason")) or "stop"
+        fr = _map_finish_reason(choice.get("finish_reason")) or ""
         entry = {"role": "assistant", "parts": parts, "finish_reason": fr}
         if content_filter_results:
             entry["content_filter_results"] = content_filter_results

packages/opentelemetry-instrumentation-openai/opentelemetry/instrumentation/openai/shared/completion_wrappers.py

@@ -190,7 +190,7 @@ def _set_output_messages(span, choices):
 
     messages = []
     for choice in choices:
-        fr = _map_finish_reason(choice.get("finish_reason")) or "stop"
+        fr = _map_finish_reason(choice.get("finish_reason")) or ""
         entry = {
             "role": "assistant",
             "parts": [{"content": choice.get("text"), "type": "text"}],

packages/opentelemetry-instrumentation-openai/tests/traces/test_semconv_compliance.py

@@ -454,6 +454,62 @@ def test_refusal_captured_in_output_messages(self, mock_span):
         )
 
 
+# ---------------------------------------------------------------------------
+# finish_reason fallback: must be "" when unknown, not fabricated "stop"
+# ---------------------------------------------------------------------------
+
+class TestFinishReasonFallback:
+    """finish_reason in output messages must be '' when unknown (Bedrock convention)."""
+
+    def test_chat_missing_finish_reason_uses_empty_string(self, mock_span):
+        choices = [
+            {
+                "message": {"role": "assistant", "content": "Hello"},
+                "finish_reason": None,
+            }
+        ]
+        _set_output_messages(mock_span, choices)
+        result = _get_output_messages(mock_span)
+        assert result[0]["finish_reason"] == "", (
+            f"Expected '' for missing finish_reason, got '{result[0]['finish_reason']}'"
+        )
+
+    def test_chat_present_finish_reason_preserved(self, mock_span):
+        choices = [
+            {
+                "message": {"role": "assistant", "content": "Hi"},
+                "finish_reason": "stop",
+            }
+        ]
+        _set_output_messages(mock_span, choices)
+        result = _get_output_messages(mock_span)
+        assert result[0]["finish_reason"] == "stop"
+
+    def test_chat_tool_calls_finish_reason_mapped(self, mock_span):
+        choices = [
+            {
+                "message": {"role": "assistant", "content": None, "tool_calls": [
+                    {"id": "call_1", "type": "function", "function": {"name": "f", "arguments": "{}"}}
+                ]},
+                "finish_reason": "tool_calls",
+            }
+        ]
+        _set_output_messages(mock_span, choices)
+        result = _get_output_messages(mock_span)
+        assert result[0]["finish_reason"] == "tool_call"
+
+    def test_completion_missing_finish_reason_uses_empty_string(self, mock_span):
+        from opentelemetry.instrumentation.openai.shared.completion_wrappers import (
+            _set_output_messages as _set_completion_output_messages,
+        )
+        choices = [{"text": "Hello world", "finish_reason": None}]
+        _set_completion_output_messages(mock_span, choices)
+        result = _get_output_messages(mock_span)
+        assert result[0]["finish_reason"] == "", (
+            f"Expected '' for missing finish_reason, got '{result[0]['finish_reason']}'"
+        )
+
+
 # ---------------------------------------------------------------------------
 # P2-4: Metrics must map finish reason values correctly
 # ---------------------------------------------------------------------------