# Models and Types

The model, reasoning, service tier, error, checkpoint, and usage types that the `nanocode` crate re-exports.

Each type is at the crate root, such as `nanocode::Model`. The tables list the values in the current source. Model identifiers are the strings that each harness sends to its provider.

```rust
use nanocode::{ClaudeModel, Model, ModelSelection, Thinking};

// Names one model on each harness and checks a thinking level
let codex = ModelSelection::Codex(Model::Sol);
let claude = ModelSelection::Claude(ClaudeModel::Opus55);
assert!(claude.supports_thinking(Thinking::High));
println!("{} {}", codex.as_str(), claude.as_str());
```

## Model

The models of the Codex harness. The enum is non-exhaustive, and `Model::default()` is `Model::Astra`.

| Variant | Identifier            | Default thinking | Thinking levels         |
| ------- | --------------------- | ---------------- | ----------------------- |
| `Sol`   | `gpt-6.1-sol`         | `Medium`         | All except `None`       |
| `Luna`  | `gpt-6-luna`          | `Medium`         | All                     |
| `Astra` | `gpt-6-astra`         | `Low`            | All except `None`       |
| `Glm53` | `@cf/zai-org/glm-5.3` | `Low`            | `Low`, `Medium`, `High` |
| `Kimi`  | `kimi-k3`             | `Low`            | `Low`, `High`           |
| `Mimo`  | `mimo-v2.6-pro`       | `Low`            | `Low`, `Medium`, `High` |

`Glm53`, `Kimi`, and `Mimo` do not support `ReasoningMode::Pro`. The maximum context window is 872,000 tokens, except `Glm53` (1,310,720), `Kimi` (1,000,000), and `Mimo` (1,048,576). `FromStr` accepts the identifier or the short name, such as `"luna"`.

```rust
use nanocode::Model;

// Parses a short name and reads the model's default effort
let model: Model = "luna".parse()?;
println!("{} {}", model, model.default_thinking());
```

## ClaudeModel

The models of the Claude harness. `HarnessFamily::Claude.default_model()` is `ClaudeModel::Opus55`.

| Variant    | Identifier          | Default thinking | Thinking levels                        |
| ---------- | ------------------- | ---------------- | -------------------------------------- |
| `Opus55`   | `claude-opus-5-5`   | `Medium`         | `Low` to `Max`                         |
| `Sonnet55` | `claude-sonnet-5-5` | `High`           | `Low` to `Max`                         |
| `Haiku55`  | `claude-haiku-5-5`  | `Medium`         | All                                    |
| `Fable51`  | `claude-fable-5-1`  | `High`           | `Low` to `Max`                         |
| `Mythos51` | `claude-mythos-5-1` | `High`           | `Low` to `Max`                         |
| `Opus46`   | `claude-opus-4-6`   | `High`           | `None`, `Low`, `Medium`, `High`, `Max` |
| `Sonnet46` | `claude-sonnet-4-6` | `High`           | `None`, `Low`, `Medium`, `High`, `Max` |
| `Haiku45`  | `claude-haiku-4-5`  | `None`           | `None`                                 |

`FromStr` accepts the identifier, or `opus`, `sonnet`, `haiku`, `fable`, and `mythos` for the 5.x models. Only `Opus55` supports fast mode.

```rust
use nanocode::ClaudeModel;

// Parses a short name
let model: ClaudeModel = "sonnet".parse()?;
println!("{model}");
```

## Thinking

The reasoning effort. Each model supports a subset, and a level outside it fails `build` with `NanocodeError::InvalidRequest`.

| Variant  | String                     |
| -------- | -------------------------- |
| `None`   | `none`                     |
| `Low`    | `low`, the `Default` value |
| `Medium` | `medium`                   |
| `High`   | `high`                     |
| `Xhigh`  | `xhigh`                    |
| `Max`    | `max`                      |

```rust
use nanocode::Thinking;

// Parses the lowercase name
let thinking: Thinking = "xhigh".parse()?;
```

## ReasoningMode

| Variant    | Behavior                                                                   |
| ---------- | -------------------------------------------------------------------------- |
| `Standard` | The default. Requests send no reasoning mode.                              |
| `Pro`      | Requests send the `pro` mode. Not available on `Glm53`, `Kimi`, or `Mimo`. |

```rust
use nanocode::ReasoningMode;

// Selects pro reasoning for one agent
let (agent, events) = runtime
    .spawn()
    .reasoning_mode(ReasoningMode::Pro)
    .build()
    .await?;
```

## ServiceTier

The processing tier of model requests. `ServiceTier::from_fast_mode(true)` is `Fast`.

| Variant     | Behavior                                                        |
| ----------- | --------------------------------------------------------------- |
| `Standard`  | The default. Requests send no tier.                             |
| `Priority`  | Requests send the `priority` tier.                              |
| `Fast`      | Requests send the `priority` tier.                              |
| `Ultrafast` | Requests send the `ultrafast` tier. `Luna` uses `Fast` instead. |

`Glm53`, `Kimi`, and `Mimo` always use `Standard`. `ServiceTier::effective_for_model` returns the tier that a model uses.

```rust
use nanocode::{Model, ServiceTier};

// Luna falls back from Ultrafast to Fast
assert_eq!(
    ServiceTier::Ultrafast.effective_for_model(Model::Luna),
    ServiceTier::Fast
);
```

## ModelSelection

A model on a harness: a struct with the public fields `backend` and `model`. It names models of third-party harnesses too.

| Member                                                          | Behavior                                |
| --------------------------------------------------------------- | --------------------------------------- |
| `ModelSelection::Codex(model)`, `ModelSelection::Claude(model)` | Selects a built-in model.               |
| `ModelSelection::new(family, model)`                            | Selects any model ID on any harness.    |
| `family()`, `as_str()`                                          | Returns the harness and the model ID.   |
| `as_codex()`, `as_claude()`                                     | Returns the built-in model, or `None`.  |
| `default_thinking()`, `supports_thinking(thinking)`             | Reads the thinking levels of the model. |

```rust
use nanocode::{HarnessFamily, ModelSelection};

// Names a model of a custom harness
let model = ModelSelection::new(HarnessFamily::new("local"), "llama-5");
```

## HarnessFamily

The identity of a harness. `HarnessFamily::Codex` and `HarnessFamily::Claude` are the built-in families, with the strings `codex` and `claude`. `HarnessFamily::new(name)` names another family, and `default_model()` returns its default `ModelSelection`.

```rust
use nanocode::HarnessFamily;

// Prints gpt-6.1-sol
println!("{}", HarnessFamily::Codex.default_model().as_str());
```

## NanocodeError

The error of runtime, agent, and turn operations. Notable variants:

| Variant                                | Meaning                                           |
| -------------------------------------- | ------------------------------------------------- |
| `InvalidRequest(String)`               | A configuration or input is not valid.            |
| `AgentStopped`                         | The agent stopped before it accepted the command. |
| `TurnStopped`                          | The agent stopped before the turn completed.      |
| `TurnCancelled`                        | The turn was cancelled.                           |
| `TurnNotSteerable`, `SteerQueueFull`   | Steering was refused.                             |
| `ForkBeforeCompletedTurn`              | `fork` found no completed turn to branch from.    |
| `InvalidCheckpoint(String)`            | A checkpoint failed validation.                   |
| `UnsupportedCapability { capability }` | The backend does not support the operation.       |
| `CompactionFailed { .. }`              | Compaction failed.                                |
| `Backend { backend, source }`          | A backend, such as `durability`, failed.          |
| `TokioRuntimeUnavailable`              | `build_async` ran outside Tokio.                  |
| `Tools(ToolsBuildError)`               | An agent's tools failed to build.                 |

```rust
use nanocode::NanocodeError;

// Retries only turns that stopped with the agent
fn should_retry(error: &NanocodeError) -> bool {
    matches!(
        error,
        NanocodeError::TurnStopped | NanocodeError::AgentStopped
    )
}
```

## SessionCheckpoint

A portable snapshot of a session that `runtime.resume` accepts. `Agent.checkpoint` and `TurnResult.checkpoint` return it.

| Member                                              | Behavior                                             |
| --------------------------------------------------- | ---------------------------------------------------- |
| `to_json()`, `SessionCheckpoint::from_json(json)`   | Serializes and parses the checkpoint.                |
| `validate()`                                        | Checks the checkpoint before use. `resume` calls it. |
| `session_id()`, `family()`, `model()`, `thinking()` | Reads the session and its settings.                  |
| `turn_id()`                                         | The turn that the checkpoint follows, if any.        |

```rust
use nanocode::SessionCheckpoint;

// Round-trips a checkpoint through JSON
let json = agent.checkpoint().await?.to_json()?;
let (resumed, events) =
    runtime.resume(SessionCheckpoint::from_json(&json)?).await?;
```

## TurnUsage

The usage of one turn, from `TurnResult.usage`. Every count is a `u64`.

| Method                       | Value                                        |
| ---------------------------- | -------------------------------------------- |
| `input_tokens()`             | Input tokens.                                |
| `cached_input_tokens()`      | Input tokens read from the prompt cache.     |
| `cache_write_input_tokens()` | Input tokens written to the prompt cache.    |
| `output_tokens()`            | Output tokens.                               |
| `reasoning_output_tokens()`  | Output tokens spent on reasoning.            |
| `total_tokens()`             | All tokens of the turn.                      |
| `estimated_cost()`           | The `EstimatedUsdCost`, if pricing is known. |
| `cost_status()`              | Whether the cost is known.                   |

```rust
// Prints the token counts of a turn
if let Some(usage) = result.usage() {
    println!(
        "{} in, {} out",
        usage.input_tokens(),
        usage.output_tokens()
    );
}
```