SDK reference

This page documents the hosted Megan SDK — the metered HTTP client for milestone sessions, disturbance anticipators, and the progress-scalar governor.For megan’s relation chain running in your own process — an instruction parsed into aligned → near → grasped → lifted → over → placed, grounded entities, and per-step guidance — see Relational megan. It is a different surface with a different vocabulary, not a newer version of this one, and the hosted API has no relational routes.

Everything is importable from the top-level package:

from cadenzalabs import (
    MeganTK, MeganSession, Anticipator, Governor,
    Decision, ProtectResult,
    MeganTKError, AuthRequired,
)

# the local relational surface, installed with cadenzalabs[megan]
from cadenzalabs import Megan, relational_available

`MeganTK`

The client, bound to one account’s token. Construct once and reuse.

MeganTK(api_key=None, *, api_url=None, timeout=30.0)

Argument	Type	Default	Purpose
`api_key`	`str \| None`	resolved	The token. If `None`, resolved from `CADENZA_API_KEY`, `CADENZA_TOKEN`, then the CLI session.
`api_url`	`str \| None`	hosted API	Base URL override. Falls back to `CADENZA_API_URL`, then `https://www.api.cadenzalabs.xyz`.
`timeout`	`float`	`30.0`	Per-request timeout, seconds.

Raises AuthRequired at construction if no key can be resolved.

Methods

Method	Returns	Description
`version()`	`dict`	`{service, megantk_version, api_version}`. Open route — no auth, not metered.
`ping()`	`bool`	`True` if the token authenticates (raises otherwise).
`usage(days=30)`	`dict`	Your metered consumption. See Usage.
`session(objective, milestones, *, ring_radii=None, obstacle_block_radius=0.8, config=None)`	`MeganSession`	Open a token session.
`anticipator(actions=(), *, lead=1.4, guard=0.8, min_events=2)`	`Anticipator`	Open a disturbance anticipator.
`governor(*, n_candidates=9, patience=6, eval_window=6, epsilon=0.2, seed=0)`	`Governor`	Open a progress-guided governor.

`session(...)`

Argument	Type	Default	Purpose
`objective`	`str`	—	The goal the token pursues.
`milestones`	`Sequence[str]`	—	Ordered milestone chain (at least one).
`ring_radii`	`Sequence[float] \| None`	`None`	One shrinking radius per milestone. Provide to enable `perceive`.
`obstacle_block_radius`	`float`	`0.8`	How close an obstacle must be to block (perception path).
`config`	`dict \| None`	`None`	Optional MeganToken config overrides.

`anticipator(...)`

Argument	Type	Default	Purpose
`actions`	`Sequence[str]`	`()`	Protective action names to register.
`lead`	`float`	`1.4`	Seconds to start protecting before a predicted hit.
`guard`	`float`	`0.8`	Seconds to keep protecting after.
`min_events`	`int`	`2`	Disturbances observed before the period is trusted.

`governor(...)`

Argument	Type	Default	Purpose
`n_candidates`	`int`	`9`	Candidate action-frame rotations searched.
`patience`	`int`	`6`	Flat-progress steps before it adapts.
`eval_window`	`int`	`6`	Steps each correction trial is scored over.
`epsilon`	`float`	`0.2`	Explore rate once every candidate has been tried once.
`seed`	`int`	`0`	RNG seed (reproducible).

`MeganSession`

A live token session. Returned by MeganTK.session(). A context manager — close() runs on __exit__. Attributes: session_id: str, objective: str, milestones: list[str], perception: bool.

Method	Returns	Description
`step(reached=(), obstacles=())`	`Decision`	Milestone path. `reached`: milestone indices satisfied. `obstacles`: `{"id","milestone"}` dicts or `(id, index)` tuples.
`perceive(position, goal, obstacles=())`	`Decision`	Perception path (session must have `ring_radii`). `obstacles`: `{"id","position"}` dicts or `(id, position)` tuples.
`status()`	`dict`	`{session_id, session_step, objective, perception}`.
`close()`	`bool`	Delete server-side. Idempotent — `True` first time, `False` after.

`Anticipator`

A live disturbance anticipator. Returned by MeganTK.anticipator(). A context manager. Attributes: anticipator_id: str, actions: list[str].

Method	Returns	Description
`disturbance(t)`	`dict`	Log a disturbance at time `t` (seconds). Returns `{anticipator_id, ready, best_action}`.
`outcome(name, saved)`	`dict`	Record whether registered action `name` preserved the outcome.
`protect(t)`	`ProtectResult`	Should you protect at time `t`?
`status()`	`dict`	`{anticipator_id, ready, best_action}`.
`close()`	`bool`	Delete server-side. Idempotent.

`Governor`

A live progress-guided governor. Returned by MeganTK.governor(). A context manager. The bandit + gating run server-side; you send scalar progress and apply the returned phi (radians) to your action’s (x, y). Attributes: governor_id: str.

Method	Returns	Description
`episode_start()`	`dict`	Impose the learned correction and reset per-episode state. Returns `{governor_id, governor_step, best_phi, adapting}`. Call once per episode.
`step(progress)`	`float`	Report live scalar `progress`; returns the action-frame rotation `phi` to apply this step. Uses only step-to-step gains (scale/offset irrelevant).
`step_full(progress)`	`dict`	Like `step` but returns `{phi, adapting, governor_step}`.
`status()`	`dict`	`{governor_id, governor_step, best_phi, adapting}`. `best_phi` is the learned correction.
`close()`	`bool`	Delete server-side. Idempotent.

`Decision`

Frozen value object returned by step / perceive.

Field	Type	Meaning
`route`	`str`	`'continue'` or `'adapt'`.
`frontier`	`str \| None`	The milestone attention is on (e.g. `'milestone_1'`).
`session_step`	`int`	Monotonic step counter.
`adapt`	`bool` (property)	`True` when `route == 'adapt'`.

`ProtectResult`

Frozen value object returned by protect.

Field	Type	Meaning
`should_protect`	`bool`	Engage a protective action now?
`best_action`	`str \| None`	Which registered action is currently best.
`ready`	`bool`	Whether the rhythm is learned enough to act on.

Errors

from cadenzalabs import MeganTKError, AuthRequired

Exception	Raised when
`AuthRequired` (subclass of `MeganTKError`)	No key could be resolved, or the server returned 401/403 (invalid/revoked token, deactivated account).
`MeganTKError`	Any other API problem — bad request (422), rate limit (429), not found (404), or an unreachable API. The message is the server’s human-readable `detail`.

from cadenzalabs import MeganTK, AuthRequired, MeganTKError

try:
    tk = MeganTK()
    d = tk.session("goal", ["a", "b"]).step(reached=[0])
except AuthRequired as e:
    ...   # fix the key / sign in
except MeganTKError as e:
    ...   # transient / bad input — inspect str(e)

See Building deep for retry and rate-limit patterns.

Introduction

Configure

Using the CLI

Megan

Reference

`MeganTK`

Methods

`session(...)`

`anticipator(...)`

`governor(...)`

`MeganSession`

`Anticipator`

`Governor`

`Decision`

`ProtectResult`

Errors

​MeganTK

​Methods

​session(...)

​anticipator(...)

​governor(...)

​MeganSession

​Anticipator

​Governor

​Decision

​ProtectResult

​Errors

`MeganTK`

Methods

`session(...)`

`anticipator(...)`

`governor(...)`

`MeganSession`

`Anticipator`

`Governor`

`Decision`

`ProtectResult`

Errors