mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/tools/decorator.py

@@ -14,8 +14,12 @@ from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
 class ToolDecorator:
     """Protocol for the tool decorator."""
 
-    strict: bool
-    """Whether to use strict tool calling, if supported by the provider."""
+    strict: bool | None = None
+    """Whether to use strict tool calling, if supported by the provider.
+    
+    If set to None, then it will use the provider's default setting (usually the 
+    strictest possible).
+    """
 
     @overload
     def __call__(  # pyright:ignore[reportOverlappingOverload]
@@ -62,15 +66,19 @@ class ToolDecorator:
         is_async = _tool_utils.is_async_tool_fn(fn)
 
         if is_context and is_async:
-            return AsyncContextTool[DepsT, JsonableCovariantT, P](
+            return AsyncContextTool[DepsT, JsonableCovariantT, P].from_function(
                 fn, strict=self.strict
             )
         elif is_context:
-            return ContextTool[DepsT, JsonableCovariantT, P](fn, strict=self.strict)
+            return ContextTool[DepsT, JsonableCovariantT, P].from_function(
+                fn, strict=self.strict
+            )
         elif is_async:
-            return AsyncTool[P, JsonableCovariantT](fn, strict=self.strict)
+            return AsyncTool[P, JsonableCovariantT].from_function(
+                fn, strict=self.strict
+            )
         else:
-            return Tool[P, JsonableCovariantT](fn, strict=self.strict)
+            return Tool[P, JsonableCovariantT].from_function(fn, strict=self.strict)
 
 
 @overload
@@ -102,7 +110,7 @@ def tool(__fn: ToolFn[P, JsonableCovariantT]) -> Tool[P, JsonableCovariantT]:
 
 
 @overload
-def tool(*, strict: bool = False) -> ToolDecorator:
+def tool(*, strict: bool | None = None) -> ToolDecorator:
     """Overload for setting non-default arguments."""
     ...
 
@@ -114,7 +122,7 @@ def tool(
     | AsyncToolFn[P, JsonableCovariantT]
     | None = None,
     *,
-    strict: bool = False,
+    strict: bool | None = None,
 ) -> (
     ContextTool[DepsT, JsonableCovariantT, P]
     | AsyncContextTool[DepsT, JsonableCovariantT, P]
@@ -133,6 +141,7 @@ def tool(
 
     Args:
         strict: Whether the tool should use strict mode when supported by the model.
+            If None, uses provider's default (usually as strict as possible).
 
     Returns:
         A decorator function that converts the function into a Tool or ContextTool.

mirascope/llm/tools/tool_schema.py

@@ -157,8 +157,12 @@ class ToolSchema(Generic[ToolFnT]):
     it should **not be modified** after the ToolSchema is created.
     """
 
-    strict: bool
-    """Whether the tool should use strict mode when supported by the model."""
+    strict: bool | None
+    """Whether the tool should use strict mode when supported by the model.
+    
+    If set to None, will use the provider's default setting (usually as strict as 
+    possible).
+    """
 
     def __hash__(self) -> int:
         if not hasattr(self, "_hash"):
@@ -175,10 +179,36 @@ class ToolSchema(Generic[ToolFnT]):
     def __init__(
         self,
         fn: ToolFnT,
+        name: str,
+        description: str,
+        parameters: ToolParameterSchema,
         *,
-        strict: bool = False,
-        is_context_tool: bool = False,
+        strict: bool | None = None,
     ) -> None:
+        """Create a `ToolSchema` with the provided values.
+
+        Args:
+            fn: The function that implements the tool's functionality
+            name: The name of the tool
+            description: Description of what the tool does
+            parameters: JSON Schema describing the parameters accepted by the tool
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
+        """
+        self.fn = fn
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.strict = strict
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: AnyToolFn,
+        *,
+        strict: bool | None = None,
+        is_context_tool: bool = False,
+    ) -> ToolSchema[AnyToolFn]:
         """Create a `ToolSchema` by inspecting a function and its docstring.
 
         Uses Pydantic's create_model to dynamically build a model from the function
@@ -187,7 +217,8 @@ class ToolSchema(Generic[ToolFnT]):
 
         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).
             is_context_tool: Whether this is a context tool (skips the context parameter)
 
         Returns:
@@ -264,11 +295,13 @@ class ToolSchema(Generic[ToolFnT]):
         if "$defs" in schema:
             parameters.defs = schema["$defs"]
 
-        self.fn = fn
-        self.name = name
-        self.description = description
-        self.parameters = parameters
-        self.strict = strict
+        return cls(
+            fn=cast(ToolFnT, fn),
+            name=name,
+            description=description,
+            parameters=parameters,
+            strict=strict,
+        )
 
     def can_execute(self, tool_call: ToolCall) -> bool:
         """Check if a `ToolCall` can be executed by tools with this `ToolSchema`.

mirascope/llm/tools/toolkit.py

@@ -60,7 +60,7 @@ class BaseToolkit(Generic[ToolSchemaT]):
         """
         tool = self.tools_dict.get(tool_call.name, None)
         if not tool:
-            raise ToolNotFoundError(f"Tool not found in toolkit: {tool_call.name}")
+            raise ToolNotFoundError(tool_call.name)
         return tool
 
 
@@ -75,12 +75,14 @@ class Toolkit(BaseToolkit[Tool]):
 
         Returns:
             The output from executing the `Tool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        return tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class AsyncToolkit(BaseToolkit[AsyncTool]):
@@ -94,12 +96,14 @@ class AsyncToolkit(BaseToolkit[AsyncTool]):
 
         Returns:
             The output from executing the `AsyncTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        return await tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class ContextToolkit(BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]):
@@ -114,15 +118,17 @@ class ContextToolkit(BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]):
 
         Returns:
             The output from executing the `ContextTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        if isinstance(tool, ContextTool):
-            return tool.execute(ctx, tool_call)
-        else:
-            return tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, ContextTool):
+                return tool.execute(ctx, tool_call)
+            else:
+                return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class AsyncContextToolkit(
@@ -141,12 +147,14 @@ class AsyncContextToolkit(
 
         Returns:
             The output from executing the `AsyncContextTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        if isinstance(tool, AsyncContextTool):
-            return await tool.execute(ctx, tool_call)
-        else:
-            return await tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, AsyncContextTool):
+                return await tool.execute(ctx, tool_call)
+            else:
+                return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )

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,
@@ -40,10 +41,28 @@ class Tool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=False)
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        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.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            a `Tool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(ToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(self, *args: AnyP.args, **kwargs: AnyP.kwargs) -> JsonableCovariantT:
         """Call the underlying function directly."""
@@ -51,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(
@@ -69,10 +93,28 @@ class AsyncTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=False)
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        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.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            an `AsyncTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(AsyncToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self, *args: AnyP.args, **kwargs: AnyP.kwargs
@@ -82,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(
@@ -100,13 +147,31 @@ class ContextTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self,
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
         fn: ContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
-        strict: bool = False,
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=True)
+        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.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            a `ContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(ContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self,
@@ -121,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(
@@ -141,13 +211,31 @@ class AsyncContextTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self,
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
         fn: AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
-        strict: bool = False,
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=True)
+        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.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            an `AsyncContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self,
@@ -162,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

@@ -2,122 +2,76 @@
 
 from __future__ import annotations
 
-try:
-    from ._internal.configuration import configure, tracer_context
-    from ._internal.context import propagated_context
-    from ._internal.instrumentation.llm import (
-        instrument_llm,
-        uninstrument_llm,
-    )
-    from ._internal.propagation import (
-        ContextPropagator,
-        PropagatorFormat,
-        extract_context,
-        get_propagator,
-        inject_context,
-        reset_propagator,
-    )
-    from ._internal.session import (
-        SESSION_HEADER_NAME,
-        SessionContext,
-        current_session,
-        extract_session_id,
-        session,
-    )
-    from ._internal.spans import Span, span
-    from ._internal.traced_calls import (
-        TracedAsyncCall,
-        TracedAsyncContextCall,
-        TracedCall,
-        TracedContextCall,
-    )
-    from ._internal.traced_functions import (
-        AsyncTrace,
-        AsyncTracedFunction,
-        Trace,
-        TracedFunction,
-    )
-    from ._internal.tracing import (
-        TraceDecorator,
-        trace,
-    )
-    from ._internal.versioned_calls import (
-        VersionedAsyncCall,
-        VersionedAsyncContextCall,
-        VersionedCall,
-        VersionedContextCall,
-    )
-    from ._internal.versioned_functions import (
-        AsyncVersionedFunction,
-        VersionedFunction,
-        VersionInfo,
-    )
-    from ._internal.versioning import (
-        VersionDecorator,
-        version,
-    )
-    from .exceptions import ClosureComputationError
+from .._stubs import stub_module_if_missing
 
-except ImportError:  # pragma: no cover
-    # TODO: refactor alongside other import error handling improvements
-    from collections.abc import Callable
-
-    def _create_otel_import_error_stub(name: str) -> Callable[..., None]:
-        """Create a stub that raises ImportError with helpful message."""
-
-        def _raise_not_installed() -> None:
-            raise ImportError(
-                f"The 'opentelemetry' packages are required to use {name}. "
-                "Install them with: `uv add 'mirascope[otel]'`."
-            )
-
-        return _raise_not_installed
-
-    propagated_context = _create_otel_import_error_stub("propagated_context")
-    instrument_llm = _create_otel_import_error_stub("instrument_llm")
-    uninstrument_llm = _create_otel_import_error_stub("uninstrument_llm")
-    ContextPropagator = _create_otel_import_error_stub("ContextPropagator")
-    PropagatorFormat = str
-    extract_context = _create_otel_import_error_stub("extract_context")
-    get_propagator = _create_otel_import_error_stub("get_propagator")
-    inject_context = _create_otel_import_error_stub("inject_context")
-    reset_propagator = _create_otel_import_error_stub("reset_propagator")
-    SESSION_HEADER_NAME = "X-Mirascope-Session-ID"
-    SessionContext = _create_otel_import_error_stub("SessionContext")
-    current_session = _create_otel_import_error_stub("current_session")
-    extract_session_id = _create_otel_import_error_stub("extract_session_id")
-    session = _create_otel_import_error_stub("session")
-    Span = _create_otel_import_error_stub("Span")
-    span = _create_otel_import_error_stub("span")
-    AsyncTrace = _create_otel_import_error_stub("AsyncTrace")
-    AsyncTracedFunction = _create_otel_import_error_stub("AsyncTracedFunction")
-    Trace = _create_otel_import_error_stub("Trace")
-    TraceDecorator = _create_otel_import_error_stub("TraceDecorator")
-    TracedAsyncCall = _create_otel_import_error_stub("TracedAsyncCall")
-    TracedAsyncContextCall = _create_otel_import_error_stub("TracedAsyncContextCall")
-    TracedCall = _create_otel_import_error_stub("TracedCall")
-    TracedContextCall = _create_otel_import_error_stub("TracedContextCall")
-    TracedFunction = _create_otel_import_error_stub("TracedFunction")
-    trace = _create_otel_import_error_stub("trace")
-    configure = _create_otel_import_error_stub("configure")
-    tracer_context = _create_otel_import_error_stub("tracer_context")
-    AsyncVersionedFunction = _create_otel_import_error_stub("AsyncVersionedFunction")
-    VersionDecorator = _create_otel_import_error_stub("VersionDecorator")
-    VersionedAsyncCall = _create_otel_import_error_stub("VersionedAsyncCall")
-    VersionedAsyncContextCall = _create_otel_import_error_stub(
-        "VersionedAsyncContextCall"
-    )
-    VersionedCall = _create_otel_import_error_stub("VersionedCall")
-    VersionedContextCall = _create_otel_import_error_stub("VersionedContextCall")
-    VersionedFunction = _create_otel_import_error_stub("VersionedFunction")
-    VersionInfo = _create_otel_import_error_stub("VersionInfo")
-    version = _create_otel_import_error_stub("version")
+# Stub modules for missing optional dependencies BEFORE importing
+# This must happen before any imports from these modules
+stub_module_if_missing("mirascope.ops", "ops")
 
+# Now imports work regardless of which packages are installed
+# ruff: noqa: E402
+from ._internal.configuration import configure, tracer_context
+from ._internal.context import propagated_context
+from ._internal.instrumentation.llm import (
+    instrument_llm,
+    uninstrument_llm,
+)
+from ._internal.propagation import (
+    ContextPropagator,
+    PropagatorFormat,
+    extract_context,
+    get_propagator,
+    inject_context,
+    reset_propagator,
+)
+from ._internal.session import (
+    SESSION_HEADER_NAME,
+    SessionContext,
+    current_session,
+    extract_session_id,
+    session,
+)
+from ._internal.spans import Span, span
+from ._internal.traced_calls import (
+    TracedAsyncCall,
+    TracedAsyncContextCall,
+    TracedCall,
+    TracedContextCall,
+)
+from ._internal.traced_functions import (
+    AsyncTrace,
+    AsyncTracedFunction,
+    AsyncTracedSpanFunction,
+    Trace,
+    TracedFunction,
+    TracedSpanFunction,
+)
+from ._internal.tracing import (
+    TraceDecorator,
+    trace,
+)
+from ._internal.versioned_calls import (
+    VersionedAsyncCall,
+    VersionedAsyncContextCall,
+    VersionedCall,
+    VersionedContextCall,
+)
+from ._internal.versioned_functions import (
+    AsyncVersionedFunction,
+    VersionedFunction,
+    VersionInfo,
+)
+from ._internal.versioning import (
+    VersionDecorator,
+    version,
+)
+from .exceptions import ClosureComputationError
 
 __all__ = [
     "SESSION_HEADER_NAME",
     "AsyncTrace",
     "AsyncTracedFunction",
+    "AsyncTracedSpanFunction",
     "AsyncVersionedFunction",
     "ClosureComputationError",
     "ContextPropagator",
@@ -131,6 +85,7 @@ __all__ = [
     "TracedCall",
     "TracedContextCall",
     "TracedFunction",
+    "TracedSpanFunction",
     "VersionDecorator",
     "VersionInfo",
     "VersionedAsyncCall",