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: extract Service layer from async_client (#50)
qin-ctxef23bdc44449
diff --git a/docs/design/server_client/prompt.md b/docs/design/server_client/prompt.mdindex 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_ovpack3. **创建 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/health5. **实现服务启动器** (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):- 直接调用 OpenVikingServicediff --git a/docs/design/server_client/server-cli-design.md b/docs/design/server_client/server-cli-design.mdindex 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 showopenviking 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_processedBody: {"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.pyfrom fastapi import FastAPI, Dependsfrom 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, debugapp = FastAPI(title="OpenViking API",@@ -1202,6 +1242,7 @@ app.include_router(filesystem.router, prefix="/api/v1/fs", dependencies=[Dependsapp.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.mdindex 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.mdindex 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 StorageOpenViking 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.mdindex 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.mdindex 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.pyindex 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 importsimport threadingfrom 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 SystemStatusfrom 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_fsfrom 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 OpenVikingConfiglogger = 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 = Falseself._singleton_initialized = False@@ -197,53 +176,7 @@ class AsyncOpenViking:cls._instance._singleton_initialized = Falsecls._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 URIsession: Session object for contextlimit: Max results- grep: Keyword filtersfilter: Metadata filtersReturns: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.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_healthydiff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 764e40c42..225b07e45 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -18,7 +18,9 @@ from openviking.utils import get_loggerfrom openviking.utils.config import get_openviking_configif 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 VikingFSlogger = 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_compressorself.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 0updated = 0- storage = self.client._vikingdb_manager+ storage = self._vikingdb_managerfor 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 matchingscore = 0if 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_fsarchive_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_fsturn_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:returnlines = [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:returntool_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_fsfor 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.pyindex 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()@propertydef viking_fs(self):diff --git a/pyproject.toml b/pyproject.tomlindex 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.pyindex 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. Importimport_uri = await client.import_ovpack(diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.pynew file mode 100644index 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 Falsediff --git a/uv.lock b/uv.lockindex 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" },