vllm_mlx.reasoning.gpt_oss_parser

Reasoning parser for GPT-OSS models using channel-based format.

View the complete module source at #L1-L214.

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.gpt_oss_parser

Reasoning parser for GPT-OSS models using channel-based format.

GPT-OSS models use a channel-based token format instead of ... tags: <|channel|>analysis<|message|>[reasoning]<|start|>assistant<|channel|>final<|message|>[content]<|return|>

Some models also emit an extended format with a constrain token

<|channel|>final <|constrain|>JSON<|message|>[content]<|return|>

This parser extracts reasoning from the 'analysis' channel and content from the 'final' channel, stripping all structural tokens from API responses.

vllm_mlx.reasoning.gpt_oss_parser._STRUCTURAL_TOKENS module-attribute

_STRUCTURAL_TOKENS = re.compile('<\\|start\\|>|<\\|end\\|>|<\\|channel\\|>|<\\|return\\|>|<\\|call\\|>|<\\|constrain\\|>')

vllm_mlx.reasoning.gpt_oss_parser._CHANNEL_RE module-attribute

_CHANNEL_RE = re.compile('<\\|channel\\|>(analysis|final)(?:[^<]*(?:<\\|constrain\\|>[^<]*)?)?<\\|message\\|>')

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser

GptOssReasoningParser(tokenizer: Any | None = None)

Bases: ReasoningParser

Reasoning parser for GPT-OSS models.

GPT-OSS uses channel-based tokens

<|channel|>analysis<|message|>[reasoning] <|start|>assistant<|channel|>final<|message|>[content]<|return|>

The 'analysis' channel maps to reasoning, 'final' to content.

Also handles extended format with constrain token

<|channel|>final <|constrain|>JSON<|message|>[content]<|return|>

Source code in vllm_mlx/reasoning/base.py

def __init__(self, tokenizer: Any | None = None):
    """
    Initialize parser with optional tokenizer.

    Args:
        tokenizer: Optional tokenizer for token-based parsing. For vllm-mlx,
                  text-based parsing is sufficient, so this is optional.
    """
    self.tokenizer = tokenizer

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning

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

Extract reasoning and content from complete model output.

Parameters:

• model_output (str) –

  Complete text output from the model.

Returns:

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

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

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

def extract_reasoning(
    self,
    model_output: str,
) -> tuple[str | None, str | None]:
    """
    Extract reasoning and content from complete model output.

    Args:
        model_output: Complete text output from the model.

    Returns:
        (reasoning, content) tuple. Either may be None.
    """
    if not model_output or "<|channel|>" not in model_output:
        return None, model_output if model_output else None

    reasoning = _extract_channel(model_output, "analysis")
    content = _extract_channel(model_output, "final")

    # Strip trailing <|return|>
    if content:
        content = content.replace("<|return|>", "").strip()
        content = _STRUCTURAL_TOKENS.sub("", content).strip()
        content = content if content else None

    # Strip any remaining structural tokens from reasoning
    if reasoning:
        reasoning = _STRUCTURAL_TOKENS.sub("", reasoning).strip()
        reasoning = reasoning if reasoning else None

    # If no channels found, return as plain content
    if reasoning is None and content is None:
        return None, model_output

    return reasoning, content

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning_streaming

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

Extract reasoning from streaming delta.

Uses stateless phase detection from current_text on each call.

Parameters:

• previous_text (str) –

  Accumulated text before this delta.

• current_text (str) –

  Accumulated text including this delta.

• delta_text (str) –

  Just the new text in this streaming chunk.

Returns:

• DeltaMessage | None –

  DeltaMessage with reasoning and/or content, or None to skip.

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

def extract_reasoning_streaming(
    self,
    previous_text: str,
    current_text: str,
    delta_text: str,
) -> DeltaMessage | None:
    """
    Extract reasoning from streaming delta.

    Uses stateless phase detection from current_text on each call.

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

    Returns:
        DeltaMessage with reasoning and/or content, or None to skip.
    """
    prev_phase = self._detect_phase(previous_text)
    curr_phase = self._detect_phase(current_text)

    # Phase changed — extract content after the new marker
    if curr_phase != prev_phase and curr_phase in ("analysis", "final"):
        after_marker = self._extract_content_after_marker_in_delta(
            current_text, curr_phase
        )
        if after_marker:
            after_marker = self._strip_return(after_marker)
            if curr_phase == "analysis":
                return DeltaMessage(reasoning=after_marker)
            else:
                return DeltaMessage(content=after_marker)
        return None

    # In a steady phase — emit delta directly
    if curr_phase == "analysis":
        cleaned = self._strip_return(delta_text)
        # Skip structural tokens in the delta
        if _STRUCTURAL_TOKENS.search(cleaned):
            cleaned = _STRUCTURAL_TOKENS.sub("", cleaned)
        if cleaned:
            return DeltaMessage(reasoning=cleaned)
        return None
    elif curr_phase == "final":
        cleaned = self._strip_return(delta_text)
        if _STRUCTURAL_TOKENS.search(cleaned):
            cleaned = _STRUCTURAL_TOKENS.sub("", cleaned)
        if cleaned:
            return DeltaMessage(content=cleaned)
        return None

    # init or transition phase — skip structural tokens
    return None

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._detect_phase staticmethod

_detect_phase(text: str) -> str

Detect current streaming phase from accumulated text.

Returns:

• str –

  "final" — final channel marker complete

• str –

  "analysis" — analysis marker complete, no structural token after

• str –

  "transition" — analysis present but structural token follows

• str –

  "init" — no channel marker yet

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

@staticmethod
def _detect_phase(text: str) -> str:
    """
    Detect current streaming phase from accumulated text.

    Returns:
        "final"      — final channel marker complete
        "analysis"   — analysis marker complete, no structural token after
        "transition" — analysis present but structural token follows
        "init"       — no channel marker yet
    """
    # Find all channel markers in text
    matches = list(_CHANNEL_RE.finditer(text))
    if not matches:
        return "init"

    last = matches[-1]
    if last.group(1) == "final":
        return "final"

    # analysis channel found — check if there's a structural token after
    after = text[last.end() :]
    if _STRUCTURAL_TOKENS.search(after):
        return "transition"
    return "analysis"

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._extract_content_after_marker_in_delta staticmethod

_extract_content_after_marker_in_delta(current_text: str, phase: str) -> str | None

When phase changes, extract only the content after the phase marker that falls within the current accumulated text's tail.

Parameters:

• current_text (str) –

  Full accumulated text.

• phase (str) –

  Current phase ("analysis" or "final").

Returns:

• str | None –

  Content after the marker, or None.

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

@staticmethod
def _extract_content_after_marker_in_delta(
    current_text: str, phase: str
) -> str | None:
    """
    When phase changes, extract only the content after the phase marker
    that falls within the current accumulated text's tail.

    Args:
        current_text: Full accumulated text.
        phase: Current phase ("analysis" or "final").

    Returns:
        Content after the marker, or None.
    """
    channel_name = "analysis" if phase == "analysis" else "final"
    matches = list(_CHANNEL_RE.finditer(current_text))
    for m in reversed(matches):
        if m.group(1) == channel_name:
            return current_text[m.end() :]
    return None

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._strip_return staticmethod

_strip_return(text: str) -> str

Strip <|return|> from text.

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

@staticmethod
def _strip_return(text: str) -> str:
    """Strip <|return|> from text."""
    return text.replace("<|return|>", "")

vllm_mlx.reasoning.gpt_oss_parser._extract_channel

_extract_channel(text: str, channel_name: str) -> str | None

Extract content from a named channel.

Finds <|channel|>{name}...<|message|> (with optional constrain token) and extracts text up to the next structural token or end of string.

Parameters:

• text (str) –

  Full model output text.

• channel_name (str) –

  Channel name to extract (e.g., "analysis", "final").

Returns:

• str | None –

  Extracted channel content, or None if channel not found.

Source code in vllm_mlx/reasoning/gpt_oss_parser.py

def _extract_channel(text: str, channel_name: str) -> str | None:
    """
    Extract content from a named channel.

    Finds <|channel|>{name}...<|message|> (with optional constrain token)
    and extracts text up to the next structural token or end of string.

    Args:
        text: Full model output text.
        channel_name: Channel name to extract (e.g., "analysis", "final").

    Returns:
        Extracted channel content, or None if channel not found.
    """
    for m in _CHANNEL_RE.finditer(text):
        if m.group(1) == channel_name:
            start = m.end()
            # Find next structural token after message content
            end_match = _STRUCTURAL_TOKENS.search(text, start)
            content = text[start : end_match.start()] if end_match else text[start:]
            content = content.strip()
            return content if content else None
    return None

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.gpt_oss_parser._extract_channel · function

vllm_mlx.reasoning.gpt_oss_parser._extract_channel(text: str, channel_name: str) -> str | None

Extract content from a named channel.

Parameters

Name	Type	Required	Default	Description
text	str	yes	none	Full model output text.
channel_name	str	yes	none	Channel name to extract (e.g., "analysis", "final").

Returns

• Type: str | None
• Direct return expressions: content if content else None; None

Exceptions and behavior

Function _extract_channel calls _CHANNEL_RE.finditer, m.group, m.end, _STRUCTURAL_TOKENS.search; has 2 explicit return paths. No direct raise statement appears in this definition.

View source #L33-L55.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser · class

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser()

Reasoning parser for GPT-OSS models.

Parameters

This callable has no explicit inputs.

Returns

• Constructs: vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser

Exceptions and behavior

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

View source #L58-L214.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning · method

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning(model_output: str) -> tuple[str | None, str | None]

Extract reasoning and content from complete model output.

Parameters

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

Returns

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

Exceptions and behavior

Method GptOssReasoningParser.extract_reasoning calls _extract_channel, content.replace('<|return|>', '').strip, content.replace, _STRUCTURAL_TOKENS.sub('', content).strip; has 3 explicit return paths. No direct raise statement appears in this definition.

View source #L72-L106.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning_streaming · method

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser.extract_reasoning_streaming(previous_text: str, current_text: str, delta_text: str) -> DeltaMessage | None

Extract reasoning from streaming delta.

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	Just the new text in this streaming chunk.

Returns

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

Exceptions and behavior

Method GptOssReasoningParser.extract_reasoning_streaming calls self._detect_phase, self._extract_content_after_marker_in_delta, self._strip_return, DeltaMessage; has 5 explicit return paths. No direct raise statement appears in this definition.

View source #L108-L161.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._detect_phase · method

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._detect_phase(text: str) -> str

Detect current streaming phase from accumulated text.

Parameters

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

Returns

• Type: str
• Direct return expressions: 'init'; 'final'; 'transition'; 'analysis'

Exceptions and behavior

Method GptOssReasoningParser._detect_phase calls list, _CHANNEL_RE.finditer, last.group, last.end; has 4 explicit return paths. No direct raise statement appears in this definition.

View source #L164-L187.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._extract_content_after_marker_in_delta · method

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._extract_content_after_marker_in_delta(current_text: str, phase: str) -> str | None

When phase changes, extract only the content after the phase marker that falls within the current accumulated text's tail.

Parameters

Name	Type	Required	Default	Description
current_text	str	yes	none	Full accumulated text.
phase	str	yes	none	Current phase ("analysis" or "final").

Returns

• Type: str | None
• Direct return expressions: current_text[m.end():]; None

Exceptions and behavior

Method GptOssReasoningParser._extract_content_after_marker_in_delta calls list, _CHANNEL_RE.finditer, reversed, m.group; has 2 explicit return paths. No direct raise statement appears in this definition.

View source #L190-L209.

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._strip_return · method

vllm_mlx.reasoning.gpt_oss_parser.GptOssReasoningParser._strip_return(text: str) -> str

Strip <|return|> from text.

Parameters

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

Returns

• Type: str
• Direct return expressions: text.replace('<|return|>', '')

Exceptions and behavior

Method GptOssReasoningParser._strip_return calls text.replace; returns text.replace('<|return|>', ''). No direct raise statement appears in this definition.

View source #L212-L214.

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
_extract_channel	function	_extract_channel(text: str, channel_name: str) -> str \| None	Extract content from a named channel.	#L33-L55
GptOssReasoningParser	class	GptOssReasoningParser()	Reasoning parser for GPT-OSS models.	#L58-L214
GptOssReasoningParser.extract_reasoning	method	GptOssReasoningParser.extract_reasoning(model_output: str) -> tuple[str \| None, str \| None]	Extract reasoning and content from complete model output.	#L72-L106
GptOssReasoningParser.extract_reasoning_streaming	method	GptOssReasoningParser.extract_reasoning_streaming(previous_text: str, current_text: str, delta_text: str) -> DeltaMessage \| None	Extract reasoning from streaming delta.	#L108-L161
GptOssReasoningParser._detect_phase	method	GptOssReasoningParser._detect_phase(text: str) -> str	Detect current streaming phase from accumulated text.	#L164-L187
GptOssReasoningParser._extract_content_after_marker_in_delta	method	GptOssReasoningParser._extract_content_after_marker_in_delta(current_text: str, phase: str) -> str \| None	When phase changes, extract only the content after the phase marker that falls within the current accumulated text's tail.	#L190-L209
GptOssReasoningParser._strip_return	method	GptOssReasoningParser._strip_return(text: str) -> str	Strip <|return|> from text.	#L212-L214