Mirascope AI Agent

<p align="center"> <a href="https://mirascope.com/#mirascope"> <img src="https://mirascope.com/icons/logo-with-text.png" /> </a> </p> <p align="center"> <a href="https://github.com/Mirascope/mirascope/actions/workflows/ci.yml" target="_blank"><img src="https://github.com/Mirascope/mirascope/actions/workflows/ci.yml/badge.svg?branch=main" alt="Tests"/></a> <a href="https://app.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://pypi.org/project/mirascope/" target="_blank"><img src="https://img.shields.io/pypi/v/mirascope.svg" alt="PyPI Version"/></a> <a href="https://pypi.org/project/mirascope/" target="_blank"><img src="https://img.shields.io/pypi/pyversions/mirascope.svg" alt="Python Versions"/></a> <a href="https://github.com/Mirascope/mirascope/blob/main/python/LICENSE" target="_blank"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"/></a> </p>

---

Mirascope

Welcome to Mirascope, which allows you to use any frontier LLM with one unified interface.

Quick Start

Install Mirascope:

uv add "mirascope[all]"

Call LLMs with a Decorator

from mirascope import llm


@llm.call("anthropic/claude-sonnet-4-5")
def recommend_book(genre: str):
    return f"Recommend a {genre} book."


response = recommend_book("fantasy")
print(response.text())

Get Structured Output

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.call("anthropic/claude-sonnet-4-5", format=Book)
def recommend_book(genre: str):
    return f"Recommend a {genre} book."


book = recommend_book("fantasy").parse()
print(f"{book.title} by {book.author}")

Build an Agent with Tools

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.tool
def get_available_books(genre: str) -> list[Book]:
    """Get available books in the library by genre."""
    return [Book(title="The Name of the Wind", author="Patrick Rothfuss")]


@llm.call("anthropic/claude-sonnet-4-5", tools=[get_available_books], format=Book)
def librarian(request: str):
    return f"You are a librarian. Help the user: {request}"


response = librarian("I want a fantasy book")
while response.tool_calls:
    response = response.resume(response.execute_tools())
book = response.parse()
print(f"Recommending: {book.title} by {book.author}")

For streaming, async, multi-turn conversations, and more, see the full documentation.

Monorepo Structure

This project is structured as a monorepo, that conceptually divides into four parts:

• python/ contains the Python implementation, and examples (in python/examples)
• typescript/ contains the Typescript implementation, and examples (in typescript/examples)
• website/ contains the marketing website (docs, blog, landing page)
• docs/ contains the unified cross-language documentation (in docs/content), as well as configuration needed to build the docs

For detailed information about the codebase structure, architecture, and design decisions, see STRUCTURE.md.

Developing the site

Use bun run website:dev to launch the dev server.

Note that Bun must be installed.

CI and local testing

We currently have four CI jobs:

• codespell: Checks for common misspellings including python, typescript, and docs repos
• python-lint: Linting and typechecking for Python code
• typescript-lint: Linting and typechecking for Typescript code
• cloudflare docs build: Builds and previews the documentation site

You can run bun run ci in the root directory to run all CI checks locally. If adding new checks to GitHub CI, please also add it to the ci script in root package.json as well.

Versioning

Mirascope uses Semantic Versioning.

License

This project is licensed under the MIT License.