# `vllm_mlx.constrained.thinking_processor`

Thinking-aware logits processor for reasoning models.

[View the complete module source at #L1-L287](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L1-L287).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.constrained.thinking_processor
    options:
      members:
        - BoundedSuffixMatcher
        - Phase
        - ThinkingAwareLogitsProcessor
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher</code> · class</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher(target_ids: list[int])
```

Detect a target token sequence in a stream using a rolling suffix buffer.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `target_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Constructs: `vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher`

**Exceptions and behavior**

Class `BoundedSuffixMatcher` declares 5 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L16-L48](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L16-L48).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.__init__" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.__init__</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.__init__(target_ids: list[int]) -> None
```

Method `BoundedSuffixMatcher.__init__` updates `self.target`, `self._max_len`, `self._buf`; calls `ValueError`, `tuple`, `len`, `deque`; can raise `ValueError`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `target_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BoundedSuffixMatcher.__init__` updates `self.target`, `self._max_len`, `self._buf`; calls `ValueError`, `tuple`, `len`, `deque`; can raise `ValueError`.
Directly raised exceptions: `ValueError`.

[View source #L25-L30](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L25-L30).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.feed" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.feed</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.feed(token_id: int) -> bool
```

Feed one token.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `token_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `len(self._buf) == self._max_len and tuple(self._buf) == self.target`

**Exceptions and behavior**

Method `BoundedSuffixMatcher.feed` calls `self._buf.append`, `len`, `tuple`; returns `len(self._buf) == self._max_len and tuple(self._buf) == self.target`.
No direct `raise` statement appears in this definition.

[View source #L32-L35](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L32-L35).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.reset" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.reset</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.reset() -> None
```

Clear the buffer.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BoundedSuffixMatcher.reset` calls `self._buf.clear`.
No direct `raise` statement appears in this definition.

[View source #L37-L39](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L37-L39).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.snapshot" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.snapshot</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.snapshot() -> tuple[int, ...]
```

Return a serializable copy of the current suffix buffer.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `tuple[int, ...]`
- Direct return expressions: `tuple(self._buf)`

**Exceptions and behavior**

Method `BoundedSuffixMatcher.snapshot` calls `tuple`; returns `tuple(self._buf)`.
No direct `raise` statement appears in this definition.

[View source #L41-L43](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L41-L43).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.restore" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.restore</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.restore(state: tuple[int, ...]) -> None
```

Restore the suffix buffer from a previous snapshot.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `state` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BoundedSuffixMatcher.restore` calls `self._buf.clear`, `self._buf.extend`.
No direct `raise` statement appears in this definition.

[View source #L45-L48](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L45-L48).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.Phase" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.Phase</code> · class</summary>

```python
vllm_mlx.constrained.thinking_processor.Phase()
```

Thinking lifecycle phases.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.constrained.thinking_processor.Phase`

**Exceptions and behavior**

Class `Phase` derives from `enum.Enum` and declares 0 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L51-L57](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L51-L57).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor</code> · class</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor(start_token_ids: list[int], end_token_ids: list[int], thinking_token_budget: int, inner: Callable[[mx.array, mx.array], mx.array] | None = None, vocab_size: int = 152064, prompt_has_think_tag: bool = False, no_final_content_token_limit: int | None = None)
```

Unified logits processor for thinking-model lifecycle management.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `start_token_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |
| `end_token_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |
| `thinking_token_budget` | `int` | `yes` | `none` | Required positional or keyword input. |
| `inner` | `Callable[[mx.array, mx.array], mx.array] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `vocab_size` | `int` | `no` | `152064` | Optional positional or keyword input; defaults to `152064`. |
| `prompt_has_think_tag` | `bool` | `no` | `False` | Optional positional or keyword input; defaults to `False`. |
| `no_final_content_token_limit` | `int \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |

**Returns**

- Constructs: `vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor`

**Exceptions and behavior**

Class `ThinkingAwareLogitsProcessor` declares 12 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L60-L287](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L60-L287).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__init__" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__init__</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__init__(start_token_ids: list[int], end_token_ids: list[int], thinking_token_budget: int, inner: Callable[[mx.array, mx.array], mx.array] | None = None, vocab_size: int = 152064, prompt_has_think_tag: bool = False, no_final_content_token_limit: int | None = None) -> None
```

Method `ThinkingAwareLogitsProcessor.__init__` updates `self._start_matcher`, `self._end_matcher`, `self._end_token_ids`, `self._content_phase_mask_ids`; calls `BoundedSuffixMatcher`, `list`, `tuple`, `dict.fromkeys`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `start_token_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |
| `end_token_ids` | `list[int]` | `yes` | `none` | Required positional or keyword input. |
| `thinking_token_budget` | `int` | `yes` | `none` | Required positional or keyword input. |
| `inner` | `Callable[[mx.array, mx.array], mx.array] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `vocab_size` | `int` | `no` | `152064` | Optional positional or keyword input; defaults to `152064`. |
| `prompt_has_think_tag` | `bool` | `no` | `False` | Optional positional or keyword input; defaults to `False`. |
| `no_final_content_token_limit` | `int \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor.__init__` updates `self._start_matcher`, `self._end_matcher`, `self._end_token_ids`, `self._content_phase_mask_ids`; calls `BoundedSuffixMatcher`, `list`, `tuple`, `dict.fromkeys`.
No direct `raise` statement appears in this definition.

[View source #L92-L129](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L92-L129).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.state" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.state</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.state() -> Phase
```

Return the current reasoning lifecycle phase.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `Phase`
- Direct return expressions: `self._state`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor.state` returns `self._state`.
No direct `raise` statement appears in this definition.

[View source #L132-L135](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L132-L135).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.thinking_tokens" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.thinking_tokens</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.thinking_tokens() -> int
```

Return the number of generated tokens counted as reasoning.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `self._thinking_tokens`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor.thinking_tokens` returns `self._thinking_tokens`.
No direct `raise` statement appears in this definition.

[View source #L138-L141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L138-L141).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.is_retired" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.is_retired</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.is_retired() -> bool
```

True when the processor is in CONTENT with no inner constraint.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `bool`
- Direct return expressions: `self._state == Phase.CONTENT and self._inner is None`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor.is_retired` returns `self._state == Phase.CONTENT and self._inner is None`.
No direct `raise` statement appears in this definition.

[View source #L144-L150](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L144-L150).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__call__" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__call__</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__call__(tokens: mx.array, logits: mx.array) -> mx.array
```

Method `ThinkingAwareLogitsProcessor.__call__` calls `self._force_transition`, `self._call_inner`, `self._sync_to_tokens`; has 3 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `logits` | `mx.array` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `mx.array`
- Direct return expressions: `self._force_transition(logits)`; `self._call_inner(tokens, logits)`; `logits`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor.__call__` calls `self._force_transition`, `self._call_inner`, `self._sync_to_tokens`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L152-L170](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L152-L170).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._force_transition" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._force_transition</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._force_transition(logits: mx.array) -> mx.array
```

Force the next token in the reasoning end sequence.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `logits` | `mx.array` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `mx.array`
- Direct return expressions: `masked`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._force_transition` calls `mx.full`, `float`; returns `masked`.
No direct `raise` statement appears in this definition.

[View source #L172-L182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L172-L182).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._call_inner" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._call_inner</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._call_inner(tokens: mx.array, logits: mx.array) -> mx.array
```

Delegate to inner processor if present.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `logits` | `mx.array` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `mx.array`
- Direct return expressions: `self._mask_content_phase_control_tokens(logits)`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._call_inner` calls `self._inner`, `self._mask_content_phase_control_tokens`; returns `self._mask_content_phase_control_tokens(logits)`.
No direct `raise` statement appears in this definition.

[View source #L184-L188](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L184-L188).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens(logits: mx.array) -> mx.array
```

Prevent reserved think-tag starts from leaking into final content.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `logits` | `mx.array` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `mx.array`
- Direct return expressions: `logits`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens` calls `float`; returns `logits`.
No direct `raise` statement appears in this definition.

[View source #L190-L197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L190-L197).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._snapshot_state" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._snapshot_state</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._snapshot_state() -> tuple[Phase, int, int, tuple[int, ...], tuple[int, ...], bool]
```

Method `ThinkingAwareLogitsProcessor._snapshot_state` calls `self._start_matcher.snapshot`, `self._end_matcher.snapshot`; returns `(self._state, self._thinking_tokens, self._transition_index, self._start_matcher.snapshot(), self._end_matcher.snapshot…`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `tuple[Phase, int, int, tuple[int, ...], tuple[int, ...], bool]`
- Direct return expressions: `(self._state, self._thinking_tokens, self._transition_index, self._start_matcher.snapshot(), self._end_matcher.snapshot…`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._snapshot_state` calls `self._start_matcher.snapshot`, `self._end_matcher.snapshot`; returns `(self._state, self._thinking_tokens, self._transition_index, self._start_matcher.snapshot(), self._end_matcher.snapshot…`.
No direct `raise` statement appears in this definition.

[View source #L199-L209](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L199-L209).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._restore_snapshot" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._restore_snapshot</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._restore_snapshot(processed_len: int) -> None
```

Method `ThinkingAwareLogitsProcessor._restore_snapshot` updates `self._state`, `self._thinking_tokens`, `self._transition_index`, `self.watchdog_was_enforced`; calls `min`, `len`, `self._start_matcher.restore`, `self._end_matcher.restore`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `processed_len` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._restore_snapshot` updates `self._state`, `self._thinking_tokens`, `self._transition_index`, `self.watchdog_was_enforced`; calls `min`, `len`, `self._start_matcher.restore`, `self._end_matcher.restore`.
No direct `raise` statement appears in this definition.

[View source #L211-L229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L211-L229).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._sync_to_tokens" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._sync_to_tokens</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._sync_to_tokens(tokens: mx.array) -> None
```

Method `ThinkingAwareLogitsProcessor._sync_to_tokens` updates `self._processed_len`; calls `int`, `tokens.tolist`, `min`, `self._restore_snapshot`; returns `None`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `mx.array` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._sync_to_tokens` updates `self._processed_len`; calls `int`, `tokens.tolist`, `min`, `self._restore_snapshot`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L231-L252](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L231-L252).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._advance_with_token" markdown="1">
<summary><code>vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._advance_with_token</code> · method</summary>

```python
vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._advance_with_token(token_id: int) -> None
```

Method `ThinkingAwareLogitsProcessor._advance_with_token` updates `self._state`, `self._transition_index`, `self._thinking_tokens`, `self.watchdog_was_enforced`; calls `self._start_matcher.feed`, `self._end_matcher.feed`, `len`, `self._end_matcher.reset`; returns `None`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `token_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `ThinkingAwareLogitsProcessor._advance_with_token` updates `self._state`, `self._transition_index`, `self._thinking_tokens`, `self.watchdog_was_enforced`; calls `self._start_matcher.feed`, `self._end_matcher.feed`, `len`, `self._end_matcher.reset`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L254-L287](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L254-L287).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`BoundedSuffixMatcher`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher) | class | `BoundedSuffixMatcher(target_ids: list[int])` | Detect a target token sequence in a stream using a rolling suffix buffer. | [#L16-L48](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L16-L48) |
| [`BoundedSuffixMatcher.__init__`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.__init__) | method | `BoundedSuffixMatcher.__init__(target_ids: list[int]) -> None` | Method `BoundedSuffixMatcher.__init__` updates `self.target`, `self._max_len`, `self._buf`; calls `ValueError`, `tuple`, `len`, `deque`; can raise `ValueError`. | [#L25-L30](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L25-L30) |
| [`BoundedSuffixMatcher.feed`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.feed) | method | `BoundedSuffixMatcher.feed(token_id: int) -> bool` | Feed one token. | [#L32-L35](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L32-L35) |
| [`BoundedSuffixMatcher.reset`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.reset) | method | `BoundedSuffixMatcher.reset() -> None` | Clear the buffer. | [#L37-L39](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L37-L39) |
| [`BoundedSuffixMatcher.snapshot`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.snapshot) | method | `BoundedSuffixMatcher.snapshot() -> tuple[int, ...]` | Return a serializable copy of the current suffix buffer. | [#L41-L43](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L41-L43) |
| [`BoundedSuffixMatcher.restore`](#contract-vllm_mlx.constrained.thinking_processor.BoundedSuffixMatcher.restore) | method | `BoundedSuffixMatcher.restore(state: tuple[int, ...]) -> None` | Restore the suffix buffer from a previous snapshot. | [#L45-L48](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L45-L48) |
| [`Phase`](#contract-vllm_mlx.constrained.thinking_processor.Phase) | class | `Phase()` | Thinking lifecycle phases. | [#L51-L57](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L51-L57) |
| [`ThinkingAwareLogitsProcessor`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor) | class | `ThinkingAwareLogitsProcessor(start_token_ids: list[int], end_token_ids: list[int], thinking_token_budget: int, inner: Callable[[mx.array, mx.array], mx.array] \| None = None, vocab_size: int = 152064, prompt_has_think_tag: bool = False, no_final_content_token_limit: int \| None = None)` | Unified logits processor for thinking-model lifecycle management. | [#L60-L287](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L60-L287) |
| [`ThinkingAwareLogitsProcessor.__init__`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__init__) | method | `ThinkingAwareLogitsProcessor.__init__(start_token_ids: list[int], end_token_ids: list[int], thinking_token_budget: int, inner: Callable[[mx.array, mx.array], mx.array] \| None = None, vocab_size: int = 152064, prompt_has_think_tag: bool = False, no_final_content_token_limit: int \| None = None) -> None` | Method `ThinkingAwareLogitsProcessor.__init__` updates `self._start_matcher`, `self._end_matcher`, `self._end_token_ids`, `self._content_phase_mask_ids`; calls `BoundedSuffixMatcher`, `list`, `tuple`, `dict.fromkeys`. | [#L92-L129](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L92-L129) |
| [`ThinkingAwareLogitsProcessor.state`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.state) | method | `ThinkingAwareLogitsProcessor.state() -> Phase` | Return the current reasoning lifecycle phase. | [#L132-L135](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L132-L135) |
| [`ThinkingAwareLogitsProcessor.thinking_tokens`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.thinking_tokens) | method | `ThinkingAwareLogitsProcessor.thinking_tokens() -> int` | Return the number of generated tokens counted as reasoning. | [#L138-L141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L138-L141) |
| [`ThinkingAwareLogitsProcessor.is_retired`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.is_retired) | method | `ThinkingAwareLogitsProcessor.is_retired() -> bool` | True when the processor is in CONTENT with no inner constraint. | [#L144-L150](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L144-L150) |
| [`ThinkingAwareLogitsProcessor.__call__`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor.__call__) | method | `ThinkingAwareLogitsProcessor.__call__(tokens: mx.array, logits: mx.array) -> mx.array` | Method `ThinkingAwareLogitsProcessor.__call__` calls `self._force_transition`, `self._call_inner`, `self._sync_to_tokens`; has 3 explicit return paths. | [#L152-L170](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L152-L170) |
| [`ThinkingAwareLogitsProcessor._force_transition`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._force_transition) | method | `ThinkingAwareLogitsProcessor._force_transition(logits: mx.array) -> mx.array` | Force the next token in the reasoning end sequence. | [#L172-L182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L172-L182) |
| [`ThinkingAwareLogitsProcessor._call_inner`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._call_inner) | method | `ThinkingAwareLogitsProcessor._call_inner(tokens: mx.array, logits: mx.array) -> mx.array` | Delegate to inner processor if present. | [#L184-L188](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L184-L188) |
| [`ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens) | method | `ThinkingAwareLogitsProcessor._mask_content_phase_control_tokens(logits: mx.array) -> mx.array` | Prevent reserved think-tag starts from leaking into final content. | [#L190-L197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L190-L197) |
| [`ThinkingAwareLogitsProcessor._snapshot_state`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._snapshot_state) | method | `ThinkingAwareLogitsProcessor._snapshot_state() -> tuple[Phase, int, int, tuple[int, ...], tuple[int, ...], bool]` | Method `ThinkingAwareLogitsProcessor._snapshot_state` calls `self._start_matcher.snapshot`, `self._end_matcher.snapshot`; returns `(self._state, self._thinking_tokens, self._transition_index, self._start_matcher.snapshot(), self._end_matcher.snapshot…`. | [#L199-L209](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L199-L209) |
| [`ThinkingAwareLogitsProcessor._restore_snapshot`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._restore_snapshot) | method | `ThinkingAwareLogitsProcessor._restore_snapshot(processed_len: int) -> None` | Method `ThinkingAwareLogitsProcessor._restore_snapshot` updates `self._state`, `self._thinking_tokens`, `self._transition_index`, `self.watchdog_was_enforced`; calls `min`, `len`, `self._start_matcher.restore`, `self._end_matcher.restore`. | [#L211-L229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L211-L229) |
| [`ThinkingAwareLogitsProcessor._sync_to_tokens`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._sync_to_tokens) | method | `ThinkingAwareLogitsProcessor._sync_to_tokens(tokens: mx.array) -> None` | Method `ThinkingAwareLogitsProcessor._sync_to_tokens` updates `self._processed_len`; calls `int`, `tokens.tolist`, `min`, `self._restore_snapshot`; returns `None`. | [#L231-L252](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L231-L252) |
| [`ThinkingAwareLogitsProcessor._advance_with_token`](#contract-vllm_mlx.constrained.thinking_processor.ThinkingAwareLogitsProcessor._advance_with_token) | method | `ThinkingAwareLogitsProcessor._advance_with_token(token_id: int) -> None` | Method `ThinkingAwareLogitsProcessor._advance_with_token` updates `self._state`, `self._transition_index`, `self._thinking_tokens`, `self.watchdog_was_enforced`; calls `self._start_matcher.feed`, `self._end_matcher.feed`, `len`, `self._end_matcher.reset`; returns `None`. | [#L254-L287](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/thinking_processor.py#L254-L287) |