Skip to content

v0.1.16 - JSON Flattening for CLI Output (2025-12-06)

What Changed?

This release adds JSON flattening support to kazunoko CLI, enabling researchers to export detector data in flattened JSON format for integration with data pipelines and Unix tools. The status command now supports --flatten for single-line JSON output, and the read command supports --format csv|ssv for CSV and space-separated values output. All flattened output preserves 100% of field data with underscore-separated keys.

What's New

Main Feature: Flattened JSON Output Format

What it does: Converts nested OSECHI detector JSON responses into flat structures with underscore-separated keys (e.g., system_version, detection_trigger_count). Enables piping detector data directly to files and processing with standard Unix tools like jq, grep, and data analysis tools.

How to use it:

# Display status as flattened single-line JSON
kazunoko status --flatten

# Pipe to jq for field queries
kazunoko status --mock --flatten | jq .system_version

# Export detection events to CSV
kazunoko read --format csv > events.csv

# Export detection events to space-separated values
kazunoko read --format ssv > events.txt

Flattening Algorithm:

  • Nested dicts: joins keys with underscore (system.version → system_version)
  • Arrays: creates indexed keys (items[0] → items_0, items[1] → items_1)
  • Scalars: preserved as-is (numbers, strings, booleans, None)
  • Deep nesting: recursively flattened to single level

Installation

Quick Start

# Get the release
git checkout v0.1.16

# Setup
uv sync

# Run CLI
uv run kazunoko --help
uv run kazunoko status --mock --flatten

What's Different from the Last Version?

✅ Added

  • status --flatten option: outputs detector status as single-line flattened JSON
  • read --format csv|ssv option: streams detection events in CSV or space-separated values format
  • Internal _flatten() helper function for recursive dict/list flattening
  • Flattening algorithm preserves 100% of field data with underscore-separated keys

🔧 Changed

  • MockDevice command names: STATUS → GET_STATUS, UPTIME → GET_UPTIME (consistency with Command class)
  • CLI output behavior: status command still defaults to table format (backward compatible)

🐛 Fixed

  • MockDevice consistency: command names now match Command layer expectations

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • Default table format is preserved for status command
  • Flattening is opt-in via --flatten flag
  • New --format option for read command doesn't affect existing behavior
  • All existing commands and options work unchanged

Tests Passed

  • ✅ Builds without errors
  • ✅ kazunoko status --mock (table format - default)
  • ✅ kazunoko status --mock --flatten (flattened JSON output)
  • ✅ kazunoko read --format csv (CSV export)
  • ✅ kazunoko read --format ssv (space-separated values export)
  • ✅ Pre-commit hooks (linting, commitizen)

Release Details

  • Date: 2025-12-06
  • Version: v0.1.16
  • Branch: 002-add-flattener
  • Files Changed: 3 (cli.py, mock.py, docs)
  • Commits:
  • c2e4c80: docs: update progress log - JSON flattening feature implementation completed
  • (plus previous commits for CLI and MockDevice updates)

Next Steps

  • Optional: Create public flattener.py module if library users need programmatic access to flatten() function
  • Optional: Add --flatten option to other commands (query, threshold, etc.)
  • User Story 3 (P2): Field filtering/selection in flattened output (future enhancement)