release: SkillFactory v0.0.2

This commit is contained in:
2026-10-10 16:34:40 +08:00
parent 7f39abb613
commit 8019d6f8d6
22 changed files with 4974 additions and 6 deletions
@@ -0,0 +1,311 @@
#!/usr/bin/env python3
"""Generate explicitly synthetic multi-part design examples, not manufacturer assets or runnable policies."""
from __future__ import annotations
import argparse
import copy
import json
from pathlib import Path
def joint(name, parent, child, joint_type="revolute", coupling=None):
linear = joint_type == "prismatic"
return {
"id": name,
"source_name": name,
"type": joint_type,
"parent": parent,
"child": child,
"origin": {"xyz": [0, 0, 0.1], "quat_xyzw": [0, 0, 0, 1]},
"actuation": "coupled" if coupling else "active",
"position_unit": "m" if linear else "rad",
"axis": [1, 0, 0] if linear else [0, 1, 0],
"limits_origin": "declared",
"limits": {
"position": None if joint_type == "continuous" else ([0, 0.04] if linear else [-1.5, 1.5]),
"velocity": 1 if linear else 10,
"effort": 10,
},
"coupling": coupling,
}
def part(part_type, count, mode="position_pd", joint_type="revolute"):
part_id = f"example_{part_type}"
joints = [joint(f"joint_{i}", "base" if i == 0 else f"link_{i - 1}", f"link_{i}", joint_type) for i in range(count)]
actuators = []
for item in joints:
linear = joint_type == "prismatic"
neutral = 0.02 if linear else 0.0
unit = ("m" if linear else "rad") if mode == "position_pd" else "rad/s"
actuators.append(
{
"id": "drive_" + item["id"],
"joint_id": item["id"],
"neutral_position": neutral,
"commands": {
mode: {
"unit": unit,
"scale": 0.01 if linear else 0.25,
"offset": neutral if mode == "position_pd" else 0,
"gains": {"kp": 25, "kd": 0.5} if mode == "position_pd" else None,
}
},
}
)
root = {"id": "root", "body": "base", "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]}
sensors = []
if joints:
sensors.append(
{
"id": "joint_state",
"kind": "joint_state",
"outputs": ["joint.position", "joint.velocity"],
"frame_id": "root",
"target": {"entity": "joint", "ids": [item["id"] for item in joints]},
"update_period_s": 0.002,
}
)
return {
"schema_version": 2,
"kind": "robot_part",
"part_id": part_id,
"part_type": part_type,
"description_role": "design_template",
"source": {
"format": "design",
"root": None,
"path": None,
"package_name": None,
"license_file": None,
"license_id": "LicenseRef-Design-Template",
"revision": None,
"sha256": None,
},
"topology": {
"structure": "tree",
"root_body": "base",
"bodies": ["base", *[item["child"] for item in joints]],
"joints": joints,
"constraints": [],
},
"frames": [root],
"root_frame": "root",
"attachment": {"mode": "fixed", "frame_id": "root", "source_mount_joint": None, "auxiliary_root_joints": []},
"actuators": actuators,
"end_effectors": [],
"sensors": sensors,
"timing": {"physics_dt_s": 0.002, "control_dt_s": 0.01},
"safety": {
"soft_limit_factor": 0.9,
"on_invalid_command": "reject",
"on_timeout": "disable",
"command_timeout_s": 0.05,
},
"scales": {"length_m": None, "known_mass_kg": None},
"extensions": {"skillfactory.example": {"synthetic": True, "not_manufacturer_data": True}},
}
def effector(data, name, body, role):
data["frames"].append({"id": name + "_frame", "body": body, "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]})
data["end_effectors"].append({"id": name, "role": role, "frame_id": name + "_frame", "contact": None})
def sensor(data, name, kind, outputs):
data["sensors"].append(
{
"id": name,
"kind": kind,
"outputs": outputs,
"frame_id": "root",
"target": {"entity": "part", "ids": [data["part_id"]]},
"update_period_s": 0.02,
}
)
def feature(name, quantity, unit="1", normalization="identity"):
return {"name": name, "quantity": quantity, "unit": unit, "normalization": normalization}
def port(name, entity, kind, shape, features=(), selector=None, required=True, mask=None, command=None):
return {
"name": name,
"direction": "output" if kind == "command" else "input",
"kind": kind,
"entity": entity,
"selector": selector or {"type": "all", "values": []},
"required": required,
"dtype": "bool" if kind == "mask" else ("uint8" if kind == "image" else "float32"),
"shape": shape,
"frame": "part_root" if kind == "goal" else "none",
"representation": "features" if features else "tensor",
"features": list(features),
"mask": mask,
"command": command,
}
def software(name, bindings, part_types, joint_types, mode=None):
return {
"schema_version": 2,
"kind": "part_software",
"software_id": name,
"software_version": "0.0.2",
"status": "design",
"binding_mode": "alternatives",
"hardware_bindings": [{"part_id": item, "spec_path": f"configs/parts/{item}.json"} for item in bindings],
"requirements": {
"part_types": part_types,
"joint_types": joint_types,
"topologies": ["tree"],
"attachment_modes": ["fixed", "external", "floating"],
"supports_coupling": True,
"required_control_modes": [mode] if mode else [],
"required_sensor_kinds": ["joint_state"] if mode else ["camera"],
"required_sensor_outputs": ["joint.position", "joint.velocity"] if mode else ["image.rgb8"],
"required_effector_roles": [],
"capacities": {"Jmax": 32, "Amax": 32, "Emax": 8, "Smax": 8},
},
"interface": {
"contract_id": name,
"contract_version": 1,
"quaternion_order": "xyzw",
"ports": [],
"reset": "indexed_isolated" if mode else "not_applicable",
"action_history": "last_applied" if mode else "none",
},
"runtime": {
"adapter_id": None,
"implementation": "unimplemented",
"dependencies": {},
"devices": ["cpu", "cuda"],
"timing": {"policy": "per_part", "control_dt_s": None},
},
"artifact": {"format": "none", "checkpoint": None, "trained_skill": False, "frozen": False},
}
def control_ports(mode, include_goal=False):
ports = [
port("joint_mask", "joint", "mask", ["B", "Jmax"]),
port(
"joint_state",
"joint",
"state",
["B", "Jmax", 2],
[
feature("position", "joint.position", "joint_position"),
feature("velocity", "joint.velocity", "joint_velocity"),
],
mask="joint_mask",
),
port("actuator_mask", "actuator", "mask", ["B", "Amax"]),
port(
"command",
"actuator",
"command",
["B", "Amax", 1],
[feature("command", "actuator.command", normalization="command_scale_offset")],
mask="actuator_mask",
command={"mode": mode, "encoding": "normalized", "clip": [-1, 1]},
),
]
if include_goal:
ports.extend(
[
port("effector_mask", "end_effector", "mask", ["B", "Emax"], required=False),
port(
"target_position",
"end_effector",
"goal",
["B", "Emax", 3],
[feature(axis, "goal.position." + axis, "m") for axis in ("x", "y", "z")],
required=False,
mask="effector_mask",
),
]
)
return ports
def build_examples():
arm, torso, head = part("arm", 6), part("torso", 2), part("head", 2)
effector(arm, "tool", "link_5", "tool")
effector(head, "gaze", "link_1", "gaze")
sensor(head, "camera", "camera", ["image.rgb8"])
sensor(head, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
hand = part("hand", 4)
# Two independent fingers, each with a coupled distal joint: J=4, A=2, E=2.
hand["topology"]["joints"][2]["parent"] = "base"
for distal, driver in ((1, 0), (3, 2)):
item = hand["topology"]["joints"][distal]
item["actuation"] = "coupled"
item["coupling"] = {"joint_id": f"joint_{driver}", "multiplier": 0.5, "offset": 0}
hand["actuators"] = [item for item in hand["actuators"] if item["joint_id"] in ("joint_0", "joint_2")]
effector(hand, "finger_a", "link_1", "fingertip")
effector(hand, "finger_b", "link_3", "fingertip")
gripper = part("gripper", 2, joint_type="prismatic")
gripper["topology"]["joints"][1].update(
parent="base", actuation="coupled", coupling={"joint_id": "joint_0", "multiplier": -1, "offset": 0.04}
)
gripper["actuators"] = gripper["actuators"][:1]
effector(gripper, "jaw_a", "link_0", "grasp")
effector(gripper, "jaw_b", "link_1", "grasp")
base = part("mobile_base", 4, mode="velocity", joint_type="continuous")
base["attachment"]["mode"] = "floating"
for item in base["topology"]["joints"]:
item["parent"] = "base"
sensor(base, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
pod = part("sensor", 0)
pod["attachment"]["mode"] = "external"
sensor(pod, "camera", "camera", ["image.rgb8"])
sensor(pod, "imu", "imu", ["imu.acceleration", "imu.angular_velocity"])
parts = [arm, hand, gripper, torso, head, base, pod]
outputs = {f"configs/parts/{data['part_id']}.json": data for data in parts}
pd = software(
"part_position_control",
["go2_fl", *[data["part_id"] for data in parts[:5]]],
["leg", "arm", "hand", "gripper", "torso", "head"],
["revolute", "prismatic"],
"position_pd",
)
pd["interface"]["ports"] = control_ports("position_pd", include_goal=True)
velocity = software("wheel_velocity_control", ["example_mobile_base"], ["mobile_base"], ["continuous"], "velocity")
velocity["interface"]["ports"] = control_ports("velocity")
vision = software("part_rgb_perception", ["example_head", "example_sensor"], ["head", "sensor"], ["revolute"])
# Capacities cover hardware, even when this profile doesn't command head motors or consume gaze.
vision["requirements"]["capacities"].update(Amax=2, Emax=1)
selector = {"type": "sensor_output", "values": ["image.rgb8"]}
vision["interface"]["ports"] = [
port("camera_mask", "sensor", "mask", ["B", "Smax"], selector=copy.deepcopy(selector)),
port("rgb_image", "sensor", "image", ["B", "Smax", 480, 640, 3], selector=selector, mask="camera_mask"),
]
for data in (pd, velocity, vision):
outputs[f"configs/software/{data['software_id']}.json"] = data
return outputs
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--output-root",
type=Path,
required=True,
help="Repository-shaped destination; existing files are never overwritten",
)
args = parser.parse_args()
outputs = build_examples()
paths = [(args.output_root / name, data) for name, data in outputs.items()]
if any(path.exists() for path, _ in paths):
parser.error("Refusing to overwrite existing descriptions")
for path, data in paths:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(data, indent=2, allow_nan=False) + "\n", encoding="utf-8")
print(f"Generated {len(paths)} synthetic design/profile examples; none provides a runtime adapter")
if __name__ == "__main__":
main()
+186
View File
@@ -0,0 +1,186 @@
#!/usr/bin/env python3
"""Export a validated legacy leg bundle as PartSpec v2; this does not create a new runtime adapter."""
from __future__ import annotations
import argparse
import json
import math
from pathlib import Path
def _quaternion(rpy):
r, p, y = (angle / 2 for angle in rpy)
cr, sr, cp, sp, cy, sy = math.cos(r), math.sin(r), math.cos(p), math.sin(p), math.cos(y), math.sin(y)
return [
sr * cp * cy - cr * sp * sy,
cr * sp * cy + sr * cp * sy,
cr * cp * sy - sr * sp * cy,
cr * cp * cy + sr * sp * sy,
]
def part_from_leg_bundle(bundle):
"""Keep all bodies/fixed branches and the independent actuator declaration order."""
if bundle.get("schema_version") != 2 or bundle.get("kind") != "single_leg":
raise ValueError("Expected legacy single_leg asset manifest v2")
spec = bundle["spec"]
records = {joint["name"]: joint for joint in bundle["joints"]}
controls = {joint["name"]: joint for joint in spec["joints"]}
if bundle["joint_order"] != list(controls) or set(records) != set(controls):
raise ValueError("Legacy controlled-joint order mismatch")
joints = []
for node in bundle["tree"]:
fixed = node["type"] == "fixed"
limits = records[node["name"]]["limits"] if not fixed else None
joints.append(
{
"id": node["name"],
"source_name": node["name"],
"type": node["type"],
"parent": node["parent"],
"child": node["child"],
"origin": {"xyz": node["xyz"], "quat_xyzw": _quaternion(node["rpy"])},
"actuation": "fixed" if fixed else "active",
"position_unit": None if fixed else "rad",
"axis": None if fixed else node["axis"],
"limits_origin": "source",
"limits": None
if fixed
else {
"position": [limits["lower"], limits["upper"]],
"velocity": limits["velocity"],
"effort": limits["effort"],
},
"coupling": None,
}
)
dt = spec["physics_dt"] * spec["decimation"]
part = {
"schema_version": 2,
"kind": "robot_part",
"part_id": spec["part_id"],
"part_type": "leg",
"description_role": "asset_reference",
"source": {
"format": "urdf",
"root": spec["source_root"],
"path": spec["urdf"],
"package_name": spec["package_name"],
"license_file": spec["license_file"],
"license_id": spec["license_id"],
"revision": bundle["source"]["commit"],
"sha256": bundle["source"]["sha256"],
},
"topology": {
"structure": "tree",
"root_body": bundle["anchor_body"],
"bodies": [bundle["anchor_body"], *bundle["links"]],
"joints": joints,
"constraints": [],
},
"frames": [
{"id": "root", "body": bundle["anchor_body"], "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]},
{"id": "foot_link", "body": bundle["foot"]["body"], "xyz": [0, 0, 0], "quat_xyzw": [0, 0, 0, 1]},
],
"root_frame": "root",
"attachment": {
"mode": "fixed",
"frame_id": "root",
"source_mount_joint": spec["mount_joint"],
"auxiliary_root_joints": spec["auxiliary_root_joints"],
"source_parent_transform": {
"body": bundle["mount"]["source_parent"],
"xyz": bundle["mount"]["source_parent_T_anchor"]["xyz"],
"quat_xyzw": _quaternion(bundle["mount"]["source_parent_T_anchor"]["rpy"]),
},
},
"actuators": [
{
"id": "drive_" + control["name"],
"joint_id": control["name"],
"neutral_position": control["q_default"],
"commands": {
"position_pd": {
"unit": "rad",
"scale": control["action_scale"],
"offset": control["q_default"],
"gains": {"kp": control["kp"], "kd": control["kd"]},
}
},
}
for control in spec["joints"]
],
"end_effectors": [
{
"id": "foot",
"role": "support",
"frame_id": "foot_link",
"contact": {
"source_collision_index": spec["foot_collision_index"],
"gap_method": bundle["foot"]["type"],
},
}
],
"sensors": [
{
"id": "joint_state",
"kind": "joint_state",
"outputs": ["joint.position", "joint.velocity"],
"frame_id": "root",
"target": {"entity": "joint", "ids": bundle["joint_order"]},
"update_period_s": spec["physics_dt"],
},
{
"id": "foot_contact",
"kind": "contact_normal",
"outputs": ["contact.normal_force"],
"frame_id": "foot_link",
"target": {"entity": "end_effector", "ids": ["foot"]},
"update_period_s": spec["physics_dt"],
},
],
"timing": {"physics_dt_s": spec["physics_dt"], "control_dt_s": dt},
"safety": {
"soft_limit_factor": spec["soft_limit_factor"],
"on_invalid_command": "reject",
"on_timeout": "hold",
"command_timeout_s": 5 * dt,
},
"scales": {"length_m": bundle["length_scale_m"], "known_mass_kg": bundle["known_mass_scale_kg"]},
"extensions": {
"skillfactory.legacy": {
"profile": "single_leg_v1",
"derived_urdf_sha256": bundle["derived_urdf_sha256"],
"watchdog_policy": "v2 requirement only; not implemented by the legacy runtime",
}
},
}
return part
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--bundle", type=Path, required=True)
parser.add_argument("--output", type=Path, required=True)
args = parser.parse_args()
from SkillFactory.legs.spec import load_bundle
from validate_descriptions import validate_hardware
output = args.output.resolve()
if output.exists() or output.is_relative_to(args.bundle.resolve()):
parser.error("Output must be a new file outside the legacy bundle")
part = part_from_leg_bundle(load_bundle(args.bundle))
output.parent.mkdir(parents=True, exist_ok=True)
temporary = output.with_suffix(output.suffix + ".tmp")
try:
temporary.write_text(json.dumps(part, indent=2, allow_nan=False) + "\n", encoding="utf-8")
validate_hardware(temporary)
temporary.replace(output)
finally:
temporary.unlink(missing_ok=True)
print(f"PartSpec v2 exported: {output}; legacy simulation/training remains unchanged")
if __name__ == "__main__":
main()
+531
View File
@@ -0,0 +1,531 @@
#!/usr/bin/env python3
"""Validate the current PartSpec/SoftwareSpec v2 contracts; never launch Kit or load weights."""
from __future__ import annotations
import argparse
import hashlib
import json
import math
from pathlib import Path
from jsonschema import Draft202012Validator
ROOT = Path(__file__).resolve().parents[1]
SCHEMAS = ROOT / "docs/schemas"
ENTITY_AXES = {"joint": "Jmax", "actuator": "Amax", "end_effector": "Emax", "sensor": "Smax"}
PART_TYPES = {"leg", "arm", "hand", "gripper", "torso", "neck", "head", "mobile_base", "sensor", "other"}
SENSOR_KINDS = {"joint_state", "contact_normal", "wrench", "imu", "camera", "tactile", "lidar", "other"}
EFFECTOR_ROLES = {"support", "tool", "fingertip", "grasp", "gaze", "sensor_mount", "other"}
def _finite_float(text):
value = float(text)
if not math.isfinite(value):
raise ValueError(f"Non-finite JSON number: {text}")
return value
def _finite_int(text):
value = int(text)
try:
finite = math.isfinite(value)
except OverflowError as error:
raise ValueError("JSON integer exceeds finite physical numeric range") from error
if not finite:
raise ValueError("Non-finite JSON integer")
return value
def _reject_constant(text):
raise ValueError(f"Non-standard JSON constant: {text}")
def _unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError(f"Duplicate JSON key: {key}")
result[key] = value
return result
def read_json(path):
return json.loads(
Path(path).read_text(encoding="utf-8"),
parse_float=_finite_float,
parse_int=_finite_int,
parse_constant=_reject_constant,
object_pairs_hook=_unique_object,
)
def _structure(path, schema_name):
data = read_json(path)
schema = read_json(SCHEMAS / schema_name)
Draft202012Validator.check_schema(schema)
error = next(Draft202012Validator(schema).iter_errors(data), None)
if error is not None:
location = ".".join(str(part) for part in error.absolute_path) or "<root>"
raise ValueError(f"{path}: {location}: {error.message}")
return data
def _version(path):
data = read_json(path)
if not isinstance(data, dict) or type(data.get("schema_version")) is not int:
raise ValueError("schema_version must be a JSON integer in an object")
if data["schema_version"] != 2:
raise ValueError(
"Only schema_version=2 is supported; migrate legacy leg bundles with migrate_leg_description.py"
)
return data["schema_version"]
def _integers(data, fields):
# JSON Schema considers 1.0 an integer; the Python contracts require int.
for field in fields:
if field in data and type(data[field]) is not int:
raise ValueError(f"{field} must be a JSON integer, not a decimal/bool")
def _indexed(records, field="id"):
result = {item[field]: item for item in records}
if len(result) != len(records):
raise ValueError(f"Duplicate {field} in entity collection")
return result
def _source_path(root, relative):
root = Path(root).expanduser().resolve()
if not (root / relative).resolve().is_relative_to(root):
raise ValueError("Source asset path must remain inside source root")
def validate_hardware(path):
_version(path)
data = _structure(path, "part_spec.v2.schema.json")
_validate_part(data)
return data
def _joint_semantics(joint):
if not math.isclose(math.hypot(*joint["origin"]["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Joint origin quaternion must be normalized xyzw")
fixed = joint["type"] == "fixed"
expected_unit = None if fixed else ("m" if joint["type"] == "prismatic" else "rad")
if joint["position_unit"] != expected_unit or (joint["actuation"] == "fixed") != fixed:
raise ValueError("Joint type, actuation and position unit disagree")
if fixed:
if joint["axis"] is not None or joint["limits"] is not None:
raise ValueError("Fixed joints must not have moving axes/limits")
elif joint["axis"] is None or not math.isclose(math.hypot(*joint["axis"]), 1.0, abs_tol=1e-5):
raise ValueError("Moving joint axis must be a unit vector")
if (joint["coupling"] is not None) != (joint["actuation"] == "coupled"):
raise ValueError("Coupled joints require an explicit coupling, other joints forbid it")
limits = joint["limits"]
if not fixed and joint["limits_origin"] == "declared" and limits is None:
raise ValueError("Declared moving joint limits cannot be missing")
if limits is not None:
position = limits["position"]
if joint["type"] == "continuous":
if position is not None:
raise ValueError("Continuous joints cannot have bounded position limits")
elif position is None or not position[0] < position[1]:
raise ValueError("Bounded joint position limits require lower < upper")
def _tree_semantics(topology, joints):
bodies, root = set(topology["bodies"]), topology["root_body"]
if root not in bodies:
raise ValueError("Missing topology root body")
parents = {}
for joint in joints.values():
_joint_semantics(joint)
parent, child = joint["parent"], joint["child"]
if parent not in bodies or child not in bodies or parent == child or child == root or child in parents:
raise ValueError("Invalid body reference or multiple parents in spanning tree")
parents[child] = parent
if set(parents) != bodies - {root}:
raise ValueError("Disconnected body in spanning tree")
for body in bodies:
seen = set()
while body != root:
if body in seen:
raise ValueError("Cyclic spanning tree; use explicit loop constraints instead")
seen.add(body)
body = parents[body]
if (topology["structure"] == "closed_chain") != bool(topology["constraints"]):
raise ValueError("Closed chains require explicit loop constraints; trees forbid them")
def _coupling_semantics(joints):
for name, joint in joints.items():
coupling = joint["coupling"]
if coupling is None:
continue
target = joints.get(coupling["joint_id"])
if (
target is None
or target["type"] == "fixed"
or target["position_unit"] != joint["position_unit"]
or coupling["multiplier"] == 0
):
raise ValueError("Coupling references an incompatible joint")
seen, current = {name}, target
while current["coupling"] is not None:
if current["id"] in seen:
raise ValueError("Cyclic joint coupling")
seen.add(current["id"])
next_id = current["coupling"]["joint_id"]
if next_id not in joints:
raise ValueError("Missing coupling joint")
current = joints[next_id]
def _actuator_semantics(actuators, joints):
driven = []
for actuator in actuators.values():
joint = joints.get(actuator["joint_id"])
if joint is None or joint["actuation"] != "active":
raise ValueError("Actuator must drive one active joint, not a passive/coupled/fixed joint")
driven.append(joint["id"])
linear = joint["type"] == "prismatic"
units = {"position_pd": "m" if linear else "rad", "position": "m" if linear else "rad"}
units.update(velocity="m/s" if linear else "rad/s", effort="N" if linear else "N*m")
for mode, command in actuator["commands"].items():
if command["unit"] != units[mode]:
raise ValueError("Actuator command unit disagrees with joint type/mode")
if (command["gains"] is not None) != (mode == "position_pd"):
raise ValueError("Only position_pd requires explicit PD gains")
limits = joint["limits"]
if (
limits
and limits["position"]
and not limits["position"][0] <= actuator["neutral_position"] <= limits["position"][1]
):
raise ValueError("Actuator neutral position outside hard limits")
active = {joint["id"] for joint in joints.values() if joint["actuation"] == "active"}
if len(set(driven)) != len(driven) or set(driven) != active:
raise ValueError("Require exactly one independent actuator per active joint")
def _validate_part(data):
source = data["source"]
if data["description_role"] == "asset_reference":
_source_path(source["root"], source["path"])
topology = data["topology"]
joints = _indexed(topology["joints"])
if len({joint["source_name"] for joint in joints.values()}) != len(joints):
raise ValueError("Duplicate source joint names")
_tree_semantics(topology, joints)
_coupling_semantics(joints)
frames = _indexed(data["frames"])
if data["root_frame"] not in frames or frames[data["root_frame"]]["body"] != topology["root_body"]:
raise ValueError("Root frame must belong to root body")
if data["attachment"]["frame_id"] not in frames:
raise ValueError("Missing attachment frame")
parent_transform = data["attachment"].get("source_parent_transform")
if parent_transform is not None and not math.isclose(math.hypot(*parent_transform["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Source parent transform quaternion must be normalized xyzw")
for frame in frames.values():
if frame["body"] not in topology["bodies"]:
raise ValueError("Frame references missing body")
if not math.isclose(math.hypot(*frame["quat_xyzw"]), 1.0, abs_tol=1e-5):
raise ValueError("Frame quaternion must be normalized xyzw")
for constraint in _indexed(topology["constraints"]).values():
if constraint["parent_frame"] not in frames or constraint["child_frame"] not in frames:
raise ValueError("Loop constraint references missing frame")
if frames[constraint["parent_frame"]]["body"] == frames[constraint["child_frame"]]["body"]:
raise ValueError("Loop constraint must connect different bodies")
_actuator_semantics(_indexed(data["actuators"]), joints)
effectors = _indexed(data["end_effectors"])
for effector in effectors.values():
if effector["frame_id"] not in frames:
raise ValueError("End effector references missing frame")
if effector["contact"] is not None:
_integers(effector["contact"], ("source_collision_index",))
targets = {"part": {data["part_id"]}, "joint": set(joints), "end_effector": set(effectors)}
for sensor in _indexed(data["sensors"]).values():
if sensor["frame_id"] not in frames or not set(sensor["target"]["ids"]) <= targets[sensor["target"]["entity"]]:
raise ValueError("Sensor references missing frame/target")
if sensor["kind"] == "joint_state" and sensor["target"]["entity"] != "joint":
raise ValueError("Joint-state sensor must explicitly target joints")
if sensor["kind"] == "contact_normal" and set(sensor["outputs"]) != {"contact.normal_force"}:
raise ValueError("Normal-contact sensors cannot advertise a full wrench or friction output")
prefixes = {
"joint_state": "joint.",
"wrench": "contact.wrench",
"imu": "imu.",
"camera": "image.",
"lidar": "range.",
}
prefix = prefixes.get(sensor["kind"])
if prefix is not None and any(not signal.startswith(prefix) for signal in sensor["outputs"]):
raise ValueError("Sensor output semantics disagree with sensor kind")
timing = data["timing"]
if timing["physics_dt_s"] is not None:
ratio = timing["control_dt_s"] / timing["physics_dt_s"]
if not math.isfinite(ratio) or ratio < 1 or not math.isclose(ratio, round(ratio), abs_tol=1e-8):
raise ValueError("Control dt must be an integer multiple of physics dt")
if data["safety"]["command_timeout_s"] < timing["control_dt_s"]:
raise ValueError("Command timeout must not be shorter than one control step")
def _repo_file(root, relative):
path = (root / relative).resolve()
if not path.is_relative_to(root):
raise ValueError(f"Path escapes repository: {relative}")
if not path.is_file():
raise FileNotFoundError(path)
return path
def _artifact(data, root):
checkpoint = data["artifact"]["checkpoint"]
if checkpoint is not None:
weights = _repo_file(root, checkpoint["path"])
with weights.open("rb") as stream:
actual = hashlib.file_digest(stream, "sha256").hexdigest()
if actual != checkpoint["sha256"]:
raise ValueError("Checkpoint SHA256 mismatch")
def _bindings(data, root):
bindings = data["hardware_bindings"]
ids = [item["part_id"] for item in bindings]
if len(set(ids)) != len(ids):
raise ValueError("Duplicate hardware part_id bindings")
hardware = []
for binding in bindings:
part = validate_hardware(_repo_file(root, binding["spec_path"]))
if part["part_id"] != binding["part_id"]:
raise ValueError("Hardware binding part_id mismatch")
hardware.append(part)
return hardware
def _entities(part):
return {
"part": [{"id": part["part_id"]}],
"joint": [joint for joint in part["topology"]["joints"] if joint["type"] != "fixed"],
"actuator": part["actuators"],
"end_effector": part["end_effectors"],
"sensor": part["sensors"],
}
def _select(port, entities):
records = entities[port["entity"]]
selector, values = port["selector"]["type"], set(port["selector"]["values"])
if selector == "all":
if values:
raise ValueError("all selector must have empty values")
return records
if not values:
raise ValueError("Explicit selectors require nonempty values")
if selector == "ids":
if not values <= {record["id"] for record in records}:
raise ValueError("Port selector references missing entity ID")
return [record for record in records if record["id"] in values]
if selector == "sensor_output":
if port["entity"] != "sensor":
raise ValueError("sensor_output selector requires sensor entity")
return [record for record in records if values <= set(record["outputs"])]
field, expected = ("role", "end_effector") if selector == "role" else ("kind", "sensor")
if port["entity"] != expected:
raise ValueError("role/sensor_kind selector used on incompatible entity")
return [record for record in records if record[field] in values]
def _port_structure(port, ports, capacities):
shape, entity = port["shape"], port["entity"]
prefix = ["B"] if entity == "part" else ["B", ENTITY_AXES[entity]]
if shape[: len(prefix)] != prefix or any(type(dim) is not int or dim < 1 for dim in shape[len(prefix) :]):
raise ValueError("Port shape must use B and its entity capacity axis followed by positive integer dimensions")
if entity != "part" and capacities[ENTITY_AXES[entity]] == 0:
raise ValueError("Declared port has zero entity capacity; omit it from this profile")
if port["representation"] == "features":
if not port["features"] or len(shape) != len(prefix) + 1 or shape[-1] != len(port["features"]):
raise ValueError("Feature port dimension must exactly match ordered features")
_indexed(port["features"], "name")
elif port["features"]:
raise ValueError("Opaque tensor ports must not claim scalar feature layouts")
if port["kind"] == "mask":
if port["dtype"] != "bool" or shape != prefix or port["mask"] is not None or port["representation"] != "tensor":
raise ValueError("Entity masks require bool [B,capacity], no features or nested mask")
if port["direction"] != "input":
raise ValueError("Entity masks are adapter-provided input ports")
elif entity != "part":
mask = ports.get(port["mask"])
if mask is None or mask["kind"] != "mask" or mask["entity"] != entity or mask["selector"] != port["selector"]:
raise ValueError("Entity port requires a matching selector/entity mask")
elif port["mask"] is not None:
raise ValueError("Part-level ports must not use entity masks")
if port["kind"] == "command":
if port["direction"] != "output" or entity != "actuator" or port["command"] is None:
raise ValueError("Commands must be explicit actuator output ports")
if port["dtype"] != "float32" or port["representation"] != "features" or len(port["features"]) != 1:
raise ValueError("Scalar actuator commands require one float32 feature per actuator")
command = port["command"]
if command["encoding"] == "normalized":
if command["clip"] != [-1, 1] or port["features"][0]["unit"] != "1":
raise ValueError("Normalized commands require dimensionless [-1,1] execution clip")
elif command["clip"] is not None and command["clip"][0] >= command["clip"][1]:
raise ValueError("Physical command clip requires lower < upper")
elif port["command"] is not None:
raise ValueError("Non-command ports must not contain command metadata")
def _requirements(requirements, part):
for field, allowed in (
("part_types", PART_TYPES),
("required_sensor_kinds", SENSOR_KINDS),
("required_effector_roles", EFFECTOR_ROLES),
):
if not set(requirements[field]) <= allowed:
raise ValueError(f"Unknown requirement in {field}")
if part["part_type"] not in requirements["part_types"]:
raise ValueError("Software does not support this part type")
if (
part["topology"]["structure"] not in requirements["topologies"]
or part["attachment"]["mode"] not in requirements["attachment_modes"]
):
raise ValueError("Unsupported topology or attachment mode")
entities = _entities(part)
if not {joint["type"] for joint in entities["joint"]} <= set(requirements["joint_types"]):
raise ValueError("Unsupported joint type")
if not requirements["supports_coupling"] and any(joint["coupling"] for joint in entities["joint"]):
raise ValueError("Software does not support coupled joints")
for entity, axis in ENTITY_AXES.items():
if len(entities[entity]) > requirements["capacities"][axis]:
raise ValueError(f"Hardware exceeds {axis} capacity")
if not set(requirements["required_sensor_kinds"]) <= {sensor["kind"] for sensor in part["sensors"]}:
raise ValueError("Missing required sensor capability")
outputs = {output for sensor in part["sensors"] for output in sensor["outputs"]}
if not set(requirements["required_sensor_outputs"]) <= outputs:
raise ValueError("Missing required sensor output semantics")
if not set(requirements["required_effector_roles"]) <= {effector["role"] for effector in part["end_effectors"]}:
raise ValueError("Missing required end-effector role")
for actuator in part["actuators"]:
if not set(requirements["required_control_modes"]) <= set(actuator["commands"]):
raise ValueError("Missing required actuator control mode")
if requirements["required_control_modes"] and not part["actuators"]:
raise ValueError("Control software requires actuators")
return entities
def _signal_coverage(port, selected, entities):
if port["kind"] != "state" or port["representation"] != "features":
return
for feature in port["features"]:
quantity = feature["quantity"]
if quantity in ("joint.position", "joint.velocity"):
dynamic_unit = "joint_position" if quantity == "joint.position" else "joint_velocity"
for record in selected:
if port["entity"] != "joint":
raise ValueError("Joint-state quantities require joint entity ports")
physical_unit = record["position_unit"] + ("/s" if quantity == "joint.velocity" else "")
expected = (dynamic_unit, physical_unit) if feature["normalization"] == "identity" else ("1",)
if feature["unit"] not in expected:
raise ValueError("Joint-state feature unit/normalization disagrees with selected joints")
if not quantity.startswith(("joint.", "contact.")):
continue
covered = set()
for sensor in entities["sensor"]:
if sensor["target"]["entity"] != port["entity"]:
continue
if any(quantity == signal or quantity.startswith(signal + ".") for signal in sensor["outputs"]):
covered.update(sensor["target"]["ids"])
if not {record["id"] for record in selected} <= covered:
raise ValueError(f"State port {port['name']} lacks sensor coverage for {quantity}")
def _port_binding(port, selected, commanded, entities):
if port["required"] and not selected:
raise ValueError(f"Required port {port['name']} selects no entities")
_signal_coverage(port, selected, entities)
if port["kind"] != "command":
return
mode = port["command"]["mode"]
for actuator in selected:
if actuator["id"] in commanded:
raise ValueError("Conflicting command ports target the same actuator")
commanded.add(actuator["id"])
if mode not in actuator["commands"]:
raise ValueError("Command port mode unavailable on selected actuator")
unit = port["features"][0]["unit"]
if port["command"]["encoding"] == "physical" and unit not in (
"actuator_command",
actuator["commands"][mode]["unit"],
):
raise ValueError("Physical command port unit disagrees with selected actuator")
def _software_contract(data, root):
requirements, interface = data["requirements"], data["interface"]
_integers(requirements["capacities"], ENTITY_AXES.values())
_integers(interface, ("contract_version",))
ports = _indexed(interface["ports"], "name")
for port in ports.values():
_port_structure(port, ports, requirements["capacities"])
parts = _bindings(data, root)
for part in parts:
entities = _requirements(requirements, part)
commanded = set()
for port in ports.values():
_port_binding(port, _select(port, entities), commanded, entities)
timing = data["runtime"]["timing"]
steps = [part["timing"]["control_dt_s"] for part in parts]
if timing["policy"] == "per_part":
if timing["control_dt_s"] is not None:
raise ValueError("per_part timing must not declare a single common control dt")
elif any(not math.isclose(step, steps[0], rel_tol=0, abs_tol=1e-12) for step in steps):
raise ValueError("Software requires common control dt across alternative bindings")
elif timing["control_dt_s"] is not None and not math.isclose(
timing["control_dt_s"], steps[0], rel_tol=0, abs_tol=1e-12
):
raise ValueError("Software/hardware control dt mismatch")
runtime = data["runtime"]
if runtime["implementation"] == "available":
raise ValueError("No v2 runtime adapters are registered yet; do not claim availability")
if runtime["adapter_id"] is not None:
raise ValueError("Unimplemented runtime must not advertise a callable adapter")
def validate_software(path, repo_root=ROOT, require_runtime=False):
_version(path)
data = _structure(path, "software_spec.v2.schema.json")
root = Path(repo_root).resolve()
_software_contract(data, root)
if require_runtime:
raise ValueError("v2 description is compatible, but its runtime adapter is unimplemented")
_artifact(data, root)
return data
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--hardware", type=Path, nargs="+", default=[])
parser.add_argument("--software", type=Path, nargs="+", default=[])
parser.add_argument("--repo-root", type=Path, default=ROOT)
parser.add_argument(
"--require-runtime", action="store_true", help="Reject compatible but unimplemented software adapters"
)
args = parser.parse_args(argv)
if not args.hardware and not args.software:
parser.error("Provide --hardware and/or --software")
try:
for path in args.hardware:
validate_hardware(path)
print(f"Hardware description OK: {path}")
for path in args.software:
validate_software(path, args.repo_root, args.require_runtime)
print(f"Software description and bindings OK: {path} (v2 runtime unimplemented)")
except (ValueError, OSError) as error:
parser.exit(1, f"Description validation failed: {error}\n")
print("Static descriptions only; simulation, checkpoint contents and trained-skill quality are NOT verified.")
if __name__ == "__main__":
main()