mirascope 1.19.0__tar.gz → 1.20.1__tar.gz

mirascope-1.20.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: mirascope
+Version: 1.20.1
+Summary: LLM abstractions that aren't obstructions
+Project-URL: Homepage, https://mirascope.com
+Project-URL: Documentation, https://mirascope.com/WELCOME
+Project-URL: Repository, https://github.com/Mirascope/mirascope
+Project-URL: Issues, https://github.com/Mirascope/mirascope/issues
+Project-URL: Changelog, https://github.com/Mirascope/mirascope/releases
+Author-email: William Bakst <william@mirascope.com>, Brendan Kao <brendan@mirascope.com>
+Maintainer-email: William Bakst <william@mirascope.com>
+License: MIT License
+        
+        Copyright (c) 2023 Mirascope, Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,anthropic,artificial intelligence,bedrock,cohere,developer tools,gemini,groq,llm,llm tools,mistral,openai,prompt engineering,pydantic,vertex
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: File Formats :: JSON
+Classifier: Topic :: File Formats :: JSON :: JSON Schema
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: docstring-parser<1.0,>=0.15
+Requires-Dist: jiter>=0.5.0
+Requires-Dist: pydantic<3.0,>=2.7.4
+Requires-Dist: typing-extensions>=4.10.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0,>=0.29.0; extra == 'anthropic'
+Provides-Extra: azure
+Requires-Dist: aiohttp<4.0,>=3.10.5; extra == 'azure'
+Requires-Dist: azure-ai-inference<2.0,>=1.0.0b4; extra == 'azure'
+Provides-Extra: bedrock
+Requires-Dist: aioboto3<14,>=13.1.1; extra == 'bedrock'
+Requires-Dist: boto3-stubs[bedrock-runtime]<2,>=1.35.32; extra == 'bedrock'
+Requires-Dist: boto3<2,>=1.34.70; extra == 'bedrock'
+Requires-Dist: types-aioboto3[bedrock-runtime]<14,>=13.1.1; extra == 'bedrock'
+Provides-Extra: cohere
+Requires-Dist: cohere<6,>=5.5.8; extra == 'cohere'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai<1,>=0.4.0; extra == 'gemini'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'gemini'
+Provides-Extra: google
+Requires-Dist: google-genai<2,>=1.2.0; extra == 'google'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'google'
+Provides-Extra: groq
+Requires-Dist: groq<1,>=0.9.0; extra == 'groq'
+Provides-Extra: hyperdx
+Requires-Dist: hyperdx-opentelemetry<1,>=0.1.0; extra == 'hyperdx'
+Provides-Extra: langfuse
+Requires-Dist: langfuse<3,>=2.30.0; extra == 'langfuse'
+Provides-Extra: litellm
+Requires-Dist: litellm<2,>=1.42.12; extra == 'litellm'
+Provides-Extra: logfire
+Requires-Dist: logfire<4,>=1.0.0; extra == 'logfire'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: mistral
+Requires-Dist: mistralai<2,>=1.0.0; extra == 'mistral'
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.6.0; extra == 'openai'
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api<2,>=1.22.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-sdk<2,>=1.22.0; extra == 'opentelemetry'
+Provides-Extra: realtime
+Requires-Dist: numpy<2,>=1.26.4; extra == 'realtime'
+Requires-Dist: pydub<1,>=0.25.1; extra == 'realtime'
+Requires-Dist: sounddevice<1,>=0.5.1; extra == 'realtime'
+Requires-Dist: websockets<14,>=13.1; extra == 'realtime'
+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">
+    <a href="https://mirascope.com">
+        <img align="bottom" src="https://github.com/Mirascope/mirascope/assets/99370834/e403d7ee-f8bc-4df1-b2d0-33763f021c89" alt="Frog Logo" width="84"/><br><img align="bottom" src="https://uploads-ssl.webflow.com/65a6fd6a1c3b2704d6217d3d/65b5674e9ceef563dc57eb11_Medium%20length%20hero%20headline%20goes%20here.svg" width="400" alt="Mirascope"/>
+    </a>
+</div>
+
+<p align="center">
+    <a href="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml" target="_blank"><img src="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests"/></a>
+    <a href="https://codecov.io/github/Mirascope/mirascope" target="_blank"><img src="https://codecov.io/github/Mirascope/mirascope/graph/badge.svg?token=HAEAWT3KC9" alt="Coverage"/></a>
+    <a href="https://mirascope.com/WELCOME" target="_blank"><img src="https://img.shields.io/badge/docs-available-brightgreen" alt="Docs"/></a>
+    <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/v/mirascope.svg" alt="PyPI Version"/></a>
+    <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/pyversions/mirascope.svg" alt="Stars"/></a>
+    <a href="https://github.com/Mirascope/mirascope/blog/dev/LICENSE"><img src="https://img.shields.io/github/license/Mirascope/mirascope.svg" alt="License"/></a>
+    <a href="https://github.com/Mirascope/mirascope/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/Mirascope/mirascope.svg" alt="Stars"/></a>
+</p>
+
+---
+
+Mirascope is a powerful, flexible, and user-friendly library that simplifies the process of working with LLMs through a unified interface that works across various supported providers, including [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Mistral](https://mistral.ai/), [Google (Gemini/Vertex)](https://googleapis.github.io/python-genai/), [Groq](https://groq.com/), [Cohere](https://cohere.com/), [LiteLLM](https://www.litellm.ai/), [Azure AI](https://azure.microsoft.com/en-us/solutions/ai), and [Bedrock](https://aws.amazon.com/bedrock/).
+
+Whether you're generating text, extracting structured information, or developing complex AI-driven agent systems, Mirascope provides the tools you need to streamline your development process and create powerful, robust applications.
+
+## 30 Second Quickstart
+
+Install Mirascope, specifying the provider(s) you intend to use, and set your API key:
+
+```bash
+pip install "mirascope[openai]"
+export OPENAI_API_KEY=XXXXX
+```
+
+Make your first call to an LLM to extract the title and author of a book from unstructured text:
+
+```python
+from mirascope import llm
+from pydantic import BaseModel
+
+class Book(BaseModel):
+    title: str
+    author: str
+
+@llm.call(provider="openai", model="gpt-4o-mini", 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'
+```
+
+## Tutorials
+
+Check out our [quickstart tutorial](https://mirascope.com/tutorials/getting_started/quickstart) and many other tutorials for an interactive way to getting started with Mirascope.
+
+## Usage
+
+For a complete guide on how to use all of the various features Mirascope has to offer, read through our [Learn](https://mirascope.com/learn) documentation.
+
+## Versioning
+
+Mirascope uses [Semantic Versioning](https://semver.org/).
+
+## Licence
+
+This project is licensed under the terms of the [MIT License](https://github.com/Mirascope/mirascope/blob/dev/LICENSE).

mirascope-1.20.1/docs/WHY.md

@@ -0,0 +1,245 @@
+# Why Use Mirascope?
+
+Trusted by founders and engineers building the next generation of AI-native applications:
+
+<div class="grid cards" markdown>
+
+-   __Jake Duth__
+
+    ---
+
+    Co-Founder & CTO / Reddy
+
+    ---
+
+    "Mirascope's simplicity made it the natural next step from OpenAI's API — all without fighting the unnecessary complexity of tools like LangChain. We have all the bells and whistles we need for production while maintaining exceptional ease of use."
+
+-   __Vince Trost__
+
+    ---
+
+    Co-Founder / Plastic Labs
+
+    ---
+
+    "The Pydantic inspired LLM toolkit the space has been missing. Simple, modular, extensible...helps where you need it, stays out of your way when you don't."
+
+-   __Skylar Payne__
+
+    ---
+
+    VP of Engineering & DS / Health Rhythms
+
+    ---
+
+    "Mirascope's 'abstractions that aren't obstructions' tagline rings true – I was up and running in minutes, with seamless switching between AI providers. The type system catches any schema issues while I iterate, letting me focus entirely on crafting the perfect prompts."
+
+-   __Off Sornsoontorn__
+
+    ---
+
+    Senior AI & ML Engineer / Six Atomic
+
+    ---
+
+    "LangChain required learning many concepts and its rigid abstractions made LLM behavior hard to customize. Mirascope lets us easily adapt LLM behaviors to any UI/UX design, so we can focus on innovation rather than working around limitations."
+
+-   __William Profit__
+
+    ---
+
+    Co-Founder / Callisto
+
+    ---
+
+    "After trying many alternatives, we chose Mirascope for our large project and haven't looked back. It's simple, lean, and gets the job done without getting in the way. The team & community are super responsive, making building even easier."
+
+-   __Rami Awar__
+
+    ---
+
+    Founder / DataLine
+
+    ---
+
+    "Migrating DataLine to Mirascope feels like I was rid of a pebble in my shoe that I never knew existed. This is what good design should feel like. Well done."
+
+</div>
+
+## Abstractions That Aren't Obstructions
+
+Mirascope provides powerful abstractions that simplify LLM interactions without hiding the underlying mechanics. This approach gives you the convenience of high-level APIs while maintaining full control and transparency.
+
+### Everything Beyond The Prompt Is Boilerplate
+
+By eliminating boilerplate, Mirascope allows you to focus on what matter most: your prompt.
+
+Let's compare structured outputs using Mirascope vs. the official SDKs:
+
+!!! mira "Mirascope"
+
+    {% for provider in supported_llm_providers %}
+    === "{{ provider }}"
+
+        ```python hl_lines="12 19"
+        --8<-- "build/snippets/learn/response_models/basic_usage/{{ provider | provider_dir }}/shorthand.py:3:21"
+        ```
+    {% endfor %}
+
+!!! note "Official SDK"
+
+    {% for provider in supported_llm_providers %}
+    === "{{ provider }}"
+
+        {% if provider == "Anthropic" %}
+        ```python hl_lines="19-38 43"
+        {% elif provider == "Mistral" %}
+        ```python hl_lines="21-46 51"
+        {% elif provider == "Gemini" %}
+        ```python hl_lines="19-57 62"
+        {% elif provider == "Cohere" %}
+        ```python hl_lines="19-36 41"
+        {% elif provider == "LiteLLM" %}
+        ```python hl_lines="16-37 42"
+        {% elif provider == "Azure AI" %}
+        ```python hl_lines="26-46 51"
+        {% elif provider == "Vertex AI" %}
+        ```python hl_lines="23-62 67"
+        {% elif provider == "Bedrock" %}
+        ```python hl_lines="17-48 53"
+        {% else %}
+        ```python hl_lines="18-39 44"
+        {% endif %}
+        --8<-- "examples/learn/response_models/basic_usage/official_sdk/{{ provider | provider_dir }}_sdk.py"
+        ```
+
+    {% endfor %}
+
+Reducing this boilerplate becomes increasingly important as the number and complexity of your calls grows beyond a single basic example. Furthermore, the Mirascope interface works across all of our various supported providers, so you don't need to learn the intracacies of each provider to use them the same way.
+
+### Functional, Modular Design
+
+Mirascope's functional approach promotes modularity and reusability. You can easily compose and chain LLM calls, creating complex workflows with simple, readable code:
+
+!!! mira ""
+
+    === "Separate Calls"
+
+        {% for provider in supported_llm_providers %}
+        === "{{ provider }}"
+
+            {% if method == "string_template" %}
+            ```python hl_lines="6 11 14-15"
+            {% elif method == "base_message_param" %}
+            ```python hl_lines="5 10 19-20"
+            {% else %}
+            ```python hl_lines="5 10 14-15"
+            {% endif %}
+            --8<-- "build/snippets/learn/chaining/function_chaining/{{ provider | provider_dir }}/shorthand.py"
+            ```
+        {% endfor %}
+
+    === "Nested Calls"
+
+        {% for provider in supported_llm_providers %}
+        === "{{ provider }}"
+
+            {% if method == "string_template" %}
+            ```python hl_lines="6 10 12 15"
+            {% elif method == "base_message_param" %}
+            ```python hl_lines="5 11 15 20"
+            {% else %}
+            ```python hl_lines="5 11-12 15"
+            {% endif %}
+            --8<-- "build/snippets/learn/chaining/nested_chains/{{ provider | provider_dir }}/shorthand.py"
+            ```
+        {% endfor %}
+
+The goal of our design approach is to remain __Pythonic__ so you can __build your way__.
+
+### Provider-Agnostic When Wanted, Specific When Needed
+
+We understand the desire for easily switching between various LLM providers. We also understand the (common) need to engineer a prompt for a specific provider (and model).
+
+By implementing our LLM API call functionality as decorators, Mirascope makes implementing any and all of these paths straightforward and easy:
+
+!!! mira ""
+
+    === "Provider-Specific"
+
+        ```python hl_lines="4-5 9-10 14 17"
+        from mirascope.core import anthropic, openai
+
+
+        @openai.call("gpt-4o-mini")
+        def openai_recommend_book(genre: str) -> str:
+            return f"Recommend a {genre} book"
+
+
+        @anthropic.call("claude-3-5-sonnet-20240620")
+        def anthropic_recommend_book(genre: str) -> str:
+            return f"Recommend a {genre} book"
+
+
+        openai_response = openai_recommend_book("fantasy")
+        print(openai_response.content)
+
+        anthropic_response = anthropic_recommend_book("fantasy")
+        print(anthropic_response.content)
+        ```
+
+    === "Provider-Agnostic"
+
+        ```python hl_lines="4-5 11-12 17-18"
+        from mirascope.core import anthropic, openai, prompt_template
+
+
+        @prompt_template()
+        def recommend_book_prompt(genre: str) -> str:
+            return f"Recommend a {genre} book"
+
+
+        # OpenAI
+        openai_model = "gpt-4o-mini"
+        openai_recommend_book = openai.call(openai_model)(recommend_book_prompt)
+        openai_response = openai_recommend_book("fantasy")
+        print(openai_response.content)
+
+        # Anthropic
+        anthropic_model = "claude-3-5-sonnet-20240620"
+        anthropic_recommend_book = anthropic.call(anthropic_model)(recommend_book_prompt)
+        anthropic_response = anthropic_recommend_book("fantasy")
+        print(anthropic_response.content)
+        ```
+
+### Type Hints & Editor Support
+
+<div class="grid cards" markdown>
+
+- :material-shield-check: __Type Safety__ to catch errors before runtime during lint
+- :material-lightbulb-auto: __Editor Support__ for rich autocomplete and inline documentation
+
+</div>
+
+<video src="https://github.com/user-attachments/assets/174acc23-a026-4754-afd3-c4ca570a9dde" controls="controls" style="max-width: 730px;"></video>
+
+## Who Should Use Mirascope?
+
+Mirascope is __designed for everyone__ to use!
+
+However, we believe that the value of Mirascope will shine in particular for:
+
+- __Professional Developers__: Who need fine-grained control and transparency in their LLM interactions.
+- __AI Application Builders__: Looking for a tool that can grow with their project from prototype to production.
+- __Teams__: Who value clean, maintainable code and want to avoid the "black box" problem of many AI frameworks.
+- __Researchers and Experimenters__: Who need the flexibility to quickly try out new ideas without fighting their tools.
+
+## Getting Started
+
+[:material-clock-fast: Getting Started](./index.md){: .md-button }
+[:material-school: Learn](./learn/index.md){: .md-button }
+[:material-account-group: Join Our Community](https://join.slack.com/t/mirascope-community/shared_invite/zt-2ilqhvmki-FB6LWluInUCkkjYD3oSjNA){: .md-button }
+
+By choosing Mirascope, you're opting for a tool that respects your expertise as a developer while providing the conveniences you need to work efficiently and effectively with LLMs.
+
+We believe the best tools get out of your way and let you focus on building great applications.

mirascope-1.20.1/docs/api/core/base/types.md

@@ -0,0 +1,3 @@
+# mirascope.core.base.types
+
+::: mirascope.core.base.types

mirascope-1.20.1/docs/api/core/costs/calculate_cost.md

@@ -0,0 +1,3 @@
+# mirascope.core.costs.calculate_cost
+
+::: mirascope.core.costs.calculate_cost

mirascope-1.20.1/docs/find_missing_snippets.py

@@ -0,0 +1,141 @@
+"""Scope:
+Finds every code import in docs/learn/**/*.md, and checks that the target file exists.
+
+Usage: python -m docs.find_missing_snippets
+
+Note: The script depends on hand-maintained substitutions
+in FILE_SPECIFIC_SUBSTITUTUTIONS, which may require updates as documents
+are changed or updated. There is automated testing to ensure that all new
+imports exist, which will fail if FILE_SPECIFIC_SUBSTITUTUTIONS is not updated.
+"""
+
+import re
+from collections.abc import Iterable
+from itertools import product
+from pathlib import Path
+
+# Define the namedtuple
+from typing import Dict, List, NamedTuple
+
+import yaml
+from docs.generate_provider_examples import (
+    generate_provider_examples,
+)
+
+Substitutions = Dict[str, List[str]]
+
+
+# Hardcoded list of which docs files have non-standard substitutions,
+# which we maintain by hand because this changes infrequently and implementing a general
+# solution via parsing the jinja2 templates and environment is overkill.
+FILE_SPECIFIC_SUBSTITUTIONS: dict[str, Substitutions] = {
+    "docs/learn/tools.md": {
+        "{{ tool_method }}": ["base_tool", "function"],
+        "{{ pre_made_tool_method }}": ["basic_usage", "custom_config"],
+    },
+    "docs/learn/local_models.md": {
+        "{{ provider.lower() }}": ["ollama", "vllm"],
+    },
+    "docs/learn/prompts.md": {
+        "{{ audio_pkg }}": ["pydub", "wave"],
+        "{{ filename }}": ["lists", "texts", "parts"],
+    },
+}
+
+
+def extact_yaml_section(file_path, section_name):
+    # Manually get some info from yaml files, as mkdocs.yml is not easy to parse
+    section_lines = []
+    in_section = False
+    section_indent = None
+
+    with open(file_path, "r") as file:
+        section_indent = 0
+        for line in file:
+            if line.lstrip().startswith(section_name + ":"):
+                in_section = True
+                section_indent = len(line) - len(line.lstrip())
+                continue
+
+            if in_section:
+                current_indent = len(line) - len(line.lstrip())
+                if current_indent > section_indent:
+                    section_lines.append(line)
+                else:
+                    break
+
+    section_content = "\n".join(section_lines)
+    return yaml.safe_load(section_content) if section_lines else []
+
+
+CONFIG_FILE = Path("mkdocs.yml")
+PROVIDERS = [
+    p.split()[0].lower()
+    for p in extact_yaml_section(CONFIG_FILE, "supported_llm_providers")
+]
+BASE_SUBSTITUTIONS = {
+    "{{ provider | provider_dir }}": PROVIDERS,
+    "{{ method }}": extact_yaml_section(CONFIG_FILE, "prompt_writing_methods"),
+}
+
+
+class Snippet(NamedTuple):
+    path: Path
+    source_file: Path
+
+
+def substituted_snippet_paths(
+    markdown_content: str, substitutions: dict[str, list[str]]
+) -> Iterable[Path]:
+    pattern = r'--8<--\s*"([^"]+\.py(?::\d+(?::\d+)?)?)"'
+    # Extract paths and strip line numbers
+    paths = {
+        match.group(1).split(":")[0] for match in re.finditer(pattern, markdown_content)
+    }
+
+    for path in paths:
+        # Find all keys in the import path that need substitution
+        keys_to_substitute = [key for key in substitutions if key in path]
+
+        # Generate all combinations of substitutions for the keys
+        substitution_combinations = product(
+            *(substitutions[key] for key in keys_to_substitute)
+        )
+
+        for combination in substitution_combinations:
+            # Create a new path with all substitutions applied
+            new_path = path
+            for key, value in zip(keys_to_substitute, combination):
+                new_path = new_path.replace(key, value)
+
+            yield Path(new_path)
+
+
+def missing_snippets_for_file(
+    markdown_path: Path, substitutions: dict[str, list[str]]
+) -> Iterable[Snippet]:
+    markdown_content = markdown_path.read_text()
+    for path in substituted_snippet_paths(markdown_content, substitutions):
+        if not path.exists():
+            yield Snippet(path, markdown_path)
+
+
+def all_missing_snippets(root_dir: Path) -> Iterable[Snippet]:
+    provider_example_dirs = extact_yaml_section(CONFIG_FILE, "provider_example_dirs")
+    generate_provider_examples(
+        example_dirs=provider_example_dirs,
+        examples_root=root_dir / "examples",
+        snippets_dir=root_dir / "build/snippets",
+    )
+    for md_path in root_dir.glob("docs/**/*.md"):
+        relative_path = md_path.relative_to(root_dir)
+        substitutions = {
+            **BASE_SUBSTITUTIONS,
+            **FILE_SPECIFIC_SUBSTITUTIONS.get(str(relative_path), {}),
+        }
+        yield from missing_snippets_for_file(md_path, substitutions)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    for imp in all_missing_snippets(Path(".")):
+        print(f"Missing import: {imp.path} (from {imp.source_file})")