mirascope 2.1.1__tar.gz → 2.2.0__tar.gz

mirascope-2.2.0/.coveragerc

@@ -0,0 +1,45 @@
+[run]
+# Exclude modules from coverage tracking until they have full test coverage
+# Remove items from this list as we add comprehensive tests for each module
+# Goal: When this exclude list is empty, we have 100% coverage across the entire codebase
+omit =
+
+    # NOTE: MLX modules are excluded because the `mlx` package is macOS-only (Apple Silicon).
+    # CI runs on Linux where `mlx` is not available, so these modules cannot be tested there.
+    # TODO: Add a macOS CI job to run MLX tests and restore coverage for these modules.
+    mirascope/llm/providers/mlx/*
+
+    # Exclude Fern generated code
+    mirascope/api/_generated/*
+
+    # Exclude other top-level modules for now
+    mirascope/graphs/*
+    
+    # Exclude examples, tests, and scripts from coverage
+    examples/*
+    tests/*
+    scripts/*
+
+[report]
+# Show lines that weren't covered
+show_missing = True
+
+# Fail if coverage is below 100% for tracked files
+fail_under = 100
+
+# Exclude patterns from coverage analysis
+exclude_also =
+    pragma: no cover
+    def __repr__
+    if self.debug:
+    if settings.DEBUG
+    raise AssertionError
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    class .*\bProtocol\):
+    @(abc\.)?abstractmethod
+    if TYPE_CHECKING:
+    @overload
+
+[html]
+directory = htmlcov

mirascope-2.2.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: mirascope
+Version: 2.2.0
+Summary: Every frontier LLM. One unified interface.
+Project-URL: Homepage, https://mirascope.com
+Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2
+Project-URL: Repository, https://github.com/Mirascope/mirascope/tree/v2
+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>, Dandelion Mané <dandelion@mirascope.com>
+Maintainer-email: William Bakst <william@mirascope.com>, Dandelion Mané <dandelion@mirascope.com>
+License: MIT License
+        
+        Copyright (c) 2026 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,context engineering,developer tools,gemini,llm,llm tools,openai,prompt engineering
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.14
+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>=0.17.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jiter>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.10.0
+Provides-Extra: all
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'all'
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'all'
+Requires-Dist: libcst>=1.8.6; extra == 'all'
+Requires-Dist: mcp<2,>=1.25.0; extra == 'all'
+Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'all'
+Requires-Dist: openai<3,>=2.15.0; extra == 'all'
+Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-jaeger>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk<2,>=1.38.0; extra == 'all'
+Requires-Dist: orjson>=3.11.4; extra == 'all'
+Requires-Dist: packaging>=25.0; extra == 'all'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'all'
+Requires-Dist: proto-plus>=1.24.0; extra == 'all'
+Requires-Dist: pydantic-settings>=2.12.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'anthropic'
+Provides-Extra: api
+Requires-Dist: pydantic-settings>=2.12.0; extra == 'api'
+Provides-Extra: google
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'google'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'google'
+Requires-Dist: proto-plus>=1.24.0; extra == 'google'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.25.0; extra == 'mcp'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'mlx'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.15.0; extra == 'openai'
+Provides-Extra: ops
+Requires-Dist: libcst>=1.8.6; extra == 'ops'
+Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-jaeger>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-sdk<2,>=1.38.0; extra == 'ops'
+Requires-Dist: orjson>=3.11.4; extra == 'ops'
+Requires-Dist: packaging>=25.0; extra == 'ops'
+Description-Content-Type: text/markdown
+
+# Mirascope Python
+
+This directory contains the Python implementation of Mirascope: The LLM Anti-Framework. It's intended as a "Goldilocks API" that affords the fine-grained control you'd get from using raw provider APIs, as well as the type safety and easy ergonomics that are offered by higher-level agent frameworks. Think of Mirascope as the "React" of LLM development, where provider native APIs are HTML/CSS, and the agent frameworks are Angular.
+
+## Documentation 
+
+- [Why use Mirascope?](https://mirascope.com/docs/why)
+- [Mirascope Quickstart](https://mirascope.com/docs/quickstart)
+- [Mirascope Concepts](https://mirascope.com/docs/learn/llm)
+
+## Installation
+
+```bash
+# using uv, with all provider deps
+uv add "mirascope[all]"
+
+# using uv, with just Anthropic
+uv add "mirascope[anthropic]"
+
+# using pip, with all deps 
+pip install "mirascope[all]"
+
+# using pip, just OpenAI
+pip install "mirascope[openai]"
+```
+
+## Usage
+
+Here's an example of creating a simple agent, with tool-calling and streaming, using Mirascope. For many more examples, [read the docs](https://mirascope.com/docs).
+
+```python
+from mirascope import llm
+
+@llm.tool
+def exp(a: float, b: float) -> float:
+   """Compute an exponent"""
+   return a ** b
+
+@llm.tool
+def add(a: float, b: float) -> float:
+   """Add two numbers"""
+   return a + b
+
+model = llm.Model("anthropic/claude-haiku-4-5")
+response = model.stream("What is 42 ** 4 + 37 ** 3?", tools=[exp, add])
+
+while True:
+   for stream in response.streams():
+         if stream.content_type == "text":
+            for delta in stream:
+               print(delta, end="", flush=True)
+         elif stream.content_type == "tool_call":
+            stream.collect()  # consume the stream
+            print(f"\n> Calling {stream.tool_name}({stream.partial_args})")
+   print()
+   if response.tool_calls:
+         response = response.resume(response.execute_tools())
+   else:
+         break
+```
+
+## Development Setup
+
+1. **Environment Variables**: Copy `.env.example` to `.env` and fill in your API keys:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   # Necessary for updating e2e snapshot tests
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   cd python
+   uv sync --all-extras --dev
+   ```
+
+## Helpful Commands:
+
+Here are helpful development commands. All must be run from within the `python` directory.
+
+- `uv run pyright .`
+
+Run typechecking.
+
+- `uv run ruff check --fix .`
+
+Check ruff linter (fixing issues where possible).
+
+- `uv run ruff format .`
+
+Run ruff formatter.
+
+- `uv run pytest`
+
+Run all Python unit tests.
+
+- `uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+Run all Python unit tests, and report code coverage. (We require 100% coverage in CI.)
+
+- `uv run pytest --fix`
+
+Run all Python unit tests, and update any changed snapshots.
+
+- `uvx codespell --config ../.codespellrc`
+
+Run codespell, identifying many common spelling mistakes.
+
+## Typechecking
+
+We prize type safety, both on the API surface and internally. You can run typechecking via `uv run pyright .` within this `python/` directory. (We're looking into supporting `ty` so as to speed up our typechecking.)
+
+## Testing
+
+This project makes extensive use of e2e tests, which replay real interactions with various LLM providers to ensure that Mirascope truly works on the providers' APIs. We use [VCR.py](https://vcrpy.readthedocs.io/) and [inline-snapshot](https://15r10nk.github.io/inline-snapshot/) to maintain these e2e tests. For more details, read [tests/e2e/README.md](./tests/e2e/README.md).
+
+If you make changes to Mirascope that require new snapshots, you should manually delete the outdated cassette files, and then run `uv run pytest python/tests/e2e --fix`. Note that doing so requires real API keys in your `.env` file.
+
+We require 100% code coverage in CI. You can get a code coverage report via:
+
+`uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+## Read More
+
+For more info on contributing, read [the contributing page in our docs](https://mirascope.com/docs/contributing).

mirascope-2.2.0/examples/reliability/basic_call.py

@@ -0,0 +1,12 @@
+from mirascope import llm
+
+
+@llm.retry()
+@llm.call("openai/gpt-4o-mini")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+response = recommend_book("fantasy")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/basic_model.py

@@ -0,0 +1,6 @@
+from mirascope import llm
+
+model = llm.retry_model("openai/gpt-4o-mini")
+response = model.call("Recommend a fantasy book")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/basic_prompt.py

@@ -0,0 +1,12 @@
+from mirascope import llm
+
+
+@llm.retry()
+@llm.prompt
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+response = recommend_book("openai/gpt-4o-mini", "fantasy")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/fallback_call.py

@@ -0,0 +1,17 @@
+from mirascope import llm
+
+
+@llm.retry(
+    fallback_models=[
+        "anthropic/claude-3-5-haiku-latest",
+        "google/gemini-2.0-flash",
+    ]
+)
+@llm.call("openai/gpt-4o-mini")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+response = recommend_book("fantasy")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/fallback_model.py

@@ -0,0 +1,12 @@
+from mirascope import llm
+
+model = llm.retry_model(
+    "openai/gpt-4o-mini",
+    fallback_models=[
+        "anthropic/claude-3-5-haiku-latest",
+        "google/gemini-2.0-flash",
+    ],
+)
+response = model.call("Recommend a fantasy book")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/fallback_prompt.py

@@ -0,0 +1,17 @@
+from mirascope import llm
+
+
+@llm.retry(
+    fallback_models=[
+        "anthropic/claude-3-5-haiku-latest",
+        "google/gemini-2.0-flash",
+    ]
+)
+@llm.prompt
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+response = recommend_book("openai/gpt-4o-mini", "fantasy")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/retries_exhausted.py

@@ -0,0 +1,15 @@
+from mirascope import llm
+
+model = llm.retry_model(
+    "openai/gpt-4o-mini",
+    max_retries=2,
+    fallback_models=["anthropic/claude-3-5-haiku-latest"],
+)
+
+try:
+    response = model.call("Recommend a fantasy book")
+    print(response.text())
+except llm.RetriesExhausted as e:
+    print(f"All {len(e.failures)} attempts failed:")
+    for failure in e.failures:
+        print(f"  {failure.model.model_id}: {type(failure.exception).__name__}")

mirascope-2.2.0/examples/reliability/retry_config.py

@@ -0,0 +1,19 @@
+from mirascope import llm
+
+
+@llm.retry(
+    max_retries=5,
+    initial_delay=1.0,
+    max_delay=30.0,
+    backoff_multiplier=2.0,
+    jitter=0.1,
+    retry_on=(llm.RateLimitError, llm.ServerError),
+)
+@llm.call("openai/gpt-4o-mini")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+
+response = recommend_book("fantasy")
+print(response.text())
+# > The Name of the Wind by Patrick Rothfuss

mirascope-2.2.0/examples/reliability/stream_restart.py

@@ -0,0 +1,13 @@
+from mirascope import llm
+
+model = llm.retry_model("openai/gpt-4o-mini")
+response = model.stream("Tell me a story about a wizard")
+
+while True:
+    try:
+        for chunk in response.text_stream():
+            print(chunk, end="", flush=True)
+        break  # Stream completed successfully
+    except llm.StreamRestarted:
+        print("\n[Stream restarted due to error, retrying...]\n")
+        # Loop continues with the restarted stream

mirascope-2.2.0/examples/reliability/stream_resume.py

@@ -0,0 +1,26 @@
+from mirascope import llm
+
+# Use a `llm.Model` (not `llm.RetryModel`) for manual control when resuming the
+# stream response.
+model = llm.Model("openai/gpt-4o-mini")
+response = model.stream("Tell me a story about a wizard")
+
+max_retries = 3
+for attempt in range(max_retries + 1):
+    try:
+        for chunk in response.text_stream():
+            # Each chunk of text gets added to `response.content` as part
+            # of the final final assistant message in `response.messages`.
+            # This state accumulates even if the response is later interrupted.
+            print(chunk, end="", flush=True)
+        break  # Stream completed successfully
+    except llm.Error:
+        if attempt == max_retries:
+            raise
+        print("\n[Error occurred, continuing from where we left off...]\n")
+        # Manually calling `response.resume` uses the partially-streamed text
+        # content above, as well as any tool calls that fully streamed. (Partial
+        # tool calls are discarded).
+        # This differs from using a `RetryStreamResponse`, which would restart
+        # the stream without persisting any partially streamed content.
+        response = response.resume("Please continue from where you left off.")

mirascope-2.2.0/examples/structured_output/validate.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel, field_validator
+
+from mirascope import llm
+
+
+class BookRecommendation(BaseModel):
+    title: str
+    year: int
+
+    @field_validator("year")
+    @classmethod
+    def must_be_recent(cls, v: int) -> int:
+        if v < 2020:
+            raise ValueError(f"Must be published after 2020, got {v}")
+        return v
+
+
+@llm.call("openai/gpt-4o-mini", format=BookRecommendation)
+def recommend_book():
+    return "Recommend a science fiction book."
+
+
+response = recommend_book()
+book, response = response.validate()  # Retries once if validation fails
+print(f"{book.title} ({book.year})")