Skip to content

Build and run agents you can see, understand and trust.

fix(formatter): decode percent-encoded local file URLs before opening (#3250)

Zhu Lei3cea63492dab
diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.py
index 956eb88e8..71003c3ea 100644
--- a/src/agentscope/formatter/_anthropic_formatter.py
+++ b/src/agentscope/formatter/_anthropic_formatter.py
@@ -4,6 +4,7 @@ import base64
import fnmatch
from abc import ABC
from typing import Any
+from urllib.request import url2pathname
import requests
from pydantic import Field
@@ -337,7 +338,10 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
elif isinstance(source, URLSource):
url = str(source.url)
if url.startswith("file://"):
- with open(url.removeprefix("file://"), "rb") as f:
+ with open(
+ url2pathname(url.removeprefix("file://")),
+ "rb",
+ ) as f:
data = base64.b64encode(f.read()).decode("utf-8")
else:
response = requests.get(url, timeout=30)
diff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.py
index 9ea0a2acc..9ee200f78 100644
--- a/src/agentscope/formatter/_dashscope_formatter.py
+++ b/src/agentscope/formatter/_dashscope_formatter.py
@@ -5,6 +5,7 @@ import base64
from typing import Any
from fnmatch import fnmatch
from abc import ABC
+from urllib.request import url2pathname
from pydantic import Field
@@ -125,7 +126,7 @@ class _DashScopeFormatterBase(FormatterBase, ABC):
elif isinstance(source, URLSource):
url_str = str(source.url)
if url_str.startswith("file://"):
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
url = f"data:{source.media_type};base64,{encoded}"
@@ -154,7 +155,7 @@ class _DashScopeFormatterBase(FormatterBase, ABC):
elif isinstance(source, URLSource):
url_str = str(source.url)
if url_str.startswith("file://"):
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
url = f"data:{source.media_type};base64,{encoded}"
@@ -194,7 +195,7 @@ class _DashScopeFormatterBase(FormatterBase, ABC):
if isinstance(source, URLSource):
url_str = str(source.url)
if url_str.startswith("file://"):
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
return {
diff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.py
index 1cee40df4..c69e1c9d0 100644
--- a/src/agentscope/formatter/_gemini_formatter.py
+++ b/src/agentscope/formatter/_gemini_formatter.py
@@ -4,6 +4,7 @@ import base64
import fnmatch
from abc import ABC
from typing import Any
+from urllib.request import url2pathname
import requests
from pydantic import Field
@@ -84,7 +85,7 @@ class _GeminiFormatterBase(FormatterBase, ABC):
url = str(source.url)
if url.startswith("file://"):
# Local file - read and convert to base64
- file_path = url.removeprefix("file://")
+ file_path = url2pathname(url.removeprefix("file://"))
with open(file_path, "rb") as f:
data = base64.b64encode(f.read()).decode("utf-8")
return {
diff --git a/src/agentscope/formatter/_moonshot_formatter.py b/src/agentscope/formatter/_moonshot_formatter.py
index 9ed223183..af64fb59f 100644
--- a/src/agentscope/formatter/_moonshot_formatter.py
+++ b/src/agentscope/formatter/_moonshot_formatter.py
@@ -4,6 +4,7 @@
import base64
from fnmatch import fnmatch
from typing import Any
+from urllib.request import url2pathname
import requests
from pydantic import Field
@@ -40,7 +41,7 @@ def _moonshot_format_media_source(
elif isinstance(source, URLSource):
url_str = str(source.url)
if url_str.startswith("file://"):
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
url = f"data:{source.media_type};base64,{encoded}"
diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.py
index f0f70282a..a131aec75 100644
--- a/src/agentscope/formatter/_openai_formatter.py
+++ b/src/agentscope/formatter/_openai_formatter.py
@@ -4,6 +4,7 @@ import base64
from abc import ABC
from fnmatch import fnmatch
from typing import Any
+from urllib.request import url2pathname
import requests
from pydantic import Field
@@ -103,7 +104,7 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
url_str = str(source.url)
if url_str.startswith("file://"):
# Local file — read and encode as base64 data URI
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
url = f"data:{source.media_type};base64,{encoded}"
@@ -162,7 +163,7 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
url_str = str(source.url)
if url_str.startswith("file://"):
# Local file
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
data = base64.b64encode(f.read()).decode("utf-8")
else:
@@ -208,7 +209,10 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
elif isinstance(source, URLSource):
url_str = str(source.url)
if url_str.startswith("file://"):
- with open(url_str.removeprefix("file://"), "rb") as f:
+ with open(
+ url2pathname(url_str.removeprefix("file://")),
+ "rb",
+ ) as f:
data = base64.b64encode(f.read()).decode("utf-8")
else:
response = requests.get(url_str, timeout=30)
diff --git a/src/agentscope/formatter/_xai_formatter.py b/src/agentscope/formatter/_xai_formatter.py
index 38ee4996e..11f3209de 100644
--- a/src/agentscope/formatter/_xai_formatter.py
+++ b/src/agentscope/formatter/_xai_formatter.py
@@ -10,6 +10,7 @@ other formatter, the ``format()`` method returns a list of
import base64
from fnmatch import fnmatch
from typing import Any, List
+from urllib.request import url2pathname
from pydantic import Field
@@ -74,7 +75,7 @@ def _xai_user_args_from_blocks(
if isinstance(sub.source, URLSource):
url_str = str(sub.source.url)
if url_str.startswith("file://"):
- local_path = url_str.removeprefix("file://")
+ local_path = url2pathname(url_str.removeprefix("file://"))
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode(
"utf-8",
diff --git a/tests/formatter_anthropic_test.py b/tests/formatter_anthropic_test.py
index cc3655985..4f617fc2c 100644
--- a/tests/formatter_anthropic_test.py
+++ b/tests/formatter_anthropic_test.py
@@ -3,6 +3,9 @@
AnthropicMultiAgentFormatter, following the reference test style with exact
ground-truth comparisons.
"""
+import base64
+import tempfile
+from pathlib import Path
from unittest import IsolatedAsyncioTestCase
from agentscope.formatter import (
@@ -19,12 +22,15 @@ from agentscope.message import (
ToolResultBlock,
ToolResultState,
Base64Source,
+ URLSource,
ThinkingBlock,
HintBlock,
)
-class TestAnthropicFormatter(IsolatedAsyncioTestCase):
+class TestAnthropicFormatter( # pylint: disable=too-many-public-methods
+ IsolatedAsyncioTestCase,
+):
"""Comprehensive tests for Anthropic Chat and MultiAgent formatters."""
async def asyncSetUp(self) -> None:
@@ -337,6 +343,50 @@ class TestAnthropicFormatter(IsolatedAsyncioTestCase):
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = AnthropicChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": expected_b64,
+ },
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
async def test_chat_formatter_base64_pdf(self) -> None:
"""Base64-encoded PDF is formatted as an Anthropic document block."""
fmt = AnthropicChatFormatter()
diff --git a/tests/formatter_dashscope_test.py b/tests/formatter_dashscope_test.py
index f99563221..14d4e259b 100644
--- a/tests/formatter_dashscope_test.py
+++ b/tests/formatter_dashscope_test.py
@@ -3,8 +3,12 @@
DashScopeMultiAgentFormatter, following the reference test style with exact
ground-truth comparisons.
"""
+import base64
+import tempfile
+from pathlib import Path
from unittest import IsolatedAsyncioTestCase
from unittest.mock import mock_open, patch
+from urllib.request import url2pathname
from agentscope.formatter import (
DashScopeChatFormatter,
@@ -373,6 +377,47 @@ class TestDashScopeFormatter(IsolatedAsyncioTestCase):
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ data_uri = f"data:image/png;base64,{expected_b64}"
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = DashScopeChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": data_uri},
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
async def test_chat_formatter_base64_audio(self) -> None:
"""Base64-encoded audio is inlined as a DashScope data URL."""
fmt = DashScopeChatFormatter()
@@ -487,7 +532,10 @@ class TestDashScopeFormatter(IsolatedAsyncioTestCase):
],
res,
)
- mocked_open.assert_called_once_with("/tmp/audio.wav", "rb")
+ mocked_open.assert_called_once_with(
+ url2pathname("/tmp/audio.wav"),
+ "rb",
+ )
async def test_chat_formatter_url_image_in_tool_result(
self,
diff --git a/tests/formatter_gemini_test.py b/tests/formatter_gemini_test.py
index 4fe08c226..7c4e1d890 100644
--- a/tests/formatter_gemini_test.py
+++ b/tests/formatter_gemini_test.py
@@ -3,6 +3,9 @@
GeminiMultiAgentFormatter, following the reference test style with exact
ground-truth comparisons.
"""
+import base64
+import tempfile
+from pathlib import Path
from unittest import IsolatedAsyncioTestCase
from agentscope.formatter import (
@@ -19,6 +22,7 @@ from agentscope.message import (
ToolResultBlock,
ToolResultState,
Base64Source,
+ URLSource,
ThinkingBlock,
HintBlock,
)
@@ -316,6 +320,48 @@ class TestGeminiFormatter(IsolatedAsyncioTestCase):
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = GeminiChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "parts": [
+ {"text": "What's in this image?"},
+ {
+ "inline_data": {
+ "data": expected_b64,
+ "mime_type": "image/png",
+ },
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
async def test_chat_formatter_thinking_preserved(self) -> None:
"""ThinkingBlock becomes a part with thought=True in Gemini format."""
fmt = GeminiChatFormatter()
diff --git a/tests/formatter_moonshot_test.py b/tests/formatter_moonshot_test.py
index 55441c793..14bc43ac9 100644
--- a/tests/formatter_moonshot_test.py
+++ b/tests/formatter_moonshot_test.py
@@ -4,6 +4,8 @@ MoonshotMultiAgentFormatter, following the reference test style with exact
ground-truth comparisons.
"""
import base64
+import tempfile
+from pathlib import Path
from unittest import IsolatedAsyncioTestCase
from unittest.mock import patch, MagicMock
@@ -426,6 +428,48 @@ class TestMoonshotFormatter(IsolatedAsyncioTestCase):
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ data_uri = f"data:image/png;base64,{expected_b64}"
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = MoonshotChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": data_uri},
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
async def test_chat_formatter_base64_video(self) -> None:
"""Base64-encoded video is emitted as a video URL block."""
fmt = MoonshotChatFormatter(
diff --git a/tests/formatter_openai_chat_test.py b/tests/formatter_openai_chat_test.py
index c3ab06596..90f61b365 100644
--- a/tests/formatter_openai_chat_test.py
+++ b/tests/formatter_openai_chat_test.py
@@ -3,6 +3,9 @@
OpenAIMultiAgentFormatter, following the reference test style with exact
ground-truth comparisons.
"""
+import base64
+import tempfile
+from pathlib import Path
from unittest import IsolatedAsyncioTestCase
from unittest.mock import Mock, patch
@@ -349,6 +352,111 @@ class TestOpenAIFormatter(IsolatedAsyncioTestCase):
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ data_uri = f"data:image/png;base64,{expected_b64}"
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = OpenAIChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": data_uri},
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
+ async def test_chat_formatter_percent_encoded_local_audio(self) -> None:
+ """Local file:// audio paths with spaces and '#' are decoded."""
+ audio_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(audio_bytes).decode("utf-8")
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.wav"
+ path.write_bytes(audio_bytes)
+ fmt = OpenAIChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="audio/wav",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertEqual(
+ res[0]["content"][0],
+ {
+ "type": "input_audio",
+ "input_audio": {
+ "data": expected_b64,
+ "format": "wav",
+ },
+ },
+ )
+
+ async def test_chat_formatter_percent_encoded_local_file(self) -> None:
+ """Local file:// PDF paths with spaces and '#' are decoded."""
+ file_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(file_bytes).decode("utf-8")
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.pdf"
+ path.write_bytes(file_bytes)
+ fmt = OpenAIChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="application/pdf",
+ ),
+ name="my file #1.pdf",
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertEqual(
+ res[0]["content"][0]["file"]["file_data"],
+ f"data:application/pdf;base64,{expected_b64}",
+ )
+
async def test_chat_formatter_base64_pdf(self) -> None:
"""Base64-encoded PDF becomes a ``file`` content part."""
fmt = OpenAIChatFormatter()
diff --git a/tests/formatter_xai_test.py b/tests/formatter_xai_test.py
index f3d2166a3..5cb2e1750 100644
--- a/tests/formatter_xai_test.py
+++ b/tests/formatter_xai_test.py
@@ -7,7 +7,10 @@ dicts), a lightweight xai_sdk stub is built at module load so that tests run
without the real package. The stub objects support __eq__ and __repr__ so
full assertListEqual comparisons work.
"""
+import base64
import sys
+import tempfile
+from pathlib import Path
from typing import Any
from types import ModuleType
from unittest import IsolatedAsyncioTestCase
@@ -277,6 +280,40 @@ class TestXAIFormatter( # pylint: disable=too-many-public-methods
res,
)
+ async def test_chat_formatter_percent_encoded_local_image(self) -> None:
+ """Local file:// image paths with spaces and '#' are decoded."""
+ image_bytes = b"spaced-name-bytes"
+ expected_b64 = base64.b64encode(image_bytes).decode("utf-8")
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir) / "my file #1.png"
+ path.write_bytes(image_bytes)
+ fmt = XAIChatFormatter()
+ res = await fmt.format(
+ [
+ UserMsg(
+ name="user",
+ content=[
+ TextBlock(text="What's in this image?"),
+ DataBlock(
+ source=URLSource(
+ url=path.as_uri(),
+ media_type="image/png",
+ ),
+ ),
+ ],
+ ),
+ ],
+ )
+ self.assertListEqual(
+ [
+ user(
+ "What's in this image?",
+ image(f"data:image/png;base64,{expected_b64}"),
+ ),
+ ],
+ res,
+ )
+
async def test_chat_formatter_tool_call(self) -> None:
"""Assistant tool call becomes a _MessageProto with tool_calls set."""
fmt = XAIChatFormatter()