Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
22.4 KB
Raw Blame
"""Normalize native MiniMax-M3 tool markup exposed by NVIDIA NIM."""

import json
import uuid
from collections.abc import AsyncIterator, Mapping, Sequence
from dataclasses import dataclass
from enum import StrEnum
from types import SimpleNamespace
from typing import Any

from free_claude_code.providers.failure_policy import RetryableToolProtocolError
from free_claude_code.providers.http import maybe_await_aclose

from .native_tool_schema import (
    arguments_match_schema,
    coerce_text_argument,
    schema_type,
)

_NAMESPACE = "]<]minimax[>["
_TOOL_BLOCK_START = f"{_NAMESPACE}<tool_call>"
_TOOL_BLOCK_END = f"{_NAMESPACE}</tool_call>"
_INVOKE_START = f"{_NAMESPACE}<invoke"
_INVOKE_END = f"{_NAMESPACE}</invoke>"
_ELEMENT_START = f"{_NAMESPACE}<"
_ELEMENT_END_START = f"{_NAMESPACE}</"
_MIXED_TEXT_FIELD = "$text"
_MAX_NATIVE_TOOL_BLOCK_CHARS = 4 * 1024 * 1024
_MAX_NATIVE_ARGUMENT_DEPTH = 64


class NimNativeToolProtocolError(RetryableToolProtocolError):
    """NIM exposed malformed model-native tool markup instead of tool deltas."""


class _NormalizedNativeToolStream(AsyncIterator[Any]):
    """Expose normalized chunks while retaining the raw stream's close contract."""

    def __init__(self, iterator: AsyncIterator[Any], source: Any) -> None:
        self._iterator = iterator
        self._source = source
        self._closed = False

    def __aiter__(self) -> _NormalizedNativeToolStream:
        return self

    async def __anext__(self) -> Any:
        if self._closed:
            raise StopAsyncIteration
        return await anext(self._iterator)

    async def aclose(self) -> None:
        if self._closed:
            return
        self._closed = True
        await maybe_await_aclose(self._iterator)
        await maybe_await_aclose(self._source)


@dataclass(frozen=True, slots=True)
class _Element:
    name: str
    text: str
    children: tuple[_Element, ...]


@dataclass(frozen=True, slots=True)
class _NativeToolCall:
    index: int
    name: str
    arguments: dict[str, Any]


class _FramingMode(StrEnum):
    TEXT = "text"
    TOOL_BLOCK = "tool_block"
    AFTER_TOOL_BLOCK = "after_tool_block"
    FINISHED = "finished"


class _MiniMaxM3ToolFramer:
    """Separate visible text from one namespace-delimited native tool block."""

    def __init__(self) -> None:
        self._mode = _FramingMode.TEXT
        self._text_tail = ""
        self._tool_tail = ""
        self._tool_parts: list[str] = []
        self._tool_length = 0
        self._tool_block: str | None = None

    @property
    def tool_block(self) -> str | None:
        return self._tool_block

    def feed(self, text: str) -> str:
        if self._mode is _FramingMode.FINISHED:
            raise RuntimeError("MiniMax-M3 tool framer is already finished")
        if not text:
            return ""
        if self._mode is _FramingMode.TOOL_BLOCK:
            self._feed_tool_block(text)
            return ""
        if self._mode is _FramingMode.AFTER_TOOL_BLOCK:
            self._validate_trailing_text(text)
            return ""

        candidate = "".join((self._text_tail, text))
        marker_index = candidate.find(_TOOL_BLOCK_START)
        held_length = _partial_marker_suffix_length(candidate, _TOOL_BLOCK_START)
        protected_namespace_index = (
            marker_index
            if marker_index >= 0
            else len(candidate) - held_length
            if held_length
            else -1
        )
        namespace_index = candidate.find(_NAMESPACE)
        if namespace_index >= 0 and namespace_index != protected_namespace_index:
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned malformed native MiniMax tool markup."
            )
        if marker_index >= 0:
            visible = candidate[:marker_index]
            self._text_tail = ""
            self._mode = _FramingMode.TOOL_BLOCK
            self._feed_tool_block(candidate[marker_index + len(_TOOL_BLOCK_START) :])
            return visible

        if held_length:
            visible = candidate[:-held_length]
            self._text_tail = candidate[-held_length:]
            return visible

        self._text_tail = ""
        return candidate

    def finish(self, *, require_complete: bool) -> str:
        if self._mode is _FramingMode.FINISHED:
            return ""
        if self._mode is _FramingMode.TEXT:
            tail = self._text_tail
            self._text_tail = ""
            self._mode = _FramingMode.FINISHED
            if _NAMESPACE in tail:
                if require_complete:
                    raise NimNativeToolProtocolError(
                        "NVIDIA NIM returned an incomplete native MiniMax tool marker."
                    )
                return ""
            return tail
        if self._mode is _FramingMode.TOOL_BLOCK and require_complete:
            self._mode = _FramingMode.FINISHED
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned an incomplete native MiniMax tool call."
            )
        self._tool_parts.clear()
        self._tool_tail = ""
        self._mode = _FramingMode.FINISHED
        return ""

    def _feed_tool_block(self, text: str) -> None:
        candidate = "".join((self._tool_tail, text))
        marker_index = candidate.find(_TOOL_BLOCK_END)
        if marker_index < 0:
            held_length = _partial_marker_suffix_length(candidate, _TOOL_BLOCK_END)
            if held_length:
                self._append_tool_fragment(candidate[:-held_length])
                self._tool_tail = candidate[-held_length:]
            else:
                self._append_tool_fragment(candidate)
                self._tool_tail = ""
            return

        self._append_tool_fragment(candidate[:marker_index])
        self._tool_block = "".join(self._tool_parts)
        self._tool_parts.clear()
        self._tool_tail = ""
        self._mode = _FramingMode.AFTER_TOOL_BLOCK
        self._validate_trailing_text(candidate[marker_index + len(_TOOL_BLOCK_END) :])

    def _append_tool_fragment(self, fragment: str) -> None:
        if not fragment:
            return
        self._tool_length += len(fragment)
        if self._tool_length > _MAX_NATIVE_TOOL_BLOCK_CHARS:
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned an oversized native MiniMax tool call."
            )
        self._tool_parts.append(fragment)

    @staticmethod
    def _validate_trailing_text(text: str) -> None:
        if text.strip():
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned content after a native MiniMax tool call."
            )


def normalize_nim_native_tool_stream(
    stream: Any,
    body: Mapping[str, Any],
) -> AsyncIterator[Any]:
    """Convert leaked MiniMax-M3 markup into ordinary OpenAI tool-call chunks."""
    schemas = _openai_tool_schemas(body)

    async def _iter() -> AsyncIterator[Any]:
        content_framer = _MiniMaxM3ToolFramer()
        reasoning_framer = _MiniMaxM3ToolFramer()
        structured_tool_calls_seen = False
        finalized = False

        async for chunk in stream:
            choices = getattr(chunk, "choices", None)
            if not choices:
                yield chunk
                continue

            choice = choices[0]
            delta = getattr(choice, "delta", None)
            if delta is None:
                yield chunk
                continue

            native_tool_calls = getattr(delta, "tool_calls", None)
            if _has_structured_tool_calls(native_tool_calls):
                structured_tool_calls_seen = True

            content = getattr(delta, "content", None)
            safe_content = (
                content_framer.feed(content) if isinstance(content, str) else content
            )
            reasoning = getattr(delta, "reasoning_content", None)
            safe_reasoning = (
                reasoning_framer.feed(reasoning)
                if isinstance(reasoning, str)
                else reasoning
            )
            finish_reason = getattr(choice, "finish_reason", None)
            generated_calls: tuple[_NativeToolCall, ...] = ()
            if finish_reason is not None:
                safe_content, safe_reasoning, generated_calls = (
                    _finish_native_tool_framers(
                        content_framer,
                        reasoning_framer,
                        content=safe_content,
                        reasoning_content=safe_reasoning,
                        schemas=schemas,
                        structured_tool_calls_seen=structured_tool_calls_seen,
                    )
                )
                finalized = True

            normalized = _normalized_chunks(
                chunk,
                choice,
                delta,
                content=safe_content,
                reasoning_content=safe_reasoning,
                generated_calls=generated_calls,
                terminal=finish_reason is not None,
            )
            for normalized_chunk in normalized:
                yield normalized_chunk

        if not finalized:
            content, reasoning, generated_calls = _finish_native_tool_framers(
                content_framer,
                reasoning_framer,
                content=None,
                reasoning_content=None,
                schemas=schemas,
                structured_tool_calls_seen=structured_tool_calls_seen,
            )
            if content or reasoning or generated_calls:
                for normalized_chunk in _synthetic_chunks(
                    content=content,
                    reasoning_content=reasoning,
                    generated_calls=generated_calls,
                ):
                    yield normalized_chunk

    return _NormalizedNativeToolStream(_iter(), stream)


def _normalized_chunks(
    source_chunk: Any,
    source_choice: Any,
    source_delta: Any,
    *,
    content: Any,
    reasoning_content: Any,
    generated_calls: tuple[_NativeToolCall, ...],
    terminal: bool,
) -> list[Any]:
    source_content = getattr(source_delta, "content", None)
    source_reasoning = getattr(source_delta, "reasoning_content", None)
    structured_calls = getattr(source_delta, "tool_calls", None)
    source_finish_reason = getattr(source_choice, "finish_reason", None)
    source_usage = getattr(source_chunk, "usage", None)

    if (
        not generated_calls
        and content == source_content
        and reasoning_content == source_reasoning
    ):
        return [source_chunk]

    chunks: list[Any] = []
    has_source_payload = (
        bool(content)
        or bool(reasoning_content)
        or _has_structured_tool_calls(structured_calls)
    )
    if has_source_payload or not generated_calls:
        chunks.append(
            _chunk(
                content=content,
                reasoning_content=reasoning_content,
                tool_calls=structured_calls,
            )
        )

    chunks.extend(_tool_call_chunk(call) for call in generated_calls)

    if not chunks:
        chunks.append(_chunk())

    if terminal:
        chunks[-1].choices[0].finish_reason = source_finish_reason
        chunks[-1].usage = source_usage
    return chunks


def _synthetic_chunks(
    *,
    content: str | None,
    reasoning_content: str | None,
    generated_calls: tuple[_NativeToolCall, ...],
) -> list[Any]:
    chunks = (
        [_chunk(content=content, reasoning_content=reasoning_content)]
        if content or reasoning_content
        else []
    )
    chunks.extend(_tool_call_chunk(call) for call in generated_calls)
    return chunks


def _finish_native_tool_framers(
    content_framer: _MiniMaxM3ToolFramer,
    reasoning_framer: _MiniMaxM3ToolFramer,
    *,
    content: Any,
    reasoning_content: Any,
    schemas: Mapping[str, dict[str, Any]],
    structured_tool_calls_seen: bool,
) -> tuple[Any, Any, tuple[_NativeToolCall, ...]]:
    require_complete = not structured_tool_calls_seen
    content = _join_optional_text(
        content,
        content_framer.finish(require_complete=require_complete),
    )
    reasoning_content = _join_optional_text(
        reasoning_content,
        reasoning_framer.finish(require_complete=require_complete),
    )
    if structured_tool_calls_seen:
        return content, reasoning_content, ()

    blocks = tuple(
        block
        for block in (content_framer.tool_block, reasoning_framer.tool_block)
        if block is not None
    )
    if len(blocks) > 1:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned native MiniMax tool calls in multiple output fields."
        )
    generated_calls = _parse_tool_block(blocks[0], schemas) if blocks else ()
    return content, reasoning_content, generated_calls


def _chunk(
    *,
    content: Any = None,
    reasoning_content: Any = None,
    tool_calls: Any = None,
) -> Any:
    return SimpleNamespace(
        choices=[
            SimpleNamespace(
                delta=SimpleNamespace(
                    content=content,
                    reasoning_content=reasoning_content,
                    tool_calls=tool_calls,
                ),
                finish_reason=None,
            )
        ],
        usage=None,
    )


def _tool_call_chunk(call: _NativeToolCall) -> Any:
    tool_call = SimpleNamespace(
        index=call.index,
        id=f"call_nim_native_{uuid.uuid4().hex}",
        function=SimpleNamespace(
            name=call.name,
            arguments=json.dumps(
                call.arguments,
                ensure_ascii=False,
                separators=(",", ":"),
            ),
        ),
    )
    return _chunk(tool_calls=[tool_call])


def _parse_tool_block(
    block: str,
    schemas: Mapping[str, dict[str, Any]],
) -> tuple[_NativeToolCall, ...]:
    cursor = 0
    calls: list[_NativeToolCall] = []
    while True:
        cursor = _skip_whitespace(block, cursor)
        if cursor == len(block):
            break
        name, body, cursor = _parse_invoke(block, cursor)
        schema = schemas.get(name)
        if schema is None:
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned a native call for an undeclared tool."
            )
        arguments = _parse_arguments(body, schema)
        _validate_arguments(name, arguments, schema)
        calls.append(
            _NativeToolCall(
                index=len(calls),
                name=name,
                arguments=arguments,
            )
        )

    if not calls:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an empty native MiniMax tool-call block."
        )
    return tuple(calls)


def _parse_invoke(text: str, cursor: int) -> tuple[str, str, int]:
    if not text.startswith(_INVOKE_START, cursor):
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned malformed native MiniMax tool markup."
        )
    tag_end = text.find(">", cursor + len(_INVOKE_START))
    if tag_end < 0:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an incomplete native MiniMax invoke tag."
        )
    attributes = text[cursor + len(_INVOKE_START) : tag_end]
    name = _parse_invoke_name(attributes)
    body_start = tag_end + 1
    body_end = text.find(_INVOKE_END, body_start)
    if body_end < 0:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an incomplete native MiniMax invoke block."
        )
    return name, text[body_start:body_end], body_end + len(_INVOKE_END)


def _parse_invoke_name(attributes: str) -> str:
    value = attributes.strip()
    if not value.startswith("name"):
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned a native MiniMax invoke without a tool name."
        )
    remainder = value[len("name") :].lstrip()
    if not remainder.startswith("="):
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned a malformed native MiniMax tool name."
        )
    remainder = remainder[1:].strip()
    if not remainder:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an empty native MiniMax tool name."
        )

    quote = remainder[0]
    if quote in {'"', "'"}:
        if len(remainder) < 2 or not remainder.endswith(quote):
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned an unterminated native MiniMax tool name."
            )
        name = remainder[1:-1]
    else:
        if any(character.isspace() for character in remainder):
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned malformed native MiniMax invoke attributes."
            )
        name = remainder

    name = name.strip()
    if not name:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an empty native MiniMax tool name."
        )
    return name


def _parse_arguments(body: str, schema: dict[str, Any]) -> dict[str, Any]:
    cursor = 0
    elements: list[_Element] = []
    while True:
        cursor = _skip_whitespace(body, cursor)
        if cursor == len(body):
            break
        element, cursor = _parse_element(body, cursor, depth=1)
        elements.append(element)
    return _elements_to_object(elements, schema)


def _parse_element(text: str, cursor: int, *, depth: int) -> tuple[_Element, int]:
    if depth > _MAX_NATIVE_ARGUMENT_DEPTH:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned excessively nested native MiniMax tool arguments."
        )
    if not text.startswith(_ELEMENT_START, cursor) or text.startswith(
        _ELEMENT_END_START, cursor
    ):
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned malformed native MiniMax tool arguments."
        )
    name_start = cursor + len(_ELEMENT_START)
    tag_end = text.find(">", name_start)
    if tag_end < 0:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an incomplete native MiniMax argument tag."
        )
    name = text[name_start:tag_end]
    if (
        not name
        or name.strip() != name
        or any(character.isspace() for character in name)
    ):
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned an invalid native MiniMax argument name."
        )

    close_tag = f"{_ELEMENT_END_START}{name}>"
    cursor = tag_end + 1
    text_parts: list[str] = []
    children: list[_Element] = []
    while True:
        marker = text.find(_NAMESPACE, cursor)
        if marker < 0:
            raise NimNativeToolProtocolError(
                "NVIDIA NIM returned an incomplete native MiniMax argument."
            )
        text_parts.append(text[cursor:marker])
        if text.startswith(close_tag, marker):
            cursor = marker + len(close_tag)
            break
        if text.startswith(_ELEMENT_START, marker) and not text.startswith(
            _ELEMENT_END_START, marker
        ):
            child, cursor = _parse_element(text, marker, depth=depth + 1)
            children.append(child)
            continue
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned mismatched native MiniMax argument tags."
        )

    return (
        _Element(
            name=name,
            text="".join(text_parts),
            children=tuple(children),
        ),
        cursor,
    )


def _elements_to_object(
    elements: Sequence[_Element],
    schema: Mapping[str, Any],
) -> dict[str, Any]:
    properties = schema.get("properties")
    property_schemas = properties if isinstance(properties, Mapping) else {}
    additional = schema.get("additionalProperties")
    output: dict[str, Any] = {}
    for element in elements:
        property_schema = property_schemas.get(element.name)
        if not isinstance(property_schema, Mapping):
            property_schema = additional if isinstance(additional, Mapping) else {}
        value = _element_value(element, property_schema)
        _append_object_value(output, element.name, value)
    return output


def _element_value(element: _Element, schema: Mapping[str, Any]) -> Any:
    declared_type = schema_type(schema)
    if element.children:
        if declared_type == "array":
            item_schema = schema.get("items")
            if not isinstance(item_schema, Mapping):
                item_schema = {}
            return [_element_value(child, item_schema) for child in element.children]

        result = _elements_to_object(element.children, schema)
        if element.text.strip():
            mixed_name = _MIXED_TEXT_FIELD
            while mixed_name in result:
                mixed_name = f"${mixed_name}"
            result[mixed_name] = element.text
        return result

    try:
        return coerce_text_argument(element.text, schema)
    except ValueError:
        raise NimNativeToolProtocolError(
            "NVIDIA NIM returned a native MiniMax argument with the wrong type."
        ) from None


def _validate_arguments(
    tool_name: str,
    arguments: dict[str, Any],
    schema: dict[str, Any],
) -> None:
    if not arguments_match_schema(arguments, schema):
        raise NimNativeToolProtocolError(
            f"NVIDIA NIM returned schema-invalid arguments for tool {tool_name!r}."
        )


def _openai_tool_schemas(body: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
    tools = body.get("tools")
    if not isinstance(tools, list):
        return {}

    schemas: dict[str, dict[str, Any]] = {}
    for tool in tools:
        if not isinstance(tool, Mapping):
            continue
        function = tool.get("function")
        if not isinstance(function, Mapping):
            continue
        name = function.get("name")
        if not isinstance(name, str) or not name:
            continue
        parameters = function.get("parameters")
        schemas[name] = dict(parameters) if isinstance(parameters, Mapping) else {}
    return schemas


def _append_object_value(output: dict[str, Any], name: str, value: Any) -> None:
    if name not in output:
        output[name] = value
        return
    existing = output[name]
    if isinstance(existing, list):
        existing.append(value)
    else:
        output[name] = [existing, value]


def _skip_whitespace(text: str, cursor: int) -> int:
    while cursor < len(text) and text[cursor].isspace():
        cursor += 1
    return cursor


def _partial_marker_suffix_length(text: str, marker: str) -> int:
    max_length = min(len(text), len(marker) - 1)
    for length in range(max_length, 0, -1):
        if marker.startswith(text[-length:]):
            return length
    return 0


def _join_optional_text(first: Any, second: str) -> Any:
    if not second:
        return first
    if isinstance(first, str):
        return "".join((first, second))
    return second


def _has_structured_tool_calls(value: Any) -> bool:
    return isinstance(value, list | tuple) and bool(value)