Merge branch 'main' into add-rstcheck

xrmx · web-flow · commit 23d8e5d54751 · 2025-09-25T09:38:02.000+02:00
diff --git a/.github/workflows/package-prepare-patch-release.yml b/.github/workflows/package-prepare-patch-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 permissions:
@@ -48,7 +49,7 @@ jobs:
 
           version=$(./scripts/eachdist.py version --package ${{ inputs.package }})
 
-          version_file=$(find $path -type f -path "*version*.py")
+          version_file=$(find $path -type f -path "**/version.py")
           file_count=$(echo "$version_file" | wc -l)
 
           if [ "$file_count" -ne 1 ]; then
diff --git a/.github/workflows/package-prepare-release.yml b/.github/workflows/package-prepare-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 
@@ -60,7 +61,7 @@ jobs:
 
           version=${version_dev%.dev}
 
-          version_file=$(find $path -type f -path "*version*.py")
+          version_file=$(find $path -type f -path "**/version.py")
           file_count=$(echo "$version_file" | wc -l)
 
           if [ "$file_count" -ne 1 ]; then
diff --git a/.github/workflows/package-release.yml b/.github/workflows/package-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 permissions:
diff --git a/docs/instrumentation-genai/util.rst b/docs/instrumentation-genai/util.rst
@@ -21,7 +21,7 @@ OpenTelemetry Python - GenAI Util
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.util.genai.upload_hook
+.. automodule:: opentelemetry.util.genai.completion_hook
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml
@@ -26,7 +26,9 @@ classifiers = [
 dependencies = [
   "opentelemetry-api ~= 1.28",
   "opentelemetry-instrumentation ~= 0.58b0",
-  "opentelemetry-util-genai == 0.1b0.dev",
+  # TODO https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3786: restrict
+  # version after the first release
+  "opentelemetry-util-genai",
   "opentelemetry-semantic-conventions ~= 0.58b0",
 ]
 
diff --git a/instrumentation/opentelemetry-instrumentation-botocore/src/opentelemetry/instrumentation/botocore/extensions/bedrock_utils.py b/instrumentation/opentelemetry-instrumentation-botocore/src/opentelemetry/instrumentation/botocore/extensions/bedrock_utils.py
@@ -117,7 +117,7 @@ def _process_event(self, event):
                         self._content_block["toolUse"]["input"] = json.loads(
                             self._tool_json_input_buf
                         )
-                    except json.DecodeError:
+                    except json.JSONDecodeError:
                         self._content_block["toolUse"]["input"] = (
                             self._tool_json_input_buf
                         )
diff --git a/util/opentelemetry-util-genai/CHANGELOG.md b/util/opentelemetry-util-genai/CHANGELOG.md
@@ -7,12 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-- Add upload hook to genai utils to implement semconv v1.37.
+- Add completion hook to genai utils to implement semconv v1.37.
 
-  The hook uses [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) to support
-  various pluggable backends.
+  Includes a hook implementation using
+  [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) to support uploading to various
+  pluggable backends.
+
+  ([#3780](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3780))
   ([#3752](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3752))
-  ([#3759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3752))
+  ([#3759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3759))
   ([#3763](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3763))
 - Add a utility to parse the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable.
   Add `gen_ai_latest_experimental` as a new value to the Sem Conv stability flag ([#3716](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3716)).
diff --git a/util/opentelemetry-util-genai/pyproject.toml b/util/opentelemetry-util-genai/pyproject.toml
@@ -30,8 +30,8 @@ dependencies = [
   "opentelemetry-api>=1.31.0",
 ]
 
-[project.entry-points.opentelemetry_genai_upload_hook]
-fsspec = "opentelemetry.util.genai._fsspec_upload:fsspec_upload_hook"
+[project.entry-points.opentelemetry_genai_completion_hook]
+fsspec_upload = "opentelemetry.util.genai._fsspec_upload:fsspec_completion_upload_hook"
 
 [project.optional-dependencies]
 test = ["pytest>=7.0.0"]
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/__init__.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/__init__.py
@@ -16,24 +16,27 @@
 
 from os import environ
 
+from opentelemetry.util.genai.completion_hook import (
+    CompletionHook,
+    _NoOpCompletionHook,
+)
 from opentelemetry.util.genai.environment_variables import (
     OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH,
 )
-from opentelemetry.util.genai.upload_hook import UploadHook, _NoOpUploadHook
 
 
-def fsspec_upload_hook() -> UploadHook:
+def fsspec_completion_upload_hook() -> CompletionHook:
     # If fsspec is not installed the hook will be a no-op.
     try:
         # pylint: disable=import-outside-toplevel
-        from opentelemetry.util.genai._fsspec_upload.fsspec_hook import (
-            FsspecUploadHook,
+        from opentelemetry.util.genai._fsspec_upload.completion_hook import (
+            FsspecUploadCompletionHook,
         )
     except ImportError:
-        return _NoOpUploadHook()
+        return _NoOpCompletionHook()
 
     base_path = environ.get(OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH)
     if not base_path:
-        return _NoOpUploadHook()
+        return _NoOpCompletionHook()
 
-    return FsspecUploadHook(base_path=base_path)
+    return FsspecUploadCompletionHook(base_path=base_path)
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/completion_hook.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/completion_hook.py
@@ -34,7 +34,7 @@
 from opentelemetry.semconv._incubating.attributes import gen_ai_attributes
 from opentelemetry.trace import Span
 from opentelemetry.util.genai import types
-from opentelemetry.util.genai.upload_hook import UploadHook
+from opentelemetry.util.genai.completion_hook import CompletionHook
 
 GEN_AI_INPUT_MESSAGES_REF: Final = (
     gen_ai_attributes.GEN_AI_INPUT_MESSAGES + "_ref"
@@ -75,12 +75,12 @@ def fsspec_open(urlpath: str, mode: Literal["w"]) -> TextIO:
     return cast(TextIO, fsspec.open(urlpath, mode))  # pyright: ignore[reportUnknownMemberType]
 
 
-class FsspecUploadHook(UploadHook):
-    """An upload hook using ``fsspec`` to upload to external storage
+class FsspecUploadCompletionHook(CompletionHook):
+    """An completion hook using ``fsspec`` to upload to external storage
 
     This function can be used as the
-    :func:`~opentelemetry.util.genai.upload_hook.load_upload_hook` implementation by
-    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK` to ``fsspec``.
+    :func:`~opentelemetry.util.genai.completion_hook.load_completion_hook` implementation by
+    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` to ``fsspec_upload``.
     :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` must be configured to specify the
     base path for uploads.
 
@@ -128,7 +128,7 @@ def done(future: Future[None]) -> None:
                 fut.add_done_callback(done)
             except RuntimeError:
                 _logger.info(
-                    "attempting to upload file after FsspecUploadHook.shutdown() was already called"
+                    "attempting to upload file after FsspecUploadCompletionHook.shutdown() was already called"
                 )
                 self._semaphore.release()
 
@@ -161,7 +161,7 @@ def _do_upload(
                 cls=Base64JsonEncoder,
             )
 
-    def upload(
+    def on_completion(
         self,
         *,
         inputs: list[types.InputMessage],
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/completion_hook.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/completion_hook.py
@@ -12,13 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""This module defines the generic hooks for GenAI content uploading
+"""This module defines the generic hooks for GenAI content completion
 
 The hooks are specified as part of semconv in `Uploading content to external storage
 <https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/gen-ai/gen-ai-spans.md#uploading-content-to-external-storage>`__.
 
-This module defines the `UploadHook` type that custom implementations should implement, and a
-`load_upload_hook` function to load it from an entry point.
+This module defines the `CompletionHook` type that custom implementations should implement, and a
+`load_completion_hook` function to load it from an entry point.
 """
 
 from __future__ import annotations
@@ -34,18 +34,18 @@
 )
 from opentelemetry.util.genai import types
 from opentelemetry.util.genai.environment_variables import (
-    OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK,
+    OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK,
 )
 
 _logger = logging.getLogger(__name__)
 
 
 @runtime_checkable
-class UploadHook(Protocol):
-    """A hook to upload GenAI content to an external storage.
+class CompletionHook(Protocol):
+    """A hook to be called on completion of a GenAI operation.
 
     This is the interface for a hook that can be
-    used to upload GenAI content to an external storage. The hook is a
+    used to capture GenAI content on completion. The hook is a
     callable that takes the inputs, outputs, and system instruction of a
     GenAI interaction, as well as the span and log record associated with
     it.
@@ -66,7 +66,7 @@ class UploadHook(Protocol):
             interaction.
     """
 
-    def upload(
+    def on_completion(
         self,
         *,
         inputs: list[types.InputMessage],
@@ -77,43 +77,47 @@ def upload(
     ) -> None: ...
 
 
-class _NoOpUploadHook(UploadHook):
-    def upload(self, **kwargs: Any) -> None:
+class _NoOpCompletionHook(CompletionHook):
+    def on_completion(self, **kwargs: Any) -> None:
         return None
 
 
-def load_upload_hook() -> UploadHook:
-    """Load the upload hook from entry point or return a noop implementation
+def load_completion_hook() -> CompletionHook:
+    """Load the completion hook from entry point or return a noop implementation
 
-    This function loads an upload hook from the entry point group
-    ``opentelemetry_genai_upload_hook`` with name coming from
-    :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK`. If one can't be found, returns a no-op
+    This function loads an completion hook from the entry point group
+    ``opentelemetry_genai_completion_hook`` with name coming from
+    :envvar:`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK`. If one can't be found, returns a no-op
     implementation.
     """
-    hook_name = environ.get(OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK, None)
+    hook_name = environ.get(OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK, None)
     if not hook_name:
-        return _NoOpUploadHook()
+        return _NoOpCompletionHook()
 
-    for entry_point in entry_points(group="opentelemetry_genai_upload_hook"):  # pyright: ignore[reportUnknownVariableType]
+    for entry_point in entry_points(  # pyright: ignore[reportUnknownVariableType]
+        group="opentelemetry_genai_completion_hook"
+    ):
         name = cast(str, entry_point.name)  # pyright: ignore[reportUnknownMemberType]
         try:
             if hook_name != name:
                 continue
 
             hook = entry_point.load()()  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
-            if not isinstance(hook, UploadHook):
-                _logger.debug("%s is not a valid UploadHook. Using noop", name)
+            if not isinstance(hook, CompletionHook):
+                _logger.debug(
+                    "%s is not a valid CompletionHook. Using noop", name
+                )
                 continue
 
-            _logger.debug("Using UploadHook %s", name)
+            _logger.debug("Using CompletionHook %s", name)
             return hook
 
         except Exception:  # pylint: disable=broad-except
             _logger.exception(
-                "UploadHook %s configuration failed. Using noop", name
+                "CompletionHook %s configuration failed. Using noop", name
             )
 
-    return _NoOpUploadHook()
+    return _NoOpCompletionHook()
 
 
-__all__ = ["UploadHook", "load_upload_hook"]
+__all__ = ["CompletionHook", "load_completion_hook"]
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py
@@ -16,11 +16,11 @@
     "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
 )
 
-OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK = (
-    "OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK"
+OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK = (
+    "OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK"
 )
 """
-.. envvar:: OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK
+.. envvar:: OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK
 """
 
 OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH = (
diff --git a/util/opentelemetry-util-genai/tests/test_completion_hook.py b/util/opentelemetry-util-genai/tests/test_completion_hook.py
diff --git a/util/opentelemetry-util-genai/tests/test_fsspec_upload.py b/util/opentelemetry-util-genai/tests/test_fsspec_upload.py
diff --git a/util/opentelemetry-util-genai/tests/test_upload_hook.py b/util/opentelemetry-util-genai/tests/test_upload_hook.py

Original file line number	Diff line number	Diff line change
`@@ -117,7 +117,7 @@ def _process_event(self, event):`
`117`	`117`	`self._content_block["toolUse"]["input"] = json.loads(`
`118`	`118`	`self._tool_json_input_buf`
`119`	`119`	`)`
`120`		`- except json.DecodeError:`
	`120`	`+ except json.JSONDecodeError:`
`121`	`121`	`self._content_block["toolUse"]["input"] = (`
`122`	`122`	`self._tool_json_input_buf`
`123`	`123`	`)`
Original file line number	Diff line number	Diff line change
`@@ -30,8 +30,8 @@ dependencies = [`
`30`	`30`	`"opentelemetry-api>=1.31.0",`
`31`	`31`	`]`
`32`	`32`
`33`		`-[project.entry-points.opentelemetry_genai_upload_hook]`
`34`		`-fsspec = "opentelemetry.util.genai._fsspec_upload:fsspec_upload_hook"`
	`33`	`+[project.entry-points.opentelemetry_genai_completion_hook]`
	`34`	`+fsspec_upload = "opentelemetry.util.genai._fsspec_upload:fsspec_completion_upload_hook"`
`35`	`35`
`36`	`36`	`[project.optional-dependencies]`
`37`	`37`	`test = ["pytest>=7.0.0"]`