diff --git a/docs/content/docs/framework/tools/builtin.en.mdx b/docs/content/docs/framework/tools/builtin.en.mdx
index 881971503..29a7f3a1f 100644
--- a/docs/content/docs/framework/tools/builtin.en.mdx
+++ b/docs/content/docs/framework/tools/builtin.en.mdx
@@ -50,6 +50,17 @@ Built-in tools depend on Volcengine services. Enable the corresponding service a
| `image_edit` | [Edit images](https://www.volcengine.com/docs/82379/1541523) (image-to-image) | `from veadk.tools.builtin_tools.image_edit import image_edit` |
| `video_generate` | [Generate videos](https://www.volcengine.com/docs/82379/1520757) from text | `from veadk.tools.builtin_tools.video_generate import video_generate` |
| `text_to_speech` | Text-to-speech (TTS) | `from veadk.tools.builtin_tools.tts import text_to_speech` |
+| `speech_to_text` | Speech recognition (ASR) for local files or public audio URLs | `from veadk.tools.builtin_tools.speech_to_text import speech_to_text` |
+| `http_request` | Generic HTTP requests with SSRF guards and a response-size cap | `from veadk.tools.builtin_tools.http_request import http_request` |
+| `document_parse` | Extract text from PDF / Word / Excel / CSV / HTML documents | `from veadk.tools.builtin_tools.document_parse import document_parse` |
+| `doc_generate` | Generate Word / Excel / CSV / Markdown documents | `from veadk.tools.builtin_tools.doc_generate import doc_generate` |
+| `mindmap_generate` | Generate a mind map (Mermaid + SVG) from a Markdown outline | `from veadk.tools.builtin_tools.mindmap_generate import mindmap_generate` |
+| `qrcode_generate` | Generate a QR code PNG | `from veadk.tools.builtin_tools.qrcode_generate import qrcode_generate` |
+| `image_transform` | Resize, crop, rotate, flip, and convert images | `from veadk.tools.builtin_tools.image_transform import image_transform` |
+| `image_understand` | Understand images with the configured model | `from veadk.tools.builtin_tools.image_understand import image_understand` |
+| `ocr` | Extract image text with the configured model | `from veadk.tools.builtin_tools.ocr import ocr` |
+| `calculator` | Safe arithmetic evaluation | `from veadk.tools.builtin_tools.calculator import calculator` |
+| `datetime` | Parse, format, convert, and calculate dates and times | `from veadk.tools.builtin_tools.datetime_tool import datetime` |
| `run_code` | Execute code in an AgentKit sandbox | `from veadk.tools.builtin_tools.run_code import run_code` |
| `execute_skills` | Run an `agent.py` workflow in a prebuilt skills sandbox | `from veadk.tools.builtin_tools.execute_skills import execute_skills` |
| `coding` | Run a code-generation workflow in a prebuilt OpenCode sandbox | `from veadk.tools.builtin_tools.coding import coding` |
@@ -469,6 +480,40 @@ Environment variables:
- `TOOL_VESPEECH_SPEAKER`: voice, defaults to `zh_female_vv_uranus_bigtts`
- `TOOL_VESPEECH_AUDIO_OUTPUT_PATH`: audio output directory, defaults to the system temp directory
+## General-purpose tools
+
+These tools cover general data processing, office documents, and multimodal work without binding to one business service. None require extra credentials except `speech_to_text`; `image_understand` and `ocr` reuse the current agent's model configuration.
+
+```python
+from veadk import Agent
+from veadk.tools.builtin_tools.calculator import calculator
+from veadk.tools.builtin_tools.datetime_tool import datetime
+from veadk.tools.builtin_tools.http_request import http_request
+
+agent = Agent(
+ name="utility_agent",
+ instruction="Use the available tools to answer precisely.",
+ tools=[calculator, datetime, http_request],
+)
+```
+
+- `http_request(url, method="GET", headers=None, params=None, json_body=None, body=None, timeout=30, max_bytes=5_000_000, follow_redirects=False)`: make an HTTP(S) request. Only http/https is allowed; private, loopback, link-local, and cloud-metadata addresses are rejected. Redirects are off by default; when enabled, every hop is revalidated and at most three hops are followed. Bodies larger than `max_bytes` are truncated with `truncated: true`. A header value of `env:NAME` reads a secret from the environment so it never enters model arguments. Credentials (`Authorization`, `Cookie`, `Proxy-Authorization`, and every `env:`-resolved header) are dropped when a redirect changes origin or downgrades to http; a same-host http→https upgrade keeps them. Set `TOOL_HTTP_ALLOWLIST=api.example.com,cdn.example.com` to restrict target hosts.
+- `document_parse(source, format=None, max_chars=200000)`: parse a local file or public URL as pdf, docx, xlsx, csv, txt, md, json, or html. Scanned PDFs return `needs_ocr: true`; pass them to `ocr`. A local file larger than 20,000,000 bytes fails instead of being read into memory; a URL download larger than that is truncated and flagged in `metadata.download_truncated`.
+- `doc_generate(format, title, content="", sheets=None, rows=None, filename=None)`: generate docx, xlsx, csv, or md and save it as an artifact. PDF generation is not supported. String cells starting with `=`, `+`, `-`, or `@` are written as text (CSV adds a `'` prefix) to prevent formula injection, and the result sets `truncated: true` when sheet, row, or column caps cut the input.
+- `mindmap_generate(title, markdown, filename=None)`: build Mermaid text and an SVG from headings and indented bullets; no Node.js is required.
+- `qrcode_generate(content, filename="qrcode.png", box_size=10, border=4, fill_color="black", back_color="white")`: generate a PNG QR code. Decoding is not supported.
+- `image_transform(source, operations, output_format=None, quality=90, filename=None)`: apply `resize`, `crop`, `rotate`, `flip`, `thumbnail`, `grayscale`, and `convert` in order and output png, jpeg, or webp. Local paths and public URLs are accepted. The output canvas, including the expanded size after `rotate`, may not exceed 40,000,000 pixels.
+- `image_understand(images, prompt="Describe the image in detail.", model_name=None)`: understand one to eight local or public images; `model_name` overrides the vision model. Local images are capped at 20,000,000 bytes each and 40,000,000 bytes total. Public URLs pass the same SSRF check as `http_request` before they are sent to the model provider.
+- `ocr(image, language="auto", model_name=None)`: extract text from an image. `language` is a hint only; `auto` adds no constraint. Public URLs are SSRF-checked as well; local images carry the same per-image and total size caps.
+- `speech_to_text(audio, timeout=300)`: call Volcengine flash ASR for wav, mp3, ogg, or opus audio up to 100 MB, from a local path or a public URL.
+- `calculator(expression, precision=10)`: arithmetic, powers, modulo, and a small function set such as `sqrt`, `log`, and `sin`. Arbitrary Python is rejected.
+- `datetime(action, value=None, value2=None, timezone=None, target_timezone=None, format=None, amount=None, unit=None)`: `action` is `now`, `parse`, `format`, `convert`, `diff`, or `add`; timezones use IANA names.
+
+Environment variables:
+
+- `TOOL_SPEECH_TO_TEXT_API_KEY`: ASR API key; falls back to `TOOL_VESPEECH_API_KEY`. Used only by `speech_to_text`.
+- `TOOL_HTTP_ALLOWLIST`: optional comma-separated host allowlist, used only by `http_request`.
+
## Code sandboxes
VeADK provides a set of tools that run tasks remotely in an [AgentKit sandbox](https://console.volcengine.com/agentkit):
diff --git a/docs/content/docs/framework/tools/builtin.mdx b/docs/content/docs/framework/tools/builtin.mdx
index a9086b09d..2f28337a2 100644
--- a/docs/content/docs/framework/tools/builtin.mdx
+++ b/docs/content/docs/framework/tools/builtin.mdx
@@ -50,6 +50,17 @@ agent = Agent(tools=[web_search])
| `image_edit` | [编辑图片](https://www.volcengine.com/docs/82379/1541523)(图生图) | `from veadk.tools.builtin_tools.image_edit import image_edit` |
| `video_generate` | 根据文本描述[生成视频](https://www.volcengine.com/docs/82379/1520757) | `from veadk.tools.builtin_tools.video_generate import video_generate` |
| `text_to_speech` | 语音合成(TTS) | `from veadk.tools.builtin_tools.tts import text_to_speech` |
+| `speech_to_text` | 语音识别(ASR),支持本地文件或公网音频 URL | `from veadk.tools.builtin_tools.speech_to_text import speech_to_text` |
+| `http_request` | 带 SSRF 防护与体积上限的通用 HTTP 请求 | `from veadk.tools.builtin_tools.http_request import http_request` |
+| `document_parse` | 解析 PDF / Word / Excel / CSV / HTML 等文档文本 | `from veadk.tools.builtin_tools.document_parse import document_parse` |
+| `doc_generate` | 生成 Word / Excel / CSV / Markdown 文档 | `from veadk.tools.builtin_tools.doc_generate import doc_generate` |
+| `mindmap_generate` | 由 Markdown 大纲生成思维导图(Mermaid + SVG) | `from veadk.tools.builtin_tools.mindmap_generate import mindmap_generate` |
+| `qrcode_generate` | 生成二维码 PNG | `from veadk.tools.builtin_tools.qrcode_generate import qrcode_generate` |
+| `image_transform` | 图片缩放、裁剪、旋转、翻转、格式转换 | `from veadk.tools.builtin_tools.image_transform import image_transform` |
+| `image_understand` | 复用当前模型配置理解图片 | `from veadk.tools.builtin_tools.image_understand import image_understand` |
+| `ocr` | 复用当前模型配置识别图片文字 | `from veadk.tools.builtin_tools.ocr import ocr` |
+| `calculator` | 安全的算术表达式计算 | `from veadk.tools.builtin_tools.calculator import calculator` |
+| `datetime` | 日期时间解析、格式化、时区转换与计算 | `from veadk.tools.builtin_tools.datetime_tool import datetime` |
| `run_code` | 在 AgentKit 沙箱中执行代码 | `from veadk.tools.builtin_tools.run_code import run_code` |
| `execute_skills` | 在预制技能沙箱中远程执行 `agent.py` 工作流 | `from veadk.tools.builtin_tools.execute_skills import execute_skills` |
| `coding` | 在预制 OpenCode 沙箱中执行代码生成工作流 | `from veadk.tools.builtin_tools.coding import coding` |
@@ -466,6 +477,40 @@ if __name__ == "__main__":
- `TOOL_VESPEECH_SPEAKER`:音色,默认为 `zh_female_vv_uranus_bigtts`
- `TOOL_VESPEECH_AUDIO_OUTPUT_PATH`:音频输出目录,默认为系统临时目录
+## 通用工具
+
+以下工具面向通用数据处理、办公文档与多模态场景,不绑定单一业务服务。除 `speech_to_text` 外均无需额外凭证;`image_understand`、`ocr` 直接复用当前 Agent 的模型配置。
+
+```python
+from veadk import Agent
+from veadk.tools.builtin_tools.calculator import calculator
+from veadk.tools.builtin_tools.datetime_tool import datetime
+from veadk.tools.builtin_tools.http_request import http_request
+
+agent = Agent(
+ name="utility_agent",
+ instruction="Use the available tools to answer precisely.",
+ tools=[calculator, datetime, http_request],
+)
+```
+
+- `http_request(url, method="GET", headers=None, params=None, json_body=None, body=None, timeout=30, max_bytes=5_000_000, follow_redirects=False)`:发起 HTTP(S) 请求。仅允许 http/https,默认拒绝内网、回环、链路本地和云元数据地址;重定向默认关闭,开启后每一跳都会重新校验,最多 3 跳;响应体超过 `max_bytes` 时截断并返回 `truncated: true`。请求头值写成 `env:NAME` 可从环境变量读取密钥,避免密钥进入模型参数。跨域重定向或 https→http 降级时会自动丢弃 `Authorization`、`Cookie`、`Proxy-Authorization` 以及所有从 `env:` 解析出的请求头(同域 http→https 升级除外),避免凭证泄露给重定向目标。可用 `TOOL_HTTP_ALLOWLIST=api.example.com,cdn.example.com` 限定目标域名。
+- `document_parse(source, format=None, max_chars=200000)`:解析本地文件或公网 URL,支持 pdf、docx、xlsx、csv、txt、md、json、html。扫描版 PDF 返回 `needs_ocr: true`,可继续调用 `ocr`。本地文件超过 20,000,000 字节直接报错;URL 下载超过该上限会截断,并在 `metadata.download_truncated` 中标记。
+- `doc_generate(format, title, content="", sheets=None, rows=None, filename=None)`:生成 docx、xlsx、csv 或 md 并保存为 artifact;不支持 PDF。以 `=`、`+`、`-`、`@` 开头的字符串单元格会按文本写入(CSV 加 `'` 前缀),防止公式注入;因 sheet/行列上限被截断时返回 `truncated: true`。
+- `mindmap_generate(title, markdown, filename=None)`:按标题层级和缩进列表生成 Mermaid 文本与 SVG,无需 Node.js。
+- `qrcode_generate(content, filename="qrcode.png", box_size=10, border=4, fill_color="black", back_color="white")`:生成 PNG 二维码;仅支持生成,不支持解码。
+- `image_transform(source, operations, output_format=None, quality=90, filename=None)`:按顺序执行 `resize`、`crop`、`rotate`、`flip`、`thumbnail`、`grayscale`、`convert`,输出 png / jpeg / webp;本地路径和公网 URL 均可。输出画布(含 `rotate` 扩展后的尺寸)不得超过 40,000,000 像素。
+- `image_understand(images, prompt="Describe the image in detail.", model_name=None)`:理解 1–8 张图片,支持本地路径或公网 URL,可传 `model_name` 覆盖视觉模型。本地图片单张上限 20,000,000 字节、合计上限 40,000,000 字节。公网 URL 会先经过与 `http_request` 相同的 SSRF 校验,再交给模型服务。
+- `ocr(image, language="auto", model_name=None)`:提取图片文字;`language` 仅作为提示,`auto` 时不额外约束。公网 URL 同样先做 SSRF 校验;本地图片适用相同的单张与合计大小限制。
+- `speech_to_text(audio, timeout=300)`:调用火山引擎录音文件识别极速版,支持 wav / mp3 / ogg / opus,单文件不超过 100 MB,也支持公网音频 URL。
+- `calculator(expression, precision=10)`:支持四则运算、幂、取模和 `sqrt` / `log` / `sin` 等少量函数,拒绝任意 Python 代码。
+- `datetime(action, value=None, value2=None, timezone=None, target_timezone=None, format=None, amount=None, unit=None)`:`action` 取 `now` / `parse` / `format` / `convert` / `diff` / `add`,时区使用 IANA 名称。
+
+环境变量:
+
+- `TOOL_SPEECH_TO_TEXT_API_KEY`:语音识别 API Key;未设置时回退读取 `TOOL_VESPEECH_API_KEY`。仅 `speech_to_text` 需要。
+- `TOOL_HTTP_ALLOWLIST`:可选,逗号分隔的允许域名列表,仅 `http_request` 使用。
+
## 代码沙箱
VeADK 提供一组在 [AgentKit 沙箱](https://console.volcengine.com/agentkit)中远程执行任务的工具:
diff --git a/frontend/server/studio_tools/builtin_declarations.py b/frontend/server/studio_tools/builtin_declarations.py
index 63214d069..8bad52cd2 100644
--- a/frontend/server/studio_tools/builtin_declarations.py
+++ b/frontend/server/studio_tools/builtin_declarations.py
@@ -20,6 +20,28 @@
BUILTIN_TOOL_DECLARATIONS: dict[str, tuple[str, dict[str, Any]]] = {
+ "calculator": (
+ "Evaluate a numeric arithmetic expression safely.\n\nUse this "
+ "tool for arithmetic, percentages, powers, roots, logarithms, "
+ "and\nbasic trigonometry. Named constants ``pi`` and ``e`` and "
+ "the functions\n``abs``, ``round``, ``min``, ``max``, ``sqrt``, "
+ "``log``, ``log10``,\n``exp``, ``sin``, ``cos``, ``tan``, ``floor``, "
+ "and ``ceil`` are supported.\n\nArgs:\n expression: The arithmetic "
+ 'expression, for example ``"(1 + 2) * 3"``.\n precision: '
+ "Decimal places for a floating-point result (0-15).\n\nReturns:\n"
+ " A dict with ``expression`` and ``result``. On invalid input, "
+ "a dict with\n an ``error`` key.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "expression": {"title": "Expression", "type": "string"},
+ "precision": {"default": 10, "title": "Precision", "type": "integer"},
+ },
+ "required": ["expression"],
+ "title": "calculatorParams",
+ "type": "object",
+ },
+ ),
"coding": (
"Create code with the pre-configured OpenCode AgentKit sandbox.",
{
@@ -33,6 +55,165 @@
"type": "object",
},
),
+ "datetime": (
+ "Work with dates and times, including timezone conversions.\n"
+ "\nUse this tool for the current time, parsing or formatting "
+ "a timestamp,\nconverting a timestamp between timezones, computing "
+ "the difference between\ntwo timestamps, or adding a duration. "
+ "Timestamps without an explicit offset\nuse ``timezone`` (default "
+ "UTC).\n\nArgs:\n action: One of ``now``, ``parse``, ``format``, "
+ "``convert``, ``diff``,\n ``add``.\n value: The primary "
+ "date/time string for ``parse``, ``format``,\n ``convert``, "
+ "``diff``, and ``add``.\n value2: The second date/time string "
+ "for ``diff``.\n timezone: IANA timezone name (for example "
+ "``Asia/Shanghai``) used when\n ``value`` has no offset. "
+ "Defaults to UTC.\n target_timezone: IANA timezone name to "
+ "convert to (``convert`` only).\n format: ``strftime`` format "
+ "string (``format`` only).\n amount: Numeric amount to add "
+ "(``add`` only).\n unit: One of ``seconds``, ``minutes``, "
+ "``hours``, ``days``, ``weeks``\n (``add`` only).\n\nReturns:\n"
+ " A dict with the requested fields. On invalid input, a dict "
+ "with an\n ``error`` key.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "action": {"title": "Action", "type": "string"},
+ "amount": {
+ "anyOf": [{"type": "number"}, {"type": "null"}],
+ "default": None,
+ "title": "Amount",
+ },
+ "format": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Format",
+ },
+ "target_timezone": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Target Timezone",
+ },
+ "timezone": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Timezone",
+ },
+ "unit": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Unit",
+ },
+ "value": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Value",
+ },
+ "value2": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Value2",
+ },
+ },
+ "required": ["action"],
+ "title": "datetimeParams",
+ "type": "object",
+ },
+ ),
+ "doc_generate": (
+ "Generate a document and attach it to the current conversation.\n"
+ "\nArgs:\n format: One of ``docx``, ``xlsx``, ``csv``, or "
+ "``md`` (case-insensitive).\n title: Document title. Rendered "
+ "as the Word title and the Markdown\n heading; ignored "
+ "for CSV.\n content: Markdown-ish body for ``docx``/``md``; "
+ "raw CSV text fallback\n for ``csv``. Supports ``#``-``###`` "
+ "headings and ``-``/``*``/``+``\n bullets for Word.\n "
+ ' sheets: For ``xlsx``, a list of ``{"name": str, "rows": '
+ "list[list]}``.\n String cells starting with ``=``, ``+``, "
+ "``-`` or ``@`` (after\n leading tab/CR/LF) are written as "
+ "text, never as formulas.\n rows: For ``csv``, a list of rows. "
+ "CSV output is plain UTF-8 without a\n byte-order mark. "
+ "Formula-like cells get a leading ``'`` so\n spreadsheet "
+ "applications treat them as text.\n filename: "
+ "Optional output filename; the correct extension is forced.\n"
+ " tool_context: Current ADK tool context used to save the "
+ "artifact. When\n omitted, the file is written to a temporary "
+ 'directory instead.\n\nReturns:\n ``{"filename", "format", '
+ '"size_bytes", "mime_type", "truncated",\n "artifact_saved", '
+ '"path"}`` on success, or ``{"error"}`` on failure.\n '
+ "``truncated`` is true when sheets, rows, or columns hit the "
+ "documented\n caps and the generated file is shorter than the "
+ "input.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "content": {"default": "", "title": "Content", "type": "string"},
+ "filename": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Filename",
+ },
+ "format": {"title": "Format", "type": "string"},
+ "rows": {
+ "anyOf": [
+ {"items": {"items": {}, "type": "array"}, "type": "array"},
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Rows",
+ },
+ "sheets": {
+ "anyOf": [
+ {
+ "items": {"additionalProperties": True, "type": "object"},
+ "type": "array",
+ },
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Sheets",
+ },
+ "title": {"title": "Title", "type": "string"},
+ },
+ "required": ["format", "title"],
+ "title": "doc_generateParams",
+ "type": "object",
+ },
+ ),
+ "document_parse": (
+ "Parse a document into bounded plain text.\n\nAccepts a local "
+ "file path or a public http(s) URL. The format is taken from\n"
+ "``format`` when supplied, otherwise inferred from the file extension, "
+ "then\nfrom the response ``Content-Type``, then from the file's magic "
+ "bytes, then\nfrom an HTML sniff, and finally treated as UTF-8 "
+ "text.\n\nArgs:\n source: Local path or public http(s) URL. A "
+ "local file larger than\n 20,000,000 bytes returns an error; "
+ "a remote body larger than that\n is truncated and flagged in "
+ '``metadata["download_truncated"]``.\n format: Optional override: '
+ "pdf, docx, xlsx, csv, txt, md, json, or html.\n max_chars: "
+ "Maximum characters returned (1,000-1,000,000).\n\nReturns:\n "
+ '``{"format", "text", "truncated", "metadata"}`` on success, or\n '
+ '``{"error"}`` on failure. ``metadata`` reports ``size_bytes`` and\n'
+ " whether the byte cap truncated the download.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "format": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Format",
+ },
+ "max_chars": {
+ "default": 200000,
+ "title": "Max Chars",
+ "type": "integer",
+ },
+ "source": {"title": "Source", "type": "string"},
+ },
+ "required": ["source"],
+ "title": "document_parseParams",
+ "type": "object",
+ },
+ ),
"get_city_weather": (
"Retrieves the weather information of a given city. the args must in English",
{
@@ -53,6 +234,75 @@
"type": "object",
},
),
+ "http_request": (
+ "Make an HTTP(S) request and return the status, headers, and "
+ "body.\n\nUse this tool when you need to call an HTTP API or "
+ "download a small\nresource. Private/internal addresses are blocked. "
+ "Redirects are only\nfollowed when ``follow_redirects`` is true "
+ "(at most three hops), and every\nhop is re-validated. Credentials "
+ "(``Authorization``, ``Cookie``,\n``Proxy-Authorization``, and any "
+ "``env:``-resolved header) are dropped when\na redirect changes "
+ "origin or downgrades to http. Set a header value to\n"
+ "``env:NAME`` to read a secret from environment variable ``NAME`` "
+ "without\nexposing it in the arguments.\n\nArgs:\n"
+ " url: The absolute http(s) URL to request.\n method: One "
+ "of GET, POST, PUT, PATCH, DELETE, HEAD (case-insensitive).\n"
+ " headers: Optional request headers. ``env:NAME`` values are "
+ "resolved from\n the environment.\n params: Optional "
+ "query parameters.\n json_body: Optional JSON-serializable "
+ "request body.\n body: Optional raw string request body. Mutually "
+ "exclusive with\n ``json_body``.\n timeout: Request "
+ "timeout in seconds (1-120).\n max_bytes: Maximum response "
+ "body size in bytes (1,000-20,000,000).\n Larger bodies "
+ "are truncated and ``truncated`` is set to true.\n follow_redirects: "
+ "Whether to follow 301/302/303/307/308 redirects.\n\nReturns:\n"
+ " A dict with ``status_code``, ``url``, ``headers``, ``content_type``,\n"
+ " ``body``, ``bytes``, and ``truncated``. On failure, a dict "
+ "with an\n ``error`` key.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "body": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Body",
+ },
+ "follow_redirects": {
+ "default": False,
+ "title": "Follow Redirects",
+ "type": "boolean",
+ },
+ "headers": {
+ "anyOf": [
+ {"additionalProperties": {"type": "string"}, "type": "object"},
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Headers",
+ },
+ "json_body": {"default": None, "title": "Json Body"},
+ "max_bytes": {
+ "default": 5000000,
+ "title": "Max Bytes",
+ "type": "integer",
+ },
+ "method": {"default": "GET", "title": "Method", "type": "string"},
+ "params": {
+ "anyOf": [
+ {"additionalProperties": True, "type": "object"},
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Params",
+ },
+ "timeout": {"default": 30, "title": "Timeout", "type": "integer"},
+ "url": {"title": "Url", "type": "string"},
+ },
+ "required": ["url"],
+ "title": "http_requestParams",
+ "type": "object",
+ },
+ ),
"image_edit": (
"Edit images in batch according to prompts and optional settings.\n"
"\n"
@@ -247,6 +497,91 @@
"type": "object",
},
),
+ "image_transform": (
+ "Apply ordered Pillow operations to an image and save the result.\n"
+ "\n``source`` may be a local path or an http(s) URL. Operations "
+ "are applied in\norder; each item is a dict with a ``type``:\n"
+ "\n- ``resize``: ``width`` and/or ``height`` (positive ints). "
+ "When only one\n side is given the aspect ratio is preserved. "
+ "With both sides and\n ``keep_aspect`` true (default) the image "
+ "fits inside the box. The output\n canvas may not exceed 40,000,000 "
+ "pixels.\n- ``crop``: ``left``, ``top``, ``right``, "
+ "``bottom`` pixel coordinates.\n- ``rotate``: ``degrees`` (float), "
+ "expanding the canvas and filling with\n white (RGB) or transparency "
+ "(RGBA); the expanded canvas is subject to the\n same pixel limit.\n"
+ "- ``flip``: ``direction`` equal to ``horizontal`` or "
+ "``vertical``.\n- ``thumbnail``: ``max_size`` (positive int), "
+ "preserving aspect ratio.\n- ``grayscale``: converts the image "
+ "to grayscale.\n- ``convert``: ``format`` of ``png``, ``jpeg`` "
+ "or ``webp``; the output\n format is applied after every operation.\n"
+ "\nArgs:\n source: Local image path or public http(s) URL.\n"
+ " operations: Ordered list of operation dicts (at most 20).\n"
+ " output_format: png, jpeg or webp. Defaults to the source "
+ "format when it\n is png/jpeg/webp, otherwise png.\n "
+ " quality: Encoder quality from 1 to 100 for jpeg/webp only.\n"
+ " filename: Optional output filename; sanitized with the right "
+ "extension.\n tool_context: Current ADK tool context used "
+ "to save the result artifact.\n\nReturns:\n A dict with filename, "
+ "format, width, height, size_bytes, mime_type,\n artifact_saved "
+ "and path. On failure, a dict with an ``error`` key.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "filename": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Filename",
+ },
+ "operations": {
+ "items": {"additionalProperties": True, "type": "object"},
+ "title": "Operations",
+ "type": "array",
+ },
+ "output_format": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Output Format",
+ },
+ "quality": {"default": 90, "title": "Quality", "type": "integer"},
+ "source": {"title": "Source", "type": "string"},
+ },
+ "required": ["source", "operations"],
+ "title": "image_transformParams",
+ "type": "object",
+ },
+ ),
+ "image_understand": (
+ "Describe one or more images in detail with a vision model.\n"
+ "\nArgs:\n images: Local image paths or public http(s) URLs "
+ "(1 to 8 items).\n prompt: What to ask about the images. The "
+ "default requests a detailed\n description covering objects, "
+ "text, layout and notable details.\n model_name: Optional "
+ 'vision model override.\n\nReturns:\n ``{"text": ..., "model": '
+ '...}`` on success, otherwise\n ``{"error": ...}``.',
+ {
+ "additionalProperties": False,
+ "properties": {
+ "images": {
+ "items": {"type": "string"},
+ "title": "Images",
+ "type": "array",
+ },
+ "model_name": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Model Name",
+ },
+ "prompt": {
+ "default": "Describe the image in detail.",
+ "title": "Prompt",
+ "type": "string",
+ },
+ },
+ "required": ["images"],
+ "title": "image_understandParams",
+ "type": "object",
+ },
+ ),
"link_reader": (
"Use this tool when you need to fetch content from web pages, PDFs, "
"or Douyin videos.\n"
@@ -272,6 +607,58 @@
"type": "object",
},
),
+ "mindmap_generate": (
+ "Build a Mermaid mindmap and a deterministic SVG from a Markdown "
+ "outline.\n\nHeadings (``#`` through ``######``) nest by level; "
+ "``-``/``*``/``+`` bullets\nnest by two-space indentation. Blank "
+ "lines and plain text are ignored.\n\nArgs:\n title: Root "
+ "node label.\n markdown: Outline using headings and/or indented "
+ "bullets.\n filename: Optional base filename; ``.mmd`` and "
+ "``.svg`` are generated.\n tool_context: Current ADK tool "
+ "context. When omitted, both files are\n written to a "
+ 'temporary directory instead.\n\nReturns:\n ``{"title", '
+ '"mermaid", "mmd_filename", "svg_filename", "nodes",\n'
+ ' "artifact_saved", "mmd_path", "svg_path"}`` on success, '
+ 'or\n ``{"error"}`` on failure.',
+ {
+ "additionalProperties": False,
+ "properties": {
+ "filename": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Filename",
+ },
+ "markdown": {"title": "Markdown", "type": "string"},
+ "title": {"title": "Title", "type": "string"},
+ },
+ "required": ["title", "markdown"],
+ "title": "mindmap_generateParams",
+ "type": "object",
+ },
+ ),
+ "ocr": (
+ "Transcribe text from an image with a vision model.\n\nArgs:\n"
+ " image: Local image path or public http(s) URL.\n language: "
+ "Expected text language, or ``auto`` to let the model decide.\n"
+ " model_name: Optional vision model override.\n\nReturns:\n"
+ ' ``{"text": ..., "language": ..., "model": ...}`` on '
+ 'success, otherwise\n ``{"error": ...}``.',
+ {
+ "additionalProperties": False,
+ "properties": {
+ "image": {"title": "Image", "type": "string"},
+ "language": {"default": "auto", "title": "Language", "type": "string"},
+ "model_name": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Model Name",
+ },
+ },
+ "required": ["image"],
+ "title": "ocrParams",
+ "type": "object",
+ },
+ ),
"parallel_web_search": (
"Search queries from websites in parallel.\n"
"\n"
@@ -339,6 +726,46 @@
"type": "object",
},
),
+ "qrcode_generate": (
+ "Generate a PNG QR code for text or a URL and save it.\n\nArgs:\n"
+ " content: Text or URL to encode (non-empty, at most 2000 "
+ "characters).\n filename: Output filename; a .png extension "
+ "is enforced.\n box_size: Pixels per QR module, from 1 to "
+ "50.\n border: Quiet-zone size in modules, from 0 to 20.\n"
+ " fill_color: Pillow color name or hex value for the dark "
+ "modules.\n back_color: Pillow color name or hex value for "
+ "the background.\n tool_context: Current ADK tool context "
+ "used to save the result artifact.\n\nReturns:\n A dict with "
+ "filename, format, width, height, size_bytes, mime_type,\n "
+ " artifact_saved and path. On failure, a dict with an ``error`` "
+ "key.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "back_color": {
+ "default": "white",
+ "title": "Back Color",
+ "type": "string",
+ },
+ "border": {"default": 4, "title": "Border", "type": "integer"},
+ "box_size": {"default": 10, "title": "Box Size", "type": "integer"},
+ "content": {"title": "Content", "type": "string"},
+ "filename": {
+ "default": "qrcode.png",
+ "title": "Filename",
+ "type": "string",
+ },
+ "fill_color": {
+ "default": "black",
+ "title": "Fill Color",
+ "type": "string",
+ },
+ },
+ "required": ["content"],
+ "title": "qrcode_generateParams",
+ "type": "object",
+ },
+ ),
"run_code": (
"Run code in a code sandbox and return the output.\n"
"For C++ code, don't execute it directly, compile and execute via "
@@ -394,6 +821,26 @@
"type": "object",
},
),
+ "speech_to_text": (
+ "Transcribe speech in an audio file into text.\n\nSupports local "
+ "wav/mp3/ogg/opus files (up to 100 MB) and public http(s)\naudio "
+ "URLs. The service auto-detects the spoken language.\n\nArgs:\n"
+ " audio: Local file path or public http(s) URL of the audio.\n"
+ " timeout: Request timeout in seconds, between 1 and 600.\n"
+ "\nReturns:\n A dict with ``text``, ``duration_ms``, ``utterances`` "
+ "and ``log_id``,\n or a dict with ``error`` when transcription "
+ "fails.",
+ {
+ "additionalProperties": False,
+ "properties": {
+ "audio": {"title": "Audio", "type": "string"},
+ "timeout": {"default": 300, "title": "Timeout", "type": "integer"},
+ },
+ "required": ["audio"],
+ "title": "speech_to_textParams",
+ "type": "object",
+ },
+ ),
"text_to_speech": (
"TTS provides users with the ability to convert text to speech, "
"turning the text content of LLM into audio.\n"
diff --git a/pyproject.toml b/pyproject.toml
index b22d19771..10ad65940 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -51,7 +51,9 @@ dependencies = [
"filetype==1.2.0",
"pypdfium2>=4.30.0", # Frontend PDF attachments are rendered as page images
"pillow>=10.0.0", # Encode rendered PDF pages as PNG
- "qrcode>=8,<9", # Render Feishu app-registration links for Studio setup
+ "qrcode>=8,<9", # Render Feishu app-registration links for Studio setup and the qrcode_generate tool
+ "python-docx>=1.1.0,<2", # Read and write Word documents in document_parse/doc_generate
+ "openpyxl>=3.1.0,<4", # Read and write Excel workbooks in document_parse/doc_generate
"vikingdb-python-sdk>=0.1.32", # For Viking DB
"agentkit-sdk-python>=0.8.5",
"websockets>=15,<16", # Stream temporary AgentKit Sandbox conversations
diff --git a/tests/cli/test_studio_rbac.py b/tests/cli/test_studio_rbac.py
index fc5211324..e1fb28c12 100644
--- a/tests/cli/test_studio_rbac.py
+++ b/tests/cli/test_studio_rbac.py
@@ -5844,6 +5844,25 @@ async def request(
},
headers=headers,
)
+ # The endpoint answers 202 while the background lookup is pending; a
+ # loaded CI runner can exceed the route's initial wait budget even when
+ # every runtime call is stubbed.
+ capability_deadline = time.monotonic() + 30.0
+ while capability.status_code == 202:
+ assert time.monotonic() < capability_deadline, (
+ "Runtime update capability remained pending"
+ )
+ time.sleep(0.05)
+ capability = client.get(
+ "/web/runtime-update-capability",
+ params={
+ "runtimeId": runtime.runtime_id,
+ "region": "cn-beijing",
+ "appName": "mpa-agent",
+ "currentVersion": 3,
+ },
+ headers=headers,
+ )
response = client.post(
"/web/deploy-agentkit",
headers=headers,
diff --git a/tests/tools/builtin_tools/test_calculator.py b/tests/tools/builtin_tools/test_calculator.py
new file mode 100644
index 000000000..ea64e6df0
--- /dev/null
+++ b/tests/tools/builtin_tools/test_calculator.py
@@ -0,0 +1,219 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the ``calculator`` built-in tool."""
+
+import ast
+import inspect
+import math
+
+import pytest
+
+from veadk.tools.builtin_tools import calculator as calculator_module
+from veadk.tools.builtin_tools.calculator import calculator
+
+
+def test_signature():
+ params = inspect.signature(calculator).parameters
+ assert list(params) == ["expression", "precision"]
+
+
+def test_defaults():
+ params = inspect.signature(calculator).parameters
+ assert params["expression"].default is inspect.Parameter.empty
+ assert params["precision"].default == 10
+
+
+# ------------------------------------------------------------ happy paths ---
+@pytest.mark.parametrize(
+ ("expression", "expected"),
+ [
+ ("1+2*3", 7),
+ ("(1+2)*3", 9),
+ ("2**10", 1024),
+ ("7//2", 3),
+ ("7%4", 3),
+ ("-5+3", -2),
+ ("+5", 5),
+ ("--5", 5),
+ ("20/5", 4.0),
+ ("2**3**2", 512),
+ ("abs(-3)", 3),
+ ("round(3.14159, 2)", 3.14),
+ ("min(1,2,3)", 1),
+ ("max(1,2,3)", 3),
+ ("floor(3.9)", 3),
+ ("ceil(3.1)", 4),
+ ("log10(1000)", 3.0),
+ ("exp(0)", 1.0),
+ ("sin(0)", 0.0),
+ ("cos(0)", 1.0),
+ ("tan(0)", 0.0),
+ ],
+)
+def test_happy_paths(expression, expected):
+ result = calculator(expression)
+ assert "error" not in result
+ assert result["result"] == expected
+
+
+def test_integer_results_stay_int():
+ result = calculator("2**10")
+ assert result == {"expression": "2**10", "result": 1024}
+ assert type(result["result"]) is int
+
+
+def test_float_results_are_rounded():
+ assert calculator("1/3")["result"] == 0.3333333333
+ assert calculator("1/3", precision=2)["result"] == 0.33
+ assert calculator("1/3", precision=0)["result"] == 0.0
+
+
+def test_named_constants():
+ assert calculator("pi")["result"] == round(math.pi, 10)
+ assert calculator("e")["result"] == round(math.e, 10)
+ assert calculator("sqrt(16)")["result"] == 4.0
+ assert calculator("log(e)")["result"] == 1.0
+ assert calculator("2**0.5")["result"] == round(math.sqrt(2), 10)
+
+
+@pytest.mark.parametrize("precision", [0, 1, 15])
+def test_precision_bounds_accepted(precision):
+ assert "error" not in calculator("1/3", precision=precision)
+
+
+# ------------------------------------------------------------- rejections ---
+@pytest.mark.parametrize(
+ "expression",
+ [
+ None,
+ 123,
+ "",
+ " ",
+ "x+1",
+ "(1).real",
+ "[1, 2][0]",
+ "[x for x in [1]]",
+ "lambda: 1",
+ "'abc'",
+ "True",
+ "1j",
+ "1 & 2",
+ "1 if 1 else 2",
+ "unknown_function(1)",
+ "not 1",
+ "~5",
+ "1 2",
+ "1 +",
+ ],
+)
+def test_rejects_unsupported_input(expression):
+ result = calculator(expression)
+ assert "error" in result
+ assert "result" not in result
+
+
+def test_rejects_overlong_expression():
+ result = calculator("1+" * 500 + "1")
+ assert "error" in result
+ assert "too long" in result["error"]
+
+
+@pytest.mark.parametrize("precision", [-1, 16, True, "10", 1.5, None])
+def test_rejects_bad_precision(precision):
+ result = calculator("1+1", precision=precision)
+ assert "error" in result
+
+
+@pytest.mark.parametrize("expression", ["1/0", "1//0", "1%0", "0**-1"])
+def test_division_by_zero(expression):
+ result = calculator(expression)
+ assert result == {"error": "division by zero"}
+
+
+@pytest.mark.parametrize(
+ "expression",
+ [
+ "2**101",
+ "2**(-101)",
+ "2**x",
+ "10**100+10**100",
+ "9" * 200,
+ "(-8)**0.5",
+ "sqrt(-1)",
+ "exp(1000)",
+ "min()",
+ "round(1.234, ndigits=2)",
+ "max(*[1, 2])",
+ "min(1)(2)",
+ "1e50*1e60",
+ ],
+)
+def test_rejects_limits_and_domains(expression):
+ result = calculator(expression)
+ assert "error" in result
+
+
+def test_exponent_limit_accepts_boundary():
+ result = calculator("1**100")
+ assert result["result"] == 1
+
+
+def test_non_finite_helper_is_rejected():
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._check_number(float("inf"))
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._check_number(float("nan"))
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._check_number(True)
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._check_number(1j)
+
+
+def test_function_zero_division_branch(monkeypatch):
+ def explode(*args):
+ raise ZeroDivisionError
+
+ monkeypatch.setitem(calculator_module._FUNCTIONS, "abs", explode)
+ node = ast.parse("abs(1)", mode="eval").body
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._apply_call(node)
+
+
+def test_binary_overflow_branch():
+ result = calculator("1e100**100")
+ assert result == {"error": "numeric overflow"}
+
+
+def test_recursion_error_is_reported(monkeypatch):
+ def explode(node):
+ raise RecursionError
+
+ monkeypatch.setattr(calculator_module, "_evaluate", explode)
+ result = calculator("1+1")
+ assert result == {"error": "expression is too complex"}
+
+
+def test_unexpected_evaluation_error_is_reported(monkeypatch):
+ def explode(node):
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr(calculator_module, "_evaluate", explode)
+ result = calculator("1+1")
+ assert result == {"error": "invalid expression"}
+
+
+def test_unsupported_expression_element():
+ with pytest.raises(calculator_module._EvalError):
+ calculator_module._evaluate(object())
diff --git a/tests/tools/builtin_tools/test_datetime_tool.py b/tests/tools/builtin_tools/test_datetime_tool.py
new file mode 100644
index 000000000..28d06dbac
--- /dev/null
+++ b/tests/tools/builtin_tools/test_datetime_tool.py
@@ -0,0 +1,324 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the ``datetime`` built-in tool."""
+
+import inspect
+from datetime import datetime as _datetime
+from datetime import timedelta as _timedelta
+from datetime import timezone as _timezone
+
+import pytest
+
+from veadk.tools.builtin_tools import datetime_tool as datetime_module
+from veadk.tools.builtin_tools.datetime_tool import datetime as datetime_tool
+
+_WEEKDAYS = {
+ "monday",
+ "tuesday",
+ "wednesday",
+ "thursday",
+ "friday",
+ "saturday",
+ "sunday",
+}
+
+
+def test_signature():
+ params = inspect.signature(datetime_tool).parameters
+ assert list(params) == [
+ "action",
+ "value",
+ "value2",
+ "timezone",
+ "target_timezone",
+ "format",
+ "amount",
+ "unit",
+ ]
+
+
+def test_defaults():
+ params = inspect.signature(datetime_tool).parameters
+ assert params["action"].default is inspect.Parameter.empty
+ for name in (
+ "value",
+ "value2",
+ "timezone",
+ "target_timezone",
+ "format",
+ "amount",
+ "unit",
+ ):
+ assert params[name].default is None
+
+
+# --------------------------------------------------------------------- now --
+def test_now_defaults_to_utc():
+ result = datetime_tool("now")
+ assert result["timezone"] == "UTC"
+ moment = _datetime.fromisoformat(result["iso"])
+ assert moment.utcoffset() == _timedelta(0)
+ assert result["weekday"] in _WEEKDAYS
+ assert isinstance(result["timestamp"], float)
+
+
+def test_now_in_timezone():
+ result = datetime_tool("now", timezone="Asia/Shanghai")
+ assert result["timezone"] == "Asia/Shanghai"
+ assert result["iso"].endswith("+08:00")
+
+
+@pytest.mark.parametrize("timezone", ["Not/AZone", "", 123])
+def test_now_rejects_bad_timezone(timezone):
+ assert "error" in datetime_tool("now", timezone=timezone)
+
+
+# ------------------------------------------------------------------- parse --
+def test_parse_iso_with_offset():
+ result = datetime_tool("parse", value="2024-01-02T03:04:05+08:00")
+ assert result["year"] == 2024
+ assert result["month"] == 1
+ assert result["day"] == 2
+ assert result["hour"] == 3
+ assert result["minute"] == 4
+ assert result["second"] == 5
+ assert result["weekday"] == "tuesday"
+ assert result["timezone"] == "+08:00"
+ expected = _datetime(
+ 2024, 1, 2, 3, 4, 5, tzinfo=_timezone(_timedelta(hours=8))
+ ).timestamp()
+ assert result["timestamp"] == expected
+
+
+def test_parse_z_suffix():
+ result = datetime_tool("parse", value="2024-01-02T03:04:05Z")
+ assert result["timezone"] == "UTC"
+ assert result["iso"] == "2024-01-02T03:04:05+00:00"
+
+
+def test_parse_date_only_uses_utc():
+ result = datetime_tool("parse", value="2024-01-02")
+ assert result["iso"] == "2024-01-02T00:00:00+00:00"
+ assert result["hour"] == 0
+
+
+def test_parse_naive_uses_timezone():
+ result = datetime_tool(
+ "parse", value="2024-01-02 03:04:05", timezone="Asia/Shanghai"
+ )
+ assert result["timezone"] == "Asia/Shanghai"
+ assert result["iso"] == "2024-01-02T03:04:05+08:00"
+
+
+def test_parse_slash_date():
+ result = datetime_tool("parse", value="2024/01/02")
+ assert result["iso"] == "2024-01-02T00:00:00+00:00"
+
+
+def test_parse_slash_datetime():
+ result = datetime_tool("parse", value="2024/01/02 03:04:05")
+ assert result["iso"] == "2024-01-02T03:04:05+00:00"
+
+
+@pytest.mark.parametrize("value", [None, "", "not a date", 123])
+def test_parse_rejects_bad_value(value):
+ assert "error" in datetime_tool("parse", value=value)
+
+
+def test_parse_naive_with_bad_timezone():
+ result = datetime_tool("parse", value="2024-01-02", timezone="Not/AZone")
+ assert "error" in result
+
+
+# ------------------------------------------------------------------ format --
+def test_format_default():
+ result = datetime_tool("format", value="2024-01-02T03:04:05+00:00")
+ assert result["formatted"] == "2024-01-02 03:04:05"
+ assert result["iso"] == "2024-01-02T03:04:05+00:00"
+
+
+def test_format_custom():
+ result = datetime_tool("format", value="2024-01-02", format="%Y/%m/%d")
+ assert result["formatted"] == "2024/01/02"
+
+
+def test_format_rejects_non_string_format():
+ result = datetime_tool("format", value="2024-01-02", format=123)
+ assert "error" in result
+
+
+def test_format_requires_value():
+ assert "error" in datetime_tool("format")
+
+
+def test_format_string_failure_is_reported(monkeypatch):
+ class _BadMoment:
+ def strftime(self, pattern):
+ raise ValueError("bad format")
+
+ monkeypatch.setattr(datetime_module, "_parse", lambda *args: _BadMoment())
+ result = datetime_tool("format", value="2024-01-02", format="%Y")
+ assert "error" in result
+
+
+# ----------------------------------------------------------------- convert --
+def test_convert_from_utc_to_target():
+ result = datetime_tool(
+ "convert",
+ value="2024-01-01 12:00:00",
+ timezone="UTC",
+ target_timezone="Asia/Shanghai",
+ )
+ assert result["iso"] == "2024-01-01T20:00:00+08:00"
+ assert result["timezone"] == "Asia/Shanghai"
+ expected = _datetime(2024, 1, 1, 12, 0, 0, tzinfo=_timezone.utc).timestamp()
+ assert result["timestamp"] == expected
+
+
+def test_convert_aware_value_uses_its_offset():
+ result = datetime_tool(
+ "convert",
+ value="2024-01-01T12:00:00+08:00",
+ target_timezone="UTC",
+ )
+ assert result["iso"] == "2024-01-01T04:00:00+00:00"
+ assert result["timezone"] == "UTC"
+
+
+def test_convert_requires_target_timezone():
+ result = datetime_tool("convert", value="2024-01-01")
+ assert "error" in result
+
+
+def test_convert_rejects_bad_target_timezone():
+ result = datetime_tool("convert", value="2024-01-01", target_timezone="Not/AZone")
+ assert "error" in result
+
+
+# -------------------------------------------------------------------- diff --
+def test_diff_positive():
+ result = datetime_tool(
+ "diff",
+ value="2024-01-01 00:00:00",
+ value2="2024-01-03 03:04:05",
+ )
+ assert result["seconds"] == 183845.0
+ assert result["days"] == pytest.approx(183845 / 86400)
+ assert result["human"] == "2 days, 3:04:05"
+
+
+def test_diff_zero():
+ result = datetime_tool(
+ "diff", value="2024-01-01T00:00:00Z", value2="2024-01-01T00:00:00Z"
+ )
+ assert result["seconds"] == 0
+ assert result["human"] == "0:00:00"
+
+
+def test_diff_negative_seconds():
+ result = datetime_tool(
+ "diff",
+ value="2024-01-01 00:00:05",
+ value2="2024-01-01 00:00:00",
+ )
+ assert result["seconds"] == -5.0
+ assert result["human"] == "-0:00:05"
+
+
+def test_diff_negative_day_is_singular():
+ result = datetime_tool(
+ "diff",
+ value="2024-01-02 00:00:00",
+ value2="2024-01-01 00:00:00",
+ )
+ assert result["human"] == "-1 day, 0:00:00"
+
+
+def test_diff_requires_value2():
+ assert "error" in datetime_tool("diff", value="2024-01-01")
+
+
+def test_diff_rejects_bad_value():
+ assert "error" in datetime_tool("diff", value="nope", value2="2024-01-01")
+
+
+# --------------------------------------------------------------------- add --
+@pytest.mark.parametrize(
+ ("amount", "unit", "expected"),
+ [
+ (30, "seconds", "2024-01-01T00:00:30+00:00"),
+ (90, "minutes", "2024-01-01T01:30:00+00:00"),
+ (2, "hours", "2024-01-01T02:00:00+00:00"),
+ (1, "days", "2024-01-02T00:00:00+00:00"),
+ (1, "weeks", "2024-01-08T00:00:00+00:00"),
+ (1.5, "hours", "2024-01-01T01:30:00+00:00"),
+ (1, "DAYS", "2024-01-02T00:00:00+00:00"),
+ ],
+)
+def test_add_units(amount, unit, expected):
+ result = datetime_tool(
+ "add", value="2024-01-01T00:00:00Z", amount=amount, unit=unit
+ )
+ assert result["iso"] == expected
+ assert "error" not in result
+
+
+def test_add_requires_amount():
+ assert "error" in datetime_tool("add", value="2024-01-01", unit="days")
+
+
+@pytest.mark.parametrize("amount", [True, "1", None])
+def test_add_rejects_bad_amount(amount):
+ result = datetime_tool("add", value="2024-01-01", amount=amount, unit="days")
+ assert "error" in result
+
+
+@pytest.mark.parametrize("amount", [float("nan"), float("inf")])
+def test_add_rejects_non_finite_amount(amount):
+ result = datetime_tool("add", value="2024-01-01", amount=amount, unit="days")
+ assert "error" in result
+
+
+@pytest.mark.parametrize("unit", [None, "months", 1, ""])
+def test_add_rejects_bad_unit(unit):
+ result = datetime_tool("add", value="2024-01-01", amount=1, unit=unit)
+ assert "error" in result
+
+
+def test_add_rejects_bad_value():
+ result = datetime_tool("add", value="nope", amount=1, unit="days")
+ assert "error" in result
+
+
+def test_add_overflow_returns_error():
+ result = datetime_tool("add", value="2024-01-01", amount=1e30, unit="days")
+ assert "error" in result
+
+
+# ------------------------------------------------------------------- other --
+@pytest.mark.parametrize("action", ["unknown", "", None, 1])
+def test_unknown_action(action):
+ result = datetime_tool(action)
+ assert "error" in result
+
+
+def test_unexpected_internal_error_is_reported(monkeypatch):
+ def explode(timezone):
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr(datetime_module, "_action_now", explode)
+ result = datetime_tool("now")
+ assert "error" in result
+ assert "RuntimeError" in result["error"]
diff --git a/tests/tools/builtin_tools/test_doc_generate.py b/tests/tools/builtin_tools/test_doc_generate.py
new file mode 100644
index 000000000..402dd6568
--- /dev/null
+++ b/tests/tools/builtin_tools/test_doc_generate.py
@@ -0,0 +1,532 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import csv
+import io
+from pathlib import Path
+
+import pytest
+
+from veadk.tools.builtin_tools import doc_generate as doc_generate_module
+from veadk.tools.builtin_tools.doc_generate import doc_generate
+
+
+class SaveContext:
+ def __init__(self, failures: int = 0) -> None:
+ self.artifacts: list[tuple[str, object]] = []
+ self.failures = failures
+
+ async def save_artifact(self, filename: str, artifact: object) -> int:
+ if self.failures:
+ self.failures -= 1
+ raise RuntimeError("storage unavailable")
+ self.artifacts.append((filename, artifact))
+ return len(self.artifacts)
+
+
+DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+
+# --------------------------------------------------------------------- docx --
+@pytest.mark.asyncio
+async def test_docx_writes_temp_file_with_light_markdown(tmp_path: Path) -> None:
+ content = (
+ "# Heading One\n"
+ "first line\n"
+ "second line\n"
+ "\n"
+ "- **bold** item\n"
+ "* star item\n"
+ "+ plus item\n"
+ "\n"
+ "#### raw heading\n"
+ "\n"
+ "plain __em__ text\n"
+ "## Heading Two\n"
+ "### Heading Three\n"
+ )
+
+ result = await doc_generate(
+ "docx",
+ "My Title",
+ content=content,
+ filename="report",
+ tool_context=None,
+ )
+
+ assert result["filename"] == "report.docx"
+ assert result["format"] == "docx"
+ assert result["mime_type"] == DOCX_MIME
+ assert result["artifact_saved"] is False
+ path = Path(result["path"])
+ assert path.is_file()
+ assert path.stat().st_size == result["size_bytes"]
+
+ import docx
+
+ document = docx.Document(str(path))
+ paragraphs = [(p.text, p.style.name) for p in document.paragraphs]
+ assert paragraphs == [
+ ("My Title", "Title"),
+ ("Heading One", "Heading 1"),
+ ("first line second line", "Normal"),
+ ("bold item", "List Bullet"),
+ ("star item", "List Bullet"),
+ ("plus item", "List Bullet"),
+ ("raw heading", "Normal"),
+ ("plain em text", "Normal"),
+ ("Heading Two", "Heading 2"),
+ ("Heading Three", "Heading 3"),
+ ]
+
+
+@pytest.mark.asyncio
+async def test_docx_saves_artifact() -> None:
+ context = SaveContext()
+
+ result = await doc_generate(
+ " DOCX ",
+ "Title",
+ content="body **text**",
+ filename="notes",
+ tool_context=context, # type: ignore[arg-type]
+ )
+
+ assert result["artifact_saved"] is True
+ assert result["path"] is None
+ assert result["filename"] == "notes.docx"
+ assert len(context.artifacts) == 1
+ name, artifact = context.artifacts[0]
+ assert name == "notes.docx"
+ assert artifact.inline_data.mime_type == DOCX_MIME
+ assert artifact.inline_data.display_name == "notes.docx"
+ assert len(artifact.inline_data.data) == result["size_bytes"]
+
+
+@pytest.mark.asyncio
+async def test_docx_default_filename_and_empty_content() -> None:
+ result = await doc_generate("docx", "", tool_context=None)
+ assert result["filename"] == "document.docx"
+ assert result["size_bytes"] > 0
+
+
+@pytest.mark.asyncio
+async def test_docx_handles_none_content() -> None:
+ result = await doc_generate("docx", "Title", content=None, tool_context=None) # type: ignore[arg-type]
+ assert result["artifact_saved"] is False
+
+
+@pytest.mark.asyncio
+async def test_artifact_save_failure_returns_error() -> None:
+ result = await doc_generate(
+ "docx",
+ "Title",
+ tool_context=SaveContext(failures=1), # type: ignore[arg-type]
+ )
+ assert "error" in result
+ assert "failed to save artifact" in result["error"]
+
+
+# --------------------------------------------------------------------- xlsx --
+@pytest.mark.asyncio
+async def test_xlsx_writes_sheets_with_bold_header_and_widths() -> None:
+ import openpyxl
+
+ sheets = [
+ {"name": "Data", "rows": [["Name", "Age"], ["Alice", 30], ["x" * 100, None]]}
+ ]
+
+ result = await doc_generate("xlsx", "Ignored", sheets=sheets, tool_context=None)
+
+ assert result["filename"] == "document.xlsx"
+ assert result["mime_type"] == XLSX_MIME
+ workbook = openpyxl.load_workbook(result["path"])
+ worksheet = workbook["Data"]
+ assert worksheet["A1"].value == "Name"
+ assert worksheet["A1"].font.bold is True
+ assert worksheet["B1"].font.bold is True
+ assert worksheet["B2"].value == 30
+ assert worksheet["B3"].value is None
+ assert 8 <= worksheet.column_dimensions["A"].width <= 60
+ assert worksheet.column_dimensions["A"].width == 60
+
+
+@pytest.mark.asyncio
+async def test_xlsx_creates_multiple_unique_sheets() -> None:
+ import openpyxl
+
+ sheets = [
+ {"name": "Same", "rows": [["a"]]},
+ {"name": "Same", "rows": [["b"]]},
+ {"name": "Same", "rows": [["c"]]},
+ {"name": "Bad/Name:*?[]", "rows": []},
+ {"name": " ", "rows": []},
+ ]
+
+ result = await doc_generate("xlsx", "", sheets=sheets, tool_context=None)
+
+ workbook = openpyxl.load_workbook(result["path"])
+ assert workbook.sheetnames == [
+ "Same",
+ "Same_2",
+ "Same_3",
+ "Bad Name",
+ "Sheet5",
+ ]
+
+
+@pytest.mark.asyncio
+async def test_xlsx_enforces_sheet_row_and_column_caps(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ import openpyxl
+
+ monkeypatch.setattr(doc_generate_module, "_MAX_SHEETS", 1)
+ monkeypatch.setattr(doc_generate_module, "_MAX_ROWS_PER_SHEET", 1)
+ monkeypatch.setattr(doc_generate_module, "_MAX_COLUMNS", 2)
+ sheets = [
+ {"name": "One", "rows": [["a", "b", "c"], ["d", "e", "f"]]},
+ {"name": "Two", "rows": [["g"]]},
+ ]
+
+ result = await doc_generate("xlsx", "", sheets=sheets, tool_context=None)
+
+ workbook = openpyxl.load_workbook(result["path"])
+ assert workbook.sheetnames == ["One"]
+ worksheet = workbook["One"]
+ assert worksheet.max_row == 1
+ assert worksheet.max_column == 2
+
+
+@pytest.mark.asyncio
+async def test_xlsx_converts_non_basic_cell_values() -> None:
+ import openpyxl
+
+ result = await doc_generate(
+ "xlsx",
+ "",
+ sheets=[{"name": "S", "rows": [[{"a": 1}]]}],
+ tool_context=None,
+ )
+
+ workbook = openpyxl.load_workbook(result["path"])
+ assert workbook["S"]["A1"].value == "{'a': 1}"
+
+
+@pytest.mark.asyncio
+async def test_xlsx_writes_formula_like_cells_as_text() -> None:
+ import openpyxl
+
+ result = await doc_generate(
+ "xlsx",
+ "",
+ sheets=[
+ {
+ "name": "S",
+ "rows": [
+ ["=1+1", "+1", "-1", "@SUM(A1)", "\r=cmd", "safe"],
+ [1, -2, 3.5, True, None, "x"],
+ ],
+ }
+ ],
+ tool_context=None,
+ )
+
+ workbook = openpyxl.load_workbook(result["path"], data_only=False)
+ worksheet = workbook["S"]
+ for column in ("A1", "B1", "C1", "D1", "E1"):
+ assert worksheet[column].value.startswith(("=", "+", "-", "@", "\r"))
+ assert worksheet[column].data_type == "s"
+ assert worksheet["F1"].value == "safe"
+ # Numbers and booleans keep their native type.
+ assert worksheet["A2"].value == 1
+ assert worksheet["B2"].value == -2
+ assert worksheet["D2"].value is True
+
+
+@pytest.mark.asyncio
+async def test_xlsx_truncation_flag(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(doc_generate_module, "_MAX_COLUMNS", 1)
+ result = await doc_generate(
+ "xlsx",
+ "",
+ sheets=[{"name": "S", "rows": [["a", "b"]]}],
+ tool_context=None,
+ )
+ assert result["truncated"] is True
+
+
+@pytest.mark.asyncio
+async def test_docx_and_md_are_never_truncated() -> None:
+ docx_result = await doc_generate("docx", "T", content="body", tool_context=None)
+ md_result = await doc_generate("md", "T", content="body", tool_context=None)
+ assert docx_result["truncated"] is False
+ assert md_result["truncated"] is False
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "sheets",
+ [
+ None,
+ [],
+ "not-a-list",
+ [object()],
+ [{"name": "S"}],
+ [{"name": "S", "rows": "nope"}],
+ [{"name": 3, "rows": []}],
+ [{"name": "S", "rows": ["nope"]}],
+ ],
+)
+async def test_xlsx_invalid_sheets_return_error(sheets: object) -> None:
+ result = await doc_generate(
+ "xlsx",
+ "",
+ sheets=sheets, # type: ignore[arg-type]
+ tool_context=None,
+ )
+ assert "error" in result
+
+
+# ---------------------------------------------------------------------- csv --
+@pytest.mark.asyncio
+async def test_csv_rows_are_written_as_utf8() -> None:
+ result = await doc_generate(
+ "csv",
+ "",
+ rows=[["name", "note"], [1, None], ["中文", "ok"]],
+ filename="export",
+ tool_context=None,
+ )
+
+ assert result["filename"] == "export.csv"
+ assert result["mime_type"] == "text/csv"
+ text = Path(result["path"]).read_bytes().decode("utf-8")
+ assert text.startswith("name,note")
+ assert list(csv.reader(io.StringIO(text))) == [
+ ["name", "note"],
+ ["1", ""],
+ ["中文", "ok"],
+ ]
+
+
+@pytest.mark.asyncio
+async def test_csv_content_is_used_when_rows_missing() -> None:
+ content = "a,b\n1,2\n"
+ result = await doc_generate("csv", "", content=content, tool_context=None)
+ assert Path(result["path"]).read_bytes() == content.encode("utf-8")
+
+
+@pytest.mark.asyncio
+async def test_csv_requires_rows_or_content() -> None:
+ result = await doc_generate("csv", "", tool_context=None)
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_csv_invalid_rows() -> None:
+ result = await doc_generate("csv", "", rows="nope", tool_context=None) # type: ignore[arg-type]
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_csv_invalid_row_item() -> None:
+ result = await doc_generate("csv", "", rows=["nope"], tool_context=None) # type: ignore[list-item]
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_csv_row_cap(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(doc_generate_module, "_MAX_CSV_ROWS", 1)
+ result = await doc_generate(
+ "csv",
+ "",
+ rows=[["a"], ["b"], ["c"]],
+ tool_context=None,
+ )
+ assert Path(result["path"]).read_bytes() == b"a\r\n"
+ assert result["truncated"] is True
+
+
+@pytest.mark.asyncio
+async def test_csv_neutralizes_formula_cells() -> None:
+ rows = [
+ ["=1+1", "+1", "-1", "@SUM(A1)", "\t=cmd|'/C calc'!A0", "safe", " - note"],
+ ]
+ result = await doc_generate("csv", "", rows=rows, tool_context=None)
+
+ parsed = list(
+ csv.reader(io.StringIO(Path(result["path"]).read_text(encoding="utf-8")))
+ )
+ assert parsed == [
+ [
+ "'=1+1",
+ "'+1",
+ "'-1",
+ "'@SUM(A1)",
+ "'\t=cmd|'/C calc'!A0",
+ "safe",
+ " - note",
+ ]
+ ]
+
+
+@pytest.mark.asyncio
+async def test_csv_without_truncation_sets_flag_false() -> None:
+ result = await doc_generate("csv", "", rows=[["a"]], tool_context=None)
+ assert result["truncated"] is False
+
+
+@pytest.mark.asyncio
+async def test_csv_empty_rows_is_valid() -> None:
+ result = await doc_generate("csv", "", rows=[], tool_context=None)
+ assert result["size_bytes"] == 0
+
+
+# ----------------------------------------------------------------------- md --
+@pytest.mark.asyncio
+async def test_md_prefixes_title_heading() -> None:
+ result = await doc_generate("md", "My Title", content="Body", tool_context=None)
+ assert Path(result["path"]).read_text(encoding="utf-8") == "# My Title\n\nBody"
+ assert result["mime_type"] == "text/markdown"
+ assert result["filename"] == "document.md"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("content", ["# Existing\nbody", " ## Existing\nbody"])
+async def test_md_does_not_prefix_existing_heading(content: str) -> None:
+ result = await doc_generate("md", "Title", content=content, tool_context=None)
+ assert Path(result["path"]).read_text(encoding="utf-8") == content
+
+
+@pytest.mark.asyncio
+async def test_md_title_only() -> None:
+ result = await doc_generate("md", "Title", content="", tool_context=None)
+ assert Path(result["path"]).read_text(encoding="utf-8") == "# Title\n"
+
+
+@pytest.mark.asyncio
+async def test_md_empty_document() -> None:
+ result = await doc_generate("md", "", content="", tool_context=None)
+ assert result["size_bytes"] == 0
+
+
+@pytest.mark.asyncio
+async def test_md_saves_artifact() -> None:
+ context = SaveContext()
+ result = await doc_generate(
+ "md",
+ "T",
+ content="body",
+ filename="notes.txt",
+ tool_context=context, # type: ignore[arg-type]
+ )
+ assert result["artifact_saved"] is True
+ assert result["path"] is None
+ assert result["filename"] == "notes.md"
+ name, artifact = context.artifacts[0]
+ assert name == "notes.md"
+ assert artifact.inline_data.mime_type == "text/markdown"
+
+
+# ---------------------------------------------------------------- validation --
+@pytest.mark.asyncio
+@pytest.mark.parametrize("fmt", ["pdf", "html", "", None, 123])
+async def test_invalid_format_returns_error(fmt: object) -> None:
+ result = await doc_generate(fmt, "t", tool_context=None) # type: ignore[arg-type]
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("filename", "fmt", "expected"),
+ [
+ ("../../evil name!.txt", "docx", "evil-name.docx"),
+ ("C:\\tmp\\report.docx", "docx", "report.docx"),
+ ("report", "docx", "report.docx"),
+ ("报告 final.md", "md", "报告-final.md"),
+ ("archive.tar.gz", "csv", "archive.tar.csv"),
+ (" ", "csv", "document.csv"),
+ ("!!!", "csv", "document.csv"),
+ (None, "csv", "document.csv"),
+ (123, "csv", "document.csv"),
+ ],
+)
+async def test_filename_sanitization(filename: object, fmt: str, expected: str) -> None:
+ result = await doc_generate(
+ fmt,
+ "",
+ content="x" if fmt != "csv" else "",
+ rows=[["x"]] if fmt == "csv" else None,
+ filename=filename, # type: ignore[arg-type]
+ tool_context=None,
+ )
+ assert result["filename"] == expected
+
+
+@pytest.mark.asyncio
+async def test_long_filename_is_capped() -> None:
+ result = await doc_generate(
+ "md",
+ "",
+ content="x",
+ filename="a" * 300 + ".md",
+ tool_context=None,
+ )
+ assert len(result["filename"]) <= 120
+ assert result["filename"].endswith(".md")
+
+
+@pytest.mark.asyncio
+async def test_non_string_title_and_content_are_coerced() -> None:
+ result = await doc_generate("md", 123, content=456, tool_context=None) # type: ignore[arg-type]
+ text = Path(result["path"]).read_text(encoding="utf-8")
+ assert text == "# 123\n\n456"
+
+
+@pytest.mark.asyncio
+async def test_none_title_is_treated_as_empty() -> None:
+ result = await doc_generate("md", None, content="body", tool_context=None) # type: ignore[arg-type]
+ assert Path(result["path"]).read_text(encoding="utf-8") == "body"
+
+
+@pytest.mark.asyncio
+async def test_unexpected_build_failure_returns_error(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ def explode(title: str, content: str) -> bytes:
+ raise RuntimeError("unexpected")
+
+ monkeypatch.setattr(doc_generate_module, "_build_md", explode)
+
+ result = await doc_generate("md", "T", content="body", tool_context=None)
+
+ assert "failed to generate md" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_temp_file_write_failure_returns_error(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ blocker = tmp_path / "not-a-directory"
+ blocker.write_text("x", encoding="utf-8")
+ monkeypatch.setattr(
+ doc_generate_module.tempfile, "mkdtemp", lambda **kwargs: str(blocker)
+ )
+
+ result = await doc_generate("md", "T", content="body", tool_context=None)
+
+ assert "error" in result
+ assert "failed to write file" in result["error"]
diff --git a/tests/tools/builtin_tools/test_document_parse.py b/tests/tools/builtin_tools/test_document_parse.py
new file mode 100644
index 000000000..b783911aa
--- /dev/null
+++ b/tests/tools/builtin_tools/test_document_parse.py
@@ -0,0 +1,852 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import csv
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+from veadk.tools.builtin_tools import document_parse as document_parse_module
+from veadk.tools.builtin_tools.document_parse import document_parse
+
+
+# --------------------------------------------------------------- PDF helpers --
+def _make_pdf(page_texts: list[str]) -> bytes:
+ """Build a tiny, valid PDF with one text object per page."""
+ font_id = 3
+ objects: dict[int, bytes] = {
+ 1: b"<< /Type /Catalog /Pages 2 0 R >>",
+ 2: (
+ "<< /Type /Pages /Kids ["
+ + " ".join(f"{4 + 2 * i} 0 R" for i in range(len(page_texts)))
+ + f"] /Count {len(page_texts)} >>"
+ ).encode(),
+ 3: b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+ }
+ for index, text in enumerate(page_texts):
+ page_id = 4 + 2 * index
+ content_id = 5 + 2 * index
+ objects[page_id] = (
+ f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] "
+ f"/Resources << /Font << /F1 {font_id} 0 R >> >> "
+ f"/Contents {content_id} 0 R >>"
+ ).encode()
+ escaped = text.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+ stream = f"BT /F1 24 Tf 72 720 Td ({escaped}) Tj ET".encode()
+ objects[content_id] = (
+ b"<< /Length "
+ + str(len(stream)).encode()
+ + b" >>\nstream\n"
+ + stream
+ + b"\nendstream"
+ )
+
+ output = bytearray(b"%PDF-1.4\n")
+ offsets: dict[int, int] = {}
+ for object_id in sorted(objects):
+ offsets[object_id] = len(output)
+ output += f"{object_id} 0 obj\n".encode() + objects[object_id] + b"\nendobj\n"
+ xref = len(output)
+ size = max(objects) + 1
+ output += f"xref\n0 {size}\n".encode()
+ output += b"0000000000 65535 f \n"
+ for object_id in range(1, size):
+ output += f"{offsets[object_id]:010d} 00000 n \n".encode()
+ output += (
+ f"trailer\n<< /Size {size} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n".encode()
+ )
+ return bytes(output)
+
+
+def _write_pdf(path: Path, page_texts: list[str]) -> Path:
+ path.write_bytes(_make_pdf(page_texts))
+ return path
+
+
+def _make_docx_bytes(
+ paragraphs: list[str], table: list[list[str]] | None = None
+) -> bytes:
+ import docx
+
+ document = docx.Document()
+ for paragraph in paragraphs:
+ document.add_paragraph(paragraph)
+ if table:
+ created = document.add_table(rows=len(table), cols=len(table[0]))
+ for row_index, row in enumerate(table):
+ for column_index, value in enumerate(row):
+ created.cell(row_index, column_index).text = value
+ buffer = io.BytesIO()
+ document.save(buffer)
+ return buffer.getvalue()
+
+
+def _make_xlsx_bytes(sheets: list[tuple[str, list[list[object]]]]) -> bytes:
+ import openpyxl
+
+ workbook = openpyxl.Workbook()
+ default = workbook.active
+ for index, (name, rows) in enumerate(sheets):
+ worksheet = default if index == 0 else workbook.create_sheet()
+ worksheet.title = name
+ for row in rows:
+ worksheet.append(row)
+ buffer = io.BytesIO()
+ workbook.save(buffer)
+ return buffer.getvalue()
+
+
+class FakeResponse:
+ def __init__(
+ self,
+ body: bytes = b"",
+ *,
+ status: int = 200,
+ headers: dict[str, str] | None = None,
+ redirect: bool = False,
+ chunks: list[bytes] | None = None,
+ ) -> None:
+ self._body = body
+ self.status_code = status
+ self.headers = headers or {}
+ self._redirect = redirect
+ self._chunks = chunks
+ self.closed = False
+
+ @property
+ def is_redirect(self) -> bool:
+ return self._redirect
+
+ @property
+ def ok(self) -> bool:
+ return self.status_code < 400
+
+ def iter_content(self, chunk_size: int = 16_384):
+ if self._chunks is not None:
+ yield from self._chunks
+ return
+ for start in range(0, len(self._body), chunk_size):
+ yield self._body[start : start + chunk_size]
+
+ def close(self) -> None:
+ self.closed = True
+
+
+# --------------------------------------------------------------- local files --
+def test_parse_txt_file_metadata(tmp_path: Path) -> None:
+ path = tmp_path / "note.txt"
+ path.write_text("hello world", encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "txt"
+ assert result["text"] == "hello world"
+ assert result["truncated"] is False
+ metadata = result["metadata"]
+ assert metadata["source_kind"] == "file"
+ assert metadata["path"] == str(path)
+ assert metadata["size_bytes"] == 11
+ assert metadata["format"] == "txt"
+
+
+def test_parse_md_by_extension(tmp_path: Path) -> None:
+ path = tmp_path / "readme.md"
+ path.write_text("# Title\n\nBody", encoding="utf-8")
+ result = document_parse(str(path))
+ assert result["format"] == "md"
+ assert "# Title" in result["text"]
+
+
+@pytest.mark.parametrize("suffix", [".md", ".markdown", ".txt"])
+def test_text_formats_by_extension(tmp_path: Path, suffix: str) -> None:
+ path = tmp_path / f"doc{suffix}"
+ path.write_text("content", encoding="utf-8")
+ assert document_parse(str(path))["format"] in {"md", "txt"}
+
+
+def test_parse_json_valid_is_pretty_printed(tmp_path: Path) -> None:
+ path = tmp_path / "data.json"
+ path.write_text('{"b": 1, "a": "\\u4e2d"}', encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "json"
+ assert result["text"] == json.dumps(
+ {"b": 1, "a": "中"}, ensure_ascii=False, indent=2
+ )
+ assert result["metadata"]["valid_json"] is True
+
+
+def test_parse_invalid_json_falls_back_to_text(tmp_path: Path) -> None:
+ path = tmp_path / "broken.json"
+ path.write_text("{not json", encoding="utf-8")
+ result = document_parse(str(path))
+ assert result["format"] == "json"
+ assert result["text"] == "{not json"
+ assert result["metadata"]["valid_json"] is False
+
+
+def test_parse_csv_sniffs_semicolon_delimiter(tmp_path: Path) -> None:
+ path = tmp_path / "table.csv"
+ path.write_text("a;b\n1;2\n", encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "csv"
+ assert result["text"] == "a\tb\n1\t2"
+ assert result["metadata"]["delimiter"] == ";"
+ assert result["metadata"]["rows"] == 2
+
+
+def test_parse_csv_falls_back_to_comma(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ def raise_error(self, sample):
+ raise csv.Error("cannot sniff")
+
+ monkeypatch.setattr(csv.Sniffer, "sniff", raise_error)
+ path = tmp_path / "table.csv"
+ path.write_text("a,b\n1,2\n", encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["text"] == "a\tb\n1\t2"
+ assert result["metadata"]["delimiter"] == ","
+
+
+def test_parse_csv_row_cap(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_CSV_ROWS", 1)
+ path = tmp_path / "table.csv"
+ path.write_text("a,b\n1,2\n3,4\n", encoding="utf-8")
+ result = document_parse(str(path))
+ assert result["text"] == "a\tb"
+ assert result["metadata"]["rows"] == 1
+
+
+def test_parse_html_uses_trafilatura(tmp_path: Path) -> None:
+ path = tmp_path / "page.html"
+ path.write_text(
+ "
Readable body content.
",
+ encoding="utf-8",
+ )
+ result = document_parse(str(path))
+ assert result["format"] == "html"
+ assert "Readable body content." in result["text"]
+ assert result["metadata"]["extraction"] in {"trafilatura", "fallback"}
+
+
+def test_parse_html_fallback_strips_tags_and_scripts(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ import trafilatura
+
+ monkeypatch.setattr(trafilatura, "extract", lambda text: None)
+ path = tmp_path / "page.html"
+ path.write_text(
+ ""
+ "Hello & bye
",
+ encoding="utf-8",
+ )
+
+ result = document_parse(str(path))
+
+ assert result["metadata"]["extraction"] == "fallback"
+ assert "Hello & bye" in result["text"]
+ assert "secret" not in result["text"]
+ assert ".x{}" not in result["text"]
+
+
+def test_parse_html_fallback_when_extractor_raises(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ import trafilatura
+
+ def explode(text):
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr(trafilatura, "extract", explode)
+ path = tmp_path / "page.html"
+ path.write_text("Fallback
", encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["text"] == "Fallback"
+ assert result["metadata"]["extraction"] == "fallback"
+
+
+def test_parse_empty_text_file(tmp_path: Path) -> None:
+ path = tmp_path / "empty.txt"
+ path.write_bytes(b"")
+ result = document_parse(str(path))
+ assert result == {
+ "format": "txt",
+ "text": "",
+ "truncated": False,
+ "metadata": {
+ "source_kind": "file",
+ "path": str(path),
+ "size_bytes": 0,
+ "download_truncated": False,
+ "format": "txt",
+ },
+ }
+
+
+def test_truncation_sets_flag_and_caps_length(tmp_path: Path) -> None:
+ path = tmp_path / "long.txt"
+ path.write_text("a" * 1_500, encoding="utf-8")
+
+ result = document_parse(str(path), max_chars=1_000)
+
+ assert result["truncated"] is True
+ assert len(result["text"]) == 1_000
+
+
+def test_exact_length_is_not_truncated(tmp_path: Path) -> None:
+ path = tmp_path / "exact.txt"
+ path.write_text("b" * 1_000, encoding="utf-8")
+ assert document_parse(str(path), max_chars=1_000)["truncated"] is False
+
+
+@pytest.mark.parametrize("max_chars", [999, 1_000_001, True, "1000", None, 1.5])
+def test_invalid_max_chars_returns_error(max_chars: object) -> None:
+ result = document_parse("anything", max_chars=max_chars) # type: ignore[arg-type]
+ assert "error" in result
+
+
+def test_missing_file_returns_error(tmp_path: Path) -> None:
+ result = document_parse(str(tmp_path / "nope.txt"))
+ assert "error" in result
+ assert "not found" in result["error"]
+
+
+@pytest.mark.parametrize("source", ["", " ", None, 123])
+def test_invalid_source_returns_error(source: object) -> None:
+ result = document_parse(source) # type: ignore[arg-type]
+ assert "error" in result
+
+
+def test_unsupported_explicit_format_returns_error(tmp_path: Path) -> None:
+ path = tmp_path / "x.txt"
+ path.write_text("x", encoding="utf-8")
+ result = document_parse(str(path), format="xml")
+ assert "error" in result
+ assert "unsupported format" in result["error"]
+
+
+def test_non_string_explicit_format_returns_error(tmp_path: Path) -> None:
+ path = tmp_path / "x.txt"
+ path.write_text("x", encoding="utf-8")
+ result = document_parse(str(path), format=123) # type: ignore[arg-type]
+ assert "unsupported format" in result["error"]
+
+
+def test_format_override_wins_over_extension(tmp_path: Path) -> None:
+ path = tmp_path / "data.txt"
+ path.write_text('{"a": 1}', encoding="utf-8")
+ result = document_parse(str(path), format="json")
+ assert result["format"] == "json"
+ assert result["metadata"]["valid_json"] is True
+
+
+def test_format_alias_is_normalized(tmp_path: Path) -> None:
+ path = tmp_path / "doc.md"
+ path.write_text("body", encoding="utf-8")
+ result = document_parse(str(path), format="markdown")
+ assert result["format"] == "md"
+
+
+def test_filetype_detects_format_without_extension(tmp_path: Path) -> None:
+ path = tmp_path / "blob.bin"
+ path.write_bytes(_make_docx_bytes(["hello"]))
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "docx"
+ assert result["text"] == "hello"
+
+
+def test_unknown_bytes_fall_back_to_text(tmp_path: Path) -> None:
+ path = tmp_path / "blob.bin"
+ path.write_bytes(b"\x00\x01random bytes")
+ result = document_parse(str(path))
+ assert result["format"] == "txt"
+
+
+def test_detected_but_unsupported_binary_falls_back_to_text(tmp_path: Path) -> None:
+ import base64
+
+ png = base64.b64decode(
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8"
+ "z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+ )
+ path = tmp_path / "image.bin"
+ path.write_bytes(png)
+ assert document_parse(str(path))["format"] == "txt"
+
+
+def test_read_failure_returns_error(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ path = tmp_path / "denied.txt"
+ path.write_text("x", encoding="utf-8")
+
+ def explode(self, *args, **kwargs):
+ raise PermissionError("denied")
+
+ monkeypatch.setattr(Path, "open", explode)
+
+ result = document_parse(str(path))
+
+ assert "failed to read file" in result["error"]
+
+
+def test_filetype_error_falls_back_to_text(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ def explode(data):
+ raise RuntimeError("detector failed")
+
+ monkeypatch.setattr(document_parse_module.filetype, "guess", explode)
+ path = tmp_path / "blob.bin"
+ path.write_bytes(b"plain text")
+ result = document_parse(str(path))
+ assert result["format"] == "txt"
+
+
+def test_detection_failure_returns_error(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ def explode(*args, **kwargs):
+ raise RuntimeError("unexpected")
+
+ monkeypatch.setattr(document_parse_module, "_detect_format", explode)
+ path = tmp_path / "blob.txt"
+ path.write_text("x", encoding="utf-8")
+ result = document_parse(str(path))
+ assert result["error"].startswith("failed to parse document")
+
+
+# --------------------------------------------------------------------- docx --
+def test_parse_docx_paragraphs_and_tables(tmp_path: Path) -> None:
+ import docx
+
+ document = docx.Document()
+ document.add_paragraph("First")
+ table = document.add_table(rows=2, cols=2)
+ for row_index, row in enumerate([["a", "b"], ["c", "d"]]):
+ for column_index, value in enumerate(row):
+ table.cell(row_index, column_index).text = value
+ document.add_paragraph("After")
+ buffer = io.BytesIO()
+ document.save(buffer)
+
+ path = tmp_path / "report.docx"
+ path.write_bytes(buffer.getvalue())
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "docx"
+ assert result["text"] == "First\n\na | b\nc | d\n\nAfter"
+ assert result["metadata"]["paragraphs"] == 2
+ assert result["metadata"]["tables"] == 1
+
+
+def test_corrupt_docx_returns_error(tmp_path: Path) -> None:
+ path = tmp_path / "broken.docx"
+ path.write_bytes(b"not a zip archive")
+ result = document_parse(str(path))
+ assert result["error"].startswith("failed to parse docx")
+
+
+# --------------------------------------------------------------------- xlsx --
+def test_parse_xlsx_sheets_and_rows(tmp_path: Path) -> None:
+ path = tmp_path / "book.xlsx"
+ path.write_bytes(
+ _make_xlsx_bytes(
+ [
+ ("Alpha", [["a", "b"], [1, 2]]),
+ ("Beta", [["c"]]),
+ ]
+ )
+ )
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "xlsx"
+ assert result["text"] == "## Alpha\na\tb\n1\t2\n## Beta\nc"
+ assert result["metadata"]["sheets"] == ["Alpha", "Beta"]
+ assert result["metadata"]["total_rows"] == 3
+
+
+def test_parse_xlsx_caps_sheets_and_rows(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_XLSX_SHEETS", 1)
+ monkeypatch.setattr(document_parse_module, "_MAX_XLSX_ROWS_PER_SHEET", 1)
+ path = tmp_path / "book.xlsx"
+ path.write_bytes(
+ _make_xlsx_bytes(
+ [
+ ("Alpha", [["a"], ["b"]]),
+ ("Beta", [["c"]]),
+ ]
+ )
+ )
+
+ result = document_parse(str(path))
+
+ assert result["text"] == "## Alpha\na"
+ assert result["metadata"]["sheets"] == ["Alpha"]
+ assert result["metadata"]["total_rows"] == 1
+
+
+def test_corrupt_xlsx_returns_error(tmp_path: Path) -> None:
+ path = tmp_path / "broken.xlsx"
+ path.write_bytes(b"not a workbook")
+ result = document_parse(str(path))
+ assert result["error"].startswith("failed to parse xlsx")
+
+
+# ---------------------------------------------------------------------- pdf --
+def test_parse_pdf_multiple_pages(tmp_path: Path) -> None:
+ path = _write_pdf(tmp_path / "doc.pdf", ["First page", "Second page"])
+
+ result = document_parse(str(path))
+
+ assert result["format"] == "pdf"
+ assert result["text"] == "First page\n\nSecond page"
+ assert result["metadata"]["pages"] == 2
+ assert result["metadata"]["needs_ocr"] is False
+
+
+def test_parse_pdf_without_text_sets_needs_ocr(tmp_path: Path) -> None:
+ path = _write_pdf(tmp_path / "scan.pdf", [""])
+
+ result = document_parse(str(path))
+
+ assert result["text"] == ""
+ assert result["metadata"]["pages"] == 1
+ assert result["metadata"]["needs_ocr"] is True
+
+
+def test_parse_pdf_blank_pages_do_not_set_needs_ocr_when_text_exists(
+ tmp_path: Path,
+) -> None:
+ path = _write_pdf(tmp_path / "mixed.pdf", ["text", ""])
+ result = document_parse(str(path))
+ assert result["metadata"]["needs_ocr"] is False
+
+
+def test_corrupt_pdf_returns_error(tmp_path: Path) -> None:
+ path = tmp_path / "broken.pdf"
+ path.write_bytes(b"%PDF-1.4 definitely broken")
+ result = document_parse(str(path))
+ assert result["error"].startswith("failed to parse pdf")
+
+
+# --------------------------------------------------------------------- URLs --
+def test_url_download_success(monkeypatch: pytest.MonkeyPatch) -> None:
+ checked: list[str] = []
+ response = FakeResponse(b"remote text")
+
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: checked.append(url)
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/file", format="txt")
+
+ assert result["format"] == "txt"
+ assert result["text"] == "remote text"
+ assert result["metadata"]["source_kind"] == "url"
+ assert result["metadata"]["url"] == "https://example.com/file"
+ assert result["metadata"]["requested_url"] == "https://example.com/file"
+ assert result["metadata"]["size_bytes"] == 11
+ assert checked == ["https://example.com/file"]
+ assert response.closed is True
+
+
+def test_url_redirect_is_revalidated_and_detected_by_extension(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ checked: list[str] = []
+ responses = [
+ FakeResponse(redirect=True, headers={"location": "/next.csv"}),
+ FakeResponse(b"a,b\n1,2\n"),
+ ]
+
+ def fake_get(*args, **kwargs):
+ assert kwargs["allow_redirects"] is False
+ return responses.pop(0)
+
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: checked.append(url)
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", fake_get)
+
+ result = document_parse("https://example.com/start")
+
+ assert checked == [
+ "https://example.com/start",
+ "https://example.com/next.csv",
+ ]
+ assert result["format"] == "csv"
+ assert result["text"] == "a\tb\n1\t2"
+ assert result["metadata"]["url"] == "https://example.com/next.csv"
+
+
+def test_url_redirect_to_private_host_is_rejected(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ response = FakeResponse(redirect=True, headers={"location": "http://127.0.0.1/x"})
+
+ def guard(url: str) -> str:
+ if "127.0.0.1" in url:
+ raise ValueError("Blocked non-public address")
+ return "example.com"
+
+ monkeypatch.setattr(document_parse_module, "assert_public_url", guard)
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/start")
+
+ assert result == {"error": "Blocked non-public address"}
+
+
+def test_url_too_many_redirects(monkeypatch: pytest.MonkeyPatch) -> None:
+ responses = [
+ FakeResponse(redirect=True, headers={"location": f"/hop{i}"}) for i in range(4)
+ ]
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(
+ document_parse_module.requests, "get", lambda *a, **k: responses.pop(0)
+ )
+
+ result = document_parse("https://example.com/start")
+
+ assert "too many redirects" in result["error"]
+
+
+def test_url_http_error(monkeypatch: pytest.MonkeyPatch) -> None:
+ response = FakeResponse(status=404)
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/missing")
+
+ assert result == {"error": "HTTP 404"}
+ assert response.closed is True
+
+
+def test_url_request_exception(monkeypatch: pytest.MonkeyPatch) -> None:
+ import requests
+
+ def explode(*args, **kwargs):
+ raise requests.RequestException("connection reset")
+
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", explode)
+
+ result = document_parse("https://example.com/start")
+
+ assert "download failed" in result["error"]
+
+
+def test_local_file_is_capped(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_DOWNLOAD_BYTES", 10)
+ path = tmp_path / "big.txt"
+ path.write_bytes(b"x" * 11)
+
+ result = document_parse(str(path))
+
+ assert "error" in result
+ assert "byte limit" in result["error"]
+
+
+def test_local_file_at_cap_is_parsed(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_DOWNLOAD_BYTES", 10)
+ path = tmp_path / "exact.txt"
+ path.write_bytes(b"x" * 10)
+
+ result = document_parse(str(path))
+
+ assert result["text"] == "x" * 10
+ assert result["metadata"]["size_bytes"] == 10
+
+
+def test_url_download_is_capped(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_DOWNLOAD_BYTES", 10)
+ response = FakeResponse(chunks=[b"", b"x" * 8, b"y" * 8])
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/big", format="txt")
+
+ assert result["text"] == "xxxxxxxxyy"
+ assert result["metadata"]["size_bytes"] == 10
+ assert result["metadata"]["download_truncated"] is True
+
+
+def test_url_exact_cap_is_not_flagged_as_truncated(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(document_parse_module, "_MAX_DOWNLOAD_BYTES", 10)
+ response = FakeResponse(body=b"x" * 10)
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/exact", format="txt")
+
+ assert result["text"] == "x" * 10
+ assert result["metadata"]["download_truncated"] is False
+
+
+def test_local_file_never_reports_download_truncation(tmp_path: Path) -> None:
+ path = tmp_path / "note.txt"
+ path.write_text("hello", encoding="utf-8")
+
+ result = document_parse(str(path))
+
+ assert result["metadata"]["download_truncated"] is False
+
+
+def test_url_private_address_is_rejected_before_request() -> None:
+ result = document_parse("http://127.0.0.1/secret.txt")
+ assert "error" in result
+ assert result["error"]
+
+
+def test_url_unsupported_explicit_format(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(
+ document_parse_module.requests,
+ "get",
+ lambda *a, **k: FakeResponse(b"data"),
+ )
+ result = document_parse("https://example.com/x", format="xml")
+ assert "unsupported format" in result["error"]
+
+
+# ------------------------------------------------- URL format detection --
+def test_url_content_type_detects_html_without_suffix(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ body = b"Hello page
"
+ response = FakeResponse(body, headers={"content-type": "text/html; charset=utf-8"})
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/page")
+
+ assert result["format"] == "html"
+ assert "Hello page" in result["text"]
+ assert "" not in result["text"]
+ assert result["metadata"]["content_type"] == "text/html; charset=utf-8"
+
+
+def test_url_content_type_detects_json(monkeypatch: pytest.MonkeyPatch) -> None:
+ response = FakeResponse(b'{"a": 1}', headers={"content-type": "application/json"})
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/api/data")
+
+ assert result["format"] == "json"
+ assert result["metadata"]["valid_json"] is True
+ assert json.loads(result["text"]) == {"a": 1}
+
+
+def test_url_html_is_sniffed_without_content_type(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ response = FakeResponse(b"\n
plain")
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/")
+
+ assert result["format"] == "html"
+ assert "plain" in result["text"]
+ assert "content_type" not in result["metadata"]
+
+
+def test_url_explicit_format_wins_over_content_type(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ response = FakeResponse(
+ b"raw",
+ headers={"content-type": "text/html"},
+ )
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/page", format="txt")
+
+ assert result["format"] == "txt"
+ assert result["text"] == "raw"
+
+
+def test_url_suffix_wins_over_content_type(monkeypatch: pytest.MonkeyPatch) -> None:
+ response = FakeResponse(b"a,b\n1,2\n", headers={"content-type": "text/html"})
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/table.csv")
+
+ assert result["format"] == "csv"
+ assert result["text"] == "a\tb\n1\t2"
+
+
+def test_url_unknown_content_type_falls_back_to_text(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ response = FakeResponse(
+ b"plain words", headers={"content-type": "application/octet-stream"}
+ )
+ monkeypatch.setattr(
+ document_parse_module, "assert_public_url", lambda url: "example.com"
+ )
+ monkeypatch.setattr(document_parse_module.requests, "get", lambda *a, **k: response)
+
+ result = document_parse("https://example.com/blob")
+
+ assert result["format"] == "txt"
+ assert result["text"] == "plain words"
diff --git a/tests/tools/builtin_tools/test_http_request.py b/tests/tools/builtin_tools/test_http_request.py
new file mode 100644
index 000000000..c943dacdb
--- /dev/null
+++ b/tests/tools/builtin_tools/test_http_request.py
@@ -0,0 +1,755 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the ``http_request`` built-in tool."""
+
+import inspect
+import socket
+
+import httpx
+import pytest
+
+from veadk.tools.builtin_tools import http_request as http_request_module
+from veadk.tools.builtin_tools.http_request import http_request
+
+_PUBLIC_IP = "93.184.216.34"
+
+
+def _addrinfo(ip: str) -> list:
+ return [(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP, "", (ip, 0))]
+
+
+def _public_addrinfo(host: str, port: int | None = None) -> list:
+ return _addrinfo(_PUBLIC_IP)
+
+
+@pytest.fixture(autouse=True)
+def _hermetic_dns(monkeypatch):
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo", _public_addrinfo
+ )
+ monkeypatch.delenv("TOOL_HTTP_ALLOWLIST", raising=False)
+
+
+class _FakeResponse:
+ def __init__(
+ self,
+ status_code: int = 200,
+ headers: dict | None = None,
+ content: bytes = b"",
+ encoding: str | None = None,
+ chunks: list[bytes] | None = None,
+ ):
+ self.status_code = status_code
+ self.headers = headers or {}
+ self.encoding = encoding
+ self._chunks = chunks if chunks is not None else [content]
+
+ def iter_bytes(self):
+ yield from self._chunks
+
+
+class _FakeStream:
+ def __init__(self, response: _FakeResponse):
+ self._response = response
+
+ def __enter__(self) -> _FakeResponse:
+ return self._response
+
+ def __exit__(self, *exc) -> bool:
+ return False
+
+
+class _FakeClient:
+ def __init__(self, responses: list[_FakeResponse], **kwargs):
+ self._responses = list(responses)
+ self.kwargs = kwargs
+ self.calls: list[dict] = []
+ self.closed = False
+
+ def stream(self, method, url, headers=None, params=None, json=None, content=None):
+ self.calls.append(
+ {
+ "method": method,
+ "url": url,
+ "headers": headers,
+ "params": params,
+ "json": json,
+ "content": content,
+ }
+ )
+ return _FakeStream(self._responses.pop(0))
+
+ def close(self) -> None:
+ self.closed = True
+
+
+def _patch_client(
+ monkeypatch, responses: list[_FakeResponse], client_cls=_FakeClient
+) -> list:
+ created: list = []
+
+ def factory(**kwargs):
+ client = client_cls(responses, **kwargs)
+ created.append(client)
+ return client
+
+ monkeypatch.setattr(http_request_module.httpx, "Client", factory)
+ return created
+
+
+# --------------------------------------------------------------- contract ----
+def test_signature():
+ params = inspect.signature(http_request).parameters
+ assert list(params) == [
+ "url",
+ "method",
+ "headers",
+ "params",
+ "json_body",
+ "body",
+ "timeout",
+ "max_bytes",
+ "follow_redirects",
+ ]
+
+
+def test_defaults():
+ params = inspect.signature(http_request).parameters
+ assert params["url"].default is inspect.Parameter.empty
+ assert params["method"].default == "GET"
+ assert params["headers"].default is None
+ assert params["params"].default is None
+ assert params["json_body"].default is None
+ assert params["body"].default is None
+ assert params["timeout"].default == 30
+ assert params["max_bytes"].default == 5_000_000
+ assert params["follow_redirects"].default is False
+
+
+# ------------------------------------------------------------ validation ----
+@pytest.mark.parametrize("method", ["TRACE", "OPTIONS", "GET ", "", 123, None])
+def test_rejects_bad_method(method):
+ result = http_request("http://example.com", method=method)
+ assert "error" in result
+
+
+@pytest.mark.parametrize("timeout", [0, 121, True, "30", 1.5, None])
+def test_rejects_bad_timeout(timeout):
+ result = http_request("http://example.com", timeout=timeout)
+ assert "error" in result
+
+
+@pytest.mark.parametrize("max_bytes", [999, 20_000_001, True, "1000", 1000.0])
+def test_rejects_bad_max_bytes(max_bytes):
+ result = http_request("http://example.com", max_bytes=max_bytes)
+ assert "error" in result
+
+
+@pytest.mark.parametrize(
+ "url", ["ftp://example.com", "not a url", "", None, 123, "http:///no-host"]
+)
+def test_rejects_bad_url(url):
+ result = http_request(url)
+ assert "error" in result
+
+
+def test_blocks_private_address(monkeypatch):
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo",
+ lambda *args, **kwargs: _addrinfo("127.0.0.1"),
+ )
+ result = http_request("http://internal.example.com")
+ assert "error" in result
+
+
+@pytest.mark.parametrize(
+ "headers",
+ [
+ {"host": "evil.example.com"},
+ {"Host": "evil.example.com"},
+ {"content-length": "10"},
+ {"Content-Length": "10"},
+ {1: "value"},
+ {"X-Test": 1},
+ {"X-Bad\n": "value"},
+ {"X-Test": "value\r\nInjected: 1"},
+ ],
+)
+def test_rejects_bad_headers(headers):
+ result = http_request("http://example.com", headers=headers)
+ assert "error" in result
+
+
+@pytest.mark.parametrize("headers", [["x", "y"], "x"])
+def test_rejects_non_mapping_headers(headers):
+ result = http_request("http://example.com", headers=headers)
+ assert "error" in result
+
+
+def test_missing_env_header_returns_error(monkeypatch):
+ monkeypatch.delenv("VEADK_TEST_MISSING_TOKEN", raising=False)
+ result = http_request(
+ "http://example.com",
+ headers={"Authorization": "env:VEADK_TEST_MISSING_TOKEN"},
+ )
+ assert "error" in result
+
+
+def test_empty_env_name_returns_error(monkeypatch):
+ result = http_request("http://example.com", headers={"Authorization": "env:"})
+ assert "error" in result
+
+
+def test_empty_env_value_returns_error(monkeypatch):
+ monkeypatch.setenv("VEADK_TEST_EMPTY_TOKEN", "")
+ result = http_request(
+ "http://example.com",
+ headers={"Authorization": "env:VEADK_TEST_EMPTY_TOKEN"},
+ )
+ assert "error" in result
+
+
+# --------------------------------------------------------------- allowlist --
+def test_allowlist_exact_host(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", "example.com")
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://example.com/path")
+ assert result["status_code"] == 200
+
+
+def test_allowlist_subdomain(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", "example.com")
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://api.example.com/path")
+ assert result["status_code"] == 200
+
+
+def test_allowlist_case_insensitive(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", "EXAMPLE.COM")
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://Example.COM/path")
+ assert result["status_code"] == 200
+
+
+def test_allowlist_denies_other_host(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", "example.com")
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://evil.example.org/path")
+ assert "error" in result
+ assert created[0].calls == []
+ assert created[0].closed is True
+
+
+def test_empty_allowlist_is_unrestricted(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", " , ")
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://example.com/path")
+ assert result["status_code"] == 200
+
+
+def test_allowlist_applies_to_redirect(monkeypatch):
+ monkeypatch.setenv("TOOL_HTTP_ALLOWLIST", "example.com")
+ _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "http://evil.example.org/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ result = http_request("http://example.com/start", follow_redirects=True)
+ assert "error" in result
+
+
+# ------------------------------------------------------------ happy paths ---
+def test_get_success(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(
+ 200,
+ {"Content-Type": "text/plain", "X-Test": "1"},
+ b"hello",
+ )
+ ],
+ )
+ result = http_request("http://example.com/path")
+ assert result == {
+ "status_code": 200,
+ "url": "http://example.com/path",
+ "headers": {"content-type": "text/plain", "x-test": "1"},
+ "content_type": "text/plain",
+ "body": "hello",
+ "bytes": 5,
+ "truncated": False,
+ }
+ client = created[0]
+ assert client.closed is True
+ assert client.kwargs == {"timeout": 30, "follow_redirects": False}
+ assert client.calls[0]["method"] == "GET"
+
+
+def test_method_is_normalized(monkeypatch):
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ http_request("http://example.com", method="get")
+ assert created[0].calls[0]["method"] == "GET"
+
+
+def test_head_response_has_empty_body(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ignored")])
+ result = http_request("http://example.com", method="HEAD")
+ assert result["body"] == ""
+ assert result["bytes"] == 0
+ assert result["truncated"] is False
+
+
+def test_missing_content_type_is_none(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request("http://example.com")
+ assert result["content_type"] is None
+
+
+def test_resolves_env_header_without_leaking_value(monkeypatch):
+ monkeypatch.setenv("VEADK_TEST_TOKEN", "s3cret-value")
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request(
+ "http://example.com",
+ headers={"Authorization": "env:VEADK_TEST_TOKEN", "X-Plain": "ok"},
+ )
+ assert result["status_code"] == 200
+ assert created[0].calls[0]["headers"] == {
+ "Authorization": "s3cret-value",
+ "X-Plain": "ok",
+ }
+ assert "s3cret-value" not in str(result)
+
+
+def test_post_json_body_and_params(monkeypatch):
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ http_request(
+ "http://example.com/api",
+ method="POST",
+ params={"q": "x"},
+ json_body={"a": 1},
+ )
+ call = created[0].calls[0]
+ assert call["method"] == "POST"
+ assert call["params"] == {"q": "x"}
+ assert call["json"] == {"a": 1}
+ assert call["content"] is None
+
+
+def test_raw_body(monkeypatch):
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ http_request("http://example.com/api", method="POST", body="raw")
+ call = created[0].calls[0]
+ assert call["content"] == "raw"
+ assert call["json"] is None
+
+
+def test_json_body_and_raw_body_are_mutually_exclusive(monkeypatch):
+ created = _patch_client(monkeypatch, [_FakeResponse(200, content=b"ok")])
+ result = http_request(
+ "http://example.com/api", method="POST", json_body={"a": 1}, body="raw"
+ )
+ assert "error" in result
+ assert created == []
+
+
+# --------------------------------------------------------------- decoding ---
+def test_decodes_using_response_encoding(monkeypatch):
+ _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(
+ 200,
+ {"content-type": "text/plain; charset=iso-8859-1"},
+ b"caf\xe9",
+ encoding="iso-8859-1",
+ )
+ ],
+ )
+ result = http_request("http://example.com")
+ assert result["body"] == "café"
+
+
+def test_decodes_as_utf8_by_default(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"caf\xc3\xa9")])
+ result = http_request("http://example.com")
+ assert result["body"] == "café"
+
+
+def test_unknown_encoding_falls_back_to_utf8(monkeypatch):
+ _patch_client(
+ monkeypatch,
+ [_FakeResponse(200, content=b"ok", encoding="not-a-codec")],
+ )
+ result = http_request("http://example.com")
+ assert result["body"] == "ok"
+
+
+# -------------------------------------------------------------- truncation --
+def test_truncates_at_max_bytes(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"a" * 1001)])
+ result = http_request("http://example.com", max_bytes=1000)
+ assert result["bytes"] == 1000
+ assert len(result["body"]) == 1000
+ assert result["truncated"] is True
+
+
+def test_exact_limit_is_not_truncated(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(200, content=b"a" * 1000)])
+ result = http_request("http://example.com", max_bytes=1000)
+ assert result["bytes"] == 1000
+ assert result["truncated"] is False
+
+
+def test_truncates_across_chunks_and_skips_empty(monkeypatch):
+ _patch_client(
+ monkeypatch,
+ [_FakeResponse(200, chunks=[b"", b"a" * 600, b"b" * 600])],
+ )
+ result = http_request("http://example.com", max_bytes=1000)
+ assert result["bytes"] == 1000
+ assert result["body"] == "a" * 600 + "b" * 400
+ assert result["truncated"] is True
+
+
+# --------------------------------------------------------------- redirects --
+def test_redirect_not_followed_by_default(monkeypatch):
+ created = _patch_client(
+ monkeypatch, [_FakeResponse(302, {"location": "/next"}, content=b"moved")]
+ )
+ result = http_request("http://example.com/start")
+ assert result["status_code"] == 302
+ assert result["body"] == "moved"
+ assert result["url"] == "http://example.com/start"
+ assert len(created[0].calls) == 1
+
+
+def test_follows_relative_redirect(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ result = http_request(
+ "http://example.com/start", params={"a": "1"}, follow_redirects=True
+ )
+ assert result["url"] == "http://example.com/next"
+ assert result["body"] == "ok"
+ assert [call["url"] for call in created[0].calls] == [
+ "http://example.com/start",
+ "http://example.com/next",
+ ]
+ assert created[0].calls[0]["params"] == {"a": "1"}
+ assert created[0].calls[1]["params"] is None
+
+
+def test_follows_absolute_redirect(monkeypatch):
+ _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(301, {"location": "http://other.example.com/final"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ result = http_request("http://example.com/start", follow_redirects=True)
+ assert result["url"] == "http://other.example.com/final"
+
+
+def test_303_switches_post_to_get_and_drops_body(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(303, {"location": "/done"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com/api",
+ method="POST",
+ json_body={"a": 1},
+ follow_redirects=True,
+ )
+ redirected = created[0].calls[1]
+ assert redirected["method"] == "GET"
+ assert redirected["json"] is None
+ assert redirected["content"] is None
+
+
+def test_301_switches_post_to_get(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(301, {"location": "/done"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com/api", method="POST", body="raw", follow_redirects=True
+ )
+ assert created[0].calls[1]["method"] == "GET"
+ assert created[0].calls[1]["content"] is None
+
+
+def test_302_preserves_non_post_method(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "/done"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com/api",
+ method="PUT",
+ body="raw",
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["method"] == "PUT"
+ assert created[0].calls[1]["content"] == "raw"
+
+
+@pytest.mark.parametrize("status", [307, 308])
+def test_307_308_preserve_method_and_body(monkeypatch, status):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(status, {"location": "/done"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com/api",
+ method="POST",
+ json_body={"a": 1},
+ follow_redirects=True,
+ )
+ redirected = created[0].calls[1]
+ assert redirected["method"] == "POST"
+ assert redirected["json"] == {"a": 1}
+
+
+def test_credentials_are_kept_on_same_origin_redirect(monkeypatch):
+ monkeypatch.setenv("VEADK_TEST_TOKEN", "s3cret-value")
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "https://example.com/start",
+ headers={"Authorization": "env:VEADK_TEST_TOKEN", "X-Plain": "ok"},
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["headers"] == {
+ "Authorization": "s3cret-value",
+ "X-Plain": "ok",
+ }
+
+
+def test_explicit_default_port_is_same_origin(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "http://example.com/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com:80/start",
+ headers={"Authorization": "Bearer t"},
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["headers"] == {"Authorization": "Bearer t"}
+
+
+def test_credentials_are_kept_on_same_host_https_upgrade(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(301, {"location": "https://example.com/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "http://example.com/start",
+ headers={"Authorization": "Bearer t", "Cookie": "a=b", "X-Plain": "ok"},
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["headers"] == {
+ "Authorization": "Bearer t",
+ "Cookie": "a=b",
+ "X-Plain": "ok",
+ }
+
+
+def test_credentials_are_stripped_across_hosts(monkeypatch):
+ monkeypatch.setenv("VEADK_TEST_TOKEN", "s3cret-value")
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "https://evil.example/capture"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ result = http_request(
+ "https://safe.example/x",
+ headers={
+ "Authorization": "env:VEADK_TEST_TOKEN",
+ "X-Api-Key": "env:VEADK_TEST_TOKEN",
+ "Proxy-Authorization": "Basic abc",
+ "Cookie": "session=1",
+ "X-Plain": "ok",
+ },
+ follow_redirects=True,
+ )
+ assert result["status_code"] == 200
+ first_headers = created[0].calls[0]["headers"]
+ assert first_headers["Authorization"] == "s3cret-value"
+ assert first_headers["X-Api-Key"] == "s3cret-value"
+ # Only non-secret, non-sensitive headers survive a cross-origin hop.
+ assert created[0].calls[1]["headers"] == {"X-Plain": "ok"}
+
+
+def test_credentials_are_stripped_on_https_to_http_downgrade(monkeypatch):
+ monkeypatch.setenv("VEADK_TEST_TOKEN", "s3cret-value")
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "http://example.com/next"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "https://example.com/start",
+ headers={
+ "Authorization": "env:VEADK_TEST_TOKEN",
+ "X-Api-Key": "env:VEADK_TEST_TOKEN",
+ "X-Plain": "ok",
+ },
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["headers"] == {"X-Plain": "ok"}
+
+
+def test_stripped_credentials_stay_stripped_on_later_hops(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "https://evil.example/one"}),
+ _FakeResponse(302, {"location": "/two"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ http_request(
+ "https://safe.example/x",
+ headers={"Authorization": "Bearer t"},
+ follow_redirects=True,
+ )
+ assert created[0].calls[1]["headers"] == {}
+ assert created[0].calls[2]["headers"] == {}
+
+
+def test_303_preserves_head_method(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(303, {"location": "/done"}),
+ _FakeResponse(200),
+ ],
+ )
+ http_request("http://example.com/api", method="HEAD", follow_redirects=True)
+ assert created[0].calls[1]["method"] == "HEAD"
+
+
+def test_too_many_redirects(monkeypatch):
+ created = _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "/1"}),
+ _FakeResponse(302, {"location": "/2"}),
+ _FakeResponse(302, {"location": "/3"}),
+ _FakeResponse(302, {"location": "/4"}),
+ ],
+ )
+ result = http_request("http://example.com/start", follow_redirects=True)
+ assert "error" in result
+ assert "redirect" in result["error"]
+ assert created[0].closed is True
+
+
+def test_redirect_without_location_is_final(monkeypatch):
+ _patch_client(monkeypatch, [_FakeResponse(302, {}, content=b"body")])
+ result = http_request("http://example.com", follow_redirects=True)
+ assert result["status_code"] == 302
+ assert result["body"] == "body"
+
+
+def test_redirect_to_private_address_is_blocked(monkeypatch):
+ def mixed_addrinfo(host, port=None):
+ if host == "internal.example.com":
+ return _addrinfo("10.0.0.1")
+ return _public_addrinfo(host, port)
+
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo", mixed_addrinfo
+ )
+ _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "http://internal.example.com/x"}),
+ _FakeResponse(200, content=b"secret"),
+ ],
+ )
+ result = http_request("http://example.com/start", follow_redirects=True)
+ assert "error" in result
+
+
+def test_redirect_to_non_http_scheme_is_blocked(monkeypatch):
+ _patch_client(
+ monkeypatch,
+ [
+ _FakeResponse(302, {"location": "ftp://example.com/x"}),
+ _FakeResponse(200, content=b"ok"),
+ ],
+ )
+ result = http_request("http://example.com/start", follow_redirects=True)
+ assert "error" in result
+
+
+# --------------------------------------------------------------- failures ---
+def test_client_creation_failure_returns_error(monkeypatch):
+ def boom(**kwargs):
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr(http_request_module.httpx, "Client", boom)
+ result = http_request("http://example.com")
+ assert "error" in result
+
+
+def test_network_error_returns_error_and_closes_client(monkeypatch):
+ class _ExplodingClient(_FakeClient):
+ def stream(self, *args, **kwargs):
+ raise httpx.ConnectError("boom")
+
+ created = _patch_client(monkeypatch, [], client_cls=_ExplodingClient)
+ result = http_request("http://example.com")
+ assert "error" in result
+ assert created[0].closed is True
diff --git a/tests/tools/builtin_tools/test_image_transform.py b/tests/tools/builtin_tools/test_image_transform.py
new file mode 100644
index 000000000..d8b616946
--- /dev/null
+++ b/tests/tools/builtin_tools/test_image_transform.py
@@ -0,0 +1,690 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the ``image_transform`` built-in tool."""
+
+import inspect
+from io import BytesIO
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from veadk.tools.builtin_tools import image_transform as tool
+
+PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+
+
+def _png_bytes(size=(4, 4), mode="RGB", color=(255, 0, 0)) -> bytes:
+ buffer = BytesIO()
+ Image.new(mode, size, color).save(buffer, format="PNG")
+ return buffer.getvalue()
+
+
+def _save(tmp_path: Path, name: str, size=(40, 20), mode="RGB", color=(255, 0, 0)):
+ path = tmp_path / name
+ Image.new(mode, size, color).save(path)
+ return str(path)
+
+
+class FakeToolContext:
+ def __init__(self, fail: bool = False) -> None:
+ self.fail = fail
+ self.saved: list[tuple[str, object]] = []
+
+ async def save_artifact(self, filename: str, artifact: object) -> int:
+ if self.fail:
+ raise RuntimeError("artifact store unavailable")
+ self.saved.append((filename, artifact))
+ return 1
+
+
+class FakeResponse:
+ def __init__(
+ self,
+ status_code: int = 200,
+ content: bytes = b"",
+ headers: dict | None = None,
+ is_redirect: bool = False,
+ ) -> None:
+ self.status_code = status_code
+ self.content = content
+ self.headers = headers or {}
+ self.is_redirect = is_redirect
+
+ async def aiter_bytes(self):
+ # Yield an empty chunk first: HTTP clients may do this, and the
+ # bounded reader must skip it rather than treat it as data.
+ yield b""
+ for index in range(0, len(self.content), 4):
+ yield self.content[index : index + 4]
+
+
+class FakeStream:
+ def __init__(self, response: FakeResponse) -> None:
+ self.response = response
+
+ async def __aenter__(self) -> FakeResponse:
+ return self.response
+
+ async def __aexit__(self, *exc_info) -> bool:
+ return False
+
+
+def _install_http(monkeypatch, responses):
+ captured: dict[str, object] = {"client_kwargs": [], "requests": []}
+
+ class FakeClient:
+ def __init__(self, **kwargs) -> None:
+ captured["client_kwargs"].append(kwargs)
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc_info):
+ return False
+
+ def stream(self, method, url, headers=None):
+ captured["requests"].append(
+ {"method": method, "url": url, "headers": headers}
+ )
+ return FakeStream(responses.pop(0))
+
+ monkeypatch.setattr(tool.httpx, "AsyncClient", FakeClient)
+ return captured
+
+
+def _allow_public(monkeypatch):
+ validated: list[str] = []
+
+ def fake_assert(url: str) -> str:
+ validated.append(url)
+ return "example.com"
+
+ monkeypatch.setattr(tool, "assert_public_url", fake_assert)
+ return validated
+
+
+def test_signature_and_defaults():
+ params = inspect.signature(tool.image_transform).parameters
+ assert list(params) == [
+ "source",
+ "operations",
+ "output_format",
+ "quality",
+ "filename",
+ "tool_context",
+ ]
+ assert params["output_format"].default is None
+ assert params["quality"].default == 90
+ assert params["filename"].default is None
+ assert params["tool_context"].default is None
+
+
+@pytest.mark.asyncio
+async def test_resize_both_dimensions_keeps_aspect(tmp_path):
+ source = _save(tmp_path, "source.png", size=(40, 20))
+ result = await tool.image_transform(
+ source, [{"type": "resize", "width": 20, "height": 20}]
+ )
+ assert result["width"] == 20
+ assert result["height"] == 10
+ assert Path(result["path"]).is_file()
+
+
+@pytest.mark.asyncio
+async def test_resize_single_dimension_preserves_aspect(tmp_path):
+ source = _save(tmp_path, "source.png", size=(40, 20))
+ by_width = await tool.image_transform(source, [{"type": "resize", "width": 10}])
+ assert (by_width["width"], by_width["height"]) == (10, 5)
+ by_height = await tool.image_transform(source, [{"type": "resize", "height": 10}])
+ assert (by_height["width"], by_height["height"]) == (20, 10)
+
+
+@pytest.mark.asyncio
+async def test_resize_keep_aspect_false_distorts(tmp_path):
+ source = _save(tmp_path, "source.png", size=(40, 20))
+ result = await tool.image_transform(
+ source,
+ [{"type": "resize", "width": 10, "height": 3, "keep_aspect": False}],
+ )
+ assert (result["width"], result["height"]) == (10, 3)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "operation",
+ [
+ {"type": "resize"},
+ {"type": "resize", "width": 0},
+ {"type": "resize", "width": -3},
+ {"type": "resize", "width": True},
+ {"type": "resize", "width": 10, "keep_aspect": "yes"},
+ ],
+)
+async def test_resize_validation(tmp_path, operation):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(source, [operation])
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_local_source_is_size_capped(tmp_path, monkeypatch):
+ monkeypatch.setattr(tool, "_MAX_DOWNLOAD_BYTES", 4)
+ source = tmp_path / "big.png"
+ source.write_bytes(b"12345")
+ result = await tool.image_transform(str(source), [{"type": "grayscale"}])
+ assert "error" in result
+ assert "byte limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_resize_rejects_oversized_output(tmp_path):
+ source = _save(tmp_path, "source.png", size=(10, 10))
+ result = await tool.image_transform(
+ source,
+ [{"type": "resize", "width": 50000, "height": 50000, "keep_aspect": False}],
+ )
+ assert "error" in result
+ assert "pixel limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_resize_rejects_oversized_derived_dimension(tmp_path):
+ source = _save(tmp_path, "source.png", size=(10, 10))
+ result = await tool.image_transform(source, [{"type": "resize", "height": 40000}])
+ assert "error" in result
+ assert "pixel limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_rotate_rejects_oversized_expanded_canvas(tmp_path, monkeypatch):
+ monkeypatch.setattr(tool, "_MAX_OUTPUT_PIXELS", 100)
+ source = _save(tmp_path, "source.png", size=(40, 20))
+ result = await tool.image_transform(source, [{"type": "rotate", "degrees": 45}])
+ assert "error" in result
+ assert "pixel limit" in result["error"]
+
+
+def test_rotated_size_matches_pillow():
+ width, height = tool._rotated_size(100, 50, 90)
+ assert (width, height) == (50, 100)
+
+
+@pytest.mark.asyncio
+async def test_crop(tmp_path):
+ source = _save(tmp_path, "source.png", size=(10, 10))
+ result = await tool.image_transform(
+ source,
+ [{"type": "crop", "left": 1, "top": 2, "right": 9, "bottom": 8}],
+ )
+ assert (result["width"], result["height"]) == (8, 6)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "operation",
+ [
+ {"type": "crop", "left": 0, "top": 0, "right": 20, "bottom": 10},
+ {"type": "crop", "left": 5, "top": 0, "right": 5, "bottom": 10},
+ {"type": "crop", "left": -1, "top": 0, "right": 5, "bottom": 10},
+ {"type": "crop", "left": 0, "top": 0, "right": 5},
+ {"type": "crop", "left": "0", "top": 0, "right": 5, "bottom": 5},
+ ],
+)
+async def test_crop_validation(tmp_path, operation):
+ source = _save(tmp_path, "source.png", size=(10, 10))
+ result = await tool.image_transform(source, [operation])
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_rotate_rgb_fills_white(tmp_path):
+ source = _save(tmp_path, "source.png", size=(10, 5))
+ result = await tool.image_transform(source, [{"type": "rotate", "degrees": 45}])
+ assert result["width"] > 10
+ assert result["height"] > 5
+ with Image.open(result["path"]) as image:
+ assert image.getpixel((0, 0)) == (255, 255, 255)
+
+
+@pytest.mark.asyncio
+async def test_rotate_rgba_fills_transparent(tmp_path):
+ source = _save(
+ tmp_path, "source.png", size=(10, 5), mode="RGBA", color=(0, 0, 255, 255)
+ )
+ result = await tool.image_transform(source, [{"type": "rotate", "degrees": 45}])
+ with Image.open(result["path"]) as image:
+ assert image.mode == "RGBA"
+ assert image.getpixel((0, 0))[3] == 0
+
+
+@pytest.mark.asyncio
+async def test_rotate_validation(tmp_path):
+ source = _save(tmp_path, "source.png")
+ for degrees in (None, "90", True):
+ result = await tool.image_transform(
+ source, [{"type": "rotate", "degrees": degrees}]
+ )
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_flip_horizontal(tmp_path):
+ path = tmp_path / "split.png"
+ image = Image.new("RGB", (4, 2), (255, 0, 0))
+ image.paste((0, 0, 255), (2, 0, 4, 2))
+ image.save(path)
+ result = await tool.image_transform(
+ str(path), [{"type": "flip", "direction": "horizontal"}]
+ )
+ with Image.open(result["path"]) as flipped:
+ assert flipped.getpixel((0, 0)) == (0, 0, 255)
+
+
+@pytest.mark.asyncio
+async def test_flip_vertical(tmp_path):
+ path = tmp_path / "split.png"
+ image = Image.new("RGB", (2, 4), (255, 0, 0))
+ image.paste((0, 0, 255), (0, 2, 2, 4))
+ image.save(path)
+ result = await tool.image_transform(
+ str(path), [{"type": "flip", "direction": "vertical"}]
+ )
+ with Image.open(result["path"]) as flipped:
+ assert flipped.getpixel((0, 0)) == (0, 0, 255)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("direction", ["diagonal", None, 3])
+async def test_flip_validation(tmp_path, direction):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source, [{"type": "flip", "direction": direction}]
+ )
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_thumbnail_preserves_aspect(tmp_path):
+ source = _save(tmp_path, "source.png", size=(100, 50))
+ result = await tool.image_transform(source, [{"type": "thumbnail", "max_size": 20}])
+ assert (result["width"], result["height"]) == (20, 10)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("max_size", [0, -1, True, "20"])
+async def test_thumbnail_validation(tmp_path, max_size):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source, [{"type": "thumbnail", "max_size": max_size}]
+ )
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_grayscale_to_jpeg(tmp_path):
+ source = _save(tmp_path, "source.png", mode="RGB")
+ result = await tool.image_transform(
+ source,
+ [{"type": "grayscale"}, {"type": "convert", "format": "jpeg"}],
+ )
+ assert result["format"] == "jpeg"
+ assert result["filename"] == "image.jpg"
+ with Image.open(result["path"]) as image:
+ assert image.mode == "RGB"
+
+
+@pytest.mark.asyncio
+async def test_convert_operation_applies_at_end(tmp_path):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source,
+ [{"type": "resize", "width": 20}, {"type": "convert", "format": "webp"}],
+ )
+ assert result["format"] == "webp"
+ assert result["mime_type"] == "image/webp"
+ assert result["filename"] == "image.webp"
+ assert Path(result["path"]).read_bytes().startswith(b"RIFF")
+
+
+@pytest.mark.asyncio
+async def test_output_format_parameter_wins_over_convert(tmp_path):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source,
+ [{"type": "convert", "format": "webp"}],
+ output_format="png",
+ )
+ assert result["format"] == "png"
+
+
+@pytest.mark.asyncio
+async def test_output_format_defaults_to_jpeg_source(tmp_path):
+ source = _save(tmp_path, "source.jpg")
+ result = await tool.image_transform(source, [{"type": "grayscale"}])
+ assert result["format"] == "jpeg"
+ assert result["mime_type"] == "image/jpeg"
+
+
+@pytest.mark.asyncio
+async def test_output_format_defaults_to_png_for_other_sources(tmp_path):
+ path = tmp_path / "source.bmp"
+ Image.new("RGB", (4, 4), (1, 2, 3)).save(path, format="BMP")
+ result = await tool.image_transform(str(path), [{"type": "grayscale"}])
+ assert result["format"] == "png"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("bad_format", ["gif", "JPG2", "", 3])
+async def test_output_format_validation(tmp_path, bad_format):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source, [{"type": "grayscale"}], output_format=bad_format
+ )
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("quality", [0, 101, True, "90"])
+async def test_quality_validation(tmp_path, quality):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source, [{"type": "grayscale"}], quality=quality
+ )
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_quality_only_affects_jpeg_and_webp(tmp_path):
+ source = _save(tmp_path, "source.png", size=(32, 32))
+ low = await tool.image_transform(
+ source, [{"type": "grayscale"}], output_format="jpeg", quality=1
+ )
+ high = await tool.image_transform(
+ source, [{"type": "grayscale"}], output_format="jpeg", quality=100
+ )
+ assert low["size_bytes"] < high["size_bytes"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "operations",
+ [
+ "not-a-list",
+ [],
+ [{"type": "grayscale"}] * 21,
+ [{"type": "unknown"}],
+ ["not-a-dict"],
+ [{"width": 10}],
+ [{"type": 3}],
+ [{"type": "convert", "format": "gif"}],
+ [{"type": "convert", "format": None}],
+ ],
+)
+async def test_operation_validation(tmp_path, operations):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(source, operations)
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_invalid_source_inputs(tmp_path):
+ assert "error" in await tool.image_transform("", [{"type": "grayscale"}])
+ assert "error" in await tool.image_transform(123, [{"type": "grayscale"}]) # type: ignore[arg-type]
+ missing = tmp_path / "missing.png"
+ assert "error" in await tool.image_transform(str(missing), [{"type": "grayscale"}])
+ assert "error" in await tool.image_transform(str(tmp_path), [{"type": "grayscale"}])
+ assert "error" in await tool.image_transform(
+ "ftp://example.com/a.png", [{"type": "grayscale"}]
+ )
+
+
+@pytest.mark.asyncio
+async def test_invalid_image_bytes(tmp_path):
+ path = tmp_path / "broken.png"
+ path.write_bytes(b"not an image")
+ result = await tool.image_transform(str(path), [{"type": "grayscale"}])
+ assert "error" in result
+ assert "decode" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_palette_transparency_becomes_rgba(tmp_path):
+ path = tmp_path / "palette.png"
+ image = Image.new("P", (4, 4), 0)
+ image.putpalette([0, 0, 0, 255, 255, 255] + [0, 0, 0] * 254)
+ image.info["transparency"] = 0
+ image.save(path, format="PNG")
+ result = await tool.image_transform(str(path), [{"type": "grayscale"}])
+ with Image.open(result["path"]) as output:
+ assert output.mode == "L"
+
+
+@pytest.mark.asyncio
+async def test_url_download_success(tmp_path, monkeypatch):
+ validated = _allow_public(monkeypatch)
+ captured = _install_http(
+ monkeypatch, [FakeResponse(content=_png_bytes(size=(8, 4)))]
+ )
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert validated == ["https://example.com/image.png"]
+ assert result["width"] == 8
+ assert result["height"] == 4
+ assert captured["client_kwargs"][0]["follow_redirects"] is False
+ assert captured["requests"][0]["headers"]["User-Agent"].startswith("VeADK")
+
+
+@pytest.mark.asyncio
+async def test_url_redirect_revalidates_each_hop(monkeypatch):
+ validated = _allow_public(monkeypatch)
+ _install_http(
+ monkeypatch,
+ [
+ FakeResponse(
+ status_code=302,
+ headers={"location": "https://cdn.example.com/image.png"},
+ is_redirect=True,
+ ),
+ FakeResponse(content=_png_bytes()),
+ ],
+ )
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "error" not in result
+ assert validated == [
+ "https://example.com/image.png",
+ "https://cdn.example.com/image.png",
+ ]
+
+
+@pytest.mark.asyncio
+async def test_url_too_many_redirects(monkeypatch):
+ _allow_public(monkeypatch)
+ redirect = FakeResponse(
+ status_code=302,
+ headers={"location": "https://example.com/next"},
+ is_redirect=True,
+ )
+ _install_http(monkeypatch, [redirect, redirect, redirect, redirect])
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "too many redirects" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_url_redirect_without_location(monkeypatch):
+ _allow_public(monkeypatch)
+ _install_http(monkeypatch, [FakeResponse(status_code=302, is_redirect=True)])
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "location" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_url_http_error(monkeypatch):
+ _allow_public(monkeypatch)
+ _install_http(monkeypatch, [FakeResponse(status_code=404)])
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "HTTP 404" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_url_declared_size_limit(monkeypatch):
+ _allow_public(monkeypatch)
+ monkeypatch.setattr(tool, "_MAX_DOWNLOAD_BYTES", 10)
+ _install_http(monkeypatch, [FakeResponse(headers={"content-length": "11"})])
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "byte limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_url_actual_size_limit(monkeypatch):
+ _allow_public(monkeypatch)
+ monkeypatch.setattr(tool, "_MAX_DOWNLOAD_BYTES", 10)
+ _install_http(monkeypatch, [FakeResponse(content=b"x" * 11)])
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "byte limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_url_invalid_content_length_falls_back(monkeypatch):
+ _allow_public(monkeypatch)
+ _install_http(
+ monkeypatch,
+ [FakeResponse(content=_png_bytes(), headers={"content-length": "abc"})],
+ )
+ result = await tool.image_transform(
+ "https://example.com/image.png", [{"type": "grayscale"}]
+ )
+ assert "error" not in result
+
+
+@pytest.mark.asyncio
+async def test_artifact_saving(tmp_path):
+ source = _save(tmp_path, "source.png", size=(6, 3))
+ context = FakeToolContext()
+ result = await tool.image_transform(
+ source,
+ [{"type": "grayscale"}],
+ filename="out!!.png",
+ tool_context=context,
+ )
+ assert result["artifact_saved"] is True
+ assert result["path"] is None
+ assert result["filename"] == "out.png"
+ assert result["mime_type"] == "image/png"
+ filename, artifact = context.saved[0]
+ assert filename == "out.png"
+ assert artifact.inline_data.mime_type == "image/png"
+ assert artifact.inline_data.display_name == "out.png"
+ assert artifact.inline_data.data.startswith(PNG_MAGIC)
+
+
+@pytest.mark.asyncio
+async def test_artifact_failure_returns_error(tmp_path):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source,
+ [{"type": "grayscale"}],
+ tool_context=FakeToolContext(fail=True),
+ )
+ assert "artifact store unavailable" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_temp_file_path_when_no_context(tmp_path):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(source, [{"type": "grayscale"}])
+ path = Path(result["path"])
+ assert result["artifact_saved"] is False
+ assert path.is_file()
+ assert path.name.endswith(".png")
+ assert path.read_bytes().startswith(PNG_MAGIC)
+ assert result["size_bytes"] == path.stat().st_size
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("filename", "output_format", "expected"),
+ [
+ ("../../evil", None, "evil.png"),
+ ("photo.jpeg", "png", "photo.png"),
+ ("my photo!!.webp", "webp", "my-photo.webp"),
+ ("", None, "image.png"),
+ (None, None, "image.png"),
+ ],
+)
+async def test_filename_sanitization(tmp_path, filename, output_format, expected):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source,
+ [{"type": "grayscale"}],
+ output_format=output_format,
+ filename=filename,
+ )
+ assert result["filename"] == expected
+
+
+@pytest.mark.asyncio
+async def test_jpg_format_alias(tmp_path):
+ source = _save(tmp_path, "source.png")
+ result = await tool.image_transform(
+ source, [{"type": "grayscale"}], output_format="jpg"
+ )
+ assert result["format"] == "jpeg"
+ assert result["filename"] == "image.jpg"
+
+
+def test_source_format_jpg_alias():
+ from types import SimpleNamespace
+
+ assert tool._detect_source_format(SimpleNamespace(format="JPG")) == "jpeg"
+
+
+@pytest.mark.asyncio
+async def test_rgb_image_saved_as_jpeg(tmp_path):
+ source = _save(tmp_path, "source.png", mode="RGB")
+ result = await tool.image_transform(
+ source, [{"type": "thumbnail", "max_size": 20}], output_format="jpeg"
+ )
+ assert result["format"] == "jpeg"
+ with Image.open(result["path"]) as image:
+ assert image.mode == "RGB"
+
+
+@pytest.mark.asyncio
+async def test_rgba_image_flattened_for_jpeg(tmp_path):
+ source = _save(
+ tmp_path, "source.png", size=(8, 8), mode="RGBA", color=(255, 0, 0, 0)
+ )
+ result = await tool.image_transform(
+ source, [{"type": "thumbnail", "max_size": 4}], output_format="jpeg"
+ )
+ assert result["format"] == "jpeg"
+ with Image.open(result["path"]) as image:
+ assert image.mode == "RGB"
+ # Transparent pixels are composited onto a white background.
+ assert image.getpixel((0, 0)) == (255, 255, 255)
diff --git a/tests/tools/builtin_tools/test_mindmap_generate.py b/tests/tools/builtin_tools/test_mindmap_generate.py
new file mode 100644
index 000000000..a30bef111
--- /dev/null
+++ b/tests/tools/builtin_tools/test_mindmap_generate.py
@@ -0,0 +1,311 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+from pathlib import Path
+
+import pytest
+
+from veadk.tools.builtin_tools import mindmap_generate as mindmap_module
+from veadk.tools.builtin_tools.mindmap_generate import (
+ _count_nodes,
+ _mermaid_label,
+ _parse_markdown,
+ _render_mermaid,
+ _render_svg,
+ _sanitize_stem,
+ _xml_escape,
+ mindmap_generate,
+)
+
+
+class SaveContext:
+ def __init__(self, fail_on: int | None = None) -> None:
+ self.artifacts: list[tuple[str, object]] = []
+ self.fail_on = fail_on
+ self.calls = 0
+
+ async def save_artifact(self, filename: str, artifact: object) -> int:
+ self.calls += 1
+ if self.fail_on == self.calls:
+ raise RuntimeError("storage unavailable")
+ self.artifacts.append((filename, artifact))
+ return len(self.artifacts)
+
+
+def _max_depth(node) -> int:
+ if not node.children:
+ return node.depth
+ return max(_max_depth(child) for child in node.children)
+
+
+# --------------------------------------------------------------------- parse --
+def test_parse_headings_and_nested_bullets() -> None:
+ markdown = "# A\n## A1\n- b1\n - b2\n - b3\n## A2\n# B\n"
+
+ root = _parse_markdown("Root", markdown)
+
+ assert root.label == "Root"
+ assert [child.label for child in root.children] == ["A", "B"]
+ a = root.children[0]
+ assert [child.label for child in a.children] == ["A1", "A2"]
+ a1 = a.children[0]
+ assert [child.label for child in a1.children] == ["b1"]
+ assert [child.label for child in a1.children[0].children] == ["b2"]
+ assert [child.label for child in a1.children[0].children[0].children] == ["b3"]
+ assert _max_depth(root) == 5
+
+
+def test_parse_bullets_before_any_heading_attach_to_root() -> None:
+ root = _parse_markdown("Root", "- one\n - two\n - three")
+ assert [child.label for child in root.children] == ["one"]
+ assert root.children[0].children[0].label == "two"
+ assert root.children[0].children[0].children[0].label == "three"
+
+
+def test_parse_ignores_blank_plain_and_empty_lines() -> None:
+ root = _parse_markdown("Root", "\nplain text\n# \n- \n* \n# Real\n")
+ assert [child.label for child in root.children] == ["Real"]
+
+
+def test_parse_heading_levels_nest() -> None:
+ root = _parse_markdown("Root", "### Deep\n# Shallow\n## Mid")
+ # A level-3 heading without a level-1 parent still nests under the root.
+ assert [child.label for child in root.children] == ["Deep", "Shallow"]
+ assert root.children[1].children[0].label == "Mid"
+
+
+def test_parse_caps_node_count() -> None:
+ markdown = "\n".join(f"- node {index}" for index in range(600))
+ root = _parse_markdown("Root", markdown)
+ assert _count_nodes(root) == 500
+
+
+def test_parse_caps_depth_at_eight() -> None:
+ lines = ["- level 0"]
+ for level in range(1, 11):
+ lines.append(" " * level + f"- level {level}")
+ root = _parse_markdown("Root", "\n".join(lines))
+ assert _max_depth(root) <= 8
+
+
+def test_parse_tabs_count_as_two_spaces() -> None:
+ root = _parse_markdown("Root", "- a\n\t- b")
+ assert root.children[0].children[0].label == "b"
+
+
+# ------------------------------------------------------------------- mermaid --
+def test_mermaid_labels_escape_structural_characters() -> None:
+ root = _parse_markdown('A (B) [C] {D} "E"', "- x(y) [z]\n- " + "long " * 30)
+ mermaid = _render_mermaid(root)
+
+ assert mermaid.splitlines()[0] == "mindmap"
+ assert mermaid.splitlines()[1] == " root((A B C D E))"
+ assert "(B)" not in mermaid
+ assert "[" not in mermaid
+ labels = [line.strip() for line in mermaid.splitlines()[2:]]
+ assert labels[0] == "x y z"
+ assert len(labels[1]) <= 80
+
+
+def test_mermaid_label_falls_back_to_dash() -> None:
+ assert _mermaid_label("()[]{}") == "-"
+
+
+def test_mermaid_indentation_tracks_depth() -> None:
+ root = _parse_markdown("Root", "# A\n## B\n- c")
+ lines = _render_mermaid(root).splitlines()
+ assert lines == [
+ "mindmap",
+ " root((Root))",
+ " A",
+ " B",
+ " c",
+ ]
+
+
+# ----------------------------------------------------------------------- svg --
+def test_svg_has_expected_structure_and_escapes_xml() -> None:
+ root = _parse_markdown(' & "Quote"', "- a & b\n - c < d")
+ svg = _render_svg(root)
+
+ assert svg.startswith('')
+ assert 'xmlns="http://www.w3.org/2000/svg"' in svg
+ assert 'fill="#ffffff"' in svg
+ assert 'rx="8"' in svg
+ assert "" not in svg
+ assert "a & b" in svg
+ assert "c < d" in svg
+ assert svg.endswith("")
+
+
+def test_svg_is_deterministic_and_grows_with_content() -> None:
+ small = _render_svg(_parse_markdown("Root", ""))
+ large = _render_svg(
+ _parse_markdown("Root", "\n".join(f"- node {i}" for i in range(20)))
+ )
+ assert small == _render_svg(_parse_markdown("Root", ""))
+
+ def width(svg: str) -> int:
+ return int(re.search(r'width="(\d+)"', svg).group(1))
+
+ assert width(large) > width(small)
+ assert 'height="' in large
+
+
+def test_xml_escape_removes_control_characters() -> None:
+ assert _xml_escape("a\x00b\x07c") == "abc"
+
+
+# ------------------------------------------------------------------- filename --
+@pytest.mark.parametrize(
+ ("filename", "expected"),
+ [
+ (None, "mindmap"),
+ ("", "mindmap"),
+ (" ", "mindmap"),
+ (123, "mindmap"),
+ ("../../evil mind", "evil-mind"),
+ ("My Chart.mmd", "My-Chart"),
+ ("diagram.svg", "diagram"),
+ ("报告 final", "报告-final"),
+ ("C:\\tmp\\chart", "chart"),
+ (".hidden", "hidden"),
+ ],
+)
+def test_sanitize_stem(filename: object, expected: str) -> None:
+ assert _sanitize_stem(filename) == expected
+
+
+# ---------------------------------------------------------------- generation --
+@pytest.mark.asyncio
+async def test_empty_markdown_creates_root_only_mindmap() -> None:
+ result = await mindmap_generate("Root", "", tool_context=None)
+
+ assert result["title"] == "Root"
+ assert result["nodes"] == 1
+ assert result["mermaid"] == "mindmap\n root((Root))"
+ assert result["artifact_saved"] is False
+ assert result["mmd_filename"] == "mindmap.mmd"
+ assert result["svg_filename"] == "mindmap.svg"
+ assert Path(result["mmd_path"]).read_text(encoding="utf-8") == result["mermaid"]
+ assert Path(result["svg_path"]).read_text(encoding="utf-8").startswith(" None:
+ result = await mindmap_generate("", "- child", tool_context=None)
+ assert result["title"] == "Mindmap"
+ assert result["nodes"] == 2
+
+
+@pytest.mark.asyncio
+async def test_generation_counts_nodes_and_uses_custom_filename() -> None:
+ result = await mindmap_generate(
+ "Plan",
+ "# Phase 1\n- a\n- b\n# Phase 2",
+ filename="../../my plan.mmd",
+ tool_context=None,
+ )
+
+ assert result["nodes"] == 5
+ assert result["mmd_filename"] == "my-plan.mmd"
+ assert result["svg_filename"] == "my-plan.svg"
+ assert Path(result["mmd_path"]).name == "my-plan.mmd"
+ assert Path(result["svg_path"]).name == "my-plan.svg"
+ assert "Phase 1" in result["mermaid"]
+
+
+@pytest.mark.asyncio
+async def test_non_string_arguments_are_coerced() -> None:
+ result = await mindmap_generate(123, None, tool_context=None) # type: ignore[arg-type]
+ assert result["title"] == "123"
+ assert result["nodes"] == 1
+
+
+@pytest.mark.asyncio
+async def test_saves_mmd_and_svg_artifacts() -> None:
+ context = SaveContext()
+
+ result = await mindmap_generate(
+ "Root",
+ "- child",
+ filename="map",
+ tool_context=context, # type: ignore[arg-type]
+ )
+
+ assert result["artifact_saved"] is True
+ assert result["mmd_path"] is None
+ assert result["svg_path"] is None
+ assert [name for name, _ in context.artifacts] == ["map.mmd", "map.svg"]
+ mmd = context.artifacts[0][1]
+ svg = context.artifacts[1][1]
+ assert mmd.inline_data.mime_type == "text/plain"
+ assert mmd.inline_data.display_name == "map.mmd"
+ assert mmd.inline_data.data == result["mermaid"].encode("utf-8")
+ assert svg.inline_data.mime_type == "image/svg+xml"
+ assert svg.inline_data.display_name == "map.svg"
+ assert svg.inline_data.data.decode("utf-8").startswith(" None:
+ result = await mindmap_generate(
+ "Root",
+ "- child",
+ tool_context=SaveContext(fail_on=1), # type: ignore[arg-type]
+ )
+ assert "error" in result
+ assert "failed to save artifact" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_artifact_failure_on_second_save_returns_error() -> None:
+ context = SaveContext(fail_on=2)
+ result = await mindmap_generate(
+ "Root",
+ "- child",
+ tool_context=context, # type: ignore[arg-type]
+ )
+ assert "failed to save artifact" in result["error"]
+ assert context.calls == 2
+ assert len(context.artifacts) == 1
+
+
+@pytest.mark.asyncio
+async def test_temp_dir_write_failure_returns_error(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ blocker = tmp_path / "not-a-directory"
+ blocker.write_text("x", encoding="utf-8")
+ monkeypatch.setattr(
+ mindmap_module.tempfile, "mkdtemp", lambda **kwargs: str(blocker)
+ )
+
+ result = await mindmap_generate("Root", "- child", tool_context=None)
+
+ assert "error" in result
+ assert "failed to write files" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_mermaid_escapes_title_in_generated_output() -> None:
+ result = await mindmap_generate("A (B)", "- c [d]", tool_context=None)
+ assert result["mermaid"] == "mindmap\n root((A B))\n c d"
+ assert "(B)" not in result["mermaid"]
diff --git a/tests/tools/builtin_tools/test_qrcode_generate.py b/tests/tools/builtin_tools/test_qrcode_generate.py
new file mode 100644
index 000000000..ce0ea4423
--- /dev/null
+++ b/tests/tools/builtin_tools/test_qrcode_generate.py
@@ -0,0 +1,155 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the ``qrcode_generate`` built-in tool."""
+
+import inspect
+from io import BytesIO
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from veadk.tools.builtin_tools import qrcode_generate as tool
+
+PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+
+
+class FakeToolContext:
+ def __init__(self, fail: bool = False) -> None:
+ self.fail = fail
+ self.saved: list[tuple[str, object]] = []
+
+ async def save_artifact(self, filename: str, artifact: object) -> int:
+ if self.fail:
+ raise RuntimeError("artifact store unavailable")
+ self.saved.append((filename, artifact))
+ return 1
+
+
+def test_signature_and_defaults():
+ params = inspect.signature(tool.qrcode_generate).parameters
+ assert list(params) == [
+ "content",
+ "filename",
+ "box_size",
+ "border",
+ "fill_color",
+ "back_color",
+ "tool_context",
+ ]
+ assert params["filename"].default == "qrcode.png"
+ assert params["box_size"].default == 10
+ assert params["border"].default == 4
+ assert params["fill_color"].default == "black"
+ assert params["back_color"].default == "white"
+ assert params["tool_context"].default is None
+
+
+@pytest.mark.asyncio
+async def test_generates_real_png_temp_file():
+ result = await tool.qrcode_generate("hello world", box_size=2, border=1)
+ path = Path(result["path"])
+ assert result["artifact_saved"] is False
+ assert result["format"] == "png"
+ assert result["mime_type"] == "image/png"
+ assert result["filename"] == "qrcode.png"
+ assert path.is_file()
+ data = path.read_bytes()
+ assert data.startswith(PNG_MAGIC)
+ assert result["size_bytes"] == len(data)
+ with Image.open(BytesIO(data)) as image:
+ assert image.format == "PNG"
+ assert image.size == (result["width"], result["height"])
+ assert result["width"] == result["height"]
+ assert result["width"] > 2 * 1 * 2 + 2 * 2
+
+
+@pytest.mark.asyncio
+async def test_custom_colors_and_dimensions():
+ result = await tool.qrcode_generate(
+ "https://example.com",
+ box_size=5,
+ border=2,
+ fill_color="#102030",
+ back_color="#ffffff",
+ )
+ assert "error" not in result
+ with Image.open(result["path"]) as image:
+ assert image.size == (result["width"], result["height"])
+
+
+@pytest.mark.asyncio
+async def test_artifact_saving():
+ context = FakeToolContext()
+ result = await tool.qrcode_generate(
+ "artifact payload", filename="My Code!!.jpg", tool_context=context
+ )
+ assert result["artifact_saved"] is True
+ assert result["path"] is None
+ assert result["filename"] == "My-Code.png"
+ filename, artifact = context.saved[0]
+ assert filename == "My-Code.png"
+ assert artifact.inline_data.mime_type == "image/png"
+ assert artifact.inline_data.display_name == "My-Code.png"
+ assert artifact.inline_data.data.startswith(PNG_MAGIC)
+
+
+@pytest.mark.asyncio
+async def test_artifact_failure_returns_error():
+ result = await tool.qrcode_generate(
+ "payload", tool_context=FakeToolContext(fail=True)
+ )
+ assert "artifact store unavailable" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("kwargs", "fragment"),
+ [
+ ({"content": ""}, "content"),
+ ({"content": " "}, "content"),
+ ({"content": 123}, "content"),
+ ({"content": "x" * 2001}, "2000"),
+ ({"content": "x", "box_size": 0}, "box_size"),
+ ({"content": "x", "box_size": 51}, "box_size"),
+ ({"content": "x", "box_size": 1.5}, "box_size"),
+ ({"content": "x", "box_size": True}, "box_size"),
+ ({"content": "x", "border": -1}, "border"),
+ ({"content": "x", "border": 21}, "border"),
+ ({"content": "x", "border": True}, "border"),
+ ({"content": "x", "fill_color": 5}, "fill_color"),
+ ({"content": "x", "back_color": None}, "back_color"),
+ ({"content": "x", "fill_color": "notacolor"}, "color"),
+ ],
+)
+async def test_validation_errors(kwargs, fragment):
+ result = await tool.qrcode_generate(**kwargs)
+ assert "error" in result
+ assert fragment.lower() in result["error"].lower()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("filename", "expected"),
+ [
+ ("../../code", "code.png"),
+ ("code.jpg", "code.png"),
+ ("", "qrcode.png"),
+ ("code", "code.png"),
+ ],
+)
+async def test_filename_sanitization(filename, expected):
+ result = await tool.qrcode_generate("payload", filename=filename)
+ assert result["filename"] == expected
diff --git a/tests/tools/builtin_tools/test_speech_to_text.py b/tests/tools/builtin_tools/test_speech_to_text.py
new file mode 100644
index 000000000..d148ef89a
--- /dev/null
+++ b/tests/tools/builtin_tools/test_speech_to_text.py
@@ -0,0 +1,310 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base64
+import inspect
+
+import httpx
+import pytest
+
+from veadk.tools.builtin_tools import speech_to_text as stt_module
+from veadk.tools.builtin_tools.speech_to_text import speech_to_text
+
+
+class _FakeClient:
+ def __init__(self, response=None, error=None):
+ self.response = response
+ self.error = error
+ self.calls = []
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ return False
+
+ async def post(self, url, headers=None, json=None):
+ self.calls.append({"url": url, "headers": headers, "json": json})
+ if self.error:
+ raise self.error
+ return self.response
+
+
+def _patch_client(monkeypatch, response=None, error=None):
+ fake = _FakeClient(response=response, error=error)
+ monkeypatch.setattr(stt_module.httpx, "AsyncClient", lambda *a, **kw: fake)
+ return fake
+
+
+def _success_response(text="hello", utterances=None, duration=1200):
+ return httpx.Response(
+ 200,
+ headers={"X-Api-Status-Code": "20000000", "X-Tt-Logid": "log-1"},
+ json={
+ "audio_info": {"duration": duration},
+ "result": {
+ "text": text,
+ "utterances": utterances
+ if utterances is not None
+ else [
+ {
+ "start_time": 0,
+ "end_time": 500,
+ "text": "hello",
+ "words": [{"text": "hello"}],
+ }
+ ],
+ },
+ },
+ )
+
+
+def test_signature():
+ sig = inspect.signature(speech_to_text)
+ assert list(sig.parameters) == ["audio", "timeout"]
+ assert sig.parameters["timeout"].default == 300
+
+
+@pytest.mark.asyncio
+async def test_missing_api_key(monkeypatch):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "")
+ result = await speech_to_text("a.wav")
+ assert "TOOL_SPEECH_TO_TEXT_API_KEY" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("audio", ["", None, 123])
+async def test_invalid_audio(monkeypatch, audio):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ result = await speech_to_text(audio)
+ assert result == {"error": "audio must be a non-empty path or URL"}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("timeout", [0, 601, 1.5, True, "30"])
+async def test_invalid_timeout(monkeypatch, timeout):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ result = await speech_to_text("a.wav", timeout=timeout)
+ assert result == {"error": "timeout must be an integer between 1 and 600 seconds"}
+
+
+@pytest.mark.asyncio
+async def test_missing_file(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ result = await speech_to_text(str(tmp_path / "missing.wav"))
+ assert "does not exist" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_unsupported_suffix(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.flac"
+ path.write_bytes(b"data")
+ result = await speech_to_text(str(path))
+ assert "unsupported audio format" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_empty_file(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.mp3"
+ path.touch()
+ result = await speech_to_text(str(path))
+ assert "empty" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_file_too_large(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ monkeypatch.setattr(stt_module, "_MAX_AUDIO_BYTES", 2)
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"12345")
+ result = await speech_to_text(str(path))
+ assert "100 MB" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_local_file_success(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"audio-bytes")
+ fake = _patch_client(monkeypatch, response=_success_response("hi there"))
+
+ result = await speech_to_text(str(path))
+
+ assert result["text"] == "hi there"
+ assert result["duration_ms"] == 1200
+ assert result["log_id"] == "log-1"
+ assert result["utterances"] == [{"start_time": 0, "end_time": 500, "text": "hello"}]
+ sent = fake.calls[0]
+ assert sent["url"] == stt_module._ENDPOINT
+ assert sent["headers"]["X-Api-Key"] == "key"
+ assert sent["headers"]["X-Api-Resource-Id"] == "volc.bigasr.auc_turbo"
+ assert sent["headers"]["X-Api-Sequence"] == "-1"
+ assert base64.b64decode(sent["json"]["audio"]["data"]) == b"audio-bytes"
+ assert sent["json"]["request"]["model_name"] == "bigmodel"
+
+
+@pytest.mark.asyncio
+async def test_non_object_utterance_is_skipped(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"audio-bytes")
+ _patch_client(
+ monkeypatch,
+ response=_success_response("hi", utterances=["not-a-dict", {"text": "ok"}]),
+ )
+
+ result = await speech_to_text(str(path))
+
+ assert result["utterances"] == [
+ {"start_time": None, "end_time": None, "text": "ok"}
+ ]
+
+
+@pytest.mark.asyncio
+async def test_url_success(monkeypatch):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ monkeypatch.setattr(stt_module, "assert_public_url", lambda url: "example.com")
+ fake = _patch_client(monkeypatch, response=_success_response("remote"))
+
+ result = await speech_to_text("https://example.com/a.mp3")
+
+ assert result["text"] == "remote"
+ assert fake.calls[0]["json"]["audio"] == {"url": "https://example.com/a.mp3"}
+
+
+@pytest.mark.asyncio
+async def test_url_rejected(monkeypatch):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+
+ def reject(_url):
+ raise ValueError("Blocked non-public address")
+
+ monkeypatch.setattr(stt_module, "assert_public_url", reject)
+ result = await speech_to_text("http://127.0.0.1/a.mp3")
+ assert "Blocked non-public address" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("status", "message", "expected"),
+ [
+ ("20000003", None, "no speech"),
+ ("45000001", None, "invalid request parameters"),
+ ("45000002", None, "empty"),
+ ("45000151", None, "unsupported audio format"),
+ ("55000031", None, "busy"),
+ ("99999999", "custom failure", "custom failure"),
+ ("", None, "HTTP 400"),
+ ],
+)
+async def test_error_status(monkeypatch, tmp_path, status, message, expected):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"x")
+ headers = {"X-Tt-Logid": "log-err"}
+ if status:
+ headers["X-Api-Status-Code"] = status
+ if message:
+ headers["X-Api-Message"] = message
+ _patch_client(monkeypatch, response=httpx.Response(400, headers=headers))
+
+ result = await speech_to_text(str(path))
+
+ assert expected in result["error"]
+ assert result["log_id"] == "log-err"
+
+
+@pytest.mark.asyncio
+async def test_invalid_json(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"x")
+ _patch_client(
+ monkeypatch,
+ response=httpx.Response(
+ 200,
+ headers={"X-Api-Status-Code": "20000000", "X-Tt-Logid": "log"},
+ content=b"not-json",
+ ),
+ )
+ result = await speech_to_text(str(path))
+ assert "invalid ASR response" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_http_error_without_status_header(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"x")
+ _patch_client(monkeypatch, response=httpx.Response(500))
+ result = await speech_to_text(str(path))
+ assert "HTTP 500" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_transport_error(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"x")
+ _patch_client(monkeypatch, error=httpx.ConnectError("boom"))
+ result = await speech_to_text(str(path))
+ assert "ASR request failed" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_response_with_unexpected_shapes(monkeypatch, tmp_path):
+ monkeypatch.setattr(stt_module, "_resolve_api_key", lambda: "key")
+ path = tmp_path / "audio.wav"
+ path.write_bytes(b"x")
+ _patch_client(
+ monkeypatch,
+ response=httpx.Response(
+ 200,
+ headers={"X-Api-Status-Code": "20000000"},
+ json=["unexpected"],
+ ),
+ )
+ result = await speech_to_text(str(path))
+ assert result["text"] == ""
+ assert result["utterances"] == []
+ assert result["duration_ms"] is None
+
+
+def test_resolve_api_key_env(monkeypatch):
+ monkeypatch.setenv("TOOL_SPEECH_TO_TEXT_API_KEY", "primary")
+ monkeypatch.setenv("TOOL_VESPEECH_API_KEY", "fallback")
+ assert stt_module._resolve_api_key() == "primary"
+
+
+def test_resolve_api_key_falls_back(monkeypatch):
+ monkeypatch.delenv("TOOL_SPEECH_TO_TEXT_API_KEY", raising=False)
+ monkeypatch.setenv("TOOL_VESPEECH_API_KEY", "fallback")
+ assert stt_module._resolve_api_key() == "fallback"
+
+
+def test_resolve_api_key_settings_failure(monkeypatch):
+ monkeypatch.delenv("TOOL_SPEECH_TO_TEXT_API_KEY", raising=False)
+ monkeypatch.delenv("TOOL_VESPEECH_API_KEY", raising=False)
+
+ class Broken:
+ @property
+ def api_key(self):
+ raise RuntimeError("no credentials")
+
+ monkeypatch.setattr(
+ stt_module.settings, "tool", type("Tool", (), {"vespeech": Broken()})()
+ )
+ assert stt_module._resolve_api_key() == ""
diff --git a/tests/tools/builtin_tools/test_vision_tools.py b/tests/tools/builtin_tools/test_vision_tools.py
new file mode 100644
index 000000000..e1710dcd3
--- /dev/null
+++ b/tests/tools/builtin_tools/test_vision_tools.py
@@ -0,0 +1,608 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hermetic tests for the shared vision helper and its tools."""
+
+import base64
+import inspect
+import socket
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from PIL import Image
+
+from veadk.tools.builtin_tools import image_understand as understand_tool
+from veadk.tools.builtin_tools import ocr as ocr_tool
+from veadk.tools.builtin_tools import vision
+
+_PUBLIC_IP = "93.184.216.34"
+
+
+def _addrinfo(ip: str) -> list:
+ return [(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP, "", (ip, 0))]
+
+
+@pytest.fixture(autouse=True)
+def _hermetic_dns(monkeypatch):
+ # Remote image URLs now pass through the shared SSRF guard, which resolves
+ # the host; keep tests off the network.
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo",
+ lambda *args, **kwargs: _addrinfo(_PUBLIC_IP),
+ )
+
+
+def _fake_settings(
+ monkeypatch,
+ *,
+ api_key="settings-key",
+ name="vision-model",
+ base_url="https://api.example.com/v1",
+):
+ monkeypatch.delenv("MODEL_AGENT_API_KEY", raising=False)
+ monkeypatch.delenv("MODEL_VISION_NAME", raising=False)
+ fake = SimpleNamespace(
+ model=SimpleNamespace(name=name, api_base=base_url, api_key=api_key)
+ )
+ monkeypatch.setattr(vision, "settings", fake)
+ return fake
+
+
+class FakeResponse:
+ def __init__(self, status_code=200, payload=None, json_error=None):
+ self.status_code = status_code
+ self.payload = payload
+ self.json_error = json_error
+
+ def json(self):
+ if self.json_error is not None:
+ raise self.json_error
+ return self.payload
+
+
+def _install_client(monkeypatch, response=None, error=None):
+ captured = {}
+
+ class FakeClient:
+ def __init__(self, timeout=None):
+ captured["timeout"] = timeout
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc_info):
+ return False
+
+ async def post(self, url, headers=None, json=None):
+ captured["url"] = url
+ captured["headers"] = headers
+ captured["json"] = json
+ if error is not None:
+ raise error
+ return response
+
+ monkeypatch.setattr(vision.httpx, "AsyncClient", FakeClient)
+ return captured
+
+
+def _chat_payload(content):
+ return {"choices": [{"message": {"content": content}}]}
+
+
+def _png_bytes(path):
+ Image.new("RGB", (3, 2), (10, 20, 30)).save(path, format="PNG")
+ return path
+
+
+def test_analyze_images_signature_and_defaults():
+ params = inspect.signature(vision.analyze_images).parameters
+ assert list(params) == ["images", "prompt", "model_name", "timeout"]
+ assert params["model_name"].default is None
+ assert params["timeout"].default == 60
+
+
+@pytest.mark.asyncio
+async def test_success_with_string_content(monkeypatch):
+ _fake_settings(monkeypatch)
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(
+ ["https://example.com/a.png"], "What is this?", timeout=42
+ )
+ assert result == {"text": "ok", "model": "vision-model"}
+ assert captured["url"] == "https://api.example.com/v1/chat/completions"
+ assert captured["headers"]["Authorization"] == "Bearer settings-key"
+ assert captured["timeout"] == 42
+ body = captured["json"]
+ assert body["model"] == "vision-model"
+ assert body["messages"][0]["role"] == "user"
+ content = body["messages"][0]["content"]
+ assert content[0] == {"type": "text", "text": "What is this?"}
+ assert content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "https://example.com/a.png"},
+ }
+
+
+@pytest.mark.asyncio
+async def test_success_with_list_content_parts(monkeypatch):
+ _fake_settings(monkeypatch, base_url="https://api.example.com/v1/")
+ _install_client(
+ monkeypatch,
+ FakeResponse(
+ payload=_chat_payload(
+ [
+ {"type": "text", "text": "Hello "},
+ {"type": "text", "text": "world"},
+ {"type": "image_url", "image_url": {"url": "x"}},
+ "not-a-dict",
+ {"text": 5},
+ ]
+ )
+ ),
+ )
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert result == {"text": "Hello world", "model": "vision-model"}
+
+
+@pytest.mark.asyncio
+async def test_local_image_is_base64_encoded(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ path = _png_bytes(tmp_path / "local.png")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images([str(path)], "prompt")
+ assert result == {"text": "ok", "model": "vision-model"}
+ data_url = captured["json"]["messages"][0]["content"][1]["image_url"]["url"]
+ assert data_url.startswith("data:image/png;base64,")
+ decoded = base64.b64decode(data_url.split(",", 1)[1])
+ assert decoded == path.read_bytes()
+
+
+@pytest.mark.asyncio
+async def test_local_jpeg_mime_from_pillow(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ path = tmp_path / "photo.jpg"
+ Image.new("RGB", (2, 2), (0, 0, 0)).save(path, format="JPEG")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ await vision.analyze_images([str(path)], "prompt")
+ data_url = captured["json"]["messages"][0]["content"][1]["image_url"]["url"]
+ assert data_url.startswith("data:image/jpeg;base64,")
+
+
+@pytest.mark.asyncio
+async def test_filetype_fallback(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ path = _png_bytes(tmp_path / "image.bin")
+ monkeypatch.setattr(
+ vision.Image, "open", lambda *args, **kwargs: (_ for _ in ()).throw(OSError())
+ )
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ await vision.analyze_images([str(path)], "prompt")
+ data_url = captured["json"]["messages"][0]["content"][1]["image_url"]["url"]
+ assert data_url.startswith("data:image/png;base64,")
+
+
+@pytest.mark.asyncio
+async def test_extension_fallback(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ path = tmp_path / "image.webp"
+ path.write_bytes(b"not-really-an-image")
+ monkeypatch.setattr(
+ vision.Image, "open", lambda *args, **kwargs: (_ for _ in ()).throw(OSError())
+ )
+ monkeypatch.setattr(vision.filetype, "guess", lambda data: None)
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ await vision.analyze_images([str(path)], "prompt")
+ data_url = captured["json"]["messages"][0]["content"][1]["image_url"]["url"]
+ assert data_url.startswith("data:image/webp;base64,")
+
+
+@pytest.mark.asyncio
+async def test_octet_stream_fallback(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ path = tmp_path / "image.bin"
+ path.write_bytes(b"not-an-image")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ await vision.analyze_images([str(path)], "prompt")
+ data_url = captured["json"]["messages"][0]["content"][1]["image_url"]["url"]
+ assert data_url.startswith("data:application/octet-stream;base64,")
+
+
+@pytest.mark.asyncio
+async def test_model_name_override(monkeypatch):
+ _fake_settings(monkeypatch)
+ monkeypatch.setenv("MODEL_VISION_NAME", "env-model")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(
+ ["https://example.com/a.png"], "prompt", model_name="explicit-model"
+ )
+ assert result["model"] == "explicit-model"
+ assert captured["json"]["model"] == "explicit-model"
+
+
+@pytest.mark.asyncio
+async def test_model_name_from_environment(monkeypatch):
+ _fake_settings(monkeypatch)
+ monkeypatch.setenv("MODEL_VISION_NAME", "env-model")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert result["model"] == "env-model"
+ assert captured["json"]["model"] == "env-model"
+
+
+@pytest.mark.asyncio
+async def test_missing_model_name(monkeypatch):
+ _fake_settings(monkeypatch, name="")
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "model name" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_api_key_from_environment(monkeypatch):
+ _fake_settings(monkeypatch, api_key="settings-key")
+ monkeypatch.setenv("MODEL_AGENT_API_KEY", "env-key")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert captured["headers"]["Authorization"] == "Bearer env-key"
+
+
+@pytest.mark.asyncio
+async def test_missing_api_key(monkeypatch):
+ _fake_settings(monkeypatch, api_key="")
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "API key" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_missing_api_base(monkeypatch):
+ _fake_settings(monkeypatch, base_url="")
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "API base" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_http_error_includes_status_but_not_key(monkeypatch):
+ _fake_settings(monkeypatch, api_key="super-secret-value")
+ _install_client(monkeypatch, FakeResponse(status_code=429))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "429" in result["error"]
+ assert "super-secret-value" not in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_http_error_includes_provider_message(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(
+ monkeypatch,
+ FakeResponse(
+ status_code=400,
+ payload={
+ "error": {
+ "code": "InvalidEndpoint.ClosedEndpoint",
+ "message": "The request targeted an endpoint that is closed.",
+ }
+ },
+ ),
+ )
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "HTTP status 400" in result["error"]
+ assert "endpoint that is closed" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_http_error_falls_back_to_provider_code(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(
+ monkeypatch,
+ FakeResponse(status_code=500, payload={"error": {"code": "InternalError"}}),
+ )
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "HTTP status 500: InternalError" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ ("payload", "expected"),
+ [
+ ({"error": "plain failure"}, "HTTP status 503: plain failure"),
+ ({"message": "top-level failure"}, "HTTP status 503: top-level failure"),
+ ({"error": {"message": 42}}, "HTTP status 503"),
+ (["unexpected"], "HTTP status 503"),
+ ],
+)
+async def test_http_error_detail_variants(monkeypatch, payload, expected):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(status_code=503, payload=payload))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert result["error"] == f"vision request failed with {expected}"
+
+
+@pytest.mark.asyncio
+async def test_http_error_with_non_json_body(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(
+ monkeypatch,
+ FakeResponse(status_code=502, json_error=ValueError("not json")),
+ )
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert result["error"] == "vision request failed with HTTP status 502"
+
+
+@pytest.mark.asyncio
+async def test_http_error_detail_is_truncated(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(
+ monkeypatch,
+ FakeResponse(status_code=400, payload={"message": "x" * 500}),
+ )
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert result["error"].endswith("x" * vision._ERROR_DETAIL_LIMIT)
+ assert (
+ len(result["error"])
+ == len("vision request failed with HTTP status 400: ")
+ + vision._ERROR_DETAIL_LIMIT
+ )
+
+
+@pytest.mark.asyncio
+async def test_invalid_json_response(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(json_error=ValueError("not json")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "not valid JSON" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "payload",
+ [
+ [],
+ {},
+ {"choices": []},
+ {"choices": ["bad"]},
+ {"choices": [{}]},
+ {"choices": [{"message": "bad"}]},
+ {"choices": [{"message": {"content": None}}]},
+ {"choices": [{"message": {"content": 123}}]},
+ ],
+)
+async def test_unparseable_response(monkeypatch, payload):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(payload=payload))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "did not contain text content" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_transport_error(monkeypatch):
+ _fake_settings(monkeypatch, api_key="secret")
+ _install_client(monkeypatch, error=httpx.ConnectError("connection reset"))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "vision request failed" in result["error"]
+ assert "secret" not in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_unexpected_response_error(monkeypatch):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(json_error=RuntimeError("weird")))
+ result = await vision.analyze_images(["https://example.com/a.png"], "prompt")
+ assert "vision request failed" in result["error"]
+ assert "RuntimeError" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "overrides",
+ [
+ {"images": "not-a-list"},
+ {"images": []},
+ {"images": ["u"] * 9},
+ {"images": [123]},
+ {"images": [""]},
+ {"prompt": ""},
+ {"prompt": 5},
+ {"timeout": 0},
+ {"timeout": 301},
+ {"timeout": True},
+ {"timeout": "60"},
+ ],
+)
+async def test_validation_errors(monkeypatch, overrides):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ arguments = {
+ "images": ["https://example.com/a.png"],
+ "prompt": "prompt",
+ "timeout": 60,
+ }
+ arguments.update(overrides)
+ result = await vision.analyze_images(**arguments)
+ assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_missing_local_image(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images([str(tmp_path / "missing.png")], "prompt")
+ assert "does not exist" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_remote_image_internal_address_is_rejected(monkeypatch):
+ _fake_settings(monkeypatch)
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo",
+ lambda *args, **kwargs: _addrinfo("169.254.169.254"),
+ )
+ result = await vision.analyze_images(
+ ["http://169.254.169.254/latest/meta-data/"], "prompt"
+ )
+ assert "error" in result
+ assert "non-public" in result["error"] or "Blocked" in result["error"]
+ # The provider must never be asked to fetch the internal URL.
+ assert "json" not in captured
+
+
+@pytest.mark.asyncio
+async def test_remote_image_loopback_is_rejected(monkeypatch):
+ _fake_settings(monkeypatch)
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ monkeypatch.setattr(
+ "veadk.tools.builtin_tools.web_fetch.socket.getaddrinfo",
+ lambda *args, **kwargs: _addrinfo("127.0.0.1"),
+ )
+ result = await vision.analyze_images(["http://127.0.0.1/secret.png"], "prompt")
+ assert "error" in result
+ assert "json" not in captured
+
+
+@pytest.mark.asyncio
+async def test_local_image_size_limit(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ monkeypatch.setattr(vision, "_MAX_IMAGE_BYTES", 4)
+ path = tmp_path / "big.png"
+ path.write_bytes(b"12345")
+ _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+ result = await vision.analyze_images([str(path)], "prompt")
+ assert "byte limit" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_local_images_share_an_aggregate_size_limit(monkeypatch, tmp_path):
+ _fake_settings(monkeypatch)
+ monkeypatch.setattr(vision, "_MAX_TOTAL_IMAGE_BYTES", 4)
+ first = tmp_path / "one.png"
+ second = tmp_path / "two.png"
+ first.write_bytes(b"abc")
+ second.write_bytes(b"def")
+ captured = _install_client(monkeypatch, FakeResponse(payload=_chat_payload("ok")))
+
+ result = await vision.analyze_images([str(first), str(second)], "prompt")
+
+ assert "total limit" in result["error"]
+ assert "json" not in captured
+
+
+def test_image_understand_signature_and_defaults():
+ params = inspect.signature(understand_tool.image_understand).parameters
+ assert list(params) == ["images", "prompt", "model_name"]
+ assert params["prompt"].default == "Describe the image in detail."
+ assert params["model_name"].default is None
+
+
+@pytest.mark.asyncio
+async def test_image_understand_delegates_with_default_prompt(monkeypatch):
+ captured = {}
+
+ async def fake_analyze(images, prompt, model_name=None):
+ captured["args"] = (images, prompt, model_name)
+ return {"text": "description", "model": "m"}
+
+ monkeypatch.setattr(understand_tool, "analyze_images", fake_analyze)
+ result = await understand_tool.image_understand(["https://example.com/a.png"])
+ assert result == {"text": "description", "model": "m"}
+ assert captured["args"] == (
+ ["https://example.com/a.png"],
+ "Describe the image in detail.",
+ None,
+ )
+
+
+@pytest.mark.asyncio
+async def test_image_understand_passes_overrides(monkeypatch):
+ captured = {}
+
+ async def fake_analyze(images, prompt, model_name=None):
+ captured["args"] = (images, prompt, model_name)
+ return {"error": "nope"}
+
+ monkeypatch.setattr(understand_tool, "analyze_images", fake_analyze)
+ result = await understand_tool.image_understand(
+ ["local.png"], "custom prompt", "custom-model"
+ )
+ assert result == {"error": "nope"}
+ assert captured["args"] == (["local.png"], "custom prompt", "custom-model")
+
+
+def test_ocr_signature_and_defaults():
+ params = inspect.signature(ocr_tool.ocr).parameters
+ assert list(params) == ["image", "language", "model_name"]
+ assert params["language"].default == "auto"
+ assert params["model_name"].default is None
+
+
+@pytest.mark.asyncio
+async def test_ocr_auto_language(monkeypatch):
+ captured = {}
+
+ async def fake_analyze(images, prompt, model_name=None):
+ captured["args"] = (images, prompt, model_name)
+ return {"text": "line one\nline two", "model": "m"}
+
+ monkeypatch.setattr(ocr_tool, "analyze_images", fake_analyze)
+ result = await ocr_tool.ocr("page.png")
+ assert result == {
+ "text": "line one\nline two",
+ "language": "auto",
+ "model": "m",
+ }
+ assert captured["args"][0] == ["page.png"]
+ assert "Transcribe all text" in captured["args"][1]
+ assert "preserving line breaks" in captured["args"][1]
+ assert "expected to be in" not in captured["args"][1]
+
+
+@pytest.mark.asyncio
+async def test_ocr_requested_language(monkeypatch):
+ captured = {}
+
+ async def fake_analyze(images, prompt, model_name=None):
+ captured["prompt"] = prompt
+ return {"text": "", "model": "m"}
+
+ monkeypatch.setattr(ocr_tool, "analyze_images", fake_analyze)
+ result = await ocr_tool.ocr("page.png", language="Chinese", model_name="vision")
+ assert result == {"text": "", "language": "Chinese", "model": "m"}
+ assert "expected to be in Chinese" in captured["prompt"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("language", ["auto", "AUTO", None])
+async def test_ocr_auto_variants(monkeypatch, language):
+ captured = {}
+
+ async def fake_analyze(images, prompt, model_name=None):
+ captured["prompt"] = prompt
+ return {"text": "x", "model": "m"}
+
+ monkeypatch.setattr(ocr_tool, "analyze_images", fake_analyze)
+ result = await ocr_tool.ocr("page.png", language=language)
+ assert result["language"] == language
+ assert "expected to be in" not in captured["prompt"]
+
+
+@pytest.mark.asyncio
+async def test_ocr_error_passthrough(monkeypatch):
+ async def fake_analyze(images, prompt, model_name=None):
+ return {"error": "boom"}
+
+ monkeypatch.setattr(ocr_tool, "analyze_images", fake_analyze)
+ result = await ocr_tool.ocr("page.png")
+ assert result == {"error": "boom"}
diff --git a/tests/tools/test_builtin_registry_contract.py b/tests/tools/test_builtin_registry_contract.py
index 17ace4dbf..18c518b45 100644
--- a/tests/tools/test_builtin_registry_contract.py
+++ b/tests/tools/test_builtin_registry_contract.py
@@ -42,6 +42,17 @@
"video_task_query",
"ppt_generate",
"text_to_speech",
+ "speech_to_text",
+ "image_transform",
+ "image_understand",
+ "ocr",
+ "http_request",
+ "document_parse",
+ "doc_generate",
+ "mindmap_generate",
+ "qrcode_generate",
+ "calculator",
+ "datetime",
}
diff --git a/uv.lock b/uv.lock
index 807cb0be4..126a48fb4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4519,6 +4519,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/43/5e/21abf578182fb15006a57faf3711a1e659e29d600d19b6e557eae908c81d/python_discovery-1.6.0-py3-none-any.whl", hash = "sha256:d4e244cf17b8b29819ed78003d55fbacf86eda23425b075454fff9271b79377a", size = 38451, upload-time = "2026-08-28T17:30:01.236Z" },
]
+[[package]]
+name = "python-docx"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "lxml" },
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/f7/eddfe33871520adab45aaa1a71f0402a2252050c14c7e3009446c8f4701c/python_docx-1.2.0.tar.gz", hash = "sha256:7bc9d7b7d8a69c9c02ca09216118c86552704edc23bac179283f2e38f86220ce", size = 5723256, upload-time = "2025-06-16T20:46:27.921Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d0/00/1e03a4989fa5795da308cd774f05b704ace555a70f9bf9d3be057b680bcf/python_docx-1.2.0-py3-none-any.whl", hash = "sha256:3fd478f3250fbbbfd3b94fe1e985955737c145627498896a8a6bf81f4baf66c7", size = 252987, upload-time = "2025-06-16T20:46:22.506Z" },
+]
+
[[package]]
name = "python-dotenv"
version = "1.2.2"
@@ -5842,6 +5855,7 @@ dependencies = [
{ name = "litellm" },
{ name = "mcp" },
{ name = "omegaconf" },
+ { name = "openpyxl" },
{ name = "opentelemetry-exporter-otlp" },
{ name = "opentelemetry-instrumentation-logging" },
{ name = "openviking-sdk" },
@@ -5851,6 +5865,7 @@ dependencies = [
{ name = "pyjwt", extra = ["crypto"] },
{ name = "pymysql" },
{ name = "pypdfium2" },
+ { name = "python-docx" },
{ name = "python-frontmatter" },
{ name = "pyyaml" },
{ name = "qrcode" },
@@ -5976,6 +5991,7 @@ requires-dist = [
{ name = "mem0ai", marker = "extra == 'database'", specifier = ">=1.0.0,<2" },
{ name = "omegaconf", specifier = "==2.3.0" },
{ name = "openai-codex", marker = "extra == 'codex'", specifier = "==0.159.2" },
+ { name = "openpyxl", specifier = ">=3.1.0,<4" },
{ name = "opensearch-py", marker = "extra == 'extensions'", specifier = ">=2.8.0" },
{ name = "opentelemetry-exporter-otlp", specifier = ">=1.37.0,<1.43" },
{ name = "opentelemetry-instrumentation-logging", specifier = ">=0.56b0,<0.64" },
@@ -5995,6 +6011,7 @@ requires-dist = [
{ name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=1.0.0" },
{ name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=7.0.0,<8.0.0" },
{ name = "pytest-xdist", marker = "extra == 'dev'", specifier = ">=3.8.0" },
+ { name = "python-docx", specifier = ">=1.1.0,<2" },
{ name = "python-dotenv", marker = "extra == 'sandbox'", specifier = ">=1.0.0" },
{ name = "python-frontmatter", specifier = "==1.1.0" },
{ name = "pyyaml", specifier = ">=6.0.2" },
diff --git a/veadk/tools/__init__.py b/veadk/tools/__init__.py
index 1c0081278..a734f8a8c 100644
--- a/veadk/tools/__init__.py
+++ b/veadk/tools/__init__.py
@@ -29,16 +29,29 @@
"parallel_web_search": "veadk.tools.builtin_tools.parallel_web_search:parallel_web_search",
"vesearch": "veadk.tools.builtin_tools.vesearch:vesearch",
"link_reader": "veadk.tools.builtin_tools.link_reader:link_reader",
+ "http_request": "veadk.tools.builtin_tools.http_request:http_request",
# Code
"run_code": "veadk.tools.builtin_tools.run_code:run_code",
"coding": "veadk.tools.builtin_tools.coding:coding",
- # Image / video / speech generation
+ # Image / video / speech
"image_generate": "veadk.tools.builtin_tools.image_generate:image_generate",
"image_edit": "veadk.tools.builtin_tools.image_edit:image_edit",
+ "image_transform": "veadk.tools.builtin_tools.image_transform:image_transform",
+ "image_understand": "veadk.tools.builtin_tools.image_understand:image_understand",
+ "ocr": "veadk.tools.builtin_tools.ocr:ocr",
"video_generate": "veadk.tools.builtin_tools.video_generate:video_generate",
"video_task_query": "veadk.tools.builtin_tools.video_generate:video_task_query",
"ppt_generate": "veadk.tools.builtin_tools.ppt_generate:ppt_generate",
"text_to_speech": "veadk.tools.builtin_tools.tts:text_to_speech",
+ "speech_to_text": "veadk.tools.builtin_tools.speech_to_text:speech_to_text",
+ # Documents and office
+ "document_parse": "veadk.tools.builtin_tools.document_parse:document_parse",
+ "doc_generate": "veadk.tools.builtin_tools.doc_generate:doc_generate",
+ "mindmap_generate": "veadk.tools.builtin_tools.mindmap_generate:mindmap_generate",
+ "qrcode_generate": "veadk.tools.builtin_tools.qrcode_generate:qrcode_generate",
+ # Utility
+ "calculator": "veadk.tools.builtin_tools.calculator:calculator",
+ "datetime": "veadk.tools.builtin_tools.datetime_tool:datetime",
# Demo / example tools
"get_city_weather": "veadk.tools.demo_tools:get_city_weather",
"get_location_weather": "veadk.tools.demo_tools:get_location_weather",
diff --git a/veadk/tools/builtin_tools/calculator.py b/veadk/tools/builtin_tools/calculator.py
new file mode 100644
index 000000000..194dcac43
--- /dev/null
+++ b/veadk/tools/builtin_tools/calculator.py
@@ -0,0 +1,183 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A safe arithmetic expression evaluator for model use.
+
+Parses the expression with :mod:`ast` and walks only the small set of numeric
+nodes it allows. Names, attribute access, subscripts, comprehensions, lambdas,
+strings, booleans, and complex numbers are all rejected, so the tool cannot be
+used to execute arbitrary Python.
+"""
+
+import ast
+import math
+import operator
+
+_MAX_EXPRESSION_LENGTH = 1000
+_MAX_EXPONENT = 100
+_MAX_ABS_RESULT = 1e100
+_MAX_PRECISION = 15
+
+_CONSTANTS = {"pi": math.pi, "e": math.e}
+_FUNCTIONS = {
+ "abs": abs,
+ "round": round,
+ "min": min,
+ "max": max,
+ "sqrt": math.sqrt,
+ "log": math.log,
+ "log10": math.log10,
+ "exp": math.exp,
+ "sin": math.sin,
+ "cos": math.cos,
+ "tan": math.tan,
+ "floor": math.floor,
+ "ceil": math.ceil,
+}
+_BINARY_OPERATORS = {
+ ast.Add: operator.add,
+ ast.Sub: operator.sub,
+ ast.Mult: operator.mul,
+ ast.Div: operator.truediv,
+ ast.FloorDiv: operator.floordiv,
+ ast.Mod: operator.mod,
+ ast.Pow: operator.pow,
+}
+
+
+class _EvalError(Exception):
+ """Internal evaluation error surfaced as ``{"error": ...}``."""
+
+
+def _check_number(value: object) -> None:
+ """Reject non-real, non-finite, or excessively large intermediate values."""
+ if type(value) not in (int, float):
+ raise _EvalError("result is not a finite real number")
+ if isinstance(value, float) and not math.isfinite(value):
+ raise _EvalError("result is not a finite real number")
+ if abs(value) > _MAX_ABS_RESULT:
+ raise _EvalError("result exceeds the allowed magnitude")
+
+
+def _apply_call(node: ast.Call) -> int | float:
+ if not isinstance(node.func, ast.Name) or node.func.id not in _FUNCTIONS:
+ raise _EvalError("unsupported function")
+ if node.keywords:
+ raise _EvalError("keyword arguments are not supported")
+ args = [_evaluate(argument) for argument in node.args]
+ try:
+ result = _FUNCTIONS[node.func.id](*args)
+ except ZeroDivisionError as exc:
+ raise _EvalError("division by zero") from exc
+ except OverflowError as exc:
+ raise _EvalError("numeric overflow") from exc
+ except (TypeError, ValueError) as exc:
+ raise _EvalError("math domain error") from exc
+ _check_number(result)
+ return result
+
+
+def _apply_binary(node: ast.BinOp) -> int | float:
+ operation = _BINARY_OPERATORS.get(type(node.op))
+ if operation is None:
+ raise _EvalError("unsupported binary operator")
+ left = _evaluate(node.left)
+ right = _evaluate(node.right)
+ if isinstance(node.op, ast.Pow) and (
+ type(right) not in (int, float) or abs(right) > _MAX_EXPONENT
+ ):
+ raise _EvalError(
+ f"exponent must be a number with absolute value <= {_MAX_EXPONENT}"
+ )
+ try:
+ result = operation(left, right)
+ except ZeroDivisionError as exc:
+ raise _EvalError("division by zero") from exc
+ except OverflowError as exc:
+ raise _EvalError("numeric overflow") from exc
+ _check_number(result)
+ return result
+
+
+def _evaluate(node: ast.AST) -> int | float:
+ if isinstance(node, ast.Expression):
+ return _evaluate(node.body)
+ if isinstance(node, ast.Constant):
+ if type(node.value) not in (int, float):
+ raise _EvalError("unsupported constant")
+ _check_number(node.value)
+ return node.value
+ if isinstance(node, ast.Name):
+ if node.id in _CONSTANTS:
+ return _CONSTANTS[node.id]
+ raise _EvalError(f"unknown name: {node.id}")
+ if isinstance(node, ast.UnaryOp):
+ operand = _evaluate(node.operand)
+ if isinstance(node.op, ast.UAdd):
+ result = +operand
+ elif isinstance(node.op, ast.USub):
+ result = -operand
+ else:
+ raise _EvalError("unsupported unary operator")
+ _check_number(result)
+ return result
+ if isinstance(node, ast.BinOp):
+ return _apply_binary(node)
+ if isinstance(node, ast.Call):
+ return _apply_call(node)
+ raise _EvalError(f"unsupported expression element: {type(node).__name__}")
+
+
+def calculator(expression: str, precision: int = 10) -> dict:
+ """Evaluate a numeric arithmetic expression safely.
+
+ Use this tool for arithmetic, percentages, powers, roots, logarithms, and
+ basic trigonometry. Named constants ``pi`` and ``e`` and the functions
+ ``abs``, ``round``, ``min``, ``max``, ``sqrt``, ``log``, ``log10``,
+ ``exp``, ``sin``, ``cos``, ``tan``, ``floor``, and ``ceil`` are supported.
+
+ Args:
+ expression: The arithmetic expression, for example ``"(1 + 2) * 3"``.
+ precision: Decimal places for a floating-point result (0-15).
+
+ Returns:
+ A dict with ``expression`` and ``result``. On invalid input, a dict with
+ an ``error`` key.
+ """
+ if not isinstance(expression, str) or not expression.strip():
+ return {"error": "expression must be a non-empty string"}
+ if len(expression) > _MAX_EXPRESSION_LENGTH:
+ return {
+ "error": f"expression is too long (max {_MAX_EXPRESSION_LENGTH} characters)"
+ }
+ if type(precision) is not int or not 0 <= precision <= _MAX_PRECISION:
+ return {"error": f"precision must be an integer between 0 and {_MAX_PRECISION}"}
+ try:
+ tree = ast.parse(expression, mode="eval")
+ except (SyntaxError, ValueError, TypeError, RecursionError):
+ return {"error": "invalid expression"}
+
+ try:
+ result = _evaluate(tree)
+ except _EvalError as exc:
+ return {"error": str(exc)}
+ except RecursionError:
+ return {"error": "expression is too complex"}
+ except Exception: # noqa: BLE001 - tool results must not raise
+ return {"error": "invalid expression"}
+
+ if type(result) is int:
+ return {"expression": expression, "result": result}
+ rounded = round(float(result), precision)
+ return {"expression": expression, "result": rounded}
diff --git a/veadk/tools/builtin_tools/datetime_tool.py b/veadk/tools/builtin_tools/datetime_tool.py
new file mode 100644
index 000000000..ea13d2a7e
--- /dev/null
+++ b/veadk/tools/builtin_tools/datetime_tool.py
@@ -0,0 +1,255 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A timezone-aware date/time tool for model use.
+
+Supports producing the current time, parsing common date/time strings,
+formatting, converting between timezones, computing differences, and adding
+durations. Uses ``zoneinfo`` so no credentials or external services are
+required.
+"""
+
+import math
+from datetime import datetime as _datetime
+from datetime import timedelta as _timedelta
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+_DEFAULT_TIMEZONE = "UTC"
+_DEFAULT_FORMAT = "%Y-%m-%d %H:%M:%S"
+_WEEKDAYS = (
+ "monday",
+ "tuesday",
+ "wednesday",
+ "thursday",
+ "friday",
+ "saturday",
+ "sunday",
+)
+_PARSE_FORMATS = (
+ "%Y-%m-%d",
+ "%Y-%m-%d %H:%M:%S",
+ "%Y/%m/%d",
+ "%Y/%m/%d %H:%M:%S",
+)
+_UNITS = ("seconds", "minutes", "hours", "days", "weeks")
+_ACTIONS = ("now", "parse", "format", "convert", "diff", "add")
+
+
+class _ToolError(Exception):
+ """Internal error surfaced to the model as ``{"error": ...}``."""
+
+
+def _get_zone(name: str | None) -> ZoneInfo:
+ if name is None:
+ return ZoneInfo(_DEFAULT_TIMEZONE)
+ if not isinstance(name, str) or not name.strip():
+ raise _ToolError("timezone must be a non-empty string")
+ try:
+ return ZoneInfo(name.strip())
+ except (ZoneInfoNotFoundError, ValueError, OSError) as exc:
+ raise _ToolError(f"unknown timezone: {name}") from exc
+
+
+def _timezone_name(moment: _datetime) -> str:
+ """Return a stable label: zone key when known, else the UTC offset."""
+ key = getattr(moment.tzinfo, "key", None)
+ if key:
+ return key
+ offset = moment.utcoffset()
+ if offset is None or offset == _timedelta(0):
+ return _DEFAULT_TIMEZONE
+ total = int(offset.total_seconds())
+ sign = "+" if total >= 0 else "-"
+ hours, remainder = divmod(abs(total), 3600)
+ minutes = remainder // 60
+ return f"{sign}{hours:02d}:{minutes:02d}"
+
+
+def _parse(value: str | None, timezone: str | None) -> _datetime:
+ if not isinstance(value, str) or not value.strip():
+ raise _ToolError("value must be a non-empty string")
+ text = value.strip()
+ if text.endswith(("Z", "z")):
+ text = text[:-1] + "+00:00"
+ parsed: _datetime | None = None
+ try:
+ parsed = _datetime.fromisoformat(text)
+ except ValueError:
+ for fmt in _PARSE_FORMATS:
+ try:
+ parsed = _datetime.strptime(text, fmt)
+ break
+ except ValueError:
+ continue
+ if parsed is None:
+ raise _ToolError(f"invalid datetime: {value}")
+ if parsed.tzinfo is None:
+ parsed = parsed.replace(tzinfo=_get_zone(timezone))
+ return parsed
+
+
+def _moment_fields(moment: _datetime) -> dict:
+ return {
+ "iso": moment.isoformat(),
+ "timestamp": moment.timestamp(),
+ "timezone": _timezone_name(moment),
+ "weekday": _WEEKDAYS[moment.weekday()],
+ }
+
+
+def _human_delta(seconds: float) -> str:
+ sign = "-" if seconds < 0 else ""
+ remaining = int(abs(seconds))
+ days, remaining = divmod(remaining, 86400)
+ hours, remaining = divmod(remaining, 3600)
+ minutes, secs = divmod(remaining, 60)
+ clock = f"{hours}:{minutes:02d}:{secs:02d}"
+ if days:
+ label = "day" if days == 1 else "days"
+ return f"{sign}{days} {label}, {clock}"
+ return f"{sign}{clock}"
+
+
+def _action_now(timezone: str | None) -> dict:
+ return _moment_fields(_datetime.now(_get_zone(timezone)))
+
+
+def _action_parse(value: str | None, timezone: str | None) -> dict:
+ moment = _parse(value, timezone)
+ return {
+ "iso": moment.isoformat(),
+ "timestamp": moment.timestamp(),
+ "timezone": _timezone_name(moment),
+ "year": moment.year,
+ "month": moment.month,
+ "day": moment.day,
+ "hour": moment.hour,
+ "minute": moment.minute,
+ "second": moment.second,
+ "weekday": _WEEKDAYS[moment.weekday()],
+ }
+
+
+def _action_format(value: str | None, timezone: str | None, fmt: str | None) -> dict:
+ if fmt is not None and not isinstance(fmt, str):
+ raise _ToolError("format must be a string")
+ moment = _parse(value, timezone)
+ pattern = fmt or _DEFAULT_FORMAT
+ try:
+ formatted = moment.strftime(pattern)
+ except (TypeError, ValueError) as exc:
+ raise _ToolError("invalid format string") from exc
+ return {"formatted": formatted, "iso": moment.isoformat()}
+
+
+def _action_convert(
+ value: str | None, timezone: str | None, target_timezone: str | None
+) -> dict:
+ if target_timezone is None:
+ raise _ToolError("target_timezone is required for convert")
+ moment = _parse(value, timezone).astimezone(_get_zone(target_timezone))
+ return {
+ "iso": moment.isoformat(),
+ "timestamp": moment.timestamp(),
+ "timezone": _timezone_name(moment),
+ }
+
+
+def _action_diff(value: str | None, value2: str | None, timezone: str | None) -> dict:
+ start = _parse(value, timezone)
+ end = _parse(value2, timezone)
+ delta = end - start
+ seconds = delta.total_seconds()
+ return {
+ "seconds": seconds,
+ "days": seconds / 86400,
+ "human": _human_delta(seconds),
+ }
+
+
+def _action_add(
+ value: str | None,
+ timezone: str | None,
+ amount: float | None,
+ unit: str | None,
+) -> dict:
+ if amount is None:
+ raise _ToolError("amount is required for add")
+ if isinstance(amount, bool) or not isinstance(amount, (int, float)):
+ raise _ToolError("amount must be a number")
+ if not math.isfinite(amount):
+ raise _ToolError("amount must be finite")
+ if not isinstance(unit, str) or unit.strip().lower() not in _UNITS:
+ raise _ToolError("unit must be one of: " + ", ".join(_UNITS))
+ moment = _parse(value, timezone) + _timedelta(**{unit.strip().lower(): amount})
+ return {"iso": moment.isoformat(), "timestamp": moment.timestamp()}
+
+
+def datetime(
+ action: str,
+ value: str | None = None,
+ value2: str | None = None,
+ timezone: str | None = None,
+ target_timezone: str | None = None,
+ format: str | None = None,
+ amount: float | None = None,
+ unit: str | None = None,
+) -> dict:
+ """Work with dates and times, including timezone conversions.
+
+ Use this tool for the current time, parsing or formatting a timestamp,
+ converting a timestamp between timezones, computing the difference between
+ two timestamps, or adding a duration. Timestamps without an explicit offset
+ use ``timezone`` (default UTC).
+
+ Args:
+ action: One of ``now``, ``parse``, ``format``, ``convert``, ``diff``,
+ ``add``.
+ value: The primary date/time string for ``parse``, ``format``,
+ ``convert``, ``diff``, and ``add``.
+ value2: The second date/time string for ``diff``.
+ timezone: IANA timezone name (for example ``Asia/Shanghai``) used when
+ ``value`` has no offset. Defaults to UTC.
+ target_timezone: IANA timezone name to convert to (``convert`` only).
+ format: ``strftime`` format string (``format`` only).
+ amount: Numeric amount to add (``add`` only).
+ unit: One of ``seconds``, ``minutes``, ``hours``, ``days``, ``weeks``
+ (``add`` only).
+
+ Returns:
+ A dict with the requested fields. On invalid input, a dict with an
+ ``error`` key.
+ """
+ try:
+ if action == "now":
+ return _action_now(timezone)
+ if action == "parse":
+ return _action_parse(value, timezone)
+ if action == "format":
+ return _action_format(value, timezone, format)
+ if action == "convert":
+ return _action_convert(value, timezone, target_timezone)
+ if action == "diff":
+ return _action_diff(value, value2, timezone)
+ if action == "add":
+ return _action_add(value, timezone, amount, unit)
+ raise _ToolError(
+ f"unsupported action: {action!r}; expected one of " + ", ".join(_ACTIONS)
+ )
+ except _ToolError as exc:
+ return {"error": str(exc)}
+ except (OverflowError, ValueError, TypeError, OSError) as exc:
+ return {"error": str(exc) or type(exc).__name__}
+ except Exception as exc: # noqa: BLE001 - tool results must not raise
+ return {"error": f"invalid datetime input ({type(exc).__name__})"}
diff --git a/veadk/tools/builtin_tools/doc_generate.py b/veadk/tools/builtin_tools/doc_generate.py
new file mode 100644
index 000000000..bcd9b8726
--- /dev/null
+++ b/veadk/tools/builtin_tools/doc_generate.py
@@ -0,0 +1,337 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generate a Word, Excel, CSV, or Markdown document as an ADK artifact."""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+import tempfile
+from pathlib import Path
+
+from google.adk.tools import ToolContext
+from google.genai import types
+
+_SUPPORTED_FORMATS = {"docx", "xlsx", "csv", "md"}
+
+_MIME_TYPES = {
+ "docx": ("application/vnd.openxmlformats-officedocument.wordprocessingml.document"),
+ "xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+ "csv": "text/csv",
+ "md": "text/markdown",
+}
+
+_MAX_SHEETS = 20
+_MAX_ROWS_PER_SHEET = 5_000
+_MAX_COLUMNS = 100
+_MAX_CSV_ROWS = 10_000
+_MAX_COLUMN_WIDTH = 60
+_MAX_FILENAME_LENGTH = 120
+
+_ALLOWED_FILENAME_RE = re.compile(r"[^A-Za-z0-9._\-一-鿿]+")
+_HEADING_RE = re.compile(r"^(#{1,3})\s+(.*)$")
+_ANY_HEADING_RE = re.compile(r"^\s*#{1,6}(?:\s|$)")
+# Spreadsheet applications treat these leading characters as formula starts;
+# generated files embed model-extracted data, so neutralize them.
+_FORMULA_PREFIXES = ("=", "+", "-", "@")
+_FORMULA_LEADING_WHITESPACE = "\t\r\n"
+
+
+class _DocError(Exception):
+ """Internal: converted to ``{"error": ...}`` at the tool boundary."""
+
+
+# --------------------------------------------------------------------- docx --
+def _strip_emphasis(value: str) -> str:
+ return re.sub(r"\*\*|__", "", value).strip()
+
+
+def _build_docx(title: str, content: str) -> bytes:
+ import docx
+
+ document = docx.Document()
+ if title:
+ document.add_heading(title, level=0)
+
+ buffer: list[str] = []
+
+ def flush() -> None:
+ if buffer:
+ document.add_paragraph(_strip_emphasis(" ".join(buffer)))
+ buffer.clear()
+
+ for raw_line in content.splitlines():
+ line = raw_line.strip()
+ if not line:
+ flush()
+ continue
+ heading = _HEADING_RE.match(line)
+ if heading:
+ flush()
+ document.add_heading(
+ _strip_emphasis(heading.group(2)),
+ level=len(heading.group(1)),
+ )
+ continue
+ if line.startswith(("- ", "* ", "+ ")):
+ flush()
+ document.add_paragraph(_strip_emphasis(line[2:]), style="List Bullet")
+ continue
+ if line.startswith("#"):
+ buffer.append(line.lstrip("#").strip())
+ continue
+ buffer.append(line)
+ flush()
+
+ output = io.BytesIO()
+ document.save(output)
+ return output.getvalue()
+
+
+# --------------------------------------------------------------------- xlsx --
+def _safe_sheet_name(value: object, fallback: str) -> str:
+ if not isinstance(value, str):
+ raise _DocError("each sheet needs a string name")
+ name = re.sub(r"[\[\]:*?/\\]", " ", value).strip()
+ if not name:
+ name = fallback
+ return name[:31]
+
+
+def _cell_value(value: object) -> object:
+ if value is None or isinstance(value, (str, int, float, bool)):
+ return value
+ return str(value)
+
+
+def _is_formula_like(value: str) -> bool:
+ return value.lstrip(_FORMULA_LEADING_WHITESPACE).startswith(_FORMULA_PREFIXES)
+
+
+def _build_xlsx(sheets: list[dict] | None) -> tuple[bytes, bool]:
+ import openpyxl
+ from openpyxl.styles import Font
+ from openpyxl.utils import get_column_letter
+
+ if not isinstance(sheets, list) or not sheets:
+ raise _DocError("sheets must be a non-empty list")
+
+ workbook = openpyxl.Workbook()
+ used_names: set[str] = set()
+ first_sheet = True
+ truncated = len(sheets) > _MAX_SHEETS
+ for index, sheet in enumerate(sheets[:_MAX_SHEETS]):
+ if not isinstance(sheet, dict):
+ raise _DocError("each sheet must be an object")
+ name = _safe_sheet_name(sheet.get("name"), f"Sheet{index + 1}")
+ rows = sheet.get("rows")
+ if not isinstance(rows, list):
+ raise _DocError(f"sheet {name!r} must have a rows list")
+ if name in used_names:
+ suffix = 2
+ while f"{name[:28]}_{suffix}" in used_names:
+ suffix += 1
+ name = f"{name[:28]}_{suffix}"
+ used_names.add(name)
+
+ if first_sheet:
+ worksheet = workbook.active
+ worksheet.title = name
+ first_sheet = False
+ else:
+ worksheet = workbook.create_sheet(title=name)
+
+ truncated = truncated or len(rows) > _MAX_ROWS_PER_SHEET
+ widths: dict[int, int] = {}
+ for row_index, row in enumerate(rows[:_MAX_ROWS_PER_SHEET], start=1):
+ if not isinstance(row, (list, tuple)):
+ raise _DocError(f"sheet {name!r} contains a non-list row")
+ truncated = truncated or len(row) > _MAX_COLUMNS
+ for column_index, value in enumerate(row[:_MAX_COLUMNS], start=1):
+ cell_value = _cell_value(value)
+ cell = worksheet.cell(
+ row=row_index,
+ column=column_index,
+ value=cell_value,
+ )
+ if isinstance(cell_value, str) and _is_formula_like(cell_value):
+ # Force a text cell so the value is never evaluated as a
+ # spreadsheet formula.
+ cell.data_type = "s"
+ width = len(str(value)) if value is not None else 0
+ widths[column_index] = max(widths.get(column_index, 0), width)
+ if rows:
+ for cell in worksheet[1]:
+ cell.font = Font(bold=True)
+ for column_index, width in widths.items():
+ worksheet.column_dimensions[get_column_letter(column_index)].width = min(
+ max(8, width + 2), _MAX_COLUMN_WIDTH
+ )
+
+ output = io.BytesIO()
+ workbook.save(output)
+ return output.getvalue(), truncated
+
+
+# ---------------------------------------------------------------------- csv --
+def _build_csv(rows: list[list] | None, content: str) -> tuple[bytes, bool]:
+ if rows is not None:
+ if not isinstance(rows, list):
+ raise _DocError("rows must be a list")
+ buffer = io.StringIO(newline="")
+ writer = csv.writer(buffer)
+ for row in rows[:_MAX_CSV_ROWS]:
+ if not isinstance(row, (list, tuple)):
+ raise _DocError("each row must be a list")
+ cells = ["" if value is None else str(value) for value in row]
+ # CSV has no cell types, so prefix dangerous values with a quote
+ # (the usual spreadsheet text marker) instead.
+ writer.writerow(
+ [
+ f"'{cell}" if cell and _is_formula_like(cell) else cell
+ for cell in cells
+ ]
+ )
+ return buffer.getvalue().encode("utf-8"), len(rows) > _MAX_CSV_ROWS
+ if content:
+ return content.encode("utf-8"), False
+ raise _DocError("csv requires rows or content")
+
+
+# ----------------------------------------------------------------------- md --
+def _build_md(title: str, content: str) -> bytes:
+ if title and not _ANY_HEADING_RE.match(content):
+ content = f"# {title}\n\n{content}" if content else f"# {title}\n"
+ return content.encode("utf-8")
+
+
+# ----------------------------------------------------------------- filename --
+def _sanitize_filename(filename: str | None, fmt: str) -> str:
+ default = f"document.{fmt}"
+ if not isinstance(filename, str) or not filename.strip():
+ return default
+ name = filename.strip().replace("\\", "/").rsplit("/", 1)[-1]
+ name = _ALLOWED_FILENAME_RE.sub("-", name).strip(".-")
+ if not name:
+ return default
+ suffix = f".{fmt}"
+ if name.lower().endswith(suffix):
+ stem = name[: -len(suffix)].strip(".-")
+ else:
+ stem = name.rsplit(".", 1)[0] if "." in name else name
+ stem = stem.strip(".-")
+ stem = stem[: _MAX_FILENAME_LENGTH - len(suffix)] or "document"
+ return f"{stem}{suffix}"
+
+
+# --------------------------------------------------------------------- tool --
+async def doc_generate(
+ format: str,
+ title: str,
+ content: str = "",
+ sheets: list[dict] | None = None,
+ rows: list[list] | None = None,
+ filename: str | None = None,
+ tool_context: ToolContext | None = None,
+) -> dict:
+ """Generate a document and attach it to the current conversation.
+
+ Args:
+ format: One of ``docx``, ``xlsx``, ``csv``, or ``md`` (case-insensitive).
+ title: Document title. Rendered as the Word title and the Markdown
+ heading; ignored for CSV.
+ content: Markdown-ish body for ``docx``/``md``; raw CSV text fallback
+ for ``csv``. Supports ``#``-``###`` headings and ``-``/``*``/``+``
+ bullets for Word.
+ sheets: For ``xlsx``, a list of ``{"name": str, "rows": list[list]}``.
+ String cells starting with ``=``, ``+``, ``-`` or ``@`` (after
+ leading tab/CR/LF) are written as text, never as formulas.
+ rows: For ``csv``, a list of rows. CSV output is plain UTF-8 without a
+ byte-order mark. Formula-like cells get a leading ``'`` so
+ spreadsheet applications treat them as text.
+ filename: Optional output filename; the correct extension is forced.
+ tool_context: Current ADK tool context used to save the artifact. When
+ omitted, the file is written to a temporary directory instead.
+
+ Returns:
+ ``{"filename", "format", "size_bytes", "mime_type", "truncated",
+ "artifact_saved", "path"}`` on success, or ``{"error"}`` on failure.
+ ``truncated`` is true when sheets, rows, or columns hit the documented
+ caps and the generated file is shorter than the input.
+ """
+ fmt = format.strip().lower() if isinstance(format, str) else ""
+ if fmt not in _SUPPORTED_FORMATS:
+ return {"error": "format must be one of docx, xlsx, csv, md"}
+
+ title_text = (
+ title if isinstance(title, str) else ("" if title is None else str(title))
+ )
+ content_text = (
+ content
+ if isinstance(content, str)
+ else ("" if content is None else str(content))
+ )
+
+ truncated = False
+ try:
+ if fmt == "docx":
+ data = _build_docx(title_text.strip(), content_text)
+ elif fmt == "xlsx":
+ data, truncated = _build_xlsx(sheets)
+ elif fmt == "csv":
+ data, truncated = _build_csv(rows, content_text)
+ else:
+ data = _build_md(title_text.strip(), content_text)
+ except _DocError as exc:
+ return {"error": str(exc)}
+ except Exception as exc: # noqa: BLE001 - never raise out of the tool
+ return {"error": f"failed to generate {fmt}: {exc}"}
+
+ name = _sanitize_filename(filename, fmt)
+ mime_type = _MIME_TYPES[fmt]
+ result = {
+ "filename": name,
+ "format": fmt,
+ "size_bytes": len(data),
+ "mime_type": mime_type,
+ "truncated": truncated,
+ "artifact_saved": False,
+ "path": None,
+ }
+
+ if tool_context is None:
+ directory = tempfile.mkdtemp(prefix="veadk-doc-")
+ path = Path(directory) / name
+ try:
+ path.write_bytes(data)
+ except OSError as exc:
+ return {"error": f"failed to write file: {exc}"}
+ result["path"] = str(path)
+ return result
+
+ try:
+ artifact = types.Part.from_bytes(data=data, mime_type=mime_type)
+ if artifact.inline_data is not None:
+ artifact.inline_data.display_name = name
+ await tool_context.save_artifact(name, artifact)
+ except Exception as exc: # noqa: BLE001 - artifact storage failure
+ return {"error": f"failed to save artifact: {exc}"}
+
+ result["artifact_saved"] = True
+ return result
+
+
+__all__ = ["doc_generate"]
diff --git a/veadk/tools/builtin_tools/document_parse.py b/veadk/tools/builtin_tools/document_parse.py
new file mode 100644
index 000000000..7e181e95d
--- /dev/null
+++ b/veadk/tools/builtin_tools/document_parse.py
@@ -0,0 +1,457 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Convert a local document or a public URL into bounded plain text.
+
+The tool intentionally returns a dictionary instead of raising: malformed input,
+missing files, SSRF-rejected URLs, and corrupt documents all surface as
+``{"error": "..."}`` so an agent receives a tool result rather than an
+exception. Remote downloads reuse the ``web_fetch`` public-URL guard and follow
+redirects manually (re-validating every hop) with a hard size cap.
+"""
+
+from __future__ import annotations
+
+import csv
+import html as _html
+import io
+import json
+import re
+from pathlib import Path
+from urllib.parse import urlparse, urljoin
+
+import filetype
+import requests
+
+from veadk.tools.builtin_tools.web_fetch import assert_public_url
+
+_DEFAULT_MAX_CHARS = 200_000
+_MIN_MAX_CHARS = 1_000
+_MAX_MAX_CHARS = 1_000_000
+
+_MAX_DOWNLOAD_BYTES = 20_000_000
+_MAX_REDIRECTS = 3
+_DOWNLOAD_TIMEOUT_SECONDS = 30
+
+_MAX_XLSX_SHEETS = 50
+_MAX_XLSX_ROWS_PER_SHEET = 1_000
+_MAX_CSV_ROWS = 5_000
+
+_USER_AGENT = (
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+ "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+)
+
+_SUPPORTED_FORMATS = {"pdf", "docx", "xlsx", "csv", "txt", "md", "json", "html"}
+_FORMAT_ALIASES = {"markdown": "md", "htm": "html"}
+_EXTENSION_FORMATS = {
+ ".pdf": "pdf",
+ ".docx": "docx",
+ ".xlsx": "xlsx",
+ ".csv": "csv",
+ ".txt": "txt",
+ ".md": "md",
+ ".markdown": "md",
+ ".json": "json",
+ ".html": "html",
+ ".htm": "html",
+}
+
+# Server-provided ``Content-Type`` fallback for URLs without a useful suffix,
+# e.g. ``https://example.com/document`` serving HTML or JSON.
+_CONTENT_TYPE_FORMATS = {
+ "text/html": "html",
+ "application/xhtml+xml": "html",
+ "application/json": "json",
+ "text/csv": "csv",
+ "application/pdf": "pdf",
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+ "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+}
+
+
+class _ParseError(Exception):
+ """Internal: converted to ``{"error": ...}`` at the tool boundary."""
+
+
+# --------------------------------------------------------------- validation --
+def _validate_max_chars(value: object) -> int:
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise _ParseError("max_chars must be an integer")
+ if not _MIN_MAX_CHARS <= value <= _MAX_MAX_CHARS:
+ raise _ParseError(
+ f"max_chars must be between {_MIN_MAX_CHARS} and {_MAX_MAX_CHARS}"
+ )
+ return value
+
+
+def _is_url(source: str) -> bool:
+ return source.lower().startswith(("http://", "https://"))
+
+
+def _normalize_format(value: object) -> str | None:
+ if not isinstance(value, str):
+ return None
+ normalized = value.strip().lower()
+ normalized = _FORMAT_ALIASES.get(normalized, normalized)
+ return normalized if normalized in _SUPPORTED_FORMATS else None
+
+
+def _format_from_content_type(value: str | None) -> str | None:
+ if not value:
+ return None
+ media_type = value.split(";", 1)[0].strip().lower()
+ return _CONTENT_TYPE_FORMATS.get(media_type)
+
+
+def _looks_like_html(data: bytes) -> bool:
+ head = data[:512].decode("utf-8", errors="ignore").lstrip().lower()
+ return head.startswith((" str | None:
+ if explicit is not None:
+ return _normalize_format(explicit)
+
+ if _is_url(source):
+ suffix = Path(urlparse(source).path).suffix.lower()
+ else:
+ suffix = Path(source).suffix.lower()
+ if suffix in _EXTENSION_FORMATS:
+ return _EXTENSION_FORMATS[suffix]
+
+ by_content_type = _format_from_content_type(content_type)
+ if by_content_type is not None:
+ return by_content_type
+
+ try:
+ kind = filetype.guess(data)
+ except Exception: # noqa: BLE001 - detection is best-effort
+ kind = None
+ if kind is not None:
+ detected = _EXTENSION_FORMATS.get(f".{kind.extension.lower()}")
+ if detected is not None:
+ return detected
+ if _looks_like_html(data):
+ return "html"
+ return "txt"
+
+
+# ----------------------------------------------------------------- download --
+def _read_capped(response: requests.Response) -> tuple[bytes, bool]:
+ """Read at most ``_MAX_DOWNLOAD_BYTES`` and report whether more remained."""
+ chunks: list[bytes] = []
+ total = 0
+ # Keep reading until the cap is exceeded so an exactly-sized body is not
+ # misreported as truncated.
+ for chunk in response.iter_content(chunk_size=16_384):
+ if not chunk:
+ continue
+ chunks.append(chunk)
+ total += len(chunk)
+ if total > _MAX_DOWNLOAD_BYTES:
+ break
+ data = b"".join(chunks)
+ return data[:_MAX_DOWNLOAD_BYTES], len(data) > _MAX_DOWNLOAD_BYTES
+
+
+def _download_url(url: str) -> tuple[bytes, bool, str, str | None]:
+ """Download *url*, re-validating each redirect hop and capping the size.
+
+ Returns the body, whether the cap truncated it, the final URL after
+ redirects, and the response ``Content-Type`` (if any) so format detection
+ can use it.
+ """
+ current = url
+ hops = 0
+ while True:
+ # Raises ValueError for non-http(s) schemes or non-public hosts.
+ assert_public_url(current)
+ response = requests.get(
+ current,
+ headers={"User-Agent": _USER_AGENT},
+ timeout=_DOWNLOAD_TIMEOUT_SECONDS,
+ allow_redirects=False,
+ stream=True,
+ )
+ try:
+ location = response.headers.get("location")
+ if response.is_redirect and location:
+ hops += 1
+ if hops > _MAX_REDIRECTS:
+ raise _ParseError(f"too many redirects (>{_MAX_REDIRECTS})")
+ current = urljoin(current, location)
+ continue
+ if not response.ok:
+ raise _ParseError(f"HTTP {response.status_code}")
+ data, truncated = _read_capped(response)
+ return data, truncated, current, response.headers.get("content-type")
+ finally:
+ response.close()
+
+
+# ------------------------------------------------------------------ parsers --
+def _extract_pdf(data: bytes) -> tuple[str, dict]:
+ import pypdfium2 as pdfium
+
+ with pdfium.PdfDocument(io.BytesIO(data)) as document:
+ page_count = len(document)
+ parts: list[str] = []
+ for index in range(page_count):
+ page = document[index]
+ try:
+ textpage = page.get_textpage()
+ try:
+ parts.append(textpage.get_text_range())
+ finally:
+ textpage.close()
+ finally:
+ page.close()
+ text = "\n\n".join(parts)
+ return text, {"pages": page_count, "needs_ocr": page_count > 0 and not text.strip()}
+
+
+def _extract_docx(data: bytes) -> tuple[str, dict]:
+ import docx
+ from docx.oxml.ns import qn
+ from docx.table import Table
+ from docx.text.paragraph import Paragraph
+
+ document = docx.Document(io.BytesIO(data))
+ blocks: list[str] = []
+ paragraph_count = 0
+ table_count = 0
+ for child in document.element.body.iterchildren():
+ if child.tag == qn("w:p"):
+ blocks.append(Paragraph(child, document).text)
+ paragraph_count += 1
+ elif child.tag == qn("w:tbl"):
+ table = Table(child, document)
+ rows = [
+ " | ".join(cell.text.strip() for cell in row.cells)
+ for row in table.rows
+ ]
+ blocks.append("\n".join(rows))
+ table_count += 1
+ text = "\n\n".join(block for block in blocks if block.strip())
+ return text, {"paragraphs": paragraph_count, "tables": table_count}
+
+
+def _extract_xlsx(data: bytes) -> tuple[str, dict]:
+ import openpyxl
+
+ # ``read_only`` keeps memory proportional to one row at a time, but the
+ # 20,000,000-byte input cap is the only bound on zip/XML expansion inside
+ # openpyxl. Treat xlsx input as trusted up to that cap; lowering the cap is
+ # the way to tighten this, not adding a second decompression budget here.
+ workbook = openpyxl.load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+ try:
+ sheet_names = list(workbook.sheetnames)[:_MAX_XLSX_SHEETS]
+ lines: list[str] = []
+ total_rows = 0
+ for name in sheet_names:
+ lines.append(f"## {name}")
+ emitted = 0
+ for row in workbook[name].iter_rows(values_only=True):
+ if emitted >= _MAX_XLSX_ROWS_PER_SHEET:
+ break
+ lines.append(
+ "\t".join("" if value is None else str(value) for value in row)
+ )
+ emitted += 1
+ total_rows += emitted
+ finally:
+ workbook.close()
+ text = "\n".join(lines)
+ return text, {"sheets": sheet_names, "total_rows": total_rows}
+
+
+def _extract_csv(data: bytes) -> tuple[str, dict]:
+ decoded = data.decode("utf-8", errors="replace")
+ try:
+ dialect = csv.Sniffer().sniff(decoded[:4096])
+ except csv.Error:
+ dialect = csv.excel
+ delimiter = getattr(dialect, "delimiter", ",")
+ lines: list[str] = []
+ for index, row in enumerate(csv.reader(io.StringIO(decoded), dialect)):
+ if index >= _MAX_CSV_ROWS:
+ break
+ lines.append("\t".join(row))
+ return "\n".join(lines), {"delimiter": delimiter, "rows": len(lines)}
+
+
+def _strip_html_tags(value: str) -> str:
+ value = re.sub(
+ r"<(script|style)[\s\S]*?\1(?:\s+[^>]*)?>",
+ " ",
+ value,
+ flags=re.IGNORECASE,
+ )
+ value = _html.unescape(re.sub(r"<[^>]+>", " ", value))
+ return re.sub(r"\s+", " ", value).strip()
+
+
+def _extract_html(data: bytes) -> tuple[str, dict]:
+ import trafilatura
+
+ decoded = data.decode("utf-8", errors="replace")
+ try:
+ extracted = trafilatura.extract(decoded)
+ except Exception: # noqa: BLE001 - fall back to a coarse strip
+ extracted = None
+ if extracted and extracted.strip():
+ return extracted.strip(), {"extraction": "trafilatura"}
+ return _strip_html_tags(decoded), {"extraction": "fallback"}
+
+
+def _extract_json(data: bytes) -> tuple[str, dict]:
+ decoded = data.decode("utf-8", errors="replace")
+ try:
+ parsed = json.loads(decoded)
+ except (TypeError, ValueError):
+ return decoded, {"valid_json": False}
+ return json.dumps(parsed, ensure_ascii=False, indent=2), {"valid_json": True}
+
+
+def _extract_text(data: bytes) -> tuple[str, dict]:
+ return data.decode("utf-8", errors="replace"), {}
+
+
+def _parse_bytes(fmt: str, data: bytes) -> tuple[str, dict]:
+ if fmt == "pdf":
+ return _extract_pdf(data)
+ if fmt == "docx":
+ return _extract_docx(data)
+ if fmt == "xlsx":
+ return _extract_xlsx(data)
+ if fmt == "csv":
+ return _extract_csv(data)
+ if fmt == "html":
+ return _extract_html(data)
+ if fmt == "json":
+ return _extract_json(data)
+ return _extract_text(data)
+
+
+# --------------------------------------------------------------------- tool --
+def document_parse(
+ source: str,
+ format: str | None = None,
+ max_chars: int = _DEFAULT_MAX_CHARS,
+) -> dict:
+ """Parse a document into bounded plain text.
+
+ Accepts a local file path or a public http(s) URL. The format is taken from
+ ``format`` when supplied, otherwise inferred from the file extension, then
+ from the response ``Content-Type``, then from the file's magic bytes, then
+ from an HTML sniff, and finally treated as UTF-8 text.
+
+ Args:
+ source: Local path or public http(s) URL. A local file larger than
+ 20,000,000 bytes returns an error; a remote body larger than that
+ is truncated and flagged in ``metadata["download_truncated"]``.
+ format: Optional override: pdf, docx, xlsx, csv, txt, md, json, or html.
+ max_chars: Maximum characters returned (1,000-1,000,000).
+
+ Returns:
+ ``{"format", "text", "truncated", "metadata"}`` on success, or
+ ``{"error"}`` on failure. ``metadata`` reports ``size_bytes`` and
+ whether the byte cap truncated the download.
+ """
+ try:
+ limit = _validate_max_chars(max_chars)
+ except _ParseError as exc:
+ return {"error": str(exc)}
+
+ if not isinstance(source, str) or not source.strip():
+ return {"error": "source is required"}
+ source = source.strip()
+
+ metadata: dict[str, object] = {}
+ detection_source = source
+ content_type: str | None = None
+ download_truncated = False
+ try:
+ if _is_url(source):
+ try:
+ data, download_truncated, final_url, content_type = _download_url(
+ source
+ )
+ except ValueError as exc:
+ return {"error": str(exc)}
+ except _ParseError as exc:
+ return {"error": str(exc)}
+ except requests.RequestException as exc:
+ return {"error": f"download failed: {exc}"}
+ metadata.update(
+ {
+ "source_kind": "url",
+ "url": final_url,
+ "requested_url": source,
+ }
+ )
+ if content_type:
+ metadata["content_type"] = content_type
+ detection_source = final_url
+ else:
+ path = Path(source)
+ if not path.is_file():
+ return {"error": f"file not found: {source}"}
+ try:
+ # Bound the read even though the file may grow between the
+ # existence check and the read.
+ with path.open("rb") as handle:
+ data = handle.read(_MAX_DOWNLOAD_BYTES + 1)
+ except OSError as exc:
+ return {"error": f"failed to read file: {exc}"}
+ if len(data) > _MAX_DOWNLOAD_BYTES:
+ return {"error": f"file exceeds the {_MAX_DOWNLOAD_BYTES} byte limit"}
+ metadata.update({"source_kind": "file", "path": str(path)})
+
+ metadata["size_bytes"] = len(data)
+ # Remote bodies cannot be rejected before reading, so the cap truncates
+ # them; surface that explicitly or a parse error looks unexplainable.
+ metadata["download_truncated"] = download_truncated
+ detected = _detect_format(detection_source, data, format, content_type)
+ if detected is None:
+ return {"error": f"unsupported format: {format}"}
+ fmt = detected
+ metadata["format"] = fmt
+
+ try:
+ text, extra = _parse_bytes(fmt, data)
+ except Exception as exc: # noqa: BLE001 - corrupt input is a tool error
+ return {"error": f"failed to parse {fmt}: {exc}"}
+ metadata.update(extra)
+ except Exception as exc: # noqa: BLE001 - never raise out of the tool
+ return {"error": f"failed to parse document: {exc}"}
+
+ truncated = len(text) > limit
+ if truncated:
+ text = text[:limit]
+ return {
+ "format": fmt,
+ "text": text,
+ "truncated": truncated,
+ "metadata": metadata,
+ }
+
+
+__all__ = ["document_parse"]
diff --git a/veadk/tools/builtin_tools/http_request.py b/veadk/tools/builtin_tools/http_request.py
new file mode 100644
index 000000000..5af4576b1
--- /dev/null
+++ b/veadk/tools/builtin_tools/http_request.py
@@ -0,0 +1,383 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A generic HTTP request tool with SSRF, redirect, and size safeguards.
+
+The tool performs a single HTTP(S) request on behalf of the model. It reuses
+``web_fetch``'s SSRF guard (``assert_public_url``) so private/internal targets
+stay blocked, validates the URL again on every redirect hop, supports an
+optional host allowlist (``TOOL_HTTP_ALLOWLIST``), resolves secret header
+values from the environment via ``env:NAME``, and caps the downloaded body at
+``max_bytes`` so a large response cannot exhaust memory.
+"""
+
+import os
+from typing import Any
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from veadk.tools.builtin_tools.web_fetch import assert_public_url
+
+_ALLOWED_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"})
+_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+_MAX_REDIRECTS = 3
+_ALLOWLIST_ENV = "TOOL_HTTP_ALLOWLIST"
+_BLOCKED_HEADERS = frozenset({"host", "content-length"})
+# Credentials must not be replayed to a different origin (or over a
+# downgraded scheme). httpx strips `Authorization` itself, but this tool
+# follows redirects manually and therefore has to do it here.
+_SENSITIVE_HEADERS = frozenset(
+ {"authorization", "proxy-authorization", "cookie", "cookie2"}
+)
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+_MIN_TIMEOUT = 1
+_MAX_TIMEOUT = 120
+_MIN_MAX_BYTES = 1_000
+_MAX_MAX_BYTES = 20_000_000
+
+
+class _RequestAborted(Exception):
+ """Internal error surfaced to the model as ``{"error": ...}``."""
+
+
+def _validate_target(url: str, allowlist: tuple[str, ...]) -> None:
+ """Validate scheme/host/SSRF policy and the optional host allowlist."""
+ try:
+ host = assert_public_url(url)
+ except ValueError as exc:
+ raise _RequestAborted(str(exc)) from exc
+ if allowlist and not _host_is_allowed(host, allowlist):
+ raise _RequestAborted(f"host {host!r} is not in the allowlist")
+
+
+def _host_is_allowed(host: str, allowlist: tuple[str, ...]) -> bool:
+ host = host.lower()
+ return any(host == entry or host.endswith("." + entry) for entry in allowlist)
+
+
+def _read_allowlist() -> tuple[str, ...]:
+ raw = os.environ.get(_ALLOWLIST_ENV, "")
+ return tuple(entry.strip().lower() for entry in raw.split(",") if entry.strip())
+
+
+def _resolve_headers(
+ headers: dict[str, str] | None,
+) -> tuple[dict[str, str], frozenset[str]]:
+ """Validate headers and resolve ``env:NAME`` values from the environment.
+
+ Returns the resolved headers and the names whose values came from the
+ environment, so redirects can drop secrets even for custom header names.
+ """
+ if headers is None:
+ return {}, frozenset()
+ if not isinstance(headers, dict):
+ raise _RequestAborted("headers must be an object")
+ resolved: dict[str, str] = {}
+ from_environment: set[str] = set()
+ for name, value in headers.items():
+ if not isinstance(name, str) or not isinstance(value, str):
+ raise _RequestAborted("header names and values must be strings")
+ lowered = name.lower()
+ if lowered in _BLOCKED_HEADERS:
+ raise _RequestAborted(f"header {name!r} is not allowed")
+ if any(char in name for char in "\r\n") or any(
+ char in value for char in "\r\n"
+ ):
+ raise _RequestAborted(f"header {name!r} contains an invalid character")
+ if value.startswith("env:"):
+ env_name = value[len("env:") :]
+ env_value = os.environ.get(env_name) if env_name else None
+ if not env_value:
+ raise _RequestAborted(
+ f"environment variable for header {name!r} is not set"
+ )
+ resolved[name] = env_value
+ from_environment.add(name)
+ else:
+ resolved[name] = value
+ return resolved, frozenset(from_environment)
+
+
+def _origin(url: str) -> tuple[str, str, int | None]:
+ parsed = urlparse(url)
+ scheme = parsed.scheme.lower()
+ try:
+ port = parsed.port
+ except ValueError:
+ port = None
+ if port is None:
+ port = _DEFAULT_PORTS.get(scheme)
+ return scheme, (parsed.hostname or "").lower(), port
+
+
+def _headers_for_redirect(
+ headers: dict[str, str],
+ env_header_names: frozenset[str],
+ previous_url: str,
+ next_url: str,
+) -> dict[str, str]:
+ """Drop credentials that must not cross to the redirect target.
+
+ Mirrors httpx's redirect handling: auth headers survive only a same-origin
+ hop or a same-host http -> https upgrade. ``env:``-resolved headers are
+ treated as secrets regardless of their name, and a scheme downgrade always
+ strips credentials.
+ """
+ previous = _origin(previous_url)
+ next_origin = _origin(next_url)
+ if previous == next_origin:
+ return headers
+ previous_scheme, previous_host, previous_port = previous
+ next_scheme, next_host, next_port = next_origin
+ # Same-host upgrade on the standard ports (requests' behaviour).
+ if (
+ previous_scheme == "http"
+ and next_scheme == "https"
+ and previous_host == next_host
+ and previous_port == 80
+ and next_port == 443
+ ):
+ return headers
+ return {
+ name: value
+ for name, value in headers.items()
+ if name.lower() not in _SENSITIVE_HEADERS and name not in env_header_names
+ }
+
+
+def _read_body(response: httpx.Response, max_bytes: int) -> tuple[bytes, bool]:
+ """Read at most ``max_bytes + 1`` bytes so truncation is detectable."""
+ remaining = max_bytes + 1
+ chunks: list[bytes] = []
+ for chunk in response.iter_bytes():
+ if not chunk:
+ continue
+ piece = chunk[:remaining]
+ chunks.append(piece)
+ remaining -= len(piece)
+ if remaining <= 0:
+ break
+ raw = b"".join(chunks)
+ if len(raw) > max_bytes:
+ return raw[:max_bytes], True
+ return raw, False
+
+
+def _build_result(
+ url: str,
+ response: httpx.Response,
+ method: str,
+ raw: bytes,
+ truncated: bool,
+) -> dict:
+ headers = {
+ str(name).lower(): str(value) for name, value in response.headers.items()
+ }
+ if method == "HEAD":
+ raw = b""
+ truncated = False
+ encoding = response.encoding or "utf-8"
+ try:
+ body = raw.decode(encoding, errors="replace")
+ except LookupError:
+ body = raw.decode("utf-8", errors="replace")
+ return {
+ "status_code": int(response.status_code),
+ "url": url,
+ "headers": headers,
+ "content_type": headers.get("content-type"),
+ "body": body,
+ "bytes": len(raw),
+ "truncated": truncated,
+ }
+
+
+def _perform_request(
+ client: httpx.Client,
+ url: str,
+ method: str,
+ headers: dict[str, str],
+ params: dict[str, Any] | None,
+ json_body: Any,
+ body: str | None,
+ max_bytes: int,
+ follow_redirects: bool,
+ allowlist: tuple[str, ...],
+ env_header_names: frozenset[str] = frozenset(),
+) -> dict:
+ current_url = url
+ current_method = method
+ current_params = params
+ current_json = json_body
+ current_body = body
+ current_headers = headers
+ hops = 0
+
+ while True:
+ _validate_target(current_url, allowlist)
+ with client.stream(
+ current_method,
+ current_url,
+ headers=current_headers,
+ params=current_params,
+ json=current_json,
+ content=current_body,
+ ) as response:
+ if follow_redirects and response.status_code in _REDIRECT_STATUSES:
+ location = response.headers.get("location")
+ if location:
+ hops += 1
+ if hops > _MAX_REDIRECTS:
+ raise _RequestAborted(
+ f"too many redirects (max {_MAX_REDIRECTS})"
+ )
+ next_url = urljoin(current_url, location)
+ # Credentials follow httpx semantics: never cross origins
+ # or downgrade to http, including env-resolved secrets.
+ current_headers = _headers_for_redirect(
+ current_headers,
+ env_header_names,
+ current_url,
+ next_url,
+ )
+ if current_method != "HEAD" and (
+ response.status_code == 303
+ or (
+ response.status_code in (301, 302)
+ and current_method == "POST"
+ )
+ ):
+ current_method = "GET"
+ current_json = None
+ current_body = None
+ current_url = next_url
+ # Query params belong to the original URL; a redirect's
+ # Location already carries the target query string.
+ current_params = None
+ continue
+ raw, truncated = _read_body(response, max_bytes)
+ return _build_result(current_url, response, current_method, raw, truncated)
+
+
+def _run(
+ url: str,
+ method: str,
+ headers: dict[str, str] | None,
+ params: dict[str, Any] | None,
+ json_body: Any,
+ body: str | None,
+ timeout: int,
+ max_bytes: int,
+ follow_redirects: bool,
+) -> dict:
+ if not isinstance(method, str):
+ raise _RequestAborted("method must be a string")
+ normalized_method = method.upper()
+ if normalized_method not in _ALLOWED_METHODS:
+ raise _RequestAborted(f"unsupported method: {method}")
+ if type(timeout) is not int or not _MIN_TIMEOUT <= timeout <= _MAX_TIMEOUT:
+ raise _RequestAborted(
+ f"timeout must be an integer between {_MIN_TIMEOUT} and {_MAX_TIMEOUT}"
+ )
+ if type(max_bytes) is not int or not _MIN_MAX_BYTES <= max_bytes <= _MAX_MAX_BYTES:
+ raise _RequestAborted(
+ "max_bytes must be an integer between "
+ f"{_MIN_MAX_BYTES} and {_MAX_MAX_BYTES}"
+ )
+ if not isinstance(url, str) or not url:
+ raise _RequestAborted("url must be a non-empty string")
+ if json_body is not None and body is not None:
+ raise _RequestAborted("provide only one of json_body or body")
+
+ allowlist = _read_allowlist()
+ resolved_headers, env_header_names = _resolve_headers(headers)
+
+ client = httpx.Client(timeout=timeout, follow_redirects=False)
+ try:
+ return _perform_request(
+ client,
+ url,
+ normalized_method,
+ resolved_headers,
+ params,
+ json_body,
+ body,
+ max_bytes,
+ follow_redirects,
+ allowlist,
+ env_header_names,
+ )
+ finally:
+ client.close()
+
+
+def http_request(
+ url: str,
+ method: str = "GET",
+ headers: dict[str, str] | None = None,
+ params: dict[str, Any] | None = None,
+ json_body: Any = None,
+ body: str | None = None,
+ timeout: int = 30,
+ max_bytes: int = 5_000_000,
+ follow_redirects: bool = False,
+) -> dict:
+ """Make an HTTP(S) request and return the status, headers, and body.
+
+ Use this tool when you need to call an HTTP API or download a small
+ resource. Private/internal addresses are blocked. Redirects are only
+ followed when ``follow_redirects`` is true (at most three hops), and every
+ hop is re-validated. Credentials (``Authorization``, ``Cookie``,
+ ``Proxy-Authorization``, and any ``env:``-resolved header) are dropped when
+ a redirect changes origin or downgrades to http. Set a header value to
+ ``env:NAME`` to read a secret from environment variable ``NAME`` without
+ exposing it in the arguments.
+
+ Args:
+ url: The absolute http(s) URL to request.
+ method: One of GET, POST, PUT, PATCH, DELETE, HEAD (case-insensitive).
+ headers: Optional request headers. ``env:NAME`` values are resolved from
+ the environment.
+ params: Optional query parameters.
+ json_body: Optional JSON-serializable request body.
+ body: Optional raw string request body. Mutually exclusive with
+ ``json_body``.
+ timeout: Request timeout in seconds (1-120).
+ max_bytes: Maximum response body size in bytes (1,000-20,000,000).
+ Larger bodies are truncated and ``truncated`` is set to true.
+ follow_redirects: Whether to follow 301/302/303/307/308 redirects.
+
+ Returns:
+ A dict with ``status_code``, ``url``, ``headers``, ``content_type``,
+ ``body``, ``bytes``, and ``truncated``. On failure, a dict with an
+ ``error`` key.
+ """
+ try:
+ return _run(
+ url,
+ method,
+ headers,
+ params,
+ json_body,
+ body,
+ timeout,
+ max_bytes,
+ follow_redirects,
+ )
+ except _RequestAborted as exc:
+ return {"error": str(exc)}
+ except Exception as exc: # noqa: BLE001 - tool results must not raise
+ # Do not interpolate the exception text: it may contain request headers.
+ return {"error": f"request failed ({type(exc).__name__})"}
diff --git a/veadk/tools/builtin_tools/image_transform.py b/veadk/tools/builtin_tools/image_transform.py
new file mode 100644
index 000000000..b63fa790e
--- /dev/null
+++ b/veadk/tools/builtin_tools/image_transform.py
@@ -0,0 +1,424 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Transform a local or remote image with Pillow and save the result."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import os
+import re
+import tempfile
+from io import BytesIO
+from pathlib import Path
+from urllib.parse import urljoin, urlparse
+
+import httpx
+from google.adk.tools import ToolContext
+from google.genai import types
+from PIL import Image, ImageOps
+
+from veadk.tools.builtin_tools.web_fetch import assert_public_url
+
+_MAX_OPERATIONS = 20
+_MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024
+# Pillow's decompression-bomb guard only protects input decoding; upscaling via
+# resize/rotate allocates the output bitmap directly, so bound it explicitly.
+_MAX_OUTPUT_PIXELS = 40_000_000
+_MAX_REDIRECTS = 3
+_DOWNLOAD_TIMEOUT_SECONDS = 30
+_USER_AGENT = "VeADK-ImageTransform/1.0"
+
+# format -> (Pillow format, file extension, MIME type)
+_FORMATS: dict[str, tuple[str, str, str]] = {
+ "png": ("PNG", "png", "image/png"),
+ "jpeg": ("JPEG", "jpg", "image/jpeg"),
+ "webp": ("WEBP", "webp", "image/webp"),
+}
+
+
+def _normalize_format(value: object) -> str:
+ if not isinstance(value, str):
+ raise ValueError("format must be one of: png, jpeg, webp")
+ normalized = value.strip().lower()
+ if normalized == "jpg":
+ normalized = "jpeg"
+ if normalized not in _FORMATS:
+ raise ValueError("format must be one of: png, jpeg, webp")
+ return normalized
+
+
+def _detect_source_format(image: Image.Image) -> str:
+ source_format = (image.format or "").lower()
+ if source_format == "jpg":
+ source_format = "jpeg"
+ return source_format if source_format in _FORMATS else "png"
+
+
+def _safe_filename(filename: str | None, extension: str) -> str:
+ value = Path(filename.strip()).name if isinstance(filename, str) else ""
+ stem = Path(value).stem if value else "image"
+ stem = re.sub(r"[^\w一-鿿.-]+", "-", stem).strip("-._")[:100]
+ return f"{stem or 'image'}.{extension}"
+
+
+def _positive_int(value: object, name: str) -> int:
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+ raise ValueError(f"{name} must be a positive integer")
+ return value
+
+
+def _integer(value: object, name: str) -> int:
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise ValueError(f"{name} must be an integer")
+ return value
+
+
+def _number(value: object, name: str) -> float:
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ raise ValueError(f"{name} must be a number")
+ return float(value)
+
+
+async def _download_url(url: str) -> bytes:
+ current = url
+ redirects = 0
+ headers = {"User-Agent": _USER_AGENT}
+ async with httpx.AsyncClient(
+ timeout=_DOWNLOAD_TIMEOUT_SECONDS, follow_redirects=False
+ ) as client:
+ while True:
+ # DNS resolution blocks; keep it off the event loop.
+ await asyncio.to_thread(assert_public_url, current)
+ async with client.stream("GET", current, headers=headers) as response:
+ if response.is_redirect:
+ location = response.headers.get("location")
+ if not location:
+ raise ValueError("redirect response did not include a location")
+ if redirects >= _MAX_REDIRECTS:
+ raise ValueError(f"too many redirects (>{_MAX_REDIRECTS})")
+ current = urljoin(current, location)
+ redirects += 1
+ continue
+ if response.status_code >= 400:
+ raise ValueError(
+ f"failed to download image: HTTP {response.status_code}"
+ )
+ declared_length = response.headers.get("content-length")
+ if declared_length is not None:
+ try:
+ declared_bytes = int(declared_length)
+ except (TypeError, ValueError):
+ declared_bytes = 0
+ if declared_bytes > _MAX_DOWNLOAD_BYTES:
+ raise ValueError(
+ f"image exceeds the {_MAX_DOWNLOAD_BYTES} byte limit"
+ )
+ # Stream with a hard cap: Content-Length is advisory and may be
+ # absent or wrong, so never buffer an unbounded response.
+ chunks: list[bytes] = []
+ total = 0
+ async for chunk in response.aiter_bytes():
+ if not chunk:
+ continue
+ total += len(chunk)
+ if total > _MAX_DOWNLOAD_BYTES:
+ raise ValueError(
+ f"image exceeds the {_MAX_DOWNLOAD_BYTES} byte limit"
+ )
+ chunks.append(chunk)
+ return b"".join(chunks)
+
+
+async def _read_source(source: str) -> bytes:
+ if "://" in source:
+ parsed = urlparse(source)
+ if parsed.scheme not in ("http", "https"):
+ raise ValueError("only http(s) URLs are supported")
+ return await _download_url(source)
+ path = Path(source)
+ if not path.is_file():
+ raise ValueError(f"image file does not exist: {source}")
+ # Match the download cap so a huge local file cannot exhaust memory.
+ with path.open("rb") as handle:
+ data = handle.read(_MAX_DOWNLOAD_BYTES + 1)
+ if len(data) > _MAX_DOWNLOAD_BYTES:
+ raise ValueError(f"image exceeds the {_MAX_DOWNLOAD_BYTES} byte limit")
+ return data
+
+
+def _load_image(data: bytes) -> Image.Image:
+ try:
+ image = Image.open(BytesIO(data))
+ image.load()
+ except Exception as e:
+ raise ValueError(f"unable to decode image: {e}") from e
+ return image
+
+
+def _normalize_mode(image: Image.Image) -> Image.Image:
+ has_alpha = (
+ "A" in image.getbands()
+ or image.mode in ("RGBA", "LA")
+ or (image.mode == "P" and "transparency" in image.info)
+ )
+ return image.convert("RGBA" if has_alpha else "RGB")
+
+
+def _check_output_size(width: int, height: int) -> None:
+ """Reject outputs whose bitmap would be unreasonably large."""
+ if width * height <= _MAX_OUTPUT_PIXELS:
+ return
+ raise ValueError(
+ f"output image would be {width}x{height} ({width * height} pixels), "
+ f"exceeding the {_MAX_OUTPUT_PIXELS} pixel limit"
+ )
+
+
+def _rotated_size(width: int, height: int, degrees: float) -> tuple[int, int]:
+ """Predicted canvas size of ``rotate(expand=True)`` without allocating it."""
+ angle = math.radians(degrees % 360.0)
+ cos = abs(math.cos(angle))
+ sin = abs(math.sin(angle))
+ # Truncate float noise (cos(90°) is 6e-17, not 0) before rounding up.
+ return (
+ max(1, math.ceil(width * cos + height * sin - 1e-9)),
+ max(1, math.ceil(width * sin + height * cos - 1e-9)),
+ )
+
+
+def _op_resize(image: Image.Image, operation: dict) -> Image.Image:
+ width_value = operation.get("width")
+ height_value = operation.get("height")
+ if width_value is None and height_value is None:
+ raise ValueError("resize requires width and/or height")
+ width = None if width_value is None else _positive_int(width_value, "width")
+ height = None if height_value is None else _positive_int(height_value, "height")
+ keep_aspect = operation.get("keep_aspect", True)
+ if not isinstance(keep_aspect, bool):
+ raise ValueError("keep_aspect must be a boolean")
+ if width is None:
+ width = max(1, round(image.width * height / image.height))
+ _check_output_size(width, height)
+ return image.resize((width, height))
+ if height is None:
+ height = max(1, round(image.height * width / image.width))
+ _check_output_size(width, height)
+ return image.resize((width, height))
+ _check_output_size(width, height)
+ if keep_aspect:
+ return ImageOps.contain(image, (width, height))
+ return image.resize((width, height))
+
+
+def _op_crop(image: Image.Image, operation: dict) -> Image.Image:
+ left = _integer(operation.get("left"), "left")
+ top = _integer(operation.get("top"), "top")
+ right = _integer(operation.get("right"), "right")
+ bottom = _integer(operation.get("bottom"), "bottom")
+ if (
+ left < 0
+ or top < 0
+ or right > image.width
+ or bottom > image.height
+ or left >= right
+ or top >= bottom
+ ):
+ raise ValueError("crop box must be inside the image bounds")
+ return image.crop((left, top, right, bottom))
+
+
+def _op_rotate(image: Image.Image, operation: dict) -> Image.Image:
+ degrees = _number(operation.get("degrees"), "degrees")
+ # Check the expanded canvas before Pillow allocates it.
+ _check_output_size(*_rotated_size(image.width, image.height, degrees))
+ fill = (0, 0, 0, 0) if image.mode == "RGBA" else "white"
+ return image.rotate(degrees, expand=True, fillcolor=fill)
+
+
+def _op_flip(image: Image.Image, operation: dict) -> Image.Image:
+ direction = operation.get("direction")
+ if not isinstance(direction, str):
+ raise ValueError("flip direction must be 'horizontal' or 'vertical'")
+ if direction.strip().lower() == "horizontal":
+ return image.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
+ if direction.strip().lower() == "vertical":
+ return image.transpose(Image.Transpose.FLIP_TOP_BOTTOM)
+ raise ValueError("flip direction must be 'horizontal' or 'vertical'")
+
+
+def _op_thumbnail(image: Image.Image, operation: dict) -> Image.Image:
+ max_size = _positive_int(operation.get("max_size"), "max_size")
+ image.thumbnail((max_size, max_size))
+ return image
+
+
+def _apply_operations(
+ image: Image.Image, operations: list[dict]
+) -> tuple[Image.Image, str | None]:
+ format_override: str | None = None
+ for operation in operations:
+ if not isinstance(operation, dict):
+ raise ValueError("each operation must be a dict")
+ operation_type = operation.get("type")
+ if not isinstance(operation_type, str):
+ raise ValueError("each operation requires a string 'type'")
+ operation_type = operation_type.strip().lower()
+ if operation_type == "resize":
+ image = _op_resize(image, operation)
+ elif operation_type == "crop":
+ image = _op_crop(image, operation)
+ elif operation_type == "rotate":
+ image = _op_rotate(image, operation)
+ elif operation_type == "flip":
+ image = _op_flip(image, operation)
+ elif operation_type == "thumbnail":
+ image = _op_thumbnail(image, operation)
+ elif operation_type == "grayscale":
+ image = image.convert("L")
+ elif operation_type == "convert":
+ format_override = _normalize_format(operation.get("format"))
+ else:
+ raise ValueError(f"unsupported operation type: {operation_type!r}")
+ return image, format_override
+
+
+def _flatten_to_rgb(image: Image.Image) -> Image.Image:
+ if "A" in image.getbands() or (image.mode == "P" and "transparency" in image.info):
+ rgba = image.convert("RGBA")
+ background = Image.new("RGB", rgba.size, "white")
+ background.paste(rgba, mask=rgba.getchannel("A"))
+ return background
+ if image.mode != "RGB":
+ return image.convert("RGB")
+ return image
+
+
+def _encode_image(image: Image.Image, image_format: str, quality: int) -> bytes:
+ pillow_format = _FORMATS[image_format][0]
+ if image_format == "jpeg":
+ image = _flatten_to_rgb(image)
+ params: dict[str, object] = {}
+ if image_format in ("jpeg", "webp"):
+ params["quality"] = quality
+ buffer = BytesIO()
+ image.save(buffer, format=pillow_format, **params)
+ return buffer.getvalue()
+
+
+def _write_temp_file(data: bytes, extension: str) -> str:
+ file_descriptor, path = tempfile.mkstemp(
+ prefix="veadk-image-", suffix=f".{extension}"
+ )
+ with os.fdopen(file_descriptor, "wb") as handle:
+ handle.write(data)
+ return path
+
+
+async def image_transform(
+ source: str,
+ operations: list[dict],
+ output_format: str | None = None,
+ quality: int = 90,
+ filename: str | None = None,
+ tool_context: ToolContext | None = None,
+) -> dict:
+ """Apply ordered Pillow operations to an image and save the result.
+
+ ``source`` may be a local path or an http(s) URL. Operations are applied in
+ order; each item is a dict with a ``type``:
+
+ - ``resize``: ``width`` and/or ``height`` (positive ints). When only one
+ side is given the aspect ratio is preserved. With both sides and
+ ``keep_aspect`` true (default) the image fits inside the box. The output
+ canvas may not exceed 40,000,000 pixels.
+ - ``crop``: ``left``, ``top``, ``right``, ``bottom`` pixel coordinates.
+ - ``rotate``: ``degrees`` (float), expanding the canvas and filling with
+ white (RGB) or transparency (RGBA); the expanded canvas is subject to the
+ same pixel limit.
+ - ``flip``: ``direction`` equal to ``horizontal`` or ``vertical``.
+ - ``thumbnail``: ``max_size`` (positive int), preserving aspect ratio.
+ - ``grayscale``: converts the image to grayscale.
+ - ``convert``: ``format`` of ``png``, ``jpeg`` or ``webp``; the output
+ format is applied after every operation.
+
+ Args:
+ source: Local image path or public http(s) URL.
+ operations: Ordered list of operation dicts (at most 20).
+ output_format: png, jpeg or webp. Defaults to the source format when it
+ is png/jpeg/webp, otherwise png.
+ quality: Encoder quality from 1 to 100 for jpeg/webp only.
+ filename: Optional output filename; sanitized with the right extension.
+ tool_context: Current ADK tool context used to save the result artifact.
+
+ Returns:
+ A dict with filename, format, width, height, size_bytes, mime_type,
+ artifact_saved and path. On failure, a dict with an ``error`` key.
+ """
+ try:
+ if not isinstance(source, str) or not source.strip():
+ raise ValueError("source is required")
+ if not isinstance(operations, list):
+ raise ValueError("operations must be a list")
+ if not operations:
+ raise ValueError("operations must not be empty")
+ if len(operations) > _MAX_OPERATIONS:
+ raise ValueError(f"at most {_MAX_OPERATIONS} operations are allowed")
+ if isinstance(quality, bool) or not isinstance(quality, int):
+ raise ValueError("quality must be an integer between 1 and 100")
+ if not 1 <= quality <= 100:
+ raise ValueError("quality must be an integer between 1 and 100")
+
+ data = await _read_source(source.strip())
+ image = _load_image(data)
+ source_format = _detect_source_format(image)
+ image = _normalize_mode(image)
+ image, format_override = _apply_operations(image, operations)
+
+ if output_format is not None:
+ image_format = _normalize_format(output_format)
+ elif format_override is not None:
+ image_format = format_override
+ else:
+ image_format = source_format
+
+ _, extension, mime_type = _FORMATS[image_format]
+ artifact_name = _safe_filename(filename, extension)
+ encoded = _encode_image(image, image_format, quality)
+
+ result: dict[str, object] = {
+ "filename": artifact_name,
+ "format": image_format,
+ "width": image.width,
+ "height": image.height,
+ "size_bytes": len(encoded),
+ "mime_type": mime_type,
+ "artifact_saved": False,
+ "path": None,
+ }
+ if tool_context is None:
+ result["path"] = _write_temp_file(encoded, extension)
+ else:
+ artifact = types.Part.from_bytes(data=encoded, mime_type=mime_type)
+ if artifact.inline_data is not None:
+ artifact.inline_data.display_name = artifact_name
+ await tool_context.save_artifact(artifact_name, artifact)
+ result["artifact_saved"] = True
+ return result
+ except Exception as e:
+ return {"error": str(e)}
+
+
+__all__ = ["image_transform"]
diff --git a/veadk/tools/builtin_tools/image_understand.py b/veadk/tools/builtin_tools/image_understand.py
new file mode 100644
index 000000000..118bb3b55
--- /dev/null
+++ b/veadk/tools/builtin_tools/image_understand.py
@@ -0,0 +1,42 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Understand images with the configured vision model."""
+
+from __future__ import annotations
+
+from veadk.tools.builtin_tools.vision import analyze_images
+
+
+async def image_understand(
+ images: list[str],
+ prompt: str = "Describe the image in detail.",
+ model_name: str | None = None,
+) -> dict:
+ """Describe one or more images in detail with a vision model.
+
+ Args:
+ images: Local image paths or public http(s) URLs (1 to 8 items).
+ prompt: What to ask about the images. The default requests a detailed
+ description covering objects, text, layout and notable details.
+ model_name: Optional vision model override.
+
+ Returns:
+ ``{"text": ..., "model": ...}`` on success, otherwise
+ ``{"error": ...}``.
+ """
+ return await analyze_images(images, prompt, model_name)
+
+
+__all__ = ["image_understand"]
diff --git a/veadk/tools/builtin_tools/mindmap_generate.py b/veadk/tools/builtin_tools/mindmap_generate.py
new file mode 100644
index 000000000..a707a87af
--- /dev/null
+++ b/veadk/tools/builtin_tools/mindmap_generate.py
@@ -0,0 +1,346 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Turn a Markdown outline into a Mermaid mindmap and a standalone SVG."""
+
+from __future__ import annotations
+
+import html
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from google.adk.tools import ToolContext
+from google.genai import types
+
+_MAX_NODES = 500
+_MAX_DEPTH = 8
+_MAX_LABEL_LENGTH = 80
+
+_MERMAID_MIME_TYPE = "text/plain"
+_SVG_MIME_TYPE = "image/svg+xml"
+_DEFAULT_STEM = "mindmap"
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*)$")
+_BULLET_RE = re.compile(r"^(\s*)[-*+]\s+(.*)$")
+_FILENAME_RE = re.compile(r"[^A-Za-z0-9._\-一-鿿]+")
+
+# Mermaid mindmap labels break on these structural characters.
+_MERMAID_TRANSLATION = str.maketrans(
+ {"(": " ", ")": " ", "[": " ", "]": " ", "{": " ", "}": " ", '"': " "}
+)
+
+_NODE_HEIGHT = 36
+_NODE_MIN_WIDTH = 80
+_NODE_MAX_WIDTH = 260
+_HORIZONTAL_GAP = 24
+_VERTICAL_GAP = 48
+_MARGIN = 32
+_FONT_SIZE = 13
+
+
+@dataclass
+class _Node:
+ label: str
+ depth: int
+ children: list["_Node"] = field(default_factory=list)
+
+
+def _clean_label(value: object) -> str:
+ text = str(value or "").replace("\r", " ").replace("\n", " ")
+ text = re.sub(r"\s+", " ", text).strip()
+ return text[:_MAX_LABEL_LENGTH]
+
+
+def _parse_markdown(title: str, markdown: str) -> _Node:
+ root = _Node(_clean_label(title) or "Mindmap", 0)
+ node_count = 1
+ heading_stack: list[tuple[int, _Node]] = []
+ bullet_stack: list[tuple[int, _Node]] = []
+
+ for raw_line in markdown.splitlines():
+ if node_count >= _MAX_NODES:
+ break
+ line = raw_line.rstrip()
+ if not line.strip():
+ continue
+
+ heading = _HEADING_RE.match(line.strip())
+ if heading:
+ level = len(heading.group(1))
+ label = _clean_label(heading.group(2))
+ while heading_stack and heading_stack[-1][0] >= level:
+ heading_stack.pop()
+ parent = heading_stack[-1][1] if heading_stack else root
+ node = _Node(label, parent.depth + 1)
+ if node.depth <= _MAX_DEPTH:
+ parent.children.append(node)
+ node_count += 1
+ heading_stack.append((level, node))
+ bullet_stack.clear()
+ continue
+
+ bullet = _BULLET_RE.match(line)
+ if bullet:
+ indent = len(bullet.group(1).expandtabs(2)) // 2
+ label = _clean_label(bullet.group(2))
+ while bullet_stack and bullet_stack[-1][0] >= indent:
+ bullet_stack.pop()
+ if bullet_stack:
+ parent = bullet_stack[-1][1]
+ elif heading_stack:
+ parent = heading_stack[-1][1]
+ else:
+ parent = root
+ node = _Node(label, parent.depth + 1)
+ if node.depth <= _MAX_DEPTH:
+ parent.children.append(node)
+ node_count += 1
+ bullet_stack.append((indent, node))
+ continue
+ # Plain text lines are not part of the outline.
+
+ return root
+
+
+def _mermaid_label(value: str) -> str:
+ text = value.translate(_MERMAID_TRANSLATION)
+ text = re.sub(r"\s+", " ", text).strip()
+ return text[:_MAX_LABEL_LENGTH] or "-"
+
+
+def _render_mermaid(root: _Node) -> str:
+ lines = ["mindmap", f" root(({_mermaid_label(root.label)}))"]
+
+ def walk(node: _Node, depth: int) -> None:
+ for child in node.children:
+ lines.append(f"{' ' * (depth + 1)}{_mermaid_label(child.label)}")
+ walk(child, depth + 1)
+
+ walk(root, 1)
+ return "\n".join(lines)
+
+
+def _display_label(node: _Node) -> str:
+ return _mermaid_label(node.label)
+
+
+def _node_width(node: _Node) -> int:
+ text_width = int(len(_display_label(node)) * 7.5) + 24
+ return max(_NODE_MIN_WIDTH, min(_NODE_MAX_WIDTH, text_width))
+
+
+def _subtree_width(node: _Node) -> int:
+ if not node.children:
+ return _node_width(node)
+ children_width = sum(_subtree_width(child) for child in node.children)
+ children_width += _HORIZONTAL_GAP * (len(node.children) - 1)
+ return max(_node_width(node), children_width)
+
+
+def _tree_depth(node: _Node) -> int:
+ if not node.children:
+ return 0
+ return 1 + max(_tree_depth(child) for child in node.children)
+
+
+def _xml_escape(value: str) -> str:
+ cleaned = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", value)
+ return html.escape(cleaned, quote=True)
+
+
+def _render_svg(root: _Node) -> str:
+ positions: dict[int, tuple[float, float]] = {}
+
+ def assign(node: _Node, left: float, depth: int) -> None:
+ subtree = float(_subtree_width(node))
+ center_y = _MARGIN + depth * (_NODE_HEIGHT + _VERTICAL_GAP) + _NODE_HEIGHT / 2
+ if not node.children:
+ positions[id(node)] = (left + subtree / 2, center_y)
+ return
+ cursor = left
+ for child in node.children:
+ assign(child, cursor, depth + 1)
+ cursor += _subtree_width(child) + _HORIZONTAL_GAP
+ first = positions[id(node.children[0])][0]
+ last = positions[id(node.children[-1])][0]
+ own_width = float(_node_width(node))
+ center_x = (first + last) / 2
+ center_x = max(
+ left + own_width / 2, min(center_x, left + subtree - own_width / 2)
+ )
+ positions[id(node)] = (center_x, center_y)
+
+ assign(root, _MARGIN, 0)
+
+ width = _subtree_width(root) + 2 * _MARGIN
+ depth = _tree_depth(root)
+ height = 2 * _MARGIN + (depth + 1) * _NODE_HEIGHT + depth * _VERTICAL_GAP
+
+ parts = [
+ '',
+ (
+ f'")
+ return "\n".join(parts)
+
+
+def _sanitize_stem(filename: str | None) -> str:
+ if not isinstance(filename, str) or not filename.strip():
+ return _DEFAULT_STEM
+ name = filename.strip().replace("\\", "/").rsplit("/", 1)[-1]
+ name = _FILENAME_RE.sub("-", name).strip(".-")
+ stem = name.rsplit(".", 1)[0] if "." in name else name
+ stem = stem.strip(".-")
+ return (stem or _DEFAULT_STEM)[:100]
+
+
+def _count_nodes(node: _Node) -> int:
+ return 1 + sum(_count_nodes(child) for child in node.children)
+
+
+async def mindmap_generate(
+ title: str,
+ markdown: str,
+ filename: str | None = None,
+ tool_context: ToolContext | None = None,
+) -> dict:
+ """Build a Mermaid mindmap and a deterministic SVG from a Markdown outline.
+
+ Headings (``#`` through ``######``) nest by level; ``-``/``*``/``+`` bullets
+ nest by two-space indentation. Blank lines and plain text are ignored.
+
+ Args:
+ title: Root node label.
+ markdown: Outline using headings and/or indented bullets.
+ filename: Optional base filename; ``.mmd`` and ``.svg`` are generated.
+ tool_context: Current ADK tool context. When omitted, both files are
+ written to a temporary directory instead.
+
+ Returns:
+ ``{"title", "mermaid", "mmd_filename", "svg_filename", "nodes",
+ "artifact_saved", "mmd_path", "svg_path"}`` on success, or
+ ``{"error"}`` on failure.
+ """
+ title_text = (
+ title if isinstance(title, str) else ("" if title is None else str(title))
+ )
+ markdown_text = (
+ markdown
+ if isinstance(markdown, str)
+ else ("" if markdown is None else str(markdown))
+ )
+ root = _parse_markdown(title_text, markdown_text)
+ mermaid = _render_mermaid(root)
+ svg = _render_svg(root)
+
+ stem = _sanitize_stem(filename)
+ mmd_name = f"{stem}.mmd"
+ svg_name = f"{stem}.svg"
+ mmd_bytes = mermaid.encode("utf-8")
+ svg_bytes = svg.encode("utf-8")
+
+ result = {
+ "title": root.label,
+ "mermaid": mermaid,
+ "mmd_filename": mmd_name,
+ "svg_filename": svg_name,
+ "nodes": _count_nodes(root),
+ "artifact_saved": False,
+ "mmd_path": None,
+ "svg_path": None,
+ }
+
+ if tool_context is None:
+ directory = tempfile.mkdtemp(prefix="veadk-mindmap-")
+ mmd_path = Path(directory) / mmd_name
+ svg_path = Path(directory) / svg_name
+ try:
+ mmd_path.write_bytes(mmd_bytes)
+ svg_path.write_bytes(svg_bytes)
+ except OSError as exc:
+ return {"error": f"failed to write files: {exc}"}
+ result["mmd_path"] = str(mmd_path)
+ result["svg_path"] = str(svg_path)
+ return result
+
+ try:
+ for name, data, mime_type in (
+ (mmd_name, mmd_bytes, _MERMAID_MIME_TYPE),
+ (svg_name, svg_bytes, _SVG_MIME_TYPE),
+ ):
+ artifact = types.Part.from_bytes(data=data, mime_type=mime_type)
+ if artifact.inline_data is not None:
+ artifact.inline_data.display_name = name
+ await tool_context.save_artifact(name, artifact)
+ except Exception as exc: # noqa: BLE001 - artifact storage failure
+ return {"error": f"failed to save artifact: {exc}"}
+
+ result["artifact_saved"] = True
+ return result
+
+
+__all__ = ["mindmap_generate"]
diff --git a/veadk/tools/builtin_tools/ocr.py b/veadk/tools/builtin_tools/ocr.py
new file mode 100644
index 000000000..f13517fd3
--- /dev/null
+++ b/veadk/tools/builtin_tools/ocr.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Extract text from images with the configured vision model."""
+
+from __future__ import annotations
+
+from veadk.tools.builtin_tools.vision import analyze_images
+
+_BASE_PROMPT = (
+ "Transcribe all text visible in the image exactly as it appears. Return "
+ "only the transcribed text, preserving line breaks and reading order. Do "
+ "not translate, summarize, or add commentary. If the image contains no "
+ "text, return an empty string."
+)
+
+
+async def ocr(
+ image: str,
+ language: str = "auto",
+ model_name: str | None = None,
+) -> dict:
+ """Transcribe text from an image with a vision model.
+
+ Args:
+ image: Local image path or public http(s) URL.
+ language: Expected text language, or ``auto`` to let the model decide.
+ model_name: Optional vision model override.
+
+ Returns:
+ ``{"text": ..., "language": ..., "model": ...}`` on success, otherwise
+ ``{"error": ...}``.
+ """
+ prompt = _BASE_PROMPT
+ if isinstance(language, str) and language.strip().lower() != "auto":
+ prompt = f"{prompt} The text is expected to be in {language.strip()}."
+ result = await analyze_images([image], prompt, model_name)
+ if "error" in result:
+ return result
+ return {
+ "text": result["text"],
+ "language": language,
+ "model": result["model"],
+ }
+
+
+__all__ = ["ocr"]
diff --git a/veadk/tools/builtin_tools/qrcode_generate.py b/veadk/tools/builtin_tools/qrcode_generate.py
new file mode 100644
index 000000000..41898f5c0
--- /dev/null
+++ b/veadk/tools/builtin_tools/qrcode_generate.py
@@ -0,0 +1,142 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generate a QR code image and save it as an ADK artifact."""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from io import BytesIO
+from pathlib import Path
+
+import qrcode
+from google.adk.tools import ToolContext
+from google.genai import types
+from PIL import Image
+from qrcode.constants import ERROR_CORRECT_M
+from qrcode.image.pil import PilImage
+
+_MAX_CONTENT_LENGTH = 2000
+_MAX_BOX_SIZE = 50
+_MAX_BORDER = 20
+_MIME_TYPE = "image/png"
+
+
+def _safe_filename(filename: str) -> str:
+ value = Path(filename.strip()).name if isinstance(filename, str) else ""
+ stem = Path(value).stem if value else "qrcode"
+ stem = re.sub(r"[^\w一-鿿.-]+", "-", stem).strip("-._")[:100]
+ return f"{stem or 'qrcode'}.png"
+
+
+def _positive_int_in_range(value: object, name: str, minimum: int, maximum: int) -> int:
+ if (
+ isinstance(value, bool)
+ or not isinstance(value, int)
+ or not minimum <= value <= maximum
+ ):
+ raise ValueError(f"{name} must be an integer between {minimum} and {maximum}")
+ return value
+
+
+def _render(content: str, box_size: int, border: int, fill: str, back: str) -> bytes:
+ qr = qrcode.QRCode(
+ error_correction=ERROR_CORRECT_M,
+ box_size=box_size,
+ border=border,
+ image_factory=PilImage,
+ )
+ qr.add_data(content)
+ qr.make(fit=True)
+ image = qr.make_image(fill_color=fill, back_color=back).get_image()
+ buffer = BytesIO()
+ image.save(buffer, format="PNG")
+ return buffer.getvalue()
+
+
+def _write_temp_file(data: bytes) -> str:
+ file_descriptor, path = tempfile.mkstemp(prefix="veadk-qrcode-", suffix=".png")
+ with os.fdopen(file_descriptor, "wb") as handle:
+ handle.write(data)
+ return path
+
+
+async def qrcode_generate(
+ content: str,
+ filename: str = "qrcode.png",
+ box_size: int = 10,
+ border: int = 4,
+ fill_color: str = "black",
+ back_color: str = "white",
+ tool_context: ToolContext | None = None,
+) -> dict:
+ """Generate a PNG QR code for text or a URL and save it.
+
+ Args:
+ content: Text or URL to encode (non-empty, at most 2000 characters).
+ filename: Output filename; a .png extension is enforced.
+ box_size: Pixels per QR module, from 1 to 50.
+ border: Quiet-zone size in modules, from 0 to 20.
+ fill_color: Pillow color name or hex value for the dark modules.
+ back_color: Pillow color name or hex value for the background.
+ tool_context: Current ADK tool context used to save the result artifact.
+
+ Returns:
+ A dict with filename, format, width, height, size_bytes, mime_type,
+ artifact_saved and path. On failure, a dict with an ``error`` key.
+ """
+ try:
+ if not isinstance(content, str) or not content.strip():
+ raise ValueError("content must be a non-empty string")
+ if len(content) > _MAX_CONTENT_LENGTH:
+ raise ValueError(
+ f"content must be at most {_MAX_CONTENT_LENGTH} characters"
+ )
+ box_size = _positive_int_in_range(box_size, "box_size", 1, _MAX_BOX_SIZE)
+ border = _positive_int_in_range(border, "border", 0, _MAX_BORDER)
+ if not isinstance(fill_color, str) or not isinstance(back_color, str):
+ raise ValueError("fill_color and back_color must be strings")
+
+ encoded = _render(content, box_size, border, fill_color, back_color)
+ artifact_name = _safe_filename(filename)
+
+ with Image.open(BytesIO(encoded)) as image:
+ width, height = image.size
+
+ result: dict[str, object] = {
+ "filename": artifact_name,
+ "format": "png",
+ "width": width,
+ "height": height,
+ "size_bytes": len(encoded),
+ "mime_type": _MIME_TYPE,
+ "artifact_saved": False,
+ "path": None,
+ }
+ if tool_context is None:
+ result["path"] = _write_temp_file(encoded)
+ else:
+ artifact = types.Part.from_bytes(data=encoded, mime_type=_MIME_TYPE)
+ if artifact.inline_data is not None:
+ artifact.inline_data.display_name = artifact_name
+ await tool_context.save_artifact(artifact_name, artifact)
+ result["artifact_saved"] = True
+ return result
+ except Exception as e:
+ return {"error": str(e)}
+
+
+__all__ = ["qrcode_generate"]
diff --git a/veadk/tools/builtin_tools/speech_to_text.py b/veadk/tools/builtin_tools/speech_to_text.py
new file mode 100644
index 000000000..f27de77ea
--- /dev/null
+++ b/veadk/tools/builtin_tools/speech_to_text.py
@@ -0,0 +1,200 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Transcribe an audio file with the Volcengine flash ASR API.
+
+The flash endpoint returns the transcript in the same request, so no task
+polling is required. Local files are sent as base64; public URLs are passed
+through for the service to download.
+"""
+
+from __future__ import annotations
+
+import base64
+import uuid
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from veadk.config import getenv, settings
+from veadk.tools.builtin_tools.web_fetch import assert_public_url
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_ENDPOINT = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/recognize/flash"
+_RESOURCE_ID = "volc.bigasr.auc_turbo"
+_MAX_AUDIO_BYTES = 100 * 1024 * 1024
+_SUPPORTED_SUFFIXES = {".wav", ".mp3", ".ogg", ".opus"}
+_MAX_UTTERANCES = 200
+
+_STATUS_MESSAGES = {
+ "20000003": "the audio contains no speech",
+ "45000001": "invalid request parameters",
+ "45000002": "the audio is empty",
+ "45000151": "unsupported audio format (use wav, mp3, ogg, or opus)",
+ "55000031": "the ASR service is busy; retry later",
+}
+
+
+def _resolve_api_key() -> str:
+ """Return the speech API key, or an empty string when none is configured."""
+ for env_name in ("TOOL_SPEECH_TO_TEXT_API_KEY", "TOOL_VESPEECH_API_KEY"):
+ value = getenv(env_name, "", allow_false_values=True)
+ if value:
+ return value
+ try:
+ return settings.tool.vespeech.api_key or ""
+ except Exception as e: # Missing AK/SK must surface as a tool error.
+ logger.debug(f"Unable to resolve the speech API key: {e}")
+ return ""
+
+
+def _load_audio(audio: str) -> dict[str, str]:
+ """Build the ``audio`` request object for a local path or public URL."""
+ if audio.startswith(("http://", "https://")):
+ assert_public_url(audio)
+ return {"url": audio}
+
+ path = Path(audio).expanduser()
+ if not path.is_file():
+ raise ValueError(f"audio file does not exist: {audio}")
+ if path.suffix.lower() not in _SUPPORTED_SUFFIXES:
+ raise ValueError(
+ "unsupported audio format; expected one of: "
+ + ", ".join(sorted(_SUPPORTED_SUFFIXES))
+ )
+ size = path.stat().st_size
+ if size <= 0:
+ raise ValueError("the audio file is empty")
+ if size > _MAX_AUDIO_BYTES:
+ raise ValueError("the audio file exceeds the 100 MB limit")
+ return {"data": base64.b64encode(path.read_bytes()).decode("ascii")}
+
+
+def _parse_response(response: httpx.Response) -> dict[str, Any]:
+ status = response.headers.get("X-Api-Status-Code", "")
+ log_id = response.headers.get("X-Tt-Logid", "")
+ if status != "20000000":
+ message = _STATUS_MESSAGES.get(status) or response.headers.get("X-Api-Message")
+ return {
+ "error": message
+ or f"ASR request failed with status {status or response.status_code}",
+ "code": status or str(response.status_code),
+ "log_id": log_id,
+ }
+
+ try:
+ payload = response.json()
+ except ValueError as e:
+ return {"error": f"invalid ASR response: {e}", "log_id": log_id}
+
+ result = payload.get("result") if isinstance(payload, dict) else None
+ result = result if isinstance(result, dict) else {}
+ text = result.get("text")
+ if not isinstance(text, str):
+ text = ""
+
+ utterances: list[dict[str, Any]] = []
+ raw_utterances = result.get("utterances")
+ if isinstance(raw_utterances, list):
+ for item in raw_utterances[:_MAX_UTTERANCES]:
+ if not isinstance(item, dict):
+ continue
+ utterances.append(
+ {
+ "start_time": item.get("start_time"),
+ "end_time": item.get("end_time"),
+ "text": item.get("text", ""),
+ }
+ )
+
+ audio_info = payload.get("audio_info") if isinstance(payload, dict) else None
+ duration = audio_info.get("duration") if isinstance(audio_info, dict) else None
+ return {
+ "text": text,
+ "duration_ms": duration,
+ "utterances": utterances,
+ "log_id": log_id,
+ }
+
+
+async def speech_to_text(audio: str, timeout: int = 300) -> dict:
+ """Transcribe speech in an audio file into text.
+
+ Supports local wav/mp3/ogg/opus files (up to 100 MB) and public http(s)
+ audio URLs. The service auto-detects the spoken language.
+
+ Args:
+ audio: Local file path or public http(s) URL of the audio.
+ timeout: Request timeout in seconds, between 1 and 600.
+
+ Returns:
+ A dict with ``text``, ``duration_ms``, ``utterances`` and ``log_id``,
+ or a dict with ``error`` when transcription fails.
+ """
+ if not audio or not isinstance(audio, str):
+ return {"error": "audio must be a non-empty path or URL"}
+ if (
+ isinstance(timeout, bool)
+ or not isinstance(timeout, int)
+ or not 1 <= timeout <= 600
+ ):
+ return {"error": "timeout must be an integer between 1 and 600 seconds"}
+
+ api_key = _resolve_api_key()
+ if not api_key:
+ return {
+ "error": (
+ "Missing speech API key: set TOOL_SPEECH_TO_TEXT_API_KEY "
+ "(or TOOL_VESPEECH_API_KEY)."
+ )
+ }
+
+ try:
+ audio_payload = _load_audio(audio)
+ except ValueError as e:
+ return {"error": str(e)}
+
+ headers = {
+ "X-Api-Key": api_key,
+ "X-Api-Resource-Id": _RESOURCE_ID,
+ "X-Api-Request-Id": str(uuid.uuid4()),
+ "X-Api-Sequence": "-1",
+ "Content-Type": "application/json",
+ }
+ body = {
+ "user": {"uid": "veadk"},
+ "audio": audio_payload,
+ "request": {
+ "model_name": "bigmodel",
+ "enable_itn": True,
+ "enable_punc": True,
+ },
+ }
+
+ try:
+ async with httpx.AsyncClient(timeout=timeout) as client:
+ response = await client.post(_ENDPOINT, headers=headers, json=body)
+ except httpx.HTTPError as e:
+ logger.error(f"speech_to_text request failed: {e}")
+ return {"error": f"ASR request failed: {e}"}
+
+ if response.status_code >= 400 and not response.headers.get("X-Api-Status-Code"):
+ return {
+ "error": f"ASR request failed with HTTP {response.status_code}",
+ "log_id": response.headers.get("X-Tt-Logid", ""),
+ }
+ return _parse_response(response)
diff --git a/veadk/tools/builtin_tools/vision.py b/veadk/tools/builtin_tools/vision.py
new file mode 100644
index 000000000..59a4734f7
--- /dev/null
+++ b/veadk/tools/builtin_tools/vision.py
@@ -0,0 +1,274 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared vision helper for image understanding and OCR tools."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from io import BytesIO
+from pathlib import Path
+
+import filetype
+import httpx
+from PIL import Image
+
+from veadk.config import getenv, settings
+from veadk.tools.builtin_tools.web_fetch import assert_public_url
+
+_MAX_IMAGES = 8
+_MAX_IMAGE_BYTES = 20 * 1024 * 1024
+# Base64 inflates payloads by roughly a third, so a per-image cap alone still
+# allows a ~200 MB request for eight images. Bound the aggregate local payload.
+_MAX_TOTAL_IMAGE_BYTES = 40 * 1024 * 1024
+_DEFAULT_TIMEOUT_SECONDS = 60
+_ERROR_DETAIL_LIMIT = 200
+
+_PILLOW_MIME_TYPES = {
+ "PNG": "image/png",
+ "JPEG": "image/jpeg",
+ "WEBP": "image/webp",
+ "GIF": "image/gif",
+ "BMP": "image/bmp",
+ "TIFF": "image/tiff",
+}
+_EXTENSION_MIME_TYPES = {
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".webp": "image/webp",
+ ".gif": "image/gif",
+ ".bmp": "image/bmp",
+ ".tif": "image/tiff",
+ ".tiff": "image/tiff",
+}
+
+
+def _validate(images: object, prompt: object, timeout: object) -> None:
+ if not isinstance(images, list) or not 1 <= len(images) <= _MAX_IMAGES:
+ raise ValueError(f"images must be a list of 1 to {_MAX_IMAGES} items")
+ for image in images:
+ if not isinstance(image, str) or not image.strip():
+ raise ValueError("each image must be a non-empty path or URL")
+ if not isinstance(prompt, str) or not prompt.strip():
+ raise ValueError("prompt must be a non-empty string")
+ if (
+ isinstance(timeout, bool)
+ or not isinstance(timeout, int)
+ or not 1 <= timeout <= 300
+ ):
+ raise ValueError("timeout must be an integer between 1 and 300")
+
+
+def _is_http_url(value: str) -> bool:
+ lowered = value.lower()
+ return lowered.startswith("http://") or lowered.startswith("https://")
+
+
+def _guess_mime(data: bytes, path: Path | None) -> str:
+ try:
+ with Image.open(BytesIO(data)) as image:
+ if image.format in _PILLOW_MIME_TYPES:
+ return _PILLOW_MIME_TYPES[image.format]
+ except Exception:
+ pass
+ kind = filetype.guess(data)
+ if kind is not None:
+ return kind.mime
+ if path is not None:
+ extension = path.suffix.lower()
+ if extension in _EXTENSION_MIME_TYPES:
+ return _EXTENSION_MIME_TYPES[extension]
+ return "application/octet-stream"
+
+
+def _image_part(image: str) -> tuple[dict, int]:
+ """Build a message part and return its local payload size in bytes.
+
+ Remote URLs are forwarded to the provider, so no local bytes are read and
+ the returned size is 0. Local files are read under the per-image cap and
+ their size is reported so the caller can enforce an aggregate budget.
+ """
+ if _is_http_url(image):
+ # The provider fetches the URL, so apply the shared SSRF policy first:
+ # a model-supplied internal address must never reach the provider.
+ assert_public_url(image)
+ return {"type": "image_url", "image_url": {"url": image}}, 0
+ path = Path(image)
+ if not path.is_file():
+ raise ValueError(f"image file does not exist: {image}")
+ # Bounded read so a huge local file cannot be buffered whole.
+ with path.open("rb") as handle:
+ data = handle.read(_MAX_IMAGE_BYTES + 1)
+ if len(data) > _MAX_IMAGE_BYTES:
+ raise ValueError(f"image exceeds the {_MAX_IMAGE_BYTES} byte limit")
+ mime_type = _guess_mime(data, path)
+ encoded = base64.b64encode(data).decode("ascii")
+ return (
+ {
+ "type": "image_url",
+ "image_url": {"url": f"data:{mime_type};base64,{encoded}"},
+ },
+ len(data),
+ )
+
+
+def _error_detail(response: object) -> str:
+ """Extract a short provider error message so callers can fix the config."""
+ try:
+ payload = response.json() # type: ignore[attr-defined]
+ except Exception:
+ return ""
+ if not isinstance(payload, dict):
+ return ""
+ error = payload.get("error")
+ if isinstance(error, dict):
+ message = error.get("message") or error.get("code")
+ elif isinstance(error, str):
+ message = error
+ else:
+ message = payload.get("message")
+ if not isinstance(message, str):
+ return ""
+ return " ".join(message.split())[:_ERROR_DETAIL_LIMIT]
+
+
+def _resolve_model(model_name: str | None) -> str:
+ model = (
+ model_name
+ or getenv("MODEL_VISION_NAME", "", allow_false_values=True)
+ or settings.model.name
+ )
+ if not isinstance(model, str) or not model.strip():
+ raise ValueError("vision model name is not configured")
+ return model.strip()
+
+
+def _resolve_api_key() -> str:
+ api_key = getenv("MODEL_AGENT_API_KEY", "", allow_false_values=True)
+ if not api_key:
+ api_key = settings.model.api_key
+ if not api_key:
+ raise ValueError("vision model API key is not configured")
+ return str(api_key)
+
+
+def _extract_text(payload: object) -> str | None:
+ if not isinstance(payload, dict):
+ return None
+ choices = payload.get("choices")
+ if not isinstance(choices, list) or not choices:
+ return None
+ first = choices[0]
+ if not isinstance(first, dict):
+ return None
+ message = first.get("message")
+ if not isinstance(message, dict):
+ return None
+ content = message.get("content")
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts = [
+ part.get("text")
+ for part in content
+ if isinstance(part, dict) and isinstance(part.get("text"), str)
+ ]
+ return "".join(parts)
+ return None
+
+
+async def analyze_images(
+ images: list[str],
+ prompt: str,
+ model_name: str | None = None,
+ timeout: int = _DEFAULT_TIMEOUT_SECONDS,
+) -> dict:
+ """Send one or more images to the configured vision model.
+
+ Args:
+ images: Local image paths or public http(s) URLs (1 to 8 items). Remote
+ URLs are SSRF-checked before they are forwarded to the model.
+ Local images are capped at 20,000,000 bytes each and 40,000,000
+ bytes in total.
+ prompt: Instruction for the model.
+ model_name: Optional vision model override. Defaults to
+ ``MODEL_VISION_NAME`` or the agent model name.
+ timeout: Request timeout in seconds (1 to 300).
+
+ Returns:
+ ``{"text": ..., "model": ...}`` on success, otherwise
+ ``{"error": ...}``. The API key is never included in errors.
+ """
+ try:
+ _validate(images, prompt, timeout)
+ model = _resolve_model(model_name)
+ api_key = _resolve_api_key()
+ base_url = settings.model.api_base
+ if not isinstance(base_url, str) or not base_url.strip():
+ raise ValueError("vision model API base is not configured")
+
+ image_parts: list[dict] = []
+ total_bytes = 0
+ for image in images:
+ # Offload blocking DNS lookups and file reads off the event loop.
+ part, size = await asyncio.to_thread(_image_part, image)
+ total_bytes += size
+ if total_bytes > _MAX_TOTAL_IMAGE_BYTES:
+ raise ValueError(
+ f"images exceed the {_MAX_TOTAL_IMAGE_BYTES} byte total limit"
+ )
+ image_parts.append(part)
+ payload = {
+ "model": model,
+ "messages": [
+ {
+ "role": "user",
+ "content": [{"type": "text", "text": prompt}, *image_parts],
+ }
+ ],
+ }
+ url = f"{base_url.rstrip('/')}/chat/completions"
+ headers = {
+ "Authorization": f"Bearer {api_key}",
+ "Content-Type": "application/json",
+ }
+ async with httpx.AsyncClient(timeout=timeout) as client:
+ response = await client.post(url, headers=headers, json=payload)
+
+ if response.status_code >= 400:
+ detail = _error_detail(response)
+ suffix = f": {detail}" if detail else ""
+ return {
+ "error": f"vision request failed with HTTP status "
+ f"{response.status_code}{suffix}"
+ }
+ try:
+ response_payload = response.json()
+ except ValueError:
+ return {"error": "vision response was not valid JSON"}
+ text = _extract_text(response_payload)
+ if text is None:
+ return {"error": "vision response did not contain text content"}
+ return {"text": text, "model": model}
+ except ValueError as e:
+ return {"error": str(e)}
+ except httpx.HTTPError as e:
+ return {"error": f"vision request failed: {e}"}
+ except Exception as e:
+ return {"error": f"vision request failed: {type(e).__name__}: {e}"}
+
+
+__all__ = ["analyze_images"]
diff --git a/veadk/tools/builtin_tools/web_fetch.py b/veadk/tools/builtin_tools/web_fetch.py
index 65c9493cc..c6623c3ae 100644
--- a/veadk/tools/builtin_tools/web_fetch.py
+++ b/veadk/tools/builtin_tools/web_fetch.py
@@ -102,6 +102,24 @@ def _check_url(url: str) -> str:
return parsed.hostname
+def assert_public_url(url: str) -> str:
+ """Validate that *url* is an http(s) URL on a public address.
+
+ This is the reusable guard behind ``web_fetch``; other outbound-HTTP tools
+ such as ``http_request`` use it so SSRF policy stays in one place.
+
+ Returns:
+ The URL hostname.
+
+ Raises:
+ ValueError: If the scheme, host, or resolved address is not allowed.
+ """
+ try:
+ return _check_url(url)
+ except _WebFetchError as e:
+ raise ValueError(str(e)) from e
+
+
# ---------------------------------------------- coarse HTML -> markdown/text --
def _normalize_whitespace(value: str) -> str:
value = value.replace("\r", "")