Main brain and state machine#

The main brain: a supervisor that keeps a state machine over the robot’s sub-agents and may consult a local language model.

Structure#

Sub-agents (MotorSubAgent, SensorSubAgent, PerceptionSubAgent, Heartbeat) each watch one sub-system and report a Status with a health level (OK, WARN, FAULT, HEALING, FAILED). The motor sub-agent wraps MotorAgent, which does its own local self-healing.
State machine (StateMachine): the robot is in one Mode (BOOT, CALIBRATING, NOMINAL, DEGRADED, HOLD, SAFE_STOP). Only the transitions in TRANSITIONS exist; anything else is refused and logged.
Brain (RuleBrain or LocalLLMBrain): when a sub-system reports something other than OK, the brain picks one action from the set allowed in the current mode. A local LLM can be the brain, but it only proposes: its reply must be JSON with an allowed action, and hard rules run first and cannot be overridden (any FAILED sub-agent means SAFE_STOP; SAFE_STOP is left only by a human reset). An unparsable or disallowed reply falls back to the rule brain and is counted.
Supervisor (Supervisor): runs the sub-agents every step, fires state-machine events, asks the brain, applies the action to the command, and keeps an incident log.

The LLM is optional and runs locally (ollama_generate() talks to an Ollama server on this machine; any str -> str callable works). No language model ships with the library and none was run during development: the LLM path is tested with scripted replies only.

Classes

`Health`	Health level a sub-agent reports, from fine (`OK`) to out of service (`FAILED`).
`Mode`	Operating mode of the robot, the states of the supervisor's state machine.
`Status`
`Decision`
`StateMachine`
`MotorSubAgent`	Reports the motor agent's view: healing a fault, failed (safe stop) or fine.
`SensorSubAgent`	Encoder, MEMS and quantum accelerometer health.
`PerceptionSubAgent`	Grounding confidence: WARN while the instruction is ambiguous (the gate would ask).
`Heartbeat`	Watchdog: FAILED if no telemetry arrived within `timeout` seconds.
`RuleBrain`	Deterministic policy; also the fallback when the LLM misbehaves.
`LocalLLMBrain`	Ask a local language model to choose the action.
`Supervisor`	The main brain's loop: sub-agent statuses -> state-machine events -> brain decision -> command limits.

Functions

`ollama_generate`	A `generate` function for a local Ollama server (needs Ollama running on this machine; not exercised in the test suite).
`run_supervised_episode`	Two-leg move under the main brain.

class Health(*values)[source]#

Bases: Enum

Health level a sub-agent reports, from fine (OK) to out of service (FAILED).

class Mode(*values)[source]#

Bases: Enum

Operating mode of the robot, the states of the supervisor’s state machine.

class Status(name: 'str', health: 'Health', message: 'str' = '', data: 'dict' = <factory>)[source]#

Bases: object

Parameters:

name (str)
health (Health)
message (str)
data (dict)

class Decision(action: 'str', reason: 'str' = '', source: 'str' = 'rules')[source]#

Bases: object

Parameters:

action (str)
reason (str)
source (str)

class StateMachine[source]#: Bases: object

class MotorSubAgent[source]#

Bases: object

Reports the motor agent’s view: healing a fault, failed (safe stop) or fine.

class SensorSubAgent(quantum_timeout=3.0, bias_limit=0.15)[source]#

Bases: object

Encoder, MEMS and quantum accelerometer health.

class PerceptionSubAgent[source]#

Bases: object

Grounding confidence: WARN while the instruction is ambiguous (the gate would ask).

class Heartbeat(timeout=0.5)[source]#

Bases: object

Watchdog: FAILED if no telemetry arrived within timeout seconds.

class RuleBrain[source]#

Bases: object

Deterministic policy; also the fallback when the LLM misbehaves.

class LocalLLMBrain(generate, fallback=None)[source]#

Bases: object

Ask a local language model to choose the action. generate(prompt) -> str is any local text generator.

The prompt carries the mode, every status and the allowed actions; the reply must contain {"action": ..., "reason": ...}. A reply that is not JSON, or names an action that is not allowed in this mode, is discarded and the rule brain decides (counted in stats).

class Supervisor(subagents=None, brain=None, calibrate_steps=20, recover_steps=40, dt=0.05, slow_factor=0.5)[source]#

Bases: object

The main brain’s loop: sub-agent statuses -> state-machine events -> brain decision -> command limits.

human_reset()[source]#: The only way out of SAFE_STOP (an operator has inspected the machine).

observe(ctx)[source]#: Run one supervision step with the telemetry context; returns the current mode.

limit(u)[source]#: Apply the current action to a motor command.

ollama_generate(model='llama3.2', host='http://localhost:11434', timeout=30.0)[source]#: A generate function for a local Ollama server (needs Ollama running on this machine; not exercised in the test suite).

run_supervised_episode(act, rng, faults=(), brain=None, steps=100, switch_at=30, tol=0.0625, heal=True, dropped_telemetry_at=None)[source]#

Two-leg move under the main brain. Returns the final error, the mode trace and the supervisor.

dropped_telemetry_at (seconds) stops telemetry from arriving from then on, which the heartbeat must catch.