mirascope 1.25.7__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/core/base/structured_stream.py

@@ -1,296 +0,0 @@
-"""This module defines the base class for structured streams."""
-
-from collections.abc import (
-    AsyncGenerator,
-    AsyncIterable,
-    Awaitable,
-    Callable,
-    Generator,
-    Iterable,
-)
-from functools import wraps
-from typing import (
-    Any,
-    Generic,
-    ParamSpec,
-    TypeVar,
-    cast,
-    overload,
-)
-
-from pydantic import BaseModel
-
-from ._utils import (
-    BaseType,
-    GetJsonOutput,
-    SameSyncAndAsyncClientSetupCall,
-    SetupCall,
-    extract_tool_return,
-    fn_is_async,
-    setup_extract_tool,
-)
-from ._utils._get_fields_from_call_args import (
-    get_fields_from_call_args,
-)
-from .call_params import BaseCallParams
-from .call_response import BaseCallResponse
-from .call_response_chunk import BaseCallResponseChunk
-from .dynamic_config import BaseDynamicConfig
-from .stream import BaseStream, stream_factory
-from .tool import BaseTool
-
-_BaseCallResponseT = TypeVar("_BaseCallResponseT", bound=BaseCallResponse)
-_BaseCallResponseChunkT = TypeVar(
-    "_BaseCallResponseChunkT", bound=BaseCallResponseChunk
-)
-_BaseToolT = TypeVar("_BaseToolT", bound=BaseTool)
-_BaseCallParamsT = TypeVar("_BaseCallParamsT", bound=BaseCallParams)
-_BaseDynamicConfigT = TypeVar("_BaseDynamicConfigT", bound=BaseDynamicConfig)
-_ResponseModelT = TypeVar("_ResponseModelT", bound=BaseModel | BaseType)
-
-
-class BaseStructuredStream(Generic[_ResponseModelT]):
-    """A base class for streaming structured outputs from LLMs."""
-
-    stream: BaseStream
-    response_model: type[_ResponseModelT]
-    constructed_response_model: _ResponseModelT
-
-    def __init__(
-        self,
-        *,
-        stream: BaseStream,
-        response_model: type[_ResponseModelT],
-        fields_from_call_args: dict[str, Any],
-    ) -> None:
-        """Initializes an instance of `BaseStructuredStream`."""
-        self.stream = stream
-        self.response_model = response_model
-        self.fields_from_call_args = fields_from_call_args
-
-    def __iter__(self) -> Generator[_ResponseModelT, None, None]:
-        """Iterates over the stream and extracts structured outputs."""
-        json_output = ""
-        for chunk, _ in self.stream:
-            json_output += chunk.content
-            if json_output and json_output[0] != "{":
-                try:
-                    json_start = json_output.index("{")
-                    json_output = json_output[json_start:]
-                except ValueError:
-                    json_output = ""
-            if chunk.model is not None:
-                self.stream.model = chunk.model
-            if json_output:
-                yield extract_tool_return(
-                    self.response_model, json_output, True, self.fields_from_call_args
-                )
-        if json_output:
-            json_output = json_output[: json_output.rfind("}") + 1]
-        self.constructed_response_model = extract_tool_return(
-            self.response_model, json_output, False, self.fields_from_call_args
-        )
-        yield self.constructed_response_model
-
-    def __aiter__(self) -> AsyncGenerator[_ResponseModelT, None]:
-        """Iterates over the stream and extracts structured outputs."""
-
-        async def generator() -> AsyncGenerator[_ResponseModelT, None]:
-            json_output = ""
-            async for chunk, _ in self.stream:
-                json_output += chunk.content
-                if json_output and json_output[0] != "{":
-                    try:
-                        json_start = json_output.index("{")
-                        json_output = json_output[json_start:]
-                    except ValueError:
-                        json_output = ""
-                if chunk.model is not None:
-                    self.stream.model = chunk.model
-                if json_output:
-                    yield extract_tool_return(
-                        self.response_model,
-                        json_output,
-                        True,
-                        self.fields_from_call_args,
-                    )
-            if json_output:
-                json_output = json_output[: json_output.rfind("}") + 1]
-            self.constructed_response_model = extract_tool_return(
-                self.response_model, json_output, False, self.fields_from_call_args
-            )
-            yield self.constructed_response_model
-
-        return generator()
-
-
-_BaseDynamicConfigT = TypeVar("_BaseDynamicConfigT", bound=BaseDynamicConfig)
-_AsyncBaseDynamicConfigT = TypeVar("_AsyncBaseDynamicConfigT", bound=BaseDynamicConfig)
-_SameSyncAndAsyncClientT = TypeVar("_SameSyncAndAsyncClientT", contravariant=True)
-_SyncBaseClientT = TypeVar("_SyncBaseClientT", contravariant=True)
-_AsyncBaseClientT = TypeVar("_AsyncBaseClientT", contravariant=True)
-_ResponseT = TypeVar("_ResponseT")
-_ResponseChunkT = TypeVar("_ResponseChunkT")
-_AsyncResponseT = TypeVar("_AsyncResponseT")
-_AsyncResponseChunkT = TypeVar("_AsyncResponseChunkT")
-_P = ParamSpec("_P")
-
-
-def structured_stream_factory(  # noqa: ANN201
-    *,
-    TCallResponse: type[_BaseCallResponseT],
-    TCallResponseChunk: type[_BaseCallResponseChunkT],
-    TStream: type[BaseStream],
-    TToolType: type[_BaseToolT],
-    setup_call: SameSyncAndAsyncClientSetupCall[
-        _SameSyncAndAsyncClientT,
-        _BaseDynamicConfigT,
-        _AsyncBaseDynamicConfigT,
-        _BaseCallParamsT,
-        _ResponseT,
-        _ResponseChunkT,
-        _AsyncResponseT,
-        _AsyncResponseChunkT,
-        _BaseToolT,
-    ]
-    | SetupCall[
-        _SyncBaseClientT,
-        _AsyncBaseClientT,
-        _BaseDynamicConfigT,
-        _AsyncBaseDynamicConfigT,
-        _BaseCallParamsT,
-        _ResponseT,
-        _ResponseChunkT,
-        _AsyncResponseT,
-        _AsyncResponseChunkT,
-        _BaseToolT,
-    ],
-    get_json_output: GetJsonOutput[_BaseCallResponseChunkT],
-):
-    class CustomContentChunk(TCallResponseChunk):
-        json_output: str
-
-        @property
-        def content(self) -> str:
-            return self.json_output
-
-    @overload
-    def decorator(
-        fn: Callable[_P, _BaseDynamicConfigT],
-        model: str,
-        response_model: type[_ResponseModelT],
-        json_mode: bool,
-        client: _SameSyncAndAsyncClientT | _SyncBaseClientT | None,
-        call_params: _BaseCallParamsT,
-    ) -> Callable[
-        _P,
-        Iterable[_ResponseModelT],
-    ]: ...
-
-    @overload
-    def decorator(
-        fn: Callable[_P, Awaitable[_AsyncBaseDynamicConfigT]],
-        model: str,
-        response_model: type[_ResponseModelT],
-        json_mode: bool,
-        client: _SameSyncAndAsyncClientT | _AsyncBaseClientT | None,
-        call_params: _BaseCallParamsT,
-    ) -> Callable[
-        _P,
-        Awaitable[AsyncIterable[_ResponseModelT]],
-    ]: ...
-
-    def decorator(
-        fn: Callable[_P, _BaseDynamicConfigT]
-        | Callable[_P, Awaitable[_AsyncBaseDynamicConfigT]],
-        model: str,
-        response_model: type[_ResponseModelT],
-        json_mode: bool,
-        client: _SameSyncAndAsyncClientT | _SyncBaseClientT | _AsyncBaseClientT | None,
-        call_params: _BaseCallParamsT,
-    ) -> Callable[
-        _P,
-        Iterable[_ResponseModelT] | Awaitable[AsyncIterable[_ResponseModelT]],
-    ]:
-        def handle_chunk(
-            chunk: _ResponseChunkT | _AsyncResponseChunkT,
-        ) -> tuple[_BaseCallResponseChunkT, None]:
-            call_response_chunk = TCallResponseChunk(chunk=chunk)
-            json_output = get_json_output(call_response_chunk, json_mode)
-
-            call_response_chunk = cast(
-                _BaseCallResponseChunkT,
-                CustomContentChunk(chunk=chunk, json_output=json_output),  # pyright: ignore [reportAbstractUsage]
-            )
-            return call_response_chunk, None
-
-        def handle_stream(
-            stream: Generator[_ResponseChunkT, None, None],
-            tool_types: list[type[_BaseToolT]] | None,
-            partial_tools: bool = False,
-        ) -> Generator[tuple[_BaseCallResponseChunkT, None], None, None]:
-            for chunk in stream:
-                yield handle_chunk(chunk)
-
-        async def handle_stream_async(
-            stream: AsyncGenerator[_AsyncResponseChunkT, None],
-            tool_types: list[type[_BaseToolT]] | None,
-            partial_tools: bool = False,
-        ) -> AsyncGenerator[tuple[_BaseCallResponseChunkT, None], None]:
-            async for chunk in stream:
-                yield handle_chunk(chunk)
-
-        stream_decorator = stream_factory(
-            TCallResponse=TCallResponse,
-            TStream=TStream,
-            setup_call=setup_call,
-            handle_stream=handle_stream,
-            handle_stream_async=handle_stream_async,
-        )
-
-        tool = setup_extract_tool(response_model, TToolType)
-        stream_decorator_kwargs = {
-            "model": model,
-            "tools": [tool],
-            "json_mode": json_mode,
-            "client": client,
-            "call_params": call_params,
-        }
-        fn._model = model  # pyright: ignore [reportFunctionMemberAccess]
-        fn.__mirascope_call__ = True  # pyright: ignore [reportFunctionMemberAccess]
-        if fn_is_async(fn):
-
-            @wraps(fn)
-            async def inner_async(
-                *args: _P.args, **kwargs: _P.kwargs
-            ) -> AsyncIterable[_ResponseModelT]:
-                fields_from_call_args = get_fields_from_call_args(
-                    response_model, fn, args, kwargs
-                )
-                return BaseStructuredStream[_ResponseModelT](
-                    stream=await stream_decorator(fn=fn, **stream_decorator_kwargs)(
-                        *args, **kwargs
-                    ),
-                    response_model=response_model,
-                    fields_from_call_args=fields_from_call_args,
-                )
-
-            return inner_async
-        else:
-
-            @wraps(fn)
-            def inner(*args: _P.args, **kwargs: _P.kwargs) -> Iterable[_ResponseModelT]:
-                fields_from_call_args = get_fields_from_call_args(
-                    response_model, fn, args, kwargs
-                )
-                return BaseStructuredStream[_ResponseModelT](
-                    stream=stream_decorator(fn=fn, **stream_decorator_kwargs)(
-                        *args, **kwargs
-                    ),
-                    response_model=response_model,
-                    fields_from_call_args=fields_from_call_args,
-                )
-
-            return inner
-
-    return decorator

mirascope/core/base/tool.py

@@ -1,214 +0,0 @@
-"""This module defines the base class for tools used in LLM calls.
-
-usage-docs: learn/tools.md
-"""
-
-from __future__ import annotations
-
-import inspect
-import warnings
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from typing import Any, ClassVar, TypeVar
-
-import jiter
-from pydantic import BaseModel, ConfigDict
-from pydantic.json_schema import (
-    DEFAULT_REF_TEMPLATE,
-    GenerateJsonSchema,
-    JsonSchemaMode,
-    JsonSchemaValue,
-    SkipJsonSchema,
-)
-from pydantic_core.core_schema import CoreSchema
-from typing_extensions import TypedDict
-
-from . import _utils
-
-_BaseToolT = TypeVar("_BaseToolT", bound=BaseModel)
-_ToolSchemaT = TypeVar("_ToolSchemaT")
-
-
-class ToolConfig(TypedDict, total=False):
-    """A base class for tool configurations."""
-
-
-class GenerateJsonSchemaNoTitles(GenerateJsonSchema):
-    _openai_strict: ClassVar[bool] = False
-
-    def _remove_title(self, key: str | None, obj: Any) -> Any:  # noqa: ANN401
-        if isinstance(obj, dict):
-            if self._openai_strict and "type" in obj and obj["type"] == "object":
-                obj["additionalProperties"] = False
-            if "type" in obj or "$ref" in obj or "properties" in obj:
-                title = obj.pop("title", None)
-                if key and title and key.lower() != title.lower():
-                    obj["title"] = title
-
-            for key, value in list(obj.items()):
-                obj[key] = self._remove_title(key, value)
-        elif isinstance(obj, list):
-            return [self._remove_title(None, item) for item in obj]
-
-        return obj
-
-    def generate(
-        self, schema: CoreSchema, mode: JsonSchemaMode = "validation"
-    ) -> JsonSchemaValue:
-        json_schema = super().generate(schema, mode=mode)
-        json_schema.pop("title", None)
-        json_schema.pop("description", None)
-        json_schema = self._remove_title(None, json_schema)
-        return json_schema
-
-
-class BaseTool(BaseModel, ABC):
-    '''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}"
-    ```
-    '''
-
-    __provider__: ClassVar[str] = "NONE"
-    __tool_config_type__: ClassVar[type[ToolConfig]] = ToolConfig
-    __custom_name__: ClassVar[str] = ""
-    tool_config: ClassVar[ToolConfig] = ToolConfig()
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-    delta: SkipJsonSchema[str | None] = None
-
-    @classmethod
-    def _dict_from_json(cls, json: str, allow_partial: bool = False) -> dict[str, Any]:
-        """Returns a dictionary from a JSON string."""
-        if not json:
-            return {}
-        return jiter.from_json(
-            json.encode(), partial_mode="trailing-strings" if allow_partial else "off"
-        )
-
-    @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 not in {"tool_call", "delta"}
-        }
-
-    @property
-    def id(self) -> str | None:
-        """The id of the tool."""
-        if tool_call := getattr(self, "tool_call", None):
-            # Expect tool_call has an id attribute.
-            # If not, we should override this method on the provider tool
-            return getattr(tool_call, "id", None)
-        return None
-
-    @abstractmethod
-    def call(self, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
-        """The method to call the tool."""
-        ...
-
-    @classmethod
-    def type_from_fn(cls: type[_BaseToolT], fn: Callable) -> type[_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)
-
-    @classmethod
-    def type_from_base_model_type(
-        cls: type[_BaseToolT], tool_type: type[BaseModel]
-    ) -> type[_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)
-
-    @classmethod
-    def type_from_base_type(
-        cls: type[_BaseToolT], base_type: type[_utils.BaseType]
-    ) -> type[_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)
-
-    @classmethod
-    def tool_schema(cls) -> Any:  # noqa: ANN401
-        raise RuntimeError(
-            f"{cls.__name__}.tool_schema() is not implemented. "
-            "This method should be implemented in provider-specific tool classes."
-        )
-
-    @classmethod
-    def model_json_schema(
-        cls,
-        by_alias: bool = True,
-        ref_template: str = DEFAULT_REF_TEMPLATE,
-        schema_generator: type[GenerateJsonSchema] = GenerateJsonSchemaNoTitles,
-        mode: JsonSchemaMode = "validation",
-    ) -> dict[str, Any]:
-        """Returns the generated JSON schema for the class."""
-        cls.warn_for_unsupported_configurations()
-        return super().model_json_schema(
-            by_alias=by_alias,
-            ref_template=ref_template,
-            schema_generator=schema_generator,
-            mode=mode,
-        )
-
-    @classmethod
-    def warn_for_unsupported_configurations(cls) -> None:
-        """Warns when a specific provider does not support provided config options."""
-        unsupported_tool_keys = _utils.get_unsupported_tool_config_keys(
-            cls.tool_config, cls.__tool_config_type__
-        )
-        if unsupported_tool_keys:
-            warnings.warn(
-                f"{cls.__provider__} does not support the following tool "
-                f"configurations, so they will be ignored: {unsupported_tool_keys}",
-                UserWarning,
-            )
-
-        if "strict" in cls.model_config and cls.__provider__ not in ["openai", "azure"]:
-            warnings.warn(
-                f"{cls.__provider__} does not support strict structured outputs, but "
-                "you have configured `strict=True` in your `ResponseModelConfigDict`. "
-                "Ignoring `strict` as this feature is only supported by OpenAI.",
-                UserWarning,
-            )

mirascope/core/base/toolkit.py

@@ -1,176 +0,0 @@
-"""The module for defining the toolkit class for LLM call tools.
-
-usage docs: learn/tools.md#toolkit
-"""
-
-from __future__ import annotations
-
-import inspect
-from abc import ABC
-from collections.abc import Callable
-from typing import Any, ClassVar, Concatenate, NamedTuple, TypeVar, cast, overload
-
-from pydantic import BaseModel, ConfigDict, create_model
-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")
-
-
-def is_toolkit_tool(method: Callable[..., Any] | BaseTool) -> bool:
-    return getattr(method, _TOOLKIT_TOOL_METHOD_MARKER, False) is True
-
-
-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}}}}}")
-            if inspect.isclass(method) and issubclass(method, BaseTool):
-                converted_method = create_model(
-                    f"{self.__namespace__}_{method.__name__}",
-                    __doc__=inspect.cleandoc(cast(str, method.__doc__)),
-                    __base__=method,
-                    __module__=method.__module__,
-                )
-            else:
-                converted_method = convert_function_to_base_tool(
-                    method, BaseTool, template.format(self=self), self.__namespace__
-                )
-            for key in dir(self):
-                if not hasattr(converted_method, key):
-                    setattr(converted_method, key, getattr(self, key))
-            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 key in dir(cls):
-            attr = getattr(cls, key)
-            if not is_toolkit_tool(attr):
-                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:].split(".")[0]
-
-                # 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 ABC in cls.__bases__ or any(
-            ABC in base.__bases__ for base in cls.__bases__ if base != BaseToolKit
-        ):
-            return  # Skip if the class is a generic class
-
-        if not cls._toolkit_tool_methods:
-            raise ValueError("No toolkit_tool method found")
-
-
-_BaseToolKitT = TypeVar("_BaseToolKitT", bound=BaseToolKit)
-_BaseToolT = TypeVar("_BaseToolT", bound=BaseTool)
-
-
-@overload
-def toolkit_tool(
-    method: Callable[Concatenate[_BaseToolKitT, P], str],
-) -> Callable[Concatenate[_BaseToolKitT, P], str]: ...
-
-
-@overload
-def toolkit_tool(
-    method: type[_BaseToolT],
-) -> type[_BaseToolT]: ...
-def toolkit_tool(
-    method: Callable[Concatenate[_BaseToolKitT, P], str] | type[_BaseToolT],
-) -> Callable[Concatenate[_BaseToolKitT, P], str] | type[_BaseToolT]:
-    # Mark the method as a toolkit tool
-    setattr(method, _TOOLKIT_TOOL_METHOD_MARKER, True)
-
-    return method