Format helpers - leaf module.
Small, dependency-light formatters used by the SDK facade, the TUI footer, the CLI status output, and the Telegram bot. Each one is a pure transform over basic Clojure / Java values.
format-date - java.util.Date to dd-MM-yyyy HH:mm (local TZ)
format-clojure - pass-through (code is shown as written, not reformatted)
format-duration - millisecond duration to 2.3s, 1m 15s, etc.
format-tokens - :input/:output token counts to 'tok 11461→35'
format-cost - dollar cost to '~$0.006954'
format-iterations- iteration count to '1 iter' / '3 iters'
format-meta-line - canonical ' / '-joined turn-summary line
(used identically by CLI / TUI / Telegram)
No external pretty-printer: data renders through clojure.pprint
(built-in) and source code is shown verbatim. The namespace is free of
state - safe to require from any layer.
Format helpers - leaf module.
Small, dependency-light formatters used by the SDK facade, the
TUI footer, the CLI status output, and the Telegram bot. Each one
is a pure transform over basic Clojure / Java values.
`format-date` - `java.util.Date` to `dd-MM-yyyy HH:mm` (local TZ)
`format-clojure` - pass-through (code is shown as written, not reformatted)
`format-duration` - millisecond duration to `2.3s`, `1m 15s`, etc.
`format-tokens` - `:input`/`:output` token counts to 'tok 11461→35'
`format-cost` - dollar cost to '~$0.006954'
`format-iterations`- iteration count to '1 iter' / '3 iters'
`format-meta-line` - canonical ' / '-joined turn-summary line
(used identically by CLI / TUI / Telegram)
No external pretty-printer: data renders through `clojure.pprint`
(built-in) and source code is shown verbatim. The namespace is free of
state - safe to require from any layer.(bounded-value-str v)(bounded-value-str
v
{:keys [max-chars print-length print-level]
:as opts
:or {max-chars MAX_RESULT_DISPLAY_CHARS print-length 64 print-level 6}})Bounded Clojure data rendering for plain working-memory previews
(TUI progress, history-restore, trailer ;; => … lines). Caps output
at MAX_RESULT_DISPLAY_CHARS chars by default; callers that want
tighter or looser bounds pass :max-chars. Do not use for tool results;
tools must render through their symbol-specific renderers.
Bounded Clojure data rendering for plain working-memory previews (TUI progress, history-restore, trailer `;; => …` lines). Caps output at `MAX_RESULT_DISPLAY_CHARS` chars by default; callers that want tighter or looser bounds pass `:max-chars`. Do not use for tool results; tools must render through their symbol-specific renderers.
(display-model-name m)DISPLAY-ONLY normalization of a model id: path-style ids
(google/gemma-4-12b-qat, org/model as LM Studio / HF name them)
render with the slashes flattened to dashes (google-gemma-4-12b-qat),
so a provider/model label never reads as three ambiguous segments.
The wire/config id keeps its slashes — never feed this back to a
router or provider. nil-safe; non-strings and blanks return nil.
DISPLAY-ONLY normalization of a model id: path-style ids (`google/gemma-4-12b-qat`, `org/model` as LM Studio / HF name them) render with the slashes flattened to dashes (`google-gemma-4-12b-qat`), so a `provider/model` label never reads as three ambiguous segments. The wire/config id keeps its slashes — never feed this back to a router or provider. nil-safe; non-strings and blanks return nil.
(format-clojure code-str _width)Source is shown as written — no reformatting. Returns code-str
trimmed of trailing whitespace (or unchanged when not a string).
Source is shown as written — no reformatting. Returns `code-str` trimmed of trailing whitespace (or unchanged when not a string).
(format-clojure-ansi code-str _width)Source is shown as written — no reformatting or syntax coloring.
Returns code-str trimmed of trailing whitespace.
Source is shown as written — no reformatting or syntax coloring. Returns `code-str` trimmed of trailing whitespace.
(format-cost cost)Render a dollar cost as '~$0.006954' (six decimal places, US
locale). Returns nil when cost is nil, zero, negative, or
non-numeric. Accepts either the bare number or a :total-cost
map. Detailed cost maps render the total first and the breakdown
parenthesized, in order: in, cached, write, out — e.g.
'~$0.006954 (in ~$0.001200, cached ~$0.000400, out ~$0.005354)'.
The parenthesized breakdown renders only when at least two of
those slots carry a positive value; otherwise just the total.
Render a dollar cost as '~$0.006954' (six decimal places, US locale). Returns nil when `cost` is nil, zero, negative, or non-numeric. Accepts either the bare number or a `:total-cost` map. Detailed cost maps render the total first and the breakdown parenthesized, in order: in, cached, write, out — e.g. '~$0.006954 (in ~$0.001200, cached ~$0.000400, out ~$0.005354)'. The parenthesized breakdown renders only when at least two of those slots carry a positive value; otherwise just the total.
(format-date d)Format a java.util.Date as dd-MM-yyyy HH:mm in local timezone.
Format a `java.util.Date` as `dd-MM-yyyy HH:mm` in local timezone.
(format-duration ms)Human-readable millisecond duration. e.g. 2.3s, 1m 15s. Always
uses Locale/US so the decimal separator is a dot regardless of
the JVM default locale. Coerces the input to long up-front because
callers routinely pass a double from (/ ns 1e6).
Human-readable millisecond duration. e.g. `2.3s`, `1m 15s`. Always uses Locale/US so the decimal separator is a dot regardless of the JVM default locale. Coerces the input to long up-front because callers routinely pass a double from `(/ ns 1e6)`.
(format-iterations n)(format-iterations n {:keys [silent-count]})Render an iteration count as '1 iter' or '3 iters'. Returns nil
when n is nil or non-numeric. Optional :silent-count appends
hidden/silent bookkeeping count, e.g. '3 iters (2 silent)'.
Render an iteration count as '1 iter' or '3 iters'. Returns nil when `n` is nil or non-numeric. Optional `:silent-count` appends hidden/silent bookkeeping count, e.g. '3 iters (2 silent)'.
(format-meta-line result)(format-meta-line result opts)Single-line turn summary for plain-text surfaces (the CLI [...] bracket and
the Telegram tagline): the shared meta-summary-line with the fallback note
folded inline. The TUI instead uses meta-summary-line + meta-fallback-note
directly so it can float the note on its own faint row — same words, same
numbers, just two rows. Returns "" when there's nothing to show.
Single-line turn summary for plain-text surfaces (the CLI `[...]` bracket and the Telegram tagline): the shared `meta-summary-line` with the fallback note folded inline. The TUI instead uses `meta-summary-line` + `meta-fallback-note` directly so it can float the note on its own faint row — same words, same numbers, just two rows. Returns "" when there's nothing to show.
(format-tokens {:keys [input output] :as tokens})Render token counts in the canonical compact grouped form: 'tok <input>→<output> (cached <cached-input>)' when cached input is positive, otherwise 'tok <input>→<output>'.
The arrow reads 'prompt produced completion'. Cached is cached
input tokens, parenthesized because provider APIs report cache
hits inside prompt usage. :cached is the provider field;
:cached-input / :input-cached are accepted aliases so usage
maps can name the direction explicitly.
Cache visibility: the (cached N) segment renders only when N is
positive. Zero / missing cache info stays hidden so meta lines do
not show noisy (cached 0) decorations.
Returns nil when no known field carries a number.
Render token counts in the canonical compact grouped form: 'tok <input>→<output> (cached <cached-input>)' when cached input is positive, otherwise 'tok <input>→<output>'. The arrow reads 'prompt produced completion'. Cached is cached input tokens, parenthesized because provider APIs report cache hits inside prompt usage. `:cached` is the provider field; `:cached-input` / `:input-cached` are accepted aliases so usage maps can name the direction explicitly. Cache visibility: the `(cached N)` segment renders only when N is positive. Zero / missing cache info stays hidden so meta lines do not show noisy `(cached 0)` decorations. Returns nil when no known field carries a number.
(humanize-fact-key k)Human-facing label for a fact/entity key. A turn_<N> key reads as
Turn <N> for DISPLAY. Every other key is shown with
underscores/hyphens normalized to SPACES and the first letter capitalized
(api_key -> Api key, clj_eval_render -> Clj eval render).
DISPLAY ONLY — the stored key stays verbatim, so restore still
matches. Canonical across the context panel and every channel (TUI, web).
Fact/entity keys are model-authored strings (strings-only boundary),
so (str k) is total here — no keyword branch.
Human-facing label for a fact/entity key. A `turn_<N>` key reads as `Turn <N>` for DISPLAY. Every other key is shown with underscores/hyphens normalized to SPACES and the first letter capitalized (`api_key` -> `Api key`, `clj_eval_render` -> `Clj eval render`). DISPLAY ONLY — the stored key stays verbatim, so restore still matches. Canonical across the context panel and every channel (TUI, web). Fact/entity keys are model-authored strings (strings-only boundary), so `(str k)` is total here — no keyword branch.
Default char cap on bounded plain-value output when no :max-chars
override is passed. TUI progress chunks and history-restore previews
use this. Tape rendering passes its own JOURNAL_RESULT_MAX_CHARS and
bypasses the default.
Default char cap on bounded plain-value output when no `:max-chars` override is passed. TUI progress chunks and history-restore previews use this. Tape rendering passes its own `JOURNAL_RESULT_MAX_CHARS` and bypasses the default.
(meta-cost cost)Humanized dollar cost — "~$0.0070" / "~$1.23". nil for zero / missing. Extra decimals for sub-cent turns so they don't round down to "$0".
Humanized dollar cost — "~$0.0070" / "~$1.23". nil for zero / missing. Extra decimals for sub-cent turns so they don't round down to "$0".
(meta-fallback-note {:keys [llm-selected llm-fallback? llm-routing-trace]})Faint routing note, present only when the turn fell back to another model:
↳ from <selected-model> — <reason>, retried N×
reason prefers the HTTP status (429) on the fallback event, then the reason
keyword, then the free-form error. Retries count :llm.routing/provider-retry
events in the trace. Returns nil when there was no fallback. Shared so the TUI
can float it on its own faint row while CLI/Telegram fold it inline.
Faint routing note, present only when the turn fell back to another model: ↳ from <selected-model> — <reason>, retried N× `reason` prefers the HTTP status (429) on the fallback event, then the reason keyword, then the free-form error. Retries count `:llm.routing/provider-retry` events in the trace. Returns nil when there was no fallback. Shared so the TUI can float it on its own faint row while CLI/Telegram fold it inline.
Calm separator for the shared turn-summary line — a middot ringed by spaces. Identical across CLI, TUI, and Telegram so every surface reads the same.
Calm separator for the shared turn-summary line — a middot ringed by spaces. Identical across CLI, TUI, and Telegram so every surface reads the same.
(meta-summary-line result)(meta-summary-line {:keys [tokens cost duration-ms] :as result}
{:keys [model prefix suffix]})The canonical, humanized turn-summary MAIN line, shared verbatim by the CLI bracket, the TUI bubble footer, and the Telegram tagline:
<provider/model> · <in→out (cached)> · ~$cost · <duration>
Zero-usage and zero-cost slots are dropped (no "0→0", no "$0"), so a turn
that produced nothing reads as just the model + time. Does NOT include the
fallback note — that is meta-fallback-note, which single-line surfaces fold
in via format-meta-line and the TUI floats on a second row.
opts keeps the legacy override hooks: {:model <string|false> :prefix [...] :suffix [...]} — :model false suppresses the model slot, a string overrides
it; prefix/suffix are extra slots spliced in around the standard ones.
The canonical, humanized turn-summary MAIN line, shared verbatim by the CLI
bracket, the TUI bubble footer, and the Telegram tagline:
<provider/model> · <in→out (cached)> · ~$cost · <duration>
Zero-usage and zero-cost slots are dropped (no "0→0", no "$0"), so a turn
that produced nothing reads as just the model + time. Does NOT include the
fallback note — that is `meta-fallback-note`, which single-line surfaces fold
in via `format-meta-line` and the TUI floats on a second row.
`opts` keeps the legacy override hooks: `{:model <string|false> :prefix [...]
:suffix [...]}` — `:model false` suppresses the model slot, a string overrides
it; prefix/suffix are extra slots spliced in around the standard ones.(meta-tokens tokens)Humanized token slot — "11.5k→35", with " (cached 4.1k)" only when the cached-input count is positive. Returns nil for a ZERO-usage turn (no input AND no output) so a failed / empty provider call never renders a bare "0→0".
Humanized token slot — "11.5k→35", with " (cached 4.1k)" only when the cached-input count is positive. Returns nil for a ZERO-usage turn (no input AND no output) so a failed / empty provider call never renders a bare "0→0".
(safe-zprint-file-str source & _ignored)Source-formatting seam. Vis no longer reformats code — source is shown as written — so this returns the input verbatim. Retained so callers (e.g. the Clojure language extension) keep a stable entry point.
Source-formatting seam. Vis no longer reformats code — source is shown as written — so this returns the input verbatim. Retained so callers (e.g. the Clojure language extension) keep a stable entry point.
(safe-zprint-str v & _ignored)Pretty-print a runtime DATA value to a string via clojure.pprint.
Kept under the historical name so existing data-render call sites
(ctx trailer, bounded-value previews) need no change. The optional
trailing args (width / opts) accepted by the old zprint wrapper are
ignored; pprint reads *print-length*/*print-level* from the
dynamic bindings the caller sets.
Pretty-print a runtime DATA value to a string via `clojure.pprint`. Kept under the historical name so existing data-render call sites (ctx trailer, bounded-value previews) need no change. The optional trailing args (width / opts) accepted by the old zprint wrapper are ignored; pprint reads `*print-length*`/`*print-level*` from the dynamic bindings the caller sets.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |