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

Installation

# 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.

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

Environment Variables: Copy .env.example to .env and fill in your API keys:

cp .env.example .env
# Edit .env with your API keys
# Necessary for updating e2e snapshot tests

Install Dependencies:
```
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 and inline-snapshot to maintain these e2e tests. For more details, read 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

For more info on contributing, read the contributing page in our docs.

Metadata

Release files for mirascope 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mirascope 2.5.0
File	Size	Uploaded
mirascope-2.5.0.tar.gz	3.4 MB	Jun 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mirascope 2.5.0
File	Interpreter	ABI	Platform	Reset
mirascope-2.5.0-py3-none-any.whl 275.1 kB Jun 24, 2026	Python 3	none	any	Details

Total release size: 3.6 MB

Release files / mirascope-2.5.0.tar.gz

Download URL	mirascope-2.5.0.tar.gz
Size	3.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`bf4a24838a9717eb03ec4cf1d69b211d30fd7f48a774491f000ee81d0b636968`
BLAKE2b-256 checksum How to use checksums	`5d989fde99c0d8f28506f02bfa1db7de92f9ccf7bdec45aeebc3d1ada7093636`
Upload date	Jun 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / mirascope-2.5.0-py3-none-any.whl

Download URL	mirascope-2.5.0-py3-none-any.whl
Size	275.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4aee8148ce48254a02bf016b9a494ca0ce701d3cb351baff3c1207e0484962c1`
BLAKE2b-256 checksum How to use checksums	`7c49b81e08fad3206dc6ff870d327afbf849e8cea741f873e66b4d54f80b8218`
Upload date	Jun 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`