Skip to content

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

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.md
index 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 resp
Optional 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.md
index 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.yaml
new file mode 100644
index 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.0
diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.py
index 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, Optional
from openviking.message import Message
from openviking.prompts import render_prompt
@@ -17,6 +17,22 @@ from openviking_cli.utils.logger import get_logger
logger = 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.py
index 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 Ollama
dense = 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", None
from 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}", None
diff --git a/openviking_cli/setup_wizard.py b/openviking_cli/setup_wizard.py
index 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 running
ollama_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_running
available_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_running
else:
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_running
available_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_running
vlm_model = _prompt_required_input("Vision Model")
vlm_api_base = provider.default_api_base
vlm_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 = None
if 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.py
index 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_PORT
uses_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, port
diff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.py
index 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 detail
assert 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.py
index 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.py
index 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 OpenVikingConfig
class RecordingModel:
- def __init__(self, response: str):
+ def __init__(self, response: str, model: str | None = None):
self.response = response
+ self.model = model
self.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.asyncio
async 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.asyncio
async 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.py
index 8fea27ccf..598f6f28a 100644
--- a/tests/unit/test_ollama_utils.py
+++ b/tests/unit/test_ollama_utils.py
@@ -5,18 +5,14 @@ from __future__ import annotations
from types import SimpleNamespace
from 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