oc_ui.terminal.formatting Namespace Reference

Functions
str	fmt_size_kb (int n_bytes)
str	fmt_tokens_or_size ("TokenStats" stats, int size_bytes)
str	fmt_model_caps (str model, str reasoning_effort, "ModelManager | None" model_manager, *, bool verbose=False)

Detailed Description

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)

Function Documentation

fmt_model_caps()

str oc_ui.terminal.formatting.fmt_model_caps	(	str	model,
		str	reasoning_effort,
		"ModelManager | None"	model_manager,
		*	,
		bool	verbose = False )

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.

Definition at line 94 of file formatting.py.

fmt_size_kb()

str oc_ui.terminal.formatting.fmt_size_kb

(

int

n_bytes

)

Render a byte count as ``NNN KB`` (or MB for >=1 MB).

Definition at line 69 of file formatting.py.

fmt_tokens_or_size()

str oc_ui.terminal.formatting.fmt_tokens_or_size	(	"TokenStats"	stats,
		int	size_bytes )

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.

Definition at line 76 of file formatting.py.