# `vllm_mlx.tool_parsers.harmony_tool_parser`

Harmony tool call parser for GPT-OSS models.

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

## 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.tool_parsers.harmony_tool_parser
    options:
      members:
        - _generate_tool_id
        - _COMMENTARY_BLOCK_PATTERN
        - _FINAL_BLOCK_PATTERN
        - HarmonyToolParser
        - _strip_control_tokens
        - _is_control_token
      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.tool_parsers.harmony_tool_parser._generate_tool_id" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser._generate_tool_id</code> · function</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser._generate_tool_id() -> str
```

Generate a unique tool call ID.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `str`
- Direct return expressions: `f'call_{uuid.uuid4().hex[:8]}'`

**Exceptions and behavior**

Function `_generate_tool_id` calls `uuid.uuid4`; returns `f'call_{uuid.uuid4().hex[:8]}'`.
No direct `raise` statement appears in this definition.

[View source #L32-L34](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L32-L34).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser</code> · class</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser()
```

Tool call parser for GPT-OSS models using Harmony format.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser`

**Exceptions and behavior**

Class `HarmonyToolParser` derives from `ToolParser` and declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L57-L219](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L57-L219).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls</code> · method</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls(model_output: str, request: dict[str, Any] | None = None) -> ExtractedToolCallInformation
```

Extract tool calls from a complete Harmony model response.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_output` | `str` | `yes` | `none` | Required positional or keyword input. |
| `request` | `dict[str, Any] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |

**Returns**

- Type: `ExtractedToolCallInformation`
- Direct return expressions: `ExtractedToolCallInformation(tools_called=True, tool_calls=tool_calls, content=content)`; `ExtractedToolCallInformation(tools_called=False, tool_calls=[], content=content)`

**Exceptions and behavior**

Method `HarmonyToolParser.extract_tool_calls` calls `_COMMENTARY_BLOCK_PATTERN.finditer`, `match.group`, `match.group(2).strip`, `json.loads`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L71-L140](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L71-L140).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls_streaming" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls_streaming</code> · method</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls_streaming(previous_text: str, current_text: str, delta_text: str, previous_token_ids: Sequence[int] | None = None, current_token_ids: Sequence[int] | None = None, delta_token_ids: Sequence[int] | None = None, request: dict[str, Any] | None = None) -> dict[str, Any] | None
```

Extract tool calls from streaming Harmony model output.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `previous_text` | `str` | `yes` | `none` | Required positional or keyword input. |
| `current_text` | `str` | `yes` | `none` | Required positional or keyword input. |
| `delta_text` | `str` | `yes` | `none` | Required positional or keyword input. |
| `previous_token_ids` | `Sequence[int] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `current_token_ids` | `Sequence[int] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `delta_token_ids` | `Sequence[int] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `request` | `dict[str, Any] \| None` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |

**Returns**

- Type: `dict[str, Any] | None`
- Direct return expressions: `{'content': delta_text}`; `{'tool_calls': emitted}`; `None`

**Exceptions and behavior**

Method `HarmonyToolParser.extract_tool_calls_streaming` updates `self._emitted_streaming_signatures`; calls `hasattr`, `set`, `any`, `self.extract_tool_calls`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L142-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L142-L214).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.reset" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.reset</code> · method</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.reset() -> None
```

Reset parser state for a new request.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `HarmonyToolParser.reset` updates `self._emitted_streaming_signatures`; calls `super().reset`, `super`, `set`.
No direct `raise` statement appears in this definition.

[View source #L216-L219](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L216-L219).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser._strip_control_tokens" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser._strip_control_tokens</code> · function</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser._strip_control_tokens(text: str) -> str
```

Remove Harmony control tokens from text.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `result.strip()`

**Exceptions and behavior**

Function `_strip_control_tokens` calls `result.replace`, `re.sub`, `result.strip`; returns `result.strip()`.
No direct `raise` statement appears in this definition.

[View source #L222-L240](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L222-L240).

</details>

<details class="api-contract" id="contract-vllm_mlx.tool_parsers.harmony_tool_parser._is_control_token" markdown="1">
<summary><code>vllm_mlx.tool_parsers.harmony_tool_parser._is_control_token</code> · function</summary>

```python
vllm_mlx.tool_parsers.harmony_tool_parser._is_control_token(text: str) -> bool
```

Check if text is a Harmony control token.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `text.strip() in {'<|start|>', '<|end|>', '<|message|>', '<|channel|>', '<|constrain|>', '<|return|>', '<|call|>'}`

**Exceptions and behavior**

Function `_is_control_token` calls `text.strip`; returns `text.strip() in {'<|start|>', '<|end|>', '<|message|>', '<|channel|>', '<|constrain|>', '<|return|>', '<|call|>'}`.
No direct `raise` statement appears in this definition.

[View source #L243-L253](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L243-L253).

</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 |
| --- | --- | --- | --- | --- |
| [`_generate_tool_id`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser._generate_tool_id) | function | `_generate_tool_id() -> str` | Generate a unique tool call ID. | [#L32-L34](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L32-L34) |
| [`HarmonyToolParser`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser) | class | `HarmonyToolParser()` | Tool call parser for GPT-OSS models using Harmony format. | [#L57-L219](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L57-L219) |
| [`HarmonyToolParser.extract_tool_calls`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls) | method | `HarmonyToolParser.extract_tool_calls(model_output: str, request: dict[str, Any] \| None = None) -> ExtractedToolCallInformation` | Extract tool calls from a complete Harmony model response. | [#L71-L140](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L71-L140) |
| [`HarmonyToolParser.extract_tool_calls_streaming`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.extract_tool_calls_streaming) | method | `HarmonyToolParser.extract_tool_calls_streaming(previous_text: str, current_text: str, delta_text: str, previous_token_ids: Sequence[int] \| None = None, current_token_ids: Sequence[int] \| None = None, delta_token_ids: Sequence[int] \| None = None, request: dict[str, Any] \| None = None) -> dict[str, Any] \| None` | Extract tool calls from streaming Harmony model output. | [#L142-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L142-L214) |
| [`HarmonyToolParser.reset`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser.HarmonyToolParser.reset) | method | `HarmonyToolParser.reset() -> None` | Reset parser state for a new request. | [#L216-L219](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L216-L219) |
| [`_strip_control_tokens`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser._strip_control_tokens) | function | `_strip_control_tokens(text: str) -> str` | Remove Harmony control tokens from text. | [#L222-L240](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L222-L240) |
| [`_is_control_token`](#contract-vllm_mlx.tool_parsers.harmony_tool_parser._is_control_token) | function | `_is_control_token(text: str) -> bool` | Check if text is a Harmony control token. | [#L243-L253](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/tool_parsers/harmony_tool_parser.py#L243-L253) |