mirascope 2.0.0__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

@@ -2,7 +2,6 @@
 
 from typing import TypeAlias
 
-from ..types import Jsonable
 from .audio import Audio, Base64AudioSource
 from .document import (
     Base64DocumentSource,
@@ -17,11 +16,11 @@ from .tool_call import ToolCall, ToolCallChunk, ToolCallEndChunk, ToolCallStartC
 from .tool_output import ToolOutput
 
 ContentPart: TypeAlias = (
-    Text | Image | Audio | Document | ToolOutput[Jsonable] | ToolCall | Thought
+    Text | Image | Audio | Document | ToolOutput | ToolCall | Thought
 )
 """Content parts that may be included in a Message."""
 
-UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput[Jsonable]
+UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput
 """Content parts that can be included in a UserMessage."""
 
 AssistantContentPart: TypeAlias = Text | ToolCall | Thought

mirascope/llm/content/tool_call.py

@@ -49,9 +49,6 @@ class ToolCallChunk:
     content_type: Literal["tool_call"] = "tool_call"
     """The type of content reconstructed by this chunk."""
 
-    id: str
-    """A unique identifier for this tool call."""
-
     delta: str
     """The incremental json args added in this chunk."""
 
@@ -64,6 +61,3 @@ class ToolCallEndChunk:
 
     content_type: Literal["tool_call"] = "tool_call"
     """The type of content reconstructed by this chunk."""
-
-    id: str
-    """A unique identifier for this tool call."""

mirascope/llm/content/tool_output.py

@@ -1,14 +1,13 @@
 """The `ToolOutput` content class."""
 
 from dataclasses import dataclass
-from typing import Generic, Literal, cast
+from typing import Generic, Literal
 
-from ..exceptions import ToolError
-from ..types import JsonableCovariantT
+from ..types import JsonableT
 
 
 @dataclass(kw_only=True)
-class ToolOutput(Generic[JsonableCovariantT]):
+class ToolOutput(Generic[JsonableT]):
     """Tool output content for a message.
 
     Represents the output from a tool call. This is part of a user message's
@@ -23,21 +22,5 @@ class ToolOutput(Generic[JsonableCovariantT]):
     name: str
     """The name of the tool that created this output."""
 
-    result: JsonableCovariantT | str
-    """The result of calling the tool.
-    
-    If the tool executed successfully, this will be the tool output.
-    If the tool errored, this will be the error message, as a string.
-    
-    In either case, the result should be passed back to the LLM (so it can
-    either process the output, or re-try with awareness of the error.)
-    """
-
-    error: ToolError | None = None
-    """The error from calling the tool, if any."""
-
-    @property
-    def output(self) -> JsonableCovariantT:
-        if self.error is not None:
-            raise self.error
-        return cast(JsonableCovariantT, self.result)
+    value: JsonableT
+    """The output value from the tool call."""

mirascope/llm/context/_utils.py

@@ -1,12 +1,11 @@
 import inspect
-import typing
 from collections.abc import Callable
-from typing import Any, get_origin
+from typing import get_origin
 
 from .context import Context
 
 
-def first_param_is_context(fn: Callable[..., Any]) -> bool:
+def first_param_is_context(fn: Callable) -> bool:
     """Returns whether the first argument to a function is `ctx: Context`.
 
     Also returns true if the first argument is a subclass of `Context`.
@@ -22,20 +21,8 @@ def first_param_is_context(fn: Callable[..., Any]) -> bool:
     else:
         first_param = params[0]
 
-    if first_param.name != "ctx":
-        return False
-
-    try:
-        hints = typing.get_type_hints(fn)
-        annotation = hints.get(first_param.name)
-    except (NameError, AttributeError, TypeError):
-        annotation = first_param.annotation
-
-    if annotation is None or annotation is inspect.Parameter.empty:
-        return False
-
-    type_is_context = get_origin(annotation) is Context
-    subclass_of_context = isinstance(annotation, type) and issubclass(
-        annotation, Context
+    type_is_context = get_origin(first_param.annotation) is Context
+    subclass_of_context = isinstance(first_param.annotation, type) and issubclass(
+        first_param.annotation, Context
     )
-    return type_is_context or subclass_of_context
+    return first_param.name == "ctx" and (type_is_context or subclass_of_context)