models

Class Model

The unified LLM interface that delegates to provider-specific clients.

This class provides a consistent interface for interacting with language models from various providers. It handles the common operations like generating responses, streaming, and async variants by delegating to the appropriate client methods.

Usage Note: In most cases, you should use llm.use_model() instead of instantiating Model directly. This preserves the ability to override the model at runtime using the llm.model() context manager. Only instantiate Model directly if you want to hardcode a specific model and prevent it from being overridden by context.

Example (recommended - allows override):

from mirascope import llm

def recommend_book(genre: str) -> llm.Response:
    # Uses context model if available, otherwise creates default
    model = llm.use_model("openai/gpt-5-mini")
    message = llm.messages.user(f"Please recommend a book in {genre}.")
    return model.call(messages=[message])

# Uses default model
response = recommend_book("fantasy")

# Override with different model
with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
    response = recommend_book("fantasy")  # Uses Claude

Example (direct instantiation - prevents override):

from mirascope import llm

def recommend_book(genre: str) -> llm.Response:
    # Hardcoded model, cannot be overridden by context
    model = llm.Model("openai/gpt-5-mini")
    message = llm.messages.user(f"Please recommend a book in {genre}.")
    return model.call(messages=[message])

Function call

Generate an llm.Response by synchronously calling this model's LLM provider.

Function call_async

Generate an llm.AsyncResponse by asynchronously calling this model's LLM provider.

Function stream

Generate an llm.StreamResponse by synchronously streaming from this model's LLM provider.

Function stream_async

Generate an llm.AsyncStreamResponse by asynchronously streaming from this model's LLM provider.

Function context_call

Generate an llm.ContextResponse by synchronously calling this model's LLM provider.

Function context_call_async

Generate an llm.AsyncContextResponse by asynchronously calling this model's LLM provider.

Function context_stream

Generate an llm.ContextStreamResponse by synchronously streaming from this model's LLM provider.

Function context_stream_async

Generate an llm.AsyncContextStreamResponse by asynchronously streaming from this model's LLM provider.

Function resume

Generate a new llm.Response by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function resume_async

Generate a new llm.AsyncResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function context_resume

Generate a new llm.ContextResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function context_resume_async

Generate a new llm.AsyncContextResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function resume_stream

Generate a new llm.StreamResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function resume_stream_async

Generate a new llm.AsyncStreamResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function context_resume_stream

Generate a new llm.ContextStreamResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function context_resume_stream_async

Generate a new llm.AsyncContextStreamResponse by extending another response's messages with additional user content.

Uses the previous response's tools and output format, and this model's params.

Depending on the client, this may be a wrapper around using client call methods with the response's messages and the new content, or it may use a provider-specific API for resuming an existing interaction.

Function model

Helper for creating a Model instance (which may be used as a context manager).

This is just an alias for the Model constructor, added for convenience.

This function returns a Model instance that implements the context manager protocol. When used with a with statement, the model will be set in context and used by both llm.use_model() and llm.call() within that context. This allows you to override the default model at runtime without modifying function definitions.

The returned Model instance can also be stored and reused:

m = llm.model("openai/gpt-4o")
# Use directly
response = m.call(messages=[...])
# Or use as context manager
with m:
    response = recommend_book("fantasy")

When a model is set in context, it completely overrides any model ID or parameters specified in llm.use_model() or llm.call(). The context model's parameters take precedence, and any unset parameters use default values.

Function model_from_context

Get the LLM currently set via context, if any.

Function use_model

Get the model from context if available, otherwise create a new Model.

This function checks if a model has been set in the context (via llm.model() context manager). If a model is found in the context, it returns that model, ignoring any model ID or parameters passed to this function. Otherwise, it creates and returns a new llm.Model instance with the provided arguments.

This allows you to write functions that work with a default model but can be overridden at runtime using the llm.model() context manager.

Example:

import mirascope.llm as llm

def recommend_book(genre: str) -> llm.Response:
    model = llm.use_model("openai/gpt-5-mini")
    message = llm.messages.user(f"Please recommend a book in {genre}.")
    return model.call(messages=[message])

# Uses the default model (gpt-5-mini)
response = recommend_book("fantasy")

# Override with a different model
with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
    response = recommend_book("fantasy")  # Uses Claude instead