create_run_summary.py

Purpose: Create a run summary TOML file from event data files

Use case: Recording measurement metadata, organizing measurement sessions

Features:

• Analyzes JSONL event files in a directory
• Extracts device information and metadata from event data
• Saves structured summary in TOML format
• Timestamps are converted to the local timezone (configurable via KAZUNOKO_TZ)

Required input: JSONL event files produced by get_events.py or get_runs.py

Usage:

# Create summary for a measurement directory
uv run examples/create_run_summary.py ./20251221_run126

# With verbose output
uv run examples/create_run_summary.py ./20251221_run126 --verbose

# Custom file pattern
uv run examples/create_run_summary.py ./20251221_run126 --pattern "*.jsonl"

# Overwrite existing summary
uv run examples/create_run_summary.py ./20251221_run126 --overwrite

# Use a specific timezone
KAZUNOKO_TZ=Asia/Tokyo uv run examples/create_run_summary.py ./20251221_run126

CLI Options:

Option	Default	Description
READ_FROM	(required)	Directory containing event JSONL files
--pattern	events*.jsonl	Glob pattern to filter input files
--overwrite	off	Overwrite existing summary file
--verbose / --quiet	--quiet	Show or suppress status messages
--log-level	error	Log level (debug/info/error)

Environment Variables:

Variable	Default	Description
KAZUNOKO_TZ	system timezone	IANA timezone name for timestamps (e.g. Asia/Tokyo)

Output file: READ_FROM/summary.toml

[metadata]
created_at = "2024-12-16T09:48:41+09:00"
directory = "20251221_run126"
total_events = 5000

[device]
mac_address = "AA:BB:CC:DD:EE:FF"
firmware = "1.17.0"

[[files]]
filename = "events_aabbccddeeff_2024-12-16_09h48m41s_0000000.jsonl"
events = 1000