export

Documentation

Overview

Package export renders Thread conversation histories into human-reviewable formats: plain text, self-contained HTML, and JSON.

The package depends only on artifact and ledger. It does not import any thread-container type (junk.Thread, session.Session, or *ledger.Thread). Callers construct a Thread value — a small value type carrying just the data the exporters need — from whatever container they happen to hold.

All three top-level functions accept an io.Writer and a Thread, iterate over the thread's turns, and emit every artifact in the turn. Delta artifacts are never present in persisted threads so no special handling is required.

HTML rendering specifics:

• Text artifact content is rendered as markdown (CommonMark plus the GFM extension for tables, strikethrough, task lists, and autolinks) and sanitized via bluemonday.UGCPolicy. LLM-emitted <script>, <iframe>, and javascript: URLs are stripped.
• Reasoning artifacts collapse under a <details> element. Their content is not markdown-rendered — reasoning text is typically stream-of-thought prose, and rendering it risks unintended visual changes (lists appearing where the model was just thinking in prose).
• Paired ToolCall + ToolResult artifacts in the same turn collapse under a single <details> with the tool name as the summary. Unpaired ones each get their own <details>.

JSON output uses the wire format `{id, current_tip, metadata, turns}`. This format is documented in the workshop README as user-facing; it must remain stable across versions so external tooling can consume it.

Index

• func HTML(w io.Writer, t Thread) error
• func JSON(w io.Writer, t Thread) error
• func Text(w io.Writer, t Thread) error
• type Thread

Functions

func HTML

func HTML(w io.Writer, t Thread) error

HTML writes a self-contained HTML document representing the conversation thread to w. The output uses inline CSS, native <details>/<summary> collapsibles, and has no external dependencies. Text artifacts are rendered as markdown and sanitized by bluemonday.UGCPolicy before being embedded.

func JSON

func JSON(w io.Writer, t Thread) error

JSON writes a pretty-printed JSON representation of the thread to w. The output preserves the wire format documented in the package comment — {id, current_tip, metadata, turns} with no created_at/updated_at — so external tooling continues to work.

func Text

func Text(w io.Writer, t Thread) error

Text writes a plain-text transcript of the conversation thread to w. Each turn is emitted with its role and timestamp, followed by every artifact rendered in a human-readable form.

Types

type Thread

type Thread struct {
	// ID is the thread's identifier. Surfaced in the text header
	// ("Thread: <id>") and the HTML <title>.
	ID string
	// Metadata is arbitrary per-conversation key-value state (for
	// example, "slack_thread_id", "persona"). Surfaced in the
	// text/HTML outputs and the JSON wire format's "metadata"
	// field.
	Metadata map[string]string
	// Turns is the thread's active-path turn list. Callers usually
	// obtain this via *ledger.Thread.Turns(); for in-memory tests
	// it is constructed by hand.
	Turns []ledger.Turn
}

Thread is the minimum data the exporters need from any thread-like container. Callers construct one from a *junk.Thread, *session.Session, *ledger.Thread, or any in-memory representation — the package is intentionally agnostic to the source.

The value type (rather than an interface) is chosen because a leaf utility package benefits from cheap value semantics and clear field-level access, with no need for the caller to implement a method set.