Formats and schemas¶
Repositories cooperate through versioned formats defined in hylo-core, never through each other's code. Each format carries its schema version; the JSON Schemas below are what hylo schema NAME prints.
| Format | Version | Defined in | Used for |
|---|---|---|---|
| Experiment config | hylo.experiment/v0.1 |
hylo.core.config |
what is measured: benchmark, env, agent, timing |
| Execution profile | hylo.profile/v0.1 |
hylo.core.profile |
where runtimes and the store are on one machine |
| Trace events | core.events.TRACE_SCHEMA |
hylo.core.events, core.trace |
every episode, step by step |
| Artifact manifest | hylo.artifact/v0.1 |
hylo.core.artifact |
a sealed, digest-pinned learned thing |
| Store index | hylo.store/v0.1 |
hylo.core.store |
run and artifact ids, references, tombstones |
| Scorecard | hylo.scorecard/v0.1 |
hylo.core.scorecard |
a protocol's result for one policy |
| Active version | hylo.active/v0.1 |
hylo.core.deployment |
what a policy server deploys |
| Workcell API | hylo.workcell/v0.1 |
hylo.core.remote.workcell |
control plane <-> workcell |
| Plugin contracts | hylo.<group>/v0.1 |
hylo.core.plugins |
what a plugin implements |
| Wire codec | msgpack-numpy |
hylo.core.remote.wire |
remote environments and agents |
agent-spec¶
hylo.core.agent.AgentSpec (hylo schema agent-spec)
JSON Schema
{
"$defs": {
"ActionSemantics": {
"additionalProperties": false,
"properties": {
"control_mode": {
"enum": [
"joint_pos",
"joint_delta",
"joint_vel",
"eef_delta_pos",
"eef_delta_pose",
"eef_abs_pose",
"planar_vel"
],
"title": "Control Mode",
"type": "string"
},
"frame": {
"default": "base",
"title": "Frame",
"type": "string"
},
"rotation_repr": {
"anyOf": [
{
"enum": [
"axis_angle",
"quat_xyzw",
"rot6d"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Rotation Repr"
},
"gripper": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Gripper"
},
"dim_labels": {
"default": [],
"items": {
"type": "string"
},
"title": "Dim Labels",
"type": "array"
},
"max_step": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Step"
}
},
"required": [
"control_mode"
],
"title": "ActionSemantics",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"required_state": {
"default": [],
"items": {
"type": "string"
},
"title": "Required State",
"type": "array"
},
"required_cameras": {
"default": [],
"items": {
"type": "string"
},
"title": "Required Cameras",
"type": "array"
},
"action_semantics": {
"anyOf": [
{
"$ref": "#/$defs/ActionSemantics"
},
{
"type": "null"
}
],
"default": null
},
"action_dim": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Action Dim"
},
"components": {
"additionalProperties": {
"type": "string"
},
"title": "Components",
"type": "object"
},
"weights_license": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Weights License"
}
},
"required": [
"name",
"version"
],
"title": "AgentSpec",
"type": "object"
}
benchmark¶
hylo.eval.benchmark.Benchmark (hylo schema benchmark)
JSON Schema
{
"$defs": {
"InitStateRef": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "state_ref",
"default": "state_ref",
"title": "Kind",
"type": "string"
},
"uri": {
"title": "Uri",
"type": "string"
},
"count": {
"minimum": 1,
"title": "Count",
"type": "integer"
}
},
"required": [
"uri",
"count"
],
"title": "InitStateRef",
"type": "object"
},
"Predicate": {
"additionalProperties": false,
"description": "Success predicate: builtin name, declarative `expr` (e.g. BDDL goal) or callable `ref`.",
"properties": {
"kind": {
"enum": [
"builtin",
"expr",
"callable"
],
"title": "Kind",
"type": "string"
},
"name": {
"default": "",
"title": "Name",
"type": "string"
},
"expr": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Expr"
},
"ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Ref"
}
},
"required": [
"kind"
],
"title": "Predicate",
"type": "object"
},
"SeedInit": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "seed",
"default": "seed",
"title": "Kind",
"type": "string"
}
},
"title": "SeedInit",
"type": "object"
},
"SnapshotInit": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "snapshot",
"default": "snapshot",
"title": "Kind",
"type": "string"
},
"uri": {
"title": "Uri",
"type": "string"
}
},
"required": [
"uri"
],
"title": "SnapshotInit",
"type": "object"
},
"TaskSpec": {
"additionalProperties": false,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"instruction": {
"title": "Instruction",
"type": "string"
},
"init": {
"discriminator": {
"mapping": {
"seed": "#/$defs/SeedInit",
"snapshot": "#/$defs/SnapshotInit",
"state_ref": "#/$defs/InitStateRef"
},
"propertyName": "kind"
},
"oneOf": [
{
"$ref": "#/$defs/SeedInit"
},
{
"$ref": "#/$defs/InitStateRef"
},
{
"$ref": "#/$defs/SnapshotInit"
}
],
"title": "Init"
},
"success": {
"$ref": "#/$defs/Predicate"
},
"max_steps": {
"default": 200,
"minimum": 1,
"title": "Max Steps",
"type": "integer"
},
"params": {
"additionalProperties": true,
"title": "Params",
"type": "object"
},
"tags": {
"default": [],
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
}
},
"required": [
"id",
"version",
"instruction"
],
"title": "TaskSpec",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"tasks": {
"items": {
"$ref": "#/$defs/TaskSpec"
},
"title": "Tasks",
"type": "array"
},
"splits": {
"additionalProperties": {
"items": {
"type": "integer"
},
"type": "array"
},
"title": "Splits",
"type": "object"
},
"requires_privileged": {
"default": false,
"title": "Requires Privileged",
"type": "boolean"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"title": "Metadata",
"type": "object"
}
},
"required": [
"id",
"version",
"tasks",
"splits"
],
"title": "Benchmark",
"type": "object"
}
candidate¶
hylo.evolve.candidate.Candidate (hylo schema candidate)
JSON Schema
{
"additionalProperties": false,
"properties": {
"patch": {
"additionalProperties": true,
"title": "Patch",
"type": "object"
},
"rationale": {
"title": "Rationale",
"type": "string"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Id"
},
"generator": {
"title": "Generator",
"type": "string"
},
"kind": {
"default": "config_patch",
"enum": [
"config_patch",
"critic_rule",
"recovery_rule",
"prompt",
"skill",
"policy_ref",
"code"
],
"title": "Kind",
"type": "string"
},
"evidence": {
"additionalProperties": true,
"title": "Evidence",
"type": "object"
},
"id": {
"title": "Id",
"type": "string"
}
},
"required": [
"patch",
"rationale",
"parent_id",
"generator"
],
"title": "Candidate",
"type": "object"
}
env-spec¶
hylo.core.types.EnvSpec (hylo schema env-spec)
JSON Schema
{
"$defs": {
"ActionSemantics": {
"additionalProperties": false,
"properties": {
"control_mode": {
"enum": [
"joint_pos",
"joint_delta",
"joint_vel",
"eef_delta_pos",
"eef_delta_pose",
"eef_abs_pose",
"planar_vel"
],
"title": "Control Mode",
"type": "string"
},
"frame": {
"default": "base",
"title": "Frame",
"type": "string"
},
"rotation_repr": {
"anyOf": [
{
"enum": [
"axis_angle",
"quat_xyzw",
"rot6d"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Rotation Repr"
},
"gripper": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Gripper"
},
"dim_labels": {
"default": [],
"items": {
"type": "string"
},
"title": "Dim Labels",
"type": "array"
},
"max_step": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Step"
}
},
"required": [
"control_mode"
],
"title": "ActionSemantics",
"type": "object"
},
"BoxSpace": {
"additionalProperties": false,
"properties": {
"shape": {
"items": {
"type": "integer"
},
"title": "Shape",
"type": "array"
},
"low": {
"items": {
"type": "number"
},
"title": "Low",
"type": "array"
},
"high": {
"items": {
"type": "number"
},
"title": "High",
"type": "array"
},
"semantics": {
"anyOf": [
{
"$ref": "#/$defs/ActionSemantics"
},
{
"type": "null"
}
],
"default": null
},
"dtype": {
"default": "float64",
"enum": [
"float32",
"float64"
],
"title": "Dtype",
"type": "string"
}
},
"required": [
"shape",
"low",
"high"
],
"title": "BoxSpace",
"type": "object"
},
"EnvCapabilities": {
"additionalProperties": false,
"properties": {
"seedable": {
"default": true,
"title": "Seedable",
"type": "boolean"
},
"snapshot": {
"default": false,
"title": "Snapshot",
"type": "boolean"
},
"render": {
"default": false,
"title": "Render",
"type": "boolean"
},
"privileged_state": {
"default": false,
"title": "Privileged State",
"type": "boolean"
},
"batch_size": {
"default": 1,
"minimum": 1,
"title": "Batch Size",
"type": "integer"
},
"self_paced": {
"default": false,
"title": "Self Paced",
"type": "boolean"
},
"real_robot": {
"default": false,
"title": "Real Robot",
"type": "boolean"
}
},
"title": "EnvCapabilities",
"type": "object"
},
"ObservationSpec": {
"additionalProperties": false,
"properties": {
"state": {
"additionalProperties": {
"items": {
"type": "integer"
},
"type": "array"
},
"title": "State",
"type": "object"
},
"cameras": {
"additionalProperties": {
"maxItems": 3,
"minItems": 3,
"prefixItems": [
{
"type": "integer"
},
{
"type": "integer"
},
{
"type": "integer"
}
],
"type": "array"
},
"title": "Cameras",
"type": "object"
},
"units": {
"additionalProperties": {
"type": "string"
},
"title": "Units",
"type": "object"
},
"has_instruction": {
"default": true,
"title": "Has Instruction",
"type": "boolean"
}
},
"required": [
"state"
],
"title": "ObservationSpec",
"type": "object"
},
"WorkspaceLimit": {
"additionalProperties": false,
"description": "Box the controlled point must stay in. `action_dims[i]` is the action dimension that moves along axis i\nof `state_key` (delta-position control); a move that pushes further outside the box is zeroed.",
"properties": {
"state_key": {
"title": "State Key",
"type": "string"
},
"low": {
"items": {
"type": "number"
},
"title": "Low",
"type": "array"
},
"high": {
"items": {
"type": "number"
},
"title": "High",
"type": "array"
},
"action_dims": {
"items": {
"type": "integer"
},
"title": "Action Dims",
"type": "array"
}
},
"required": [
"state_key",
"low",
"high",
"action_dims"
],
"title": "WorkspaceLimit",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"observation": {
"$ref": "#/$defs/ObservationSpec"
},
"action": {
"$ref": "#/$defs/BoxSpace"
},
"control_hz": {
"exclusiveMinimum": 0,
"title": "Control Hz",
"type": "number"
},
"capabilities": {
"$ref": "#/$defs/EnvCapabilities"
},
"workspace": {
"anyOf": [
{
"$ref": "#/$defs/WorkspaceLimit"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"name",
"version",
"observation",
"action",
"control_hz"
],
"title": "EnvSpec",
"type": "object"
}
experiment¶
hylo.core.config.ExperimentConfig (hylo schema experiment)
JSON Schema
{
"$defs": {
"BenchmarkRef": {
"additionalProperties": false,
"properties": {
"type": {
"title": "Type",
"type": "string"
},
"params": {
"additionalProperties": true,
"title": "Params",
"type": "object"
},
"split": {
"default": "validation",
"title": "Split",
"type": "string"
}
},
"required": [
"type"
],
"title": "BenchmarkRef",
"type": "object"
},
"ComponentRef": {
"additionalProperties": false,
"properties": {
"type": {
"title": "Type",
"type": "string"
},
"params": {
"additionalProperties": true,
"title": "Params",
"type": "object"
}
},
"required": [
"type"
],
"title": "ComponentRef",
"type": "object"
},
"EnvRef": {
"additionalProperties": false,
"properties": {
"type": {
"title": "Type",
"type": "string"
},
"params": {
"additionalProperties": true,
"title": "Params",
"type": "object"
},
"remote": {
"anyOf": [
{
"$ref": "#/$defs/RemoteSpec"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"type"
],
"title": "EnvRef",
"type": "object"
},
"RemoteSpec": {
"additionalProperties": false,
"description": "Where a component runs: never part of what is measured. `runtime` names a venv in this machine's profile\n(core.profile); `python` / `env` set or override it directly.",
"properties": {
"runtime": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Runtime"
},
"python": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Python"
},
"env": {
"additionalProperties": {
"type": "string"
},
"title": "Env",
"type": "object"
}
},
"title": "RemoteSpec",
"type": "object"
},
"Timing": {
"additionalProperties": false,
"description": "How policy time relates to robot time. Part of what an experiment measures.",
"properties": {
"mode": {
"default": "sync",
"enum": [
"sync",
"realtime"
],
"title": "Mode",
"type": "string"
},
"clock": {
"default": "virtual",
"enum": [
"virtual",
"wall"
],
"title": "Clock",
"type": "string"
},
"control_hz": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Control Hz"
},
"refill_steps": {
"default": 2,
"minimum": 0,
"title": "Refill Steps",
"type": "integer"
},
"adaptive_refill": {
"default": true,
"title": "Adaptive Refill",
"type": "boolean"
},
"latency_s": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Latency S"
},
"max_hold_steps": {
"default": 100,
"minimum": 1,
"title": "Max Hold Steps",
"type": "integer"
},
"require_reset_confirm": {
"default": false,
"title": "Require Reset Confirm",
"type": "boolean"
},
"verdict_timeout_s": {
"default": 0.0,
"title": "Verdict Timeout S",
"type": "number"
}
},
"title": "Timing",
"type": "object"
},
"TraceOptions": {
"additionalProperties": false,
"properties": {
"record_privileged": {
"default": true,
"title": "Record Privileged",
"type": "boolean"
},
"image_every": {
"default": 1,
"minimum": 0,
"title": "Image Every",
"type": "integer"
}
},
"title": "TraceOptions",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"schema_version": {
"const": "hylo.experiment/v0.1",
"default": "hylo.experiment/v0.1",
"title": "Schema Version",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"benchmark": {
"$ref": "#/$defs/BenchmarkRef"
},
"env": {
"$ref": "#/$defs/EnvRef"
},
"agent": {
"$ref": "#/$defs/ComponentRef"
},
"seed": {
"default": 0,
"title": "Seed",
"type": "integer"
},
"safety": {
"additionalProperties": true,
"title": "Safety",
"type": "object"
},
"trace": {
"$ref": "#/$defs/TraceOptions"
},
"timing": {
"$ref": "#/$defs/Timing"
},
"output_dir": {
"default": "runs",
"title": "Output Dir",
"type": "string"
},
"workers": {
"default": 1,
"minimum": 1,
"title": "Workers",
"type": "integer"
},
"tags": {
"default": [],
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
}
},
"required": [
"name",
"benchmark",
"env",
"agent"
],
"title": "ExperimentConfig",
"type": "object"
}
memory-item¶
hylo.core.memory.MemoryItem (hylo schema memory-item)
JSON Schema
{
"$defs": {
"MemoryKind": {
"enum": [
"working",
"episodic",
"semantic",
"spatial",
"skill"
],
"title": "MemoryKind",
"type": "string"
},
"Pose": {
"additionalProperties": false,
"properties": {
"frame_id": {
"title": "Frame Id",
"type": "string"
},
"position": {
"maxItems": 3,
"minItems": 3,
"prefixItems": [
{
"type": "number"
},
{
"type": "number"
},
{
"type": "number"
}
],
"title": "Position",
"type": "array"
},
"orientation": {
"anyOf": [
{
"maxItems": 4,
"minItems": 4,
"prefixItems": [
{
"type": "number"
},
{
"type": "number"
},
{
"type": "number"
},
{
"type": "number"
}
],
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Orientation"
}
},
"required": [
"frame_id",
"position"
],
"title": "Pose",
"type": "object"
},
"TimeSpan": {
"additionalProperties": false,
"properties": {
"start": {
"title": "Start",
"type": "number"
},
"end": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "End"
},
"clock": {
"default": "sim",
"enum": [
"sim",
"wall"
],
"title": "Clock",
"type": "string"
}
},
"required": [
"start"
],
"title": "TimeSpan",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"kind": {
"$ref": "#/$defs/MemoryKind"
},
"content": {
"title": "Content",
"type": "string"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Key"
},
"payload": {
"additionalProperties": true,
"title": "Payload",
"type": "object"
},
"entities": {
"default": [],
"items": {
"type": "string"
},
"title": "Entities",
"type": "array"
},
"scope": {
"additionalProperties": {
"type": "string"
},
"title": "Scope",
"type": "object"
},
"pose": {
"anyOf": [
{
"$ref": "#/$defs/Pose"
},
{
"type": "null"
}
],
"default": null
},
"event_time": {
"anyOf": [
{
"$ref": "#/$defs/TimeSpan"
},
{
"type": "null"
}
],
"default": null
},
"valid_from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Valid From"
},
"confidence": {
"default": 1.0,
"maximum": 1.0,
"minimum": 0.0,
"title": "Confidence",
"type": "number"
},
"source": {
"default": "",
"title": "Source",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
}
},
"required": [
"kind",
"content"
],
"title": "MemoryItem",
"type": "object"
}
task¶
hylo.core.task.TaskSpec (hylo schema task)
JSON Schema
{
"$defs": {
"InitStateRef": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "state_ref",
"default": "state_ref",
"title": "Kind",
"type": "string"
},
"uri": {
"title": "Uri",
"type": "string"
},
"count": {
"minimum": 1,
"title": "Count",
"type": "integer"
}
},
"required": [
"uri",
"count"
],
"title": "InitStateRef",
"type": "object"
},
"Predicate": {
"additionalProperties": false,
"description": "Success predicate: builtin name, declarative `expr` (e.g. BDDL goal) or callable `ref`.",
"properties": {
"kind": {
"enum": [
"builtin",
"expr",
"callable"
],
"title": "Kind",
"type": "string"
},
"name": {
"default": "",
"title": "Name",
"type": "string"
},
"expr": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Expr"
},
"ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Ref"
}
},
"required": [
"kind"
],
"title": "Predicate",
"type": "object"
},
"SeedInit": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "seed",
"default": "seed",
"title": "Kind",
"type": "string"
}
},
"title": "SeedInit",
"type": "object"
},
"SnapshotInit": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "snapshot",
"default": "snapshot",
"title": "Kind",
"type": "string"
},
"uri": {
"title": "Uri",
"type": "string"
}
},
"required": [
"uri"
],
"title": "SnapshotInit",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"instruction": {
"title": "Instruction",
"type": "string"
},
"init": {
"discriminator": {
"mapping": {
"seed": "#/$defs/SeedInit",
"snapshot": "#/$defs/SnapshotInit",
"state_ref": "#/$defs/InitStateRef"
},
"propertyName": "kind"
},
"oneOf": [
{
"$ref": "#/$defs/SeedInit"
},
{
"$ref": "#/$defs/InitStateRef"
},
{
"$ref": "#/$defs/SnapshotInit"
}
],
"title": "Init"
},
"success": {
"$ref": "#/$defs/Predicate"
},
"max_steps": {
"default": 200,
"minimum": 1,
"title": "Max Steps",
"type": "integer"
},
"params": {
"additionalProperties": true,
"title": "Params",
"type": "object"
},
"tags": {
"default": [],
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
}
},
"required": [
"id",
"version",
"instruction"
],
"title": "TaskSpec",
"type": "object"
}