Skip to content

renderer-guide.md

Latest commit

 

History

History
73 lines (45 loc) · 2.14 KB

renderer-guide.md

File metadata and controls

73 lines (45 loc) · 2.14 KB

Renderer Guide

TraceCC renders multiple views from the same persisted IR. All views rely on the same full-view line numbers.

The design follows the view semantics described in the paper at arXiv:2603.29678, but this codebase targets semantic compatibility rather than byte-for-byte output parity with any prior implementation.

Full view

Purpose:

  • lossless transcript
  • canonical line-number coordinate system
  • dereference target for all other views

Behavior:

  • emits every node in line order
  • includes semantic headers like [user], [assistant], and [tool_result]
  • preserves assigned line ranges exactly

UI view

Purpose:

  • present what a human most likely perceived during the session

Behavior:

  • hides internal/system content by default
  • emits visible user and assistant text
  • collapses tool interactions into concise summary lines with full-view pointers
  • keeps line pointers stable

Adaptive view

Purpose:

  • support retrieval without flattening away conversational structure

Modes:

  • document Keeps temporal structure and section grouping.
  • index Emits a flat list of matching blocks.

Behavior:

  • runs a predicate over persisted nodes
  • includes semantic role labels
  • includes line-range pointers into full view

The default predicate today is regex. BM25 is implemented for search and can feed adaptive workflows later without changing pointer semantics.

Compat renderer

internal/render/compat/compat.go is an internal renderer used by the export pipeline. It delegates to the three primary renderers based on a mode string:

  • "min" → UI renderer
  • "view" → adaptive renderer (defaults to document mode)
  • default (empty or unrecognized) → full renderer

The compat renderer is not exposed as a CLI --view option. It is used internally by tracecc export to generate the three text export files from a single code path.

Compatibility export

tracecc export writes:

  • .txt
  • .min.txt
  • .view.txt

These are generated from TraceCC renderers. The goal is workflow compatibility and stable dereference behavior, not exact byte-for-byte reproduction of a legacy formatter.