mirascope 2.0.0a2__py3-none-any.whl → 2.0.0a4__py3-none-any.whl

mirascope/llm/providers/openai/responses/provider.py

@@ -0,0 +1,469 @@
+"""OpenAI Responses API client implementation."""
+
+from collections.abc import Sequence
+from typing_extensions import Unpack
+
+from openai import AsyncOpenAI, OpenAI
+
+from ....context import Context, DepsT
+from ....formatting import Format, FormattableT
+from ....messages import Message
+from ....responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ....tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+)
+from ...base import BaseProvider, Params
+from ..model_id import OpenAIModelId, model_name
+from . import _utils
+
+
+class OpenAIResponsesProvider(BaseProvider[OpenAI]):
+    """The client for the OpenAI Responses API."""
+
+    id = "openai:responses"
+    default_scope = "openai/"
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        """Initialize the OpenAI Responses client."""
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
+        self.async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+    def _call(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> Response | Response[FormattableT]:
+        """Generate an `llm.Response` by synchronously calling the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.Response` object containing the LLM-generated content.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = self.client.responses.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return Response(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _call_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` by asynchronously calling the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncResponse` object containing the LLM-generated content.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _stream(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generate a `llm.StreamResponse` by synchronously streaming from the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.StreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return StreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    async def _stream_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Generate a `llm.AsyncStreamResponse` by asynchronously streaming from the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncStreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    def _context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT] | ContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.ContextResponse` by synchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.ContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = self.client.responses.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.AsyncContextResponse` by asynchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
+        """Generate a `llm.ContextStreamResponse` by synchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.ContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    async def _context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> (
+        AsyncContextStreamResponse[DepsT]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generate a `llm.AsyncContextStreamResponse` by asynchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )

mirascope/llm/providers/provider_id.py

@@ -0,0 +1,23 @@
+"""Identifiers for all registered providers."""
+
+from typing import Literal, TypeAlias, get_args
+
+KnownProviderId: TypeAlias = Literal[
+    "anthropic",  # Anthropic provider via AnthropicProvider
+    "anthropic-beta",  # Anthropic beta provider via AnthropicBetaProvider
+    "google",  # Google provider via GoogleProvider
+    "mlx",  # Local inference powered by `mlx-lm`, via MLXProvider
+    "ollama",  # Ollama provider via OllamaProvider
+    "openai",  # OpenAI provider via OpenAIProvider (prefers Responses routing when available)
+    "together",  # Together AI provider via TogetherProvider
+]
+KNOWN_PROVIDER_IDS = get_args(KnownProviderId)
+
+ProviderId = KnownProviderId | str
+
+OpenAICompletionsCompatibleProviderId: TypeAlias = Literal[
+    "ollama",  # Ollama (OpenAI-compatible)
+    "openai",  # OpenAI via OpenAIProvider (routes to completions)
+    "openai:completions",  # OpenAI Completions API directly
+    "together",  # Together AI (OpenAI-compatible)
+]

mirascope/llm/providers/provider_registry.py

@@ -0,0 +1,169 @@
+"""Provider registry for managing provider instances and scopes."""
+
+from typing import overload
+
+from ..exceptions import NoRegisteredProviderError
+from .base import Provider
+from .load_provider import load_provider
+from .provider_id import ProviderId
+
+# Global registry mapping scopes to providers
+# Scopes are matched by prefix (longest match wins)
+PROVIDER_REGISTRY: dict[str, Provider] = {}
+
+# Default auto-registration mapping for built-in providers
+# These providers will be automatically registered on first use
+DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
+    "anthropic/": "anthropic",
+    "google/": "google",
+    "mlx-community/": "mlx",
+    "ollama/": "ollama",
+    "openai/": "openai",
+    "together/": "together",
+}
+
+
+@overload
+def register_provider(
+    provider: Provider,
+    scope: str | list[str] | None = None,
+) -> Provider:
+    """Register a provider instance with scope(s).
+
+    Args:
+        provider: Provider instance to register.
+        scope: Scope string or list of scopes (e.g., "anthropic/", ["anthropic/", "openai/"]).
+            If None, uses the provider's default_scope.
+    """
+    ...
+
+
+@overload
+def register_provider(
+    provider: ProviderId,
+    scope: str | list[str] | None = None,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Provider:
+    """Register a provider by ID with scope(s).
+
+    Args:
+        provider: Provider ID string (e.g., "anthropic", "openai").
+        scope: Scope string or list of scopes (e.g., "anthropic/", ["anthropic/", "openai/"]).
+            If None, uses the provider's default_scope.
+        api_key: API key for authentication.
+        base_url: Base URL for the API.
+    """
+    ...
+
+
+def register_provider(
+    provider: ProviderId | Provider,
+    scope: str | list[str] | None = None,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Provider:
+    """Register a provider with scope(s) in the global registry.
+
+    Scopes use prefix matching on model IDs:
+    - "anthropic/" matches "anthropic/*"
+    - "anthropic/claude-4-5" matches "anthropic/claude-4-5*"
+    - "anthropic/claude-4-5-sonnet" matches exactly "anthropic/claude-4-5-sonnet"
+
+    When multiple scopes match a model_id, the longest match wins.
+
+    Args:
+        provider: Either a provider ID string or a provider instance.
+        scope: Scope string or list of scopes for prefix matching on model IDs.
+            If None, uses the provider's default_scope attribute.
+            Can be a single string or a list of strings.
+        api_key: API key for authentication (only used if provider is a string).
+        base_url: Base URL for the API (only used if provider is a string).
+
+    Example:
+        ```python
+        # Register with default scope
+        llm.register_provider("anthropic", api_key="key")
+
+        # Register for specific models
+        llm.register_provider("openai", scope="openai/gpt-4")
+
+        # Register for multiple scopes
+        llm.register_provider("aws-bedrock", scope=["anthropic/", "openai/"])
+
+        # Register a custom instance
+        custom = llm.providers.AnthropicProvider(api_key="team-key")
+        llm.register_provider(custom, scope="anthropic/claude-4-5-sonnet")
+        ```
+    """
+
+    if isinstance(provider, str):
+        provider = load_provider(provider, api_key=api_key, base_url=base_url)
+
+    if scope is None:
+        scope = provider.default_scope
+
+    scopes = [scope] if isinstance(scope, str) else scope
+    for s in scopes:
+        PROVIDER_REGISTRY[s] = provider
+
+    return provider
+
+
+def get_provider_for_model(model_id: str) -> Provider:
+    """Get the provider for a model_id based on the registry.
+
+    Uses longest prefix matching to find the most specific provider for the model.
+    If no explicit registration is found, checks for auto-registration defaults
+    and automatically registers the provider on first use.
+
+    Args:
+        model_id: The full model ID (e.g., "anthropic/claude-4-5-sonnet").
+
+    Returns:
+        The provider instance registered for this model.
+
+    Raises:
+        ValueError: If no provider is registered or available for this model.
+
+    Example:
+        ```python
+        # Assuming providers are registered:
+        # - "anthropic/" -> AnthropicProvider()
+        # - "anthropic/claude-4-5-sonnet" -> CustomProvider()
+
+        provider = get_provider_for_model("anthropic/claude-4-5-sonnet")
+        # Returns CustomProvider (longest match)
+
+        provider = get_provider_for_model("anthropic/claude-3-opus")
+        # Returns AnthropicProvider (matches "anthropic/" prefix)
+
+        # Auto-registration on first use:
+        provider = get_provider_for_model("openai/gpt-4")
+        # Automatically loads and registers OpenAIProvider() for "openai/"
+        ```
+    """
+    # Try explicit registry first (longest match wins)
+    matching_scopes = [
+        scope for scope in PROVIDER_REGISTRY if model_id.startswith(scope)
+    ]
+    if matching_scopes:
+        best_scope = max(matching_scopes, key=len)
+        return PROVIDER_REGISTRY[best_scope]
+
+    # Fall back to auto-registration
+    matching_defaults = [
+        scope for scope in DEFAULT_AUTO_REGISTER_SCOPES if model_id.startswith(scope)
+    ]
+    if matching_defaults:
+        best_scope = max(matching_defaults, key=len)
+        provider_id = DEFAULT_AUTO_REGISTER_SCOPES[best_scope]
+        provider = load_provider(provider_id)
+        # Auto-register for future calls
+        PROVIDER_REGISTRY[best_scope] = provider
+        return provider
+
+    # No provider found
+    raise NoRegisteredProviderError(model_id)

mirascope/llm/providers/together/__init__.py

@@ -0,0 +1,19 @@
+"""Together AI provider implementation."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .provider import TogetherProvider
+else:
+    try:
+        from .provider import TogetherProvider
+    except ImportError:  # pragma: no cover
+        from .._missing_import_stubs import (
+            create_provider_stub,
+        )
+
+        TogetherProvider = create_provider_stub("openai", "TogetherProvider")
+
+__all__ = [
+    "TogetherProvider",
+]