Metadata-Version: 2.5
Name: cadence-net
Version: 0.50.0
Summary: Deep Recursive Settlement Networks: processing populations and observers learning and settling together.
Project-URL: Homepage, https://floatingpragma.io/cadence/
Project-URL: Documentation, https://github.com/muellerberndt/cadence/blob/main/docs/index.md
Project-URL: Repository, https://github.com/muellerberndt/cadence
Project-URL: Issues, https://github.com/muellerberndt/cadence/issues
Author: Bernhard Mueller
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: cortical column,local learning,observer,recursive observation,settling,supervised learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
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
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: torch>=2.5; extra == 'gpu'
Description-Content-Type: text/markdown

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

# Cadence

[Website](https://floatingpragma.io/cadence/) · [Demo](https://github.com/muellerberndt/cadence-demos) · [Paper](https://philpapers.org/rec/MUECAP-2) · [PyPI](https://pypi.org/project/cadence-net/) · [Documentation](docs/index.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: GPL v3](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/muellerberndt/cadence/blob/main/LICENSE)

**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.

The aim is a straightforward replacement for legacy deep neural networks,
including transformers, built around persistent recursive settlement.
Performance comparisons are ongoing.

Cadence implements this population architecture with a standard-library Python
engine and optional tensor execution on CPU, Apple Silicon GPU or NVIDIA GPU.
Every processing and observer patch uses one local prediction relation. The
compiled brain supports joint settlement, supervised witness learning,
diagnostics and continuation.

In the **bootstrapping phase**, guided experience teaches the brain its basic
abilities. In the **live phase**, that same brain acts in its environment and
can continue learning from actual new witnesses. Both phases use the same
patch rule and retained world model.

## Three pillars

- **Minimalism:** one patch rule, a small public API, no required 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](AGENTS.md) define the checks.

## The demo: a brain plays Doom

The main Cadence demo is [Doom Lab](https://github.com/muellerberndt/cadence-demos/tree/main/doom-lab):
a settling brain plays shareware Doom in your browser from pixels alone —
two grayscale retinas in, eight settled motor states out, no policy network
and no backpropagation. Take the controls yourself and your frame-and-button
pairs are admitted as witnesses while you play; a live, rotatable 3D view
shows the populations settling, the wiring carrying signal, and each
committed batch as it changes the brain. Brains hot-swap mid-game and travel
as single export files.

```sh
git clone https://github.com/muellerberndt/cadence-demos
cd cadence-demos/doom-lab && ./get_wad.sh && python server.py
```

The complete training pipeline ships with it — scripted privileged teacher,
witness corpora, conditioned batched bootstrap with matched controls, DAgger
correction rounds, and a foresight variant trained on measured outcomes:
[demo page](https://floatingpragma.io/cadence/demos/) ·
[training tutorial](https://github.com/muellerberndt/cadence-demos/blob/main/doom-lab/TRAINING.md).

## Install

Python 3.11 or later; the default engine has no runtime dependencies:

```sh
python -m pip install --upgrade "cadence-net>=0.49.0"
```

If your package index has not listed a new release yet, its wheel is also
available from [GitHub Releases](https://github.com/muellerberndt/cadence/releases/latest).

For GPU execution, install the optional tensor extra:

```sh
python -m pip install --upgrade "cadence-net[gpu]"
```

Choose `Cortex(device="mps")` for an Apple Silicon GPU or
`Cortex(device="cuda")` for a compatible NVIDIA GPU. The same brain methods
and learning rule apply. Final admission is checked against the original
float64 objective. Small brains can be faster with the default Python engine;
see [GPU execution and parallel experience](docs/ACCELERATION.md) for precision,
measurement and independent simulated lives.

## Declare the brain

```python
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 learned 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
[bootstrapping guide](docs/BOOTSTRAP.md).
Inspection also reports sensor coverage for each output coordinate, so you can
check the decision's connections before bootstrapping.

## Bootstrapping phase

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

```python
from cadence import bootstrap

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

examples = [({"signal": [x]}, {"answer": [x]}) for x in (-0.8, 0.8)]
checks = [({"signal": [x]}, {"answer": [x]}) for x in (-0.4, 0.4)]
report = bootstrap(learner, examples, checks=checks, max_error=0.2)
assert report["passed"], report

# 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.

Use **batch bootstrapping** to jointly learn from groups of examples:

```python
batch_report = bootstrap(
    learner, examples, checks=checks, max_error=0.2, batch_size=32,
)
assert batch_report["passed"], batch_report
```

Each batch jointly settles private example states and shared parameters;
CPU/GPU tensors vectorize the examples. `brain.observe_batch(examples)` admits
one batch directly. Batch commits preserve live activity and update parameters
atomically. The default `batch_size=1` keeps ordered single-experience learning.
See [batch bootstrapping](docs/BOOTSTRAP.md) for the objective and resource tradeoffs.

## Live phase

```python
activity = learner.step({"signal": [0.3]})
assert activity["accepted"]
print(activity["outputs"]["answer"])

# When an actual teaching signal arrives, the same brain can keep learning.
assert learner.observe({"signal": [0.3]}, {"answer": [0.3]})["accepted"]
```

`bootstrap` supplies reproducible replay and unclamped readiness checks.
Applications supply sensory acquisition, witnesses, actuator interpretation
and environment-specific behavior checks. The [guide](docs/BOOTSTRAP.md)
explains calibration and staged bootstrapping for perception and body control.

Development support for a continuing life adds explicit sensory `History`,
discrete reward learning with `Reinforcement`, an optional `LearningProgress`
curiosity signal, and a `LiveController` that keeps rendering independent of
brain work. Reward-derived action values are labeled estimates and learned by
the same patch repair. Replay and checkpointing preserve experience for later
use. These additions follow 0.49.0; see [memory, rewards and live control](docs/LIVE.md)
for setup, examples and the boundary between learned decisions and body support.

## 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.
Discrete Q-learning and bounded temporal history have small behavioral checks;
long-lived learned memory, broader capability and advantages from recursive
depth require further controlled experiments. Follow the
[DRSN completion epic](https://github.com/muellerberndt/cadence/issues/51).

| Documentation | Scope |
| --- | --- |
| [DRSN guide](docs/DRSN.md) | Population layouts, equations, learning, all configuration, diagnostics and checkpoints |
| [Quickstart](docs/QUICKSTART.md) | Inputs, settlement, learning and saved continuation |
| [Bootstrapping and live phases](docs/BOOTSTRAP.md) | Calibration, guided experience, small starting layouts and readiness checks |
| [GPU execution and parallel experience](docs/ACCELERATION.md) | Device selection, precision, checkpoint transfer and concurrent simulated lives |
| [API reference](docs/REFERENCE.md) | Every public class, method and configuration parameter |
| [Mathematical specification](docs/SPECIFICATION.md) | Guarantees, qualification and evidence boundaries |

GPL-3.0-or-later license.
