Mirascope

Common errors

• llm.AuthenticationError: Invalid or missing API key

  cause The required API key for the specified LLM provider (e.g., OpenAI, Anthropic, Google) is either not set in the environment variables or is incorrect.
  fix Set the appropriate environment variable for your provider (e.g., `export OPENAI_API_KEY='your_key_here'`, `export ANTHROPIC_API_KEY='your_key_here'`, or `export GOOGLE_API_KEY='your_key_here'`). Ensure the key is valid and has the necessary permissions.

• ModuleNotFoundError: No module named 'mirascope.core'

  cause This error often occurs when trying to use older v1 API patterns (e.g., `from mirascope.core import openai`) while the current recommended API surface is `mirascope.llm` (v2), or when the `mirascope.core` module is not correctly installed/available in the environment.
  fix Update your imports to use the v2 API, typically `from mirascope import llm` and then access provider-specific functions via `llm.call(provider='openai', ...)` or `llm.openai.call(...)`. If using a specific provider's legacy decorator, ensure `mirascope[provider]` is installed and verify the correct import path for your Mirascope version.

• llm.ParseError: Failed to parse structured response

  cause Mirascope failed to parse the LLM's response into the expected structured format (e.g., a Pydantic `response_model` or JSON). This often happens when the LLM's output does not conform to the schema or expected JSON format.
  fix Review the `response_model` or `json_mode` configuration to ensure it matches the expected output format. Adjust your prompt to guide the LLM to produce output strictly adhering to the specified schema or JSON format. You can also use `response.content` to inspect the raw output from the LLM.

• AttributeError: 'NoneType' object has no attribute 'content'

  cause This error indicates that an LLM call likely failed or returned an unexpected `None` value, and subsequent code attempted to access an attribute (like `content` or `text()`) on this `None` object. This can stem from underlying `llm.Error` exceptions (e.g., `ProviderError`, `ConnectionError`, `TimeoutError`) that were not caught or handled.
  fix Implement robust error handling using `try...except` blocks to catch Mirascope's unified `llm.Error` exceptions (e.g., `llm.ProviderError`, `llm.ConnectionError`, `llm.TimeoutError`). Inspect the raw response object before accessing attributes, or add checks for `None` to prevent attribute access on an invalid object.

Warnings

• breaking v2 replaced provider-specific imports with unified 'from mirascope import llm'. Model strings now use 'provider/model' format (e.g. 'openai/gpt-4o-mini', 'anthropic/claude-sonnet-4-5').
  Fix: Replace 'from mirascope.core import openai; @openai.call(model)' with 'from mirascope import llm; @llm.call("openai/model")'.
• breaking Response access changed in v2. v1 used response.content, v2 uses response.text(). response_model= renamed to format=. .parse() method added for structured output.
  Fix: response.text() not response.content. format=Book not response_model=Book. response.parse() for structured output.
• breaking v0 class-based approach (OpenAIChat, AnthropicChat classes) completely removed in v1+. All tutorials using class instantiation are broken.
  Fix: Use decorator-based approach. See migration guide at mirascope.com/docs/mirascope/getting-started/migration
• gotcha v1 (mirascope.core provider-specific imports) still works in v2 but is not the current API. LLMs trained on 2024 data will generate v1 patterns — functional but not idiomatic.
  Fix: v1 patterns work but migrate to llm module for new code.
• gotcha Provider extras must be installed separately. 'pip install mirascope' alone gives ImportError when using provider-specific features.
  Fix: pip install 'mirascope[openai]' or 'mirascope[anthropic]' etc.
• gotcha Docstring-as-prompt pattern from v1 no longer default in v2. Function return value is now the prompt. Docstring-style still works via @prompt_template decorator.
  Fix: Return the prompt string from the function body, or use @prompt_template decorator for docstring-style prompts.
• breaking Mirascope requires API keys for providers to be set as environment variables (e.g., OPENAI_API_KEY for OpenAI, ANTHROPIC_API_KEY for Anthropic). Failing to set these will result in a `MissingAPIKeyError` at runtime.
  Fix: Ensure the relevant API key environment variable is set before running your application (e.g., `export OPENAI_API_KEY='your_key_here'`). Alternatively, for cross-provider support, set `MIRASCOPE_API_KEY`.

Install

• pip install mirascope Python (core)
• pip install 'mirascope[openai]' Python (with OpenAI)
• pip install 'mirascope[anthropic]' Python (with Anthropic)

Imports

• llm.call (v2 — current)
  wrong:

  from mirascope.core import openai
  
  @openai.call('gpt-4o-mini')
  def recommend_book(genre: str):
      """Recommend a {genre} book."""
  
  response = recommend_book('fantasy')
  print(response.content)

  correct:

  from mirascope import llm
  
  @llm.call('openai/gpt-4o-mini')
  def recommend_book(genre: str):
      return f'Recommend a {genre} book.'
  
  response = recommend_book('fantasy')
  print(response.text())

  v1 used provider-specific imports (from mirascope.core import openai). v2 uses unified 'from mirascope import llm' with provider-prefixed model strings. v1 still works but v2 is canonical.
• structured output (v2)
  wrong:

  from mirascope.core import openai
  from pydantic import BaseModel
  
  class Book(BaseModel):
      title: str
      author: str
  
  @openai.call('gpt-4o-mini', response_model=Book)
  def recommend_book(genre: str):
      """Recommend a {genre} book."""
  

  correct:

  from pydantic import BaseModel
  from mirascope import llm
  
  class Book(BaseModel):
      title: str
      author: str
  
  @llm.call('openai/gpt-4o-mini', 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}')

  v1 used response_model= parameter. v2 uses format= parameter and .parse() method. Response access changed from .content to .text().

Quickstart

Mirascope v2 unified llm module quickstart.

# pip install 'mirascope[openai]'
from mirascope import llm
from pydantic import BaseModel

# Simple call
@llm.call('openai/gpt-4o-mini')
def recommend_book(genre: str):
    return f'Recommend a {genre} book.'

print(recommend_book('fantasy').text())

# Structured output
class Book(BaseModel):
    title: str
    author: str

@llm.call('openai/gpt-4o-mini', format=Book)
def recommend_structured(genre: str):
    return f'Recommend a {genre} book.'

book = recommend_structured('fantasy').parse()
print(f'{book.title} by {book.author}')