-spec compile_for_nif(network()) -> network().

Compile network for NIF acceleration.

If the NIF is loaded, compiles the network to a flat representation that can be evaluated much faster. Falls back to Erlang evaluation if NIF is not available.

WARNING: Use sparingly! Each compiled network holds a Rust ResourceArc reference that keeps native memory alive. During neuroevolution, do NOT compile networks automatically (especially in create_feedforward or set_weights) as this causes massive memory leaks - one compiled_ref per offspring per generation accumulates unboundedly.

Only call this when you need maximum performance for a specific network that will be evaluated many times (e.g., the final champion network).

-spec create_cfc_feedforward(pos_integer(), [pos_integer()], pos_integer(), atom(), atom() | undefined) ->
                                network().

Create a CfC feedforward network with random weights and CfC neuron metadata.

Same layer structure as create_feedforward but hidden neurons are CfC type. Output neurons remain standard. CfC neurons use evaluate_cfc for temporal adaptation with learnable time constants.

-spec create_feedforward(pos_integer(), [pos_integer()], pos_integer()) -> network().

Create a feedforward network with random weights.

-spec create_feedforward(pos_integer(), [pos_integer()], pos_integer(), atom()) -> network().

Create a feedforward network with specified activation.

-spec create_feedforward(pos_integer(), [pos_integer()], pos_integer(), atom(), atom() | undefined) ->
                            network().

Create a feedforward network with separate output activation.

Hidden layers use Activation, output layer uses OutputActivation. If OutputActivation is undefined, all layers use Activation.

-spec evaluate(network(), [float()]) -> [float()].

Evaluate the network with given inputs.

Performs synchronous forward propagation through all layers. Uses NIF acceleration if available and network was compiled.

-spec evaluate_with_activations(network(), [float()]) ->
                                   {Outputs :: [float()], Activations :: [[float()]]}.

Evaluate network and return all layer activations.

Returns {Outputs, AllActivations} where AllActivations is a list of activation vectors for each layer (including input and output).

-spec evaluate_with_state(network(), [float()]) -> {[float()], network()}.

Evaluate the network with stateful CfC processing.

For standard feedforward networks (no neuron_meta), behaves identically to evaluate/2 but returns {Outputs, Network} tuple.

For CfC networks, each CfC neuron updates its internal state based on the input-dependent time constant, enabling temporal reasoning.

-spec from_binary(binary()) -> {ok, network()} | {error, term()}.

Deserialize a network from binary.

-spec from_genotype(term()) -> {ok, network()} | {error, term()}.

Load a network from a genotype stored in ETS.

Reads the agent's neural network structure and weights from Mnesia and creates an evaluator network.

-spec from_json(map()) -> {ok, network()} | {error, term()}.

Deserialize a network from a JSON-compatible map.

Accepts the format produced by to_json/1.

-spec get_activation(network()) -> atom().

Get the hidden layer activation function from a network.

See get_layers/1 for why callers outside this module should use accessors.

-spec get_layers(network()) -> [layer()].

Get the layer list from a network.

Accessor for consumers outside this module. Use this rather than destructuring the network tuple directly, so that adding fields to the network record cannot silently break callers.

-spec get_neuron_meta(network()) -> [layer_meta()] | undefined.

Get neuron metadata from a CfC network.

Returns undefined for standard feedforward networks.

-spec get_output_activation(network()) -> atom() | undefined.

Get the output layer activation function from a network.

Returns undefined when the output layer uses the same activation as the hidden layers.

-spec get_topology(network()) -> map().

Get network topology information for visualization.

Returns a map with layer sizes for rendering the network structure.

-spec get_viz_data(network(), [float()], [binary()]) -> map().

Get visualization data for rendering the network.

Combines topology, weights, and activations into a format suitable for frontend visualization.

-spec get_weights(network()) -> [float()].

Get all weights from the network as a flat list.

Useful for evolution - can be mutated and set back.

-spec reset_internal_state(network()) -> network().

Reset internal state of a CfC network to zeros.

Call this at the start of each episode to prevent state leakage between independent evaluation sequences (e.g., between game rounds).

-spec set_neuron_meta(network(), [layer_meta()] | undefined) -> network().

Set neuron metadata on a network.

Used by mutation operators to update CfC parameters (tau, state_bound).

-spec set_weights(network(), [float()]) -> network().

Set weights from a flat list.

The list must have the same number of elements as returned by get_weights/1. NOTE: Does NOT compile for NIF - this prevents memory leaks during evolution.

-spec strip_compiled_ref(Network :: network() | map() | term()) -> network() | map() | term().

Strip the compiled_ref from a network to release NIF memory.

IMPORTANT: Call this before storing networks long-term (archives, events) to prevent NIF ResourceArc references from accumulating and causing memory leaks. The compiled_ref is a Rust ResourceArc that holds native memory - keeping references alive prevents the memory from being freed.

The network can be recompiled on-demand when needed for evaluation.

-spec to_binary(network()) -> binary().

Serialize a network to binary using Erlang term format.

This is more compact than JSON and preserves exact floating point values. Use this for Erlang-to-Erlang transfer or storage.

-spec to_json(network()) -> map().

Serialize a network to a JSON-compatible map.

The output format is suitable for JSON encoding and can be loaded in other runtimes (Python, JavaScript, etc.) for inference.

Format: A map with keys "version", "activation", and "layers". The layers list contains maps with "weights" and "biases" keys.