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"\nplain") + 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]*?]*)?>", + " ", + 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'' + ), + f'', + ] + + def edges(node: _Node) -> None: + parent_x, parent_y = positions[id(node)] + start_y = parent_y + _NODE_HEIGHT / 2 + for child in node.children: + child_x, child_y = positions[id(child)] + end_y = child_y - _NODE_HEIGHT / 2 + middle_y = (start_y + end_y) / 2 + parts.append( + ( + f'' + ) + ) + edges(child) + + edges(root) + + def boxes(node: _Node) -> None: + center_x, center_y = positions[id(node)] + node_width = _node_width(node) + x = center_x - node_width / 2 + y = center_y - _NODE_HEIGHT / 2 + parts.append( + ( + f'' + ) + ) + parts.append( + ( + f'' + f"{_xml_escape(_display_label(node))}" + ) + ) + for child in node.children: + boxes(child) + + boxes(root) + parts.append("") + 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", "")