Skip to content

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

12.5 KB
Raw Blame
# 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}"