Format helpers - leaf module.
Small, dependency-light formatters used by the SDK facade, the TUI footer and the CLI status output. 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)
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 and the CLI status output. 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)
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):
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): 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 {:strs [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. Reads the canonical string-keyed usage
map ("input" / "output" / "cached" / "cache_created").
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. Reads the canonical string-keyed usage map (`"input"` / `"output"` / `"cached"` / `"cache_created"`). 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 the CLI folds 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 the CLI folds it inline.
Calm separator for the shared turn-summary line — a middot ringed by spaces. Identical across CLI and TUI so every surface reads the same.
Calm separator for the shared turn-summary line — a middot ringed by spaces. Identical across CLI and TUI 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 and the TUI bubble footer:
<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 and the TUI bubble footer:
<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 |