mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/providers/provider_registry.py

@@ -0,0 +1,305 @@
+"""Provider registry for managing provider instances and scopes."""
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import overload
+
+from ..exceptions import MissingAPIKeyError, NoRegisteredProviderError
+from .anthropic import AnthropicProvider
+from .base import Provider
+from .google import GoogleProvider
+from .mirascope import MirascopeProvider
+from .mlx import MLXProvider
+from .ollama import OllamaProvider
+from .openai import OpenAIProvider
+from .openai.completions.provider import OpenAICompletionsProvider
+from .openai.responses.provider import OpenAIResponsesProvider
+from .openrouter import OpenRouterProvider
+from .provider_id import ProviderId
+from .together import TogetherProvider
+
+# Global registry mapping scopes to providers
+# Scopes are matched by prefix (longest match wins)
+PROVIDER_REGISTRY: dict[str, Provider] = {}
+
+
+def reset_provider_registry() -> None:
+    """Resets the provider registry, clearing all registered providers."""
+    PROVIDER_REGISTRY.clear()
+    provider_singleton.cache_clear()
+
+
+@dataclass(frozen=True)
+class ProviderDefault:
+    """Configuration for a provider in the auto-registration fallback chain.
+
+    When auto-registering a provider for a scope, the fallback chain is tried
+    in order. The first provider whose API key is available will be used.
+    """
+
+    provider_id: ProviderId
+    """The provider identifier."""
+
+    api_key_env_var: str | None
+    """Environment variable for the API key, or None if no key is required."""
+
+
+# Fallback chain for auto-registration: try providers in order until one has
+# its API key available. This enables automatic fallback to Mirascope Router
+# when direct provider keys are not set.
+DEFAULT_AUTO_REGISTER_SCOPES: dict[str, Sequence[ProviderDefault]] = {
+    "anthropic/": [
+        ProviderDefault("anthropic", "ANTHROPIC_API_KEY"),
+        ProviderDefault("mirascope", "MIRASCOPE_API_KEY"),
+    ],
+    "google/": [
+        ProviderDefault("google", "GOOGLE_API_KEY"),
+        ProviderDefault("mirascope", "MIRASCOPE_API_KEY"),
+    ],
+    "openai/": [
+        ProviderDefault("openai", "OPENAI_API_KEY"),
+        ProviderDefault("mirascope", "MIRASCOPE_API_KEY"),
+    ],
+    "together/": [
+        ProviderDefault("together", "TOGETHER_API_KEY"),
+        # No Mirascope fallback for together
+    ],
+    "ollama/": [
+        ProviderDefault("ollama", None),  # No API key required
+    ],
+    "mlx-community/": [
+        ProviderDefault("mlx", None),  # No API key required
+    ],
+    "openrouter/": [
+        ProviderDefault("openrouter", "OPENROUTER_API_KEY"),
+    ],
+}
+
+
+def _has_api_key(default: ProviderDefault) -> bool:
+    """Check if the API key for a provider default is available.
+
+    Args:
+        default: The provider default configuration to check.
+
+    Returns:
+        True if the API key is available or not required, False otherwise.
+    """
+    if default.api_key_env_var is None:
+        return True  # Provider doesn't require API key
+    return os.environ.get(default.api_key_env_var) is not None
+
+
+@lru_cache(maxsize=256)
+def provider_singleton(
+    provider_id: ProviderId, *, api_key: str | None = None, base_url: str | None = None
+) -> Provider:
+    """Create a cached provider instance for the specified provider id.
+
+    Args:
+        provider_id: The provider name ("openai", "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 provider instance for the specified provider with the given parameters.
+
+    Raises:
+        ValueError: If the provider_id is not supported.
+    """
+    match provider_id:
+        case "anthropic":
+            return AnthropicProvider(api_key=api_key, base_url=base_url)
+        case "google":
+            return GoogleProvider(api_key=api_key, base_url=base_url)
+        case "mirascope":
+            return MirascopeProvider(api_key=api_key, base_url=base_url)
+        case "mlx":  # pragma: no cover (MLX is only available on macOS)
+            return MLXProvider()
+        case "ollama":
+            return OllamaProvider(api_key=api_key, base_url=base_url)
+        case "openai":
+            return OpenAIProvider(api_key=api_key, base_url=base_url)
+        case "openai:completions":
+            return OpenAICompletionsProvider(api_key=api_key, base_url=base_url)
+        case "openai:responses":
+            return OpenAIResponsesProvider(api_key=api_key, base_url=base_url)
+        case "openrouter":
+            return OpenRouterProvider(api_key=api_key, base_url=base_url)
+        case "together":
+            return TogetherProvider(api_key=api_key, base_url=base_url)
+        case _:  # pragma: no cover
+            raise ValueError(f"Unknown provider: '{provider_id}'")
+
+
+@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 = provider_singleton(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.
+
+    When auto-registering, providers are tried in fallback order. For example,
+    if ANTHROPIC_API_KEY is not set but MIRASCOPE_API_KEY is, the Mirascope
+    Router will be used as a fallback for anthropic/ models.
+
+    Args:
+        model_id: The full model ID (e.g., "anthropic/claude-4-5-sonnet").
+
+    Returns:
+        The provider instance registered for this model.
+
+    Raises:
+        NoRegisteredProviderError: If no provider scope matches the model_id.
+        MissingAPIKeyError: If no provider in the fallback chain has its API key set.
+
+    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/"
+
+        # Fallback to Mirascope Router if direct key missing:
+        # (with MIRASCOPE_API_KEY set but not ANTHROPIC_API_KEY)
+        provider = get_provider_for_model("anthropic/claude-4-5-sonnet")
+        # Returns MirascopeProvider registered for "anthropic/" scope
+        ```
+    """
+    # 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 with fallback chain
+    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)
+        fallback_chain = DEFAULT_AUTO_REGISTER_SCOPES[best_scope]
+
+        # Try each provider in the fallback chain
+        for default in fallback_chain:
+            if _has_api_key(default):
+                provider = provider_singleton(default.provider_id)
+                # Register for just this scope (not all provider's default scopes)
+                PROVIDER_REGISTRY[best_scope] = provider
+                return provider
+
+        # No provider in chain has API key - raise helpful error
+        primary = fallback_chain[0]
+        has_mirascope_fallback = any(
+            d.provider_id == "mirascope" for d in fallback_chain
+        )
+        raise MissingAPIKeyError(
+            provider_id=primary.provider_id,
+            env_var=primary.api_key_env_var or "",
+            has_mirascope_fallback=has_mirascope_fallback,
+        )
+
+    # No matching scope at all
+    raise NoRegisteredProviderError(model_id)

mirascope/llm/providers/together/__init__.py

@@ -0,0 +1,7 @@
+"""Together AI provider implementation."""
+
+from .provider import TogetherProvider
+
+__all__ = [
+    "TogetherProvider",
+]

mirascope/llm/providers/together/provider.py

@@ -0,0 +1,40 @@
+"""Together AI provider implementation."""
+
+from typing import ClassVar
+
+from ..openai.completions.base_provider import BaseOpenAICompletionsProvider
+
+
+class TogetherProvider(BaseOpenAICompletionsProvider):
+    """Provider for Together AI's OpenAI-compatible API.
+
+    Inherits from BaseOpenAICompletionsProvider with Together-specific configuration:
+    - Uses Together AI's API endpoint
+    - Requires TOGETHER_API_KEY
+
+    Usage:
+        Register the provider with model ID prefixes you want to use:
+
+        ```python
+        import llm
+
+        # Register for meta-llama models
+        llm.register_provider("together", "meta-llama/")
+
+        # Now you can use meta-llama models directly
+        @llm.call("meta-llama/Llama-3.3-70B-Instruct-Turbo")
+        def my_prompt():
+            return [llm.messages.user("Hello!")]
+        ```
+    """
+
+    id: ClassVar[str] = "together"
+    default_scope: ClassVar[str | list[str]] = []
+    default_base_url: ClassVar[str | None] = "https://api.together.xyz/v1"
+    api_key_env_var: ClassVar[str] = "TOGETHER_API_KEY"
+    api_key_required: ClassVar[bool] = True
+    provider_name: ClassVar[str | None] = "Together"
+
+    def _model_name(self, model_id: str) -> str:
+        """Return the model ID as-is for Together API."""
+        return model_id

mirascope/llm/responses/__init__.py

@@ -0,0 +1,66 @@
+"""The Responses module for LLM responses."""
+
+from . import _utils
+from .base_response import ResponseT
+from .base_stream_response import (
+    AsyncChunkIterator,
+    ChunkIterator,
+    RawMessageChunk,
+    RawStreamEventChunk,
+    StreamResponseChunk,
+    StreamResponseT,
+)
+from .finish_reason import FinishReason, FinishReasonChunk
+from .response import AsyncContextResponse, AsyncResponse, ContextResponse, Response
+from .root_response import AnyResponse, RootResponse
+from .stream_response import (
+    AsyncContextStreamResponse,
+    AsyncStreamResponse,
+    ContextStreamResponse,
+    StreamResponse,
+)
+from .streams import (
+    AsyncStream,
+    AsyncTextStream,
+    AsyncThoughtStream,
+    AsyncToolCallStream,
+    Stream,
+    TextStream,
+    ThoughtStream,
+    ToolCallStream,
+)
+from .usage import ProviderToolUsage, Usage, UsageDeltaChunk
+
+__all__ = [
+    "AnyResponse",
+    "AsyncChunkIterator",
+    "AsyncContextResponse",
+    "AsyncContextStreamResponse",
+    "AsyncResponse",
+    "AsyncStream",
+    "AsyncStreamResponse",
+    "AsyncTextStream",
+    "AsyncThoughtStream",
+    "AsyncToolCallStream",
+    "ChunkIterator",
+    "ContextResponse",
+    "ContextStreamResponse",
+    "FinishReason",
+    "FinishReasonChunk",
+    "ProviderToolUsage",
+    "RawMessageChunk",
+    "RawStreamEventChunk",
+    "Response",
+    "ResponseT",
+    "RootResponse",
+    "Stream",
+    "StreamResponse",
+    "StreamResponseChunk",
+    "StreamResponseT",
+    "TextStream",
+    "ThoughtStream",
+    "ToolCallStream",
+    "Usage",
+    "UsageDeltaChunk",
+    "_utils",
+]

mirascope/llm/responses/_utils.py

@@ -0,0 +1,146 @@
+"""Utilities for response classes."""
+
+import json
+from typing import cast
+
+import jiter
+from pydantic import BaseModel
+
+from ..formatting import (
+    FormattableT,
+    Partial,
+    PrimitiveWrapperModel,
+    create_wrapper_model,
+    is_primitive_type,
+)
+
+
+def _strip_json_preamble(text: str) -> str | None:
+    """Strip preamble text before JSON content.
+
+    Handles cases where models output text before JSON like:
+    "Sure thing! Here's the JSON:\n{..."
+
+    Or cases where the model wraps the JSON in code blocks like:
+    "```json\n{..."
+
+    Args:
+        text: The raw text that may contain a JSON object
+
+    Returns:
+        Text starting from the opening `{`, or None if no `{` found.
+    """
+    code_block_start_marker = "```json"
+    code_block_start = text.find(code_block_start_marker)
+    if code_block_start > -1:
+        # Discard text prior to code block; it takes precedence over brackets that
+        # may be found before it.
+        text = text[code_block_start:]
+
+    json_start = text.find("{")
+    if json_start == -1:
+        return None
+
+    return text[json_start:]
+
+
+def extract_serialized_json(text: str) -> str:
+    """Extract the serialized JSON string from text that may contain extra content.
+
+    Handles cases where models output text before JSON like:
+    "Sure thing! Here's the JSON:\n{...}"
+
+    Or cases where the model wraps the JSON in code blocks like:
+    "```json\n{...}\n```"
+
+    Args:
+        text: The raw text that may contain a JSON object
+
+    Raises:
+        json.JSONDecodeError: If no valid JSON object could be extracted.
+
+    Returns:
+        The extracted serialized JSON string
+    """
+    stripped = _strip_json_preamble(text)
+    if stripped is None:
+        raise json.JSONDecodeError("No JSON object found: missing '{'", text, 0)
+
+    # Find the matching closing brace
+    brace_count = 0
+    in_string = False
+    escaped = False
+
+    for i, char in enumerate(stripped):
+        if escaped:
+            escaped = False
+            continue
+
+        if char == "\\":
+            escaped = True
+            continue
+
+        if char == '"' and not escaped:
+            in_string = not in_string
+            continue
+
+        if not in_string:
+            if char == "{":
+                brace_count += 1
+            elif char == "}":
+                brace_count -= 1
+                if brace_count == 0:
+                    return stripped[: i + 1]
+
+    raise json.JSONDecodeError("No JSON object found: missing '}'", text, len(text))
+
+
+def parse_partial_json(
+    json_text: str, formattable: type[FormattableT]
+) -> FormattableT | Partial[FormattableT] | None:
+    """Parse incomplete JSON into a Partial model for structured streaming.
+
+    Uses jiter's partial mode to handle incomplete JSON gracefully.
+    Returns None if JSON cannot be parsed yet.
+
+    Handles cases where models output text before JSON like:
+    "Sure thing! Here's the JSON:\n{..."
+
+    Args:
+        json_text: The incomplete JSON string to parse
+        formattable: The target format type (BaseModel or PrimitiveType)
+
+    Returns:
+        Parsed partial object, or None if unparsable
+
+    Example:
+        >>> from pydantic import BaseModel
+        >>> class Book(BaseModel):
+        ...     title: str
+        ...     author: str
+        >>> parse_partial_json('{"title": "The Name"', Book)
+        PartialBook(title='The Name', author=None)
+    """
+    # Strip preamble text before JSON
+    stripped = _strip_json_preamble(json_text)
+    if stripped is None:
+        return None
+
+    try:
+        parsed = jiter.from_json(stripped.encode(), partial_mode="trailing-strings")
+    except Exception:
+        return None
+
+    target_model = formattable
+    if is_primitive_type(target_model):
+        target_model = cast(BaseModel, create_wrapper_model(target_model))
+
+    try:
+        instance = cast(BaseModel, Partial[target_model]).model_validate(parsed)
+    except Exception:
+        return None
+
+    if is_primitive_type(formattable):
+        return cast(PrimitiveWrapperModel, instance).output
+
+    return cast(Partial[FormattableT], instance)

mirascope/llm/responses/base_response.py

@@ -0,0 +1,103 @@
+"""Shared base of Response and AsyncResponse."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ..content import Text, Thought, ToolCall
+from ..formatting import Format, FormattableT
+from ..messages import AssistantMessage, Message
+from ..tools import FORMAT_TOOL_NAME, ToolkitT
+from .finish_reason import FinishReason
+from .root_response import RootResponse
+from .usage import Usage
+
+if TYPE_CHECKING:
+    from ..models import Params
+    from ..providers import ModelId, ProviderId
+
+ResponseT = TypeVar("ResponseT", bound="BaseResponse[Any, Any]")
+
+
+class BaseResponse(RootResponse[ToolkitT, FormattableT]):
+    """The response generated by an LLM."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider_id: "ProviderId",
+        model_id: "ModelId",
+        provider_model_name: str,
+        params: "Params",
+        toolkit: ToolkitT,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+        usage: Usage | None,
+    ) -> None:
+        """Initialize a Response.
+
+        Args:
+            raw: The raw response from the LLM.
+            provider: The provider name (e.g. "anthropic", "openai").
+            model_id: The model identifier that generated the response.
+            provider_model_name: Optional provider-specific model name. May include
+                provider-specific additional info (like api mode in "gpt-5:responses").
+            params: The params used to generate the response (or None).
+            toolkit: Toolkit containing all the tools used to generate the response.
+            format: The `Format` for the expected structured output format (or None).
+            input_messages: The message history before the final assistant message.
+            assistant_message: The final assistant message containing the response content.
+            finish_reason: The reason why the LLM finished generating a response.
+            usage: Token usage statistics for the response.
+        """
+        self.raw = raw
+        self.provider_id = provider_id
+        self.model_id = model_id
+        self.provider_model_name = provider_model_name
+        self.params = params
+        self.toolkit = toolkit
+        self.finish_reason = finish_reason
+        self.usage = usage
+        self.format = format
+
+        # Process content in the assistant message, organizing it by type and
+        # transforming ToolCalls to the special format tool into text (as calls to the
+        # formatting tool are not "real" tool calls, and response.parse() expects to
+        # operate on text content).
+        self.texts = []
+        self.tool_calls = []
+        self.thoughts = []
+        self.content = []
+        found_format_tool = False
+
+        for part in assistant_message.content:
+            if isinstance(part, ToolCall) and part.name.startswith(FORMAT_TOOL_NAME):
+                part = Text(text=part.args)
+                found_format_tool = True
+
+            self.content.append(part)
+            if isinstance(part, Text):
+                self.texts.append(part)
+            elif isinstance(part, ToolCall):
+                self.tool_calls.append(part)
+            elif isinstance(part, Thought):
+                self.thoughts.append(part)
+            else:
+                raise NotImplementedError
+
+        if found_format_tool:
+            # We create a new assistant message if we found a formatting ToolCall
+            # since this indicates we've transformed the content from the original
+            # NOTE: we copy over the assistant message `name` field, although in
+            # practice we don't know of any providers that set the name themselves.
+            assistant_message = AssistantMessage(
+                content=self.content,
+                name=assistant_message.name,
+                provider_id=assistant_message.provider_id,
+                model_id=assistant_message.model_id,
+                provider_model_name=assistant_message.provider_model_name,
+                raw_message=assistant_message.raw_message,
+            )
+        self.messages = list(input_messages) + [assistant_message]