mirascope 1.22.3__tar.gz → 1.22.5__tar.gz

mirascope-1.22.5/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: mirascope
+Version: 1.22.5
+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'
+Requires-Dist: proto-plus>=1.24.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.3.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.22.5/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)  # pragma: no cover
+
+
+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})")

mirascope-1.22.5/docs/generate_provider_examples.py

@@ -0,0 +1,186 @@
+import re
+from pathlib import Path
+
+from mirascope.llm import Provider
+from pydantic import BaseModel
+
+
+class ProviderInfo(BaseModel):
+    """Provider information for UI and substitutions."""
+
+    provider: Provider
+    title: str
+    model: str
+
+
+PROVIDER_INFO: dict[Provider, ProviderInfo] = {
+    "openai": ProviderInfo(provider="openai", title="OpenAI", model="gpt-4o-mini"),
+    "anthropic": ProviderInfo(
+        provider="anthropic", title="Anthropic", model="claude-3-5-sonnet-latest"
+    ),
+    "google": ProviderInfo(provider="google", title="Google", model="gemini-2.0-flash"),
+    "groq": ProviderInfo(
+        provider="groq", title="Groq", model="llama-3.3-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"),
+    "bedrock": ProviderInfo(
+        provider="bedrock",
+        title="Bedrock",
+        model="amazon.nova-lite-v1:0",
+    ),
+}
+
+
+def substitute_provider_import(content: str, provider: Provider) -> str:
+    """Substitute provider in import statement."""
+    return re.sub(
+        r"(from mirascope.core import .*?)openai(.*?)",
+        rf"\1{provider}\2",
+        content,
+    )
+
+
+def substitute_provider_type(content: str, provider: Provider) -> str:
+    """Substitute provider in type names (e.g. openai.OpenAICallResponse)."""
+    provider_name = provider.capitalize()
+
+    if provider == "litellm":
+        provider_name = "LiteLLM"
+    if provider == "openai":
+        provider_name = "OpenAI"
+
+    return re.sub(
+        r"openai\.OpenAI",
+        f"{provider}.{provider_name}",
+        content,
+    )
+
+
+def substitute_llm_call_decorator(content: str, provider: Provider) -> str:
+    """Substitute provider and model into @llm.call decorator."""
+    subs = PROVIDER_INFO[provider]
+
+    # Use regex with re.DOTALL to match across lines
+    decorator_pattern = r"@llm\.call\((.*?)\)"
+
+    def replace_decorator(match: re.Match) -> str:
+        decorator_args = match.group(1)
+
+        # Check if we found the expected parameters
+        if 'provider="openai"' not in decorator_args:
+            raise ValueError(
+                f"Could not find provider='openai' in decorator: {decorator_args}"
+            )
+        if 'model="gpt-4o-mini"' not in decorator_args:
+            raise ValueError(
+                f"Could not find model='gpt-4o-mini' in decorator: {decorator_args}"
+            )
+
+        # Make substitutions, preserving whitespace
+        updated_args = decorator_args.replace(
+            'provider="openai"', f'provider="{subs.provider}"'
+        ).replace('model="gpt-4o-mini"', f'model="{subs.model}"')
+
+        return f"@llm.call({updated_args})"
+
+    # Perform substitution with re.DOTALL flag
+    new_content, _ = re.subn(
+        decorator_pattern, replace_decorator, content, flags=re.DOTALL
+    )
+
+    return new_content
+
+
+def substitute_llm_override(content: str, provider: Provider) -> str:
+    """Substitute provider and model into llm.override function."""
+    replacement_provider = "openai" if provider == "anthropic" else "anthropic"
+    subs = PROVIDER_INFO[replacement_provider]
+
+    # Use regex with re.DOTALL to match across lines
+    override_pattern = r"llm\.override\((.*?)\)"
+
+    def replace_override(match: re.Match) -> str:
+        override_args = match.group(1)
+
+        # Check if we found the expected parameters
+        if 'provider="anthropic"' not in override_args:
+            raise ValueError(
+                f"Could not find provider='anthropic' in override: {override_args}"
+            )
+        if 'model="claude-3-5-sonnet-latest"' not in override_args:
+            raise ValueError(
+                f"Could not find model='claude-3-5-sonnet-latest' in override: {override_args}"
+            )
+
+        # Make substitutions, preserving whitespace
+        updated_args = override_args.replace(
+            'provider="anthropic"', f'provider="{subs.provider}"'
+        ).replace('model="claude-3-5-sonnet-latest"', f'model="{subs.model}"')
+
+        return f"llm.override({updated_args})"
+
+    # Perform substitution with re.DOTALL flag
+    new_content, _ = re.subn(
+        override_pattern, replace_override, content, flags=re.DOTALL
+    )
+
+    return new_content
+
+
+def substitute_provider_specific_content(content: str, provider: Provider) -> str:
+    """Apply all provider-specific substitutions."""
+    if provider not in PROVIDER_INFO:
+        raise ValueError(f"Provider {provider} not found in {PROVIDER_INFO}")
+
+    content = substitute_llm_call_decorator(content, provider)
+    content = substitute_provider_import(content, provider)
+    content = substitute_provider_type(content, provider)
+    content = substitute_llm_override(content, provider)
+    return content
+
+
+SNIPPETS_DIR = Path("build/snippets")
+
+
+def get_supported_providers() -> list[ProviderInfo]:
+    return list(PROVIDER_INFO.values())
+
+
+def generate_provider_examples(
+    *, example_dirs: list[str], examples_root: Path, snippets_dir: Path
+) -> None:
+    """Generate provider-specific examples for python files in configured paths."""
+    # Clear/create snippets directory
+    if snippets_dir.exists():
+        for file in snippets_dir.rglob("*.py"):
+            file.unlink()
+    snippets_dir.mkdir(exist_ok=True, parents=True)
+    supported_providers = get_supported_providers()
+
+    for example_dir in example_dirs:
+        source_dir = examples_root / example_dir
+
+        for info in supported_providers:
+            provider_name = info.provider
+            output_dir = snippets_dir / example_dir / provider_name
+            output_dir.mkdir(parents=True, exist_ok=True)
+
+            for base_file in source_dir.glob("*.py"):
+                content = base_file.read_text()
+                output = substitute_provider_specific_content(content, provider_name)
+
+                out_file = output_dir / base_file.name
+                out_file.write_text(output)
+
+            for override_file in (source_dir / provider_name).glob("*.py"):
+                # If there was a file specified for this provider, use it,
+                # potentially overriding the default content.
+                content = override_file.read_text()
+                out_file = output_dir / override_file.name
+                out_file.write_text(content)