muellerberndt/cadence

Website · Documentation · Application demos · Paper · PyPI

One continuing equilibrium brain: learn a world, act in it, repair what fails.

from cadence import Brain

brain = Brain.compose(inputs=4, actions=2, arousal=True)
action = brain.live([[1.0, 0.0, 0.0, 0.0]])

Execute the returned action, then pass its measured reward with the next observation: brain.live(next_observation, reward=reward). Tune named settings with compose or brain.retune(...); inspect them with brain.describe(). The composition guide explains defaults and which learning rates each operation uses.

Cadence is not a feed-forward deep neural network. Its primary application is one acquired brain continuing through experience.

Cadence aims to build a simulated human-like brain from simplified biological mechanisms. Its default System 1 is a continuing animal-like brain with perception, plastic connections, memory and action. Optional System 2 adds recursive feedback through observing cortical regions in the same neural graph. The base can already be deep and modular. Biological names describe functional software roles.

Bounded, observer-like regions carry local neural state. The composition declares sensory and motor indices, exposes activity for readback and retains working traces and cue/outcome associations. Reciprocal regions constrain one another as the neural graph settles; actions require its full equations to qualify. Actual observations and consequences guide local plasticity and memory writes. The aim is to bootstrap a useful interpretation, use it in an ongoing life, and repair witnessed failures while retaining the same acquired brain.

Learned parameters and memories support a family of equilibria under changing evidence and context. They do not hold the brain at one frozen state. An internally consistent answer can still be wrong about the world: numerical settlement and useful understanding need separate evidence.

Start with one continuing equilibrium brain, the canonical guide to this lifecycle and its current implementation boundaries. Brain.compose already supplies continuing action, local learning and memory, and Brain.live adds a first routine-and-repair loop for one stream, measured on one bounded chamber. Integrated learned world prediction, repair localized to what failed and cheap stable operation remain development goals. Cadence is alpha research software.

compose constructs the brain; live runs its life. The explicit arousal=True uses the founder arousal settings; omitting it preserves the lower-level composition for step, teaching and batched streams. brain.last_settlement is an optional diagnostic report. Release history belongs in the changelog.

Start with the simplest existing System 1: proposed additions must remain local repair within the same equilibrium and demonstrate benefit without losing working capabilities. Animal and human brains guide the abstraction, including finite capacity and possible rigidity.

Brain.compose(inputs=4, actions=2, modules=(64, 32, 16)) builds reciprocal processing regions whose activity settles together. Later regions can shape earlier ones while an answer forms. Working and associative memory contribute to the current drive; the selected motor action comes from the qualified neural state. An external trained readout would be a separate answer-producing model.

The graph learner compares local activities in free and nudged phases, without a backward differentiation pass through those phases. Default teaching and reward eligibility are finite; LearnerConfig(qualified=True, ...) explicitly requires supervised phases to qualify before updating. Other Cadence model families have their own learning contracts, including explicit adjoints in record and belief models.

Independent classification and calibration remain useful mechanism tests. They do not exercise the complete continuing brain. Recurrent networks trained by backpropagation can also learn online and use memory: the relevant comparison is acquired behavior and total work on the same task and information, not an architectural label. See the update mechanisms.

The library makes continuing state, reciprocal interpretation, local plasticity and memory available in one small interface. A saved brain can resume an action awaiting its actual outcome. Private imagination can inspect responses without rewriting live experience. These are mechanisms for testing acquisition, retention and recovery through a life.

The target includes full-sentence language and reusable world understanding. A small fixed-label task is a control, not that destination. Greater capability, scalability and efficiency than transformers must be established with matched comparisons. A small numerical residual does not measure low physical energy or guarantee a correct answer.

Python 3.11+ and NumPy are required. Install the published release for this basic example:

python -m pip install cadence-net==0.83.0

Its released documentation describes the APIs included in that package.

import numpy as np
from cadence import Brain

brain = Brain.compose(inputs=4, actions=2, arousal=True)
observation = np.array([[1.0, 0.0, 0.0, 0.0]])
action = brain.live(observation)

# A tiny environment rewards action 0 and supplies the next observation.
reward = (action == 0).astype(float)
next_observation = np.array([[0.0, 1.0, 0.0, 0.0]])
action = brain.live(next_observation, reward=reward)
assert action.shape == (1,)

live takes the preceding action's measured reward, then chooses the next action for one continuing stream. Supply one observation row per call. A calm brain acts greedily without learning; youth or arousal enables exploration, learning and memory writes. There is no training/inference mode switch. Continuous interaction covers arousal, resets and saved continuation.

For explicit teaching, batched streams or learning from every outcome, use the lower-level step loop. Its teacher= labels the current observation. The continuing brain example demonstrates that explicit teaching policy through changed conditions and saved continuation. It is an advanced control over the same composed brain.

The constructor includes a working trace and fast/persistent associative memory. The trace carries recent activity; learned graph parameters and consolidated associations retain changes across resets. A current teacher changes graph parameters. Actual chosen-action outcomes write associative memory. act reads both memory pathways; independent predict and accuracy read neither, so they measure the graph's learned response. Capacity is finite; overlapping associations and further plasticity can interfere with recall.

phases = brain.imagine([observation, next_observation])
assert phases  # Inspect phase.converged before using an imagined response.

Imagination carries a private trace without changing live memory, random state or pending feedback. It evaluates responses to the observations you supply. For learned environmental consequences and action planning, use the separate temporal model.

To work from source, install from the library repository root:

python -m pip install -e .

This installs the local source as an editable package.

The API keeps each completed action solve's residual, qualification, sweeps and check counts in read-only brain.last_settlement, including refused attempts. These diagnostics exclude learning, reward eligibility and memory work. The quickstart shows how to inspect them; the continuing example also records other settling phases. Cheap routine operation and a useful response to surprise must be measured, not inferred from a small residual.

recursive = Brain.compose(
    inputs=4, actions=2, modules=(16, 8), observers=(8,), seed=7,
    arousal=True,
)

Observer regions read and return influence to the base, motor regions and earlier observers. They join the same settlement and use the same interaction interface. This makes recursive feedback available; learning when it helps remains a task for experience and evaluation.

Actions and independent predictions require the full neural equation residual to meet the configured tolerance. Exhausting the budget refuses an action without changing its live state, memory or pending feedback. If live has accepted an outcome before the next action refuses, retry live(observation) without submitting that reward again. Numerical damping stays within the total budget and checks the original equations. It does not change the teaching rule. See contracts.

The design points in one page: MANIFESTO.md, including the dedicated language goal, whole consistent sentences from the settled state.

Build a brain for custom wiring, memory for traces and associations, and the memory/planning example for a bounded demonstration with actual toy-body outcomes. Record patches provide event records and consolidation. The advanced population solver provides exact state-and-error readback under its own numerical contract.

cadence-demos contains the application demos.

Cadence has an official memecoin on Solana. Its token address is 46doJPsSjEVMsNZm4b32UbbvbUXjFTM3TDPBWMM3pump (chart on Dexscreener). Any other token using the Cadence name is unrelated to this project.

Pragma Research did not deploy the token and holds none of it. It was set up so that Bernhard Mueller can claim all the SOL fees it generates, and those fees have been a very helpful source of funding for Cadence.

Cadence itself does not use the token, and no integration into the core library is planned. We encourage the crypto community to build interesting projects that integrate it.

Nothing here is financial advice.

Documentation · API · Contributing · Changelog · Research tasks

Licensed under GPL-3.0.