rhylthyme-cli-runner 0.2.7a0__tar.gz → 0.2.8a0__tar.gz

{rhylthyme_cli_runner-0.2.7a0/src/rhylthyme_cli_runner.egg-info → rhylthyme_cli_runner-0.2.8a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhylthyme-cli-runner
-Version: 0.2.7a0
+Version: 0.2.8a0
 Summary: CLI runner for Rhylthyme real-time program schedules
 Home-page: https://github.com/rhylthyme/rhylthyme-cli-runner
 Author: Rhylthyme Team
@@ -26,7 +26,9 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: jsonschema>=4.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: colorama>=0.4.0
-Requires-Dist: rhylthyme-spec>=0.2.0a0
+Requires-Dist: rhylthyme-spec>=0.2.1a0
+Provides-Extra: galago
+Requires-Dist: rhylthyme-galago>=0.1.0a0; extra == "galago"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=2.10.0; extra == "dev"

{rhylthyme_cli_runner-0.2.7a0 → rhylthyme_cli_runner-0.2.8a0}/setup.py

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="rhylthyme-cli-runner",
-    version="0.2.7a0",
+    version="0.2.8a0",
     description="CLI runner for Rhylthyme real-time program schedules",
     long_description=read_readme(),
     long_description_content_type="text/markdown",
@@ -38,9 +38,11 @@ setup(
         "jsonschema>=4.0.0",
         "pyyaml>=6.0",
         "colorama>=0.4.0",
-        "rhylthyme-spec>=0.2.0a0",
+        "rhylthyme-spec>=0.2.1a0",
     ],
     extras_require={
+        # Instrument steps on galago-tools lab instruments (--workcell)
+        "galago": ["rhylthyme-galago>=0.1.0a0"],
         "dev": [
             # Testing framework
             "pytest>=6.0.0",

{rhylthyme_cli_runner-0.2.7a0 → rhylthyme_cli_runner-0.2.8a0}/src/rhylthyme_cli_runner/__init__.py

@@ -6,7 +6,7 @@ This package provides the command-line interface for running and validating
 Rhylthyme real-time program schedules.
 """
 
-__version__ = "0.2.7a0"
+__version__ = "0.2.8a0"
 __author__ = "Rhylthyme Team"
 __description__ = "CLI runner for Rhylthyme real-time program schedules"
 

{rhylthyme_cli_runner-0.2.7a0 → rhylthyme_cli_runner-0.2.8a0}/src/rhylthyme_cli_runner/cli.py

@@ -105,7 +105,18 @@ def cli(ctx, environments_dir):
     is_flag=True,
     help="Enforce all tasks must be defined in resourceConstraints (strict mode)",
 )
-def validate(program_files, schema, environment, verbose, json_output, strict):
+@click.option(
+    "--workcell",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help=(
+        "Workcell file: check instrument steps against its galago tools "
+        "(tool names, types, commands and params)"
+    ),
+)
+def validate(
+    program_files, schema, environment, verbose, json_output, strict, workcell
+):
     """
     Validate one or more program files against the schema.
 
@@ -115,6 +126,8 @@ def validate(program_files, schema, environment, verbose, json_output, strict):
     Use --json to get machine-readable output for CI or scripting.
     Use --strict to require all tasks used in steps/buffers to be defined in resourceConstraints.
     Use -e/--environment to validate against specific environment constraints.
+    Use --workcell to check instrument steps against a lab's galago tools;
+    without it, commands are checked against each step's toolType.
     """
     # Set up environment for validation if specified
     if environment:
@@ -165,7 +178,7 @@ def validate(program_files, schema, environment, verbose, json_output, strict):
     all_valid = True
     for program_file in program_files:
         success = validate_program_file(
-            program_file, schema, verbose, json_output, strict
+            program_file, schema, verbose, json_output, strict, workcell
         )
         if not success:
             all_valid = False
@@ -256,6 +269,28 @@ def validate(program_files, schema, environment, verbose, json_output, strict):
         "answers, which are what the record stores in context.userTags"
     ),
 )
+@click.option(
+    "--workcell",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help=(
+        "Workcell file mapping the program's instrument tools to galago-tools "
+        "servers; required for programs with instrument steps"
+    ),
+)
+@click.option(
+    "--live",
+    is_flag=True,
+    help=(
+        "Run instrument steps on real hardware instead of galago's simulated "
+        "mode; shows what will run and asks first"
+    ),
+)
+@click.option(
+    "--confirm-live",
+    is_flag=True,
+    help="Answer the --live question in advance (for scripts)",
+)
 def run(
     program_file,
     schema,
@@ -270,6 +305,9 @@ def run(
     history_file,
     no_history,
     predict_context,
+    workcell,
+    live,
+    confirm_live,
 ):
     """
     Run a program file with the interactive UI.
@@ -296,6 +334,11 @@ def run(
     --history FILE to read a specific corpus, --no-history to turn it off,
     and --predict-context KEY=VALUE to predict for a context other than the
     factor answers.
+
+    Programs with instrument steps need --workcell FILE (galago-tools servers,
+    via rhylthyme-galago). Tools run in galago's simulated mode unless you pass
+    --live, which lists the tools and commands and asks you to type 'live'
+    before anything is configured; --confirm-live answers for scripts.
     """
     run_program(
         program_file,
@@ -311,6 +354,9 @@ def run(
         history_file=history_file,
         use_history=not no_history,
         predict_context=predict_context,
+        workcell=workcell,
+        live=live,
+        confirm_live=confirm_live,
     )
 
 
@@ -324,7 +370,16 @@ def run(
 @click.option(
     "--verbose", "-v", is_flag=True, help="Show detailed planning information"
 )
-def plan(input_file, output_file, environment, verbose):
+@click.option(
+    "--workcell",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help=(
+        "Workcell file: estimate instrument steps that have no duration from "
+        "their tools' EstimateDuration"
+    ),
+)
+def plan(input_file, output_file, environment, verbose, workcell):
     """
     Optimize a program schedule to reduce resource contention.
 
@@ -333,9 +388,17 @@ def plan(input_file, output_file, environment, verbose):
     starts to reduce contention at critical junctures.
 
     The optimized program is saved to the specified output file.
+
+    Instrument steps without a duration get an estimated one (flagged in
+    metadata.durationEstimate): from the tool with --workcell, else from a
+    duration-like command param, else a default.
     """
     success = plan_program(
-        input_file, output_file, verbose, environment_file=environment
+        input_file,
+        output_file,
+        verbose,
+        environment_file=environment,
+        workcell=workcell,
     )
     if not success:
         sys.exit(1)

{rhylthyme_cli_runner-0.2.7a0 → rhylthyme_cli_runner-0.2.8a0}/src/rhylthyme_cli_runner/history/recorder.py

@@ -13,6 +13,8 @@ the events it emits are:
 ``step_aborted``     {step_id, time, reason}
 ``program_paused``   {time, wall_time}
 ``program_resumed``  {time, wall_time, paused_seconds}
+``program_aborted``  {time, reason}  (reason goes to ``context.abortReason``)
+``instrument_reply`` {step_id, time, ok, code, errorMessage, metadata}
 
 All ``time`` values are the runner's program clock (an epoch float that
 advances at ``time_scale``); the record stores them as seconds from the
@@ -217,6 +219,8 @@ class RunRecorder:
         self.context: Dict[str, Any] = self._build_context()
 
         self.actuals: Dict[str, Dict[str, Any]] = {}
+        # step id -> {tool, command, replies: [{attempt, at, code, ...}]}
+        self.instrument_log: Dict[str, Dict[str, Any]] = {}
         self.paused_seconds: Dict[str, float] = {sid: 0.0 for sid in self.step_order}
         self._pause_wall: Optional[float] = None
         self._paused_running: List[str] = []
@@ -271,6 +275,31 @@ class RunRecorder:
             entry.setdefault("start", data["time"])
             entry["end"] = data["time"]
             entry["endedBy"] = "abort"
+        elif event_type == "instrument_reply":
+            sid = data["step_id"]
+            step = getattr(self.runner, "steps", {}).get(sid)
+            instrument = (getattr(step, "instrument", None) or {}) if step else {}
+            log = self.instrument_log.setdefault(
+                sid,
+                {
+                    "tool": str(instrument.get("tool", "")),
+                    "command": str(instrument.get("command", "")),
+                    "replies": [],
+                },
+            )
+            reply: Dict[str, Any] = {
+                "attempt": getattr(step, "instrument_attempts", 0)
+                or len(log["replies"]) + 1,
+                "at": data["time"],
+                "code": str(data.get("code", "")),
+            }
+            if data.get("errorMessage"):
+                reply["errorMessage"] = str(data["errorMessage"])
+            if data.get("metadata"):
+                reply["metadata"] = copy.deepcopy(data["metadata"])
+            log["replies"].append(reply)
+        elif event_type == "program_aborted":
+            self.context["abortReason"] = data.get("reason") or "aborted"
         elif event_type == "program_paused":
             self._pause_wall = data.get("wall_time", time.time())
             self._paused_running = list(getattr(self.runner, "running_steps", []))
@@ -344,6 +373,13 @@ class RunRecorder:
                     entry["endedBy"] = actual.get("endedBy", "executor")
                 if "triggerFiredAt" in actual:
                     entry["triggerFiredAt"] = rel(actual["triggerFiredAt"])
+            log = self.instrument_log.get(sid)
+            if log:
+                entry["instrument"] = {
+                    "tool": log["tool"],
+                    "command": log["command"],
+                    "replies": [dict(r, at=rel(r["at"])) for r in log["replies"]],
+                }
             steps.append(entry)
 
         started_iso = _iso_utc(start_epoch) if start_epoch is not None else None

rhylthyme_cli_runner-0.2.8a0/src/rhylthyme_cli_runner/instruments.py

@@ -0,0 +1,258 @@
+"""
+Connect a ProgramRunner to galago-tools instruments (``rhylthyme run --workcell``).
+
+Needs the optional ``rhylthyme-galago`` package (``pip install
+rhylthyme[galago]``). When a step with an ``instrument`` starts, its command is
+sent on a worker thread; the reply comes back through
+``ProgramRunner.post_instrument_reply`` and ends (or fails) the step.
+"""
+
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+from .instance_checks import Finding
+
+INSTALL_HINT = "Instrument steps need rhylthyme-galago: pip install 'rhylthyme[galago]'"
+
+
+class InstrumentSetupError(RuntimeError):
+    """The workcell cannot run this program's instrument steps."""
+
+
+def program_uses_instruments(program: Mapping[str, Any]) -> bool:
+    return any(
+        step.get("instrument")
+        for track in program.get("tracks", [])
+        for step in track.get("steps", [])
+    )
+
+
+def instrument_findings(
+    program: Mapping[str, Any], workcell_source=None
+) -> List[Finding]:
+    """
+    Validation findings for a program's instrument steps: galago commands and
+    params checked against each step's toolType, or against the workcell's
+    tools when ``workcell_source`` (a path or dict) is given.
+    """
+    if workcell_source is None and not program_uses_instruments(program):
+        return []
+    try:
+        import rhylthyme_galago as galago
+    except ImportError:
+        return [
+            Finding(
+                code="instrument_unchecked",
+                message="Instrument steps were not checked",
+                where="program",
+                fix=INSTALL_HINT,
+                severity="error" if workcell_source is not None else "warning",
+            )
+        ]
+    workcell = None
+    if workcell_source is not None:
+        try:
+            workcell = galago.load_workcell(workcell_source)
+        except galago.WorkcellError as e:
+            return [Finding(code="workcell_invalid", message=str(e), where="workcell")]
+    return [
+        Finding(
+            code=issue.code,
+            message=issue.message,
+            where=f"step:{issue.step_id}",
+            severity=issue.severity,
+        )
+        for issue in galago.check_program(program, workcell)
+    ]
+
+
+def fill_instrument_durations(
+    program: Dict[str, Any], workcell_source=None
+) -> Tuple[Dict[str, Any], List[str]]:
+    """
+    Give instrument steps without a duration an estimated one, for planning:
+    the tool's EstimateDuration (with a workcell), else a duration-like
+    command param, else a default. Returns the new program and report lines;
+    without rhylthyme-galago the program comes back unchanged with a note.
+    """
+    missing = [step for step in _instrument_steps(program) if "duration" not in step]
+    if not missing:
+        return program, []
+    try:
+        import rhylthyme_galago as galago
+        from rhylthyme_galago.estimates import describe
+    except ImportError:
+        return program, [
+            f"{len(missing)} instrument step(s) have no duration and were not "
+            f"estimated. {INSTALL_HINT}"
+        ]
+    workcell = None
+    if workcell_source is not None:
+        try:
+            workcell = galago.load_workcell(workcell_source)
+        except galago.WorkcellError as e:
+            raise InstrumentSetupError(str(e)) from None
+    filled, estimates = galago.fill_durations(program, workcell)
+    return filled, ["Estimated instrument durations:"] + describe(estimates)
+
+
+def _reply_dict(reply) -> Dict[str, Any]:
+    return {
+        "ok": reply.ok,
+        "code": reply.code,
+        "errorMessage": reply.error_message,
+        "metadata": dict(reply.metadata),
+    }
+
+
+def _instrument_steps(program: Mapping[str, Any]) -> List[Dict[str, Any]]:
+    return [
+        step
+        for track in program.get("tracks", [])
+        for step in track.get("steps", [])
+        if step.get("instrument")
+    ]
+
+
+def _params_text(params: Optional[Mapping[str, Any]]) -> str:
+    return ", ".join(f"{k}={v!r}" for k, v in (params or {}).items())
+
+
+class InstrumentSession:
+    """
+    The workcell tools one run uses. Opening it touches no instrument;
+    ``summary()`` only reads tool status; ``prepare()`` configures the tools
+    (simulated unless the session is live); ``attach()`` wires the runner so
+    each instrument step's command is sent when the step starts.
+    """
+
+    def __init__(self, executor: Any, tools: List[str]):
+        self.executor = executor
+        self.tools = tools
+        self.checks: List[Any] = []
+
+    @property
+    def live(self) -> bool:
+        return not self.executor.simulated
+
+    def summary(self, program: Mapping[str, Any], limit: int = 12) -> List[str]:
+        """What a run will do, for the --live confirmation. Status is read-only."""
+        workcell = self.executor.workcell
+        mode = "LIVE: real hardware will move" if self.live else "simulated"
+        lines = [f"Workcell {workcell.id!r} ({mode})", "Tools:"]
+        for name in self.tools:
+            binding = workcell.tool(name)
+            status = self.executor.client(name).status()
+            lines.append(
+                f"  {name} ({binding.type}) @ {binding.address}: {status.status}"
+            )
+        steps = _instrument_steps(program)
+        lines.append(f"Instrument steps ({len(steps)}):")
+        for step in steps[:limit]:
+            inst = step["instrument"]
+            lines.append(
+                f"  {step['stepId']}: {inst['tool']}.{inst['command']}"
+                f"({_params_text(inst.get('params'))})"
+            )
+        if len(steps) > limit:
+            lines.append(f"  ... and {len(steps) - limit} more")
+        return lines
+
+    def prepare(self) -> None:
+        """Configure every tool; raise InstrumentSetupError unless all are ready."""
+        self.checks = self.executor.prepare(self.tools)
+        if not all(check.ready for check in self.checks):
+            raise InstrumentSetupError("\n".join(self.report()))
+
+    def report(self) -> List[str]:
+        mode = "simulated" if self.executor.simulated else "LIVE"
+        lines = [f"Workcell {self.executor.workcell.id!r} ({mode}):"]
+        for check in self.checks:
+            mark = "ok" if check.ready else "NOT READY"
+            detail = check.configure.error_message or check.status.error_message
+            line = f"  {check.tool} @ {check.address}: {check.status.status} [{mark}]"
+            lines.append(line + (f" {detail}" if detail and not check.ready else ""))
+        return lines
+
+    def attach(self, runner) -> None:
+        executor = self.executor
+
+        def on_reply(step_id: str, reply) -> None:
+            runner.post_instrument_reply(step_id, _reply_dict(reply))
+
+        def on_event(event_type: str, data: Dict[str, Any]) -> None:
+            # A step's command goes out when it starts and again on each retry
+            if event_type not in ("step_started", "step_retry"):
+                return
+            step = runner.steps.get(data["step_id"])
+            if step is not None and step.instrument:
+                step.instrument_attempts += 1
+                executor.submit(step.step_id, step.instrument, on_reply)
+
+        runner.add_event_listener(on_event)
+
+    def shutdown(self) -> List[str]:
+        """Stop the executor; return steps whose commands were still in flight."""
+        return self.executor.shutdown()
+
+
+def open_instruments(
+    program: Mapping[str, Any],
+    workcell_source,
+    *,
+    client_factory: Optional[Callable] = None,
+    live: bool = False,
+) -> InstrumentSession:
+    """
+    Load the workcell for ``program`` without contacting any tool.
+
+    Tools run simulated unless ``live`` is true. Raises InstrumentSetupError
+    when rhylthyme-galago is missing, the workcell is invalid, or a step
+    names a tool the workcell lacks.
+    """
+    try:
+        import rhylthyme_galago as galago
+    except ImportError:
+        raise InstrumentSetupError(INSTALL_HINT) from None
+
+    try:
+        workcell = galago.load_workcell(workcell_source)
+    except galago.WorkcellError as e:
+        raise InstrumentSetupError(str(e)) from None
+
+    tools = galago.instrument_tools(program)
+    unknown = [t for t in tools if t not in workcell.tools]
+    if unknown:
+        raise InstrumentSetupError(
+            f"Workcell {workcell.id!r} has no tool named "
+            + ", ".join(repr(t) for t in unknown)
+            + f" (tools: {', '.join(sorted(workcell.tools))})"
+        )
+
+    kwargs: Dict[str, Any] = {"simulated": not live}
+    if client_factory is not None:
+        kwargs["client_factory"] = client_factory
+    return InstrumentSession(galago.InstrumentExecutor(workcell, **kwargs), tools)
+
+
+def attach_instruments(
+    runner,
+    workcell_source,
+    *,
+    client_factory: Optional[Callable] = None,
+    live: bool = False,
+) -> InstrumentSession:
+    """
+    Open, configure and attach in one go (no confirmation step): the tools
+    are configured and ``runner`` sends each instrument step's command when
+    the step starts.
+    """
+    session = open_instruments(
+        runner.program, workcell_source, client_factory=client_factory, live=live
+    )
+    try:
+        session.prepare()
+    except InstrumentSetupError:
+        session.shutdown()
+        raise
+    session.attach(runner)
+    return session

{rhylthyme_cli_runner-0.2.7a0 → rhylthyme_cli_runner-0.2.8a0}/src/rhylthyme_cli_runner/program_planner.py

@@ -16,6 +16,8 @@ from typing import Any, Dict, List, Optional, Set, Tuple, Union
 
 import yaml
 
+from .instruments import fill_instrument_durations
+
 
 def load_program_file(file_path: str) -> dict:
     """
@@ -965,11 +967,30 @@ def save_optimized_program(program: dict, output_file: str):
             json.dump(program, f, indent=2)
 
 
+def planned_makespan(program: dict) -> float:
+    """
+    Seconds from program start to the end of the last step, following start
+    triggers and durations (resource waits not included). Uses the
+    validator's trigger arithmetic, which reads the current trackId/stepId
+    schema.
+    """
+    from .validate_program import calculate_step_start_time, parse_duration_to_seconds
+
+    end = 0.0
+    for track in program.get("tracks", []):
+        steps = track.get("steps", [])
+        for step in steps:
+            start = calculate_step_start_time(step, steps, program)
+            end = max(end, start + parse_duration_to_seconds(step.get("duration")))
+    return end
+
+
 def plan_program(
     input_file: str,
     output_file: str,
     verbose: bool = False,
     environment_file: Optional[str] = None,
+    workcell: Optional[str] = None,
 ) -> bool:
     """
     Plan and optimize a program schedule.
@@ -979,18 +1000,27 @@ def plan_program(
         output_file: Path to the output program file
         verbose: Whether to print verbose information
         environment_file: Path to the environment file
+        workcell: Workcell file; instrument steps without a duration are
+            estimated from its tools (else from their params, else a default)
 
     Returns:
         True if successful, False otherwise
     """
     try:
         program = load_program_file(input_file)
+        program, estimate_lines = fill_instrument_durations(program, workcell)
+        for line in estimate_lines:
+            print(line)
         environment = None
         if environment_file:
             environment = load_program_file(environment_file)
         planner = ProgramPlanner(program, verbose, environment)
         optimized_program = planner.optimize_schedule()
         save_optimized_program(optimized_program, output_file)
+        print(
+            "Makespan (by start triggers and durations): "
+            f"{planned_makespan(optimized_program):g} s"
+        )
         if verbose:
             print(f"Saved optimized program to {output_file}")
         return True