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

mirascope/llm/clients/openai/responses/model_ids.py

@@ -0,0 +1,8 @@
+"""OpenAI Responses registered LLM models."""
+
+from typing import TypeAlias
+
+from openai.types import ResponsesModel
+
+OpenAIResponsesModelId: TypeAlias = ResponsesModel | str
+"""The OpenAI Responses model ids registered with Mirascope."""

mirascope/llm/clients/openai/shared/__init__.py

@@ -0,0 +1,7 @@
+"""Shared types and utils for all OpenAI clients."""
+
+from . import _utils
+
+__all__ = [
+    "_utils",
+]

mirascope/llm/clients/openai/shared/_utils.py

@@ -0,0 +1,55 @@
+"""Shared utils for all OpenAI clients."""
+
+MODELS_WITHOUT_JSON_SCHEMA_SUPPORT = {
+    "chatgpt-4o-latest",
+    "gpt-3.5-turbo",
+    "gpt-3.5-turbo-0125",
+    "gpt-3.5-turbo-1106",
+    "gpt-3.5-turbo-16k",
+    "gpt-4",
+    "gpt-4-0125-preview",
+    "gpt-4-0613",
+    "gpt-4-1106-preview",
+    "gpt-4-turbo",
+    "gpt-4-turbo-2024-04-09",
+    "gpt-4-turbo-preview",
+    "gpt-4o-2024-05-13",
+    "gpt-4o-audio-preview",
+    "gpt-4o-audio-preview-2024-10-01",
+    "gpt-4o-audio-preview-2024-12-17",
+    "gpt-4o-audio-preview-2025-06-03",
+    "gpt-4o-mini-audio-preview",
+    "gpt-4o-mini-audio-preview-2024-12-17",
+    "gpt-5-chat-latest",
+    "o1-mini",
+    "o1-mini-2024-09-12",
+}
+
+MODELS_WITHOUT_JSON_OBJECT_SUPPORT = {
+    "gpt-4",
+    "gpt-4-0613",
+    "gpt-4o-audio-preview",
+    "gpt-4o-audio-preview-2024-10-01",
+    "gpt-4o-audio-preview-2024-12-17",
+    "gpt-4o-audio-preview-2025-06-03",
+    "gpt-4o-mini-audio-preview",
+    "gpt-4o-mini-audio-preview-2024-12-17",
+    "gpt-4o-mini-search-preview",
+    "gpt-4o-mini-search-preview-2025-03-11",
+    "gpt-4o-search-preview",
+    "gpt-4o-search-preview-2025-03-11",
+    "o1-mini",
+    "o1-mini-2024-09-12",
+}
+
+
+def _ensure_additional_properties_false(obj: object) -> None:
+    """Recursively adds additionalProperties = False to a schema, required by OpenAI API."""
+    if isinstance(obj, dict):
+        if obj.get("type") == "object" and "additionalProperties" not in obj:
+            obj["additionalProperties"] = False
+        for value in obj.values():
+            _ensure_additional_properties_false(value)
+    elif isinstance(obj, list):
+        for item in obj:
+            _ensure_additional_properties_false(item)

mirascope/llm/clients/providers.py

@@ -0,0 +1,175 @@
+from typing import Literal, TypeAlias, get_args, overload
+
+from .anthropic import (
+    AnthropicClient,
+    AnthropicModelId,
+    client as anthropic_client,
+    get_client as get_anthropic_client,
+)
+from .google import (
+    GoogleClient,
+    GoogleModelId,
+    client as google_client,
+    get_client as get_google_client,
+)
+from .openai import (
+    OpenAICompletionsClient,
+    OpenAICompletionsModelId,
+    OpenAIResponsesClient,
+    OpenAIResponsesModelId,
+    completions_client as openai_completions_client,
+    get_completions_client as get_openai_completions_client,
+    get_responses_client as get_openai_responses_client,
+    responses_client as openai_responses_client,
+)
+
+Provider: TypeAlias = Literal[
+    "anthropic",
+    "google",
+    "openai:completions",  # OpenAICompletionsClient
+    "openai:responses",  # OpenAIResponsesClient
+    "openai",  # Alias for "openai:responses"
+]
+PROVIDERS = get_args(Provider)
+
+ModelId: TypeAlias = (
+    AnthropicModelId
+    | GoogleModelId
+    | OpenAIResponsesModelId
+    | OpenAICompletionsModelId
+    | str
+)
+
+
+@overload
+def get_client(provider: Literal["anthropic"]) -> AnthropicClient:
+    """Get an Anthropic client instance."""
+    ...
+
+
+@overload
+def get_client(provider: Literal["google"]) -> GoogleClient:
+    """Get a Google client instance."""
+    ...
+
+
+@overload
+def get_client(provider: Literal["openai:completions"]) -> OpenAICompletionsClient:
+    """Get an OpenAI client instance."""
+    ...
+
+
+@overload
+def get_client(
+    provider: Literal["openai:responses", "openai"],
+) -> OpenAIResponsesClient:
+    """Get an OpenAI responses client instance."""
+    ...
+
+
+def get_client(
+    provider: Provider,
+) -> AnthropicClient | GoogleClient | OpenAICompletionsClient | OpenAIResponsesClient:
+    """Get a client instance for the specified provider.
+
+    Args:
+        provider: The provider name ("openai:completions", "anthropic", or "google").
+
+    Returns:
+        A client instance for the specified provider. The specific client type
+        depends on the provider:
+        - "openai:completions" returns `OpenAICompletionsClient` (ChatCompletion API)
+        - "openai:responses" returns `OpenAIResponsesClient` (Responses API)
+        - "anthropic" returns `AnthropicClient`
+        - "google" returns `GoogleClient`
+
+    Multiple calls to get_client will return the same Client rather than constructing
+    new ones.
+
+    Raises:
+        ValueError: If the provider is not supported.
+    """
+    match provider:
+        case "anthropic":
+            return get_anthropic_client()
+        case "google":
+            return get_google_client()
+        case "openai:completions":
+            return get_openai_completions_client()
+        case "openai:responses" | "openai":
+            return get_openai_responses_client()
+        case _:
+            raise ValueError(f"Unknown provider: {provider}")
+
+
+@overload
+def client(
+    provider: Literal["openai:completions"],
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> OpenAICompletionsClient:
+    """Create a cached OpenAI chat completions client with the given parameters."""
+    ...
+
+
+@overload
+def client(
+    provider: Literal["openai:responses", "openai"],
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> OpenAIResponsesClient:
+    """Create a cached OpenAI responses client with the given parameters."""
+    ...
+
+
+@overload
+def client(
+    provider: Literal["anthropic"],
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> AnthropicClient:
+    """Create a cached Anthropic client with the given parameters."""
+    ...
+
+
+@overload
+def client(
+    provider: Literal["google"],
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> GoogleClient:
+    """Create a cached Google client with the given parameters."""
+    ...
+
+
+def client(
+    provider: Provider, *, api_key: str | None = None, base_url: str | None = None
+) -> AnthropicClient | GoogleClient | OpenAICompletionsClient | OpenAIResponsesClient:
+    """Create a cached client instance for the specified provider.
+
+    Args:
+        provider: The provider name ("openai:completions", "anthropic", or "google").
+        api_key: API key for authentication. If None, uses provider-specific env var.
+        base_url: Base URL for the API. If None, uses provider-specific env var.
+
+    Returns:
+        A cached client instance for the specified provider with the given parameters.
+
+    Raises:
+        ValueError: If the provider is not supported.
+    """
+    match provider:
+        case "anthropic":
+            return anthropic_client(api_key=api_key, base_url=base_url)
+        case "google":
+            return google_client(api_key=api_key, base_url=base_url)
+        case "openai:completions":
+            return openai_completions_client(api_key=api_key, base_url=base_url)
+        case "openai:responses" | "openai":
+            return openai_responses_client(api_key=api_key, base_url=base_url)
+        case _:  # pragma: no cover
+            raise ValueError(f"Unknown provider: {provider}")

mirascope/llm/content/__init__.py

@@ -0,0 +1,70 @@
+"""The `llm.messages.content` module."""
+
+from typing import TypeAlias
+
+from .audio import Audio, Base64AudioSource
+from .document import (
+    Base64DocumentSource,
+    Document,
+    TextDocumentSource,
+    URLDocumentSource,
+)
+from .image import Base64ImageSource, Image, ImageMimeType, URLImageSource
+from .text import Text, TextChunk, TextEndChunk, TextStartChunk
+from .thought import Thought, ThoughtChunk, ThoughtEndChunk, ThoughtStartChunk
+from .tool_call import ToolCall, ToolCallChunk, ToolCallEndChunk, ToolCallStartChunk
+from .tool_output import ToolOutput
+
+ContentPart: TypeAlias = (
+    Text | Image | Audio | Document | ToolOutput | ToolCall | Thought
+)
+"""Content parts that may be included in a Message."""
+
+UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput
+"""Content parts that can be included in a UserMessage."""
+
+AssistantContentPart: TypeAlias = Text | ToolCall | Thought
+"""Content parts that can be included in an AssistantMessage."""
+
+AssistantContentChunk: TypeAlias = (
+    TextStartChunk
+    | TextChunk
+    | TextEndChunk
+    | ThoughtStartChunk
+    | ThoughtChunk
+    | ThoughtEndChunk
+    | ToolCallStartChunk
+    | ToolCallChunk
+    | ToolCallEndChunk
+)
+"""Chunks of assistant content that may be streamed as generated by the LLM."""
+
+__all__ = [
+    "AssistantContentChunk",
+    "AssistantContentPart",
+    "Audio",
+    "Base64AudioSource",
+    "Base64DocumentSource",
+    "Base64ImageSource",
+    "ContentPart",
+    "Document",
+    "Image",
+    "ImageMimeType",
+    "Text",
+    "TextChunk",
+    "TextDocumentSource",
+    "TextEndChunk",
+    "TextStartChunk",
+    "Thought",
+    "ThoughtChunk",
+    "ThoughtEndChunk",
+    "ThoughtStartChunk",
+    "ToolCall",
+    "ToolCallChunk",
+    "ToolCallEndChunk",
+    "ToolCallStartChunk",
+    "ToolOutput",
+    "URLDocumentSource",
+    "URLImageSource",
+    "UserContentPart",
+]

mirascope/llm/content/audio.py

@@ -0,0 +1,173 @@
+"""The `Audio` content class."""
+
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, get_args
+
+import httpx
+
+AudioMimeType = Literal[
+    "audio/wav",
+    "audio/mp3",
+    "audio/aiff",
+    "audio/aac",
+    "audio/ogg",
+    "audio/flac",
+]  # TODO: add e2e tests for every supported type
+
+MIME_TYPES = get_args(AudioMimeType)
+
+# Maximum audio size in bytes (25MB)
+MAX_AUDIO_SIZE = 25 * 1024 * 1024
+
+
+def infer_audio_type(audio_data: bytes) -> AudioMimeType:
+    """Get the MIME type of an audio file from its raw bytes.
+
+    Raises:
+        ValueError: If the audio type cannot be determined or data is too small
+    """
+    if len(audio_data) < 12:
+        raise ValueError("Audio data too small to determine type (minimum 12 bytes)")
+
+    if audio_data.startswith(b"RIFF") and audio_data[8:12] == b"WAVE":
+        return "audio/wav"
+    elif audio_data.startswith(b"ID3") or audio_data.startswith(b"\xff\xfb"):
+        return "audio/mp3"
+    elif audio_data.startswith(b"FORM") and audio_data[8:12] == b"AIFF":
+        return "audio/aiff"
+    elif audio_data.startswith(b"\xff\xf1") or audio_data.startswith(b"\xff\xf9"):
+        return "audio/aac"
+    elif audio_data.startswith(b"OggS"):
+        return "audio/ogg"
+    elif audio_data.startswith(b"fLaC"):
+        return "audio/flac"
+    raise ValueError("Unsupported audio type")
+
+
+@dataclass(kw_only=True)
+class Base64AudioSource:
+    """Audio data represented as a base64 encoded string."""
+
+    type: Literal["base64_audio_source"]
+
+    data: str
+    """The audio data, as a base64 encoded string."""
+
+    mime_type: AudioMimeType
+    """The mime type of the audio (e.g. audio/mp3)."""
+
+
+def _process_audio_bytes(data: bytes, max_size: int) -> Base64AudioSource:
+    """Validate and process audio bytes into a Base64AudioSource.
+
+    Args:
+        data: Raw audio bytes
+        max_size: Maximum allowed size in bytes
+
+    Returns:
+        A Base64AudioSource with validated and encoded data
+
+    Raises:
+        ValueError: If data size exceeds max_size
+    """
+    size = len(data)
+    if size > max_size:
+        raise ValueError(
+            f"Audio size ({size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+        )
+
+    mime_type = infer_audio_type(data)
+    encoded_data = base64.b64encode(data).decode("utf-8")
+    return Base64AudioSource(
+        type="base64_audio_source",
+        data=encoded_data,
+        mime_type=mime_type,
+    )
+
+
+@dataclass(kw_only=True)
+class Audio:
+    """Audio content for a message.
+
+    Audio can be included in messages for voice or sound-based interactions.
+    """
+
+    type: Literal["audio"] = "audio"
+
+    source: Base64AudioSource
+
+    @classmethod
+    def download(cls, url: str, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Download and encode an audio file from a URL.
+
+        Args:
+            url: The URL of the audio file to download
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Returns:
+            An `Audio` with a `Base64AudioSource`
+
+        Raises:
+            ValueError: If the downloaded audio exceeds max_size
+        """
+        response = httpx.get(url, follow_redirects=True)
+        response.raise_for_status()
+        return cls(source=_process_audio_bytes(response.content, max_size))
+
+    @classmethod
+    async def download_async(
+        cls, url: str, *, max_size: int = MAX_AUDIO_SIZE
+    ) -> "Audio":
+        """Asynchronously download and encode an audio file from a URL.
+
+        Args:
+            url: The URL of the audio file to download
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Returns:
+            An `Audio` with a `Base64AudioSource`
+
+        Raises:
+            ValueError: If the downloaded audio exceeds max_size
+        """
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, follow_redirects=True)
+            response.raise_for_status()
+            return cls(source=_process_audio_bytes(response.content, max_size))
+
+    @classmethod
+    def from_file(cls, file_path: str, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Create an `Audio` from a file path.
+
+        Args:
+            file_path: Path to the audio file
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Raises:
+            FileNotFoundError: If the file does not exist
+            ValueError: If the file size exceeds max_size
+        """
+        path = Path(file_path)
+        file_size = path.stat().st_size
+        if file_size > max_size:
+            raise ValueError(
+                f"Audio file size ({file_size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+            )
+        with open(path, "rb") as f:
+            audio_bytes = f.read()
+        return cls(source=_process_audio_bytes(audio_bytes, max_size))
+
+    @classmethod
+    def from_bytes(cls, data: bytes, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Create an `Audio` from raw bytes.
+
+        Args:
+            data: Raw audio bytes
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Raises:
+            ValueError: If the data size exceeds max_size
+        """
+        return cls(source=_process_audio_bytes(data, max_size))

mirascope/llm/content/document.py

@@ -0,0 +1,94 @@
+"""The `Document` content class."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+DocumentTextMimeType = Literal[
+    "application/json",
+    "text/plain",
+    "application/x-javascript",
+    "text/javascript",
+    "application/x-python",
+    "text/x-python",
+    "text/html",
+    "text/css",
+    "text/xml",
+    "text/rtf",
+]
+"""Mime type for documents encoded as plain text."""
+
+DocumentBase64MimeType = Literal["application/pdf"]
+"""Mime type for documents encoded as base64 strings."""
+
+
+@dataclass(kw_only=True)
+class Base64DocumentSource:
+    """Document data represented as a base64 encoded string."""
+
+    type: Literal["base64_document_source"]
+
+    data: str
+    """The document data, as a base64 encoded string."""
+
+    media_type: DocumentBase64MimeType
+    """The media type of the document (e.g. application/pdf)."""
+
+
+@dataclass(kw_only=True)
+class TextDocumentSource:
+    """Plain text document data."""
+
+    type: Literal["text_document_source"]
+
+    data: str
+    """The document data, as plain text."""
+
+    media_type: DocumentTextMimeType
+    """The media type of the document (e.g. text/plain, text/csv)."""
+
+
+@dataclass(kw_only=True)
+class URLDocumentSource:
+    """Document data referenced via external URL."""
+
+    type: Literal["url_document_source"]
+
+    url: str
+    """The url of the document (e.g. https://example.com/paper.pdf)."""
+
+
+@dataclass(kw_only=True)
+class Document:
+    """Document content for a message.
+
+    Documents (like PDFs) can be included for the model to analyze or reference.
+    """
+
+    type: Literal["document"] = "document"
+
+    source: Base64DocumentSource | TextDocumentSource | URLDocumentSource
+
+    @classmethod
+    def from_url(cls, url: str, *, download: bool = False) -> "Document":
+        """Create a `Document` from a URL."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_file(
+        cls,
+        file_path: str,
+        *,
+        mime_type: DocumentTextMimeType | DocumentBase64MimeType | None,
+    ) -> "Document":
+        """Create a `Document` from a file path."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_bytes(
+        cls,
+        data: bytes,
+        *,
+        mime_type: DocumentTextMimeType | DocumentBase64MimeType | None,
+    ) -> "Document":
+        """Create a `Document` from raw bytes."""
+        raise NotImplementedError