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

mirascope/llm/formatting/output_parser.py

@@ -1,178 +0,0 @@
-"""The `llm.output_parser` decorator for creating custom output parsers."""
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
-from typing_extensions import TypeIs
-
-if TYPE_CHECKING:
-    from ..responses import AnyResponse
-
-OutputT = TypeVar("OutputT")
-
-
-class OutputParser(Generic[OutputT]):
-    """Represents a custom output parser created with @llm.output_parser.
-
-    This class wraps a parsing function and stores formatting instructions.
-    It is created by the @llm.output_parser decorator and used as a format
-    argument in LLM calls.
-
-    Unlike BaseModel and primitive type formats that use structured outputs
-    (JSON schema, tools, strict mode), OutputParser works with raw text responses
-    and custom parsing logic.
-
-    Example:
-        ```python
-        @llm.output_parser(
-            formatting_instructions="Return XML: <book><title>...</title></book>"
-        )
-        def parse_book_xml(response: llm.AnyResponse) -> Book:
-            text = "".join(part.text for part in response.texts)
-            root = ET.fromstring(text)
-            return Book(title=root.find("title").text, ...)
-
-        @llm.call("openai/gpt-4o", format=parse_book_xml)
-        def recommend_book(genre: str):
-            return f"Recommend a {genre} book."
-
-        response = recommend_book("fantasy")
-        book = response.parse()  # Returns Book instance
-        ```
-    """
-
-    def __init__(
-        self,
-        func: Callable[["AnyResponse"], OutputT],
-        formatting_instructions: str,
-    ) -> None:
-        """Initialize the OutputParser.
-
-        Args:
-            func: The parsing function that takes a Response and returns parsed output.
-            formatting_instructions: Instructions for the LLM on how to format output.
-        """
-        self.func = func
-        self._formatting_instructions = formatting_instructions
-        self.__name__ = func.__name__
-        self.__doc__ = func.__doc__
-
-    def formatting_instructions(self) -> str:
-        """Return the formatting instructions for the LLM.
-
-        These instructions are added to the system prompt to guide the LLM
-        on how to format its output for parsing.
-
-        Returns:
-            The formatting instructions string.
-        """
-        return self._formatting_instructions
-
-    def __call__(self, response: "AnyResponse") -> OutputT:
-        """Parse the response using the wrapped function.
-
-        Args:
-            response: The response object from the LLM call.
-
-        Returns:
-            The parsed output of type OutputT.
-
-        Raises:
-            Any exception raised by the wrapped parsing function.
-        """
-        return self.func(response)
-
-
-def output_parser(
-    *,
-    formatting_instructions: str,
-) -> Callable[[Callable[["AnyResponse"], OutputT]], OutputParser[OutputT]]:
-    """Decorator to create an output parser for custom format parsing.
-
-    Use this decorator to create custom parsers for non-JSON formats like
-    XML, YAML, CSV, or any custom text structure. The decorated function
-    receives the full Response object and returns the parsed output.
-
-    This is the recommended way to handle custom output formats that don't
-    fit the JSON/BaseModel paradigm. The formatting instructions guide the
-    LLM on how to structure its output, and the parsing function extracts
-    the data you need.
-
-    Args:
-        formatting_instructions: Instructions for the LLM on how to format
-            the output. These will be added to the system prompt.
-
-    Returns:
-        Decorator that converts a function into an OutputParser.
-
-    Example:
-
-        XML parsing:
-        ```python
-        @llm.output_parser(
-            formatting_instructions='''
-            Return the book information in this XML structure:
-            <book>
-                <title>Book Title</title>
-                <author>Author Name</author>
-                <rating>5</rating>
-            </book>
-            '''
-        )
-        def parse_book_xml(response: llm.AnyResponse) -> Book:
-            import xml.etree.ElementTree as ET
-            text = "".join(part.text for part in response.texts)
-            root = ET.fromstring(text)
-            return Book(
-                title=root.find("title").text,
-                author=root.find("author").text,
-                rating=int(root.find("rating").text),
-            )
-        ```
-
-    Example:
-
-        CSV parsing:
-        ```python
-        @llm.output_parser(
-            formatting_instructions='''
-            Return book information as CSV format with header:
-            title,author,rating
-            Book 1,Author 1,5
-            Book 2,Author 2,4
-            '''
-        )
-        def parse_books_csv(response: llm.AnyResponse) -> list[Book]:
-            text = "".join(part.text for part in response.texts)
-            lines = text.strip().split('\\n')[1:]  # Skip header
-            return [
-                Book(
-                    title=line.split(',')[0].strip(),
-                    author=line.split(',')[1].strip(),
-                    rating=int(line.split(',')[2]),
-                )
-                for line in lines
-            ]
-        ```
-    """
-
-    def decorator(
-        func: Callable[["AnyResponse"], OutputT],
-    ) -> OutputParser[OutputT]:
-        return OutputParser(func, formatting_instructions)
-
-    return decorator
-
-
-def is_output_parser(obj: Any) -> TypeIs[OutputParser[Any]]:  # noqa: ANN401
-    """Check if an object is an OutputParser.
-
-    This is a type guard function that narrows the type of `obj` to
-    `OutputParser[Any, Any]` when it returns True.
-
-    Args:
-        obj: The object to check.
-
-    Returns:
-        True if the object is an OutputParser instance, False otherwise.
-    """
-    return isinstance(obj, OutputParser)

mirascope/llm/formatting/primitives.py

@@ -1,192 +0,0 @@
-"""Utilities for handling primitive types in formatting."""
-
-import inspect
-from enum import Enum
-from types import UnionType
-from typing import (
-    Annotated,
-    Any,
-    Literal,
-    Protocol,
-    TypeAlias,
-    Union,
-    cast,
-    get_args,
-    get_origin,
-)
-from typing_extensions import TypeIs
-
-from pydantic import create_model
-
-PrimitiveType: TypeAlias = (
-    str
-    | int
-    | float
-    | bool
-    | bytes
-    | list[Any]
-    | set[Any]
-    | tuple[Any, ...]
-    | dict[Any, Any]
-)
-"""Primitive types that can be used with format parameter.
-
-These types are automatically wrapped in a BaseModel for schema generation,
-then unwrapped after validation to return the primitive value.
-"""
-
-
-class PrimitiveWrapperModel(Protocol):
-    """Protocol for wrapper models with an output field."""
-
-    output: Any
-    model_fields: Any
-
-    def __init__(self, *, output: Any) -> None: ...  # noqa: ANN401
-
-    @classmethod
-    def model_json_schema(cls) -> dict[str, Any]: ...
-
-    @classmethod
-    def model_validate_json(cls, json_data: str) -> "PrimitiveWrapperModel": ...
-
-
-def is_primitive_type(
-    type_: Any,  # noqa: ANN401
-) -> TypeIs[type[PrimitiveType]]:
-    """Check if a type is a primitive type that needs wrapping.
-
-    Returns True for:
-    - Basic primitives: str, int, float, bool, bytes, list, set, tuple, dict
-    - Enum types
-    - Generic types with primitive origins: list[Book], dict[str, int]
-    - Literal types
-    - Union types (including Optional)
-    - Annotated types
-
-    Returns False for:
-    - BaseModel subclasses (already have model_json_schema)
-    - None/NoneType
-
-    Args:
-        type_: The type to check
-
-    Returns:
-        True if the type is a primitive that needs wrapping
-
-    Example:
-        >>> is_primitive_type(str)
-        True
-        >>> is_primitive_type(list[int])
-        True
-        >>> from pydantic import BaseModel
-        >>> class Book(BaseModel):
-        ...     title: str
-        >>> is_primitive_type(Book)
-        False
-    """
-    primitive_types: set[type[PrimitiveType]] = {
-        str,
-        int,
-        float,
-        bool,
-        bytes,
-        list,
-        set,
-        tuple,
-        dict,
-    }
-    special_types: set[Any] = {Annotated, Literal, Union, UnionType}
-
-    return (
-        (inspect.isclass(type_) and issubclass(type_, Enum))
-        or type_ in primitive_types
-        or get_origin(type_) in primitive_types.union(special_types)
-    )
-
-
-def _get_type_name(type_: Any) -> str:  # noqa: ANN401
-    """Extract a clean name from a type for use in model naming.
-
-    Handles Annotated types by extracting the underlying type,
-    and generates clean names for generic types.
-
-    Args:
-        type_: The type to extract a name from
-
-    Returns:
-        A clean string suitable for use in a Python class name
-
-    Example:
-        >>> _get_type_name(str)
-        'str'
-        >>> _get_type_name(list[int])
-        'list_int_'
-    """
-    # Import Annotated locally
-    # Check if this is an Annotated type
-    if get_origin(type_) in {Annotated}:
-        # For Annotated types, use the first arg (the actual type)
-        return _get_type_name(get_args(type_)[0])
-
-    # If the type has a __name__ attribute, use it
-    if hasattr(type_, "__name__"):
-        return type_.__name__
-
-    # For complex generics like list[Book], use string representation
-    type_str = str(type_)
-
-    # Clean up the string to make it a valid Python identifier
-    # Replace brackets and commas with underscores
-    clean = (
-        type_str.replace("[", "_")
-        .replace("]", "_")
-        .replace(", ", "_")
-        .replace(" ", "")
-        .replace("'", "")
-        .replace('"', "")
-    )
-
-    return clean
-
-
-def create_wrapper_model(
-    primitive_type: Any,  # noqa: ANN401
-) -> type[PrimitiveWrapperModel]:
-    """Create a wrapper BaseModel for a primitive type.
-
-    The wrapper has a single field called "output" containing the primitive value.
-    Uses Pydantic's create_model() to generate the wrapper dynamically.
-
-    Args:
-        primitive_type: The primitive type to wrap
-
-    Returns:
-        A dynamically created BaseModel with an "output" field
-
-    Example:
-        >>> wrapper = create_wrapper_model(str)
-        >>> instance = wrapper(output="hello")
-        >>> instance.output
-        'hello'
-
-        >>> from pydantic import BaseModel
-        >>> class Book(BaseModel):
-        ...     title: str
-        >>> wrapper = create_wrapper_model(list[Book])
-        >>> books = [Book(title="Test")]
-        >>> instance = wrapper(output=books)
-        >>> len(instance.output)
-        1
-    """
-    # Get a clean name for the wrapper class
-    type_name = _get_type_name(primitive_type)
-
-    # Create wrapper model with "output" field (required)
-    wrapper = create_model(
-        f"{type_name}Output",
-        __doc__=f"Wrapper for primitive type {type_name}",
-        output=(primitive_type, ...),  # ... means required
-    )
-
-    return cast(type[PrimitiveWrapperModel], wrapper)

mirascope/llm/mcp/mcp_client.py

@@ -1,130 +0,0 @@
-import contextlib
-from collections.abc import AsyncIterator
-from datetime import timedelta
-from typing import cast
-
-from mcp import ClientSession
-from mcp.client.sse import sse_client as mcp_sse_client
-from mcp.client.stdio import StdioServerParameters, stdio_client as mcp_stdio_client
-from mcp.client.streamable_http import (
-    streamable_http_client as mcp_streamable_http_client,
-)
-from mcp.types import CallToolResult, Tool as MCPTool
-
-from ..tools import AsyncTool
-from ..tools.tool_schema import ToolParameterSchema
-from ..types import Jsonable
-
-
-class MCPClient:
-    """Mirascope wrapper around a MCP ClientSession.
-
-    It provides a way to get MCP results that are pre-converted into Mirascope-friendly
-    types.
-
-    The underlying MCP ClientSession may be accessed by .session if needed.
-    """
-
-    def __init__(self, session: ClientSession) -> None:
-        self._session = session
-
-    @property
-    def session(self) -> ClientSession:
-        """Access the underlying MCP ClientSession if needed."""
-        return self._session
-
-    def _convert_mcp_tool_to_async_tool(self, mcp_tool: MCPTool) -> AsyncTool:
-        """Convert an MCP Tool to a Mirascope AsyncTool.
-
-        Args:
-            mcp_tool: The MCP tool to convert.
-
-        Returns:
-            An `AsyncTool` that wraps the MCP tool.
-        """
-
-        # Create an async function that calls the MCP tool
-        async def tool_fn(**kwargs: object) -> Jsonable:
-            tool_result: CallToolResult = await self._session.call_tool(
-                mcp_tool.name, kwargs
-            )
-            # Convert ContentBlock objects to JSON-serializable dicts
-            # Cast to Jsonable since model_dump() returns dict[str, Any]
-            return cast(
-                Jsonable, [content.model_dump() for content in tool_result.content]
-            )
-
-        # Convert MCP tool's inputSchema to Mirascope's ToolParameterSchema
-        input_schema = mcp_tool.inputSchema
-        parameters = ToolParameterSchema(
-            properties=input_schema.get("properties", {}),
-            required=input_schema.get("required", []),
-            additionalProperties=input_schema.get("additionalProperties", False),
-        )
-        if "$defs" in input_schema:
-            parameters.defs = input_schema["$defs"]
-
-        # Create the AsyncTool instance
-        return AsyncTool(
-            fn=tool_fn,
-            name=mcp_tool.name,
-            description=mcp_tool.description or mcp_tool.name,
-            parameters=parameters,
-            strict=False,
-        )
-
-    async def list_tools(self) -> list[AsyncTool]:
-        """List all tools available on the MCP server.
-
-        Returns:
-            A list of dynamically created `AsyncTool`s.
-        """
-        result = await self._session.list_tools()
-        return [self._convert_mcp_tool_to_async_tool(tool) for tool in result.tools]
-
-
-@contextlib.asynccontextmanager
-async def streamable_http_client(
-    url: str,
-) -> AsyncIterator[MCPClient]:  # pragma: no cover
-    """Create a Mirascope MCPClient using StreamableHTTP."""
-    # NOTE: If updating this function, unskip and manually run the TestTransportModes
-    # tests in test_mcp_client.py. (Skipped because they are flaky)
-    async with (
-        mcp_streamable_http_client(url) as (read, write, _),
-        ClientSession(read, write) as session,
-    ):
-        await session.initialize()
-        yield MCPClient(session)
-
-
-@contextlib.asynccontextmanager
-async def stdio_client(
-    server_parameters: StdioServerParameters,
-    name: str | None = None,
-) -> AsyncIterator[MCPClient]:
-    """Create a Mirascope MCPClient using stdio."""
-    async with (
-        mcp_stdio_client(server_parameters) as (read, write),
-        ClientSession(read, write) as session,
-    ):
-        await session.initialize()
-        yield MCPClient(session)
-
-
-@contextlib.asynccontextmanager
-async def sse_client(
-    url: str,
-    read_timeout_seconds: timedelta | None = None,
-) -> AsyncIterator[MCPClient]:  # pragma: no cover
-    """Create a Mirascope MCPClient using sse."""
-    # NOTE: If updating this function, unskip and manually run the TestTransportModes
-    # tests in test_mcp_client.py. (Skipped because they are flaky)
-    async with (
-        mcp_sse_client(url) as (read, write),
-        ClientSession(
-            read, write, read_timeout_seconds=read_timeout_seconds
-        ) as session,
-    ):
-        await session.initialize()
-        yield MCPClient(session)

mirascope/llm/messages/_utils.py

@@ -1,34 +0,0 @@
-"""Utility functions for message handling."""
-
-from collections.abc import Sequence
-from typing_extensions import TypeIs
-
-from .message import (
-    AssistantMessage,
-    Message,
-    SystemMessage,
-    UserContent,
-    UserMessage,
-    user,
-)
-
-
-def is_messages(
-    content: UserContent | Sequence[Message],
-) -> TypeIs[Sequence[Message]]:
-    if isinstance(content, list):
-        if not content:
-            raise ValueError("Empty array may not be used as message content")
-        return isinstance(content[0], SystemMessage | UserMessage | AssistantMessage)
-    return False
-
-
-def promote_to_messages(content: UserContent | Sequence[Message]) -> Sequence[Message]:
-    """Promote a prompt result to a list of messages.
-
-    If the result is already a list of Messages, returns it as-is.
-    If the result is str/UserContentPart/Sequence of content parts, wraps it in a user message.
-    """
-    if is_messages(content):
-        return content
-    return [user(content)]

mirascope/llm/models/thinking_config.py

@@ -1,61 +0,0 @@
-"""Configuration for extended reasoning/thinking in LLM responses."""
-
-from typing import Literal
-from typing_extensions import Required, TypedDict
-
-ThinkingLevel = Literal["none", "default", "minimal", "low", "medium", "high", "max"]
-"""Level of effort/reasoning to apply to thinking."""
-
-
-class ThinkingConfig(TypedDict, total=False):
-    """Configuration for extended reasoning/thinking in LLM responses.
-
-    Thinking is a process where the model spends additional tokens reasoning about
-    the prompt before generating a response. Providing any `ThinkingConfig` will enable
-    thinking (unless it is specifically disabled via level="minimal"). Depending on
-    the provider and model, thinking may always be active regardless of user settings.
-    """
-
-    level: Required[ThinkingLevel]
-    """Level of effort/reasoning to apply to thinking.
-
-    - none: Disable thinking entirely. Minimizes cost and latency.
-    - default: Use the provider's default
-    - minimal: Use the provider's lowest setting for reasoning
-    - medium: Use a moderate amount of reasoning tokens
-    - high: Allow extensive resources for thinking
-    - max: Uses as much thinking as allowed by the provider.
-
-    Mirascope makes a best effort to apply the chosen thinking level, but exact behavior
-    varies by provider and model. For example, some models may not support thinking,
-    while other models may not allow disabling it.
-    """
-
-    include_thoughts: bool
-    """Whether to include Thought content in the model output.
-
-    Depending on the model and provider, enabling include_thoughts to true may
-    request reasoning summaries (which are not the underlying reasoning tokens,
-    but a readable summary produced by another model), or it may be the original
-    reasoning tokens.
-
-    When include_thoughts is false, no summaries will be requested, and thoughts
-    will not be included in the output even if they were provided by the provider.
-
-    Defaults to false.
-    """
-
-    encode_thoughts_as_text: bool
-    """Re-encode Thought content as text for model consumption.
-
-    If `True`, when an `AssistantMessage` contains `Thoughts` and is passed back
-    to an LLM, those `Thoughts` will be encoded as `Text`, ensuring the assistant
-    can read its prior reasoning. This contrasts with provider defaults which may
-    ignore prior thoughts, particularly if tool calls are not involved.
-
-    When `True`, Mirascope will re-encode messages rather than reusing raw provider
-    response content, which may disable provider-specific optimizations like cached
-    reasoning tokens.
-
-    Defaults to `False` if unset.
-    """