Mirascope LLM Toolkit

What is Mirascope?

Mirascope is a framework for ergonomic Python LLM interface. It simplifies building AI applications by providing high-level abstractions over raw LLM APIs.

Best for: toolkit

Installation

bash
pip install mirascope
or with uv:
uv add mirascope

Core Concepts

Mirascope is built around a few key ideas:

Quick Start

python
Minimal working example
import os
os.environ["OPENAI_API_KEY"] = "sk-..."
Import Mirascope
(See framework-specific docs for exact imports)
Basic usage pattern for ergonomic Python LLM interface
def create_pipeline():
    """Create a Mirascope pipeline for toolkit."""
    # 1. Initialize the framework
    # 2. Configure your LLM (GPT-4o, Claude, etc.)
    # 3. Define the pipeline logic
    # 4. Return the configured pipeline
    pass
pipeline = create_pipeline()
result = pipeline.run("Your input here")
print(result)

Real-World Example: Toolkit

python
from openai import OpenAI
import json
class MirascopePipeline:
    """
    Mirascope implementation for toolkit.
    
    Architecture:
    - Input validation
    - Mirascope processing
    - Output structuring
    """
    
    def __init__(self, model: str = "gpt-4o-mini"):
        self.client = OpenAI()
        self.model = model
        self.system_prompt = f"""You are an AI assistant specialized in {specialty}.
        Use your expertise to provide accurate, helpful responses.
        Always be concise and structured in your answers."""
    
    def process(self, user_input: str, context: dict = None) -> dict:
        """Process input through the Mirascope pipeline."""
        
        # Build context-aware prompt
        context_str = json.dumps(context, indent=2) if context else "None"
        
        messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": f"Context:\n{context_str}\n\nRequest:\n{user_input}"}
        ]
        
        # Execute LLM call
        response = self.client.chat.completions.create(
            model=self.model,
            messages=messages,
            temperature=0.2,
            max_tokens=2000
        )
        
        content = response.choices[0].message.content
        
        return {
            "result": content,
            "model": self.model,
            "framework": "Mirascope",
            "tokens_used": response.usage.total_tokens
        }
    
    def batch_process(self, inputs: list[str]) -> list[dict]:
        """Process multiple inputs efficiently."""
        return [self.process(inp) for inp in inputs]
Usage
pipeline = MirascopePipeline()
result = pipeline.process("Explain toolkit with a code example")
print(result["result"])
print(f"Tokens used: {result['tokens_used']}")

Advanced Patterns

Streaming Responses

python
def stream_response(self, user_input: str):
    """Stream tokens for real-time output."""
    stream = self.client.chat.completions.create(
        model=self.model,
        messages=[{"role": "user", "content": user_input}],
        stream=True
    )
    for chunk in stream:
        delta = chunk.choices[0].delta
        if delta.content:
            yield delta.content

Error Handling and Retries

python
import time
from openai import RateLimitError, APIError
def process_with_retry(self, input_text: str, max_retries: int = 3) -> str:
    for attempt in range(max_retries):
        try:
            return self.process(input_text)
        except RateLimitError:
            wait_time = 2 ** attempt
            print(f"Rate limited, waiting {wait_time}s...")
            time.sleep(wait_time)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            print(f"API error: {e}, retrying...")
    raise Exception("Max retries exceeded")

Testing

python
import pytest
@pytest.fixture
def pipeline():
    return MirascopePipeline(model="gpt-4o-mini")
def test_basic_processing(pipeline):
    result = pipeline.process("What is toolkit?")
    assert "result" in result
    assert len(result["result"]) > 10
def test_batch_processing(pipeline):
    inputs = ["Question 1", "Question 2", "Question 3"]
    results = pipeline.batch_process(inputs)
    assert len(results) == len(inputs)

Production Deployment

python
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI(title="Mirascope API")
pipeline = MirascopePipeline()
class ProcessRequest(BaseModel):
    input: str
    context: dict = {}
@app.get("/health")
async def health():
    return {"status": "ok", "framework": "Mirascope"}

Best Practices

Resources

Official Mirascope documentation

GitHub repository with examples

Community Discord/Slack for support

Cookbook with real-world patterns