mirascope 2.0.0a6__py3-none-any.whl → 2.0.1__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/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

@@ -233,24 +233,51 @@ 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
@@ -288,6 +315,32 @@ class MirascopeOTLPExporter(SpanExporter):
                     string_value=str(list(value))
                 )
 
+    def _convert_event_attribute_value(
+        self, value: AttributeValue
+    ) -> dict[str, object]:
+        """Convert OpenTelemetry AttributeValue to OTLP event attribute value format.
+
+        This uses the OTLP JSON format with typed value wrappers (e.g., stringValue, intValue).
+
+        Args:
+            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
+
+        Returns:
+            A dict with the typed value (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 _:
+                # Sequences - convert to string representation
+                return {"stringValue": str(list(value))}
+
     def _convert_resource_attribute_value(
         self, value: AttributeValue
     ) -> TracesCreateRequestResourceSpansItemResourceAttributesItemValue: