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
refactor(client): 拆分 HTTP 客户端,分离嵌入模式与 HTTP 模式 (#141)
qin-ctx002e14087ffc
diff --git a/docs/design/server_client/server-cli-design.md b/docs/design/server_client/server-cli-design.mdindex 477b8bc67..32ce02615 100644--- a/docs/design/server_client/server-cli-design.md+++ b/docs/design/server_client/server-cli-design.md@@ -345,10 +345,10 @@ OpenViking 提供三种接口,面向不同使用场景:```python# 构造函数参数-client = OpenViking(url="http://localhost:1933", api_key="your-api-key", user="alice")+client = SyncHTTPClient(url="http://localhost:1933", api_key="your-api-key")```-SDK 构造函数只接受 `url`、`api_key`、`path`、`user` 参数。不支持 `config` 参数,也不支持 `vectordb_url`/`agfs_url` 参数。+SDK 构造函数只接受 `url`、`api_key`、`path` 参数。不支持 `config` 参数,也不支持 `vectordb_url`/`agfs_url` 参数。#### CLI 配置@@ -358,7 +358,6 @@ CLI 通过 `ovcli.conf` 配置文件管理连接信息,不使用 `--url`、`--{"url": "http://localhost:1933","api_key": "sk-xxx",- "user": "alice","output": "table"}```@@ -652,7 +651,7 @@ class UsageInfo:**session**(Python CLI 返回 Session 对象,HTTP API 返回 JSON)```python# Python CLI-session = client.session(user="alice")+session = client.session()session.id # "session-abc123"session.user # "alice"session.created_at # datetime@@ -871,7 +870,6 @@ export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf# {# "url": "http://localhost:1933",# "api_key": "sk-xxx",-# "user": "alice",# "output": "table"# }@@ -1024,7 +1022,7 @@ for r in results.data.results:print(f"{r.uri}: {r.score:.2f}")# 会话管理(OOP 模式)-session = client.session(user="alice")+session = client.session()session.add_message("user", "What is OpenViking?")results = client.search("What is OpenViking?", session=session)diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex 0fcde97b1..3d8b49d8e 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -21,31 +21,52 @@ client = ov.OpenViking(path="./data")client.initialize()```+Embedded mode uses `ov.conf` to configure embedding, vlm, storage, and other modules. Default path: `~/.openviking/ov.conf`. You can also specify the path via environment variable:++```bash+export OPENVIKING_CONFIG_FILE=/path/to/ov.conf+```++Minimal configuration example:++```json+{+ "embedding": {+ "dense": {+ "api_base": "<api-endpoint>",+ "api_key": "<your-api-key>",+ "provider": "<volcengine|openai>",+ "dimension": 1024,+ "model": "<model-name>"+ }+ },+ "vlm": {+ "api_base": "<api-endpoint>",+ "api_key": "<your-api-key>",+ "provider": "<volcengine|openai>",+ "model": "<model-name>"+ }+}+```++For full configuration options and provider-specific examples, see the [Configuration Guide](../guides/01-configuration.md).+### HTTP Mode```python-client = ov.OpenViking(+client = ov.SyncHTTPClient(url="http://localhost:1933",api_key="your-key",)client.initialize()```-### Direct HTTP (curl)+When `url` is not explicitly provided, the HTTP client automatically loads connection info from `ovcli.conf`. This config file is shared between the HTTP client and CLI. Default path: `~/.openviking/ovcli.conf`. You can also specify the path via environment variable:```bash-curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \- -H "X-API-Key: your-key"+export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf```-### CLI Mode--The CLI connects to an OpenViking server and exposes all operations as shell commands.--**Configuration**--Create `~/.openviking/ovcli.conf` (or set `OPENVIKING_CLI_CONFIG_FILE` environment variable):-```json{"url": "http://localhost:1933",@@ -53,6 +74,25 @@ Create `~/.openviking/ovcli.conf` (or set `OPENVIKING_CLI_CONFIG_FILE` environme}```+| Field | Description | Default |+|-------|-------------|---------|+| `url` | Server address | (required) |+| `api_key` | API key | `null` (no auth) |+| `output` | Default output format: `"table"` or `"json"` | `"table"` |++See the [Configuration Guide](../guides/01-configuration.md#ovcliconf) for details.++### Direct HTTP (curl)++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: your-key"+```++### CLI Mode++The CLI connects to an OpenViking server and exposes all operations as shell commands. The CLI also loads connection info from `ovcli.conf` (shared with the HTTP client).+**Basic Usage**```bash@@ -74,15 +114,32 @@ openviking --json ls viking://resources/openviking -o json ls viking://resources/```-## Client Lifecycle+## Lifecycle++**Embedded Mode**```python-client = ov.OpenViking(path="./data") # or url="http://..."-client.initialize() # Required before any operations+import openviking as ov++client = ov.OpenViking(path="./data")+client.initialize()++# ... use client ...++client.close()+```++**HTTP Mode**++```python+import openviking as ov++client = ov.SyncHTTPClient(url="http://localhost:1933")+client.initialize()# ... use client ...-client.close() # Release resources+client.close()```## Authenticationdiff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex 33ec8f048..eff4d56f1 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -46,14 +46,9 @@ Add a resource to the knowledge base.| wait | bool | No | False | Wait for semantic processing to complete || timeout | float | No | None | Timeout in seconds (only used when wait=True) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-result = client.add_resource("./documents/guide.md",reason="User guide documentation"@@ -61,7 +56,6 @@ result = client.add_resource(print(f"Added: {result['root_uri']}")client.wait_processed()-client.close()```**HTTP API**@@ -103,7 +97,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"**Example: Add from URL**-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresult = client.add_resource(@@ -136,7 +130,7 @@ openviking add-resource https://example.com/api-docs.md --to viking://resources/**Example: Wait for Processing**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# Option 1: Wait inline@@ -187,21 +181,14 @@ Export a resource tree as a `.ovpack` file.| uri | str | Yes | - | Viking URI to export || to | str | Yes | - | Target file path |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-path = client.export_ovpack("viking://resources/my-project/","./exports/my-project.ovpack")print(f"Exported to: {path}")--client.close()```**HTTP API**@@ -253,14 +240,9 @@ Import a `.ovpack` file.| force | bool | No | False | Overwrite existing resources || vectorize | bool | No | True | Trigger vectorization after import |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-uri = client.import_ovpack("./exports/my-project.ovpack","viking://resources/imported/",@@ -270,7 +252,6 @@ uri = client.import_ovpack(print(f"Imported to: {uri}")client.wait_processed()-client.close()```**HTTP API**@@ -315,7 +296,7 @@ openviking import ./exports/my-project.ovpack viking://resources/imported/ --for### List Resources-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# List all resources@@ -388,7 +369,7 @@ openviking ls viking://resources/ --recursive### Read Resource Content-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# L0: Abstract@@ -444,7 +425,7 @@ openviking read viking://resources/docs/api.md### Move Resources-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.mv(@@ -492,7 +473,7 @@ openviking mv viking://resources/old-project/ viking://resources/new-project/### Delete Resources-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# Delete single file@@ -544,7 +525,7 @@ openviking rm viking://resources/old-project/ --recursive### Create Links-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# Link related resources@@ -616,7 +597,7 @@ openviking link viking://resources/docs/auth/ viking://resources/docs/security/### Get Relations-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonrelations = client.relations("viking://resources/docs/auth/")@@ -658,7 +639,7 @@ openviking relations viking://resources/docs/auth/### Remove Links-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.unlink(diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex a4dac8ca6..e1a762e2a 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -14,19 +14,12 @@ Read L0 abstract (~100 tokens summary).|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI (must be a directory) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-abstract = client.abstract("viking://resources/docs/")print(f"Abstract: {abstract}")# Output: "Documentation for the project API, covering authentication, endpoints..."--client.close()```**HTTP API**@@ -68,18 +61,11 @@ Read L1 overview, applies to directories.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI (must be a directory) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-overview = client.overview("viking://resources/docs/")print(f"Overview:\n{overview}")--client.close()```**HTTP API**@@ -121,18 +107,11 @@ Read L2 full content.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-content = client.read("viking://resources/docs/api.md")print(f"Content:\n{content}")--client.close()```**HTTP API**@@ -190,20 +169,13 @@ List directory contents.}```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-entries = client.ls("viking://resources/")for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['name']} - {type_str}")--client.close()```**HTTP API**@@ -263,20 +235,13 @@ Get directory tree structure.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-entries = client.tree("viking://resources/")for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['rel_path']} - {type_str}")--client.close()```**HTTP API**@@ -333,19 +298,12 @@ Get file or directory status information.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-info = client.stat("viking://resources/docs/api.md")print(f"Size: {info['size']}")print(f"Is directory: {info['isDir']}")--client.close()```**HTTP API**@@ -394,17 +352,10 @@ Create a directory.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI for the new directory |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.mkdir("viking://resources/new-project/")--client.close()```**HTTP API**@@ -453,21 +404,14 @@ Remove file or directory.| uri | str | Yes | - | Viking URI to remove || recursive | bool | No | False | Remove directory recursively |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Remove single fileclient.rm("viking://resources/docs/old.md")# Remove directory recursivelyclient.rm("viking://resources/old-project/", recursive=True)--client.close()```**HTTP API**@@ -517,20 +461,13 @@ Move file or directory.| from_uri | str | Yes | - | Source Viking URI || to_uri | str | Yes | - | Destination Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.mv("viking://resources/old-name/","viking://resources/new-name/")--client.close()```**HTTP API**@@ -582,14 +519,9 @@ Search content by pattern.| pattern | str | Yes | - | Search pattern (regex) || case_insensitive | bool | No | False | Ignore case |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.grep("viking://resources/","authentication",@@ -600,8 +532,6 @@ print(f"Found {results['count']} matches")for match in results['matches']:print(f" {match['uri']}:{match['line']}")print(f" {match['content']}")--client.close()```**HTTP API**@@ -659,14 +589,9 @@ Match files by pattern.| pattern | str | Yes | - | Glob pattern (e.g., `**/*.md`) || uri | str | No | "viking://" | Starting URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Find all markdown filesresults = client.glob("**/*.md", "viking://resources/")print(f"Found {results['count']} markdown files:")@@ -676,8 +601,6 @@ for uri in results['matches']:# Find all Python filesresults = client.glob("**/*.py", "viking://resources/")print(f"Found {results['count']} Python files")--client.close()```**HTTP API**@@ -732,14 +655,9 @@ Create relations between resources.| uris | str or List[str] | Yes | - | Target URI(s) || reason | str | No | "" | Reason for the link |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Single linkclient.link("viking://resources/docs/auth/",@@ -756,8 +674,6 @@ client.link(],reason="Related documentation")--client.close()```**HTTP API**@@ -819,20 +735,13 @@ Get relations for a resource.|-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-relations = client.relations("viking://resources/docs/auth/")for rel in relations:print(f"Related: {rel['uri']}")print(f" Reason: {rel['reason']}")--client.close()```**HTTP API**@@ -878,20 +787,13 @@ Remove a relation.| from_uri | str | Yes | - | Source URI || uri | str | Yes | - | Target URI to unlink |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.unlink("viking://resources/docs/auth/","viking://resources/docs/security/")--client.close()```**HTTP API**diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.mdindex de3f0516e..9d0360854 100644--- a/docs/en/api/04-skills.md+++ b/docs/en/api/04-skills.md@@ -57,14 +57,9 @@ description: Skill description- Single file: Path to `SKILL.md` file- Directory: Path to directory containing `SKILL.md` (auxiliary files included)-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-skill = {"name": "search-web","description": "Search the web for current information",@@ -81,8 +76,6 @@ Search the web for current information.result = client.add_skill(skill)print(f"Added: {result['uri']}")--client.close()```**HTTP API**@@ -127,14 +120,9 @@ openviking add-skill ./my-skill/ [--wait]**Example: Add from MCP Tool**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# MCP tool format is auto-detected and convertedmcp_tool = {"name": "calculator",@@ -153,8 +141,6 @@ mcp_tool = {result = client.add_skill(mcp_tool)print(f"Added: {result['uri']}")--client.close()```**HTTP API**@@ -183,14 +169,9 @@ curl -X POST http://localhost:1933/api/v1/skills \**Example: Add from SKILL.md File**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Add from file pathresult = client.add_skill("./skills/search-web/SKILL.md")print(f"Added: {result['uri']}")@@ -199,8 +180,6 @@ print(f"Added: {result['uri']}")result = client.add_skill("./skills/code-runner/")print(f"Added: {result['uri']}")print(f"Auxiliary files: {result['auxiliary_files']}")--client.close()```**HTTP API**@@ -269,14 +248,9 @@ Concrete examples of skill invocation.### List Skills-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# List all skillsskills = client.ls("viking://agent/skills/")for skill in skills:@@ -285,8 +259,6 @@ for skill in skills:# Simple list (names only)names = client.ls("viking://agent/skills/", simple=True)print(names)--client.close()```**HTTP API**@@ -298,7 +270,7 @@ curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://agent/skills/" \### Read Skill Content-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonuri = "viking://agent/skills/search-web/"@@ -334,7 +306,7 @@ curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://agent/skills### Search Skills-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# Semantic search for skills@@ -365,7 +337,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \### Remove Skills-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.rm("viking://agent/skills/old-skill/", recursive=True)diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex 1c8d266d2..d2ff520d0 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -14,19 +14,12 @@ Create a new session.|-----------|------|----------|---------|-------------|| session_id | str | No | None | Session ID. Creates new session with auto-generated ID if None |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data", user="alice")-client.initialize()-# Create new session (auto-generated ID)session = client.session()print(f"Session URI: {session.uri}")--client.close()```**HTTP API**@@ -66,19 +59,12 @@ openviking session newList all sessions.-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-sessions = client.ls("viking://session/")for s in sessions:print(f"{s['name']}")--client.close()```**HTTP API**@@ -123,20 +109,13 @@ Get session details.|-----------|------|----------|---------|-------------|| session_id | str | Yes | - | Session ID |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Load existing sessionsession = client.session(session_id="a1b2c3d4")session.load()print(f"Loaded {len(session.messages)} messages")--client.close()```**HTTP API**@@ -182,17 +161,10 @@ Delete a session.|-----------|------|----------|---------|-------------|| session_id | str | Yes | - | Session ID to delete |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.rm("viking://session/a1b2c3d4/", recursive=True)--client.close()```**HTTP API**@@ -264,15 +236,11 @@ ToolPart()```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ovfrom openviking.message import TextPart-client = ov.OpenViking(path="./data")-client.initialize()-session = client.session()# Add user message@@ -284,8 +252,6 @@ session.add_message("user", [session.add_message("assistant", [TextPart(text="You can use OAuth 2.0 for authentication...")])--client.close()```**HTTP API**@@ -345,14 +311,9 @@ Commit a session by archiving messages and extracting memories.|-----------|------|----------|---------|-------------|| session_id | str | Yes | - | Session ID to commit |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-session = client.session(session_id="a1b2c3d4")session.load()@@ -360,8 +321,6 @@ session.load()result = session.commit()print(f"Status: {result['status']}")print(f"Memories extracted: {result['memories_extracted']}")--client.close()```**HTTP API**@@ -447,7 +406,7 @@ viking://session/{session_id}/## Full Example-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonimport openviking as ovdiff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex 8685e915d..b7b11ba1a 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -54,14 +54,9 @@ class MatchedContext:relations: List[RelatedContext] # Related contexts```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.find("how to authenticate users")for ctx in results.resources:@@ -70,8 +65,6 @@ for ctx in results.resources:print(f"Type: {ctx.context_type}")print(f"Abstract: {ctx.abstract[:100]}...")print("---")--client.close()```**HTTP API**@@ -122,7 +115,7 @@ openviking find "how to authenticate users" [--uri viking://resources/] [--limit**Example: Search with Target URI**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# Search only in resources@@ -192,15 +185,11 @@ Search with session context and intent analysis.| score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filters |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ovfrom openviking.message import TextPart-client = ov.OpenViking(path="./data")-client.initialize()-# Create session with conversation contextsession = client.session()session.add_message("user", [@@ -219,8 +208,6 @@ results = client.search(for ctx in results.resources:print(f"Found: {ctx.uri}")print(f"Abstract: {ctx.abstract[:200]}...")--client.close()```**HTTP API**@@ -275,7 +262,7 @@ openviking search "best practices" [--session-id abc123] [--limit 10]**Example: Search Without Session**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# search can also be used without session@@ -313,14 +300,9 @@ Search content by pattern (regex).| pattern | str | Yes | - | Search pattern (regex) || case_insensitive | bool | No | False | Ignore case |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.grep("viking://resources/","authentication",@@ -331,8 +313,6 @@ print(f"Found {results['count']} matches")for match in results['matches']:print(f" {match['uri']}:{match['line']}")print(f" {match['content']}")--client.close()```**HTTP API**@@ -390,14 +370,9 @@ Match files by glob pattern.| pattern | str | Yes | - | Glob pattern (e.g., `**/*.md`) || uri | str | No | "viking://" | Starting URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Find all markdown filesresults = client.glob("**/*.md", "viking://resources/")print(f"Found {results['count']} markdown files:")@@ -407,8 +382,6 @@ for uri in results['matches']:# Find all Python filesresults = client.glob("**/*.py", "viking://resources/")print(f"Found {results['count']} Python files")--client.close()```**HTTP API**@@ -466,7 +439,7 @@ Query -> Intent Analysis -> Vector Search (L0) -> Rerank (L1) -> Results### Read Content Progressively-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresults = client.find("authentication")@@ -505,7 +478,7 @@ curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/do### Get Related Resources-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresults = client.find("OAuth implementation")diff --git a/docs/en/api/07-system.md b/docs/en/api/07-system.mdindex acfe80b89..79ad55588 100644--- a/docs/en/api/07-system.md+++ b/docs/en/api/07-system.md@@ -8,19 +8,12 @@ OpenViking provides system health, observability, and debug APIs for monitoringBasic health check endpoint. No authentication required.-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Check if system is healthyif client.observer.is_healthy():print("System OK")--client.close()```**HTTP API**@@ -53,17 +46,10 @@ openviking healthGet system status including initialization state and user info.-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-print(client.observer.system)--client.close()```**HTTP API**@@ -108,22 +94,15 @@ Wait for all asynchronous processing (embedding, semantic generation) to complet|-----------|------|----------|---------|-------------|| timeout | float | No | None | Timeout in seconds |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# Add resourcesclient.add_resource("./docs/")# Wait for all processing to completestatus = client.wait_processed()print(f"Processing complete: {status}")--client.close()```**HTTP API**@@ -172,14 +151,9 @@ The observer API provides detailed component-level monitoring.Get queue system status (embedding and semantic processing queues).-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-print(client.observer.queue)# Output:# [queue] (healthy)@@ -187,8 +161,6 @@ print(client.observer.queue)# Embedding 0 0 10 0 10# Semantic 0 0 10 0 10# TOTAL 0 0 20 0 20--client.close()```**HTTP API**@@ -229,7 +201,7 @@ openviking observer queueGet VikingDB status (collections, indexes, vector counts).-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.vikingdb)@@ -282,7 +254,7 @@ openviking observer vikingdbGet VLM (Vision Language Model) token usage status.-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.vlm)@@ -331,7 +303,7 @@ openviking observer vlmGet overall system status including all components.-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.system)@@ -404,20 +376,13 @@ openviking observer systemQuick health check for the entire system.-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-if client.observer.is_healthy():print("System OK")else:print(client.observer.system)--client.close()```**HTTP API**diff --git a/docs/en/concepts/01-architecture.md b/docs/en/concepts/01-architecture.mdindex 1c88186fb..88a136f12 100644--- a/docs/en/concepts/01-architecture.md+++ b/docs/en/concepts/01-architecture.md@@ -140,7 +140,7 @@ For team sharing, production deployment, and cross-language integration:```python# Python SDK connects to OpenViking Server-client = OpenViking(url="http://localhost:1933", api_key="xxx")+client = SyncHTTPClient(url="http://localhost:1933", api_key="xxx")``````bashdiff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.mdindex f5b41558b..4cc8a9f9d 100644--- a/docs/en/faq/faq.md+++ b/docs/en/faq/faq.md@@ -124,11 +124,11 @@ client = ov.AsyncOpenViking(path="./my_data")await client.initialize()# Async client - HTTP client mode-client = ov.AsyncOpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()```-The SDK constructor only accepts `url`, `api_key`, `path`, and `user` parameters. Other configuration (embedding, vlm, etc.) is managed through the `ov.conf` config file.+The SDK constructor only accepts `url`, `api_key`, and `path` parameters. Other configuration (embedding, vlm, etc.) is managed through the `ov.conf` config file.### What file formats are supported?@@ -347,7 +347,7 @@ This strategy finds semantically matching fragments while understanding the comp1. **Batch processing**: Adding multiple resources at once is more efficient than one by one2. **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 `AsyncOpenViking`'s async capabilities+4. **Async operations**: Fully utilize `AsyncOpenViking` / `AsyncHTTPClient`'s async capabilities## Deployment@@ -363,7 +363,7 @@ This strategy finds semantically matching fragments while understanding the compclient = ov.AsyncOpenViking(path="./data")# HTTP client mode (connects to a remote server)-client = ov.AsyncOpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")```### Is OpenViking open source?diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.mdindex 373751c65..2edec0f4b 100644--- a/docs/en/getting-started/02-quickstart.md+++ b/docs/en/getting-started/02-quickstart.md@@ -53,57 +53,7 @@ Create a configuration file `~/.openviking/ov.conf`:}```-### Configuration Examples--<details>-<summary><b>Example 1: Using Volcengine (Doubao Models)</b></summary>--```json-{- "embedding": {- "dense": {- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",- "api_key" : "your-volcengine-api-key",- "provider" : "volcengine",- "dimension": 1024,- "model" : "doubao-embedding-vision-250615"- }- },- "vlm": {- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",- "api_key" : "your-volcengine-api-key",- "provider" : "volcengine",- "model" : "doubao-seed-1-8-251228"- }-}-```--</details>--<details>-<summary><b>Example 2: Using OpenAI Models</b></summary>--```json-{- "embedding": {- "dense": {- "api_base" : "https://api.openai.com/v1",- "api_key" : "your-openai-api-key",- "provider" : "openai",- "dimension": 3072,- "model" : "text-embedding-3-large"- }- },- "vlm": {- "api_base" : "https://api.openai.com/v1",- "api_key" : "your-openai-api-key",- "provider" : "openai",- "model" : "gpt-4-vision-preview"- }-}-```--</details>+For complete examples for each model provider, see [Configuration Guide - Examples](../guides/01-configuration.md#configuration-examples).### Environment Variablesdiff --git a/docs/en/getting-started/03-quickstart-server.md b/docs/en/getting-started/03-quickstart-server.mdindex 3876045ed..8f617bf06 100644--- a/docs/en/getting-started/03-quickstart-server.md+++ b/docs/en/getting-started/03-quickstart-server.md@@ -40,7 +40,7 @@ curl http://localhost:1933/health```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933")+client = ov.SyncHTTPClient(url="http://localhost:1933")```If the server has authentication enabled, pass the API key:@@ -48,7 +48,7 @@ If the server has authentication enabled, pass the API key:```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")```**Full example:**@@ -56,7 +56,7 @@ client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933")+client = ov.SyncHTTPClient(url="http://localhost:1933")try:client.initialize()diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 6049f0a1f..6442210e5 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -39,6 +39,59 @@ Create `~/.openviking/ov.conf` in your project directory:}```+## Configuration Examples++<details>+<summary><b>Volcengine (Doubao Models)</b></summary>++```json+{+ "embedding": {+ "dense": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "dimension": 1024,+ "model" : "doubao-embedding-vision-250615",+ "input": "multimodal"+ }+ },+ "vlm": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "model" : "doubao-seed-1-8-251228"+ }+}+```++</details>++<details>+<summary><b>OpenAI Models</b></summary>++```json+{+ "embedding": {+ "dense": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "dimension": 3072,+ "model" : "text-embedding-3-large"+ }+ },+ "vlm": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "model" : "gpt-4-vision-preview"+ }+}+```++</details>+## Configuration Sections### embedding@@ -241,7 +294,7 @@ OpenViking uses two config files:| File | Purpose | Default Path ||------|---------|-------------|| `ov.conf` | SDK embedded mode + server config | `~/.openviking/ov.conf` |-| `ovcli.conf` | CLI connection to remote server | `~/.openviking/ovcli.conf` |+| `ovcli.conf` | HTTP client and CLI connection to remote server | `~/.openviking/ovcli.conf` |When config files are at the default path, OpenViking loads them automatically — no additional setup needed.@@ -262,7 +315,7 @@ The config sections documented above (embedding, vlm, rerank, storage) all belon### ovcli.conf-Config file for CLI to connect to a remote server:+Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI to connect to a remote server:```json{@@ -346,8 +399,7 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut"port": 1933,"api_key": "string","cors_origins": ["*"]- },- "user": "string"+ }}```diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex b44547ec1..5141247c6 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -101,7 +101,7 @@ python -m openviking serve```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()results = client.find("how to use openviking")diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.mdindex b91e64333..335ede619 100644--- a/docs/en/guides/04-authentication.md+++ b/docs/en/guides/04-authentication.md@@ -40,12 +40,12 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \-H "Authorization: Bearer your-secret-key"```-**Python SDK**+**Python SDK (HTTP)**```pythonimport openviking as ov-client = ov.OpenViking(+client = ov.SyncHTTPClient(url="http://localhost:1933",api_key="your-secret-key")diff --git a/docs/en/guides/05-monitoring.md b/docs/en/guides/05-monitoring.mdindex d89f4ee7f..90f0ea69e 100644--- a/docs/en/guides/05-monitoring.md+++ b/docs/en/guides/05-monitoring.md@@ -18,7 +18,7 @@ curl http://localhost:1933/health### Overall System Health-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonstatus = client.get_status()@@ -60,7 +60,7 @@ Check individual components:### Quick Health Check-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonif client.is_healthy():diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 560afc6b2..29bec07f7 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -21,31 +21,52 @@ client = ov.OpenViking(path="./data")client.initialize()```+嵌入式模式通过 `ov.conf` 配置 embedding、vlm、storage 等模块。默认路径 `~/.openviking/ov.conf`,也可通过环境变量指定:++```bash+export OPENVIKING_CONFIG_FILE=/path/to/ov.conf+```++最小配置示例:++```json+{+ "embedding": {+ "dense": {+ "api_base": "<api-endpoint>",+ "api_key": "<your-api-key>",+ "provider": "<volcengine|openai>",+ "dimension": 1024,+ "model": "<model-name>"+ }+ },+ "vlm": {+ "api_base": "<api-endpoint>",+ "api_key": "<your-api-key>",+ "provider": "<volcengine|openai>",+ "model": "<model-name>"+ }+}+```++完整配置选项和各服务商示例见 [配置指南](../guides/01-configuration.md)。+### HTTP 模式```python-client = ov.OpenViking(+client = ov.SyncHTTPClient(url="http://localhost:1933",api_key="your-key",)client.initialize()```-### 直接 HTTP(curl)+未显式传入 `url` 时,HTTP 客户端会自动从 `ovcli.conf` 读取连接信息。`ovcli.conf` 是 HTTP 客户端和 CLI 共享的配置文件,默认路径 `~/.openviking/ovcli.conf`,也可通过环境变量指定:```bash-curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \- -H "X-API-Key: your-key"+export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf```-### CLI 模式--CLI 连接到 OpenViking 服务端,将所有操作暴露为 Shell 命令。--**配置**--创建 `~/.openviking/ovcli.conf`(或设置 `OPENVIKING_CLI_CONFIG_FILE` 环境变量):-```json{"url": "http://localhost:1933",@@ -53,6 +74,25 @@ CLI 连接到 OpenViking 服务端,将所有操作暴露为 Shell 命令。}```+| 字段 | 说明 | 默认值 |+|------|------|--------|+| `url` | 服务端地址 | (必填) |+| `api_key` | API Key | `null`(无认证) |+| `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |++详见 [配置指南](../guides/01-configuration.md#ovcliconf)。++### 直接 HTTP(curl)++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: your-key"+```++### CLI 模式++CLI 连接到 OpenViking 服务端,将所有操作暴露为 Shell 命令。CLI 同样从 `ovcli.conf` 读取连接信息(与 HTTP 客户端共享)。+**基本用法**```bash@@ -74,15 +114,32 @@ openviking --json ls viking://resources/openviking -o json ls viking://resources/```-## 客户端生命周期+## 生命周期++**嵌入式模式**```python-client = ov.OpenViking(path="./data") # or url="http://..."-client.initialize() # Required before any operations+import openviking as ov++client = ov.OpenViking(path="./data")+client.initialize()++# ... 使用 client ...++client.close()+```++**HTTP 模式**++```python+import openviking as ov++client = ov.SyncHTTPClient(url="http://localhost:1933")+client.initialize()-# ... use client ...+# ... 使用 client ...-client.close() # Release resources+client.close()```## 认证diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex 5887e6fc1..440e2fa30 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -46,14 +46,9 @@ Input -> Parser -> TreeBuilder -> AGFS -> SemanticQueue -> Vector Index| wait | bool | 否 | False | 等待语义处理完成 || timeout | float | 否 | None | 超时时间(秒),仅在 wait=True 时生效 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-result = client.add_resource("./documents/guide.md",reason="User guide documentation"@@ -61,7 +56,6 @@ result = client.add_resource(print(f"Added: {result['root_uri']}")client.wait_processed()-client.close()```**HTTP API**@@ -103,7 +97,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"**示例:从 URL 添加**-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresult = client.add_resource(@@ -136,7 +130,7 @@ openviking add-resource https://example.com/api-docs.md --to viking://resources/**示例:等待处理完成**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 方式 1:内联等待@@ -187,21 +181,14 @@ openviking add-resource ./documents/guide.md --wait| uri | str | 是 | - | 要导出的 Viking URI || to | str | 是 | - | 目标文件路径 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-path = client.export_ovpack("viking://resources/my-project/","./exports/my-project.ovpack")print(f"Exported to: {path}")--client.close()```**HTTP API**@@ -253,14 +240,9 @@ openviking export viking://resources/my-project/ ./exports/my-project.ovpack| force | bool | 否 | False | 覆盖已有资源 || vectorize | bool | 否 | True | 导入后触发向量化 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-uri = client.import_ovpack("./exports/my-project.ovpack","viking://resources/imported/",@@ -270,7 +252,6 @@ uri = client.import_ovpack(print(f"Imported to: {uri}")client.wait_processed()-client.close()```**HTTP API**@@ -315,7 +296,7 @@ openviking import ./exports/my-project.ovpack viking://resources/imported/ --for### 列出资源-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 列出所有资源@@ -388,7 +369,7 @@ openviking ls viking://resources/ --recursive### 读取资源内容-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# L0:摘要@@ -444,7 +425,7 @@ openviking read viking://resources/docs/api.md### 移动资源-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.mv(@@ -492,7 +473,7 @@ openviking mv viking://resources/old-project/ viking://resources/new-project/### 删除资源-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 删除单个文件@@ -544,7 +525,7 @@ openviking rm viking://resources/old-project/ --recursive### 创建链接-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 链接相关资源@@ -616,7 +597,7 @@ openviking link viking://resources/docs/auth/ viking://resources/docs/security/### 获取关联-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonrelations = client.relations("viking://resources/docs/auth/")@@ -658,7 +639,7 @@ openviking relations viking://resources/docs/auth/### 删除链接-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.unlink(diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 871cc8ed5..75c94f9a4 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -14,19 +14,12 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。|------|------|------|--------|------|| uri | str | 是 | - | Viking URI(必须是目录) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-abstract = client.abstract("viking://resources/docs/")print(f"Abstract: {abstract}")# Output: "Documentation for the project API, covering authentication, endpoints..."--client.close()```**HTTP API**@@ -68,18 +61,11 @@ openviking abstract viking://resources/docs/|------|------|------|--------|------|| uri | str | 是 | - | Viking URI(必须是目录) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-overview = client.overview("viking://resources/docs/")print(f"Overview:\n{overview}")--client.close()```**HTTP API**@@ -121,18 +107,11 @@ openviking overview viking://resources/docs/|------|------|------|--------|------|| uri | str | 是 | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-content = client.read("viking://resources/docs/api.md")print(f"Content:\n{content}")--client.close()```**HTTP API**@@ -190,20 +169,13 @@ openviking read viking://resources/docs/api.md}```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-entries = client.ls("viking://resources/")for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['name']} - {type_str}")--client.close()```**HTTP API**@@ -263,20 +235,13 @@ openviking ls viking://resources/ [--simple] [--recursive]|------|------|------|--------|------|| uri | str | 是 | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-entries = client.tree("viking://resources/")for entry in entries:type_str = "dir" if entry['isDir'] else "file"print(f"{entry['rel_path']} - {type_str}")--client.close()```**HTTP API**@@ -333,19 +298,12 @@ openviking tree viking://resources/my-project/|------|------|------|--------|------|| uri | str | 是 | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-info = client.stat("viking://resources/docs/api.md")print(f"Size: {info['size']}")print(f"Is directory: {info['isDir']}")--client.close()```**HTTP API**@@ -394,17 +352,10 @@ openviking stat viking://resources/my-project/docs/api.md|------|------|------|--------|------|| uri | str | 是 | - | 新目录的 Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.mkdir("viking://resources/new-project/")--client.close()```**HTTP API**@@ -453,21 +404,14 @@ openviking mkdir viking://resources/new-project/| uri | str | 是 | - | 要删除的 Viking URI || recursive | bool | 否 | False | 递归删除目录 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 删除单个文件client.rm("viking://resources/docs/old.md")# 递归删除目录client.rm("viking://resources/old-project/", recursive=True)--client.close()```**HTTP API**@@ -517,20 +461,13 @@ openviking rm viking://resources/old.md [--recursive]| from_uri | str | 是 | - | 源 Viking URI || to_uri | str | 是 | - | 目标 Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.mv("viking://resources/old-name/","viking://resources/new-name/")--client.close()```**HTTP API**@@ -582,14 +519,9 @@ openviking mv viking://resources/old-name/ viking://resources/new-name/| pattern | str | 是 | - | 搜索模式(正则表达式) || case_insensitive | bool | 否 | False | 忽略大小写 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.grep("viking://resources/","authentication",@@ -600,8 +532,6 @@ print(f"Found {results['count']} matches")for match in results['matches']:print(f" {match['uri']}:{match['line']}")print(f" {match['content']}")--client.close()```**HTTP API**@@ -659,14 +589,9 @@ openviking grep viking://resources/ "authentication" [--ignore-case]| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`) || uri | str | 否 | "viking://" | 起始 URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 查找所有 Markdown 文件results = client.glob("**/*.md", "viking://resources/")print(f"Found {results['count']} markdown files:")@@ -676,8 +601,6 @@ for uri in results['matches']:# 查找所有 Python 文件results = client.glob("**/*.py", "viking://resources/")print(f"Found {results['count']} Python files")--client.close()```**HTTP API**@@ -732,14 +655,9 @@ openviking glob "**/*.md" [--uri viking://resources/]| uris | str 或 List[str] | 是 | - | 目标 URI || reason | str | 否 | "" | 关联原因 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 单个关联client.link("viking://resources/docs/auth/",@@ -756,8 +674,6 @@ client.link(],reason="Related documentation")--client.close()```**HTTP API**@@ -819,20 +735,13 @@ openviking link viking://resources/docs/auth/ viking://resources/docs/security/|------|------|------|--------|------|| uri | str | 是 | - | Viking URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-relations = client.relations("viking://resources/docs/auth/")for rel in relations:print(f"Related: {rel['uri']}")print(f" Reason: {rel['reason']}")--client.close()```**HTTP API**@@ -878,20 +787,13 @@ openviking relations viking://resources/docs/auth/| from_uri | str | 是 | - | 源 URI || uri | str | 是 | - | 要取消关联的目标 URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.unlink("viking://resources/docs/auth/","viking://resources/docs/security/")--client.close()```**HTTP API**diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.mdindex cc7ca6447..9a0f32593 100644--- a/docs/zh/api/04-skills.md+++ b/docs/zh/api/04-skills.md@@ -57,14 +57,9 @@ description: Skill description- 单个文件:指向 `SKILL.md` 文件的路径- 目录:指向包含 `SKILL.md` 的目录路径(辅助文件会一并包含)-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-skill = {"name": "search-web","description": "Search the web for current information",@@ -81,8 +76,6 @@ Search the web for current information.result = client.add_skill(skill)print(f"Added: {result['uri']}")--client.close()```**HTTP API**@@ -127,14 +120,9 @@ openviking add-skill ./my-skill/ [--wait]**示例:从 MCP Tool 添加**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# MCP tool 格式会被自动检测并转换mcp_tool = {"name": "calculator",@@ -153,8 +141,6 @@ mcp_tool = {result = client.add_skill(mcp_tool)print(f"Added: {result['uri']}")--client.close()```**HTTP API**@@ -183,14 +169,9 @@ curl -X POST http://localhost:1933/api/v1/skills \**示例:从 SKILL.md 文件添加**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 从文件路径添加result = client.add_skill("./skills/search-web/SKILL.md")print(f"Added: {result['uri']}")@@ -199,8 +180,6 @@ print(f"Added: {result['uri']}")result = client.add_skill("./skills/code-runner/")print(f"Added: {result['uri']}")print(f"Auxiliary files: {result['auxiliary_files']}")--client.close()```**HTTP API**@@ -269,14 +248,9 @@ Concrete examples of skill invocation.### 列出技能-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 列出所有技能skills = client.ls("viking://agent/skills/")for skill in skills:@@ -285,8 +259,6 @@ for skill in skills:# 简单列表(仅名称)names = client.ls("viking://agent/skills/", simple=True)print(names)--client.close()```**HTTP API**@@ -298,7 +270,7 @@ curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://agent/skills/" \### 读取技能内容-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonuri = "viking://agent/skills/search-web/"@@ -334,7 +306,7 @@ curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://agent/skills### 搜索技能-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 语义搜索技能@@ -365,7 +337,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \### 删除技能-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonclient.rm("viking://agent/skills/old-skill/", recursive=True)diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex 8c64e074f..7573492ea 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -14,19 +14,12 @@|------|------|------|--------|------|| session_id | str | 否 | None | 会话 ID。如果为 None,则创建一个自动生成 ID 的新会话 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data", user="alice")-client.initialize()-# 创建新会话(自动生成 ID)session = client.session()print(f"Session URI: {session.uri}")--client.close()```**HTTP API**@@ -66,19 +59,12 @@ openviking session new列出所有会话。-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-sessions = client.ls("viking://session/")for s in sessions:print(f"{s['name']}")--client.close()```**HTTP API**@@ -123,20 +109,13 @@ openviking session list|------|------|------|--------|------|| session_id | str | 是 | - | 会话 ID |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 加载已有会话session = client.session(session_id="a1b2c3d4")session.load()print(f"Loaded {len(session.messages)} messages")--client.close()```**HTTP API**@@ -182,17 +161,10 @@ openviking session get a1b2c3d4|------|------|------|--------|------|| session_id | str | 是 | - | 要删除的会话 ID |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-client.rm("viking://session/a1b2c3d4/", recursive=True)--client.close()```**HTTP API**@@ -264,15 +236,11 @@ ToolPart()```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ovfrom openviking.message import TextPart-client = ov.OpenViking(path="./data")-client.initialize()-session = client.session()# 添加用户消息@@ -284,8 +252,6 @@ session.add_message("user", [session.add_message("assistant", [TextPart(text="You can use OAuth 2.0 for authentication...")])--client.close()```**HTTP API**@@ -345,14 +311,9 @@ openviking session add-message a1b2c3d4 --role user --content "How do I authenti|------|------|------|--------|------|| session_id | str | 是 | - | 要提交的会话 ID |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-session = client.session(session_id="a1b2c3d4")session.load()@@ -360,8 +321,6 @@ session.load()result = session.commit()print(f"Status: {result['status']}")print(f"Memories extracted: {result['memories_extracted']}")--client.close()```**HTTP API**@@ -447,7 +406,7 @@ viking://session/{session_id}/## 完整示例-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonimport openviking as ovdiff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex c7adee11e..0c4268a24 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -54,14 +54,9 @@ class MatchedContext:relations: List[RelatedContext] # 关联上下文```-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.find("how to authenticate users")for ctx in results.resources:@@ -70,8 +65,6 @@ for ctx in results.resources:print(f"Type: {ctx.context_type}")print(f"Abstract: {ctx.abstract[:100]}...")print("---")--client.close()```**HTTP API**@@ -122,7 +115,7 @@ openviking find "how to authenticate users" [--uri viking://resources/] [--limit**示例:使用 Target URI 搜索**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# 仅在资源中搜索@@ -192,15 +185,11 @@ curl -X POST http://localhost:1933/api/v1/search/find \| score_threshold | float | 否 | None | 最低相关性分数阈值 || filter | Dict | 否 | None | 元数据过滤器 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ovfrom openviking.message import TextPart-client = ov.OpenViking(path="./data")-client.initialize()-# 创建带对话上下文的会话session = client.session()session.add_message("user", [@@ -219,8 +208,6 @@ results = client.search(for ctx in results.resources:print(f"Found: {ctx.uri}")print(f"Abstract: {ctx.abstract[:200]}...")--client.close()```**HTTP API**@@ -275,7 +262,7 @@ openviking search "best practices" [--session-id abc123] [--limit 10]**示例:不使用会话的搜索**-**Python SDK**+**Python SDK (Embedded / HTTP)**```python# search 也可以在没有会话的情况下使用@@ -313,14 +300,9 @@ curl -X POST http://localhost:1933/api/v1/search/search \| pattern | str | 是 | - | 搜索模式(正则表达式) || case_insensitive | bool | 否 | False | 忽略大小写 |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-results = client.grep("viking://resources/","authentication",@@ -331,8 +313,6 @@ print(f"Found {results['count']} matches")for match in results['matches']:print(f" {match['uri']}:{match['line']}")print(f" {match['content']}")--client.close()```**HTTP API**@@ -390,14 +370,9 @@ openviking grep viking://resources/ "authentication" [--ignore-case]| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`) || uri | str | 否 | "viking://" | 起始 URI |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 查找所有 markdown 文件results = client.glob("**/*.md", "viking://resources/")print(f"Found {results['count']} markdown files:")@@ -407,8 +382,6 @@ for uri in results['matches']:# 查找所有 Python 文件results = client.glob("**/*.py", "viking://resources/")print(f"Found {results['count']} Python files")--client.close()```**HTTP API**@@ -466,7 +439,7 @@ openviking glob "**/*.md" [--uri viking://resources/]### 渐进式读取内容-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresults = client.find("authentication")@@ -505,7 +478,7 @@ curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/do### 获取关联资源-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonresults = client.find("OAuth implementation")diff --git a/docs/zh/api/07-system.md b/docs/zh/api/07-system.mdindex f637eb9f5..8f7442722 100644--- a/docs/zh/api/07-system.md+++ b/docs/zh/api/07-system.md@@ -8,19 +8,12 @@ OpenViking 提供系统健康检查、可观测性和调试 API,用于监控基础健康检查端点。无需认证。-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 检查系统是否健康if client.observer.is_healthy():print("System OK")--client.close()```**HTTP API**@@ -53,17 +46,10 @@ openviking health获取系统状态,包括初始化状态和用户信息。-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-print(client.observer.system)--client.close()```**HTTP API**@@ -108,22 +94,15 @@ openviking status|------|------|------|--------|------|| timeout | float | 否 | None | 超时时间(秒) |-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-# 添加资源client.add_resource("./docs/")# 等待所有处理完成status = client.wait_processed()print(f"Processing complete: {status}")--client.close()```**HTTP API**@@ -172,14 +151,9 @@ Observer API 提供详细的组件级监控。获取队列系统状态(embedding 和语义处理队列)。-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-print(client.observer.queue)# Output:# [queue] (healthy)@@ -187,8 +161,6 @@ print(client.observer.queue)# Embedding 0 0 10 0 10# Semantic 0 0 10 0 10# TOTAL 0 0 20 0 20--client.close()```**HTTP API**@@ -229,7 +201,7 @@ openviking observer queue获取 VikingDB 状态(集合、索引、向量数量)。-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.vikingdb)@@ -282,7 +254,7 @@ openviking observer vikingdb获取 VLM(视觉语言模型)token 使用状态。-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.vlm)@@ -331,7 +303,7 @@ openviking observer vlm获取整体系统状态,包括所有组件。-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonprint(client.observer.system)@@ -404,20 +376,13 @@ openviking observer system快速检查整个系统的健康状态。-**Python SDK**+**Python SDK (Embedded / HTTP)**```python-import openviking as ov--client = ov.OpenViking(path="./data")-client.initialize()-if client.observer.is_healthy():print("System OK")else:print(client.observer.system)--client.close()```**HTTP API**diff --git a/docs/zh/concepts/01-architecture.md b/docs/zh/concepts/01-architecture.mdindex 2ec4aea58..101917f32 100644--- a/docs/zh/concepts/01-architecture.md+++ b/docs/zh/concepts/01-architecture.md@@ -139,7 +139,7 @@ client = OpenViking(path="./data")```python# Python SDK 连接 OpenViking Server-client = OpenViking(url="http://localhost:1933", api_key="xxx")+client = SyncHTTPClient(url="http://localhost:1933", api_key="xxx")``````bashdiff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.mdindex c05dcf5cf..d3f7ba3b7 100644--- a/docs/zh/faq/faq.md+++ b/docs/zh/faq/faq.md@@ -124,11 +124,11 @@ client = ov.AsyncOpenViking(path="./my_data")await client.initialize()# 异步客户端 - 服务模式-client = ov.AsyncOpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()```-SDK 构造函数仅接受 `url`、`api_key`、`path`、`user` 参数。其他配置(embedding、vlm 等)通过 `ov.conf` 配置文件管理。+SDK 构造函数仅接受 `url`、`api_key`、`path` 参数。其他配置(embedding、vlm 等)通过 `ov.conf` 配置文件管理。### 支持哪些文件格式?@@ -347,7 +347,7 @@ OpenViking 使用分数传播机制:1. **批量处理**:一次添加多个资源比逐个添加更高效2. **合理设置 `batch_size`**:Embedding 配置中调整批处理大小3. **使用本地存储**:开发阶段使用 `local` 后端减少网络延迟-4. **异步操作**:充分利用 `AsyncOpenViking` 的异步特性+4. **异步操作**:充分利用 `AsyncOpenViking` / `AsyncHTTPClient` 的异步特性## 部署相关@@ -363,7 +363,7 @@ OpenViking 使用分数传播机制:client = ov.AsyncOpenViking(path="./data")# 服务模式-client = ov.AsyncOpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")```### OpenViking 是开源的吗?diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.mdindex 9ed53b814..30d8b407d 100644--- a/docs/zh/getting-started/02-quickstart.md+++ b/docs/zh/getting-started/02-quickstart.md@@ -53,57 +53,7 @@ OpenViking 支持多种模型服务:}```-### 配置示例--<details>-<summary><b>示例 1:使用火山引擎(豆包模型)</b></summary>--```json-{- "embedding": {- "dense": {- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",- "api_key" : "your-volcengine-api-key",- "provider" : "volcengine",- "dimension": 1024,- "model" : "doubao-embedding-vision-250615"- }- },- "vlm": {- "api_base" : "https://ark.cn-beijing.volces.com/api/v3",- "api_key" : "your-volcengine-api-key",- "provider" : "volcengine",- "model" : "doubao-seed-1-8-251228"- }-}-```--</details>--<details>-<summary><b>示例 2:使用 OpenAI 模型</b></summary>--```json-{- "embedding": {- "dense": {- "api_base" : "https://api.openai.com/v1",- "api_key" : "your-openai-api-key",- "provider" : "openai",- "dimension": 3072,- "model" : "text-embedding-3-large"- }- },- "vlm": {- "api_base" : "https://api.openai.com/v1",- "api_key" : "your-openai-api-key",- "provider" : "openai",- "model" : "gpt-4-vision-preview"- }-}-```--</details>+各模型服务的完整配置示例请参见 [配置指南 - 配置示例](../guides/01-configuration.md#配置示例)。### 设置环境变量diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.mdindex 7542cfe69..9ae996898 100644--- a/docs/zh/getting-started/03-quickstart-server.md+++ b/docs/zh/getting-started/03-quickstart-server.md@@ -40,7 +40,7 @@ curl http://localhost:1933/health```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933")+client = ov.SyncHTTPClient(url="http://localhost:1933")```如果服务端启用了认证,需要传入 `api_key`:@@ -48,7 +48,7 @@ client = ov.OpenViking(url="http://localhost:1933")```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")```**完整示例:**@@ -56,7 +56,7 @@ client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933")+client = ov.SyncHTTPClient(url="http://localhost:1933")try:client.initialize()diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 96ddfce44..7ee667626 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -23,26 +23,76 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支},"embedding": {"dense": {- "model": "doubao-embedding-vision-250615",- "api_key": "{your-api-key}",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "api_base" : "<api-endpoint>",+ "api_key" : "<your-api-key>",+ "provider" : "<provider-type>","dimension": 1024,- "provider": "volcengine",+ "model" : "<model-name>"+ }+ },+ "vlm": {+ "api_base" : "<api-endpoint>",+ "api_key" : "<your-api-key>",+ "provider" : "<provider-type>",+ "model" : "<model-name>"+ }+}++```++## 配置示例++<details>+<summary><b>火山引擎(豆包模型)</b></summary>++```json+{+ "embedding": {+ "dense": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "dimension": 1024,+ "model" : "doubao-embedding-vision-250615","input": "multimodal"}},"vlm": {- "model": "doubao-seed-1-8-251228",- "api_key": "{your-api-key}",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "temperature": 0.0,- "max_retries": 2,- "provider": "volcengine"+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "provider" : "volcengine",+ "model" : "doubao-seed-1-8-251228"}}+```++</details>++<details>+<summary><b>OpenAI 模型</b></summary>+```json+{+ "embedding": {+ "dense": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "dimension": 3072,+ "model" : "text-embedding-3-large"+ }+ },+ "vlm": {+ "api_base" : "https://api.openai.com/v1",+ "api_key" : "your-openai-api-key",+ "provider" : "openai",+ "model" : "gpt-4-vision-preview"+ }+}```+</details>+## 配置部分### embedding@@ -247,7 +297,7 @@ OpenViking 使用两个配置文件:| 配置文件 | 用途 | 默认路径 ||---------|------|---------|| `ov.conf` | SDK 嵌入模式 + 服务端配置 | `~/.openviking/ov.conf` |-| `ovcli.conf` | CLI 连接远程服务端 | `~/.openviking/ovcli.conf` |+| `ovcli.conf` | HTTP 客户端和 CLI 连接远程服务端 | `~/.openviking/ovcli.conf` |配置文件放在默认路径时,OpenViking 自动加载,无需额外设置。@@ -268,7 +318,7 @@ python -m openviking serve --config /path/to/ov.conf### ovcli.conf-CLI 工具连接远程服务端的配置文件:+HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远程服务端的配置文件:```json{@@ -352,8 +402,7 @@ CLI 工具连接远程服务端的配置文件:"port": 1933,"api_key": "string","cors_origins": ["string"]- },- "user": "string"+ }}```diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex d0185eb00..9b7cd5b84 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -101,7 +101,7 @@ python -m openviking serve```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()results = client.find("how to use openviking")diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.mdindex 635d801a0..aad7a4f80 100644--- a/docs/zh/guides/04-authentication.md+++ b/docs/zh/guides/04-authentication.md@@ -40,12 +40,12 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \-H "Authorization: Bearer your-secret-key"```-**Python SDK**+**Python SDK (HTTP)**```pythonimport openviking as ov-client = ov.OpenViking(+client = ov.SyncHTTPClient(url="http://localhost:1933",api_key="your-secret-key")diff --git a/docs/zh/guides/05-monitoring.md b/docs/zh/guides/05-monitoring.mdindex 7b3f4ad1b..54359b86b 100644--- a/docs/zh/guides/05-monitoring.md+++ b/docs/zh/guides/05-monitoring.md@@ -18,7 +18,7 @@ curl http://localhost:1933/health### 整体系统健康状态-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonstatus = client.get_status()@@ -60,7 +60,7 @@ curl http://localhost:1933/api/v1/observer/system \### 快速健康检查-**Python SDK**+**Python SDK (Embedded / HTTP)**```pythonif client.is_healthy():diff --git a/examples/chatmem/chatmem.py b/examples/chatmem/chatmem.pyindex ec0f7ec77..e4b0c7843 100644--- a/examples/chatmem/chatmem.py+++ b/examples/chatmem/chatmem.py@@ -336,7 +336,7 @@ class ChatREPL:config_dict = json.load(f)config = OpenVikingConfig.from_dict(config_dict)- self.client = SyncOpenViking(path=self.data_path, config=config, user="default")+ self.client = SyncOpenViking(path=self.data_path, config=config)self.client.initialize()# Create/load sessiondiff --git a/examples/chatmem/docs/2026-02-03-chatmem-implementation.md b/examples/chatmem/docs/2026-02-03-chatmem-implementation.mdindex 91610490f..64cb00513 100644--- a/examples/chatmem/docs/2026-02-03-chatmem-implementation.md+++ b/examples/chatmem/docs/2026-02-03-chatmem-implementation.md@@ -282,7 +282,6 @@ def run(self):# Create/load sessionself.session = self.client.session(- user="default",session_id=self.session_id)self.session.load()@@ -432,7 +431,7 @@ client = SyncOpenViking(path='./data', config=config)client.initialize()# Create session-session = client.session(user="test", session_id="test-123")+session = client.session(session_id="test-123")# Add messagessession.add_message("user", [TextPart("Hello")])@@ -1070,7 +1069,7 @@ self.session = None# In run()self.client = SyncOpenViking(path=data_path, config=config)self.client.initialize()-self.session = self.client.session(user="default", session_id=session_id)+self.session = self.client.session(session_id=session_id)self.session.load()# Recording messagesdiff --git a/examples/chatmem/docs/COMPARISON.md b/examples/chatmem/docs/COMPARISON.mdindex 1c45f7f10..90d03c134 100644--- a/examples/chatmem/docs/COMPARISON.md+++ b/examples/chatmem/docs/COMPARISON.md@@ -82,7 +82,7 @@ self.session = None# In run()self.client = SyncOpenViking(path=data_path, config=config)self.client.initialize()-self.session = self.client.session(user="default", session_id=session_id)+self.session = self.client.session(session_id=session_id)self.session.load()# Recording messagesdiff --git a/examples/memex/cli.py b/examples/memex/cli.pyindex 49d19dc0f..8b36119b7 100644--- a/examples/memex/cli.py+++ b/examples/memex/cli.py@@ -3,7 +3,7 @@Memex CLI - Personal Knowledge AssistantUsage:- python -m memex.cli [--data-path PATH] [--user USER]+ python -m memex.cli [--data-path PATH]Commands:/help Show help@@ -425,14 +425,11 @@ def main():default="./ov.conf",help="Path to OpenViking config file (default: ./ov.conf)",)- parser.add_argument("--user", default="default", help="User name (default: default)")-args = parser.parse_args()config = MemexConfig(data_path=args.data_path,config_path=args.config_path,- user=args.user,)cli = MemexCLI(config)diff --git a/examples/memex/client.py b/examples/memex/client.pyindex 241cc279d..f4c7df936 100644--- a/examples/memex/client.py+++ b/examples/memex/client.py@@ -7,7 +7,6 @@ from typing import Any, Optionalfrom config import MemexConfigimport openviking as ov-from openviking.session.user_id import UserIdentifierclass MemexClient:@@ -33,13 +32,9 @@ class MemexClient:def initialize(self) -> None:"""Initialize the OpenViking client."""ov_config = self.config.get_openviking_config()- user = UserIdentifier(- ov_config.default_account, ov_config.default_user, ov_config.default_agent- )self._client = ov.SyncOpenViking(path=self.config.data_path,config=ov_config,- user=user,)self._client.initialize()diff --git a/examples/memex/config.py b/examples/memex/config.pyindex b82b419bc..5df10e5ab 100644--- a/examples/memex/config.py+++ b/examples/memex/config.py@@ -18,7 +18,6 @@ class MemexConfig:# OpenViking settingsdata_path: str = "./memex_data"config_path: str = "./ov.conf"- user: str = "default"# LLM settings (for RAG, read from ov.conf)llm_temperature: float = 0.7@@ -45,7 +44,6 @@ class MemexConfig:return cls(data_path=os.getenv("MEMEX_DATA_PATH", "./memex_data"),config_path=os.getenv("MEMEX_CONFIG_PATH", "./ov.conf"),- user=os.getenv("MEMEX_USER", "default"),llm_temperature=float(os.getenv("MEMEX_LLM_TEMPERATURE", "0.7")),llm_max_tokens=int(os.getenv("MEMEX_LLM_MAX_TOKENS", "2048")),search_top_k=int(os.getenv("MEMEX_SEARCH_TOP_K", "5")),diff --git a/examples/quick_start.py b/examples/quick_start.pyindex 5113a2482..cc455980a 100644--- a/examples/quick_start.py+++ b/examples/quick_start.py@@ -1,7 +1,7 @@import openviking as ovclient = ov.OpenViking(path="./data")-# client = ov.OpenViking(url="http://localhost:1933") # HTTP mode: connect to OpenViking Server+# client = ov.SyncHTTPClient(url="http://localhost:1933") # HTTP mode: connect to OpenViking Servertry:client.initialize()diff --git a/examples/server_client/README.md b/examples/server_client/README.mdindex c4ab60465..850a2d1b1 100644--- a/examples/server_client/README.md+++ b/examples/server_client/README.md@@ -42,8 +42,8 @@ bash client_cli.sh # CLI 使用示例## 文件说明```-client_sync.py # 同步客户端示例(SyncOpenViking HTTP mode)-client_async.py # 异步客户端示例(AsyncOpenViking HTTP mode)+client_sync.py # 同步客户端示例(SyncHTTPClient)+client_async.py # 异步客户端示例(AsyncHTTPClient)client_cli.sh # CLI 使用示例(覆盖所有命令和参数)ov.conf.example # Server/SDK 配置文件模板(ov.conf)ovcli.conf.example # CLI 连接配置文件模板(ovcli.conf)@@ -73,14 +73,12 @@ pyproject.toml # 项目依赖|------|------|--------|| `url` | Server 地址 | (必填) || `api_key` | API Key 认证 | `null`(无认证) |-| `user` | 默认用户名 | `"default"` || `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |```json{"url": "http://localhost:1933","api_key": null,- "user": "default","output": "table"}```@@ -116,7 +114,7 @@ main()```pythonimport openviking as ov-client = ov.OpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()client.add_resource(path="./document.md")@@ -131,7 +129,7 @@ client.close()```pythonimport openviking as ov-client = ov.AsyncOpenViking(url="http://localhost:1933", api_key="your-key")+client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()await client.add_resource(path="./document.md")diff --git a/examples/server_client/client_async.py b/examples/server_client/client_async.pyindex fc2093eb4..660ac7641 100644--- a/examples/server_client/client_async.py+++ b/examples/server_client/client_async.py@@ -2,7 +2,7 @@"""OpenViking 异步客户端示例 (HTTP mode)-使用 AsyncOpenViking 通过 HTTP 连接远程 Server,演示完整 API。+使用 AsyncHTTPClient 通过 HTTP 连接远程 Server,演示完整 API。前置条件:先启动 Server: openviking serve@@ -37,7 +37,7 @@ async def main():parser.add_argument("--api-key", default=None, help="API key")args = parser.parse_args()- client = ov.AsyncOpenViking(url=args.url, api_key=args.api_key)+ client = ov.AsyncHTTPClient(url=args.url, api_key=args.api_key)try:# ── Connect ──diff --git a/examples/server_client/client_cli.sh b/examples/server_client/client_cli.shindex 6d3455481..dd40d8d8e 100755--- a/examples/server_client/client_cli.sh+++ b/examples/server_client/client_cli.sh@@ -178,7 +178,6 @@ SESSION_ID=$(openviking --json session new | python3 -c "import sys, json; print(json.load(sys.stdin)['result']['session_id'])")echo " session_id: $SESSION_ID"-# openviking session new --user "alice" # with custom usersection "7.2 Add Messages"openviking session add-message "$SESSION_ID" \diff --git a/examples/server_client/client_sync.py b/examples/server_client/client_sync.pyindex 12ed42ab6..c0297db70 100644--- a/examples/server_client/client_sync.py+++ b/examples/server_client/client_sync.py@@ -2,7 +2,7 @@"""OpenViking 同步客户端示例 (HTTP mode)-使用 SyncOpenViking 通过 HTTP 连接远程 Server,演示完整 API。+使用 SyncHTTPClient 通过 HTTP 连接远程 Server,演示完整 API。前置条件:先启动 Server: openviking serve@@ -63,7 +63,7 @@ def main():parser.add_argument("--api-key", default=None, help="API key")args = parser.parse_args()- client = ov.OpenViking(url=args.url, api_key=args.api_key)+ client = ov.SyncHTTPClient(url=args.url, api_key=args.api_key)try:# ── Connect ──@@ -182,7 +182,7 @@ def main():ctx_results = spin("Searching with session context...",- client.search, "how to use it", session=session, limit=3,+ client.search, "how to use it", session_id=session.session_id, limit=3,)if hasattr(ctx_results, "resources") and ctx_results.resources:for r in ctx_results.resources:diff --git a/openviking/__init__.py b/openviking/__init__.pyindex f9c7d73c8..b5da2e4ac 100644--- a/openviking/__init__.py+++ b/openviking/__init__.py@@ -7,6 +7,8 @@ Data in, Context out."""from openviking.async_client import AsyncOpenViking+from openviking.client.http import AsyncHTTPClient+from openviking.client.sync_http import SyncHTTPClientfrom openviking.session import Sessionfrom openviking.session.user_id import UserIdentifierfrom openviking.sync_client import SyncOpenViking@@ -27,6 +29,8 @@ __all__ = ["OpenViking","SyncOpenViking","AsyncOpenViking",+ "SyncHTTPClient",+ "AsyncHTTPClient","Session","UserIdentifier",]diff --git a/openviking/async_client.py b/openviking/async_client.pyindex ea3aa83ca..3376ab946 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -1,15 +1,15 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: Apache-2.0"""-Async OpenViking client implementation.+Async OpenViking client implementation (embedded mode only).-Supports both embedded mode (LocalClient) and HTTP mode (HTTPClient).+For HTTP mode, use AsyncHTTPClient or SyncHTTPClient."""import threadingfrom typing import Any, Dict, List, Optional, Union-from openviking.client import HTTPClient, LocalClient, Session+from openviking.client import LocalClient, Sessionfrom openviking.client.base import BaseClientfrom openviking.service.debug_service import SystemStatusfrom openviking.session.user_id import UserIdentifier@@ -20,36 +20,20 @@ logger = get_logger(__name__)class AsyncOpenViking:"""- OpenViking main client class (Asynchronous).+ OpenViking main client class (Asynchronous, embedded mode only).- Supports two deployment modes:- - Embedded mode: Uses local storage and auto-starts services (singleton)- - HTTP mode: Connects to remote OpenViking Server via HTTP API (not singleton)+ Uses local storage and auto-starts services (singleton).+ For HTTP mode, use AsyncHTTPClient or SyncHTTPClient instead.Examples:- # 1. Embedded mode (loads config from ov.conf)client = AsyncOpenViking(path="./data")await client.initialize()-- # 2. HTTP mode (connects to OpenViking Server)- client = AsyncOpenViking(- url="http://localhost:8000",- api_key="your-api-key",- user="alice"- )- await client.initialize()"""_instance: Optional["AsyncOpenViking"] = None_lock = threading.Lock()def __new__(cls, *args, **kwargs):- # HTTP mode: no singleton- url = kwargs.get("url")- if url:- return object.__new__(cls)-- # Embedded mode: use singletonif cls._instance is None:with cls._lock:if cls._instance is None:@@ -59,41 +43,26 @@ class AsyncOpenViking:def __init__(self,path: Optional[str] = None,- url: Optional[str] = None,- api_key: Optional[str] = None,- user: Optional[UserIdentifier] = None,**kwargs,):"""- Initialize OpenViking client.+ Initialize OpenViking client (embedded mode).Args:- path: Local storage path for embedded mode (overrides ov.conf storage path).- url: OpenViking Server URL for HTTP mode.- api_key: API key for HTTP mode authentication.- user: UserIdentifier object for session management.+ path: Local storage path (overrides ov.conf storage path).**kwargs: Additional configuration parameters."""# Singleton guard for repeated initializationif hasattr(self, "_singleton_initialized") and self._singleton_initialized:return- if isinstance(user, str):- user = UserIdentifier.the_default_user(user)- self.user = user or UserIdentifier.the_default_user()+ self.user = UserIdentifier.the_default_user()self._initialized = Falseself._singleton_initialized = True- # Create the appropriate client- if url:- # HTTP mode- self._client: BaseClient = HTTPClient(url=url, api_key=api_key, user=self.user)- else:- # Embedded mode - LocalClient loads config from ov.conf singleton- self._client: BaseClient = LocalClient(- path=path,- user=self.user,- )+ self._client: BaseClient = LocalClient(+ path=path,+ )# ============= Lifecycle methods =============diff --git a/openviking/cli/context.py b/openviking/cli/context.pyindex 989b8df15..a389a0671 100644--- a/openviking/cli/context.py+++ b/openviking/cli/context.py@@ -7,70 +7,34 @@ from typing import TYPE_CHECKING, Optionalimport typer-from openviking.utils.config.config_loader import (- DEFAULT_CONFIG_DIR,- DEFAULT_OVCLI_CONF,- OPENVIKING_CLI_CONFIG_ENV,- require_config,-)-if TYPE_CHECKING:- from openviking.sync_client import SyncOpenViking+ from openviking.client.sync_http import SyncHTTPClientclass CliConfigError(ValueError):"""Raised when required CLI configuration is missing or invalid."""-def build_sync_client(**kwargs) -> "SyncOpenViking":- """Create SyncOpenViking lazily to keep CLI import lightweight."""- from openviking.sync_client import SyncOpenViking-- return SyncOpenViking(**kwargs)--@dataclassclass CLIContext:"""Shared state for one CLI invocation."""json_output: bool = Falseoutput_format: str = "table"- _client: Optional["SyncOpenViking"] = field(default=None, init=False, repr=False)+ _client: Optional["SyncHTTPClient"] = field(default=None, init=False, repr=False)- def get_client_http_only(self) -> "SyncOpenViking":- """Create an HTTP client from ovcli.conf."""+ def get_client_http_only(self) -> "SyncHTTPClient":+ """Create an HTTP client (auto-loads ovcli.conf)."""if self._client is not None:return self._client- try:- cli_config = require_config(- None,- OPENVIKING_CLI_CONFIG_ENV,- DEFAULT_OVCLI_CONF,- "CLI",- )- except FileNotFoundError:- default_path = DEFAULT_CONFIG_DIR / DEFAULT_OVCLI_CONF- raise CliConfigError(- f"CLI configuration file not found.\n"- f"Please create {default_path} or set {OPENVIKING_CLI_CONFIG_ENV}.\n"- f"Example content: "- f'{{"url": "http://localhost:1933", "api_key": null}}'- )-- url = cli_config.get("url")- if not url:- default_path = DEFAULT_CONFIG_DIR / DEFAULT_OVCLI_CONF- raise CliConfigError(- f'"url" is required in {default_path}.\n'- f'Example: {{"url": "http://localhost:1933"}}'- )+ from openviking.client.sync_http import SyncHTTPClient- self._client = build_sync_client(- url=url,- api_key=cli_config.get("api_key"),- user=cli_config.get("user"),- )+ try:+ self._client = SyncHTTPClient()+ except ValueError as e:+ raise CliConfigError(str(e)) from e+ self._client.initialize()return self._clientdef close_client(self) -> None:diff --git a/openviking/client.py b/openviking/client.pyindex 43afabc28..34d5e6737 100644--- a/openviking/client.py+++ b/openviking/client.py@@ -6,6 +6,8 @@ This module provides both synchronous and asynchronous clients."""from openviking.async_client import AsyncOpenViking+from openviking.client.http import AsyncHTTPClient+from openviking.client.sync_http import SyncHTTPClientfrom openviking.sync_client import SyncOpenViking-__all__ = ["SyncOpenViking", "AsyncOpenViking"]+__all__ = ["SyncOpenViking", "AsyncOpenViking", "SyncHTTPClient", "AsyncHTTPClient"]diff --git a/openviking/client/__init__.py b/openviking/client/__init__.pyindex c6fba72d2..c4ab52cf0 100644--- a/openviking/client/__init__.py+++ b/openviking/client/__init__.py@@ -2,17 +2,19 @@# SPDX-License-Identifier: Apache-2.0"""OpenViking Client module.-Provides client implementations for both embedded (LocalClient) and HTTP (HTTPClient) modes.+Provides client implementations for embedded (LocalClient) and HTTP (AsyncHTTPClient/SyncHTTPClient) modes."""from openviking.client.base import BaseClient-from openviking.client.http import HTTPClient+from openviking.client.http import AsyncHTTPClientfrom openviking.client.local import LocalClientfrom openviking.client.session import Session+from openviking.client.sync_http import SyncHTTPClient__all__ = ["BaseClient",- "HTTPClient",+ "AsyncHTTPClient",+ "SyncHTTPClient","LocalClient","Session",]diff --git a/openviking/client/base.py b/openviking/client/base.pyindex 084304522..b5cc80610 100644--- a/openviking/client/base.py+++ b/openviking/client/base.py@@ -2,7 +2,7 @@# SPDX-License-Identifier: Apache-2.0"""Base client interface for OpenViking.-Defines the abstract base class that both LocalClient and HTTPClient implement.+Defines the abstract base class that both LocalClient and AsyncHTTPClient implement."""from abc import ABC, abstractmethod@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional, Unionclass BaseClient(ABC):"""Abstract base class for OpenViking clients.- Both LocalClient (embedded mode) and HTTPClient (HTTP mode) implement this interface.+ Both LocalClient (embedded mode) and AsyncHTTPClient (HTTP mode) implement this interface."""# ============= Lifecycle =============diff --git a/openviking/client/http.py b/openviking/client/http.pyindex d464a1059..2f201633b 100644--- a/openviking/client/http.py+++ b/openviking/client/http.py@@ -1,6 +1,6 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: Apache-2.0-"""HTTP Client for OpenViking.+"""Async HTTP Client for OpenViking.Implements BaseClient interface using HTTP calls to OpenViking Server."""@@ -10,6 +10,12 @@ from typing import Any, Dict, List, Optional, Unionimport httpxfrom openviking.client.base import BaseClient+from openviking.utils.config.config_loader import (+ DEFAULT_OVCLI_CONF,+ OPENVIKING_CLI_CONFIG_ENV,+ load_json_config,+ resolve_config_path,+)from openviking.exceptions import (AlreadyExistsError,DeadlineExceededError,@@ -56,7 +62,7 @@ class _HTTPObserver:Provides the same interface as the local observer but fetches data via HTTP."""- def __init__(self, client: "HTTPClient"):+ def __init__(self, client: "AsyncHTTPClient"):self._client = clientself._cache = {}@@ -102,28 +108,45 @@ class _HTTPObserver:return status.get("is_healthy", False)-class HTTPClient(BaseClient):- """HTTP Client for OpenViking Server.+class AsyncHTTPClient(BaseClient):+ """Async HTTP Client for OpenViking Server.Implements BaseClient interface using HTTP calls.+ Supports auto-loading url/api_key from ovcli.conf when not provided.++ Examples:+ # Explicit url+ client = AsyncHTTPClient(url="http://localhost:1933", api_key="key")++ # Auto-load from ~/.openviking/ovcli.conf+ client = AsyncHTTPClient()"""def __init__(self,- url: str,+ url: Optional[str] = None,api_key: Optional[str] = None,- user: Optional[UserIdentifier] = None,):- """Initialize HTTPClient.+ """Initialize AsyncHTTPClient.Args:- url: OpenViking Server URL- api_key: API key for authentication- user: User name for session management+ url: OpenViking Server URL. If not provided, reads from ovcli.conf.+ api_key: API key for authentication. If not provided, reads from ovcli.conf."""+ if url is None:+ config_path = resolve_config_path(None, OPENVIKING_CLI_CONFIG_ENV, DEFAULT_OVCLI_CONF)+ if config_path:+ cfg = load_json_config(config_path)+ url = cfg.get("url")+ api_key = api_key or cfg.get("api_key")+ if not url:+ raise ValueError(+ "url is required. Pass it explicitly or configure in "+ "~/.openviking/ovcli.conf (key: \"url\")."+ )self._url = url.rstrip("/")self._api_key = api_key- self._user = user or UserIdentifier.the_default_user()+ self._user = UserIdentifier.the_default_user()self._http: Optional[httpx.AsyncClient] = Noneself._observer: Optional[_HTTPObserver] = None@@ -349,18 +372,20 @@ class HTTPClient(BaseClient):self,query: str,target_uri: str = "",+ session: Optional[Any] = None,session_id: Optional[str] = None,limit: int = 10,score_threshold: Optional[float] = None,filter: Optional[Dict[str, Any]] = None,) -> FindResult:"""Semantic search with optional session context."""+ sid = session_id or (session.session_id if session else None)response = await self._http.post("/api/v1/search/search",json={"query": query,"target_uri": target_uri,- "session_id": session_id,+ "session_id": sid,"limit": limit,"score_threshold": score_threshold,"filter": filter,diff --git a/openviking/client/local.py b/openviking/client/local.pyindex 3a7a541b9..650a2d5a4 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -22,17 +22,15 @@ class LocalClient(BaseClient):def __init__(self,path: Optional[str] = None,- user: Optional[UserIdentifier] = None,):"""Initialize LocalClient.Args:path: Local storage path (overrides ov.conf storage path)- user: User name for session management"""self._service = OpenVikingService(path=path,- user=user or UserIdentifier.the_default_user(),+ user=UserIdentifier.the_default_user(),)self._user = self._service.userdiff --git a/openviking/client/session.py b/openviking/client/session.pyindex 0dc035e2b..39f62e32c 100644--- a/openviking/client/session.py+++ b/openviking/client/session.py@@ -2,7 +2,7 @@# SPDX-License-Identifier: Apache-2.0"""Lightweight Session class for OpenViking client.-Session delegates all operations to the underlying Client (LocalClient or HTTPClient).+Session delegates all operations to the underlying Client (LocalClient or AsyncHTTPClient)."""from typing import TYPE_CHECKING, Any, Dict@@ -24,7 +24,7 @@ class Session:"""Initialize Session.Args:- client: The underlying client (LocalClient or HTTPClient)+ client: The underlying client (LocalClient or AsyncHTTPClient)session_id: Session IDuser: User name"""diff --git a/openviking/client/sync_http.py b/openviking/client/sync_http.pynew file mode 100644index 000000000..5a69ad62b--- /dev/null+++ b/openviking/client/sync_http.py@@ -0,0 +1,241 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Synchronous HTTP Client for OpenViking.++Wraps AsyncHTTPClient with synchronous methods.+"""++from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union++if TYPE_CHECKING:+ from openviking.client.session import Session++from openviking.client.http import AsyncHTTPClient+from openviking.utils import run_async+++class SyncHTTPClient:+ """Synchronous HTTP Client for OpenViking Server.++ Wraps AsyncHTTPClient with synchronous methods.+ Supports auto-loading url/api_key from ovcli.conf when not provided.++ Examples:+ # Explicit url+ client = SyncHTTPClient(url="http://localhost:1933", api_key="key")+ client.initialize()++ # Auto-load from ~/.openviking/ovcli.conf+ client = SyncHTTPClient()+ client.initialize()+ """++ def __init__(+ self,+ url: Optional[str] = None,+ api_key: Optional[str] = None,+ ):+ self._async_client = AsyncHTTPClient(url=url, api_key=api_key)+ self._initialized = False++ # ============= Lifecycle =============++ def initialize(self) -> None:+ """Initialize the HTTP client."""+ run_async(self._async_client.initialize())+ self._initialized = True++ def close(self) -> None:+ """Close the HTTP client and release resources."""+ run_async(self._async_client.close())+ self._initialized = False++ # ============= Session =============++ def session(self, session_id: Optional[str] = None) -> "Session":+ """Create new session or load existing session."""+ return self._async_client.session(session_id)++ def create_session(self) -> Dict[str, Any]:+ """Create a new session."""+ return run_async(self._async_client.create_session())++ def list_sessions(self) -> List[Any]:+ """List all sessions."""+ return run_async(self._async_client.list_sessions())++ def get_session(self, session_id: str) -> Dict[str, Any]:+ """Get session details."""+ return run_async(self._async_client.get_session(session_id))++ def delete_session(self, session_id: str) -> None:+ """Delete a session."""+ run_async(self._async_client.delete_session(session_id))++ def add_message(self, session_id: str, role: str, content: str) -> Dict[str, Any]:+ """Add a message to a session."""+ return run_async(self._async_client.add_message(session_id, role, content))++ def commit_session(self, session_id: str) -> Dict[str, Any]:+ """Commit a session (archive and extract memories)."""+ return run_async(self._async_client.commit_session(session_id))++ # ============= Resource =============++ def add_resource(+ self,+ path: str,+ target: Optional[str] = None,+ reason: str = "",+ instruction: str = "",+ wait: bool = False,+ timeout: Optional[float] = None,+ ) -> Dict[str, Any]:+ """Add resource to OpenViking."""+ return run_async(+ self._async_client.add_resource(path, target, reason, instruction, wait, timeout)+ )++ def add_skill(+ self,+ data: Any,+ wait: bool = False,+ timeout: Optional[float] = None,+ ) -> Dict[str, Any]:+ """Add skill to OpenViking."""+ return run_async(self._async_client.add_skill(data, wait=wait, timeout=timeout))++ def wait_processed(self, timeout: Optional[float] = None) -> Dict[str, Any]:+ """Wait for all processing to complete."""+ return run_async(self._async_client.wait_processed(timeout))++ # ============= Search =============++ def search(+ self,+ query: str,+ target_uri: str = "",+ session: Optional[Union["Session", Any]] = None,+ session_id: Optional[str] = None,+ limit: int = 10,+ score_threshold: Optional[float] = None,+ filter: Optional[Dict] = None,+ ):+ """Semantic search with optional session context."""+ return run_async(+ self._async_client.search(+ query=query,+ target_uri=target_uri,+ session=session,+ session_id=session_id,+ limit=limit,+ score_threshold=score_threshold,+ filter=filter,+ )+ )++ def find(+ self,+ query: str,+ target_uri: str = "",+ limit: int = 10,+ score_threshold: Optional[float] = None,+ filter: Optional[Dict] = None,+ ):+ """Semantic search without session context."""+ return run_async(+ self._async_client.find(query, target_uri, limit, score_threshold, filter)+ )++ def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:+ """Content search with pattern."""+ return run_async(self._async_client.grep(uri, pattern, case_insensitive))++ def glob(self, pattern: str, uri: str = "viking://") -> Dict:+ """File pattern matching."""+ return run_async(self._async_client.glob(pattern, uri))++ # ============= File System =============++ def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> List[Any]:+ """List directory contents."""+ return run_async(self._async_client.ls(uri, simple=simple, recursive=recursive))++ def tree(self, uri: str) -> Dict:+ """Get directory tree."""+ return run_async(self._async_client.tree(uri))++ def stat(self, uri: str) -> Dict:+ """Get resource status."""+ return run_async(self._async_client.stat(uri))++ def mkdir(self, uri: str) -> None:+ """Create directory."""+ run_async(self._async_client.mkdir(uri))++ def rm(self, uri: str, recursive: bool = False) -> None:+ """Remove resource."""+ run_async(self._async_client.rm(uri, recursive))++ def mv(self, from_uri: str, to_uri: str) -> None:+ """Move resource."""+ run_async(self._async_client.mv(from_uri, to_uri))++ # ============= Content =============++ def read(self, uri: str) -> str:+ """Read file content."""+ return run_async(self._async_client.read(uri))++ def abstract(self, uri: str) -> str:+ """Read L0 abstract."""+ return run_async(self._async_client.abstract(uri))++ def overview(self, uri: str) -> str:+ """Read L1 overview."""+ return run_async(self._async_client.overview(uri))++ # ============= Relations =============++ def relations(self, uri: str) -> List[Dict[str, Any]]:+ """Get relations for a resource."""+ return run_async(self._async_client.relations(uri))++ def link(self, from_uri: str, uris: Union[str, List[str]], reason: str = "") -> None:+ """Create link between resources."""+ run_async(self._async_client.link(from_uri, uris, reason))++ def unlink(self, from_uri: str, uri: str) -> None:+ """Remove link between resources."""+ run_async(self._async_client.unlink(from_uri, uri))++ # ============= Pack =============++ def export_ovpack(self, uri: str, to: str) -> str:+ """Export context as .ovpack file."""+ return run_async(self._async_client.export_ovpack(uri, to))++ def import_ovpack(+ self, file_path: str, target: str, force: bool = False, vectorize: bool = True+ ) -> str:+ """Import .ovpack file."""+ return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))++ # ============= Debug =============++ def health(self) -> bool:+ """Check server health."""+ return run_async(self._async_client.health())++ def get_status(self) -> Dict[str, Any]:+ """Get system status."""+ return self._async_client.get_status()++ def is_healthy(self) -> bool:+ """Quick health check."""+ return self._async_client.is_healthy()++ @property+ def observer(self):+ """Get observer service for component status."""+ return self._async_client.observerdiff --git a/openviking/service/core.py b/openviking/service/core.pyindex 7f5ac143c..9c0d48e6f 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -24,7 +24,7 @@ from openviking.storage import VikingDBManagerfrom openviking.storage.collection_schemas import init_context_collectionfrom openviking.storage.viking_fs import VikingFS, init_viking_fsfrom openviking.utils import get_logger-from openviking.utils.config import OpenVikingConfig, get_openviking_config+from openviking.utils.config import get_openviking_configfrom openviking.utils.config.open_viking_config import initialize_openviking_configfrom openviking.utils.config.storage_config import StorageConfigfrom openviking.utils.resource_processor import ResourceProcessor@@ -178,9 +178,6 @@ class OpenVikingService:# Create context collectionawait init_context_collection(self._vikingdb_manager)- # Start queues after collections are ready- self._vikingdb_manager.start_queues()-# Initialize VikingFSself._viking_fs = init_viking_fs(agfs_url=self._agfs_url or "http://localhost:8080",diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex df536f79f..e49208c3f 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -534,17 +534,10 @@ class VikingFS:def _uri_to_path(self, uri: str) -> str:"""viking://user/memories/preferences/test -> /local/user/memories/preferences/test"""- if uri.startswith("viking://"):- path = uri.replace("viking://", "/")- elif uri.startswith("/"):- path = uri- else:- path = f"/{uri}"-- if not path.startswith("/local/"):- path = "/local" + path-- return path.rstrip("/")+ remainder = uri[len("viking://"):].strip("/")+ if not remainder:+ return "/local"+ return f"/local/{remainder}"def _path_to_uri(self, path: str) -> str:"""/local/user/memories/preferences -> viking://user/memories/preferences"""diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.pyindex 9d96105f7..59f9b8f38 100644--- a/openviking/storage/vikingdb_manager.py+++ b/openviking/storage/vikingdb_manager.py@@ -59,11 +59,12 @@ class VikingDBManager(VikingVectorIndexBackend):self._embedding_handler = Noneself._semantic_processor = None- # Initialize queue manager (but don't start yet — collections must be created first)+ # Initialize queue manager if AGFS URL is providedself._init_queue_manager()if self._queue_manager:self._init_embedding_queue()self._init_semantic_queue()+ self._queue_manager.start()def _init_queue_manager(self):"""Initialize queue manager for background processing."""@@ -111,12 +112,6 @@ class VikingDBManager(VikingVectorIndexBackend):)logger.info("Semantic queue initialized with SemanticProcessor")- def start_queues(self):- """Start the queue manager. Call after collections are created."""- if self._queue_manager:- self._queue_manager.start()- logger.info("Queue manager started")-async def close(self) -> None:"""Close storage connection and release resources, including queue manager."""try:diff --git a/tests/README.md b/tests/README.mdindex 6d00d305a..f5e18366b 100644--- a/tests/README.md+++ b/tests/README.md@@ -126,7 +126,7 @@ Tests for the OpenViking client API (`AsyncOpenViking` / `SyncOpenViking`).### server/-Tests for the OpenViking HTTP server API and HTTPClient SDK.+Tests for the OpenViking HTTP server API and AsyncHTTPClient SDK.| File | Description | Key Test Cases ||------|-------------|----------------|@@ -140,7 +140,7 @@ Tests for the OpenViking HTTP server API and HTTPClient SDK.| `test_api_relations.py` | Relations endpoints | Get relations, link single/multiple targets, unlink || `test_api_observer.py` | Observer endpoints | Queue, VikingDB, VLM, system observer status || `test_error_scenarios.py` | Error handling | Invalid JSON, missing fields, not found, wrong content type, invalid URI format |-| `test_http_client_sdk.py` | HTTPClient SDK E2E | Health, add resource, wait, ls, mkdir, tree, session lifecycle, find, full workflow (real HTTP server) |+| `test_http_client_sdk.py` | AsyncHTTPClient SDK E2E | Health, add resource, wait, ls, mkdir, tree, session lifecycle, find, full workflow (real HTTP server) |### session/diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.pyindex 42c014cca..daa2d2d0b 100644--- a/tests/cli/test_cli.py+++ b/tests/cli/test_cli.py@@ -57,7 +57,11 @@ def _run_cli(args, server_url, env=None, expected_exit_code=0):def test_requires_ovcli_conf():- result = runner.invoke(app, ["find", "hello"], env={})+ result = runner.invoke(+ app,+ ["find", "hello"],+ env={"OPENVIKING_CLI_CONFIG_FILE": "/tmp/nonexistent/ovcli.conf"},+ )assert result.exit_code == 2assert "ovcli.conf" in result.outputdiff --git a/tests/client/test_lifecycle.py b/tests/client/test_lifecycle.pyindex 09d6193a0..677d4bbdb 100644--- a/tests/client/test_lifecycle.py+++ b/tests/client/test_lifecycle.py@@ -6,7 +6,6 @@from pathlib import Pathfrom openviking import AsyncOpenViking-from openviking.session.user_id import UserIdentifierclass TestClientInitialization:@@ -35,7 +34,7 @@ class TestClientClose:async def test_close_success(self, test_data_dir: Path):"""Test normal close"""await AsyncOpenViking.reset()- client = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))+ client = AsyncOpenViking(path=str(test_data_dir))await client.initialize()await client.close()@@ -46,7 +45,7 @@ class TestClientClose:async def test_close_idempotent(self, test_data_dir: Path):"""Test repeated close is safe"""await AsyncOpenViking.reset()- client = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))+ client = AsyncOpenViking(path=str(test_data_dir))await client.initialize()await client.close()@@ -62,12 +61,12 @@ class TestClientReset:"""Test reset clears singleton"""await AsyncOpenViking.reset()- client1 = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))+ client1 = AsyncOpenViking(path=str(test_data_dir))await client1.initialize()await AsyncOpenViking.reset()- client2 = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))+ client2 = AsyncOpenViking(path=str(test_data_dir))# Should be new instance after resetassert client1 is not client2@@ -81,8 +80,8 @@ class TestClientSingleton:"""Test embedded mode uses singleton"""await AsyncOpenViking.reset()- client1 = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))- client2 = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test"))+ client1 = AsyncOpenViking(path=str(test_data_dir))+ client2 = AsyncOpenViking(path=str(test_data_dir))assert client1 is client2diff --git a/tests/conftest.py b/tests/conftest.pyindex 41a88d634..1e5cf17d7 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -12,7 +12,6 @@ import pytestimport pytest_asynciofrom openviking import AsyncOpenViking-from openviking.session.user_id import UserIdentifier# Test data root directoryTEST_ROOT = Path(__file__).parent@@ -150,7 +149,7 @@ async def client(test_data_dir: Path) -> AsyncGenerator[AsyncOpenViking, None]:"""Create initialized OpenViking client"""await AsyncOpenViking.reset()- client = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test_user"))+ client = AsyncOpenViking(path=str(test_data_dir))await client.initialize()yield client@@ -164,7 +163,7 @@ async def uninitialized_client(test_data_dir: Path) -> AsyncGenerator[AsyncOpenV"""Create uninitialized OpenViking client (for testing initialization flow)"""await AsyncOpenViking.reset()- client = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("test_user"))+ client = AsyncOpenViking(path=str(test_data_dir))yield clientdiff --git a/tests/integration/conftest.py b/tests/integration/conftest.pyindex 756bfae8c..bebed0694 100644--- a/tests/integration/conftest.py+++ b/tests/integration/conftest.py@@ -4,8 +4,7 @@"""Shared fixtures for integration tests.Automatically starts an OpenViking server in a background thread so that-HTTPClient / AsyncOpenViking integration tests can run without a manually-started server process.+AsyncHTTPClient integration tests can run without a manually started server process."""import shutildiff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.pyindex aa8b71a2e..ab4aa7366 100644--- a/tests/integration/test_full_workflow.py+++ b/tests/integration/test_full_workflow.py@@ -10,7 +10,6 @@ import pytest_asynciofrom openviking import AsyncOpenVikingfrom openviking.message import TextPart-from openviking.session.user_id import UserIdentifier@pytest_asyncio.fixture(scope="function")@@ -22,7 +21,7 @@ async def integration_client(test_data_dir: Path):shutil.rmtree(test_data_dir, ignore_errors=True)test_data_dir.mkdir(parents=True, exist_ok=True)- client = AsyncOpenViking(path=str(test_data_dir), user=UserIdentifier.the_default_user("integration_test_user"))+ client = AsyncOpenViking(path=str(test_data_dir))await client.initialize()yield clientdiff --git a/tests/integration/test_http_integration.py b/tests/integration/test_http_integration.pyindex 90f9a2fe2..a152f5085 100644--- a/tests/integration/test_http_integration.py+++ b/tests/integration/test_http_integration.py@@ -9,19 +9,17 @@ defined in ``conftest.py``.import pytestimport pytest_asyncio-from openviking import AsyncOpenViking-from openviking.client import HTTPClient+from openviking.client.http import AsyncHTTPClientfrom openviking.exceptions import NotFoundError-from openviking.session.user_id import UserIdentifierclass TestHTTPClientIntegration:- """Integration tests for HTTPClient."""+ """Integration tests for AsyncHTTPClient."""@pytest_asyncio.fixtureasync def client(self, server_url):- """Create and initialize HTTPClient."""- client = HTTPClient(url=server_url, user=UserIdentifier.the_default_user("test_user"))+ """Create and initialize AsyncHTTPClient."""+ client = AsyncHTTPClient(url=server_url)await client.initialize()yield clientawait client.close()@@ -83,8 +81,8 @@ class TestSessionIntegration:@pytest_asyncio.fixtureasync def client(self, server_url):- """Create and initialize HTTPClient."""- client = HTTPClient(url=server_url, user=UserIdentifier.the_default_user("test_user"))+ """Create and initialize AsyncHTTPClient."""+ client = AsyncHTTPClient(url=server_url)await client.initialize()yield clientawait client.close()@@ -119,43 +117,38 @@ class TestSessionIntegration:assert isinstance(result, list)-class TestAsyncOpenVikingHTTPMode:- """Integration tests for AsyncOpenViking in HTTP mode."""+class TestAsyncHTTPClientIntegration:+ """Integration tests for AsyncHTTPClient as a standalone client."""@pytest_asyncio.fixture- async def ov(self, server_url):- """Create AsyncOpenViking in HTTP mode."""- client = AsyncOpenViking(url=server_url, user=UserIdentifier.the_default_user("test_user"))+ async def client(self, server_url):+ """Create AsyncHTTPClient."""+ client = AsyncHTTPClient(url=server_url)await client.initialize()yield clientawait client.close()@pytest.mark.asyncio- async def test_http_mode_detection(self, ov):- """Test HTTP mode is correctly detected."""- assert isinstance(ov._client, HTTPClient)-- @pytest.mark.asyncio- async def test_find_via_ov(self, ov):- """Test find via AsyncOpenViking."""- result = await ov.find(query="test", limit=5)+ async def test_find_via_client(self, client):+ """Test find via AsyncHTTPClient."""+ result = await client.find(query="test", limit=5)assert result is not None@pytest.mark.asyncio- async def test_ls_via_ov(self, ov):- """Test ls via AsyncOpenViking."""- result = await ov.ls("viking://")+ async def test_ls_via_client(self, client):+ """Test ls via AsyncHTTPClient."""+ result = await client.ls("viking://")assert isinstance(result, list)@pytest.mark.asyncio- async def test_observer_access(self, ov):- """Test observer access in HTTP mode."""- observer = ov.observer+ async def test_observer_access(self, client):+ """Test observer access."""+ observer = client.observerassert observer is not None@pytest.mark.asyncio- async def test_session_via_ov(self, ov):- """Test session creation via AsyncOpenViking."""- session = ov.session()+ async def test_session_via_client(self, client):+ """Test session creation via AsyncHTTPClient."""+ session = client.session()assert session is not Noneassert session._client is not Nonediff --git a/tests/server/conftest.py b/tests/server/conftest.pyindex 9d7499576..5eddf1e22 100644--- a/tests/server/conftest.py+++ b/tests/server/conftest.py@@ -108,7 +108,7 @@ async def client_with_resource(client, service, sample_markdown_file):# ----------------------------------------------------------------------------# SDK fixtures: real uvicorn server + HTTPClient (end-to-end tests)+# SDK fixtures: real uvicorn server + AsyncHTTPClient (end-to-end tests)# ---------------------------------------------------------------------------diff --git a/tests/server/test_http_client_sdk.py b/tests/server/test_http_client_sdk.pyindex d918bed9b..a10080586 100644--- a/tests/server/test_http_client_sdk.py+++ b/tests/server/test_http_client_sdk.py@@ -1,24 +1,22 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: Apache-2.0-"""SDK tests using HTTPClient against a real uvicorn server."""+"""SDK tests using AsyncHTTPClient against a real uvicorn server."""from pathlib import Pathimport pytest_asyncio-from openviking.client.http import HTTPClient-from openviking.session.user_id import UserIdentifier+from openviking.client.http import AsyncHTTPClientfrom tests.server.conftest import SAMPLE_MD_CONTENT, TEST_TMP_DIR@pytest_asyncio.fixture()async def http_client(running_server):- """Create an HTTPClient connected to the running server."""+ """Create an AsyncHTTPClient connected to the running server."""port, svc = running_server- client = HTTPClient(+ client = AsyncHTTPClient(url=f"http://127.0.0.1:{port}",- user=UserIdentifier.the_default_user("sdk_test_user"),)await client.initialize()yield client, svc