Personal AI, On Personal Devices
Python
docs: clarify CLI agent defaults and direct mode (#987)
Johnny C Wattc54525d28c90
diff --git a/docs/architecture/query-flow.md b/docs/architecture/query-flow.mdindex 0261de6e..87c127b9 100644--- a/docs/architecture/query-flow.md+++ b/docs/architecture/query-flow.md@@ -41,7 +41,7 @@ sequenceDiagramAGT->>CTX: inject_context(query, messages, backend)CTX-->>AGT: messages with context prepended- loop Tool-calling loop (max_turns)+ loop Inference (single turn for SimpleAgent; tool loop for tool-using agents)AGT->>ENG: generate(messages, model, tools)ENG-->>AGT: {content, tool_calls, usage}opt Tool calls present@@ -72,27 +72,39 @@ sequenceDiagramOpenJarvis supports two query processing paths, selected by the `--agent` CLI flag or the `agent` parameter in the SDK.-### Direct Mode (Default)+The CLI and SDK have different defaults:++- **CLI:** When `--agent` is omitted for a text query, `agent.default_agent` from configuration is used. Its default is `simple`. An empty configured default selects direct mode. Image and screen queries use direct mode automatically when `--agent` is omitted.+- **SDK:** Omitting `agent` (or passing `agent=None`) uses direct mode. The SDK does not fall back to `agent.default_agent`.++### Direct ModeIn direct mode, the query goes straight to the inference engine with optional memory context. This is the simplest path -- one inference call, no tool loop.```bash# CLI-jarvis ask "What is the capital of France?"+jarvis ask --agent "" "What is the capital of France?"+```-# SDK+```python+# SDK (direct mode is the default)j = Jarvis()response = j.ask("What is the capital of France?")```+Direct mode bypasses the agent's system prompt and persona handling. In the CLI, set `default_agent = ""` in the `[agent]` section of `~/.openjarvis/config.toml` to make this the default for text queries.+### Agent Mode-In agent mode, the query is handled by a named agent that can perform multiple inference rounds and invoke tools. The `OrchestratorAgent` is the most common choice, enabling a multi-turn tool-calling loop.+In agent mode, the query is handled by a named agent. The CLI's default `SimpleAgent` makes a single inference call without a tool loop, while applying the configured system prompt and persona files (`SOUL.md`, `MEMORY.md`, and `USER.md`). Agents such as `OrchestratorAgent` can perform multiple inference rounds and invoke tools.```bash# CLI+jarvis ask "Hello" # Uses SimpleAgent with the default configurationjarvis ask --agent orchestrator --tools calculator,think "What is 2^10 + 3^5?"+```+```python# SDKresponse = j.ask("What is 2^10 + 3^5?", agent="orchestrator", tools=["calculator"])```diff --git a/docs/user-guide/cli.md b/docs/user-guide/cli.mdindex 519c957c..eaad767e 100644--- a/docs/user-guide/cli.md+++ b/docs/user-guide/cli.md@@ -64,20 +64,20 @@ jarvis ask "What is the capital of France?"| `--json` | flag | off | Output raw JSON result instead of plain text || `--no-stream` | flag | off | Disable streaming (synchronous mode) || `--no-context` | flag | off | Disable memory context injection |-| `-a`, `--agent AGENT` | string | none | Agent to use (`simple`, `orchestrator`) |+| `-a`, `--agent AGENT` | string | config (`simple`) | Agent to use; `""` selects direct mode || `--tools TOOLS` | string | none | Comma-separated tool names to enable || `-i`, `--image PATH` | path | none | Image file for a vision model (e.g. `gemma3:4b`); repeatable || `-S`, `--screen` | flag | off | Capture the current screen and send it to the vision model |### Direct Mode vs Agent Mode-**Direct mode** (default) sends the query straight to the inference engine:+**Agent mode** is the default for text queries. When `--agent` is omitted, the CLI uses `agent.default_agent` from configuration, which defaults to `simple`. `SimpleAgent` makes a single inference call without a tool loop, while applying the configured system prompt and persona files (`SOUL.md`, `MEMORY.md`, and `USER.md`).```bashjarvis ask "Explain quantum computing"```-**Agent mode** routes the query through an agent that can use tools and manage multi-turn interactions:+Use `--agent` to select an agent explicitly. Agents such as `orchestrator` can use tools and manage multi-turn interactions:```bashjarvis ask --agent orchestrator "What is 2+2?"@@ -85,6 +85,14 @@ jarvis ask --agent orchestrator --tools calculator,think "Calculate sqrt(144) +jarvis ask --agent simple "Hello"```+**Direct mode** sends the query straight to the inference engine with optional memory context, bypassing the agent's system prompt and persona handling. Pass an empty agent name to select it:++```bash+jarvis ask --agent "" "Explain quantum computing"+```++To make direct mode the default, set `default_agent = ""` in the `[agent]` section of `~/.openjarvis/config.toml`.+### Usage Examples```bash@@ -124,7 +132,9 @@ jarvis ask -i chart-a.png -i chart-b.png "Compare these two charts"jarvis ask --screen "Summarize what's on my screen"```-Vision runs in **direct mode** only. If you also pass `--agent`, the image is+Vision runs in **direct mode** only. When `--agent` is omitted, image and screen+queries automatically use direct mode, overriding the configured default agent.+If you explicitly select an agent, the image isignored and a note is printed — re-run with `--agent ""` to force direct mode.The Ollama context window can be tuned for large images or long prompts with