Files
SkillFactory/scripts/validate_descriptions.py
T
2026-10-10 16:34:40 +08:00

532 lines
25 KiB
Python

#!/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()