@spec action_to_one_hot(atom()) :: Nx.Tensor.t()

Encode an action atom as a one-hot tensor of shape {@num_actions}.

@spec actions() :: [:hide | :show | :expand | :shrink | :none, ...]

Returns the ordered list of action atoms.

@spec build_model() :: Axon.t()

Build the Axon model graph.

Architecture: input(10) -> dense(32, relu) -> dense(16, relu) -> dense(5, softmax)

@spec compiled_model() :: {function(), function()}

Returns the compiled {init_fn, predict_fn} pair, cached via persistent_term.

@spec extract_features(map(), [atom()]) :: {Nx.Tensor.t(), [atom()]}

Extract per-pane feature tensors from a behavior aggregate.

Returns {features_tensor, pane_ids} where features_tensor has shape [n_panes, 10].

Features (per pane)

1. dwell_pct -- fraction of total dwell time
2. is_most_used -- 1.0 if highest dwell
3. is_least_used -- 1.0 if in least-used set
4. alert_response_norm -- normalized alert response time
5. scroll_freq_norm -- normalized scroll frequency
6. scroll_vel_norm -- normalized scroll velocity
7. command_conc_pct -- fraction of commands targeting this pane
8. takeover_pct -- fraction of takeover time on this pane
9. pane_count_norm -- total panes / 10 (normalized)
10. dwell_rank_norm -- rank position / pane_count (0.0 = most used, 1.0 = least)

@spec feature_size() :: 10

Returns the number of input features per pane.

@spec init_params() :: map()

Initialize random model parameters.

@spec interpret_predictions(Nx.Tensor.t(), [atom()]) :: [{atom(), atom(), float()}]

Interpret model output into ranked pane action recommendations.

Returns a list of {pane_id, action, confidence} tuples sorted by confidence descending, excluding :none actions.

@spec model_version() :: 2

Returns the model version for parameter compatibility checking.

@spec predict(map(), Nx.Tensor.t()) :: Nx.Tensor.t()

Run inference on feature tensor, returns action probabilities.

@spec train(
  [{Nx.Tensor.t(), Nx.Tensor.t()}],
  keyword()
) :: map()

Train the model on accumulated feedback data.

training_data is a list of {features_tensor, label_tensor} tuples where features is {1, 4} and label is {5} (one-hot).

Returns trained model parameters.