code-puppy 0.0.562__tar.gz → 0.0.563__tar.gz

{code_puppy-0.0.562 → code_puppy-0.0.563}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-puppy
-Version: 0.0.562
+Version: 0.0.563
 Summary: Code generation agent
 Project-URL: repository, https://github.com/mpfaffenberger/code_puppy
 Project-URL: HomePage, https://github.com/mpfaffenberger/code_puppy

{code_puppy-0.0.562 → code_puppy-0.0.563}/code_puppy/agents/event_stream_handler.py

@@ -25,7 +25,12 @@ from code_puppy.agents.smooth_stream import (
     make_smooth_termflow_writer,
     make_thinking_smoother,
 )
-from code_puppy.config import get_banner_color, get_subagent_verbose
+from code_puppy.config import (
+    get_banner_color,
+    get_output_level,
+    get_subagent_verbose,
+    get_suppress_thinking_messages,
+)
 from code_puppy.messaging.spinner import pause_all_spinners, resume_all_spinners
 from code_puppy.tools.subagent_context import is_subagent
 
@@ -86,12 +91,41 @@ def get_streaming_console() -> Console:
 def _should_suppress_output() -> bool:
     """Check if sub-agent output should be suppressed.
 
+    In ``high`` output mode, sub-agent output is never suppressed.
+
     Returns:
         True if we're in a sub-agent context and verbose mode is disabled.
     """
+    if get_output_level() == "high":
+        return False
     return is_subagent() and not get_subagent_verbose()
 
 
+def _suppress_thinking_stream() -> bool:
+    """Return True if thinking banners/content should be hidden.
+
+    Thinking is suppressed in ``low`` output mode (collapsed to a peek
+    by the RichConsoleRenderer) or when the user has explicitly set
+    ``suppress_thinking_messages``.
+
+    In ``high`` output mode, thinking is *never* suppressed -- the user
+    explicitly asked for maximum visibility.
+    """
+    level = get_output_level()
+    if level == "high":
+        return False
+    return level == "low" or get_suppress_thinking_messages()
+
+
+def _suppress_tool_progress() -> bool:
+    """Return True if tool-call progress counters should be hidden.
+
+    In ``low`` mode, the shell-start peek in the RichConsoleRenderer is
+    sufficient; the streaming token counter is noise.
+    """
+    return get_output_level() == "low"
+
+
 async def event_stream_handler(
     ctx: RunContext,
     events: AsyncIterable[Any],
@@ -130,7 +164,9 @@ async def event_stream_handler(
     banner_printed: set[int] = set()  # Track if banner was already printed
     token_count: dict[int, int] = {}  # Track token count per text/tool part
     tool_names: dict[int, str] = {}  # Track tool name per tool part index
+    tool_args_buffer: dict[int, str] = {}  # Accumulate raw tool-call args JSON
     did_stream_anything = False  # Track if we streamed any content
+    is_high_mode = get_output_level() == "high"
 
     # Termflow streaming state for text parts
     termflow_parsers: dict[int, TermflowParser] = {}
@@ -188,6 +224,7 @@ async def event_stream_handler(
         console.print()  # Newline before banner
         # Bold banner with configurable color and lightning bolt
         thinking_color = get_banner_color("thinking")
+
         console.print(
             Text.from_markup(
                 f"[bold white on {thinking_color}] THINKING [/bold white on {thinking_color}] [dim]\u26a1 "
@@ -267,9 +304,11 @@ async def event_stream_handler(
                     streaming_parts.add(event.index)
                     thinking_parts.add(event.index)
                     # If there's initial content, print banner + content now
+                    # (unless thinking is suppressed by output level or toggle).
                     if part.content and part.content.strip():
-                        await _print_thinking_banner()
-                        _emit_thinking(event.index, part.content)
+                        if not _suppress_thinking_stream():
+                            await _print_thinking_banner()
+                            _emit_thinking(event.index, part.content)
                         banner_printed.add(event.index)
                 elif isinstance(part, TextPart):
                     streaming_parts.add(event.index)
@@ -287,6 +326,7 @@ async def event_stream_handler(
                     streaming_parts.add(event.index)
                     tool_parts.add(event.index)
                     token_count[event.index] = 0  # Initialize token counter
+                    tool_args_buffer[event.index] = ""  # Accumulate JSON args
                     # Capture tool name from the start event
                     tool_names[event.index] = part.tool_name or ""
                     # Track tool name for display
@@ -336,10 +376,12 @@ async def event_stream_handler(
                             else:
                                 # For thinking parts, stream smoothly (dim) via a
                                 # rate-limited buffer so bursty deltas don't stutter.
-                                if event.index not in banner_printed:
-                                    await _print_thinking_banner()
-                                    banner_printed.add(event.index)
-                                _emit_thinking(event.index, delta.content_delta)
+                                # Gate on output level / suppress_thinking toggle.
+                                if not _suppress_thinking_stream():
+                                    if event.index not in banner_printed:
+                                        await _print_thinking_banner()
+                                        banner_printed.add(event.index)
+                                    _emit_thinking(event.index, delta.content_delta)
                     elif isinstance(delta, ToolCallPartDelta):
                         # For tool calls, estimate tokens from args_delta content
                         # args_delta contains the streaming JSON arguments
@@ -348,6 +390,10 @@ async def event_stream_handler(
                             # Same 2.5 chars/token heuristic as BaseAgent and file_operations
                             estimated_tokens = max(1, math.floor(len(args_delta) / 2.5))
                             token_count[event.index] += estimated_tokens
+                            # Accumulate raw args JSON for high-mode display.
+                            tool_args_buffer[event.index] = (
+                                tool_args_buffer.get(event.index, "") + args_delta
+                            )
                         else:
                             # Even empty deltas count as activity
                             token_count[event.index] += 1
@@ -359,20 +405,23 @@ async def event_stream_handler(
                                 tool_names.get(event.index, "") + tool_name_delta
                             )
 
-                        # Use stored tool name for display
-                        tool_name = tool_names.get(event.index, "")
-                        count = token_count[event.index]
-                        # Display with tool wrench icon and tool name
-                        if tool_name:
-                            console.print(
-                                f"  \U0001f527 Calling {tool_name}... {count} token(s)   ",
-                                end="\r",
-                            )
-                        else:
-                            console.print(
-                                f"  \U0001f527 Calling tool... {count} token(s)   ",
-                                end="\r",
-                            )
+                        # Use stored tool name for display.
+                        # In low mode, skip the progress counter — the
+                        # RichConsoleRenderer peek is sufficient.
+                        if not _suppress_tool_progress():
+                            tool_name = tool_names.get(event.index, "")
+                            count = token_count[event.index]
+                            # Display with tool wrench icon and tool name
+                            if tool_name:
+                                console.print(
+                                    f"  \U0001f527 Calling {tool_name}... {count} token(s)   ",
+                                    end="\r",
+                                )
+                            else:
+                                console.print(
+                                    f"  \U0001f527 Calling tool... {count} token(s)   ",
+                                    end="\r",
+                                )
 
             # PartEndEvent - finish the streaming with a newline
             elif isinstance(event, PartEndEvent):
@@ -417,6 +466,27 @@ async def event_stream_handler(
                     elif event.index in tool_parts:
                         # Clear the chunk counter line by printing spaces and returning
                         console.print(" " * 50, end="\r")
+                        # In high mode, dump the full tool call arguments so the
+                        # user can see exactly what the model sent to the tool.
+                        if is_high_mode:
+                            tool_name = tool_names.get(event.index, "tool")
+                            raw_args = tool_args_buffer.get(event.index, "")
+                            if raw_args:
+                                # Pretty-print the JSON if possible.
+                                import json as _json
+
+                                try:
+                                    parsed = _json.loads(raw_args)
+                                    formatted = _json.dumps(
+                                        parsed, indent=2, ensure_ascii=False
+                                    )
+                                except (ValueError, TypeError):
+                                    formatted = raw_args
+                                console.print(
+                                    f"[dim]  tool_call {escape(tool_name)} args:[/dim]"
+                                )
+                                for arg_line in formatted.splitlines():
+                                    console.print(f"[dim]    {escape(arg_line)}[/dim]")
                     # For thinking parts, drain the smoother then print newline
                     elif event.index in thinking_parts:
                         smoother = thinking_smoothers.pop(event.index, None)
@@ -429,6 +499,7 @@ async def event_stream_handler(
                     # Clean up token count and tool names
                     token_count.pop(event.index, None)
                     tool_names.pop(event.index, None)
+                    tool_args_buffer.pop(event.index, None)
                     # Clean up all tracking sets
                     streaming_parts.discard(event.index)
                     thinking_parts.discard(event.index)

{code_puppy-0.0.562 → code_puppy-0.0.563}/code_puppy/agents/run_stats.py

@@ -70,12 +70,16 @@ class AgentRunStats:
     _last_token_time: float = 0.0
     _gen_seconds: float = 0.0
     _output_tokens: int = 0
+    _current_model_name: str = ""
 
     # Snapshot of the most-recently-finished cycle. Used as a fallback so
     # consumers (telemetry, future displays) have something stable to read
     # between cycles instead of seeing zeros.
     _last_ttft_seconds: float = 0.0
     _last_gen_tps: float = 0.0
+    _last_output_tokens: int = 0
+    _last_gen_seconds: float = 0.0
+    _last_model_name: str = ""
 
     # --------------- conversation-wide aggregates ---------------
     # Summed across every model call in the session so we can report
@@ -87,7 +91,7 @@ class AgentRunStats:
 
     # ----------------- API -----------------
     @classmethod
-    def mark_request_start(cls) -> None:
+    def mark_request_start(cls, model_name: str = "") -> None:
         """Mark T0 = true request-start (called by ``agent_run_start`` hook).
 
         Resets per-cycle counters but preserves conversation-wide aggregates
@@ -99,6 +103,7 @@ class AgentRunStats:
             cls._last_token_time = 0.0
             cls._gen_seconds = 0.0
             cls._output_tokens = 0
+            cls._current_model_name = model_name
 
     @classmethod
     def record_output_tokens(cls, tokens: int) -> None:
@@ -127,7 +132,9 @@ class AgentRunStats:
             cls._output_tokens += int(tokens)
 
     @classmethod
-    def snapshot_cycle_into_aggregates(cls) -> None:
+    def snapshot_cycle_into_aggregates(
+        cls,
+    ) -> None:
         """Fold the just-finished cycle into conversation-wide aggregates.
 
         Called by the ``agent_run_end`` hook so the auto-save line reflects
@@ -136,22 +143,46 @@ class AgentRunStats:
         starts cleanly.
         """
         with cls._lock:
+            cls._last_model_name = cls._current_model_name
             if cls._first_token_time > 0.0 and cls._stream_start_time > 0.0:
                 ttft = cls._first_token_time - cls._stream_start_time
                 if ttft > 0:
                     cls._last_ttft_seconds = ttft
                     cls._total_ttft_seconds += ttft
                     cls._ttft_sample_count += 1
+                cls._last_output_tokens = cls._output_tokens
+                cls._last_gen_seconds = cls._gen_seconds
                 if cls._output_tokens > 0 and cls._gen_seconds > 0:
                     cls._last_gen_tps = cls._output_tokens / cls._gen_seconds
                     cls._total_output_tokens += cls._output_tokens
                     cls._total_gen_seconds += cls._gen_seconds
+            else:
+                cls._last_output_tokens = 0
+                cls._last_gen_seconds = 0.0
+
             # Zero per-cycle state so the next run starts cleanly.
             cls._stream_start_time = 0.0
             cls._first_token_time = 0.0
             cls._last_token_time = 0.0
             cls._gen_seconds = 0.0
             cls._output_tokens = 0
+            cls._current_model_name = ""
+
+    @classmethod
+    def get_last_cycle_stats(cls) -> dict:
+        """Return a snapshot of the most-recently-completed cycle.
+
+        Keys: ``model``, ``ttft_seconds``, ``gen_tps``, ``gen_seconds``,
+        ``output_tokens``.
+        """
+        with cls._lock:
+            return {
+                "model": cls._last_model_name,
+                "ttft_seconds": cls._last_ttft_seconds,
+                "gen_tps": cls._last_gen_tps,
+                "gen_seconds": cls._last_gen_seconds,
+                "output_tokens": cls._last_output_tokens,
+            }
 
     @classmethod
     def reset_cycle_state(cls) -> None:
@@ -166,8 +197,12 @@ class AgentRunStats:
             cls._last_token_time = 0.0
             cls._gen_seconds = 0.0
             cls._output_tokens = 0
+            cls._current_model_name = ""
             cls._last_ttft_seconds = 0.0
             cls._last_gen_tps = 0.0
+            cls._last_output_tokens = 0
+            cls._last_gen_seconds = 0.0
+            cls._last_model_name = ""
 
     @classmethod
     def reset_conversation_stats(cls) -> None:
@@ -229,6 +264,226 @@ class AgentRunStats:
         return " | ".join(parts)
 
 
+# ---------------------------------------------------------------------------
+# High output-mode per-turn stats rendering
+# ---------------------------------------------------------------------------
+
+
+# Line threshold above which an informational footer is shown in high mode.
+# This is NOT a truncation gate — high mode always shows the full result.
+_HIGH_MODE_RESULT_FOOTER_THRESHOLD = 50
+
+
+# Tool names whose response has already been rendered inline (streamed or
+# via display_non_streamed_result) and should NOT be dumped again.
+_ALREADY_RENDERED_TOOLS = frozenset({"invoke_agent", "invoke_agent_with_model"})
+
+# Tools whose output is already rendered by the rich_renderer via MessageBus
+# messages (FileContentMessage, DiffMessage, GrepResultMessage, etc.).
+# High-mode metadata annotations are already shown inline by the renderer,
+# so dumping the tool result body again would be noisy redundancy.
+_TOOLS_WITH_RENDERER = frozenset(
+    {
+        "read_file",
+        "list_files",
+        "grep",
+        "create_file",
+        "replace_in_file",
+        "delete_file",
+        "delete_snippet",
+        "edit_file",
+        "agent_run_shell_command",
+        "ask_user_question",
+        "activate_skill",
+        "list_or_search_skills",
+        "agent_share_your_reasoning",
+        "universal_constructor",
+        "load_image_for_analysis",
+    }
+)
+
+
+def _stringify_result(result: Any) -> str:
+    """Convert a tool result to a human-readable multi-line string.
+
+    Handles structured types (Pydantic BaseModel, dataclass, dict, list)
+    that produce single-line repr strings with escaped newlines when
+    passed through ``str()``.
+    """
+    if isinstance(result, str):
+        return result
+
+    # Pydantic BaseModel -> JSON-like dict
+    if hasattr(result, "model_dump"):
+        try:
+            import json
+
+            return json.dumps(result.model_dump(), indent=2, default=str)
+        except Exception:
+            pass
+
+    # dataclass -> JSON-like dict
+    import dataclasses
+
+    if dataclasses.is_dataclass(result) and not isinstance(result, type):
+        try:
+            import json
+
+            return json.dumps(dataclasses.asdict(result), indent=2, default=str)
+        except Exception:
+            pass
+
+    # dict / list -> JSON
+    if isinstance(result, (dict, list)):
+        try:
+            import json
+
+            return json.dumps(result, indent=2, default=str)
+        except Exception:
+            pass
+
+    # Last resort: str() with escaped-newline recovery.
+    text = str(result)
+    if "\\n" in text and "\n" not in text:
+        text = text.replace("\\n", "\n")
+    return text
+
+
+def _render_high_mode_tool_result(
+    tool_name: str,
+    tool_args: Any,
+    result: Any,
+    duration_ms: float,
+) -> None:
+    """Print a tool-result summary when ``output_level`` is ``high``.
+
+    Shows the return value that gets sent back to the model, truncated to
+    keep the terminal readable.  Medium mode is unaffected.
+    """
+    try:
+        from code_puppy.config import get_output_level
+
+        if get_output_level() != "high":
+            return
+
+        from rich.markup import escape as _esc
+
+        from code_puppy.agents.event_stream_handler import get_streaming_console
+
+        console = get_streaming_console()
+        dur_str = f"{duration_ms:.0f}" if duration_ms >= 1 else f"{duration_ms:.1f}"
+
+        # Sub-agent results: the response body was already streamed or
+        # rendered by display_non_streamed_result.  Dumping the raw repr
+        # of AgentInvokeOutput would produce a single unreadable line
+        # with escaped newlines.  Show a compact summary instead.
+        if tool_name in _ALREADY_RENDERED_TOOLS:
+            _render_high_mode_agent_result(console, tool_name, result, dur_str)
+            return
+
+        # Tools whose output was already rendered by the rich_renderer:
+        # show a compact duration-only line to avoid double-rendering.
+        if tool_name in _TOOLS_WITH_RENDERER:
+            console.print(
+                f"[dim]  \u21a9 {_esc(tool_name)} returned ({dur_str} ms)[/dim]"
+            )
+            return
+
+        # General path: convert structured results to readable multi-line
+        # text (handles Pydantic models, dataclasses, dicts, lists).
+        # High mode shows the FULL result — no truncation.  The user
+        # explicitly opted into maximum verbosity.
+        result_str = _stringify_result(result)
+        lines = result_str.splitlines()
+        total_lines = len(lines)
+        total_chars = len(result_str)
+
+        console.print(f"[dim]  \u21a9 {_esc(tool_name)} returned ({dur_str} ms):[/dim]")
+        for line in lines:
+            console.print(f"[dim]    {_esc(line)}[/dim]")
+        if total_lines > _HIGH_MODE_RESULT_FOOTER_THRESHOLD:
+            console.print(
+                f"[dim]    ({total_lines} lines, ~{total_chars:,} chars)[/dim]"
+            )
+    except Exception:
+        pass  # never crash for cosmetic output
+
+
+def _render_high_mode_agent_result(
+    console: Any,
+    tool_name: str,
+    result: Any,
+    dur_str: str,
+) -> None:
+    """Compact one-liner for invoke_agent / invoke_agent_with_model results."""
+    from rich.markup import escape as _esc
+
+    agent_name = getattr(result, "agent_name", None) or "?"
+    error = getattr(result, "error", None)
+    response = getattr(result, "response", None)
+
+    if error:
+        console.print(
+            f"[dim]  \u21a9 {_esc(tool_name)} returned ({dur_str} ms): "
+            f"[red]FAIL[/red] {_esc(agent_name)}[/dim]"
+        )
+    elif response is not None:
+        char_count = len(response)
+        console.print(
+            f"[dim]  \u21a9 {_esc(tool_name)} returned ({dur_str} ms): "
+            f"[green]OK[/green] {_esc(agent_name)} ({char_count:,} chars)[/dim]"
+        )
+    else:
+        console.print(
+            f"[dim]  \u21a9 {_esc(tool_name)} returned ({dur_str} ms): "
+            f"{_esc(agent_name)} (no response)[/dim]"
+        )
+
+
+def _render_high_mode_stats() -> None:
+    """Print a per-turn stats line when ``output_level`` is ``high``.
+
+    Reads the just-snapshotted cycle data from :class:`AgentRunStats` and
+    renders a compact dim line below the response showing model name,
+    TTFT, generation latency, and token counts.
+    """
+    try:
+        from code_puppy.config import get_output_level
+
+        if get_output_level() != "high":
+            return
+
+        stats = AgentRunStats.get_last_cycle_stats()
+        # Only render if we actually have timing data.
+        if stats["ttft_seconds"] <= 0 and stats["gen_seconds"] <= 0:
+            return
+
+        from code_puppy.agents.event_stream_handler import get_streaming_console
+
+        console = get_streaming_console()
+
+        parts: list[str] = []
+
+        if stats["ttft_seconds"] > 0:
+            parts.append(f"TTFT {stats['ttft_seconds']:.2f} s")
+
+        if stats["gen_seconds"] > 0:
+            parts.append(f"gen {stats['gen_seconds']:.1f} s")
+
+        if stats["gen_tps"] > 0:
+            parts.append(f"{stats['gen_tps']:,.1f} t/s")
+
+        if stats["output_tokens"] > 0:
+            parts.append(f"~{stats['output_tokens']:,} output tokens (est)")
+
+        if parts:
+            line = " | ".join(parts)
+            console.print(f"\n[dim] {line}[/dim]")
+    except Exception:
+        # Never crash the app for cosmetic stats rendering.
+        pass
+
+
 # ---------------------------------------------------------------------------
 # Callback handlers
 # ---------------------------------------------------------------------------
@@ -255,7 +510,7 @@ async def _on_agent_run_start(
     """Mark T0 = true request-start, before any HTTP packets fly."""
     if is_subagent():
         return
-    AgentRunStats.mark_request_start()
+    AgentRunStats.mark_request_start(model_name=model_name)
 
 
 async def _on_stream_event(
@@ -287,6 +542,17 @@ async def _on_stream_event(
                 _record_text_tokens(args)
 
 
+async def _on_post_tool_call(
+    tool_name: str,
+    tool_args: Any,
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Render the tool return value inline in ``high`` output mode."""
+    _render_high_mode_tool_result(tool_name, tool_args, result, duration_ms)
+
+
 async def _on_agent_run_end(
     agent_name: str,
     model_name: str,
@@ -300,10 +566,14 @@ async def _on_agent_run_end(
 
     Always fires regardless of success/failure so partial-but-real stats
     still count toward the running averages.
+
+    In ``high`` output mode, a per-turn stats line is printed to the
+    streaming console so the user sees timing + token data inline.
     """
     if is_subagent():
         return
     AgentRunStats.snapshot_cycle_into_aggregates()
+    _render_high_mode_stats()
 
 
 # ---------------------------------------------------------------------------
@@ -313,7 +583,7 @@ _HOOKS_REGISTERED = False
 
 
 def register_hooks() -> None:
-    """Idempotently register the three run-stats callback hooks."""
+    """Idempotently register the run-stats callback hooks."""
     global _HOOKS_REGISTERED
     if _HOOKS_REGISTERED:
         return
@@ -323,6 +593,7 @@ def register_hooks() -> None:
         register_callback("agent_run_start", _on_agent_run_start)
         register_callback("stream_event", _on_stream_event)
         register_callback("agent_run_end", _on_agent_run_end)
+        register_callback("post_tool_call", _on_post_tool_call)
         _HOOKS_REGISTERED = True
     except Exception:
         # Callback module unavailable (extremely unlikely); silently skip
@@ -341,4 +612,5 @@ __all__ = [
     "_on_agent_run_start",
     "_on_stream_event",
     "_on_agent_run_end",
+    "_on_post_tool_call",
 ]

{code_puppy-0.0.562 → code_puppy-0.0.563}/code_puppy/command_line/set_menu_catalog.py

@@ -46,6 +46,7 @@ from code_puppy.config import (
     get_openai_reasoning_effort,
     get_openai_reasoning_summary,
     get_openai_verbosity,
+    get_output_level,
     get_owner_name,
     get_pack_agents_enabled,
     get_protected_token_count,
@@ -489,6 +490,19 @@ _SAFETY = SettingsCategory(
 _OUTPUT = SettingsCategory(
     name="Output",
     settings=(
+        Setting(
+            key="output_level",
+            display_name="Output Level",
+            description=(
+                "Unified density control for conversation output. "
+                "low = one-line peeks for tool calls & thinking, "
+                "medium = current default, "
+                "high = full metadata with timing, tokens, and verbose output."
+            ),
+            type_hint="choice",
+            valid_values=("low", "medium", "high"),
+            effective_getter=get_output_level,
+        ),
         Setting(
             key="smooth_response_stream",
             display_name="Smooth Response Stream",

{code_puppy-0.0.562 → code_puppy-0.0.563}/code_puppy/config.py

@@ -2015,6 +2015,51 @@ def set_suppress_informational_messages(enabled: bool):
     set_config_value("suppress_informational_messages", "true" if enabled else "false")
 
 
+# ---------------------------------------------------------------------------
+# Output level (unified density control)
+# ---------------------------------------------------------------------------
+
+_VALID_OUTPUT_LEVELS = frozenset({"low", "medium", "high"})
+
+
+def get_output_level() -> str:
+    """Return the current output density level.
+
+    Valid values: ``low``, ``medium``, ``high``.  Default is ``medium``
+    (current behaviour).  The value is read from ``puppy.cfg`` with the
+    key ``output_level``.
+
+    * **low** — collapse tool calls, thinking blocks, and info messages
+      to one-line peeks.  Great for focused work.
+    * **medium** — current default behaviour.
+    * **high** — full metadata: timing, tokens, verbose grep, all
+      sub-agent output.
+    """
+    cfg_val = get_value("output_level")
+    if cfg_val is not None:
+        normalised = str(cfg_val).strip().lower()
+        if normalised in _VALID_OUTPUT_LEVELS:
+            return normalised
+    return "medium"
+
+
+def set_output_level(level: str) -> None:
+    """Set the output density level.
+
+    Args:
+        level: One of ``low``, ``medium``, or ``high``.
+
+    Raises:
+        ValueError: If *level* is not a valid choice.
+    """
+    normalised = level.strip().lower()
+    if normalised not in _VALID_OUTPUT_LEVELS:
+        raise ValueError(
+            f"Invalid output_level {level!r}; choose from low, medium, high"
+        )
+    set_config_value("output_level", normalised)
+
+
 # API Key management functions
 def get_api_key(key_name: str) -> str:
     """Get an API key from puppy.cfg.