formatting.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_ui/terminal/formatting.py
 
"""
Pure presentation helpers for terminal labels and tables.
 
Purpose
-------
Format strings the user sees — byte-count → ``KB``/``MB``, token
count → ``2.4K``/``1.20M``, model + capability → ``deepseek-v4-pro
(thinking, high)``. These are a layer above the
:class:`~oc_ui.presenter_base.Presenter` ABC: the presenters call
``show_info`` / ``show_session_list`` / ``show_available_models``
with strings produced here.
 
Sub-agents that use :class:`LoggingPresenter` or no presenter at all
never need these — that's why they live in ``oc_ui`` rather than
next to the runtime objects they describe.
 
Responsibilities
----------------
- :func:`fmt_size_kb` — render a byte count compactly.
- :func:`fmt_tokens_or_size` — pick the most informative chat-volume
  label for the menu (token count when available, file size as a
  fallback).
- :func:`fmt_model_caps` — format the model line with thinking /
  reasoning capability hints in either compact (table) or verbose
  (continue-prompt) form.
 
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All three formatters are pure functions: same inputs → same string
  output.
- :func:`fmt_size_kb` switches to ``MB`` at ``1_000_000`` bytes.
- :func:`fmt_tokens_or_size` falls back to ``"empty"`` when neither
  tokens nor bytes are recorded.
- :func:`fmt_model_caps` returns the bare model name when the model
  declares neither ``supports_thinking`` nor ``supports_reasoning``.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.models (lazy; ModelManager type hint for fmt_model_caps)
- oc_chat.core.session (lazy; TokenStats type hint for fmt_tokens_or_size)
"""
from __future__ import annotations
 
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
if TYPE_CHECKING:
    from oc_chat.core.models import ModelManager
    from oc_chat.core.session import TokenStats
 
 
_dbg("OC_UI.TERMINAL", "module", "loaded", 4)
 
 
def fmt_size_kb(n_bytes: int) -> str:
    """Render a byte count as ``NNN KB`` (or MB for >=1 MB)."""
    if n_bytes >= 1_000_000:
        return f"{n_bytes / 1_000_000:.1f} MB"
    return f"{n_bytes / 1024:.0f} KB"
 
 
def fmt_tokens_or_size(stats: "TokenStats", size_bytes: int) -> str:
    """Pick the most informative chat-volume label for the menu.
 
    If usage tokens were recorded, display them.  Otherwise fall back to
    the chat log file size so the user has *something* to gauge volume by.
    """
    if stats.total_tokens > 0:
        n = stats.total_tokens
        if n >= 1_000_000:
            return f"tokens: {n / 1_000_000:.2f}M"
        if n >= 1_000:
            return f"tokens: {n / 1_000:.1f}K"
        return f"tokens: {n}"
    if size_bytes > 0:
        return f"size: {fmt_size_kb(size_bytes)}"
    return "empty"
 
 
def fmt_model_caps(
    model: str,
    reasoning_effort: str,
    model_manager: "ModelManager | None",
    *,
    verbose: bool = False,
) -> str:
    """Format the model line including thinking/reasoning capability hints.
 
    *verbose* form: ``"deepseek-v4-pro (thinking, effort: high)"`` — fine
    for the [1] continue-prompt where we have a whole line.
    Default compact form: ``"deepseek-v4-pro (thinking, high)"`` — fits the
    list-table column.
    """
    caps = model_manager.capabilities(model) if model_manager else {}
    if caps.get("supports_thinking"):
        kind = "thinking"
    elif caps.get("supports_reasoning"):
        kind = "reasoning"
    else:
        return model
    if verbose:
        return f"{model} ({kind}, effort: {reasoning_effort})"
    return f"{model} ({kind}, {reasoning_effort})"