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
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