Skip to content

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

refactor: extract Service layer from async_client (#50)

qin-ctxef23bdc44449
diff --git a/docs/design/server_client/prompt.md b/docs/design/server_client/prompt.md
index 05d8026b5..dfd2425b8 100644
--- a/docs/design/server_client/prompt.md
+++ b/docs/design/server_client/prompt.md
@@ -24,7 +24,8 @@ openviking/service/
├── search_service.py # 语义搜索
├── session_service.py # 会话管理
├── relation_service.py # 关联管理
-└── pack_service.py # 导入导出
+├── pack_service.py # 导入导出
+└── debug_service.py # 调试服务
```
2. **抽取业务逻辑**:
@@ -34,6 +35,7 @@ openviking/service/
- `SearchService`: find, search
- `SessionService`: session, sessions, add_message, compress, extract
- `RelationService`: link, unlink, relations
+- `DebugService`: get_queue_status, get_vikingdb_status, get_vlm_status, get_system_status, is_healthy
- `PackService`: export_ovpack, import_ovpack
3. **创建 OpenVikingService 主类**:
@@ -86,7 +88,8 @@ openviking/server/
├── relations.py # /api/v1/relations
├── sessions.py # /api/v1/sessions
├── pack.py # /api/v1/pack
- └── system.py # /api/v1/system, /health
+ ├── system.py # /api/v1/system, /health
+ └── debug.py # /api/v1/debug
```
2. **实现统一响应格式**(参考设计文档 5.2 节):
@@ -112,6 +115,7 @@ class Response(BaseModel):
- 会话: POST/GET/DELETE /api/v1/sessions
- 导入导出: POST /api/v1/pack/export, /import
- 系统: GET /health, GET /api/v1/system/status
+- 调试: GET /api/v1/debug/status, GET /api/v1/debug/health
5. **实现服务启动器** (bootstrap.py):
- 加载配置文件 `~/.openviking/server.yaml`
@@ -175,7 +179,10 @@ cli = [
```bash
# 服务管理
openviking serve --path <dir> [--port 8000] [--host 0.0.0.0]
-openviking status
+
+# 调试命令
+openviking status # 系统整体状态(包含 queue/vikingdb/vlm 组件状态)
+openviking health # 快速健康检查
# 资源导入
openviking add-resource <path> [--to <uri>] [--wait] [--timeout N]
@@ -252,6 +259,18 @@ class BaseClient(ABC):
- 实现所有 API 端点的客户端方法
- 处理认证(API Key)
- 处理错误响应,转换为异常
+- 实现 debug 方法(get_status, is_healthy):
+```python
+def get_status(self) -> SystemStatus:
+ """Get system status (same as LocalClient)."""
+ response = self._get("/api/v1/debug/status")
+ return SystemStatus(**response["result"])
+
+def is_healthy(self) -> bool:
+ """Quick health check (same as LocalClient)."""
+ response = self._get("/api/v1/debug/health")
+ return response["healthy"]
+```
4. **实现 LocalClient** (local.py):
- 直接调用 OpenVikingService
diff --git a/docs/design/server_client/server-cli-design.md b/docs/design/server_client/server-cli-design.md
index d05955445..be75647dc 100644
--- a/docs/design/server_client/server-cli-design.md
+++ b/docs/design/server_client/server-cli-design.md
@@ -234,6 +234,7 @@ OpenViking 提供三种接口,面向不同使用场景:
│ │ - SearchService (语义搜索) ││
│ │ - SessionService (会话管理) ││
│ │ - FSService (文件系统操作) ││
+│ │ - DebugService (调试服务) ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
│
@@ -386,7 +387,8 @@ openviking/
│ ├── search_service.py # 语义搜索
│ ├── session_service.py # 会话管理
│ ├── relation_service.py # 关联管理
-│ └── pack_service.py # 导入导出
+│ ├── pack_service.py # 导入导出
+│ └── debug_service.py # 调试服务
│
├── server/ # HTTP Server
│ ├── __init__.py
@@ -400,7 +402,8 @@ openviking/
│ ├── content.py # /api/v1/content
│ ├── search.py # /api/v1/search
│ ├── relations.py # /api/v1/relations
-│ └── sessions.py # /api/v1/sessions
+│ ├── sessions.py # /api/v1/sessions
+│ └── debug.py # /api/v1/debug
│
├── cli/ # CLI 模块
│ ├── __init__.py
@@ -464,6 +467,8 @@ dependencies = [
| `session` | `user` | 创建/获取 Session 对象 |
| `sessions` | - | 获取所有 Session 对象列表 |
| `wait_processed` | `timeout` | 等待处理完成 |
+| `get_status` | - | 获取系统状态(包含 queue/vikingdb/vlm 组件状态) |
+| `is_healthy` | - | 快速健康检查 |
**Session 对象方法:**
@@ -662,6 +667,30 @@ session.compressed # False
}
```
+**debug/status**
+```json
+{
+ "status": "ok",
+ "result": {
+ "is_healthy": true,
+ "components": {
+ "queue": {"name": "queue", "is_healthy": true, "has_errors": false, "details": {...}},
+ "vikingdb": {"name": "vikingdb", "is_healthy": true, "has_errors": false, "details": {...}},
+ "vlm": {"name": "vlm", "is_healthy": true, "has_errors": false, "details": {...}}
+ },
+ "errors": []
+ },
+ "time": 0.05
+}
+```
+
+**debug/health**
+```json
+{
+ "healthy": true
+}
+```
+
### 5.4 错误处理
基于 gRPC 标准状态码,结合 OpenViking 业务场景定制。
@@ -876,6 +905,10 @@ openviking import <file.ovpack> <uri> [--force] [--no-vectorize]
openviking wait [--timeout N]
openviking config show
openviking config init
+
+# 调试命令
+openviking status # 系统整体状态(包含 queue/vikingdb/vlm 组件状态)
+openviking health # 快速健康检查
```
#### 命令分组说明
@@ -887,6 +920,7 @@ openviking config init
| `read/abstract/overview` | 分层上下文 | L0/L1/L2 按需加载 |
| `find/search` | 目录递归检索 | 语义搜索 + 目录定位 |
| `session *` | 会话管理 | 自动压缩、记忆提取 |
+| `status/health` | 调试诊断 | 系统状态查询、健康检查 |
#### 实现 (使用 Typer)
@@ -1182,13 +1216,19 @@ POST /api/v1/system/wait # wait_processed
Body: {"timeout": 60}
```
+#### 调试 `/api/v1/debug`
+```
+GET /api/v1/debug/status # 系统整体状态(包含 queue/vikingdb/vlm 组件状态)
+GET /api/v1/debug/health # 快速健康检查(返回 bool)
+```
+
### 7.4 Server 实现
```python
# openviking/server/app.py
from fastapi import FastAPI, Depends
from openviking.server.auth import verify_api_key
-from openviking.server.routers import resources, filesystem, content, search, sessions
+from openviking.server.routers import resources, filesystem, content, search, sessions, debug
app = FastAPI(
title="OpenViking API",
@@ -1202,6 +1242,7 @@ app.include_router(filesystem.router, prefix="/api/v1/fs", dependencies=[Depends
app.include_router(content.router, prefix="/api/v1/content", dependencies=[Depends(verify_api_key)])
app.include_router(search.router, prefix="/api/v1/search", dependencies=[Depends(verify_api_key)])
app.include_router(sessions.router, prefix="/api/v1/sessions", dependencies=[Depends(verify_api_key)])
+app.include_router(debug.router, prefix="/api/v1/debug", dependencies=[Depends(verify_api_key)])
@app.get("/health")
async def health():
diff --git a/docs/en/api/01-client.md b/docs/en/api/01-client.md
index db60efb29..f57233c0f 100644
--- a/docs/en/api/01-client.md
+++ b/docs/en/api/01-client.md
@@ -252,30 +252,78 @@ ov.OpenViking.reset()
---
-### observers
+### get_status()
-Get observer objects for monitoring.
+Get system status including health status of all components.
**Signature**
```python
-@property
-def observers(self) -> Dict[str, Any]
+def get_status(self) -> SystemStatus
```
+**Parameters**
+
+None.
+
**Returns**
| Type | Description |
|------|-------------|
-| Dict[str, Any] | Observer objects |
+| SystemStatus | System status object |
**Return Structure**
```python
-{
- "queue": QueueObserver, # Queue processing observer
- "vikingdb": VikingDBObserver # Vector database observer
-}
+SystemStatus(
+ is_healthy=True, # Overall system health
+ components={ # Component statuses
+ "queue": ComponentStatus(...),
+ "vikingdb": ComponentStatus(...),
+ "vlm": ComponentStatus(...)
+ },
+ errors=[] # Error list
+)
+```
+
+**Example**
+
+```python
+status = client.get_status()
+print(f"System healthy: {status.is_healthy}")
+print(f"Queue status: {status.components['queue'].is_healthy}")
+```
+
+---
+
+### is_healthy()
+
+Quick health check.
+
+**Signature**
+
+```python
+def is_healthy(self) -> bool
+```
+
+**Parameters**
+
+None.
+
+**Returns**
+
+| Type | Description |
+|------|-------------|
+| bool | True if all components are healthy, False otherwise |
+
+**Example**
+
+```python
+if client.is_healthy():
+ print("System OK")
+else:
+ status = client.get_status()
+ print(f"Errors: {status.errors}")
```
---
diff --git a/docs/en/concepts/01-architecture.md b/docs/en/concepts/01-architecture.md
index dc101a8d9..f92d0daf5 100644
--- a/docs/en/concepts/01-architecture.md
+++ b/docs/en/concepts/01-architecture.md
@@ -13,6 +13,11 @@ OpenViking is a context database designed for AI Agents, unifying all context ty
│ │ Client │ │
│ │ (OpenViking)│ │
│ └──────┬──────┘ │
+│ │ delegates │
+│ ┌──────▼──────┐ │
+│ │ Service │ │
+│ │ Layer │ │
+│ └──────┬──────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
@@ -48,13 +53,28 @@ OpenViking is a context database designed for AI Agents, unifying all context ty
| Module | Responsibility | Key Capabilities |
|--------|----------------|------------------|
-| **Client** | Unified entry | Provides all operation interfaces, coordinates modules |
+| **Client** | Unified entry | Provides all operation interfaces, delegates to Service layer |
+| **Service** | Business logic | FSService, SearchService, SessionService, ResourceService, RelationService, PackService, DebugService |
| **Retrieve** | Context retrieval | Intent analysis (IntentAnalyzer), hierarchical retrieval (HierarchicalRetriever), Rerank |
| **Session** | Session management | Message recording, usage tracking, session compression, memory commit |
| **Parse** | Context extraction | Document parsing (PDF/MD/HTML), tree building (TreeBuilder), async semantic generation |
| **Compressor** | Memory compression | 6-category memory extraction, LLM deduplication decisions |
| **Storage** | Storage layer | VikingFS virtual filesystem, vector index, AGFS integration |
+## Service Layer
+
+The Service layer decouples business logic from the transport layer, enabling reuse across HTTP Server and CLI:
+
+| Service | Responsibility | Key Methods |
+|---------|----------------|-------------|
+| **FSService** | File system operations | ls, mkdir, rm, mv, tree, stat, read, abstract, overview, grep, glob |
+| **SearchService** | Semantic search | search, find |
+| **SessionService** | Session management | session, sessions, compress, extract, delete |
+| **ResourceService** | Resource import | add_resource, add_skill, wait_processed |
+| **RelationService** | Relation management | relations, link, unlink |
+| **PackService** | Import/export | export_ovpack, import_ovpack |
+| **DebugService** | Debug service | get_system_status, get_queue_status, get_vikingdb_status, get_vlm_status, is_healthy |
+
## Dual-Layer Storage
OpenViking uses a dual-layer storage architecture separating content from index (see [Storage Architecture](./05-storage.md)):
diff --git a/docs/zh/api/01-client.md b/docs/zh/api/01-client.md
index 040d47b1f..6b1aae3ed 100644
--- a/docs/zh/api/01-client.md
+++ b/docs/zh/api/01-client.md
@@ -252,30 +252,78 @@ ov.OpenViking.reset()
---
-### observers
+### get_status()
-获取观察者对象,用于监控。
+获取系统状态,包含所有组件的健康状态。
**签名**
```python
-@property
-def observers(self) -> Dict[str, Any]
+def get_status(self) -> SystemStatus
```
+**参数**
+
+无。
+
**返回值**
| 类型 | 说明 |
|------|------|
-| Dict[str, Any] | 观察者对象 |
+| SystemStatus | 系统状态对象 |
**返回结构**
```python
-{
- "queue": QueueObserver, # 队列处理观察者
- "vikingdb": VikingDBObserver # 向量数据库观察者
-}
+SystemStatus(
+ is_healthy=True, # 系统整体是否健康
+ components={ # 各组件状态
+ "queue": ComponentStatus(...),
+ "vikingdb": ComponentStatus(...),
+ "vlm": ComponentStatus(...)
+ },
+ errors=[] # 错误列表
+)
+```
+
+**示例**
+
+```python
+status = client.get_status()
+print(f"系统健康: {status.is_healthy}")
+print(f"队列状态: {status.components['queue'].is_healthy}")
+```
+
+---
+
+### is_healthy()
+
+快速健康检查。
+
+**签名**
+
+```python
+def is_healthy(self) -> bool
+```
+
+**参数**
+
+无。
+
+**返回值**
+
+| 类型 | 说明 |
+|------|------|
+| bool | 所有组件健康返回 True,否则返回 False |
+
+**示例**
+
+```python
+if client.is_healthy():
+ print("系统正常")
+else:
+ status = client.get_status()
+ print(f"错误: {status.errors}")
```
---
diff --git a/docs/zh/concepts/01-architecture.md b/docs/zh/concepts/01-architecture.md
index 6fd066779..8db2f8bb6 100644
--- a/docs/zh/concepts/01-architecture.md
+++ b/docs/zh/concepts/01-architecture.md
@@ -13,6 +13,11 @@ OpenViking 是为 AI Agent 设计的上下文数据库,将所有上下文(Me
│ │ Client │ │
│ │ (OpenViking)│ │
│ └──────┬──────┘ │
+│ │ 委托 │
+│ ┌──────▼──────┐ │
+│ │ Service │ │
+│ │ Layer │ │
+│ └──────┬──────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
@@ -47,13 +52,28 @@ OpenViking 是为 AI Agent 设计的上下文数据库,将所有上下文(Me
| 模块 | 职责 | 关键能力 |
|------|------|---------|
-| **Client** | 统一入口 | 提供所有操作接口,协调各模块 |
+| **Client** | 统一入口 | 提供所有操作接口,委托给 Service 层 |
+| **Service** | 业务逻辑 | FSService、SearchService、SessionService、ResourceService、RelationService、PackService、DebugService |
| **Retrieve** | 上下文检索 | 意图分析(IntentAnalyzer)、层级检索(HierarchicalRetriever)、Rerank 精排 |
| **Session** | 会话管理 | 消息记录、使用追踪、会话压缩、记忆提交 |
| **Parse** | 上下文提取 | 文档解析(PDF/MD/HTML)、树构建(TreeBuilder)、异步语义生成 |
| **Compressor** | 记忆压缩 | 6 种记忆分类提取、LLM 去重决策 |
| **Storage** | 存储层 | VikingFS 虚拟文件系统、向量索引、AGFS 集成 |
+## Service 层
+
+Service 层将业务逻辑与传输层解耦,便于 HTTP Server 和 CLI 复用:
+
+| Service | 职责 | 主要方法 |
+|---------|------|----------|
+| **FSService** | 文件系统操作 | ls, mkdir, rm, mv, tree, stat, read, abstract, overview, grep, glob |
+| **SearchService** | 语义搜索 | search, find |
+| **SessionService** | 会话管理 | session, sessions, compress, extract, delete |
+| **ResourceService** | 资源导入 | add_resource, add_skill, wait_processed |
+| **RelationService** | 关联管理 | relations, link, unlink |
+| **PackService** | 导入导出 | export_ovpack, import_ovpack |
+| **DebugService** | 调试服务 | get_system_status, get_queue_status, get_vikingdb_status, get_vlm_status, is_healthy |
+
## 双层存储
OpenViking 采用双层存储架构,实现内容与索引分离(详见 [存储架构](./05-storage.md)):
diff --git a/openviking/async_client.py b/openviking/async_client.py
index ac66128e4..d56c9637b 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -2,31 +2,18 @@
# SPDX-License-Identifier: Apache-2.0
"""
Async OpenViking client implementation.
+
+This is a compatibility layer that delegates to OpenVikingService.
"""
-# Standard library imports
import threading
from typing import Any, Dict, List, Optional
-# Local imports - Core modules
-from openviking.agfs_manager import AGFSManager
-from openviking.core.directories import DirectoryInitializer
+from openviking.service.core import OpenVikingService
+from openviking.service.debug_service import SystemStatus
from openviking.session import Session
-from openviking.session.compressor import SessionCompressor
-from openviking.storage import VikingDBManager
-from openviking.storage.collection_schemas import init_context_collection
-from openviking.storage.local_fs import export_ovpack as local_export_ovpack
-from openviking.storage.local_fs import import_ovpack as local_import_ovpack
-from openviking.storage.observers import QueueObserver, VikingDBObserver, VLMObserver
-from openviking.storage.queuefs import get_queue_manager
-from openviking.storage.viking_fs import VikingFS, init_viking_fs
from openviking.utils import get_logger
-from openviking.utils.config import OpenVikingConfig, get_openviking_config
-from openviking.utils.config.open_viking_config import initialize_openviking_config
-from openviking.utils.config.storage_config import StorageConfig
-from openviking.utils.resource_processor import ResourceProcessor
-from openviking.utils.skill_processor import SkillProcessor
-from openviking.utils.uri import VikingURI
+from openviking.utils.config import OpenVikingConfig
logger = get_logger(__name__)
@@ -114,76 +101,68 @@ class AsyncOpenViking:
if hasattr(self, "_singleton_initialized") and self._singleton_initialized:
return
- # Initialize config
- config = initialize_openviking_config(
- config=config,
- user=user,
+ # Create the service layer
+ self._service = OpenVikingService(
path=path,
vectordb_url=vectordb_url,
agfs_url=agfs_url,
- )
- self._config = config
- self.user = config.user
-
- self._agfs_manager = None
- self._agfs_url = None
- self._vikingdb_manager = self.__init_storage(config.storage)
-
- # Get embedder instance - must succeed for proper initialization
- self._embedder: Optional[Any] = None
- self._embedder = config.embedding.get_embedder()
- logger.info(
- f"Initialized embedder (dim {config.embedding.dimension}, sparse {self._embedder.is_sparse})"
+ user=user,
+ config=config,
)
- # Initialize VikingFS (will be created in _ensure_initialized)
- self._viking_fs: Optional["VikingFS"] = None
+ self.user = self._service.user
+ self._initialized = False
+ self._singleton_initialized = True
- # Initialize coordinated writer
- self._resource_processor: Optional[ResourceProcessor] = None
+ # ============= Properties for backward compatibility =============
- # Initialize compressor
- self._session_compressor: Optional["SessionCompressor"] = None
+ @property
+ def viking_fs(self):
+ return self._service.viking_fs
- # Initialize collections flag
- self._initialized = False
+ @property
+ def _viking_fs(self):
+ return self._service.viking_fs
- # Mark singleton as initialized
- self._singleton_initialized = True
+ @property
+ def _vikingdb_manager(self):
+ return self._service.vikingdb_manager
@property
- def viking_fs(self) -> "VikingFS":
- return self._viking_fs
-
- def __init_storage(self, config: StorageConfig) -> VikingDBManager:
- """Initialize storage resources."""
- if config.agfs.backend == "local":
- # Initialize AGFS manager (auto-start subprocess)
- self._agfs_manager = AGFSManager(config=config.agfs)
- self._agfs_manager.start()
- self._agfs_url = self._agfs_manager.url
- else:
- self._agfs_url = config.agfs.url
-
- self._vikingdb_manager = VikingDBManager(
- vectordb_config=config.vectordb, agfs_config=config.agfs
- )
- return self._vikingdb_manager
+ def _session_compressor(self):
+ return self._service.session_compressor
+
+ @property
+ def _config(self):
+ return self._service._config
+
+ @property
+ def _agfs_manager(self):
+ return self._service._agfs_manager
+
+ @property
+ def _resource_processor(self):
+ return self._service._resource_processor
+
+ @property
+ def _skill_processor(self):
+ return self._service._skill_processor
+
+ # ============= Lifecycle methods =============
+
+ async def initialize(self) -> None:
+ """Initialize OpenViking storage and indexes."""
+ await self._service.initialize()
+ self._initialized = True
+
+ async def _ensure_initialized(self):
+ """Ensure storage collections are initialized."""
+ if not self._initialized:
+ await self.initialize()
async def close(self) -> None:
"""Close OpenViking and release resources."""
- if self._agfs_manager:
- self._agfs_manager.stop()
- self._agfs_manager = None
-
- if self._vikingdb_manager:
- await self._vikingdb_manager.close()
- self._vikingdb_manager = None
-
- self._viking_fs = None
- self._resource_processor = None
- self._skill_processor = None
- self._session_compressor = None
+ await self._service.close()
self._initialized = False
self._singleton_initialized = False
@@ -197,53 +176,7 @@ class AsyncOpenViking:
cls._instance._singleton_initialized = False
cls._instance = None
- async def initialize(self) -> None:
- """Initialize OpenViking storage and indexes."""
- await self._ensure_initialized()
-
- async def _ensure_initialized(self):
- """Ensure storage collections are initialized."""
- if self._vikingdb_manager is None:
- self._vikingdb_manager = self.__init_storage(self._config.storage)
-
- if self._embedder is None:
- self._embedder = self._config.embedding.get_embedder()
-
- if self._initialized:
- logger.debug(
- f"Already initialized, _session_compressor={bool(self._session_compressor)}"
- )
- return
-
- assert self._vikingdb_manager is not None, "VikingDB manager must be initialized"
- config = get_openviking_config()
-
- # Create single context collection
- await init_context_collection(self._vikingdb_manager)
- # Initialize VikingFS (singleton)
- self._viking_fs = init_viking_fs(
- agfs_url=self._agfs_url or "http://localhost:8080",
- query_embedder=self._embedder,
- rerank_config=config.rerank,
- vector_store=self._vikingdb_manager,
- timeout=config.storage.agfs.timeout,
- )
-
- # Initialize user directories if user is provided
- directory_initializer = DirectoryInitializer(vikingdb=self._vikingdb_manager)
- await directory_initializer.initialize_all()
-
- # Initialize user directories
- count = await directory_initializer.initialize_user_directories()
- logger.info(f"Initialized {count} directories for user scope")
-
- # Initialize processors
- self._resource_processor = ResourceProcessor(vikingdb=self._vikingdb_manager)
- self._skill_processor = SkillProcessor(vikingdb=self._vikingdb_manager)
- self._session_compressor = SessionCompressor(vikingdb=self._vikingdb_manager)
-
- # Mark collections as initialized
- self._initialized = True
+ # ============= Session methods =============
def session(self, session_id: Optional[str] = None) -> Session:
"""
@@ -253,11 +186,15 @@ class AsyncOpenViking:
session_id: Session ID, creates a new session (auto-generated ID) if None
"""
return Session(
- client=self,
+ viking_fs=self._service.viking_fs,
+ vikingdb_manager=self._service.vikingdb_manager,
+ session_compressor=self._service.session_compressor,
user=self.user,
session_id=session_id,
)
+ # ============= Resource methods =============
+
async def add_resource(
self,
path: str,
@@ -274,80 +211,18 @@ class AsyncOpenViking:
timeout: Wait timeout in seconds
"""
await self._ensure_initialized()
-
- if not self._resource_processor:
- raise RuntimeError("CoordinatedWriter not initialized")
-
- # add_resource only supports resources scope
- if target and target.startswith("viking://"):
- parsed = VikingURI(target)
- if parsed.scope != "resources":
- raise ValueError(
- f"add_resource only supports resources scope, use dedicated interface to add {parsed.scope} content"
- )
-
- result = await self._resource_processor.process_resource(
+ return await self._service.resources.add_resource(
path=path,
+ target=target,
reason=reason,
instruction=instruction,
- scope="resources",
- target=target,
+ wait=wait,
+ timeout=timeout,
)
- if wait:
- from openviking.storage.queuefs import get_queue_manager
-
- qm = get_queue_manager()
- status = await qm.wait_complete(timeout=timeout)
- result["queue_status"] = {
- name: {
- "processed": s.processed,
- "error_count": s.error_count,
- "errors": [{"message": e.message} for e in s.errors],
- }
- for name, s in status.items()
- }
-
- return result
-
async def wait_processed(self, timeout: float = None) -> Dict[str, Any]:
- from openviking.storage.queuefs import get_queue_manager
-
- qm = get_queue_manager()
- status = await qm.wait_complete(timeout=timeout)
- status = {
- name: {
- "processed": s.processed,
- "error_count": s.error_count,
- "errors": [{"message": e.message} for e in s.errors],
- }
- for name, s in status.items()
- }
- return status
-
- @property
- def observers(self):
- queue_manager = get_queue_manager()
- queue_observer = QueueObserver(queue_manager)
- vikingdb_observer = VikingDBObserver(self._vikingdb_manager)
- config = get_openviking_config()
- vlm_observer = VLMObserver(config.vlm.get_vlm_instance())
-
- available_observers = {
- "queue": queue_observer,
- "vikingdb": vikingdb_observer,
- "vlm": vlm_observer,
- }
- result = {}
- for name in available_observers.keys():
- observer_name = name.lower()
- if observer_name not in available_observers:
- raise ValueError(
- f"Unknown observer: {observer_name}. "
- f"Available observers: {list(available_observers.keys())}"
- )
- result[observer_name] = available_observers[observer_name]
- return result
+ """Wait for all queued processing to complete."""
+ return await self._service.resources.wait_processed(timeout=timeout)
async def add_skill(
self,
@@ -362,31 +237,13 @@ class AsyncOpenViking:
timeout: Wait timeout in seconds
"""
await self._ensure_initialized()
-
- if not self.viking_fs:
- raise RuntimeError("VikingFS not initialized")
-
- result = await self._skill_processor.process_skill(
+ return await self._service.resources.add_skill(
data=data,
- viking_fs=self.viking_fs,
- user=self.user,
+ wait=wait,
+ timeout=timeout,
)
- if wait:
- from openviking.storage.queuefs import get_queue_manager
-
- qm = get_queue_manager()
- status = await qm.wait_complete(timeout=timeout)
- result["queue_status"] = {
- name: {
- "processed": s.processed,
- "error_count": s.error_count,
- "errors": [{"message": e.message} for e in s.errors],
- }
- for name, s in status.items()
- }
-
- return result
+ # ============= Search methods =============
async def search(
self,
@@ -405,32 +262,21 @@ class AsyncOpenViking:
target_uri: Target directory URI
session: Session object for context
limit: Max results
- grep: Keyword filters
filter: Metadata filters
Returns:
FindResult
"""
await self._ensure_initialized()
-
- session_info = None
- if session:
- session_info = session.get_context_for_search(query)
-
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
-
- return await self._viking_fs.search(
+ return await self._service.search.search(
query=query,
target_uri=target_uri,
- session_info=session_info,
+ session=session,
limit=limit,
score_threshold=score_threshold,
filter=filter,
)
- # ============= VikingFS specific capabilities =============
-
async def find(
self,
query: str,
@@ -441,9 +287,7 @@ class AsyncOpenViking:
):
"""Semantic search"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.find(
+ return await self._service.search.find(
query=query,
target_uri=target_uri,
limit=limit,
@@ -451,33 +295,22 @@ class AsyncOpenViking:
filter=filter,
)
+ # ============= FS methods =============
+
async def abstract(self, uri: str) -> str:
"""Read L0 abstract (.abstract.md)"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.abstract(uri)
+ return await self._service.fs.abstract(uri)
async def overview(self, uri: str) -> str:
"""Read L1 overview (.overview.md)"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.overview(uri)
+ return await self._service.fs.overview(uri)
async def read(self, uri: str) -> str:
"""Read file content"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.read_file(uri)
-
- async def relations(self, uri: str) -> List[Dict[str, Any]]:
- """Get relations (returns [{"uri": "...", "reason": "..."}, ...])"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.relations(uri)
+ return await self._service.fs.read(uri)
async def ls(self, uri: str, **kwargs) -> List[Any]:
"""
@@ -489,21 +322,51 @@ class AsyncOpenViking:
recursive: List all subdirectories recursively (bool, default: False)
"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
-
recursive = kwargs.get("recursive", False)
simple = kwargs.get("simple", False)
+ return await self._service.fs.ls(uri, recursive=recursive, simple=simple)
+
+ async def rm(self, uri: str, recursive: bool = False) -> None:
+ """Remove resource"""
+ await self._ensure_initialized()
+ await self._service.fs.rm(uri, recursive=recursive)
+
+ async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
+ """Content search"""
+ await self._ensure_initialized()
+ return await self._service.fs.grep(uri, pattern, case_insensitive=case_insensitive)
+
+ async def glob(self, pattern: str, uri: str = "viking://") -> Dict:
+ """File pattern matching"""
+ await self._ensure_initialized()
+ return await self._service.fs.glob(pattern, uri=uri)
- if recursive:
- entries = await self._viking_fs.tree(uri)
- else:
- entries = await self._viking_fs.ls(uri)
+ async def mv(self, from_uri: str, to_uri: str) -> None:
+ """Move resource"""
+ await self._ensure_initialized()
+ await self._service.fs.mv(from_uri, to_uri)
+
+ async def tree(self, uri: str) -> Dict:
+ """Get directory tree"""
+ await self._ensure_initialized()
+ return await self._service.fs.tree(uri)
+
+ async def mkdir(self, uri: str) -> None:
+ """Create directory"""
+ await self._ensure_initialized()
+ await self._service.fs.mkdir(uri)
+
+ async def stat(self, uri: str) -> Dict:
+ """Get resource status"""
+ await self._ensure_initialized()
+ return await self._service.fs.stat(uri)
- if simple:
- return [e.get("rel_path", e.get("name", "")) for e in entries]
- else:
- return entries
+ # ============= Relation methods =============
+
+ async def relations(self, uri: str) -> List[Dict[str, Any]]:
+ """Get relations (returns [{"uri": "...", "reason": "..."}, ...])"""
+ await self._ensure_initialized()
+ return await self._service.relations.relations(uri)
async def link(self, from_uri: str, uris: Any, reason: str = "") -> None:
"""
@@ -515,9 +378,7 @@ class AsyncOpenViking:
reason: Reason for linking
"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- await self.viking_fs.link(from_uri, uris, reason)
+ await self._service.relations.link(from_uri, uris, reason)
async def unlink(self, from_uri: str, uri: str) -> None:
"""
@@ -528,9 +389,9 @@ class AsyncOpenViking:
uri: Target URI to remove
"""
await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- await self._viking_fs.unlink(from_uri, uri)
+ await self._service.relations.unlink(from_uri, uri)
+
+ # ============= Pack methods =============
async def export_ovpack(self, uri: str, to: str) -> str:
"""
@@ -544,7 +405,7 @@ class AsyncOpenViking:
Exported file path
"""
await self._ensure_initialized()
- return await local_export_ovpack(self._viking_fs, uri, to)
+ return await self._service.pack.export_ovpack(uri, to)
async def import_ovpack(
self, file_path: str, parent: str, force: bool = False, vectorize: bool = True
@@ -562,55 +423,22 @@ class AsyncOpenViking:
Imported root resource URI
"""
await self._ensure_initialized()
- return await local_import_ovpack(
- self._viking_fs, file_path, parent, force=force, vectorize=vectorize
- )
+ return await self._service.pack.import_ovpack(file_path, parent, force=force, vectorize=vectorize)
- async def rm(self, uri: str, recursive: bool = False) -> None:
- """Remove resource"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- await self._viking_fs.rm(uri, recursive=recursive)
+ # ============= Debug methods =============
- async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
- """Content search"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.grep(uri, pattern, case_insensitive=case_insensitive)
-
- async def glob(self, pattern: str, uri: str = "viking://") -> Dict:
- """File pattern matching"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.glob(pattern, uri=uri)
+ def get_status(self) -> SystemStatus:
+ """Get system status.
- async def mv(self, from_uri: str, to_uri: str) -> None:
- """Move resource"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- await self._viking_fs.mv(from_uri, to_uri)
-
- async def tree(self, uri: str) -> Dict:
- """Get directory tree"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.tree(uri)
+ Returns:
+ SystemStatus containing health status of all components.
+ """
+ return self._service.debug.get_system_status()
- async def mkdir(self, uri: str) -> None:
- """Create directory"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- await self._viking_fs.mkdir(uri)
+ def is_healthy(self) -> bool:
+ """Quick health check.
- async def stat(self, uri: str) -> Dict:
- """Get resource status"""
- await self._ensure_initialized()
- if not self._viking_fs:
- raise RuntimeError("VikingFS not initialized")
- return await self._viking_fs.stat(uri)
+ Returns:
+ True if all components are healthy, False otherwise.
+ """
+ return self._service.debug.is_healthy()
diff --git a/openviking/exceptions.py b/openviking/exceptions.py
new file mode 100644
index 000000000..3f3e15d3c
--- /dev/null
+++ b/openviking/exceptions.py
@@ -0,0 +1,150 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unified exception classes for OpenViking.
+
+Based on gRPC standard status codes for consistency across service boundaries.
+"""
+
+from typing import Optional
+
+
+class OpenVikingError(Exception):
+ """Base exception for all OpenViking errors."""
+
+ def __init__(self, message: str, code: str = "UNKNOWN", details: Optional[dict] = None):
+ super().__init__(message)
+ self.message = message
+ self.code = code
+ self.details = details or {}
+
+
+# ============= Argument Errors =============
+
+
+class InvalidArgumentError(OpenVikingError):
+ """Invalid argument provided."""
+
+ def __init__(self, message: str, details: Optional[dict] = None):
+ super().__init__(message, code="INVALID_ARGUMENT", details=details)
+
+
+class InvalidURIError(InvalidArgumentError):
+ """Invalid Viking URI format."""
+
+ def __init__(self, uri: str, reason: str = ""):
+ message = f"Invalid URI: {uri}"
+ if reason:
+ message += f" ({reason})"
+ super().__init__(message, details={"uri": uri, "reason": reason})
+
+
+# ============= Resource Errors =============
+
+
+class NotFoundError(OpenVikingError):
+ """Resource not found."""
+
+ def __init__(self, resource: str, resource_type: str = "resource"):
+ message = f"{resource_type.capitalize()} not found: {resource}"
+ super().__init__(message, code="NOT_FOUND", details={"resource": resource, "type": resource_type})
+
+
+class AlreadyExistsError(OpenVikingError):
+ """Resource already exists."""
+
+ def __init__(self, resource: str, resource_type: str = "resource"):
+ message = f"{resource_type.capitalize()} already exists: {resource}"
+ super().__init__(message, code="ALREADY_EXISTS", details={"resource": resource, "type": resource_type})
+
+
+# ============= Authentication Errors =============
+
+
+class UnauthenticatedError(OpenVikingError):
+ """Authentication required but not provided or invalid."""
+
+ def __init__(self, message: str = "Authentication required"):
+ super().__init__(message, code="UNAUTHENTICATED")
+
+
+class PermissionDeniedError(OpenVikingError):
+ """Permission denied for the requested operation."""
+
+ def __init__(self, message: str = "Permission denied", resource: Optional[str] = None):
+ details = {"resource": resource} if resource else {}
+ super().__init__(message, code="PERMISSION_DENIED", details=details)
+
+
+# ============= Service Errors =============
+
+
+class UnavailableError(OpenVikingError):
+ """Service temporarily unavailable."""
+
+ def __init__(self, service: str = "service", reason: str = ""):
+ message = f"{service.capitalize()} unavailable"
+ if reason:
+ message += f": {reason}"
+ super().__init__(message, code="UNAVAILABLE", details={"service": service, "reason": reason})
+
+
+class InternalError(OpenVikingError):
+ """Internal server error."""
+
+ def __init__(self, message: str = "Internal error", cause: Optional[Exception] = None):
+ details = {"cause": str(cause)} if cause else {}
+ super().__init__(message, code="INTERNAL", details=details)
+
+
+class DeadlineExceededError(OpenVikingError):
+ """Operation timed out."""
+
+ def __init__(self, operation: str = "operation", timeout: Optional[float] = None):
+ message = f"{operation.capitalize()} timed out"
+ if timeout:
+ message += f" after {timeout}s"
+ super().__init__(message, code="DEADLINE_EXCEEDED", details={"operation": operation, "timeout": timeout})
+
+
+# ============= Business Errors =============
+
+
+class ProcessingError(OpenVikingError):
+ """Error during resource processing."""
+
+ def __init__(self, message: str, source: Optional[str] = None):
+ details = {"source": source} if source else {}
+ super().__init__(message, code="PROCESSING_ERROR", details=details)
+
+
+class EmbeddingFailedError(ProcessingError):
+ """Embedding generation failed."""
+
+ def __init__(self, message: str = "Embedding generation failed", source: Optional[str] = None):
+ super().__init__(message, source=source)
+ self.code = "EMBEDDING_FAILED"
+
+
+class VLMFailedError(ProcessingError):
+ """VLM processing failed."""
+
+ def __init__(self, message: str = "VLM processing failed", source: Optional[str] = None):
+ super().__init__(message, source=source)
+ self.code = "VLM_FAILED"
+
+
+class SessionExpiredError(OpenVikingError):
+ """Session has expired."""
+
+ def __init__(self, session_id: str):
+ message = f"Session expired: {session_id}"
+ super().__init__(message, code="SESSION_EXPIRED", details={"session_id": session_id})
+
+
+class NotInitializedError(OpenVikingError):
+ """Service or component not initialized."""
+
+ def __init__(self, component: str = "service"):
+ message = f"{component.capitalize()} not initialized. Call initialize() first."
+ super().__init__(message, code="NOT_INITIALIZED", details={"component": component})
diff --git a/openviking/service/__init__.py b/openviking/service/__init__.py
new file mode 100644
index 000000000..c9d2f7006
--- /dev/null
+++ b/openviking/service/__init__.py
@@ -0,0 +1,30 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Service layer for OpenViking.
+
+Provides business logic decoupled from transport layer,
+enabling reuse across HTTP Server and CLI.
+"""
+
+from openviking.service.core import OpenVikingService
+from openviking.service.debug_service import ComponentStatus, DebugService, SystemStatus
+from openviking.service.fs_service import FSService
+from openviking.service.pack_service import PackService
+from openviking.service.relation_service import RelationService
+from openviking.service.resource_service import ResourceService
+from openviking.service.search_service import SearchService
+from openviking.service.session_service import SessionService
+
+__all__ = [
+ "OpenVikingService",
+ "ComponentStatus",
+ "DebugService",
+ "SystemStatus",
+ "FSService",
+ "RelationService",
+ "PackService",
+ "SearchService",
+ "ResourceService",
+ "SessionService",
+]
diff --git a/openviking/service/core.py b/openviking/service/core.py
new file mode 100644
index 000000000..79b33659f
--- /dev/null
+++ b/openviking/service/core.py
@@ -0,0 +1,248 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+OpenViking Service Core.
+
+Main service class that composes all sub-services and manages infrastructure lifecycle.
+"""
+
+from typing import Any, Optional
+
+from openviking.agfs_manager import AGFSManager
+from openviking.core.directories import DirectoryInitializer
+from openviking.exceptions import NotInitializedError
+from openviking.service.debug_service import DebugService
+from openviking.service.fs_service import FSService
+from openviking.service.pack_service import PackService
+from openviking.service.relation_service import RelationService
+from openviking.service.resource_service import ResourceService
+from openviking.service.search_service import SearchService
+from openviking.service.session_service import SessionService
+from openviking.session.compressor import SessionCompressor
+from openviking.storage import VikingDBManager
+from openviking.storage.collection_schemas import init_context_collection
+from openviking.storage.viking_fs import VikingFS, init_viking_fs
+from openviking.utils import get_logger
+from openviking.utils.config import OpenVikingConfig, get_openviking_config
+from openviking.utils.config.open_viking_config import initialize_openviking_config
+from openviking.utils.config.storage_config import StorageConfig
+from openviking.utils.resource_processor import ResourceProcessor
+from openviking.utils.skill_processor import SkillProcessor
+
+logger = get_logger(__name__)
+
+
+class OpenVikingService:
+ """
+ OpenViking main service class.
+
+ Composes all sub-services and manages infrastructure lifecycle.
+ """
+
+ def __init__(
+ self,
+ path: Optional[str] = None,
+ vectordb_url: Optional[str] = None,
+ agfs_url: Optional[str] = None,
+ user: Optional[str] = None,
+ config: Optional[OpenVikingConfig] = None,
+ ):
+ """Initialize OpenViking service.
+
+ Args:
+ path: Local storage path for embedded mode.
+ vectordb_url: Remote VectorDB service URL for service mode.
+ agfs_url: Remote AGFS service URL for service mode.
+ user: Username for session management.
+ config: OpenVikingConfig object for advanced configuration.
+ """
+ # Initialize config
+ config = initialize_openviking_config(
+ config=config,
+ user=user,
+ path=path,
+ vectordb_url=vectordb_url,
+ agfs_url=agfs_url,
+ )
+ self._config = config
+ self.user = config.user
+
+ # Infrastructure
+ self._agfs_manager: Optional[AGFSManager] = None
+ self._agfs_url: Optional[str] = None
+ self._vikingdb_manager: Optional[VikingDBManager] = None
+ self._viking_fs: Optional[VikingFS] = None
+ self._embedder: Optional[Any] = None
+ self._resource_processor: Optional[ResourceProcessor] = None
+ self._skill_processor: Optional[SkillProcessor] = None
+ self._session_compressor: Optional[SessionCompressor] = None
+
+ # Sub-services
+ self._fs_service = FSService()
+ self._relation_service = RelationService()
+ self._pack_service = PackService()
+ self._search_service = SearchService()
+ self._resource_service = ResourceService()
+ self._session_service = SessionService()
+ self._debug_service = DebugService()
+
+ # State
+ self._initialized = False
+
+ # Initialize storage
+ self._init_storage(config.storage)
+
+ # Initialize embedder
+ self._embedder = config.embedding.get_embedder()
+ logger.info(
+ f"Initialized embedder (dim {config.embedding.dimension}, sparse {self._embedder.is_sparse})"
+ )
+
+ def _init_storage(self, config: StorageConfig) -> None:
+ """Initialize storage resources."""
+ if config.agfs.backend == "local":
+ self._agfs_manager = AGFSManager(config=config.agfs)
+ self._agfs_manager.start()
+ self._agfs_url = self._agfs_manager.url
+ else:
+ self._agfs_url = config.agfs.url
+
+ self._vikingdb_manager = VikingDBManager(
+ vectordb_config=config.vectordb, agfs_config=config.agfs
+ )
+
+ @property
+ def viking_fs(self) -> Optional[VikingFS]:
+ """Get VikingFS instance."""
+ return self._viking_fs
+
+ @property
+ def vikingdb_manager(self) -> Optional[VikingDBManager]:
+ """Get VikingDBManager instance."""
+ return self._vikingdb_manager
+
+ @property
+ def session_compressor(self) -> Optional[SessionCompressor]:
+ """Get SessionCompressor instance."""
+ return self._session_compressor
+
+ @property
+ def fs(self) -> FSService:
+ """Get FSService instance."""
+ return self._fs_service
+
+ @property
+ def relations(self) -> RelationService:
+ """Get RelationService instance."""
+ return self._relation_service
+
+ @property
+ def pack(self) -> PackService:
+ """Get PackService instance."""
+ return self._pack_service
+
+ @property
+ def search(self) -> SearchService:
+ """Get SearchService instance."""
+ return self._search_service
+
+ @property
+ def resources(self) -> ResourceService:
+ """Get ResourceService instance."""
+ return self._resource_service
+
+ @property
+ def sessions(self) -> SessionService:
+ """Get SessionService instance."""
+ return self._session_service
+
+ @property
+ def debug(self) -> DebugService:
+ """Get DebugService instance."""
+ return self._debug_service
+
+ async def initialize(self) -> None:
+ """Initialize OpenViking storage and indexes."""
+ if self._initialized:
+ logger.debug("Already initialized")
+ return
+
+ if self._vikingdb_manager is None:
+ self._init_storage(self._config.storage)
+
+ if self._embedder is None:
+ self._embedder = self._config.embedding.get_embedder()
+
+ config = get_openviking_config()
+
+ # Create context collection
+ await init_context_collection(self._vikingdb_manager)
+
+ # Initialize VikingFS
+ self._viking_fs = init_viking_fs(
+ agfs_url=self._agfs_url or "http://localhost:8080",
+ query_embedder=self._embedder,
+ rerank_config=config.rerank,
+ vector_store=self._vikingdb_manager,
+ timeout=config.storage.agfs.timeout,
+ )
+
+ # Initialize directories
+ directory_initializer = DirectoryInitializer(vikingdb=self._vikingdb_manager)
+ await directory_initializer.initialize_all()
+ count = await directory_initializer.initialize_user_directories()
+ logger.info(f"Initialized {count} directories for user scope")
+
+ # Initialize processors
+ self._resource_processor = ResourceProcessor(vikingdb=self._vikingdb_manager)
+ self._skill_processor = SkillProcessor(vikingdb=self._vikingdb_manager)
+ self._session_compressor = SessionCompressor(vikingdb=self._vikingdb_manager)
+
+ # Wire up sub-services
+ self._fs_service.set_viking_fs(self._viking_fs)
+ self._relation_service.set_viking_fs(self._viking_fs)
+ self._pack_service.set_viking_fs(self._viking_fs)
+ self._search_service.set_viking_fs(self._viking_fs)
+ self._resource_service.set_dependencies(
+ vikingdb=self._vikingdb_manager,
+ viking_fs=self._viking_fs,
+ resource_processor=self._resource_processor,
+ skill_processor=self._skill_processor,
+ user=self.user,
+ )
+ self._session_service.set_dependencies(
+ vikingdb=self._vikingdb_manager,
+ viking_fs=self._viking_fs,
+ session_compressor=self._session_compressor,
+ user=self.user,
+ )
+ self._debug_service.set_dependencies(
+ vikingdb=self._vikingdb_manager,
+ config=self._config,
+ )
+
+ self._initialized = True
+ logger.info("OpenVikingService initialized")
+
+ async def close(self) -> None:
+ """Close OpenViking and release resources."""
+ if self._agfs_manager:
+ self._agfs_manager.stop()
+ self._agfs_manager = None
+
+ if self._vikingdb_manager:
+ await self._vikingdb_manager.close()
+ self._vikingdb_manager = None
+
+ self._viking_fs = None
+ self._resource_processor = None
+ self._skill_processor = None
+ self._session_compressor = None
+ self._initialized = False
+
+ logger.info("OpenVikingService closed")
+
+ def _ensure_initialized(self) -> None:
+ """Ensure service is initialized."""
+ if not self._initialized:
+ raise NotInitializedError("OpenVikingService")
diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.py
new file mode 100644
index 000000000..3de83d827
--- /dev/null
+++ b/openviking/service/debug_service.py
@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Debug Service - provides system status query and health check.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from openviking.storage import VikingDBManager
+from openviking.storage.observers import QueueObserver, VikingDBObserver, VLMObserver
+from openviking.storage.queuefs import get_queue_manager
+from openviking.utils.config import OpenVikingConfig
+
+
+@dataclass
+class ComponentStatus:
+ """Component status."""
+
+ name: str
+ is_healthy: bool
+ has_errors: bool
+ details: Dict[str, Any]
+
+
+@dataclass
+class SystemStatus:
+ """System overall status."""
+
+ is_healthy: bool
+ components: Dict[str, ComponentStatus]
+ errors: List[str]
+
+
+class DebugService:
+ """Debug service - provides system status query and health check."""
+
+ def __init__(
+ self,
+ vikingdb: Optional[VikingDBManager] = None,
+ config: Optional[OpenVikingConfig] = None,
+ ):
+ self._vikingdb = vikingdb
+ self._config = config
+
+ def set_dependencies(
+ self,
+ vikingdb: VikingDBManager,
+ config: OpenVikingConfig,
+ ) -> None:
+ """Set dependencies after initialization."""
+ self._vikingdb = vikingdb
+ self._config = config
+
+ def get_queue_status(self) -> ComponentStatus:
+ """Get queue status."""
+ observer = QueueObserver(get_queue_manager())
+ return ComponentStatus(
+ name="queue",
+ is_healthy=observer.is_healthy(),
+ has_errors=observer.has_errors(),
+ details={"status_table": observer.get_status_table()},
+ )
+
+ def get_vikingdb_status(self) -> ComponentStatus:
+ """Get VikingDB status."""
+ observer = VikingDBObserver(self._vikingdb)
+ return ComponentStatus(
+ name="vikingdb",
+ is_healthy=observer.is_healthy(),
+ has_errors=observer.has_errors(),
+ details={"status_table": observer.get_status_table()},
+ )
+
+ def get_vlm_status(self) -> ComponentStatus:
+ """Get VLM status."""
+ observer = VLMObserver(self._config.vlm.get_vlm_instance())
+ return ComponentStatus(
+ name="vlm",
+ is_healthy=observer.is_healthy(),
+ has_errors=observer.has_errors(),
+ details={"status_table": observer.get_status_table()},
+ )
+
+ def get_system_status(self) -> SystemStatus:
+ """Get system overall status."""
+ components = {
+ "queue": self.get_queue_status(),
+ "vikingdb": self.get_vikingdb_status(),
+ "vlm": self.get_vlm_status(),
+ }
+ errors = [f"{c.name} has errors" for c in components.values() if c.has_errors]
+ return SystemStatus(
+ is_healthy=all(c.is_healthy for c in components.values()),
+ components=components,
+ errors=errors,
+ )
+
+ def is_healthy(self) -> bool:
+ """Quick health check."""
+ return self.get_system_status().is_healthy
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
new file mode 100644
index 000000000..00b5afc1c
--- /dev/null
+++ b/openviking/service/fs_service.py
@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+File System Service for OpenViking.
+
+Provides file system operations: ls, mkdir, rm, mv, tree, stat, read, abstract, overview, grep, glob.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from openviking.exceptions import NotFoundError, NotInitializedError
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class FSService:
+ """File system operations service."""
+
+ def __init__(self, viking_fs: Optional[VikingFS] = None):
+ self._viking_fs = viking_fs
+
+ def set_viking_fs(self, viking_fs: VikingFS) -> None:
+ """Set VikingFS instance (for deferred initialization)."""
+ self._viking_fs = viking_fs
+
+ def _ensure_initialized(self) -> VikingFS:
+ """Ensure VikingFS is initialized."""
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+ return self._viking_fs
+
+ async def ls(self, uri: str, recursive: bool = False, simple: bool = False) -> List[Any]:
+ """List directory contents.
+
+ Args:
+ uri: Viking URI
+ recursive: List all subdirectories recursively
+ simple: Return only relative path list
+ """
+ viking_fs = self._ensure_initialized()
+
+ if recursive:
+ entries = await viking_fs.tree(uri)
+ else:
+ entries = await viking_fs.ls(uri)
+
+ if simple:
+ return [e.get("rel_path", e.get("name", "")) for e in entries]
+ return entries
+
+ async def mkdir(self, uri: str) -> None:
+ """Create directory."""
+ viking_fs = self._ensure_initialized()
+ await viking_fs.mkdir(uri)
+
+ async def rm(self, uri: str, recursive: bool = False) -> None:
+ """Remove resource."""
+ viking_fs = self._ensure_initialized()
+ await viking_fs.rm(uri, recursive=recursive)
+
+ async def mv(self, from_uri: str, to_uri: str) -> None:
+ """Move resource."""
+ viking_fs = self._ensure_initialized()
+ await viking_fs.mv(from_uri, to_uri)
+
+ async def tree(self, uri: str) -> List[Dict[str, Any]]:
+ """Get directory tree."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.tree(uri)
+
+ async def stat(self, uri: str) -> Dict[str, Any]:
+ """Get resource status."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.stat(uri)
+
+ async def read(self, uri: str) -> str:
+ """Read file content."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.read_file(uri)
+
+ async def abstract(self, uri: str) -> str:
+ """Read L0 abstract (.abstract.md)."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.abstract(uri)
+
+ async def overview(self, uri: str) -> str:
+ """Read L1 overview (.overview.md)."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.overview(uri)
+
+ async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
+ """Content search."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.grep(uri, pattern, case_insensitive=case_insensitive)
+
+ async def glob(self, pattern: str, uri: str = "viking://") -> Dict:
+ """File pattern matching."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.glob(pattern, uri=uri)
diff --git a/openviking/service/pack_service.py b/openviking/service/pack_service.py
new file mode 100644
index 000000000..54095145f
--- /dev/null
+++ b/openviking/service/pack_service.py
@@ -0,0 +1,64 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Pack Service for OpenViking.
+
+Provides ovpack export/import operations.
+"""
+
+from typing import Optional
+
+from openviking.exceptions import NotInitializedError
+from openviking.storage.local_fs import export_ovpack as local_export_ovpack
+from openviking.storage.local_fs import import_ovpack as local_import_ovpack
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class PackService:
+ """OVPack export/import service."""
+
+ def __init__(self, viking_fs: Optional[VikingFS] = None):
+ self._viking_fs = viking_fs
+
+ def set_viking_fs(self, viking_fs: VikingFS) -> None:
+ """Set VikingFS instance (for deferred initialization)."""
+ self._viking_fs = viking_fs
+
+ def _ensure_initialized(self) -> VikingFS:
+ """Ensure VikingFS is initialized."""
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+ return self._viking_fs
+
+ async def export_ovpack(self, uri: str, to: str) -> str:
+ """Export specified context path as .ovpack file.
+
+ Args:
+ uri: Viking URI
+ to: Target file path
+
+ Returns:
+ Exported file path
+ """
+ viking_fs = self._ensure_initialized()
+ return await local_export_ovpack(viking_fs, uri, to)
+
+ async def import_ovpack(
+ self, file_path: str, parent: str, force: bool = False, vectorize: bool = True
+ ) -> str:
+ """Import local .ovpack file to specified parent path.
+
+ Args:
+ file_path: Local .ovpack file path
+ parent: Target parent URI (e.g., viking://user/alice/resources/references/)
+ force: Whether to force overwrite existing resources
+ vectorize: Whether to trigger vectorization
+
+ Returns:
+ Imported root resource URI
+ """
+ viking_fs = self._ensure_initialized()
+ return await local_import_ovpack(viking_fs, file_path, parent, force=force, vectorize=vectorize)
diff --git a/openviking/service/relation_service.py b/openviking/service/relation_service.py
new file mode 100644
index 000000000..6dd0fb5a4
--- /dev/null
+++ b/openviking/service/relation_service.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Relation Service for OpenViking.
+
+Provides relation management operations: relations, link, unlink.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from openviking.exceptions import NotInitializedError
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class RelationService:
+ """Relation management service."""
+
+ def __init__(self, viking_fs: Optional[VikingFS] = None):
+ self._viking_fs = viking_fs
+
+ def set_viking_fs(self, viking_fs: VikingFS) -> None:
+ """Set VikingFS instance (for deferred initialization)."""
+ self._viking_fs = viking_fs
+
+ def _ensure_initialized(self) -> VikingFS:
+ """Ensure VikingFS is initialized."""
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+ return self._viking_fs
+
+ async def relations(self, uri: str) -> List[Dict[str, Any]]:
+ """Get relations (returns [{"uri": "...", "reason": "..."}, ...])."""
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.relations(uri)
+
+ async def link(self, from_uri: str, uris: Union[str, List[str]], reason: str = "") -> None:
+ """Create link (single or multiple).
+
+ Args:
+ from_uri: Source URI
+ uris: Target URI or list of URIs
+ reason: Reason for linking
+ """
+ viking_fs = self._ensure_initialized()
+ await viking_fs.link(from_uri, uris, reason)
+
+ async def unlink(self, from_uri: str, uri: str) -> None:
+ """Remove link (remove specified URI from uris).
+
+ Args:
+ from_uri: Source URI
+ uri: Target URI to remove
+ """
+ viking_fs = self._ensure_initialized()
+ await viking_fs.unlink(from_uri, uri)
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
new file mode 100644
index 000000000..9a7b5b2a7
--- /dev/null
+++ b/openviking/service/resource_service.py
@@ -0,0 +1,174 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Resource Service for OpenViking.
+
+Provides resource management operations: add_resource, add_skill, wait_processed.
+"""
+
+from typing import Any, Dict, Optional
+
+from openviking.exceptions import InvalidArgumentError, NotInitializedError
+from openviking.storage import VikingDBManager
+from openviking.storage.queuefs import get_queue_manager
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+from openviking.utils.resource_processor import ResourceProcessor
+from openviking.utils.skill_processor import SkillProcessor
+from openviking.utils.uri import VikingURI
+
+logger = get_logger(__name__)
+
+
+class ResourceService:
+ """Resource management service."""
+
+ def __init__(
+ self,
+ vikingdb: Optional[VikingDBManager] = None,
+ viking_fs: Optional[VikingFS] = None,
+ resource_processor: Optional[ResourceProcessor] = None,
+ skill_processor: Optional[SkillProcessor] = None,
+ user: str = "default",
+ ):
+ self._vikingdb = vikingdb
+ self._viking_fs = viking_fs
+ self._resource_processor = resource_processor
+ self._skill_processor = skill_processor
+ self._user = user
+
+ def set_dependencies(
+ self,
+ vikingdb: VikingDBManager,
+ viking_fs: VikingFS,
+ resource_processor: ResourceProcessor,
+ skill_processor: SkillProcessor,
+ user: str,
+ ) -> None:
+ """Set dependencies (for deferred initialization)."""
+ self._vikingdb = vikingdb
+ self._viking_fs = viking_fs
+ self._resource_processor = resource_processor
+ self._skill_processor = skill_processor
+ self._user = user
+
+ def _ensure_initialized(self) -> None:
+ """Ensure all dependencies are initialized."""
+ if not self._resource_processor:
+ raise NotInitializedError("ResourceProcessor")
+ if not self._skill_processor:
+ raise NotInitializedError("SkillProcessor")
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+
+ async 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 (only supports resources scope).
+
+ Args:
+ path: Resource path (local file or URL)
+ target: Target URI
+ reason: Reason for adding
+ instruction: Processing instruction
+ wait: Whether to wait for semantic extraction and vectorization to complete
+ timeout: Wait timeout in seconds
+
+ Returns:
+ Processing result
+ """
+ self._ensure_initialized()
+
+ # add_resource only supports resources scope
+ if target and target.startswith("viking://"):
+ parsed = VikingURI(target)
+ if parsed.scope != "resources":
+ raise InvalidArgumentError(
+ f"add_resource only supports resources scope, use dedicated interface to add {parsed.scope} content"
+ )
+
+ result = await self._resource_processor.process_resource(
+ path=path,
+ reason=reason,
+ instruction=instruction,
+ scope="resources",
+ target=target,
+ )
+
+ if wait:
+ qm = get_queue_manager()
+ status = await qm.wait_complete(timeout=timeout)
+ result["queue_status"] = {
+ name: {
+ "processed": s.processed,
+ "error_count": s.error_count,
+ "errors": [{"message": e.message} for e in s.errors],
+ }
+ for name, s in status.items()
+ }
+
+ return result
+
+ async def add_skill(
+ self,
+ data: Any,
+ wait: bool = False,
+ timeout: Optional[float] = None,
+ ) -> Dict[str, Any]:
+ """Add skill to OpenViking.
+
+ Args:
+ data: Skill data (directory path, file path, string, or dict)
+ wait: Whether to wait for vectorization to complete
+ timeout: Wait timeout in seconds
+
+ Returns:
+ Processing result
+ """
+ self._ensure_initialized()
+
+ result = await self._skill_processor.process_skill(
+ data=data,
+ viking_fs=self._viking_fs,
+ user=self._user,
+ )
+
+ if wait:
+ qm = get_queue_manager()
+ status = await qm.wait_complete(timeout=timeout)
+ result["queue_status"] = {
+ name: {
+ "processed": s.processed,
+ "error_count": s.error_count,
+ "errors": [{"message": e.message} for e in s.errors],
+ }
+ for name, s in status.items()
+ }
+
+ return result
+
+ async def wait_processed(self, timeout: Optional[float] = None) -> Dict[str, Any]:
+ """Wait for all queued processing to complete.
+
+ Args:
+ timeout: Wait timeout in seconds
+
+ Returns:
+ Queue status
+ """
+ qm = get_queue_manager()
+ status = await qm.wait_complete(timeout=timeout)
+ return {
+ name: {
+ "processed": s.processed,
+ "error_count": s.error_count,
+ "errors": [{"message": e.message} for e in s.errors],
+ }
+ for name, s in status.items()
+ }
diff --git a/openviking/service/search_service.py b/openviking/service/search_service.py
new file mode 100644
index 000000000..6f88204d9
--- /dev/null
+++ b/openviking/service/search_service.py
@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Search Service for OpenViking.
+
+Provides semantic search operations: search, find.
+"""
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from openviking.exceptions import NotInitializedError
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+
+if TYPE_CHECKING:
+ from openviking.session import Session
+
+logger = get_logger(__name__)
+
+
+class SearchService:
+ """Semantic search service."""
+
+ def __init__(self, viking_fs: Optional[VikingFS] = None):
+ self._viking_fs = viking_fs
+
+ def set_viking_fs(self, viking_fs: VikingFS) -> None:
+ """Set VikingFS instance (for deferred initialization)."""
+ self._viking_fs = viking_fs
+
+ def _ensure_initialized(self) -> VikingFS:
+ """Ensure VikingFS is initialized."""
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+ return self._viking_fs
+
+ async def search(
+ self,
+ query: str,
+ target_uri: str = "",
+ session: Optional["Session"] = None,
+ limit: int = 10,
+ score_threshold: Optional[float] = None,
+ filter: Optional[Dict] = None,
+ ) -> Any:
+ """Complex search with session context.
+
+ Args:
+ query: Query string
+ target_uri: Target directory URI
+ session: Session object for context
+ limit: Max results
+ score_threshold: Score threshold
+ filter: Metadata filters
+
+ Returns:
+ FindResult
+ """
+ viking_fs = self._ensure_initialized()
+
+ session_info = None
+ if session:
+ session_info = session.get_context_for_search(query)
+
+ return await viking_fs.search(
+ query=query,
+ target_uri=target_uri,
+ session_info=session_info,
+ limit=limit,
+ score_threshold=score_threshold,
+ filter=filter,
+ )
+
+ async def find(
+ self,
+ query: str,
+ target_uri: str = "",
+ limit: int = 10,
+ score_threshold: Optional[float] = None,
+ filter: Optional[Dict] = None,
+ ) -> Any:
+ """Semantic search without session context.
+
+ Args:
+ query: Query string
+ target_uri: Target directory URI
+ limit: Max results
+ score_threshold: Score threshold
+ filter: Metadata filters
+
+ Returns:
+ FindResult
+ """
+ viking_fs = self._ensure_initialized()
+ return await viking_fs.find(
+ query=query,
+ target_uri=target_uri,
+ limit=limit,
+ score_threshold=score_threshold,
+ filter=filter,
+ )
diff --git a/openviking/service/session_service.py b/openviking/service/session_service.py
new file mode 100644
index 000000000..f3738ff6d
--- /dev/null
+++ b/openviking/service/session_service.py
@@ -0,0 +1,152 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Session Service for OpenViking.
+
+Provides session management operations: session, sessions, add_message, compress, extract, delete.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from openviking.exceptions import NotFoundError, NotInitializedError
+from openviking.message import Part
+from openviking.session import Session
+from openviking.session.compressor import SessionCompressor
+from openviking.storage import VikingDBManager
+from openviking.storage.viking_fs import VikingFS
+from openviking.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class SessionService:
+ """Session management service."""
+
+ def __init__(
+ self,
+ vikingdb: Optional[VikingDBManager] = None,
+ viking_fs: Optional[VikingFS] = None,
+ session_compressor: Optional[SessionCompressor] = None,
+ user: str = "default",
+ ):
+ self._vikingdb = vikingdb
+ self._viking_fs = viking_fs
+ self._session_compressor = session_compressor
+ self._user = user
+
+ def set_dependencies(
+ self,
+ vikingdb: VikingDBManager,
+ viking_fs: VikingFS,
+ session_compressor: SessionCompressor,
+ user: str,
+ ) -> None:
+ """Set dependencies (for deferred initialization)."""
+ self._vikingdb = vikingdb
+ self._viking_fs = viking_fs
+ self._session_compressor = session_compressor
+ self._user = user
+
+ def _ensure_initialized(self) -> None:
+ """Ensure all dependencies are initialized."""
+ if not self._viking_fs:
+ raise NotInitializedError("VikingFS")
+
+ def session(self, session_id: Optional[str] = None) -> Session:
+ """Create a new session or load an existing one.
+
+ Args:
+ session_id: Session ID, creates a new session (auto-generated ID) if None
+
+ Returns:
+ Session instance
+ """
+ self._ensure_initialized()
+ return Session(
+ viking_fs=self._viking_fs,
+ vikingdb_manager=self._vikingdb,
+ session_compressor=self._session_compressor,
+ user=self._user,
+ session_id=session_id,
+ )
+
+ async def sessions(self) -> List[Dict[str, Any]]:
+ """Get all sessions for the current user.
+
+ Returns:
+ List of session info dicts
+ """
+ self._ensure_initialized()
+ session_base_uri = "viking://session"
+
+ try:
+ entries = await self._viking_fs.ls(session_base_uri)
+ sessions = []
+ for entry in entries:
+ name = entry.get("name", "")
+ if name in [".", ".."]:
+ continue
+ sessions.append({
+ "session_id": name,
+ "uri": f"{session_base_uri}/{name}",
+ "is_dir": entry.get("isDir", False),
+ })
+ return sessions
+ except Exception:
+ return []
+
+ async def delete(self, session_id: str) -> bool:
+ """Delete a session.
+
+ Args:
+ session_id: Session ID to delete
+
+ Returns:
+ True if deleted successfully
+ """
+ self._ensure_initialized()
+ session_uri = f"viking://session/{session_id}"
+
+ try:
+ await self._viking_fs.rm(session_uri, recursive=True)
+ logger.info(f"Deleted session: {session_id}")
+ return True
+ except Exception as e:
+ logger.error(f"Failed to delete session {session_id}: {e}")
+ raise NotFoundError(session_id, "session")
+
+ async def compress(self, session_id: str) -> Dict[str, Any]:
+ """Compress a session (commit and archive).
+
+ Args:
+ session_id: Session ID to compress
+
+ Returns:
+ Compression result
+ """
+ self._ensure_initialized()
+ session = self.session(session_id)
+ session.load()
+ return session.commit()
+
+ async def extract(self, session_id: str) -> List[Any]:
+ """Extract memories from a session.
+
+ Args:
+ session_id: Session ID to extract from
+
+ Returns:
+ List of extracted memories
+ """
+ self._ensure_initialized()
+ if not self._session_compressor:
+ raise NotInitializedError("SessionCompressor")
+
+ session = self.session(session_id)
+ session.load()
+
+ return await self._session_compressor.extract_long_term_memories(
+ messages=session.messages,
+ user=self._user,
+ session_id=session_id,
+ )
diff --git a/openviking/session/session.py b/openviking/session/session.py
index 764e40c42..225b07e45 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -18,7 +18,9 @@ from openviking.utils import get_logger
from openviking.utils.config import get_openviking_config
if TYPE_CHECKING:
- from openviking.sync_client import OpenViking
+ from openviking.session.compressor import SessionCompressor
+ from openviking.storage import VikingDBManager
+ from openviking.storage.viking_fs import VikingFS
logger = get_logger(__name__)
@@ -77,12 +79,16 @@ class Session:
def __init__(
self,
- client: "OpenViking",
- user: str,
+ viking_fs: "VikingFS",
+ vikingdb_manager: Optional["VikingDBManager"] = None,
+ session_compressor: Optional["SessionCompressor"] = None,
+ user: str = "default",
session_id: Optional[str] = None,
auto_commit_threshold: int = 8000,
):
- self.client = client
+ self._viking_fs = viking_fs
+ self._vikingdb_manager = vikingdb_manager
+ self._session_compressor = session_compressor
self.user = user or "default"
self.session_id = session_id or str(uuid4())
self.created_at = datetime.now()
@@ -104,7 +110,7 @@ class Session:
try:
content = _run_async(
- self.client.viking_fs.read_file(f"{self._session_uri}/messages.jsonl")
+ self._viking_fs.read_file(f"{self._session_uri}/messages.jsonl")
)
self._messages = [
Message.from_dict(json.loads(line))
@@ -117,7 +123,7 @@ class Session:
# Restore compression_index (scan history directory)
try:
- history_items = _run_async(self.client.viking_fs.ls(f"{self._session_uri}/history"))
+ history_items = _run_async(self._viking_fs.ls(f"{self._session_uri}/history"))
archives = [
item["name"] for item in history_items if item["name"].startswith("archive_")
]
@@ -244,12 +250,12 @@ class Session:
)
# 2. Extract long-term memories
- if self.client and self.client._session_compressor:
+ if self._session_compressor:
logger.info(
f"Starting memory extraction from {len(messages_to_archive)} archived messages"
)
memories = _run_async(
- self.client._session_compressor.extract_long_term_memories(
+ self._session_compressor.extract_long_term_memories(
messages=messages_to_archive,
user=self.user,
session_id=self.session_id,
@@ -284,11 +290,11 @@ class Session:
def _update_active_counts(self) -> int:
"""Update active_count for used contexts/skills."""
- if not self.client or not self.client._vikingdb_manager:
+ if not self._vikingdb_manager:
return 0
updated = 0
- storage = self.client._vikingdb_manager
+ storage = self._vikingdb_manager
for usage in self._usage_records:
try:
@@ -328,7 +334,7 @@ class Session:
summaries = []
if self.compression.compression_index > 0:
try:
- history_items = _run_async(self.client.viking_fs.ls(f"{self._session_uri}/history"))
+ history_items = _run_async(self._viking_fs.ls(f"{self._session_uri}/history"))
query_lower = query.lower()
# Collect all archives with relevance scores
@@ -338,7 +344,7 @@ class Session:
if name and name.startswith("archive_"):
overview_uri = f"{self._session_uri}/history/{name}/.overview.md"
try:
- overview = _run_async(self.client.viking_fs.read_file(overview_uri))
+ overview = _run_async(self._viking_fs.read_file(overview_uri))
# Calculate relevance by keyword matching
score = 0
if query_lower in overview.lower():
@@ -406,10 +412,10 @@ class Session:
overview: str,
) -> None:
"""Write archive to history/archive_N/."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
- viking_fs = self.client.viking_fs
+ viking_fs = self._viking_fs
archive_uri = f"{self._session_uri}/history/archive_{index:03d}"
# Write messages.jsonl
@@ -428,10 +434,10 @@ class Session:
def _write_to_agfs(self, messages: List[Message]) -> None:
"""Write messages.jsonl to AGFS."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
- viking_fs = self.client.viking_fs
+ viking_fs = self._viking_fs
turn_count = len([m for m in messages if m.role == "user"])
abstract = self._generate_abstract()
@@ -463,10 +469,10 @@ class Session:
def _append_to_jsonl(self, msg: Message) -> None:
"""Append to messages.jsonl."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
_run_async(
- self.client.viking_fs.append_file(
+ self._viking_fs.append_file(
f"{self._session_uri}/messages.jsonl",
msg.to_jsonl() + "\n",
)
@@ -474,13 +480,13 @@ class Session:
def _update_message_in_jsonl(self) -> None:
"""Update message in messages.jsonl."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
lines = [m.to_jsonl() for m in self._messages]
content = "\n".join(lines) + "\n"
_run_async(
- self.client.viking_fs.write_file(
+ self._viking_fs.write_file(
f"{self._session_uri}/messages.jsonl",
content,
)
@@ -494,7 +500,7 @@ class Session:
status: str,
) -> None:
"""Save tool result to tools/{tool_id}/tool.json."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
tool_part = msg.find_tool_part(tool_id)
@@ -511,7 +517,7 @@ class Session:
"time": {"created": datetime.now().isoformat()},
}
_run_async(
- self.client.viking_fs.write_file(
+ self._viking_fs.write_file(
f"{self._session_uri}/tools/{tool_id}/tool.json",
json.dumps(tool_data, ensure_ascii=False),
)
@@ -551,10 +557,10 @@ class Session:
def _write_relations(self) -> None:
"""Create relations to used contexts/tools."""
- if not self.client or not self.client.viking_fs:
+ if not self._viking_fs:
return
- viking_fs = self.client.viking_fs
+ viking_fs = self._viking_fs
for usage in self._usage_records:
try:
_run_async(viking_fs.link(self._session_uri, usage.uri))
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index fbe61b70f..64ebdf602 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -160,9 +160,21 @@ class SyncOpenViking:
"""Create directory"""
return asyncio.run(self._async_client.mkdir(uri))
- @property
- def observers(self):
- return self._async_client.observers
+ def get_status(self):
+ """Get system status.
+
+ Returns:
+ SystemStatus containing health status of all components.
+ """
+ return self._async_client.get_status()
+
+ def is_healthy(self) -> bool:
+ """Quick health check.
+
+ Returns:
+ True if all components are healthy, False otherwise.
+ """
+ return self._async_client.is_healthy()
@property
def viking_fs(self):
diff --git a/pyproject.toml b/pyproject.toml
index 5e7c4dd3f..fbfa95725 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,6 +47,7 @@ dependencies = [
"uvicorn>=0.39.0",
"xxhash>=3.0.0",
"jinja2>=3.1.6",
+ "nest-asyncio>=1.5.0",
]
[project.optional-dependencies]
@@ -73,6 +74,7 @@ Issues = "https://github.com/volcengine/openviking/issues"
[project.scripts]
openviking-viewer = "openviking.tools.viewer:main"
+openviking-server = "openviking.server.bootstrap:main"
[tool.setuptools.packages.find]
where = ["."]
diff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.py
index 3e2c1107d..5c3816f90 100644
--- a/tests/integration/test_full_workflow.py
+++ b/tests/integration/test_full_workflow.py
@@ -163,7 +163,7 @@ class TestImportExportWorkflow:
assert export_path.exists()
# 4. Delete original resource
- await client.rm(original_uri)
+ await client.rm(original_uri, recursive=True)
# 5. Import
import_uri = await client.import_ovpack(
diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.py
new file mode 100644
index 000000000..679f52d60
--- /dev/null
+++ b/tests/misc/test_debug_service.py
@@ -0,0 +1,222 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for DebugService.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openviking.service.debug_service import (
+ ComponentStatus,
+ DebugService,
+ SystemStatus,
+)
+
+
+class TestComponentStatus:
+ """Tests for ComponentStatus dataclass."""
+
+ def test_component_status_creation(self):
+ """Test ComponentStatus can be created with all fields."""
+ status = ComponentStatus(
+ name="test_component",
+ is_healthy=True,
+ has_errors=False,
+ details={"key": "value"},
+ )
+ assert status.name == "test_component"
+ assert status.is_healthy is True
+ assert status.has_errors is False
+ assert status.details == {"key": "value"}
+
+ def test_component_status_unhealthy(self):
+ """Test ComponentStatus with unhealthy state."""
+ status = ComponentStatus(
+ name="unhealthy_component",
+ is_healthy=False,
+ has_errors=True,
+ details={"error": "connection failed"},
+ )
+ assert status.is_healthy is False
+ assert status.has_errors is True
+
+
+class TestSystemStatus:
+ """Tests for SystemStatus dataclass."""
+
+ def test_system_status_healthy(self):
+ """Test SystemStatus with all healthy components."""
+ components = {
+ "queue": ComponentStatus("queue", True, False, {}),
+ "vikingdb": ComponentStatus("vikingdb", True, False, {}),
+ }
+ status = SystemStatus(is_healthy=True, components=components, errors=[])
+ assert status.is_healthy is True
+ assert len(status.components) == 2
+ assert status.errors == []
+
+ def test_system_status_with_errors(self):
+ """Test SystemStatus with errors."""
+ components = {
+ "queue": ComponentStatus("queue", False, True, {}),
+ "vikingdb": ComponentStatus("vikingdb", True, False, {}),
+ }
+ status = SystemStatus(
+ is_healthy=False,
+ components=components,
+ errors=["queue has errors"],
+ )
+ assert status.is_healthy is False
+ assert len(status.errors) == 1
+
+
+class TestDebugService:
+ """Tests for DebugService class."""
+
+ def test_init_without_dependencies(self):
+ """Test DebugService can be created without dependencies."""
+ service = DebugService()
+ assert service._vikingdb is None
+ assert service._config is None
+
+ def test_init_with_dependencies(self):
+ """Test DebugService can be created with dependencies."""
+ mock_vikingdb = MagicMock()
+ mock_config = MagicMock()
+ service = DebugService(vikingdb=mock_vikingdb, config=mock_config)
+ assert service._vikingdb is mock_vikingdb
+ assert service._config is mock_config
+
+ def test_set_dependencies(self):
+ """Test set_dependencies method."""
+ service = DebugService()
+ mock_vikingdb = MagicMock()
+ mock_config = MagicMock()
+ service.set_dependencies(vikingdb=mock_vikingdb, config=mock_config)
+ assert service._vikingdb is mock_vikingdb
+ assert service._config is mock_config
+
+ @patch("openviking.service.debug_service.get_queue_manager")
+ @patch("openviking.service.debug_service.QueueObserver")
+ def test_get_queue_status(self, mock_observer_cls, mock_get_queue_manager):
+ """Test get_queue_status returns ComponentStatus."""
+ mock_queue_manager = MagicMock()
+ mock_get_queue_manager.return_value = mock_queue_manager
+
+ mock_observer = MagicMock()
+ mock_observer.is_healthy.return_value = True
+ mock_observer.has_errors.return_value = False
+ mock_observer.get_status_table.return_value = "Queue Status Table"
+ mock_observer_cls.return_value = mock_observer
+
+ service = DebugService()
+ status = service.get_queue_status()
+
+ assert isinstance(status, ComponentStatus)
+ assert status.name == "queue"
+ assert status.is_healthy is True
+ assert status.has_errors is False
+ assert status.details["status_table"] == "Queue Status Table"
+ mock_observer_cls.assert_called_once_with(mock_queue_manager)
+
+ @patch("openviking.service.debug_service.VikingDBObserver")
+ def test_get_vikingdb_status(self, mock_observer_cls):
+ """Test get_vikingdb_status returns ComponentStatus."""
+ mock_vikingdb = MagicMock()
+ mock_observer = MagicMock()
+ mock_observer.is_healthy.return_value = True
+ mock_observer.has_errors.return_value = False
+ mock_observer.get_status_table.return_value = "VikingDB Status Table"
+ mock_observer_cls.return_value = mock_observer
+
+ service = DebugService(vikingdb=mock_vikingdb)
+ status = service.get_vikingdb_status()
+
+ assert isinstance(status, ComponentStatus)
+ assert status.name == "vikingdb"
+ assert status.is_healthy is True
+ assert status.has_errors is False
+ assert status.details["status_table"] == "VikingDB Status Table"
+ mock_observer_cls.assert_called_once_with(mock_vikingdb)
+
+ @patch("openviking.service.debug_service.VLMObserver")
+ def test_get_vlm_status(self, mock_observer_cls):
+ """Test get_vlm_status returns ComponentStatus."""
+ mock_config = MagicMock()
+ mock_vlm_instance = MagicMock()
+ mock_config.vlm.get_vlm_instance.return_value = mock_vlm_instance
+
+ mock_observer = MagicMock()
+ mock_observer.is_healthy.return_value = True
+ mock_observer.has_errors.return_value = False
+ mock_observer.get_status_table.return_value = "VLM Status Table"
+ mock_observer_cls.return_value = mock_observer
+
+ service = DebugService(config=mock_config)
+ status = service.get_vlm_status()
+
+ assert isinstance(status, ComponentStatus)
+ assert status.name == "vlm"
+ assert status.is_healthy is True
+ assert status.has_errors is False
+ assert status.details["status_table"] == "VLM Status Table"
+ mock_observer_cls.assert_called_once_with(mock_vlm_instance)
+
+ @patch.object(DebugService, "get_queue_status")
+ @patch.object(DebugService, "get_vikingdb_status")
+ @patch.object(DebugService, "get_vlm_status")
+ def test_get_system_status_all_healthy(
+ self, mock_vlm, mock_vikingdb, mock_queue
+ ):
+ """Test get_system_status when all components are healthy."""
+ mock_queue.return_value = ComponentStatus("queue", True, False, {})
+ mock_vikingdb.return_value = ComponentStatus("vikingdb", True, False, {})
+ mock_vlm.return_value = ComponentStatus("vlm", True, False, {})
+
+ service = DebugService()
+ status = service.get_system_status()
+
+ assert isinstance(status, SystemStatus)
+ assert status.is_healthy is True
+ assert len(status.components) == 3
+ assert status.errors == []
+
+ @patch.object(DebugService, "get_queue_status")
+ @patch.object(DebugService, "get_vikingdb_status")
+ @patch.object(DebugService, "get_vlm_status")
+ def test_get_system_status_with_errors(
+ self, mock_vlm, mock_vikingdb, mock_queue
+ ):
+ """Test get_system_status when some components have errors."""
+ mock_queue.return_value = ComponentStatus("queue", False, True, {})
+ mock_vikingdb.return_value = ComponentStatus("vikingdb", True, False, {})
+ mock_vlm.return_value = ComponentStatus("vlm", False, True, {})
+
+ service = DebugService()
+ status = service.get_system_status()
+
+ assert isinstance(status, SystemStatus)
+ assert status.is_healthy is False
+ assert len(status.errors) == 2
+ assert "queue has errors" in status.errors
+ assert "vlm has errors" in status.errors
+
+ @patch.object(DebugService, "get_system_status")
+ def test_is_healthy_returns_true(self, mock_get_system_status):
+ """Test is_healthy returns True when system is healthy."""
+ mock_get_system_status.return_value = SystemStatus(
+ is_healthy=True, components={}, errors=[]
+ )
+ service = DebugService()
+ assert service.is_healthy() is True
+
+ @patch.object(DebugService, "get_system_status")
+ def test_is_healthy_returns_false(self, mock_get_system_status):
+ """Test is_healthy returns False when system is unhealthy."""
+ mock_get_system_status.return_value = SystemStatus(
+ is_healthy=False, components={}, errors=["error"]
+ )
+ service = DebugService()
+ assert service.is_healthy() is False
diff --git a/uv.lock b/uv.lock
index 0a5490419..296c48a16 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1476,6 +1476,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/5f/df/76d0321c3797b54b60fef9ec3bd6f4cfd124b9e422182156a1dd418722cf/myst_parser-4.0.1-py3-none-any.whl", hash = "sha256:9134e88959ec3b5780aedf8a99680ea242869d012e8821db3126d427edc9c95d", size = 84579, upload-time = "2025-02-12T10:53:02.078Z" },
]
+[[package]]
+name = "nest-asyncio"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/83/f8/51569ac65d696c8ecbee95938f89d4abf00f47d58d48f6fbabfe8f0baefe/nest_asyncio-1.6.0.tar.gz", hash = "sha256:6f172d5449aca15afd6c646851f4e31e02c598d553a667e38cafa997cfec55fe", size = 7418, upload-time = "2024-01-21T14:25:19.227Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a0/c4/c2971a3ba4c6103a3d10c4b0f24f461ddc027f0f09763220cf35ca1401b3/nest_asyncio-1.6.0-py3-none-any.whl", hash = "sha256:87af6efd6b5e897c81050477ef65c62e2b2f35d51703cae01aff2905b1852e1c", size = 5195, upload-time = "2024-01-21T14:25:17.223Z" },
+]
+
[[package]]
name = "openai"
version = "2.14.0"
@@ -1507,6 +1516,7 @@ dependencies = [
{ name = "json-repair", version = "0.44.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
{ name = "json-repair", version = "0.55.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
{ name = "markdownify" },
+ { name = "nest-asyncio" },
{ name = "openai" },
{ name = "pdfplumber" },
{ name = "pyagfs" },
@@ -1553,6 +1563,7 @@ requires-dist = [
{ name = "markdownify", specifier = ">=0.11.0" },
{ name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
{ name = "myst-parser", marker = "extra == 'doc'", specifier = ">=2.0.0" },
+ { name = "nest-asyncio", specifier = ">=1.5.0" },
{ name = "openai", specifier = ">=1.0.0" },
{ name = "pdfplumber", specifier = ">=0.10.0" },
{ name = "pyagfs", specifier = ">=1.4.0" },