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

mirascope/llm/providers/provider_registry.py

@@ -1,299 +0,0 @@
-"""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 .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
-    ],
-}
-
-
-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 "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

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

mirascope/llm/providers/together/provider.py

@@ -1,40 +0,0 @@
-"""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/usage.py

@@ -1,95 +0,0 @@
-"""Provider-agnostic usage statistics for LLM API calls."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, Literal
-
-
-@dataclass(kw_only=True)
-class UsageDeltaChunk:
-    """A chunk containing incremental token usage information from a streaming response.
-
-    This represents a delta/increment in usage statistics as they arrive during streaming.
-    Multiple UsageDeltaChunks are accumulated to produce the final Usage object.
-    """
-
-    type: Literal["usage_delta_chunk"] = "usage_delta_chunk"
-
-    input_tokens: int = 0
-    """Delta in input tokens."""
-
-    output_tokens: int = 0
-    """Delta in output tokens."""
-
-    cache_read_tokens: int = 0
-    """Delta in cache read tokens."""
-
-    cache_write_tokens: int = 0
-    """Delta in cache write tokens."""
-
-    reasoning_tokens: int = 0
-    """Delta in reasoning/thinking tokens."""
-
-
-@dataclass(kw_only=True)
-class Usage:
-    """Token usage statistics from an LLM API call.
-
-    This abstraction captures common usage metrics across providers while preserving
-    access to the raw provider-specific usage data.
-    """
-
-    input_tokens: int = 0
-    """The number of input tokens used.
-
-    This includes ALL input tokens, including cache read and write tokens.
-
-    Will be 0 if not reported by the provider.
-    """
-
-    output_tokens: int = 0
-    """The number of output tokens used.
-
-    This includes ALL output tokens, including `reasoning_tokens` that may not be
-    in the user's visible output, or other "hidden" tokens.
-
-    Will be 0 if not reported by the provider.
-    """
-
-    cache_read_tokens: int = 0
-    """The number of tokens read from cache (prompt caching).
-
-    These are input tokens that were read from cache. Cache read tokens are generally
-    much less expensive than regular input tokens.
-
-    Will be 0 if not reported by the provider or if caching was not used.
-    """
-
-    cache_write_tokens: int = 0
-    """The number of tokens written to cache (cache creation).
-
-    These are input tokens that were written to cache, for future reuse and retrieval.
-    Cache write tokens are generally more expensive than uncached input tokens,
-    but may lead to cost savings down the line when they are re-read as cache_read_tokens.
-
-    Will be 0 if not reported by the provider or if caching was not used.
-    """
-
-    reasoning_tokens: int = 0
-    """The number of tokens used for reasoning/thinking.
-
-    Reasoning tokens are a subset of output_tokens that were generated as part of the model's
-    interior reasoning process. They are billed as output tokens, though they are generally
-    not shown to the user.
-
-    Will be 0 if not reported by the provider or if the model does not support reasoning.
-    """
-
-    raw: Any = None
-    """The raw usage object from the provider."""
-
-    @property
-    def total_tokens(self) -> int:
-        """The total number of tokens used (input + output)."""
-        return self.input_tokens + self.output_tokens

mirascope/ops/__init__.py

@@ -1,111 +0,0 @@
-"""Operational helpers (tracing, sessions, future ops.* utilities)."""
-
-from __future__ import annotations
-
-from .._stubs import stub_module_if_missing
-
-# Stub modules for missing optional dependencies BEFORE importing
-# This must happen before any imports from these modules
-stub_module_if_missing("mirascope.ops", "ops")
-
-# Now imports work regardless of which packages are installed
-# ruff: noqa: E402
-from ._internal.configuration import configure, tracer_context
-from ._internal.context import propagated_context
-from ._internal.instrumentation.llm import (
-    instrument_llm,
-    uninstrument_llm,
-)
-from ._internal.propagation import (
-    ContextPropagator,
-    PropagatorFormat,
-    extract_context,
-    get_propagator,
-    inject_context,
-    reset_propagator,
-)
-from ._internal.session import (
-    SESSION_HEADER_NAME,
-    SessionContext,
-    current_session,
-    extract_session_id,
-    session,
-)
-from ._internal.spans import Span, span
-from ._internal.traced_calls import (
-    TracedAsyncCall,
-    TracedAsyncContextCall,
-    TracedCall,
-    TracedContextCall,
-)
-from ._internal.traced_functions import (
-    AsyncTrace,
-    AsyncTracedFunction,
-    AsyncTracedSpanFunction,
-    Trace,
-    TracedFunction,
-    TracedSpanFunction,
-)
-from ._internal.tracing import (
-    TraceDecorator,
-    trace,
-)
-from ._internal.versioned_calls import (
-    VersionedAsyncCall,
-    VersionedAsyncContextCall,
-    VersionedCall,
-    VersionedContextCall,
-)
-from ._internal.versioned_functions import (
-    AsyncVersionedFunction,
-    VersionedFunction,
-    VersionInfo,
-)
-from ._internal.versioning import (
-    VersionDecorator,
-    version,
-)
-from .exceptions import ClosureComputationError
-
-__all__ = [
-    "SESSION_HEADER_NAME",
-    "AsyncTrace",
-    "AsyncTracedFunction",
-    "AsyncTracedSpanFunction",
-    "AsyncVersionedFunction",
-    "ClosureComputationError",
-    "ContextPropagator",
-    "PropagatorFormat",
-    "SessionContext",
-    "Span",
-    "Trace",
-    "TraceDecorator",
-    "TracedAsyncCall",
-    "TracedAsyncContextCall",
-    "TracedCall",
-    "TracedContextCall",
-    "TracedFunction",
-    "TracedSpanFunction",
-    "VersionDecorator",
-    "VersionInfo",
-    "VersionedAsyncCall",
-    "VersionedAsyncContextCall",
-    "VersionedCall",
-    "VersionedContextCall",
-    "VersionedFunction",
-    "configure",
-    "current_session",
-    "extract_context",
-    "extract_session_id",
-    "get_propagator",
-    "inject_context",
-    "instrument_llm",
-    "propagated_context",
-    "reset_propagator",
-    "session",
-    "span",
-    "trace",
-    "tracer_context",
-    "uninstrument_llm",
-    "version",
-]

mirascope/ops/_internal/__init__.py

@@ -1,5 +0,0 @@
-"""Private internal module for Mirascope.
-
-All modules within this directory are considered private implementation details
-and should not be imported directly by users.
-"""