Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: use SyncHTTPClient in Python examples (#5534)
Zayn Jarvis39a39e80cc83
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex 7c12e90f9..ea3c9f752 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -99,19 +99,19 @@ curl -X POST http://localhost:1933/api/v1/sessions \import openviking_sdk as ov# Use HTTP client-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Create new session (auto-generated ID)-result = await client.create_session()+result = client.create_session()print(f"Session ID: {result['session_id']}")# Create new session with specified ID-result = await client.create_session(session_id="my-custom-session-id")+result = client.create_session(session_id="my-custom-session-id")print(f"Session ID: {result['session_id']}")# Create new session with a custom auto-commit policy-result = await client.create_session(+result = client.create_session(options={"auto_commit_policy": {"pending_token_threshold": 8000,@@ -202,12 +202,12 @@ curl -X GET http://localhost:1933/api/v1/sessions \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-sessions = await client.list_sessions()+sessions = client.list_sessions()for s in sessions:print(f"{s['session_id']} -> {s['uri']}")```@@ -303,19 +303,19 @@ curl -X GET http://localhost:1933/api/v1/sessions/a1b2c3d4 \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Get existing session (raises NotFoundError if not found)-info = await client.get_session(session_id="a1b2c3d4")+info = client.get_session(session_id="a1b2c3d4")print(f"Live Messages: {info['message_count']}")print(f"Total Messages: {info.get('total_message_count', 'n/a')}")print(f"Commits: {info['commit_count']}")# Get or create session-info = await client.get_session(session_id="a1b2c3d4", auto_create=True)+info = client.get_session(session_id="a1b2c3d4", auto_create=True)```**TypeScript SDK**@@ -463,7 +463,7 @@ curl -X PATCH http://localhost:1933/api/v1/sessions/a1b2c3d4/config \**Python SDK**```python-result = await client.update_session_config(+result = client.update_session_config(session_id="a1b2c3d4",options={"memory_extraction_config": {@@ -730,12 +730,12 @@ curl -X GET "http://localhost:1933/api/v1/sessions/a1b2c3d4/context?token_budget**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-context = await client.get_session_context(session_id="a1b2c3d4", token_budget=128000)+context = client.get_session_context(session_id="a1b2c3d4", token_budget=128000)print(context["latest_archive_overview"])print(len(context["messages"]))```@@ -842,10 +842,10 @@ curl -X GET "http://localhost:1933/api/v1/sessions/a1b2c3d4/archives/archive_002```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-archive = await client.get_session_archive(+archive = client.get_session_archive(session_id="a1b2c3d4",archive_id="archive_002",)@@ -960,11 +960,11 @@ curl -X DELETE http://localhost:1933/api/v1/sessions/a1b2c3d4 \```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Delete session-await client.delete_session(session_id="a1b2c3d4")+client.delete_session(session_id="a1b2c3d4")```**TypeScript SDK**@@ -1135,18 +1135,18 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \import openviking_sdk as ovfrom openviking_sdk import ContextPart, ImagePart, TextPart-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Simple mode: Add user message-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="user",content="How do I authenticate users?",)# Parts mode: Add assistant message with context reference-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="assistant",parts=[@@ -1160,7 +1160,7 @@ await client.add_message()# Parts mode: Add user message with an image URL-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="user",parts=[@@ -1262,13 +1262,13 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages/batch \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Add messages in batch-result = await client.batch_add_messages(+result = client.batch_add_messages(session_id="a1b2c3d4",messages=[{"role": "user", "content": "How do I authenticate users?"},@@ -1391,18 +1391,18 @@ curl -X GET http://localhost:1933/api/v1/tasks/{task_id} \```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# Commit finishes Phase 1; summary and memory extraction run in the background-result = await client.commit_session(session_id="a1b2c3d4")+result = client.commit_session(session_id="a1b2c3d4")print(f"Status: {result['status']}")print(f"Task ID: {result['task_id']}")# Check once; poll again if the task is still pending or runningtask_id = result.get("task_id")if task_id:- task = await client.get_task(task_id=task_id)+ task = client.get_task(task_id=task_id)print(task["status"])if task["status"] == "completed":print(task["result"]["memories_extracted"])@@ -1616,29 +1616,29 @@ An empty `memory_diff.json` (all counts zero) is written when long-term memory e**Python SDK**```python-import asyncio+import time-from openviking_sdk import AsyncHTTPClient, ContextPart, TextPart+from openviking_sdk import SyncHTTPClient, ContextPart, TextPart# Initialize client-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()try:# Create new session- session_result = await client.create_session()+ session_result = client.create_session()session_id = session_result["session_id"]print(f"Session created: {session_id}")# Add user message- await client.add_message(+ client.add_message(session_id=session_id,role="user",content="How do I configure embedding?",)# Search with session context- results = await client.search(+ results = client.search(query="embedding configuration",session_id=session_id,)@@ -1647,7 +1647,7 @@ try:resources = results.get("resources", [])if resources:resource = resources[0]- await client.add_message(+ client.add_message(session_id=session_id,role="assistant",parts=[@@ -1660,24 +1660,24 @@ try:],)# Commit session; summary and memory extraction run in the background- commit_result = await client.commit_session(session_id=session_id)+ commit_result = client.commit_session(session_id=session_id)print(f"Task ID: {commit_result['task_id']}")# Optional: poll for completiontask_id = commit_result.get("task_id")if task_id:for _ in range(30):- task = await client.get_task(task_id=task_id)+ task = client.get_task(task_id=task_id)if task and task["status"] == "completed":print(task.get("result"))breakif task and task["status"] in {"failed", "cancelled"}:raise RuntimeError(task)- await asyncio.sleep(1)+ time.sleep(1)else:print(f"Still pending: {task_id}; check this task again later")finally:- await client.close()+ client.close()```**HTTP API**@@ -1724,16 +1724,16 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \```python# Commit after significant interactions-session_info = await client.get_session(session_id=session_id)+session_info = client.get_session(session_id=session_id)if session_info["message_count"] > 10:- await client.commit_session(session_id=session_id)+ client.commit_session(session_id=session_id)```### Use Session Context for Search```python# Interpret the query using session context; results depend on relevance and query-planning settings-results = await client.search(query=query, session_id=session_id)+results = client.search(query=query, session_id=session_id)```---diff --git a/docs/en/api/17-tasks.md b/docs/en/api/17-tasks.mdindex 341be0512..f1314d103 100644--- a/docs/en/api/17-tasks.md+++ b/docs/en/api/17-tasks.md@@ -50,29 +50,29 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \**Python SDK**```python-import asyncio+import time-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()try:- submitted = await client.add_resource("https://example.com/guide.md")+ submitted = client.add_resource("https://example.com/guide.md")task_id = submitted["task_id"]print(f"Import task: {task_id}")while True:- task = await client.get_task(task_id)+ task = client.get_task(task_id)if task is None:raise RuntimeError(f"Task {task_id} is no longer available")if task["status"] == "completed":breakif task["status"] in {"failed", "cancelled"}:raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- await asyncio.sleep(2)+ time.sleep(2)print(task["result"])finally:- await client.close()+ client.close()```**TypeScript SDK**@@ -233,7 +233,7 @@ Only the current user who owns the task can cancel it. ROOT identities cannot ca**Python SDK**```python-task = await client.cancel_task(task_id="uuid-xxx")+task = client.cancel_task(task_id="uuid-xxx")print(task["status"])```@@ -342,19 +342,19 @@ curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-tasks = await client.list_tasks(+tasks = client.list_tasks(task_type="session_commit",status="running",limit=20,)for task in tasks:print(task["task_id"], task["status"])-await client.close()+client.close()```**TypeScript SDK**diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.mdindex 8ddadfa46..8f328a0b6 100644--- a/docs/en/faq/faq.md+++ b/docs/en/faq/faq.md@@ -147,10 +147,10 @@ Supports Dense, Sparse, and Hybrid embedding modes.### How do I initialize the client?```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()```Embedding, VLM, storage, and other service configuration is managed by the OpenViking Server through `ov.conf`.@@ -170,20 +170,20 @@ Embedding, VLM, storage, and other service configuration is managed by the OpenV```python# Add single file-await client.add_resource(+client.add_resource(path="./document.pdf",parent="viking://resources", # Store under this directory; the name comes from the sourceoptions={"reason": "Project technical documentation"}, # Used for L0/L1 summaries when no instruction is given, and for resource-linked memory extraction)# Add web page-await client.add_resource(+client.add_resource(path="https://example.com/api-docs",options={"reason": "API reference documentation"},)# Wait for processing to complete-await client.wait_processed()+client.wait_processed()```### What is the difference between `to` and `parent`? Which should I use?@@ -220,13 +220,13 @@ Note: `processing_mode="vectors_only"` skips semantic processing, so the survivi```python# find(): Simple direct semantic search-results = await client.find(+results = client.find(query="OAuth authentication flow",target_uri="viking://resources/",)# search(): Complex tasks requiring intent analysis-results = await client.search(+results = client.search(query="Help me implement user login functionality",session_id=session.session_id,)@@ -244,21 +244,21 @@ Session management is a core capability of OpenViking, supporting conversation tfrom openviking_sdk import TextPart# Create session-session_info = await client.create_session()+session_info = client.create_session()session = client.session(session_id=session_info["session_id"])# Add conversation messages-await session.add_message(+session.add_message(role="user",parts=[TextPart(text="Help me analyze performance issues in this code")],)-await session.add_message(+session.add_message(role="assistant",parts=[TextPart(text="Let me analyze...")],)# Commit session to trigger memory extraction-await session.commit()+session.commit()```### What memory types does OpenViking support?@@ -271,16 +271,16 @@ Memories are stored in the current User or Peer namespace; there is no current w```python# List directory contents-items = await client.ls(uri="viking://resources/")+items = client.ls(uri="viking://resources/")# Read full content (L2)-content = await client.read(uri="viking://resources/doc.md")+content = client.read(uri="viking://resources/doc.md")# Get abstract (L0)-abstract = await client.abstract(uri="viking://resources")+abstract = client.abstract(uri="viking://resources")# Get overview (L1)-overview = await client.overview(uri="viking://resources")+overview = client.overview(uri="viking://resources")```## Retrieval Optimization@@ -309,7 +309,7 @@ Each query runs one global vector search within its directory scope, permission1. **Didn't wait for processing to complete**```python- result = await client.add_resource(path="./doc.pdf", wait=True)+ result = client.add_resource(path="./doc.pdf", wait=True)print(result)```Use `wait=True` for a new import. To inspect an import already submitted, query its returned `task_id` instead of importing it again. Keep waiting while its status is `pending` or `running`; inspect the task details if it is `failed` or `cancelled`. A request timeout alone does not mean the background task failed. See [Async Tasks](../api/17-tasks.md).@@ -333,8 +333,8 @@ Each query runs one global vector search within its directory scope, permissionUse the `task_id` returned by the import. `completed` means processing has finished; inspect the cause if the task is `failed` or `cancelled`.```python# Check if resources exist- items = await client.ls(uri="viking://resources/")- task = await client.get_task("<task_id returned by the import>")+ items = client.ls(uri="viking://resources/")+ task = client.get_task("<task_id returned by the import>")print(task["status"] if task is not None else "Task not found or expired")```@@ -348,7 +348,7 @@ Each query runs one global vector search within its directory scope, permission4. **Check L0 abstract quality**```python- abstract = await client.abstract(uri="viking://resources/your-doc")+ abstract = client.abstract(uri="viking://resources/your-doc")print(abstract) # Confirm abstract accurately reflects content```@@ -358,7 +358,7 @@ Each query runs one global vector search within its directory scope, permission1. **Ensure `commit()` was called**```python- await session.commit() # Triggers memory extraction+ session.commit() # Triggers memory extraction```2. **Check VLM configuration**@@ -371,7 +371,7 @@ Each query runs one global vector search within its directory scope, permission4. **List the memory directory**```python- memories = await client.ls(uri="viking://~/memories/")+ memories = client.ls(uri="viking://~/memories/")```### Performance issues@@ -381,7 +381,7 @@ Each query runs one global vector search within its directory scope, permission1. **Locate the bottleneck**: Inspect queues, model latency, and storage time before changing concurrency2. **Set appropriate `batch_size`**: Adjust batch processing size in Embedding configuration3. **Use local storage**: Use `local` backend during development to reduce network latency-4. **Async operations**: Fully utilize `AsyncHTTPClient`'s async capabilities+4. **Async operations**: Use `AsyncHTTPClient` when your application already runs an event loop (FastAPI, agent frameworks); `SyncHTTPClient` wraps it for scripts and notebooks## Deploymentdiff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.mdindex 947f93a21..1b3bdb84a 100644--- a/docs/en/guides/08-encryption.md+++ b/docs/en/guides/08-encryption.md@@ -58,32 +58,31 @@ Merge the following encryption settings into `~/.openviking/ov.conf`; retain youRestart the server after changing encryption settings, and run this example against that server. Install the [Python SDK](../api/01-overview.md#using-python-sdk-client-without-configuration-file) in the environment running the script.```python-import asynciofrom pathlib import Path-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-async def test():+def test():# OPENVIKING_API_KEY: use a tenant-bound user/admin key when authentication is enabled.- client = AsyncHTTPClient(url="http://localhost:1933")+ client = SyncHTTPClient(url="http://localhost:1933")try:- await client.initialize()+ client.initialize()sample = Path("./encrypted-sample.txt")sample.write_text("Hello, encrypted world!", encoding="utf-8")- imported = await client.add_resource(+ imported = client.add_resource(path=str(sample),wait=True,timeout=120,)- results = await client.find(+ results = client.find(query="encrypted", target_uri=imported["root_uri"])print(f"Found {len(results.get('resources', []))} resources")finally:- await client.close()+ client.close()-asyncio.run(test())+test()```It waits for import processing and checks retrieval; successful retrieval alone does not prove encryption at rest. Use [Check File Content](#method-1-check-file-content) to inspect the stored file header.diff --git a/docs/en/guides/09-ovpack.md b/docs/en/guides/09-ovpack.mdindex a7fae25d4..eab78f7a7 100644--- a/docs/en/guides/09-ovpack.md+++ b/docs/en/guides/09-ovpack.md@@ -134,7 +134,7 @@ details include only one missing key to keep logs small.Python SDK:```python-report = await client.check_consistency(uri="viking://resources/my-project")+report = client.check_consistency(uri="viking://resources/my-project")print(report["ok"], report["missing_records"])```@@ -206,40 +206,40 @@ After restoring content, register the remaining users with the same `user_id` vaUse source credentials for export/backup and a separately configured target client for import/restore across deployments. The full restore examples below assume you have completed the target-account and overwrite checks above. Queue completion alone does not prove a successful index rebuild; inspect errors and run a consistency check.```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-async def migrate_project():- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")- await client.initialize()+def migrate_project():+ client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+ client.initialize()try:- await client.export_ovpack(+ client.export_ovpack(uri="viking://resources/my-project",to="./exports/my-project.ovpack",include_vectors=False,)- imported_uri = await client.import_ovpack(+ imported_uri = client.import_ovpack(file_path="./exports/my-project.ovpack",parent="viking://resources/imported/",on_conflict="fail",vector_mode="auto",)print(imported_uri)- print(await client.wait_processed(timeout=120))- print(await client.check_consistency(uri=imported_uri))+ print(client.wait_processed(timeout=120))+ print(client.check_consistency(uri=imported_uri))finally:- await client.close()+ client.close()```Full backup:```python-await client.backup_ovpack(+client.backup_ovpack(to="./backups/openviking.ovpack",include_vectors=True,)-await client.restore_ovpack(+client.restore_ovpack(file_path="./backups/openviking.ovpack",on_conflict="overwrite",vector_mode="auto",diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex 188dc07f3..4242cc28a 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -99,19 +99,19 @@ curl -X POST http://localhost:1933/api/v1/sessions \import openviking_sdk as ov# 使用 HTTP 客户端-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# 创建新会话(自动生成 ID)-result = await client.create_session()+result = client.create_session()print(f"Session ID: {result['session_id']}")# 创建指定 ID 的新会话-result = await client.create_session(session_id="my-custom-session-id")+result = client.create_session(session_id="my-custom-session-id")print(f"Session ID: {result['session_id']}")# 创建带自定义自动 commit 策略的新会话-result = await client.create_session(+result = client.create_session(options={"auto_commit_policy": {"pending_token_threshold": 8000,@@ -202,12 +202,12 @@ curl -X GET http://localhost:1933/api/v1/sessions \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-sessions = await client.list_sessions()+sessions = client.list_sessions()for s in sessions:print(f"{s['session_id']} -> {s['uri']}")```@@ -305,17 +305,17 @@ curl -X GET http://localhost:1933/api/v1/sessions/a1b2c3d4 \```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# 获取已有会话(不存在时抛 NotFoundError)-info = await client.get_session(session_id="a1b2c3d4")+info = client.get_session(session_id="a1b2c3d4")print(f"Live Messages: {info['message_count']}")print(f"Total Messages: {info.get('total_message_count', 'n/a')}")print(f"Commits: {info['commit_count']}")# 获取或创建会话-info = await client.get_session(session_id="a1b2c3d4", auto_create=True)+info = client.get_session(session_id="a1b2c3d4", auto_create=True)```**TypeScript SDK**@@ -461,7 +461,7 @@ curl -X PATCH http://localhost:1933/api/v1/sessions/a1b2c3d4/config \**Python SDK**```python-result = await client.update_session_config(+result = client.update_session_config(session_id="a1b2c3d4",options={"memory_extraction_config": {@@ -730,10 +730,10 @@ curl -X GET "http://localhost:1933/api/v1/sessions/a1b2c3d4/context?token_budget```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-context = await client.get_session_context(session_id="a1b2c3d4", token_budget=128000)+context = client.get_session_context(session_id="a1b2c3d4", token_budget=128000)print(context["latest_archive_overview"])print(len(context["messages"]))```@@ -840,10 +840,10 @@ curl -X GET "http://localhost:1933/api/v1/sessions/a1b2c3d4/archives/archive_002```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-archive = await client.get_session_archive(+archive = client.get_session_archive(session_id="a1b2c3d4",archive_id="archive_002",)@@ -958,11 +958,11 @@ curl -X DELETE http://localhost:1933/api/v1/sessions/a1b2c3d4 \```pythonimport openviking_sdk as ov-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# 删除会话-await client.delete_session(session_id="a1b2c3d4")+client.delete_session(session_id="a1b2c3d4")```**TypeScript SDK**@@ -1132,18 +1132,18 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \import openviking_sdk as ovfrom openviking_sdk import ContextPart, ImagePart, TextPart-client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# 简单模式:添加用户消息-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="user",content="How do I authenticate users?",)# Parts 模式:添加带有上下文引用的助手消息-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="assistant",parts=[@@ -1157,7 +1157,7 @@ await client.add_message()# Parts 模式:添加包含图片 URL 的用户消息-await client.add_message(+client.add_message(session_id="a1b2c3d4",role="user",parts=[@@ -1259,13 +1259,13 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages/batch \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# 批量添加消息-result = await client.batch_add_messages(+result = client.batch_add_messages(session_id="a1b2c3d4",messages=[{"role": "user", "content": "How do I authenticate users?"},@@ -1385,20 +1385,20 @@ curl -X GET http://localhost:1933/api/v1/tasks/{task_id} \**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()# commit 完成 Phase 1 后返回,摘要生成和记忆提取在后台执行-result = await client.commit_session(session_id="a1b2c3d4")+result = client.commit_session(session_id="a1b2c3d4")print(f"Status: {result['status']}")print(f"Task ID: {result['task_id']}")# 查询一次;若任务仍在等待或运行中,稍后继续查询task_id = result.get("task_id")if task_id:- task = await client.get_task(task_id=task_id)+ task = client.get_task(task_id=task_id)print(task["status"])if task["status"] == "completed":print(task["result"]["memories_extracted"])@@ -1612,29 +1612,29 @@ viking://user/{user_id}/sessions/{session_id}/**Python SDK**```python-import asyncio+import time-from openviking_sdk import AsyncHTTPClient, ContextPart, TextPart+from openviking_sdk import SyncHTTPClient, ContextPart, TextPart# 初始化客户端-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()try:# 创建新会话- session_result = await client.create_session()+ session_result = client.create_session()session_id = session_result["session_id"]print(f"Session created: {session_id}")# 添加用户消息- await client.add_message(+ client.add_message(session_id=session_id,role="user",content="How do I configure embedding?",)# 使用会话上下文进行搜索- results = await client.search(+ results = client.search(query="embedding configuration",session_id=session_id,)@@ -1643,7 +1643,7 @@ try:resources = results.get("resources", [])if resources:resource = resources[0]- await client.add_message(+ client.add_message(session_id=session_id,role="assistant",parts=[@@ -1656,24 +1656,24 @@ try:],)# 提交会话;摘要生成和记忆提取在后台执行- commit_result = await client.commit_session(session_id=session_id)+ commit_result = client.commit_session(session_id=session_id)print(f"Task ID: {commit_result['task_id']}")# 可选:等待后台任务完成task_id = commit_result.get("task_id")if task_id:for _ in range(30):- task = await client.get_task(task_id=task_id)+ task = client.get_task(task_id=task_id)if task and task["status"] == "completed":print(task.get("result"))breakif task and task["status"] in {"failed", "cancelled"}:raise RuntimeError(task)- await asyncio.sleep(1)+ time.sleep(1)else:print(f"Still pending: {task_id}; check this task again later")finally:- await client.close()+ client.close()```**HTTP API**@@ -1720,16 +1720,16 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \```python# 在重要交互后提交-session_info = await client.get_session(session_id=session_id)+session_info = client.get_session(session_id=session_id)if session_info["message_count"] > 10:- await client.commit_session(session_id=session_id)+ client.commit_session(session_id=session_id)```### 使用会话上下文进行搜索```python# 用会话上下文解释当前查询;效果取决于上下文相关性和查询规划配置-results = await client.search(query=query, session_id=session_id)+results = client.search(query=query, session_id=session_id)```---diff --git a/docs/zh/api/17-tasks.md b/docs/zh/api/17-tasks.mdindex 8f9755a53..1db0eaa59 100644--- a/docs/zh/api/17-tasks.md+++ b/docs/zh/api/17-tasks.md@@ -50,29 +50,29 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \**Python SDK**```python-import asyncio+import time-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()try:- submitted = await client.add_resource("https://example.com/guide.md")+ submitted = client.add_resource("https://example.com/guide.md")task_id = submitted["task_id"]print(f"Import task: {task_id}")while True:- task = await client.get_task(task_id)+ task = client.get_task(task_id)if task is None:raise RuntimeError(f"Task {task_id} is no longer available")if task["status"] == "completed":breakif task["status"] in {"failed", "cancelled"}:raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")- await asyncio.sleep(2)+ time.sleep(2)print(task["result"])finally:- await client.close()+ client.close()```**TypeScript SDK**@@ -231,7 +231,7 @@ ov task status uuid-xxx**Python SDK**```python-task = await client.cancel_task(task_id="uuid-xxx")+task = client.cancel_task(task_id="uuid-xxx")print(task["status"])```@@ -340,19 +340,19 @@ curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=**Python SDK**```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()-tasks = await client.list_tasks(+tasks = client.list_tasks(task_type="session_commit",status="running",limit=20,)for task in tasks:print(task["task_id"], task["status"])-await client.close()+client.close()```**TypeScript SDK**diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.mdindex 8f3475e87..d2e0701ba 100644--- a/docs/zh/faq/faq.md+++ b/docs/zh/faq/faq.md@@ -145,10 +145,10 @@ pip install openviking --upgrade --force-reinstall### 如何初始化客户端?```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+client.initialize()```Embedding、VLM、存储等服务配置由 OpenViking Server 通过 `ov.conf` 管理。@@ -168,20 +168,20 @@ Embedding、VLM、存储等服务配置由 OpenViking Server 通过 `ov.conf````python# 添加单个文件-await client.add_resource(+client.add_resource(path="./document.pdf",parent="viking://resources", # 存到这个目录下面,文件名由来源决定options={"reason": "项目技术文档"}, # 未传 instruction 时用于生成 L0/L1 摘要,也用于资源相关的记忆提取)# 添加网页-await client.add_resource(+client.add_resource(path="https://example.com/api-docs",options={"reason": "API 参考文档"},)# 等待处理完成-await client.wait_processed()+client.wait_processed()```### `to` 和 `parent` 有什么区别?该用哪个?@@ -218,13 +218,13 @@ await client.wait_processed()```python# find(): 简单直接的语义搜索-results = await client.find(+results = client.find(query="OAuth 认证流程",target_uri="viking://resources/",)# search(): 复杂任务,需要意图分析-results = await client.search(+results = client.search(query="帮我实现用户登录功能",session_id=session.session_id,)@@ -242,21 +242,21 @@ results = await client.search(from openviking_sdk import TextPart# 创建会话-session_info = await client.create_session()+session_info = client.create_session()session = client.session(session_id=session_info["session_id"])# 添加对话消息-await session.add_message(+session.add_message(role="user",parts=[TextPart(text="帮我分析这段代码的性能问题")],)-await session.add_message(+session.add_message(role="assistant",parts=[TextPart(text="我来分析一下...")],)# 提交会话,触发记忆提取-await session.commit()+session.commit()```### OpenViking 支持哪些记忆类型?@@ -269,16 +269,16 @@ OpenViking 内置 `profile`、`preferences`、`entities`、`events`、`identity````python# 列出目录内容-items = await client.ls(uri="viking://resources/")+items = client.ls(uri="viking://resources/")# 读取完整内容(L2)-content = await client.read(uri="viking://resources/doc.md")+content = client.read(uri="viking://resources/doc.md")# 获取摘要(L0)-abstract = await client.abstract(uri="viking://resources")+abstract = client.abstract(uri="viking://resources")# 获取概览(L1)-overview = await client.overview(uri="viking://resources")+overview = client.overview(uri="viking://resources")```## 检索优化@@ -307,7 +307,7 @@ overview = await client.overview(uri="viking://resources")1. **未等待处理完成**```python- result = await client.add_resource(path="./doc.pdf", wait=True)+ result = client.add_resource(path="./doc.pdf", wait=True)print(result)```新导入时可用 `wait=True` 等待。排查已经提交的导入时,用返回的 `task_id` 查询任务,不必重复导入。状态仍为 `pending` 或 `running` 时需要继续等待;`failed` 或 `cancelled` 时查看任务详情。请求超时也不能据此判断后台任务已经失败,详见[异步任务](../api/17-tasks.md)。@@ -331,8 +331,8 @@ overview = await client.overview(uri="viking://resources")用导入时返回的 `task_id` 查询任务;`completed` 表示处理完成,`failed` 或 `cancelled` 需先检查原因。```python# 检查资源是否存在- items = await client.ls(uri="viking://resources/")- task = await client.get_task("<导入时返回的 task_id>")+ items = client.ls(uri="viking://resources/")+ task = client.get_task("<导入时返回的 task_id>")print(task["status"] if task is not None else "任务不存在或已过期")```@@ -346,7 +346,7 @@ overview = await client.overview(uri="viking://resources")4. **检查 L0 摘要质量**```python- abstract = await client.abstract(uri="viking://resources/your-doc")+ abstract = client.abstract(uri="viking://resources/your-doc")print(abstract) # 确认摘要是否准确反映内容```@@ -356,7 +356,7 @@ overview = await client.overview(uri="viking://resources")1. **确保调用了 `commit()`**```python- await session.commit() # 触发记忆提取+ session.commit() # 触发记忆提取```2. **检查 VLM 配置**@@ -369,7 +369,7 @@ overview = await client.overview(uri="viking://resources")4. **查看记忆目录**```python- memories = await client.ls(uri="viking://~/memories/")+ memories = client.ls(uri="viking://~/memories/")```### 性能问题@@ -379,7 +379,7 @@ overview = await client.overview(uri="viking://resources")1. **定位瓶颈**:先检查处理队列、模型延迟和存储耗时,再调整并发2. **合理设置 `batch_size`**:Embedding 配置中调整批处理大小3. **使用本地存储**:开发阶段使用 `local` 后端减少网络延迟-4. **异步操作**:充分利用 `AsyncHTTPClient` 的异步特性+4. **异步操作**:应用自身已有事件循环(FastAPI、agent 框架)时用 `AsyncHTTPClient`;脚本和 notebook 用 `SyncHTTPClient`,它是异步客户端的包装## 部署相关diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.mdindex a2c3e5201..582aa4157 100644--- a/docs/zh/guides/08-encryption.md+++ b/docs/zh/guides/08-encryption.md@@ -58,32 +58,31 @@ ov system crypto init-key --output-file ~/.openviking/master.key修改加密配置后重启服务,再对该服务运行示例。在运行脚本的环境中安装 [Python SDK](../api/01-overview.md#完全不依赖配置文件使用-python-sdk-客户端)。```python-import asynciofrom pathlib import Path-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-async def test():+def test():# 启用认证时,将 OPENVIKING_API_KEY 设置为绑定租户身份的 user/admin key。- client = AsyncHTTPClient(url="http://localhost:1933")+ client = SyncHTTPClient(url="http://localhost:1933")try:- await client.initialize()+ client.initialize()sample = Path("./encrypted-sample.txt")sample.write_text("Hello, encrypted world!", encoding="utf-8")- imported = await client.add_resource(+ imported = client.add_resource(path=str(sample),wait=True,timeout=120,)- results = await client.find(+ results = client.find(query="encrypted", target_uri=imported["root_uri"])print(f"找到 {len(results.get('resources', []))} 个资源")finally:- await client.close()+ client.close()-asyncio.run(test())+test()```示例会等待导入处理完成并检查检索;检索成功本身不能证明文件已加密。请按下方“验证加密”的文件内容检查步骤确认存储文件头。diff --git a/docs/zh/guides/09-ovpack.md b/docs/zh/guides/09-ovpack.mdindex a1aa74ff5..55230c314 100644--- a/docs/zh/guides/09-ovpack.md+++ b/docs/zh/guides/09-ovpack.md@@ -116,7 +116,7 @@ ov system consistency viking://resources/my-projectPython SDK:```python-report = await client.check_consistency(uri="viking://resources/my-project")+report = client.check_consistency(uri="viking://resources/my-project")print(report["ok"], report["missing_records"])```@@ -186,40 +186,40 @@ OPENVIKING_CLI_CONFIG_FILE=./restore.ovcli.conf \跨部署迁移时,导出和备份使用源端身份,导入和恢复使用单独配置的目标客户端。下方全量恢复示例以已完成上述目标 account 初始化和覆盖检查为前提。队列结束不证明索引重建成功,仍需检查错误和一致性结果。```python-from openviking_sdk import AsyncHTTPClient+from openviking_sdk import SyncHTTPClient-async def migrate_project():- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")- await client.initialize()+def migrate_project():+ client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+ client.initialize()try:- await client.export_ovpack(+ client.export_ovpack(uri="viking://resources/my-project",to="./exports/my-project.ovpack",include_vectors=False,)- imported_uri = await client.import_ovpack(+ imported_uri = client.import_ovpack(file_path="./exports/my-project.ovpack",parent="viking://resources/imported/",on_conflict="fail",vector_mode="auto",)print(imported_uri)- print(await client.wait_processed(timeout=120))- print(await client.check_consistency(uri=imported_uri))+ print(client.wait_processed(timeout=120))+ print(client.check_consistency(uri=imported_uri))finally:- await client.close()+ client.close()```全量备份:```python-await client.backup_ovpack(+client.backup_ovpack(to="./backups/openviking.ovpack",include_vectors=True,)-await client.restore_ovpack(+client.restore_ovpack(file_path="./backups/openviking.ovpack",on_conflict="overwrite",vector_mode="auto",