mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/models/params.py

@@ -0,0 +1,72 @@
+"""Base parameters for LLM providers."""
+
+from typing import TypedDict
+
+from .thinking_config import ThinkingConfig
+
+
+class Params(TypedDict, total=False):
+    """Common parameters shared across LLM providers.
+
+    Note: Each provider may handle these parameters differently or not support them at all.
+    Please check provider-specific documentation for parameter support and behavior.
+    """
+
+    temperature: float
+    """Controls randomness in the output (0.0 to 1.0).
+
+    Lower temperatures are good for prompts that require a less open-ended or
+    creative response, while higher temperatures can lead to more diverse or
+    creative results.
+    """
+
+    max_tokens: int
+    """Maximum number of tokens to generate."""
+
+    top_p: float
+    """Nucleus sampling parameter (0.0 to 1.0).
+
+    Tokens are selected from the most to least probable until the sum of their
+    probabilities equals this value. Use a lower value for less random responses and a
+    higher value for more random responses.
+    """
+
+    top_k: int
+    """Limits token selection to the k most probable tokens (typically 1 to 100).
+
+    For each token selection step, the ``top_k`` tokens with the
+    highest probabilities are sampled. Then tokens are further filtered based
+    on ``top_p`` with the final token selected using temperature sampling. Use
+    a lower number for less random responses and a higher number for more
+    random responses.
+    """
+
+    seed: int
+    """Random seed for reproducibility.
+
+    When ``seed`` is fixed to a specific number, the model makes a best
+    effort to provide the same response for repeated requests.
+
+    Not supported by all providers, and does not guarantee strict reproducibility.
+    """
+
+    stop_sequences: list[str]
+    """Stop sequences to end generation.
+
+    The model will stop generating text if one of these strings is encountered in the
+    response.
+    """
+
+    thinking: ThinkingConfig | None
+    """Configuration for extended reasoning/thinking.
+
+    Pass a `ThinkingConfig` to configure thinking behavior. The `level` field controls
+    whether thinking is enabled and how much reasoning to use. Level may be one of
+    "minimal", "low", "medium", or "high". If level is unset, then thinking is enabled
+    with a provider-specific default level.
+
+    `ThinkingConfig` can also include `encode_thoughts_as_text`, which is an advanced
+    feature for providing past thoughts back to the model as text content. This is
+    primarily useful for making thoughts transferable when passing a conversation
+    to a different model or provider than the one that generated the thinking.
+    """

mirascope/llm/models/thinking_config.py

@@ -0,0 +1,61 @@
+"""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.
+    """

mirascope/llm/prompts/__init__.py

@@ -0,0 +1,34 @@
+"""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 PromptDecorator, prompt
+from .prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+)
+from .protocols import (
+    AsyncContextMessageTemplate,
+    AsyncMessageTemplate,
+    ContextMessageTemplate,
+    MessageTemplate,
+)
+
+__all__ = [
+    "AsyncContextMessageTemplate",
+    "AsyncContextPrompt",
+    "AsyncMessageTemplate",
+    "AsyncPrompt",
+    "ContextMessageTemplate",
+    "ContextPrompt",
+    "MessageTemplate",
+    "Prompt",
+    "PromptDecorator",
+    "_utils",
+    "prompt",
+]

mirascope/llm/prompts/_utils.py

@@ -0,0 +1,31 @@
+import inspect
+from typing_extensions import TypeIs
+
+from ..context import DepsT, _utils as _context_utils
+from ..types import P
+from .protocols import (
+    AsyncContextMessageTemplate,
+    AsyncMessageTemplate,
+    ContextMessageTemplate,
+    MessageTemplate,
+)
+
+
+def is_context_promptable(
+    fn: ContextMessageTemplate[P, DepsT]
+    | AsyncContextMessageTemplate[P, DepsT]
+    | MessageTemplate[P]
+    | AsyncMessageTemplate[P],
+) -> TypeIs[ContextMessageTemplate[P, DepsT] | AsyncContextMessageTemplate[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]]:
+    """Type guard to check if a function is an async promptable function."""
+    return inspect.iscoroutinefunction(fn)

mirascope/llm/prompts/decorator.py

@@ -0,0 +1,215 @@
+"""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 FormatSpec, FormattableT
+from ..tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+    ToolT,
+)
+from ..types import P
+from . import _utils
+from .prompts import (
+    AsyncContextPrompt,
+    AsyncPrompt,
+    ContextPrompt,
+    Prompt,
+)
+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: FormatSpec[FormattableT] | None
+    """The structured output format off the prompt, if any."""
+
+    def __init__(
+        self,
+        tools: Sequence[ToolT] | None = None,
+        format: FormatSpec[FormattableT] | None = None,
+    ) -> None:
+        """Initialize the decorator with optional tools and format."""
+        self.tools = tools
+        self.format = format
+
+    @overload
+    def __call__(
+        self: "PromptDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT]",
+        fn: AsyncContextMessageTemplate[P, DepsT],
+    ) -> AsyncContextPrompt[P, DepsT, FormattableT]:
+        """Decorator for creating async context prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self: "PromptDecorator[Tool | ContextTool[DepsT], FormattableT]",
+        fn: ContextMessageTemplate[P, DepsT],
+    ) -> ContextPrompt[P, DepsT, FormattableT]:
+        """Decorator for creating context prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self: "PromptDecorator[AsyncTool, FormattableT]",
+        fn: AsyncMessageTemplate[P],
+    ) -> AsyncPrompt[P, FormattableT]:
+        """Decorator for creating async prompts."""
+        ...
+
+    @overload
+    def __call__(
+        self: "PromptDecorator[Tool, FormattableT]",
+        fn: MessageTemplate[P],
+    ) -> Prompt[P, FormattableT]:
+        """Decorator for creating prompts."""
+        ...
+
+    def __call__(
+        self,
+        fn: ContextMessageTemplate[P, DepsT]
+        | AsyncContextMessageTemplate[P, DepsT]
+        | MessageTemplate[P]
+        | AsyncMessageTemplate[P],
+    ) -> (
+        Prompt[P, FormattableT]
+        | AsyncPrompt[P, FormattableT]
+        | ContextPrompt[P, DepsT, FormattableT]
+        | AsyncContextPrompt[P, DepsT, FormattableT]
+    ):
+        """Decorator for creating a prompt with tools and format."""
+        is_context = _utils.is_context_promptable(fn)
+        is_async = _utils.is_async_promptable(fn)
+
+        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,
+            )
+        elif is_context:
+            tools = cast(Sequence[Tool | ContextTool[DepsT]] | None, self.tools)
+            return ContextPrompt(
+                fn=fn,
+                toolkit=ContextToolkit(tools=tools),
+                format=self.format,
+            )
+        elif is_async:
+            tools = cast(Sequence[AsyncTool] | None, self.tools)
+            return AsyncPrompt(
+                fn=fn, toolkit=AsyncToolkit(tools=tools), format=self.format
+            )
+        else:
+            tools = cast(Sequence[Tool] | None, self.tools)
+            return Prompt(fn=fn, toolkit=Toolkit(tools=tools), format=self.format)
+
+
+@overload
+def prompt(  # pyright: ignore[reportOverlappingOverload]
+    __fn: ContextMessageTemplate[P, DepsT],
+) -> ContextPrompt[P, DepsT, None]:
+    """Create a decorator for sync ContextPrompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(  # pyright: ignore[reportOverlappingOverload]
+    __fn: AsyncContextMessageTemplate[P, DepsT],
+) -> AsyncContextPrompt[P, DepsT, None]:
+    """Create a decorator for async ContextPrompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    __fn: MessageTemplate[P],
+) -> Prompt[P, None]:
+    """Create a decorator for sync Prompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    __fn: AsyncMessageTemplate[P],
+) -> AsyncPrompt[P, None]:
+    """Create a decorator for async Prompt functions (no arguments)."""
+    ...
+
+
+@overload
+def prompt(
+    *,
+    tools: Sequence[ToolT] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
+) -> PromptDecorator[ToolT, FormattableT]:
+    """Create a decorator for Prompt functions with tools and format"""
+
+
+def prompt(
+    __fn: AsyncContextMessageTemplate[P, DepsT]
+    | ContextMessageTemplate[P, DepsT]
+    | AsyncMessageTemplate[P]
+    | MessageTemplate[P]
+    | None = None,
+    *,
+    tools: Sequence[ToolT] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
+) -> (
+    AsyncContextPrompt[P, DepsT, FormattableT]
+    | ContextPrompt[P, DepsT, FormattableT]
+    | AsyncPrompt[P, FormattableT]
+    | Prompt[P, FormattableT]
+    | PromptDecorator[ToolT, FormattableT]
+):
+    """Decorates a `MessageTemplate` to create a `Prompt` callable with a model.
+
+    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.
+
+    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`
+
+    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
+
+    Returns:
+        A `Prompt` variant (Prompt, AsyncPrompt, ContextPrompt, or AsyncContextPrompt)
+        or a `PromptDecorator` if called with arguments
+    """
+    decorator = PromptDecorator(tools=tools, format=format)
+    if __fn is None:
+        return decorator
+    # TODO: See if we can do without the pyright: ignores here
+    return decorator(__fn)  # pyright: ignore[reportUnknownVariableType, reportCallIssue]