Skip to content

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

refactor: unify async execution utilities into run_async (#75)

qin-ctxb03d10a8c553
diff --git a/openviking/session/session.py b/openviking/session/session.py
index 225b07e45..689dbe474 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -5,7 +5,6 @@
Session as Context: Sessions integrated into L0/L1/L2 system.
"""
-import asyncio
import json
import re
from dataclasses import dataclass, field
@@ -14,7 +13,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional
from uuid import uuid4
from openviking.message import Message, Part
-from openviking.utils import get_logger
+from openviking.utils import get_logger, run_async
from openviking.utils.config import get_openviking_config
if TYPE_CHECKING:
@@ -25,20 +24,6 @@ if TYPE_CHECKING:
logger = get_logger(__name__)
-def _run_async(coro):
- """Run async coroutine."""
- try:
- loop = asyncio.get_running_loop()
- # If already in event loop, use nest_asyncio or return directly
- import nest_asyncio
-
- nest_asyncio.apply()
- return loop.run_until_complete(coro)
- except RuntimeError:
- # No running event loop, use asyncio.run()
- return asyncio.run(coro)
-
-
@dataclass
class SessionCompression:
"""Session compression information."""
@@ -109,7 +94,7 @@ class Session:
return
try:
- content = _run_async(
+ content = run_async(
self._viking_fs.read_file(f"{self._session_uri}/messages.jsonl")
)
self._messages = [
@@ -123,7 +108,7 @@ class Session:
# Restore compression_index (scan history directory)
try:
- history_items = _run_async(self._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_")
]
@@ -254,7 +239,7 @@ class Session:
logger.info(
f"Starting memory extraction from {len(messages_to_archive)} archived messages"
)
- memories = _run_async(
+ memories = run_async(
self._session_compressor.extract_long_term_memories(
messages=messages_to_archive,
user=self.user,
@@ -298,7 +283,7 @@ class Session:
for usage in self._usage_records:
try:
- _run_async(
+ run_async(
storage.update(
collection="context",
filter={"uri": usage.uri},
@@ -334,7 +319,7 @@ class Session:
summaries = []
if self.compression.compression_index > 0:
try:
- history_items = _run_async(self._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
@@ -344,7 +329,7 @@ class Session:
if name and name.startswith("archive_"):
overview_uri = f"{self._session_uri}/history/{name}/.overview.md"
try:
- overview = _run_async(self._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():
@@ -397,7 +382,7 @@ class Session:
"compression.structured_summary",
{"messages": formatted},
)
- return _run_async(vlm.get_completion_async(prompt))
+ return run_async(vlm.get_completion_async(prompt))
except Exception as e:
logger.warning(f"LLM summary failed: {e}")
@@ -420,15 +405,15 @@ class Session:
# Write messages.jsonl
lines = [m.to_jsonl() for m in messages]
- _run_async(
+ run_async(
viking_fs.write_file(
uri=f"{archive_uri}/messages.jsonl",
content="\n".join(lines) + "\n",
)
)
- _run_async(viking_fs.write_file(uri=f"{archive_uri}/.abstract.md", content=abstract))
- _run_async(viking_fs.write_file(uri=f"{archive_uri}/.overview.md", content=overview))
+ run_async(viking_fs.write_file(uri=f"{archive_uri}/.abstract.md", content=abstract))
+ run_async(viking_fs.write_file(uri=f"{archive_uri}/.overview.md", content=overview))
logger.debug(f"Written archive: {archive_uri}")
@@ -446,7 +431,7 @@ class Session:
lines = [m.to_jsonl() for m in messages]
content = "\n".join(lines) + "\n" if lines else ""
- _run_async(
+ run_async(
viking_fs.write_file(
uri=f"{self._session_uri}/messages.jsonl",
content=content,
@@ -454,13 +439,13 @@ class Session:
)
# Update L0/L1
- _run_async(
+ run_async(
viking_fs.write_file(
uri=f"{self._session_uri}/.abstract.md",
content=abstract,
)
)
- _run_async(
+ run_async(
viking_fs.write_file(
uri=f"{self._session_uri}/.overview.md",
content=overview,
@@ -471,7 +456,7 @@ class Session:
"""Append to messages.jsonl."""
if not self._viking_fs:
return
- _run_async(
+ run_async(
self._viking_fs.append_file(
f"{self._session_uri}/messages.jsonl",
msg.to_jsonl() + "\n",
@@ -485,7 +470,7 @@ class Session:
lines = [m.to_jsonl() for m in self._messages]
content = "\n".join(lines) + "\n"
- _run_async(
+ run_async(
self._viking_fs.write_file(
f"{self._session_uri}/messages.jsonl",
content,
@@ -516,7 +501,7 @@ class Session:
"status": status,
"time": {"created": datetime.now().isoformat()},
}
- _run_async(
+ run_async(
self._viking_fs.write_file(
f"{self._session_uri}/tools/{tool_id}/tool.json",
json.dumps(tool_data, ensure_ascii=False),
@@ -563,7 +548,7 @@ class Session:
viking_fs = self._viking_fs
for usage in self._usage_records:
try:
- _run_async(viking_fs.link(self._session_uri, usage.uri))
+ run_async(viking_fs.link(self._session_uri, usage.uri))
logger.debug(f"Created relation: {self._session_uri} -> {usage.uri}")
except Exception as e:
logger.warning(f"Failed to create relation to {usage.uri}: {e}")
diff --git a/openviking/storage/observers/README.md b/openviking/storage/observers/README.md
index 43f7c2292..071bbacff 100644
--- a/openviking/storage/observers/README.md
+++ b/openviking/storage/observers/README.md
@@ -38,7 +38,7 @@ Monitors queue system status (Embedding, Semantic, and custom queues).
import openviking as ov
client = ov.OpenViking(path="./data")
-print(client.observers["queue"])
+print(client.observer.queue)
# Output:
# Queue Pending In Progress Processed Errors Total
# Embedding 5 2 100 0 107
@@ -58,7 +58,7 @@ Monitors VikingDB collection status (index count and vector count per collection
import openviking as ov
client = ov.OpenViking(path="./data")
-print(client.observers["vikingdb"])
+print(client.observer.vikingdb)
# Output:
# Collection Index Count Vector Count Status
# context 1 69 OK
diff --git a/openviking/storage/observers/async_utils.py b/openviking/storage/observers/async_utils.py
deleted file mode 100644
index 5b2e30cd7..000000000
--- a/openviking/storage/observers/async_utils.py
+++ /dev/null
@@ -1,40 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: Apache-2.0
-"""
-Async helper utilities for observers.
-"""
-
-import asyncio
-import threading
-from typing import Any, Awaitable, Callable
-
-
-def run_coroutine_sync(coro_factory: Callable[[], Awaitable[Any]]) -> Any:
- """
- Run a coroutine from sync code.
-
- If an event loop is already running in this thread, execute the coroutine
- in a dedicated thread with its own event loop.
- """
-
- try:
- asyncio.get_running_loop()
- except RuntimeError:
- return asyncio.run(coro_factory())
-
- result: dict = {}
-
- def runner() -> None:
- try:
- result["value"] = asyncio.run(coro_factory())
- except Exception as exc:
- result["error"] = exc
-
- thread = threading.Thread(target=runner, daemon=True)
- thread.start()
- thread.join()
-
- if "error" in result:
- raise result["error"]
-
- return result.get("value")
diff --git a/openviking/storage/observers/queue_observer.py b/openviking/storage/observers/queue_observer.py
index b7efa8b84..fec514d40 100644
--- a/openviking/storage/observers/queue_observer.py
+++ b/openviking/storage/observers/queue_observer.py
@@ -8,10 +8,10 @@ Provides methods to observe and report queue status in various formats.
from typing import Dict
-from openviking.storage.observers.async_utils import run_coroutine_sync
from openviking.storage.observers.base_observer import BaseObserver
from openviking.storage.queuefs.named_queue import QueueStatus
from openviking.storage.queuefs.queue_manager import QueueManager
+from openviking.utils import run_async
from openviking.utils.logger import get_logger
logger = get_logger(__name__)
@@ -32,7 +32,7 @@ class QueueObserver(BaseObserver):
return self._format_status_as_table(statuses)
def get_status_table(self) -> str:
- return run_coroutine_sync(self.get_status_table_async)
+ return run_async(self.get_status_table_async())
def __str__(self) -> str:
return self.get_status_table()
diff --git a/openviking/storage/observers/vikingdb_observer.py b/openviking/storage/observers/vikingdb_observer.py
index 5ede61ba8..91b7d38f8 100644
--- a/openviking/storage/observers/vikingdb_observer.py
+++ b/openviking/storage/observers/vikingdb_observer.py
@@ -8,9 +8,9 @@ Provides methods to observe and report VikingDB collection status.
from typing import Dict
-from openviking.storage.observers.async_utils import run_coroutine_sync
from openviking.storage.observers.base_observer import BaseObserver
from openviking.storage.vikingdb_manager import VikingDBManager
+from openviking.utils import run_async
from openviking.utils.logger import get_logger
logger = get_logger(__name__)
@@ -39,7 +39,7 @@ class VikingDBObserver(BaseObserver):
return self._format_status_as_table(statuses)
def get_status_table(self) -> str:
- return run_coroutine_sync(self.get_status_table_async)
+ return run_async(self.get_status_table_async())
def __str__(self) -> str:
return self.get_status_table()
@@ -156,7 +156,7 @@ class VikingDBObserver(BaseObserver):
try:
if not self._vikingdb_manager:
return True
- run_coroutine_sync(self._vikingdb_manager.health_check)
+ run_async(self._vikingdb_manager.health_check())
return False
except Exception as e:
logger.error(f"VikingDB health check failed: {e}")
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index 0709e5341..9a5da5357 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -4,13 +4,13 @@
Synchronous OpenViking client implementation.
"""
-import asyncio
from typing import TYPE_CHECKING, Any, Dict, List, Optional
if TYPE_CHECKING:
from openviking.session import Session
from openviking.async_client import AsyncOpenViking
+from openviking.utils import run_async
class SyncOpenViking:
@@ -25,7 +25,7 @@ class SyncOpenViking:
def initialize(self) -> None:
"""Initialize OpenViking storage and indexes."""
- asyncio.run(self._async_client.initialize())
+ run_async(self._async_client.initialize())
self._initialized = True
def session(self, session_id: Optional[str] = None) -> "Session":
@@ -42,7 +42,7 @@ class SyncOpenViking:
timeout: float = None,
) -> Dict[str, Any]:
"""Add resource to OpenViking (resources scope only)"""
- return asyncio.run(
+ return run_async(
self._async_client.add_resource(path, target, reason, instruction, wait, timeout)
)
@@ -53,7 +53,7 @@ class SyncOpenViking:
timeout: float = None,
) -> Dict[str, Any]:
"""Add skill to OpenViking."""
- return asyncio.run(self._async_client.add_skill(data, wait=wait, timeout=timeout))
+ return run_async(self._async_client.add_skill(data, wait=wait, timeout=timeout))
def search(
self,
@@ -65,7 +65,7 @@ class SyncOpenViking:
filter: Optional[Dict] = None,
):
"""Execute complex retrieval (intent analysis, hierarchical retrieval)."""
- return asyncio.run(
+ return run_async(
self._async_client.search(query, target_uri, session, limit, score_threshold, filter)
)
@@ -77,19 +77,19 @@ class SyncOpenViking:
score_threshold: Optional[float] = None,
):
"""Quick retrieval"""
- return asyncio.run(self._async_client.find(query, target_uri, limit, score_threshold))
+ return run_async(self._async_client.find(query, target_uri, limit, score_threshold))
def abstract(self, uri: str) -> str:
"""Read L0 abstract"""
- return asyncio.run(self._async_client.abstract(uri))
+ return run_async(self._async_client.abstract(uri))
def overview(self, uri: str) -> str:
"""Read L1 overview"""
- return asyncio.run(self._async_client.overview(uri))
+ return run_async(self._async_client.overview(uri))
def read(self, uri: str) -> str:
"""Read file"""
- return asyncio.run(self._async_client.read(uri))
+ return run_async(self._async_client.read(uri))
def ls(self, uri: str, **kwargs) -> List[Any]:
"""
@@ -100,65 +100,65 @@ class SyncOpenViking:
simple: Return only relative path list (bool, default: False)
recursive: List all subdirectories recursively (bool, default: False)
"""
- return asyncio.run(self._async_client.ls(uri, **kwargs))
+ return run_async(self._async_client.ls(uri, **kwargs))
def link(self, from_uri: str, uris: Any, reason: str = "") -> None:
"""Create relation"""
- return asyncio.run(self._async_client.link(from_uri, uris, reason))
+ return run_async(self._async_client.link(from_uri, uris, reason))
def unlink(self, from_uri: str, uri: str) -> None:
"""Delete relation"""
- return asyncio.run(self._async_client.unlink(from_uri, uri))
+ return run_async(self._async_client.unlink(from_uri, uri))
def export_ovpack(self, uri: str, to: str) -> str:
"""Export .ovpack file"""
- return asyncio.run(self._async_client.export_ovpack(uri, to))
+ return run_async(self._async_client.export_ovpack(uri, to))
def import_ovpack(
self, file_path: str, target: str, force: bool = False, vectorize: bool = True
) -> str:
"""Import .ovpack file (triggers vectorization by default)"""
- return asyncio.run(self._async_client.import_ovpack(file_path, target, force, vectorize))
+ return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))
def close(self) -> None:
"""Close OpenViking and release resources."""
- return asyncio.run(self._async_client.close())
+ return run_async(self._async_client.close())
def relations(self, uri: str) -> List[Dict[str, Any]]:
"""Get relations"""
- return asyncio.run(self._async_client.relations(uri))
+ return run_async(self._async_client.relations(uri))
def rm(self, uri: str, recursive: bool = False) -> None:
"""Delete resource"""
- return asyncio.run(self._async_client.rm(uri, recursive))
+ return run_async(self._async_client.rm(uri, recursive))
def wait_processed(self, timeout: float = None) -> None:
"""Wait for all async operations to complete"""
- return asyncio.run(self._async_client.wait_processed(timeout))
+ return run_async(self._async_client.wait_processed(timeout))
def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
"""Content search"""
- return asyncio.run(self._async_client.grep(uri, pattern, case_insensitive))
+ return run_async(self._async_client.grep(uri, pattern, case_insensitive))
def glob(self, pattern: str, uri: str = "viking://") -> Dict:
"""File pattern matching"""
- return asyncio.run(self._async_client.glob(pattern, uri))
+ return run_async(self._async_client.glob(pattern, uri))
def mv(self, from_uri: str, to_uri: str) -> None:
"""Move resource"""
- return asyncio.run(self._async_client.mv(from_uri, to_uri))
+ return run_async(self._async_client.mv(from_uri, to_uri))
def tree(self, uri: str) -> Dict:
"""Get directory tree"""
- return asyncio.run(self._async_client.tree(uri))
+ return run_async(self._async_client.tree(uri))
def stat(self, uri: str) -> Dict:
"""Get resource status"""
- return asyncio.run(self._async_client.stat(uri))
+ return run_async(self._async_client.stat(uri))
def mkdir(self, uri: str) -> None:
"""Create directory"""
- return asyncio.run(self._async_client.mkdir(uri))
+ return run_async(self._async_client.mkdir(uri))
def get_status(self):
"""Get system status.
@@ -196,4 +196,4 @@ class SyncOpenViking:
@classmethod
def reset(cls) -> None:
"""Reset singleton (for testing)."""
- return asyncio.run(AsyncOpenViking.reset())
+ return run_async(AsyncOpenViking.reset())
diff --git a/openviking/utils/__init__.py b/openviking/utils/__init__.py
index 0bb8fbfe2..939b8fd10 100644
--- a/openviking/utils/__init__.py
+++ b/openviking/utils/__init__.py
@@ -2,6 +2,7 @@
# SPDX-License-Identifier: Apache-2.0
"""Utility functions and helpers."""
+from openviking.utils.async_utils import run_async
from openviking.utils.llm import StructuredLLM, parse_json_from_response, parse_json_to_model
from openviking.utils.logger import default_logger, get_logger
from openviking.utils.uri import VikingURI
@@ -13,4 +14,5 @@ __all__ = [
"StructuredLLM",
"parse_json_from_response",
"parse_json_to_model",
+ "run_async",
]
diff --git a/openviking/utils/async_utils.py b/openviking/utils/async_utils.py
new file mode 100644
index 000000000..8e47034ec
--- /dev/null
+++ b/openviking/utils/async_utils.py
@@ -0,0 +1,35 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Async helper utilities for running coroutines from sync code.
+"""
+
+import asyncio
+from typing import Coroutine, TypeVar
+
+T = TypeVar("T")
+
+
+def run_async(coro: Coroutine[None, None, T]) -> T:
+ """
+ Run async coroutine from sync code, handling nested event loops.
+
+ This function safely runs a coroutine whether or not there's already
+ a running event loop (e.g., when called from within an MCP server).
+
+ Args:
+ coro: The coroutine to run
+
+ Returns:
+ The result of the coroutine
+ """
+ try:
+ loop = asyncio.get_running_loop()
+ # Already in event loop, use nest_asyncio to allow nested calls
+ import nest_asyncio
+
+ nest_asyncio.apply()
+ return loop.run_until_complete(coro)
+ except RuntimeError:
+ # No running event loop, use asyncio.run()
+ return asyncio.run(coro)
diff --git a/tests/client/test_resource_management.py b/tests/client/test_resource_management.py
index c82fd8a42..6fac382fe 100644
--- a/tests/client/test_resource_management.py
+++ b/tests/client/test_resource_management.py
@@ -41,9 +41,9 @@ class TestAddResource:
)
assert "root_uri" in result
- # In async mode, status can be monitored via observers
- observers = client.observers
- assert "queue" in observers
+ # In async mode, status can be monitored via observer
+ observer = client.observer
+ assert observer.queue is not None
async def test_add_resource_with_target(
self, client: AsyncOpenViking, sample_markdown_file: Path
diff --git a/tests/misc/test_vikingdb_observer.py b/tests/misc/test_vikingdb_observer.py
index 0cfbfa168..35318fc5c 100644
--- a/tests/misc/test_vikingdb_observer.py
+++ b/tests/misc/test_vikingdb_observer.py
@@ -24,43 +24,44 @@ async def test_vikingdb_observer():
# Test observer access
print("\n1. Test observer access:")
- print(f"Available observers: {list(client.observers.keys())}")
+ print(f"Observer service: {client.observer}")
# Test QueueObserver
print("\n2. Test QueueObserver:")
- queue_observer = client.observers["queue"]
- print(f"Type: {type(queue_observer)}")
- print(f"Is healthy: {queue_observer.is_healthy()}")
- print(f"Has errors: {queue_observer.has_errors()}")
+ queue_status = client.observer.queue
+ print(f"Type: {type(queue_status)}")
+ print(f"Is healthy: {queue_status.is_healthy}")
+ print(f"Has errors: {queue_status.has_errors}")
# Test direct print
print("\n3. Test direct print QueueObserver:")
- print(queue_observer)
+ print(queue_status)
# Test VikingDBObserver
print("\n4. Test VikingDBObserver:")
- vikingdb_observer = client.observers["vikingdb"]
- print(f"Type: {type(vikingdb_observer)}")
- print(f"Is healthy: {vikingdb_observer.is_healthy()}")
- print(f"Has errors: {vikingdb_observer.has_errors()}")
+ vikingdb_status = client.observer.vikingdb
+ print(f"Type: {type(vikingdb_status)}")
+ print(f"Is healthy: {vikingdb_status.is_healthy}")
+ print(f"Has errors: {vikingdb_status.has_errors}")
# Test direct print
print("\n5. Test direct print VikingDBObserver:")
- print(vikingdb_observer)
-
- # Test get status table
- print("\n6. Test get status table:")
- status_table = vikingdb_observer.get_status_table()
- print(f"Status table type: {type(status_table)}")
- print(f"Status table length: {len(status_table)}")
-
- # Test observer properties
- print("\n7. Test observer properties:")
- for name, observer in client.observers.items():
+ print(vikingdb_status)
+
+ # Test status string
+ print("\n6. Test status string:")
+ print(f"Status type: {type(vikingdb_status.status)}")
+ print(f"Status length: {len(vikingdb_status.status)}")
+
+ # Test system status
+ print("\n7. Test system status:")
+ system_status = client.observer.system
+ print(f"System is_healthy: {system_status.is_healthy}")
+ for name, component in system_status.components.items():
print(f"\n{name}:")
- print(f" is_healthy: {observer.is_healthy()}")
- print(f" has_errors: {observer.has_errors()}")
- print(f" str(observer): {str(observer)[:100]}...")
+ print(f" is_healthy: {component.is_healthy}")
+ print(f" has_errors: {component.has_errors}")
+ print(f" status: {component.status[:100]}...")
print("\n=== All tests completed ===")
@@ -80,7 +81,7 @@ def test_sync_client():
"""Test sync client"""
print("\n=== Test sync client ===")
- client = ov.OpenViking(path="./test_data_sync")
+ client = ov.OpenViking(path="./test_data")
try:
# Initialize
@@ -88,15 +89,15 @@ def test_sync_client():
print("Sync client initialized successfully")
# Test observer access
- print(f"Available observers: {list(client.observers.keys())}")
+ print(f"Observer service: {client.observer}")
# Test QueueObserver
print("\nQueueObserver status:")
- print(client.observers["queue"])
+ print(client.observer.queue)
# Test VikingDBObserver
print("\nVikingDBObserver status:")
- print(client.observers["vikingdb"])
+ print(client.observer.vikingdb)
print("\n=== Sync client test completed ===")