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

mirascope/core/base/_utils/__init__.py

@@ -1,64 +0,0 @@
-"""Internal Utilities."""
-
-from ._base_type import BaseType, is_base_type
-from ._convert_base_model_to_base_tool import convert_base_model_to_base_tool
-from ._convert_base_type_to_base_tool import convert_base_type_to_base_tool
-from ._convert_function_to_base_tool import convert_function_to_base_tool
-from ._default_tool_docstring import DEFAULT_TOOL_DOCSTRING
-from ._extract_tool_return import extract_tool_return
-from ._format_template import format_template
-from ._get_audio_type import get_audio_type
-from ._get_fn_args import get_fn_args
-from ._get_image_type import get_image_type
-from ._get_metadata import get_metadata
-from ._get_possible_user_message_param import get_possible_user_message_param
-from ._get_prompt_template import get_prompt_template
-from ._get_template_values import get_template_values
-from ._get_template_variables import get_template_variables
-from ._json_mode_content import json_mode_content
-from ._parse_content_template import parse_content_template
-from ._parse_prompt_messages import parse_prompt_messages
-from ._protocols import (
-    AsyncCreateFn,
-    CalculateCost,
-    CreateFn,
-    GetJsonOutput,
-    HandleStream,
-    HandleStreamAsync,
-    LLMFunctionDecorator,
-    SetupCall,
-)
-from ._setup_call import setup_call
-from ._setup_extract_tool import setup_extract_tool
-
-__all__ = [
-    "AsyncCreateFn",
-    "BaseType",
-    "CalculateCost",
-    "convert_base_model_to_base_tool",
-    "convert_base_type_to_base_tool",
-    "convert_function_to_base_tool",
-    "CreateFn",
-    "DEFAULT_TOOL_DOCSTRING",
-    "extract_tool_return",
-    "format_template",
-    "GetJsonOutput",
-    "get_audio_type",
-    "get_fn_args",
-    "get_image_type",
-    "get_metadata",
-    "get_possible_user_message_param",
-    "get_prompt_template",
-    "get_template_values",
-    "get_template_variables",
-    "HandleStream",
-    "HandleStreamAsync",
-    "is_base_type",
-    "json_mode_content",
-    "LLMFunctionDecorator",
-    "parse_content_template",
-    "parse_prompt_messages",
-    "SetupCall",
-    "setup_call",
-    "setup_extract_tool",
-]

mirascope/core/base/_utils/_base_type.py

@@ -1,17 +0,0 @@
-"""This module contains utility functions for base types."""
-
-import inspect
-from enum import Enum
-from typing import Annotated, Any, Literal, TypeGuard, Union, get_origin
-
-BaseType = str | int | float | bool | bytes | list | set | tuple | dict
-
-
-def is_base_type(type_: Any) -> TypeGuard[type[BaseType]]:  # noqa: ANN401
-    """Check if a type is a base type."""
-    base_types = {str, int, float, bool, bytes, list, set, tuple, dict}
-    return (
-        (inspect.isclass(type_) and issubclass(type_, Enum))
-        or type_ in base_types
-        or get_origin(type_) in base_types.union({Literal, Union, Annotated})
-    )

mirascope/core/base/_utils/_convert_base_model_to_base_tool.py

@@ -1,45 +0,0 @@
-"""Utility for converting a model into a base tool."""
-
-import inspect
-from abc import update_abstractmethods
-from typing import Any, TypeVar, cast
-
-from pydantic import BaseModel, create_model
-
-from ._default_tool_docstring import DEFAULT_TOOL_DOCSTRING
-
-BaseToolT = TypeVar("BaseToolT", bound=BaseModel)
-
-
-def convert_base_model_to_base_tool(
-    model: type[BaseModel], base: type[BaseToolT]
-) -> type[BaseToolT]:
-    """Converts a `BaseModel` schema to a `BaseToolT` type.
-
-    By adding a docstring (if needed) and passing on fields and field information in
-    dictionary format, a Pydantic `BaseModel` can be converted into an `BaseTool` for
-    performing extraction.
-
-    Args:
-        model: The `BaseModel` schema to convert.
-        base: The base type to extend with the `BaseModel` fields.
-
-    Returns:
-        The constructed `BaseModelT` type.
-    """
-    field_definitions = {
-        field_name: (field_info.annotation, field_info)
-        for field_name, field_info in model.model_fields.items()
-    }
-    tool_type = create_model(
-        f"{model.__name__}",
-        __base__=base,
-        __doc__=model.__doc__ if model.__doc__ else DEFAULT_TOOL_DOCSTRING,
-        **cast(dict[str, Any], field_definitions),
-    )
-    bases = list(tool_type.__bases__)
-    tool_type.__bases__ = tuple(bases) if model in bases else tuple([model] + bases)
-    for name, value in inspect.getmembers(model):
-        if not hasattr(tool_type, name) or name in ["_name", "_description", "call"]:
-            setattr(tool_type, name, value)
-    return update_abstractmethods(tool_type)

mirascope/core/base/_utils/_convert_base_type_to_base_tool.py

@@ -1,24 +0,0 @@
-"""This module contains the `convert_base_type_to_base_tool` function."""
-
-from typing import Annotated, TypeVar, get_args, get_origin
-
-from pydantic import BaseModel, create_model
-
-from ._base_type import BaseType
-from ._default_tool_docstring import DEFAULT_TOOL_DOCSTRING
-
-BaseToolT = TypeVar("BaseToolT", bound=BaseModel)
-
-
-def convert_base_type_to_base_tool(
-    schema: type[BaseType], base: type[BaseToolT]
-) -> type[BaseToolT]:
-    """Converts a `BaseType` to a `BaseToolT` type."""
-    if get_origin(schema) == Annotated:
-        schema.__name__ = get_args(schema)[0].__name__
-    return create_model(
-        schema.__name__,
-        __base__=base,
-        __doc__=DEFAULT_TOOL_DOCSTRING,
-        value=(schema, ...),
-    )

mirascope/core/base/_utils/_convert_function_to_base_tool.py

@@ -1,126 +0,0 @@
-import inspect
-from abc import update_abstractmethods
-from collections.abc import Callable
-from typing import Any, TypeVar, cast, get_type_hints
-
-import jiter
-from docstring_parser import parse
-from pydantic import BaseModel, create_model
-from pydantic.fields import FieldInfo
-
-from ._default_tool_docstring import DEFAULT_TOOL_DOCSTRING
-
-BaseToolT = TypeVar("BaseToolT", bound=BaseModel)
-
-
-def convert_function_to_base_tool(
-    fn: Callable,
-    base: type[BaseToolT],
-    __doc__: str | None = None,
-    __namespace__: str | None = None,
-) -> type[BaseToolT]:
-    """Constructs a `BaseToolT` type from the given function.
-
-    This method expects all function parameters to be properly documented in identical
-    order with identical variable names, as well as descriptions of each parameter.
-    Errors will be raised if any of these conditions are not met.
-
-    Args:
-        fn: The function to convert.
-        base: The `BaseToolT` type to which the function is converted.
-        __doc__: The docstring to use for the constructed `BaseToolT` type.
-        __namespace__: The namespace to use for the constructed `BaseToolT` type.
-
-    Returns:
-        The constructed `BaseToolT` type.
-
-    Raises:
-        ValueError: if the given function's parameters don't have type annotations.
-        ValueError: if a given function's parameter is in the docstring args section but
-            the name doesn't match the docstring's parameter name.
-        ValueError: if a given function's parameter is in the docstring args section but
-            doesn't have a docstring description.
-    """
-    docstring, examples = None, []
-    func_doc = __doc__ or fn.__doc__
-    if func_doc:
-        docstring = parse(func_doc)
-        for example in docstring.examples or []:
-            if example.description:
-                examples.append(jiter.from_json(example.description.encode()))
-
-    field_definitions = {}
-    hints = get_type_hints(fn)
-    has_self = False
-    for i, parameter in enumerate(inspect.signature(fn).parameters.values()):
-        if parameter.name == "self":
-            has_self = True
-            continue
-        if parameter.name == "cls":
-            continue
-        if parameter.annotation == inspect.Parameter.empty:
-            raise ValueError("All parameters must have a type annotation.")
-
-        docstring_description = None
-        if docstring and i < len(docstring.params):
-            docstring_param = docstring.params[i]
-            if docstring_param.arg_name != parameter.name:
-                raise ValueError(
-                    f"Function parameter name {parameter.name} does not match docstring "
-                    f"parameter name {docstring_param.arg_name}. Make sure that the "
-                    "parameter names match exactly."
-                )
-            if not docstring_param.description:
-                raise ValueError("All parameters must have a description.")
-            docstring_description = docstring_param.description
-
-        field_info = FieldInfo(annotation=hints[parameter.name])
-        if parameter.default != inspect.Parameter.empty:
-            field_info.default = parameter.default
-        if docstring_description:  # we check falsy here because this comes from docstr
-            field_info.description = docstring_description
-
-        param_name = parameter.name
-        if param_name.startswith("model_"):  # model_ is a BaseModel reserved namespace
-            param_name = "aliased_" + param_name
-            field_info.alias = parameter.name
-            field_info.validation_alias = parameter.name
-            field_info.serialization_alias = parameter.name
-
-        field_definitions[param_name] = (
-            hints[parameter.name],
-            field_info,
-        )
-
-    model = create_model(
-        f"{__namespace__}_{fn.__name__}" if __namespace__ else fn.__name__,
-        __base__=base,
-        __doc__=inspect.cleandoc(func_doc) if func_doc else DEFAULT_TOOL_DOCSTRING,
-        **cast(dict[str, Any], field_definitions),
-    )
-    if examples:
-        model.model_config["json_schema_extra"] = {"examples": examples}
-
-    def call(self: base) -> Any:  # noqa: ANN401
-        return fn(
-            **(
-                ({"self": self} if has_self else {})
-                | {
-                    str(
-                        self.model_fields[field_name].alias
-                        if self.model_fields[field_name].alias
-                        else field_name
-                    ): getattr(self, field_name)
-                    for field_name in self.model_dump(exclude={"tool_call"})
-                }
-            )
-        )
-
-    async def call_async(self: base) -> Callable:
-        return await call(self)
-
-    if inspect.iscoroutinefunction(fn):
-        model.call = call_async  # pyright: ignore [reportAttributeAccessIssue]
-    else:
-        model.call = call  # pyright: ignore [reportAttributeAccessIssue]
-    return update_abstractmethods(model)

mirascope/core/base/_utils/_default_tool_docstring.py

@@ -1,6 +0,0 @@
-"""The default docstring to use when tools don't have a docstring."""
-
-DEFAULT_TOOL_DOCSTRING = """\
-Correctly formatted and typed parameters extracted from the completion. \
-Must include required parameters and may exclude optional parameters unless present in the text.\
-"""

mirascope/core/base/_utils/_extract_tool_return.py

@@ -1,36 +0,0 @@
-"""This module contains the function to extract the return value of a tool."""
-
-from typing import TypeVar
-
-import jiter
-from pydantic import BaseModel
-
-from .._partial import partial
-from ._base_type import BaseType, is_base_type
-from ._convert_base_type_to_base_tool import convert_base_type_to_base_tool
-
-_ResponseModelT = TypeVar("_ResponseModelT", bound=BaseModel | BaseType)
-
-
-def extract_tool_return(
-    response_model: type[_ResponseModelT],
-    json_output: str | object,
-    allow_partial: bool,
-) -> _ResponseModelT:
-    json_obj = (
-        jiter.from_json(
-            json_output.encode(),
-            partial_mode="trailing-strings" if allow_partial else "off",
-        )
-        if isinstance(json_output, str)
-        else json_output
-    )
-    if is_base_type(response_model):
-        temp_model = convert_base_type_to_base_tool(response_model, BaseModel)  # type: ignore
-        if allow_partial:
-            return partial(temp_model).model_validate(json_obj).value  # type: ignore
-        return temp_model.model_validate(json_obj).value  # type: ignore
-
-    if allow_partial:
-        return partial(response_model).model_validate(json_obj)  # type: ignore
-    return response_model.model_validate(json_obj)  # type: ignore

mirascope/core/base/_utils/_format_template.py

@@ -1,29 +0,0 @@
-"""This module contains the `format_template` function."""
-
-import inspect
-from typing import Any
-
-from ._get_template_values import get_template_values
-from ._get_template_variables import get_template_variables
-
-
-def format_template(template: str, attrs: dict[str, Any]) -> str:
-    """Formats the given prompt `template`
-
-    Args:
-        template: The template to format.
-        attrs: The attributes to use for formatting.
-
-    Returns:
-        The formatted template.
-
-    """
-    dedented_template = inspect.cleandoc(template).strip()
-    template_vars = get_template_variables(dedented_template, True)
-
-    values = get_template_values(template_vars, attrs)
-
-    # Remove any special format specs that are actually invalid normally
-    dedented_template = dedented_template.replace(":lists", "").replace(":list", "")
-
-    return dedented_template.format(**values).strip()

mirascope/core/base/_utils/_get_audio_type.py

@@ -1,18 +0,0 @@
-"""Utility for determining the type of an audio file from its bytes."""
-
-
-def get_audio_type(audio_data: bytes) -> str:
-    if audio_data.startswith(b"RIFF") and audio_data[8:12] == b"WAVE":
-        return "wav"
-    elif audio_data.startswith(b"ID3") or audio_data.startswith(b"\xff\xfb"):
-        return "mp3"
-    elif audio_data.startswith(b"FORM") and audio_data[8:12] == b"AIFF":
-        return "aiff"
-    elif audio_data.startswith(b"\xff\xf1") or audio_data.startswith(b"\xff\xf9"):
-        return "aac"
-    elif audio_data.startswith(b"OggS"):
-        return "ogg"
-    elif audio_data.startswith(b"fLaC"):
-        return "flac"
-
-    raise ValueError("Unsupported audio type")

mirascope/core/base/_utils/_get_fn_args.py

@@ -1,14 +0,0 @@
-"""Function for binding `args` and `kwargs` as a dictionary to the fn's signature."""
-
-import inspect
-from collections.abc import Callable
-from typing import Any
-
-
-def get_fn_args(
-    fn: Callable, args: tuple[object, ...], kwargs: dict[str, Any]
-) -> dict[str, Any]:
-    """Returns the `args` and `kwargs` as a dictionary bound by `fn`'s signature."""
-    bound_args = inspect.signature(fn).bind_partial(*args, **kwargs)
-    bound_args.apply_defaults()
-    return bound_args.arguments

mirascope/core/base/_utils/_get_image_type.py

@@ -1,26 +0,0 @@
-"""Utility for determining the type of an image from its bytes."""
-
-
-def get_image_type(image_data: bytes) -> str:
-    if image_data.startswith(b"\xff\xd8\xff"):
-        return "jpeg"
-    elif image_data.startswith(b"\x89PNG\r\n\x1a\n"):
-        return "png"
-    elif image_data.startswith(b"GIF87a") or image_data.startswith(b"GIF89a"):
-        return "gif"
-    elif image_data.startswith(b"RIFF") and image_data[8:12] == b"WEBP":
-        return "webp"
-    elif image_data[4:12] in (
-        b"ftypmif1",
-        b"ftypmsf1",
-        b"ftypheic",
-        b"ftypheix",
-        b"ftyphevc",
-        b"ftyphevx",
-    ):
-        subtype = image_data[8:12]
-        if subtype in (b"heic", b"heix"):
-            return "heic"
-        elif subtype in (b"mif1", b"msf1", b"hevc", b"hevx"):
-            return "heif"
-    raise ValueError("Unsupported image type")

mirascope/core/base/_utils/_get_metadata.py

@@ -1,17 +0,0 @@
-"""Utility for pulling metadata from a call and merging with any dynamic metadata."""
-
-from collections.abc import Callable
-
-from pydantic import BaseModel
-
-from ..dynamic_config import BaseDynamicConfig
-from ..metadata import Metadata
-
-
-def get_metadata(
-    fn: Callable | BaseModel, dynamic_config: BaseDynamicConfig
-) -> Metadata:
-    """Get the metadata from the function and merge with any dynamic metadata."""
-    if dynamic_config and "metadata" in dynamic_config:
-        return dynamic_config["metadata"]
-    return getattr(fn, "_metadata", Metadata())

mirascope/core/base/_utils/_get_possible_user_message_param.py

@@ -1,21 +0,0 @@
-"""Utility for getting the possible most recent user message."""
-
-from typing import TypeVar
-
-_T = TypeVar("_T")
-
-
-def get_possible_user_message_param(messages: list[_T]) -> _T | None:
-    """Get the possible most recent user message."""
-    if not messages:
-        return None
-    most_recent_message = messages[-1]
-    if (
-        isinstance(most_recent_message, dict)
-        and "role" in most_recent_message
-        and most_recent_message["role"] == "user"
-    ):
-        return most_recent_message
-    if hasattr(most_recent_message, "role") and most_recent_message.role == "user":  # pyright: ignore [reportAttributeAccessIssue]
-        return most_recent_message
-    return None

mirascope/core/base/_utils/_get_prompt_template.py

@@ -1,25 +0,0 @@
-"""Utility for pulling the `prompt_template` from a call or `BasePrompt`."""
-
-import inspect
-import os
-from collections.abc import Callable
-
-from pydantic import BaseModel
-
-
-def get_prompt_template(fn: Callable | BaseModel) -> str:
-    """Get the metadata from the function and merge with any dynamic metadata."""
-    prompt_template = getattr(fn, "_prompt_template", None)
-    if prompt_template:
-        return prompt_template
-
-    docstring_prompt_enabled = os.getenv("MIRASCOPE_DOCSTRING_PROMPT_TEMPLATE")
-    doc = fn.__doc__
-    if not doc:
-        raise ValueError("No prompt template set!")
-    if docstring_prompt_enabled != "ENABLED":
-        raise ValueError(
-            "You must explicitly enable docstring prompt templates by setting "
-            "`MIRASCOPE_DOCSTRING_PROMPT_TEMPLATE=ENABLED` in your environment."
-        )
-    return inspect.cleandoc(doc)

mirascope/core/base/_utils/_get_template_values.py

@@ -1,52 +0,0 @@
-"""This module contains the `get_template_values` function."""
-
-from typing import Any
-
-
-def get_template_values(
-    template_variables: list[tuple[str, str | None]], attrs: dict[str, Any]
-) -> dict[str, Any]:
-    """Returns the values of the given `template_variables` from the provided `attrs`.
-
-    Args:
-        template_variables: The variables to extract from the `attrs`.
-        attrs: The attributes to extract the variables from.
-
-    Returns:
-        The values of the template variables.
-    """
-    values = {}
-    attrs.update(attrs.pop("kwargs", {}))
-    if "self" in attrs:
-        values["self"] = attrs.get("self")
-    for var, format_spec in template_variables:
-        if var.startswith("self"):
-            values["self"] = attrs.get("self")
-        elif "." in var:
-            var = var.split(".")[0]
-            values[var] = attrs.get(var)
-            continue
-        elif format_spec in ["list", "lists"]:
-            value = attrs[var]
-            if format_spec == "list":
-                if not isinstance(value, list):
-                    raise ValueError(
-                        f"Template variable '{var}' must be a list when using the "
-                        "'list' format spec."
-                    )
-                values[var] = "\n".join([str(item) for item in attrs[var]])
-            else:
-                if not isinstance(value, list) or (
-                    value
-                    and not all(isinstance(item, list | tuple | set) for item in value)
-                ):
-                    raise ValueError(
-                        f"Template variable '{var}' must be a list of lists when using "
-                        "the 'lists' format spec."
-                    )
-                values[var] = "\n\n".join(
-                    ["\n".join([str(subitem) for subitem in item]) for item in value]
-                )
-        else:
-            values[var] = attrs[var] if attrs[var] is not None else ""
-    return values

mirascope/core/base/_utils/_get_template_variables.py

@@ -1,38 +0,0 @@
-"""This module provides a function to get the variables in a template string."""
-
-from string import Formatter
-from typing import Literal, overload
-
-
-@overload
-def get_template_variables(
-    template: str, include_format_spec: Literal[True]
-) -> list[tuple[str, str | None]]: ...
-
-
-@overload
-def get_template_variables(
-    template: str, include_format_spec: Literal[False]
-) -> list[str]: ...
-
-
-def get_template_variables(
-    template: str, include_format_spec: bool
-) -> list[str] | list[tuple[str, str | None]]:
-    """Returns the variables in the given template string.
-
-    Args:
-        template: The template string to parse.
-        include_format_spec: A boolean indicating whether to include format specifications.
-
-    Returns:
-        The variables in the template string.
-    """
-    if include_format_spec:
-        return [
-            (var, format_spec)
-            for _, var, format_spec, _ in Formatter().parse(template)
-            if var
-        ]
-    else:
-        return [var for _, var, _, _ in Formatter().parse(template) if var]

mirascope/core/base/_utils/_json_mode_content.py

@@ -1,15 +0,0 @@
-"""A function generating content to request JSON mode from models without it."""
-
-import json
-
-from ..tool import BaseTool
-
-
-def json_mode_content(tool_type: type[BaseTool] | None) -> str:
-    """Returns the content to request JSON mode from models without it."""
-    if not tool_type:
-        return "\n\nExtract ONLY a valid JSON dict using the schema."
-    return f"""
-
-Extract ONLY a valid JSON dict (NOT THE SCHEMA) from the content that adheres to this schema:
-{json.dumps(tool_type.model_json_schema(), indent=2)}"""