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

mirascope/llm/__init__.py

@@ -1,4 +1,4 @@
-"""LLM abstractions that aren't obstructions.
+"""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
@@ -8,25 +8,22 @@ code that works with multiple LLM providers without changing your application lo
 # 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,
+    clients,
     content,
     exceptions,
     formatting,
+    mcp,
     messages,
     models,
     prompts,
-    providers,
     responses,
     tools,
     types,
 )
-
-with suppress(ImportError):
-    from . import mcp
-from .calls import AsyncCall, AsyncContextCall, Call, CallDecorator, ContextCall, call
+from .calls import call
+from .clients import ModelId, Params, Provider, client, get_client
 from .content import (
     AssistantContentChunk,
     AssistantContentPart,
@@ -51,37 +48,23 @@ from .content import (
     URLImageSource,
     UserContentPart,
 )
-from .context import Context, DepsT
+from .context import Context
 from .exceptions import (
     APIError,
     AuthenticationError,
     BadRequestError,
     ConnectionError,
-    Error,
     FeatureNotSupportedError,
-    MissingAPIKeyError,
-    NoRegisteredProviderError,
+    FormattingModeNotSupportedError,
+    MirascopeError,
     NotFoundError,
-    ParseError,
     PermissionError,
-    ProviderError,
     RateLimitError,
-    ResponseValidationError,
     ServerError,
     TimeoutError,
-    ToolError,
-    ToolExecutionError,
     ToolNotFoundError,
 )
-from .formatting import (
-    Format,
-    FormattableT,
-    FormattingMode,
-    OutputParser,
-    Partial,
-    format,
-    output_parser,
-)
+from .formatting import Format, FormattingMode, Partial, format
 from .messages import (
     AssistantContent,
     AssistantMessage,
@@ -91,32 +74,9 @@ from .messages import (
     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 .models import Model, model, use_model
+from .prompts import prompt
 from .responses import (
-    AnyResponse,
     AsyncChunkIterator,
     AsyncContextResponse,
     AsyncContextStreamResponse,
@@ -132,52 +92,36 @@ from .responses import (
     FinishReason,
     RawMessageChunk,
     Response,
-    RootResponse,
     Stream,
     StreamResponse,
     StreamResponseChunk,
     TextStream,
     ThoughtStream,
     ToolCallStream,
-    Usage,
-    UsageDeltaChunk,
 )
 from .tools import (
-    AnyToolFn,
-    AnyToolSchema,
     AsyncContextTool,
     AsyncContextToolkit,
     AsyncTool,
     AsyncToolkit,
-    BaseToolkit,
     ContextTool,
     ContextToolkit,
     Tool,
     Toolkit,
-    ToolkitT,
-    ToolSchema,
     tool,
 )
-from .types import Jsonable
 
 __all__ = [
     "APIError",
-    "AnyResponse",
-    "AnyToolFn",
-    "AnyToolSchema",
     "AssistantContent",
     "AssistantContentChunk",
     "AssistantContentPart",
     "AssistantMessage",
-    "AsyncCall",
     "AsyncChunkIterator",
-    "AsyncContextCall",
-    "AsyncContextPrompt",
     "AsyncContextResponse",
     "AsyncContextStreamResponse",
     "AsyncContextTool",
     "AsyncContextToolkit",
-    "AsyncPrompt",
     "AsyncResponse",
     "AsyncStream",
     "AsyncStreamResponse",
@@ -191,49 +135,30 @@ __all__ = [
     "BadRequestError",
     "Base64AudioSource",
     "Base64ImageSource",
-    "BaseToolkit",
-    "Call",
-    "CallDecorator",
     "ChunkIterator",
     "ConnectionError",
     "Context",
-    "ContextCall",
-    "ContextPrompt",
     "ContextResponse",
     "ContextStreamResponse",
     "ContextTool",
     "ContextToolkit",
-    "DepsT",
     "Document",
-    "Error",
     "FeatureNotSupportedError",
     "FinishReason",
     "Format",
-    "FormattableT",
     "FormattingMode",
+    "FormattingModeNotSupportedError",
     "Image",
-    "Jsonable",
     "Message",
-    "MissingAPIKeyError",
+    "MirascopeError",
     "Model",
-    "ModelId",
-    "NoRegisteredProviderError",
     "NotFoundError",
-    "OutputParser",
     "Params",
-    "ParseError",
     "Partial",
     "PermissionError",
-    "Prompt",
-    "PromptDecorator",
-    "Provider",
-    "ProviderError",
-    "ProviderId",
     "RateLimitError",
     "RawMessageChunk",
     "Response",
-    "ResponseValidationError",
-    "RootResponse",
     "ServerError",
     "Stream",
     "StreamResponse",
@@ -245,8 +170,6 @@ __all__ = [
     "TextEndChunk",
     "TextStartChunk",
     "TextStream",
-    "ThinkingConfig",
-    "ThinkingLevel",
     "Thought",
     "ThoughtChunk",
     "ThoughtEndChunk",
@@ -259,36 +182,28 @@ __all__ = [
     "ToolCallEndChunk",
     "ToolCallStartChunk",
     "ToolCallStream",
-    "ToolError",
-    "ToolExecutionError",
     "ToolNotFoundError",
     "ToolOutput",
-    "ToolSchema",
     "Toolkit",
-    "ToolkitT",
     "URLImageSource",
-    "Usage",
-    "UsageDeltaChunk",
     "UserContent",
     "UserContentPart",
     "UserMessage",
     "call",
     "calls",
+    "client",
+    "clients",
     "content",
     "exceptions",
     "format",
     "formatting",
+    "get_client",
     "mcp",
     "messages",
     "model",
-    "model_from_context",
     "models",
-    "output_parser",
     "prompt",
     "prompts",
-    "providers",
-    "register_provider",
-    "reset_provider_registry",
     "responses",
     "tool",
     "tools",

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

@@ -1,6 +1,6 @@
 """The `llm.calls` module."""
 
-from .calls import AsyncCall, AsyncContextCall, Call, CallT, ContextCall
+from .calls import AsyncCall, AsyncContextCall, Call, ContextCall
 from .decorator import (
     CallDecorator,
     call,
@@ -11,7 +11,6 @@ __all__ = [
     "AsyncContextCall",
     "Call",
     "CallDecorator",
-    "CallT",
     "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