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

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

@@ -2,6 +2,8 @@
 
 from typing import TypedDict
 
+from .thinking_config import ThinkingConfig
+
 
 class Params(TypedDict, total=False):
     """Common parameters shared across LLM providers.
@@ -23,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.
     """
@@ -41,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.
 
@@ -50,44 +52,21 @@ 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.
     """
 
-    thinking: bool
-    """Configures whether the model should use thinking.
-    
-    Thinking is a process where the model spends additional tokens thinking about the
-    prompt before generating a response. You may configure thinking either by passing
-    a bool to enable or disable it.
-
-    If `params.thinking` is `True`, then thinking and thought summaries will be enabled
-    (if supported by the model/provider), with a default budget for thinking tokens.
-
-    If `params.thinking` is `False`, then thinking will be wholly disabled, assuming
-    the model allows this (some models, e.g. `google:gemini-2.5-pro`, do not allow
-    disabling thinking).
-
-    If `params.thinking` is unset (or `None`), then we will use provider-specific default
-    behavior for the chosen model.
-    """
-
-    encode_thoughts_as_text: bool
-    """Configures whether `Thought` content should be re-encoded as text for model consumption.
-    
-    If `True`, then when an `AssistantMessage` contains `Thoughts` and is being passed back
-    to an LLM, those `Thoughts` will be encoded as `Text`, so that the assistant can read
-    those thoughts. That ensures the assistant has access to (at least the summarized output of)
-    its reasoning process, and contrasts with provider default behaviors which may ignore
-    prior thoughts, particularly if tool calls are not involved.
-
-    When `True`, we will always re-encode Mirascope messages being passed to the provider,
-    rather than reusing raw provider response content. This may disable provider-specific
-    behavior like cached reasoning tokens.
+    thinking: ThinkingConfig | None
+    """Configuration for extended reasoning/thinking.
 
-    If `False`, then `Thoughts` will not be encoded as text, and whether reasoning context
-    is available to the model depends entirely on the provider's behavior. 
+    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.
 
-    Defaults to `False` if unset.
+    `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/_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]