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
"""openviking-server init - interactive setup wizard for OpenViking.
Guides users through model selection and configuration, with a focus on
local deployment via Ollama for macOS / Apple Silicon beginners.
"""
from __future__ import annotations
import importlib
import json
import os
import re
import secrets
import select
import shutil
import subprocess
import sys
import tempfile
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from urllib.parse import urlsplit
from openviking_cli.utils.config.consts import DEFAULT_CONFIG_DIR, OPENVIKING_CONFIG_ENV
from openviking_cli.utils.ollama import (
check_ollama_running,
get_ollama_models,
install_ollama,
is_model_available,
is_ollama_installed,
ollama_pull_model,
start_ollama,
)
_DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
_DEFAULT_KIMI_BASE_URL = "https://api.kimi.com/coding"
_DEFAULT_GLM_BASE_URL = "https://api.z.ai/api/coding/paas/v4"
_DEFAULT_CODEX_MODEL = "gpt-5.6-terra"
_DEFAULT_KIMI_MODEL = "kimi-code"
_DEFAULT_GLM_MODEL = "glm-4.6v"
# Sentinel returned by flows that hand the user off to manual config editing;
# distinguishes "handled elsewhere" from "cancelled" (None).
_CUSTOM_SETUP = object()
# Sentinel for "user chose to skip the VLM" (embedding-only setup).
_SKIP_VLM = object()
# Sentinel for "user navigated back to the previous step" (← key / [0] Back).
_GO_BACK = object()
# Free-text equivalent of ← / [0] Back inside prompts that take typed input.
_BACK_TOKEN = "!back"
# rich ships with typer (a core dependency); degrade gracefully without it.
try:
from rich.console import Console as _RichConsole
from rich.panel import Panel as _RichPanel
_console: Any = _RichConsole(highlight=False)
except ImportError: # pragma: no cover
_console = None
# ---------------------------------------------------------------------------
# ANSI helpers (same pattern as doctor.py)
# ---------------------------------------------------------------------------
_USE_COLOR = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
def _green(t: str) -> str:
return f"\033[32m{t}\033[0m" if _USE_COLOR else t
def _red(t: str) -> str:
return f"\033[31m{t}\033[0m" if _USE_COLOR else t
def _yellow(t: str) -> str:
return f"\033[33m{t}\033[0m" if _USE_COLOR else t
def _dim(t: str) -> str:
return f"\033[2m{t}\033[0m" if _USE_COLOR else t
def _bold(t: str) -> str:
return f"\033[1m{t}\033[0m" if _USE_COLOR else t
def _cyan(t: str) -> str:
return f"\033[36m{t}\033[0m" if _USE_COLOR else t
# ---------------------------------------------------------------------------
# Interactive prompt helpers (stdlib only)
# ---------------------------------------------------------------------------
def _prompt_choice(
prompt: str,
options: list[tuple[str, str]],
default: int = 1,
*,
allow_back: bool = False,
) -> int:
"""Display a selectable option list and return the 1-based selection index.
On an interactive TTY this renders an arrow-key menu (↑/↓ or j/k to move,
digits to jump, Enter or → to confirm, ← to go back when *allow_back* is
set). Anywhere else (pipes, tests, dumb terminals) it falls back to the
classic numbered prompt, where ``0`` means back.
Returns 0 when *allow_back* is set and the user navigated back.
"""
if _stdin_stdout_tty() and os.environ.get("TERM", "") != "dumb":
try:
import termios
except ImportError:
return _prompt_choice_numbered(prompt, options, default, allow_back=allow_back)
try:
return _prompt_choice_interactive(prompt, options, default, allow_back=allow_back)
except (OSError, termios.error):
pass
return _prompt_choice_numbered(prompt, options, default, allow_back=allow_back)
def _prompt_choice_numbered(
prompt: str,
options: list[tuple[str, str]],
default: int = 1,
*,
allow_back: bool = False,
) -> int:
"""Numbered fallback selector (non-TTY, pipes, tests)."""
print(f"\n {_bold(prompt)}\n")
for i, (label, desc) in enumerate(options, 1):
marker = " "
line = f" {marker}[{i}] {label}"
if desc:
line += f" {_dim(desc)}"
print(line)
if allow_back:
print(f" [0] Back {_dim('(previous step)')}")
while True:
try:
raw = input(f"\n Select [{default}]: ").strip()
except (EOFError, OSError):
return default
if not raw:
return default
try:
choice = int(raw)
if allow_back and choice == 0:
return 0
if 1 <= choice <= len(options):
return choice
except ValueError:
pass
low = "0" if allow_back else "1"
print(f" {_red('Please enter a number between ' + low + ' and ' + str(len(options)))}")
def _read_menu_key(fd: int) -> str:
"""Read one key press from *fd*, decoding arrow-key escape sequences.
Reads at the file-descriptor level (``os.read``) — ``sys.stdin`` is
buffered and its readahead would consume escape-sequence bytes behind
``select``'s back.
"""
data = os.read(fd, 1)
if data != b"\x1b":
return data.decode("utf-8", errors="ignore")
if not select.select([fd], [], [], 0.05)[0]:
return "\x1b"
if os.read(fd, 1) != b"[":
return "\x1b"
if not select.select([fd], [], [], 0.05)[0]:
return "\x1b"
return "\x1b[" + os.read(fd, 1).decode("utf-8", errors="ignore")
def _prompt_choice_interactive(
prompt: str,
options: list[tuple[str, str]],
default: int = 1,
*,
allow_back: bool = False,
) -> int:
"""Arrow-key menu: ↑/↓/j/k move, digits jump, Enter/→ confirm, ← back."""
import termios
import tty
n = len(options)
idx = max(0, min(n - 1, default - 1))
out = sys.stdout
went_back = False
def render(first: bool) -> None:
if not first:
out.write(f"\x1b[{n}A")
for i, (label, desc) in enumerate(options):
out.write("\x1b[2K")
if i == idx:
line = f" \x1b[1;36m❯ {label}\x1b[0m"
else:
line = f" {label}"
if desc:
line += f" \x1b[2m{desc}\x1b[0m"
out.write(line + "\n")
out.flush()
hint = "↑/↓ move · enter select"
if allow_back:
hint += " · ← back"
print(f"\n {_bold(prompt)} {_dim(hint)}\n")
render(True)
fd = sys.stdin.fileno()
old_attrs = termios.tcgetattr(fd)
while True:
tty.setraw(fd)
try:
key = _read_menu_key(fd)
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old_attrs)
if key in ("\r", "\n", "\x04", "\x1b[C"): # Enter / Ctrl-D / → confirm
break
if key == "\x03":
raise KeyboardInterrupt
if allow_back and key == "\x1b[D": # ← back to previous step
went_back = True
break
if key in ("\x1b[A", "k"):
idx = (idx - 1) % n
elif key in ("\x1b[B", "j", "\t"):
idx = (idx + 1) % n
elif key.isdigit():
jump = 9 if key == "0" else int(key) - 1
if jump < n:
idx = jump
render(False)
# Collapse the menu into a single confirmation line.
out.write(f"\x1b[{n}A\x1b[0J")
if went_back:
out.write(" \x1b[2m← back\x1b[0m\n")
out.flush()
return 0
out.write(f" \x1b[1;36m❯\x1b[0m {options[idx][0]}\n")
out.flush()
return idx + 1
def _mask_secret(value: str, prefix: int = 7, suffix: int = 4) -> str:
"""Mask a secret string, showing only the first ``prefix`` and last ``suffix`` chars."""
if not value:
return ""
if len(value) <= prefix + suffix:
return "*" * len(value)
return f"{value[:prefix]}{'*' * (len(value) - prefix - suffix)}{value[-suffix:]}"
def _masked_input(prompt: str) -> str:
"""Read a line of input, echoing ``*`` per character; on submit, rewrite
the line to show ``prompt + _mask_secret(value)`` (prefix 7 + suffix 4).
Falls back to plain ``input()`` when stdin/stdout aren't TTYs (tests,
pipes) and to ``getpass.getpass`` (no echo at all) on platforms
without ``termios`` (Windows).
"""
import sys
if not (sys.stdin.isatty() and sys.stdout.isatty()):
return input(prompt)
try:
import termios
import tty
except ImportError:
import getpass
return getpass.getpass(prompt)
sys.stdout.write(prompt)
sys.stdout.flush()
fd = sys.stdin.fileno()
old_attrs = termios.tcgetattr(fd)
chars: list[str] = []
try:
tty.setraw(fd)
while True:
ch = sys.stdin.read(1)
if ch in ("\r", "\n"):
break
if ch == "\x03": # Ctrl-C
raise KeyboardInterrupt
if ch == "\x04": # Ctrl-D / EOF
if not chars:
raise EOFError
break
if ch in ("\x7f", "\b"): # Backspace / DEL
if chars:
chars.pop()
sys.stdout.write("\b \b")
sys.stdout.flush()
continue
if ch < " ": # Other control chars — ignore
continue
chars.append(ch)
sys.stdout.write("*")
sys.stdout.flush()
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old_attrs)
value = "".join(chars)
# Rewrite the line: \r → clear → prompt + masked preview + \n.
sys.stdout.write("\r\033[2K" + prompt + _mask_secret(value) + "\n")
sys.stdout.flush()
return value
def _prompt_required_input(
prompt: str, default: str | None = None, *, mask: bool = False, allow_back: bool = False
) -> str | object:
"""Prompt for a required free-text value. When ``mask`` is True, echo ``*``
per char. With ``allow_back``, typing ``!back`` returns ``_GO_BACK``."""
reader = _masked_input if mask else input
while True:
try:
prompt_text = f" {prompt} [{default}]: " if default is not None else f" {prompt}: "
raw = reader(prompt_text).strip()
except (EOFError, OSError):
return default or ""
if allow_back and raw == _BACK_TOKEN:
return _GO_BACK
if not raw and default is not None:
return default
if raw:
return raw
print(f" {_red(prompt + ' is required')}")
def _prompt_api_key(prompt: str = "API Key", *, allow_back: bool = False) -> str | object:
"""Prompt for an API key with inline masked echo (no extra confirmation line)."""
return _prompt_required_input(prompt, mask=True, allow_back=allow_back)
def _stdin_stdout_tty() -> bool:
"""True when both stdin and stdout are interactive TTYs."""
try:
return sys.stdin.isatty() and sys.stdout.isatty()
except (AttributeError, ValueError):
return False
# Environment variables that commonly carry each provider's API key, keyed by
# the internal provider string (BytePlus shares "volcengine").
_PROVIDER_ENV_KEYS: dict[str, list[str]] = {
"volcengine": ["ARK_API_KEY"],
"openai": ["OPENAI_API_KEY"],
"kimi": ["KIMI_API_KEY", "MOONSHOT_API_KEY"],
"glm": ["GLM_API_KEY", "ZHIPUAI_API_KEY"],
}
def _prompt_api_key_with_env(
env_vars: list[str] | None, prompt: str = "API Key", *, allow_back: bool = False
) -> str | object:
"""Prompt for an API key, offering any matching environment variable first.
Only engages the env-var shortcut on interactive TTYs so scripted or
piped runs keep the plain prompt behavior.
"""
if env_vars and _stdin_stdout_tty():
for var in env_vars:
value = os.environ.get(var, "").strip()
if value and _prompt_confirm(f"Found ${var} ({_mask_secret(value)}). Use it?"):
return value
return _prompt_api_key(prompt, allow_back=allow_back)
def _prompt_required_int(
prompt: str, default: int | None = None, *, allow_back: bool = False
) -> int | None | object:
"""Prompt for a required integer value. With ``allow_back``, typing
``!back`` returns ``_GO_BACK``."""
while True:
try:
prompt_text = f" {prompt} [{default}]: " if default is not None else f" {prompt}: "
raw = input(prompt_text).strip()
except (EOFError, OSError):
return default
if allow_back and raw == _BACK_TOKEN:
return _GO_BACK
if not raw:
if default is not None:
return default
print(f" {_red(prompt + ' is required')}")
continue
try:
return int(raw)
except ValueError:
print(f" {_red('Please enter a valid integer')}")
def _prompt_confirm(prompt: str, default: bool = True) -> bool:
"""Yes/no confirmation prompt."""
hint = "Y/n" if default else "y/N"
try:
raw = input(f" {prompt} [{hint}]: ").strip().lower()
except (EOFError, OSError):
return default
if not raw:
return default
return raw in ("y", "yes")
def _rule(title: str) -> None:
"""Print a section rule (rich when available, plain bold header otherwise)."""
if _console is not None:
_console.print()
_console.rule(f"[bold cyan]{title}[/bold cyan]", style="dim cyan")
else:
print(f"\n {_bold(title)}")
def _print_banner() -> None:
"""Print the wizard banner."""
if _console is not None:
_console.print()
_console.print(
_RichPanel.fit(
"[bold cyan]OpenViking[/bold cyan] [bold]Setup[/bold]\n"
"[dim]Context database for AI agents — data in, context out[/dim]",
border_style="cyan",
padding=(0, 2),
)
)
else:
print(f"\n {_bold('OpenViking Setup')}")
print(f" {'=' * 16}")
# ---------------------------------------------------------------------------
# System info
# ---------------------------------------------------------------------------
def _get_system_ram_gb() -> int:
"""Get total system RAM in GB."""
try:
pages = os.sysconf("SC_PHYS_PAGES")
page_size = os.sysconf("SC_PAGE_SIZE")
return (pages * page_size) // (1024**3)
except (ValueError, OSError, AttributeError):
pass
# Windows fallback
try:
import ctypes
kernel32 = ctypes.windll.kernel32 # type: ignore[attr-defined]
class MEMORYSTATUSEX(ctypes.Structure):
_fields_ = [
("dwLength", ctypes.c_ulong),
("dwMemoryLoad", ctypes.c_ulong),
("ullTotalPhys", ctypes.c_ulonglong),
("ullAvailPhys", ctypes.c_ulonglong),
("ullTotalPageFile", ctypes.c_ulonglong),
("ullAvailPageFile", ctypes.c_ulonglong),
("ullTotalVirtual", ctypes.c_ulonglong),
("ullAvailVirtual", ctypes.c_ulonglong),
("ullAvailExtendedVirtual", ctypes.c_ulonglong),
]
stat = MEMORYSTATUSEX()
stat.dwLength = ctypes.sizeof(stat)
kernel32.GlobalMemoryStatusEx(ctypes.byref(stat))
return stat.ullTotalPhys // (1024**3)
except Exception:
return 0
def _parse_size_gb(size_hint: str) -> float:
"""Parse a human size hint like ``~4.7 GB`` or ``~639 MB`` into GB."""
match = re.search(r"([\d.]+)\s*(GB|MB)", size_hint, re.IGNORECASE)
if not match:
return 0.0
value = float(match.group(1))
return value / 1024 if match.group(2).upper() == "MB" else value
def _check_disk_before_pull(required_gb: float) -> bool:
"""Return True when there is enough free disk for a download of *required_gb*.
When space looks too tight (less than the download plus a 5 GB margin),
warn and let the user decide.
"""
if required_gb <= 0:
return True
try:
free_gb = shutil.disk_usage(Path.home()).free / (1024**3)
except OSError:
return True
if free_gb >= required_gb + 5:
return True
print(
f" {_yellow(f'Low disk space: {free_gb:.0f} GB free, download needs ~{required_gb:.0f} GB.')}"
)
return _prompt_confirm("Continue anyway?", default=False)
# ---------------------------------------------------------------------------
# Ollama interaction (delegates to openviking_cli.utils.ollama)
# ---------------------------------------------------------------------------
def _ensure_ollama() -> bool:
"""Make sure Ollama is installed and running (interactive). Returns True if ready."""
print("\n Checking Ollama...", end=" ", flush=True)
if is_ollama_installed():
if check_ollama_running():
print(_green("running at localhost:11434"))
return True
print(_yellow("installed but not running"))
print(f" {_dim('Starting Ollama...')}", end=" ", flush=True)
result = start_ollama()
if result.success:
print(_green("ready"))
else:
msg = result.stderr_output or result.message
print(_yellow(f"failed ({msg})"))
return result.success
# Not installed
print(_yellow("not installed"))
if not _prompt_confirm("Install Ollama now?"):
print(f"\n {_dim('Manual install: https://ollama.com/download')}")
return False
print()
if not install_ollama():
print(f" {_red('Installation failed.')}")
print(f" {_dim('Try manually: https://ollama.com/download')}")
return False
print(f" {_green('OK')} Ollama installed")
print(f" {_dim('Starting Ollama...')}", end=" ", flush=True)
result = start_ollama()
if result.success:
print(_green("ready"))
else:
msg = result.stderr_output or result.message
print(_yellow(f"failed ({msg})"))
return result.success
def _ensure_model_pulled(
model: str,
size_hint: str,
ollama_running: bool,
available_models: list[str],
*,
ask: bool = True,
) -> None:
"""Pull *model* via Ollama when missing.
With ``ask=True`` the user confirms each pull (with a disk-space check);
``ask=False`` is for flows where the user already approved the batch.
"""
if not ollama_running or is_model_available(model, available_models):
return
if ask:
if not _prompt_confirm(f"'{model}' not found locally. Pull now? ({size_hint})"):
return
if not _check_disk_before_pull(_parse_size_gb(size_hint)):
return
print()
if not ollama_pull_model(model):
print(f" {_yellow('Pull failed. You can pull it later: ollama pull ' + model)}")
else:
print(f" {_green('OK')} {model} pulled successfully")
def _ensure_codex_auth() -> bool:
import importlib
importlib.import_module("openviking.models.vlm")
codex_auth = importlib.import_module("openviking.models.vlm.backends.codex_auth")
print("\n Checking Codex OAuth...", end=" ", flush=True)
try:
creds = codex_auth.resolve_codex_runtime_credentials(refresh_if_expiring=False)
source = creds.get("source", "unknown")
print(_green(f"ready via {source}"))
return True
except Exception:
print(_yellow("not ready"))
status = codex_auth.get_codex_auth_status()
bootstrap_path = status.get("bootstrap_path")
if status.get("bootstrap_available") and bootstrap_path:
if _prompt_confirm(f"Import existing Codex CLI auth from {bootstrap_path}?"):
try:
path = codex_auth.bootstrap_codex_auth()
except codex_auth.CodexAuthError as exc:
print(f" {_yellow(str(exc))}")
else:
if path is not None:
print(f" {_green('OK')} Imported Codex OAuth into {path}")
return True
if _prompt_confirm("Sign in to Codex now?"):
try:
path = codex_auth.login_codex_with_device_code()
except codex_auth.CodexAuthError as exc:
print(f" {_yellow(str(exc))}")
else:
print(f" {_green('OK')} Codex OAuth stored in {path}")
return True
print(
f" {_dim('You can finish setup now and re-run `openviking-server init` later to complete Codex sign-in.')}"
)
return False
# ---------------------------------------------------------------------------
# Model presets
# ---------------------------------------------------------------------------
@dataclass
class EmbeddingPreset:
label: str
model: str # Ollama model name
dimension: int
size_hint: str
min_ram_gb: int # Minimum recommended RAM
@dataclass
class VLMPreset:
label: str
ollama_model: str # For ollama pull
litellm_model: str # For config: "ollama/xxx"
size_hint: str
min_ram_gb: int # Minimum recommended RAM
@dataclass
class QueryPlannerPreset:
label: str
ollama_model: str # For ollama pull
litellm_model: str # For config: "ollama/xxx"
size_hint: str
EMBEDDING_PRESETS: list[EmbeddingPreset] = [
EmbeddingPreset("Qwen3-Embedding 0.6B", "qwen3-embedding:0.6b", 1024, "~639 MB", 4),
EmbeddingPreset("Qwen3-Embedding 4B", "qwen3-embedding:4b", 1024, "~2.5 GB", 8),
EmbeddingPreset("Qwen3-Embedding 8B", "qwen3-embedding:8b", 1024, "~4.7 GB", 16),
EmbeddingPreset("EmbeddingGemma 300M", "embeddinggemma:300m", 768, "~622 MB", 4),
]
VLM_PRESETS: list[VLMPreset] = [
VLMPreset("Qwen 3.5 4B", "qwen3.5:4b", "ollama/qwen3.5:4b", "~3.4 GB", 8),
VLMPreset("Qwen 3.5 9B", "qwen3.5:9b", "ollama/qwen3.5:9b", "~6.6 GB", 16),
VLMPreset("Qwen 3.6 27B", "qwen3.6:27b", "ollama/qwen3.6:27b", "~17 GB, 256K ctx", 32),
VLMPreset("Qwen 3.6 35B", "qwen3.6:35b", "ollama/qwen3.6:35b", "~24 GB, 256K ctx", 48),
VLMPreset("Qwen 3.5 122B", "qwen3.5:122b", "ollama/qwen3.5:122b", "~81 GB", 128),
VLMPreset("Gemma 4 E2B", "gemma4:e2b", "ollama/gemma4:e2b", "~7.2 GB", 16),
VLMPreset("Gemma 4 E4B", "gemma4:e4b", "ollama/gemma4:e4b", "~9.6 GB", 16),
VLMPreset("Gemma 4 26B", "gemma4:26b", "ollama/gemma4:26b", "~18 GB", 32),
VLMPreset("Gemma 4 31B", "gemma4:31b", "ollama/gemma4:31b", "~20 GB", 48),
]
# Lightweight query-planner models (intent analysis / query planning). All run
# locally via Ollama. Runtime prompt selection is handled by the retrieval
# intent analyzer based on the configured model name.
QUERY_PLANNER_PRESETS: list[QueryPlannerPreset] = [
QueryPlannerPreset(
"ov_intent_analysis_sft v7_q8",
"guoxuter/ov_intent_analysis_sft:v7_q8",
"ollama/guoxuter/ov_intent_analysis_sft:v7_q8",
"~0.8B, recommended",
),
QueryPlannerPreset(
"ov_intent_analysis_sft v4_q8",
"guoxuter/ov_intent_analysis_sft:v4_q8",
"ollama/guoxuter/ov_intent_analysis_sft:v4_q8",
"~0.8B",
),
]
# Approximate download size of the q8 query-planner models (size_hint above
# carries the parameter count, not the artifact size).
_QUERY_PLANNER_DOWNLOAD_GB = 0.9
# Recommended defaults indexed by RAM tier. qwen3.5:4b is the smallest VLM we
# recommend — smaller models fail OV's memory extraction (they copy the prompt's
# few-shot examples into fabricated memories), so there is no sub-4B tier.
_RAM_TIERS: list[tuple[int, int, int]] = [
# (max_ram_gb, embedding_preset_index, vlm_preset_index)
(8, 0, 0), # ≤8 GB: qwen3-embedding:0.6b + qwen3.5:4b
(16, 0, 0), # 8-16 GB: qwen3-embedding:0.6b + qwen3.5:4b
(32, 2, 1), # 16-32 GB: qwen3-embedding:8b + qwen3.5:9b
(64, 2, 6), # 32-64 GB: qwen3-embedding:8b + gemma4:e4b
]
_RAM_DEFAULT_EMBED = 2 # ≥64 GB: qwen3-embedding:8b
_RAM_DEFAULT_VLM = 2 # ≥64 GB: qwen3.6:27b
def _get_recommended_indices(ram_gb: int) -> tuple[int, int]:
"""Return (embedding_index, vlm_index) for the RAM tier (0-based)."""
for max_ram, emb_idx, vlm_idx in _RAM_TIERS:
if ram_gb <= max_ram:
return emb_idx, vlm_idx
return _RAM_DEFAULT_EMBED, _RAM_DEFAULT_VLM
# ---------------------------------------------------------------------------
# Cloud provider presets
# ---------------------------------------------------------------------------
@dataclass
class CloudProvider:
label: str
provider: str
default_api_base: str
default_embedding_model: str
default_embedding_dim: int
default_vlm_model: str
CLOUD_PROVIDERS: list[CloudProvider] = [
CloudProvider(
"VolcEngine (火山引擎)",
"volcengine",
"https://ark.cn-beijing.volces.com/api/v3",
"doubao-embedding-vision-251215",
1024,
"doubao-seed-2-1-lite-260915",
),
CloudProvider(
"BytePlus",
"volcengine",
"https://ark.ap-southeast.bytepluses.com/api/v3",
"skylark-embedding-vision-251215",
1024,
"seed-2-0-lite-260428",
),
CloudProvider(
"OpenAI",
"openai",
"https://api.openai.com/v1",
"text-embedding-3-small",
1536,
"gpt-5.4",
),
]
@dataclass
class AccessPlan:
label: str
api_base: str
default_embedding_model: str
default_embedding_dim: int
default_vlm_model: str
desc: str
# VolcEngine Ark access tiers. The two subscription plans share the same
# default models; pay-as-you-go uses the versioned model IDs.
VOLCENGINE_PLANS: list[AccessPlan] = [
AccessPlan(
"Agent Plan",
"https://ark.cn-beijing.volces.com/api/plan/v3",
"doubao-embedding-vision",
1024,
"doubao-seed-2.1-lite",
"(subscription — agent workloads)",
),
AccessPlan(
"Coding Plan",
"https://ark.cn-beijing.volces.com/api/coding/v3",
"doubao-embedding-vision",
1024,
"doubao-seed-2.1-lite",
"(subscription — coding assistants)",
),
AccessPlan(
"Pay-as-you-go API",
"https://ark.cn-beijing.volces.com/api/v3",
"doubao-embedding-vision-251215",
1024,
"doubao-seed-2-1-lite-260915",
"(billed by API usage)",
),
]
# BytePlus ModelArk access tiers.
BYTEPLUS_PLANS: list[AccessPlan] = [
AccessPlan(
"ModelArk Coding Plan",
"https://ark.ap-southeast.bytepluses.com/api/coding/v3",
"skylark-embedding-vision",
1024,
"dola-seed-2.0-lite",
"(subscription — coding assistants)",
),
AccessPlan(
"Pay-as-you-go API",
"https://ark.ap-southeast.bytepluses.com/api/v3",
"skylark-embedding-vision-251215",
1024,
"seed-2-0-lite-260428",
"(billed by API usage)",
),
]
# Cloud providers with a plan submenu, keyed by CLOUD_PROVIDERS label; the
# domain identifies the provider's own endpoints (both share the "volcengine"
# provider string, so the domain is what tells them apart).
_PLAN_MENUS: dict[str, tuple[str, list[AccessPlan]]] = {
"VolcEngine (火山引擎)": ("volces.com", VOLCENGINE_PLANS),
"BytePlus": ("bytepluses.com", BYTEPLUS_PLANS),
}
def _plan_seed_for(current: dict[str, Any], domain: str) -> str | None:
"""api_base worth seeding a plan menu with — only an existing endpoint on
the same domain, never another provider's."""
api_base = str(current.get("api_base") or "")
if current.get("provider") == "volcengine" and domain in api_base:
return api_base
return None
def _plan_index_for(plans: list[AccessPlan], api_base: str) -> int | None:
"""0-based *plans* index matching *api_base*, or None."""
for i, plan in enumerate(plans):
if plan.api_base == api_base:
return i
return None
def _select_access_plan(
provider_label: str,
plans: list[AccessPlan],
current_api_base: str | None = None,
*,
allow_back: bool = False,
) -> AccessPlan | object:
"""Plan submenu. ``_GO_BACK`` when the user navigated back.
*current_api_base* seeds the default; a current endpoint that matches no
plan (e.g. a proxy) is offered as an extra "keep" option that preserves
the endpoint with the pay-as-you-go default models.
"""
options = [(p.label, p.desc) for p in plans]
current_idx = _plan_index_for(plans, current_api_base or "")
keep_custom = bool(current_api_base) and current_idx is None
if keep_custom:
options.append(("Custom endpoint", f"(keep current: {current_api_base})"))
if current_idx is not None:
default = current_idx + 1
elif keep_custom:
default = len(options)
else:
default = 1
choice = _prompt_choice(
f"{provider_label} access:", options, default=default, allow_back=allow_back
)
if choice == 0:
return _GO_BACK
if keep_custom and choice == len(options):
payg = plans[-1]
return AccessPlan(
"Custom endpoint",
str(current_api_base),
payg.default_embedding_model,
payg.default_embedding_dim,
payg.default_vlm_model,
"",
)
return plans[choice - 1]
_WIZARD_VLM_OPTIONS: list[tuple[str, str]] = [
("VolcEngine (火山引擎)", "(API)"),
("BytePlus", "(API)"),
("OpenAI", "(API)"),
("OpenAI Codex", "(Subscription)"),
("Kimi", "(Subscription API Key)"),
("GLM", "(Subscription API Key)"),
("Custom (OpenAI-compatible)", "(Any OpenAI-compatible endpoint)"),
("Local via Ollama", "(no API key, runs on this machine)"),
]
_WIZARD_VLM_OLLAMA_CHOICE = 8 # index of "Local via Ollama" in _WIZARD_VLM_OPTIONS
_WIZARD_VLM_CUSTOM_CHOICE = 7 # index of "Custom (OpenAI-compatible)" in _WIZARD_VLM_OPTIONS
# ---------------------------------------------------------------------------
# llama.cpp local embedding presets
# ---------------------------------------------------------------------------
@dataclass
class LocalGGUFPreset:
label: str
model_name: str # key in LOCAL_DENSE_MODEL_SPECS
dimension: int
size_hint: str
LOCAL_GGUF_PRESETS: list[LocalGGUFPreset] = [
LocalGGUFPreset("BGE-small-zh v1.5 (f16)", "bge-small-zh-v1.5-f16", 512, "~24 MB"),
]
def _is_llamacpp_installed() -> bool:
try:
importlib.import_module("llama_cpp")
return True
except ImportError:
return False
def _install_llamacpp() -> bool:
"""Attempt to install llama-cpp-python via pip.
On the first attempt, uses the default build flags. If compilation
fails (common on ARM with older binutils that reject advanced
``-march`` extensions), retries with ``GGML_NATIVE=OFF`` to produce
a generic build.
"""
pip_cmd = [sys.executable, "-m", "pip", "install", "openviking[local-embed]"]
try:
subprocess.run(pip_cmd, check=True)
return True
except (subprocess.CalledProcessError, FileNotFoundError):
pass
print(f" {_yellow('Native build failed, retrying with generic CPU flags...')}")
env = os.environ.copy()
prev = env.get("CMAKE_ARGS", "")
env["CMAKE_ARGS"] = f"{prev} -DGGML_NATIVE=OFF -DLLAMA_NATIVE=OFF".strip()
try:
subprocess.run(pip_cmd, check=True, env=env)
return True
except (subprocess.CalledProcessError, FileNotFoundError):
return False
def _check_gguf_model_cached(model_name: str, cache_dir: str | None = None) -> bool:
from openviking.models.embedder.local_embedders import get_local_model_cache_path
return get_local_model_cache_path(model_name, cache_dir).exists()
# ---------------------------------------------------------------------------
# Config building
# ---------------------------------------------------------------------------
def _build_ollama_config(
embedding: EmbeddingPreset,
vlm: VLMPreset,
workspace: str,
) -> dict[str, Any]:
"""Build ov.conf dict for Ollama-based setup."""
return {
"storage": {"workspace": workspace},
"embedding": {
"dense": _ollama_dense_config(embedding),
},
"vlm": _ollama_vlm_config(vlm),
}
def _ollama_dense_config(embedding: EmbeddingPreset) -> dict[str, Any]:
"""Build the dense-embedding config block for an Ollama-served model."""
return {
"provider": "ollama",
"model": embedding.model,
"api_base": "http://localhost:11434/v1",
"dimension": embedding.dimension,
"input": "text",
}
def _ollama_vlm_config(vlm: VLMPreset) -> dict[str, Any]:
"""Build the VLM config block for an Ollama-served model.
``extra_request_body`` raises Ollama's context window past its 4096-token
default (OV's memory-extraction prompt alone is ~5k tokens, so the default
silently truncates the conversation) and disables thinking, which otherwise
makes thinking models emit only reasoning and stall.
"""
return {
"provider": "litellm",
"model": vlm.litellm_model,
"api_key": "no-key",
"api_base": "http://localhost:11434",
"temperature": 0.0,
"max_retries": 2,
"extra_request_body": {"num_ctx": 16384, "think": False},
}
def _build_query_planner_config(preset: QueryPlannerPreset) -> dict[str, Any]:
"""Build the ``query_planner`` config block for an Ollama-served model.
Uses the litellm provider with the bare Ollama base URL (no ``/v1``) to
match how the wizard configures the Ollama VLM, and disables thinking for
lower latency on the small planner model.
"""
return {
"provider": "litellm",
"model": preset.litellm_model,
"api_key": "no-key",
"api_base": "http://localhost:11434",
"temperature": 0.0,
"timeout": 60,
"extra_request_body": {"think": False},
}
# ---------------------------------------------------------------------------
# Config I/O
# ---------------------------------------------------------------------------
_PIP_LOCAL_EMBED = 'pip install "openviking[local-embed]"'
def _config_path() -> Path:
"""Where init writes ov.conf — honors OPENVIKING_CONFIG_FILE."""
override = os.environ.get(OPENVIKING_CONFIG_ENV)
if override:
return Path(override).expanduser()
return DEFAULT_CONFIG_DIR / "ov.conf"
def _workspace_path() -> str:
"""Workspace lives next to ov.conf so a single mount captures everything."""
return str(_config_path().parent / "data")
def _next_backup_path(config_path: Path) -> Path:
"""Return a non-conflicting backup path: .bak, then .bak.1, .bak.2, ..."""
base = config_path.with_suffix(".conf.bak")
if not base.exists():
return base
i = 1
while True:
candidate = base.with_suffix(f".bak.{i}")
if not candidate.exists():
return candidate
i += 1
def _write_secure_backup(config_path: Path, backup: Path) -> None:
fd, raw_temp_path = tempfile.mkstemp(prefix=f".{backup.name}.", dir=backup.parent)
temp_path = Path(raw_temp_path)
try:
with os.fdopen(fd, "wb") as target, config_path.open("rb") as source:
shutil.copyfileobj(source, target)
target.flush()
os.fsync(target.fileno())
os.chmod(temp_path, 0o600)
os.replace(temp_path, backup)
temp_path = None
finally:
if temp_path is not None:
temp_path.unlink(missing_ok=True)
def _write_config(config_dict: dict[str, Any], config_path: Path) -> bool:
"""Write config dict as JSON. Backs up existing file as .bak (rotates on conflict)."""
temp_path: Path | None = None
try:
config_path.parent.mkdir(parents=True, exist_ok=True)
fd, raw_temp_path = tempfile.mkstemp(prefix=f".{config_path.name}.", dir=config_path.parent)
temp_path = Path(raw_temp_path)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
handle.write(json.dumps(config_dict, indent=2, ensure_ascii=False) + "\n")
handle.flush()
os.fsync(handle.fileno())
os.chmod(temp_path, 0o600)
if config_path.exists():
backup = _next_backup_path(config_path)
os.chmod(config_path, 0o600)
_write_secure_backup(config_path, backup)
print(f" {_dim('Existing config backed up to ' + str(backup))}")
os.replace(temp_path, config_path)
temp_path = None
os.chmod(config_path, 0o600)
return True
except OSError as exc:
print(f" {_red(f'Failed to write config: {exc}')}")
return False
finally:
if temp_path is not None:
temp_path.unlink(missing_ok=True)
# ---------------------------------------------------------------------------
# Shared selection helpers
# ---------------------------------------------------------------------------
def _select_embedding_preset(
ollama_running: bool,
available_models: list[str],
rec_idx: int,
*,
allow_back: bool = False,
) -> EmbeddingPreset | None:
"""Interactive Ollama embedding preset selection. None when the user went back."""
embed_options: list[tuple[str, str]] = []
for i, p in enumerate(EMBEDDING_PRESETS):
rec = " *" if i == rec_idx else ""
avail = ""
if ollama_running and is_model_available(p.model, available_models):
avail = _green(" [downloaded]")
embed_options.append(
(
f"{p.label}",
f"({p.dimension}d, {p.size_hint}){avail}{rec}",
)
)
choice = _prompt_choice(
"Embedding model — powers semantic search:",
embed_options,
default=rec_idx + 1,
allow_back=allow_back,
)
if choice == 0:
return None
return EMBEDDING_PRESETS[choice - 1]
def _select_vlm_preset(
ollama_running: bool,
available_models: list[str],
rec_idx: int,
*,
allow_back: bool = False,
) -> VLMPreset | None:
"""Interactive Ollama VLM preset selection. None when the user went back."""
vlm_options: list[tuple[str, str]] = []
for i, p in enumerate(VLM_PRESETS):
rec = " *" if i == rec_idx else ""
avail = ""
if ollama_running and is_model_available(p.ollama_model, available_models):
avail = _green(" [downloaded]")
vlm_options.append((f"{p.label}", f"({p.size_hint}){avail}{rec}"))
choice = _prompt_choice(
"Vision-language model (VLM) — parses documents & images:",
vlm_options,
default=rec_idx + 1,
allow_back=allow_back,
)
if choice == 0:
return None
return VLM_PRESETS[choice - 1]
def _prompt_ollama_vlm(
*, allow_back: bool = False, current_litellm_model: str | None = None
) -> tuple[dict[str, Any] | None | object, bool | None]:
"""Ollama VLM selection: ensure Ollama, pick a preset, pull it.
Returns ``(vlm_config, ollama_running)``; ``vlm_config`` is None on cancel
or ``_GO_BACK`` when the user navigated back from the preset list.
*current_litellm_model* seeds the preset default when it matches one.
"""
ollama_running = _ensure_ollama()
if not ollama_running:
if not _prompt_confirm("Continue without Ollama?", default=False):
return None, ollama_running
available_models = get_ollama_models() if ollama_running else []
ram_gb = _get_system_ram_gb()
_, rec_vlm_idx = _get_recommended_indices(ram_gb)
if current_litellm_model:
for i, p in enumerate(VLM_PRESETS):
if p.litellm_model == current_litellm_model:
rec_vlm_idx = i # default to the currently configured model
break
vlm = _select_vlm_preset(ollama_running, available_models, rec_vlm_idx, allow_back=allow_back)
if vlm is None:
return _GO_BACK, ollama_running
_ensure_model_pulled(vlm.ollama_model, vlm.size_hint, ollama_running, available_models)
return _ollama_vlm_config(vlm), ollama_running
def _prompt_vlm_api_key(
provider: str,
reuse_key: tuple[str, str] | None,
reuse_prompt: str = "Reuse the embedding API key for the VLM?",
*,
allow_back: bool = False,
) -> str | object:
"""Get a VLM API key: offer same-provider reuse first, then env vars, then prompt."""
if reuse_key and reuse_key[0] == provider and reuse_key[1]:
if _prompt_confirm(reuse_prompt):
return reuse_key[1]
return _prompt_api_key_with_env(_PROVIDER_ENV_KEYS.get(provider), allow_back=allow_back)
def _vlm_option_index_for(current: dict[str, Any]) -> int:
"""1-based ``_WIZARD_VLM_OPTIONS`` index matching an existing VLM config."""
provider = str(current.get("provider") or "")
api_base = str(current.get("api_base") or "")
model = str(current.get("model") or "")
if provider == "volcengine":
return 2 if "bytepluses" in api_base else 1
if provider == "openai-codex":
return 4
if provider == "kimi":
return 5
if provider == "glm":
return 6
if provider == "litellm" and model.startswith("ollama/"):
return _WIZARD_VLM_OLLAMA_CHOICE
if provider == "openai":
return 3 if "api.openai.com" in api_base else 7
return 1
def _prompt_custom_vlm(
current: dict[str, Any],
reuse_key: tuple[str, str] | None,
reuse_prompt: str,
) -> dict[str, Any] | None | object:
"""Custom OpenAI-compatible VLM setup.
Returns the VLM config dict or ``_GO_BACK`` when the user types ``!back``
at any prompt.
"""
print(f"\n {_bold('Custom OpenAI-compatible VLM configuration')}")
print(f" {_dim(f'Type {_BACK_TOKEN} at any prompt to return to the provider menu.')}")
same_openai = current.get("provider") == "openai"
vlm_api_base = _prompt_required_input(
"API Base URL",
default=str(current["api_base"]) if same_openai and current.get("api_base") else None,
allow_back=True,
)
if vlm_api_base is _GO_BACK:
return _GO_BACK
vlm_api_key = _prompt_vlm_api_key("openai", reuse_key, reuse_prompt, allow_back=True)
if vlm_api_key is _GO_BACK:
return _GO_BACK
vlm_model = _prompt_required_input(
"Model",
default=str(current["model"]) if same_openai and current.get("model") else None,
allow_back=True,
)
if vlm_model is _GO_BACK:
return _GO_BACK
vlm_config: dict[str, Any] = {
"provider": "openai",
"model": vlm_model,
"api_base": vlm_api_base,
"temperature": 0.0,
"max_retries": 2,
}
if vlm_api_key:
vlm_config["api_key"] = vlm_api_key
return vlm_config
def _prompt_cloud_vlm(
allow_skip: bool = False,
reuse_key: tuple[str, str] | None = None,
allow_back: bool = False,
current: dict[str, Any] | None = None,
plan_seed: str | None = None,
) -> tuple[dict[str, Any] | None | object, bool | None]:
"""VLM provider selection (cloud APIs, subscriptions, or local Ollama).
Returns ``(vlm_config, ollama_running)``; ``vlm_config`` is None on cancel,
the ``_SKIP_VLM`` sentinel when *allow_skip* is set and taken, or
``_GO_BACK`` when *allow_back* is set and the user navigated back.
``ollama_running`` is only set when the local Ollama option was taken.
*reuse_key* is an optional ``(provider, api_key)`` from the embedding step,
offered for reuse when the VLM provider matches. *current* (the existing
VLM config, if any) seeds the menu position, model default, and offers to
keep the existing API key. *plan_seed* is a VolcEngine api_base from the
embedding step, used to default the plan menu to the same tier.
"""
current = current or {}
options = list(_WIZARD_VLM_OPTIONS)
if allow_skip:
options.append(("Skip for now", "(embedding only — add a VLM later)"))
default_idx = _vlm_option_index_for(current) if current else 1
# An existing same-provider key takes priority as the reuse candidate.
if current.get("api_key") and current.get("provider"):
reuse_key = (str(current["provider"]), str(current["api_key"]))
reuse_prompt = f"Keep the existing API key ({_mask_secret(str(current['api_key']))})?"
else:
reuse_prompt = "Reuse the embedding API key for the VLM?"
def _default_model(branch_provider: str, fallback: str) -> str:
if current.get("model") and current.get("provider") == branch_provider:
return str(current["model"])
return fallback
cloud_plan: AccessPlan | None = None
while True:
vlm_mode = _prompt_choice(
"VLM provider:", options, default=default_idx, allow_back=allow_back
)
if vlm_mode == 0:
return _GO_BACK, None
if allow_skip and vlm_mode == len(options):
return _SKIP_VLM, None
if vlm_mode == _WIZARD_VLM_OLLAMA_CHOICE:
current_ollama_model = (
str(current["model"])
if current.get("provider") == "litellm"
and str(current.get("model", "")).startswith("ollama/")
else None
)
vlm_config, ollama_running = _prompt_ollama_vlm(
allow_back=True, current_litellm_model=current_ollama_model
)
if vlm_config is _GO_BACK:
continue # back to the provider menu
return vlm_config, ollama_running
if vlm_mode == _WIZARD_VLM_CUSTOM_CHOICE:
custom = _prompt_custom_vlm(current, reuse_key, reuse_prompt)
if custom is _GO_BACK:
continue # back to the provider menu
if custom is None:
return None, None
return custom, None
if vlm_mode <= len(CLOUD_PROVIDERS):
menu = _PLAN_MENUS.get(CLOUD_PROVIDERS[vlm_mode - 1].label)
if menu: # pick plan / pay-as-you-go first
domain, plans = menu
seed = _plan_seed_for(current, domain) or (
plan_seed if plan_seed and domain in plan_seed else None
)
selected = _select_access_plan(
CLOUD_PROVIDERS[vlm_mode - 1].label, plans, seed, allow_back=True
)
if selected is _GO_BACK:
continue # back to the provider menu
cloud_plan = selected
break
if vlm_mode in (1, 2, 3): # VolcEngine / BytePlus / OpenAI — same order as CLOUD_PROVIDERS
vlm_choice = CLOUD_PROVIDERS[vlm_mode - 1]
print(f"\n {_bold(f'{vlm_choice.label} VLM configuration')}")
vlm_api_key = _prompt_vlm_api_key(vlm_choice.provider, reuse_key, reuse_prompt)
if not vlm_api_key:
print(f" {_red('API key is required')}")
return None, None
default_vlm_model = (
cloud_plan.default_vlm_model if cloud_plan else vlm_choice.default_vlm_model
)
vlm_model = _prompt_required_input(
"Model", default=_default_model(vlm_choice.provider, default_vlm_model)
)
vlm_api_base = cloud_plan.api_base if cloud_plan else vlm_choice.default_api_base
vlm_provider = vlm_choice.provider
elif vlm_mode == 4:
_ensure_codex_auth()
print(f"\n {_bold('Codex VLM configuration')}")
vlm_model = _prompt_required_input(
"Model", default=_default_model("openai-codex", _DEFAULT_CODEX_MODEL)
)
vlm_api_base = _DEFAULT_CODEX_BASE_URL
vlm_api_key = None
vlm_provider = "openai-codex"
elif vlm_mode == 5:
print(f"\n {_bold('Kimi VLM configuration')}")
vlm_api_key = _prompt_vlm_api_key("kimi", reuse_key, reuse_prompt)
if not vlm_api_key:
print(f" {_red('API key is required')}")
return None, None
vlm_model = _prompt_required_input(
"Model", default=_default_model("kimi", _DEFAULT_KIMI_MODEL)
)
vlm_api_base = _DEFAULT_KIMI_BASE_URL
vlm_provider = "kimi"
elif vlm_mode == 6:
print(f"\n {_bold('GLM VLM configuration')}")
vlm_api_key = _prompt_vlm_api_key("glm", reuse_key, reuse_prompt)
if not vlm_api_key:
print(f" {_red('API key is required')}")
return None, None
vlm_model = _prompt_required_input(
"Model", default=_default_model("glm", _DEFAULT_GLM_MODEL)
)
vlm_api_base = _DEFAULT_GLM_BASE_URL
vlm_provider = "glm"
vlm_config: dict[str, Any] = {
"provider": vlm_provider,
"model": vlm_model,
"api_base": vlm_api_base,
"temperature": 0.0,
"max_retries": 2,
}
if vlm_api_key:
vlm_config["api_key"] = vlm_api_key
return vlm_config, None
def _cloud_provider_index_for(section: dict[str, Any]) -> int:
"""1-based CLOUD_PROVIDERS index matching an existing config section."""
provider = str(section.get("provider") or "")
api_base = str(section.get("api_base") or "")
for i, p in enumerate(CLOUD_PROVIDERS, 1):
if p.provider == provider and p.default_api_base == api_base:
return i
# Same provider + same endpoint domain — covers plan endpoints, which
# never equal default_api_base (VolcEngine and BytePlus share the
# "volcengine" provider string, so the domain is the disambiguator).
for i, p in enumerate(CLOUD_PROVIDERS, 1):
menu = _PLAN_MENUS.get(p.label)
if p.provider == provider and menu and menu[0] in api_base:
return i
for i, p in enumerate(CLOUD_PROVIDERS, 1):
if p.provider == provider:
return i
return 1
def _prompt_cloud_embedding(
*, allow_back: bool = False, current: dict[str, Any] | None = None
) -> dict[str, Any] | None | object:
"""Cloud embedding provider selection.
Returns the dense-embedding config dict, ``None`` on cancel,
``_CUSTOM_SETUP`` when the user picked manual configuration, or
``_GO_BACK`` when *allow_back* is set and the user navigated back.
*current* (the existing dense config, if any) seeds every default so an
update run can keep values by just pressing Enter.
"""
current = current or {}
provider_options = [(p.label, "") for p in CLOUD_PROVIDERS]
provider_options.append(("Custom / manual", "(OpenAI-compatible endpoint, or edit ov.conf)"))
default_idx = _cloud_provider_index_for(current) if current else 1
provider: CloudProvider | None = None
plan: AccessPlan | None = None
while True:
choice = _prompt_choice(
"Embedding provider:", provider_options, default=default_idx, allow_back=allow_back
)
if choice == 0:
return _GO_BACK
if choice > len(CLOUD_PROVIDERS):
custom = _prompt_custom_embedding(current)
if custom is _GO_BACK:
continue # back to the provider menu
return custom
provider = CLOUD_PROVIDERS[choice - 1]
menu = _PLAN_MENUS.get(provider.label)
if menu:
domain, plans = menu
selected = _select_access_plan(
provider.label, plans, _plan_seed_for(current, domain), allow_back=True
)
if selected is _GO_BACK:
continue # back to the provider menu
plan = selected
break
assert provider is not None
same_provider = bool(current) and current.get("provider") == provider.provider
api_base = plan.api_base if plan else provider.default_api_base
default_embedding_model = (
plan.default_embedding_model if plan else provider.default_embedding_model
)
default_embedding_dim = plan.default_embedding_dim if plan else provider.default_embedding_dim
print(f"\n {_bold('Embedding configuration')}")
embedding_api_key = ""
if same_provider and current.get("api_key"):
masked = _mask_secret(str(current["api_key"]))
if _prompt_confirm(f"Keep the existing API key ({masked})?"):
embedding_api_key = str(current["api_key"])
if not embedding_api_key:
embedding_api_key = _prompt_api_key_with_env(_PROVIDER_ENV_KEYS.get(provider.provider))
if not embedding_api_key:
print(f" {_red('API key is required')}")
return None
default_model = (
str(current["model"]) if same_provider and current.get("model") else default_embedding_model
)
embedding_model = _prompt_required_input("Model", default=default_model)
if (
same_provider
and embedding_model == current.get("model")
and isinstance(current.get("dimension"), int)
):
embedding_dim = current["dimension"]
print(f" {_dim(f'Dimension: {embedding_dim} (kept from current config)')}")
elif embedding_model == default_embedding_model:
embedding_dim = default_embedding_dim
print(f" {_dim(f'Dimension: {embedding_dim} (auto-filled for {embedding_model})')}")
else:
embedding_dim = _prompt_required_int("Dimension", default=default_embedding_dim)
if embedding_dim is None:
print(f" {_red('Dimension is required')}")
return None
return {
"provider": provider.provider,
"model": embedding_model,
"api_key": embedding_api_key,
"api_base": api_base,
"dimension": embedding_dim,
}
def _prompt_custom_embedding(current: dict[str, Any]) -> dict[str, Any] | None | object:
"""Custom embedding: interactive OpenAI-compatible prompts or manual editing.
Returns the dense-embedding config dict, ``None`` on cancel,
``_CUSTOM_SETUP`` when the user chose to edit ov.conf directly, or
``_GO_BACK`` to return to the provider menu.
"""
choice = _prompt_choice(
"Custom embedding setup:",
[
("Interactive (OpenAI-compatible)", "(enter API base URL, key, model, dimension)"),
("Edit ov.conf manually", "(opens $EDITOR with the example config)"),
],
default=1,
allow_back=True,
)
if choice == 0:
return _GO_BACK
if choice == 2:
_wizard_custom()
return _CUSTOM_SETUP
same_openai = current.get("provider") == "openai"
def _current_value(key: str) -> str | None:
return str(current[key]) if same_openai and current.get(key) else None
print(f"\n {_bold('Custom OpenAI-compatible embedding configuration')}")
print(f" {_dim(f'Type {_BACK_TOKEN} at any prompt to return to the provider menu.')}")
api_base = _prompt_required_input(
"API Base URL", default=_current_value("api_base"), allow_back=True
)
if api_base is _GO_BACK:
return _GO_BACK
api_key: str | object = ""
if _current_value("api_key"):
masked = _mask_secret(str(current["api_key"]))
if _prompt_confirm(f"Keep the existing API key ({masked})?"):
api_key = str(current["api_key"])
if not api_key:
api_key = _prompt_api_key_with_env(_PROVIDER_ENV_KEYS.get("openai"), allow_back=True)
if api_key is _GO_BACK:
return _GO_BACK
if not api_key:
print(f" {_red('API key is required')}")
return None
model = _prompt_required_input("Model", default=_current_value("model"), allow_back=True)
if model is _GO_BACK:
return _GO_BACK
current_dim = current.get("dimension") if same_openai else None
dimension = _prompt_required_int(
"Dimension",
default=current_dim if isinstance(current_dim, int) else None,
allow_back=True,
)
if dimension is _GO_BACK:
return _GO_BACK
if dimension is None:
print(f" {_red('Dimension is required')}")
return None
return {
"provider": "openai",
"model": model,
"api_key": api_key,
"api_base": api_base,
"dimension": dimension,
}
def _prompt_llamacpp_embedding() -> LocalGGUFPreset | None:
"""llama.cpp embedding setup: ensure runtime, pick a GGUF preset, download it."""
print("\n Checking llama-cpp-python...", end=" ", flush=True)
if _is_llamacpp_installed():
print(_green("installed"))
else:
print(_yellow("not installed"))
print(f"\n {_dim('llama-cpp-python is required for local CPU embedding.')}")
if _prompt_confirm(f"Install now? ({_PIP_LOCAL_EMBED})"):
print()
if _install_llamacpp():
print(f" {_green('OK')} llama-cpp-python installed")
else:
print(f" {_red('Installation failed.')}")
print(f" {_dim('Try manually: ' + _PIP_LOCAL_EMBED)}")
if not _prompt_confirm(
"Continue anyway? (config will be generated)", default=False
):
return None
else:
print(f"\n {_dim('Install later: ' + _PIP_LOCAL_EMBED)}")
if not _prompt_confirm("Continue anyway? (config will be generated)", default=False):
return None
model_options: list[tuple[str, str]] = []
for p in LOCAL_GGUF_PRESETS:
cached = ""
try:
if _check_gguf_model_cached(p.model_name):
cached = _green(" [downloaded]")
except Exception:
pass
model_options.append(
(
p.label,
f"({p.dimension}d, {p.size_hint}){cached}",
)
)
model_choice = _prompt_choice("Embedding model:", model_options, default=1)
preset = LOCAL_GGUF_PRESETS[model_choice - 1]
# Download if not cached
try:
if not _check_gguf_model_cached(preset.model_name):
if _prompt_confirm(
f"Model '{preset.model_name}' not downloaded yet. Download now? ({preset.size_hint})"
):
print(f"\n {_dim('Downloading...')}", end=" ", flush=True)
try:
import requests
from openviking.models.embedder.local_embedders import (
get_local_model_cache_path,
get_local_model_spec,
)
spec = get_local_model_spec(preset.model_name)
target = get_local_model_cache_path(preset.model_name)
target.parent.mkdir(parents=True, exist_ok=True)
tmp = target.with_suffix(target.suffix + ".part")
with requests.get(spec.download_url, stream=True, timeout=(10, 300)) as resp:
resp.raise_for_status()
total = int(resp.headers.get("content-length", 0))
downloaded = 0
with tmp.open("wb") as fh:
for chunk in resp.iter_content(chunk_size=1024 * 1024):
if chunk:
fh.write(chunk)
downloaded += len(chunk)
if total > 0:
pct = downloaded * 100 // total
print(
f"\r {_dim(f'Downloading... {pct}%')}",
end=" ",
flush=True,
)
os.replace(tmp, target)
print(f"\r {_green('OK')} Model downloaded to {target} ")
except Exception as exc:
print(f"\r {_yellow(f'Download failed: {exc}')}")
print(f" {_dim('Model will be auto-downloaded on first server start.')}")
else:
print(f" {_dim('Model will be auto-downloaded on first server start.')}")
except Exception:
pass
return preset
# ---------------------------------------------------------------------------
# Wizard flows
# ---------------------------------------------------------------------------
def _wizard_ollama() -> tuple[dict[str, Any] | None, bool | None]:
"""Ollama-based local model setup flow.
Returns ``(config, ollama_running)`` so later steps (e.g. the query planner)
can reuse the Ollama state instead of re-running the install flow.
"""
# Ensure Ollama is installed and running
ollama_running = _ensure_ollama()
if not ollama_running:
if not _prompt_confirm(
"Continue without Ollama? (config will be generated but models won't be pulled)",
default=False,
):
return None, ollama_running
available_models = get_ollama_models() if ollama_running else []
# System RAM
ram_gb = _get_system_ram_gb()
rec_embed_idx, rec_vlm_idx = _get_recommended_indices(ram_gb)
if ram_gb > 0:
print(f"\n {_dim(f'Detected {ram_gb} GB RAM')}")
# --- Recommended one-shot setup ---
rec_embed = EMBEDDING_PRESETS[rec_embed_idx]
rec_vlm = VLM_PRESETS[rec_vlm_idx]
rec_planner = QUERY_PLANNER_PRESETS[0]
total_gb = (
_parse_size_gb(rec_embed.size_hint)
+ _parse_size_gb(rec_vlm.size_hint)
+ _QUERY_PLANNER_DOWNLOAD_GB
)
ram_note = f" (for {ram_gb} GB RAM)" if ram_gb > 0 else ""
print(f"\n {_bold('Recommended local setup' + ram_note)}")
print(f" Embedding {rec_embed.model} {_dim('(' + rec_embed.size_hint + ')')}")
print(f" VLM {rec_vlm.ollama_model} {_dim('(' + rec_vlm.size_hint + ')')}")
print(f" Query planner {rec_planner.ollama_model} {_dim('(~0.9 GB)')}")
print(
f" {_dim(f'Total download ~{total_gb:.0f} GB — already-downloaded models are skipped')}"
)
if _prompt_confirm("Use this recommended setup?"):
if _check_disk_before_pull(total_gb):
for model, hint in (
(rec_embed.model, rec_embed.size_hint),
(rec_vlm.ollama_model, rec_vlm.size_hint),
(rec_planner.ollama_model, f"~{_QUERY_PLANNER_DOWNLOAD_GB} GB"),
):
_ensure_model_pulled(model, hint, ollama_running, available_models, ask=False)
config = _build_ollama_config(rec_embed, rec_vlm, _workspace_path())
config["query_planner"] = _build_query_planner_config(rec_planner)
return config, ollama_running
print(f" {_dim('Pick smaller models below instead.')}")
# --- Per-model selection ---
embedding = _select_embedding_preset(ollama_running, available_models, rec_embed_idx)
_ensure_model_pulled(embedding.model, embedding.size_hint, ollama_running, available_models)
vlm = _select_vlm_preset(ollama_running, available_models, rec_vlm_idx)
_ensure_model_pulled(vlm.ollama_model, vlm.size_hint, ollama_running, available_models)
return _build_ollama_config(embedding, vlm, _workspace_path()), ollama_running
def _wizard_two_step() -> tuple[dict[str, Any] | None | object, bool | None]:
"""Step-by-step setup: embedding first, then VLM — each cloud or local.
Returns ``(config, ollama_running)``. ``config`` may also be the
``_CUSTOM_SETUP`` sentinel when the user was routed to manual editing, or
``_GO_BACK`` when the user backed out to the mode menu.
"""
while True:
_rule("Step 1/2 · Embedding — powers semantic search")
dense, ollama_running = _prompt_embedding_flow(allow_back=True)
if dense is _GO_BACK:
return _GO_BACK, None
if dense is _CUSTOM_SETUP:
return _CUSTOM_SETUP, None
if dense is None:
return None, ollama_running
print(f"\n {_green('✓')} Embedding: {_summarize_model(dense)}")
_rule("Step 2/2 · VLM — parses documents & extracts memories")
reuse_key = None
if isinstance(dense, dict) and dense.get("api_key"):
reuse_key = (dense["provider"], dense["api_key"])
plan_seed = None
if dense.get("provider") == "volcengine" and dense.get("api_base"):
plan_seed = str(dense["api_base"])
vlm_config, vlm_ollama = _prompt_cloud_vlm(
allow_skip=True, reuse_key=reuse_key, allow_back=True, plan_seed=plan_seed
)
if vlm_config is _GO_BACK:
continue # back to Step 1
if vlm_config is None:
return None, ollama_running
if vlm_ollama is not None:
ollama_running = vlm_ollama
if vlm_config is _SKIP_VLM:
print(f"\n {_green('✓')} VLM: {_dim('skipped — add one later with init')}")
else:
print(f"\n {_green('✓')} VLM: {_summarize_model(vlm_config)}")
config: dict[str, Any] = {
"storage": {"workspace": _workspace_path()},
"embedding": {"dense": dense},
}
if vlm_config is not _SKIP_VLM:
config["vlm"] = vlm_config
return config, ollama_running
def _wizard_server(current: dict[str, Any] | None = None) -> dict[str, Any] | None:
"""Prompt for server binding, port, and auth (root API key when remote).
Auth mode is auto-detected by the server from ``root_api_key``: setting a
key switches to ``api_key`` mode, no key means ``dev`` mode (which the
server only permits on localhost) — so this step never writes
``auth_mode`` explicitly. *current* (the existing server config, if any)
seeds all defaults so an update run can keep values by pressing Enter.
"""
current = current or {}
_rule("Server & auth")
if current:
print(f" {_dim('Current: ' + _summarize_server(current))}")
print(f" {_dim('Local: only this machine can reach the server (no auth, dev mode).')}")
print(f" {_dim('Remote: bind to 0.0.0.0 for Docker / LAN access — requires API-key auth.')}")
is_remote_now = str(current.get("host") or "127.0.0.1") not in (
"127.0.0.1",
"localhost",
"::1",
)
mode = _prompt_choice(
"Bind server host to:",
[
("Local (127.0.0.1)", "(default, safer — no auth needed)"),
("Remote (0.0.0.0)", "(Docker / remote access — root API key required)"),
],
default=2 if is_remote_now else 1,
)
try:
port_default = int(current.get("port") or 1933)
except (TypeError, ValueError):
port_default = 1933
port = _prompt_required_int("Port", default=port_default)
if port is None:
port = port_default
if mode == 1:
return {"host": "127.0.0.1", "port": port}
print(f"\n {_dim('Non-local binding switches auth to api_key mode: every client must send')}")
print(f" {_dim('the root API key as a Bearer token (Authorization: Bearer <key>).')}")
existing_key = str(current.get("root_api_key") or "")
key_options: list[tuple[str, str]] = []
if existing_key:
key_options.append(("Keep existing key", f"({_mask_secret(existing_key)})"))
key_options.append(
("Generate one for me", "(recommended — 64-char random key, shown once below)")
)
key_options.append(("Enter my own", ""))
key_source = _prompt_choice("Root API key:", key_options, default=1)
offset = 1 if existing_key else 0
if existing_key and key_source == 1:
root_api_key = existing_key
elif key_source == 1 + offset:
root_api_key = secrets.token_hex(32)
print(f"\n {_green('Generated root API key — copy it now, clients need it:')}")
print(f"\n {_bold(root_api_key)}\n")
print(f" {_dim('It is also saved in ov.conf (server.root_api_key).')}")
print(f" {_dim('Clients authenticate with: Authorization: Bearer <this key>')}")
else:
root_api_key = _prompt_api_key("Root API Key")
if not root_api_key:
print(f" {_red('Root API key is required for remote binding')}")
return None
return {"host": "0.0.0.0", "port": port, "root_api_key": root_api_key}
def _wizard_gateway(
server: dict[str, Any], current: dict[str, Any] | None = None
) -> dict[str, Any]:
"""Enable the gateway on the server port and choose who may configure it."""
from openviking_gateway.config import EmbeddedGatewayConfig
# Settings the embedded gateway no longer reads are dropped on save.
removed = EmbeddedGatewayConfig.removed_fields
gateway = {k: v for k, v in (current or {}).items() if k not in removed}
_rule("OpenViking Gateway")
gateway["enabled"] = _prompt_confirm(
"Enable OpenViking Gateway on the same port?", default=gateway.get("enabled", False)
)
if gateway["enabled"]:
_check_gateway_public_url(server, gateway)
_prompt_gateway_access(server, gateway)
return gateway
def _check_gateway_public_url(server: dict[str, Any], gateway: dict[str, Any]) -> None:
"""Offer to clear a public_url left over from the old 1935 gateway port."""
public_url = str(gateway.get("public_url") or "")
port = urlsplit(public_url).port
server_port = int(server.get("port") or 1933)
if port is None or port == server_port:
return
print(f"\n {_yellow(f'gateway.public_url points at port {port}:')} {public_url}")
print(f" {_dim(f'The gateway now serves on the server port ({server_port}).')}")
if _prompt_confirm("Clear gateway.public_url?", default=port == 1935):
gateway.pop("public_url")
def _prompt_gateway_access(server: dict[str, Any], gateway: dict[str, Any]) -> None:
"""Remote servers choose whether users may configure upstreams themselves."""
if not (server.get("root_api_key") or server.get("auth_mode") == "api_key"):
return
allow_users = _prompt_confirm(
"Allow users to configure their own gateway upstreams?",
default=not bool(gateway.get("management_key")),
)
if allow_users:
gateway.pop("management_key", None)
elif not gateway.get("management_key"):
gateway["management_key"] = "ovgm_" + secrets.token_urlsafe(32)
print(f"\n {_green('Generated gateway management key — copy it to unlock editing:')}")
print(f"\n {_bold(gateway['management_key'])}\n")
print(f" {_dim('Saved in ov.conf (gateway.management_key).')}")
def _wizard_query_planner(config_dict: dict[str, Any], ollama_running: bool | None = None) -> None:
"""Optionally configure a lightweight local query-planner model.
When this setup already uses an Ollama VLM (*ollama_running* is not
``None``) the planner rides on that running Ollama at near-zero extra cost,
so it is recommended and enabled by default. Otherwise (Cloud / non-Ollama
VLM) it is still offered but off by default and without the recommendation,
and enabling it runs the Ollama install flow.
Mutates *config_dict* in place to add ``query_planner``. Prompt selection is
resolved at retrieval time from the configured model name.
"""
if "query_planner" in config_dict:
return # already configured (e.g. by the recommended Ollama setup)
_rule("Query planner (optional)")
print(f" {_dim('A small local model that plans retrieval before search — skips')}")
print(f" {_dim('lookups for small talk and emits focused queries otherwise, saving tokens.')}")
# Recommend it and default to yes only when an Ollama VLM is already running;
# cloud / non-Ollama setups would need a fresh Ollama install, so default to
# no and drop the recommendation.
has_ollama_vlm = ollama_running is not None
prompt = "Enable a lightweight local query planner via Ollama?"
if has_ollama_vlm:
prompt += " (recommended)"
if not _prompt_confirm(prompt, default=has_ollama_vlm):
return
if ollama_running is None:
ollama_running = _ensure_ollama()
if not ollama_running:
if not _prompt_confirm(
"Continue without Ollama? (config will be written but the model won't be pulled)",
default=False,
):
return
available_models = get_ollama_models() if ollama_running else []
options = [(p.label, p.size_hint) for p in QUERY_PLANNER_PRESETS]
choice = _prompt_choice("Query planner model:", options, default=1)
preset = QUERY_PLANNER_PRESETS[choice - 1]
_ensure_model_pulled(
preset.ollama_model,
f"~{_QUERY_PLANNER_DOWNLOAD_GB} GB",
bool(ollama_running),
available_models,
)
config_dict["query_planner"] = _build_query_planner_config(preset)
def _wizard_custom() -> dict[str, Any] | None:
"""Custom configuration - point user to example config."""
config_path = _config_path()
example = Path(__file__).parent.parent / "examples" / "ov.conf.example"
if example.exists():
print(f"\n Example config: {_cyan(str(example))}")
print(f" Config path: {_cyan(str(config_path))}")
editor = os.environ.get("EDITOR", os.environ.get("VISUAL", ""))
if editor:
if _prompt_confirm(f"Open {config_path} in {editor}?"):
config_path.parent.mkdir(parents=True, exist_ok=True)
if not config_path.exists():
# Copy example as starting point
try:
config_path.write_text(example.read_text(encoding="utf-8"), encoding="utf-8")
except OSError:
pass
subprocess.run([editor, str(config_path)], check=False)
else:
print(f"\n {_dim('Set $EDITOR to open the config file automatically.')}")
return None
# ---------------------------------------------------------------------------
# Partial reconfiguration of an existing ov.conf
# ---------------------------------------------------------------------------
def _prompt_embedding_flow(
*, allow_back: bool = False, current: dict[str, Any] | None = None
) -> tuple[dict[str, Any] | None | object, bool | None]:
"""Embedding selection across all backends (main flow and section updates).
Returns ``(dense_config, ollama_running)``; ``dense_config`` is None on
cancel, the ``_CUSTOM_SETUP`` sentinel for manual editing, or ``_GO_BACK``
when *allow_back* is set and the user backed out of the backend menu.
*current* (the existing dense config, if any) seeds all defaults.
"""
current = current or {}
backend_default = {"ollama": 2, "local": 3}.get(str(current.get("provider") or ""), 1)
while True:
choice = _prompt_choice(
"Embedding setup:",
[
("Cloud API", "(VolcEngine, BytePlus, OpenAI)"),
("Local via Ollama", "(no API key, runs on this machine)"),
("Lightweight CPU embedding", "(llama.cpp, ~24 MB, no Ollama needed)"),
],
default=backend_default,
allow_back=allow_back,
)
if choice == 0:
return _GO_BACK, None
if choice == 1:
dense = _prompt_cloud_embedding(allow_back=True, current=current)
if dense is _GO_BACK:
continue # back to the backend menu
return dense, None
if choice == 2:
ollama_running = _ensure_ollama()
if not ollama_running:
if not _prompt_confirm("Continue without Ollama?", default=False):
return None, ollama_running
available_models = get_ollama_models() if ollama_running else []
ram_gb = _get_system_ram_gb()
rec_idx, _ = _get_recommended_indices(ram_gb)
if current.get("provider") == "ollama":
for i, p in enumerate(EMBEDDING_PRESETS):
if p.model == current.get("model"):
rec_idx = i # default to the currently configured model
break
preset = _select_embedding_preset(
ollama_running, available_models, rec_idx, allow_back=True
)
if preset is None:
continue # back to the backend menu
_ensure_model_pulled(preset.model, preset.size_hint, ollama_running, available_models)
return _ollama_dense_config(preset), ollama_running
gguf = _prompt_llamacpp_embedding()
if gguf is None:
return None, None
return {
"provider": "local",
"model": gguf.model_name,
"dimension": gguf.dimension,
}, None
def _update_existing_config(config_path: Path, section: str) -> int:
"""Update a single section of an existing ov.conf."""
try:
data = json.loads(config_path.read_text(encoding="utf-8-sig"))
except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
print(f" {_red(f'Cannot read existing config: {exc}')}")
print(f" {_dim('Fix or remove the file, then re-run `openviking-server init`.')}")
return 1
if not isinstance(data, dict):
print(f" {_red('Existing config is not a JSON object; cannot update in place.')}")
return 1
if section == "vlm":
current_vlm = _config_section(data, "vlm")
print(f"\n Current VLM: {_summarize_model(current_vlm)}")
vlm_config, _ = _prompt_cloud_vlm(current=current_vlm)
if vlm_config is None:
print("\n Setup cancelled.\n")
return 0
old_summary, new_summary = _summarize_model(current_vlm), _summarize_model(vlm_config)
data["vlm"] = vlm_config
elif section == "embedding":
old_dense = _config_section(data, "embedding", "dense")
old_dim = old_dense.get("dimension")
print(f"\n Current embedding: {_summarize_model(old_dense)}")
dense, _ = _prompt_embedding_flow(current=old_dense)
if dense is _CUSTOM_SETUP:
return 0
if dense is None:
print("\n Setup cancelled.\n")
return 0
if old_dim and dense.get("dimension") != old_dim:
print(
f"\n {_yellow('Embedding dimension changes from ' + str(old_dim) + ' to ' + str(dense.get('dimension')) + '.')}"
)
print(
f" {_yellow('Existing vector indexes become unusable — data must be re-ingested.')}"
)
if not _prompt_confirm("Continue?", default=False):
print("\n Setup cancelled.\n")
return 0
old_summary, new_summary = _summarize_model(old_dense), _summarize_model(dense)
data.setdefault("embedding", {})["dense"] = dense
elif section == "gateway":
current_gateway = _config_section(data, "gateway")
gateway = _wizard_gateway(_config_section(data, "server"), current_gateway)
old_summary, new_summary = (
_summarize_gateway(current_gateway),
_summarize_gateway(gateway),
)
data["gateway"] = gateway
else: # server
current_server = _config_section(data, "server")
server_dict = _wizard_server(current=current_server)
if server_dict is None:
print("\n Setup cancelled.\n")
return 0
old_summary, new_summary = (
_summarize_server(current_server),
_summarize_server(server_dict),
)
updated_server = {**current_server, **server_dict}
if server_dict.get("host") == "127.0.0.1":
updated_server.pop("auth_mode", None)
updated_server.pop("root_api_key", None)
data["server"] = updated_server
gateway = _config_section(data, "gateway")
if gateway.get("enabled"):
# Local dev has no restricted configuration; remote asks who may configure.
if server_dict.get("host") == "127.0.0.1":
gateway.pop("management_key", None)
else:
_prompt_gateway_access(updated_server, gateway)
data["gateway"] = gateway
print(f"\n {_bold('Change:')} {old_summary}")
print(f" {_cyan('→')} {new_summary}")
if not _prompt_confirm("\n Save configuration?"):
print("\n Setup cancelled.\n")
return 0
if not _write_config(data, config_path):
return 1
print(f" {_green('OK')} Configuration updated\n")
_post_save_actions()
return 0
# ---------------------------------------------------------------------------
# Post-save actions
# ---------------------------------------------------------------------------
def _post_save_actions() -> None:
"""Offer to validate the fresh config and start the server right away."""
if _prompt_confirm("Validate the setup now? (runs `openviking-server doctor`)"):
try:
from openviking_cli.doctor import run_doctor
run_doctor()
except Exception as exc:
print(f" {_yellow(f'doctor failed to run: {exc}')}")
if _prompt_confirm("Start the server now?", default=False):
# Replace the wizard process with the server so Ctrl-C etc. behave
# exactly as a direct `openviking-server` invocation.
os.execv(sys.executable, [sys.executable, "-m", "openviking_cli.server_bootstrap"])
# ---------------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------------
def _summarize_model(section: dict[str, Any]) -> str:
"""One-line, secret-free description of a model config block."""
if not section:
return _dim("(not configured)")
provider = section.get("provider", "?")
model = section.get("model", "?")
text = f"{provider} · {model}"
api_base = str(section.get("api_base") or "")
if api_base:
# The endpoint distinguishes e.g. VolcEngine plans from pay-as-you-go.
text += f" @ {api_base.removeprefix('https://').removeprefix('http://')}"
if section.get("dimension"):
text += f" ({section['dimension']}d)"
return text
def _summarize_server(server: dict[str, Any]) -> str:
"""One-line, secret-free description of the server config block."""
if not server:
return _dim("(defaults: 127.0.0.1:1933 · auth dev)")
host = server.get("host", "127.0.0.1")
port = server.get("port", 1933)
auth = "api_key (root key set)" if server.get("root_api_key") else "dev (no auth)"
return f"{host}:{port} · auth {auth}"
def _summarize_gateway(gateway: dict[str, Any]) -> str:
if not gateway.get("enabled"):
return "disabled"
access = "management key required" if gateway.get("management_key") else "users can configure"
return f"enabled on server port · {access}"
def _config_section(data: dict[str, Any], *keys: str) -> dict[str, Any]:
"""Safely walk nested dict keys, returning {} on any non-dict hop."""
node: Any = data
for key in keys:
if not isinstance(node, dict):
return {}
node = node.get(key)
return node if isinstance(node, dict) else {}
def _load_config_data(config_path: Path) -> dict[str, Any] | None:
"""Best-effort read of the existing ov.conf; None when unreadable."""
try:
data = json.loads(config_path.read_text(encoding="utf-8-sig"))
except (OSError, json.JSONDecodeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def _print_current_config(data: dict[str, Any]) -> None:
"""Show the non-secret parts of the existing configuration."""
print(f"\n {_bold('Current configuration')}")
print(f" Embedding: {_summarize_model(_config_section(data, 'embedding', 'dense'))}")
print(f" VLM: {_summarize_model(_config_section(data, 'vlm'))}")
print(f" Query planner: {_summarize_model(_config_section(data, 'query_planner'))}")
print(f" Server: {_summarize_server(_config_section(data, 'server'))}")
print(f" Gateway: {_summarize_gateway(_config_section(data, 'gateway'))}")
def run_init() -> int:
"""Run the interactive setup wizard."""
config_path = _config_path()
workspace = _workspace_path()
_print_banner()
print(f" {_dim(f'Data will be stored under {workspace} unless you edit ov.conf later.')}\n")
# Existing config: show what is configured and offer section-level updates
# instead of forcing a redo.
if config_path.exists():
print(f" {_yellow('Existing config found:')} {config_path}")
data = _load_config_data(config_path)
vlm_now = emb_now = server_now = gateway_now = ""
if data is not None:
_print_current_config(data)
vlm_now = f"(now: {_summarize_model(_config_section(data, 'vlm'))})"
emb_now = f"(now: {_summarize_model(_config_section(data, 'embedding', 'dense'))})"
server_now = f"(now: {_summarize_server(_config_section(data, 'server'))})"
gateway_now = f"(now: {_summarize_gateway(_config_section(data, 'gateway'))})"
action = _prompt_choice(
"What would you like to do?",
[
("Start over", "(full setup, current config backed up as .bak)"),
("Update VLM", vlm_now),
("Update embedding", emb_now),
("Update server & auth", server_now),
("Update gateway", gateway_now),
("Cancel", ""),
],
default=1,
)
if action == 6:
print(" Setup cancelled.\n")
return 0
if action in (2, 3, 4, 5):
section = {2: "vlm", 3: "embedding", 4: "server", 5: "gateway"}[action]
return _update_existing_config(config_path, section)
config_dict: dict[str, Any] | None = None
# Tracks whether Ollama was already set up by the chosen mode, so the query
# planner reuses that state instead of re-running the install flow. ``None``
# means the mode never touched Ollama (e.g. Cloud).
ollama_running: bool | None = None
# Setup mode; ← inside step-by-step returns here.
while True:
mode = _prompt_choice(
"Choose setup mode:",
[
(
"Step-by-step setup",
"(pick embedding & VLM separately — cloud, local, or mixed)",
),
("Recommended local setup", "(all-Ollama, sized to your RAM, one confirm)"),
("Manual", "(edit ov.conf directly)"),
],
default=1,
)
if mode == 1:
result, ollama_running = _wizard_two_step()
if result is _GO_BACK:
continue # back to the mode menu
if result is _CUSTOM_SETUP:
return 0
config_dict = result # type: ignore[assignment]
elif mode == 2:
config_dict, ollama_running = _wizard_ollama()
else:
_wizard_custom()
return 0
break
if config_dict is None:
print("\n Setup cancelled.\n")
return 0
_wizard_query_planner(config_dict, ollama_running)
server_dict = _wizard_server()
if server_dict is None:
print("\n Setup cancelled.\n")
return 0
config_dict["server"] = server_dict
config_dict["gateway"] = _wizard_gateway(server_dict)
# Summary — providers/models/dimensions are shown, secrets never are.
emb = config_dict.get("embedding", {}).get("dense", {})
vlm = config_dict.get("vlm", {})
_rule("Summary")
print(f" Embedding: {_summarize_model(emb)}")
if emb.get("model_path"):
print(" Model path: custom local model (hidden)")
print(f" VLM: {_summarize_model(vlm)}")
planner = config_dict.get("query_planner", {})
print(f" Query planner: {_summarize_model(planner)}")
print(f" Server: {_summarize_server(server_dict)}")
print(f" Gateway: {_summarize_gateway(config_dict['gateway'])}")
if server_dict.get("root_api_key"):
print(" Root API key: configured (hidden)")
print(" Workspace: configured (hidden)")
print(" Config: default config location")
if not _prompt_confirm("\n Save configuration?"):
print("\n Setup cancelled.\n")
return 0
# Write
if not _write_config(config_dict, config_path):
return 1
print(f" {_green('OK')} Configuration written to the default config location\n")
# Post-init tips
print(f" {_bold('Next steps:')}")
if emb.get("provider") == "local":
print(f" Install runtime: {_cyan(_PIP_LOCAL_EMBED)}")
print(f" Start the server: {_cyan('openviking-server')}")
print(f" Validate setup: {_cyan('openviking-server doctor')}")
print()
_post_save_actions()
return 0
def main() -> int:
"""Entry point for ``openviking-server init``."""
try:
return run_init()
except KeyboardInterrupt:
print("\n\n Setup cancelled.\n")
return 130