Building AI agents, atomically
Add optional OpenInference instrumentor for agents and tools
Eigenwise84981ce51de2
diff --git a/atomic-agents/atomic_agents/observability/__init__.py b/atomic-agents/atomic_agents/observability/__init__.pynew file mode 100644index 0000000..6fe3567--- /dev/null+++ b/atomic-agents/atomic_agents/observability/__init__.py@@ -0,0 +1,98 @@+"""+Opt-in OpenInference tracing for Atomic Agents.++Emits an AGENT span per ``AtomicAgent`` run and a TOOL span per ``BaseTool`` run, rendered by+Arize Phoenix and any other OpenTelemetry backend. Needs the ``observability`` extra:+``pip install "atomic-agents[observability]"``. Phoenix discovers :class:`AtomicAgentsInstrumentor`+through the ``openinference_instrumentor`` entry point, so ``phoenix.otel.register(auto_instrument=True)``+activates it without further code. See ``docs/guides/observability.md``.+"""++import importlib.util+import logging+from importlib.metadata import PackageNotFoundError, version+from typing import TYPE_CHECKING, Optional++if TYPE_CHECKING:+ from openinference.instrumentation import TraceConfig+ from opentelemetry.trace import TracerProvider++logger = logging.getLogger(__name__)++_INSTALL_HINT = (+ "Atomic Agents observability needs the OpenInference packages. "+ 'Install them with: pip install "atomic-agents[observability]"'+)+_OPENINFERENCE_DISTRIBUTION = "openinference-instrumentation"+_MINIMUM_OPENINFERENCE_VERSION = (0, 1, 38)+++def _openinference_is_installed() -> bool:+ return importlib.util.find_spec("openinference") is not None+++def _openinference_is_too_old() -> bool:+ try:+ installed = version(_OPENINFERENCE_DISTRIBUTION)+ except PackageNotFoundError:+ return True+ release = tuple(int(part) for part in installed.split(".")[:3] if part.isdigit())+ return release < _MINIMUM_OPENINFERENCE_VERSION+++def _load_tracing_module():+ if _openinference_is_too_old():+ logger.warning(+ "Atomic Agents tracing is disabled: %s %s or newer is required.",+ _OPENINFERENCE_DISTRIBUTION,+ ".".join(str(part) for part in _MINIMUM_OPENINFERENCE_VERSION),+ )+ return None+ from atomic_agents.observability import openinference_tracing++ return openinference_tracing+++class AtomicAgentsInstrumentor:+ """+ Installs OpenInference AGENT and TOOL spans around ``AtomicAgent`` and ``BaseTool`` calls.++ The public surface mirrors OpenTelemetry's ``BaseInstrumentor`` (``instrument`` / ``uninstrument``)+ without depending on it, because Arize Phoenix only guarantees ``opentelemetry-api`` and+ ``openinference-instrumentation`` in an auto-instrumented environment.+ """++ def instrument(+ self, *, tracer_provider: Optional["TracerProvider"] = None, config: Optional["TraceConfig"] = None+ ) -> None:+ """+ Patch the framework classes. Safe to call more than once; a second call with different+ arguments logs a warning and keeps the first installation.++ Args:+ tracer_provider: An OpenTelemetry ``TracerProvider``. Defaults to the global provider.+ config: An ``openinference.instrumentation.TraceConfig`` (for example ``hide_inputs=True``).++ Raises:+ ImportError: When the ``observability`` extra is not installed.+ """+ if not _openinference_is_installed():+ raise ImportError(_INSTALL_HINT)+ tracing = _load_tracing_module()+ if tracing is not None:+ tracing.install(tracer_provider=tracer_provider, config=config)++ def uninstrument(self) -> None:+ """Restore the original framework methods. No-op when nothing is installed."""+ if not self.is_instrumented_by_opentelemetry:+ return+ _load_tracing_module().uninstall()++ @property+ def is_instrumented_by_opentelemetry(self) -> bool:+ if not _openinference_is_installed() or _openinference_is_too_old():+ return False+ return _load_tracing_module().is_installed()+++__all__ = ["AtomicAgentsInstrumentor"]diff --git a/atomic-agents/atomic_agents/observability/openinference_tracing.py b/atomic-agents/atomic_agents/observability/openinference_tracing.pynew file mode 100644index 0000000..7959be4--- /dev/null+++ b/atomic-agents/atomic_agents/observability/openinference_tracing.py@@ -0,0 +1,475 @@+"""+OpenInference span emission for ``AtomicAgent`` runs and ``BaseTool`` runs.++Loaded lazily by :class:`atomic_agents.observability.AtomicAgentsInstrumentor`; importing this module+requires the ``observability`` extra.+"""++import asyncio+import contextvars+import functools+import hashlib+import inspect+import json+import logging+from types import FunctionType+from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Dict, Generator, List, Optional, Type++from openinference.instrumentation import OITracer, TraceConfig+from openinference.semconv.trace import SpanAttributes+from opentelemetry import context as context_api+from opentelemetry import trace as trace_api+from opentelemetry.trace import Status, StatusCode++from atomic_agents import __version__+from atomic_agents.agents.atomic_agent import AtomicAgent+from atomic_agents.base.base_tool import BaseTool++if TYPE_CHECKING:+ from opentelemetry.trace import TracerProvider++logger = logging.getLogger(__name__)++TRACED_MARKER = "__atomic_agents_traced__"+INHERITED_MARKER = "__atomic_agents_inherited__"+TRACER_NAME = "atomic_agents"++AGENT_SYNC_METHOD = "run"+AGENT_ASYNC_METHOD = "run_async"+AGENT_SYNC_STREAM_METHOD = "run_stream"+AGENT_ASYNC_STREAM_METHOD = "run_async_stream"+TOOL_METHOD_NAMES = ("run", "run_async", "arun")++ATTR_MODEL = "atomic_agents.model"+ATTR_MODE = "atomic_agents.mode"+ATTR_INPUT_SCHEMA = "atomic_agents.input_schema"+ATTR_OUTPUT_SCHEMA = "atomic_agents.output_schema"+ATTR_HISTORY_MESSAGE_COUNT = "atomic_agents.history.message_count"+ATTR_CONTEXT_PROVIDERS = "atomic_agents.context_providers"+ATTR_SYSTEM_PROMPT_SHA256 = "atomic_agents.system_prompt.sha256"+ATTR_STREAM_CLOSED_EARLY = "atomic_agents.stream.closed_early"++_active_tool: contextvars.ContextVar[Optional[BaseTool]] = contextvars.ContextVar("atomic_agents_active_tool", default=None)+++class _Installation:+ def __init__(+ self,+ tracer: OITracer,+ tracer_provider: Optional["TracerProvider"],+ config: TraceConfig,+ original_init_subclass: classmethod,+ ):+ self.tracer = tracer+ self.tracer_provider = tracer_provider+ self.config = config+ self.original_init_subclass = original_init_subclass+++_installation: Optional[_Installation] = None+++def is_installed() -> bool:+ return _installation is not None+++def install(*, tracer_provider: Optional["TracerProvider"] = None, config: Optional[TraceConfig] = None) -> None:+ global _installation+ config = config or TraceConfig()+ if _installation is not None:+ _warn_if_reinstalled_differently(_installation, tracer_provider, config)+ return+ tracer = OITracer(trace_api.get_tracer(TRACER_NAME, __version__, tracer_provider), config=config)+ original_init_subclass = BaseTool.__dict__["__init_subclass__"]+ _installation = _Installation(tracer, tracer_provider, config, original_init_subclass)+ _instrument_agent_class(tracer)+ _instrument_existing_tool_classes(tracer)+ _hook_future_tool_classes(tracer, original_init_subclass)+++def uninstall() -> None:+ global _installation+ if _installation is None:+ return+ setattr(BaseTool, "__init_subclass__", _installation.original_init_subclass)+ for tool_class in _all_subclasses(BaseTool):+ _restore_tool_class(tool_class)+ for method_name in _AGENT_WRAPPERS:+ _restore_method(AtomicAgent, method_name)+ _installation = None+++def _warn_if_reinstalled_differently(+ installed: _Installation, tracer_provider: Optional["TracerProvider"], config: TraceConfig+) -> None:+ same_provider = tracer_provider is None or tracer_provider is installed.tracer_provider+ same_config = config == installed.config+ if not (same_provider and same_config):+ logger.warning(+ "AtomicAgentsInstrumentor is already installed; the new tracer_provider/config are ignored. "+ "Call uninstrument() first to change them."+ )+++def _instrument_agent_class(tracer: OITracer) -> None:+ for method_name, wrap in _AGENT_WRAPPERS.items():+ original = AtomicAgent.__dict__[method_name]+ if not getattr(original, TRACED_MARKER, False):+ setattr(AtomicAgent, method_name, _mark_traced(wrap(tracer, method_name, original), original, False))+++def _mark_traced(wrapper: Callable, original: Callable, inherited: bool) -> Callable:+ setattr(wrapper, TRACED_MARKER, True)+ setattr(wrapper, INHERITED_MARKER, inherited)+ setattr(wrapper, "__wrapped__", original)+ return wrapper+++def _restore_method(owner: Type, method_name: str) -> None:+ current = owner.__dict__.get(method_name)+ if current is None or not getattr(current, TRACED_MARKER, False):+ return+ if getattr(current, INHERITED_MARKER, False):+ delattr(owner, method_name)+ else:+ setattr(owner, method_name, current.__wrapped__)+++def _all_subclasses(base: Type) -> List[Type]:+ found: List[Type] = []+ pending = list(base.__subclasses__())+ while pending:+ current = pending.pop(0)+ if current not in found:+ found.append(current)+ pending.extend(current.__subclasses__())+ return found+++def _instrument_existing_tool_classes(tracer: OITracer) -> None:+ for tool_class in _all_subclasses(BaseTool):+ _instrument_tool_class(tool_class, tracer)+++def _hook_future_tool_classes(tracer: OITracer, original_init_subclass: classmethod) -> None:+ def traced_init_subclass(cls, **kwargs):+ original_init_subclass.__func__(cls, **kwargs)+ _instrument_tool_class(cls, tracer)++ setattr(BaseTool, "__init_subclass__", classmethod(traced_init_subclass))+++def _instrument_tool_class(tool_class: Type, tracer: OITracer) -> None:+ for method_name in TOOL_METHOD_NAMES:+ method = inspect.getattr_static(tool_class, method_name, None)+ if _is_traceable_function(method):+ inherited = method_name not in tool_class.__dict__+ setattr(tool_class, method_name, _mark_traced(_trace_tool_method(tracer, method), method, inherited))+++def _is_traceable_function(method: Any) -> bool:+ if not isinstance(method, FunctionType) or inspect.isasyncgenfunction(method):+ return False+ if getattr(method, "__isabstractmethod__", False):+ return False+ return not getattr(method, TRACED_MARKER, False)+++def _restore_tool_class(tool_class: Type) -> None:+ for method_name in TOOL_METHOD_NAMES:+ _restore_method(tool_class, method_name)+++def _agent_display_name(agent: AtomicAgent) -> str:+ return f"{type(agent).__name__}[{agent.input_schema.__name__}, {agent.output_schema.__name__}]"+++def _agent_start_attributes(agent: AtomicAgent) -> Dict[str, Any]:+ try:+ return {+ SpanAttributes.AGENT_NAME: _agent_display_name(agent),+ ATTR_MODEL: agent.model,+ ATTR_MODE: getattr(agent.mode, "value", str(agent.mode)),+ ATTR_INPUT_SCHEMA: agent.input_schema.__name__,+ ATTR_OUTPUT_SCHEMA: agent.output_schema.__name__,+ ATTR_HISTORY_MESSAGE_COUNT: len(agent.history.history),+ ATTR_CONTEXT_PROVIDERS: _context_provider_names(agent),+ **_system_prompt_version(agent),+ }+ except Exception as error:+ logger.warning("Could not describe agent for tracing: %s", error)+ return {}+++def _context_provider_names(agent: AtomicAgent) -> List[str]:+ providers = getattr(agent.system_prompt_generator, "context_providers", None) or {}+ return sorted(str(name) for name in providers)+++def _system_prompt_version(agent: AtomicAgent) -> Dict[str, str]:+ """Hashes only the static prompt sections, so the value identifies the prompt version across turns+ even though context providers change the rendered prompt on every call."""+ generator = agent.system_prompt_generator+ sections = {name: getattr(generator, name, None) for name in ("background", "steps", "output_instructions")}+ if agent.system_role is None or all(value is None for value in sections.values()):+ return {}+ digest = hashlib.sha256(json.dumps(sections, sort_keys=True, default=str).encode("utf-8")).hexdigest()+ return {ATTR_SYSTEM_PROMPT_SHA256: digest}+++def _user_input_from_call(args: tuple, kwargs: dict) -> Any:+ return args[0] if args else kwargs.get("user_input")+++def _set_input_safely(span: Any, value: Any) -> None:+ if value is None:+ return+ try:+ span.set_input(value)+ except Exception as error:+ logger.warning("Could not record span input: %s", error)+++def _set_output_safely(span: Any, value: Any) -> None:+ if value is None:+ return+ try:+ span.set_output(value)+ except Exception as error:+ logger.warning("Could not record span output: %s", error)+++def _finish_agent_span(span: Any, output: Any) -> None:+ _set_output_safely(span, output)+ span.set_status(Status(StatusCode.OK))+++def _mark_closed_early(span: Any, output: Any) -> None:+ span.set_attribute(ATTR_STREAM_CLOSED_EARLY, True)+ _set_output_safely(span, output)+++def _record_failure(span: Any, error: BaseException) -> None:+ span.record_exception(error)+ span.set_status(Status(StatusCode.ERROR, str(error)))+++def _trace_agent_call(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:+ @functools.wraps(wrapped)+ def traced(agent, *args, **kwargs):+ span_name = f"{_agent_display_name(agent)}.{method_name}"+ with tracer.start_as_current_span(+ span_name, openinference_span_kind="agent", attributes=_agent_start_attributes(agent)+ ) as span:+ _set_input_safely(span, _user_input_from_call(args, kwargs))+ response = wrapped(agent, *args, **kwargs)+ _finish_agent_span(span, response)+ return response++ return traced+++def _trace_agent_async_call(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:+ @functools.wraps(wrapped)+ async def traced(agent, *args, **kwargs):+ span_name = f"{_agent_display_name(agent)}.{method_name}"+ with tracer.start_as_current_span(+ span_name, openinference_span_kind="agent", attributes=_agent_start_attributes(agent)+ ) as span:+ _set_input_safely(span, _user_input_from_call(args, kwargs))+ response = await wrapped(agent, *args, **kwargs)+ _finish_agent_span(span, response)+ return response++ return traced+++def _start_agent_span(tracer: OITracer, agent: AtomicAgent, method_name: str, args: tuple, kwargs: dict) -> Any:+ span = tracer.start_span(+ f"{_agent_display_name(agent)}.{method_name}",+ openinference_span_kind="agent",+ attributes=_agent_start_attributes(agent),+ )+ _set_input_safely(span, _user_input_from_call(args, kwargs))+ return span+++def _call_within_span(span: Any, function: Callable, *args: Any) -> Any:+ token = context_api.attach(trace_api.set_span_in_context(span))+ try:+ return function(*args)+ finally:+ context_api.detach(token)+++async def _await_within_span(span: Any, awaitable: Any) -> Any:+ token = context_api.attach(trace_api.set_span_in_context(span))+ try:+ return await awaitable+ finally:+ context_api.detach(token)+++class _SyncStreamCursor:+ def __init__(self, span: Any, inner: Generator):+ self.span = span+ self.inner = inner+ self.last: Any = None+ self.final: Any = None++ def advance(self) -> bool:+ try:+ self.last = _call_within_span(self.span, next, self.inner)+ except StopIteration as stop:+ self.final = stop.value+ return False+ return True++ def close_early(self) -> None:+ _call_within_span(self.span, self.inner.close)+ _mark_closed_early(self.span, self.last)+ self.span.set_status(Status(StatusCode.OK))+++class _AsyncStreamCursor:+ """Async twin of :class:`_SyncStreamCursor`; async generators carry no return value, so the last partial is the output."""++ def __init__(self, span: Any, inner: AsyncGenerator):+ self.span = span+ self.inner = inner+ self.last: Any = None++ async def advance(self) -> bool:+ try:+ self.last = await _await_within_span(self.span, self.inner.__anext__())+ except StopAsyncIteration:+ return False+ return True++ async def close_early(self) -> None:+ await _await_within_span(self.span, self.inner.aclose())+ _mark_closed_early(self.span, self.last)+ self.span.set_status(Status(StatusCode.OK))++ def mark_cancelled(self) -> None:+ _mark_closed_early(self.span, self.last)+++def _trace_agent_stream(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:+ @functools.wraps(wrapped)+ def traced(agent, *args, **kwargs):+ span = _start_agent_span(tracer, agent, method_name, args, kwargs)+ cursor = _SyncStreamCursor(span, wrapped(agent, *args, **kwargs))+ try:+ while cursor.advance():+ yield cursor.last+ _finish_agent_span(span, cursor.final)+ return cursor.final+ except GeneratorExit:+ cursor.close_early()+ raise+ except BaseException as error:+ _record_failure(span, error)+ raise+ finally:+ span.end()++ return traced+++def _trace_agent_async_stream(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:+ @functools.wraps(wrapped)+ async def traced(agent, *args, **kwargs):+ span = _start_agent_span(tracer, agent, method_name, args, kwargs)+ cursor = _AsyncStreamCursor(span, wrapped(agent, *args, **kwargs))+ try:+ while await cursor.advance():+ yield cursor.last+ _finish_agent_span(span, cursor.last)+ except GeneratorExit:+ await cursor.close_early()+ raise+ except asyncio.CancelledError:+ cursor.mark_cancelled()+ raise+ except BaseException as error:+ _record_failure(span, error)+ raise+ finally:+ span.end()++ return traced+++def _describe_tool(span: Any, tool: BaseTool) -> None:+ try:+ span.set_tool(+ name=tool.tool_name,+ description=tool.tool_description,+ parameters=tool.input_schema.model_json_schema(),+ )+ except Exception as error:+ logger.warning("Could not describe tool %s for tracing: %s", type(tool).__name__, error)+++def _tool_input_from_call(args: tuple, kwargs: dict) -> Any:+ return args[0] if args else kwargs.get("params")+++def _trace_tool_method(tracer: OITracer, wrapped: Callable) -> Callable:+ if inspect.iscoroutinefunction(wrapped):+ return _trace_tool_async_method(tracer, wrapped)++ @functools.wraps(wrapped)+ def traced(tool, *args, **kwargs):+ if _active_tool.get() is tool:+ return wrapped(tool, *args, **kwargs)+ with tracer.start_as_current_span(type(tool).__name__, openinference_span_kind="tool") as span:+ _describe_tool(span, tool)+ _set_input_safely(span, _tool_input_from_call(args, kwargs))+ result = _run_as_active_tool(tool, wrapped, args, kwargs)+ _set_output_safely(span, result)+ span.set_status(Status(StatusCode.OK))+ return result++ return traced+++def _trace_tool_async_method(tracer: OITracer, wrapped: Callable) -> Callable:+ @functools.wraps(wrapped)+ async def traced(tool, *args, **kwargs):+ if _active_tool.get() is tool:+ return await wrapped(tool, *args, **kwargs)+ with tracer.start_as_current_span(type(tool).__name__, openinference_span_kind="tool") as span:+ _describe_tool(span, tool)+ _set_input_safely(span, _tool_input_from_call(args, kwargs))+ result = await _await_as_active_tool(tool, wrapped, args, kwargs)+ _set_output_safely(span, result)+ span.set_status(Status(StatusCode.OK))+ return result++ return traced+++def _run_as_active_tool(tool: BaseTool, wrapped: Callable, args: tuple, kwargs: dict) -> Any:+ token = _active_tool.set(tool)+ try:+ return wrapped(tool, *args, **kwargs)+ finally:+ _active_tool.reset(token)+++async def _await_as_active_tool(tool: BaseTool, wrapped: Callable, args: tuple, kwargs: dict) -> Any:+ token = _active_tool.set(tool)+ try:+ return await wrapped(tool, *args, **kwargs)+ finally:+ _active_tool.reset(token)+++_AGENT_WRAPPERS: Dict[str, Callable[[OITracer, str, Callable], Callable]] = {+ AGENT_SYNC_METHOD: _trace_agent_call,+ AGENT_ASYNC_METHOD: _trace_agent_async_call,+ AGENT_SYNC_STREAM_METHOD: _trace_agent_stream,+ AGENT_ASYNC_STREAM_METHOD: _trace_agent_async_stream,+}diff --git a/atomic-agents/tests/observability/test_openinference_tracing.py b/atomic-agents/tests/observability/test_openinference_tracing.pynew file mode 100644index 0000000..8bb56c4--- /dev/null+++ b/atomic-agents/tests/observability/test_openinference_tracing.py@@ -0,0 +1,820 @@+import abc+import asyncio+import contextvars+import gc+import json+import logging+import types+from concurrent.futures import ThreadPoolExecutor+from importlib.metadata import entry_points+from typing import Dict, List+from unittest.mock import Mock++import instructor+import pytest+from openinference.instrumentation import TraceConfig, using_metadata, using_session+from openinference.semconv.trace import OpenInferenceSpanKindValues, SpanAttributes+from opentelemetry import trace as trace_api+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider+from opentelemetry.sdk.trace.export import SimpleSpanProcessor+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter+from opentelemetry.trace import StatusCode+from pydantic import Field++from atomic_agents import AgentConfig, AtomicAgent, BaseIOSchema, BaseTool+from atomic_agents.context import BaseDynamicContextProvider, SystemPromptGenerator+from atomic_agents.observability import AtomicAgentsInstrumentor+import atomic_agents.observability as observability+from atomic_agents.observability import openinference_tracing as tracing+++class QuestionSchema(BaseIOSchema):+ """A question for the agent."""++ question: str = Field(...)+++class AnswerSchema(BaseIOSchema):+ """An answer from the agent."""++ answer: str = Field(...)+++class CalculationInputSchema(BaseIOSchema):+ """Expression to evaluate."""++ expression: str = Field(...)+++class CalculationOutputSchema(BaseIOSchema):+ """Result of the evaluation."""++ result: str = Field(...)+++class CalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema, precision: int = 2) -> CalculationOutputSchema:+ return CalculationOutputSchema(result=f"{len(params.expression):.{precision}f}")+++class AsyncCalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return asyncio.run(self.arun(params))++ async def arun(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result=str(len(params.expression)))+++class ThreadedCalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result=str(len(params.expression)))++ async def run_async(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return await asyncio.to_thread(self.run, params)+++class RunMixin:+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="mixin")+++class MixinCalculatorTool(RunMixin, BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ pass+++class StaticRunTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ @staticmethod+ def run(params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="static")+++class FailingTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ raise ValueError("boom")+++class AnswerStore:+ """Container object pydantic cannot serialize to JSON."""++ def __init__(self):+ self.values: List[int] = []+++class UnserializableInputSchema(BaseIOSchema):+ """Input carrying an arbitrary object."""++ model_config = {"arbitrary_types_allowed": True}+ store: AnswerStore = Field(...)+++class EchoTool(BaseTool[UnserializableInputSchema, CalculationOutputSchema]):+ def run(self, params: UnserializableInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="echo")+++def exporter():+ exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(exporter))+ exporter.provider = provider+ instrumentor = AtomicAgentsInstrumentor()+ instrumentor.instrument(tracer_provider=provider)+ yield exporter+ instrumentor.uninstrument()+++def provider_tracer(exporter):+ return exporter.provider.get_tracer("test")+++def sync_client(response=None, partials=None):+ client = Mock(spec=instructor.Instructor)+ client.chat = Mock()+ client.chat.completions = Mock()+ client.chat.completions.create = Mock(return_value=response or AnswerSchema(answer="42"))++ def create_partial(**kwargs):+ for partial in partials or [AnswerSchema(answer="4"), AnswerSchema(answer="42")]:+ yield partial++ client.chat.completions.create_partial = create_partial+ return client+++def async_client(response=None, partials=None):+ client = Mock(spec=instructor.core.client.AsyncInstructor)+ client.chat = Mock()+ client.chat.completions = Mock()++ async def create(**kwargs):+ return response or AnswerSchema(answer="42")++ async def create_partial(**kwargs):+ for partial in partials or [AnswerSchema(answer="4"), AnswerSchema(answer="42")]:+ yield partial++ client.chat.completions.create = create+ client.chat.completions.create_partial = create_partial+ return client+++def make_agent(client) -> AtomicAgent[QuestionSchema, AnswerSchema]:+ return AtomicAgent[QuestionSchema, AnswerSchema](AgentConfig(client=client, model="test-model"))+++def spans_of(exporter) -> List[ReadableSpan]:+ return list(exporter.get_finished_spans())+++def kind_of(span: ReadableSpan) -> str:+ return span.attributes[SpanAttributes.OPENINFERENCE_SPAN_KIND]+++def input_json(span: ReadableSpan) -> Dict:+ return json.loads(span.attributes[SpanAttributes.INPUT_VALUE])+++def output_json(span: ReadableSpan) -> Dict:+ return json.loads(span.attributes[SpanAttributes.OUTPUT_VALUE])+++def test_run_emits_agent_span_with_io_and_framework_attributes(exporter):+ agent = make_agent(sync_client())++ response = agent.run(QuestionSchema(question="6*7?"))++ assert response.answer == "42"+ (span,) = spans_of(exporter)+ assert span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run"+ assert kind_of(span) == OpenInferenceSpanKindValues.AGENT.value+ assert span.attributes[SpanAttributes.AGENT_NAME] == "AtomicAgent[QuestionSchema, AnswerSchema]"+ assert input_json(span) == {"question": "6*7?"}+ assert output_json(span) == {"answer": "42"}+ assert span.attributes[SpanAttributes.INPUT_MIME_TYPE] == "application/json"+ assert span.attributes[SpanAttributes.OUTPUT_MIME_TYPE] == "application/json"+ assert span.attributes[tracing.ATTR_MODEL] == "test-model"+ assert span.attributes[tracing.ATTR_MODE] == agent.mode.value+ assert span.attributes[tracing.ATTR_INPUT_SCHEMA] == "QuestionSchema"+ assert span.attributes[tracing.ATTR_OUTPUT_SCHEMA] == "AnswerSchema"+ assert span.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 0+ assert span.attributes[tracing.ATTR_CONTEXT_PROVIDERS] == ()+ assert len(span.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]) == 64+ assert span.status.status_code == StatusCode.OK+++def test_second_turn_reports_history_size_entering_the_turn(exporter):+ agent = make_agent(sync_client())+ agent.run(QuestionSchema(question="first"))++ agent.run(QuestionSchema(question="second"))++ first, second = spans_of(exporter)+ assert first.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 0+ assert second.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 2+++def test_agent_without_system_role_has_no_prompt_hash(exporter):+ agent = AtomicAgent[QuestionSchema, AnswerSchema](AgentConfig(client=sync_client(), model="m", system_role=None))++ agent.run(QuestionSchema(question="?"))++ (span,) = spans_of(exporter)+ assert tracing.ATTR_SYSTEM_PROMPT_SHA256 not in span.attributes+++def test_abstract_intermediate_tool_base_is_not_wrapped(exporter):+ class AbstractCalculator(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ @abc.abstractmethod+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ raise NotImplementedError++ assert not hasattr(AbstractCalculator.__dict__["run"], tracing.TRACED_MARKER)+++def test_run_without_input_sets_no_input_attribute(exporter):+ agent = make_agent(sync_client())++ agent.run()++ (span,) = spans_of(exporter)+ assert SpanAttributes.INPUT_VALUE not in span.attributes+ assert output_json(span) == {"answer": "42"}+++def test_run_failure_propagates_and_marks_span_error(exporter):+ client = sync_client()+ client.chat.completions.create = Mock(side_effect=RuntimeError("provider down"))+ agent = make_agent(client)++ with pytest.raises(RuntimeError, match="provider down"):+ agent.run(QuestionSchema(question="?"))++ (span,) = spans_of(exporter)+ assert span.status.status_code == StatusCode.ERROR+ assert [event.name for event in span.events] == ["exception"]+++def test_subclassed_agent_is_named_after_the_subclass_and_emits_one_span(exporter):+ class ResearchAgent(AtomicAgent[QuestionSchema, AnswerSchema]):+ def run(self, user_input=None):+ return super().run(user_input)++ agent = ResearchAgent(AgentConfig(client=sync_client(), model="test-model"))++ agent.run(QuestionSchema(question="?"))++ (span,) = spans_of(exporter)+ assert span.name == "ResearchAgent[QuestionSchema, AnswerSchema].run"+++def test_agent_span_nests_under_a_user_chain_span(exporter, provider_tracer):+ agent = make_agent(sync_client())++ with provider_tracer.start_as_current_span("turn") as turn:+ agent.run(QuestionSchema(question="?"))++ agent_span, turn_span = spans_of(exporter)+ assert agent_span.parent.span_id == turn.get_span_context().span_id+ assert turn_span.name == "turn"+++def test_llm_call_inside_run_becomes_child_of_agent_span(exporter, provider_tracer):+ def create(**kwargs):+ with provider_tracer.start_as_current_span("llm"):+ return AnswerSchema(answer="42")++ client = sync_client()+ client.chat.completions.create = create+ agent = make_agent(client)++ agent.run(QuestionSchema(question="?"))++ llm_span, agent_span = spans_of(exporter)+ assert llm_span.parent.span_id == agent_span.context.span_id+++def test_run_stream_records_final_output_and_keeps_child_context_per_step(exporter, provider_tracer):+ current_between_yields = []++ def create_partial(**kwargs):+ yield AnswerSchema(answer="4")+ with provider_tracer.start_as_current_span("llm-chunk"):+ yield AnswerSchema(answer="42")++ client = sync_client()+ client.chat.completions.create_partial = create_partial+ agent = make_agent(client)++ partials = []+ for partial in agent.run_stream(QuestionSchema(question="?")):+ partials.append(partial.answer)+ current_between_yields.append(trace_api.get_current_span())++ assert partials == ["4", "42"]+ assert all(span is trace_api.INVALID_SPAN for span in current_between_yields)+ chunk_span, agent_span = spans_of(exporter)+ assert agent_span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_stream"+ assert chunk_span.parent.span_id == agent_span.context.span_id+ assert output_json(agent_span) == {"answer": "42"}+ assert agent_span.status.status_code == StatusCode.OK+++def test_run_stream_preserves_the_generator_return_value(exporter):+ agent = make_agent(sync_client())++ def consume():+ final = yield from agent.run_stream(QuestionSchema(question="?"))+ return final++ generator = consume()+ with pytest.raises(StopIteration) as stop:+ while True:+ next(generator)++ assert stop.value.value.answer == "42"+++def test_run_stream_with_no_partials_ends_ok_without_output(exporter):+ client = sync_client()+ client.chat.completions.create_partial = lambda **kwargs: iter([])+ agent = make_agent(client)++ assert list(agent.run_stream(QuestionSchema(question="?"))) == []++ (span,) = spans_of(exporter)+ assert span.status.status_code == StatusCode.OK+ assert SpanAttributes.OUTPUT_VALUE not in span.attributes+++def test_run_stream_closed_early_ends_span_and_closes_inner_generator(exporter):+ inner_closed = []++ def create_partial(**kwargs):+ try:+ yield AnswerSchema(answer="4")+ yield AnswerSchema(answer="42")+ finally:+ inner_closed.append(True)++ client = sync_client()+ client.chat.completions.create_partial = create_partial+ agent = make_agent(client)++ for partial in agent.run_stream(QuestionSchema(question="?")):+ break++ assert inner_closed == [True]+ (span,) = spans_of(exporter)+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True+ assert output_json(span) == {"answer": "4"}+ assert span.status.status_code == StatusCode.OK+++def test_run_stream_failure_mid_stream_marks_error(exporter):+ def create_partial(**kwargs):+ yield AnswerSchema(answer="4")+ raise RuntimeError("stream broke")++ client = sync_client()+ client.chat.completions.create_partial = create_partial+ agent = make_agent(client)++ with pytest.raises(RuntimeError, match="stream broke"):+ list(agent.run_stream(QuestionSchema(question="?")))++ (span,) = spans_of(exporter)+ assert span.status.status_code == StatusCode.ERROR+++async def test_run_async_emits_agent_span(exporter):+ agent = make_agent(async_client())++ response = await agent.run_async(QuestionSchema(question="?"))++ assert response.answer == "42"+ (span,) = spans_of(exporter)+ assert span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_async"+ assert output_json(span) == {"answer": "42"}+ assert span.status.status_code == StatusCode.OK+++async def test_run_async_stream_records_last_partial_and_nests_children(exporter, provider_tracer):+ async def create_partial(**kwargs):+ yield AnswerSchema(answer="4")+ with provider_tracer.start_as_current_span("llm-chunk"):+ yield AnswerSchema(answer="42")++ client = async_client()+ client.chat.completions.create_partial = create_partial+ agent = make_agent(client)++ partials = [partial.answer async for partial in agent.run_async_stream(QuestionSchema(question="?"))]++ assert partials == ["4", "42"]+ chunk_span, agent_span = spans_of(exporter)+ assert agent_span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_async_stream"+ assert chunk_span.parent.span_id == agent_span.context.span_id+ assert output_json(agent_span) == {"answer": "42"}+++async def test_run_async_stream_closed_early_ends_span(exporter):+ agent = make_agent(async_client())++ stream = agent.run_async_stream(QuestionSchema(question="?"))+ first = await stream.__anext__()+ await stream.aclose()++ assert first.answer == "4"+ (span,) = spans_of(exporter)+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True+ assert span.status.status_code == StatusCode.OK+++async def test_concurrent_async_runs_keep_separate_spans(exporter):+ first = make_agent(async_client(response=AnswerSchema(answer="one")))+ second = make_agent(async_client(response=AnswerSchema(answer="two")))++ await asyncio.gather(first.run_async(QuestionSchema(question="1")), second.run_async(QuestionSchema(question="2")))++ outputs = {input_json(span)["question"]: output_json(span)["answer"] for span in spans_of(exporter)}+ assert outputs == {"1": "one", "2": "two"}+ assert all(span.parent is None for span in spans_of(exporter))+++def test_tool_defined_before_instrumentation_emits_tool_span(exporter):+ tool = CalculatorTool()++ result = tool.run(CalculationInputSchema(expression="6*7"), precision=1)++ assert result.result == "3.0"+ (span,) = spans_of(exporter)+ assert span.name == "CalculatorTool"+ assert kind_of(span) == OpenInferenceSpanKindValues.TOOL.value+ assert span.attributes[SpanAttributes.TOOL_NAME] == "CalculationInputSchema"+ assert span.attributes[SpanAttributes.TOOL_DESCRIPTION] == "Expression to evaluate."+ assert json.loads(span.attributes[SpanAttributes.TOOL_PARAMETERS])["title"] == "CalculationInputSchema"+ assert input_json(span) == {"expression": "6*7"}+ assert output_json(span) == {"result": "3.0"}+ assert span.status.status_code == StatusCode.OK+++def test_tool_accepts_keyword_params(exporter):+ result = CalculatorTool().run(params=CalculationInputSchema(expression="1+1"))++ assert result.result == "3.00"+ (span,) = spans_of(exporter)+ assert input_json(span) == {"expression": "1+1"}+++def test_tool_defined_after_instrumentation_emits_tool_span(exporter):+ class LateTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="late")++ LateTool().run(CalculationInputSchema(expression="x"))++ (span,) = spans_of(exporter)+ assert span.name == "LateTool"+ assert LateTool().input_schema is CalculationInputSchema+++def test_subclass_calling_super_run_emits_one_span(exporter):+ class LoudCalculatorTool(CalculatorTool):+ def run(self, params: CalculationInputSchema, precision: int = 2) -> CalculationOutputSchema:+ return super().run(params, precision)++ LoudCalculatorTool().run(CalculationInputSchema(expression="2*2"))++ (span,) = spans_of(exporter)+ assert span.name == "LoudCalculatorTool"+++def test_sync_run_delegating_to_arun_emits_one_span(exporter):+ AsyncCalculatorTool().run(CalculationInputSchema(expression="2*2"))++ (span,) = spans_of(exporter)+ assert span.name == "AsyncCalculatorTool"+ assert output_json(span) == {"result": "3"}+++async def test_run_async_delegating_to_thread_emits_one_span(exporter):+ await ThreadedCalculatorTool().run_async(CalculationInputSchema(expression="3*3"))++ (span,) = spans_of(exporter)+ assert span.name == "ThreadedCalculatorTool"+ assert output_json(span) == {"result": "3"}+++def test_mixin_defined_run_is_traced(exporter):+ MixinCalculatorTool().run(CalculationInputSchema(expression="x"))++ (span,) = spans_of(exporter)+ assert span.name == "MixinCalculatorTool"+++def test_static_run_is_left_alone(exporter):+ assert StaticRunTool.run(CalculationInputSchema(expression="x")).result == "static"+ assert spans_of(exporter) == []+++def test_tool_failure_propagates_same_exception_and_marks_error(exporter):+ with pytest.raises(ValueError, match="boom") as raised:+ FailingTool().run(CalculationInputSchema(expression="x"))++ (span,) = spans_of(exporter)+ assert span.status.status_code == StatusCode.ERROR+ assert raised.value.args == ("boom",)+++def test_unserializable_input_still_returns_result(exporter, caplog):+ with caplog.at_level(logging.WARNING):+ result = EchoTool().run(UnserializableInputSchema(store=AnswerStore()))++ assert result.result == "echo"+ (span,) = spans_of(exporter)+ assert span.status.status_code == StatusCode.OK+++def test_agent_run_inside_tool_nests_under_tool_span(exporter):+ agent = make_agent(sync_client())++ class AgentTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result=agent.run(QuestionSchema(question=params.expression)).answer)++ AgentTool().run(CalculationInputSchema(expression="?"))++ agent_span, tool_span = spans_of(exporter)+ assert agent_span.parent.span_id == tool_span.context.span_id+++def test_hide_inputs_and_outputs_redacts_values_and_drops_mime_types():+ exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(exporter))+ instrumentor = AtomicAgentsInstrumentor()+ instrumentor.instrument(tracer_provider=provider, config=TraceConfig(hide_inputs=True, hide_outputs=True))+ try:+ make_agent(sync_client()).run(QuestionSchema(question="secret"))+ CalculatorTool().run(CalculationInputSchema(expression="1+1"))+ finally:+ instrumentor.uninstrument()++ for span in spans_of(exporter):+ assert span.attributes[SpanAttributes.INPUT_VALUE] == "__REDACTED__"+ assert span.attributes[SpanAttributes.OUTPUT_VALUE] == "__REDACTED__"+ assert SpanAttributes.INPUT_MIME_TYPE not in span.attributes+ assert SpanAttributes.OUTPUT_MIME_TYPE not in span.attributes+++def test_session_and_user_metadata_survive_on_agent_span(exporter):+ agent = make_agent(sync_client())++ with using_session("session-1"), using_metadata({"tenant": "acme"}):+ agent.run(QuestionSchema(question="?"))++ (span,) = spans_of(exporter)+ assert span.attributes[SpanAttributes.SESSION_ID] == "session-1"+ assert json.loads(span.attributes[SpanAttributes.METADATA]) == {"tenant": "acme"}+++def test_second_instrument_with_other_settings_warns_and_keeps_first(exporter, caplog):+ other_provider = TracerProvider()++ with caplog.at_level(logging.WARNING):+ AtomicAgentsInstrumentor().instrument(tracer_provider=other_provider)++ assert "already installed" in caplog.text+ make_agent(sync_client()).run(QuestionSchema(question="?"))+ assert len(spans_of(exporter)) == 1+++def test_uninstrument_restores_originals_and_stops_tracing():+ original_run = AtomicAgent.__dict__["run"]+ original_tool_run = CalculatorTool.__dict__["run"]+ original_init_subclass = BaseTool.__dict__["__init_subclass__"]+ exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(exporter))+ instrumentor = AtomicAgentsInstrumentor()++ instrumentor.instrument(tracer_provider=provider)+ assert instrumentor.is_instrumented_by_opentelemetry+ instrumentor.uninstrument()+ instrumentor.uninstrument()++ assert not instrumentor.is_instrumented_by_opentelemetry+ assert AtomicAgent.__dict__["run"] is original_run+ assert CalculatorTool.__dict__["run"] is original_tool_run+ assert BaseTool.__dict__["__init_subclass__"] is original_init_subclass+ assert "run" not in MixinCalculatorTool.__dict__++ class AfterwardsTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="plain")++ assert AfterwardsTool().input_schema is CalculationInputSchema+ make_agent(sync_client()).run(QuestionSchema(question="?"))+ AfterwardsTool().run(CalculationInputSchema(expression="x"))+ assert spans_of(exporter) == []+++def test_phoenix_entry_point_loads_and_instruments_with_only_a_tracer_provider():+ (entry_point,) = [point for point in entry_points(group="openinference_instrumentor") if point.name == "atomic_agents"]+ exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(exporter))++ instrumentor = entry_point.load()()+ instrumentor.instrument(tracer_provider=provider)+ try:+ make_agent(sync_client()).run(QuestionSchema(question="?"))+ finally:+ instrumentor.uninstrument()++ assert isinstance(instrumentor, AtomicAgentsInstrumentor)+ assert len(spans_of(exporter)) == 1+++def test_instrument_without_openinference_raises_install_hint(monkeypatch):+ monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)++ with pytest.raises(ImportError, match="atomic-agents\\[observability\\]"):+ AtomicAgentsInstrumentor().instrument()+++def test_uninstrument_without_openinference_is_a_no_op(monkeypatch):+ monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)++ AtomicAgentsInstrumentor().uninstrument()++ assert not AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry+++def test_openinference_below_the_floor_disables_tracing_with_a_warning(monkeypatch, caplog):+ monkeypatch.setattr(observability, "version", lambda distribution: "0.1.20")++ with caplog.at_level(logging.WARNING):+ AtomicAgentsInstrumentor().instrument()++ assert "0.1.38 or newer is required" in caplog.text+ assert not AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry+ assert AtomicAgent.__dict__["run"].__name__ == "run"+ assert not hasattr(AtomicAgent.__dict__["run"], tracing.TRACED_MARKER)+++class CountingProvider(BaseDynamicContextProvider):+ def __init__(self):+ super().__init__(title="Counter")+ self.calls = 0++ def get_info(self) -> str:+ self.calls += 1+ return f"call {self.calls}"+++def test_prompt_hash_identifies_static_sections_despite_dynamic_providers(exporter):+ generator = SystemPromptGenerator(background=["v1"], context_providers={"counter": CountingProvider()})+ agent = AtomicAgent[QuestionSchema, AnswerSchema](+ AgentConfig(client=sync_client(), model="m", system_prompt_generator=generator)+ )++ agent.run(QuestionSchema(question="a"))+ agent.run(QuestionSchema(question="b"))++ first, second = spans_of(exporter)+ assert first.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256] == second.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]+ assert first.attributes[tracing.ATTR_CONTEXT_PROVIDERS] == ("counter",)+++def test_prompt_hash_changes_when_static_sections_change(exporter):+ agent = make_agent(sync_client())+ agent.run(QuestionSchema(question="a"))+ agent.system_prompt_generator.background = ["v2"]++ agent.run(QuestionSchema(question="b"))++ first, second = spans_of(exporter)+ assert first.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256] != second.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]+++def test_run_stream_dropped_without_close_still_ends_span(exporter):+ agent = make_agent(sync_client())+ stream = agent.run_stream(QuestionSchema(question="?"))+ next(stream)++ del stream+ gc.collect()++ (span,) = spans_of(exporter)+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True+++async def test_run_async_stream_cancelled_mid_await_is_not_an_error(exporter):+ release = asyncio.Event()++ async def create_partial(**kwargs):+ yield AnswerSchema(answer="4")+ await release.wait()+ yield AnswerSchema(answer="42")++ client = async_client()+ client.chat.completions.create_partial = create_partial+ agent = make_agent(client)++ async def consume():+ async for _ in agent.run_async_stream(QuestionSchema(question="?")):+ pass++ task = asyncio.create_task(consume())+ await asyncio.sleep(0.01)+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task++ (span,) = spans_of(exporter)+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True+ assert output_json(span) == {"answer": "4"}+ assert span.status.status_code != StatusCode.ERROR+++def test_forge_style_thread_pool_tool_emits_one_span_in_the_callers_trace(exporter, provider_tracer):+ class ForgeStyleTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ with ThreadPoolExecutor() as executor:+ return executor.submit(contextvars.copy_context().run, asyncio.run, self.run_async(params)).result()++ async def run_async(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="pooled")++ with provider_tracer.start_as_current_span("root") as root:+ ForgeStyleTool().run(CalculationInputSchema(expression="x"))++ tool_span, root_span = spans_of(exporter)+ assert tool_span.name == "ForgeStyleTool"+ assert tool_span.parent.span_id == root.get_span_context().span_id+ assert tool_span.context.trace_id == root_span.context.trace_id+++def test_mcp_style_generated_tool_class_emits_one_span(exporter):+ async def arun(self, params):+ return CalculationOutputSchema(result="mcp")++ def run(self, params):+ return asyncio.run(self.arun(params))++ GeneratedTool = types.new_class(+ "GeneratedTool",+ (BaseTool[CalculationInputSchema, CalculationOutputSchema],),+ {},+ lambda namespace: namespace.update({"run": run, "arun": arun}),+ )++ GeneratedTool().run(CalculationInputSchema(expression="x"))++ (span,) = spans_of(exporter)+ assert span.name == "GeneratedTool"+ assert output_json(span) == {"result": "mcp"}+++def test_async_generator_tool_method_is_left_alone(exporter):+ class StreamingTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="x")++ async def run_async(self, params: CalculationInputSchema):+ yield CalculationOutputSchema(result="chunk")++ assert not hasattr(StreamingTool.__dict__["run_async"], tracing.TRACED_MARKER)+ assert hasattr(StreamingTool.__dict__["run"], tracing.TRACED_MARKER)+++def test_instrument_uninstrument_instrument_cycle_traces_tools_defined_between_cycles():+ exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(exporter))+ instrumentor = AtomicAgentsInstrumentor()+ instrumentor.instrument(tracer_provider=provider)+ instrumentor.uninstrument()++ class BetweenCyclesTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:+ return CalculationOutputSchema(result="between")++ original_run = BetweenCyclesTool.__dict__["run"]+ instrumentor.instrument(tracer_provider=provider)+ try:+ BetweenCyclesTool().run(CalculationInputSchema(expression="x"))+ finally:+ instrumentor.uninstrument()++ assert [span.name for span in spans_of(exporter)] == ["BetweenCyclesTool"]+ assert BetweenCyclesTool.__dict__["run"] is original_rundiff --git a/pyproject.toml b/pyproject.tomlindex b99f9d2..3db1759 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -36,6 +36,13 @@ dependencies = ["litellm>=1.50.0,<2.0.0",]+[project.optional-dependencies]+observability = [+ "openinference-instrumentation>=0.1.38,<0.2.0",+ "openinference-semantic-conventions>=0.1.20,<0.2.0",+ "opentelemetry-api>=1.30.0,<2.0.0",+]+[project.urls]Homepage = "https://github.com/eigenwise/atomic-agents"Repository = "https://github.com/eigenwise/atomic-agents"@@ -43,6 +50,9 @@ Repository = "https://github.com/eigenwise/atomic-agents"[project.scripts]atomic = "atomic_assembler.main:main"+[project.entry-points.openinference_instrumentor]+atomic_agents = "atomic_agents.observability:AtomicAgentsInstrumentor"+[dependency-groups]dev = ["black>=24.8.0,<25.0.0",@@ -62,6 +72,9 @@ dev = ["beautifulsoup4>=4.12.3,<5.0.0","markdownify>=0.9.0,<1.0.0","sphinxcontrib-mermaid>=1.2.3",+ "openinference-instrumentation>=0.1.38,<0.2.0",+ "openinference-semantic-conventions>=0.1.20,<0.2.0",+ "opentelemetry-sdk>=1.30.0,<2.0.0",][tool.hatch.build.targets.wheel]diff --git a/uv.lock b/uv.lockindex e0a4a4c..9f54c63 100644--- a/uv.lock+++ b/uv.lock@@ -253,6 +253,13 @@ dependencies = [{ name = "textual" },]+[package.optional-dependencies]+observability = [+ { name = "openinference-instrumentation" },+ { name = "openinference-semantic-conventions" },+ { name = "opentelemetry-api" },+]+[package.dev-dependencies]dev = [{ name = "beautifulsoup4" },@@ -261,6 +268,9 @@ dev = [{ name = "markdownify" },{ name = "myst-parser" },{ name = "openai" },+ { name = "openinference-instrumentation" },+ { name = "openinference-semantic-conventions" },+ { name = "opentelemetry-sdk" },{ name = "pdoc3" },{ name = "pre-commit" },{ name = "pytest" },@@ -280,6 +290,9 @@ requires-dist = [{ name = "instructor", specifier = "==1.14.5" },{ name = "litellm", specifier = ">=1.50.0,<2.0.0" },{ name = "mcp", extras = ["cli"], specifier = ">=1.6.0" },+ { name = "openinference-instrumentation", marker = "extra == 'observability'", specifier = ">=0.1.38,<0.2.0" },+ { name = "openinference-semantic-conventions", marker = "extra == 'observability'", specifier = ">=0.1.20,<0.2.0" },+ { name = "opentelemetry-api", marker = "extra == 'observability'", specifier = ">=1.30.0,<2.0.0" },{ name = "pydantic", specifier = ">=2.11.0,<3.0.0" },{ name = "pyfiglet", specifier = ">=1.0.2,<2.0.0" },{ name = "pyyaml", specifier = ">=6.0.2,<7.0.0" },@@ -287,6 +300,7 @@ requires-dist = [{ name = "rich", specifier = ">=13.7.1,<14.0.0" },{ name = "textual", specifier = ">=5.3.0,<6.0.0" },]+provides-extras = ["observability"][package.metadata.requires-dev]dev = [@@ -296,6 +310,9 @@ dev = [{ name = "markdownify", specifier = ">=0.9.0,<1.0.0" },{ name = "myst-parser", specifier = ">=2.0.0,<3.0.0" },{ name = "openai", specifier = ">=2.0.0,<3.0.0" },+ { name = "openinference-instrumentation", specifier = ">=0.1.38,<0.2.0" },+ { name = "openinference-semantic-conventions", specifier = ">=0.1.20,<0.2.0" },+ { name = "opentelemetry-sdk", specifier = ">=1.30.0,<2.0.0" },{ name = "pdoc3", specifier = ">=0.11.1,<1.0.0" },{ name = "pre-commit", specifier = ">=4.0.0,<5.0.0" },{ name = "pytest", specifier = ">=8.3.3,<9.0.0" },@@ -2712,6 +2729,30 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/12/cf/03675d8bd8ecbf4445504d8071adab19f5f993676795708e36402ab38263/openapi_pydantic-0.5.1-py3-none-any.whl", hash = "sha256:a3a09ef4586f5bd760a8df7f43028b60cafb6d9f61de2acba9574766255ab146", size = 96381, upload-time = "2025-01-08T19:29:25.275Z" },]+[[package]]+name = "openinference-instrumentation"+version = "0.1.71"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "openinference-semantic-conventions" },+ { name = "opentelemetry-api" },+ { name = "opentelemetry-sdk" },+ { name = "wrapt" },+]+sdist = { url = "https://files.pythonhosted.org/packages/56/ec/ef1ca7e409ee6bddb7278b9760e0941f65911748f5dc84d17c115f6648f1/openinference_instrumentation-0.1.71.tar.gz", hash = "sha256:4d267b6ce8e067572a740d6a0dbf6b4d4c6e386c5a52a7e7f61e3a714a49849d", size = 46600, upload-time = "2026-10-07T20:26:41.084Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/7c/8c/330101bedf614dc937d8690462ed0ad4efd7f6c3248a76a5484ba6f885e3/openinference_instrumentation-0.1.71-py3-none-any.whl", hash = "sha256:07833fcf5d493a2ed15da16a0af70d6127d39f18ffa68f4d6827107e49fc6753", size = 54511, upload-time = "2026-10-07T20:26:39.634Z" },+]++[[package]]+name = "openinference-semantic-conventions"+version = "0.1.41"+source = { registry = "https://pypi.org/simple" }+sdist = { url = "https://files.pythonhosted.org/packages/53/be/e1fe52e3ae242695101144e058edfdd8e412a58ce04e2e2b410268683b05/openinference_semantic_conventions-0.1.41.tar.gz", hash = "sha256:78d4ffd9d1f2f89cb4bd58a0afe5a460475ce3d76a4d993f50fb0ce8bf4129a3", size = 15789, upload-time = "2026-10-01T18:22:33.408Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/74/fa/a5197690b860f8a5b43e56aba4a34e0b42db6548b45dd6ceda9ab8980c63/openinference_semantic_conventions-0.1.41-py3-none-any.whl", hash = "sha256:4c55f59427436da842c7aae871965399ef92b8909b41e02c076e1092b4c12e51", size = 12678, upload-time = "2026-10-01T18:22:32.275Z" },+]+[[package]]name = "opentelemetry-api"version = "1.38.0"@@ -4857,6 +4898,35 @@ dev = [{ name = "pytest-cov", specifier = ">=5.0.0,<6.0.0" },]+[[package]]+name = "wrapt"+version = "1.17.3"+source = { registry = "https://pypi.org/simple" }+sdist = { url = "https://files.pythonhosted.org/packages/95/8f/aeb76c5b46e273670962298c23e7ddde79916cb74db802131d49a85e4b7d/wrapt-1.17.3.tar.gz", hash = "sha256:f66eb08feaa410fe4eebd17f2a2c8e2e46d3476e9f8c783daa8e09e0faa666d0", size = 55547, upload-time = "2025-08-12T05:53:21.714Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/9f/41/cad1aba93e752f1f9268c77270da3c469883d56e2798e7df6240dcb2287b/wrapt-1.17.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab232e7fdb44cdfbf55fc3afa31bcdb0d8980b9b95c38b6405df2acb672af0e0", size = 53998, upload-time = "2025-08-12T05:51:47.138Z" },+ { url = "https://files.pythonhosted.org/packages/60/f8/096a7cc13097a1869fe44efe68dace40d2a16ecb853141394047f0780b96/wrapt-1.17.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:9baa544e6acc91130e926e8c802a17f3b16fbea0fd441b5a60f5cf2cc5c3deba", size = 39020, upload-time = "2025-08-12T05:51:35.906Z" },+ { url = "https://files.pythonhosted.org/packages/33/df/bdf864b8997aab4febb96a9ae5c124f700a5abd9b5e13d2a3214ec4be705/wrapt-1.17.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6b538e31eca1a7ea4605e44f81a48aa24c4632a277431a6ed3f328835901f4fd", size = 39098, upload-time = "2025-08-12T05:51:57.474Z" },+ { url = "https://files.pythonhosted.org/packages/9f/81/5d931d78d0eb732b95dc3ddaeeb71c8bb572fb01356e9133916cd729ecdd/wrapt-1.17.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:042ec3bb8f319c147b1301f2393bc19dba6e176b7da446853406d041c36c7828", size = 88036, upload-time = "2025-08-12T05:52:34.784Z" },+ { url = "https://files.pythonhosted.org/packages/ca/38/2e1785df03b3d72d34fc6252d91d9d12dc27a5c89caef3335a1bbb8908ca/wrapt-1.17.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3af60380ba0b7b5aeb329bc4e402acd25bd877e98b3727b0135cb5c2efdaefe9", size = 88156, upload-time = "2025-08-12T05:52:13.599Z" },+ { url = "https://files.pythonhosted.org/packages/b3/8b/48cdb60fe0603e34e05cffda0b2a4adab81fd43718e11111a4b0100fd7c1/wrapt-1.17.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0b02e424deef65c9f7326d8c19220a2c9040c51dc165cddb732f16198c168396", size = 87102, upload-time = "2025-08-12T05:52:14.56Z" },+ { url = "https://files.pythonhosted.org/packages/3c/51/d81abca783b58f40a154f1b2c56db1d2d9e0d04fa2d4224e357529f57a57/wrapt-1.17.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:74afa28374a3c3a11b3b5e5fca0ae03bef8450d6aa3ab3a1e2c30e3a75d023dc", size = 87732, upload-time = "2025-08-12T05:52:36.165Z" },+ { url = "https://files.pythonhosted.org/packages/9e/b1/43b286ca1392a006d5336412d41663eeef1ad57485f3e52c767376ba7e5a/wrapt-1.17.3-cp312-cp312-win32.whl", hash = "sha256:4da9f45279fff3543c371d5ababc57a0384f70be244de7759c85a7f989cb4ebe", size = 36705, upload-time = "2025-08-12T05:53:07.123Z" },+ { url = "https://files.pythonhosted.org/packages/28/de/49493f962bd3c586ab4b88066e967aa2e0703d6ef2c43aa28cb83bf7b507/wrapt-1.17.3-cp312-cp312-win_amd64.whl", hash = "sha256:e71d5c6ebac14875668a1e90baf2ea0ef5b7ac7918355850c0908ae82bcb297c", size = 38877, upload-time = "2025-08-12T05:53:05.436Z" },+ { url = "https://files.pythonhosted.org/packages/f1/48/0f7102fe9cb1e8a5a77f80d4f0956d62d97034bbe88d33e94699f99d181d/wrapt-1.17.3-cp312-cp312-win_arm64.whl", hash = "sha256:604d076c55e2fdd4c1c03d06dc1a31b95130010517b5019db15365ec4a405fc6", size = 36885, upload-time = "2025-08-12T05:52:54.367Z" },+ { url = "https://files.pythonhosted.org/packages/fc/f6/759ece88472157acb55fc195e5b116e06730f1b651b5b314c66291729193/wrapt-1.17.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a47681378a0439215912ef542c45a783484d4dd82bac412b71e59cf9c0e1cea0", size = 54003, upload-time = "2025-08-12T05:51:48.627Z" },+ { url = "https://files.pythonhosted.org/packages/4f/a9/49940b9dc6d47027dc850c116d79b4155f15c08547d04db0f07121499347/wrapt-1.17.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:54a30837587c6ee3cd1a4d1c2ec5d24e77984d44e2f34547e2323ddb4e22eb77", size = 39025, upload-time = "2025-08-12T05:51:37.156Z" },+ { url = "https://files.pythonhosted.org/packages/45/35/6a08de0f2c96dcdd7fe464d7420ddb9a7655a6561150e5fc4da9356aeaab/wrapt-1.17.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:16ecf15d6af39246fe33e507105d67e4b81d8f8d2c6598ff7e3ca1b8a37213f7", size = 39108, upload-time = "2025-08-12T05:51:58.425Z" },+ { url = "https://files.pythonhosted.org/packages/0c/37/6faf15cfa41bf1f3dba80cd3f5ccc6622dfccb660ab26ed79f0178c7497f/wrapt-1.17.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6fd1ad24dc235e4ab88cda009e19bf347aabb975e44fd5c2fb22a3f6e4141277", size = 88072, upload-time = "2025-08-12T05:52:37.53Z" },+ { url = "https://files.pythonhosted.org/packages/78/f2/efe19ada4a38e4e15b6dff39c3e3f3f73f5decf901f66e6f72fe79623a06/wrapt-1.17.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ed61b7c2d49cee3c027372df5809a59d60cf1b6c2f81ee980a091f3afed6a2d", size = 88214, upload-time = "2025-08-12T05:52:15.886Z" },+ { url = "https://files.pythonhosted.org/packages/40/90/ca86701e9de1622b16e09689fc24b76f69b06bb0150990f6f4e8b0eeb576/wrapt-1.17.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:423ed5420ad5f5529db9ce89eac09c8a2f97da18eb1c870237e84c5a5c2d60aa", size = 87105, upload-time = "2025-08-12T05:52:17.914Z" },+ { url = "https://files.pythonhosted.org/packages/fd/e0/d10bd257c9a3e15cbf5523025252cc14d77468e8ed644aafb2d6f54cb95d/wrapt-1.17.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e01375f275f010fcbf7f643b4279896d04e571889b8a5b3f848423d91bf07050", size = 87766, upload-time = "2025-08-12T05:52:39.243Z" },+ { url = "https://files.pythonhosted.org/packages/e8/cf/7d848740203c7b4b27eb55dbfede11aca974a51c3d894f6cc4b865f42f58/wrapt-1.17.3-cp313-cp313-win32.whl", hash = "sha256:53e5e39ff71b3fc484df8a522c933ea2b7cdd0d5d15ae82e5b23fde87d44cbd8", size = 36711, upload-time = "2025-08-12T05:53:10.074Z" },+ { url = "https://files.pythonhosted.org/packages/57/54/35a84d0a4d23ea675994104e667ceff49227ce473ba6a59ba2c84f250b74/wrapt-1.17.3-cp313-cp313-win_amd64.whl", hash = "sha256:1f0b2f40cf341ee8cc1a97d51ff50dddb9fcc73241b9143ec74b30fc4f44f6cb", size = 38885, upload-time = "2025-08-12T05:53:08.695Z" },+ { url = "https://files.pythonhosted.org/packages/01/77/66e54407c59d7b02a3c4e0af3783168fff8e5d61def52cda8728439d86bc/wrapt-1.17.3-cp313-cp313-win_arm64.whl", hash = "sha256:7425ac3c54430f5fc5e7b6f41d41e704db073309acfc09305816bc6a0b26bb16", size = 36896, upload-time = "2025-08-12T05:52:55.34Z" },+ { url = "https://files.pythonhosted.org/packages/1f/f6/a933bd70f98e9cf3e08167fc5cd7aaaca49147e48411c0bd5ae701bb2194/wrapt-1.17.3-py3-none-any.whl", hash = "sha256:7171ae35d2c33d326ac19dd8facb1e82e5fd04ef8c6c0e394d7af55a55051c22", size = 23591, upload-time = "2025-08-12T05:53:20.674Z" },+]+[[package]]name = "xmltodict"version = "1.0.4"