Task spec¶

Warning

Pre-implementation. This page describes proposed contracts. Class signatures, parameter types, schema fields, and behavior are subject to change before code lands. Once implementation exists, content here will be regenerated from docstrings or sourced from running tests.

A task spec is the per-task contract that wires a TaskID to its metric, OOD (out-of-distribution) axis, readout head, and target domain. One TaskSpec exists per task, pinned by the TaskRegistry, and every other layer of the harness reads from it: the evaluator picks the readout head, the protocol runner applies the axis, the scorer calls the metric. The spec is the contract; the rest is implementation.

The serialized form is the TaskSpec data type, a frozen dataclass mirroring the signature on API / Schemas. YAML configs and recipe files may use the enum string value for each field, because Pydantic deserializes it at validation time (see STYLE.md, enum versus string). The canonical input view for every v0.1 task is multi_antenna_iq, the raw multi-antenna I/Q (in-phase and quadrature) tensor documented in Data model.

Schema fields¶

Field	Type	Purpose
`id`	TaskID	Canonical task identifier, for example `E_LOC_AOA`
`pillar`	Pillar	Top-level task family (`LOCALIZATION`, `IDENTITY`, `CHANNEL`, `SCENE`, `SIGNAL_TO_TEXT`)
`version`	ReleaseVersion	Release the task ships in, for example `V0_1`
`input_view`	`str`	Canonical input representation name; `multi_antenna_iq` for every v0.1 task
`label_schema_ref`	`str`	Reference to the label schema document for the task
`metric_id`	`str`	Identifier of the primary metric class, for example the MeanAngularError class name
`ood_axis`	OODAxis	Primary transfer dimension the task is scored under, for example `LEAVE_ONE_ENVIRONMENT_OUT`
`readout_protocol`	`str`	Name of the readout head ABC the task uses, for example the AngularRegressionHead
`target_domain`	Domain	Target application community, for example `POSITIONING` or `DEFENSE`
`maturity`	Maturity	Contract state; `proposed-contract` until `src/emma/` lands
`rationale`	`str`	One-sentence statement of why the task exists

Note

input_view is multi_antenna_iq for every v0.1 task. The raw multi-antenna I/Q input is non-negotiable for AoA (angle-of-arrival) and beam tasks; derived views such as spectrograms or CSI (channel state information) are computed inside the readout head, never substituted at the input layer.

Note

metric_id names the metric class. The per-task metric wiring, including the metric direction and the standard library it reuses, lives in Metric reference. The OOD axis member in ood_axis must match the protocol the task is scored under; see OOD protocol.

Minimal example¶

The spec declares one task end to end. The YAML below declares E-LOC-AOA: localization pillar, v0.1, raw multi-antenna I/Q input, mean angular error metric, leave-one-environment-out axis, angular regression head, positioning domain.

# task spec (proposal) - declares the E-LOC-AOA task contract
id: E_LOC_AOA
pillar: LOCALIZATION
version: V0_1
input_view: multi_antenna_iq
label_schema_ref: labels/e-loc-aoa.yaml
metric_id: MeanAngularError
ood_axis: LEAVE_ONE_ENVIRONMENT_OUT
readout_protocol: AngularRegressionHead
target_domain: POSITIONING
maturity: proposed-contract
rationale: >-
  Continuous angle-of-arrival regression under an unseen channel environment;
  the flagship task that physically requires inter-antenna phase coherence.

The enum tokens (E_LOC_AOA, V0_1, LEAVE_ONE_ENVIRONMENT_OUT, POSITIONING) are the Python member names of TaskID, ReleaseVersion, OODAxis, and Domain; Pydantic accepts either the member name or the StrEnum string value at validation time. The metric_id and readout_protocol strings name the metric class and the head ABC the registry binds at load time.

References¶

Yang et al., “SUPERB: Speech processing Universal PERformance Benchmark,” Interspeech 2021, arXiv:2105.01051. The one-spec-per-task, shared-input contract the spec formalizes. (verify)
Schmidt, “Multiple emitter location and signal parameter estimation,” IEEE Trans. Acoustics, Speech, Signal Processing 1986, DOI:10.1109/TASSP.1986.1164830. The MUSIC algorithm; grounds the E-LOC-AOA regression-over-classification choice recorded in this spec. (verify)