Skip to content

API Reference

Jump to bottom
Raul Montoya Cardenas edited this page Jul 29, 2026 · 2 revisions

API Reference

Grounded in main @ c9ff99c. Frozen interop shapes: Interop Contract.

Preferred exports

ActivityRegion
RegionRouter
update_routing!
routing_diagnostics
adapt_leak!
save_state, load_state!, load_state

ActivityRegion

struct ActivityRegion
    last_spike_rate::Float32
    output::Vector{Float32}
end

ActivityRegion(last_spike_rate::Float32, output::Vector{Float32})
ActivityRegion(n_out::Int)  # zero rate, zero readout of length n_out
Field Contract
last_spike_rate Normalized firing rate in [0, 1] (caller-normalized; package does not rescale Hz)
output Readout length n_out (must match router)

Immutable value type — rebuild or replace each tick.

RegionRouter

RegionRouter(;
    n_regions::Int = 4,
    n_out::Int = 16,
    region_names::Vector{String} = DEFAULT_REGION_NAMES,  # Region1..Region4
    inhibition_matrix = nothing,  # nothing → default_inhibition_matrix(n_regions)
)

Mutable state; pre-allocated at construction.

Field Shape Notes
n_regions, n_out Int Dimensions
region_names Vector{String} Labels; auto-extends with Region$i if short
adjacency_matrix n×n Float32 Edge mask for inhibition
inhibition_matrix n×n Float32 Lateral coefficients
routing_weights n Float32 Primary output; sum ~1
readout_ema n × n_out EMA of readouts
spike_density n Last rates
prev_routing_weights n Momentum buffer (see Routing Algorithm)
prev_relevance n Scratch / raw scores
surprise n Manifold surprise
scratch n_out Hot-path scratch
tick_count Int64 Tick counter

Initial weights are uniform (1 / n_regions).

Default inhibition

default_inhibition_matrix(n) (internal; used when inhibition_matrix=nothing):

  • n ≤ 4: top-left slice of historical asymmetric INHIBIT (4×4)
  • n > 4: zero diagonal; off-diagonal 0.08f0 / abs(i - j)

Custom matrices must be exactly n_regions × n_regions (Float32 conversion applied).

update_routing!

update_routing!(router::RegionRouter, regions::Vector{ActivityRegion}) -> nothing
Requirement Detail
length(regions) == router.n_regions One summary per region
Each output length router.n_out
Rates Prefer [0, 1] Float32

Updates in place: routing_weights, EMA, surprise, densities, tick counter. Consume router.routing_weights, not a return value.

routing_diagnostics

routing_diagnostics(router::RegionRouter)::String

Example shape: [tick=N] name=w … | dominant=… | surprise=[…]

adapt_leak!

adapt_leak!(leak_rate::Ref{Float32}, stress::Real;
            min_leak::Real = 0.01f0,
            max_leak::Real = 0.25f0,
            stress_adapter = nothing)

Optional helper (LIM-233). Default: treat stress as percent-scale [0, 100] → unit, then lerp min_leak..max_leak. Custom stress_adapter(stress) → [0,1] (clamped). Throws ArgumentError on non-finite bounds or normalized stress, or if min_leak > max_leak.

Not part of the core routing loop.

Checkpointing

snap = save_state(router)::NamedTuple
load_state!(router, snap)   # preferred mutating API
load_state(router, snap)    # alias of load_state!

See Checkpointing.

Module-level scoring constants

Not exported as a config type on main; defined in region_router.jl:

Constant Default Role
ALPHA 0.50f0 Spike density weight
BETA 0.35f0 Surprise weight
GAMMA 0.15f0 Momentum weight
EMA_DECAY 0.05f0 EMA step size
MIN_SCORE 0.01f0 Soft floor
EPSILON 1.0f-6 Numerical floor

Legacy mirrors: NERO_ALPHA, NERO_BETA, …
Default names: DEFAULT_REGION_NAMES = ["Region1","Region2","Region3","Region4"] (also NERO_DEFAULT_LOBE_NAMES).

Known limitations (main)

  • No public RoutingConfig struct yet (scoring is module globals).
  • NERO aliases still exported.
  • Some older README/docs text still mentions Attention/FFN/Memory/Output; source defaults are Region1–Region4 (trust the code).

Last updated: July 29, 2026 Updated by: Grok Build: Grok 4.5 Package tip reference: c9ff99c (main)

Clone this wiki locally