Metadata-Version: 2.5
Name: cadence-net
Version: 0.15.0
Summary: Research toward general intelligence through local repair, equilibrium detuning and self-reflection.
Project-URL: Homepage, https://github.com/muellerberndt/cadence
Project-URL: Documentation, https://github.com/muellerberndt/cadence/blob/main/docs/index.md
Project-URL: Issues, https://github.com/muellerberndt/cadence/issues
Author: Bernhard Mueller
License: MIT
License-File: LICENSE
Keywords: brain,connectome,dopamine,equilibrium propagation,local learning,neurons,synapses
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Provides-Extra: accel
Requires-Dist: torch>=2.2; extra == 'accel'
Provides-Extra: apple
Requires-Dist: mlx>=0.20; extra == 'apple'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: numba>=0.60; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: scipy>=1.10; extra == 'dev'
Requires-Dist: torch>=2.2; extra == 'dev'
Provides-Extra: fast
Requires-Dist: numba>=0.60; extra == 'fast'
Requires-Dist: scipy>=1.10; extra == 'fast'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/muellerberndt/cadence/main/docs/assets/cadence-logo.png" alt="Cadence: connected patches with local state, readback and repair" width="100%">
</p>

# Cadence

[Website](https://floatingpragma.io/cadence/) · [Examples](https://github.com/muellerberndt/cadence-examples) · [Paper](https://github.com/muellerberndt/cadence/blob/main/cadence-paper.pdf) · [PyPI](https://pypi.org/project/cadence-net/) · [Documentation](https://github.com/muellerberndt/cadence/blob/main/docs/index.md) · [Changelog](https://github.com/muellerberndt/cadence/blob/main/CHANGELOG.md)

[![PyPI](https://img.shields.io/pypi/v/cadence-net)](https://pypi.org/project/cadence-net/)
[![CI](https://github.com/muellerberndt/cadence/actions/workflows/ci.yml/badge.svg)](https://github.com/muellerberndt/cadence/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/cadence-net)](https://pypi.org/project/cadence-net/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/muellerberndt/cadence/blob/main/LICENSE)

**Research toward general intelligence through overlap consensus, equilibrium detuning and self-reflection.**

Cadence's goal is a continuing learning system with the flexibility of animal
and human problem solving: acquiring skills from experience, retaining useful
knowledge, imagining alternatives and creating solutions across domains.
The mission is to find the smallest persistent state and local update rule
that can support these abilities. The building block stays as simple as possible,
like in nature; every part of a brain answers with a settled state of that one
rule; and where a choice appears, evolution across lives is preferred to design. General intelligence is the research goal;
the current library establishes bounded learning, memory and control results.

The building block is a bounded, observer-like patch with local state,
ports, records, readback and repair. A disturbance exposes disagreement. The
network can explore a possible response, test it against actual consequences
and settle into a revised organization. We seek fewer mechanisms that solve
more problems.

## The roadmap

We want to reach a point where we can effortlessly evolve a human-like brain,
teach it first by imitation and then through its own life, and give it an
experience identical to that of a human living in our world. Brains with
capabilities far beyond ours are thinkable on the same path; human-level
competence comes first, as a sensible milestone. The
[metacognition ladder](docs/METACOGNITION_LADDER.md) orders the steps from the
brains in this library to that milestone, rung by rung, each with its task, its
control, its falsifier and its issue.

## In familiar terms

Cadence is a NumPy library of brains that compute by settling into an equilibrium
and learn by detuning it. A brain is a set of patches joined by ports: groups of
neurons with their synapses, or one context vector with a record store beside it.
The answer is the state the brain settles into under its inputs. Learning settles
once more with the outputs nudged toward the outcome and moves every synapse on the
product of its own two ends in the two settled states, so nothing is propagated
backward. The record store is a fixed sparse code of the reading addressing a table
that takes an outcome in one write and reads it back at the same reading, and a
night of sleep moves what the store holds into the slow weights.
[Cadence for machine-learning people](https://github.com/muellerberndt/cadence/blob/main/docs/orientation.md)
maps each brain to the model you know, says where each learning signal comes from,
and lists the shapes and the words.

## Get started

```bash
python -m pip install cadence-net     # Python 3.11+ and NumPy; torch, MLX and Numba are optional
```

Three brains, each trained in front of you in seconds from fixed seeds, with every
neuron and synapse animated, the distance from equilibrium as a heat on the neurons,
the last change on the synapses, the learning plotted as it is measured, and a line
of text for each phase:

```bash
cadence-demo stream     # a record patch learns a stream, remembers in one shot, and sleeps
cadence-demo decide     # a settling brain decides
cadence-demo body       # a temporal patch learns a consequence and plans
```

Nothing is hosted and there is no checkpoint; [the quickstarts in your browser](https://github.com/muellerberndt/cadence/blob/main/docs/demos.md)
says what equilibrium means in each brain and what detuning buys. The same three
brains in Python are the [quickstarts](https://github.com/muellerberndt/cadence/blob/main/docs/quickstart.md).
This is the record patch: it hears a stream, recalls every outcome after one pass by
day, and after a night with the stream closed says every outcome from its weights alone:

```python
import numpy as np
from cadence import RecordPatchNet

rng = np.random.default_rng(21)
net = RecordPatchNet(
    12, 12, 5, seed=4, cells=2048, active=16, record_rate=1.0, groups=(5,), slowest=8.0
)
symbols = rng.integers(12, size=(3, 8))
heard = np.eye(12)[symbols]
outcome = np.eye(5)[(symbols + np.roll(symbols, 1, axis=1)) % 5]  # the last two symbols decide

for _ in range(8):  # the day: one write per moment, slow weights at rate zero
    net.reset()
    net.observe(heard, outcome, rate=0.0)
net.reset()
awake = net.imagine(heard, state=np.zeros((3, 12)))
assert np.array_equal(awake.output.argmax(-1), outcome.argmax(-1))  # the store recalls

night = net.sleep([heard], passes=240, rate=8.0, backtrack=True)  # dreams, then dawn
alone = RecordPatchNet.restore(net.snapshot())
alone.records.tables["y"][:] = 0.0  # the same weights with an empty store
assert np.array_equal(alone.imagine(heard, state=np.zeros((3, 12))).output.argmax(-1), outcome.argmax(-1))
print(night)
```

[Build your own brain](https://github.com/muellerberndt/cadence/blob/main/docs/build.md)
takes your own data to a trained, evaluated and saved brain of each kind, and
[troubleshooting](https://github.com/muellerberndt/cadence/blob/main/docs/troubleshooting.md)
answers the first questions.

## Which brain

Two primitives, composed through ports, and the belief patch that composes them toward a world model:

| You want | Start with | What it supplies |
| --- | --- | --- |
| to learn from a stream of events, keep single facts after one exposure, and generalise overnight | the record patch, [RecordPatchNet](https://github.com/muellerberndt/cadence/blob/main/docs/record-patch.md) | A gated linear context with a record store inside the patch: an observation is written once by day, and by night the slow weights learn from the store's own dreams (`sleep`), with nothing outside the patch consulted. Categorical ports, batched writes, a store narrower than its port and a two-patch stack. One pass of writes, with no gradient, gives a small grammar for 0.8 of its never-taught combinations; one night lifts the slow weights alone to 1.0. |
| a decision or evaluation over a fixed set of inputs, an explicit wiring, a policy that learns from reward | the settling brain: a [brain of regions](https://github.com/muellerberndt/cadence/blob/main/docs/brain.md) (`Genome`, `develop`, `Brain`, `Learner`) | Local repair of a settled state under any wiring, including a measured connectome; learning by the contrast of a free and a nudged settle; [cortices](https://github.com/muellerberndt/cadence/blob/main/docs/cortex.md), a records cortex, [reward](https://github.com/muellerberndt/cadence/blob/main/docs/reward.md) through eligibility traces, [evolution](https://github.com/muellerberndt/cadence/blob/main/docs/evolution.md) of the genome, and a [certificate](https://github.com/muellerberndt/cadence/blob/main/docs/certificate.md) on the settling. |
| continuous observations and actions, a learned dynamics model, private planning | the temporal patch, [TemporalPatchNet](https://github.com/muellerberndt/cadence/blob/main/docs/temporal.md) | Local repair of observed paths, persistent context, private imagination, [continuous planning](https://github.com/muellerberndt/cadence/blob/main/docs/planning.md) and [protected responses](https://github.com/muellerberndt/cadence/blob/main/docs/temporal-memory.md); learning by the contrast of a free and a nudged settle of the whole path. |
| a belief carried under action, repaired by evidence, that imagines with no observation | the belief patch, [BeliefPatch](https://github.com/muellerberndt/cadence/blob/main/docs/belief.md) | A belief carried by a learned transition under the executed action and repaired by a few iterations of one nonlinear map with the record store read inside it. The composition toward a learned world model, trained with the [imagination loss](https://github.com/muellerberndt/cadence/blob/main/docs/belief.md#training-the-transition-the-imagination-loss) so the transition carries the belief. |

Everything composes through ports: two record patches in depth (`RecordPatchStack`),
several settled as one equilibrium (`JointRecordPatches`), a grid read through a tied
kernel at the port (`StructuredPort`), and a genome that `evolve` mutates and selects
across lives. The [architecture guide](https://github.com/muellerberndt/cadence/blob/main/docs/architecture.md)
is the contract of the temporal patch.

## Examples

The worked applications live in the [examples repository](https://github.com/muellerberndt/cadence-examples),
each a static page that runs its brain in the browser with the library's arithmetic, with the
receipts behind every number it states and a check that recomputes them; the
[examples page](https://github.com/muellerberndt/cadence-examples#readme) lists them all. Two
of them:

<table>
<tr>
<td width="50%"><a href="https://floatingpragma.io/cadence-examples/fly-matrix/"><img src="https://raw.githubusercontent.com/muellerberndt/cadence-examples/main/fly-matrix/screenshot.png" alt="A fly in the Matrix: the whole nervous system of a fruit fly flying a body through a wireframe room"></a><br><b>A fly in the Matrix</b> · <a href="https://floatingpragma.io/cadence-examples/fly-matrix/">live</a> · <a href="https://github.com/muellerberndt/cadence-examples/tree/main/fly-matrix">code</a><br>The 150,802 neurons of a fruit fly, brain and nerve cord wired as measured, as one settling brain flying a body with physics; the physiology gates against shuffled wirings; the mushroom body learning which smell means sugar.</td>
<td width="50%"><a href="https://floatingpragma.io/cadence-examples/amen-beats/"><img src="https://raw.githubusercontent.com/muellerberndt/cadence-examples/main/amen/screenshot.png" alt="Amen: one record patch computes a jungle track from silence"></a><br><b>Amen, the jungle composer</b> · <a href="https://floatingpragma.io/cadence-examples/amen-beats/">live</a> · <a href="https://github.com/muellerberndt/cadence-examples/tree/main/amen">code</a><br>One record patch starts from silence, hears each half-beat it plays and computes sixteen bars of drums, bass and texture.</td>
</tr>
</table>

They are application tests, not definitions of the architecture. A result in one
does not establish transfer to the others. Every example states what is supplied,
what is learned, what was measured and what it does not show, and pins the release
its checks were run against.

Build your own. Fork an example, break it, give the same brain a different body or a
different sense, and put a task in front of it that nobody has tried. Every example,
finished or half-working, is data for us: it says what the architecture does where we
have not looked, and that is what scales this work toward the full humanoid simulation.
Hack things. Be crazy. Chaos is how we learn. The examples repository's
[contributing section](https://github.com/muellerberndt/cadence-examples#contributing)
says what an example needs to live there, including the card every example README carries.

## Documentation

- **Start:** [for machine-learning people](https://github.com/muellerberndt/cadence/blob/main/docs/orientation.md) · [quickstarts](https://github.com/muellerberndt/cadence/blob/main/docs/quickstart.md) · [in your browser](https://github.com/muellerberndt/cadence/blob/main/docs/demos.md) · [build your own brain](https://github.com/muellerberndt/cadence/blob/main/docs/build.md) · [troubleshooting](https://github.com/muellerberndt/cadence/blob/main/docs/troubleshooting.md)
- **Build:** [record patch](https://github.com/muellerberndt/cadence/blob/main/docs/record-patch.md) · [belief patch](https://github.com/muellerberndt/cadence/blob/main/docs/belief.md) · [temporal learning](https://github.com/muellerberndt/cadence/blob/main/docs/temporal.md), [planning](https://github.com/muellerberndt/cadence/blob/main/docs/planning.md), [learn, act and observe](https://github.com/muellerberndt/cadence/blob/main/docs/interaction.md), [response protection](https://github.com/muellerberndt/cadence/blob/main/docs/temporal-memory.md) · [compose a brain](https://github.com/muellerberndt/cadence/blob/main/docs/brain.md), [write a cortex](https://github.com/muellerberndt/cadence/blob/main/docs/cortex.md), [local learning](https://github.com/muellerberndt/cadence/blob/main/docs/learning.md), [records and memory](https://github.com/muellerberndt/cadence/blob/main/docs/memory.md), [reward](https://github.com/muellerberndt/cadence/blob/main/docs/reward.md), [evolve a brain](https://github.com/muellerberndt/cadence/blob/main/docs/evolution.md)
- **Measure:** [task design](https://github.com/muellerberndt/cadence/blob/main/docs/task-design.md) · [common missteps](https://github.com/muellerberndt/cadence/blob/main/docs/missteps.md) · [scaling](https://github.com/muellerberndt/cadence/blob/main/docs/scaling.md) · [certificate](https://github.com/muellerberndt/cadence/blob/main/docs/certificate.md) · [protocols](https://github.com/muellerberndt/cadence/blob/main/docs/protocols.md) · [receipts](https://github.com/muellerberndt/cadence/blob/main/docs/receipts.md) · [the brain viewer](https://github.com/muellerberndt/cadence/blob/main/docs/pages.md) · [backends](https://github.com/muellerberndt/cadence/blob/main/docs/backends.md)
- **Reference:** [API](https://github.com/muellerberndt/cadence/blob/main/docs/api.md) · [changelog](https://github.com/muellerberndt/cadence/blob/main/CHANGELOG.md) · [Lean proofs](https://github.com/muellerberndt/cadence/blob/main/lean/README.md) · [contributing](https://github.com/muellerberndt/cadence/blob/main/CONTRIBUTING.md)
- **The ideas:** [architecture](https://github.com/muellerberndt/cadence/blob/main/docs/architecture.md) · [equilibrium world models](https://github.com/muellerberndt/cadence/blob/main/docs/equilibrium-world-models.md) · [creativity and self-reflection](https://github.com/muellerberndt/cadence/blob/main/docs/creativity.md) · [the metacognition ladder](https://github.com/muellerberndt/cadence/blob/main/docs/METACOGNITION_LADDER.md) · [the paper](https://github.com/muellerberndt/cadence/blob/main/cadence-paper.pdf)

The [index](https://github.com/muellerberndt/cadence/blob/main/docs/index.md) is the full map.

## Four shared principles

- **Overlap consensus:** patches repair disagreement across their shared
  boundaries. The resulting equilibrium is an internally consistent model;
  its predictions have to agree with experience.
- **Equilibrium detuning:** observed outcomes perturb that equilibrium.
  Local positive/negative contrasts change learned relationships; the same
  operation can adjust proposed actions while holding the model fixed.
- **Self-readback:** a patch's proposed actions and predicted consequences are
  available to the same brain and tested by its next observation. Physical
  readback is evidence; an imagined outcome never is.
- **Metacognition as recursive self-observation:** a patch of the same kind reads
  the beliefs, residuals and surprises of the rest of the brain through ordinary
  ports, and its settled state steers them: which evidence counts, where a sense
  samples, what a habit holds, how long a repair runs. Because it is bounded it
  cannot steer everything at once, so it must select what matters for what it is
  computing; that selection is attention. Because it is a patch it can be read in
  turn, and the levels form a ladder from reflex to a robot that acts and speaks
  among people. The genome decides which readbacks exist, and a rung is earned
  only by a task the brain below it fails at matched information and compute.
  The [metacognition ladder](docs/METACOGNITION_LADDER.md) states the rungs, their
  experiments and their issues.

The current implementation provides detached self-readback and private proposal
revision. Learned steering patches, curiosity and reliable
creativity are hypotheses with their tests on the ladder. [Creativity and self-reflection](https://github.com/muellerberndt/cadence/blob/main/docs/creativity.md)
defines these goals and their behavioral tests.

## Equilibrium world models

Cadence is being developed toward **evolving equilibrium world models**: brains
whose internal representation of an actor in its world grows more accurate and
expressive through experience. The representation should carry what is happening,
what persists out of sight, what the actor controls and what its actions could
cause. It need not describe those relationships in words to use them.

An equilibrium here need not mean motionless activity. A skilled actor can
follow a coherent, changing trajectory of perceptions, expectations and actions.
When events unfold as expected, the carried state should be close to a
useful interpretation of the next moment. Familiar danger can prompt a learned
response immediately. Extra inference is needed when competing interpretations
or consequential choices warrant it.

The proposed mechanism is recursive composition through bounded, observer-like,
self-reading patches. Scene, body, candidate action and retrieved experience
meet through learned nonlinear ports. One interpretation can become input to
another, allowing the system to revise its understanding before acting. Actual
evidence anchors that revision; changing the interpretation and learning new
relationships are distinct operations. A random outcome can require a new
response and be consistent with a correctly learned probability
distribution. Teaching detuning uses a specified target to compute a learning
signal; it is not synonymous with surprise.

Skilled demonstrations and the actor's own actions supply complementary
experience. Watching reveals useful behavior and situations; acting tests what
controls actually cause. The same learned relationships should support private
branches that explore possible futures without altering factual memory. Plans
must be judged by subsequent real outcomes. Grounded replay and sleep should
then consolidate reliable relationships and successful decisions into cheaper
habits, while unfamiliar situations can reopen deliberation.

This is the architectural vision. Current APIs provide components and bounded
demonstrations, not the complete evolving world model. Each successive release
is intended to take a concrete step toward this goal. Progress must be shown in
prediction, retention, useful internal planning and behavior at declared
resource budgets; a new version alone does not establish it. The
[equilibrium world-model guide](docs/equilibrium-world-models.md) explains the
mechanism, the distinction between evidence repair and learning, and the current
implementation boundaries.

## What the library establishes

**Imagined continuations are isolated.** Branches use the learned network
without changing live activity, parameters or factual bookkeeping. Controlled
experiments demonstrate useful planning. Creativity requires additional
evidence that novel proposals satisfy meaningful constraints and survive
actual evaluation; musical improvisation is one possible example.

**Retained experience and new learning are tested together.** Protected-path
memory is conditional and finite. Importance is supplied; automatic
relevance, selective forgetting, specialization and broad skill transfer are
research requirements. The [task-design guide](https://github.com/muellerberndt/cadence/blob/main/docs/task-design.md)
and [common missteps](https://github.com/muellerberndt/cadence/blob/main/docs/missteps.md) explain how to measure them.

**General mechanisms, different applications.** Games, language, multimodal
perception, embodied control and creative work should use the same learning and
memory mechanisms with declared observation and action ports. The scaling goal is
better learned behavior from more experience and training, with as little manual
design as possible. Measure unique experience, repeated training and model
capacity separately while keeping port meanings and task evaluation fixed. The
[scaling guide](https://github.com/muellerberndt/cadence/blob/main/docs/scaling.md)
defines these comparisons and the current computational limits.

Application demonstrations are published only when they establish their
claimed behavior. Recall and interpolation are useful development tests;
original creation requires stronger evidence. Every example states what is
supplied, what is learned, what was measured and what it does not show, and
carries a check that recomputes its numbers. Research receipts are
available with the paper without presenting those tests as finished products.

## Proofs and compatibility

The [bundled Lean library](https://github.com/muellerberndt/cadence/blob/main/lean/README.md)
contains 169 checked conditional theorems about the mathematical components
and their limits. It does not certify the complete Python implementation or
prove intelligence. The paper identifies assumptions and reproducible evidence.

The [PatchNet graph interface](https://github.com/muellerberndt/cadence/blob/main/docs/patchnet.md),
`GenericBrain`, [EquilibriumActor](https://github.com/muellerberndt/cadence/blob/main/docs/actor.md),
content memory, rehearsal and sequence readback are kept for
the experiments that used them; they are distinct compositions, not parts of the two
primitives. [API reference](https://github.com/muellerberndt/cadence/blob/main/docs/api.md).

Development installs use `python -m pip install -e ".[dev]"`; [contributing](https://github.com/muellerberndt/cadence/blob/main/CONTRIBUTING.md)
lists the checks. [Optional backends](https://github.com/muellerberndt/cadence/blob/main/docs/backends.md)
apply to their documented graph APIs; the temporal implementation is NumPy.
Pin a release or exact commit for reproducible work. MIT licensed.

## Origins

Cadence started as an offshoot of a physics theory,
[Observer Patch Holography](https://github.com/FloatingPragma/observer-patch-holography),
which models reality itself as a metaphorical brain: a distributed network of
observers that finds global equilibria by repairing local conflict. The two
projects complement each other and share many of their theorems.
