ldtc.reporting¶

Paper-quality figure and table generation. Reads only the audit log; cannot reach into LREG, so nothing it produces leaks raw 𝓛.

Module	Headline symbols	Use it for
`style`	`COLORS`, `apply_matplotlib_theme`, `apply_graphviz_theme`, `new_graph`	The shared palette and matplotlib / graphviz themes.
`tables`	`write_sc1_table`	Per-trial SC1 results CSV: `eta, delta, tau_rec, M_post, pass`.
`timeline`	`render_paper_timeline`	Paper-style timeline: normalized `𝓛`, `M (dB)`, `Mmin` rule, shaded `Ω` window, audit-event tick rug.
`artifacts`	`bundle`	Convenience entry point that turns one audit log into a complete frozen artifact directory (timeline + table + manifest + config snapshot + notice).

See Reporting for the operator guide.

Reporting helpers for verification artifacts.

reporting is the last stop in an LDTC run: it turns the audit log into the human-readable artifacts the rest of the world sees, without ever leaking raw 𝓛 values or CI bounds:

style holds Matplotlib and Graphviz theming (palette, fonts, vector-friendly defaults).
tables provides CSV writers for SC1 tables; they refuse to emit raw LREG fields.
timeline renders audit-driven timelines (M (dB), normalized 𝓛, Ω shading).
artifacts is the end-to-end bundle builder: timeline, SC1 table, and manifest from one audit log.

Together, these modules render a publication-style timeline, a small manifest, and an SC1 results CSV. Everything they emit is locked to read-only on POSIX-like filesystems so an artifact directory can be treated as a frozen demo result.

style¶

style ¶

Plot and graph styles for LDTC figures.

Provides a small, opinionated theme that the rest of ldtc.reporting uses to make figures consistent across the docs site, the paper, and per-run artifact bundles. Three helpers are exposed:

apply_matplotlib_theme sets fonts, axes, and DPI on the global Matplotlib rcParams.
apply_graphviz_theme decorates a Digraph with the LDTC palette and layout defaults.
new_graph is a convenience constructor that returns an already-themed Digraph.

The shared COLORS palette in this module is colorblind-aware and anchored on the manuscript's existing colors so figures composed in the docs match the paper.

See Also

paper/main.tex: Reporting & Figures.

Functions:

Name	Description
`apply_matplotlib_theme`	Apply a consistent Matplotlib style.
`apply_graphviz_theme`	Apply consistent Graphviz attributes to a Digraph.
`new_graph`	Create a themed Graphviz Digraph.

apply_matplotlib_theme ¶

apply_matplotlib_theme(kind: str = 'paper') -> None

Apply a consistent Matplotlib style.

Configures fonts, spine visibility, label sizes, and vector-friendly output settings so that figures in the docs site and the paper share a single visual language. The function mutates the global Matplotlib rcParams; call it once at process start.

Parameters:

Name	Type	Description	Default
`kind`	`str`	Optional style variant. Currently informational; only the default paper-style theme is implemented.	`'paper'`

apply_graphviz_theme ¶

apply_graphviz_theme(dot: Any, rankdir: str = 'LR', overrides: Dict[str, Dict[str, str]] | None = None) -> None

Apply consistent Graphviz attributes to a Digraph.

Parameters:

Name	Type	Description	Default
`dot`	`Any`	A `graphviz.Digraph` instance.	required
`rankdir`	`str`	Graph layout direction; either `"LR"` (left-to-right) or `"TB"` (top-to-bottom).	`'LR'`
`overrides`	`Dict[str, Dict[str, str]] \| None`	Optional nested dict overriding default graph/node/edge attributes. Top-level keys must be one of `"graph"`, `"node"`, or `"edge"`; values are merged shallowly into the defaults so callers can override only the attributes they care about.	`None`

new_graph ¶

new_graph(name: str, rankdir: str = 'LR', engine: str = 'dot') -> Any

Create a themed Graphviz Digraph.

Parameters:

Name	Type	Description	Default
`name`	`str`	Graph name. Used by Graphviz for the rendered file's top-level identifier.	required
`rankdir`	`str`	Layout direction; see `apply_graphviz_theme`.	`'LR'`
`engine`	`str`	Graphviz engine (e.g., `"dot"`, `"neato"`).	`'dot'`

Returns:

Type	Description
`Any`	A `graphviz.Digraph` with the LDTC palette and layout defaults
`Any`	already applied.

Raises:

Type	Description
`RuntimeError`	If `graphviz` is not installed.

tables¶

tables ¶

CSV writers for SC1 result tables.

The writers in this module enforce LDTC's "no raw LREG" export policy (see guardrails.lreg): if a row dict ever contains L_loop, L_ex, ci_loop, or ci_ex, the writer refuses to emit the file. This is a second line of defense after the same check inside attest.exporter; together they guarantee that raw 𝓛 values can leave neither the device-signed indicator artifact nor the human-facing CSV table.

See Also

paper/main.tex: Reporting & Figures; Export policy.

Functions:

Name	Description
`write_sc1_table`	Write SC1 result rows to a CSV file.

write_sc1_table ¶

write_sc1_table(rows: List[Dict[str, Any]], out_csv: str) -> None

Write SC1 result rows to a CSV file.

Column order is taken from the first row's keys, so callers should use a stable dict layout (e.g., always emit the same fields in the same order) to keep diffs across runs minimal.

Parameters:

Name	Type	Description	Default
`rows`	`List[Dict[str, Any]]`	List of dicts with consistent keys across rows. Must not contain any raw LREG field (`L_loop`, `L_ex`, `ci_loop`, `ci_ex`); the writer refuses such rows.	required
`out_csv`	`str`	Target CSV path. The file is created or overwritten.	required

Raises:

Type	Description
`ValueError`	If any row contains a banned raw LREG field.

timeline¶

timeline ¶

Audit-driven verification timelines.

This module produces the headline figure for an LDTC run: a stacked timeline of normalized 𝓛 traces and M (dB), with Ω shading and audit-event tick marks layered on top. All inputs come from the guardrails.audit JSONL log; an optional sidecar CSV may provide normalized 𝓛 values directly. Raw LREG values are never read or rendered.

Two entry points exist:

render_verification_timeline is the legacy audit-event-density plot, kept for backwards compatibility.
render_paper_timeline is the paper-style figure: log 𝓛, M (dB), Ω spans, audit ticks.

The figure colors and DPI come from apply_matplotlib_theme and the shared COLORS palette in ldtc.reporting.style.

See Also

paper/main.tex: Reporting & Figures.

Functions:

Name	Description
`render_verification_timeline`	Render a simple audit-density timeline (legacy).
`render_paper_timeline`	Render a paper-style timeline of `𝓛` traces and `M (dB)`.

render_verification_timeline ¶

render_verification_timeline(audit_path: str, figure_path: str, show: bool = False) -> Tuple[int, int]

Render a simple audit-density timeline (legacy).

Plots audit events per second as a step function. Useful as a quick sanity check for audit liveness; production runs should prefer render_paper_timeline.

Parameters:

Name	Type	Description	Default
`audit_path`	`str`	Path to the JSONL audit log.	required
`figure_path`	`str`	Output path for the PNG figure.	required
`show`	`bool`	If `True`, display the figure interactively after saving.	`False`

Returns:

Type	Description
`Tuple[int, int]`	Tuple `(number_of_records, number_of_buckets_plotted)`.

Raises:

Type	Description
`FileNotFoundError`	If the audit file has no records.

render_paper_timeline ¶

render_paper_timeline(audit_path: str, out_base_path: str, sidecar_csv: Optional[str] = None, show: bool = False, min_tick_spacing_s: float = 0.75, use_log_L: bool = True, footer_profile: Optional[str] = None, footer_audit_head: Optional[str] = None) -> Dict[str, str]

Render a paper-style timeline of 𝓛 traces and M (dB).

Reads the audit log for per-window M, Ω spans, and tick events, optionally augmenting with a sidecar CSV of normalized 𝓛 traces. Without a sidecar, normalized 𝓛 is derived from M alone so the figure never depends on raw LREG values.

Parameters:

Name	Type	Description	Default
`audit_path`	`str`	JSONL audit log emitted by an LDTC run.	required
`out_base_path`	`str`	Output path prefix; `.png` and `.svg` are appended.	required
`sidecar_csv`	`Optional[str]`	Optional CSV file with columns `time_s,L_loop,L_ex` (normalized).	`None`
`show`	`bool`	If `True`, display the figure interactively after saving.	`False`
`min_tick_spacing_s`	`float`	Minimum spacing between audit tick marks (s) to avoid clutter.	`0.75`
`use_log_L`	`bool`	Plot `𝓛` on a log scale.	`True`
`footer_profile`	`Optional[str]`	Optional profile badge text (`"R0"` / `"R*"`). Inferred from the audit `run_header` when omitted.	`None`
`footer_audit_head`	`Optional[str]`	Optional last-hash value for audit provenance. Inferred from the last record when omitted.	`None`

Returns:

Type	Description
`Dict[str, str]`	Dict with keys `"png"` and `"svg"` pointing to the saved figure
`Dict[str, str]`	paths.

Raises:

Type	Description
`FileNotFoundError`	If per-window `M` data are absent in the audit log (no `window_measured` events).

artifacts¶

artifacts ¶

End-to-end artifact bundling for verification runs.

bundle is the convenience entry point used by python -m ldtc.cli.main run to turn a single audit log into a complete, frozen artifact directory:

a paper-style timeline (PNG and SVG) via render_paper_timeline,
an optional SC1 results CSV via write_sc1_table,
a manifest JSON describing the profile thresholds, the device pubkey hash, and the audit hash head, and
a snapshot of the original config plus a short policy notice.

All produced files are then chmod-ed to read-only on POSIX-like filesystems so a results directory is hard to mutate after the fact.

See Also

paper/main.tex: Reporting & Figures; Verification Pipeline.

Functions:

Name	Description
`bundle`	Create a verification artifact bundle from an audit log.

bundle ¶

bundle(artifact_dir: str, audit_path: str) -> Dict[str, str]

Create a verification artifact bundle from an audit log.

Generates a paper-style timeline (PNG and SVG), an optional SC1 CSV table, a manifest JSON describing profile thresholds and artifact paths, an optional config snapshot, and a short policy notice. All produced files are then made read-only on POSIX-like filesystems so a results directory is hard to mutate after the fact.

Parameters:

Name	Type	Description	Default
`artifact_dir`	`str`	Output directory for generated artifacts. Created if missing.	required
`audit_path`	`str`	Path to the JSONL audit log emitted by `AuditLog`.	required

Returns:

Type	Description
`Dict[str, str]`	Dict with keys for produced files: `timeline_png`,
`Dict[str, str]`	`timeline_svg`, `sc1_table` (optional), `manifest`,
`Dict[str, str]`	`config_snapshot` (optional), and a policy `notice`.

Raises:

Type	Description
`FileNotFoundError`	If the audit log is missing or empty.