Skip to content

v0.3.7 - Monitor Stdin Piping Support (2025-12-23)

What Changed?

This release adds stdin piping support to the real-time TUI monitor. Users can now pipe detector data directly from event generators or files into the monitor without needing to watch a directory. The original directory monitoring mode remains available via the --watch flag for backward compatibility.

What's New

Stdin Piping for Monitor

What it does: Enables piping JSONL event data directly into the monitor from stdin. The monitor now defaults to reading events from stdin, making it easy to integrate with event generators or data sources. The monitor displays real-time statistics as events arrive via the pipe.

How to use it:

# Read from piped input (default mode)
uv run kazunoko generate ... | uv run examples/monitor.py
cat data.jsonl | uv run examples/monitor.py

# Watch a directory for files (new --watch flag)
uv run examples/monitor.py --watch /path/to/data/directory

Features:

  • Default Stdin Mode: No arguments required for piping
  • Background Thread Reading: Non-blocking JSONL parsing from stdin
  • Directory Monitoring: Optional --watch flag for file-based monitoring
  • Unified Display: Shows "Reading from stdin (pipe mode)" in UI when in stdin mode
  • Real-time Statistics: Event counts, rates, and distributions update as data arrives
  • Graceful Shutdown: Proper cleanup for both stdin and directory monitoring modes

Installation

Quick Start

# Get the release
git checkout v0.3.7

# Setup
uv sync

# Pipe events into monitor
uv run kazunoko generate 10 | uv run examples/monitor.py

# Or watch a directory
uv run examples/monitor.py --watch examples/20251222_run127

What's Different from the Last Version?

✅ Added

  • StdinMonitor class: Reads JSONL events from stdin in background thread
  • Stdin piping as default input mode (no arguments needed)
  • --watch flag for directory monitoring (replaces positional argument)
  • Support for both piping and directory modes in same application

🔧 Changed

  • CLI interface: Changed from positional READ_FROM argument to optional --watch flag
  • FileListPanel: Now shows "Reading from stdin" in pipe mode instead of file list
  • DataMonitorApp: Refactored to support dual-mode operation (stdin vs directory)
  • Status bar: Different messages for stdin vs directory monitoring

🐛 Fixed

  • Unused import cleanup (TextIOWrapper removed from imports)

Is It Safe to Upgrade?

Backward Compatible: Partially

  • Directory monitoring is preserved with --watch flag (breaking change from v0.3.6)
  • Old usage: uv run examples/monitor.py /path/to/directory
  • New usage: uv run examples/monitor.py --watch /path/to/directory
  • Stdin piping is new and adds no breaking changes to library functionality
  • All existing CLI and library features remain unchanged

Tests Passed

  • ✅ Builds without errors
  • ✅ Python compilation check passed
  • ✅ Stdin piping works with JSON event parsing
  • ✅ Directory monitoring preserved with --watch flag
  • ✅ Real-time statistics calculation verified
  • ✅ Graceful shutdown for both input modes
  • ✅ Pre-commit hooks validation passed

Release Details

  • Date: 2025-12-23
  • Version: v0.3.7
  • Files Changed: 2 (examples/monitor.py + version bump)
  • Key Commits:
  • fbbf060 - feat: add stdin piping support to monitor
  • 94f0c55 - bump: version 0.3.6 → 0.3.7

Next Steps

  • Enhanced error handling and validation for malformed JSON events
  • Real-time event filtering by hit_type or ADC thresholds
  • Export functionality from monitor (save filtered events to JSONL)
  • Integration with measurement workflow for automated data collection
  • Performance optimization for high-frequency event streams