> ## Documentation Index
> Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# What are Models?

> Unified interface for calling LLMs across 10 providers.

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

```python theme={null}
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:

<ParamField path="id" type="str" required>
  The model identifier (e.g., `"gpt-4o"`, `"deepseek-chat"`).
</ParamField>

<ParamField path="api_key" type="str">
  API key for authentication. Defaults to the provider's environment variable.
</ParamField>

<ParamField path="base_url" type="str">
  Override the API base URL. Useful for proxies or self-hosted endpoints.
</ParamField>

<ParamField path="temperature" type="float">
  Sampling temperature (0.0 to 2.0). Lower values are more deterministic.
</ParamField>

<ParamField path="max_tokens" type="int">
  Maximum number of tokens to generate.
</ParamField>

<ParamField path="timeout" type="float">
  Request timeout in seconds.
</ParamField>

<ParamField path="max_retries" type="int">
  Maximum number of retries on transient failures.
</ParamField>

## 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]` |

<CodeGroup>
  ```python Sync theme={null}
  from definable.model.message import Message

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

  ```python Async theme={null}
  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)
  ```

  ```python Streaming theme={null}
  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)
  ```

  ```python Async Streaming theme={null}
  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)
  ```
</CodeGroup>

## Retry Configuration

All models support automatic retries with configurable backoff:

```python theme={null}
model = OpenAIChat(
    id="gpt-4o",
    retries=3,
    delay_between_retries=1,
    exponential_backoff=True,
)
```

<ParamField path="retries" type="int" default="0">
  Number of retry attempts on failure.
</ParamField>

<ParamField path="delay_between_retries" type="int" default="1">
  Base delay in seconds between retries.
</ParamField>

<ParamField path="exponential_backoff" type="bool" default="false">
  Whether to use exponential backoff for retries.
</ParamField>

## Response Caching

Cache model responses locally for development and testing:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

<CardGroup cols={3}>
  <Card title="String Shorthand" icon="text" href="/models/model-as-string">
    Use string format instead of class imports.
  </Card>

  <Card title="Model Resilience" icon="shield" href="/models/resilience">
    Key rotation, failover, and rate limit handling.
  </Card>

  <Card title="Streaming" icon="bars-staggered" href="/input-output/streaming">
    Stream responses token-by-token.
  </Card>

  <Card title="Structured Output" icon="code" href="/input-output/structured-output">
    Return Pydantic models from LLM calls.
  </Card>

  <Card title="Multimodal" icon="image" href="/input-output/multimodal">
    Images, audio, video, and files.
  </Card>

  <Card title="Metrics & Pricing" icon="chart-line" href="/models/metrics-and-pricing">
    Token counting and cost calculation.
  </Card>
</CardGroup>