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

# ModelSettings

> ModelSettings reference: tune temperature, max tokens, top-p, and other LLM generation parameters when configuring an Agentor agent.

## Overview

`ModelSettings` controls how the model generates text — temperature, token limits, and the rest. Pass one to the [Agentor](/agentor/api/agentor) class to tune responses.

It is provider-neutral on purpose: the parameters below are understood everywhere, and anything else you pass is forwarded to the provider untouched. That means a provider-specific parameter needs no support from Agentor.

## Import

```python theme={null} theme={null}
from agentor import ModelSettings
```

## Usage

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

model_settings = ModelSettings(
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9
)

agent = Agentor(
    name="Assistant",
    model="gpt-4o",
    model_settings=model_settings
)
```

## Common Parameters

Every parameter defaults to unset, and unset parameters are left out of the request entirely — so the provider's own default applies.

<ParamField path="temperature" type="float" default="unset">
  Controls randomness in outputs. Lower values (0.0-0.3) make outputs more focused and deterministic. Higher values (0.7-1.0) make outputs more creative and varied.

  * `0.0-0.3`: Precise, consistent, factual responses
  * `0.4-0.6`: Balanced creativity and consistency
  * `0.7-1.0`: Creative, diverse, exploratory responses
</ParamField>

<ParamField path="max_tokens" type="int" default="Model-dependent">
  Maximum number of tokens to generate in the response. Limits the length of the model's output.
</ParamField>

<ParamField path="top_p" type="float" default="1.0">
  Nucleus sampling parameter. Controls diversity by limiting cumulative probability. Alternative to temperature.

  * `0.1-0.5`: More focused, deterministic
  * `0.9-1.0`: More diverse outputs
</ParamField>

<ParamField path="presence_penalty" type="float" default="0.0">
  Penalizes tokens based on whether they appear in the text so far. Range: -2.0 to 2.0.

  * Positive values encourage new topics
  * Negative values encourage staying on topic
</ParamField>

<ParamField path="frequency_penalty" type="float" default="0.0">
  Penalizes tokens based on their frequency in the text. Range: -2.0 to 2.0.

  * Positive values reduce repetition
  * Negative values allow more repetition
</ParamField>

<ParamField path="stop" type="str | List[str]" default="None">
  Sequences where the model will stop generating. Maximum of 4 sequences.
</ParamField>

<ParamField path="seed" type="int" default="None">
  Ask the provider for reproducible sampling. Support varies by provider.
</ParamField>

<ParamField path="tool_choice" type="str | dict" default="None">
  Force or forbid tool use: `"auto"`, `"none"`, `"required"`, or a specific tool.
</ParamField>

<ParamField path="parallel_tool_calls" type="bool" default="None">
  Allow the model to request several tools in one turn. Agentor runs them concurrently.
</ParamField>

<ParamField path="reasoning_effort" type="str" default="None">
  For reasoning models: how much thinking to do before answering.
</ParamField>

<ParamField path="verbosity" type="str" default="None">
  For models that support it: how long the answer should be.
</ParamField>

<ParamField path="top_logprobs" type="int" default="None">
  Number of most-likely tokens to return log probabilities for.
</ParamField>

<ParamField path="metadata" type="dict" default="None">
  Arbitrary key/value pairs attached to the provider request.
</ParamField>

<ParamField path="extra" type="dict" default="{}">
  Extra request parameters, passed through verbatim. Unrecognised keyword arguments land here automatically, so `ModelSettings(some_provider_flag=True)` works without listing it.
</ParamField>

<Note>
  A handful of parameters from the pre-0.1.0 settings type have no chat-completions equivalent — `truncation`, `retry`, `context_management`, `include_usage`, `prompt_cache_options`, `prompt_cache_retention`, `response_include`. They are accepted and dropped with a warning rather than sent and rejected.
</Note>

## Examples

### Creative Writing

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

creative_settings = ModelSettings(
    temperature=0.9,
    top_p=0.95,
    max_tokens=2000,
    presence_penalty=0.6
)

agent = Agentor(
    name="Creative Writer",
    model="gpt-4o",
    model_settings=creative_settings,
    instructions="You are a creative storytelling assistant."
)

result = agent.run("Write a short story about a time traveler")
```

### Precise Technical Responses

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

precise_settings = ModelSettings(
    temperature=0.2,
    top_p=0.1,
    max_tokens=1500
)

agent = Agentor(
    name="Code Assistant",
    model="gpt-4o",
    model_settings=precise_settings,
    instructions="You are a precise coding assistant."
)

result = agent.run("Explain how to implement a binary search tree")
```

### Concise Responses

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

concise_settings = ModelSettings(
    temperature=0.3,
    max_tokens=100,
    stop=["\n\n"]  # Stop at double newline
)

agent = Agentor(
    name="Concise Assistant",
    model="gpt-4o",
    model_settings=concise_settings,
    instructions="Provide brief, single-paragraph answers."
)
```

### Reducing Repetition

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

varied_settings = ModelSettings(
    temperature=0.7,
    frequency_penalty=0.5,
    presence_penalty=0.3
)

agent = Agentor(
    name="Varied Assistant",
    model="gpt-4o",
    model_settings=varied_settings
)
```

### From Markdown File

You can also specify temperature in markdown frontmatter:

```markdown theme={null} theme={null}
---
name: Research Agent
model: gpt-4o
temperature: 0.5
tools: ["current_datetime"]
---

You are a research assistant that provides accurate information.
```

```python theme={null} theme={null}
from agentor import Agentor, ModelSettings

# Temperature from markdown will be merged
additional_settings = ModelSettings(
    max_tokens=2000,
    top_p=0.9
)

agent = Agentor.from_md(
    "research_agent.md",
    model_settings=additional_settings
)
```

## Parameter Selection Guide

### By Use Case

| Use Case          | Temperature | Top P | Max Tokens | Notes                  |
| ----------------- | ----------- | ----- | ---------- | ---------------------- |
| Code generation   | 0.0-0.2     | 0.1   | 2000+      | Deterministic, precise |
| Technical writing | 0.3-0.5     | 0.5   | 1500       | Balanced, accurate     |
| Creative writing  | 0.8-1.0     | 0.95  | 2000+      | Diverse, imaginative   |
| Summarization     | 0.3-0.5     | 0.5   | 500        | Concise, factual       |
| Conversation      | 0.7-0.9     | 0.9   | 1000       | Natural, engaging      |
| Data extraction   | 0.0-0.1     | 0.1   | 500        | Consistent, accurate   |

### Combining Parameters

```python theme={null} theme={null}
from agentor import ModelSettings

# Balanced configuration
balanced = ModelSettings(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1500,
    frequency_penalty=0.0,
    presence_penalty=0.0
)

# High creativity
creative = ModelSettings(
    temperature=0.9,
    top_p=0.95,
    max_tokens=2000,
    presence_penalty=0.6,
    frequency_penalty=0.3
)

# Maximum precision
precise = ModelSettings(
    temperature=0.0,
    top_p=0.1,
    max_tokens=1000,
    frequency_penalty=0.0,
    presence_penalty=0.0
)
```

## Notes

* Import it from `agentor` directly: `from agentor import ModelSettings`
* If you pass nothing, no generation parameters are sent and the provider's defaults apply
* Temperature and `top_p` are alternative sampling methods — adjust one or the other, not both
* Different models interpret these parameters differently, and not every provider supports every one

## Related

* [Agentor](/agentor/api/agentor) - Main agent class that uses ModelSettings
* [Model providers](/agentor/model-providers) - Reach any OpenAI-compatible endpoint
* [LLM](/agentor/api/llm) - Lightweight LLM client