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

mirascope/llm/calls/calls.py

@@ -0,0 +1,315 @@
+"""The Call module for generating responses using LLMs."""
+
+from dataclasses import dataclass
+from typing import Generic, overload
+
+from ..context import Context, DepsT
+from ..formatting import FormattableT
+from ..prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+)
+from ..responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ..tools import (
+    AsyncContextToolkit,
+    AsyncToolkit,
+    ContextToolkit,
+    Toolkit,
+)
+from ..types import P
+from .base_call import BaseCall
+
+
+@dataclass
+class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT]):
+    """A class for generating responses using LLMs."""
+
+    @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."""
+        messages = self.fn(*args, **kwargs)
+        return self.model.call(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
+
+    @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."""
+        messages = self.fn(*args, **kwargs)
+        return self.model.stream(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
+
+
+@dataclass
+class AsyncCall(
+    BaseCall[P, AsyncPrompt, AsyncToolkit, FormattableT],
+    Generic[P, FormattableT],
+):
+    """A class for generating responses using LLMs asynchronously."""
+
+    @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 Asyncresponse 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."""
+        messages = await self.fn(*args, **kwargs)
+        return await self.model.call_async(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
+
+    @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."""
+        messages = await self.fn(*args, **kwargs)
+        return await self.model.stream_async(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
+
+
+@dataclass
+class ContextCall(
+    BaseCall[P, ContextPrompt, ContextToolkit[DepsT], FormattableT],
+    Generic[P, DepsT, FormattableT],
+):
+    """A class for generating responses using LLMs."""
+
+    @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."""
+        messages = self.fn(ctx, *args, **kwargs)
+        return self.model.context_call(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
+
+    @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."""
+        messages = self.fn(ctx, *args, **kwargs)
+        return self.model.context_stream(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
+
+
+@dataclass
+class AsyncContextCall(
+    BaseCall[P, AsyncContextPrompt, AsyncContextToolkit[DepsT], FormattableT],
+    Generic[P, DepsT, FormattableT],
+):
+    """A class for generating responses using LLMs asynchronously."""
+
+    @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."""
+        messages = await self.fn(ctx, *args, **kwargs)
+        return await self.model.context_call_async(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
+
+    @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."""
+        messages = await self.fn(ctx, *args, **kwargs)
+        return await self.model.context_stream_async(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )

mirascope/llm/calls/decorator.py

@@ -0,0 +1,255 @@
+"""The `llm.call` decorator for turning `Prompt` functions into LLM calls."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Generic, Literal, cast, overload
+from typing_extensions import Unpack
+
+from ..clients import (
+    AnthropicModelId,
+    GoogleModelId,
+    ModelId,
+    OpenAICompletionsModelId,
+    OpenAIResponsesModelId,
+    Params,
+    Provider,
+)
+from ..context import DepsT
+from ..formatting import Format, FormattableT
+from ..models import Model
+from ..prompts import (
+    AsyncContextPromptable,
+    AsyncPromptable,
+    ContextPromptable,
+    Promptable,
+    _utils as _prompt_utils,
+    prompt,
+)
+from ..tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+    ToolT,
+)
+from ..types import P
+from .calls import AsyncCall, AsyncContextCall, Call, ContextCall
+
+
+@dataclass(kw_only=True)
+class CallDecorator(Generic[ToolT, FormattableT]):
+    """A decorator for converting prompts to calls."""
+
+    model: Model
+    tools: Sequence[ToolT] | None
+    format: type[FormattableT] | Format[FormattableT] | None
+
+    @overload
+    def __call__(
+        self: CallDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT],
+        fn: AsyncContextPromptable[P, DepsT],
+    ) -> AsyncContextCall[P, DepsT, FormattableT]:
+        """Decorate an async context prompt into an AsyncContextCall."""
+        ...
+
+    @overload
+    def __call__(
+        self: CallDecorator[Tool | ContextTool[DepsT], FormattableT],
+        fn: ContextPromptable[P, DepsT],
+    ) -> ContextCall[P, DepsT, FormattableT]:
+        """Decorate a context prompt into a ContextCall."""
+        ...
+
+    @overload
+    def __call__(
+        self: CallDecorator[AsyncTool, FormattableT], fn: AsyncPromptable[P]
+    ) -> AsyncCall[P, FormattableT]:
+        """Decorate an async prompt into an AsyncCall."""
+        ...
+
+    @overload
+    def __call__(
+        self: CallDecorator[Tool, FormattableT], fn: Promptable[P]
+    ) -> Call[P, FormattableT]:
+        """Decorate a prompt into a Call."""
+        ...
+
+    def __call__(
+        self,
+        fn: ContextPromptable[P, DepsT]
+        | AsyncContextPromptable[P, DepsT]
+        | Promptable[P]
+        | AsyncPromptable[P],
+    ) -> (
+        ContextCall[P, DepsT, FormattableT]
+        | AsyncContextCall[P, DepsT, FormattableT]
+        | Call[P, FormattableT]
+        | AsyncCall[P, FormattableT]
+    ):
+        """Decorates a prompt into a Call or ContextCall."""
+        is_context = _prompt_utils.is_context_promptable(fn)
+        is_async = _prompt_utils.is_async_promptable(fn)
+
+        if is_context and is_async:
+            tools = cast(
+                Sequence[AsyncTool | AsyncContextTool[DepsT]] | None, self.tools
+            )
+            return AsyncContextCall(
+                fn=prompt(fn),
+                default_model=self.model,
+                format=self.format,
+                toolkit=AsyncContextToolkit(tools=tools),
+            )
+        elif is_context:
+            tools = cast(Sequence[Tool | ContextTool[DepsT]] | None, self.tools)
+            return ContextCall(
+                fn=prompt(fn),
+                default_model=self.model,
+                format=self.format,
+                toolkit=ContextToolkit(tools=tools),
+            )
+        elif is_async:
+            tools = cast(Sequence[AsyncTool] | None, self.tools)
+            return AsyncCall(
+                fn=prompt(fn),
+                default_model=self.model,
+                format=self.format,
+                toolkit=AsyncToolkit(tools=tools),
+            )
+        else:
+            tools = cast(Sequence[Tool] | None, self.tools)
+            return Call(
+                fn=prompt(fn),
+                default_model=self.model,
+                format=self.format,
+                toolkit=Toolkit(tools=tools),
+            )
+
+
+@overload
+def call(
+    *,
+    provider: Literal["anthropic"],
+    model_id: AnthropicModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorate a prompt into a Call using Anthropic models."""
+    ...
+
+
+@overload
+def call(
+    *,
+    provider: Literal["google"],
+    model_id: GoogleModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorate a prompt into a Call using Google models."""
+    ...
+
+
+@overload
+def call(
+    *,
+    provider: Literal["openai:completions"],
+    model_id: OpenAICompletionsModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorate a prompt into a Call using OpenAI models."""
+    ...
+
+
+@overload
+def call(
+    *,
+    provider: Literal["openai:responses", "openai"],
+    model_id: OpenAIResponsesModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorate a prompt into a Call using OpenAI models (Responses API)."""
+    ...
+
+
+@overload
+def call(
+    *,
+    provider: Provider,
+    model_id: ModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorate a prompt into a Call using a generic provider and model."""
+    ...
+
+
+def call(
+    *,
+    provider: Provider,
+    model_id: ModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Returns a decorator for turning prompt template functions into generations.
+
+    This decorator creates a `Call` or `ContextCall` that can be used with prompt functions.
+    If the first parameter is typed as `llm.Context[T]`, it creates a ContextCall.
+    Otherwise, it creates a regular Call.
+
+    Example:
+
+        Regular call:
+        ```python
+        from mirascope import llm
+
+        @llm.call(
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
+        )
+        def answer_question(question: str) -> str:
+            return f"Answer this question: {question}"
+
+        response: llm.Response = answer_question("What is the capital of France?")
+        print(response)
+        ```
+
+    Example:
+
+        Context call:
+        ```python
+        from dataclasses import dataclass
+        from mirascope import llm
+
+        @dataclass
+        class Personality:
+            vibe: str
+
+        @llm.call(
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
+        )
+        def answer_question(ctx: llm.Context[Personality], question: str) -> str:
+            return f"Your vibe is {ctx.deps.vibe}. Answer this question: {question}"
+
+        ctx = llm.Context(deps=Personality(vibe="snarky"))
+        response = answer_question(ctx, "What is the capital of France?")
+        print(response)
+        ```
+    """
+    model = Model(provider=provider, model_id=model_id, **params)
+    return CallDecorator(model=model, tools=tools, format=format)

mirascope/llm/clients/__init__.py

@@ -0,0 +1,34 @@
+"""Client interfaces for LLM providers."""
+
+from .anthropic import (
+    AnthropicClient,
+    AnthropicModelId,
+)
+from .base import BaseClient, ClientT, Params
+from .google import GoogleClient, GoogleModelId
+from .openai import (
+    OpenAICompletionsClient,
+    OpenAICompletionsModelId,
+    OpenAIResponsesClient,
+    OpenAIResponsesModelId,
+)
+from .providers import PROVIDERS, ModelId, Provider, client, get_client
+
+__all__ = [
+    "PROVIDERS",
+    "AnthropicClient",
+    "AnthropicModelId",
+    "BaseClient",
+    "ClientT",
+    "GoogleClient",
+    "GoogleModelId",
+    "ModelId",
+    "OpenAICompletionsClient",
+    "OpenAICompletionsModelId",
+    "OpenAIResponsesClient",
+    "OpenAIResponsesModelId",
+    "Params",
+    "Provider",
+    "client",
+    "get_client",
+]

mirascope/llm/clients/anthropic/__init__.py

@@ -0,0 +1,11 @@
+"""Anthropic client implementation."""
+
+from .clients import AnthropicClient, client, get_client
+from .model_ids import AnthropicModelId
+
+__all__ = [
+    "AnthropicClient",
+    "AnthropicModelId",
+    "client",
+    "get_client",
+]

mirascope/llm/clients/anthropic/_utils/__init__.py

@@ -0,0 +1,13 @@
+from .decode import (
+    decode_async_stream,
+    decode_response,
+    decode_stream,
+)
+from .encode import encode_request
+
+__all__ = [
+    "decode_async_stream",
+    "decode_response",
+    "decode_stream",
+    "encode_request",
+]