mirascope 1.18.4__tar.gz → 1.19.0__tar.gz

{mirascope-1.18.4 → mirascope-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.18.4
+Version: 1.19.0
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME
@@ -96,6 +96,8 @@ Provides-Extra: tenacity
 Requires-Dist: tenacity<9,>=8.4.2; extra == 'tenacity'
 Provides-Extra: vertex
 Requires-Dist: google-cloud-aiplatform<2,>=1.38.0; extra == 'vertex'
+Provides-Extra: xai
+Requires-Dist: openai<2,>=1.6.0; extra == 'xai'
 Description-Content-Type: text/markdown
 
 <div align="center" justiry="start">

mirascope-1.19.0/docs/api/core/litellm/call.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.call
+
+::: mirascope.core.litellm.call

mirascope-1.19.0/docs/api/core/litellm/call_params.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.call_params
+
+::: mirascope.core.litellm.call_params

mirascope-1.19.0/docs/api/core/litellm/call_response.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.call_response
+
+::: mirascope.core.litellm.call_response

mirascope-1.19.0/docs/api/core/litellm/call_response_chunk.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.call_response_chunk
+
+::: mirascope.core.litellm.call_response_chunk

mirascope-1.19.0/docs/api/core/litellm/dynamic_config.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.dynamic_config
+
+::: mirascope.core.litellm.dynamic_config

mirascope-1.19.0/docs/api/core/litellm/stream.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.stream
+
+::: mirascope.core.litellm.stream

mirascope-1.19.0/docs/api/core/litellm/tool.md

@@ -0,0 +1,3 @@
+# mirascope.core.litellm.tool
+
+::: mirascope.core.litellm.tool

mirascope-1.19.0/docs/api/core/xai/call.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.call
+
+::: mirascope.core.xai.call

mirascope-1.19.0/docs/api/core/xai/call_params.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.call_params
+
+::: mirascope.core.xai.call_params

mirascope-1.19.0/docs/api/core/xai/call_response.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.call_response
+
+::: mirascope.core.xai.call_response

mirascope-1.19.0/docs/api/core/xai/call_response_chunk.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.call_response_chunk
+
+::: mirascope.core.xai.call_response_chunk

mirascope-1.19.0/docs/api/core/xai/dynamic_config.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.dynamic_config
+
+::: mirascope.core.xai.dynamic_config

mirascope-1.19.0/docs/api/core/xai/stream.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.stream
+
+::: mirascope.core.xai.stream

mirascope-1.19.0/docs/api/core/xai/tool.md

@@ -0,0 +1,3 @@
+# mirascope.core.xai.tool
+
+::: mirascope.core.xai.tool

{mirascope-1.18.4 → mirascope-1.19.0}/docs/generate_provider_examples.py

@@ -18,13 +18,14 @@ PROVIDER_INFO: dict[Provider, ProviderInfo] = {
     "anthropic": ProviderInfo(
         provider="anthropic", title="Anthropic", model="claude-3-5-sonnet-latest"
     ),
-    "mistral": ProviderInfo(
-        provider="mistral", title="Mistral", model="mistral-large-latest"
-    ),
     "google": ProviderInfo(provider="google", title="Google", model="gemini-2.0-flash"),
     "groq": ProviderInfo(
         provider="groq", title="Groq", model="llama-3.1-70b-versatile"
     ),
+    "xai": ProviderInfo(provider="xai", title="xAI", model="grok-3"),
+    "mistral": ProviderInfo(
+        provider="mistral", title="Mistral", model="mistral-large-latest"
+    ),
     "cohere": ProviderInfo(provider="cohere", title="Cohere", model="command-r-plus"),
     "litellm": ProviderInfo(provider="litellm", title="LiteLLM", model="gpt-4o-mini"),
     "azure": ProviderInfo(provider="azure", title="Azure AI", model="gpt-4o-mini"),

mirascope-1.19.0/docs/learn/local_models.md

@@ -0,0 +1,44 @@
+---
+search:
+  boost: 3
+---
+
+# Local (Open-Source) Models
+
+{% set local_providers = [("Ollama", "https://github.com/ollama/ollama/blob/main/docs/openai.md"), ("vLLM", "https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html")] %}
+
+You can use the [`llm.call`](../api/llm/call.md) decorator to interact with models running with [Ollama](https://github.com/ollama/ollama) or [vLLM](https://github.com/vllm-project/vllm):
+
+!!! mira ""
+
+    {% for provider, _ in local_providers %}
+    === "{{ provider }}"
+
+        ```python hl_lines="5 20"
+        --8<-- "examples/learn/local_models/{{ provider.lower() }}.py"
+        ```
+
+    {% endfor %}
+
+??? info "Double Check Support"
+
+    The `llm.call` decorator uses OpenAI compatibility under the hood. Of course, not all open-source models or providers necessarily support all of OpenAI's available features, but most use-cases are generally available. See the links we've included below for more details:
+
+    {% for provider, support_url in local_providers %}
+    - [{{ provider }} OpenAI Compatibility]({{ support_url }})
+    {% endfor %}
+
+## OpenAI Compatibility
+
+When hosting (fine-tuned) open-source LLMs yourself locally or in your own cloud with tools that have OpenAI compatibility, you can use the [`openai.call`](../api/core/openai/call.md) decorator with a [custom client](./calls.md#custom-client) to interact with your model using all of Mirascope's various features.
+
+!!! mira ""
+
+    {% for provider, _ in local_providers %}
+    === "{{ provider }}"
+
+        ```python hl_lines="5-8 11 26"
+        --8<-- "examples/learn/local_models/openai_compatibility/{{ provider.lower() }}.py"
+        ```
+    
+    {% endfor %}

mirascope-1.19.0/examples/learn/local_models/ollama.py

@@ -0,0 +1,28 @@
+from mirascope import llm
+from pydantic import BaseModel
+
+
+@llm.call("ollama", "llama3.2")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+recommendation = recommend_book("fantasy")
+print(recommendation)
+# Output: Here are some popular and highly-recommended fantasy books...
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+
+
+@llm.call("ollama", "llama3.2", response_model=Book)
+def extract_book(text: str) -> str:
+    return f"Extract {text}"
+
+
+book = extract_book("The Name of the Wind by Patrick Rothfuss")
+assert isinstance(book, Book)
+print(book)
+# Output: title='The Name of the Wind' author='Patrick Rothfuss'

{mirascope-1.18.4/examples/learn/local_models → mirascope-1.19.0/examples/learn/local_models/openai_compatibility}/ollama.py

@@ -4,7 +4,7 @@ from pydantic import BaseModel
 
 custom_client = OpenAI(
     base_url="http://localhost:11434/v1",  # your ollama endpoint
-    api_key="unused",  # required by openai, but unused
+    api_key="ollama",  # required by openai, but unused
 )
 
 

{mirascope-1.18.4/examples/learn/local_models → mirascope-1.19.0/examples/learn/local_models/openai_compatibility}/vllm.py

@@ -4,7 +4,7 @@ from pydantic import BaseModel
 
 custom_client = OpenAI(
     base_url="http://localhost:8000/v1",  # your vLLM endpoint
-    api_key="unused",  # required by openai, but unused
+    api_key="vllm",  # required by openai, but unused
 )
 
 

mirascope-1.19.0/examples/learn/local_models/vllm.py

@@ -0,0 +1,28 @@
+from mirascope import llm
+from pydantic import BaseModel
+
+
+@llm.call("vllm", "llama3.2")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+recommendation = recommend_book("fantasy")
+print(recommendation)
+# Output: Here are some popular and highly-recommended fantasy books...
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+
+
+@llm.call("vllm", "llama3.2", response_model=Book)
+def extract_book(text: str) -> str:
+    return f"Extract {text}"
+
+
+book = extract_book("The Name of the Wind by Patrick Rothfuss")
+assert isinstance(book, Book)
+print(book)
+# Output: title='The Name of the Wind' author='Patrick Rothfuss'

mirascope-1.19.0/mirascope/core/xai/__init__.py

@@ -0,0 +1,28 @@
+"""The Mirascope xAI Module."""
+
+from typing import TypeAlias
+
+from ..openai import OpenAIMessageParam
+from ._call import xai_call
+from ._call import xai_call as call
+from .call_params import XAICallParams
+from .call_response import XAICallResponse
+from .call_response_chunk import XAICallResponseChunk
+from .dynamic_config import AsyncXAIDynamicConfig, XAIDynamicConfig
+from .stream import XAIStream
+from .tool import XAITool
+
+XAIMessageParam: TypeAlias = OpenAIMessageParam
+
+__all__ = [
+    "AsyncXAIDynamicConfig",
+    "XAICallParams",
+    "XAICallResponse",
+    "XAICallResponseChunk",
+    "XAIDynamicConfig",
+    "XAIMessageParam",
+    "XAIStream",
+    "XAITool",
+    "call",
+    "xai_call",
+]

mirascope-1.19.0/mirascope/core/xai/_call.py

@@ -0,0 +1,67 @@
+"""The `xai_call` decorator for functions as LLM calls."""
+
+from ..base import call_factory
+from ..openai._utils import (
+    get_json_output,
+    handle_stream,
+    handle_stream_async,
+)
+from ._utils import setup_call
+from .call_params import XAICallParams
+from .call_response import XAICallResponse
+from .call_response_chunk import XAICallResponseChunk
+from .stream import XAIStream
+from .tool import XAITool
+
+xai_call = call_factory(
+    TCallResponse=XAICallResponse,
+    TCallResponseChunk=XAICallResponseChunk,
+    TToolType=XAITool,
+    TStream=XAIStream,
+    default_call_params=XAICallParams(),
+    setup_call=setup_call,  # pyright: ignore [reportArgumentType]
+    get_json_output=get_json_output,
+    handle_stream=handle_stream,  # pyright: ignore [reportArgumentType]
+    handle_stream_async=handle_stream_async,  # pyright: ignore [reportArgumentType]
+)
+"""A decorator for calling the xAI API with a typed function.
+
+usage docs: learn/calls.md
+
+This decorator is used to wrap a typed function that calls the xAI API. It parses
+the prompt template 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.xai import xai_call
+
+
+@xai_call("grok-2-latest")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+response = recommend_book("fantasy")
+print(response.content)
+```
+
+Args:
+    model (str): The 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 API call.
+    response_model (BaseModel | BaseType): The response model into which the response
+        should be structured.
+    output_parser (Callable[[OpenAICallResponse | 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 (None): xAI does not support a custom client.
+    call_params (OpenAICallParams): The `OpenAICallParams` call parameters to use in the
+        API call.
+
+Returns:
+    decorator (Callable): The decorator for turning a typed function into a xAI
+        routed LLM API call.
+"""

mirascope-1.19.0/mirascope/core/xai/_utils/__init__.py

@@ -0,0 +1,6 @@
+"""xAI utilities for decorator factories."""
+
+from ._calculate_cost import calculate_cost
+from ._setup_call import setup_call
+
+__all__ = ["calculate_cost", "setup_call"]

mirascope-1.19.0/mirascope/core/xai/_utils/_calculate_cost.py

@@ -0,0 +1,104 @@
+"""Calculate the cost of a Grok API call."""
+
+
+def calculate_cost(
+    input_tokens: int | float | None,
+    cached_tokens: int | float | None,
+    output_tokens: int | float | None,
+    model: str,
+) -> float | None:
+    """Calculate the cost of an xAI Grok API call.
+
+    https://docs.x.ai
+
+    Pricing (per 1M tokens):
+
+    Model                     Input              Cached             Output
+    grok-3                    $3.50              $0.875             $10.50
+    grok-3-latest             $3.50              $0.875             $10.50
+    grok-2                    $2.00              $0.50              $6.00
+    grok-2-latest             $2.00              $0.50              $6.00
+    grok-2-1212               $2.00              $0.50              $6.00
+    grok-2-mini               $0.33              $0.083             $1.00
+    grok-2-vision-1212        $2.00              $0.50              $6.00
+    grok-vision-beta          $5.00              $1.25              $15.00
+    grok-beta                 $5.00              $1.25              $15.00
+
+    Args:
+        input_tokens: Number of input tokens
+        cached_tokens: Number of cached tokens
+        output_tokens: Number of output tokens
+        model: Model name to use for pricing calculation
+
+    Returns:
+        Total cost in USD or None if invalid input
+    """
+    pricing = {
+        "grok-3": {
+            "prompt": 0.000_003_5,
+            "cached": 0.000_000_875,
+            "completion": 0.000_010_5,
+        },
+        "grok-3-latest": {
+            "prompt": 0.000_003_5,
+            "cached": 0.000_000_875,
+            "completion": 0.000_010_5,
+        },
+        "grok-2": {
+            "prompt": 0.000_002,
+            "cached": 0.000_000_5,
+            "completion": 0.000_006,
+        },
+        "grok-latest": {
+            "prompt": 0.000_002,
+            "cached": 0.000_000_5,
+            "completion": 0.000_006,
+        },
+        "grok-2-1212": {
+            "prompt": 0.000_002,
+            "cached": 0.000_000_5,
+            "completion": 0.000_006,
+        },
+        "grok-2-mini": {
+            "prompt": 0.000_000_33,
+            "cached": 0.000_000_083,
+            "completion": 0.000_001,
+        },
+        "grok-2-vision-1212": {
+            "prompt": 0.000_002,
+            "cached": 0.000_000_5,
+            "completion": 0.000_006,
+        },
+        "grok-vision-beta": {
+            "prompt": 0.000_005,
+            "cached": 0.000_001_25,
+            "completion": 0.000_015,
+        },
+        "grok-beta": {
+            "prompt": 0.000_005,
+            "cached": 0.000_001_25,
+            "completion": 0.000_015,
+        },
+    }
+
+    if input_tokens is None or output_tokens is None:
+        return None
+
+    if cached_tokens is None:
+        cached_tokens = 0
+
+    try:
+        model_pricing = pricing[model]
+    except KeyError:
+        return None
+
+    prompt_price = model_pricing["prompt"]
+    cached_price = model_pricing["cached"]
+    completion_price = model_pricing["completion"]
+
+    prompt_cost = input_tokens * prompt_price
+    cached_cost = cached_tokens * cached_price
+    completion_cost = output_tokens * completion_price
+    total_cost = prompt_cost + cached_cost + completion_cost
+
+    return total_cost

mirascope-1.19.0/mirascope/core/xai/_utils/_setup_call.py

@@ -0,0 +1,113 @@
+"""This module contains the setup_call function for OpenAI tools."""
+
+import os
+from collections.abc import Awaitable, Callable
+from typing import Any, overload
+
+from openai import AsyncOpenAI, OpenAI
+from openai.types.chat import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatCompletionMessageParam,
+)
+from pydantic import BaseModel
+
+from ...base import BaseTool
+from ...base._utils import AsyncCreateFn, CreateFn, fn_is_async
+from ...base.call_params import CommonCallParams
+from ...base.stream_config import StreamConfig
+from ...openai import (
+    AsyncOpenAIDynamicConfig,
+    OpenAICallParams,
+    OpenAIDynamicConfig,
+    OpenAITool,
+)
+from ...openai._call_kwargs import OpenAICallKwargs
+from ...openai._utils import setup_call as setup_call_openai
+
+
+@overload
+def setup_call(
+    *,
+    model: str,
+    client: AsyncOpenAI | None,
+    fn: Callable[..., Awaitable[AsyncOpenAIDynamicConfig]],
+    fn_args: dict[str, Any],
+    dynamic_config: AsyncOpenAIDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: OpenAICallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    AsyncCreateFn[ChatCompletion, ChatCompletionChunk],
+    str | None,
+    list[ChatCompletionMessageParam],
+    list[type[OpenAITool]] | None,
+    OpenAICallKwargs,
+]: ...
+
+
+@overload
+def setup_call(
+    *,
+    model: str,
+    client: OpenAI | None,
+    fn: Callable[..., OpenAIDynamicConfig],
+    fn_args: dict[str, Any],
+    dynamic_config: OpenAIDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: OpenAICallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    CreateFn[ChatCompletion, ChatCompletionChunk],
+    str | None,
+    list[ChatCompletionMessageParam],
+    list[type[OpenAITool]] | None,
+    OpenAICallKwargs,
+]: ...
+
+
+def setup_call(
+    *,
+    model: str,
+    client: OpenAI | AsyncOpenAI | None,
+    fn: Callable[..., OpenAIDynamicConfig]
+    | Callable[..., Awaitable[AsyncOpenAIDynamicConfig]],
+    fn_args: dict[str, Any],
+    dynamic_config: OpenAIDynamicConfig | AsyncOpenAIDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: OpenAICallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    CreateFn[ChatCompletion, ChatCompletionChunk]
+    | AsyncCreateFn[ChatCompletion, ChatCompletionChunk],
+    str | None,
+    list[ChatCompletionMessageParam],
+    list[type[OpenAITool]] | None,
+    OpenAICallKwargs,
+]:
+    if not client:
+        api_key = os.environ.get("XAI_API_KEY")
+        client = (
+            AsyncOpenAI(api_key=api_key, base_url="https://api.x.ai/v1")
+            if fn_is_async(fn)
+            else OpenAI(api_key=api_key, base_url="https://api.x.ai/v1")
+        )
+    create, prompt_template, messages, tool_types, call_kwargs = setup_call_openai(
+        model=model,  # pyright: ignore [reportCallIssue]
+        client=client,  # pyright: ignore [reportArgumentType]
+        fn=fn,  # pyright: ignore [reportArgumentType]
+        fn_args=fn_args,  # pyright: ignore [reportArgumentType]
+        dynamic_config=dynamic_config,
+        tools=tools,
+        json_mode=json_mode,
+        call_params=call_params,
+        response_model=response_model,
+        stream=stream,
+    )
+    return create, prompt_template, messages, tool_types, call_kwargs

mirascope-1.19.0/mirascope/core/xai/call_params.py

@@ -0,0 +1,10 @@
+"""usage docs: learn/calls.md#provider-specific-parameters"""
+
+from ..openai import OpenAICallParams
+
+
+class XAICallParams(OpenAICallParams):
+    """A simple wrapper around `OpenAICallParams.`
+
+    Since xAI supports the OpenAI spec, we change nothing here.
+    """

mirascope-1.19.0/mirascope/core/xai/call_response.py

@@ -0,0 +1,27 @@
+"""This module contains the `XAICallResponse` class.
+
+usage docs: learn/calls.md#handling-responses
+"""
+
+from pydantic import computed_field
+
+from ..openai import OpenAICallResponse
+from ._utils import calculate_cost
+
+
+class XAICallResponse(OpenAICallResponse):
+    """A simpler wrapper around `OpenAICallResponse`.
+
+    Everything is the same except the `cost` property, which has been updated to use
+    xAI's cost calculations so that cost tracking works for non-OpenAI models.
+    """
+
+    _provider = "xai"
+
+    @computed_field
+    @property
+    def cost(self) -> float | None:
+        """Returns the cost of the call."""
+        return calculate_cost(
+            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
+        )

mirascope-1.19.0/mirascope/core/xai/call_response_chunk.py

@@ -0,0 +1,14 @@
+"""This module contains the `XAICallResponseChunk` class.
+
+usage docs: learn/streams.md#handling-streamed-responses
+"""
+
+from ..openai import OpenAICallResponseChunk
+
+
+class XAICallResponseChunk(OpenAICallResponseChunk):
+    """A simpler wrapper around `OpenAICallResponse`.
+
+    Everything is the same except the `cost` property, which has been updated to use
+    xAI's cost calculations so that cost tracking works for non-OpenAI models.
+    """

mirascope-1.19.0/mirascope/core/xai/dynamic_config.py

@@ -0,0 +1,8 @@
+"""This module defines the function return type for functions as LLM calls."""
+
+from typing import TypeAlias
+
+from ..openai import AsyncOpenAIDynamicConfig, OpenAIDynamicConfig
+
+AsyncXAIDynamicConfig: TypeAlias = AsyncOpenAIDynamicConfig
+XAIDynamicConfig: TypeAlias = OpenAIDynamicConfig