mirascope 1.25.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

mirascope/llm/tools/toolkit.py

@@ -0,0 +1,160 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ..content import ToolCall, ToolOutput
+from ..context import Context, DepsT
+from ..exceptions import ToolNotFoundError
+from ..types import Jsonable
+from .tool_schema import ToolSchemaT
+from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+
+ToolkitT = TypeVar(
+    "ToolkitT",
+    bound="Toolkit | AsyncToolkit | ContextToolkit[Any] | AsyncContextToolkit[Any]",
+    covariant=True,
+)
+
+
+@dataclass
+class BaseToolkit(Generic[ToolSchemaT]):
+    """Base class for tool collections.
+
+    Provides common functionality for managing collections of tools,
+    including name validation and tool lookup.
+    """
+
+    tools: Sequence[ToolSchemaT]
+    """The tools included in the toolkit."""
+
+    tools_dict: dict[str, ToolSchemaT]
+    """A mapping from tool names to tools in the toolkit."""
+
+    def __init__(self, tools: Sequence[ToolSchemaT] | None) -> None:
+        """Initialize the toolkit with a collection of tools.
+
+        Args:
+            tools: Sequence of tools to include in the toolkit.
+
+        Raises:
+            ValueError: If multiple tools have the same name.
+        """
+        self.tools = tools or []
+        self.tools_dict = {}
+        for tool in self.tools:
+            if tool.name in self.tools_dict:
+                raise ValueError(f"Multiple tools with name: {tool.name}")
+            self.tools_dict[tool.name] = tool
+
+    def get(self, tool_call: ToolCall) -> ToolSchemaT:
+        """Get a tool that can execute a specific tool call.
+
+        Args:
+            tool_call: The tool call containing the tool name to lookup.
+
+        Returns:
+            The tool whose name matches the tool call.
+
+        Raises:
+            ToolNotFoundError: If no tool with the given name exists.
+        """
+        tool = self.tools_dict.get(tool_call.name, None)
+        if not tool:
+            raise ToolNotFoundError(tool_call.name)
+        return tool
+
+
+class Toolkit(BaseToolkit[Tool]):
+    """A collection of `Tool`s, with helpers for getting and executing specific tools."""
+
+    def execute(self, tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute a `Tool` using the provided tool call.
+
+        Args:
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `Tool`.
+        """
+        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]):
+    """A collection of `AsyncTool`s, with helpers for getting and executing specific tools."""
+
+    async def execute(self, tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute an `AsyncTool` using the provided tool call.
+
+        Args:
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `AsyncTool`.
+        """
+        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]):
+    """A collection of `ContextTool`s, with helpers for getting and executing specific tools."""
+
+    def execute(self, ctx: Context[DepsT], tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute a `ContextTool` using the provided tool call.
+
+        Args:
+            ctx: The context containing dependencies that match the tool.
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `ContextTool`.
+        """
+        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(
+    BaseToolkit[AsyncTool | AsyncContextTool[DepsT]], Generic[DepsT]
+):
+    """A collection of `AsyncContextTool`s, with helpers for getting and executing specific tools."""
+
+    async def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[Jsonable]:
+        """Execute an `AsyncContextTool` using the provided tool call.
+
+        Args:
+            ctx: The context containing dependencies that match the tool.
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `AsyncContextTool`.
+        """
+        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

@@ -0,0 +1,263 @@
+"""The `Tool` class for defining tools that LLMs can request be called."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Any, Generic, cast
+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,
+    AsyncJsonKwargsCallable,
+    AsyncKwargsCallable,
+    AsyncToolFn,
+    ContextKwargsCallable,
+    ContextToolFn,
+    KwargsCallable,
+    ToolFn,
+)
+from .tool_schema import ToolSchema
+
+ToolT = TypeVar(
+    "ToolT",
+    bound="Tool | AsyncTool | ContextTool[Any] | AsyncContextTool[Any]",
+    covariant=True,
+)
+
+
+class Tool(
+    ToolSchema[ToolFn[AnyP, JsonableCovariantT]], Generic[AnyP, JsonableCovariantT]
+):
+    """A tool that can be used by LLMs.
+
+    A `Tool` represents a function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @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."""
+        return self.fn(*args, **kwargs)
+
+    def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
+        """Execute the tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(KwargsCallable[JsonableCovariantT], self.fn)
+        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(
+    ToolSchema[AsyncToolFn[AnyP, JsonableCovariantT]],
+    Generic[AnyP, JsonableCovariantT],
+):
+    """An async tool that can be used by LLMs.
+
+    An `AsyncTool` represents an async function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @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
+    ) -> Awaitable[JsonableCovariantT]:
+        """Call the underlying async function directly."""
+        return self.fn(*args, **kwargs)
+
+    async def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
+        """Execute the async tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(AsyncKwargsCallable[JsonableCovariantT], self.fn)
+        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(
+    ToolSchema[ContextToolFn[DepsT, AnyP, JsonableCovariantT]],
+    Generic[DepsT, JsonableCovariantT, AnyP],
+):
+    """Protocol defining a tool that can be used by LLMs.
+
+    A `ContextTool` represents a function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
+        fn: ContextToolFn[DepsT, AnyP, JsonableCovariantT],
+        *,
+        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,
+        ctx: Context[DepsT],
+        *args: AnyP.args,
+        **kwargs: AnyP.kwargs,
+    ) -> JsonableCovariantT:
+        """Call the underlying function directly with context."""
+        return self.fn(ctx, *args, **kwargs)
+
+    def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[JsonableCovariantT]:
+        """Execute the context tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(
+            ContextKwargsCallable[DepsT, JsonableCovariantT], self.fn
+        )
+        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(
+    ToolSchema[AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT]],
+    Generic[DepsT, JsonableCovariantT, AnyP],
+):
+    """Protocol defining an async tool that can be used by LLMs with context.
+
+    An `AsyncContextTool` represents an async function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
+        fn: AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT],
+        *,
+        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,
+        ctx: Context[DepsT],
+        *args: AnyP.args,
+        **kwargs: AnyP.kwargs,
+    ) -> Awaitable[JsonableCovariantT]:
+        """Call the underlying async function directly with context."""
+        return self.fn(ctx, *args, **kwargs)
+
+    async def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[JsonableCovariantT]:
+        """Execute the async context tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(
+            AsyncJsonKwargsCallable[DepsT, JsonableCovariantT], self.fn
+        )
+        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/llm/types/__init__.py

@@ -0,0 +1,22 @@
+"""Types for the LLM module."""
+
+from .dataclass import Dataclass
+from .jsonable import (
+    Jsonable,
+    JsonableCovariantT,
+    JsonableT,
+)
+from .type_vars import AnyP, CovariantT, P
+
+NoneType = type(None)
+
+__all__ = [
+    "AnyP",
+    "CovariantT",
+    "Dataclass",
+    "Jsonable",
+    "JsonableCovariantT",
+    "JsonableT",
+    "NoneType",
+    "P",
+]

mirascope/llm/types/dataclass.py

@@ -0,0 +1,9 @@
+"""A protocol for defining a dataclass type."""
+
+from dataclasses import Field
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Dataclass(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, Field[Any]]]

mirascope/llm/types/jsonable.py

@@ -0,0 +1,44 @@
+"""Typing for JSON serializable objects."""
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol, TypeAlias
+from typing_extensions import TypeVar
+
+
+class JsonableObject(Protocol):
+    """Protocol for JSON-serializable objects.
+
+    This protocol defines the interface for objects that can be serialized to
+    JSON. It is used to annotate the `JsonableType` type alias.
+    """
+
+    def json(self) -> str:
+        """Serialize the object as a JSON string."""
+        ...
+
+
+Jsonable: TypeAlias = (
+    None
+    | str
+    | int
+    | float
+    | bool
+    | Sequence["Jsonable"]
+    | Mapping[str, "Jsonable"]
+    | JsonableObject
+)
+"""Simple type alias for JSON-serializable types."""
+
+
+JsonableT = TypeVar("JsonableT", bound=Jsonable)
+"""Type variable for tool output types.
+
+This TypeVar represents the return type of tool functions, which must be
+serializable to JSON (bound to Jsonable) for LLM consumption.
+"""
+
+
+JsonableCovariantT = TypeVar(
+    "JsonableCovariantT", covariant=True, bound=Jsonable, default=Jsonable
+)
+"""Type variable for covariant types that are Jsonable."""

mirascope/llm/types/type_vars.py

@@ -0,0 +1,19 @@
+"""Common TypeVar definitions for the LLM module."""
+
+from typing import TypeVar
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+"""Parameter specification for function signatures.
+
+This ParamSpec is used to preserve function parameter types and signatures
+when wrapping functions with decorators or creating generic callable types.
+It captures both positional and keyword arguments (*args, **kwargs) while
+maintaining their original types.
+"""
+
+AnyP = ParamSpec("AnyP", default=...)
+"""A parameter specification that defaults to ..."""
+
+CovariantT = TypeVar("CovariantT", covariant=True)
+"""Type variable for covariant types."""

mirascope/ops/__init__.py

@@ -0,0 +1,111 @@
+"""Operational helpers (tracing, sessions, future ops.* utilities)."""
+
+from __future__ import annotations
+
+from .._stubs import stub_module_if_missing
+
+# 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",
+    "PropagatorFormat",
+    "SessionContext",
+    "Span",
+    "Trace",
+    "TraceDecorator",
+    "TracedAsyncCall",
+    "TracedAsyncContextCall",
+    "TracedCall",
+    "TracedContextCall",
+    "TracedFunction",
+    "TracedSpanFunction",
+    "VersionDecorator",
+    "VersionInfo",
+    "VersionedAsyncCall",
+    "VersionedAsyncContextCall",
+    "VersionedCall",
+    "VersionedContextCall",
+    "VersionedFunction",
+    "configure",
+    "current_session",
+    "extract_context",
+    "extract_session_id",
+    "get_propagator",
+    "inject_context",
+    "instrument_llm",
+    "propagated_context",
+    "reset_propagator",
+    "session",
+    "span",
+    "trace",
+    "tracer_context",
+    "uninstrument_llm",
+    "version",
+]

mirascope/ops/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Private internal module for Mirascope.
+
+All modules within this directory are considered private implementation details
+and should not be imported directly by users.
+"""