mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/formatting/primitives.py

@@ -0,0 +1,192 @@
+"""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/formatting/types.py

@@ -1,18 +1,26 @@
 """Type for the formatting module."""
 
-from dataclasses import dataclass
-from typing import Generic, Literal, Protocol, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
 from typing_extensions import TypeVar
 
 from pydantic import BaseModel
 
-# TODO: Support primitive types (e.g. `format=list[Book]`)
-FormattableT = TypeVar("FormattableT", bound=BaseModel | None, default=None)
+from .primitives import PrimitiveType
+
+FormattableT = TypeVar(
+    "FormattableT", bound=BaseModel | PrimitiveType | None, default=None
+)
 """Type variable for structured response format types.
 
 This TypeVar represents the type of structured output format that LLM responses
-can be parsed into, or None if no format is specified. 
-If format is specified, it must extend Pydantic BaseModel. 
+can be parsed into, or None if no format is specified.
+
+Supported format types:
+- Pydantic BaseModel subclasses
+- Primitive types: str, int, float, bool, bytes, list, set, tuple, dict
+- Generic collections: list[Book], dict[str, int], etc.
+- Union, Literal, and Annotated types
+- Enum types
 """
 
 
@@ -20,15 +28,14 @@ FormattingMode = Literal[
     "strict",
     "json",
     "tool",
+    "parser",
 ]
 """Available modes for response format generation.
 
 - "strict": Use strict mode for structured outputs, asking the LLM to strictly adhere
     to a given JSON schema. Not all providers or models support it, and may not be
-    compatible with tool calling. When making a call using this mode, an 
-    `llm.FormattingModeNotSupportedError` error may be raised (if "strict" mode is wholly
-    unsupported), or an `llm.FeatureNotSupportedError` may be raised (if trying to use 
-    strict along with tools and that is unsupported).
+    compatible with tool calling. When making a call using this mode, an
+    `llm.FeatureNotSupportedError` error may be raised if the mode is unsupported.
 
 - "json": Use JSON mode for structured outputs. In contrast to strict mode, we ask the
     LLM to output JSON as text, though without guarantees that the model will output
@@ -43,64 +50,14 @@ FormattingMode = Literal[
     content (abstracting over the tool call). If other tools are present, they will
     be handled as regular tool calls.
 
+- "parser": Use custom parsing with formatting instructions. No schema generation or
+    structured output features. The LLM receives only formatting instructions and the
+    response is parsed using a custom parser function created with `@llm.output_parser`.
+
 Note: When `llm.format` is not used, the provider will automatically choose a mode at call time.
 """
 
 
-@dataclass(kw_only=True)
-class Format(Generic[FormattableT]):
-    """Class representing a structured output format for LLM responses.
-
-    A `Format` contains metadata needed to describe a structured output type
-    to the LLM, including the expected schema. This class is not instantiated directly,
-    but is created by calling `llm.format`, or is automatically generated by LLM
-    providers when a `Formattable` is passed to a call method.
-
-    Example:
-
-      ```python
-      from mirascope import llm
-
-      class Book:
-          title: str
-          author: str
-
-      print(llm.format(Book, mode="tool"))
-      ```
-    """
-
-    name: str
-    """The name of the response format."""
-
-    description: str | None
-    """A description of the response format, if available."""
-
-    schema: dict[str, object]
-    """JSON schema representation of the structured output format."""
-
-    mode: FormattingMode
-    """The decorator-provided mode of the response format. 
-    
-    Determines how the LLM call may be modified in order to extract the expected format.
-    """
-
-    formatting_instructions: str | None
-    """The formatting instructions that will be added to the LLM system prompt.
-
-    If the format type has a `formatting_instructions` class method, the output of that
-    call will be used for instructions. Otherwise, instructions may be auto-generated
-    based on the formatting mode.
-    """
-
-    formattable: type[FormattableT]
-    """The `Formattable` type that this `Format` describes.
-    
-    While the `FormattbleT` typevar allows for `None`, a `Format` will never be
-    constructed when the `FormattableT` is `None`, so you may treat this as 
-    a `RequiredFormattableT` in practice.
-    """
-
-
 @runtime_checkable
 class HasFormattingInstructions(Protocol):
     """Protocol for classes that have been decorated with `@format()`."""

mirascope/llm/mcp/__init__.py

@@ -1,5 +1,5 @@
 """MCP compatibility module."""
 
-from .client import MCPClient, sse_client, stdio_client, streamablehttp_client
+from .mcp_client import MCPClient, sse_client, stdio_client, streamable_http_client
 
-__all__ = ["MCPClient", "sse_client", "stdio_client", "streamablehttp_client"]
+__all__ = ["MCPClient", "sse_client", "stdio_client", "streamable_http_client"]

mirascope/llm/mcp/mcp_client.py

@@ -0,0 +1,130 @@
+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/__init__.py

@@ -5,6 +5,7 @@ as a unified `Message` class with different roles (system, user, assistant) and
 content arrays that can include text, images, audio, documents, and tool interactions.
 """
 
+from ._utils import is_messages, promote_to_messages
 from .message import (
     AssistantContent,
     AssistantMessage,
@@ -27,6 +28,8 @@ __all__ = [
     "UserContent",
     "UserMessage",
     "assistant",
+    "is_messages",
+    "promote_to_messages",
     "system",
     "user",
 ]

mirascope/llm/messages/_utils.py

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

@@ -7,9 +7,14 @@ creates a default one.
 """
 
 from .models import Model, model, model_from_context, use_model
+from .params import Params
+from .thinking_config import ThinkingConfig, ThinkingLevel
 
 __all__ = [
     "Model",
+    "Params",
+    "ThinkingConfig",
+    "ThinkingLevel",
     "model",
     "model_from_context",
     "use_model",