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

mirascope/llm/formatting/format.py

@@ -0,0 +1,104 @@
+"""The `llm.format` decorator for defining response formats as classes."""
+
+import inspect
+
+from ..types import NoneType
+from ._utils import default_formatting_instructions
+from .types import Format, FormattableT, FormattingMode, HasFormattingInstructions
+
+
+def format(
+    formattable: type[FormattableT] | None,
+    *,
+    mode: FormattingMode,
+) -> Format[FormattableT] | None:
+    """Returns a `Format` that describes structured output for a Formattable type.
+
+    This function converts a Formattable type (e.g. Pydantic BaseModel) into a `Format`
+    object that describes how the object should be formatted. Calling `llm.format`
+    is optional, as all the APIs that expect a `Format` can also take the Formattable
+    type directly. However, calling `llm.format` is necessary in order to specify the
+    formatting mode that will be used.
+
+    Args:
+        mode: The format mode to use, one of the following:
+            - "strict": Use model strict structured outputs, or fail if unavailable.
+            - "tool": Use forced tool calling with a special tool that represents a
+              formatted response.
+            - "json": Use provider json mode if available, or modify prompt to request
+              json if not.
+
+    The Formattable type may provide custom formatting instructions via a
+    `formatting_instructions(cls)` classmethod. If that method is present, it will be called,
+    and the resulting instructions will automatically be appended to the system prompt.
+
+    If no formatting instructions are present, then Mirascope may auto-generate instructions
+    based on the active format mode. To disable this behavior and all prompt modification,
+    you can add the `formatting_instructions` classmethod and have it return `None`.
+
+    Returns:
+      A `Format` object describing the Formattable type.
+
+    Example:
+      Using with an LLM call:
+
+      ```python
+      from pydantic import BaseModel
+
+      from mirascope import llm
+
+
+      class Book(BaseModel):
+          title: str
+          author: str
+
+      format = llm.format(Book, mode="strict")
+
+      @llm.call(
+          provider="openai:completions",
+          model_id="gpt-4o-mini",
+          format=format,
+      )
+      def recommend_book(genre: str):
+          return f"Recommend a {genre} book."
+
+      response = recommend_book("fantasy")
+      book: Book = response.parse()
+      print(f"{book.title} by {book.author}")
+      ```
+    """
+    # TODO: Add caching or memoization to this function (e.g. functools.lru_cache)
+
+    if formattable is None or formattable is NoneType:
+        return None
+
+    description = None
+    if formattable.__doc__:
+        description = inspect.cleandoc(formattable.__doc__)
+
+    schema = formattable.model_json_schema()
+    formatting_instructions = None
+    if isinstance(formattable, HasFormattingInstructions):
+        formatting_instructions = formattable.formatting_instructions()
+    else:
+        formatting_instructions = default_formatting_instructions(schema, mode)
+
+    return Format[FormattableT](
+        name=formattable.__name__,
+        description=description,
+        schema=schema,
+        mode=mode,
+        formatting_instructions=formatting_instructions,
+        formattable=formattable,
+    )
+
+
+def resolve_format(
+    formattable: type[FormattableT] | Format[FormattableT] | None,
+    default_mode: FormattingMode,
+) -> Format[FormattableT] | None:
+    """Resolve a `Format` (or None) from a possible `Format` or Formattable."""
+    if isinstance(formattable, Format):
+        return formattable
+    else:
+        return format(formattable, mode=default_mode)

mirascope/llm/formatting/from_call_args.py

@@ -0,0 +1,30 @@
+"""The `FromCallArgs` class annotation for marking a field as a call argument."""
+
+
+class FromCallArgs:
+    """A marker class for indicating that a field is a call argument.
+
+    This ensures that the LLM call does not attempt to generate this field. Instead, it
+    will populate this field with the call argument with a matching name.
+
+    This is useful for colocating e.g. validation of a generated output against and
+    input argument (such as the length of an output given a number input).
+
+    Example:
+
+    ```
+    class Book(BaseModel):
+        title: Annotated[str, llm.formatting.FromCallArgs()]
+        author: Annotated[str, llm.formatting.FromCallArgs()]
+        summary: str
+
+
+    @llm.call(
+        provider="openai:completions",
+        model_id="gpt-4o-mini",
+        format=Book,
+    )
+    def summarize_book(title: str, author: str):
+        return f"Summarize {title} by {author}."
+    ```
+    """

mirascope/llm/formatting/partial.py

@@ -0,0 +1,58 @@
+"""
+--------------------------------------------------------------------------------
+Source: https://github.com/pydantic/pydantic/issues/6381#issuecomment-1831607091
+By: silviumarcu
+
+This code is used in accordance with the repository's license, and this reference
+serves as an acknowledgment of the original author's contribution to this project.
+--------------------------------------------------------------------------------
+"""
+
+from typing import Generic, NoReturn
+
+from .format import FormattableT
+
+
+class Partial(Generic[FormattableT]):
+    """Generate a new class with all attributes optionals.
+
+    Notes:
+        This will wrap a class inheriting form BaseModel and will recursively
+        convert all its attributes and its children's attributes to optionals.
+
+    Example:
+        Partial[SomeModel]
+    """
+
+    def __new__(
+        cls,
+        *args: object,  # noqa :ARG003
+        **kwargs: object,  # noqa :ARG003
+    ) -> "Partial[FormattableT]":
+        """Cannot instantiate.
+
+        Raises:
+            TypeError: Direct instantiation not allowed.
+        """
+        raise TypeError("Cannot instantiate abstract Partial class.")
+
+    def __init_subclass__(
+        cls,
+        *args: object,
+        **kwargs: object,
+    ) -> NoReturn:
+        """Cannot subclass.
+
+        Raises:
+           TypeError: Subclassing not allowed.
+        """
+        raise TypeError(f"Cannot subclass {cls.__module__}.Partial")
+
+    def __class_getitem__(
+        cls,
+        wrapped_class: type[FormattableT],
+    ) -> type[FormattableT]:
+        """Convert model to a partial model with all fields being optionals."""
+        # TODO: Implement proper partial model generation
+        # For now, return the original class to avoid import errors
+        return wrapped_class

mirascope/llm/formatting/types.py

@@ -0,0 +1,109 @@
+"""Type for the formatting module."""
+
+from dataclasses import dataclass
+from typing import Generic, Literal, Protocol, runtime_checkable
+from typing_extensions import TypeVar
+
+from pydantic import BaseModel
+
+# TODO: Support primitive types (e.g. `format=list[Book]`)
+FormattableT = TypeVar("FormattableT", bound=BaseModel | None, default=None)
+"""Type variable for structured response format types.
+
+This TypeVar represents the type of structured output format that LLM responses
+can be parsed into, or None if no format is specified. 
+If format is specified, it must extend Pydantic BaseModel. 
+"""
+
+
+FormattingMode = Literal[
+    "strict",
+    "json",
+    "tool",
+]
+"""Available modes for response format generation.
+
+- "strict": Use strict mode for structured outputs, asking the LLM to strictly adhere
+    to a given JSON schema. Not all providers or models support it, and may not be
+    compatible with tool calling. When making a call using this mode, an 
+    `llm.FormattingModeNotSupportedError` error may be raised (if "strict" mode is wholly
+    unsupported), or an `llm.FeatureNotSupportedError` may be raised (if trying to use 
+    strict along with tools and that is unsupported).
+
+- "json": Use JSON mode for structured outputs. In contrast to strict mode, we ask the
+    LLM to output JSON as text, though without guarantees that the model will output
+    the expected format schema. If the provider has explicit JSON mode, it will be used;
+    otherwise, Mirascope will modify the system prompt to request JSON output. May
+    raise an `llm.FeatureNotSupportedError` if tools are present and the
+    model does not support tool calling when using JSON mode.
+
+- "tool": Use forced tool calling to structure outputs. Mirascope will construct an
+    ad-hoc tool with the required json schema as tool args. When the LLM chooses that
+    tool, it will automatically be converted from a `ToolCall` into regular response
+    content (abstracting over the tool call). If other tools are present, they will
+    be handled as regular tool calls.
+
+Note: When `llm.format` is not used, the provider will automatically choose a mode at call time.
+"""
+
+
+@dataclass(kw_only=True)
+class Format(Generic[FormattableT]):
+    """Class representing a structured output format for LLM responses.
+
+    A `Format` contains metadata needed to describe a structured output type
+    to the LLM, including the expected schema. This class is not instantiated directly,
+    but is created by calling `llm.format`, or is automatically generated by LLM
+    providers when a `Formattable` is passed to a call method.
+
+    Example:
+
+      ```python
+      from mirascope import llm
+
+      class Book:
+          title: str
+          author: str
+
+      print(llm.format(Book, mode="tool"))
+      ```
+    """
+
+    name: str
+    """The name of the response format."""
+
+    description: str | None
+    """A description of the response format, if available."""
+
+    schema: dict[str, object]
+    """JSON schema representation of the structured output format."""
+
+    mode: FormattingMode
+    """The decorator-provided mode of the response format. 
+    
+    Determines how the LLM call may be modified in order to extract the expected format.
+    """
+
+    formatting_instructions: str | None
+    """The formatting instructions that will be added to the LLM system prompt.
+
+    If the format type has a `formatting_instructions` class method, the output of that
+    call will be used for instructions. Otherwise, instructions may be auto-generated
+    based on the formatting mode.
+    """
+
+    formattable: type[FormattableT]
+    """The `Formattable` type that this `Format` describes.
+    
+    While the `FormattbleT` typevar allows for `None`, a `Format` will never be
+    constructed when the `FormattableT` is `None`, so you may treat this as 
+    a `RequiredFormattableT` in practice.
+    """
+
+
+@runtime_checkable
+class HasFormattingInstructions(Protocol):
+    """Protocol for classes that have been decorated with `@format()`."""
+
+    @classmethod
+    def formatting_instructions(cls) -> str | None: ...

mirascope/llm/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP compatibility module."""
+
+from .client import MCPClient, sse_client, stdio_client, streamablehttp_client
+
+__all__ = ["MCPClient", "sse_client", "stdio_client", "streamablehttp_client"]

mirascope/llm/mcp/client.py

@@ -0,0 +1,118 @@
+import contextlib
+from collections.abc import AsyncIterator, Callable
+from datetime import timedelta
+
+import httpx
+from mcp import ClientSession
+from mcp.client.session import ListRootsFnT, SamplingFnT
+from mcp.client.sse import sse_client as mcp_sse_client
+from mcp.client.stdio import StdioServerParameters
+from mcp.client.streamable_http import (
+    streamablehttp_client as mcp_streamablehttp_client,
+)
+from mcp.shared._httpx_utils import McpHttpClientFactory
+
+from ..tools import AsyncTool
+
+
+class MCPClient:
+    """Mirascope wrapper around a MCP ClientSession.
+
+    It provides a way to get MCP results that are pre-converted into Mirascope-friendly
+    types.
+
+    The underlying MCP ClientSession may be accessed by .session if needed.
+    """
+
+    def __init__(self, session: ClientSession) -> None:
+        self._session = session
+
+    @property
+    def session(self) -> ClientSession:
+        """Access the underlying MCP ClientSession if needed."""
+        return self._session
+
+    async def list_tools(self) -> list[AsyncTool]:
+        """List all tools available on the MCP server.
+
+        Returns:
+            A list of dynamically created `llm.Tool`s.
+        """
+        raise NotImplementedError()
+
+
+@contextlib.asynccontextmanager
+async def streamablehttp_client(
+    url: str,
+    headers: dict[str, str] | None = None,
+    timeout: float | timedelta | None = None,
+    sse_read_timeout: float | timedelta | None = None,
+    terminate_on_close: bool = True,
+    httpx_client_factory: McpHttpClientFactory | None = None,
+    auth: httpx.Auth | None = None,
+) -> AsyncIterator[MCPClient]:
+    """Create a Mirascope MCPClient using StreamableHTTP."""
+    kwargs = {}
+    if headers is not None:
+        kwargs["headers"] = headers
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+    if sse_read_timeout is not None:
+        kwargs["sse_read_timeout"] = sse_read_timeout
+    if httpx_client_factory is not None:
+        kwargs["httpx_client_factory"] = httpx_client_factory
+    if auth is not None:
+        kwargs["auth"] = auth
+
+    async with (
+        mcp_streamablehttp_client(
+            url,
+            terminate_on_close=terminate_on_close,
+            **kwargs,
+        ) as (read, write, get_session_id),
+        ClientSession(
+            read,
+            write,
+        ) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@contextlib.asynccontextmanager
+async def stdio_client(
+    server_parameters: StdioServerParameters,
+    read_stream_exception_handler: Callable[[Exception], None] | None = None,
+) -> AsyncIterator[MCPClient]:
+    """Create a Mirascope MCPClient using stdio."""
+
+    async with (
+        ClientSession(None, None) as session,  # pyright: ignore [reportArgumentType]
+    ):
+        raise NotImplementedError()
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@contextlib.asynccontextmanager
+async def sse_client(
+    url: str,
+    list_roots_callback: ListRootsFnT | None = None,
+    read_timeout_seconds: timedelta | None = None,
+    sampling_callback: SamplingFnT | None = None,
+    session: ClientSession | None = None,
+) -> AsyncIterator[MCPClient]:
+    """Create a Mirascope MCPClient using sse."""
+
+    async with (
+        mcp_sse_client(url) as (read, write),
+        ClientSession(
+            read,
+            write,
+            read_timeout_seconds=read_timeout_seconds,
+            sampling_callback=sampling_callback,
+            list_roots_callback=list_roots_callback,
+        ) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)

mirascope/llm/messages/__init__.py

@@ -0,0 +1,32 @@
+"""The messages module for LLM interactions.
+
+This module defines the message types used in LLM interactions. Messages are represented
+as a unified `Message` class with different roles (system, user, assistant) and flexible
+content arrays that can include text, images, audio, documents, and tool interactions.
+"""
+
+from .message import (
+    AssistantContent,
+    AssistantMessage,
+    Message,
+    SystemContent,
+    SystemMessage,
+    UserContent,
+    UserMessage,
+    assistant,
+    system,
+    user,
+)
+
+__all__ = [
+    "AssistantContent",
+    "AssistantMessage",
+    "Message",
+    "SystemContent",
+    "SystemMessage",
+    "UserContent",
+    "UserMessage",
+    "assistant",
+    "system",
+    "user",
+]

mirascope/llm/messages/message.py

@@ -0,0 +1,182 @@
+"""The `Message` class and its utility constructors."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+from ..content import AssistantContentPart, Text, UserContentPart
+from ..types import Jsonable
+
+if TYPE_CHECKING:
+    from ..clients import ModelId, Provider
+
+
+@dataclass(kw_only=True)
+class SystemMessage:
+    """A system message that sets context and instructions for the conversation."""
+
+    role: Literal["system"] = "system"
+    """The role of this message. Always "system"."""
+
+    content: Text
+    """The content of this `SystemMesssage`."""
+
+
+@dataclass(kw_only=True)
+class UserMessage:
+    """A user message containing input from the user."""
+
+    role: Literal["user"] = "user"
+    """The role of this message. Always "user"."""
+
+    content: Sequence[UserContentPart]
+    """The content of the user message."""
+
+    name: str | None = None
+    """A name identifying the creator of this message."""
+
+
+@dataclass(kw_only=True)
+class AssistantMessage:
+    """An assistant message containing the model's response."""
+
+    role: Literal["assistant"] = "assistant"
+    """The role of this message. Always "assistant"."""
+
+    content: Sequence[AssistantContentPart]
+    """The content of the assistant message."""
+
+    name: str | None = None
+    """A name identifying the creator of this message."""
+
+    provider: Provider | None
+    """The LLM provider that generated this assistant message, if available."""
+
+    model_id: ModelId | None
+    """The model identifier of the LLM that generated this assistant message, if available."""
+
+    raw_message: Jsonable | None
+    """The provider-specific raw representation of this assistant message, if available.
+
+    If raw_content is truthy, then it may be used for provider-specific behavior when
+    resuming an LLM interaction that included this assistant message. For example, we can
+    reuse the provider-specific raw encoding rather than re-encoding the message from it's
+    Mirascope content representation. This may also take advantage of server-side provider
+    context, e.g. identifiers of reasoning context tokens that the provider generated.
+    
+    If present, the content should be encoded as JSON-serializable data, and in a format
+    that matches representation the provider expects representing the Mirascope data.
+    This may involve e.g.  converting Pydantic `BaseModel`s into plain dicts via `model_dump`.
+
+    Raw content is not required, as the Mirascope content can also be used to generate
+    a valid input to the provider (potentially without taking advantage of provider-specific
+    reasoning caches, etc). In that case raw content should be left empty.
+    """
+
+
+Message: TypeAlias = SystemMessage | UserMessage | AssistantMessage
+"""A message in an LLM interaction.
+
+Messages have a role (system, user, or assistant) and content that is a sequence
+of content parts. The content can include text, images, audio, documents, and
+tool interactions.
+
+For most use cases, prefer the convenience functions `system()`, `user()`, and
+`assistant()` instead of directly creating `Message` objects.
+
+Example:
+
+    ```python
+    from mirascope import llm
+
+    messages = [
+        llm.messages.system("You are a helpful assistant."),
+        llm.messages.user("Hello, how are you?"),
+    ]
+    ```
+"""
+
+UserContent: TypeAlias = str | UserContentPart | Sequence[str | UserContentPart]
+"""Type alias for content that can fit into a `UserMessage`."""
+
+AssistantContent: TypeAlias = (
+    str | AssistantContentPart | Sequence[str | AssistantContentPart]
+)
+"""Type alias for content that can fit into an `AssistantMessage`."""
+
+SystemContent: TypeAlias = str | Text
+"""Type alias for content that can fit into a `SystemMessage`."""
+
+
+def system(content: SystemContent) -> SystemMessage:
+    """Creates a system message.
+
+    Args:
+        content: The content of the message, which must be a `str` or `Text` content.
+
+    Returns:
+        A `SystemMessage`.
+    """
+    promoted_content = Text(text=content) if isinstance(content, str) else content
+    return SystemMessage(content=promoted_content)
+
+
+def user(
+    content: UserContent,
+    *,
+    name: str | None = None,
+) -> UserMessage:
+    """Creates a user message.
+
+    Args:
+        content: The content of the message, which can be `str` or any `UserContent`,
+            or a sequence of such user content pieces.
+        name: Optional name to identify a specific user in multi-party conversations.
+
+    Returns:
+        A `UserMessage`.
+    """
+    if isinstance(content, str) or not isinstance(content, Sequence):
+        content = [content]
+    promoted_content = [
+        Text(text=part) if isinstance(part, str) else part for part in content
+    ]
+    return UserMessage(content=promoted_content, name=name)
+
+
+def assistant(
+    content: AssistantContent,
+    *,
+    provider: Provider | None,
+    model_id: ModelId | None,
+    raw_message: Jsonable | None = None,
+    name: str | None = None,
+) -> AssistantMessage:
+    """Creates an assistant message.
+
+    Args:
+        content: The content of the message, which can be `str` or any `AssistantContent`,
+            or a sequence of assistant content pieces.
+        provider: Optional identifier of the provider that produced this message.
+        model_id: Optional id of the model that produced this message.
+        raw_message: Optional Jsonable object that contains the provider-specific
+            "raw" data representation of the content for this assistant message.
+        name: Optional name to identify a specific assistant in multi-party conversations.
+
+    Returns:
+        An `AssistantMessage`.
+    """
+    if isinstance(content, str) or not isinstance(content, Sequence):
+        content = [content]
+    promoted_content = [
+        Text(text=part) if isinstance(part, str) else part for part in content
+    ]
+    return AssistantMessage(
+        content=promoted_content,
+        provider=provider,
+        model_id=model_id,
+        raw_message=raw_message,
+        name=name,
+    )

mirascope/llm/models/__init__.py

@@ -0,0 +1,16 @@
+"""The `llm.models` module for implementing the `Model` interface and utilities.
+
+This module provides a unified interface for interacting with different LLM models
+through the `Model` class. The `llm.model()` context manager allows you to override
+the model at runtime, and `llm.use_model()` retrieves the model from context or
+creates a default one.
+"""
+
+from .models import Model, get_model_from_context, model, use_model
+
+__all__ = [
+    "Model",
+    "get_model_from_context",
+    "model",
+    "use_model",
+]