Cadence: recursive settling populations with local state, readback and repair

Cadence

Website · Examples · Paper · PyPI · Documentation

Build Deep Recursive Settlement Networks: processing populations and their observers, learning and settling together.

Cadence explores a simple idea: a brain can be a persistent system of local relations that repairs its state as experience arrives. An observer reads what other patches are doing and influences them while remaining part of the same equilibrium. Another observer can read that enlarged system in turn.

Cadence implements this population architecture in pure Python, using only the standard library. Every processing and observer patch uses one local prediction relation. The compiled brain supports joint settlement, supervised witness learning, diagnostics and continuation.

Three pillars

Minimalism: one patch rule, a small public API, no runtime dependencies. Focused modules keep each responsibility easy to find.
User-friendliness: explicit layouts, sensible defaults and runnable examples.
Agent-friendliness: exact contracts, inspectable state and explicit refusal.

Every core change is reviewed against all three. The contributor instructions define the checks.

Install

Python 3.11 or later; no runtime dependencies:

python -m pip install --upgrade "cadence-net>=0.45.0"

If your package index has not listed a new release yet, its wheel is also available from GitHub Releases.

Declare the brain

from cadence import Cortex

cortex = Cortex(seed=7)
eyes = cortex.input("eyes", shape=(8, 8))
ears = cortex.input("ears", shape=(2, 16))
body = cortex.input("sensory_nerves", shape=(8,))
senses = (eyes, ears, body)

c1 = cortex.column("perception", patches=16, inputs=senses)
c2 = cortex.observer(
    "integration", patches=8, inputs=senses, observes=(c1,),
)
c3 = cortex.observer(
    "reflection", patches=8, inputs=senses, observes=(c1, c2),
)
cortex.output("motor_nerves", shape=(8,), reads=c3)
brain = cortex.build()

assert brain.inspect()["patches"] == 32
assert brain.inspect()["sensor_coverage"] == 104

inputs supplies sensory or represented data. observes adds readback of live patch states and exact current prediction errors. Observer constraints feed back into the observed states through the same energy and repair process. They are not a separate decision made after the lower system finishes.

Population size counts processing patches. Sensor shape counts input samples; a larger camera shape does not supply trained visual understanding. The eight outputs expose eight settled patch values, without a separate policy network. The guide also shows parallel sensory branches and inspection of actual wiring. Every patch reads all coordinates of its declared sources by default; explicit fan_in opts into sparse sampling. This is a layout example, not a pretrained vision/audio model. For a first learning task, start smaller using the training guide. Inspection also reports sensor coverage for each output coordinate, so you can check the decision's connections before training.

Learn a small relation

This inexpensive example teaches a small brain a signed input/output relation. It uses the same population primitive, with fewer patches for a quick run.

teacher_layout = Cortex(seed=2)
signal = teacher_layout.input("signal", shape=(1,))
base = teacher_layout.column("base", patches=4, inputs=signal)
reflection = teacher_layout.observer(
    "reflection", patches=2, inputs=signal, observes=base,
)
teacher_layout.output("answer", shape=(1,), reads=reflection)
learner = teacher_layout.build()

for event_id in range(40):
    value = (-0.8, 0.8)[event_id % 2]
    update = learner.observe(
        {"signal": [value]}, {"answer": [value]}, event_id=event_id,
    )
    assert update["accepted"]

# Fresh amplitudes, with no output targets supplied to the brain.
assert learner.predict({"signal": [-0.4]})["answer"][0] < -0.2
assert learner.predict({"signal": [0.4]})["answer"][0] > 0.2

Actual witnesses clamp the supplied outputs and allow joint repair of live state and retained relation parameters. Only qualified proposals are committed. Queries hold learned parameters fixed; hypothetical clamps never become experience. Learning is evaluated on later unclamped predictions, as above. This example establishes a small acquired relation, not a benefit from depth.

Scope

The reference engine repairs a nonlinear residual energy using analytic derivatives and a bounded descent procedure. Every participating population is included in the final constrained-stationarity check. Prediction errors can remain nonzero at a qualified compromise; different starting states can reach different stationary points. A solver can refuse when its budget is exhausted.

Performance evaluations and comparisons remain ongoing. Tests cover layouts, derivatives through recursive error readback, reciprocal interventions, actual acquisition, refusal and checkpoint custody. The goal is a reusable learner across perception, memory, reasoning and embodied action. Reward-driven temporal credit, broader capability and advantages from recursive depth require further controlled experiments. Follow the DRSN completion epic.

Documentation	Scope
DRSN guide	Population layouts, equations, learning, all configuration, diagnostics and checkpoints
Quickstart	Inputs, settlement, learning and saved continuation
Training and size	Small starting layouts, data conditioning, teaching and validation
API reference	Every public class, method and configuration parameter
Mathematical specification	Guarantees, qualification and evidence boundaries

MIT license.

Metadata

Release files for cadence-net 0.45.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cadence-net 0.45.0
File	Size	Uploaded
cadence_net-0.45.0.tar.gz	1.2 MB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cadence-net 0.45.0
File	Interpreter	ABI	Platform	Reset
cadence_net-0.45.0-py3-none-any.whl 23.3 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 1.3 MB

Release files / cadence_net-0.45.0.tar.gz

Download URL	cadence_net-0.45.0.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`ed48883d1256eb5cc778e52fa3848b10c032ee6997d42dabae75eba8f16cf151`
BLAKE2b-256 checksum How to use checksums	`524b19a4f10c4cdb4257bae2808bba2b1089a4baf606625bda187cec0aa23375`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.0`

Release files / cadence_net-0.45.0-py3-none-any.whl

Download URL	cadence_net-0.45.0-py3-none-any.whl
Size	23.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`113cadecd2a30414b3dd923d4b956ea51b56e9dc53003db0e92b33f1634fab75`
BLAKE2b-256 checksum How to use checksums	`f2f41c434175eb297fb0ffeb16afb4f05a7c96a9dd1dfcb2e46582ae75229375`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.0`