# tinker.types.SampledSequence

*Generated from tinker 0.30.4 at commit [`1e5777e`](https://github.com/thinking-machines-lab/tinker/tree/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d). Source links point at that snapshot.*

## *class* [**tinker.types.SampledSequence**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L16)()

A single sampled sequence from the model.

Provides two ways to access token data:

- **Numpy arrays** (`tokens_np`, `logprobs_np`): As numpy arrays without format conversion.
- **Python lists** (`tokens`, `logprobs`): Standard Python lists, converted lazily on first access.

**Fields:**

- [**stop_reason**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L27) (*[StopReason](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/_pydantic_types/stop_reason.py#L3)*) – Reason why sampling stopped.
- [**sequence_id**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L30) (*str*) – Session-scoped identifier, distinct per sequence; use it wherever a later request needs to reference this exact sequence.
- [**tokens_np**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L34) (*Optional[np.ndarray]*) – Generated token IDs as a 1-D int32 numpy array, shape `(num_tokens,)`.
- [**logprobs_np**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L37) (*Optional[np.ndarray]*) – Log probabilities for each generated token as a 1-D float32 numpy array, shape `(num_tokens,)`. None if logprobs were not requested.
- [**topk_logprobs_np**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L41) (*Optional\[[TopkLogprobs](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/topklogprobs/index.md)\]*) – Top-k logprobs at each generated position as a pair of dense `(num_tokens, k)` matrices (see [`TopkLogprobs`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/topklogprobs/index.md)). None if `SampleRequest.topk_sample_logprobs` was not requested.

### [**tokens**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L54)()

Generated token IDs as a Python list.

Converted from `tokens_np` on first access (cached afterwards).

**Returns:** *List[int]*

### [**logprobs**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L66)()

Log probabilities for each generated token (optional).

None if logprobs were not requested. Converted from `logprobs_np` on first access (cached afterwards).

**Returns:** *Optional\[List[float]\]*

### [**topk_logprobs**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/sampled_sequence.py#L79)()

Top-k logprobs at each generated position as nested Python lists.

If `SampleRequest.topk_sample_logprobs` was set to a positive integer k in the request, each generated position gets a list of up to k `(token_id, logprob)` tuples, or `None` where the engine reported nothing. Returns `None` if top-k was not requested.

Converted from `topk_logprobs_np` on first access (cached afterwards).

**Returns:** *Optional\[List\[Optional\[List\[tuple[int, float]\]\]\]\]*

## Referenced by

- [tinker.types.SampleResponse](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/sampleresponse/index.md)