unswallow 0.1.0__tar.gz

unswallow-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: unswallow
+Version: 0.1.0
+Summary: Detect and recover tool calls trapped inside a model's reasoning channel — the reasoning-channel swallow bug class across vLLM, SGLang, and llama.cpp. 1:1 mirror of the TypeScript library.
+License: MIT
+Project-URL: Homepage, https://github.com/0DukePan/unswallow
+Project-URL: Repository, https://github.com/0DukePan/unswallow
+Project-URL: Issues, https://github.com/0DukePan/unswallow/issues
+Keywords: llm,agents,tool-calls,tool-use,function-calling,reasoning,thinking,vllm,sglang,llama.cpp,qwen3,deepseek,openai-compatible
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# unswallow (Python)
+
+The 1:1 Python mirror of the `unswallow` TypeScript library: detect and recover tool calls trapped inside a model's reasoning channel — the reasoning-channel swallow bug class across vLLM, SGLang, and llama.cpp.
+
+```bash
+pip install unswallow
+```
+
+```python
+from unswallow import check_and_rescue
+
+result = check_and_rescue(
+    raw_provider_response,
+    engine_hint="vllm",
+    engine_version="0.19.0",
+    tool_schemas=my_tools,
+)
+
+if result.recovered and result.recovered_response:
+    return result.recovered_response   # tool_calls is populated, finish_reason is "tool_calls"
+```
+
+Same interface, same semantics, same bundled matrix data (synced from `packages/matrix/data/engine-matrix.json`), zero runtime dependencies, Python 3.9+.
+
+## Streaming
+
+```python
+from unswallow import check_and_rescue_stream
+
+result = await check_and_rescue_stream(
+    chunk_iterable,          # AsyncIterable of OpenAI-compatible SSE chunks
+    engine_hint="vllm",
+    engine_version="0.19.0",
+    on_leak=logger.warning,  # live pattern-C signal, optional
+)
+```
+
+Or accumulate manually with `StreamAccumulator` (`.push(chunk)` / `.end()`).
+
+## History hygiene (Pattern D)
+
+```python
+from unswallow import sanitize_history, strip_reasoning_tags
+
+clean = sanitize_history(messages)
+text = strip_reasoning_tags(assistant_text)  # "< thinking>\nplan\n< response>\nanswer" -> "answer"
+```
+
+## CLI
+
+```bash
+unswallow check                                   # bundled self-test demo (vLLM #39056)
+unswallow check --fixture response.json           # captured raw response
+unswallow check --endpoint http://localhost:8000/v1 --model Qwen/Qwen3.5-35B-A3B-FP8 --engine vllm --version 0.19.0
+unswallow matrix
+```
+
+Exit codes for live probes: `0` = not affected, `1` = affected, `2` = error.
+
+## Development
+
+```bash
+cd packages/python
+python -m unittest discover -s tests -v    # stdlib-only test suite
+```
+
+The engine matrix is bundled as data — after editing `packages/matrix/data/engine-matrix.json`, run `python packages/python/scripts/sync_matrix.py` from the repo root. CI verifies the copies stay identical.
+
+Everything else — patterns, confidence scoring, the false-positive guard, the benchmark corpus and the engine matrix — is documented in the repository root [README](../../README.md).

unswallow-0.1.0/README.md

@@ -0,0 +1,69 @@
+# unswallow (Python)
+
+The 1:1 Python mirror of the `unswallow` TypeScript library: detect and recover tool calls trapped inside a model's reasoning channel — the reasoning-channel swallow bug class across vLLM, SGLang, and llama.cpp.
+
+```bash
+pip install unswallow
+```
+
+```python
+from unswallow import check_and_rescue
+
+result = check_and_rescue(
+    raw_provider_response,
+    engine_hint="vllm",
+    engine_version="0.19.0",
+    tool_schemas=my_tools,
+)
+
+if result.recovered and result.recovered_response:
+    return result.recovered_response   # tool_calls is populated, finish_reason is "tool_calls"
+```
+
+Same interface, same semantics, same bundled matrix data (synced from `packages/matrix/data/engine-matrix.json`), zero runtime dependencies, Python 3.9+.
+
+## Streaming
+
+```python
+from unswallow import check_and_rescue_stream
+
+result = await check_and_rescue_stream(
+    chunk_iterable,          # AsyncIterable of OpenAI-compatible SSE chunks
+    engine_hint="vllm",
+    engine_version="0.19.0",
+    on_leak=logger.warning,  # live pattern-C signal, optional
+)
+```
+
+Or accumulate manually with `StreamAccumulator` (`.push(chunk)` / `.end()`).
+
+## History hygiene (Pattern D)
+
+```python
+from unswallow import sanitize_history, strip_reasoning_tags
+
+clean = sanitize_history(messages)
+text = strip_reasoning_tags(assistant_text)  # "< thinking>\nplan\n< response>\nanswer" -> "answer"
+```
+
+## CLI
+
+```bash
+unswallow check                                   # bundled self-test demo (vLLM #39056)
+unswallow check --fixture response.json           # captured raw response
+unswallow check --endpoint http://localhost:8000/v1 --model Qwen/Qwen3.5-35B-A3B-FP8 --engine vllm --version 0.19.0
+unswallow matrix
+```
+
+Exit codes for live probes: `0` = not affected, `1` = affected, `2` = error.
+
+## Development
+
+```bash
+cd packages/python
+python -m unittest discover -s tests -v    # stdlib-only test suite
+```
+
+The engine matrix is bundled as data — after editing `packages/matrix/data/engine-matrix.json`, run `python packages/python/scripts/sync_matrix.py` from the repo root. CI verifies the copies stay identical.
+
+Everything else — patterns, confidence scoring, the false-positive guard, the benchmark corpus and the engine matrix — is documented in the repository root [README](../../README.md).

unswallow-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unswallow"
+version = "0.1.0"
+description = "Detect and recover tool calls trapped inside a model's reasoning channel — the reasoning-channel swallow bug class across vLLM, SGLang, and llama.cpp. 1:1 mirror of the TypeScript library."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = [
+  "llm",
+  "agents",
+  "tool-calls",
+  "tool-use",
+  "function-calling",
+  "reasoning",
+  "thinking",
+  "vllm",
+  "sglang",
+  "llama.cpp",
+  "qwen3",
+  "deepseek",
+  "openai-compatible",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/0DukePan/unswallow"
+Repository = "https://github.com/0DukePan/unswallow"
+Issues = "https://github.com/0DukePan/unswallow/issues"
+
+[project.scripts]
+unswallow = "unswallow.cli:main"
+
+[tool.setuptools]
+packages = ["unswallow"]
+
+[tool.setuptools.package-data]
+unswallow = ["data/*.json"]

unswallow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unswallow-0.1.0/tests/test_core.py

@@ -0,0 +1,234 @@
+import unittest
+
+from unswallow import check_and_rescue, match_matrix_entry, normalize_engine
+
+
+def response(message, finish_reason="stop"):
+    return {
+        "id": "chatcmpl-test",
+        "object": "chat.completion",
+        "model": "test-model",
+        "choices": [{"index": 0, "finish_reason": finish_reason, "message": message}],
+    }
+
+
+class CoreTest(unittest.TestCase):
+    def test_pattern_a_function_xml_in_reasoning(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\nI need to answer the user\u2019s question. The answer is 204.\n"
+                    "<tool_call>\n<function=Finish>\n<parameter=answer>\n204\n</parameter>\n</function>\n"
+                    "</tool_call>\n< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "A")
+        self.assertEqual(result.source, "reasoning")
+        self.assertTrue(result.recovered)
+        self.assertEqual(result.confidence, 0.95)
+        self.assertEqual(result.tool_call.name, "Finish")
+        self.assertEqual(result.tool_call.arguments, {"answer": 204})
+        self.assertIsNotNone(result.recovered_response)
+        calls = result.recovered_response["choices"][0]["message"]["tool_calls"]
+        self.assertEqual(calls[0]["function"]["name"], "Finish")
+        self.assertEqual(calls[0]["function"]["arguments"], '{"answer": 204}')
+        self.assertEqual(result.recovered_response["choices"][0]["finish_reason"], "tool_calls")
+
+    def test_pattern_a_json_envelope_in_reasoning_content(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning_content": (
+                    "< thinking>\nI should get the weather for Tokyo.\n"
+                    '<tool_call>\n{"name": "get_weather", "arguments": {"city": "Tokyo"}}\n</tool_call>\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="sglang", engine_version="0.4.6")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "A")
+        self.assertEqual(result.source, "reasoning_content")
+        self.assertEqual(result.tool_call.arguments, {"city": "Tokyo"})
+        self.assertEqual(result.confidence, 0.95)
+
+    def test_pattern_a_think_block_in_content(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": (
+                    "<thinking>\nThe user wants the weather in Berlin.\n"
+                    '<tool_call>\n{"name": "get_weather", "arguments": {"city": "Berlin"}}\n</tool_call>\n'
+                    "</thinking>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="llama.cpp", engine_version="b8461")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "A")
+        self.assertEqual(result.source, "thinking")
+        self.assertEqual(result.tool_call.arguments, {"city": "Berlin"})
+        self.assertEqual(result.confidence, 0.95)
+
+    def test_pattern_b_trailing_text(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": (
+                    '{"name": "get_weather", "arguments": {"city": "Beijing"}}\n\n'
+                    "Let me also check whether there is any other useful information to report.\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="llama.cpp", engine_version="b8461")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "B")
+        self.assertEqual(result.source, "content")
+        self.assertTrue(result.recovered)
+        self.assertEqual(result.confidence, 0.55)
+        self.assertTrue(any(w.startswith("trailing text") for w in result.warnings))
+
+    def test_pattern_b_complete_json_in_content(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": '{"name": "get_weather", "arguments": {"city": "Paris"}}',
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.26.0")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "B")
+        self.assertTrue(result.recovered)
+
+    def test_pattern_c_leak_detection_only(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "Here is the answer. <mm:think>I should verify the weather data first",
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r)
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "C")
+        self.assertFalse(result.recovered)
+        self.assertLessEqual(result.confidence, 0.5)
+
+    def test_healthy_response_untouched(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": "< thinking>\nI will call get_weather.\n< response>\n",
+                "tool_calls": [
+                    {
+                        "id": "call_abc",
+                        "type": "function",
+                        "function": {"name": "get_weather", "arguments": '{"city": "Tokyo"}'},
+                    }
+                ],
+            },
+            "tool_calls",
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.24.0")
+        self.assertFalse(result.detected)
+        self.assertEqual(result.confidence, 0.0)
+        self.assertIsNone(result.recovered_response)
+
+    def test_resolved_range_warns(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '<tool_call>\n{"name": "get_weather", "arguments": {"city": "Tokyo"}}\n</tool_call>\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.25.0")
+        self.assertTrue(result.detected)
+        self.assertEqual(result.confidence, 0.6)
+        self.assertIsNotNone(result.matrix_match)
+        self.assertEqual(result.matrix_match.behavior, "resolved")
+        self.assertTrue(any("resolved" in w for w in result.warnings))
+
+    def test_unknown_engine_heuristic(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '{"name": "get_weather", "arguments": {"city": "Rome"}}\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r)
+        self.assertTrue(result.detected)
+        self.assertEqual(result.pattern, "A")
+        self.assertEqual(result.confidence, 0.55)
+        self.assertEqual(result.engine_hint, "unknown")
+        self.assertIsNone(result.matrix_match)
+        self.assertTrue(any("engine_hint" in w for w in result.warnings))
+
+    def test_tool_schemas_mismatch_lowers_confidence(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '{"name": "get_weather", "arguments": {"city": "Oslo"}}\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(
+            r,
+            engine_hint="vllm",
+            engine_version="0.19.0",
+            tool_schemas=[
+                {
+                    "type": "function",
+                    "function": {"name": "get_news", "parameters": {"type": "object", "properties": {}}},
+                }
+            ],
+        )
+        self.assertEqual(result.confidence, 0.85)
+        self.assertTrue(any("not found in provided tool_schemas" in w for w in result.warnings))
+
+    def test_missing_choices(self):
+        result = check_and_rescue({"choices": []})
+        self.assertFalse(result.detected)
+        self.assertEqual(result.confidence, 0.0)
+        self.assertTrue(result.warnings)
+
+    def test_normalize_engine(self):
+        self.assertEqual(normalize_engine("vllm"), "vllm")
+        self.assertEqual(normalize_engine("sglang"), "sglang")
+        self.assertEqual(normalize_engine("llama.cpp"), "llama.cpp")
+        self.assertEqual(normalize_engine("llama-cpp"), "llama.cpp")
+        self.assertEqual(normalize_engine("LLAMA.CPP"), "llama.cpp")
+        self.assertEqual(normalize_engine("anything-else"), "unknown")
+        self.assertEqual(normalize_engine(None), "unknown")
+
+
+if __name__ == "__main__":
+    unittest.main()

unswallow-0.1.0/tests/test_fp_guard.py

@@ -0,0 +1,147 @@
+import unittest
+
+from unswallow import check_and_rescue
+
+
+def response(message):
+    return {
+        "id": "chatcmpl-fp",
+        "object": "chat.completion",
+        "model": "test-model",
+        "choices": [{"index": 0, "finish_reason": "stop", "message": message}],
+    }
+
+
+class FpGuardTest(unittest.TestCase):
+    def test_discussion_only_never_recovered(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\nI could call get_weather to check the weather in Tokyo, but I do not "
+                    "need it for this answer. The user only asked a general question.\n< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+        self.assertEqual(result.confidence, 0.0)
+        self.assertIsNone(result.recovered_response)
+
+    def test_partial_json_without_arguments(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\nI might call {\"name\": \"get_weather\" if needed.\n< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+
+    def test_non_object_arguments_rejected(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '<tool_call>\n{"name": "get_weather", "arguments": "Tokyo"}\n</tool_call>\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+
+    def test_missing_name_rejected(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '<tool_call>\n{"arguments": {"city": "Tokyo"}}\n</tool_call>\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+
+    def test_unclosed_xml_with_broken_json_rejected(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\nI wonder if <tool_call>\n"
+                    '{"name": "get_weather", "arguments": {"city": "Tokyo"}\n'
+                    "is the right thing to do.\n< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+
+    def test_empty_name_function_rejected(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n<function=>\n<parameter=answer>204</parameter>\n</function>\n"
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(r, engine_hint="vllm", engine_version="0.19.0")
+        self.assertFalse(result.detected)
+
+    def test_real_recovery_with_matching_schema(self):
+        r = response(
+            {
+                "role": "assistant",
+                "content": "",
+                "reasoning": (
+                    "< thinking>\n"
+                    '<tool_call>\n{"name": "get_weather", "arguments": {"city": "Tokyo"}}\n</tool_call>\n'
+                    "< response>\n"
+                ),
+                "tool_calls": [],
+            }
+        )
+        result = check_and_rescue(
+            r,
+            engine_hint="vllm",
+            engine_version="0.19.0",
+            tool_schemas=[
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {"city": {"type": "string"}},
+                            "required": ["city"],
+                        },
+                    },
+                }
+            ],
+        )
+        self.assertTrue(result.detected)
+        self.assertEqual(result.confidence, 0.95)
+        self.assertEqual(result.tool_call.arguments, {"city": "Tokyo"})
+
+
+if __name__ == "__main__":
+    unittest.main()

unswallow-0.1.0/tests/test_history.py

@@ -0,0 +1,65 @@
+import unittest
+
+from unswallow import sanitize_history, strip_reasoning_tags
+
+
+class HistoryTest(unittest.TestCase):
+    def test_strip_complete_think_blocks(self):
+        text = "< thinking>\nI should get the weather for Tokyo.\n< response>\nThe weather in Tokyo is 24C."
+        self.assertEqual(strip_reasoning_tags(text), "The weather in Tokyo is 24C.")
+
+    def test_strip_xml_thinking_blocks(self):
+        text = "<thinking>\nplanning\n</thinking>\nFinal answer here."
+        self.assertEqual(strip_reasoning_tags(text), "Final answer here.")
+
+    def test_leak_keeps_text_drops_tag(self):
+        text = "Here is the summary. <mm:think>I should verify the weather data first"
+        self.assertEqual(strip_reasoning_tags(text), "Here is the summary. I should verify the weather data first")
+
+    def test_plain_text_untouched(self):
+        text = "The user asked about the weather and I answered directly."
+        self.assertEqual(strip_reasoning_tags(text), text)
+
+    def test_word_think_not_eaten(self):
+        text = "I think this is a great question."
+        self.assertEqual(strip_reasoning_tags(text), text)
+
+    def test_sanitize_history(self):
+        history = [
+            {"role": "user", "content": "What is the weather?"},
+            {
+                "role": "assistant",
+                "content": "< thinking>\nI need a tool.\n< response>\nLet me call the tool.",
+                "reasoning": "< thinking>\nI need a tool.\n< response>\n",
+                "reasoning_content": "< thinking>\nI need a tool.\n< response>\n",
+            },
+            {"role": "tool", "content": "24C"},
+        ]
+        frozen = json_repr(history)
+        clean = sanitize_history(history)
+        self.assertEqual(json_repr(history), frozen)
+        self.assertEqual(len(clean), 3)
+        self.assertEqual(clean[0]["content"], "What is the weather?")
+        self.assertEqual(clean[1]["content"], "Let me call the tool.")
+        self.assertNotIn("reasoning", clean[1])
+        self.assertNotIn("reasoning_content", clean[1])
+        self.assertEqual(clean[2]["content"], "24C")
+
+    def test_options(self):
+        history = [{"role": "assistant", "content": "answer", "thinking": "< thinking>\nplan\n< response>\n"}]
+        clean = sanitize_history(history, strip_reasoning_fields=False)
+        self.assertEqual(clean[0]["thinking"], "< thinking>\nplan\n< response>\n")
+        clean2 = sanitize_history(history, strip_reasoning_tags_opt=False)
+        self.assertEqual(clean2[0]["content"], "answer")
+        clean3 = sanitize_history(history, strip_reasoning_fields=False, strip_reasoning_tags_opt=False)
+        self.assertEqual(clean3, history)
+
+
+def json_repr(obj):
+    import json
+
+    return json.dumps(obj, sort_keys=True)
+
+
+if __name__ == "__main__":
+    unittest.main()