feat(sdk): sync go/ts/python SDKs with server find/search, recall, an…

benchmark/RAG/src/core/vector_store.py

@@ -27,19 +27,17 @@ def count_tokens(self, text: str) -> int:
             return 0
         return len(self.enc.encode(str(text)))
 
-    def ingest(self, samples: List[StandardDoc], max_workers=10, monitor=None, ingest_mode="per_file") -> dict:
+    def ingest(
+        self, samples: List[StandardDoc], max_workers=10, monitor=None, ingest_mode="per_file"
+    ) -> dict:
         start_time = time.time()
         total_input_tokens = 0
         total_output_tokens = 0
         total_embedding_tokens = 0
-        
+
         if not samples:
-            return {
-                "time": time.time() - start_time,
-                "input_tokens": 0,
-                "output_tokens": 0
-            }
-
+            return {"time": time.time() - start_time, "input_tokens": 0, "output_tokens": 0}
+
         if ingest_mode == "directory":
             doc_paths = [os.path.abspath(s.doc_path) for s in samples]
             common_ancestor = None
@@ -48,9 +46,12 @@ def ingest(self, samples: List[StandardDoc], max_workers=10, monitor=None, inges
                     common_ancestor = os.path.commonpath(doc_paths)
                 except ValueError:
                     common_ancestor = None
-            
+
             if common_ancestor:
-                result = self.client.add_resource(common_ancestor, wait=True, telemetry=True)
+                result = self.client.add_resource(
+                    path=common_ancestor,
+                    options={"wait": True, "telemetry": True},
+                )
                 telemetry = result.get("telemetry", {})
                 summary = telemetry.get("summary", {})
                 tokens = summary.get("tokens", {})
@@ -61,7 +62,10 @@ def ingest(self, samples: List[StandardDoc], max_workers=10, monitor=None, inges
                 total_embedding_tokens = embedding_tokens.get("total", 0)
             else:
                 for sample in samples:
-                    result = self.client.add_resource(sample.doc_path, wait=True, telemetry=True)
+                    result = self.client.add_resource(
+                        path=sample.doc_path,
+                        options={"wait": True, "telemetry": True},
+                    )
                     telemetry = result.get("telemetry", {})
                     summary = telemetry.get("summary", {})
                     tokens = summary.get("tokens", {})
@@ -72,7 +76,10 @@ def ingest(self, samples: List[StandardDoc], max_workers=10, monitor=None, inges
                     total_embedding_tokens += embedding_tokens.get("total", 0)
         else:
             for sample in samples:
-                result = self.client.add_resource(sample.doc_path, wait=True, telemetry=True)
+                result = self.client.add_resource(
+                    path=sample.doc_path,
+                    options={"wait": True, "telemetry": True},
+                )
                 telemetry = result.get("telemetry", {})
                 summary = telemetry.get("summary", {})
                 tokens = summary.get("tokens", {})
@@ -86,12 +93,15 @@ def ingest(self, samples: List[StandardDoc], max_workers=10, monitor=None, inges
             "time": time.time() - start_time,
             "input_tokens": total_input_tokens,
             "output_tokens": total_output_tokens,
-            "embedding_tokens": total_embedding_tokens
+            "embedding_tokens": total_embedding_tokens,
         }
 
     def retrieve(self, query: str, topk: int, target_uri: str = "viking://resources"):
         """Execute retrieval"""
-        return self.client.find(query=query, limit=topk, target_uri=target_uri)
+        return self.client.find(
+            query=query,
+            options={"limit": topk, "target_uri": target_uri},
+        )
 
     def read_resource(self, uri: str) -> str:
         """Read resource content"""

benchmark/retrieval/grep/vikingdb_bm25/effectiveness/step1_add_resource.py

@@ -48,16 +48,18 @@ def main():
     t0 = time.monotonic()
     try:
         try:
-            client.mkdir(args.parent)
+            client.mkdir(uri=args.parent)
         except OpenVikingError as exc:
             if exc.code != "ALREADY_EXISTS":
                 raise
         result = client.add_resource(
             path=source,
-            parent=args.parent,
-            reason="benchmark effectiveness",
-            wait=True,
-            processing_mode="semantic_and_vectors",
+            options={
+                "parent": args.parent,
+                "reason": "benchmark effectiveness",
+                "wait": True,
+                "processing_mode": "semantic_and_vectors",
+            },
         )
         elapsed = time.monotonic() - t0
         root_uri = result.get("root_uri", "?")

benchmark/retrieval/grep/vikingdb_bm25/performance/step1_add_resource.py

@@ -111,16 +111,18 @@ def main():
             t0 = time.monotonic()
             try:
                 try:
-                    client.mkdir(parent_uri)
+                    client.mkdir(uri=parent_uri)
                 except OpenVikingError as exc:
                     if exc.code != "ALREADY_EXISTS":
                         raise
                 result = client.add_resource(
                     path=dir_path,
-                    parent=parent_uri,
-                    reason=f"benchmark perf: {rel_dir}",
-                    wait=True,
-                    processing_mode="vectors_only",
+                    options={
+                        "parent": parent_uri,
+                        "reason": f"benchmark perf: {rel_dir}",
+                        "wait": True,
+                        "processing_mode": "vectors_only",
+                    },
                 )
                 elapsed = time.monotonic() - t0
                 root_uri = result.get("root_uri", "?")

docs/en/api/02-resources.md

@@ -333,75 +333,87 @@ client.initialize()
 
 # Add local file
 result = client.add_resource(
-    "./documents/guide.md",
-    reason="User guide documentation"
+    path="./documents/guide.md",
+    options={"reason": "User guide documentation"},
 )
 print(f"Added: {result['root_uri']}")
 
 # Parse each document to Markdown without splitting its body
 result = client.add_resource(
-    "./documents",
-    args={"parse_mode": "no_split"},
+    path="./documents",
+    options={"args": {"parse_mode": "no_split"}},
 )
 
 # Add from URL to specific location
 result = client.add_resource(
-    "https://example.com/api-docs.md",
-    to="viking://resources/external/api-docs.md",
-    reason="External API documentation"
+    path="https://example.com/api-docs.md",
+    options={
+        "to": "viking://resources/external/api-docs.md",
+        "reason": "External API documentation",
+    },
 )
 
 # Recursively crawl a site (same-host BFS; depth levels, max_pages cap)
 result = client.add_resource(
-    "https://docs.openviking.ai/getting-started/01-introduction",
-    wait=True,
-    timeout=180,
-    args={"depth": 1, "max_pages": 10},
+    path="https://docs.openviking.ai/getting-started/01-introduction",
+    options={
+        "wait": True,
+        "timeout": 180,
+        "args": {"depth": 1, "max_pages": 10},
+    },
 )
 
 # Recursive crawl with path-prefix filters, also downloading file links
 result = client.add_resource(
-    "https://docs.openviking.ai/",
-    args={
-        "depth": 2,
-        "max_pages": 50,
-        "include_paths": ["/docs/"],
-        "exclude_paths": ["/changelog"],
-        "skip_download_links": False,
+    path="https://docs.openviking.ai/",
+    options={
+        "args": {
+            "depth": 2,
+            "max_pages": 50,
+            "include_paths": ["/docs/"],
+            "exclude_paths": ["/changelog"],
+            "skip_download_links": False,
+        },
     },
 )
 
 # Add to the current user's private resource root
 result = client.add_resource(
-    "./documents/guide.md",
-    parent="viking://user/resources/docs",
-    create_parent=True,
+    path="./documents/guide.md",
+    options={
+        "parent": "viking://user/resources/docs",
+        "create_parent": True,
+    },
 )
 
 # Wait for processing to complete
 client.wait_processed()
 
 # Enable scheduled updates
 client.add_resource(
-    "./documents/guide.md",
-    to="viking://resources/guide.md",
-    watch_interval=60  # Update every 60 minutes
+    path="./documents/guide.md",
+    options={
+        "to": "viking://resources/guide.md",
+        "watch_interval": 60,  # Update every 60 minutes
+    },
 )
 
 # Add a Feishu document with a one-time user access token
 client.add_resource(
-    "https://example.feishu.cn/docx/doc_token",
-    args={"feishu_access_token": "u-..."},
+    path="https://example.feishu.cn/docx/doc_token",
+    options={"args": {"feishu_access_token": "u-..."}},
 )
 
 # Add a Feishu document with scheduled user-token refresh
 client.add_resource(
-    "https://example.feishu.cn/docx/doc_token",
-    to="viking://resources/feishu/doc",
-    watch_interval=1440,
-    args={
-        "feishu_access_token": "u-...",
-        "feishu_refresh_token": "r-...",
+    path="https://example.feishu.cn/docx/doc_token",
+    options={
+        "to": "viking://resources/feishu/doc",
+        "watch_interval": 1440,
+        "args": {
+            "feishu_access_token": "u-...",
+            "feishu_refresh_token": "r-...",
+        },
     },
 )
 ```

docs/en/api/04-skills.md

@@ -93,7 +93,7 @@ OpenViking automatically detects and converts MCP tool definitions to skill form
 **Conversion Example**:
 
 Input (MCP format):
-```python
+```json
 {
     "name": "search_web",
     "description": "Search the web",
@@ -115,7 +115,7 @@ Input (MCP format):
 ```
 
 Output (Skill format):
-```python
+```json
 {
     "name": "search-web",
     "description": "Search the web",
@@ -286,7 +286,7 @@ Search the web for current information.
 - **limit** (integer, optional): Max results, default 10
 """
 }
-result = client.add_skill(skill)
+result = client.add_skill(data=skill)
 print(f"Added: {result['root_uri']}")
 
 # Approach 2: Using MCP Tool format (auto-detected and converted
@@ -304,20 +304,20 @@ mcp_tool = {
         "required": ["expression"]
     }
 }
-result = client.add_skill(mcp_tool)
+result = client.add_skill(data=mcp_tool)
 print(f"Added: {result['uri']}")
 
 # Approach 3: Add from local SKILL.md file
-result = client.add_skill("./skills/search-web/SKILL.md")
+result = client.add_skill(data="./skills/search-web/SKILL.md")
 print(f"Added: {result['uri']}")
 
 # Approach 4: Add from directory containing SKILL.md (auxiliary files included
-result = client.add_skill("./skills/code-runner/")
+result = client.add_skill(data="./skills/code-runner/")
 print(f"Added: {result['uri']}")
 print(f"Auxiliary files: {result['auxiliary_files']}")
 
 # Wait for processing completion
-result = client.add_skill("./skills/my-skill/", wait=True)
+result = client.add_skill(data="./skills/my-skill/", options={"wait": True})
 client.wait_processed()
 ```
 
@@ -473,7 +473,11 @@ curl -X GET "http://localhost:1933/api/v1/skills?node_limit=1000" \
 **Python SDK**
 
 ```python
-skill = client.get_skill("search-web", include_content=True, include_files=True)
+skill = client.get_skill(
+    skill_name="search-web",
+    include_content=True,
+    include_files=True,
+)
 print(skill["name"])
 print(skill.get("content"))
 ```
@@ -506,7 +510,7 @@ curl -X GET "http://localhost:1933/api/v1/skills/search-web?include_content=true
 **Python SDK**
 
 ```python
-results = client.find_skills("search the internet", limit=5)
+results = client.find_skills(query="search the internet", limit=5)
 
 for skill in results["skills"]:
     print(skill["name"], skill["score"])
@@ -544,8 +548,12 @@ curl -X POST http://localhost:1933/api/v1/skills/find \
 **Python SDK**
 
 ```python
-validated = client.validate_skill({"name": "search-web", "description": "..."})
-updated = client.update_skill("search-web", "./skills/search-web", wait=True)
+validated = client.validate_skill(data={"name": "search-web", "description": "..."})
+updated = client.update_skill(
+    skill_name="search-web",
+    data="./skills/search-web",
+    options={"wait": True},
+)
 ```
 
 **TypeScript SDK**
@@ -599,7 +607,7 @@ curl -X PUT http://localhost:1933/api/v1/skills/search-web \
 **Python SDK**
 
 ```python
-client.delete_skill("old-skill")
+client.delete_skill(skill_name="old-skill")
 ```
 
 **TypeScript SDK**
@@ -707,14 +715,14 @@ A successful update returns the same processing result as `add_skill` with an ad
 skill = {
     "name": "search-web",
     "description": "Search the web for current information using Google",
-    ...
+    # Additional skill fields
 }
 
 # Less helpful - too vague
 skill = {
     "name": "search",
     "description": "Search",
-    ...
+    # Additional skill fields
 }
 ```