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

mirascope/llm/clients/_missing_import_stubs.py

@@ -0,0 +1,47 @@
+"""Utilities for handling optional provider dependencies."""
+
+from collections.abc import Callable
+
+
+def create_import_error_stub(
+    package_name: str, client_name: str
+) -> Callable:  # pragma: no cover
+    """Create a stub that raises ImportError when called.
+
+    Args:
+        package_name: The package/extra name (e.g., "anthropic", "openai", "google")
+        client_name: The client name for the error message (e.g., "AnthropicClient")
+
+    Returns:
+        A callable that raises `ImportError` with helpful message.
+    """
+
+    def _raise_not_installed() -> None:
+        raise ImportError(
+            f"The '{package_name}' package is required to use {client_name}. "
+            f"Install it with: `uv add 'mirascope[{package_name}]'`. "
+            "Or use `uv add 'mirascope[all]'` to support all providers."
+        )
+
+    return _raise_not_installed
+
+
+def create_client_stub(package_name: str, client_name: str) -> type:  # pragma: no cover
+    """Create a stub client class that raises ImportError when instantiated.
+
+    Args:
+        package_name: The package/extra name (e.g., "anthropic", "openai", "google")
+        client_name: The client name for the error message (e.g., "AnthropicClient")
+
+    Returns:
+        A stub class that raises `ImportError` on instantiation.
+    """
+    error_fn = create_import_error_stub(package_name, client_name)
+
+    class _ClientStub:
+        """Stub client that raises `ImportError` when instantiated."""
+
+        def __init__(self) -> None:
+            error_fn()
+
+    return _ClientStub

mirascope/llm/clients/anthropic/__init__.py

@@ -0,0 +1,25 @@
+"""Anthropic client implementation."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .clients import AnthropicClient, client, get_client
+    from .model_ids import AnthropicModelId
+else:
+    try:
+        from .clients import AnthropicClient, client, get_client
+        from .model_ids import AnthropicModelId
+    except ImportError:  # pragma: no cover
+        from .._missing_import_stubs import create_client_stub, create_import_error_stub
+
+        AnthropicClient = create_client_stub("anthropic", "AnthropicClient")
+        AnthropicModelId = str
+        client = create_import_error_stub("anthropic", "AnthropicClient")
+        get_client = create_import_error_stub("anthropic", "AnthropicClient")
+
+__all__ = [
+    "AnthropicClient",
+    "AnthropicModelId",
+    "client",
+    "get_client",
+]

mirascope/llm/{providers/openai/completions → clients/anthropic}/_utils/__init__.py

@@ -2,7 +2,6 @@ from .decode import (
     decode_async_stream,
     decode_response,
     decode_stream,
-    model_name,
 )
 from .encode import encode_request
 
@@ -11,5 +10,4 @@ __all__ = [
     "decode_response",
     "decode_stream",
     "encode_request",
-    "model_name",
 ]

mirascope/llm/{providers → clients}/anthropic/_utils/decode.py

@@ -1,11 +1,10 @@
-"""Standard Anthropic response decoding."""
+"""Anthropic response decoding."""
 
 import json
 from typing import Any, TypeAlias, cast
 
 from anthropic import types as anthropic_types
 from anthropic.lib.streaming import AsyncMessageStreamManager, MessageStreamManager
-from anthropic.types.beta import BetaUsage
 
 from ....content import (
     AssistantContentPart,
@@ -30,10 +29,8 @@ from ....responses import (
     FinishReasonChunk,
     RawMessageChunk,
     RawStreamEventChunk,
-    Usage,
-    UsageDeltaChunk,
 )
-from ..model_id import AnthropicModelId, model_name
+from ..model_ids import AnthropicModelId
 
 ANTHROPIC_FINISH_REASON_MAP = {
     "max_tokens": FinishReason.MAX_TOKENS,
@@ -61,40 +58,15 @@ def _decode_assistant_content(
         )
 
 
-def decode_usage(
-    usage: anthropic_types.Usage | BetaUsage,
-) -> Usage:
-    """Convert Anthropic Usage (or BetaUsage) to Mirascope Usage."""
-
-    cache_read_tokens = usage.cache_read_input_tokens or 0
-    cache_write_tokens = usage.cache_creation_input_tokens or 0
-    input_tokens = usage.input_tokens + cache_read_tokens + cache_write_tokens
-    output_tokens = usage.output_tokens
-    return Usage(
-        input_tokens=input_tokens,
-        output_tokens=output_tokens,
-        cache_read_tokens=cache_read_tokens,
-        cache_write_tokens=cache_write_tokens,
-        reasoning_tokens=0,
-        raw=usage,
-    )
-
-
 def decode_response(
     response: anthropic_types.Message,
     model_id: AnthropicModelId,
-    *,
-    include_thoughts: bool,
-) -> tuple[AssistantMessage, FinishReason | None, Usage]:
-    """Convert Anthropic message to mirascope AssistantMessage and usage."""
-    content = [_decode_assistant_content(part) for part in response.content]
-    if not include_thoughts:
-        content = [part for part in content if part.type != "thought"]
+) -> tuple[AssistantMessage, FinishReason | None]:
+    """Convert Anthropic message to mirascope AssistantMessage."""
     assistant_message = AssistantMessage(
-        content=content,
-        provider_id="anthropic",
+        content=[_decode_assistant_content(part) for part in response.content],
+        provider="anthropic",
         model_id=model_id,
-        provider_model_name=model_name(model_id),
         raw_message={
             "role": response.role,
             "content": [part.model_dump() for part in response.content],
@@ -105,14 +77,14 @@ def decode_response(
         if response.stop_reason
         else None
     )
-    usage = decode_usage(response.usage)
-    return assistant_message, finish_reason, usage
+    return assistant_message, finish_reason
 
 
 ContentBlock: TypeAlias = (
     anthropic_types.TextBlockParam
     | anthropic_types.ThinkingBlockParam
     | anthropic_types.ToolUseBlockParam
+    | anthropic_types.ThinkingBlockParam
     | anthropic_types.RedactedThinkingBlockParam
 )
 
@@ -120,11 +92,10 @@ ContentBlock: TypeAlias = (
 class _AnthropicChunkProcessor:
     """Processes Anthropic stream events and maintains state across events."""
 
-    def __init__(self, *, include_thoughts: bool) -> None:
+    def __init__(self) -> None:
         self.current_block_param: ContentBlock | None = None
         self.accumulated_tool_json: str = ""
         self.accumulated_blocks: list[ContentBlock] = []
-        self.include_thoughts = include_thoughts
 
     def process_event(
         self, event: anthropic_types.RawMessageStreamEvent
@@ -159,8 +130,7 @@ class _AnthropicChunkProcessor:
                     "thinking": "",
                     "signature": "",
                 }
-                if self.include_thoughts:
-                    yield ThoughtStartChunk()
+                yield ThoughtStartChunk()
             elif content_block.type == "redacted_thinking":  # pragma: no cover
                 self.current_block_param = {
                     "type": "redacted_thinking",
@@ -187,17 +157,14 @@ class _AnthropicChunkProcessor:
                         f"Received input_json_delta for {self.current_block_param['type']} block"
                     )
                 self.accumulated_tool_json += delta.partial_json
-                yield ToolCallChunk(
-                    id=self.current_block_param["id"], delta=delta.partial_json
-                )
+                yield ToolCallChunk(delta=delta.partial_json)
             elif delta.type == "thinking_delta":
                 if self.current_block_param["type"] != "thinking":  # pragma: no cover
                     raise RuntimeError(
                         f"Received thinking_delta for {self.current_block_param['type']} block"
                     )
                 self.current_block_param["thinking"] += delta.thinking
-                if self.include_thoughts:
-                    yield ThoughtChunk(delta=delta.thinking)
+                yield ThoughtChunk(delta=delta.thinking)
             elif delta.type == "signature_delta":
                 if self.current_block_param["type"] != "thinking":  # pragma: no cover
                     raise RuntimeError(
@@ -227,10 +194,9 @@ class _AnthropicChunkProcessor:
                     if self.accumulated_tool_json
                     else {}
                 )
-                yield ToolCallEndChunk(id=self.current_block_param["id"])
+                yield ToolCallEndChunk()
             elif block_type == "thinking":
-                if self.include_thoughts:
-                    yield ThoughtEndChunk()
+                yield ThoughtEndChunk()
             else:
                 raise NotImplementedError
 
@@ -243,16 +209,6 @@ class _AnthropicChunkProcessor:
                 if finish_reason is not None:
                     yield FinishReasonChunk(finish_reason=finish_reason)
 
-            # Emit usage delta
-            usage = event.usage
-            yield UsageDeltaChunk(
-                input_tokens=usage.input_tokens or 0,
-                output_tokens=usage.output_tokens,
-                cache_read_tokens=usage.cache_read_input_tokens or 0,
-                cache_write_tokens=usage.cache_creation_input_tokens or 0,
-                reasoning_tokens=0,
-            )
-
     def raw_message_chunk(self) -> RawMessageChunk:
         return RawMessageChunk(
             raw_message=cast(
@@ -266,23 +222,23 @@ class _AnthropicChunkProcessor:
 
 
 def decode_stream(
-    anthropic_stream_manager: MessageStreamManager, *, include_thoughts: bool
+    anthropic_stream_manager: MessageStreamManager,
 ) -> ChunkIterator:
-    """Returns a ChunkIterator converted from an Anthropic MessageStreamManager."""
-    processor = _AnthropicChunkProcessor(include_thoughts=include_thoughts)
+    """Returns a ChunkIterator converted from an Anthropic MessageStreamManager"""
+    processor = _AnthropicChunkProcessor()
     with anthropic_stream_manager as stream:
-        for event in stream._raw_stream:  # pyright: ignore[reportPrivateUsage]
+        for event in stream._raw_stream:
             yield from processor.process_event(event)
     yield processor.raw_message_chunk()
 
 
 async def decode_async_stream(
-    anthropic_stream_manager: AsyncMessageStreamManager, *, include_thoughts: bool
+    anthropic_stream_manager: AsyncMessageStreamManager,
 ) -> AsyncChunkIterator:
-    """Returns an AsyncChunkIterator converted from an Anthropic MessageStreamManager."""
-    processor = _AnthropicChunkProcessor(include_thoughts=include_thoughts)
+    """Returns an AsyncChunkIterator converted from an Anthropic MessageStreamManager"""
+    processor = _AnthropicChunkProcessor()
     async with anthropic_stream_manager as stream:
-        async for event in stream._raw_stream:  # pyright: ignore[reportPrivateUsage]
+        async for event in stream._raw_stream:
             for item in processor.process_event(event):
                 yield item
     yield processor.raw_message_chunk()

mirascope/llm/clients/anthropic/_utils/encode.py

@@ -0,0 +1,243 @@
+"""Anthropic message encoding and request preparation."""
+
+import json
+from collections.abc import Sequence
+from functools import lru_cache
+from typing import Literal, TypedDict, cast
+from typing_extensions import Required
+
+from anthropic import Omit, types as anthropic_types
+
+from ....content import ContentPart, ImageMimeType
+from ....exceptions import FeatureNotSupportedError, FormattingModeNotSupportedError
+from ....formatting import (
+    Format,
+    FormattableT,
+    _utils as _formatting_utils,
+    resolve_format,
+)
+from ....messages import AssistantMessage, Message, UserMessage
+from ....tools import FORMAT_TOOL_NAME, BaseToolkit, ToolSchema
+from ...base import Params, _utils as _base_utils
+from ..model_ids import AnthropicModelId
+
+DEFAULT_MAX_TOKENS = 16000
+
+AnthropicImageMimeType = Literal["image/jpeg", "image/png", "image/gif", "image/webp"]
+
+
+def encode_image_mime_type(
+    mime_type: ImageMimeType,
+) -> AnthropicImageMimeType:
+    """Convert an ImageMimeType into anthropic supported mime type"""
+    if mime_type in ("image/jpeg", "image/png", "image/gif", "image/webp"):
+        return mime_type
+    raise FeatureNotSupportedError(
+        feature=f"Image with mime_type: {mime_type}", provider="anthropic"
+    )  # pragma: no cover
+
+
+class MessageCreateKwargs(TypedDict, total=False):
+    """Kwargs for Anthropic Message.create method."""
+
+    model: Required[str]
+    max_tokens: Required[int]
+    messages: Sequence[anthropic_types.MessageParam]
+    system: str | Omit
+    tools: Sequence[anthropic_types.ToolParam] | Omit
+    tool_choice: anthropic_types.ToolChoiceParam | Omit
+    temperature: float | Omit
+    top_p: float | Omit
+    top_k: int | Omit
+    stop_sequences: list[str] | Omit
+    thinking: anthropic_types.ThinkingConfigParam | Omit
+
+
+def _encode_content(
+    content: Sequence[ContentPart], encode_thoughts: bool
+) -> str | Sequence[anthropic_types.ContentBlockParam]:
+    """Convert mirascope content to Anthropic content format."""
+
+    if len(content) == 1 and content[0].type == "text":
+        return content[0].text
+
+    blocks: list[anthropic_types.ContentBlockParam] = []
+
+    for part in content:
+        if part.type == "text":
+            blocks.append(anthropic_types.TextBlockParam(type="text", text=part.text))
+        elif part.type == "image":
+            source: (
+                anthropic_types.Base64ImageSourceParam
+                | anthropic_types.URLImageSourceParam
+            )
+            if part.source.type == "base64_image_source":
+                source = anthropic_types.Base64ImageSourceParam(
+                    type="base64",
+                    media_type=encode_image_mime_type(part.source.mime_type),
+                    data=part.source.data,
+                )
+            else:  # url_image_source
+                source = anthropic_types.URLImageSourceParam(
+                    type="url",
+                    url=part.source.url,
+                )
+            blocks.append(anthropic_types.ImageBlockParam(type="image", source=source))
+        elif part.type == "audio":
+            raise FeatureNotSupportedError(
+                "audio input",
+                "anthropic",
+                message="Anthropic does not support audio inputs.",
+            )
+        elif part.type == "tool_output":
+            blocks.append(
+                anthropic_types.ToolResultBlockParam(
+                    type="tool_result",
+                    tool_use_id=part.id,
+                    content=str(part.value),
+                )
+            )
+        elif part.type == "tool_call":
+            blocks.append(
+                anthropic_types.ToolUseBlockParam(
+                    type="tool_use",
+                    id=part.id,
+                    name=part.name,
+                    input=json.loads(part.args),
+                )
+            )
+        elif part.type == "thought":
+            if encode_thoughts:
+                blocks.append(
+                    anthropic_types.TextBlockParam(
+                        type="text", text="**Thinking:** " + part.thought
+                    )
+                )
+        else:
+            raise NotImplementedError(f"Unsupported content type: {part.type}")
+
+    return blocks
+
+
+def _encode_message(
+    message: UserMessage | AssistantMessage,
+    model_id: AnthropicModelId,
+    encode_thoughts: bool,
+) -> anthropic_types.MessageParam:
+    """Convert user or assistant `Message`s to Anthropic `MessageParam` format.
+
+    Args:
+        messages: A Sequence containing `UserMessage`s or `AssistantMessage`s
+        model_id: The Anthropic model ID being used
+
+    Returns:
+        A Sequence of converted Anthropic `MessageParam`
+    """
+
+    if (
+        message.role == "assistant"
+        and message.provider == "anthropic"
+        and message.model_id == model_id
+        and message.raw_message
+        and not encode_thoughts
+    ):
+        return cast(anthropic_types.MessageParam, message.raw_message)
+    return {
+        "role": message.role,
+        "content": _encode_content(message.content, encode_thoughts),
+    }
+
+
+@lru_cache(maxsize=128)
+def _convert_tool_to_tool_param(tool: ToolSchema) -> anthropic_types.ToolParam:
+    """Convert a single Mirascope tool to Anthropic tool format with caching."""
+    schema_dict = tool.parameters.model_dump(by_alias=True, exclude_none=True)
+    schema_dict["type"] = "object"
+    return anthropic_types.ToolParam(
+        name=tool.name,
+        description=tool.description,
+        input_schema=schema_dict,
+    )
+
+
+def encode_request(
+    *,
+    model_id: AnthropicModelId,
+    messages: Sequence[Message],
+    tools: Sequence[ToolSchema] | BaseToolkit | None,
+    format: type[FormattableT] | Format[FormattableT] | None,
+    params: Params,
+) -> tuple[Sequence[Message], Format[FormattableT] | None, MessageCreateKwargs]:
+    """Prepares a request for the `Anthropic.messages.create` method."""
+    kwargs: MessageCreateKwargs = MessageCreateKwargs(
+        {
+            "model": model_id,
+            "max_tokens": DEFAULT_MAX_TOKENS,
+        }
+    )
+    encode_thoughts = False
+
+    with _base_utils.ensure_all_params_accessed(
+        params=params, provider="anthropic", unsupported_params=["seed"]
+    ) as param_accessor:
+        if param_accessor.temperature is not None:
+            kwargs["temperature"] = param_accessor.temperature
+        if param_accessor.max_tokens is not None:
+            kwargs["max_tokens"] = param_accessor.max_tokens
+        if param_accessor.top_p is not None:
+            kwargs["top_p"] = param_accessor.top_p
+        if param_accessor.top_k is not None:
+            kwargs["top_k"] = param_accessor.top_k
+        if param_accessor.stop_sequences is not None:
+            kwargs["stop_sequences"] = param_accessor.stop_sequences
+        if param_accessor.thinking is not None:
+            if param_accessor.thinking:
+                # Set budget to 50% of max_tokens with minimum of 1024
+                budget_tokens = max(1024, kwargs["max_tokens"] // 2)
+                kwargs["thinking"] = {"type": "enabled", "budget_tokens": budget_tokens}
+            else:
+                kwargs["thinking"] = {"type": "disabled"}
+        if param_accessor.encode_thoughts_as_text:
+            encode_thoughts = True
+
+    tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
+    anthropic_tools = [_convert_tool_to_tool_param(tool) for tool in tools]
+    format = resolve_format(format, default_mode="tool")
+    if format is not None:
+        if format.mode == "strict":
+            raise FormattingModeNotSupportedError(
+                formatting_mode="strict", provider="anthropic"
+            )
+        elif format.mode == "tool":
+            format_tool_schema = _formatting_utils.create_tool_schema(format)
+            anthropic_tools.append(_convert_tool_to_tool_param(format_tool_schema))
+            if tools:
+                kwargs["tool_choice"] = {"type": "any"}
+            else:
+                kwargs["tool_choice"] = {
+                    "type": "tool",
+                    "name": FORMAT_TOOL_NAME,
+                    "disable_parallel_tool_use": True,
+                }
+
+        if format.formatting_instructions:
+            messages = _base_utils.add_system_instructions(
+                messages, format.formatting_instructions
+            )
+
+    if anthropic_tools:
+        kwargs["tools"] = anthropic_tools
+
+    system_message_content, remaining_messages = _base_utils.extract_system_message(
+        messages
+    )
+
+    kwargs["messages"] = [
+        _encode_message(remaining_message, model_id, encode_thoughts)
+        for remaining_message in remaining_messages
+    ]
+
+    if system_message_content:
+        kwargs["system"] = system_message_content
+
+    return messages, format, kwargs