> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadenzalabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Megan makes your robots self-learn on the edge — adapting in the environment, as a human would, without retraining or a human in the loop.
**Megan makes your robots self-learn — on the edge, in the environment, as they
run.** You ship a robot with a frozen, well-trained policy. Then the world moves:
a new obstacle appears, the dynamics drift, a disturbance starts hitting on a
rhythm. A frozen policy can't cope with what it never saw. Megan lets the robot
**learn its way through it on-device** — the way a person adjusts on the job —
with no retraining run, no labels, and no human in the loop.
Megan is a **steering token** that rides on top of your existing policy and adapts
it **only through governed changes**. It never retrains your model wholesale and
never touches actuators directly. It watches the task unfold, decides *whether* and
*where* to change, and commits a change only if the robot measurably did better —
otherwise it rolls back. That governance is what makes learning in the wild safe.
## Learning like a human, on the edge
* **On the edge.** The decision path is torch-free and runs on the robot
(Jetson-class hardware). No cloud dependency at runtime.
* **In the environment.** Adaptation happens *while the task runs*, against the
real world in front of the robot — not offline on a dataset.
* **Self-supervised.** Reality supplies the labels: the robot predicts what comes
next, and the world delivers the real next state a moment later. The gap between
the two is a genuine learning signal — no annotation needed.
* **Governed.** Every change is gated: keep it only if it helped and stayed stable.
## How it knows it's actually learning
Megan doesn't change things and hope. It measures a few simple signals every round
(this is what the `megan-cd` engine tracks under the hood) and only commits a change
that improves them:
| Signal | What it asks | Rule |
| -------------- | --------------------------------------------------------------------------- | ----------------------------------------------- |
| **Progress** | Is the robot getting closer to the objective / is prediction error falling? | Must improve. |
| **Stability** | Does the working outcome stay within tolerance? | Never destabilise a task that already succeeds. |
| **Skill** | Is it better than doing nothing (× vs. a "world froze" baseline)? | Recover skill after the world changes. |
| **Efficiency** | Is the same task getting faster over repetitions? | Speed up only while stability holds. |
The governance is **commit-or-rollback**: a change is applied only if it measurably
improved *and* the outcome stayed stable within tolerance; otherwise it's reverted.
In a controlled test where the world's dynamics shifted mid-deployment, a frozen
model's skill collapsed to **0.66** — *worse than assuming the world had frozen* —
while Megan brought it back to **\~2.6**, recovering online in a couple of adaptation
steps. Honest, partial, real recovery — not a staged demo.
## The three ways a robot self-learns
Everything Megan does falls into three capabilities. Each optimises one of the
signals above.
Some disturbances recur on a beat — a conveyor bump, a gust, a load that shifts
every few seconds. Megan **learns the rhythm** from the times it happens, then
tells the robot to protect *ahead* of the next hit and which protective action
is currently best. The robot stops reacting late and starts anticipating, the
way an experienced worker braces before the machine kicks.
When the frontier of a task is blocked, a frozen policy pushes into the wall.
Megan watches progress toward each milestone and, the moment the current plan
stops working, routes the robot to **adapt** — *here* — so your change-doer can
find a way around instead of stalling. It's the difference between a robot that
gives up at an obstacle and one that works out a detour.
Once a task reliably succeeds, Megan makes it **faster, one committed step at a
time** — nudging the slowest part quicker (or dropping a redundant step) and
keeping the change only if the outcome still lands within tolerance. Over
repetitions the robot sheds the caution it needed while learning and settles
into a smooth, efficient routine — exactly how a human speeds up with practice.
## The locked contract
Megan returns **only the actionable decision** — never the internals it used to
reach it.
Responses carry `route` + `frontier` (sessions) and `should_protect` +
`best_action` + `ready` (anticipators) — and nothing else. The progress metric,
stall counters, the blocked flag, the learned rhythm's period/phase/confidence, and
the reasoning trace all stay on the server. The routes are also **rate-limited per
account** so the decision boundary can't be reconstructed by probing.
You integrate against a stable, minimal decision surface, and the valuable
self-learning mechanism can't leak out of a response.
## Two ways to reach it
| Path | Use it when |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| **SDK** — `from cadenza_cli import MeganTK` | You're building an application or control loop and want to drive Megan from code. |
| **CLI** — `cadenza apikey`, `cadenza usage` | You want your API key to paste elsewhere, or to inspect what you've consumed. |
```python theme={null}
from cadenza_cli import MeganTK
tk = MeganTK(api_key="") # or MeganTK() to auto-resolve it
with tk.session("pick up the red cube", ["reach", "grasp", "lift"]) as s:
d = s.step(reached=[0], obstacles=[{"id": "wall", "milestone": 1}])
if d.adapt: # the plan is blocked — route around it
handle(d.frontier) # ...at this milestone
```
## Next
Install the SDK, get your key, make your first call.
Wire self-learning into a real control loop.