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

mirascope/core/base/tool.py

@@ -1,126 +0,0 @@
-"""This module defines the base class for tools used in LLM calls.
-
-usage-docs: learn/tools.md#the-basetool-class
-"""
-
-from __future__ import annotations
-
-import inspect
-from abc import abstractmethod
-from collections.abc import Callable
-from typing import Any, ClassVar, TypeVar, cast
-
-from pydantic import BaseModel, ConfigDict
-
-from . import _utils
-
-_BaseToolT = TypeVar("_BaseToolT")
-
-
-class BaseTool(BaseModel):
-    '''A class for defining tools for LLM calls.
-
-    Example:
-
-    ```python
-    from mirascope.core import BaseTool
-    from pydantic import Field
-
-
-    class FormatBook(BaseTool):
-        """Returns a nicely formatted book recommendation."""
-
-        title: str = Field(..., description="The title of the book.")
-        author: str = Field(..., description="The author of the book.")
-
-        def call(self) -> str:
-            return f"{self.title} by {self.author}"
-    ```
-    '''
-
-    __custom_name__: ClassVar[str] = ""
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    @classmethod
-    def _name(cls) -> str:
-        """Returns the name of the tool."""
-        return cls.__custom_name__ if cls.__custom_name__ else cls.__name__
-
-    @classmethod
-    def _description(cls) -> str:
-        """Returns the description of the tool."""
-        return (
-            inspect.cleandoc(cls.__doc__)
-            if cls.__doc__
-            else _utils.DEFAULT_TOOL_DOCSTRING
-        )
-
-    @property
-    def args(self) -> dict[str, Any]:
-        """The arguments of the tool as a dictionary."""
-        return {
-            field: getattr(self, field)
-            for field in self.model_fields
-            if field != "tool_call"
-        }
-
-    @abstractmethod
-    def call(self) -> Any:  # noqa: ANN401
-        """The method to call the tool."""
-        ...
-
-    @classmethod
-    def model_tool_schema(cls) -> dict[str, Any]:
-        """Returns the model_json_schema modified for reduced token usage."""
-        model_schema = cls.model_json_schema()
-        model_schema.pop("title", None)
-        model_schema.pop("description", None)
-
-        def remove_schema_titles(obj: Any) -> Any:  # noqa: ANN401
-            if isinstance(obj, dict):
-                # Remove the 'title' key only if it's a direct child of a schema object
-                if "type" in obj or "$ref" in obj or "properties" in obj:
-                    obj.pop("title", None)
-
-                # Recursively process nested objects
-                for key, value in list(obj.items()):
-                    obj[key] = remove_schema_titles(value)
-            elif isinstance(obj, list):
-                # Recursively process list items
-                return [remove_schema_titles(item) for item in obj]
-
-            return obj
-
-        return cast(dict[str, Any], remove_schema_titles(model_schema))
-
-    @classmethod
-    def type_from_fn(cls: _BaseToolT, fn: Callable) -> _BaseToolT:
-        """Returns this tool type converted from a function.
-
-        Args:
-            fn: The function to convert into this tool type.
-        """
-        return _utils.convert_function_to_base_tool(fn, cls)  # type: ignore
-
-    @classmethod
-    def type_from_base_model_type(
-        cls: _BaseToolT, tool_type: type[BaseModel]
-    ) -> _BaseToolT:
-        """Returns this tool type converted from a given base tool type.
-
-        Args:
-            tool_type: The tool type to convert into this tool type. This can be a
-                custom `BaseTool` or `BaseModel` definition.
-        """
-        return _utils.convert_base_model_to_base_tool(tool_type, cls)  # type: ignore
-
-    @classmethod
-    def type_from_base_type(
-        cls: _BaseToolT, base_type: type[_utils.BaseType]
-    ) -> _BaseToolT:
-        """Returns this tool type converted from a base type.
-
-        Args:
-            base_type: The base type (e.g. `int`) to convert into this tool type.
-        """
-        return _utils.convert_base_type_to_base_tool(base_type, cls)  # type: ignore

mirascope/core/base/toolkit.py

@@ -1,146 +0,0 @@
-"""The module for defining the toolkit class for LLM call tools.
-
-usage docs: learn/tools.md#basetoolkit
-"""
-
-from __future__ import annotations
-
-import inspect
-from abc import ABC
-from collections.abc import Callable
-from typing import Any, ClassVar, Concatenate, NamedTuple, TypeVar
-
-from pydantic import BaseModel, ConfigDict
-from typing_extensions import ParamSpec
-
-from . import BaseTool
-from ._utils import convert_function_to_base_tool, get_template_variables
-
-_TOOLKIT_TOOL_METHOD_MARKER: str = "__toolkit_tool_method__"
-
-_namespaces: set[str] = set()
-
-P = ParamSpec("P")
-
-
-class ToolKitToolMethod(NamedTuple):
-    method: Callable[..., str]
-    template_vars: list[str]
-    template: str
-
-
-class BaseToolKit(BaseModel, ABC):
-    """A class for defining tools for LLM call tools.
-
-    The class should have methods decorated with `@toolkit_tool` to create tools.
-
-    Example:
-    ```python
-    from mirascope.core.base import BaseToolKit, toolkit_tool
-    from mirascope.core import openai
-
-    class BookRecommendationToolKit(BaseToolKit):
-        '''A toolkit for recommending books.'''
-
-        __namespace__: ClassVar[str | None] = 'book_tools'
-        reading_level: Literal["beginner", "advanced"]
-
-        @toolkit_tool
-        def format_book(self, title: str, author: str) -> str:
-            '''Returns the title and author of a book nicely formatted.
-
-            Reading level: {self.reading_level}
-            '''
-            return f"{title} by {author}"
-
-    @openai.call(model="gpt-4o")
-    def recommend_book(genre: str, reading_level: Literal["beginner", "advanced"]):
-        '''Recommend a {genre} book.'''
-        toolkit = BookRecommendationToolKit(reading_level=reading_level)
-        return {"tools": toolkit.create_tools()}
-
-    response = recommend_book("fantasy", "beginner")
-    if tool := response.tool:
-        output = tool.call()
-        print(output)
-        #> The Name of the Wind by Patrick Rothfuss
-    else:
-        print(response.content)
-        #> Sure! I would recommend...
-    ```
-    """
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-    _toolkit_tool_methods: ClassVar[list[ToolKitToolMethod]]
-    __namespace__: ClassVar[str | None] = None
-
-    def create_tools(self) -> list[type[BaseTool]]:
-        """The method to create the tools."""
-        tools = []
-        for method, template_vars, template in self._toolkit_tool_methods:
-            for var in template_vars:
-                if var.startswith("self."):
-                    continue
-                # Replace non-self template variables with escaped double brackets so
-                # that templating `self` results in a future templateable string.
-                template = template.replace(f"{{{var}}}", f"{{{{{var}}}}}")
-            converted_method = convert_function_to_base_tool(
-                method, BaseTool, template.format(self=self), self.__namespace__
-            )
-            for key, value in self:
-                setattr(converted_method, key, value)
-            tools.append(converted_method)
-        return tools
-
-    @classmethod
-    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
-        # validate the namespace
-        if cls.__namespace__:
-            if cls.__namespace__ in _namespaces:
-                raise ValueError(f"The namespace {cls.__namespace__} is already used")
-            _namespaces.add(cls.__namespace__)
-
-        cls._toolkit_tool_methods = []
-        for attr in cls.__dict__.values():
-            if not getattr(attr, _TOOLKIT_TOOL_METHOD_MARKER, False):
-                continue
-            # Validate the toolkit_tool_method
-            if (template := attr.__doc__) is None:
-                raise ValueError("The toolkit_tool method must have a docstring")
-
-            dedented_template = inspect.cleandoc(template)
-            template_vars = get_template_variables(dedented_template, False)
-
-            for var in template_vars:
-                if not var.startswith("self."):
-                    # Skip template variables that do not start with self as they may
-                    # be later templated e.g. if using a call as a tool.
-                    continue
-
-                self_var = var[5:]
-
-                # Expecting pydantic model fields or class attribute and property
-                if self_var in cls.model_fields or hasattr(cls, self_var):
-                    continue
-                raise ValueError(
-                    f"The toolkit_tool method template variable {var} is not found in "
-                    "the class"
-                )
-
-            cls._toolkit_tool_methods.append(
-                ToolKitToolMethod(attr, template_vars, dedented_template)
-            )
-        if not cls._toolkit_tool_methods:
-            raise ValueError("No toolkit_tool method found")
-
-
-_BaseToolKitT = TypeVar("_BaseToolKitT", bound=BaseToolKit)
-
-
-def toolkit_tool(
-    method: Callable[Concatenate[_BaseToolKitT, P], str],
-) -> Callable[Concatenate[_BaseToolKitT, P], str]:
-    # Mark the method as a toolkit tool
-    setattr(method, _TOOLKIT_TOOL_METHOD_MARKER, True)
-
-    return method

mirascope/core/cohere/__init__.py

@@ -1,21 +0,0 @@
-"""The Mirascope Cohere Module."""
-
-from ._call import cohere_call
-from ._call import cohere_call as call
-from .call_params import CohereCallParams
-from .call_response import CohereCallResponse
-from .call_response_chunk import CohereCallResponseChunk
-from .dynamic_config import CohereDynamicConfig
-from .stream import CohereStream
-from .tool import CohereTool
-
-__all__ = [
-    "call",
-    "CohereDynamicConfig",
-    "CohereCallParams",
-    "CohereCallResponse",
-    "CohereCallResponseChunk",
-    "CohereStream",
-    "CohereTool",
-    "cohere_call",
-]

mirascope/core/cohere/_call.py

@@ -1,71 +0,0 @@
-"""The `cohere_call` decorator for functions as LLM calls."""
-
-from ..base import call_factory
-from ._utils import (
-    get_json_output,
-    handle_stream,
-    handle_stream_async,
-    setup_call,
-)
-from .call_params import CohereCallParams
-from .call_response import CohereCallResponse
-from .call_response_chunk import CohereCallResponseChunk
-from .dynamic_config import CohereDynamicConfig
-from .stream import CohereStream
-from .tool import CohereTool
-
-cohere_call = call_factory(
-    TCallResponse=CohereCallResponse,
-    TCallResponseChunk=CohereCallResponseChunk,
-    TDynamicConfig=CohereDynamicConfig,
-    TToolType=CohereTool,
-    TStream=CohereStream,
-    TCallParams=CohereCallParams,
-    default_call_params=CohereCallParams(),
-    setup_call=setup_call,  # type: ignore
-    get_json_output=get_json_output,
-    handle_stream=handle_stream,
-    handle_stream_async=handle_stream_async,
-)
-"""A decorator for calling the Cohere API with a typed function.
-
-usage docs: learn/calls.md
-
-This decorator is used to wrap a typed function that calls the Cohere API. It parses
-the docstring of the wrapped function as the messages array and templates the input
-arguments for the function into each message's template.
-
-Example:
-
-```python
-from mirascope.core import prompt_template
-from mirascope.core.cohere import cohere_call
-
-
-@cohere_call("command-r-plus")
-@prompt_template("Recommend a {genre} book")
-def recommend_book(genre: str):
-    ...
-
-response = recommend_book("fantasy")
-print(response.content)
-```
-
-Args:
-    model (str): The Cohere model to use in the API call.
-    stream (bool): Whether to stream the response from the API call.
-    tools (list[BaseTool | Callable]): The tools to use in the Cohere API call.
-    response_model (BaseModel | BaseType): The response model into which the response
-        should be structured.
-    output_parser (Callable[[CohereCallResponse | ResponseModelT], Any]): A function for
-        parsing the call response whose value will be returned in place of the original
-        call response.
-    json_mode (bool): Whether to use JSON Mode.
-    client (object): An optional custom client to use in place of the default client.
-    call_params (CohereCallParams): The `CohereCallParams` call parameters to use in the
-        API call.
-
-Returns:
-    decorator (Callable): The decorator for turning a typed function into a Cohere API
-        call.
-"""

mirascope/core/cohere/_utils/__init__.py

@@ -1,16 +0,0 @@
-"""Cohere utilities for decorator factories."""
-
-from ._calculate_cost import calculate_cost
-from ._convert_message_params import convert_message_params
-from ._get_json_output import get_json_output
-from ._handle_stream import handle_stream, handle_stream_async
-from ._setup_call import setup_call
-
-__all__ = [
-    "calculate_cost",
-    "convert_message_params",
-    "get_json_output",
-    "handle_stream",
-    "handle_stream_async",
-    "setup_call",
-]

mirascope/core/cohere/_utils/_calculate_cost.py

@@ -1,39 +0,0 @@
-"""Calculate the cost of a completion using the Cohere API."""
-
-
-def calculate_cost(
-    input_tokens: int | float | None,
-    output_tokens: int | float | None,
-    model: str = "command-r-plus",
-) -> float | None:
-    """Calculate the cost of a completion using the Cohere API.
-
-    https://cohere.com/pricing
-
-    Model              Input               Output
-    command-r          $0.5 / 1M tokens	   $1.5 / 1M tokens
-    command-r-plus     $3 / 1M tokens	   $15 / 1M tokens
-    """
-    pricing = {
-        "command-r": {
-            "prompt": 0.000_000_5,
-            "completion": 0.000_001_5,
-        },
-        "command-r-plus": {
-            "prompt": 0.000_003,
-            "completion": 0.000_015,
-        },
-    }
-    if input_tokens is None or output_tokens is None:
-        return None
-
-    try:
-        model_pricing = pricing[model]
-    except KeyError:
-        return None
-
-    prompt_cost = input_tokens * model_pricing["prompt"]
-    completion_cost = output_tokens * model_pricing["completion"]
-    total_cost = prompt_cost + completion_cost
-
-    return total_cost

mirascope/core/cohere/_utils/_convert_message_params.py

@@ -1,31 +0,0 @@
-"""Utility for converting `BaseMessageParam` to `ChatCompletionMessageParam`"""
-
-from cohere.types import ChatMessage
-
-from ...base import BaseMessageParam
-
-
-def convert_message_params(
-    message_params: list[BaseMessageParam | ChatMessage],
-) -> list[ChatMessage]:
-    converted_message_params = []
-    for message_param in message_params:
-        if isinstance(message_param, ChatMessage):
-            converted_message_params.append(message_param)
-        elif isinstance(content := message_param.content, str):
-            converted_message_params.append(
-                ChatMessage(
-                    role=message_param.role.upper(),  # type: ignore
-                    message=content,
-                )
-            )
-        else:
-            if len(content) != 1 or content[0].type != "text":
-                raise ValueError("Cohere does not currently support multimodalities.")
-            converted_message_params.append(
-                ChatMessage(
-                    role=message_param.role.upper(),  # type: ignore
-                    message=content[0].text,
-                )
-            )
-    return converted_message_params

mirascope/core/cohere/_utils/_get_json_output.py

@@ -1,31 +0,0 @@
-"""Get the JSON output from a completion response."""
-
-import json
-
-from cohere.types import StreamedChatResponse_ToolCallsGeneration
-
-from ..call_response import CohereCallResponse
-from ..call_response_chunk import CohereCallResponseChunk
-
-
-def get_json_output(
-    response: CohereCallResponse | CohereCallResponseChunk, json_mode: bool
-) -> str:
-    """Get the JSON output from a completion response."""
-    if isinstance(response, CohereCallResponse):
-        if json_mode and response.content:
-            return response.content
-        elif response.response.tool_calls:
-            return json.dumps(response.response.tool_calls[0].parameters)
-        raise ValueError("No tool call or JSON object found in response.")
-    else:
-        # raise ValueError("Cohere does not support structured streaming... :(")
-        if json_mode:
-            return response.content
-        elif (
-            isinstance(response.chunk, StreamedChatResponse_ToolCallsGeneration)
-            and (tool_calls := response.chunk.tool_calls)
-            and (parameters := tool_calls[0].parameters)
-        ):
-            return json.dumps(parameters)
-        return ""

mirascope/core/cohere/_utils/_handle_stream.py

@@ -1,33 +0,0 @@
-"""Handles the stream of completion chunks."""
-
-from collections.abc import AsyncGenerator, Generator
-
-from cohere.types import StreamedChatResponse
-
-from ..call_response_chunk import CohereCallResponseChunk
-from ..tool import CohereTool
-
-
-def handle_stream(
-    stream: Generator[StreamedChatResponse, None, None],
-    tool_types: list[type[CohereTool]] | None = None,
-) -> Generator[tuple[CohereCallResponseChunk, None], None, None]:
-    """Iterator over the stream and constructs tools as they are streamed.
-
-    Note: cohere does not currently support streaming tools.
-    """
-    for chunk in stream:
-        yield CohereCallResponseChunk(chunk=chunk), None
-
-
-async def handle_stream_async(
-    stream: AsyncGenerator[StreamedChatResponse, None],
-    tool_types: list[type[CohereTool]] | None = None,
-) -> AsyncGenerator[tuple[CohereCallResponseChunk, None], None]:
-    """
-    Async iterator over the stream and constructs tools as they are streamed.
-
-    Note: cohere does not currently support streaming tools.
-    """
-    async for chunk in stream:
-        yield CohereCallResponseChunk(chunk=chunk), None

mirascope/core/cohere/_utils/_setup_call.py

@@ -1,89 +0,0 @@
-"""This module contains the setup_call function for Cohere tools."""
-
-import inspect
-from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine, Iterator
-from typing import Any, cast
-
-from cohere import (
-    AsyncClient,
-    Client,
-    NonStreamedChatResponse,
-)
-from cohere.types import ChatMessage
-
-from ...base import BaseMessageParam, BaseTool, _utils
-from ..call_params import CohereCallParams
-from ..dynamic_config import CohereDynamicConfig
-from ..tool import CohereTool
-from ._convert_message_params import convert_message_params
-
-
-def setup_call(
-    *,
-    model: str,
-    client: Client | AsyncClient | None,
-    fn: Callable[..., CohereDynamicConfig | Awaitable[CohereDynamicConfig]],
-    fn_args: dict[str, Any],
-    dynamic_config: CohereDynamicConfig,
-    tools: list[type[BaseTool] | Callable] | None,
-    json_mode: bool,
-    call_params: CohereCallParams,
-    extract: bool,
-) -> tuple[
-    Callable[..., NonStreamedChatResponse]
-    | Callable[..., Awaitable[NonStreamedChatResponse]],
-    str,
-    list[ChatMessage],
-    list[type[CohereTool]] | None,
-    dict[str, Any],
-]:
-    prompt_template, messages, tool_types, call_kwargs = _utils.setup_call(
-        fn, fn_args, dynamic_config, tools, CohereTool, call_params
-    )
-    messages = cast(list[BaseMessageParam | ChatMessage], messages)
-    messages = convert_message_params(messages)
-
-    preamble = ""
-    if "preamble" in call_kwargs and call_kwargs["preamble"] is not None:
-        preamble += call_kwargs.pop("preamble")
-    if messages[0].role == "SYSTEM":  # type: ignore
-        if preamble:
-            preamble += "\n\n"
-        preamble += messages.pop(0).message
-    if preamble:
-        call_kwargs["preamble"] = preamble
-    if len(messages) > 1:
-        call_kwargs["chat_history"] = messages[:-1]
-    if json_mode:
-        # Cannot mutate ChatMessage in place
-        messages[-1] = ChatMessage(
-            role=messages[-1].role,  # type: ignore
-            message=messages[-1].message
-            + _utils.json_mode_content(tool_types[0] if tool_types else None),
-            tool_calls=messages[-1].tool_calls,
-        )
-        call_kwargs.pop("tools", None)
-    elif extract:
-        assert tool_types, "At least one tool must be provided for extraction."
-    call_kwargs |= {
-        "model": model,
-        "message": messages[-1].message,
-    }
-
-    if client is None:
-        client = AsyncClient() if inspect.iscoroutinefunction(fn) else Client()
-
-    def create_or_stream(
-        stream: bool,
-        **kwargs: Any,  # noqa: ANN401
-    ) -> (
-        Iterator[Any]
-        | AsyncIterator[Any]
-        | NonStreamedChatResponse
-        | Coroutine[Any, Any, NonStreamedChatResponse]
-    ):
-        if stream:
-            return client.chat_stream(**kwargs)
-        return client.chat(**kwargs)
-
-    return create_or_stream, prompt_template, messages, tool_types, call_kwargs  # type: ignore

mirascope/core/cohere/call_params.py

@@ -1,57 +0,0 @@
-"""usage docs: learn/calls.md#provider-specific-parameters"""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from cohere.types import (
-    ChatConnector,
-    ChatDocument,
-    ChatRequestPromptTruncation,
-    ToolResult,
-)
-from typing_extensions import NotRequired
-
-from ..base import BaseCallParams
-
-
-class CohereCallParams(BaseCallParams):
-    """The parameters to use when calling the Cohere API.
-
-    [Cohere API Reference](https://docs.cohere.com/reference/chat)
-
-    Attributes:
-        conversation_id: ...
-        prompt_truncation: ...
-        connectors: ...
-        search_queries_only: ...
-        documents: ...
-        temperature: ...
-        max_tokens: ...
-        max_input_tokens: ...
-        k: ...
-        p: ...
-        seed: ...
-        stop_sequences: ...
-        frequency_penalty: ...
-        presence_penalty: ...
-        raw_prompting: ...
-        tool_results: ...
-    """
-
-    conversation_id: NotRequired[str | None]
-    prompt_truncation: NotRequired[ChatRequestPromptTruncation | None]
-    connectors: NotRequired[Sequence[ChatConnector] | None]
-    search_queries_only: NotRequired[bool | None]
-    documents: NotRequired[Sequence[ChatDocument] | None]
-    temperature: NotRequired[float | None]
-    max_tokens: NotRequired[int | None]
-    max_input_tokens: NotRequired[int | None]
-    k: NotRequired[int | None]
-    p: NotRequired[float | None]
-    seed: NotRequired[int | None]
-    stop_sequences: NotRequired[Sequence[str] | None]
-    frequency_penalty: NotRequired[float | None]
-    presence_penalty: NotRequired[float | None]
-    raw_prompting: NotRequired[bool | None]
-    tool_results: NotRequired[Sequence[ToolResult] | None]