feat(tool): add qwen xml tool parser and rename tool call parser to tool parser

Author: Lawhy

CHANGELOG.md

@@ -29,7 +29,7 @@ pytest tests/unit/ -v
 pytest tests/unit/test_sglang.py -v
 
 # Single test
-pytest tests/unit/test_tool_parser.py::TestHermesToolCallParser::test_parse_single_tool_call -v
+pytest tests/unit/test_tool_parser.py::TestHermesToolParser::test_parse_single_tool_call -v
 
 # Unit tests with coverage
 pytest tests/unit/ -v --cov=src/strands_sglang --cov-report=html
@@ -49,7 +49,7 @@ The package lives in `src/strands_sglang/` with 5 core modules:
 
 **TokenManager** (`token.py`) - Segment-based token accumulation for TITO. Tokens organized into PROMPT segments (loss_mask=0) and RESPONSE segments (loss_mask=1) matching multi-turn conversation structure. Exposes `token_ids`, `loss_mask`, `logprobs`, and `segments` properties.
 
-**ToolCallParser** (`tool_parser.py`) - Abstract base with `HermesToolCallParser` implementation. Parses XML-wrapped JSON tool calls (`<tool_call>{"name": ..., "arguments": ...}</tool_call>`). Strict parsing: only catches JSONDecodeError, propagates failures as tool calls with `raw` content for model feedback. Excludes tool calls inside `<think>` blocks.
+**ToolParser** (`tool_parsers/`) - Abstract base with `HermesToolParser` and `QwenXMLToolParser` implementations. Parses tool calls from model output. Strict parsing: only catches JSONDecodeError, propagates failures as tool calls with `raw` content for model feedback. Excludes tool calls inside `<think>` blocks. New parsers self-register via `@register_tool_parser` decorator.
 
 **ToolIterationLimiter** (`tool_limiter.py`) - Strands hook enforcing max tool iterations per invocation. One iteration = model response with tool calls + execution + result returned. Raises `MaxToolIterationsReachedError`.
 

CLAUDE.md

@@ -24,7 +24,7 @@
 
 from strands_sglang import SGLangModel
 from strands_sglang.client import SGLangClient
-from strands_sglang.tool_parser import HermesToolCallParser
+from strands_sglang.tool_parsers import HermesToolParser
 
 
 async def main():
@@ -44,7 +44,7 @@ async def main():
     model = SGLangModel(
         tokenizer=tokenizer,
         client=client,
-        tool_call_parser=HermesToolCallParser(),
+        tool_parser=HermesToolParser(),
         model_id=model_id,
         params={"max_new_tokens": 16384},  # Limit response length
     )

examples/math_agent.py

@@ -27,7 +27,7 @@
 
 from strands_sglang import SGLangModel
 from strands_sglang.client import SGLangClient
-from strands_sglang.tool_parser import HermesToolCallParser
+from strands_sglang.tool_parsers import HermesToolParser
 
 
 def find_drift_index(original: list[int], re_encoded: list[int]) -> int | None:
@@ -53,7 +53,7 @@ async def main():
     model = SGLangModel(
         tokenizer=tokenizer,
         client=client,
-        tool_call_parser=HermesToolCallParser(),
+        tool_parser=HermesToolParser(),
         model_id=model_id,
         params={"max_new_tokens": 32768},
     )

examples/retokenization_drift/main.py

@@ -54,7 +54,7 @@
 
 from .client import SGLangClient
 from .token import TokenManager
-from .tool_parsers import HermesToolCallParser, ToolCallParser, ToolCallParseResult
+from .tool_parsers import HermesToolParser, ToolParser, ToolParseResult
 
 if TYPE_CHECKING:
     from transformers import PreTrainedTokenizerBase
@@ -72,7 +72,7 @@ class SGLangModel(Model):
         tokenizer: HuggingFace tokenizer for encoding/decoding.
         client: SGLangClient for HTTP communication with the SGLang server.
         token_manager: Tracks tokens, logprobs, and masks for on-policy training.
-        tool_call_parser: Parser for extracting tool calls from model output.
+        tool_parser: Parser for extracting tool calls from model output.
 
     Example:
         >>> from transformers import AutoTokenizer
@@ -99,22 +99,22 @@ def __init__(
         *,
         tokenizer: PreTrainedTokenizerBase,
         client: SGLangClient,
-        tool_call_parser: ToolCallParser | None = None,
+        tool_parser: ToolParser | None = None,
         **model_config: Unpack[SGLangConfig],
     ) -> None:
         """Initialize SGLang model provider.
 
         Args:
             tokenizer: HuggingFace tokenizer for chat template and tokenization.
             client: SGLangClient for HTTP communication with the SGLang server.
-            tool_call_parser: Parser for tool calls (default: HermesToolCallParser).
+            tool_parser: Parser for tool calls (default: HermesToolParser).
             **model_config: See SGLangConfig for available options.
         """
 
         # Essential attributes
         self.tokenizer = tokenizer
         self.client = client
-        self.tool_call_parser = tool_call_parser or HermesToolCallParser()
+        self.tool_parser = tool_parser or HermesToolParser()
 
         # Config
         self.config = dict(model_config)
@@ -274,8 +274,8 @@ def tokenize_prompt_messages(
             # Prepend message separator to align with chat template.
             # The model generates up to <|im_end|>, but the chat template adds
             # a separator (e.g., "\n") before the next <|im_start|>.
-            if self.tool_call_parser:
-                formatted = self.tool_call_parser.message_separator + formatted
+            if self.tool_parser:
+                formatted = self.tool_parser.message_separator + formatted
 
             return self.tokenizer.encode(formatted, add_special_tokens=False)
 
@@ -300,7 +300,7 @@ def _sort_tool_results(self, messages: Messages) -> Messages:
 
     def _yield_tool_use_events(
         self,
-        tool_calls: list[ToolCallParseResult],
+        tool_calls: list[ToolParseResult],
     ) -> Iterator[StreamEvent]:
         """Yield toolUse stream events for parsed tool calls.
 
@@ -424,7 +424,7 @@ async def stream(
         yield {"contentBlockStop": {}}
 
         # Parse tool calls and yield events
-        parsed_tool_calls = self.tool_call_parser.parse(text)
+        parsed_tool_calls = self.tool_parser.parse(text)
         for event in self._yield_tool_use_events(parsed_tool_calls):
             yield event
 

src/strands_sglang/sglang.py

@@ -21,49 +21,27 @@
 - Only handle `JSONDecodeError` (can't extract anything from malformed JSON)
 - Let Strands validate arguments against tool schemas
 - Parse errors become tool calls with error info for model feedback
-"""
-
-from typing import Any
-
-from .base import UNKNOWN_TOOL_NAME, ToolCallParser, ToolCallParseResult
-from .hermes import HermesToolCallParser
-
-# Parser registry
-TOOL_PARSER_REGISTRY: dict[str, type[ToolCallParser]] = {
-    "hermes": HermesToolCallParser,
-}
-
 
-def get_tool_parser(name: str, **kwargs: Any) -> ToolCallParser:
-    """Get a tool parser by name.
-
-    Args:
-        name: Parser name (e.g., "hermes").
-        **kwargs: Arguments passed to the parser constructor.
-
-    Returns:
-        Instantiated parser.
-
-    Raises:
-        KeyError: If parser name is not registered.
+Adding a new parser:
+    1. Create a new file (e.g., `my_parser.py`)
+    2. Decorate the class with `@register_tool_parser("my_parser")`
+    3. Import the module here to trigger registration
+"""
 
-    Example:
-        >>> parser = get_tool_parser("hermes")
-        >>> parser = get_tool_parser("hermes", think_tokens=None)
-    """
-    if name not in TOOL_PARSER_REGISTRY:
-        available = ", ".join(sorted(TOOL_PARSER_REGISTRY.keys()))
-        raise KeyError(f"Unknown tool parser: {name!r}. Available: {available}")
-    return TOOL_PARSER_REGISTRY[name](**kwargs)
+from .base import TOOL_PARSER_REGISTRY, UNKNOWN_TOOL_NAME, ToolParser, ToolParseResult, get_tool_parser
 
+# Import parsers to trigger registration via @register_tool_parser decorator
+from .hermes import HermesToolParser
+from .qwen_xml import QwenXMLToolParser
 
 __all__ = [
     # Base
-    "ToolCallParseResult",
-    "ToolCallParser",
+    "ToolParseResult",
+    "ToolParser",
     "UNKNOWN_TOOL_NAME",
     # Parsers
-    "HermesToolCallParser",
+    "HermesToolParser",
+    "QwenXMLToolParser",
     # Registry
     "TOOL_PARSER_REGISTRY",
     "get_tool_parser",

src/strands_sglang/tool_parsers/__init__.py

@@ -19,14 +19,19 @@
 import json
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Callable, TypeVar
 
 # Fallback tool name when we can't identify which tool the model tried to call
 UNKNOWN_TOOL_NAME = "unknown_tool"
 
+# Parser registry - populated by @register_tool_parser decorator
+TOOL_PARSER_REGISTRY: dict[str, type[ToolParser]] = {}
+
+T = TypeVar("T", bound="ToolParser")
+
 
 @dataclass(frozen=True, slots=True)
-class ToolCallParseResult:
+class ToolParseResult:
     """A parsed tool call request.
 
     For successful parses: name and input are populated, raw is None.
@@ -55,7 +60,7 @@ def payload(self) -> str:
         return json.dumps(self.input)
 
 
-class ToolCallParser(ABC):
+class ToolParser(ABC):
     """Base class for tool call parsers.
 
     Subclasses implement `parse` to extract tool calls from model output.
@@ -82,7 +87,7 @@ def message_separator(self) -> str:
         return ""
 
     @abstractmethod
-    def parse(self, text: str) -> list[ToolCallParseResult]:
+    def parse(self, text: str) -> list[ToolParseResult]:
         """Parse tool calls from model output text.
 
         Args:
@@ -104,3 +109,48 @@ def __call__(self, text: str) -> list[dict[str, Any]]:
         """
         results = self.parse(text)
         return [{"id": tc.id, "name": tc.name, "input": tc.input} for tc in results if not tc.is_error]
+
+
+def register_tool_parser(name: str) -> Callable[[type[T]], type[T]]:
+    """Decorator to register a tool parser class.
+
+    Args:
+        name: Registry name for the parser.
+
+    Returns:
+        Decorator that registers the class and returns it unchanged.
+
+    Example:
+        >>> @register_tool_parser("my_parser")
+        ... class MyParser(ToolParser):
+        ...     def parse(self, text): ...
+    """
+
+    def decorator(cls: type[T]) -> type[T]:
+        TOOL_PARSER_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def get_tool_parser(name: str, **kwargs: Any) -> ToolParser:
+    """Get a tool parser by name.
+
+    Args:
+        name: Parser name (e.g., "hermes", "qwen_xml").
+        **kwargs: Arguments passed to the parser constructor.
+
+    Returns:
+        Instantiated parser.
+
+    Raises:
+        KeyError: If parser name is not registered.
+
+    Example:
+        >>> parser = get_tool_parser("hermes")
+        >>> parser = get_tool_parser("hermes", think_tokens=None)
+    """
+    if name not in TOOL_PARSER_REGISTRY:
+        available = ", ".join(sorted(TOOL_PARSER_REGISTRY.keys()))
+        raise KeyError(f"Unknown tool parser: {name!r}. Available: {available}")
+    return TOOL_PARSER_REGISTRY[name](**kwargs)