feat(util-genai): refactor and make API smaller and more user-friendly (open-telemetry#4391)

* Refactor public API on GenAI utils

* more lint

* review feedback

* update tests to use named params

* address some of the comments

* up

* fix failing checks and clean up imports

* lint

* lint

* fix lint

* replace @deprecated with docstring info to avoid warnings for users

* up

* common code for context manager

Author: lmolkova

.gitignore

@@ -61,3 +61,8 @@ target
 
 # Benchmark result files
 *-benchmark.json
+
+# opentelemetry-admin jobs
+opentelemetry-admin-jobs.txt
+
+.claude/settings.local.json

instrumentation-genai/AGENTS.md

@@ -0,0 +1,41 @@
+# 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 {Error}` 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.

instrumentation-genai/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

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

@@ -26,7 +26,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.types import (
+    Error,
+    LLMInvocation,  # TODO: migrate to InferenceInvocation
+)
 from opentelemetry.util.genai.utils import (
     should_capture_content_on_spans_in_experimental_mode,
 )

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

@@ -31,7 +31,7 @@
 from opentelemetry.util.genai.handler import TelemetryHandler
 from opentelemetry.util.genai.types import (
     Error,
-    LLMInvocation,
+    LLMInvocation,  # TODO: migrate to InferenceInvocation
 )
 
 from .messages_extractors import set_invocation_response_attributes

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

@@ -28,7 +28,7 @@
 from opentelemetry.util.genai.types import (
     Error,
     InputMessage,
-    LLMInvocation,
+    LLMInvocation,  # TODO: migrate to InferenceInvocation
     MessagePart,
     OutputMessage,
     Text,
@@ -158,7 +158,7 @@ def on_chat_model_start(
         self._invocation_manager.add_invocation_state(
             run_id=run_id,
             parent_run_id=parent_run_id,
-            invocation=llm_invocation,
+            invocation=llm_invocation,  # pyright: ignore[reportArgumentType]
         )
 
     def on_llm_end(
@@ -171,7 +171,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,
         ):
             # If the invocation does not exist, we cannot set attributes or end it
             return
@@ -262,7 +263,8 @@ 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,
         ):
             # If the invocation does not exist, we cannot set attributes or end it
             return

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

@@ -25,10 +25,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

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

@@ -28,7 +28,7 @@ dependencies = [
   "opentelemetry-api ~= 1.39",
   "opentelemetry-instrumentation ~= 0.60b0",
   "opentelemetry-semantic-conventions ~= 0.60b0",
-  "opentelemetry-util-genai",
+  "opentelemetry-util-genai >= 0.4b0.dev",
 ]
 
 [project.optional-dependencies]