openinference-instrumentation-agentspec 0.1.0__tar.gz

openinference_instrumentation_agentspec-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# vendored virtual environments
+.venv
+
+# gradio work directory
+.gradio

openinference_instrumentation_agentspec-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

openinference_instrumentation_agentspec-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: openinference-instrumentation-agentspec
+Version: 0.1.0
+Summary: OpenInference Open Agent Spec Instrumentation
+Project-URL: Homepage, https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-agentspec
+Author: Oracle
+Author-email: OpenInference Authors <oss@arize.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Requires-Dist: openinference-instrumentation>=0.1.27
+Requires-Dist: openinference-semantic-conventions>=0.1.21
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-instrumentation
+Requires-Dist: opentelemetry-semantic-conventions
+Requires-Dist: typing-extensions
+Requires-Dist: wrapt
+Provides-Extra: instruments
+Requires-Dist: opentelemetry-sdk; extra == 'instruments'
+Requires-Dist: pyagentspec>=26.1.0; extra == 'instruments'
+Description-Content-Type: text/markdown
+
+# OpenInference Agent Spec Instrumentation
+
+Python auto-instrumentation library for Agent Spec.
+
+Open Agent Spec (Agent Spec) is a portable, platform-agnostic configuration language that allows Agents and Agentic Systems to be described with high fidelity.
+It defines the conceptual building blocks—called components—that make up agents in typical agent-based systems.
+This includes the properties that configure each component and the semantics that govern their behavior.
+
+Agent Spec Tracing is an extension of Agent Spec that standardizes how agent and flow executions emit traces.
+It enables:
+- Runtime adapters to emit consistent traces across different frameworks.
+- Consumers (observability backends, UIs, developer tooling) to ingest one standardized format regardless of the producer.
+
+You can find more information about Agent Spec and Agent Spec Tracing at:
+- Agent Spec: https://oracle.github.io/agent-spec/development/agentspec/index.html
+- Tracing: https://oracle.github.io/agent-spec/development/agentspec/tracing.html
+
+The traces emitted by this instrumentation are fully OpenTelemetry compatible and can be sent to an OpenTelemetry 
+collector for viewing, such as [`arize-phoenix`](https://github.com/Arize-ai/phoenix)
+
+## Installation
+
+```shell
+pip install openinference-instrumentation-agentspec
+```
+
+## Quickstart
+
+In this example we will instrument a small program that uses Agent Spec Tracing and observe 
+the traces via [`arize-phoenix`](https://github.com/Arize-ai/phoenix).
+
+Install packages.
+
+```shell
+pip install openinference-instrumentation-agentspec arize-phoenix opentelemetry-sdk opentelemetry-exporter-otlp
+```
+
+Start the phoenix server so that it is ready to collect traces.
+The Phoenix server runs entirely on your machine and does not send data over the internet.
+
+```shell
+phoenix serve
+```
+
+In a python file (e.g., `agentspec_agent.py`) , set up the `AgentSpecInstrumentor` and configure 
+the tracer to send traces to Phoenix.
+
+```python
+from pyagentspec.adapters.langgraph import AgentSpecLoader
+from pyagentspec.agent import Agent
+from pyagentspec.llms import OpenAiConfig
+
+agent = Agent(
+    name="assistant",
+    description="An general purpose agent without tools",
+    llm_config=OpenAiConfig(name="openai-gpt-5-mini", model_id="gpt-5-mini"),
+    system_prompt="You are a helpful assistant. Help the user answering politely.",
+)
+
+langgraph_agent = AgentSpecLoader().load_component(agent)
+
+from phoenix.otel import register
+
+from openinference.instrumentation.agentspec import AgentSpecInstrumentor
+
+tracer_provider = register(batch=True, project_name="hello-world-app")
+AgentSpecInstrumentor().instrument(tracer_provider=tracer_provider)
+
+while True:
+    user_input = input("USER  >>> ")
+    if user_input.lower() in ["exit", "quit"]:
+        break
+    response = langgraph_agent.invoke(
+        input={"messages": [{"role": "user", "content": user_input}]},
+        config={"configurable": {"thread_id": "1"}},
+    )
+    print("AGENT >>>", response['messages'][-1].content.strip())
+```
+
+Now simply run the python file and observe the traces in Phoenix.
+
+```shell
+python agentspec_agent.py
+```

openinference_instrumentation_agentspec-0.1.0/README.md

@@ -0,0 +1,84 @@
+# OpenInference Agent Spec Instrumentation
+
+Python auto-instrumentation library for Agent Spec.
+
+Open Agent Spec (Agent Spec) is a portable, platform-agnostic configuration language that allows Agents and Agentic Systems to be described with high fidelity.
+It defines the conceptual building blocks—called components—that make up agents in typical agent-based systems.
+This includes the properties that configure each component and the semantics that govern their behavior.
+
+Agent Spec Tracing is an extension of Agent Spec that standardizes how agent and flow executions emit traces.
+It enables:
+- Runtime adapters to emit consistent traces across different frameworks.
+- Consumers (observability backends, UIs, developer tooling) to ingest one standardized format regardless of the producer.
+
+You can find more information about Agent Spec and Agent Spec Tracing at:
+- Agent Spec: https://oracle.github.io/agent-spec/development/agentspec/index.html
+- Tracing: https://oracle.github.io/agent-spec/development/agentspec/tracing.html
+
+The traces emitted by this instrumentation are fully OpenTelemetry compatible and can be sent to an OpenTelemetry 
+collector for viewing, such as [`arize-phoenix`](https://github.com/Arize-ai/phoenix)
+
+## Installation
+
+```shell
+pip install openinference-instrumentation-agentspec
+```
+
+## Quickstart
+
+In this example we will instrument a small program that uses Agent Spec Tracing and observe 
+the traces via [`arize-phoenix`](https://github.com/Arize-ai/phoenix).
+
+Install packages.
+
+```shell
+pip install openinference-instrumentation-agentspec arize-phoenix opentelemetry-sdk opentelemetry-exporter-otlp
+```
+
+Start the phoenix server so that it is ready to collect traces.
+The Phoenix server runs entirely on your machine and does not send data over the internet.
+
+```shell
+phoenix serve
+```
+
+In a python file (e.g., `agentspec_agent.py`) , set up the `AgentSpecInstrumentor` and configure 
+the tracer to send traces to Phoenix.
+
+```python
+from pyagentspec.adapters.langgraph import AgentSpecLoader
+from pyagentspec.agent import Agent
+from pyagentspec.llms import OpenAiConfig
+
+agent = Agent(
+    name="assistant",
+    description="An general purpose agent without tools",
+    llm_config=OpenAiConfig(name="openai-gpt-5-mini", model_id="gpt-5-mini"),
+    system_prompt="You are a helpful assistant. Help the user answering politely.",
+)
+
+langgraph_agent = AgentSpecLoader().load_component(agent)
+
+from phoenix.otel import register
+
+from openinference.instrumentation.agentspec import AgentSpecInstrumentor
+
+tracer_provider = register(batch=True, project_name="hello-world-app")
+AgentSpecInstrumentor().instrument(tracer_provider=tracer_provider)
+
+while True:
+    user_input = input("USER  >>> ")
+    if user_input.lower() in ["exit", "quit"]:
+        break
+    response = langgraph_agent.invoke(
+        input={"messages": [{"role": "user", "content": user_input}]},
+        config={"configurable": {"thread_id": "1"}},
+    )
+    print("AGENT >>>", response['messages'][-1].content.strip())
+```
+
+Now simply run the python file and observe the traces in Phoenix.
+
+```shell
+python agentspec_agent.py
+```

openinference_instrumentation_agentspec-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openinference-instrumentation-agentspec"
+dynamic = ["version"]
+description = "OpenInference Open Agent Spec Instrumentation"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10, <3.15"
+authors = [
+  { name = "OpenInference Authors", email = "oss@arize.com" },
+  { name = "Oracle", email = "" },
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "opentelemetry-api",
+  "opentelemetry-instrumentation",
+  "opentelemetry-semantic-conventions",
+  "openinference-instrumentation>=0.1.27",
+  "openinference-semantic-conventions>=0.1.21",
+  "typing-extensions",
+  "wrapt",
+]
+
+[project.optional-dependencies]
+instruments = [
+  "opentelemetry-sdk",
+  "pyagentspec >= 26.1.0",
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+agentspec = "openinference.instrumentation.agentspec:AgentSpecInstrumentor"
+
+[project.entry-points.openinference_instrumentor]
+agentspec = "openinference.instrumentation.agentspec:AgentSpecInstrumentor"
+
+[project.urls]
+Homepage = "https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-agentspec"
+
+[tool.hatch.version]
+path = "src/openinference/instrumentation/agentspec/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openinference"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = [
+  "tests",
+]
+
+[tool.mypy]
+strict = true
+explicit_package_bases = true
+exclude = [
+  "examples",
+  "dist",
+  "sdist",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint.per-file-ignores]
+"*.ipynb" = ["E402", "E501"]
+"examples/*" = ["E501"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.lint.isort]
+force-single-line = false

openinference_instrumentation_agentspec-0.1.0/src/openinference/instrumentation/agentspec/__init__.py

@@ -0,0 +1,88 @@
+import logging
+import warnings
+from contextlib import contextmanager
+from typing import Any, Collection, Generator
+
+from opentelemetry import trace as trace_api
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor  # type: ignore
+from opentelemetry.sdk.trace.export import SpanProcessor as OtelSdkSpanProcessor  # type: ignore
+from pyagentspec.tracing.spanprocessor import SpanProcessor as AgentSpecSpanProcessor
+
+from openinference.instrumentation.agentspec._openinference_spanprocessor import (
+    OpenInferenceSpanProcessor,
+)
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class AgentSpecInstrumentor(BaseInstrumentor):  # type: ignore
+    """
+    An instrumentor for Agent Spec Tracing
+    """
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return ["pyagentspec >= 26.1.0"]
+
+    def _instrument(self, **kwargs: Any) -> None:
+        if not (tracer_provider := kwargs.get("tracer_provider", None)):
+            tracer_provider = trace_api.get_tracer_provider()
+        if not (resource := kwargs.get("resource", None)):
+            if hasattr(tracer_provider, "resource"):
+                resource = tracer_provider.resource
+        mask_sensitive_information = kwargs.get("mask_sensitive_information", False)
+
+        from pyagentspec.tracing.trace import Trace, get_trace
+
+        if get_trace() is not None:
+            raise ValueError(
+                "Agent Spec Trace already active, instrumentation is not allowed. "
+                "Close any existing Agent Spec Trace before instrumenting your code."
+            )
+
+        # Look for the span processors attached to the tracer provider
+        # and wrap them in an OTel Agent Spec Span Processor
+        tp_span_processors: list[OtelSdkSpanProcessor] = []
+        if hasattr(tracer_provider, "_active_span_processor"):
+            tp_span_processors = getattr(
+                tracer_provider._active_span_processor, "_span_processors", []
+            )
+        agentspec_spanprocessors: list[AgentSpecSpanProcessor] = [
+            OpenInferenceSpanProcessor(
+                otel_span_processor=otel_span_processor,
+                resource=resource,
+                mask_sensitive_information=mask_sensitive_information,
+            )
+            for otel_span_processor in tp_span_processors
+        ]
+        if len(agentspec_spanprocessors) == 0:
+            warnings.warn(
+                "Instrumenting a TracerProvider that has no SpanProcessors attached", UserWarning
+            )
+
+        trace = Trace(span_processors=agentspec_spanprocessors, shutdown_on_exit=False)
+        trace._start()
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        from pyagentspec.tracing.trace import get_trace
+
+        trace = get_trace()
+        if trace is not None:
+            try:
+                trace._end()
+            except Exception as e:
+                # Whatever happens we do not crash during the final shutdown, but we warn the user
+                logger.warning(f"Exception raised during Trace `end`: {e}")
+
+    @contextmanager
+    def instrument_context(self, **kwargs: Any) -> Generator[None, Any, None]:
+        """Context manager to instrument and uninstrument the library"""
+        self.instrument(**kwargs)
+        try:
+            yield
+        finally:
+            if self.is_instrumented_by_opentelemetry:
+                self.uninstrument(**kwargs)
+
+
+__all__ = ["AgentSpecInstrumentor", "OpenInferenceSpanProcessor"]

openinference_instrumentation_agentspec-0.1.0/src/openinference/instrumentation/agentspec/_openinference_spanprocessor.py

@@ -0,0 +1,240 @@
+from typing import Any, Dict, Optional
+
+from opentelemetry.sdk.trace import Resource as OtelSdkResource  # type: ignore
+from opentelemetry.sdk.trace.export import BatchSpanProcessor as OtelSdkBatchSpanProcessor
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor as OtelSdkSimpleSpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter as OtelSdkSpanExporter
+from opentelemetry.sdk.trace.export import SpanProcessor as OtelSdkSpanProcessor  # type: ignore
+from pyagentspec.property import _empty_default
+from pyagentspec.tools import Tool as AgentSpecTool
+from pyagentspec.tracing.events import Event as AgentSpecEvent
+from pyagentspec.tracing.events import LlmGenerationRequest as AgentSpecLlmGenerationRequest
+from pyagentspec.tracing.events import LlmGenerationResponse as AgentSpecLlmGenerationResponse
+from pyagentspec.tracing.events import ToolExecutionRequest as AgentSpecToolExecutionRequest
+from pyagentspec.tracing.spans import AgentExecutionSpan as AgentSpecAgentExecutionSpan
+from pyagentspec.tracing.spans import LlmGenerationSpan as AgentSpecLlmGenerationSpan
+from pyagentspec.tracing.spans import Span as AgentSpecSpan
+from pyagentspec.tracing.spans import ToolExecutionSpan as AgentSpecToolExecutionSpan
+
+from openinference.instrumentation.agentspec._opentelemetry_spanprocessor import (
+    _OtelSpanProcessor,
+    _try_json_serialization,
+)
+from openinference.semconv.trace import (
+    OpenInferenceSpanKindValues,
+    SpanAttributes,
+    ToolAttributes,
+    ToolCallAttributes,
+)
+
+
+def _get_event_of_given_type(
+    span: AgentSpecSpan, event_type: type[AgentSpecEvent]
+) -> Optional[AgentSpecEvent]:
+    try:
+        return next(event for event in span.events if isinstance(event, event_type))
+    except StopIteration:
+        return None
+
+
+def _get_tool_json_schema(tool: AgentSpecTool) -> Dict[str, Any]:
+    # Return tool's json schema as per OpenAI tools format
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": {
+                "type": "object",
+                "properties": {p.title: p.json_schema for p in tool.inputs or []},
+                "required": [p.title for p in (tool.inputs or []) if p.default is _empty_default],
+            },
+        },
+    }
+
+
+def _to_open_inference_format_tracing_info(
+    span: AgentSpecSpan, mask_sensitive_information: bool = True
+) -> Dict[str, Any]:
+    # See https://arize-ai.github.io/openinference/spec/ for naming conventions
+    trace = span._trace
+    tracing_info: Dict[str, Any] = span.model_dump(mask_sensitive_information=mask_sensitive_information)
+    tracing_info[SpanAttributes.SESSION_ID] = trace.id if trace else None
+    # The default value we use for span kind is CHAIN. We will overwrite if we find a better fit.
+    tracing_info[SpanAttributes.OPENINFERENCE_SPAN_KIND] = OpenInferenceSpanKindValues.CHAIN.value
+    if isinstance(span, AgentSpecAgentExecutionSpan):
+        tracing_info[SpanAttributes.OPENINFERENCE_SPAN_KIND] = (
+            OpenInferenceSpanKindValues.AGENT.value
+        )
+        tracing_info[SpanAttributes.AGENT_NAME] = span.agent.name
+        # Agent inputs and outputs are set at the end
+    elif isinstance(span, AgentSpecLlmGenerationSpan):
+        llm_info = tracing_info.pop("llm_config")
+        tracing_info[SpanAttributes.OPENINFERENCE_SPAN_KIND] = OpenInferenceSpanKindValues.LLM.value
+        tracing_info[SpanAttributes.LLM_MODEL_NAME] = llm_info.get("model_id") or llm_info.get("name") or "unknown"
+        tracing_info[SpanAttributes.LLM_INVOCATION_PARAMETERS] = _try_json_serialization(
+            {
+                k: v
+                for k, v in (llm_info.get("default_generation_parameters") or {}).items()
+                if v is not None
+            }
+        )
+        # Start event for AgentSpecLlmGenerationSpan is a AgentSpecLlmGenerationRequest
+        start_event = _get_event_of_given_type(span, AgentSpecLlmGenerationRequest)
+        if start_event is not None:
+            # If we find one, we update all the information related to the LLM requests
+            # in the Span info
+            event_info = start_event.model_dump(
+                mask_sensitive_information=mask_sensitive_information
+            )
+            if event_info["llm_generation_config"]:
+                # Update generation parameters with the specific ones for this call
+                tracing_info[SpanAttributes.LLM_INVOCATION_PARAMETERS] = _try_json_serialization(
+                    {
+                        k: v
+                        for k, v in (event_info.get("llm_generation_config") or {}).items()
+                        if v is not None
+                    }
+                )
+            # LLM tools seem to require the JSON schema of the tools in OpenAI format
+            tracing_info[SpanAttributes.LLM_TOOLS] = [
+                {
+                    ToolAttributes.TOOL_JSON_SCHEMA: _try_json_serialization(
+                        _get_tool_json_schema(tool)
+                    )
+                }
+                for tool in start_event.tools
+            ]
+            tracing_info[SpanAttributes.LLM_INPUT_MESSAGES] = [
+                # The prompt contains the list of messages dumped in dict format,
+                # we can use that directly
+                {"message": e}
+                for e in event_info["prompt"]
+            ]
+        # End event for AgentSpecLlmGenerationSpan is a AgentSpecLlmGenerationResponse
+        end_event = _get_event_of_given_type(span, AgentSpecLlmGenerationResponse)
+        if end_event is not None:
+            # If we find one, we update all the information related to the LLM response
+            # in the Span info
+            event_info = end_event.model_dump(mask_sensitive_information=mask_sensitive_information)
+            tracing_info[SpanAttributes.LLM_OUTPUT_MESSAGES] = [
+                {
+                    "message": {
+                        "content": event_info.pop("content"),
+                        "tool_calls": [
+                            {
+                                "tool_call.id": tool_call["call_id"],
+                                "tool_call.function.name": tool_call["tool_name"],
+                                "tool_call.function.arguments": tool_call["arguments"],
+                            }
+                            for tool_call in event_info["tool_calls"]
+                            if isinstance(tool_call, dict)
+                        ],
+                        "role": "assistant",
+                    },
+                }
+            ]
+            tracing_info[SpanAttributes.LLM_TOKEN_COUNT_COMPLETION] = event_info.pop(
+                "output_tokens"
+            )
+            tracing_info[SpanAttributes.LLM_TOKEN_COUNT_PROMPT] = event_info.pop("input_tokens")
+    elif isinstance(span, AgentSpecToolExecutionSpan):
+        tracing_info[SpanAttributes.OPENINFERENCE_SPAN_KIND] = (
+            OpenInferenceSpanKindValues.TOOL.value
+        )
+        tool_info = tracing_info.pop("tool")
+        tracing_info[SpanAttributes.TOOL_NAME] = tool_info["name"]
+        tracing_info[SpanAttributes.TOOL_DESCRIPTION] = tool_info["description"]
+        tracing_info[ToolAttributes.TOOL_JSON_SCHEMA] = _try_json_serialization(
+            _get_tool_json_schema(span.tool)
+        )
+        # Start event for AgentSpecToolExecutionSpan is a AgentSpecToolExecutionRequest
+        start_event = _get_event_of_given_type(span, AgentSpecToolExecutionRequest)
+        if start_event is not None:
+            # If we find one, we update all the information related to the tool execution
+            # in the Span info
+            event_info = start_event.model_dump(
+                mask_sensitive_information=mask_sensitive_information
+            )
+            tracing_info[ToolCallAttributes.TOOL_CALL_ID] = event_info["request_id"]
+            tracing_info[ToolCallAttributes.TOOL_CALL_FUNCTION_NAME] = tracing_info[
+                SpanAttributes.TOOL_NAME
+            ]
+            tracing_info[SpanAttributes.TOOL_PARAMETERS] = event_info["inputs"]
+            tracing_info[ToolCallAttributes.TOOL_CALL_FUNCTION_ARGUMENTS_JSON] = (
+                _try_json_serialization(event_info["inputs"])
+            )
+
+    if (
+        tracing_info[SpanAttributes.OPENINFERENCE_SPAN_KIND]
+        != OpenInferenceSpanKindValues.LLM.value
+    ):
+        # Spans often have generic `inputs` and `outputs`. When available, we use start event
+        # `inputs` attribute as input and end event `outputs` attribute as output of the span
+        start_event = span.events[0] if len(span.events) > 0 else None
+        if start_event is not None:
+            event_info = start_event.model_dump(
+                mask_sensitive_information=mask_sensitive_information
+            )
+            tracing_info[SpanAttributes.INPUT_VALUE] = _try_json_serialization(
+                event_info.get("inputs", {})
+            )
+        end_event = span.events[-1] if len(span.events) > 1 else None
+        if end_event is not None:
+            event_info = end_event.model_dump(mask_sensitive_information=mask_sensitive_information)
+            tracing_info[SpanAttributes.OUTPUT_VALUE] = _try_json_serialization(
+                event_info.get("outputs", {})
+            )
+
+    return tracing_info
+
+
+class OpenInferenceSpanProcessor(_OtelSpanProcessor):
+    def __init__(
+        self,
+        resource: Optional[OtelSdkResource] = None,
+        otel_span_processor: Optional[OtelSdkSpanProcessor] = None,
+        span_exporter: Optional[OtelSdkSpanExporter] = None,
+        use_batch_span_processor: bool = True,
+        mask_sensitive_information: bool = True,
+    ):
+        """
+        AgentSpec OpenInference SpanProcessor.
+
+        This class forwards the calls to AgentSpec's span processors to an OpenInference one
+        (based on OpenTelemetry).
+
+        Parameters
+        ----------
+        resource:
+            The OpenTelemetry Resource to use in Spans.
+        otel_span_processor:
+            The OpenTelemetry SpanProcessor to use to process spans.
+            If None is given, a new instance is created based on ``span_exporter`` and
+            ``use_batch_span_processor`` parameters.
+        span_exporter:
+            The OpenTelemetry SpanExporter to use to export spans.
+            This parameter is ignored if an ``otel_span_processor`` is provided.
+        use_batch_span_processor:
+            If True, an instance of OpenTelemetry BatchSpanProcessor is used to process spans.
+            If False, an instance of OpenTelemetry SimpleSpanProcessor is used to process spans.
+            This parameter is ignored if an ``otel_span_processor`` is provided.
+        mask_sensitive_information
+            Whether to mask potentially sensitive information from the span and its events
+        """
+        self.use_batch_span_processor = use_batch_span_processor
+        super().__init__(
+            otel_span_processor=otel_span_processor,
+            span_exporter=span_exporter,
+            resource=resource,
+            mask_sensitive_information=mask_sensitive_information,
+            span_model_dump_func=_to_open_inference_format_tracing_info,
+        )
+
+    def _create_otel_span_processor(
+        self, span_exporter: OtelSdkSpanExporter
+    ) -> OtelSdkSpanProcessor:
+        if self.use_batch_span_processor:
+            return OtelSdkBatchSpanProcessor(span_exporter=span_exporter)
+        else:
+            return OtelSdkSimpleSpanProcessor(span_exporter=span_exporter)

openinference_instrumentation_agentspec-0.1.0/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py

@@ -0,0 +1,448 @@
+import json
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, Optional
+
+from opentelemetry import context as context_api
+from opentelemetry.sdk.trace import Event as OtelSdkEvent
+from opentelemetry.sdk.trace import Resource as OtelSdkResource  # type: ignore
+from opentelemetry.sdk.trace import Span as OtelSdkSpan
+from opentelemetry.sdk.trace import SpanContext as OtelSdkSpanContext  # type: ignore
+from opentelemetry.sdk.trace import sampling as otel_sdk_sampling
+from opentelemetry.sdk.trace.export import BatchSpanProcessor as OtelSdkBatchSpanProcessor
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor as OtelSdkSimpleSpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter as OtelSdkSpanExporter
+from opentelemetry.sdk.trace.export import SpanProcessor as OtelSdkSpanProcessor  # type: ignore
+from opentelemetry.trace import TraceFlags as OtelSdkTraceFlags
+from opentelemetry.util.types import Attributes
+from pyagentspec.tracing.events.event import Event as AgentSpecEvent
+from pyagentspec.tracing.spanprocessor import SpanProcessor as AgentSpecSpanProcessor
+from pyagentspec.tracing.spans.span import Span as AgentSpecSpan
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+_MAX_UNSIGNED_LONG_LONG = 18446744073709551615
+
+
+def _try_id_to_int_conversion(id_: Optional[str]) -> int:
+    """
+    Convert the string ID into an integer ID as per OpenTelemetry requirement
+
+    https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spancontext
+    """
+    if id_ is not None:
+        try:
+            # First we try to get the original UUID, if the id is a compliant string
+            id_ = uuid.UUID(id_)  # type: ignore
+        except ValueError:
+            # If it is not, we try to convert the id as it is
+            pass
+    try:
+        # We try the conversion to int modulo 2**64 (unsigned long long, due to otel limitations),
+        # if it is not None. Note also the 0 is not a valid ID,
+        # so we reduce the modulo by 1 (2**64-1) and add 1 to the result
+        return (int(id_) % _MAX_UNSIGNED_LONG_LONG) + 1 if id_ else id(id_)
+    except Exception:
+        # If the conversion fails, we fall back to the id, we cannot do better
+        return id(id_)
+
+
+def _try_json_serialization(value: Any) -> str:
+    """
+    Serialize the given object into the corresponding JSON string.
+    If it is not JSON serializable, we simply stringify it
+    """
+    if isinstance(value, str):
+        # Avoid quoting strings with json dump
+        return str(value)
+    try:
+        return json.dumps(value)
+    except TypeError:
+        return str(value)
+
+
+def _flatten_attribute_dict(attribute: Dict[str, Any]) -> Dict[str, Any]:
+    """Flatten the complex types using OpenTelemetry conventions"""
+    flattened_attribute: Dict[str, Any] = {}
+    for key, value in attribute.items():
+        if isinstance(value, (tuple, set, list)):
+            # List-like values have to become dictionaries with the index as the key
+            # This will be translated according to dict rules below
+            # (e.g., attribute_name.0, attribute_name.1, ...)
+            flattened_value = dict()
+            for i, inner_value in enumerate(value):
+                flattened_value[i] = inner_value
+            value = flattened_value
+        if isinstance(value, dict):
+            # Dictionary attributes are flattened by adding each dict entry
+            # as a separate entry with name `attribute_name.key`
+            for inner_key, inner_value in _flatten_attribute_dict(value).items():
+                flattened_attribute[f"{key}.{inner_key}"] = inner_value
+        else:
+            flattened_attribute[key] = value
+    return flattened_attribute
+
+
+def _serialize_attribute_values(attributes: Dict[str, Any]) -> Dict[str, Any]:
+    """Serialize the attributes dictionary using types that OpenTelemetry supports"""
+    # Note that this function performs shallow serialization, i.e., it does not apply recursively
+    allowed_types = (str, int, float, bool, bytes)
+    return {
+        key: value if isinstance(value, allowed_types) else _try_json_serialization(value)
+        for key, value in _flatten_attribute_dict(attributes).items()
+    }
+
+
+class _OtelSdkEvent(OtelSdkEvent):
+    """Protected implementation of `opentelemetry.trace.Event`.
+
+    Contains an ID that uniquely identifies the event.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        attributes: Attributes = None,
+        timestamp: Optional[int] = None,
+    ) -> None:
+        super().__init__(name=name, attributes=attributes, timestamp=timestamp)
+        self.id = id
+
+
+class _OtelSdkSpan(OtelSdkSpan):
+    """Protected implementation of `opentelemetry.trace.Span`.
+
+    As Spans cannot be directly instantiated in the opentelemetry SDK,
+    we create a materialization of the interface that we use internally.
+    This is the same solution that opentelemetry uses to prevent anyone
+    from creating a span without a tracer provider, but we need more flexibility.
+    """
+
+    def update_events(self, events: list[AgentSpecEvent], mask_sensitive_information: bool) -> None:
+        # We update the events list by adding the missing ones
+        # These events should all be _OtelSdkEvent that contain an ID
+        # If they are not, we can ignore them because they don't come from us
+        current_event_ids = {event.id for event in self.events if hasattr(event, "id")}
+        for event in events:
+            if event.id not in current_event_ids:
+                self._add_event(convert_agentspec_event_into_otel_event(event, mask_sensitive_information))
+
+
+def convert_agentspec_event_into_otel_event(
+    event: AgentSpecEvent,
+    mask_sensitive_information: bool = True,
+) -> _OtelSdkEvent:
+    """
+    Convert an AgentSpec Event into the equivalent OpenTelemetry Event object.
+
+    Parameters
+    ----------
+    event:
+        the event to convert
+    mask_sensitive_information
+        Whether to mask potentially sensitive information from the event attributes
+
+    Returns
+    -------
+    opentelemetry.sdk.trace.Event
+        The converted event
+    """
+    try:
+        event_dump = event.model_dump(mask_sensitive_information=mask_sensitive_information)
+    except Exception as e:
+        # If anything goes wrong, we log it, and we go on without event attributes
+        logger.warning(f"Error during the dump of an event: {e}")
+        event_dump = {}
+    return _OtelSdkEvent(
+        id=event.id,
+        name=event.name or event.__class__.__name__,
+        timestamp=event.timestamp,
+        attributes=_serialize_attribute_values(event_dump),
+    )
+
+
+def convert_agentspec_span_into_otel_span(
+    span: AgentSpecSpan,
+    resource: Optional[OtelSdkResource] = None,
+    mask_sensitive_information: bool = True,
+    span_model_dump: Optional[Callable[[AgentSpecSpan, bool], Dict[str, Any]]] = None,
+    span_to_update: Optional[_OtelSdkSpan] = None,
+) -> _OtelSdkSpan:
+    """
+    Convert a AgentSpec Span into the equivalent OpenTelemetry Span object.
+
+    Parameters
+    ----------
+    span:
+        the span to convert
+    resource:
+        the OpenTelemetry Resource object to use
+    mask_sensitive_information
+        Whether to mask potentially sensitive information from the span and its events
+    span_model_dump
+        Function to dump the span model to a dictionary.
+        If None, the pydantic model_dump function will be used.
+    span_to_update
+        OpenTelemetry Span object to be updated with new information from Agent Spec Span.
+        If None, a new OpenTelemetry Span object will be created.
+
+    Returns
+    -------
+    _OtelSdkSpan
+        The converted span
+    """
+    try:
+        if span_model_dump:
+            span_attributes = span_model_dump(span, mask_sensitive_information)
+        else:
+            span_attributes = span.model_dump(mask_sensitive_information=mask_sensitive_information)
+    except Exception as e:
+        # If anything goes wrong, we log it, and we go on without span attributes
+        logger.warning(f"Error during the dump of a span: {e}")
+        span_attributes = {}
+    # We remove the tracing information we don't want to appear in the attributes,
+    # as they will be handled separately
+    for attribute_to_pop in (
+        "events",
+        "id",
+        "type",
+        "name",
+        "start_time",
+        "end_time",
+    ):
+        span_attributes.pop(attribute_to_pop, None)
+    # We create the objects required by OpenTelemetry with the expected information
+    sampling_result = otel_sdk_sampling.SamplingResult(
+        otel_sdk_sampling.Decision.RECORD_AND_SAMPLE,
+        span_attributes,
+    )
+    trace_flags = (
+        OtelSdkTraceFlags(OtelSdkTraceFlags.SAMPLED)
+        if sampling_result.decision.is_sampled()  # type: ignore
+        else OtelSdkTraceFlags(OtelSdkTraceFlags.DEFAULT)
+    )
+    # The IDs in otel are required to be integers, so we try to transform them
+    trace_id = _try_id_to_int_conversion(span._trace.id if span._trace else None)
+    span_id = _try_id_to_int_conversion(span.id)
+    span_name = span.name or span.__class__.__name__
+    span_attributes = _serialize_attribute_values(span_attributes)
+    if span_to_update:
+        span_to_update.set_attributes(span_attributes)
+        span_to_update.update_events(span.events, mask_sensitive_information)
+        return span_to_update
+    else:
+        return _OtelSdkSpan(
+            name=span_name,
+            context=OtelSdkSpanContext(
+                trace_id=trace_id,
+                span_id=span_id,
+                is_remote=False,
+                trace_flags=trace_flags,
+                trace_state=sampling_result.trace_state,
+            ),
+            parent=(
+                OtelSdkSpanContext(
+                    trace_id=trace_id,
+                    span_id=_try_id_to_int_conversion(span._parent_span.id),
+                    is_remote=False,
+                )
+                if span._parent_span
+                else None
+            ),
+            resource=resource,
+            attributes=span_attributes,
+            events=[
+                convert_agentspec_event_into_otel_event(
+                    event,
+                    mask_sensitive_information=mask_sensitive_information
+                )
+                for event in span.events
+            ],
+        )
+
+
+class _OtelSpanProcessor(AgentSpecSpanProcessor, ABC):
+    """AgentSpec wrapper for the OpenTelemetry SpanProcessor"""
+
+    def __init__(
+        self,
+        otel_span_processor: Optional[OtelSdkSpanProcessor] = None,
+        span_exporter: Optional[OtelSdkSpanExporter] = None,
+        resource: Optional[OtelSdkResource] = None,
+        mask_sensitive_information: bool = True,
+        span_model_dump_func: Optional[Callable[[AgentSpecSpan, bool], Dict[str, Any]]] = None,
+    ) -> None:
+        """
+        AgentSpec wrapper for the OpenTelemetry SpanProcessor.
+
+        This class forwards the calls to AgentSpec's span processors to an OpenTelemetry one.
+
+        Parameters
+        ----------
+        otel_span_processor:
+            The OpenTelemetry SpanProcessor to use to process spans.
+            If None is given, a new instance is created.
+        span_exporter:
+            The OpenTelemetry SpanExporter to use to export spans.
+            This parameter is ignored if an ``otel_span_processor`` is provided.
+        resource:
+            The OpenTelemetry Resource to use in Spans.
+        mask_sensitive_information
+            Whether to mask potentially sensitive information from the span and its events
+        span_model_dump_func
+            Function to dump the span model to a dictionary, used to get attributes in the
+            transformation to OTel Span. The function accepts two parameters: the Agent Spec Span,
+            and the mask_sensitive_information boolean flag.
+            If None, the pydantic model_dump function on the Agent Spec Span will be used.
+        """
+        super().__init__(mask_sensitive_information=mask_sensitive_information)
+        self.span_exporter = span_exporter
+        self.resource = resource
+        self.span_model_dump_func = span_model_dump_func
+        if otel_span_processor is not None:
+            self.span_processor = otel_span_processor
+        elif span_exporter is not None:
+            self.span_processor = self._create_otel_span_processor(span_exporter=span_exporter)
+        else:
+            raise ValueError("Span exporter must be provided when no span processor is given")
+        # We keep a registry of spans that we already created
+        # The idea is to reuse and update the same span at start and end
+        self._span_registry: Dict[str, _OtelSdkSpan] = {}
+
+    @abstractmethod
+    def _create_otel_span_processor(
+        self, span_exporter: OtelSdkSpanExporter
+    ) -> OtelSdkSpanProcessor:
+        pass
+
+    def _create_otel_span_from_agentspec_span(self, span: AgentSpecSpan) -> OtelSdkSpan:
+        # We retrieve the span from the registry, and we update it with the new information.
+        # If there's no otel span in the registry with this ID, it is created
+        span_from_registry = self._span_registry.get(span.id, None)
+        otel_span = convert_agentspec_span_into_otel_span(
+            span=span,
+            resource=self.resource,
+            mask_sensitive_information=self.mask_sensitive_information,
+            span_model_dump=self.span_model_dump_func,
+            span_to_update=span_from_registry,
+        )
+        # Record the updated span in the registry and return it
+        self._span_registry[span.id] = otel_span
+        return otel_span
+
+    def on_start(self, span: AgentSpecSpan) -> None:
+        """
+        Method called at the start of a Span.
+
+        Parameters
+        ----------
+        span:
+            The AgentSpec span that is starting
+        """
+        try:
+            otel_span = self._create_otel_span_from_agentspec_span(span=span)
+            # If instrumentation is suppressed, we still convert the span,
+            # but we don't emit anything
+            if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+                return
+            otel_span.start(start_time=span.start_time)
+            self.span_processor.on_start(span=otel_span)
+        except Exception as e:
+            # Whatever happens we do not crash the execution of the assistant,
+            # but we warn the user
+            logger.warning(f"Exception raised during SpanProcessor `on_start`: {e}")
+
+    def on_end(self, span: AgentSpecSpan) -> None:
+        """
+        Method called at the end of a Span.
+
+        Parameters
+        ----------
+        span:
+            The AgentSpec span that is ending
+        """
+        try:
+            # We re-create the span because we might need to re-format
+            # the changes happened in the span
+            otel_span = self._create_otel_span_from_agentspec_span(span=span)
+            # If instrumentation is suppressed, we manage the converted spans statuses,
+            # but we don't emit anything
+            if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+                return
+            if otel_span.start_time is None:
+                # If the span was not started for some reason, we start it manually here
+                otel_span.start(start_time=span.start_time)
+            otel_span.end(end_time=span.end_time)
+            self.span_processor.on_end(span=otel_span)
+            # We remove the span from the registry, since now it's closed
+            self._span_registry.pop(span.id, None)
+        except Exception as e:
+            # Whatever happens we do not crash the execution of the assistant,
+            # but we warn the user
+            logger.warning(f"Exception raised during SpanProcessor `on_end`: {e}")
+
+    def on_event(self, event: AgentSpecEvent, span: AgentSpecSpan) -> None:
+        # No need to do anything on events occurring, everything is handled at span closure
+        pass
+
+    def startup(self) -> None:
+        pass
+
+    def shutdown(self) -> None:
+        try:
+            self.span_processor.shutdown()
+            self._span_registry = {}
+        except Exception as e:
+            # Whatever happens we do not crash the execution of the assistant,
+            # but we warn the user
+            logger.warning(f"Exception raised during SpanProcessor `shutdown`: {e}")
+
+    async def on_start_async(self, span: AgentSpecSpan) -> None:
+        raise NotImplementedError(f"Async stack not implemented for {self.__class__.__name__} yet")
+
+    async def on_end_async(self, span: AgentSpecSpan) -> None:
+        raise NotImplementedError(f"Async stack not implemented for {self.__class__.__name__} yet")
+
+    async def on_event_async(self, event: AgentSpecEvent, span: AgentSpecSpan) -> None:
+        raise NotImplementedError(f"Async stack not implemented for {self.__class__.__name__} yet")
+
+    async def startup_async(self) -> None:
+        raise NotImplementedError(f"Async stack not implemented for {self.__class__.__name__} yet")
+
+    async def shutdown_async(self) -> None:
+        raise NotImplementedError(f"Async stack not implemented for {self.__class__.__name__} yet")
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """
+        Export all ended spans to the configured Exporter that have not yet been exported.
+
+        Forwards the call to the internal OpenTelemetry span processor.
+        """
+        try:
+            return self.span_processor.force_flush(timeout_millis=timeout_millis)
+        except Exception as e:
+            # Whatever happens we do not crash the execution of the assistant, but we warn the user
+            logger.warning(f"Exception raised during SpanProcessor `force_flush`: {e}")
+            return True
+
+
+class OtelSimpleSpanProcessor(_OtelSpanProcessor):
+    """AgentSpec wrapper for the OpenTelemetry SimpleSpanProcessor"""
+
+    def _create_otel_span_processor(
+        self, span_exporter: OtelSdkSpanExporter
+    ) -> OtelSdkSpanProcessor:
+        return OtelSdkSimpleSpanProcessor(span_exporter=span_exporter)
+
+
+class OtelBatchSpanProcessor(_OtelSpanProcessor):
+    """AgentSpec wrapper for the OpenTelemetry BatchSpanProcessor"""
+
+    def _create_otel_span_processor(
+        self, span_exporter: OtelSdkSpanExporter
+    ) -> OtelSdkSpanProcessor:
+        return OtelSdkBatchSpanProcessor(span_exporter=span_exporter)

openinference_instrumentation_agentspec-0.1.0/src/openinference/instrumentation/agentspec/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"