mirascope 2.0.0a6__py3-none-any.whl → 2.0.2__py3-none-any.whl

mirascope/llm/tools/tools.py

@@ -9,6 +9,7 @@ from typing_extensions import TypeVar
 
 from ..content import ToolCall, ToolOutput
 from ..context import Context, DepsT
+from ..exceptions import ToolError, ToolExecutionError
 from ..types import AnyP, JsonableCovariantT
 from .protocols import (
     AsyncContextToolFn,
@@ -42,13 +43,14 @@ class Tool(
 
     @classmethod
     def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
-        cls, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
+        cls, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool | None = None
     ) -> Tool[AnyP, JsonableCovariantT]:
         """Create a `Tool` by inspecting a function and its docstring.
 
         Args:
             fn: The function to extract schema from
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
 
         Returns:
             a `Tool` representing the function
@@ -68,10 +70,15 @@ class Tool(
 
     def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
         """Execute the tool using an LLM-provided `ToolCall`."""
-        kwargs_from_json = json.loads(tool_call.args)
         kwargs_callable = cast(KwargsCallable[JsonableCovariantT], self.fn)
-        result = kwargs_callable(**kwargs_from_json)
-        return ToolOutput(id=tool_call.id, value=result, name=self.name)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = kwargs_callable(**kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
 
 
 class AsyncTool(
@@ -88,13 +95,14 @@ class AsyncTool(
 
     @classmethod
     def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
-        cls, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
+        cls, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool | None = None
     ) -> AsyncTool[AnyP, JsonableCovariantT]:
         """Create an `AsyncTool` by inspecting a function and its docstring.
 
         Args:
             fn: The function to extract schema from
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
 
         Returns:
             an `AsyncTool` representing the function
@@ -116,10 +124,15 @@ class AsyncTool(
 
     async def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
         """Execute the async tool using an LLM-provided `ToolCall`."""
-        kwargs_from_json = json.loads(tool_call.args)
         kwargs_callable = cast(AsyncKwargsCallable[JsonableCovariantT], self.fn)
-        result = await kwargs_callable(**kwargs_from_json)
-        return ToolOutput(id=tool_call.id, value=result, name=self.name)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = await kwargs_callable(**kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
 
 
 class ContextTool(
@@ -139,13 +152,14 @@ class ContextTool(
         cls,
         fn: ContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
-        strict: bool = False,
+        strict: bool | None = None,
     ) -> ContextTool[DepsT, JsonableCovariantT, AnyP]:
         """Create a `ContextTool` by inspecting a function and its docstring.
 
         Args:
             fn: The function to extract schema from
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
 
         Returns:
             a `ContextTool` representing the function
@@ -172,12 +186,17 @@ class ContextTool(
         self, ctx: Context[DepsT], tool_call: ToolCall
     ) -> ToolOutput[JsonableCovariantT]:
         """Execute the context tool using an LLM-provided `ToolCall`."""
-        kwargs_from_json = json.loads(tool_call.args)
         kwargs_callable = cast(
             ContextKwargsCallable[DepsT, JsonableCovariantT], self.fn
         )
-        result = kwargs_callable(ctx, **kwargs_from_json)
-        return ToolOutput(id=tool_call.id, value=result, name=self.name)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = kwargs_callable(ctx, **kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
 
 
 class AsyncContextTool(
@@ -197,13 +216,14 @@ class AsyncContextTool(
         cls,
         fn: AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
-        strict: bool = False,
+        strict: bool | None = None,
     ) -> AsyncContextTool[DepsT, JsonableCovariantT, AnyP]:
         """Create an `AsyncContextTool` by inspecting a function and its docstring.
 
         Args:
             fn: The function to extract schema from
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
 
         Returns:
             an `AsyncContextTool` representing the function
@@ -230,9 +250,14 @@ class AsyncContextTool(
         self, ctx: Context[DepsT], tool_call: ToolCall
     ) -> ToolOutput[JsonableCovariantT]:
         """Execute the async context tool using an LLM-provided `ToolCall`."""
-        kwargs_from_json = json.loads(tool_call.args)
         kwargs_callable = cast(
             AsyncJsonKwargsCallable[DepsT, JsonableCovariantT], self.fn
         )
-        result = await kwargs_callable(ctx, **kwargs_from_json)
-        return ToolOutput(id=tool_call.id, value=result, name=self.name)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = await kwargs_callable(ctx, **kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)

mirascope/ops/__init__.py

@@ -41,8 +41,10 @@ from ._internal.traced_calls import (
 from ._internal.traced_functions import (
     AsyncTrace,
     AsyncTracedFunction,
+    AsyncTracedSpanFunction,
     Trace,
     TracedFunction,
+    TracedSpanFunction,
 )
 from ._internal.tracing import (
     TraceDecorator,
@@ -69,6 +71,7 @@ __all__ = [
     "SESSION_HEADER_NAME",
     "AsyncTrace",
     "AsyncTracedFunction",
+    "AsyncTracedSpanFunction",
     "AsyncVersionedFunction",
     "ClosureComputationError",
     "ContextPropagator",
@@ -82,6 +85,7 @@ __all__ = [
     "TracedCall",
     "TracedContextCall",
     "TracedFunction",
+    "TracedSpanFunction",
     "VersionDecorator",
     "VersionInfo",
     "VersionedAsyncCall",

mirascope/ops/_internal/closure.py

@@ -738,12 +738,15 @@ class _DependencyCollector:
             # For Python 3.13+
             return definition.func  # pyright: ignore[reportFunctionMemberAccess] # pragma: no cover
 
+        # Handle objects with .fn but no __qualname__ (e.g., old-style wrappers).
+        # With copy_function_metadata() now copying __qualname__ to ToolSchema, Prompt,
+        # Call, etc., this branch is no longer reached in normal usage.
         if (
             (wrapped_function := getattr(definition, "fn", None)) is not None
             and not hasattr(definition, "__qualname__")
             and callable(wrapped_function)
         ):
-            return wrapped_function
+            return wrapped_function  # pragma: no cover
 
         return definition
 

mirascope/ops/_internal/configuration.py

@@ -2,22 +2,25 @@
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import TYPE_CHECKING
 
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from ...api.client import Mirascope
+from ...api.settings import update_settings
+from .exporters import MirascopeOTLPExporter
+
 if TYPE_CHECKING:
-    from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.trace import Tracer
-else:
-    Tracer = None
 
 DEFAULT_TRACER_NAME = "mirascope.llm"
 
-try:
-    from opentelemetry import trace as otel_trace
-except ImportError:  # pragma: no cover
-    otel_trace = None
+logger = logging.getLogger(__name__)
 
 _tracer_provider: TracerProvider | None = None
 _tracer_name: str = DEFAULT_TRACER_NAME
@@ -25,59 +28,107 @@ _tracer_version: str | None = None
 _tracer: Tracer | None = None
 
 
+def _create_mirascope_cloud_provider(
+    api_key: str | None = None, base_url: str | None = None
+) -> TracerProvider:
+    """Create a TracerProvider configured for Mirascope Cloud.
+
+    Args:
+        api_key: Optional API key. If not provided, uses MIRASCOPE_API_KEY env var.
+
+    Returns:
+        Configured TracerProvider with MirascopeOTLPExporter.
+
+    Raises:
+        RuntimeError: If API key is not available.
+    """
+    try:
+        client = Mirascope(api_key=api_key, base_url=base_url)
+    except (ValueError, RuntimeError) as e:
+        raise RuntimeError(
+            "Failed to create Mirascope Cloud client. "
+            "Set MIRASCOPE_API_KEY environment variable or pass api_key parameter."
+        ) from e
+
+    exporter = MirascopeOTLPExporter(client=client)
+    provider = TracerProvider()
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    return provider
+
+
 def configure(
     *,
+    api_key: str | None = None,
+    base_url: str | None = None,
     tracer_provider: TracerProvider | None = None,
     tracer_name: str = DEFAULT_TRACER_NAME,
     tracer_version: str | None = None,
 ) -> None:
-    """Configure the ops module defaults for tracing.
+    """Configure the ops module for tracing.
 
-    Sets up default tracer settings for the ops module. If a tracer_provider
-    is supplied, it will be installed as the global OpenTelemetry tracer provider.
+    When called without arguments, automatically configures Mirascope Cloud
+    using the MIRASCOPE_API_KEY environment variable.
 
     Args:
-        tracer_provider: Optional OpenTelemetry TracerProvider to use as default
-            and to install globally.
+        tracer_provider: Optional custom TracerProvider. If provided, this takes
+            precedence over automatic Mirascope Cloud configuration.
+        api_key: Optional Mirascope Cloud API key. If not provided, uses
+            MIRASCOPE_API_KEY environment variable.
         tracer_name: Tracer name to use when creating a tracer.
             Defaults to "mirascope.llm".
         tracer_version: Optional tracer version.
 
+    Raises:
+        RuntimeError: If no tracer_provider is given and Mirascope Cloud
+            cannot be configured (missing API key).
+
     Example:
+        Simple Mirascope Cloud configuration (recommended):
+        ```python
+        import os
+        os.environ["MIRASCOPE_API_KEY"] = "your-api-key"
 
-        Configure custom tracer settings:
+        from mirascope import ops
+
+        ops.configure()  # Automatically uses Mirascope Cloud
+        ```
+
+        With explicit API key:
+        ```python
+        from mirascope import ops
+
+        ops.configure(api_key="your-api-key")
+        ```
+
+        With custom tracer provider:
         ```python
         from mirascope import ops
         from opentelemetry.sdk.trace import TracerProvider
 
         provider = TracerProvider()
         ops.configure(tracer_provider=provider)
-        ops.instrument_llm()
         ```
     """
-    # TODO: refactor alongside other import error handling improvements
-    if otel_trace is None:  # pragma: no cover
-        raise ImportError(
-            "OpenTelemetry is not installed. Run `pip install mirascope[otel]` "
-            "before calling `ops.configure(tracer_provider=...)`."
-        )
-
     global _tracer_provider, _tracer_name, _tracer_version, _tracer
 
-    if tracer_provider is not None:
-        _tracer_provider = tracer_provider
-        otel_trace.set_tracer_provider(tracer_provider)
+    # Update settings so get_sync_client/get_async_client can use these values
+    if api_key is not None or base_url is not None:
+        update_settings(api_key=api_key, base_url=base_url)
+
+    # If no tracer_provider given, auto-configure Mirascope Cloud
+    if tracer_provider is None:
+        tracer_provider = _create_mirascope_cloud_provider(
+            api_key=api_key, base_url=base_url
+        )
+
+    _tracer_provider = tracer_provider
+    otel_trace.set_tracer_provider(tracer_provider)
 
     _tracer_name = tracer_name
     _tracer_version = tracer_version
 
-    if otel_trace is not None:
-        provider = (
-            otel_trace.get_tracer_provider()
-            if _tracer_provider is None
-            else _tracer_provider
-        )
-        _tracer = provider.get_tracer(_tracer_name, _tracer_version)
+    _tracer = tracer_provider.get_tracer(_tracer_name, _tracer_version)
 
 
 def set_tracer(tracer: Tracer | None) -> None:

mirascope/ops/_internal/exporters/exporters.py

@@ -20,14 +20,17 @@ from ....api._generated.traces.types import (
     TracesCreateRequestResourceSpansItemResource,
     TracesCreateRequestResourceSpansItemResourceAttributesItem,
     TracesCreateRequestResourceSpansItemResourceAttributesItemValue,
+    TracesCreateRequestResourceSpansItemResourceAttributesItemValueArrayValue,
     TracesCreateRequestResourceSpansItemScopeSpansItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemScope,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue,
+    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValueArrayValue,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemStatus,
 )
 from ....api.client import Mirascope
+from .utils import to_otlp_any_value
 
 logger = logging.getLogger(__name__)
 
@@ -233,39 +236,56 @@ class MirascopeOTLPExporter(SpanExporter):
                 message=span.status.description or "",
             )
 
+        # Convert events
+        events = None
+        if span.events:
+            events = []
+            for event in span.events:
+                event_attrs: list[dict[str, object]] = []
+                if event.attributes:
+                    for key, value in event.attributes.items():
+                        # Convert to OTLP attribute format with typed values
+                        attr_value = self._convert_event_attribute_value(value)
+                        event_attrs.append({"key": key, "value": attr_value})
+                events.append(
+                    {
+                        "name": event.name,
+                        "timeUnixNano": str(event.timestamp)
+                        if event.timestamp
+                        else None,
+                        "attributes": event_attrs if event_attrs else None,
+                    }
+                )
+
         trace_id = format(context.trace_id, "032x")
         span_id = format(context.span_id, "016x")
 
-        return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem(
-            trace_id=trace_id,
-            span_id=span_id,
-            parent_span_id=(
+        # Build kwargs, only including events if present (to avoid sending null)
+        kwargs: dict[str, object] = {
+            "trace_id": trace_id,
+            "span_id": span_id,
+            "parent_span_id": (
                 format(span.parent.span_id, "016x")
                 if span.parent and span.parent.span_id
                 else None
             ),
-            name=span.name,
-            kind=span.kind.value if span.kind else 0,
-            start_time_unix_nano=str(span.start_time) if span.start_time else "0",
-            end_time_unix_nano=str(span.end_time) if span.end_time else "0",
-            attributes=attributes or None,
-            status=status,
-        )
+            "name": span.name,
+            "kind": span.kind.value if span.kind else 0,
+            "start_time_unix_nano": str(span.start_time) if span.start_time else "0",
+            "end_time_unix_nano": str(span.end_time) if span.end_time else "0",
+            "attributes": attributes or None,
+            "status": status,
+        }
+        # Only include events if present (omit entirely to avoid sending null)
+        if events:
+            kwargs["events"] = events
+
+        return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem(**kwargs)  # type: ignore[arg-type]
 
     def _convert_attribute_value(
         self, value: AttributeValue
     ) -> TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API
-        """
+        """Convert OpenTelemetry AttributeValue to Mirascope API's KeyValueValue."""
         match value:
             case str():
                 return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
@@ -285,23 +305,21 @@ class MirascopeOTLPExporter(SpanExporter):
                 )
             case _:
                 return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    string_value=str(list(value))
+                    array_value=TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValueArrayValue(
+                        values=[to_otlp_any_value(v) for v in value]
+                    )
                 )
 
+    def _convert_event_attribute_value(
+        self, value: AttributeValue
+    ) -> dict[str, object]:
+        """Convert OpenTelemetry AttributeValue to OTLP event attribute value format."""
+        return to_otlp_any_value(value)
+
     def _convert_resource_attribute_value(
         self, value: AttributeValue
     ) -> TracesCreateRequestResourceSpansItemResourceAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's resource KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API resource attributes
-        """
+        """Convert OpenTelemetry AttributeValue to Mirascope API's resource KeyValueValue."""
         match value:
             case str():
                 return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
@@ -321,7 +339,9 @@ class MirascopeOTLPExporter(SpanExporter):
                 )
             case _:
                 return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    string_value=str(list(value))
+                    array_value=TracesCreateRequestResourceSpansItemResourceAttributesItemValueArrayValue(
+                        values=[to_otlp_any_value(v) for v in value]
+                    )
                 )
 
     def shutdown(self) -> None:

mirascope/ops/_internal/exporters/utils.py

@@ -4,6 +4,43 @@ This module provides helper functions for formatting and converting
 OpenTelemetry data types for export.
 """
 
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from opentelemetry.util.types import AttributeValue
+
+
+def to_otlp_any_value(value: AttributeValue) -> dict[str, object]:
+    """Convert AttributeValue to OTLP AnyValue (dict form).
+
+    - string/bool/int/float are converted to stringValue/boolValue/intValue/doubleValue
+    - Sequence (excluding str/bytes/Mapping) is converted to arrayValue.values
+    - Unsupported types fallback to stringValue=str(value)
+
+    Args:
+        value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
+
+    Returns:
+        A dict representing OTLP AnyValue (e.g., {"stringValue": "..."})
+    """
+    match value:
+        case str():
+            return {"stringValue": value}
+        case bool():
+            return {"boolValue": value}
+        case int():
+            return {"intValue": str(value)}
+        case float():
+            return {"doubleValue": value}
+        case _ if isinstance(value, bytes | bytearray | memoryview | Mapping):
+            return {"stringValue": str(value)}
+        case _ if isinstance(value, Sequence):
+            values = [to_otlp_any_value(v) for v in value]
+            return {"arrayValue": {"values": values}}
+        case _:
+            return {"stringValue": str(value)}
+
 
 def format_trace_id(trace_id: int) -> str:
     """Format a trace ID as a 32-character hex string.