mirascope 1.22.4__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/__init__.py

@@ -1,20 +1,316 @@
-from ..core import CostMetadata, LocalProvider, Provider, calculate_cost
-from ._call import call
-from ._context import context
-from ._override import override
-from .call_response import CallResponse
-from .stream import Stream
-from .tool import Tool
+"""LLM abstractions that aren't obstructions.
+
+This module provides a unified interface for interacting with different LLM providers,
+including messages, tools, response formatting, and streaming. It allows you to write
+code that works with multiple LLM providers without changing your application logic.
+"""
+
+# TODO: Across the API, audit docstrings to ensure they are compliant Google-style docstrings
+# (Write some tooling to ensure this happens consistently + in CI)
+
+from contextlib import suppress
+
+from . import (
+    calls,
+    content,
+    exceptions,
+    formatting,
+    messages,
+    models,
+    prompts,
+    providers,
+    responses,
+    tools,
+    types,
+)
+
+with suppress(ImportError):
+    from . import mcp
+from .calls import AsyncCall, AsyncContextCall, Call, CallDecorator, ContextCall, call
+from .content import (
+    AssistantContentChunk,
+    AssistantContentPart,
+    Audio,
+    Base64AudioSource,
+    Base64ImageSource,
+    Document,
+    Image,
+    Text,
+    TextChunk,
+    TextEndChunk,
+    TextStartChunk,
+    Thought,
+    ThoughtChunk,
+    ThoughtEndChunk,
+    ThoughtStartChunk,
+    ToolCall,
+    ToolCallChunk,
+    ToolCallEndChunk,
+    ToolCallStartChunk,
+    ToolOutput,
+    URLImageSource,
+    UserContentPart,
+)
+from .context import Context, DepsT
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    Error,
+    FeatureNotSupportedError,
+    MissingAPIKeyError,
+    NoRegisteredProviderError,
+    NotFoundError,
+    ParseError,
+    PermissionError,
+    ProviderError,
+    RateLimitError,
+    ResponseValidationError,
+    ServerError,
+    TimeoutError,
+    ToolError,
+    ToolExecutionError,
+    ToolNotFoundError,
+)
+from .formatting import (
+    Format,
+    FormatSpec,
+    FormattableT,
+    FormattingMode,
+    OutputParser,
+    Partial,
+    format,
+    output_parser,
+)
+from .messages import (
+    AssistantContent,
+    AssistantMessage,
+    Message,
+    SystemContent,
+    SystemMessage,
+    UserContent,
+    UserMessage,
+)
+from .models import (
+    Model,
+    Params,
+    ThinkingConfig,
+    ThinkingLevel,
+    model,
+    model_from_context,
+    use_model,
+)
+from .prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+    PromptDecorator,
+    prompt,
+)
+from .providers import (
+    ModelId,
+    Provider,
+    ProviderId,
+    register_provider,
+    reset_provider_registry,
+)
+from .responses import (
+    AnyResponse,
+    AsyncChunkIterator,
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStream,
+    AsyncStreamResponse,
+    AsyncTextStream,
+    AsyncThoughtStream,
+    AsyncToolCallStream,
+    ChunkIterator,
+    ContextResponse,
+    ContextStreamResponse,
+    FinishReason,
+    ProviderToolUsage,
+    RawMessageChunk,
+    Response,
+    RootResponse,
+    Stream,
+    StreamResponse,
+    StreamResponseChunk,
+    TextStream,
+    ThoughtStream,
+    ToolCallStream,
+    Usage,
+    UsageDeltaChunk,
+)
+from .tools import (
+    AnyToolFn,
+    AnyTools,
+    AnyToolSchema,
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncContextTools,
+    AsyncTool,
+    AsyncToolkit,
+    AsyncTools,
+    BaseToolkit,
+    ContextTool,
+    ContextToolkit,
+    ContextTools,
+    ProviderTool,
+    Tool,
+    Toolkit,
+    ToolkitT,
+    Tools,
+    ToolSchema,
+    WebSearchTool,
+    tool,
+)
+from .types import Jsonable
 
 __all__ = [
-    "CallResponse",
-    "CostMetadata",
-    "LocalProvider",
+    "APIError",
+    "AnyResponse",
+    "AnyToolFn",
+    "AnyToolSchema",
+    "AnyTools",
+    "AssistantContent",
+    "AssistantContentChunk",
+    "AssistantContentPart",
+    "AssistantMessage",
+    "AsyncCall",
+    "AsyncChunkIterator",
+    "AsyncContextCall",
+    "AsyncContextPrompt",
+    "AsyncContextResponse",
+    "AsyncContextStreamResponse",
+    "AsyncContextTool",
+    "AsyncContextToolkit",
+    "AsyncContextTools",
+    "AsyncPrompt",
+    "AsyncResponse",
+    "AsyncStream",
+    "AsyncStreamResponse",
+    "AsyncTextStream",
+    "AsyncThoughtStream",
+    "AsyncTool",
+    "AsyncToolCallStream",
+    "AsyncToolkit",
+    "AsyncTools",
+    "Audio",
+    "AuthenticationError",
+    "BadRequestError",
+    "Base64AudioSource",
+    "Base64ImageSource",
+    "BaseToolkit",
+    "Call",
+    "CallDecorator",
+    "ChunkIterator",
+    "ConnectionError",
+    "Context",
+    "ContextCall",
+    "ContextPrompt",
+    "ContextResponse",
+    "ContextStreamResponse",
+    "ContextTool",
+    "ContextToolkit",
+    "ContextTools",
+    "DepsT",
+    "Document",
+    "Error",
+    "FeatureNotSupportedError",
+    "FinishReason",
+    "Format",
+    "FormatSpec",
+    "FormattableT",
+    "FormattingMode",
+    "Image",
+    "Jsonable",
+    "Message",
+    "MissingAPIKeyError",
+    "Model",
+    "ModelId",
+    "NoRegisteredProviderError",
+    "NotFoundError",
+    "OutputParser",
+    "Params",
+    "ParseError",
+    "Partial",
+    "PermissionError",
+    "Prompt",
+    "PromptDecorator",
     "Provider",
+    "ProviderError",
+    "ProviderId",
+    "ProviderTool",
+    "ProviderToolUsage",
+    "RateLimitError",
+    "RawMessageChunk",
+    "Response",
+    "ResponseValidationError",
+    "RootResponse",
+    "ServerError",
     "Stream",
+    "StreamResponse",
+    "StreamResponseChunk",
+    "SystemContent",
+    "SystemMessage",
+    "Text",
+    "TextChunk",
+    "TextEndChunk",
+    "TextStartChunk",
+    "TextStream",
+    "ThinkingConfig",
+    "ThinkingLevel",
+    "Thought",
+    "ThoughtChunk",
+    "ThoughtEndChunk",
+    "ThoughtStartChunk",
+    "ThoughtStream",
+    "TimeoutError",
     "Tool",
-    "calculate_cost",
+    "ToolCall",
+    "ToolCallChunk",
+    "ToolCallEndChunk",
+    "ToolCallStartChunk",
+    "ToolCallStream",
+    "ToolError",
+    "ToolExecutionError",
+    "ToolNotFoundError",
+    "ToolOutput",
+    "ToolSchema",
+    "Toolkit",
+    "ToolkitT",
+    "Tools",
+    "URLImageSource",
+    "Usage",
+    "UsageDeltaChunk",
+    "UserContent",
+    "UserContentPart",
+    "UserMessage",
+    "WebSearchTool",
+    "WebSearchTool",
     "call",
-    "context",
-    "override",
+    "calls",
+    "content",
+    "exceptions",
+    "format",
+    "formatting",
+    "mcp",
+    "messages",
+    "model",
+    "model_from_context",
+    "models",
+    "output_parser",
+    "prompt",
+    "prompts",
+    "providers",
+    "register_provider",
+    "reset_provider_registry",
+    "responses",
+    "tool",
+    "tools",
+    "types",
+    "use_model",
 ]

mirascope/llm/calls/__init__.py

@@ -0,0 +1,17 @@
+"""The `llm.calls` module."""
+
+from .calls import AsyncCall, AsyncContextCall, Call, CallT, ContextCall
+from .decorator import (
+    CallDecorator,
+    call,
+)
+
+__all__ = [
+    "AsyncCall",
+    "AsyncContextCall",
+    "Call",
+    "CallDecorator",
+    "CallT",
+    "ContextCall",
+    "call",
+]

mirascope/llm/calls/calls.py

@@ -0,0 +1,348 @@
+"""The Call module for generating responses using LLMs."""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar, overload
+
+from ..._utils import copy_function_metadata
+from ..context import Context, DepsT
+from ..formatting import FormattableT
+from ..models import Model, use_model
+from ..prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+)
+from ..prompts.prompts import BasePrompt
+from ..responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ..types import P
+
+PromptT = TypeVar("PromptT", bound=BasePrompt[Callable[..., Any]])
+CallT = TypeVar("CallT", bound="BaseCall[Any]")
+
+
+@dataclass(kw_only=True)
+class BaseCall(Generic[PromptT]):
+    """Base class for all Call types with shared model functionality."""
+
+    default_model: Model
+    """The default model that will be used if no model is set in context."""
+
+    prompt: PromptT
+    """The underlying Prompt instance that generates messages with tools and format."""
+
+    __name__: str = field(init=False, repr=False, default="")
+    """The name of the underlying function (preserved for decorator stacking)."""
+
+    @property
+    def model(self) -> Model:
+        """The model used for generating responses. May be overwritten via `with llm.model(...)`."""
+        return use_model(self.default_model)
+
+    def __post_init__(self) -> None:
+        """Preserve standard function attributes for decorator stacking."""
+        copy_function_metadata(self, self.prompt.fn)
+
+
+@dataclass
+class Call(BaseCall[Prompt[P, FormattableT]], Generic[P, FormattableT]):
+    """A call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating a `MessageTemplate` with `llm.call`. The decorated function
+    becomes directly callable to generate responses, with the `Model` bundled in.
+
+    A `Call` is essentially: `MessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `call(*args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    @overload
+    def __call__(
+        self: "Call[P, None]", *args: P.args, **kwargs: P.kwargs
+    ) -> Response: ...
+
+    @overload
+    def __call__(
+        self: "Call[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> Response[FormattableT]: ...
+
+    def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> Response | Response[FormattableT]:
+        """Generates a response using the LLM."""
+        return self.call(*args, **kwargs)
+
+    @overload
+    def call(self: "Call[P, None]", *args: P.args, **kwargs: P.kwargs) -> Response: ...
+
+    @overload
+    def call(
+        self: "Call[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> Response[FormattableT]: ...
+
+    def call(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> Response | Response[FormattableT]:
+        """Generates a response using the LLM."""
+        return self.prompt.call(self.model, *args, **kwargs)
+
+    @overload
+    def stream(
+        self: "Call[P, None]", *args: P.args, **kwargs: P.kwargs
+    ) -> StreamResponse: ...
+
+    @overload
+    def stream(
+        self: "Call[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> StreamResponse[FormattableT]: ...
+
+    def stream(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generates a streaming response using the LLM."""
+        return self.prompt.stream(self.model, *args, **kwargs)
+
+
+@dataclass
+class AsyncCall(BaseCall[AsyncPrompt[P, FormattableT]], Generic[P, FormattableT]):
+    """An async call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating an async `MessageTemplate` with `llm.call`. The decorated async
+    function becomes directly callable to generate responses asynchronously, with the `Model` bundled in.
+
+    An `AsyncCall` is essentially: async `MessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `await call(*args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    @overload
+    async def __call__(
+        self: "AsyncCall[P, None]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse: ...
+
+    @overload
+    async def __call__(
+        self: "AsyncCall[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse[FormattableT]: ...
+
+    async def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generates a response using the LLM asynchronously."""
+        return await self.call(*args, **kwargs)
+
+    @overload
+    async def call(
+        self: "AsyncCall[P, None]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse: ...
+
+    @overload
+    async def call(
+        self: "AsyncCall[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse[FormattableT]: ...
+
+    async def call(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generates a response using the LLM asynchronously."""
+        return await self.prompt.call(self.model, *args, **kwargs)
+
+    @overload
+    async def stream(
+        self: "AsyncCall[P, None]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncStreamResponse: ...
+
+    @overload
+    async def stream(
+        self: "AsyncCall[P, FormattableT]", *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncStreamResponse[FormattableT]: ...
+
+    async def stream(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncStreamResponse[FormattableT] | AsyncStreamResponse:
+        """Generates a streaming response using the LLM asynchronously."""
+        return await self.prompt.stream(self.model, *args, **kwargs)
+
+
+@dataclass
+class ContextCall(
+    BaseCall[ContextPrompt[P, DepsT, FormattableT]], Generic[P, DepsT, FormattableT]
+):
+    """A context-aware call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating a `ContextMessageTemplate` with `llm.call`. The decorated function
+    (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
+    responses with context dependencies, with the `Model` bundled in.
+
+    A `ContextCall` is essentially: `ContextMessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `call(ctx, *args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    @overload
+    def __call__(
+        self: "ContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None]: ...
+
+    @overload
+    def __call__(
+        self: "ContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, FormattableT]: ...
+
+    def __call__(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generates a response using the LLM."""
+        return self.call(ctx, *args, **kwargs)
+
+    @overload
+    def call(
+        self: "ContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None]: ...
+
+    @overload
+    def call(
+        self: "ContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, FormattableT]: ...
+
+    def call(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generates a response using the LLM."""
+        return self.prompt.call(self.model, ctx, *args, **kwargs)
+
+    @overload
+    def stream(
+        self: "ContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextStreamResponse[DepsT, None]: ...
+
+    @overload
+    def stream(
+        self: "ContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextStreamResponse[DepsT, FormattableT]: ...
+
+    def stream(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> (
+        ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generates a streaming response using the LLM."""
+        return self.prompt.stream(self.model, ctx, *args, **kwargs)
+
+
+@dataclass
+class AsyncContextCall(
+    BaseCall[AsyncContextPrompt[P, DepsT, FormattableT]],
+    Generic[P, DepsT, FormattableT],
+):
+    """An async context-aware call that directly generates LLM responses without requiring a model argument.
+
+    Created by decorating an async `ContextMessageTemplate` with `llm.call`. The decorated async
+    function (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
+    responses asynchronously with context dependencies, with the `Model` bundled in.
+
+    An `AsyncContextCall` is essentially: async `ContextMessageTemplate` + tools + format + `Model`.
+    It can be invoked directly: `await call(ctx, *args, **kwargs)` (no model argument needed).
+
+    The model can be overridden at runtime using `with llm.model(...)` context manager.
+    """
+
+    @overload
+    async def __call__(
+        self: "AsyncContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None]: ...
+
+    @overload
+    async def __call__(
+        self: "AsyncContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, FormattableT]: ...
+
+    async def __call__(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generates a response using the LLM asynchronously."""
+        return await self.call(ctx, *args, **kwargs)
+
+    @overload
+    async def call(
+        self: "AsyncContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None]: ...
+
+    @overload
+    async def call(
+        self: "AsyncContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, FormattableT]: ...
+
+    async def call(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generates a response using the LLM asynchronously."""
+        return await self.prompt.call(self.model, ctx, *args, **kwargs)
+
+    @overload
+    async def stream(
+        self: "AsyncContextCall[P, DepsT, None]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextStreamResponse[DepsT, None]: ...
+
+    @overload
+    async def stream(
+        self: "AsyncContextCall[P, DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextStreamResponse[DepsT, FormattableT]: ...
+
+    async def stream(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> (
+        AsyncContextStreamResponse[DepsT, None]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generates a streaming response using the LLM asynchronously."""
+        return await self.prompt.stream(self.model, ctx, *args, **kwargs)