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
feat(cli): add query planner setup to init wizard (#2485)
Guoxuter1c0bbcdf0eee
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 544e3e6b5..c119102d9 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -690,6 +690,8 @@ For OpenAI-compatible providers that return SSE (Server-Sent Events) format respOptional lightweight model for retrieval intent analysis and query planning. It uses the same configuration shape as `vlm`, but only affects `search()` intent analysis and query expansion. If `query_planner` is omitted or empty, OpenViking falls back to `vlm` for backward compatibility.+> In `openviking-server init` you can optionally enable a local lightweight query planner; the wizard pulls the Ollama model and writes the `query_planner` config for you. For recognized query-planner models, `search()` selects the matching bundled prompt at runtime. Models not in the mapping keep using `retrieval.intent_analysis`.+We recommend the local Ollama model [`guoxuter/ov_intent_analysis_sft:v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8). Fine-tuned from Qwen3.5-0.8B, it can be deployed locally and is well suited to letting a small model handle retrieval planning: for small talk, greetings, or turns where the context is already sufficient, it returns no queries to reduce unnecessary memory injection and token consumption; when retrieval is needed, it emits structured queries targeting `skill`, `resource`, and `memory`.Pull the model first and make sure the Ollama service is reachable:@@ -715,104 +717,7 @@ Then add the following to your OpenViking configuration:}```-> `v4_q8` produces more compact output with lower inference latency, but you also need to replace OpenViking's prompt file with the v4 prompt at `openviking/prompts/templates/retrieval/intent_analysis.yaml` to match the model's expected output schema.-> If you prefer not to modify the prompt file, you can keep using `v1_q8`, which is compatible with the current prompt: `ollama/guoxuter/ov_intent_analysis_sft:v1_q8`.--Replace `openviking/prompts/templates/retrieval/intent_analysis.yaml` with:--```yaml-metadata:- id: "retrieval.intent_analysis"- name: "Intent Analysis v4"- description: "v4 prompt for compact intent-analysis models that emit only queries."- version: "4.0.0"- language: "en"- category: "retrieval"--variables:- - name: "compression_summary"- type: "string"- description: "Session summary"- default: ""- required: false-- - name: "recent_messages"- type: "string"- description: "Recent conversation"- required: true-- - name: "current_message"- type: "string"- description: "Current message"- required: true-- - name: "context_type"- type: "string"- description: "Restricted context type (skill/resource/memory)"- default: ""- required: false-- - name: "target_abstract"- type: "string"- description: "Abstract of target directory"- default: ""- required: false--template: |- You are OpenViking's context query planner. Given the session context and the current message, decide what context information is missing and emit retrieval queries to fill the gap.-- ## Session Context-- ### Session Summary- {{ compression_summary }}-- ### Recent Conversation- {{ recent_messages }}-- ### Current Message- {{ current_message }}- {% if context_type %}-- ## Search Scope Constraints-- **Restricted Context Type**: {{ context_type }}- {% if target_abstract %}- **Target Directory Abstract**: {{ target_abstract }}- {% endif %}-- Only emit `{{ context_type }}` queries; do not generate other types.- {% endif %}-- External information takes priority over built-in knowledge - actively query for any missing context.-- ## Context Types-- - `skill` - executable capability (tool, function, API, automation). Query style: imperative starting with a verb.- - `resource` - knowledge artifact (doc, spec, guide, code, configuration). Query style: noun phrase.- - `memory` - user preference or agent execution experience.-- ## Procedure-- 1. Classify the task: operational tasks typically need skill+resource+memory; informational tasks typically need resource+memory; conversational small talk needs no query.- 2. Skip any context type already covered explicitly in the conversation.- 3. For each needed type, emit 1-5 concise retrievable queries with `priority` from 1 to 5.-- ## Output Format-- Output a single JSON object with exactly one top-level key:-- - `queries`: array of objects with:- - `query`: actual query text- - `context_type`: one of `skill`, `resource`, `memory`- - `priority`: integer from 1 to 5-- If no query is needed, set `queries` to an empty array `[]`.-- Output the JSON object directly. Do not wrap it in markdown code fences.--llm_config:- temperature: 0.0-```+For `ollama/guoxuter/ov_intent_analysis_sft:v4_q8`, OpenViking automatically uses the bundled `retrieval.ov_intent_analysis_sft_v4` prompt during search. No prompt file replacement or `prompts.templates_dir` override is required. If you use an unmapped model, OpenViking keeps the default `retrieval.intent_analysis` prompt; `v1_q8` remains compatible with that default.This lets a small model handle retrieval planning with lower latency, while keeping a stronger `vlm` for semantic extraction, memory extraction, and multimodal processing.diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex af6a86ff2..e1b68c833 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -660,6 +660,8 @@ LiteLLM 的 Bedrock bearer-token API-key 鉴权,请设置 `forward_api_key=tru可选的轻量模型配置,用于检索前的意图分析和 query 规划/改写。配置结构与 `vlm` 相同,但只影响 `search()` 的意图分析和 query expansion。未配置或配置为空时,OpenViking 会回退到 `vlm`,保持向后兼容。+> 在 `openviking-server init` 里可勾选启用本地轻量 query planner,向导会自动拉取 Ollama 模型并写入 `query_planner` 配置。对于已知的 query planner 模型,`search()` 会在运行时自动选择匹配的内置 prompt;不在映射表中的模型继续使用 `retrieval.intent_analysis`。+推荐优先使用本地 Ollama 模型 [`guoxuter/ov_intent_analysis_sft:v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8)。该模型基于 Qwen3.5-0.8B 进行微调,可本地部署,适合用小模型承担检索规划:在闲聊、问候或上下文已足够的场景下拒绝检索,从而减少不必要的记忆注入和 token 消耗;需要检索时,再生成面向 `skill`、`resource`、`memory` 的结构化查询。使用前请先拉取模型,并确保 Ollama 服务可访问:@@ -685,104 +687,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v4_q8}```-> `v4_q8` 输出更紧凑、推理时延更低,但需要同步将 OpenViking 的 prompt 文件替换为 v4 prompt:`openviking/prompts/templates/retrieval/intent_analysis.yaml`,以匹配该模型期望的输出格式。-> 如果不想修改 prompt 文件,可以继续使用兼容当前 prompt 的 `v1_q8`:`ollama/guoxuter/ov_intent_analysis_sft:v1_q8`。--将 `openviking/prompts/templates/retrieval/intent_analysis.yaml` 替换为:--```yaml-metadata:- id: "retrieval.intent_analysis"- name: "Intent Analysis v4"- description: "v4 prompt for compact intent-analysis models that emit only queries."- version: "4.0.0"- language: "en"- category: "retrieval"--variables:- - name: "compression_summary"- type: "string"- description: "Session summary"- default: ""- required: false-- - name: "recent_messages"- type: "string"- description: "Recent conversation"- required: true-- - name: "current_message"- type: "string"- description: "Current message"- required: true-- - name: "context_type"- type: "string"- description: "Restricted context type (skill/resource/memory)"- default: ""- required: false-- - name: "target_abstract"- type: "string"- description: "Abstract of target directory"- default: ""- required: false--template: |- You are OpenViking's context query planner. Given the session context and the current message, decide what context information is missing and emit retrieval queries to fill the gap.-- ## Session Context-- ### Session Summary- {{ compression_summary }}-- ### Recent Conversation- {{ recent_messages }}-- ### Current Message- {{ current_message }}- {% if context_type %}-- ## Search Scope Constraints-- **Restricted Context Type**: {{ context_type }}- {% if target_abstract %}- **Target Directory Abstract**: {{ target_abstract }}- {% endif %}-- Only emit `{{ context_type }}` queries; do not generate other types.- {% endif %}-- External information takes priority over built-in knowledge - actively query for any missing context.-- ## Context Types-- - `skill` - executable capability (tool, function, API, automation). Query style: imperative starting with a verb.- - `resource` - knowledge artifact (doc, spec, guide, code, configuration). Query style: noun phrase.- - `memory` - user preference or agent execution experience.-- ## Procedure-- 1. Classify the task: operational tasks typically need skill+resource+memory; informational tasks typically need resource+memory; conversational small talk needs no query.- 2. Skip any context type already covered explicitly in the conversation.- 3. For each needed type, emit 1-5 concise retrievable queries with `priority` from 1 to 5.-- ## Output Format-- Output a single JSON object with exactly one top-level key:-- - `queries`: array of objects with:- - `query`: actual query text- - `context_type`: one of `skill`, `resource`, `memory`- - `priority`: integer from 1 to 5-- If no query is needed, set `queries` to an empty array `[]`.-- Output the JSON object directly. Do not wrap it in markdown code fences.--llm_config:- temperature: 0.0-```+对于 `ollama/guoxuter/ov_intent_analysis_sft:v4_q8`,OpenViking 会在 search 阶段自动使用内置的 `retrieval.ov_intent_analysis_sft_v4` prompt,不需要替换 prompt 文件,也不需要设置 `prompts.templates_dir`。如果使用未映射的模型,OpenViking 会继续使用默认的 `retrieval.intent_analysis` prompt;`v1_q8` 与该默认 prompt 兼容。这样可以用小模型承担检索规划,降低延迟,同时保留更强的 `vlm` 处理语义提取、记忆提取和多模态内容。diff --git a/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v4.yaml b/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v4.yamlnew file mode 100644index 000000000..27ac21027--- /dev/null+++ b/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v4.yaml@@ -0,0 +1,93 @@+metadata:+ # Loaded directly through the query-planner model -> prompt mapping in+ # openviking.retrieve.intent_analyzer.+ id: "retrieval.ov_intent_analysis_sft_v4"+ name: "Intent Analysis v4"+ description: "v4 prompt for compact intent-analysis models that emit only queries."+ version: "4.0.0"+ language: "en"+ category: "retrieval"++variables:+ - name: "compression_summary"+ type: "string"+ description: "Session summary"+ default: ""+ required: false++ - name: "recent_messages"+ type: "string"+ description: "Recent conversation"+ required: true++ - name: "current_message"+ type: "string"+ description: "Current message"+ required: true++ - name: "context_type"+ type: "string"+ description: "Restricted context type (skill/resource/memory)"+ default: ""+ required: false++ - name: "target_abstract"+ type: "string"+ description: "Abstract of target directory"+ default: ""+ required: false++template: |+ You are OpenViking's context query planner. Given the session context and the current message, decide what context information is missing and emit retrieval queries to fill the gap.++ ## Session Context++ ### Session Summary+ {{ compression_summary }}++ ### Recent Conversation+ {{ recent_messages }}++ ### Current Message+ {{ current_message }}+ {% if context_type %}++ ## Search Scope Constraints++ **Restricted Context Type**: {{ context_type }}+ {% if target_abstract %}+ **Target Directory Abstract**: {{ target_abstract }}+ {% endif %}++ Only emit `{{ context_type }}` queries; do not generate other types.+ {% endif %}++ External information takes priority over built-in knowledge - actively query for any missing context.++ ## Context Types++ - `skill` - executable capability (tool, function, API, automation). Query style: imperative starting with a verb.+ - `resource` - knowledge artifact (doc, spec, guide, code, configuration). Query style: noun phrase.+ - `memory` - user preference or agent execution experience.++ ## Procedure++ 1. Classify the task: operational tasks typically need skill+resource+memory; informational tasks typically need resource+memory; conversational small talk needs no query.+ 2. Skip any context type already covered explicitly in the conversation.+ 3. For each needed type, emit 1-5 concise retrievable queries with `priority` from 1 to 5.++ ## Output Format++ Output a single JSON object with exactly one top-level key:++ - `queries`: array of objects with:+ - `query`: actual query text+ - `context_type`: one of `skill`, `resource`, `memory`+ - `priority`: integer from 1 to 5++ If no query is needed, set `queries` to an empty array `[]`.++ Output the JSON object directly. Do not wrap it in markdown code fences.++llm_config:+ temperature: 0.0diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.pyindex 007832e25..af6498485 100644--- a/openviking/retrieve/intent_analyzer.py+++ b/openviking/retrieve/intent_analyzer.py@@ -6,7 +6,7 @@ Intent analyzer for OpenViking retrieval.Analyzes session context to generate query plans."""-from typing import List, Optional+from typing import Any, List, Optionalfrom openviking.message import Messagefrom openviking.prompts import render_prompt@@ -17,6 +17,22 @@ from openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)+DEFAULT_INTENT_ANALYSIS_PROMPT = "retrieval.intent_analysis"++# Model-specific query-planner prompts. Models not listed here keep using the+# default intent-analysis prompt for backward compatibility.+QUERY_PLANNER_PROMPT_BY_MODEL: dict[str, str] = {+ "ollama/guoxuter/ov_intent_analysis_sft:v4_q8": "retrieval.ov_intent_analysis_sft_v4",+}+++def resolve_intent_analysis_prompt_id(query_planner: Any) -> str:+ """Return the prompt id expected by the configured query-planner model."""+ model = getattr(query_planner, "model", None)+ if not isinstance(model, str):+ return DEFAULT_INTENT_ANALYSIS_PROMPT+ return QUERY_PLANNER_PROMPT_BY_MODEL.get(model.strip(), DEFAULT_INTENT_ANALYSIS_PROMPT)+class IntentAnalyzer:"""@@ -52,18 +68,21 @@ class IntentAnalyzer:context_type: Constrained context type (only generate queries for this type)target_abstract: Target directory abstract for more precise queries"""- # Build context prompt+ # Call the lightweight query planner when configured; otherwise keep using VLM.+ config = get_openviking_config()+ query_planner = config.get_query_planner()++ # Build context prompt. Some fine-tuned planner models expect a compact+ # prompt/output contract, selected by exact model mapping above.prompt = self._build_context_prompt(compression_summary,messages,current_message,context_type,target_abstract,+ prompt_id=resolve_intent_analysis_prompt_id(query_planner),)- # Call the lightweight query planner when configured; otherwise keep using VLM.- config = get_openviking_config()- query_planner = config.get_query_planner()response = await query_planner.get_completion_async(prompt)# Parse result@@ -108,6 +127,7 @@ class IntentAnalyzer:current_message: Optional[str],context_type: Optional[ContextType] = None,target_abstract: str = "",+ prompt_id: str = DEFAULT_INTENT_ANALYSIS_PROMPT,) -> str:"""Build prompt for intent analysis."""# Format compression info@@ -124,7 +144,7 @@ class IntentAnalyzer:current = current_message if current_message else "None"return render_prompt(- "retrieval.intent_analysis",+ prompt_id,{"compression_summary": summary,"recent_messages": recent_messages,diff --git a/openviking_cli/doctor.py b/openviking_cli/doctor.pyindex 457ce67ac..e3db3c119 100644--- a/openviking_cli/doctor.py+++ b/openviking_cli/doctor.py@@ -369,19 +369,25 @@ def check_ollama() -> tuple[bool, str, Optional[str]]:# Detect whether config uses Ollamadense = data.get("embedding", {}).get("dense", {})vlm = data.get("vlm", {})+ query_planner = data.get("query_planner") or {}uses_embedding = dense.get("provider") == "ollama"uses_vlm = vlm.get("provider") == "litellm" and (vlm.get("model", "")).startswith("ollama/")+ uses_query_planner = query_planner.get("provider") == "litellm" and (+ query_planner.get("model", "")+ ).startswith("ollama/")- if not uses_embedding and not uses_vlm:+ if not uses_embedding and not uses_vlm and not uses_query_planner:return True, "not configured", Nonefrom openviking_cli.utils.ollama import check_ollama_running, parse_ollama_url- # Determine host/port from config+ # Determine host/port from config (embedding -> vlm -> query_planner)if uses_embedding:host, port = parse_ollama_url(dense.get("api_base"))- else:+ elif uses_vlm:host, port = parse_ollama_url(vlm.get("api_base"))+ else:+ host, port = parse_ollama_url(query_planner.get("api_base"))if check_ollama_running(host, port):return True, f"running at {host}:{port}", Nonediff --git a/openviking_cli/setup_wizard.py b/openviking_cli/setup_wizard.pyindex cd3cbef58..594208ac7 100644--- a/openviking_cli/setup_wizard.py+++ b/openviking_cli/setup_wizard.py@@ -372,6 +372,14 @@ class VLMPreset: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),@@ -392,6 +400,24 @@ VLM_PRESETS: list[VLMPreset] = [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 v4_q8",+ "guoxuter/ov_intent_analysis_sft:v4_q8",+ "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "~0.8B, recommended",+ ),+ QueryPlannerPreset(+ "ov_intent_analysis_sft v1_q8",+ "guoxuter/ov_intent_analysis_sft:v1_q8",+ "ollama/guoxuter/ov_intent_analysis_sft:v1_q8",+ "~0.8B, compatible with the bundled prompt",+ ),+]+# Recommended defaults indexed by RAM tier_RAM_TIERS: list[tuple[int, int, int]] = [# (max_ram_gb, embedding_preset_index, vlm_preset_index)@@ -632,6 +658,24 @@ def _build_cloud_config(}+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# ---------------------------------------------------------------------------@@ -687,8 +731,12 @@ def _write_config(config_dict: dict[str, Any], config_path: Path) -> bool:# ----------------------------------------------------------------------------def _wizard_ollama() -> dict[str, Any] | None:- """Ollama-based local model setup flow."""+def _wizard_ollama() -> tuple[dict[str, Any] | None, bool]:+ """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 runningollama_running = _ensure_ollama()@@ -697,7 +745,7 @@ def _wizard_ollama() -> dict[str, Any] | None:"Continue without Ollama? (config will be generated but models won't be pulled)",default=False,):- return None+ return None, ollama_runningavailable_models = get_ollama_models() if ollama_running else []@@ -763,11 +811,20 @@ def _wizard_ollama() -> dict[str, Any] | None:else:print(f" {_green('OK')} {vlm.ollama_model} pulled successfully")- return _build_ollama_config(embedding, vlm, _workspace_path())+ return _build_ollama_config(embedding, vlm, _workspace_path()), ollama_running++def _wizard_llamacpp() -> tuple[dict[str, Any] | None, bool | None]:+ """llama.cpp local embedding setup flow.++ Returns ``(config, ollama_running)``. ``ollama_running`` is ``None`` when the+ flow never touched Ollama (cloud or skipped VLM), so the query-planner step+ knows it still has to run the install flow itself.+ """+ # Ollama is only involved if the user picks an Ollama VLM below; None means+ # "not handled yet" so downstream steps can decide whether to ensure it.+ ollama_running: bool | None = None-def _wizard_llamacpp() -> dict[str, Any] | None:- """llama.cpp local embedding setup flow."""# --- Step 1: check / install llama-cpp-python ---print("\n Checking llama-cpp-python...", end=" ", flush=True)@@ -786,11 +843,11 @@ def _wizard_llamacpp() -> dict[str, Any] | None:if not _prompt_confirm("Continue anyway? (config will be generated)", default=False):- return None+ return None, ollama_runningelse:print(f"\n {_dim('Install later: ' + _PIP_LOCAL_EMBED)}")if not _prompt_confirm("Continue anyway? (config will be generated)", default=False):- return None+ return None, ollama_running# --- Step 2: select embedding model ---model_options: list[tuple[str, str]] = []@@ -879,7 +936,7 @@ def _wizard_llamacpp() -> dict[str, Any] | None:ollama_running = _ensure_ollama()if not ollama_running:if not _prompt_confirm("Continue without Ollama?", default=False):- return None+ return None, ollama_runningavailable_models = get_ollama_models() if ollama_running else []ram_gb = _get_system_ram_gb()@@ -932,7 +989,7 @@ def _wizard_llamacpp() -> dict[str, Any] | None:vlm_api_key = _prompt_api_key("VLM API Key")if not vlm_api_key:print(f" {_red('API key is required')}")- return None+ return None, ollama_runningvlm_model = _prompt_required_input("Vision Model")vlm_api_base = provider.default_api_basevlm_provider = provider.provider@@ -947,12 +1004,15 @@ def _wizard_llamacpp() -> dict[str, Any] | None:if vlm_api_key:vlm_config["api_key"] = vlm_api_key- return _build_local_config(- model_name=model_name,- dimension=dimension,- workspace=_workspace_path(),- model_path=custom_model_path,- vlm_config=vlm_config,+ return (+ _build_local_config(+ model_name=model_name,+ dimension=dimension,+ workspace=_workspace_path(),+ model_path=custom_model_path,+ vlm_config=vlm_config,+ ),+ ollama_running,)@@ -1090,6 +1150,59 @@ def _wizard_server() -> dict[str, Any] | None:return {"host": "0.0.0.0", "root_api_key": root_api_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.+ """+ print(f"\n {_bold('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]++ if ollama_running and not is_model_available(preset.ollama_model, available_models):+ if _prompt_confirm(f"'{preset.ollama_model}' not found locally. Pull now?"):+ print()+ if not ollama_pull_model(preset.ollama_model):+ pull_hint = "Pull failed. You can pull it later: ollama pull "+ print(f" {_yellow(pull_hint + preset.ollama_model)}")+ else:+ print(f" {_green('OK')} {preset.ollama_model} pulled successfully")++ 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()@@ -1148,13 +1261,17 @@ def run_init() -> int:)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 = Noneif mode == 1:config_dict = _wizard_cloud()elif mode == 2:- config_dict = _wizard_llamacpp()+ config_dict, ollama_running = _wizard_llamacpp()elif mode == 3:- config_dict = _wizard_ollama()+ config_dict, ollama_running = _wizard_ollama()else:_wizard_custom()return 0@@ -1163,6 +1280,8 @@ def run_init() -> int: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")@@ -1179,6 +1298,7 @@ def run_init() -> int:print(" Model path: custom local model (hidden)")vlm_summary = _configured_hint(bool(vlm))print(f" VLM: {vlm_summary}")+ print(f" Query planner: {_configured_hint(bool(config_dict.get('query_planner')))}")print(f" Server: bound to {server_dict['host']}")if server_dict.get("root_api_key"):print(" Root API key: configured (hidden)")diff --git a/openviking_cli/utils/ollama.py b/openviking_cli/utils/ollama.pyindex 11655e1ea..a15e15249 100644--- a/openviking_cli/utils/ollama.py+++ b/openviking_cli/utils/ollama.py@@ -226,6 +226,11 @@ def detect_ollama_in_config(config) -> tuple[bool, str, int]:Detection rules:- ``embedding.dense.provider == "ollama"``- ``vlm.provider == "litellm"`` **and** ``vlm.model`` starts with ``"ollama/"``+ - ``query_planner.provider == "litellm"`` **and** ``query_planner.model``+ starts with ``"ollama/"``++ When several sections use Ollama, the host/port is taken from the first+ match in the order embedding -> vlm -> query_planner."""host, port = OLLAMA_DEFAULT_HOST, OLLAMA_DEFAULT_PORTuses_ollama = False@@ -249,6 +254,18 @@ def detect_ollama_in_config(config) -> tuple[bool, str, int]:host, port = parse_ollama_url(api_base)uses_ollama = True+ # Check query planner (optional lightweight model for intent analysis)+ query_planner = getattr(config, "query_planner", None)+ if query_planner is not None:+ qp_provider = getattr(query_planner, "provider", None)+ qp_model = getattr(query_planner, "model", None) or ""+ if qp_provider == "litellm" and qp_model.startswith("ollama/"):+ if not uses_ollama:+ # Only use the planner's URL if nothing earlier set it+ api_base = getattr(query_planner, "api_base", None)+ host, port = parse_ollama_url(api_base)+ uses_ollama = True+return uses_ollama, host, portdiff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.pyindex fee08cdd0..684cf0676 100644--- a/tests/cli/test_doctor.py+++ b/tests/cli/test_doctor.py@@ -651,6 +651,53 @@ class TestCheckOllama:assert "vlm-host:11436" in detailassert fix is None+ def test_checks_query_planner_ollama_api_base(self, tmp_path: Path):+ config = tmp_path / "ov.conf"+ config.write_text(+ json.dumps(+ {+ "embedding": {+ "dense": {"provider": "openai", "model": "text-embedding-3-small"}+ },+ "vlm": {"provider": "openai", "model": "gpt-4o-mini"},+ "query_planner": {+ "provider": "litellm",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "api_base": "http://planner-host:11437",+ },+ }+ )+ )+ with patch("openviking_cli.doctor._find_config", return_value=config):+ with patch(+ "openviking_cli.utils.ollama.check_ollama_running", return_value=True+ ) as running:+ ok, detail, fix = check_ollama()+ running.assert_called_once_with("planner-host", 11437)+ assert ok+ assert "planner-host:11437" in detail+ assert fix is None++ def test_fails_when_query_planner_ollama_is_unreachable(self, tmp_path: Path):+ config = tmp_path / "ov.conf"+ config.write_text(+ json.dumps(+ {+ "query_planner": {+ "provider": "litellm",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "api_base": "http://localhost:11434",+ }+ }+ )+ )+ with patch("openviking_cli.doctor._find_config", return_value=config):+ with patch("openviking_cli.utils.ollama.check_ollama_running", return_value=False):+ ok, detail, fix = check_ollama()+ assert not ok+ assert "unreachable at localhost:11434" in detail+ assert "ollama serve" in fix+def test_fails_when_configured_ollama_is_unreachable(self, tmp_path: Path):config = tmp_path / "ov.conf"config.write_text(diff --git a/tests/cli/test_setup_wizard.py b/tests/cli/test_setup_wizard.pyindex a7741b6fc..21510ee9a 100644--- a/tests/cli/test_setup_wizard.py+++ b/tests/cli/test_setup_wizard.py@@ -13,10 +13,12 @@ from openviking_cli.setup_wizard import (CLOUD_PROVIDERS,EMBEDDING_PRESETS,LOCAL_GGUF_PRESETS,+ QUERY_PLANNER_PRESETS,VLM_PRESETS,_build_cloud_config,_build_local_config,_build_ollama_config,+ _build_query_planner_config,_config_path,_get_recommended_indices,_is_llamacpp_installed,@@ -27,6 +29,7 @@ from openviking_cli.setup_wizard import (_prompt_required_input,_prompt_required_int,_wizard_cloud,+ _wizard_query_planner,_wizard_server,_workspace_path,_write_config,@@ -464,6 +467,128 @@ class TestConfigBuilding:assert config["embedding"]["dense"]["dimension"] > 0+# ---------------------------------------------------------------------------+# Query planner+# ---------------------------------------------------------------------------+++class TestQueryPlanner:+ def test_build_query_planner_config_structure(self):+ preset = QUERY_PLANNER_PRESETS[0] # v4_q8+ config = _build_query_planner_config(preset)+ assert config["provider"] == "litellm"+ assert config["model"] == preset.litellm_model+ assert config["model"].startswith("ollama/")+ # litellm Ollama base URL must not carry the /v1 suffix+ assert config["api_base"] == "http://localhost:11434"+ assert config["temperature"] == 0.0+ assert config["extra_request_body"] == {"think": False}++ def test_presets_have_litellm_models(self):+ assert all(p.litellm_model.startswith("ollama/") for p in QUERY_PLANNER_PRESETS)++ def test_wizard_enables_v4_sets_planner_without_prompt_override(self, tmp_path):+ # Prompt selection happens at retrieval time from the configured model;+ # the wizard must not write a prompt override or prompts.templates_dir.+ config_dict: dict = {"embedding": {}, "vlm": {}}+ config_path = tmp_path / "ov.conf"+ with (+ patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),+ patch("openviking_cli.setup_wizard.get_ollama_models", return_value=[]),+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=1), # v4_q8+ patch("openviking_cli.setup_wizard.is_model_available", return_value=True),+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=True)++ assert config_dict["query_planner"]["model"] == QUERY_PLANNER_PRESETS[0].litellm_model+ assert config_dict["query_planner"]["api_base"] == "http://localhost:11434"+ assert "prompts" not in config_dict+ assert not (config_path.parent / "prompts").exists()++ def test_wizard_v1_sets_planner_and_returns_none(self, tmp_path):+ config_dict: dict = {"embedding": {}, "vlm": {}}+ config_path = tmp_path / "ov.conf"+ with (+ patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),+ patch("openviking_cli.setup_wizard.get_ollama_models", return_value=[]),+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=2), # v1_q8+ patch("openviking_cli.setup_wizard.is_model_available", return_value=True),+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=True)++ assert config_dict["query_planner"]["model"] == QUERY_PLANNER_PRESETS[1].litellm_model+ assert "prompts" not in config_dict++ def test_wizard_declined_leaves_config_untouched(self, tmp_path):+ # With an Ollama VLM present, the planner is offered; declining the+ # enable prompt must leave the config untouched.+ config_dict: dict = {"embedding": {}, "vlm": {}}+ with (+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=False),+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=True)+ assert "query_planner" not in config_dict+ assert "prompts" not in config_dict++ def test_wizard_no_ollama_vlm_defaults_to_no_without_recommend(self, tmp_path):+ # Cloud / non-Ollama-VLM setups (ollama_running is None) are still offered+ # the planner, but off by default and without the recommendation tag.+ config_dict: dict = {"embedding": {}, "vlm": {}}+ with (+ patch(+ "openviking_cli.setup_wizard._prompt_confirm", return_value=False+ ) as mock_confirm,+ patch("openviking_cli.setup_wizard._ensure_ollama") as mock_ensure,+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=None)++ enable_call = mock_confirm.call_args_list[0]+ assert enable_call.kwargs.get("default") is False+ assert "(recommended)" not in enable_call.args[0]+ mock_ensure.assert_not_called() # declined before reaching install+ assert "query_planner" not in config_dict++ def test_wizard_no_ollama_vlm_opt_in_runs_install(self, tmp_path):+ # Opting in without an Ollama VLM runs the Ollama install flow.+ config_dict: dict = {"embedding": {}, "vlm": {}}+ with (+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),+ patch("openviking_cli.setup_wizard._ensure_ollama", return_value=True) as mock_ensure,+ patch("openviking_cli.setup_wizard.get_ollama_models", return_value=[]),+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=1),+ patch("openviking_cli.setup_wizard.is_model_available", return_value=True),+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=None)++ mock_ensure.assert_called_once()+ assert config_dict["query_planner"]["model"] == QUERY_PLANNER_PRESETS[0].litellm_model++ def test_wizard_ollama_vlm_defaults_to_yes_with_recommend(self, tmp_path):+ # With an Ollama VLM present (ollama_running is not None) the planner is+ # recommended, so the enable prompt is tagged and defaults to Yes.+ config_dict: dict = {"embedding": {}, "vlm": {}}+ with (+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True) as mock_confirm,+ patch("openviking_cli.setup_wizard.get_ollama_models", return_value=[]),+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=1),+ patch("openviking_cli.setup_wizard.is_model_available", return_value=True),+ patch("builtins.print"),+ ):+ _wizard_query_planner(config_dict, ollama_running=True)++ enable_call = mock_confirm.call_args_list[0]+ assert enable_call.kwargs.get("default") is True+ assert "(recommended)" in enable_call.args[0]+ assert config_dict["query_planner"]["model"] == QUERY_PLANNER_PRESETS[0].litellm_model++# ---------------------------------------------------------------------------# RAM-based recommendations# ---------------------------------------------------------------------------@@ -546,7 +671,8 @@ class TestConfigWriting:with (patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),patch("openviking_cli.setup_wizard._prompt_choice", return_value=3),- patch("openviking_cli.setup_wizard._wizard_ollama", return_value=config),+ patch("openviking_cli.setup_wizard._wizard_ollama", return_value=(config, True)),+ patch("openviking_cli.setup_wizard._wizard_query_planner", return_value=None),patch("openviking_cli.setup_wizard._wizard_server",return_value={"host": "127.0.0.1"},@@ -581,7 +707,8 @@ class TestConfigWriting:with (patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),patch("openviking_cli.setup_wizard._prompt_choice", return_value=3),- patch("openviking_cli.setup_wizard._wizard_ollama", return_value=config),+ patch("openviking_cli.setup_wizard._wizard_ollama", return_value=(config, True)),+ patch("openviking_cli.setup_wizard._wizard_query_planner", return_value=None),patch("openviking_cli.setup_wizard._wizard_server",return_value={"host": "127.0.0.1"},diff --git a/tests/retrieve/test_intent_analyzer_query_planner.py b/tests/retrieve/test_intent_analyzer_query_planner.pyindex ad31b7832..8e9e47d3e 100644--- a/tests/retrieve/test_intent_analyzer_query_planner.py+++ b/tests/retrieve/test_intent_analyzer_query_planner.py@@ -8,8 +8,9 @@ from openviking_cli.utils.config.open_viking_config import OpenVikingConfigclass RecordingModel:- def __init__(self, response: str):+ def __init__(self, response: str, model: str | None = None):self.response = response+ self.model = modelself.prompts: list[str] = []async def get_completion_async(self, prompt: str):@@ -58,6 +59,27 @@ def test_openviking_config_uses_vlm_when_query_planner_is_absent_or_empty():assert empty_config.get_query_planner() is empty_config.vlm+def test_query_planner_prompt_mapping_defaults_for_unknown_models():+ assert (+ intent_module.resolve_intent_analysis_prompt_id(+ SimpleNamespace(model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8")+ )+ == "retrieval.ov_intent_analysis_sft_v4"+ )+ assert (+ intent_module.resolve_intent_analysis_prompt_id(SimpleNamespace(model="ollama/qwen3.5:4b"))+ == intent_module.DEFAULT_INTENT_ANALYSIS_PROMPT+ )+++def test_query_planner_prompt_mapping_targets_are_bundled():+ from openviking.prompts.manager import PromptManager++ manager = PromptManager(templates_dir=PromptManager._get_bundled_templates_dir())+ for prompt_id in intent_module.QUERY_PLANNER_PROMPT_BY_MODEL.values():+ assert manager.load_template(prompt_id).metadata.id == prompt_id++@pytest.mark.asyncioasync def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):planner = RecordingModel(_query_plan_response("planned query"))@@ -65,6 +87,7 @@ async def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):config = SimpleNamespace(get_query_planner=lambda: planner)monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)+ monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")result = await IntentAnalyzer().analyze(compression_summary="",@@ -77,12 +100,63 @@ async def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):assert vlm.prompts == []+async def test_intent_analyzer_uses_model_specific_prompt(monkeypatch):+ planner = RecordingModel(+ _query_plan_response("planned query"),+ model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ )+ config = SimpleNamespace(get_query_planner=lambda: planner)+ rendered: list[str] = []++ def fake_render_prompt(prompt_id, variables):+ rendered.append(prompt_id)+ return "rendered prompt"++ monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)+ monkeypatch.setattr(intent_module, "render_prompt", fake_render_prompt)++ result = await IntentAnalyzer().analyze(+ compression_summary="",+ messages=[],+ current_message="where is my preference?",+ )++ assert result.queries[0].query == "planned query"+ assert rendered == ["retrieval.ov_intent_analysis_sft_v4"]+ assert planner.prompts == ["rendered prompt"]+++async def test_intent_analyzer_keeps_default_prompt_for_unmapped_model(monkeypatch):+ planner = RecordingModel(_query_plan_response("planned query"), model="ollama/qwen3.5:4b")+ config = SimpleNamespace(get_query_planner=lambda: planner)+ rendered: list[str] = []++ def fake_render_prompt(prompt_id, variables):+ rendered.append(prompt_id)+ return "rendered prompt"++ monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)+ monkeypatch.setattr(intent_module, "render_prompt", fake_render_prompt)++ result = await IntentAnalyzer().analyze(+ compression_summary="",+ messages=[],+ current_message="where is my preference?",+ )++ assert result.queries[0].query == "planned query"+ assert rendered == [intent_module.DEFAULT_INTENT_ANALYSIS_PROMPT]++@pytest.mark.asyncioasync def test_intent_analyzer_falls_back_to_vlm_without_query_planner(monkeypatch):vlm = RecordingModel(_query_plan_response("vlm query"))config = SimpleNamespace(get_query_planner=lambda: vlm)monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)+ monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")result = await IntentAnalyzer().analyze(compression_summary="",diff --git a/tests/unit/test_ollama_utils.py b/tests/unit/test_ollama_utils.pyindex 8fea27ccf..598f6f28a 100644--- a/tests/unit/test_ollama_utils.py+++ b/tests/unit/test_ollama_utils.py@@ -5,18 +5,14 @@ from __future__ import annotationsfrom types import SimpleNamespacefrom unittest.mock import MagicMock, patch-import pytest-from openviking_cli.utils.ollama import (OllamaStartResult,- check_ollama_running,detect_ollama_in_config,ensure_ollama_for_server,parse_ollama_url,start_ollama,)-# ---------------------------------------------------------------------------# parse_ollama_url# ---------------------------------------------------------------------------@@ -53,12 +49,22 @@ def _make_config(vlm_provider="volcengine",vlm_model="doubao-seed",vlm_api_base=None,+ query_planner_provider=None,+ query_planner_model=None,+ query_planner_api_base=None,):"""Build a minimal config-like object for detect_ollama_in_config."""dense = SimpleNamespace(provider=embedding_provider, api_base=embedding_api_base)embedding = SimpleNamespace(dense=dense)vlm = SimpleNamespace(provider=vlm_provider, model=vlm_model, api_base=vlm_api_base)- return SimpleNamespace(embedding=embedding, vlm=vlm)+ query_planner = None+ if query_planner_provider is not None or query_planner_model is not None:+ query_planner = SimpleNamespace(+ provider=query_planner_provider,+ model=query_planner_model,+ api_base=query_planner_api_base,+ )+ return SimpleNamespace(embedding=embedding, vlm=vlm, query_planner=query_planner)class TestDetectOllamaInConfig:@@ -115,6 +121,48 @@ class TestDetectOllamaInConfig:assert host == "192.168.1.50"assert port == 8080+ def test_query_planner_ollama_detected(self):+ config = _make_config(+ query_planner_provider="litellm",+ query_planner_model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ query_planner_api_base="http://127.0.0.1:11434",+ )+ uses, host, port = detect_ollama_in_config(config)+ assert uses is True+ assert host == "127.0.0.1"+ assert port == 11434++ def test_query_planner_custom_api_base(self):+ config = _make_config(+ query_planner_provider="litellm",+ query_planner_model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ query_planner_api_base="http://gpu-host:9999",+ )+ uses, host, port = detect_ollama_in_config(config)+ assert uses is True+ assert host == "gpu-host"+ assert port == 9999++ def test_query_planner_litellm_non_ollama_model(self):+ config = _make_config(+ query_planner_provider="litellm",+ query_planner_model="anthropic/claude-3",+ )+ uses, _, _ = detect_ollama_in_config(config)+ assert uses is False++ def test_embedding_takes_priority_over_query_planner(self):+ config = _make_config(+ embedding_provider="ollama",+ embedding_api_base="http://gpu-server:11434/v1",+ query_planner_provider="litellm",+ query_planner_model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ query_planner_api_base="http://localhost:11434",+ )+ uses, host, port = detect_ollama_in_config(config)+ assert uses is True+ assert host == "gpu-server" # embedding takes priority+# ---------------------------------------------------------------------------# ensure_ollama_for_server