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

mirascope/llm/prompts/__init__.py

@@ -0,0 +1,33 @@
+"""The prompt templates module for LLM interactions.
+
+This module defines the prompt templates used in LLM interactions, which are written as
+python functions.
+"""
+
+from . import _utils
+from .decorator import prompt
+from .protocols import (
+    AsyncContextPrompt,
+    AsyncContextPromptable,
+    AsyncPrompt,
+    AsyncPromptable,
+    ContextPrompt,
+    ContextPromptable,
+    Prompt,
+    Promptable,
+    PromptT,
+)
+
+__all__ = [
+    "AsyncContextPrompt",
+    "AsyncContextPromptable",
+    "AsyncPrompt",
+    "AsyncPromptable",
+    "ContextPrompt",
+    "ContextPromptable",
+    "Prompt",
+    "PromptT",
+    "Promptable",
+    "_utils",
+    "prompt",
+]

mirascope/llm/prompts/_utils.py

@@ -0,0 +1,60 @@
+import inspect
+from typing_extensions import TypeIs
+
+from ..context import DepsT, _utils as _context_utils
+from ..messages import (
+    AssistantMessage,
+    Message,
+    SystemMessage,
+    UserContent,
+    UserMessage,
+    user,
+)
+from ..types import P
+from .protocols import (
+    AsyncContextPromptable,
+    AsyncPromptable,
+    ContextPromptable,
+    Promptable,
+)
+
+
+def is_messages(
+    messages_or_content: list[Message] | UserContent,
+) -> TypeIs[list[Message]]:
+    if not messages_or_content:
+        raise ValueError("Prompt returned empty content")
+    return isinstance(messages_or_content, list) and isinstance(
+        messages_or_content[0], SystemMessage | UserMessage | AssistantMessage
+    )
+
+
+def promote_to_messages(result: list[Message] | UserContent) -> list[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 UserContent, wraps it in a single user message.
+    """
+    if is_messages(result):
+        return result
+    return [user(result)]
+
+
+def is_context_promptable(
+    fn: ContextPromptable[P, DepsT]
+    | AsyncContextPromptable[P, DepsT]
+    | Promptable[P]
+    | AsyncPromptable[P],
+) -> TypeIs[ContextPromptable[P, DepsT] | AsyncContextPromptable[P, DepsT]]:
+    """Type guard to check if a function is a context promptable function."""
+    return _context_utils.first_param_is_context(fn)
+
+
+def is_async_promptable(
+    fn: ContextPromptable[P, DepsT]
+    | AsyncContextPromptable[P, DepsT]
+    | Promptable[P]
+    | AsyncPromptable[P],
+) -> TypeIs[AsyncPromptable[P] | AsyncContextPromptable[P, DepsT]]:
+    """Type guard to check if a function is an async promptable function."""
+    return inspect.iscoroutinefunction(fn)

mirascope/llm/prompts/decorator.py

@@ -0,0 +1,286 @@
+"""The `prompt` decorator for writing messages as string templates."""
+
+from typing import overload
+
+from ..context import Context, DepsT
+from ..messages import (
+    Message,
+)
+from ..types import P
+from . import _utils
+from .protocols import (
+    AsyncContextPrompt,
+    AsyncContextPromptable,
+    AsyncPrompt,
+    AsyncPromptable,
+    ContextPrompt,
+    ContextPromptable,
+    Prompt,
+    Promptable,
+)
+
+
+class PromptDecorator:
+    """Protocol for the `prompt` decorator when used without a template."""
+
+    @overload
+    def __call__(
+        self,
+        fn: ContextPromptable[P, DepsT],
+    ) -> ContextPrompt[P, DepsT]:
+        """Decorator for creating context prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: AsyncContextPromptable[P, DepsT],
+    ) -> AsyncContextPrompt[P, DepsT]:
+        """Decorator for creating async context prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: Promptable[P],
+    ) -> Prompt[P]:
+        """Decorator for creating prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: AsyncPromptable[P],
+    ) -> AsyncPrompt[P]:
+        """Decorator for creating async prompts."""
+        ...
+
+    def __call__(
+        self,
+        fn: ContextPromptable[P, DepsT]
+        | AsyncContextPromptable[P, DepsT]
+        | Promptable[P]
+        | AsyncPromptable[P],
+    ) -> (
+        Prompt[P]
+        | AsyncPrompt[P]
+        | ContextPrompt[P, DepsT]
+        | AsyncContextPrompt[P, DepsT]
+    ):
+        """Decorator for creating a prompt."""
+        is_context = _utils.is_context_promptable(fn)
+        is_async = _utils.is_async_promptable(fn)
+
+        # NOTE: unused `fn` expressions work around a Pyright bug
+        # TODO: Clean this up once the following Pyright bug is addressed:
+        # https://github.com/microsoft/pyright/issues/10951
+        if is_context and is_async:
+            fn  # pyright: ignore[reportUnusedExpression]  # noqa: B018
+
+            async def async_context_prompt(
+                ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+            ) -> list[Message]:
+                result = await fn(ctx, *args, **kwargs)
+                return _utils.promote_to_messages(result)
+
+            return async_context_prompt
+        elif is_context:
+            fn  # pyright: ignore[reportUnusedExpression]  # noqa: B018
+
+            def context_prompt(
+                ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+            ) -> list[Message]:
+                result = fn(ctx, *args, **kwargs)
+                return _utils.promote_to_messages(result)
+
+            return context_prompt
+        elif is_async:
+            fn  # pyright: ignore[reportUnusedExpression]  # noqa: B018
+
+            async def async_prompt(*args: P.args, **kwargs: P.kwargs) -> list[Message]:
+                result = await fn(*args, **kwargs)
+                return _utils.promote_to_messages(result)
+
+            return async_prompt
+        else:
+            fn  # pyright: ignore[reportUnusedExpression]  # noqa: B018
+
+            def prompt(*args: P.args, **kwargs: P.kwargs) -> list[Message]:
+                result = fn(*args, **kwargs)
+                return _utils.promote_to_messages(result)
+
+            return prompt
+
+
+class PromptTemplateDecorator:
+    """Protocol for the `prompt` decorator when used with a template."""
+
+    @overload
+    def __call__(
+        self,
+        fn: ContextPromptable[P, DepsT],
+    ) -> ContextPrompt[P, DepsT]:
+        """Decorator for creating context prompts from template functions."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: AsyncContextPromptable[P, DepsT],
+    ) -> AsyncContextPrompt[P, DepsT]:
+        """Decorator for creating async context prompts from template functions."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: Promptable[P],
+    ) -> Prompt[P]:
+        """Decorator for creating prompts from template functions."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: AsyncPromptable[P],
+    ) -> AsyncPrompt[P]:
+        """Decorator for creating async prompts from template functions."""
+        ...
+
+    def __call__(
+        self,
+        fn: ContextPromptable[P, DepsT]
+        | AsyncContextPromptable[P, DepsT]
+        | Promptable[P]
+        | AsyncPromptable[P],
+    ) -> (
+        Prompt[P]
+        | AsyncPrompt[P]
+        | ContextPrompt[P, DepsT]
+        | AsyncContextPrompt[P, DepsT]
+    ):
+        """Decorator for creating a prompt from a template function."""
+        raise NotImplementedError()
+
+
+@overload
+def prompt(
+    __fn: ContextPromptable[P, DepsT],
+) -> ContextPrompt[P, DepsT]:
+    """Create a decorator for sync ContextPrompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    __fn: AsyncContextPromptable[P, DepsT],
+) -> AsyncContextPrompt[P, DepsT]:
+    """Create a decorator for async ContextPrompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    __fn: Promptable[P],
+) -> Prompt[P]:
+    """Create a decorator for sync Prompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    __fn: AsyncPromptable[P],
+) -> AsyncPrompt[P]:
+    """Create a decorator for async Prompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    *,
+    template: None = None,
+) -> PromptDecorator:
+    """Create a decorator for Prompt functions (no template)"""
+
+
+@overload
+def prompt(
+    *,
+    template: str,
+) -> PromptTemplateDecorator:
+    """Create a decorator for template functions."""
+    ...
+
+
+def prompt(
+    __fn: ContextPromptable[P, DepsT]
+    | AsyncContextPromptable[P, DepsT]
+    | Promptable[P]
+    | AsyncPromptable[P]
+    | None = None,
+    *,
+    template: str | None = None,
+) -> (
+    ContextPrompt[P, DepsT]
+    | AsyncContextPrompt[P, DepsT]
+    | Prompt[P]
+    | AsyncPrompt[P]
+    | PromptDecorator
+    | PromptTemplateDecorator
+):
+    """Prompt decorator for turning functions (or "Prompts") into prompts.
+
+    This decorator transforms a function into a Prompt, i.e. a function that
+    returns `list[llm.Message]`. Its behavior depends on whether it's called with a spec
+    string.
+
+    If the first parameter is named 'ctx' or typed as `llm.Context[T]`, it creates
+    a ContextPrompt. Otherwise, it creates a regular Prompt.
+
+    With a template string, it returns a PromptTemplateDecorator, in which case it uses
+    the provided template to decorate an function with an empty body, and uses arguments
+    to the function for variable substitution in the template. The resulting PromptTemplate
+    returns messages based on the template.
+
+    Without a template string, it returns a PromptFunctionalDecorator, which
+    transforms a Prompt (a function returning either message content, or messages) into
+    a PromptTemplate. The resulting prompt template either promotes the content into a
+    list containing a single user message, or passes along the messages returned by the
+    decorated function.
+
+    Args:
+        template: A string template with placeholders using `{{ variable_name }}`
+            and optional role markers like [SYSTEM], [USER], and [ASSISTANT].
+
+    Returns:
+        A PromptTemplateDecorator or PromptFunctionalDecorator that converts
+            the decorated function into a prompt.
+
+    Spec substitution rules:
+    - [USER], [ASSISTANT], [SYSTEM] demarcate the start of a new message with that role
+    - [MESSAGES] indicates the next variable contains a list of messages to include
+    - `{{ variable }}` injects the variable as a string, unless annotated
+    - Annotations: `{{ variable:annotation }}` where annotation is one of:
+        image, images, audio, audios, document, documents
+    - Single content annotations (image, audio, document) expect a file path,
+        URL, base64 string, or bytes, which becomes a content part with inferred mime-type
+    - Multiple content annotations (images, audios, documents) expect a list
+        of strings or bytes, each becoming a content part with inferred mime-type
+
+    Examples:
+        ```python
+        @llm.prompt
+        def answer_question(question: str) -> str:
+            return f"Answer this question: {question}"
+
+        @llm.prompt
+        def answer_with_context(ctx: llm.Context[str], question: str) -> str:
+            return f"Using context {ctx.deps}, answer: {question}"
+        ```
+    """  # TODO(docs): Update this docstring
+    if template:
+        raise NotImplementedError()
+    decorator = PromptDecorator()
+    if __fn is None:
+        return decorator
+    return decorator(__fn)

mirascope/llm/prompts/protocols.py

@@ -0,0 +1,99 @@
+"""Types for prompt functions."""
+
+from typing import Protocol, TypeVar
+
+from ..context import Context, DepsT
+from ..messages import Message, UserContent
+from ..types import P
+
+PromptT = TypeVar(
+    "PromptT", bound="Prompt | AsyncPrompt | ContextPrompt | AsyncContextPrompt"
+)
+"""Type variable for prompt types.
+
+This type var represents a resolved prompt, i.e. one that returns a list of messages.
+"""
+
+
+class Prompt(Protocol[P]):
+    """Protocol for a `Prompt`, which returns `list[Message]`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> list[Message]: ...
+
+
+class Promptable(Protocol[P]):
+    """Protocol for a `Promptable` that returns `UserContent` or `list[Message]`.
+
+    May be be converted by the `prompt` decorator into a `Prompt`.
+    """
+
+    def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> UserContent | list[Message]: ...
+
+
+class AsyncPrompt(Protocol[P]):
+    """Protocol for an `AsyncPrompt`, which returns `list[Message]`."""
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> list[Message]: ...
+
+
+class AsyncPromptable(Protocol[P]):
+    """Protocol for an `AsyncPromptable` that returns `UserContent` or `list[Message]`.
+
+    May be converted by the `prompt` decorator into an `AsyncPrompt`.
+    """
+
+    async def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> UserContent | list[Message]: ...
+
+
+class ContextPrompt(Protocol[P, DepsT]):
+    """Protocol for a `ContextPrompt`, which returns `list[Message]`."""
+
+    def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> list[Message]: ...
+
+
+class ContextPromptable(Protocol[P, DepsT]):
+    """Protocol for a `ContextPromptable` that returns `UserContent` or `list[Message]`.
+
+    May be converted by the `prompt` decorator into a `ContextPrompt`.
+    """
+
+    def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> UserContent | list[Message]: ...
+
+
+class AsyncContextPrompt(Protocol[P, DepsT]):
+    """Protocol for an `AsyncContextPrompt`, which returns `list[Message]`."""
+
+    async def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> list[Message]: ...
+
+
+class AsyncContextPromptable(Protocol[P, DepsT]):
+    """Protocol for an `AsyncContextPromptable` that returns `UserContent` or `list[Message]`.
+
+    May be converted by the `prompt` decorator into an `AsyncContextPrompt`.
+    """
+
+    async def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> UserContent | list[Message]: ...

mirascope/llm/responses/__init__.py

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

mirascope/llm/responses/_utils.py

@@ -0,0 +1,56 @@
+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:
+        ValueError: If no serialized json object string was found.
+
+    Returns:
+        The extracted serialized JSON string
+    """
+    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:
+        raise ValueError("Could not extract json: no opening `{`")
+
+    # Find the matching closing brace
+    brace_count = 0
+    in_string = False
+    escaped = False
+
+    for i, char in enumerate(text[json_start:], json_start):
+        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 text[json_start : i + 1]
+
+    raise ValueError("Could not extract json: no closing `}`")

mirascope/llm/responses/base_response.py

@@ -0,0 +1,91 @@
+"""Shared base of Response and AsyncResponse."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+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
+
+if TYPE_CHECKING:
+    from ..clients import ModelId, Params, Provider
+
+
+class BaseResponse(RootResponse[ToolkitT, FormattableT]):
+    """The response generated by an LLM."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider: "Provider",
+        model_id: "ModelId",
+        params: "Params",
+        toolkit: ToolkitT,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+    ) -> None:
+        """Initialize a Response.
+
+        Args:
+            raw: The raw response from the LLM.
+            provider: The provider name (e.g. "anthropic", "openai:completions").
+            model_id: The model identifier that generated the response.
+            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.
+        """
+        self.raw = raw
+        self.provider = provider
+        self.model_id = model_id
+        self.params = params
+        self.toolkit = toolkit
+        self.finish_reason = finish_reason
+        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=assistant_message.provider,
+                model_id=assistant_message.model_id,
+                raw_message=assistant_message.raw_message,
+            )
+        self.messages = list(input_messages) + [assistant_message]