Skip to content

vllm_mlx.reasoning.harmony_parser

Reasoning parser for GPT-OSS models using Harmony format.

View the complete module source at #L1-L157.

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.reasoning.harmony_parser

Reasoning parser for GPT-OSS models using Harmony format.

Harmony uses channels for reasoning vs final content:

<|channel|>analysis
<|message|>Let me think about this...
<|end|>
<|channel|>final
<|message|>The answer is 42.
<|return|>

The analysis channel contains reasoning, and the final channel contains the user-facing response.

vllm_mlx.reasoning.harmony_parser._ANALYSIS_PATTERN module-attribute 

_ANALYSIS_PATTERN = re.compile('<\\|channel\\|>analysis\\s*<\\|message\\|>(.*?)<\\|end\\|>', re.DOTALL)

vllm_mlx.reasoning.harmony_parser._FINAL_PATTERN module-attribute 

_FINAL_PATTERN = re.compile('<\\|channel\\|>final\\s*<\\|message\\|>(.*?)<\\|return\\|>', re.DOTALL)

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser 

HarmonyReasoningParser(tokenizer=None)

Bases: ReasoningParser

Reasoning parser for GPT-OSS models using Harmony format.

Extracts reasoning from the 'analysis' channel and content from the 'final' channel. Commentary channels (tool calls) are ignored since they are handled by the tool parser.

Example

Input: "<|channel|>analysis<|message|>Thinking...<|end|> <|channel|>final<|message|>Result.<|return|>" Output: reasoning="Thinking...", content="Result."

Source code in vllm_mlx/reasoning/harmony_parser.py 
49
50
51
52
def __init__(self, tokenizer=None):
    super().__init__(tokenizer)
    self._current_channel: str | None = None
    self._in_message: bool = False

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser._current_channel instance-attribute 

_current_channel: str | None = None

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser._in_message instance-attribute 

_in_message: bool = False

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning 

extract_reasoning(model_output: str) -> tuple[str | None, str | None]

Extract reasoning from complete Harmony output.

Collects all analysis channel blocks as reasoning and the final channel block as content.

Parameters:

  • model_output (str) –

    Complete model output text.

Returns:

  • tuple[str | None, str | None] –

    (reasoning, content) tuple. Either may be None.

Source code in vllm_mlx/reasoning/harmony_parser.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def extract_reasoning(
    self,
    model_output: str,
) -> tuple[str | None, str | None]:
    """
    Extract reasoning from complete Harmony output.

    Collects all analysis channel blocks as reasoning and the
    final channel block as content.

    Args:
        model_output: Complete model output text.

    Returns:
        (reasoning, content) tuple. Either may be None.
    """
    # Collect all analysis blocks
    analysis_blocks = _ANALYSIS_PATTERN.findall(model_output)
    reasoning = "\n".join(block.strip() for block in analysis_blocks) or None

    # Extract final channel content
    final_match = _FINAL_PATTERN.search(model_output)
    content = final_match.group(1).strip() if final_match else None

    return reasoning, content

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning_streaming 

extract_reasoning_streaming(previous_text: str, current_text: str, delta_text: str) -> DeltaMessage | None

Extract reasoning from streaming Harmony output.

Tracks the current channel and emits reasoning deltas for analysis channel content and content deltas for final channel.

Parameters:

  • previous_text (str) –

    Accumulated text before this delta.

  • current_text (str) –

    Accumulated text including this delta.

  • delta_text (str) –

    The new text in this streaming chunk.

Returns:

  • DeltaMessage | None –

    DeltaMessage with reasoning and/or content, or None.

Source code in vllm_mlx/reasoning/harmony_parser.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def extract_reasoning_streaming(
    self,
    previous_text: str,
    current_text: str,
    delta_text: str,
) -> DeltaMessage | None:
    """
    Extract reasoning from streaming Harmony output.

    Tracks the current channel and emits reasoning deltas for
    analysis channel content and content deltas for final channel.

    Args:
        previous_text: Accumulated text before this delta.
        current_text: Accumulated text including this delta.
        delta_text: The new text in this streaming chunk.

    Returns:
        DeltaMessage with reasoning and/or content, or None.
    """
    # Detect channel switches in the delta
    if "<|channel|>" in delta_text:
        if "analysis" in delta_text:
            self._current_channel = "analysis"
            self._in_message = False
            return None
        elif "final" in delta_text:
            self._current_channel = "final"
            self._in_message = False
            return None
        elif "commentary" in delta_text:
            self._current_channel = "commentary"
            self._in_message = False
            return None

    # Detect channel from full context if not yet determined
    if self._current_channel is None and "<|channel|>" in current_text:
        last_channel = current_text.rfind("<|channel|>")
        after = current_text[last_channel + len("<|channel|>") :]
        if after.startswith("analysis"):
            self._current_channel = "analysis"
        elif after.startswith("final"):
            self._current_channel = "final"
        elif after.startswith("commentary"):
            self._current_channel = "commentary"

    # Handle message start
    if "<|message|>" in delta_text:
        self._in_message = True
        # Don't emit the token itself
        return None

    # Handle channel/message end tokens
    if any(
        token in delta_text
        for token in ("<|end|>", "<|return|>", "<|call|>", "<|start|>")
    ):
        self._in_message = False
        return None

    # Skip control tokens
    if delta_text.strip().startswith("<|") and delta_text.strip().endswith("|>"):
        return None

    # Emit content based on current channel
    if self._in_message and self._current_channel == "analysis":
        return DeltaMessage(reasoning=delta_text)

    if self._in_message and self._current_channel == "final":
        return DeltaMessage(content=delta_text)

    # In commentary or unknown channel, suppress
    return None

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.reset_state 

reset_state()

Reset streaming state for a new request.

Source code in vllm_mlx/reasoning/harmony_parser.py 
154
155
156
157
def reset_state(self):
    """Reset streaming state for a new request."""
    self._current_channel = None
    self._in_message = False

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.

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser · class 
vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser(tokenizer = None)

Reasoning parser for GPT-OSS models using Harmony format.

Parameters

Name Type Required Default Description
tokenizer not annotated no None Optional positional or keyword input; defaults to None.

Returns

  • Constructs: vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser

Exceptions and behavior

Class HarmonyReasoningParser derives from ReasoningParser and declares 4 direct member(s). No direct raise statement appears in this definition.

View source #L35-L157.

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.__init__ · method 
vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.__init__(tokenizer = None) -> not annotated

Method HarmonyReasoningParser.__init__ updates self._current_channel, self._in_message; calls super().__init__, super.

Parameters

Name Type Required Default Description
tokenizer not annotated no None Optional positional or keyword input; defaults to None.

Returns

  • Type: not annotated

Exceptions and behavior

Method HarmonyReasoningParser.__init__ updates self._current_channel, self._in_message; calls super().__init__, super. No direct raise statement appears in this definition.

View source #L49-L52.

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning · method 
vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning(model_output: str) -> tuple[str | None, str | None]

Extract reasoning from complete Harmony output.

Parameters

Name Type Required Default Description
model_output str yes none Complete model output text.

Returns

  • Type: tuple[str | None, str | None]
  • Direct return expressions: (reasoning, content)

Exceptions and behavior

Method HarmonyReasoningParser.extract_reasoning calls _ANALYSIS_PATTERN.findall, '\n'.join, block.strip, _FINAL_PATTERN.search; returns (reasoning, content). No direct raise statement appears in this definition.

View source #L54-L78.

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning_streaming · method 
vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.extract_reasoning_streaming(previous_text: str, current_text: str, delta_text: str) -> DeltaMessage | None

Extract reasoning from streaming Harmony output.

Parameters

Name Type Required Default Description
previous_text str yes none Accumulated text before this delta.
current_text str yes none Accumulated text including this delta.
delta_text str yes none The new text in this streaming chunk.

Returns

  • Type: DeltaMessage | None
  • Direct return expressions: None; DeltaMessage(reasoning=delta_text); DeltaMessage(content=delta_text)

Exceptions and behavior

Method HarmonyReasoningParser.extract_reasoning_streaming updates self._current_channel, self._in_message; calls current_text.rfind, len, after.startswith, any; has 3 explicit return paths. No direct raise statement appears in this definition.

View source #L80-L152.

vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.reset_state · method 
vllm_mlx.reasoning.harmony_parser.HarmonyReasoningParser.reset_state() -> not annotated

Reset streaming state for a new request.

Parameters

This callable has no explicit inputs.

Returns

  • Type: not annotated

Exceptions and behavior

Method HarmonyReasoningParser.reset_state updates self._current_channel, self._in_message. No direct raise statement appears in this definition.

View source #L154-L157.

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
HarmonyReasoningParser class HarmonyReasoningParser(tokenizer = None) Reasoning parser for GPT-OSS models using Harmony format. #L35-L157
HarmonyReasoningParser.__init__ method HarmonyReasoningParser.__init__(tokenizer = None) -> not annotated Method HarmonyReasoningParser.__init__ updates self._current_channel, self._in_message; calls super().__init__, super. #L49-L52
HarmonyReasoningParser.extract_reasoning method HarmonyReasoningParser.extract_reasoning(model_output: str) -> tuple[str \| None, str \| None] Extract reasoning from complete Harmony output. #L54-L78
HarmonyReasoningParser.extract_reasoning_streaming method HarmonyReasoningParser.extract_reasoning_streaming(previous_text: str, current_text: str, delta_text: str) -> DeltaMessage \| None Extract reasoning from streaming Harmony output. #L80-L152
HarmonyReasoningParser.reset_state method HarmonyReasoningParser.reset_state() -> not annotated Reset streaming state for a new request. #L154-L157