fix(encoding): preserve tool namespaces in prompts and completions

encoding/README.md

@@ -225,6 +225,38 @@ Tool execution results are wrapped in `<tool_result>` tags within user messages:
 <｜User｜><tool_result>{result_json}</tool_result><｜Assistant｜><think>...
 ```
 
+### Tool namespaces
+
+Tool definitions may include a `namespace` alongside `function`, either as a
+string or as an object with `name` and an optional `description`:
+
+```python
+tool = {
+    "type": "function",
+    "namespace": {"name": "search", "description": "Search tools."},
+    "function": {
+        "name": "lookup",
+        "description": "Look up a value",
+        "parameters": {"type": "object", "properties": {"query": {"type": "string"}}},
+    },
+}
+tool_call = {
+    "type": "function",
+    "namespace": "search",
+    "function": {"name": "lookup", "arguments": '{"query": "value"}'},
+}
+```
+
+The tool schema and DSML invocation both use `search::lookup`. The namespace
+description is prepended to the tool description, separated by a newline.
+The parser returns `function.name="lookup"` and `namespace="search"` on the
+tool call, so its output can be passed back to `encode_messages()` directly.
+
+Input also accepts `namespace` inside `function`, or a qualified function name
+such as `search::lookup`. A qualified name must agree with any explicit
+namespace; `::` separates exactly one namespace from the tool name. Tools
+without a namespace retain their original names and output format.
+
 ### Reasoning effort
 
 Pass `reasoning_effort` as an integer in `[1, 100]` or as one of `"low"` (50),

encoding/encoding.py

@@ -82,33 +82,75 @@ def to_json(value: Any) -> str:
 
 
 def tools_from_openai_format(tools):
-    """Extract function definitions from OpenAI-format tool list."""
-    return [tool["function"] for tool in tools]
+    """Extract function definitions with namespace-qualified names."""
+    functions = []
+    for tool in tools:
+        function = dict(tool["function"])
+        if tool.get("namespace") is not None:
+            function["namespace"] = tool["namespace"]
+        function["name"] = _tool_name_for_encoding(function)
+        namespace = function.pop("namespace", None)
+        if isinstance(namespace, dict) and namespace.get("description"):
+            function["description"] = (
+                namespace["description"] + "\n" + (function.get("description") or "")
+            )
+        functions.append(function)
+    return functions
+
+
+def _split_tool_name(name: str, namespace: Optional[str] = None) -> Tuple[Optional[str], str]:
+    """Split a qualified name and validate any explicit namespace."""
+    prefix, separator, bare_name = name.partition("::")
+    if separator:
+        assert namespace in (None, prefix), (
+            f"Conflicting tool namespaces: {namespace} != {prefix}"
+        )
+        namespace, name = prefix, bare_name
+    assert "::" not in name, f"Tool name must not contain '::': {name}"
+    assert namespace is None or "::" not in namespace, (
+        f"Tool namespace must not contain '::': {namespace}"
+    )
+    return namespace, name
+
+
+def _tool_name_for_encoding(tool: Dict[str, Any]) -> str:
+    namespace = tool.get("namespace")
+    if isinstance(namespace, dict):
+        namespace = namespace["name"]
+    namespace, name = _split_tool_name(tool["name"], namespace)
+    return name if namespace is None else f"{namespace}::{name}"
 
 
 def tool_calls_from_openai_format(tool_calls):
     """Convert OpenAI-format tool calls to internal format."""
-    return [
-        {
-            "name": tool_call["function"]["name"],
-            "arguments": tool_call["function"]["arguments"],
-        }
-        for tool_call in tool_calls
-    ]
+    calls = []
+    for tool_call in tool_calls:
+        function = tool_call["function"]
+        namespace, name = _split_tool_name(
+            function["name"], tool_call.get("namespace") or function.get("namespace")
+        )
+        call = {"name": name, "arguments": function["arguments"]}
+        if namespace is not None:
+            call["namespace"] = namespace
+        calls.append(call)
+    return calls
 
 
 def tool_calls_to_openai_format(tool_calls):
     """Convert internal tool calls to OpenAI format."""
-    return [
-        {
+    calls = []
+    for tool_call in tool_calls:
+        call = {
             "type": "function",
             "function": {
                 "name": tool_call["name"],
                 "arguments": tool_call["arguments"],
             }
         }
-        for tool_call in tool_calls
-    ]
+        if tool_call.get("namespace") is not None:
+            call["namespace"] = tool_call["namespace"]
+        calls.append(call)
+    return calls
 
 
 def decode_dsml_to_arguments(tool_name: str, tool_args: Dict[str, Tuple[str, str]]) -> Dict[str, str]:
@@ -120,7 +162,7 @@ def decode_dsml_to_arguments(tool_name: str, tool_args: Dict[str, Tuple[str, str
         tool_args: Dict mapping param_name -> (value, is_string_flag).
 
     Returns:
-        Dict with "name" and "arguments" (JSON string) keys.
+        Dict with "name", "arguments" (JSON string), and optional "namespace".
     """
     def _decode_value(key: str, value: str, string: str):
         if string == "true":
@@ -128,7 +170,11 @@ def decode_dsml_to_arguments(tool_name: str, tool_args: Dict[str, Tuple[str, str
         return f"{to_json(key)}: {value}"
 
     tool_args_json = "{" + ", ".join([_decode_value(k, v, string=is_str) for k, (v, is_str) in tool_args.items()]) + "}"
-    return dict(name=tool_name, arguments=tool_args_json)
+    namespace, name = _split_tool_name(tool_name)
+    tool_call = dict(name=name, arguments=tool_args_json)
+    if namespace is not None:
+        tool_call["namespace"] = namespace
+    return tool_call
 
 
 # ============================================================
@@ -614,7 +660,7 @@ def render_message(
                 tool_call_template.format(
                     dsml_token=dsml_token,
                     tool_call_tag_name=tool_call_tag_name,
-                    name=tc.get("name"),
+                    name=_tool_name_for_encoding(tc),
                     arguments=encode_arguments_to_dsml(tc)
                 )
                 for tc in tool_calls

encoding/test_encoding.py

@@ -5,6 +5,7 @@ Adapted from dsv41-master/deepseek_harmony/tests/test_deepseek_v41.py for the
 self-contained dict-based API in this repo.
 """
 
+import copy
 import json
 from pathlib import Path
 from typing import Any
@@ -299,6 +300,134 @@ def test_v41_parse_rejects_unspaced_v4_dsml() -> None:
         parse_message_from_completion_text(v4_output, thinking_mode="thinking")
 
 
+# ============================================================
+# Tool namespaces
+# ============================================================
+
+@pytest.mark.parametrize("location", ["tool", "function"])
+@pytest.mark.parametrize("namespace", ["search", {"name": "search", "description": "Search tools."}])
+def test_v41_renders_namespaced_tool_schemas(location: str, namespace: Any) -> None:
+    tool = make_tool()
+    target = tool if location == "tool" else tool["function"]
+    target["namespace"] = namespace
+    original = copy.deepcopy(tool)
+
+    prompt = encode_messages(
+        [{"role": "system", "content": "system", "tools": [tool]}],
+        thinking_mode="chat",
+    )
+
+    schema = dict(make_tool()["function"], name="search::lookup")
+    if isinstance(namespace, dict):
+        schema["description"] = "Search tools.\nLook up a value"
+    assert json.dumps(schema) in prompt
+    assert '"namespace":' not in prompt
+    assert tool == original
+
+
+@pytest.mark.parametrize("thinking_mode", ["chat", "thinking"])
+@pytest.mark.parametrize("location", ["tool", "function", "qualified_name"])
+def test_v41_namespaced_tool_calls_roundtrip(thinking_mode: str, location: str) -> None:
+    messages = make_tool_call_messages()
+    call = messages[1]["tool_calls"][0]
+    if location == "qualified_name":
+        call["function"]["name"] = "search::lookup"
+    else:
+        target = call if location == "tool" else call["function"]
+        target["namespace"] = "search"
+    original = copy.deepcopy(messages)
+
+    expected = V41_TOOL_CALL_OUTPUT.replace('name="lookup"', 'name="search::lookup"')
+    if thinking_mode == "chat":
+        expected = expected.split("</think>", 1)[1]
+    assert render_message(1, messages, thinking_mode=thinking_mode) == expected
+
+    parsed = parse_message_from_completion_text(expected, thinking_mode=thinking_mode)
+    assert parsed["tool_calls"] == [{
+        "type": "function",
+        "namespace": "search",
+        "function": {
+            "name": "lookup",
+            "arguments": '{"query": "value", "limit": 2}',
+        },
+    }]
+    assert encode_messages(
+        [parsed], thinking_mode=thinking_mode, context=messages[:1]
+    ) == expected
+    assert messages == original
+
+
+def test_v41_keeps_same_named_tools_in_separate_namespaces() -> None:
+    tools, calls = [], []
+    for namespace in (None, "search", "files"):
+        tool = make_tool()
+        call = {
+            "type": "function",
+            "function": {"name": "lookup", "arguments": '{"query":"value"}'},
+        }
+        if namespace is not None:
+            tool["namespace"] = {"name": namespace}
+            call["namespace"] = namespace
+        tools.append(tool)
+        calls.append(call)
+
+    messages = [
+        {"role": "system", "content": "system", "tools": tools},
+        {"role": "user", "content": "question"},
+        {"role": "assistant", "content": "summary", "tool_calls": calls},
+    ]
+    prompt = encode_messages(messages, thinking_mode="chat")
+    for name in ("lookup", "search::lookup", "files::lookup"):
+        assert f'"name": "{name}"' in prompt
+        assert f'<｜DSML｜ invoke name="{name}">' in prompt
+
+    completion = render_message(2, messages, thinking_mode="chat")
+    parsed = parse_message_from_completion_text(completion, thinking_mode="chat")
+    assert "namespace" not in parsed["tool_calls"][0]
+    assert [call.get("namespace") for call in parsed["tool_calls"]] == [None, "search", "files"]
+    assert all(call["function"]["name"] == "lookup" for call in parsed["tool_calls"])
+
+
+def test_v41_does_not_duplicate_a_qualified_namespace() -> None:
+    tool = make_tool()
+    tool["function"]["name"] = "search::lookup"
+    tool["namespace"] = {"name": "search", "description": "Search tools."}
+    schema = enc.tools_from_openai_format([tool])[0]
+    assert schema["name"] == "search::lookup"
+    assert schema["description"] == "Search tools.\nLook up a value"
+
+    messages = make_tool_call_messages()
+    call = messages[1]["tool_calls"][0]
+    call["function"]["name"] = "search::lookup"
+    call["namespace"] = "search"
+    assert render_message(1, messages, thinking_mode="thinking") == (
+        V41_TOOL_CALL_OUTPUT.replace('name="lookup"', 'name="search::lookup"')
+    )
+
+
+@pytest.mark.parametrize(
+    ("name", "namespace", "error"),
+    [
+        ("search::lookup", "files", "Conflicting tool namespaces"),
+        ("search::nested::lookup", None, "Tool name must not contain"),
+        ("lookup", "search::nested", "Tool namespace must not contain"),
+    ],
+)
+def test_v41_rejects_ambiguous_tool_namespaces(name: str, namespace: Any, error: str) -> None:
+    tool = make_tool()
+    tool["function"]["name"] = name
+    tool["namespace"] = namespace
+    with pytest.raises(AssertionError, match=error):
+        enc.tools_from_openai_format([tool])
+
+    messages = make_tool_call_messages()
+    call = messages[1]["tool_calls"][0]
+    call["function"]["name"] = name
+    call["namespace"] = namespace
+    with pytest.raises(AssertionError, match=error):
+        render_message(1, messages, thinking_mode="thinking")
+
+
 # ============================================================
 # Multi-turn flow
 # ============================================================