Skip to content

hylo-plugin-examples

Example third-party plugins for Hylo: one per extension point, each with a test and a config

Repository hylo-plugins, packages/hylo-plugin-examples. Licence: Apache-2.0. Depends on: hylo-core, hylo-eval, hylo-learn, hylo-agents, numpy>=1.24.

Registered entry points
Group Name Object
gate_tests examples.min_effect hylo_examples.stats:MinEffectMcNemar
guards examples.slow_zone hylo_examples.guards:SlowZoneGuard
learners examples.cem hylo_examples.online:CEMLearner
policies examples.ik_reacher hylo_examples.policies:IKReacherPolicy
policies examples.mixture hylo_examples.policies:MixturePolicy
Module Summary
hylo_examples Example Hylo plugins, written the way a third party would: own package name, entry points, no changes
hylo_examples.guards Example guard plugin: a slow zone (speed and separation monitoring, simplified)
hylo_examples.online Example online learner: the cross-entropy method over an agent's numeric parameters
hylo_examples.policies Policy plugins (group "policies"): one written from scratch, one composed from other registered policies
hylo_examples.stats Example gate-test plugin: statistical and practical significance

hylo_examples

Example Hylo plugins, written the way a third party would: own package name, entry points, no changes to Hylo. One per extension point; see the harness's docs/extending.md.

META module-attribute 

META = {'contracts': {'learners': 'hylo.learner/v0.1', 'gate_tests': 'hylo.gate_test/v0.1', 'policies': 'hylo.policy/v0.1', 'guards': 'hylo.guard/v0.1'}, 'maturity': 'implemented'}

hylo_examples.guards

Example guard plugin: a slow zone (speed and separation monitoring, simplified).

Inside a disc around center (e.g. where a person works next to the robot) every action is scaled down to factor of its size. Runs between the shield's mandatory finite and bounds checks like every guard plugin.

safety: {guards: [{type: examples.slow_zone, params: {state_key: pos, center: [0.5, 0.5], radius: 0.2, factor: 0.3}}]}

SlowZoneGuard 

SlowZoneGuard(state_key: str, center: list[float], radius: float, factor: float = 0.3)

name class-attribute instance-attribute 

name = 'slow_zone'

review 

review(data: ndarray, ctx: SafetyContext) -> GuardVerdict

hylo_examples.online

Example online learner: the cross-entropy method over an agent's numeric parameters.

Each iteration samples a population of parameter vectors from a Gaussian, rolls each one out on the development split (the runner does that), keeps the elite fraction by score and refits the Gaussian to the elites. The sealed artifact holds the best parameters found; a LearningProposer turns them into a candidate, which the gate then judges on init states the search never saw.

proposer: {type: learn, params: {learner: examples.cem, online: true, python: <this venv>,
           params: {space: {kp: {path: params.kp, low: 0.1, high: 6.0}}, population: 6, iterations: 3},
           patch: {agent.params.kp: "{metrics.best.kp}"}}}

The same contract fits on-policy RL: policies() returns the current policy, update() reads the rollouts' traces (run_dir) and takes a gradient step, seal() writes the weights.

CEMLearner

name class-attribute instance-attribute 

name = 'hylo_examples.cem@0.1'

start 

start(job, agent: dict[str, Any]) -> None

policies 

policies() -> list[dict[str, Any]]

update 

update(results: list[dict[str, Any]]) -> dict[str, Any]

finished 

finished() -> bool

seal 

seal(out: str, sources: list[Any]) -> ArtifactManifest

hylo_examples.policies

Policy plugins (group "policies"): one written from scratch, one composed from other registered policies.

  • examples.ik_reacher: a scripted chunk policy for MuJoCo planar reach, with seeded exploration noise.

  • examples.mixture: several policies behind one name. mode "sample": each seed picks one member (with weights), so steering's sample-and-select chooses among the members' proposals; mode "mean": the members' chunks averaged (an ensemble).

    agent: {type: steered, params: {sampler: {type: examples.mixture, params: {members: [...]}}, steering: {n_samples: 4, selector: medoid}}}

IKReacherPolicy 

IKReacherPolicy(gain: float = 0.3, horizon: int = 8, noise: float = 0.1, l1: float = 0.3, l2: float = 0.25, max_step: float = 0.05)

For mujoco.planar_reach: analytic two-link IK to the target, a chunk of joint steps toward it, plus seeded exploration noise (so steering has different proposals to choose from).

spec 

spec() -> AgentSpec

reset 

reset(ctx: EpisodeContext) -> None

default_execution_steps 

default_execution_steps() -> int

sample 

sample(observation: Observation, seeds: list[int] | None, noise_scale: float = 1.0) -> np.ndarray

MixturePolicy 

MixturePolicy(members: list[dict[str, Any]], weights: list[float] | None = None, mode: Literal['sample', 'mean'] = 'sample')

members instance-attribute 

members = [build_policy(m) for m in members]

spec 

spec() -> AgentSpec

reset 

reset(ctx: EpisodeContext) -> None

default_execution_steps 

default_execution_steps() -> int

sample 

sample(observation: Observation, seeds: list[int] | None, noise_scale: float = 1.0) -> np.ndarray

hylo_examples.stats

Example gate-test plugin: statistical and practical significance.

McNemar alone can promote a candidate whose advantage is real but tiny (many pairs, a few more wins). This test also requires the net win rate (wins - losses) / pairs to reach min_effect; below it the p-value is reported as 1, so the gate does not promote.

protocol: {gate_test: {type: examples.min_effect, params: {min_effect: 0.1}}}

MinEffectMcNemar 

MinEffectMcNemar(min_effect: float = 0.1, metric: str = 'success')

name class-attribute instance-attribute 

name = 'min_effect'

compare 

compare(candidate, parent) -> PairedComparison