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

mirascope/llm/{providers/base → models}/params.py

@@ -1,58 +1,8 @@
 """Base parameters for LLM providers."""
 
-from typing import Literal, TypedDict
-from typing_extensions import Required
+from typing import 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_summaries: bool
-    """Whether to generate reasoning summaries (human readable Thoughts) from model output.
-    
-    Generally, providers do not return raw model thinking output, but may produce
-    thought summaries. When `include_summaries` is true, these will be requested from
-    the provider (if available). Otherwise, they will not be requested.
-    """
-
-    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.
-    """
+from .thinking_config import ThinkingConfig
 
 
 class Params(TypedDict, total=False):
@@ -75,8 +25,8 @@ class Params(TypedDict, total=False):
 
     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 
+
+    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.
     """
@@ -93,7 +43,7 @@ class Params(TypedDict, total=False):
 
     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.
 
@@ -102,7 +52,7 @@ class Params(TypedDict, total=False):
 
     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.
     """
@@ -111,7 +61,7 @@ class Params(TypedDict, total=False):
     """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 
+    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.
 

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/_utils.py

@@ -1,16 +1,7 @@
 import inspect
-from collections.abc import Sequence
 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,
@@ -20,29 +11,6 @@ from .protocols import (
 )
 
 
-def is_messages(
-    messages_or_content: Sequence[Message] | UserContent,
-) -> TypeIs[Sequence[Message]]:
-    if isinstance(messages_or_content, list):
-        if not messages_or_content:
-            raise ValueError("Empty array may not be used as message content")
-        return isinstance(
-            messages_or_content[0], SystemMessage | UserMessage | AssistantMessage
-        )
-    return False
-
-
-def promote_to_messages(result: Sequence[Message] | UserContent) -> 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 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]

mirascope/llm/prompts/decorator.py

@@ -4,7 +4,7 @@ from collections.abc import Sequence
 from typing import Generic, cast, overload
 
 from ..context import DepsT
-from ..formatting import Format, FormattableT
+from ..formatting import Format, FormattableT, OutputParser
 from ..tools import (
     AsyncContextTool,
     AsyncContextToolkit,
@@ -46,13 +46,18 @@ class PromptDecorator(Generic[ToolT, FormattableT]):
     tools: Sequence[ToolT] | None
     """The tools that are included in the prompt, if any."""
 
-    format: type[FormattableT] | Format[FormattableT] | None
+    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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> None:
         """Initialize the decorator with optional tools and format."""
         self.tools = tools
@@ -168,7 +173,10 @@ def prompt(
 def prompt(
     *,
     tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT] | Format[FormattableT] | None = None,
+    format: type[FormattableT]
+    | Format[FormattableT]
+    | OutputParser[FormattableT]
+    | None = None,
 ) -> PromptDecorator[ToolT, FormattableT]:
     """Create a decorator for Prompt functions with tools and format"""
 
@@ -181,7 +189,10 @@ def prompt(
     | None = None,
     *,
     tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT] | Format[FormattableT] | None = None,
+    format: type[FormattableT]
+    | Format[FormattableT]
+    | OutputParser[FormattableT]
+    | None = None,
 ) -> (
     AsyncContextPrompt[P, DepsT, FormattableT]
     | ContextPrompt[P, DepsT, FormattableT]