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

mirascope/llm/prompts/__init__.py

@@ -5,30 +5,29 @@ python functions.
 """
 
 from . import _utils
-from .decorator import PromptDecorator, prompt
-from .prompts import (
+from .decorator import prompt
+from .protocols import (
     AsyncContextPrompt,
+    AsyncContextPromptable,
     AsyncPrompt,
+    AsyncPromptable,
     ContextPrompt,
+    ContextPromptable,
     Prompt,
-)
-from .protocols import (
-    AsyncContextMessageTemplate,
-    AsyncMessageTemplate,
-    ContextMessageTemplate,
-    MessageTemplate,
+    Promptable,
+    PromptT,
 )
 
 __all__ = [
-    "AsyncContextMessageTemplate",
     "AsyncContextPrompt",
-    "AsyncMessageTemplate",
+    "AsyncContextPromptable",
     "AsyncPrompt",
-    "ContextMessageTemplate",
+    "AsyncPromptable",
     "ContextPrompt",
-    "MessageTemplate",
+    "ContextPromptable",
     "Prompt",
-    "PromptDecorator",
+    "PromptT",
+    "Promptable",
     "_utils",
     "prompt",
 ]

mirascope/llm/prompts/_utils.py

@@ -2,30 +2,59 @@ 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 (
-    AsyncContextMessageTemplate,
-    AsyncMessageTemplate,
-    ContextMessageTemplate,
-    MessageTemplate,
+    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: ContextMessageTemplate[P, DepsT]
-    | AsyncContextMessageTemplate[P, DepsT]
-    | MessageTemplate[P]
-    | AsyncMessageTemplate[P],
-) -> TypeIs[ContextMessageTemplate[P, DepsT] | AsyncContextMessageTemplate[P, DepsT]]:
+    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: ContextMessageTemplate[P, DepsT]
-    | AsyncContextMessageTemplate[P, DepsT]
-    | MessageTemplate[P]
-    | AsyncMessageTemplate[P],
-) -> TypeIs[AsyncMessageTemplate[P] | AsyncContextMessageTemplate[P, DepsT]]:
+    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

@@ -1,170 +1,196 @@
 """The `prompt` decorator for writing messages as string templates."""
 
-from collections.abc import Sequence
-from typing import Generic, cast, overload
-
-from ..context import DepsT
-from ..formatting import Format, FormattableT, OutputParser
-from ..tools import (
-    AsyncContextTool,
-    AsyncContextToolkit,
-    AsyncTool,
-    AsyncToolkit,
-    ContextTool,
-    ContextToolkit,
-    Tool,
-    Toolkit,
-    ToolT,
+from typing import overload
+
+from ..context import Context, DepsT
+from ..messages import (
+    Message,
 )
 from ..types import P
 from . import _utils
-from .prompts import (
+from .protocols import (
     AsyncContextPrompt,
+    AsyncContextPromptable,
     AsyncPrompt,
+    AsyncPromptable,
     ContextPrompt,
+    ContextPromptable,
     Prompt,
+    Promptable,
 )
-from .protocols import (
-    AsyncContextMessageTemplate,
-    AsyncMessageTemplate,
-    ContextMessageTemplate,
-    MessageTemplate,
-)
-
-
-class PromptDecorator(Generic[ToolT, FormattableT]):
-    """Decorator for converting a `MessageTemplate` into a `Prompt`.
-
-    Takes a raw prompt function that returns message content and wraps it with
-    tools and format support, creating a `Prompt` that can be called with a model.
-
-    The decorator automatically detects whether the function is async or context-aware
-    and creates the appropriate Prompt variant (Prompt, AsyncPrompt, ContextPrompt,
-    or AsyncContextPrompt).
-    """
-
-    tools: Sequence[ToolT] | None
-    """The tools that are included in the prompt, if any."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
-    """The structured output format off the prompt, if any."""
 
-    def __init__(
-        self,
-        tools: Sequence[ToolT] | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-    ) -> None:
-        """Initialize the decorator with optional tools and format."""
-        self.tools = tools
-        self.format = format
+class PromptDecorator:
+    """Protocol for the `prompt` decorator when used without a template."""
 
     @overload
     def __call__(
-        self: "PromptDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT]",
-        fn: AsyncContextMessageTemplate[P, DepsT],
-    ) -> AsyncContextPrompt[P, DepsT, FormattableT]:
-        """Decorator for creating async context prompts."""
+        self,
+        fn: ContextPromptable[P, DepsT],
+    ) -> ContextPrompt[P, DepsT]:
+        """Decorator for creating context prompts."""
         ...
 
     @overload
     def __call__(
-        self: "PromptDecorator[Tool | ContextTool[DepsT], FormattableT]",
-        fn: ContextMessageTemplate[P, DepsT],
-    ) -> ContextPrompt[P, DepsT, FormattableT]:
-        """Decorator for creating context prompts."""
+        self,
+        fn: AsyncContextPromptable[P, DepsT],
+    ) -> AsyncContextPrompt[P, DepsT]:
+        """Decorator for creating async context prompts."""
         ...
 
     @overload
     def __call__(
-        self: "PromptDecorator[AsyncTool, FormattableT]",
-        fn: AsyncMessageTemplate[P],
-    ) -> AsyncPrompt[P, FormattableT]:
-        """Decorator for creating async prompts."""
+        self,
+        fn: Promptable[P],
+    ) -> Prompt[P]:
+        """Decorator for creating prompts."""
         ...
 
     @overload
     def __call__(
-        self: "PromptDecorator[Tool, FormattableT]",
-        fn: MessageTemplate[P],
-    ) -> Prompt[P, FormattableT]:
-        """Decorator for creating prompts."""
+        self,
+        fn: AsyncPromptable[P],
+    ) -> AsyncPrompt[P]:
+        """Decorator for creating async prompts."""
         ...
 
     def __call__(
         self,
-        fn: ContextMessageTemplate[P, DepsT]
-        | AsyncContextMessageTemplate[P, DepsT]
-        | MessageTemplate[P]
-        | AsyncMessageTemplate[P],
+        fn: ContextPromptable[P, DepsT]
+        | AsyncContextPromptable[P, DepsT]
+        | Promptable[P]
+        | AsyncPromptable[P],
     ) -> (
-        Prompt[P, FormattableT]
-        | AsyncPrompt[P, FormattableT]
-        | ContextPrompt[P, DepsT, FormattableT]
-        | AsyncContextPrompt[P, DepsT, FormattableT]
+        Prompt[P]
+        | AsyncPrompt[P]
+        | ContextPrompt[P, DepsT]
+        | AsyncContextPrompt[P, DepsT]
     ):
-        """Decorator for creating a prompt with tools and format."""
+        """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:
-            tools = cast(
-                Sequence[AsyncTool | AsyncContextTool[DepsT]] | None, self.tools
-            )
-            return AsyncContextPrompt(
-                fn=fn,
-                toolkit=AsyncContextToolkit(tools=tools),
-                format=self.format,
-            )
+            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:
-            tools = cast(Sequence[Tool | ContextTool[DepsT]] | None, self.tools)
-            return ContextPrompt(
-                fn=fn,
-                toolkit=ContextToolkit(tools=tools),
-                format=self.format,
-            )
+            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:
-            tools = cast(Sequence[AsyncTool] | None, self.tools)
-            return AsyncPrompt(
-                fn=fn, toolkit=AsyncToolkit(tools=tools), format=self.format
-            )
+            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:
-            tools = cast(Sequence[Tool] | None, self.tools)
-            return Prompt(fn=fn, toolkit=Toolkit(tools=tools), format=self.format)
+            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(  # pyright: ignore[reportOverlappingOverload]
-    __fn: ContextMessageTemplate[P, DepsT],
-) -> ContextPrompt[P, DepsT, None]:
+def prompt(
+    __fn: ContextPromptable[P, DepsT],
+) -> ContextPrompt[P, DepsT]:
     """Create a decorator for sync ContextPrompt functions (no arguments)."""
     ...
 
 
 @overload
-def prompt(  # pyright: ignore[reportOverlappingOverload]
-    __fn: AsyncContextMessageTemplate[P, DepsT],
-) -> AsyncContextPrompt[P, DepsT, None]:
+def prompt(
+    __fn: AsyncContextPromptable[P, DepsT],
+) -> AsyncContextPrompt[P, DepsT]:
     """Create a decorator for async ContextPrompt functions (no arguments)."""
     ...
 
 
 @overload
 def prompt(
-    __fn: MessageTemplate[P],
-) -> Prompt[P, None]:
+    __fn: Promptable[P],
+) -> Prompt[P]:
     """Create a decorator for sync Prompt functions (no arguments)."""
     ...
 
 
 @overload
 def prompt(
-    __fn: AsyncMessageTemplate[P],
-) -> AsyncPrompt[P, None]:
+    __fn: AsyncPromptable[P],
+) -> AsyncPrompt[P]:
     """Create a decorator for async Prompt functions (no arguments)."""
     ...
 
@@ -172,55 +198,89 @@ def prompt(
 @overload
 def prompt(
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
-) -> PromptDecorator[ToolT, FormattableT]:
-    """Create a decorator for Prompt functions with tools and format"""
+    template: None = None,
+) -> PromptDecorator:
+    """Create a decorator for Prompt functions (no template)"""
 
 
+@overload
 def prompt(
-    __fn: AsyncContextMessageTemplate[P, DepsT]
-    | ContextMessageTemplate[P, DepsT]
-    | AsyncMessageTemplate[P]
-    | MessageTemplate[P]
-    | None = None,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
+    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,
 ) -> (
-    AsyncContextPrompt[P, DepsT, FormattableT]
-    | ContextPrompt[P, DepsT, FormattableT]
-    | AsyncPrompt[P, FormattableT]
-    | Prompt[P, FormattableT]
-    | PromptDecorator[ToolT, FormattableT]
+    ContextPrompt[P, DepsT]
+    | AsyncContextPrompt[P, DepsT]
+    | Prompt[P]
+    | AsyncPrompt[P]
+    | PromptDecorator
+    | PromptTemplateDecorator
 ):
-    """Decorates a `MessageTemplate` to create a `Prompt` callable with a model.
+    """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.
 
-    This decorator transforms a raw prompt function (that returns message content)
-    into a `Prompt` object that can be invoked with a model to generate LLM responses.
+    If the first parameter is named 'ctx' or typed as `llm.Context[T]`, it creates
+    a ContextPrompt. Otherwise, it creates a regular Prompt.
 
-    The decorator automatically detects the function type:
-    - If the first parameter is named `'ctx'` with type `llm.Context[T]`, creates a `ContextPrompt`
-    - If the function is async, creates an `AsyncPrompt` or `AsyncContextPrompt`
-    - Otherwise, 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:
-        __fn: The prompt function to decorate (optional, for decorator syntax without parens)
-        tools: Optional `Sequence` of tools to make available to the LLM
-        format: Optional response format class (`BaseModel`) or Format instance
+        template: A string template with placeholders using `{{ variable_name }}`
+            and optional role markers like [SYSTEM], [USER], and [ASSISTANT].
 
     Returns:
-        A `Prompt` variant (Prompt, AsyncPrompt, ContextPrompt, or AsyncContextPrompt)
-        or a `PromptDecorator` if called with arguments
-    """
-    decorator = PromptDecorator(tools=tools, format=format)
+        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
-    # TODO: See if we can do without the pyright: ignores here
-    return decorator(__fn)  # pyright: ignore[reportUnknownVariableType, reportCallIssue]
+    return decorator(__fn)

mirascope/llm/prompts/protocols.py

@@ -1,44 +1,69 @@
 """Types for prompt functions."""
 
-from collections.abc import Sequence
-from typing import Protocol
+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.
 
-class MessageTemplate(Protocol[P]):
-    """Protocol for a prompt function that returns `UserContent` or `Sequence[Message]`.
+This type var represents a resolved prompt, i.e. one that returns a list of messages.
+"""
 
-    A `MessageTemplate` is a raw function that returns prompt content. It can be
-    converted by the `llm.prompt` decorator into a `Prompt` (callable with a `Model`),
-    or by the `llm.call` decorator into a `Call` (`Prompt` + `Model`).
+
+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 | Sequence[Message]: ...
+    ) -> UserContent | list[Message]: ...
+
 
+class AsyncPrompt(Protocol[P]):
+    """Protocol for an `AsyncPrompt`, which returns `list[Message]`."""
 
-class AsyncMessageTemplate(Protocol[P]):
-    """Protocol for an async prompt function that returns `UserContent` or `Sequence[Message]`.
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> list[Message]: ...
 
-    An async `MessageTemplate` that can be converted by the `llm.prompt` decorator
-    into an `AsyncPrompt`, or by the `llm.call` decorator into an `AsyncCall`.
+
+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 | Sequence[Message]: ...
+    ) -> 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 ContextMessageTemplate(Protocol[P, DepsT]):
-    """Protocol for a context-aware prompt function that returns `UserContent` or `Sequence[Message]`.
+class ContextPromptable(Protocol[P, DepsT]):
+    """Protocol for a `ContextPromptable` that returns `UserContent` or `list[Message]`.
 
-    A `MessageTemplate` with a first parameter named `'ctx'` of type `Context[DepsT]`.
-    Can be converted by the `llm.prompt` decorator into a `ContextPrompt`, or by
-    the `llm.call` decorator into a `ContextCall`.
+    May be converted by the `prompt` decorator into a `ContextPrompt`.
     """
 
     def __call__(
@@ -46,15 +71,24 @@ class ContextMessageTemplate(Protocol[P, DepsT]):
         ctx: Context[DepsT],
         *args: P.args,
         **kwargs: P.kwargs,
-    ) -> UserContent | Sequence[Message]: ...
+    ) -> 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 AsyncContextMessageTemplate(Protocol[P, DepsT]):
-    """Protocol for an async context-aware prompt function that returns `UserContent` or `Sequence[Message]`.
+class AsyncContextPromptable(Protocol[P, DepsT]):
+    """Protocol for an `AsyncContextPromptable` that returns `UserContent` or `list[Message]`.
 
-    An async `MessageTemplate` with a first parameter named `'ctx'` of type `Context[DepsT]`.
-    Can be converted by the `llm.prompt` decorator into an `AsyncContextPrompt`, or by
-    the `llm.call` decorator into an `AsyncContextCall`.
+    May be converted by the `prompt` decorator into an `AsyncContextPrompt`.
     """
 
     async def __call__(
@@ -62,4 +96,4 @@ class AsyncContextMessageTemplate(Protocol[P, DepsT]):
         ctx: Context[DepsT],
         *args: P.args,
         **kwargs: P.kwargs,
-    ) -> UserContent | Sequence[Message]: ...
+    ) -> UserContent | list[Message]: ...