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

# State

> Runtime state dictionary for rollouts

# State

The `State` type is a specialized dict subclass that holds all runtime information for a rollout, including inputs, outputs, trajectory, and metadata.

## Overview

`State` provides a unified interface for accessing both:

* **Input fields**: From the dataset row (`prompt`, `answer`, `task`, `info`, `example_id`)
* **Runtime fields**: Created during rollout execution (`trajectory`, `reward`, `completion`, etc.)

Fields are automatically forwarded to/from the nested `input` dict for seamless access.

## Type Definition

```python theme={null}
class State(dict):
    INPUT_FIELDS = ["prompt", "answer", "task", "info", "example_id"]
    
    # Input fields (from dataset)
    input: RolloutInput
    client: Client
    model: str
    sampling_args: SamplingArgs | None
    
    # Created during rollout
    is_completed: bool
    is_truncated: bool
    stop_condition: str | None
    tool_defs: list[Tool]
    trajectory: list[TrajectoryStep]
    completion: Messages | None
    reward: float | None
    advantage: float | None
    metrics: dict[str, float] | None
    timing: RolloutTiming | None
    error: Error | None
    usage: TokenUsage | None
    usage_tracker: object
```

## Input Fields

These fields come from the dataset and are stored in `state["input"]`:

<ParamField path="prompt" type="Messages">
  The input prompt as a list of messages.
</ParamField>

<ParamField path="answer" type="str | Any">
  Ground truth answer or reference data for scoring.
</ParamField>

<ParamField path="task" type="str">
  Task identifier (e.g., "math", "coding", "gsm8k").
</ParamField>

<ParamField path="info" type="Info">
  Additional metadata from the dataset (arbitrary dict).
</ParamField>

<ParamField path="example_id" type="int">
  Unique integer ID for this example.
</ParamField>

## Runtime Fields

<ParamField path="client" type="Client">
  The API client instance for model calls.
</ParamField>

<ParamField path="model" type="str">
  Model identifier (e.g., "gpt-4", "claude-3-5-sonnet-20241022").
</ParamField>

<ParamField path="sampling_args" type="SamplingArgs | None">
  Sampling parameters (temperature, top\_p, etc.).
</ParamField>

<ParamField path="is_completed" type="bool">
  Whether the rollout completed successfully.
</ParamField>

<ParamField path="is_truncated" type="bool">
  Whether the rollout was truncated (max turns, length limit, etc.).
</ParamField>

<ParamField path="stop_condition" type="str | None">
  Name of the stop condition that ended the rollout.
</ParamField>

<ParamField path="tool_defs" type="list[Tool]">
  Tool definitions available during this rollout.
</ParamField>

<ParamField path="trajectory" type="list[TrajectoryStep]">
  Complete turn-by-turn trajectory (prompts, completions, rewards).
</ParamField>

<ParamField path="completion" type="Messages | None">
  Final completion (last assistant message or concatenated messages).
</ParamField>

<ParamField path="reward" type="float | None">
  Total reward for this rollout.
</ParamField>

<ParamField path="advantage" type="float | None">
  Advantage value (for group scoring).
</ParamField>

<ParamField path="metrics" type="dict[str, float] | None">
  Named metric scores (e.g., `{"correctness": 1.0, "length": 0.8}`).
</ParamField>

<ParamField path="timing" type="RolloutTiming | None">
  Timing information (start\_time, generation\_ms, scoring\_ms, total\_ms).
</ParamField>

<ParamField path="error" type="Error | None">
  Error object if rollout failed.
</ParamField>

<ParamField path="usage" type="TokenUsage | None">
  Token usage (input\_tokens, output\_tokens).
</ParamField>

## Special Behavior

### Input Field Forwarding

Accessing input fields automatically looks in `state["input"]`:

```python theme={null}
state = State({
    "input": {
        "prompt": [{"role": "user", "content": "Hello"}],
        "answer": "42",
        "task": "qa",
        "example_id": 0
    }
})

# These are equivalent:
state["prompt"]          # Returns the prompt
state["input"]["prompt"] # Same result

# Setting also forwards:
state["answer"] = "43"
assert state["input"]["answer"] == "43"
```

### get() Method

```python theme={null}
def get(self, key: str, default: Any = None) -> Any
```

Safe access with default fallback:

```python theme={null}
reward = state.get("reward", 0.0)  # Returns 0.0 if not set
task = state.get("task")            # Returns None if not set
```

## Example Usage

### Basic Access

```python theme={null}
import verifiers as vf

# In a reward function
def reward_fn(state: vf.State) -> float:
    # Access input fields
    answer = state["answer"]
    task = state["task"]
    
    # Access runtime fields
    completion = state["completion"]
    trajectory = state["trajectory"]
    
    # Check completion
    if not state["is_completed"]:
        return 0.0
    
    # Compute reward
    return 1.0 if answer in str(completion) else 0.0
```

### Trajectory Inspection

```python theme={null}
def analyze_trajectory(state: vf.State) -> dict:
    """Extract statistics from trajectory."""
    trajectory = state["trajectory"]
    
    return {
        "num_turns": len(trajectory),
        "total_tokens": sum(
            step["tokens"]["completion_ids"].__len__()
            for step in trajectory
            if step.get("tokens")
        ),
        "tool_calls": sum(
            1 for step in trajectory
            if step["response"]["message"].get("tool_calls")
        ),
    }
```

### Custom State Keys

Environments can add custom keys:

```python theme={null}
class CustomEnv(vf.MultiTurnEnv):
    async def setup_state(self, state: vf.State) -> vf.State:
        state = await super().setup_state(state)
        
        # Add custom fields
        state["custom_data"] = {"foo": "bar"}
        state["attempt_count"] = 0
        
        return state
    
    async def env_response(
        self,
        messages: vf.Messages,
        state: vf.State,
        **kwargs
    ) -> vf.Messages:
        # Access custom fields
        state["attempt_count"] += 1
        
        if state["attempt_count"] > 3:
            return [{"role": "user", "content": "Too many attempts!"}]
        
        return [{"role": "user", "content": "Try again"}]
```

### Safe Error Access

```python theme={null}
def handle_errors(state: vf.State):
    error = state.get("error")
    
    if error:
        print(f"Error type: {type(error).__name__}")
        print(f"Error message: {str(error)}")
        
        # Check error type
        if isinstance(error, vf.SandboxError):
            print("Sandbox operation failed")
        elif isinstance(error, vf.InfraError):
            print("Infrastructure error")
    else:
        print("No errors")
```

## Serialization

State can be converted to `RolloutOutput` for serialization:

```python theme={null}
# During environment.generate()
output: vf.RolloutOutput = serialize_state(state)

# RolloutOutput is JSON-serializable:
import json
json.dumps(output)  # Works
```

## Type Annotations

```python theme={null}
from verifiers.types import State, Messages

def my_reward(state: State) -> float:
    # Type checker knows State has these fields
    prompt: Messages = state["prompt"]
    reward: float | None = state.get("reward")
    return reward or 0.0
```

## Common Patterns

### Checking Completion

```python theme={null}
if state["is_completed"]:
    # Rollout finished successfully
    reward = state["reward"]
else:
    # Rollout was interrupted
    error = state.get("error")
```

### Accessing Metadata

```python theme={null}
info = state.get("info", {})
custom_field = info.get("custom_field", "default")
```

### Iterating Trajectory

```python theme={null}
for i, step in enumerate(state["trajectory"]):
    print(f"Turn {i}:")
    print(f"  Prompt: {step['prompt']}")
    print(f"  Completion: {step['completion']}")
    print(f"  Reward: {step.get('reward', 0.0)}")
```

## See Also

* [TrajectoryStep](/api/types/trajectory-step) - Individual turn data
* [RolloutOutput](/api/types/rollout-output) - Serialized rollout result
* [Messages](/api/types/messages) - Message format