mirascope 1.25.7__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/llm/__init__.py

@@ -1,22 +1,212 @@
-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 .call_response_chunk import CallResponseChunk
-from .stream import Stream
-from .tool import Tool
+"""The `llm` module for writing provider-agnostic LLM Generations.
+
+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 . import (
+    calls,
+    clients,
+    content,
+    exceptions,
+    formatting,
+    mcp,
+    messages,
+    models,
+    prompts,
+    responses,
+    tools,
+    types,
+)
+from .calls import call
+from .clients import ModelId, Params, Provider, client, get_client
+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
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    FeatureNotSupportedError,
+    FormattingModeNotSupportedError,
+    MirascopeError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ToolNotFoundError,
+)
+from .formatting import Format, FormattingMode, Partial, format
+from .messages import (
+    AssistantContent,
+    AssistantMessage,
+    Message,
+    SystemContent,
+    SystemMessage,
+    UserContent,
+    UserMessage,
+)
+from .models import Model, model, use_model
+from .prompts import prompt
+from .responses import (
+    AsyncChunkIterator,
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStream,
+    AsyncStreamResponse,
+    AsyncTextStream,
+    AsyncThoughtStream,
+    AsyncToolCallStream,
+    ChunkIterator,
+    ContextResponse,
+    ContextStreamResponse,
+    FinishReason,
+    RawMessageChunk,
+    Response,
+    Stream,
+    StreamResponse,
+    StreamResponseChunk,
+    TextStream,
+    ThoughtStream,
+    ToolCallStream,
+)
+from .tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+    tool,
+)
 
 __all__ = [
-    "CallResponse",
-    "CallResponseChunk",
-    "CostMetadata",
-    "LocalProvider",
-    "Provider",
+    "APIError",
+    "AssistantContent",
+    "AssistantContentChunk",
+    "AssistantContentPart",
+    "AssistantMessage",
+    "AsyncChunkIterator",
+    "AsyncContextResponse",
+    "AsyncContextStreamResponse",
+    "AsyncContextTool",
+    "AsyncContextToolkit",
+    "AsyncResponse",
+    "AsyncStream",
+    "AsyncStreamResponse",
+    "AsyncTextStream",
+    "AsyncThoughtStream",
+    "AsyncTool",
+    "AsyncToolCallStream",
+    "AsyncToolkit",
+    "Audio",
+    "AuthenticationError",
+    "BadRequestError",
+    "Base64AudioSource",
+    "Base64ImageSource",
+    "ChunkIterator",
+    "ConnectionError",
+    "Context",
+    "ContextResponse",
+    "ContextStreamResponse",
+    "ContextTool",
+    "ContextToolkit",
+    "Document",
+    "FeatureNotSupportedError",
+    "FinishReason",
+    "Format",
+    "FormattingMode",
+    "FormattingModeNotSupportedError",
+    "Image",
+    "Message",
+    "MirascopeError",
+    "Model",
+    "NotFoundError",
+    "Params",
+    "Partial",
+    "PermissionError",
+    "RateLimitError",
+    "RawMessageChunk",
+    "Response",
+    "ServerError",
     "Stream",
+    "StreamResponse",
+    "StreamResponseChunk",
+    "SystemContent",
+    "SystemMessage",
+    "Text",
+    "TextChunk",
+    "TextEndChunk",
+    "TextStartChunk",
+    "TextStream",
+    "Thought",
+    "ThoughtChunk",
+    "ThoughtEndChunk",
+    "ThoughtStartChunk",
+    "ThoughtStream",
+    "TimeoutError",
     "Tool",
-    "calculate_cost",
+    "ToolCall",
+    "ToolCallChunk",
+    "ToolCallEndChunk",
+    "ToolCallStartChunk",
+    "ToolCallStream",
+    "ToolNotFoundError",
+    "ToolOutput",
+    "Toolkit",
+    "URLImageSource",
+    "UserContent",
+    "UserContentPart",
+    "UserMessage",
     "call",
-    "context",
-    "override",
+    "calls",
+    "client",
+    "clients",
+    "content",
+    "exceptions",
+    "format",
+    "formatting",
+    "get_client",
+    "mcp",
+    "messages",
+    "model",
+    "models",
+    "prompt",
+    "prompts",
+    "responses",
+    "tool",
+    "tools",
+    "types",
+    "use_model",
 ]

mirascope/llm/agents/__init__.py

@@ -0,0 +1,15 @@
+"""The Agents module for creating and managing LLM agents."""
+
+from .agent import Agent, AsyncAgent, BaseAgent
+from .agent_template import AgentTemplate, AsyncAgentTemplate
+from .decorator import AgentDecorator, agent
+
+__all__ = [
+    "Agent",
+    "AgentDecorator",
+    "AgentTemplate",
+    "AsyncAgent",
+    "AsyncAgentTemplate",
+    "BaseAgent",
+    "agent",
+]

mirascope/llm/agents/agent.py

@@ -0,0 +1,97 @@
+"""The `Agent` class for LLM agents."""
+
+from abc import ABC
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Generic
+
+from ..context import Context, DepsT
+from ..formatting import FormattableT
+from ..messages import UserContent
+from ..models import Model
+from ..responses import AsyncResponse, AsyncStreamResponse, Response, StreamResponse
+from ..tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+
+
+@dataclass
+class BaseAgent(Generic[DepsT, FormattableT], ABC):
+    """Agent class for generating responses using LLMs with tools."""
+
+    ctx: Context[DepsT]
+    """The context for the agent, such as the history of messages."""
+
+    format: type[FormattableT] | None
+    """The response format for the generated response."""
+
+    model: Model
+    """The default model the agent will use if not specified through context."""
+
+
+@dataclass
+class Agent(BaseAgent[DepsT, FormattableT]):
+    """Agent class for generating responses using LLMs with tools."""
+
+    tools: Sequence[Tool | ContextTool[DepsT]] | None
+    """The tools available to the agent, if any."""
+
+    def __call__(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> Response[FormattableT]:
+        """Generates a response by running the agent loop."""
+        raise NotImplementedError()
+
+    def call(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> Response[FormattableT]:
+        """Generates a response by running the agent loop."""
+        raise NotImplementedError()
+
+    def stream(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> StreamResponse[FormattableT]:
+        """Streams the response generated by running the agent loop."""
+        raise NotImplementedError()
+
+
+@dataclass
+class AsyncAgent(BaseAgent[DepsT, FormattableT]):
+    """Asynchronous agent class for generating responses using LLMs with tools."""
+
+    tools: Sequence[AsyncTool | AsyncContextTool[DepsT]] | None
+    """The tools available to the agent, if any."""
+
+    async def __call__(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> AsyncResponse[FormattableT]:
+        """Generates a response by running the agent loop asynchronously."""
+        raise NotImplementedError()
+
+    async def call(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> AsyncResponse[FormattableT]:
+        """Generates a response by running the agent loop asynchronously."""
+        raise NotImplementedError()
+
+    async def stream(
+        self,
+        content: UserContent,
+        *,
+        ctx: Context[DepsT] | None = None,
+    ) -> AsyncStreamResponse[FormattableT]:
+        """Streams the response generated by running the agent loop asynchronously."""
+        raise NotImplementedError()

mirascope/llm/agents/agent_template.py

@@ -0,0 +1,45 @@
+from typing import Generic, overload
+
+from ..context import DepsT
+from ..formatting import FormattableT
+from .agent import Agent, AsyncAgent
+
+
+class AgentTemplate(Generic[DepsT, FormattableT]):
+    @overload
+    def __call__(
+        self: "AgentTemplate[None, FormattableT]",
+    ) -> Agent[None, FormattableT]:
+        """Create an Agent with no deps"""
+
+    @overload
+    def __call__(
+        self: "AgentTemplate[DepsT, FormattableT]", deps: DepsT
+    ) -> Agent[DepsT, FormattableT]:
+        """Create an Agent with deps"""
+
+    def __call__(
+        self: "AgentTemplate[None, FormattableT] | AgentTemplate[DepsT, FormattableT]",
+        deps: DepsT | None = None,
+    ) -> Agent[None, FormattableT] | Agent[DepsT, FormattableT]:
+        raise NotImplementedError()
+
+
+class AsyncAgentTemplate(Generic[DepsT, FormattableT]):
+    @overload
+    async def __call__(
+        self: "AsyncAgentTemplate[None, FormattableT]",
+    ) -> AsyncAgent[None, FormattableT]:
+        """Create an AsyncAgent with no deps"""
+
+    @overload
+    async def __call__(
+        self: "AsyncAgentTemplate[DepsT, FormattableT]", deps: DepsT
+    ) -> AsyncAgent[DepsT, FormattableT]:
+        """Create an AsyncAgent with deps"""
+
+    async def __call__(
+        self: "AsyncAgentTemplate[None, FormattableT] | AsyncAgentTemplate[DepsT, FormattableT]",
+        deps: DepsT | None = None,
+    ) -> AsyncAgent[None, FormattableT] | AsyncAgent[DepsT, FormattableT]:
+        raise NotImplementedError()

mirascope/llm/agents/decorator.py

@@ -0,0 +1,176 @@
+"""The `llm.agent` decorator for turning a function into an agent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, Protocol, overload
+from typing_extensions import TypeVar, Unpack
+
+from ..tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+from .agent_template import AgentTemplate, AsyncAgentTemplate
+
+if TYPE_CHECKING:
+    from ..clients import (
+        AnthropicClient,
+        AnthropicModelId,
+        BaseClient,
+        GoogleClient,
+        GoogleModelId,
+        ModelId,
+        OpenAICompletionsClient,
+        OpenAICompletionsModelId,
+        Params,
+        Provider,
+    )
+
+from ..context import Context, DepsT
+from ..formatting import FormattableT
+from ..types import P
+
+AgentToolT = TypeVar(
+    "AgentToolT",
+    bound="Tool | AsyncTool | ContextTool[Any] | AsyncContextTool[Any] | None",
+    covariant=True,
+    default=None,
+)
+
+
+class SystemPrompt(Protocol[P]):
+    """Protocol for a prompt template function that returns a system prompt as a string (no context)."""
+
+    def __call__(self) -> str: ...
+
+
+class ContextSystemPrompt(Protocol[P, DepsT]):
+    """Protocol for a prompt template function that returns a system prompt as a string (with context)."""
+
+    def __call__(self, ctx: Context[DepsT]) -> str: ...
+
+
+class AsyncSystemPrompt(Protocol[P]):
+    """Protocol for an async prompt template function that returns a system prompt as a string (no context)."""
+
+    async def __call__(self) -> str: ...
+
+
+class AsyncContextSystemPrompt(Protocol[P, DepsT]):
+    """Protocol for an async prompt template function that returns a system prompt as a string (with context)."""
+
+    async def __call__(self, ctx: Context[DepsT]) -> str: ...
+
+
+class AgentDecorator(Protocol[P, AgentToolT, FormattableT]):
+    """Protocol for the `agent` decorator."""
+
+    @overload
+    def __call__(
+        self: AgentDecorator[
+            P,
+            None | Tool | ContextTool[DepsT],
+            FormattableT,
+        ],
+        fn: SystemPrompt[P] | ContextSystemPrompt[P, DepsT],
+    ) -> AgentTemplate[DepsT, FormattableT]:
+        """Decorator for creating a sync agent."""
+        ...
+
+    @overload
+    def __call__(
+        self: AgentDecorator[
+            P,
+            None | AsyncTool | AsyncContextTool[DepsT],
+            FormattableT,
+        ],
+        fn: AsyncSystemPrompt[P] | AsyncContextSystemPrompt[P, DepsT],
+    ) -> AsyncAgentTemplate[DepsT, FormattableT]:
+        """Decorator for creating an async agent."""
+        ...
+
+    def __call__(
+        self,
+        fn: SystemPrompt[P]
+        | ContextSystemPrompt[P, DepsT]
+        | AsyncSystemPrompt[P]
+        | AsyncContextSystemPrompt[P, DepsT],
+    ) -> AgentTemplate[DepsT, FormattableT] | AsyncAgentTemplate[DepsT, FormattableT]:
+        """Decorator for creating an agent."""
+        raise NotImplementedError()
+
+
+@overload
+def agent(
+    *,
+    provider: Literal["anthropic"],
+    model_id: AnthropicModelId,
+    tools: list[AgentToolT] | None = None,
+    format: type[FormattableT] | None = None,
+    client: AnthropicClient | None = None,
+    **params: Unpack[Params],
+) -> AgentDecorator[..., AgentToolT, FormattableT]:
+    """Decorator for creating an Anthropic agent."""
+    ...
+
+
+@overload
+def agent(
+    *,
+    provider: Literal["google"],
+    model_id: GoogleModelId,
+    tools: list[AgentToolT] | None = None,
+    format: type[FormattableT] | None = None,
+    client: GoogleClient | None = None,
+    **params: Unpack[Params],
+) -> AgentDecorator[..., AgentToolT, FormattableT]:
+    """Decorator for creating a Google agent."""
+    ...
+
+
+@overload
+def agent(
+    *,
+    provider: Literal["openai:completions"],
+    model_id: OpenAICompletionsModelId,
+    tools: list[AgentToolT] | None = None,
+    format: type[FormattableT] | None = None,
+    client: OpenAICompletionsClient | None = None,
+    **params: Unpack[Params],
+) -> AgentDecorator[..., AgentToolT, FormattableT]:
+    """Decorator for creating an OpenAI agent."""
+    ...
+
+
+@overload
+def agent(
+    *,
+    provider: Provider,
+    model_id: ModelId,
+    tools: list[AgentToolT] | None = None,
+    format: type[FormattableT] | None = None,
+    client: None = None,
+    **params: Unpack[Params],
+) -> AgentDecorator[..., AgentToolT, FormattableT]:
+    """Decorator for creating an agent using any registered model."""
+    ...
+
+
+def agent(
+    *,
+    provider: Provider,
+    model_id: ModelId,
+    tools: list[AgentToolT] | None = None,
+    format: type[FormattableT] | None = None,
+    client: BaseClient | None = None,
+    **params: Unpack[Params],
+) -> AgentDecorator[..., AgentToolT, FormattableT]:
+    """Decorator for creating an agent or structured agent.
+
+    Args:
+        model_id: The model to use for the agent.
+        tools: The tools available to the agent.
+        format: The response format type for the agent.
+        client: The client to use for the agent.
+        **params: Additional parameters for the model.
+
+    Returns:
+        An of `AgentDecorator`.
+    """
+    raise NotImplementedError()

mirascope/llm/calls/__init__.py

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

mirascope/llm/calls/base_call.py

@@ -0,0 +1,33 @@
+"""The `BaseCall` class for LLM calls."""
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Generic
+
+from ..formatting import Format, FormattableT
+from ..models import Model, get_model_from_context
+from ..prompts import PromptT
+from ..tools import ToolkitT
+from ..types import P
+
+
+@dataclass
+class BaseCall(Generic[P, PromptT, ToolkitT, FormattableT], ABC):
+    """A base class for generating responses using LLMs."""
+
+    default_model: Model
+    """The default model that will be used if no model is set in context."""
+
+    toolkit: ToolkitT
+    """The toolkit containing this call's tools."""
+
+    format: type[FormattableT] | Format[FormattableT] | None
+    """The response format for the generated response."""
+
+    fn: PromptT
+    """The Prompt function that generates the Prompt."""
+
+    @property
+    def model(self) -> Model:
+        """The model used for generating responses. May be overwritten via `with llm.model(...)."""
+        return get_model_from_context() or self.default_model