Skip to content

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

36.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
import hashlib
import json
import logging
import os
from pathlib import Path
from threading import Lock
from typing import Any, Dict, List, Literal, Optional
from urllib.parse import urlsplit

from pydantic import BaseModel, Field, ValidationError, model_validator

from openviking_cli.session.user_id import UserIdentifier

from .agent_evolution_config import AgentEvolutionConfig
from .cache_config import CacheConfig
from .config_loader import resolve_config_path
from .config_utils import (
    DEFAULT_SERVICE_NAME,
    format_validation_error,
    normalize_service_name,
    warn_unknown_config_fields,
    warn_unknown_fields,
)
from .consts import (
    DEFAULT_CONFIG_DIR,
    DEFAULT_OV_CONF,
    OPENVIKING_CONFIG_ENV,
    SYSTEM_CONFIG_DIR,
)
from .embedding_config import EmbeddingConfig
from .encryption_config import EncryptionConfig
from .expiry_config import ExpiryConfig
from .git_config import GitConfig
from .glob_config import GlobConfig
from .grep_config import GrepConfig
from .ingest_config import IngestConfig
from .log_config import LogConfig
from .memory_config import MemoryConfig
from .oauth_config import OAuthConfig
from .openviking_gateway_config import EmbeddedGatewayConfig
from .parser_config import (
    AnydocConfig,
    AudioConfig,
    CodeConfig,
    DirectoryConfig,
    FeishuConfig,
    HTMLConfig,
    ImageConfig,
    MarkdownConfig,
    PDFConfig,
    SemanticConfig,
    TextConfig,
    VideoConfig,
    WebFeedConfig,
)
from .prompts_config import PromptsConfig
from .queue_worker_config import QueueWorkersConfig
from .reindex_config import ReindexConfig
from .rerank_config import RerankConfig
from .retrieval_config import RetrievalConfig
from .rules_config import RulesConfig
from .runtime_field import RuntimeField
from .storage_config import StorageConfig
from .telemetry_config import TelemetryConfig
from .ttl_config import TTLConfig
from .vlm_config import VLMConfig


def _get_config_logger():
    """Use stdlib logging during config bootstrap to avoid early logger side effects."""
    return logging.getLogger(__name__)


class ConnectorConfig(BaseModel):
    """Configuration for external Connector service."""

    enable: bool = False
    connector: str = ""
    tracker: str = ""
    auth: str = ""
    timeout_seconds: int = 3600
    poll_interval_ms: int = 5000
    allowed_add_types: List[str] = Field(default_factory=lambda: ["tos"])

    @model_validator(mode="after")
    def _validate(self) -> "ConnectorConfig":
        self.auth = self.auth.strip()
        if self.auth:
            url = urlsplit(self.auth)
            if (
                url.scheme not in {"http", "https"}
                or not url.hostname
                or url.username
                or url.password
                or url.fragment
            ):
                raise ValueError(
                    "connector.auth must be an HTTP(S) endpoint URL without credentials or fragment"
                )
        if self.enable:
            for name, url in (("connector", self.connector), ("tracker", self.tracker)):
                if not url.strip():
                    raise ValueError(f"connector.{name} is required when connector.enable=true")
                if "://" not in url:
                    raise ValueError(
                        f"connector.{name} must be a full endpoint URL including scheme "
                        "(e.g., http://...)"
                    )
        if self.timeout_seconds <= 0:
            raise ValueError("connector.timeout_seconds must be > 0")
        if self.poll_interval_ms <= 0:
            raise ValueError("connector.poll_interval_ms must be > 0")
        return self

    def credential_resolve_url(self) -> str:
        """Derive the unified credential-resolve endpoint from ``auth``.

        The Feishu compatibility endpoint (``.../oauth/access_token``) and the
        unified resolver (``.../credential/resolve``) are two fixed paths on the
        same KernelAPI inner entry, so the resolver URL is derived from the
        configured ``auth`` rather than adding a second endpoint setting; this
        keeps existing Feishu deployments unchanged. Returns an empty string
        when ``auth`` is unset or uses an unrecognized path.
        """
        auth = self.auth.strip()
        if not auth:
            return ""
        compat_suffix = "/oauth/access_token"
        resolve_suffix = "/credential/resolve"
        if auth.endswith(compat_suffix):
            return auth[: -len(compat_suffix)] + resolve_suffix
        if auth.endswith(resolve_suffix):
            return auth
        return ""


class ParserApiConfig(BaseModel):
    """Configuration for the Understanding files/responses API."""

    enable: bool = False
    extensions: List[str] = Field(default_factory=list)
    host: str = ""
    api_key: str = ""
    enable_feishu_url: bool = False
    enable_resumable_upload: bool = False
    upload_simple_max_bytes: int = 512 * 1024 * 1024
    upload_part_size_bytes: int = 8 * 1024 * 1024
    http_timeout_seconds: float = 10.0
    response_timeout_seconds: int = 1800
    poll_interval_ms: int = 3000

    @model_validator(mode="after")
    def _normalize_and_validate(self) -> "ParserApiConfig":
        normalized_extensions: List[str] = []
        for ext in self.extensions or []:
            s = str(ext).strip().lower()
            if not s:
                continue
            if s.startswith("."):
                s = s[1:]
            normalized_extensions.append(s)
        self.extensions = normalized_extensions

        if self.enable:
            if not self.host.strip():
                raise ValueError("parser_api.host is required when parser_api.enable=true")
            if not self.api_key.strip():
                raise ValueError("parser_api.api_key is required when parser_api.enable=true")
        if self.host and "://" not in self.host:
            raise ValueError("parser_api.host must include scheme (e.g., https://...)")
        if self.upload_simple_max_bytes <= 0:
            raise ValueError("parser_api.upload_simple_max_bytes must be > 0")
        if self.upload_part_size_bytes <= 0:
            raise ValueError("parser_api.upload_part_size_bytes must be > 0")
        if self.http_timeout_seconds <= 0:
            raise ValueError("parser_api.http_timeout_seconds must be > 0")
        if self.response_timeout_seconds <= 0:
            raise ValueError("parser_api.response_timeout_seconds must be > 0")
        if self.poll_interval_ms <= 0:
            raise ValueError("parser_api.poll_interval_ms must be > 0")
        return self


class ParserRuntimeConfig(BaseModel):
    """Runtime directories used by built-in parser download/extraction paths."""

    download_temp_dir: Optional[str] = Field(
        default=None,
        description=(
            "Directory for parser-owned downloads, Git checkouts, and archive extraction. "
            "Defaults to the system temporary directory."
        ),
    )


class CompileApiConfig(BaseModel):
    """Configuration for the external Compile task API."""

    base_url: str = ""
    gateway_token: str = ""
    http_timeout_seconds: float = 10.0
    poll_interval_ms: int = 30000
    # Run Redis-backed Compile scheduling on this instance.
    scheduler_enabled: bool = False
    scheduler_backend: Literal["redis"] = "redis"

    @model_validator(mode="after")
    def _validate(self) -> "CompileApiConfig":
        if self.base_url and "://" not in self.base_url:
            raise ValueError("compile_api.base_url must include scheme (e.g., https://...)")
        if self.http_timeout_seconds <= 0:
            raise ValueError("compile_api.http_timeout_seconds must be > 0")
        if self.poll_interval_ms <= 0:
            raise ValueError("compile_api.poll_interval_ms must be > 0")
        self.base_url = self.base_url.rstrip("/")
        return self


class RuntimeConfigSettings(BaseModel):
    """Startup selection of the runtime config source."""

    source: str = "file"
    module: Optional[str] = None
    params: Dict[str, Any] = Field(default_factory=dict)


class OpenVikingConfig(BaseModel):
    """Main configuration for OpenViking."""

    default_account: Optional[str] = Field(
        default="default", description="Default account identifier"
    )
    default_user: Optional[str] = Field(default="default", description="Default user identifier")
    default_agent: Optional[str] = Field(
        default=None,
        description="Deprecated and ignored. User is the only data-plane identity.",
    )
    service_name: str = Field(
        default=DEFAULT_SERVICE_NAME,
        description="OpenViking deployment name shared by cache namespaces and OTel defaults",
    )

    cache: Optional[CacheConfig] = Field(
        default=None,
        description="Global cache Provider configuration",
    )

    storage: StorageConfig = Field(
        default_factory=StorageConfig, description="Storage configuration"
    )

    parser: ParserRuntimeConfig = Field(
        default_factory=ParserRuntimeConfig,
        description="Runtime directories used by built-in parsers",
    )

    embedding: EmbeddingConfig = Field(
        default_factory=EmbeddingConfig, description="Embedding configuration"
    )

    vlm: VLMConfig = Field(default_factory=VLMConfig, description="VLM configuration")

    query_planner: Optional[VLMConfig] = Field(
        default=None,
        description=(
            "Optional lightweight model configuration for retrieval intent analysis and query "
            "planning. Falls back to vlm when unset or empty."
        ),
    )

    rerank: RerankConfig = Field(default_factory=RerankConfig, description="Rerank configuration")

    rules: RulesConfig = Field(
        default_factory=RulesConfig,
        description="Rule compilation and applicability model configuration",
    )

    retrieval: RetrievalConfig = Field(
        default_factory=RetrievalConfig,
        description="Retrieval behavior configuration",
    )

    grep: GrepConfig = Field(
        default_factory=GrepConfig,
        description="Grep engine configuration",
    )

    glob: GlobConfig = Field(
        default_factory=GlobConfig,
        description="Glob engine configuration",
    )

    # Encryption configuration
    encryption: EncryptionConfig = Field(
        default_factory=EncryptionConfig, description="Encryption configuration"
    )

    git: GitConfig = Field(
        default_factory=GitConfig, description="Git version control configuration"
    )

    pdf: PDFConfig = Field(default_factory=PDFConfig, description="PDF parsing configuration")

    code: CodeConfig = Field(default_factory=CodeConfig, description="Code parsing configuration")

    image: ImageConfig = Field(
        default_factory=ImageConfig, description="Image parsing configuration"
    )

    audio: AudioConfig = Field(
        default_factory=AudioConfig, description="Audio parsing configuration"
    )

    video: VideoConfig = Field(
        default_factory=VideoConfig, description="Video parsing configuration"
    )

    markdown: MarkdownConfig = Field(
        default_factory=MarkdownConfig, description="Markdown parsing configuration"
    )

    anydoc: AnydocConfig = Field(
        default_factory=AnydocConfig,
        description="Shared anydoc Office conversion configuration",
    )

    html: HTMLConfig = Field(default_factory=HTMLConfig, description="HTML parsing configuration")

    text: TextConfig = Field(default_factory=TextConfig, description="Text parsing configuration")

    directory: DirectoryConfig = Field(
        default_factory=DirectoryConfig, description="Directory parsing configuration"
    )

    feishu: FeishuConfig = Field(
        default_factory=FeishuConfig,
        description="Feishu/Lark document parsing configuration",
    )

    webfeed: WebFeedConfig = Field(
        default_factory=WebFeedConfig,
        description="Whole-site ingestion via sitemap / RSS / Atom feeds",
    )

    semantic: SemanticConfig = Field(
        default_factory=SemanticConfig,
        description="Semantic processing configuration (overview/abstract limits)",
    )

    queue_workers: QueueWorkersConfig = Field(
        default_factory=QueueWorkersConfig,
        description="Queue worker runtime configuration",
    )

    reindex: ReindexConfig = Field(
        default_factory=ReindexConfig,
        description="Admin reindex runtime configuration",
    )

    parser_api: ParserApiConfig = Field(
        default_factory=ParserApiConfig,
        description="Third-party parser API configuration (files/responses)",
    )

    compile_api: CompileApiConfig = Field(
        default_factory=CompileApiConfig,
        description="External Compile task API configuration",
    )

    connector: ConnectorConfig = Field(
        default_factory=ConnectorConfig,
        description="External Connector service configuration for data import",
    )

    gateway: EmbeddedGatewayConfig = Field(default_factory=EmbeddedGatewayConfig)

    enable_watch_scheduler: bool = Field(
        default=True,
        description=(
            "Whether to start the background WatchScheduler that periodically re-processes "
            "watched resources. Disable on read-only replicas that share a writer's data "
            "so only the writer runs the watch/refresh background loop."
        ),
    )

    reconcile_system_assets_on_startup: bool = Field(
        default=True,
        description=(
            "Whether to reconcile packaged system assets for active accounts during startup. "
            "Disable on read-only replicas that share a writer's data."
        ),
    )

    auto_generate_l0: bool = Field(
        default=True, description="Automatically generate L0 (abstract) if not provided"
    )

    auto_generate_l1: bool = Field(
        default=True, description="Automatically generate L1 (overview) if not provided"
    )

    default_search_mode: str = Field(
        default="thinking",
        description="Default search mode: 'fast' (vector only) or 'thinking' (vector + LLM rerank)",
    )

    default_search_limit: int = Field(default=3, description="Default number of results to return")

    language_fallback: str = Field(
        default="en",
        description=(
            "Deprecated. No longer used — detection falls back to 'en' when no language can be "
            "inferred. Set output_language_override instead to pin an explicit language."
        ),
    )

    output_language_override: str = Field(
        default="",
        description=(
            "When non-empty, bypasses content-based language detection for memory extraction "
            "and semantic summaries/overviews and forces this language instead. Use when your "
            "corpus is mixed-language but you want summaries pinned to a single language "
            "(e.g., 'en', 'zh-CN', 'ja'). Leave empty (default) to auto-detect per content."
        ),
    )

    @model_validator(mode="after")
    def _warn_on_deprecated_language_fallback(self) -> "OpenVikingConfig":
        if self.language_fallback and self.language_fallback != "en":
            _get_config_logger().warning(
                "Config field 'language_fallback=%s' is deprecated and has no effect; "
                "remove it, or set 'output_language_override' to pin an explicit language.",
                self.language_fallback,
            )
        return self

    @model_validator(mode="after")
    def _validate_service_name(self) -> "OpenVikingConfig":
        """Validate and normalize the top-level service name."""
        self.service_name = normalize_service_name(self.service_name)
        return self

    @model_validator(mode="after")
    def _validate_cache_runtime_config(self) -> "OpenVikingConfig":
        """Require the shared cache Provider whenever AGFS selects a cache-backed runtime."""
        agfs = self.storage.agfs
        backups = agfs.backups or {}
        uses_canonical_cache = (
            agfs.cachefs.backend == "cache"
            or agfs.queuefs.backend == "cache"
            or agfs.pathlock.provider == "cache"
            or backups.get("provider", "filesystem") == "cache"
        )
        if uses_canonical_cache and self.cache is None:
            raise ValueError("top-level cache config is required when an AGFS backend uses cache")
        return self

    @model_validator(mode="before")
    @classmethod
    def _inherit_git_defaults_from_agfs(cls, data: Any) -> Any:
        """Let the `git` section inherit unset defaults from `storage.agfs`.

        - `git.backend` defaults to `storage.agfs.backend` (a 'memory' storage
          backend maps to 'local') when not set explicitly.
        - When the effective git backend is 's3', the `git.s3` fields
          bucket/region/endpoint/access_key/secret_key default to the matching
          `storage.agfs.s3` values when not set explicitly and the source value
          is non-empty.

        Injecting into the raw dict keeps GitConfig's own validation intact.
        """
        if not isinstance(data, dict):
            return data

        storage = data.get("storage")
        agfs = storage.get("agfs", {}) if isinstance(storage, dict) else {}
        if not isinstance(agfs, dict):
            agfs = {}

        git = data.get("git")
        if not isinstance(git, dict):
            if git is not None:
                # git provided as a model instance; respect it as-is.
                return data
            git = {}
        git = dict(git)

        if "backend" not in git:
            agfs_backend = agfs.get("backend", "local")
            if agfs_backend == "memory":
                agfs_backend = "local"
            if agfs_backend in ("local", "s3"):
                git["backend"] = agfs_backend

        if git.get("backend", "local") == "s3":
            agfs_s3 = agfs.get("s3", {})
            if not isinstance(agfs_s3, dict):
                agfs_s3 = {}
            git_s3 = git.get("s3")
            git_s3 = dict(git_s3) if isinstance(git_s3, dict) else {}
            for field in ("bucket", "region", "endpoint", "access_key", "secret_key"):
                if field not in git_s3 and agfs_s3.get(field):
                    git_s3[field] = agfs_s3[field]
            git["s3"] = git_s3

        data = dict(data)
        data["git"] = git
        return data

    allow_private_networks: bool = Field(
        default=False,
        description=(
            "Allow fetching resources from private/non-public network addresses. "
            "When disabled (default), only public IP addresses and hostnames are allowed."
        ),
    )

    log: LogConfig = Field(default_factory=LogConfig, description="Logging configuration")

    memory: MemoryConfig = Field(default_factory=MemoryConfig, description="Memory configuration")

    expiry: ExpiryConfig = Field(
        default_factory=ExpiryConfig,
        description="Distributed expiry scheduling configuration",
    )

    ttl: TTLConfig = RuntimeField(
        default_factory=TTLConfig,
        description=(
            "Directory TTL recycling policy. Default-off; requires the enabled Redis TTL runtime."
        ),
    )

    @model_validator(mode="after")
    def _validate_expiry_backend(self) -> "OpenVikingConfig":
        self._check_expiry_backend()
        return self

    def _check_expiry_backend(self) -> None:
        if self.uses_redis_expiry():
            self.expiry.validate_for_runtime()

    def uses_redis_session_expiry(self) -> bool:
        idle = self.memory.session_auto_commit
        return idle.enabled and idle.idle_backend == "redis"

    def uses_redis_compile_schedule(self) -> bool:
        return self.compile_api.scheduler_enabled

    def uses_redis_expiry(self) -> bool:
        """Whether any feature needs the distributed ExpiryScheduler."""
        return self.uses_redis_session_expiry() or self.uses_redis_compile_schedule()

    agent_evolution: AgentEvolutionConfig = RuntimeField(
        default_factory=AgentEvolutionConfig,
        description="Dynamic cluster default for Agent Evolution.",
    )

    oauth: OAuthConfig = Field(
        default_factory=OAuthConfig,
        description="OAuth 2.1 (MCP) configuration",
    )

    telemetry: "TelemetryConfig" = Field(
        default_factory=TelemetryConfig, description="Telemetry configuration"
    )
    prompts: PromptsConfig = Field(
        default_factory=PromptsConfig,
        description="Prompt template configuration",
    )

    ingest: IngestConfig = Field(
        default_factory=IngestConfig,
        description="Conversation-log ingest (openviking-server ingest) configuration",
    )

    runtime_config: RuntimeConfigSettings = Field(
        default_factory=RuntimeConfigSettings,
        description=(
            "Boot-level selection of the runtime config source. "
            "Read once at startup and never mutated by the dynamic config API."
        ),
    )

    model_config = {"arbitrary_types_allowed": True, "hide_input_in_errors": True}

    @classmethod
    def from_dict(cls, config: Dict[str, Any]) -> "OpenVikingConfig":
        """Create configuration from dictionary."""
        try:
            # Make a copy to avoid modifying the original
            config_copy = config.copy()

            parser_types = [
                "pdf",
                "code",
                "image",
                "audio",
                "video",
                "markdown",
                "anydoc",
                "html",
                "text",
                "directory",
                "feishu",
                "webfeed",
            ]

            warn_unknown_config_fields(
                data=config_copy,
                model=cls,
                extra_valid_fields={"server", "bot", "parsers"},
                logger=_get_config_logger(),
            )

            # Remove sections managed by other loaders (e.g. server config)
            config_copy.pop("server", None)
            config_copy.pop("bot", None)

            # Handle parser configurations from nested "parsers" section
            parser_configs = {}
            missing_parser_download_temp_dir = object()
            parser_download_temp_dir = missing_parser_download_temp_dir
            if "parsers" in config_copy:
                parser_configs = config_copy.pop("parsers")
                if parser_configs is None:
                    parser_configs = {}
                if not isinstance(parser_configs, dict):
                    raise ValueError("Invalid parsers config: 'parsers' section must be an object")
                parser_configs = parser_configs.copy()
                if "excel" in parser_configs:
                    parser_configs.pop("excel")
                    _get_config_logger().error(
                        "Config field 'parsers.excel' was removed and is ignored; "
                        "spreadsheet parsing now uses 'parsers.anydoc'."
                    )
                parser_download_temp_dir = parser_configs.pop(
                    "download_temp_dir", missing_parser_download_temp_dir
                )
                warn_unknown_fields(
                    data=parser_configs,
                    valid_fields=set(parser_types) | {"download_temp_dir"},
                    path_prefix="parsers",
                    logger=_get_config_logger(),
                )
            for parser_type in parser_types:
                if parser_type in config_copy:
                    parser_configs[parser_type] = config_copy.pop(parser_type)

            # Handle log configuration from nested "log" section
            log_config_data = None
            if "log" in config_copy:
                log_config_data = config_copy.pop("log")

            # Handle memory configuration from nested "memory" section
            memory_config_data = None
            if "memory" in config_copy:
                memory_config_data = config_copy.pop("memory")

            instance = cls(**config_copy)

            # Apply log configuration
            if log_config_data is not None:
                instance.log = LogConfig.from_dict(log_config_data)

            # Apply memory configuration
            if memory_config_data is not None:
                try:
                    instance.memory = MemoryConfig.from_dict(memory_config_data)
                except ValidationError as e:
                    raise ValueError(
                        format_validation_error(
                            root_model=MemoryConfig,
                            error=e,
                            path_prefix="memory",
                        )
                    ) from None
            instance._check_expiry_backend()

            # Apply parser configurations
            if parser_download_temp_dir is not missing_parser_download_temp_dir:
                instance.parser = ParserRuntimeConfig(download_temp_dir=parser_download_temp_dir)

            for parser_type in parser_types:
                if parser_type in parser_configs:
                    parser_data = parser_configs[parser_type]
                    config_class = getattr(instance, parser_type).__class__
                    if isinstance(parser_data, dict):
                        warn_unknown_fields(
                            data=parser_data,
                            valid_fields=set(config_class.__dataclass_fields__),
                            path_prefix=f"parsers.{parser_type}",
                            logger=_get_config_logger(),
                        )
                    setattr(instance, parser_type, config_class.from_dict(parser_data))

            # Check dimension consistency
            if (
                getattr(instance, "storage", None)
                and getattr(instance.storage, "vectordb", None)
                and getattr(instance, "embedding", None)
            ):
                instance.storage.vectordb.apply_resolved_dimension(instance.embedding.dimension)
                db_dim = instance.storage.vectordb.dimension
                emb_dim = instance.embedding.dimension
                if db_dim > 0 and emb_dim > 0 and db_dim != emb_dim:
                    logging.warning(
                        f"Dimension mismatch: VectorDB dimension is {db_dim}, "
                        f"but Embedding dimension is {emb_dim}. "
                        "This may cause errors during vector search."
                    )
            return instance
        except ValidationError as e:
            # The formatted error omits input values; do not reattach a raw
            # validation traceback which could expose nested credentials.
            raise ValueError(format_validation_error(root_model=cls, error=e)) from None

    def to_dict(self) -> Dict[str, Any]:
        """Convert configuration to dictionary."""
        return self.model_dump()

    def get_query_planner(self) -> VLMConfig:
        """Return the model config used for retrieval intent analysis and query planning."""
        if self.query_planner is not None and self.query_planner._has_any_config():
            return self.query_planner
        return self.vlm


class OpenVikingConfigSingleton:
    """Global singleton for OpenVikingConfig.

    Resolution chain for ov.conf:
      1. Explicit path passed to initialize()
      2. OPENVIKING_CONFIG_FILE environment variable
      3. ~/.openviking/ov.conf
      4. /etc/openviking/ov.conf
      5. Error with clear guidance

    ``_initializing`` prevents a same-thread deadlock: loading the config
    triggers pydantic validation which can import modules whose module-level
    ``get_logger()`` calls ``get_instance()`` again *before* the lock is
    released.  The flag is checked **before** ``_lock.acquire()`` so the
    re-entrant call raises immediately, letting ``_load_log_config()``
    fall back to default logging.
    """

    _instance: Optional[OpenVikingConfig] = None
    _lock: Lock = Lock()
    _initializing: bool = False
    _config_file: Optional[Path] = None
    _config_file_revision: Optional[str] = None
    _config_file_content: Optional[bytes] = None

    @classmethod
    def get_instance(cls) -> OpenVikingConfig:
        """Get the global singleton instance.

        Raises FileNotFoundError if no config file is found.
        Raises RuntimeError if called re-entrantly during initialization.
        """
        if cls._initializing:
            raise RuntimeError(
                "OpenVikingConfigSingleton is still initializing "
                "(re-entrant call detected, falling back to defaults)"
            )
        if cls._instance is None:
            with cls._lock:
                if cls._instance is None:
                    cls._initializing = True
                    try:
                        config_path = resolve_config_path(
                            None, OPENVIKING_CONFIG_ENV, DEFAULT_OV_CONF
                        )
                        if config_path is not None:
                            cls._instance = cls._load_from_file(str(config_path))
                        else:
                            default_path_user = DEFAULT_CONFIG_DIR / DEFAULT_OV_CONF
                            default_path_system = SYSTEM_CONFIG_DIR / DEFAULT_OV_CONF
                            raise FileNotFoundError(
                                f"OpenViking configuration file not found.\n"
                                f"Please create {default_path_user} or {default_path_system}, "
                                f"or set {OPENVIKING_CONFIG_ENV}.\n"
                                f"See: https://openviking.ai/docs"
                            )
                    finally:
                        cls._initializing = False
                    from openviking_cli.utils.logger import reconfigure_logging

                    reconfigure_logging()
        return cls._instance

    @classmethod
    def initialize(
        cls,
        config_dict: Optional[Dict[str, Any]] = None,
        config_path: Optional[str] = None,
    ) -> OpenVikingConfig:
        """Initialize the global singleton.

        Args:
            config_dict: Direct config dictionary (highest priority).
            config_path: Explicit path to ov.conf file.
        """
        with cls._lock:
            cls._initializing = True
            try:
                if config_dict is not None:
                    cls._instance = OpenVikingConfig.from_dict(config_dict)
                    cls._config_file = None
                    cls._config_file_revision = None
                    cls._config_file_content = None
                else:
                    path = resolve_config_path(config_path, OPENVIKING_CONFIG_ENV, DEFAULT_OV_CONF)
                    if path is not None:
                        cls._instance = cls._load_from_file(str(path))
                    else:
                        default_path_user = DEFAULT_CONFIG_DIR / DEFAULT_OV_CONF
                        default_path_system = SYSTEM_CONFIG_DIR / DEFAULT_OV_CONF
                        raise FileNotFoundError(
                            f"OpenViking configuration file not found.\n"
                            f"Please create {default_path_user} or {default_path_system}, "
                            f"or set {OPENVIKING_CONFIG_ENV}.\n"
                            f"See: https://openviking.ai/docs"
                        )
            finally:
                cls._initializing = False
        from openviking_cli.utils.logger import reconfigure_logging

        reconfigure_logging()
        return cls._instance

    @classmethod
    def _load_from_file(cls, config_file: str) -> "OpenVikingConfig":
        """Load configuration from JSON config file."""
        try:
            config_path = Path(config_file)
            if not config_path.exists():
                raise FileNotFoundError(f"Config file does not exist: {config_file}")

            data = config_path.read_bytes()
            raw = data.decode("utf-8-sig")

            # Expand $VAR and ${VAR} inside the JSON text (useful for container deployments).
            # Unset variables are left unchanged by expandvars().
            raw = os.path.expandvars(raw)
            config_data = json.loads(raw)

            config = OpenVikingConfig.from_dict(config_data)
            cls._config_file = config_path.resolve()
            cls._config_file_revision = hashlib.sha256(data).hexdigest()
            cls._config_file_content = data
            return config
        except json.JSONDecodeError as e:
            raise ValueError(f"Config file JSON format error: {e}")
        except ValueError:
            raise
        except Exception as e:
            raise RuntimeError(f"Failed to load config file: {e}")

    @classmethod
    def set_instance(cls, config: "OpenVikingConfig") -> None:
        """Atomically publish an already-built validated configuration."""
        with cls._lock:
            cls._instance = config

    @classmethod
    def reset_instance(cls) -> None:
        """Reset the singleton instance (mainly for testing)."""
        with cls._lock:
            cls._instance = None
            cls._config_file = None
            cls._config_file_revision = None
            cls._config_file_content = None

    @classmethod
    def get_config_file_content(cls) -> Optional[bytes]:
        """Return the exact startup bytes for recovery, even after subsequent saves."""
        return cls._config_file_content

    @classmethod
    def get_config_file_revision(cls) -> Optional[str]:
        """Return the revision of the complete file read at startup."""
        return cls._config_file_revision

    @classmethod
    def get_config_file(cls) -> Optional[Path]:
        """Return the actual startup file, not a newly resolved default path."""
        return cls._config_file


# Global convenience function
def get_openviking_config() -> OpenVikingConfig:
    """Get the global OpenVikingConfig instance."""
    return OpenVikingConfigSingleton.get_instance()


def set_openviking_config(config: OpenVikingConfig) -> None:
    """Atomically publish an already-built OpenVikingConfig."""
    OpenVikingConfigSingleton.set_instance(config)


def is_valid_openviking_config(config: OpenVikingConfig) -> bool:
    """
    Check if OpenVikingConfig is valid.

    Note: Most validation is now handled by Pydantic validators in individual config classes.
    This function only validates cross-config consistency.

    Raises:
        ValueError: If configuration is invalid with detailed error messages

    Returns:
        bool: True if configuration is valid
    """
    errors = []

    # Validate account identifier
    if not config.default_account or not config.default_account.strip():
        errors.append("Default account identifier cannot be empty")

    if errors:
        error_message = "Invalid OpenViking configuration:\n" + "\n".join(
            f"  - {e}" for e in errors
        )
        raise ValueError(error_message)

    return True


def initialize_openviking_config(
    user: Optional[UserIdentifier] = None,
    path: Optional[str] = None,
) -> OpenVikingConfig:
    """
    Initialize OpenViking configuration with provided parameters.

    Loads ov.conf from the standard resolution chain, then applies
    parameter overrides.

    Args:
        user: UserIdentifier for session management
        path: Optional local workspace override for the service

    Returns:
        Configured OpenVikingConfig instance

    Raises:
        ValueError: If the resulting configuration is invalid
        FileNotFoundError: If no config file is found
    """
    config = get_openviking_config()

    if user:
        # Set user if provided, like a email address or a account_id
        config.default_account = user._account_id
        config.default_user = user._user_id

    # Configure storage based on provided parameters
    if path:
        # Explicit local workspace override
        config.storage.agfs.backend = config.storage.agfs.backend or "local"
        config.storage.vectordb.backend = config.storage.vectordb.backend or "local"
        # Resolve and update workspace + dependent paths (model_validator won't
        # re-run on attribute assignment, so sync agfs.path / vectordb.path here).
        workspace_path = Path(path).expanduser().resolve()
        workspace_path.mkdir(parents=True, exist_ok=True)
        resolved = str(workspace_path)
        config.storage.workspace = resolved
        config.storage.agfs.path = resolved
        config.storage.vectordb.path = resolved

    config.storage.vectordb.apply_resolved_dimension(config.embedding.dimension)

    # Validate configuration
    if not is_valid_openviking_config(config):
        raise ValueError("Invalid OpenViking configuration")

    return config