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
from __future__ import annotations
import base64
import json
import os
from dataclasses import dataclass
from difflib import get_close_matches
from pathlib import Path
from typing import Optional
OPENVIKING_CLI_CONFIG_ENV = "OPENVIKING_CLI_CONFIG_FILE"
DEFAULT_OVCLI_CONF = Path.home() / ".openviking" / "ovcli.conf"
@dataclass(frozen=True)
class ClientConfig:
url: str
api_key: Optional[str]
account: Optional[str]
user: Optional[str]
actor_peer_id: Optional[str]
timeout: float
profile_enabled: bool
extra_headers: dict[str, str]
gateway_token: Optional[str]
upload_mode: Optional[str]
# LDAP authentication (None when auth mode is not LDAP)
auth_mode: Optional[str]
ldap_username: Optional[str]
ldap_password: Optional[str]
# OIDC authentication (None when auth mode is not OIDC)
oidc_token: Optional[str]
@dataclass(frozen=True)
class OVCLIConfig:
url: Optional[str]
api_key: Optional[str]
account: Optional[str]
user: Optional[str]
actor_peer_id: Optional[str]
agent_id: Optional[str]
timeout: float
profile: bool
extra_headers: dict[str, str]
gateway_token: Optional[str]
upload_mode: Optional[str]
output: Optional[str]
# LDAP authentication
auth_mode: Optional[str]
ldap_username: Optional[str]
ldap_password: Optional[str]
# OIDC authentication
oidc_token: Optional[str]
def _resolve_ovcli_config_path() -> Optional[Path]:
config_path = os.getenv(OPENVIKING_CLI_CONFIG_ENV)
if config_path:
return Path(config_path).expanduser()
if DEFAULT_OVCLI_CONF.exists():
return DEFAULT_OVCLI_CONF
return None
def _require_mapping(value: object, *, path: str) -> dict:
if not isinstance(value, dict):
raise ValueError(f"Invalid value for '{path}': expected object")
return value
def _optional_string(value: object, *, path: str) -> Optional[str]:
if value is None:
return None
if not isinstance(value, str):
raise ValueError(f"Invalid value for '{path}': expected string")
return value
def _optional_bool(value: object, *, path: str) -> Optional[bool]:
if value is None:
return None
if not isinstance(value, bool):
raise ValueError(f"Invalid value for '{path}': expected boolean")
return value
def _optional_float(value: object, *, path: str) -> Optional[float]:
if value is None:
return None
if isinstance(value, bool):
raise ValueError(f"Invalid value for '{path}': expected number")
if not isinstance(value, (int, float)):
raise ValueError(f"Invalid value for '{path}': expected number")
return float(value)
def _parse_extra_headers(value: object, *, path: str) -> dict[str, str]:
if value is None:
return {}
data = _require_mapping(value, path=path)
parsed: dict[str, str] = {}
for key, header_value in data.items():
if not isinstance(key, str):
raise ValueError(f"Invalid value for '{path}': expected string keys")
if not isinstance(header_value, str):
raise ValueError(f"Invalid value for '{path}.{key}': expected string")
parsed[key] = header_value
return parsed
def _unknown_field_error(path: str, key: str, allowed_keys: set[str]) -> ValueError:
message = f"Unknown field '{path}.{key}'"
matches = get_close_matches(key, sorted(allowed_keys), n=1, cutoff=0.6)
if matches:
message = f"{message}. Did you mean '{path}.{matches[0]}'?"
return ValueError(message)
def load_ovcli_config(config_path: Optional[str] = None) -> Optional[OVCLIConfig]:
path = Path(config_path).expanduser() if config_path else _resolve_ovcli_config_path()
if path is None or not path.exists():
return None
try:
raw = json.loads(path.read_text())
except json.JSONDecodeError as exc:
raise ValueError(f"Invalid CLI config in {path}: {exc.msg}") from exc
try:
data = _require_mapping(raw, path="ovcli")
# ovcli.conf is written by the Rust CLI (crates/ov_cli/src/config.rs).
# Accept every field it can write, including the ones the SDK does not
# read, plus the `plugin` section the harness memory plugins own.
allowed_keys = {
"url",
"api_key",
"account",
"user",
"actor_peer_id",
"agent_id",
"timeout",
"profile",
"upload",
"extra_headers",
"extra_header",
"output",
"echo_command",
"show_progress",
"verbose",
"root_api_key",
"gateway_token",
"plugin",
# Authentication
"auth_mode",
# LDAP
"ldap_username",
"ldap_password",
# OIDC
"oidc_token",
}
unknown_keys = sorted(set(data) - allowed_keys)
if unknown_keys:
raise _unknown_field_error("ovcli", unknown_keys[0], allowed_keys)
extra_header_alias = data.get("extra_header")
extra_headers_value = data.get("extra_headers", extra_header_alias)
upload_data = data.get("upload")
upload_mode = None
if upload_data is not None:
upload = _require_mapping(upload_data, path="ovcli.upload")
allowed_upload_keys = {"mode", "ignore_dirs", "include", "exclude"}
unknown_upload_keys = sorted(set(upload) - allowed_upload_keys)
if unknown_upload_keys:
raise _unknown_field_error(
"ovcli.upload", unknown_upload_keys[0], allowed_upload_keys
)
upload_mode = _optional_string(upload.get("mode"), path="ovcli.upload.mode")
actor_peer_id = _optional_string(data.get("actor_peer_id"), path="ovcli.actor_peer_id")
agent_id = _optional_string(data.get("agent_id"), path="ovcli.agent_id")
if actor_peer_id is not None and agent_id is not None:
raise ValueError("actor_peer_id cannot be used with agent_id")
timeout = _optional_float(data.get("timeout"), path="ovcli.timeout")
profile = _optional_bool(data.get("profile"), path="ovcli.profile")
# Parse LDAP config
auth_mode = _optional_string(data.get("auth_mode"), path="ovcli.auth_mode")
ldap_username = _optional_string(
data.get("ldap_username"), path="ovcli.ldap_username"
)
ldap_password = _optional_string(
data.get("ldap_password"), path="ovcli.ldap_password"
)
oidc_token = _optional_string(
data.get("oidc_token"), path="ovcli.oidc_token"
)
return OVCLIConfig(
url=_optional_string(data.get("url"), path="ovcli.url"),
api_key=_optional_string(data.get("api_key"), path="ovcli.api_key"),
account=_optional_string(data.get("account"), path="ovcli.account"),
user=_optional_string(data.get("user"), path="ovcli.user"),
actor_peer_id=actor_peer_id,
agent_id=agent_id,
timeout=60.0 if timeout is None else timeout,
profile=False if profile is None else profile,
extra_headers=_parse_extra_headers(extra_headers_value, path="ovcli.extra_headers"),
gateway_token=_optional_string(data.get("gateway_token"), path="ovcli.gateway_token"),
upload_mode=upload_mode,
output=_optional_string(data.get("output"), path="ovcli.output"),
auth_mode=auth_mode,
ldap_username=ldap_username,
ldap_password=ldap_password,
oidc_token=oidc_token,
)
except ValueError as exc:
raise ValueError(f"Invalid CLI config in {path}: {exc}") from exc
def _resolve_env_or_config(env_var: str, explicit: Optional[str], config_value: Optional[str]) -> Optional[str]:
"""Helper to resolve value: explicit arg > env var > config file."""
if explicit is not None:
return explicit
env_value = os.getenv(env_var)
if env_value is not None:
return env_value
return config_value
def resolve_client_config(
*,
url: Optional[str] = None,
api_key: Optional[str] = None,
account: Optional[str] = None,
user: Optional[str] = None,
actor_peer_id: Optional[str] = None,
timeout: Optional[float] = None,
extra_headers: Optional[dict[str, str]] = None,
profile_enabled: Optional[bool] = None,
upload_mode: Optional[str] = None,
# LDAP parameters
auth_mode: Optional[str] = None,
ldap_username: Optional[str] = None,
ldap_password: Optional[str] = None,
# OIDC parameters
oidc_token: Optional[str] = None,
) -> ClientConfig:
cli_config = load_ovcli_config()
# Resolve LDAP config (explicit arg > env var > config file)
resolved_auth_mode = _resolve_env_or_config(
"OPENVIKING_AUTH_MODE", auth_mode,
cli_config.auth_mode if cli_config else None
)
resolved_ldap_username = _resolve_env_or_config(
"OPENVIKING_USERNAME", ldap_username,
cli_config.ldap_username if cli_config else None
)
resolved_ldap_password = _resolve_env_or_config(
"OPENVIKING_PASSWORD", ldap_password,
cli_config.ldap_password if cli_config else None
)
# OIDC token: explicit arg > env var > config file.
# When auth_mode is oidc and no token is resolvable, leave it None so
# callers can choose to fall back to an api_key that looks like a JWT.
resolved_oidc_token = _resolve_env_or_config(
"OPENVIKING_OIDC_TOKEN", oidc_token,
cli_config.oidc_token if cli_config else None
)
resolved_url = url or os.getenv("OPENVIKING_URL") or (cli_config.url if cli_config else None)
resolved_api_key = (
api_key or os.getenv("OPENVIKING_API_KEY") or (cli_config.api_key if cli_config else None)
)
resolved_account = (
account or os.getenv("OPENVIKING_ACCOUNT") or (cli_config.account if cli_config else None)
)
resolved_user = (
user or os.getenv("OPENVIKING_USER") or (cli_config.user if cli_config else None)
)
resolved_actor_peer_id = (
actor_peer_id
or os.getenv("OPENVIKING_ACTOR_PEER_ID")
or (cli_config.actor_peer_id if cli_config else None)
)
if resolved_actor_peer_id is None and cli_config is not None and cli_config.agent_id:
resolved_actor_peer_id = cli_config.agent_id
if timeout is not None:
resolved_timeout = timeout
else:
env_timeout = os.getenv("OPENVIKING_TIMEOUT")
if env_timeout:
resolved_timeout = float(env_timeout)
elif cli_config is not None:
resolved_timeout = cli_config.timeout
else:
resolved_timeout = 60.0
resolved_profile_enabled = bool(profile_enabled)
if profile_enabled is None and cli_config is not None:
resolved_profile_enabled = cli_config.profile
resolved_extra_headers = dict(extra_headers) if extra_headers is not None else {}
if extra_headers is None and cli_config is not None:
resolved_extra_headers = dict(cli_config.extra_headers)
resolved_gateway_token = None
if (
cli_config is not None
and cli_config.url
and resolved_url
and cli_config.url.rstrip("/") == resolved_url.rstrip("/")
):
resolved_gateway_token = cli_config.gateway_token
resolved_upload_mode = upload_mode
if resolved_upload_mode is None and cli_config is not None:
resolved_upload_mode = cli_config.upload_mode
if not resolved_url:
raise ValueError(
"url is required. Pass it explicitly, set OPENVIKING_URL, or configure ovcli.conf."
)
return ClientConfig(
url=resolved_url.rstrip("/"),
api_key=resolved_api_key,
account=resolved_account,
user=resolved_user,
actor_peer_id=resolved_actor_peer_id,
timeout=resolved_timeout,
profile_enabled=resolved_profile_enabled,
extra_headers=resolved_extra_headers,
gateway_token=resolved_gateway_token,
upload_mode=resolved_upload_mode,
auth_mode=resolved_auth_mode,
ldap_username=resolved_ldap_username,
ldap_password=resolved_ldap_password,
oidc_token=resolved_oidc_token,
)
def get_basic_auth_header(username: str, password: str) -> str:
"""生成 HTTP Basic Auth header 值."""
credentials = f"{username}:{password}".encode("utf-8")
encoded = base64.b64encode(credentials).decode("ascii")
return f"Basic {encoded}"