What are Models?

Models provide a consistent interface for invoking any supported LLM provider. Call synchronously, asynchronously, or via streaming — with the same API regardless of provider.

Supported Providers

Provider	Class	Default Model	Install Extra
OpenAI	`OpenAIChat`	`gpt-4o`	(core)
DeepSeek	`DeepSeekChat`	`deepseek-chat`	(core)
Moonshot	`MoonshotChat`	`kimi-k2-turbo-preview`	(core)
xAI	`xAI`	`grok-3`	(core)
Anthropic	`Claude`	`claude-sonnet-4-20250514`	`pip install 'definable[anthropic]'`
Mistral	`MistralChat`	`mistral-large-latest`	`pip install 'definable[mistral]'`
Google	`Gemini`	`gemini-2.0-flash-001`	`pip install 'definable[google]'`
Perplexity	`Perplexity`	`pplx-70b-online`	(core)
Ollama	`Ollama`	`llama3`	`pip install 'definable[ollama]'`
OpenRouter	`OpenRouter`	—	(core)
Custom	`OpenAILike`	—	(core)

Basic Usage

from definable.model.openai import OpenAIChat
from definable.model.message import Message

model = OpenAIChat(id="gpt-4o")
response = model.invoke(
    messages=[Message(role="user", content="Hello!")],
    assistant_message=Message(role="assistant", content=""),
)
print(response.content)

Common Parameters

All model classes accept these parameters:

str

required

The model identifier (e.g., "gpt-4o", "deepseek-chat").

str

API key for authentication. Defaults to the provider’s environment variable.

str

Override the API base URL. Useful for proxies or self-hosted endpoints.

float

Sampling temperature (0.0 to 2.0). Lower values are more deterministic.

int

Maximum number of tokens to generate.

float

Request timeout in seconds.

int

Maximum number of retries on transient failures.

Invocation Methods

Every model supports four ways to call it:

Method	Sync/Async	Streaming	Returns
`invoke()`	Sync	No	`ModelResponse`
`ainvoke()`	Async	No	`ModelResponse`
`invoke_stream()`	Sync	Yes	`Iterator[ModelResponse]`
`ainvoke_stream()`	Async	Yes	`AsyncIterator[ModelResponse]`

from definable.model.message import Message

response = model.invoke(
    messages=[Message(role="user", content="Hello!")],
    assistant_message=Message(role="assistant", content=""),
)
print(response.content)

from definable.model.message import Message

response = await model.ainvoke(
    messages=[Message(role="user", content="Hello!")],
    assistant_message=Message(role="assistant", content=""),
)
print(response.content)

from definable.model.message import Message

for chunk in model.invoke_stream(
    messages=[Message(role="user", content="Hello!")],
    assistant_message=Message(role="assistant", content=""),
):
    if chunk.content:
        print(chunk.content, end="", flush=True)

from definable.model.message import Message

async for chunk in model.ainvoke_stream(
    messages=[Message(role="user", content="Hello!")],
    assistant_message=Message(role="assistant", content=""),
):
    if chunk.content:
        print(chunk.content, end="", flush=True)

Retry Configuration

All models support automatic retries with configurable backoff:

model = OpenAIChat(
    id="gpt-4o",
    retries=3,
    delay_between_retries=1,
    exponential_backoff=True,
)

int

default:"0"

Number of retry attempts on failure.

int

default:"1"

Base delay in seconds between retries.

bool

default:"false"

Whether to use exponential backoff for retries.

Response Caching

Cache model responses locally for development and testing:

model = OpenAIChat(
    id="gpt-4o",
    cache_response=True,
    cache_ttl=3600,
    cache_dir=".cache/models",
)

Model Resolution from Strings

Agents accept string model shorthand — no explicit model import needed:

from definable.agent import Agent

# Bare model name (defaults to OpenAI)
agent = Agent(model="gpt-4o-mini", instructions="Hello")

# Provider/model-id format
agent = Agent(model="anthropic/claude-sonnet-4-20250514", instructions="Hello")
agent = Agent(model="google/gemini-2.0-flash-001", instructions="Hello")

You can also resolve strings programmatically:

from definable.model.utils import resolve_model_string

model = resolve_model_string("openai/gpt-4o")
model = resolve_model_string("deepseek/deepseek-chat")

Supported providers: openai, deepseek, moonshot, xai, anthropic, mistral, google, perplexity, ollama, openrouter

Next Steps

String Shorthand

Use string format instead of class imports.

Model Resilience

Key rotation, failover, and rate limit handling.

Streaming

Stream responses token-by-token.

Structured Output

Return Pydantic models from LLM calls.

Multimodal

Images, audio, video, and files.

Metrics & Pricing

Token counting and cost calculation.

Get Started

Basics

Capabilities

Advanced

Supported Providers

Basic Usage

Common Parameters

Invocation Methods

Retry Configuration

Response Caching

Model Resolution from Strings

Next Steps

String Shorthand

Model Resilience

Streaming

Structured Output

Multimodal

Metrics & Pricing

​Supported Providers

​Basic Usage

​Common Parameters

​Invocation Methods

​Retry Configuration

​Response Caching

​Model Resolution from Strings

​Next Steps

String Shorthand

Model Resilience

Streaming

Structured Output

Multimodal

Metrics & Pricing

Supported Providers

Basic Usage

Common Parameters

Invocation Methods

Retry Configuration

Response Caching

Model Resolution from Strings

Next Steps