Live Calibration

← Back to Index

Purpose

Live Calibration is a runtime adjustment layer between raw analysis and confirmed model values. It lets operators tune behavior for room/system conditions without changing core model logic.

Calibration control is currently WebSocket-only (no REST endpoint).

What Changed

Recent vendetta-engine updates added:

  • simplified 4-axis calibration model with mapping functions
  • built-in templates embedded in engine:
    • punchy_dry
    • rolling_melodic
    • minimal_hypnotic
  • template persistence beside the executable:
    • vendetta-calibration-templates.json
  • richer runtime calibration state with:
    • raw values
    • axes
    • axis custom flags
    • reverse detection + override flag
    • blend threshold scale factor
    • active template
  • runtime engine support for:
    • toggling reverse detection
    • runtime blend-threshold scaling
    • reverse sustain fallback/reclassification when reverse detection is disabled
  • frame payload extensions:
    • calibration.reverse_detection
    • calibration.blend_threshold_scale_factor
  • new WS controls:
    • calibration.axes.get
    • calibration.axes.set
    • calibration.reverse_detection.set
    • calibration.templates.get
    • calibration.template.apply
    • calibration.template.save
  • richer calibration object in calibration.get / calibration.set / calibration.reset responses
  • unit tests for axis/reverse/blend mapping

Calibration Surface

The runtime surface is now axis-oriented instead of exposing only raw low-level dials.

Operator-facing shape:

  • raw: low-level calibration values
  • axes: simplified 4-axis control values
  • axis_custom: per-axis custom flags
  • reverse_detection: effective reverse detection state
  • reverse_detection_override: override flag/value
  • blend_threshold_scale_factor: runtime blend-threshold scale
  • active_template: currently active template metadata

Templates

Template presets are available at runtime and can be applied or saved over WebSocket.

Built-in templates:

  • punchy_dry
  • rolling_melodic
  • minimal_hypnotic

Persistence behavior:

  • templates are persisted beside the executable in vendetta-calibration-templates.json
  • saved templates survive process restarts

WebSocket Control Contract

Inbound control messages

Existing controls

  • calibration.get
  • calibration.set
  • calibration.reset

These now return/emit the richer calibration object described above.

New controls

calibration.axes.get

Requests current axes state and related calibration metadata.

{ "type": "calibration.axes.get" }
calibration.axes.set

Applies an axes patch and optional reverse detection override. reverse_detection_override accepts true, false, or null (clear override).

{
  "type": "calibration.axes.set",
  "axes": {
    "axis_name": 0.58
  },
  "reverse_detection_override": null,
  "source": "ui.axes"
}
calibration.reverse_detection.set

Sets reverse detection mode directly. enabled accepts true, false, or null (clear override/use default behavior).

{
  "type": "calibration.reverse_detection.set",
  "enabled": false,
  "source": "ui.toggle"
}
calibration.templates.get

Returns available built-in + persisted templates.

{ "type": "calibration.templates.get" }
calibration.template.apply

Applies a template by name.

{ "type": "calibration.template.apply", "name": "rolling_melodic" }
calibration.template.save

Saves current state as a template. label is optional.

{
  "type": "calibration.template.save",
  "name": "warehouse_room_a",
  "label": "Warehouse Room A"
}

Outbound meta events

  • calibration_state
  • calibration_updated
  • calibration_reset
  • calibration_error

Meta envelopes include:

  • version
  • t_ms

Frame Contract Additions

stream.frame includes calibration metadata that can affect interpretation in realtime, including:

  • calibration.reverse_detection
  • calibration.blend_threshold_scale_factor

Use these together with:

  • source_blend
  • source_blend_reliable

Runtime Behavior

  • calibration changes apply to future evaluation cycles only
  • no retroactive story re-evaluation
  • reverse detection can be enabled, disabled, or override-cleared at runtime
  • when reverse detection is disabled, reverse sustain classification uses fallback/reclassification behavior
  • threshold behavior remains blend-aware:
    • effective = base * (1 + blend * threshold_scale_factor)
    • variance/sustain scaling capped at 2x
    • weight-band confirmation not scaled