react-manip 0.1.0__py3-none-any.whl

scripts/pygame_task_debug.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Manual task-default debugger; this does not replay or score the fixed bank."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from scripts.pygame_demo import KeyboardPoseControl
+
+
+def _parser():
+    from react_manip.instances.records import SUPPORTED_TASKS
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--task', choices=SUPPORTED_TASKS,
+                        default='laptop_into_drawer')
+    parser.add_argument('--robot', default=None,
+                        help='robot override; defaults to the task-configured embodiment')
+    parser.add_argument('--seed', type=int, default=0,
+                        help='nonnegative task-default construction seed')
+    parser.add_argument('--scenario', type=Path,
+                        help='resolved Scenario JSON for the selected task')
+    parser.add_argument('--hz', type=float, default=20,
+                        help='display pacing; task physics timing stays unchanged')
+    parser.add_argument('--camera', help='initial camera name')
+    parser.add_argument('--fast-speed', type=float, default=1.0,
+                        help='fast target speed in m/s, (0, 2]; default 1.0')
+    return parser
+
+
+def main(argv=None):
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.seed < 0:
+        parser.error('seed must be nonnegative')
+    if args.hz <= 0 or not np.isfinite(args.hz):
+        parser.error('hz must be positive')
+    if not np.isfinite(args.fast_speed) or not 0 < args.fast_speed <= 2:
+        parser.error('fast-speed must be in (0, 2] m/s')
+
+    try:
+        import pygame
+    except ImportError:
+        parser.error('install dependencies: python -m pip install -r requirements.txt')
+
+    from react_manip.builtin import register_builtin_tasks
+    from react_manip.cameras import display_camera_names
+    from react_manip.core.compatibility import resolve_task_robot
+    from react_manip.core.registry import get_task_registry
+    from react_manip.core.scenarios import Scenario, sample_scenario
+    from react_manip.rendering import NativeRGBRenderer
+    from react_manip.robot_registry import register_default_robots
+
+    register_default_robots()
+    register_builtin_tasks()
+    definition = get_task_registry().get(args.task)
+    try:
+        args.robot = resolve_task_robot(definition.spec, args.robot)
+    except ValueError as exc:
+        parser.error(str(exc))
+
+    if args.scenario:
+        scenario = Scenario.load(args.scenario)
+    elif args.task == 'button_indicator_matching':
+        profile = ROOT / 'configs' / args.task / 'profile_default.json'
+        scenario = sample_scenario(json.loads(profile.read_text()), seed=args.seed)
+    else:
+        scenario = None
+    if scenario is not None and scenario.task_id != args.task:
+        parser.error('scenario task does not match --task')
+
+    seed = scenario.seed if scenario is not None else args.seed
+    env = renderer = None
+    try:
+        kwargs = dict(seed=seed, robot_id=args.robot,
+                      has_offscreen_renderer=False)
+        if scenario is not None:
+            kwargs['scenario'] = scenario
+        env = definition.factory(**kwargs)
+
+        pygame.init()
+        screen = pygame.display.set_mode((1120, 720))
+        pygame.display.set_caption('ReAct-Manip task debug: ' + args.task)
+        font = pygame.font.Font(None, 24)
+        clock = pygame.time.Clock()
+        renderer = NativeRGBRenderer()
+        keys = set()
+        active = 0
+        camera_index = 0
+        fast_latched = False
+        raw = arms = layout = grippers = manual = cameras = None
+        done, info = False, {}
+
+        def reset():
+            nonlocal raw, arms, layout, grippers, manual, done, info
+            nonlocal cameras, active, camera_index, fast_latched
+            reset_result = env.reset()
+            info = (reset_result[1] if isinstance(reset_result, tuple)
+                    and len(reset_result) == 2 else {})
+            raw = getattr(env, 'env', env)
+            robot = raw.robots[0]
+            arms = tuple(robot.arms)
+            layout = robot.composite_controller._action_split_indexes
+            grippers = {arm: -1.0 for arm in arms}
+            manual = KeyboardPoseControl(robot, raw.control_timestep,
+                                         args.fast_speed)
+            fast_latched = False
+            done = False
+            active = 0
+            keys.clear()
+            cameras = list(display_camera_names(raw, include_legacy=True))
+            if not cameras:
+                cameras = ['__free__']
+            camera_index = (cameras.index(args.camera)
+                            if args.camera in cameras else 0)
+
+        reset()
+        running = True
+        while running:
+            for event in pygame.event.get():
+                if event.type == pygame.QUIT:
+                    running = False
+                elif event.type == pygame.KEYDOWN:
+                    if event.key == pygame.K_ESCAPE:
+                        running = False
+                    elif event.key == pygame.K_BACKSPACE:
+                        reset()
+                    elif event.key == pygame.K_TAB:
+                        manual.stop()
+                        fast_latched = False
+                        active = (active + 1) % len(arms)
+                        keys.clear()
+                    elif event.key == pygame.K_f:
+                        fast_latched = not fast_latched
+                    elif event.key in (pygame.K_EQUALS, pygame.K_KP_PLUS,
+                                       pygame.K_MINUS, pygame.K_KP_MINUS):
+                        sign = (1 if event.key in
+                                (pygame.K_EQUALS, pygame.K_KP_PLUS) else -1)
+                        manual.fast_speed = float(np.clip(
+                            round(manual.fast_speed + sign * .05, 2), .05, 2.))
+                    elif event.key == pygame.K_SPACE:
+                        arm = arms[active]
+                        grippers[arm] = -grippers[arm]
+                    elif pygame.K_1 <= event.key <= pygame.K_9:
+                        index = event.key - pygame.K_1
+                        if index < len(cameras):
+                            camera_index = index
+                    elif event.key in (pygame.K_LEFTBRACKET,
+                                       pygame.K_RIGHTBRACKET):
+                        step = 1 if event.key == pygame.K_RIGHTBRACKET else -1
+                        camera_index = (camera_index + step) % len(cameras)
+                    else:
+                        keys.add(event.key)
+                elif event.type == pygame.WINDOWFOCUSLOST:
+                    fast_latched = False
+                    keys.clear()
+                    manual.stop()
+                elif event.type == pygame.KEYUP:
+                    keys.discard(event.key)
+            if not running:
+                break
+
+            def axis(positive, negative):
+                return float((positive in keys) - (negative in keys))
+
+            target = np.array([
+                axis(pygame.K_RIGHT, pygame.K_LEFT),
+                axis(pygame.K_UP, pygame.K_DOWN),
+                axis(pygame.K_PAGEUP, pygame.K_PAGEDOWN),
+                axis(pygame.K_d, pygame.K_a),
+                axis(pygame.K_w, pygame.K_s),
+                axis(pygame.K_e, pygame.K_q),
+            ])
+            fast = fast_latched or bool(
+                keys & {pygame.K_LSHIFT, pygame.K_RSHIFT})
+            if not done:
+                action = manual.action(env.action_dim, layout, arms[active],
+                                       target, grippers, fast=fast)
+                _, _, terminated, truncated, info = env.step(action)
+                done = bool(terminated or truncated)
+
+            frame = renderer.render(raw.sim, cameras[camera_index])
+            screen.fill((20, 24, 30))
+            screen.blit(pygame.surfarray.make_surface(
+                frame.transpose(1, 0, 2)), (0, 0))
+            score = next((info[key] for key in
+                          ('task_score', 'total_score', 'score', 'S')
+                          if key in info), '--')
+            lines = [
+                f'Task debug: {args.task}',
+                f'Robot: {args.robot}  Seed: {seed}  Arm: {arms[active]}',
+                f'Camera: {cameras[camera_index]}', f'Score: {score}',
+                f"Mode: {'FAST' if fast else 'FINE'}  "
+                f"Target: {manual.fast_speed if fast else .06:.2f} m/s",
+                'Arrows / PgUp PgDn: translation',
+                'A D / W S / Q E: rotation',
+                'F: toggle fast; Shift: hold fast',
+                f'+/-: fast target {manual.fast_speed:.2f} m/s',
+                'Space: gripper    Tab: switch arm',
+                '1-9 / [ ]: cameras',
+                'Backspace: reset    Esc: quit',
+                ('Episode ended. Backspace to reset.'
+                 if done else 'Unscored task-default debug'),
+            ]
+            for index, line in enumerate(lines):
+                screen.blit(font.render(line, True, (235, 235, 235)),
+                            (650, 20 + index * 32))
+            prompt = str(info.get('language_prompt', ''))
+            line, rows = '', []
+            for word in prompt.split():
+                candidate = (line + ' ' + word).strip()
+                if font.size(candidate)[0] > 1080 and line:
+                    rows.append(line)
+                    line = word
+                else:
+                    line = candidate
+            if line:
+                rows.append(line)
+            for index, line in enumerate(rows[:6]):
+                screen.blit(font.render(line, True, (235, 235, 235)),
+                            (20, 510 + index * 28))
+            pygame.display.flip()
+            clock.tick(args.hz)
+        return 0
+    finally:
+        if renderer is not None:
+            renderer.close()
+        if env is not None:
+            env.close()
+        pygame.quit()
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

scripts/regenerate_instance_bank.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Rebuild saved initial states from existing resolved questions on current robots.
+
+This preserves compatible question parameters, scenes, and instruction plans.
+It does not copy old simulation vectors or certify robot solvability.
+"""
+import argparse
+from copy import deepcopy
+import json
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from react_manip.core.compatibility import resolve_task_robot
+from react_manip.core.scenarios import Scenario
+from react_manip.instances.records import digest, seal, save_record, validate_parameters
+from react_manip.instances.runtime import (
+    _construct, capture_state, contract_for, runtime_identity, spec_for, ReplayEnv,
+)
+from react_manip.instances.candidate_bank import checked_path, load_bank, write_json
+from react_manip.instances.variation import TASKS as VARIED_TASKS, sample_variation, episode_scenario
+
+
+def build_varied_episode(task, scenario, robot, source, index, report):
+    """Resolve sizes/physics before compilation, retaining accepted stored values."""
+    episode = deepcopy(source)
+    variation = (episode['variation'] if 'variation' in episode else
+                 sample_variation(task, scenario.parameters, scenario.seed, index))
+    resolved = episode_scenario(scenario, variation)
+    if task == 'leveling_board1':
+        from tasks.leveling_board1.feasibility import certify_dimensions
+        certificate = certify_dimensions(resolved.parameters)
+        report.setdefault('leveling_certificates', []).append(dict(
+            episode_id=episode['episode_id'], variation_digest=digest(variation), certificate=certificate))
+        if 'variation' not in source:
+            from tasks.leveling_board1.instances import sample_episode_instance
+            episode['scene'] = sample_episode_instance(
+                resolved.parameters, source['provenance']['seed'])
+    env = _construct(task, resolved, robot, episode=episode.get('scene'))
+    try:
+        env.reset()
+        episode.update(variation=variation, runtime=runtime_identity(env, task),
+                       initial_state=capture_state(env))
+        return episode
+    finally:
+        env.close()
+
+
+def read_checked(root, ref):
+    value = json.loads(checked_path(root, ref['path']).read_text())
+    actual = digest({k: v for k, v in value.items() if k != 'content_digest'})
+    if actual != ref['digest'] or actual != value['content_digest']:
+        raise ValueError(f"Corrupt source record: {ref['path']}")
+    return value
+
+
+def bind_scene(env, episode):
+    if 'scene' in episode:
+        env.env.episode_instance = deepcopy(episode['scene'])
+        if episode['task_id'] == 'phone_lean':
+            env.env.episode_seed = episode['scene']['episode_seed']
+            env.env.layout_seed = env.env.episode_seed
+
+
+def rebuild(source, out, *, include_tasks=None, suite_id=None, min_lighting_scale=None):
+    source = source.resolve()
+    bank = json.loads(source.read_text())
+    if bank['content_digest'] != digest({k: v for k, v in bank.items() if k != 'content_digest'}):
+        raise ValueError('Corrupt source bank')
+    manifest = read_checked(source.parent, dict(path=bank['manifest'], digest=bank['manifest_digest']))
+    out.mkdir(parents=True, exist_ok=False)
+    groups = []
+    report = dict(source_bank_digest=bank['content_digest'], instances=0, episodes=0,
+                  scope='Fresh resolved Episode models and reset states; not robot solvability certification',
+                  preserved='Base Task parameters, Task/Episode IDs, round plans and protocol; four feedback tasks receive explicit Episode variations, retained on later rebuilds',
+                  verification='Every episode restored exactly and advanced one zero-action step',
+                  robots={}, cameras={}, language_samples=[], parameter_migrations=[])
+    for group in manifest['groups']:
+        old = read_checked(source.parent, group['task_instance'])
+        task = old['task_id']
+        if include_tasks is not None and task not in include_tasks:continue
+        spec, contract = spec_for(task), contract_for(task)
+        robot = resolve_task_robot(spec)
+        scenario = Scenario(**{k: deepcopy(v) for k, v in old['scenario'].items() if k != 'digest'})
+        if scenario.digest != old['scenario']['digest']:
+            raise ValueError('Corrupt source scenario')
+        if min_lighting_scale is not None:
+            lighting = scenario.parameters.get('lighting')
+            if isinstance(lighting, dict) and 'intensity_scale' in lighting:
+                old_scale = float(lighting['intensity_scale'])
+                if old_scale < min_lighting_scale:
+                    lighting['intensity_scale'] = float(min_lighting_scale)
+                    report.setdefault('lighting_migrations', []).append(dict(
+                        task_instance_id=old['task_instance_id'], old_scale=old_scale,
+                        new_scale=float(min_lighting_scale)))
+        if task in VARIED_TASKS:
+            scenario.metadata['episode_variation_version'] = 1
+        source_episodes = [read_checked(source.parent, ref) for ref in group['episodes']]
+        # Episode scenes for these tasks carry a digest of the Task parameters.
+        # Raising the lighting floor changes those parameters, so refresh the
+        # scene reference while preserving the sampled pose/layout itself.
+        if task in ('rope_hang', 'laptop_into_drawer'):
+            for episode in source_episodes:
+                scene = episode.get('scene')
+                if isinstance(scene, dict) and 'task_digest' in scene:
+                    scene['task_digest'] = digest(scenario.parameters)
+        validate_parameters(scenario.parameters, contract)
+        env = _construct(task, scenario, robot)
+        try:
+            env.reset()
+            fields = {k: deepcopy(v) for k, v in old.items()
+                      if k not in ('schema_version', 'kind', 'content_digest')}
+            fields.update(scenario=scenario.to_dict(), robot_id=robot, task_spec_digest=digest(spec.to_dict()),
+                          contract_digest=digest(contract), runtime=runtime_identity(env, task))
+            instance = seal('task_instance', **fields)
+            save_record(instance, out / group['task_instance']['path'])
+            new_group = dict(task_instance=dict(path=group['task_instance']['path'],
+                                               digest=instance['content_digest']), episodes=[])
+            episodes = []
+            for episode_index, (ref, source_episode) in enumerate(zip(group['episodes'], source_episodes)):
+                episode = deepcopy(source_episode)
+                if episode['task_instance_digest'] != old['content_digest']:
+                    raise ValueError('Source episode belongs to a different instance')
+                if task in VARIED_TASKS:
+                    episode = build_varied_episode(task, scenario, robot, episode, episode_index, report)
+                    fields = {k: deepcopy(v) for k,v in episode.items()
+                              if k not in ('schema_version','kind','content_digest')}
+                    fields['task_instance_digest'] = instance['content_digest']
+                    record = seal('episode_instance', **fields)
+                    save_record(record, out / ref['path'])
+                    new_group['episodes'].append(dict(path=ref['path'], digest=record['content_digest']))
+                    episodes.append(record)
+                    print(f"  {record['episode_id']}: resolved Episode model saved", flush=True)
+                    continue
+                bind_scene(env, episode)
+                env.reset()
+                fields = {k: deepcopy(v) for k, v in episode.items()
+                          if k not in ('schema_version', 'kind', 'content_digest')}
+                fields.update(task_instance_digest=instance['content_digest'], initial_state=capture_state(env))
+                record = seal('episode_instance', **fields)
+                save_record(record, out / ref['path'])
+                new_group['episodes'].append(dict(path=ref['path'], digest=record['content_digest']))
+                episodes.append(record)
+        finally:
+            env.close()
+        replay = ReplayEnv(instance, cameras=False)
+        try:
+            import numpy as np
+            for episode_index, episode in enumerate(episodes):
+                replay.bind(episode)
+                _, reset_info = replay.reset()
+                if episode_index == 0:
+                    report['language_samples'].append(dict(task_instance_id=instance['task_instance_id'],
+                        task_id=task, episode_id=episode['episode_id'],
+                        prompt=reset_info['language_prompt_structured']))
+                if capture_state(replay) != episode['initial_state']:
+                    raise ValueError('Replay initial state is not exact')
+                info = replay.step(np.zeros(replay.action_dim))[-1]
+                assert info['language_prompt_structured'] == replay._wrapped.get_language_prompt()
+                assert info['language_prompt'] == info['language_prompt_structured']['text']
+        finally:
+            replay.close()
+        groups.append(new_group)
+        report['instances'] += 1
+        report['episodes'] += len(episodes)
+        report['robots'][task] = robot
+        report['cameras'][task] = instance['runtime']['cameras']
+        print(f"{report['instances']}/{len(manifest['groups'])} {instance['task_instance_id']}: {robot}, {len(episodes)} exact replays", flush=True)
+    result = seal('manifest', suite_id=suite_id or manifest['suite_id'], protocol=manifest['protocol'], groups=groups)
+    save_record(result, out / 'candidates.json')
+    bank = {k: deepcopy(v) for k, v in bank.items() if k != 'content_digest'}
+    bank.update(manifest='candidates.json', manifest_digest=result['content_digest'])
+    bank['content_digest'] = digest(bank)
+    write_json(out / 'bank.json', bank)
+    load_bank(out / 'bank.json')
+    report['bank_digest'] = bank['content_digest']
+    report['included_tasks']=sorted(report['robots'])
+    report['excluded_tasks']=sorted(set(read_checked(source.parent,g['task_instance'])['task_id'] for g in manifest['groups'])-set(report['robots']))
+    write_json(out / 'generation.json', report)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--source', type=Path, default=ROOT / 'react_manip/suites/piperx_candidates_v1/bank.json')
+    parser.add_argument('--out', type=Path, required=True, help='New, nonexistent output directory')
+    parser.add_argument('--min-lighting-scale', type=float,
+                        help='Raise saved scenario lighting intensity_scale values below this floor before rebuilding')
+    args = parser.parse_args()
+    if args.min_lighting_scale is not None and not 0 < args.min_lighting_scale <= 2:
+        parser.error('--min-lighting-scale must be in (0, 2]')
+    rebuild(args.source, args.out, min_lighting_scale=args.min_lighting_scale)

scripts/remove_task_from_bank.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Remove one task and its referenced records from a sealed candidate bank."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from react_manip.instances.candidate_bank import checked_path, write_json
+from react_manip.instances.records import digest, seal
+
+
+IDENTITY_FIELDS = ("task_id", "task_instance_id", "episode_id")
+
+
+def _checked_record(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    expected = digest({key: item for key, item in value.items() if key != "content_digest"})
+    if value.get("content_digest") != expected:
+        raise ValueError(f"content digest mismatch: {path}")
+    return value
+
+
+def _belongs_to_task(value: object, task_id: str) -> bool:
+    if not isinstance(value, dict):
+        return False
+    prefix = task_id + "_"
+    return any(
+        value.get(field) == task_id
+        or (isinstance(value.get(field), str) and value[field].startswith(prefix))
+        for field in IDENTITY_FIELDS
+    )
+
+
+def remove_task(bank_path: Path, task_id: str) -> None:
+    bank_path = bank_path.resolve()
+    bank = _checked_record(bank_path)
+    manifest_path = checked_path(bank_path.parent, bank["manifest"])
+    manifest = _checked_record(manifest_path)
+    prefix = f"instances/{task_id}_"
+    removed = [
+        group for group in manifest["groups"]
+        if group["task_instance"]["path"].startswith(prefix)
+    ]
+    if not removed:
+        raise ValueError(f"task is not present in the bank: {task_id}")
+    if any(len(group["episodes"]) != 15 for group in removed):
+        raise ValueError("removed task contains a nonstandard Episode count")
+
+    kept = [group for group in manifest["groups"] if group not in removed]
+    result = seal(
+        "manifest",
+        suite_id=manifest["suite_id"],
+        protocol=manifest["protocol"],
+        groups=kept,
+    )
+    write_json(manifest_path, result)
+
+    bank_fields = {key: value for key, value in bank.items() if key != "content_digest"}
+    bank_fields["manifest_digest"] = result["content_digest"]
+    bank_fields["content_digest"] = digest(bank_fields)
+    write_json(bank_path, bank_fields)
+
+    generation_path = bank_path.parent / "generation.json"
+    if generation_path.exists():
+        generation = json.loads(generation_path.read_text(encoding="utf-8"))
+        for field in ("robots", "cameras"):
+            if isinstance(generation.get(field), dict):
+                generation[field].pop(task_id, None)
+        for field, value in list(generation.items()):
+            if isinstance(value, list):
+                generation[field] = [
+                    item for item in value if not _belongs_to_task(item, task_id)
+                ]
+        generation["instances"] = len(kept)
+        generation["episodes"] = sum(len(group["episodes"]) for group in kept)
+        generation["included_tasks"] = sorted(generation.get("robots", {}))
+        generation["bank_digest"] = bank_fields["content_digest"]
+        for obsolete in ("phone_certificates", "resampled_scenes", "variation_rejections"):
+            if generation.get(obsolete) == []:
+                generation.pop(obsolete)
+        write_json(generation_path, generation)
+
+    for group in removed:
+        for reference in [group["task_instance"], *group["episodes"]]:
+            checked_path(bank_path.parent, reference["path"]).unlink(missing_ok=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--bank", type=Path, required=True)
+    parser.add_argument("--task", required=True)
+    args = parser.parse_args()
+    remove_task(args.bank, args.task)
+
+
+if __name__ == "__main__":
+    main()

scripts/select_task_instances.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Select all three instances and their Episodes for one task from the main bank."""
+import argparse
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from react_manip.instances.candidate_bank import (
+    ALGORITHM, copy_group, load_bank, write_json,
+)
+from react_manip.instances.records import digest, save_record, seal
+
+
+def select_task(path, *, task, seed, out):
+    bank, source, manifest, choices = load_bank(path)
+    if task not in choices:
+        raise ValueError(f'Unknown task {task!r}; available: {", ".join(sorted(choices))}')
+    if type(seed) is not int or seed < 0:
+        raise ValueError('draw seed must be a nonnegative integer')
+    selected_groups = []
+    records = []
+    for instance, episodes in choices[task]:
+        group = next(g for g in manifest['groups']
+                     if g['task_instance']['digest'] == instance['content_digest'])
+        selected_groups.append(group)
+        records.append(dict(task_id=task, task_instance_id=instance['task_instance_id'],
+                            task_instance_digest=instance['content_digest'],
+                            episode_digests=[e['content_digest'] for e in episodes]))
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=False)
+    for group in selected_groups:
+        copy_group(group, source.parent, out)
+    selected = seal('manifest', suite_id=out.name, protocol=manifest['protocol'], groups=selected_groups)
+    save_record(selected, out / 'manifest.json')
+    provenance = dict(
+        schema_version='cl-manip.draw.v1', algorithm=ALGORITHM, draw_seed=seed,
+        draws_per_task=3,
+        bank_digest=bank['content_digest'], candidate_manifest_digest=manifest['content_digest'],
+        selected_manifest_digest=selected['content_digest'],
+        selected=records,
+    )
+    provenance['content_digest'] = digest(provenance)
+    write_json(out / 'selection.json', provenance)
+    return out / 'manifest.json'
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--candidate-bank', type=Path,
+                        default=ROOT / 'react_manip/suites/piperx_candidates_v1/bank.json')
+    parser.add_argument('--task', required=True)
+    parser.add_argument('--draw-seed', type=int, required=True)
+    parser.add_argument('--out', type=Path, required=True, help='New selection directory containing all three instances / 45 episodes')
+    args = parser.parse_args()
+    try:
+        result = select_task(args.candidate_bank, task=args.task, seed=args.draw_seed, out=args.out)
+    except (ValueError, TypeError, OSError) as exc:
+        parser.error(str(exc))
+    print(result)
+
+
+if __name__ == '__main__':
+    main()