Skip to content

Interop Contract

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

Interop Contract

Status: frozen docs/contract (LIM-228 / GH#14)
Source of truth in-repo: docs/src/interop.md (and Documenter site)

This freeze describes compact data shapes at the package boundary — not new SNN types and not a change to routing math.

Ownership boundary

Owns

Shape Role
ActivityRegion Compact per-region summary for one tick
RegionRouter Mutable routing state
update_routing! In-place per-tick update
routing_diagnostics Log string
adapt_leak! Optional stress → leak helper

Does not own

  • Spike event lists or full trains
  • Neuron / synapse / membrane state
  • Reservoir simulation or training
  • Token embeddings, ANN/LLM adapters, deployment supervision
  • Hardware telemetry (callers reduce telemetry to rates)

Core shapes

ActivityRegion

Field Type Contract
last_spike_rate Float32 [0, 1] this tick
output Vector{Float32} Length n_out

Caller duties: normalize rates yourself; match n_out; prefer Float32 end-to-end.

RegionRouter outputs / fields (interop-relevant)

Field Contract
routing_weights length n_regions, sum ≈ 1, primary output
adjacency_matrix n×n; mask (> 0 gates inhibition)
inhibition_matrix n×n lateral coefficients
rates / EMA / surprise Float32 as documented in API

Constructor:

RegionRouter(; n_regions=4, n_out=16, region_names=DEFAULT_REGION_NAMES,
               inhibition_matrix=nothing)

Tick contract

update_routing!(router, regions::Vector{ActivityRegion}) -> nothing
Input Requirement
regions length == router.n_regions
rates Float32 in [0, 1] preferred
readouts length router.n_out each
Output Contract
router.routing_weights length n, positive-ish, sum ~1
return nothing

MIN_SCORE clamps pre-/mid-normalization scores; after re-normalization individual entries may fall below MIN_SCORE.

Numeric conventions

Quantity Convention
Element type Float32
Activity rates [0, 1] caller-normalized
routing_weights sum ~1
Time base Caller-defined tick; package is tick-agnostic

Non-Julia consumers: treat the boundary as f32 arrays with the dimensions above. No spike timestamps at the API surface.

Explicit non-shapes

Not package types / not in this freeze:

  • Spike trains / event lists
  • Full membrane or synapse tensors
  • Shared “modulator” blobs beyond ActivityRegion.output
  • Config objects for α/β/γ (still module-level constants on main)

Inhibition is configurable via inhibition_matrix=.

See also

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

Clone this wiki locally