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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""openviking-server doctor - validate OpenViking subsystems and report actionable diagnostics.
Unlike ``ov health`` (which pings a running server), ``openviking-server doctor`` checks
local prerequisites without requiring a server: config file, Python version,
native vector engine, AGFS, embedding provider, VLM provider, VikingBot auth,
and disk space.
"""
from __future__ import annotations
import asyncio
import importlib
import json
import os
import platform
import shutil
import sys
from pathlib import Path
from typing import Any, Literal, Optional
from openviking.server.config import (
ServerConfig,
get_server_url_from_server_data,
)
from openviking_cli.utils.config.config_loader import resolve_config_path
from openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENV
from openviking_cli.utils.config.ovcli_config import load_ovcli_config
from openviking_cli.utils.config.vlm_config import VLMConfig
CheckStatus = Literal["pass", "warn", "fail"]
CheckResult = tuple[bool | CheckStatus, str, Optional[str]]
# ANSI helpers (disabled when stdout is not a terminal)
_USE_COLOR = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
def _green(text: str) -> str:
return f"\033[32m{text}\033[0m" if _USE_COLOR else text
def _red(text: str) -> str:
return f"\033[31m{text}\033[0m" if _USE_COLOR else text
def _yellow(text: str) -> str:
return f"\033[33m{text}\033[0m" if _USE_COLOR else text
def _dim(text: str) -> str:
return f"\033[2m{text}\033[0m" if _USE_COLOR else text
# ---------------------------------------------------------------------------
# Individual check functions
# ---------------------------------------------------------------------------
def _find_config() -> Optional[Path]:
return resolve_config_path(None, OPENVIKING_CONFIG_ENV, "ov.conf")
def _load_config_json(config_path: Path) -> Optional[dict]:
"""Parse ov.conf as JSON. Returns None if the file is unreadable or not valid JSON."""
try:
raw = config_path.read_text(encoding="utf-8-sig")
raw = os.path.expandvars(raw)
return json.loads(raw)
except (OSError, json.JSONDecodeError):
return None
def _normalize_check_result(result: CheckResult) -> tuple[CheckStatus, str, Optional[str]]:
"""Normalize legacy bool checks and newer tri-state checks."""
status, detail, fix = result
if status is True:
return "pass", detail, fix
if status is False:
return "fail", detail, fix
if status in {"pass", "warn", "fail"}:
return status, detail, fix
return "fail", f"Invalid check status: {status!r}", None
def check_config() -> tuple[bool, str, Optional[str]]:
"""Validate ov.conf exists and is valid JSON with required sections."""
config_path = _find_config()
if config_path is None:
return (
False,
"Configuration file not found",
f"Create ~/.openviking/ov.conf or set {OPENVIKING_CONFIG_ENV}",
)
try:
raw = config_path.read_text(encoding="utf-8-sig")
raw = os.path.expandvars(raw)
data = json.loads(raw)
except json.JSONDecodeError as exc:
return False, f"Invalid JSON in {config_path}", f"Fix syntax error: {exc}"
if not isinstance(data, dict):
return (
False,
f"{config_path} must contain a JSON object",
"The top-level config must be a JSON object",
)
# Validate the parsed config the same way the server does on startup, so
# `doctor` reports unknown or invalid fields instead of passing a config
# that would actually fail to load on `openviking-server` startup (#2373).
from openviking_cli.utils.config.open_viking_config import OpenVikingConfig
try:
OpenVikingConfig.from_dict(data)
except ValueError as exc:
first_error = next((line for line in str(exc).splitlines() if line.strip()), "")
detail = (
f"{config_path}: {first_error}"
if first_error
else f"Invalid configuration in {config_path}"
)
return (
False,
detail,
"Fix the reported field(s); run `openviking-server` to see full details",
)
return True, str(config_path), None
def check_python() -> tuple[bool, str, Optional[str]]:
"""Verify Python >= 3.10."""
version = sys.version_info
version_str = f"{version[0]}.{version[1]}.{version[2]}"
if version >= (3, 10):
return True, f"{version_str} (>= 3.10 required)", None
return (
False,
f"{version_str} (>= 3.10 required)",
"Upgrade Python to 3.10 or later",
)
def check_native_engine() -> tuple[bool, str, Optional[str]]:
"""Check if the native vector engine (PersistStore) is available."""
try:
from openviking.storage.vectordb.engine import (
AVAILABLE_ENGINE_VARIANTS,
ENGINE_VARIANT,
)
except ImportError as exc:
return (
False,
f"Cannot import engine module: {exc}",
"pip install openviking --upgrade --force-reinstall",
)
if ENGINE_VARIANT == "unavailable":
variants = ", ".join(AVAILABLE_ENGINE_VARIANTS) if AVAILABLE_ENGINE_VARIANTS else "none"
machine = platform.machine()
return (
False,
f"No compatible engine variant (platform: {machine}, packaged: {variants})",
'pip install openviking --upgrade --force-reinstall\n Alt: Use vectordb.backend = "volcengine" instead of "local"',
)
return True, f"variant={ENGINE_VARIANT}", None
def check_agfs() -> tuple[bool, str, Optional[str]]:
"""Verify the bundled OpenViking AGFS client loads."""
try:
pyagfs = importlib.import_module("openviking.pyagfs")
version = getattr(pyagfs, "__version__", "unknown")
return True, f"AGFS SDK {version}", None
except ImportError:
return (
False,
"Bundled AGFS client not found",
"pip install openviking --upgrade --force-reinstall",
)
def _embedding_probe_label(provider: str, model: str, dense: dict[str, Any]) -> str:
api_base = dense.get("api_base")
dimension = dense.get("dimension")
parts = [f"{provider}/{model}"]
if api_base:
parts.append(f"api_base={api_base}")
if dimension:
parts.append(f"dimension={dimension}")
return " ".join(parts)
def _probe_embedding_provider(
embedding: dict[str, Any],
dense: dict[str, Any],
) -> tuple[bool, str, Optional[str]]:
"""Create the configured embedder, make one request, and validate vector shape."""
from openviking.models.embedder.base import embed_compat
from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
provider = dense.get("provider", "local")
model = dense.get("model", "bge-small-zh-v1.5-f16")
label = _embedding_probe_label(provider, model, dense)
try:
model_config = EmbeddingModelConfig(**dense)
config_kwargs = {
key: embedding[key]
for key in ("max_concurrent", "max_retries", "text_source", "max_input_tokens")
if key in embedding
}
embedding_config = EmbeddingConfig(dense=model_config, **config_kwargs)
embedder = embedding_config.get_embedder()
expected_dimension = (
model_config.dimension
if model_config.dimension is not None
else embedder.get_dimension()
)
except Exception as exc:
return (
False,
f"{label} (invalid embedding config: {exc})",
"Fix embedding.dense provider/model/api_base/dimension in ov.conf",
)
async def _run_probe():
return await asyncio.wait_for(
embed_compat(embedder, "OpenViking doctor embedding probe", is_query=True),
timeout=10.0,
)
try:
result = asyncio.run(_run_probe())
except TimeoutError:
return (
False,
f"{label} (probe timed out)",
"Check embedding.dense.api_base and make sure the embedding provider is reachable",
)
except Exception as exc:
return (
False,
f"{label} (probe failed: {exc})",
"Check the embedding provider service, model name, API key, and api_base",
)
vector = getattr(result, "dense_vector", None)
if not vector:
return (
False,
f"{label} (probe returned no dense vector)",
"Use a dense embedding model or configure embedding.dense correctly",
)
actual_dimension = len(vector)
if actual_dimension != expected_dimension:
return (
False,
f"{label} (dimension mismatch: expected {expected_dimension}, got {actual_dimension})",
"Set embedding.dense.dimension to match the provider output, or use a matching model/index",
)
return True, f"{label} probe ok (dimension={actual_dimension})", None
def check_embedding() -> tuple[bool, str, Optional[str]]:
"""Load embedding config and verify provider connectivity."""
config_path = _find_config()
if config_path is None:
return False, "Cannot check (no config file)", None
data = _load_config_json(config_path)
if data is None:
return False, "Cannot check (config unreadable)", None
embedding = data.get("embedding", {}) or {}
dense = embedding.get("dense", {}) or {}
provider = dense.get("provider", "local")
model = dense.get("model", "bge-small-zh-v1.5-f16")
if provider == "local":
from openviking.models.embedder.local_embedders import (
get_local_model_cache_path,
get_local_model_spec,
)
try:
get_local_model_spec(model)
except ValueError as exc:
return (
False,
f"{provider}/{model} (unsupported local model)",
str(exc),
)
try:
importlib.import_module("llama_cpp")
except ImportError:
return (
False,
f"{provider}/{model} (missing llama-cpp-python)",
'pip install "openviking[local-embed]"',
)
model_path = dense.get("model_path", "")
cache_dir = Path(dense.get("cache_dir", "~/.cache/openviking/models")).expanduser()
if model_path:
if not Path(model_path).expanduser().exists():
return (
False,
f"{provider}/{model} (model_path missing)",
f"Download the GGUF model to {Path(model_path).expanduser()} or update embedding.dense.model_path",
)
return True, f"{provider}/{model} ({Path(model_path).expanduser()})", None
cached_file = get_local_model_cache_path(model, str(cache_dir))
if cached_file.exists():
return True, f"{provider}/{model} ({cached_file})", None
return (
True,
f"{provider}/{model} (will auto-download during startup initialization)",
None,
)
api_key = dense.get("api_key", "")
api_base = dense.get("api_base", "")
if provider != "ollama" and not api_base and (not api_key or api_key.startswith("{")):
return (
False,
f"{provider}/{model} (no API key)",
"Set embedding.dense.api_key in ov.conf",
)
return _probe_embedding_provider(embedding, dense)
def check_vlm() -> tuple[bool, str, Optional[str]]:
"""Load VLM config and verify it's configured."""
config_path = _find_config()
if config_path is None:
return False, "Cannot check (no config file)", None
data = _load_config_json(config_path)
if data is None:
return False, "Cannot check (config unreadable)", None
raw_vlm = data.get("vlm", {})
normalized_vlm = VLMConfig.sync_provider_backend(dict(raw_vlm))
try:
# Doctor owns the runtime credential probe below. Skip only the model's
# Codex availability check while retaining all structural validation.
vlm = VLMConfig.model_validate(
normalized_vlm,
context={"skip_codex_auth_availability": True},
)
except Exception as exc:
return False, f"Invalid VLM config: {exc}", "Fix vlm section in ov.conf"
_, provider = vlm.get_provider_config()
model = vlm.model or ""
if not provider:
return False, "No VLM provider configured", "Add vlm section to ov.conf"
if provider == "openai-codex":
api_key = vlm._get_effective_api_key()
if api_key and not api_key.startswith("{"):
return True, f"openai-codex/{model} (explicit api_key)", None
importlib.import_module("openviking.models.vlm")
codex_auth = importlib.import_module("openviking.models.vlm.backends.codex_auth")
try:
creds = codex_auth.resolve_codex_runtime_credentials()
source = creds.get("source", "unknown")
return True, f"openai-codex/{model} (oauth via {source})", None
except Exception as exc:
status = codex_auth.get_codex_auth_status()
store_path = status.get("store_path") or "~/.openviking/codex_auth.json"
bootstrap_path = status.get("bootstrap_path") or "~/.codex/auth.json"
return (
False,
f"openai-codex/{model} ({exc})",
"Run `openviking-server init` and choose `OpenAI Codex` to create OV-owned auth state\n"
f"Or bootstrap once from {bootstrap_path} into {store_path}",
)
# Ollama via LiteLLM doesn't need a real API key
if provider == "litellm" and model.startswith("ollama/"):
return True, f"{provider}/{model}", None
api_key = vlm._get_effective_api_key()
if not api_key or api_key.startswith("{"):
return (
False,
f"{provider}/{model} (no API key)",
"Set vlm.api_key in ov.conf",
)
return True, f"{provider}/{model}", None
def check_ollama() -> tuple[bool, str, Optional[str]]:
"""Check Ollama connectivity if the config uses an Ollama provider."""
config_path = _find_config()
if config_path is None:
return True, "not configured", None
data = _load_config_json(config_path)
if data is None:
return True, "not configured", None
# Detect whether config uses Ollama
dense = data.get("embedding", {}).get("dense", {})
vlm = data.get("vlm", {})
query_planner = data.get("query_planner") or {}
uses_embedding = dense.get("provider") == "ollama"
uses_vlm = vlm.get("provider") == "litellm" and (vlm.get("model", "")).startswith("ollama/")
uses_query_planner = query_planner.get("provider") == "litellm" and (
query_planner.get("model", "")
).startswith("ollama/")
if not uses_embedding and not uses_vlm and not uses_query_planner:
return True, "not configured", None
from openviking_cli.utils.ollama import check_ollama_running, parse_ollama_url
# Determine host/port from config (embedding -> vlm -> query_planner)
if uses_embedding:
host, port = parse_ollama_url(dense.get("api_base"))
elif uses_vlm:
host, port = parse_ollama_url(vlm.get("api_base"))
else:
host, port = parse_ollama_url(query_planner.get("api_base"))
if check_ollama_running(host, port):
return True, f"running at {host}:{port}", None
return (
False,
f"unreachable at {host}:{port}",
"Run 'ollama serve' or check your Ollama configuration",
)
def _is_placeholder_secret(value: str) -> bool:
stripped = value.strip()
return (
not stripped
or stripped.startswith("{")
or stripped.startswith("<")
or stripped.startswith("$")
)
def _load_ovcli_api_key_for_doctor() -> str:
try:
cli_config = load_ovcli_config()
except ValueError:
return ""
if cli_config is None:
return ""
return str(getattr(cli_config, "api_key", "") or "").strip()
def _bot_openviking_server_url(ov_server: dict[str, Any], server: dict[str, Any]) -> str:
configured_url = str(ov_server.get("server_url") or "").strip()
if configured_url:
return configured_url
return get_server_url_from_server_data(server)
def check_vikingbot() -> CheckResult:
"""Check VikingBot OpenViking Server auth config.
VikingBot is optional, so missing auth configuration is a warning rather
than a hard failure. In api_key mode VikingBot must use a User API key; in
trusted mode it uses a root API key through bot.ov_server.api_key plus
trusted identity headers.
"""
config_path = _find_config()
if config_path is None:
return "warn", "Cannot check (no config file)", None
data = _load_config_json(config_path)
if data is None:
return "warn", "Cannot check (config unreadable)", None
server = data.get("server") if isinstance(data.get("server"), dict) else {}
auth_mode = ServerConfig(
auth_mode=server.get("auth_mode"),
root_api_key=server.get("root_api_key"),
).get_effective_auth_mode()
server_root_api_key = str(server.get("root_api_key") or "").strip()
bot = data.get("bot")
if not isinstance(bot, dict):
bot = {}
ov_server = bot.get("ov_server")
if not isinstance(ov_server, dict):
ov_server = {}
api_key = str(ov_server.get("api_key") or "").strip()
root_api_key = str(ov_server.get("root_api_key") or "").strip()
explicit_api_key_type = str(ov_server.get("api_key_type") or "").strip().lower()
bot_server_url = _bot_openviking_server_url(ov_server, server)
bot_uses_current_server = not str(ov_server.get("server_url") or "").strip()
if explicit_api_key_type:
api_key_type = explicit_api_key_type
elif bot_uses_current_server:
api_key_type = "root" if auth_mode == "trusted" else "user"
else:
api_key_type = "user"
if api_key_type == "root":
if bot_uses_current_server and auth_mode != "trusted":
return (
"warn",
f"bot.ov_server targets {bot_server_url} with api_key_type=root, "
f"but that server is auth_mode={auth_mode}",
f"To use {bot_server_url}, set bot.ov_server.api_key_type to 'user' "
"and configure a User API key in bot.ov_server.api_key or ovcli.conf api_key.\n"
"To use root mode, change that OpenViking server to server.auth_mode='trusted'.\n"
"To use another trusted server, set bot.ov_server.server_url to that server "
"and keep api_key_type='root'.",
)
trusted_root_key = (
server_root_api_key if bot_uses_current_server and auth_mode == "trusted" else api_key
)
if _is_placeholder_secret(trusted_root_key):
if root_api_key:
return (
"warn",
"bot.ov_server.root_api_key is deprecated and ignored",
"Move the root API key to bot.ov_server.api_key and keep "
"bot.ov_server.api_key_type='root'",
)
if auth_mode == "trusted" and not ov_server:
return (
"warn",
"server.auth_mode=trusted without server.root_api_key",
"Configure server.root_api_key; trusted mode requires it even on localhost",
)
return (
"warn",
"bot.ov_server.api_key_type=root without root API key",
"Configure bot.ov_server.api_key with a root API key for trusted OpenViking access",
)
return "pass", "bot.ov_server configured for trusted OpenViking auth", None
if bot_uses_current_server and auth_mode == "dev":
return "pass", "VikingBot aligned with dev OpenViking auth", None
ovcli_api_key = "" if not _is_placeholder_secret(api_key) else _load_ovcli_api_key_for_doctor()
if not _is_placeholder_secret(api_key):
return "pass", "bot.ov_server.api_key configured for api_key mode", None
if not _is_placeholder_secret(ovcli_api_key):
return "pass", "ovcli.conf api_key configured for VikingBot api_key mode", None
if _is_placeholder_secret(api_key):
if root_api_key:
return (
"warn",
"bot.ov_server.root_api_key is deprecated and ignored",
"Use bot.ov_server.api_key for the active key. In api_key mode configure "
"a User API key in bot.ov_server.api_key or ovcli.conf api_key.",
)
if not bot or not ov_server:
return (
"warn",
"bot.ov_server not configured and ovcli.conf api_key not configured",
"Configure bot.ov_server.api_key or ovcli.conf api_key with an "
"OpenViking User API key",
)
return (
"warn",
"bot.ov_server.api_key and ovcli.conf api_key not configured",
"Create an OpenViking User API key and set bot.ov_server.api_key or ovcli.conf api_key",
)
return "pass", "bot.ov_server.api_key configured for api_key mode", None
def check_authentication() -> CheckResult:
"""Check authentication configuration using auth health checks."""
config_path = _find_config()
if config_path is None:
return "warn", "Cannot check (no config file)", None
data = _load_config_json(config_path)
if data is None:
return "warn", "Cannot check (config unreadable)", None
# Load server config
try:
from openviking.server.auth.health_check import run_health_check
from openviking.server.config import ServerConfig
server_data = data.get("server", {}) if isinstance(data.get("server"), dict) else {}
config = ServerConfig(**server_data)
except ImportError:
return "warn", "Auth health check not available (module missing)", None
except Exception as exc:
return "warn", f"Could not load server config: {exc}", None
# Run auth health checks
try:
report = asyncio.run(run_health_check(config, fail_on_warn=False))
except Exception as exc:
return "warn", f"Auth health check failed to run: {exc}", None
# Format results
auth_mode = report.auth_mode
pass_count = sum(1 for c in report.checks if c.status == "pass")
warn_count = sum(1 for c in report.checks if c.status == "warn")
fail_count = sum(1 for c in report.checks if c.status == "fail")
detail = f"{auth_mode}: {pass_count} passed, {warn_count} warned, {fail_count} failed"
if report.overall_status == "pass":
return "pass", detail, None
elif report.overall_status == "warn":
# Collect warning messages
warn_msgs = []
for c in report.checks:
if c.status == "warn":
warn_msgs.append(f" - {c.name}: {c.message}")
fix = "\n".join(warn_msgs) if warn_msgs else None
return "warn", detail, fix
else:
# Collect fail messages
fail_msgs = []
for c in report.checks:
if c.status == "fail":
fail_msgs.append(f" - {c.name}: {c.message}")
fix = "\n".join(fail_msgs) if fail_msgs else None
return "fail", detail, fix
def check_disk() -> tuple[bool, str, Optional[str]]:
"""Check free disk space in the workspace directory."""
config_path = _find_config()
workspace = Path.home() / ".openviking"
if config_path:
data = _load_config_json(config_path)
if data is not None:
ws = data.get("storage", {}).get("workspace", "")
if ws:
workspace = Path(ws).expanduser()
check_path = workspace if workspace.exists() else Path.home()
usage = shutil.disk_usage(check_path)
free_gb = usage.free / (1024**3)
if free_gb < 1.0:
return (
False,
f"{free_gb:.1f} GB free in {check_path}",
"Free up disk space (OpenViking needs at least 1 GB for vector storage)",
)
return True, f"{free_gb:.1f} GB free in {check_path}", None
# ---------------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------------
_CHECKS = [
("Config", check_config),
("Python", check_python),
("Native Engine", check_native_engine),
("AGFS", check_agfs),
("Authentication", check_authentication),
("Embedding", check_embedding),
("VLM", check_vlm),
("Ollama", check_ollama),
("VikingBot", check_vikingbot),
("Disk", check_disk),
]
def run_doctor() -> int:
"""Run all diagnostic checks and print a formatted report.
Returns 0 if all checks pass, 1 otherwise.
"""
print("\nOpenViking Doctor\n")
failed = 0
warned = 0
max_label = max(len(label) for label, _ in _CHECKS)
for label, check_fn in _CHECKS:
try:
status_key, detail, fix = _normalize_check_result(check_fn())
except Exception as exc:
status_key, detail, fix = "fail", f"Unexpected error: {type(exc).__name__}: {exc}", None
pad = " " * (max_label - len(label) + 1)
if status_key == "pass":
status = _green("PASS")
print(f" {label}:{pad}{status} {detail}")
elif status_key == "warn":
status = _yellow("WARN")
print(f" {label}:{pad}{status} {detail}")
warned += 1
if fix:
for line in fix.split("\n"):
print(f" {' ' * (max_label + 2)}{_dim('Fix: ' + line)}")
else:
status = _red("FAIL")
print(f" {label}:{pad}{status} {detail}")
failed += 1
if fix:
for line in fix.split("\n"):
print(f" {' ' * (max_label + 2)}{_dim('Fix: ' + line)}")
print()
if failed:
print(f" {_red(f'{failed} check(s) failed.')} See above for fix suggestions.\n")
return 1
if warned:
print(f" {_yellow(f'{warned} warning(s).')} Review the suggestions above.\n")
return 0
print(f" {_green('All checks passed.')}\n")
return 0
def main() -> int:
"""Entry point for ``openviking-server doctor``."""
return run_doctor()