Skip to content

v0.12.0 - Command History Tracking (2025-12-28)

What Changed?

This release adds automatic command history tracking to measurement scripts. Users can now record what commands were executed, when they started and completed, and the final status (completed, interrupted, or error). A new history.py sample utility provides reusable command execution metadata tracking for OSECHI detector measurement sessions.

What's New

Main Feature: Command History Tracking Utility

What it does: The new examples/history.py module provides a CommandHistory dataclass that tracks command execution metadata including:

  • Full command string reconstruction from sys.argv
  • Execution lifecycle tracking (started → completed/interrupted/error)
  • Device metadata collection (port, MAC address, firmware version)
  • JSONL-based persistence for easy analysis

How to use it: Copy history.py into your measurement script directory and use it like this:

from history import CommandHistory
from pathlib import Path

# Create history tracker at measurement start
history = CommandHistory.from_cli_context(
    executable=Path(sys.argv[0]).name,
    argv=sys.argv,
    port="/dev/ttyUSB0",
    mac_address="aa:bb:cc:dd:ee:ff",
    firmware="v1.2.3",
    kazunoko_version="0.12.0",
)

# Save initial state (status="started")
history_path = Path("20251228") / "command_history.jsonl"
history.save(history_path)

try:
    # Run measurement
    # ... measurement code ...

    # Update on success
    history.update_status("completed")
    history.save(history_path)
except KeyboardInterrupt:
    history.update_status("interrupted")
    history.save(history_path)
except Exception:
    history.update_status("error")
    history.save(history_path)

Output Format:

{"command":{"full_command":"get_events.py '1:300;2:300;3:300' 1000 --save","executable":"get_events.py","subcommand":null,"args":["1:300;2:300;3:300","1000"],"options":{"save":true,"port":"auto"}},"execution":{"started_at":"2025-12-28T12:34:56.123456+00:00","completed_at":"2025-12-28T12:45:23.789012+00:00","status":"completed","duration_sec":627.67},"device":{"port":"/dev/ttyUSB0","mac_address":"aa:bb:cc:dd:ee:ff","firmware":"v1.2.3","kazunoko":"0.12.0"}}

Installation

Quick Start

# Get the release
git checkout v0.12.0

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • examples/history.py: Sample utility for command history tracking in measurement scripts
  • Command history integration in get_events.py demonstrating single-session tracking
  • Command history integration in get_runs.py demonstrating multi-run session tracking
  • Command history integration in get_thresholds.py demonstrating threshold scan tracking

🔧 Changed

  • Example scripts now optionally record command execution metadata to command_history.jsonl
  • History tracking is gracefully degraded if history.py is not available

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All changes are additive and optional
  • Measurement scripts work identically with or without history.py
  • No breaking changes to the core kazunoko library
  • History tracking only activates when history.py is imported in user scripts

Tests Passed

  • ✅ Builds without errors
  • ✅ All example scripts run with and without history tracking
  • ✅ JSONL format validation
  • ✅ Exception handling for history recording failures

Release Details

  • Date: 2025-12-28
  • Version: v0.12.0
  • Files Changed: 4 (history.py, get_events.py, get_runs.py, get_thresholds.py)
  • Commits: refactor(examples): move command history tracking to main() in get_thresholds.py

Next Steps

  • Integration with web UI for visualizing command execution history
  • Database storage option for long-term history tracking
  • Command replay functionality for reproducing past measurements