Skip to content

v0.1.2 - MockGenerator and Event Simulation (2025-12-01)

What Changed?

This release introduces MockGenerator for flexible detection event simulation. Users can now generate realistic mock detection events from random sources or JSONL files, with configurable timing (speed and jitter). A new simulate command provides direct event streaming for testing pipelines. The library and CLI maintain full backward compatibility.

What's New

Main Feature: MockGenerator Class

What it does: Generates realistic detection event sequences from multiple sources (random or JSONL file) with configurable timing behavior. Supports speed multipliers (0.01-100x) and event timing jitter for realistic simulation.

How to use it:

# Generate random events
gen = MockGenerator.from_random(count=100, seed=42)
gen.set_speed(2.0).set_jitter(0.1)

# Load from file
gen = MockGenerator.from_file("events.jsonl")
gen.set_speed(1.0)

# Get next event with timing
event = gen.get_next_event()  # Blocks for configured delay

New CLI Command: simulate

What it does: Streams generated detection events to stdout in JSONL format, perfect for testing event processing pipelines.

How to use it:

# Generate 100 random events at normal speed
kazunoko simulate random --count 100

# Replay events from file at 2x speed with jitter
kazunoko simulate file:events.jsonl --speed 2.0 --jitter 0.1

# Generate deterministic events with seed
kazunoko simulate random --count 50 --seed 42 -v

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • MockGenerator class with from_file() and from_random() factory methods
  • Time-based event simulation with speed and jitter configuration
  • simulate CLI command for event generation and streaming
  • Comprehensive error handling (FileNotFoundError, JSONDecodeError, ValueError)
  • Input validation for speed (0.01-100x) and jitter (non-negative)
  • _setup_generator() helper for generator initialization
  • MockDevice integration with optional MockGenerator support

🔧 Changed

  • Separated listen command from mock functionality (now real device only)
  • Improved CLI structure: listen for devices, simulate for mocks
  • Enhanced MockDevice to support both generator and legacy queue_data() methods
  • Improved documentation and type annotations throughout

🐛 Fixed

  • Proper UTF-8 encoding in file operations
  • JSON error reporting with line numbers
  • Negative interval handling in timing calculations
  • Event dict copying to prevent mutation side effects

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • Existing MockDevice.queue_data() method continues to work
  • listen command behavior unchanged (still connects to real device)
  • send and info commands unchanged
  • New simulate command is additive only
  • No breaking changes to public API

Tests Passed

  • ✅ Builds without errors (uv sync)
  • ✅ Type checking passes (mypy src/)
  • ✅ Linting passes (ruff check src/)
  • ✅ MockGenerator from_file() loads JSONL correctly
  • ✅ MockGenerator from_random() generates events with seed
  • ✅ Speed and jitter validation works
  • ✅ Event timing delays work correctly
  • ✅ MockDevice generator integration works
  • ✅ Legacy queue_data() still works

Release Details

  • Date: 2025-12-01
  • Version: v0.1.2
  • Files Changed: 2 (src/kazunoko/mock.py, src/kazunoko/cli.py)
  • Commits:
  • d7be7f5: feat: implement MockGenerator for detection data simulation
  • 0cdb0e8: fix(mock): improve MockGenerator with better error handling
  • 2ba80ad: fix(mock): improve from_random method with defaults
  • 16e2f62: fix(mock): add validation for jitter parameter
  • 5e0d4c4: fix: improve set_speed method with validation
  • 2946070: feat: implement time-based event simulation
  • 5d6c144: feat: add MockGenerator support to MockDevice
  • f9a26ef: refactor(mock): reorder class definitions
  • 2025b57: feat(mock): integrate MockGenerator into receive_response
  • 923fd8c: refactor(mock): improve code quality and documentation
  • 37c6d2f: feat: add MockGenerator support to listen command
  • 273eedc: refactor(mock): separate simulate command from listen
  • d7276f0: refactor(mock): remove mock option from listen command

Next Steps

  • Add pytest tests for MockGenerator edge cases
  • Consider async event streaming for large datasets
  • Add template event files for common scenarios (constant, sinusoidal, burst patterns)
  • Expand CLI documentation with pipeline examples