Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(sdk): expose optional grep traversal depth (#5555)

Zhenghan Song28511a553a2a
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
index 79827345e..4b9d402f0 100644
--- a/docs/en/api/06-retrieval.md
+++ b/docs/en/api/06-retrieval.md
@@ -845,7 +845,7 @@ The `grep()` method performs regex pattern matching search in the file system, u
| case_insensitive | bool | No | False | Ignore case |
| exclude_uri | str | No | None | URI prefix to exclude from search |
| node_limit | int | No | 256 | Maximum number of results. Omitted requests default to 256; pass a larger integer when you need more results |
-| level_limit | int | No | Python SDK: 5; HTTP API / CLI / Go SDK: 10 | Maximum directory depth to traverse. The Go SDK currently uses the HTTP API default. |
+| level_limit | int | No | 10 | Maximum directory depth to traverse. HTTP SDKs use the server default when omitted. |
| tags | string[] | No | Unset | Search only files matching every supplied `k=v` retrieval tag |
| include_tags | bool | No | `false` | Include each matched file's retrieval tags without filtering |
| before_context | int | No | 0 | Number of context lines returned before each match; supported by the HTTP API and CLI |
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
index 6a4b57909..96d9320ad 100644
--- a/docs/zh/api/06-retrieval.md
+++ b/docs/zh/api/06-retrieval.md
@@ -844,7 +844,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \
| case_insensitive | bool | 否 | False | 忽略大小写 |
| node_limit | int | 否 | 256 | 最大返回节点数。省略时默认使用 256;如需更多结果,请显式传入更大的整数 |
| exclude_uri | str | 否 | None | 要排除在搜索之外的 URI 前缀 |
-| level_limit | int | 否 | Python SDK: 5;HTTP API / CLI / Go SDK: 10 | 最大目录遍历深度。Go SDK 当前使用 HTTP API 默认值。 |
+| level_limit | int | 否 | 10 | 最大目录遍历深度。HTTP SDK 未指定时使用服务端默认值。 |
| tags | string[] | 否 | 未设置 | 仅搜索同时匹配全部 `k=v` 检索标签的文件 |
| include_tags | bool | 否 | `false` | 不过滤时也在每条命中中返回检索标签 |
| before_context | int | 否 | 0 | 每条匹配行之前返回的上下文行数;仅 HTTP API 和 CLI 支持 |
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 8debc7bfb..b5afc34c1 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -1551,6 +1551,7 @@ class AsyncHTTPClient:
exclude_uri: Optional[str] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ level_limit: Optional[int] = None,
) -> Dict[str, Any]:
request_json = {
"uri": VikingURI.normalize(uri),
@@ -1558,6 +1559,8 @@ class AsyncHTTPClient:
"case_insensitive": case_insensitive,
"node_limit": node_limit,
}
+ if level_limit is not None:
+ request_json["level_limit"] = level_limit
if exclude_uri is not None:
request_json["exclude_uri"] = VikingURI.normalize(exclude_uri)
if tags is not None:
@@ -2865,6 +2868,7 @@ class SyncHTTPClient:
exclude_uri: Optional[str] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ level_limit: Optional[int] = None,
) -> Dict[str, Any]:
return run_async(
self._async_client.grep(
@@ -2875,6 +2879,7 @@ class SyncHTTPClient:
exclude_uri=exclude_uri,
tags=tags,
include_tags=include_tags,
+ level_limit=level_limit,
)
)
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index d98e307d0..7aa90e2bc 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -1,10 +1,12 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
+import json
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import AsyncMock, Mock, patch
+import httpx
import pytest
from openviking_sdk import (
AsyncHTTPClient,
@@ -1325,6 +1327,40 @@ async def test_search_uses_session_wrapper_session_id_in_payload():
)
[email protected]("sync", [False, True])
[email protected]("level_limit", [None, 0, 1])
+async def test_grep_sends_optional_depth_through_public_clients(sync, level_limit):
+ requests = []
+
+ def handle(request):
+ requests.append(request)
+ return httpx.Response(200, json={"status": "ok", "result": {"matches": []}})
+
+ client = (SyncHTTPClient if sync else AsyncHTTPClient)(url="http://localhost:1933")
+ async_client = client._async_client if sync else client
+ async_client._http = httpx.AsyncClient(
+ base_url="http://localhost:1933", transport=httpx.MockTransport(handle)
+ )
+ kwargs = {} if level_limit is None else {"level_limit": level_limit}
+ try:
+ if sync:
+ result = client.grep("viking://resources", "needle", **kwargs)
+ else:
+ result = await client.grep("viking://resources", "needle", **kwargs)
+ assert result == {"matches": []}
+ assert len(requests) == 1
+ assert requests[0].method == "POST"
+ assert requests[0].url.path == "/api/v1/search/grep"
+ payload = json.loads(requests[0].content)
+ if level_limit is None:
+ assert "level_limit" not in payload
+ else:
+ assert payload["level_limit"] == level_limit
+ finally:
+ await async_client.close()
+
+
@pytest.mark.asyncio
async def test_grep_normalizes_uri_and_exclude_uri():
client = AsyncHTTPClient(url="http://localhost:1933")