Refactor public API on GenAI utils

Author: lmolkova

.gitignore

@@ -64,3 +64,5 @@ target
 
 # opentelemetry-admin jobs
 opentelemetry-admin-jobs.txt
+
+.claude*/

CLAUDE.md

@@ -0,0 +1,5 @@
+# OpenTelemetry Python Contrib — Claude Guidelines
+
+**Before writing any code in this repo, you must have read the nearest `AGENTS.md` file
+in that directory or its parents (up to this root).** This is a precondition, not a suggestion.
+Follow the guidelines there in addition to these.

dev-requirements.txt

@@ -1,6 +1,6 @@
 pylint==3.0.2
 httpretty==1.1.4
-pyright==v1.1.404
+pyright==v1.1.408
 sphinx==7.1.2
 sphinx-rtd-theme==2.0.0rc4
 sphinx-autodoc-typehints==1.25.2

instrumentation-genai/AGENTS.md

@@ -0,0 +1,43 @@
+# GenAI Instrumentation — Agent and Contributor Guidelines
+
+Instrumentation packages here wrap specific libraries (OpenAI, Anthropic, etc.) and bridge
+them to the shared telemetry layer in `util/opentelemetry-util-genai`.
+
+## 1. Instrumentation Layer Boundary
+
+Do not call OpenTelemetry APIs (`tracer`, `meter`, `span`, event APIs) directly.
+Always go through `TelemetryHandler` and the invocation objects it returns.
+
+This layer is responsible only for:
+
+- Patching the library
+- Parsing library-specific input/output into invocation fields
+
+Everything else (span creation, metric recording, event emission, context propagation)
+belongs in `util/opentelemetry-util-genai`.
+
+## 2. Invocation Pattern
+
+Use `start_*()` and control span lifetime manually:
+
+```python
+invocation = handler.start_inference(provider, request_model, server_address=..., server_port=...)
+invocation.temperature = ...
+try:
+    response = client.call(...)
+    invocation.response_model_name = response.model
+    invocation.finish_reasons = response.finish_reasons
+    invocation.stop()
+except Exception as exc:
+    invocation.fail(exc)
+    raise
+```
+
+## 3. Exception Handling
+
+- Do not add `raise` statements in instrumentation/telemetry code — validation belongs in
+  tests and callers, not in the instrumentation layer.
+- When catching exceptions from the underlying library to record telemetry, always re-raise
+  the original exception unmodified.
+- Do not wrap, replace, or suppress exceptions — telemetry must be transparent to callers.
+

instrumentation-genai/opentelemetry-instrumentation-anthropic/src/opentelemetry/instrumentation/anthropic/patch.py

@@ -24,7 +24,10 @@
     gen_ai_attributes as GenAIAttributes,
 )
 from opentelemetry.util.genai.handler import TelemetryHandler
-from opentelemetry.util.genai.types import Error, LLMInvocation
+from opentelemetry.util.genai.inference_invocation import (
+    LLMInvocation,  # pyright: ignore[reportDeprecated]  # TODO: migrate to InferenceInvocation
+)
+from opentelemetry.util.genai.types import Error
 from opentelemetry.util.genai.utils import (
     should_capture_content_on_spans_in_experimental_mode,
 )
@@ -89,7 +92,7 @@ def traced_method(
             else params.model
         )
 
-        invocation = LLMInvocation(
+        invocation = LLMInvocation(  # pyright: ignore[reportDeprecated]
             request_model=request_model,
             provider=ANTHROPIC,
             input_messages=get_input_messages(params.messages)
@@ -102,7 +105,7 @@ def traced_method(
         )
 
         # Use manual lifecycle management for both streaming and non-streaming
-        handler.start_llm(invocation)
+        handler.start_llm(invocation)  # pyright: ignore[reportDeprecated]
         try:
             result = wrapped(*args, **kwargs)
             if isinstance(result, AnthropicStream):
@@ -112,10 +115,10 @@ def traced_method(
 
             wrapper = MessageWrapper(result, capture_content)
             wrapper.extract_into(invocation)
-            handler.stop_llm(invocation)
+            handler.stop_llm(invocation)  # pyright: ignore[reportDeprecated]
             return wrapper.message
         except Exception as exc:
-            handler.fail_llm(
+            handler.fail_llm(  # pyright: ignore[reportDeprecated]
                 invocation, Error(message=str(exc), type=type(exc))
             )
             raise

instrumentation-genai/opentelemetry-instrumentation-anthropic/src/opentelemetry/instrumentation/anthropic/wrappers.py

@@ -19,9 +19,11 @@
 from typing import TYPE_CHECKING, Callable, Iterator, Optional
 
 from opentelemetry.util.genai.handler import TelemetryHandler
+from opentelemetry.util.genai.inference_invocation import (
+    LLMInvocation,  # pyright: ignore[reportDeprecated]  # TODO: migrate to InferenceInvocation
+)
 from opentelemetry.util.genai.types import (
     Error,
-    LLMInvocation,
     MessagePart,
     OutputMessage,
 )
@@ -60,7 +62,7 @@ def __init__(self, message: Message, capture_content: bool):
         self._message = message
         self._capture_content = capture_content
 
-    def extract_into(self, invocation: LLMInvocation) -> None:
+    def extract_into(self, invocation: LLMInvocation) -> None:  # pyright: ignore[reportDeprecated]
         """Extract response data into the invocation."""
         if self._message.model:
             invocation.response_model_name = self._message.model
@@ -103,7 +105,7 @@ def __init__(
         self,
         stream: Stream[RawMessageStreamEvent],
         handler: TelemetryHandler,
-        invocation: LLMInvocation,
+        invocation: LLMInvocation,  # pyright: ignore[reportDeprecated]
         capture_content: bool,
     ):
         self._stream = stream
@@ -213,7 +215,7 @@ def _stop(self) -> None:
             "response attribute extraction",
         )
         self._safe_instrumentation(
-            lambda: self._handler.stop_llm(self._invocation),
+            lambda: self._handler.stop_llm(self._invocation),  # pyright: ignore[reportDeprecated]
             "stop_llm",
         )
         self._finalized = True
@@ -222,7 +224,7 @@ def _fail(self, message: str, error_type: type[BaseException]) -> None:
         if self._finalized:
             return
         self._safe_instrumentation(
-            lambda: self._handler.fail_llm(
+            lambda: self._handler.fail_llm(  # pyright: ignore[reportDeprecated]
                 self._invocation, Error(message=message, type=error_type)
             ),
             "fail_llm",

instrumentation-genai/opentelemetry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/callback_handler.py

@@ -25,10 +25,12 @@
     _InvocationManager,
 )
 from opentelemetry.util.genai.handler import TelemetryHandler
+from opentelemetry.util.genai.inference_invocation import (
+    LLMInvocation,  # pyright: ignore[reportDeprecated]  # TODO: migrate to InferenceInvocation
+)
 from opentelemetry.util.genai.types import (
     Error,
     InputMessage,
-    LLMInvocation,
     MessagePart,
     OutputMessage,
     Text,
@@ -140,7 +142,7 @@ def on_chat_model_start(
                     )
                 )
 
-        llm_invocation = LLMInvocation(
+        llm_invocation = LLMInvocation(  # pyright: ignore[reportDeprecated]
             request_model=request_model,
             input_messages=input_messages,
             provider=provider,
@@ -152,7 +154,7 @@ def on_chat_model_start(
             temperature=temperature,
             max_tokens=max_tokens,
         )
-        llm_invocation = self._telemetry_handler.start_llm(
+        llm_invocation = self._telemetry_handler.start_llm(  # pyright: ignore[reportDeprecated]
             invocation=llm_invocation
         )
         self._invocation_manager.add_invocation_state(
@@ -171,7 +173,8 @@ def on_llm_end(
     ) -> None:
         llm_invocation = self._invocation_manager.get_invocation(run_id=run_id)
         if llm_invocation is None or not isinstance(
-            llm_invocation, LLMInvocation
+            llm_invocation,
+            LLMInvocation,  # pyright: ignore[reportDeprecated]
         ):
             # If the invocation does not exist, we cannot set attributes or end it
             return
@@ -246,7 +249,7 @@ def on_llm_end(
             if response_id is not None:
                 llm_invocation.response_id = str(response_id)
 
-        llm_invocation = self._telemetry_handler.stop_llm(
+        llm_invocation = self._telemetry_handler.stop_llm(  # pyright: ignore[reportDeprecated]
             invocation=llm_invocation
         )
         if llm_invocation.span and not llm_invocation.span.is_recording():
@@ -262,13 +265,14 @@ def on_llm_error(
     ) -> None:
         llm_invocation = self._invocation_manager.get_invocation(run_id=run_id)
         if llm_invocation is None or not isinstance(
-            llm_invocation, LLMInvocation
+            llm_invocation,
+            LLMInvocation,  # pyright: ignore[reportDeprecated]
         ):
             # If the invocation does not exist, we cannot set attributes or end it
             return
 
         error_otel = Error(message=str(error), type=type(error))
-        llm_invocation = self._telemetry_handler.fail_llm(
+        llm_invocation = self._telemetry_handler.fail_llm(  # pyright: ignore[reportDeprecated]
             invocation=llm_invocation, error=error_otel
         )
         if llm_invocation.span and not llm_invocation.span.is_recording():

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml

@@ -26,10 +26,10 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api >= 1.37",
+  "opentelemetry-api >= 1.39",
   "opentelemetry-instrumentation >= 0.58b0",
-  "opentelemetry-semantic-conventions >= 0.58b0",
-  "opentelemetry-util-genai"
+  "opentelemetry-semantic-conventions >= 0.60b0",
+  "opentelemetry-util-genai >= 0.4b0.dev"
 ]
 
 [project.optional-dependencies]

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.latest.txt

@@ -50,4 +50,5 @@ grpcio>=1.60.0; implementation_name != "pypy"
 grpcio<1.60.0; implementation_name == "pypy"
 
 -e opentelemetry-instrumentation
+-e util/opentelemetry-util-genai
 -e instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.oldest.txt

@@ -26,10 +26,11 @@ pytest-asyncio==0.21.0
 wrapt==1.16.0
 opentelemetry-exporter-otlp-proto-grpc~=1.30
 opentelemetry-exporter-otlp-proto-http~=1.30
-opentelemetry-api==1.37  # when updating, also update in pyproject.toml
-opentelemetry-sdk==1.37  # when updating, also update in pyproject.toml
-opentelemetry-semantic-conventions==0.58b0  # when updating, also update in pyproject.toml
+opentelemetry-api==1.39  # when updating, also update in pyproject.toml
+opentelemetry-sdk==1.39  # when updating, also update in pyproject.toml
+opentelemetry-semantic-conventions==0.60b0  # when updating, also update in pyproject.toml
 grpcio>=1.60.0; implementation_name != "pypy"
 grpcio<1.60.0; implementation_name == "pypy"
 
+-e util/opentelemetry-util-genai
 -e instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2