Skip to content

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

docs: use SyncHTTPClient in Python examples (#5534)

Zayn Jarvis39a39e80cc83
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index 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
```python
import 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 \
```python
import 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 ov
from 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} \
```python
import 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 running
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"])
@@ -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 completion
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"))
break
if 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.md
index 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":
break
if 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.md
index 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 source
options={"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 t
from 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, permission
1. **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, permission
Use 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, permission
4. **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, permission
1. **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, permission
4. **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, permission
1. **Locate the bottleneck**: Inspect queues, model latency, and storage time before changing concurrency
2. **Set appropriate `batch_size`**: Adjust batch processing size in Embedding configuration
3. **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
## Deployment
diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.md
index 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 you
Restart 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 asyncio
from 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.md
index 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` va
Use 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.md
index 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 \
```python
import 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
```python
import 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
```python
import 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 \
```python
import 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 ov
from 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"))
break
if 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.md
index 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":
break
if 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.md
index 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.md
index 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 asyncio
from 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.md
index 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-project
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"])
```
@@ -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",