labcode 0.0.1__tar.gz → 0.1.0__tar.gz

{labcode-0.0.1 → labcode-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.0.1
+Version: 0.1.0
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -21,8 +21,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ofplang-validate>=0.1.0
-Requires-Dist: ofplang-schedule>=0.1.0
-Requires-Dist: ofplang-run>=0.1.0
+Requires-Dist: ofplang-schedule>=0.1.2
+Requires-Dist: ofplang-run>=0.1.6
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev
@@ -43,14 +43,31 @@ ofplang toolchain and exposes it under a single command:
 ```sh
 lc validate ...   # check a workflow is well-formed portable v0
 lc schedule ...   # compute a schedule for a workflow
-lc run ...        # execute a workflow (rolling-horizon runner / simulator)
+lc run ...        # execute a workflow on the labcode backend
 ```
 
 labcode is where a site-specific dialect and a custom runner (real lab hardware)
-are developed on top of the ofplang toolchain. At this version `lc` is a thin
-dispatcher that forwards each subcommand to the ofplang siblings **unchanged**;
-the dialect and custom-runner behavior will land in later versions, replacing
-individual subcommands behind the same interface.
+are developed on top of the ofplang toolchain. `lc validate` and `lc schedule`
+forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's own
+runner**: it drives the workflow on the labcode backend, running each device
+operation's script — supplied in the environment as an `x-labcode.script` extension
+on a process mode — out-of-process on a wall clock, so a long-running real operation
+never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+`x-labcode` extension.
+
+```yaml
+# in the execution environment: how a (process, mode) is carried out
+processes:
+  measure_od:
+    modes:
+      - id: v0
+        duration: 45
+        x-labcode:
+          script:
+            language: python
+            code: |
+              return {"od": read_plate(plate)}
+```
 
 ## Install
 

{labcode-0.0.1 → labcode-0.1.0}/README.md

@@ -10,14 +10,31 @@ ofplang toolchain and exposes it under a single command:
 ```sh
 lc validate ...   # check a workflow is well-formed portable v0
 lc schedule ...   # compute a schedule for a workflow
-lc run ...        # execute a workflow (rolling-horizon runner / simulator)
+lc run ...        # execute a workflow on the labcode backend
 ```
 
 labcode is where a site-specific dialect and a custom runner (real lab hardware)
-are developed on top of the ofplang toolchain. At this version `lc` is a thin
-dispatcher that forwards each subcommand to the ofplang siblings **unchanged**;
-the dialect and custom-runner behavior will land in later versions, replacing
-individual subcommands behind the same interface.
+are developed on top of the ofplang toolchain. `lc validate` and `lc schedule`
+forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's own
+runner**: it drives the workflow on the labcode backend, running each device
+operation's script — supplied in the environment as an `x-labcode.script` extension
+on a process mode — out-of-process on a wall clock, so a long-running real operation
+never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+`x-labcode` extension.
+
+```yaml
+# in the execution environment: how a (process, mode) is carried out
+processes:
+  measure_od:
+    modes:
+      - id: v0
+        duration: 45
+        x-labcode:
+          script:
+            language: python
+            code: |
+              return {"od": read_plate(plate)}
+```
 
 ## Install
 

labcode-0.1.0/SPECIFICATIONS.md

@@ -0,0 +1,135 @@
+# labcode dialect specification
+
+labcode is a dialect of the Object-Flow Programming Language (ofplang). A labcode
+workflow **is** a portable v0 ofplang workflow; the dialect lives entirely in the
+**execution environment** (§5), as an `x-labcode` extension that says *how* each device
+operation is physically carried out. `lc run` drives the workflow on the labcode backend
+(`ofplang.run.SubprocessBackend`), sourcing each operation's script from `x-labcode` and
+running it out-of-process on a wall clock.
+
+This document is the reference for the `x-labcode` extension; `labcode.dialect` is its
+conformance validator, run at the `lc run` front door.
+
+## 1. `x-labcode` on a process mode (P5)
+
+An environment process mode (§5) may carry an `x-labcode` mapping. In this version it
+holds a single key, `script`: the Python that carries out that `(process, mode)`.
+
+```yaml
+processes:
+  measure_od:
+    modes:
+      - id: v0
+        devices: [reader]
+        duration: 45          # the scheduler's estimate; real time is the script's own
+        x-labcode:
+          script:
+            language: python  # the only supported language
+            code: |
+              return {"od": read_plate(plate)}
+```
+
+`x-labcode` is tolerated (and ignored) by `ofplang-schedule` (>= 0.1.2): the environment
+still validates and schedules as plain v0. Only labcode interprets it.
+
+### 1.1 Shape
+
+- `x-labcode` MUST be a mapping.
+- `x-labcode.script`, if present, MUST be a mapping with:
+  - `language`: MUST be `python`.
+  - `code`: MUST be a string (an implementation-provided Python function body).
+
+### 1.2 Calling convention (process)
+
+The script runs as the body of a function whose parameters are the operation's **input
+port names**, each bound to that port's view value (Pure Data or an Object's view record)
+— as in a v0 §22 `python_script_processes` script. External `import` is allowed; there is
+no sandbox.
+
+**Partial outputs.** Unlike v0 §22.2 (which requires the script to return *every* output
+exactly), a labcode process script `return`s only the outputs it **computes** — a subset.
+The backend fills the rest:
+
+- an Object output declared in `objects.map` is **carried from its input** (the same
+  Object, its view unchanged) — so a pass-through need not restate it;
+- any other unset output gets a **typed default** for its type.
+
+The script's returned values override these. Each returned value must conform to its port's
+type, and **returning a name that is not a declared output is an error** (this catches a
+typo'd output name). A §22.2-strict script — one that returns every output explicitly —
+works unchanged.
+
+So for `read` (input `plate`, outputs `plate` via `objects.map` + `od`), all three are
+equivalent to returning `{"plate": plate, "od": 0.42}`… except the defaulted forms:
+
+```python
+return {"plate": plate, "od": 0.42}   # explicit
+return {"od": 0.42}                    # plate carried by objects.map
+return {}                              # plate carried; od defaults to 0.0
+```
+
+### 1.3 `x-labcode` on a transport route
+
+An environment `transports[]` route may carry an `x-labcode` with a `script`: the Python
+that physically carries out that move (e.g. commanding a robot arm). Same shape as §1.1
+(`language: python`, string `code`).
+
+```yaml
+transports:
+  - transporter: arm
+    from: reader.stage
+    to: sealer.stage
+    duration: 3
+    x-labcode:
+      script:
+        language: python
+        code: |
+          grip = "gentle" if (view or {}).get("fragile") else "firm"
+          move_plate(from_spot, to_spot, grip=grip)
+```
+
+**Calling convention (transport).** The script runs as a function body with these locals:
+`from_spot`, `to_spot`, `transporter` (the physical route), and `view` — the view value of
+the moved Object. `view` is **best-effort and MAY be `None`** (the runner resolves it from
+the producing arc; when it cannot, it is `None`), so a script that reads it should tolerate
+`None`. A transport script is **side-effect only**: its return value is ignored and no
+output is verified. Success is "it ran without raising"; an exception is a graceful failure
+(the move ends `failed`, no material is moved — the run stops).
+
+A route with no `x-labcode.script` runs as a plain timed move — the runner's material
+bookkeeping only, with no device command (a warned no-op for a real move, from != to).
+
+## 2. Code source resolution and exclusivity
+
+For a dispatched `(process, mode)`, labcode resolves the code to run in this order:
+
+1. the mode's `x-labcode.script.code` (2 — the labcode device script), else
+2. the workflow process's own `script.code` (1 — a v0 §22 script process), else
+3. none — the operation runs as a **typed-default no-op** (its outputs are typed
+   defaults; a device not yet scripted).
+
+**Exclusivity (error).** A process MUST NOT carry both a workflow `script` (1) and an env
+`x-labcode.script` (2) on any of its modes; that is ambiguous and is rejected.
+
+**Typed-default reachability (warning).** A process with neither (1) nor (2) on any mode
+will run as a typed-default no-op. This is allowed — convenient while mocking a device —
+but `lc run` warns about it, so an unimplemented device is not silently a no-op.
+
+## 3. Execution model
+
+Each dispatched operation runs in its own child process (real, wall-clock-paced); the
+runner discovers completion by polling, so a multi-minute computation never blocks it.
+The advisory `duration` is the scheduler's estimate; the real duration is the script's.
+A script error (an exception, a wrong/ missing output name, a non-conformant value) is a
+graceful runtime failure (§22.2): the operation ends `failed` and the run stops.
+
+Cadence: the effective poll period is `poll_interval × seconds_per_tick`. labcode defaults
+`seconds_per_tick` to ~20 s (so a real op is polled at an observable cadence, not
+sub-second, which would flood the replan loop); `lc run --seconds-per-tick/--speed/
+--poll-interval/--margin` override it.
+
+## 4. Not yet in this version (roadmap)
+
+- **Device / transporter `x-labcode`** — connection and availability information
+  (e.g. SiLA2 address) consolidated on `devices[]` / `transporters[]`, used for a
+  connect/command/disconnect wrapper and for `down_devices` availability probing.

labcode-0.1.0/examples/README.md

@@ -0,0 +1,40 @@
+# labcode examples
+
+## `plate_line` — an Object-bearing line, driven by environment scripts
+
+A `Plate` flows down a three-station line and a measurement is read off it:
+
+```
+load ──[move]──> read ──[move]──> store
+```
+
+- [`plate_line.workflow.yaml`](plate_line.workflow.yaml) is **portable ofplang v0** — it
+  says only *what* happens. `read` is **Object-bearing**: the Plate goes in and the *same*
+  Plate comes out (`objects.map` — identity preserved), together with a Pure Data
+  measurement `od`. The Plate is created inside the workflow, so no run boundary is needed.
+- [`plate_line.env.yaml`](plate_line.env.yaml) is the **labcode environment** — it says
+  *how* each step is carried out, as an `x-labcode.script` (see [`../SPECIFICATIONS.md`](../SPECIFICATIONS.md)).
+  **Every process mode and every transport route carries a script**: `load` makes the
+  Plate, `read` measures `od` (the Plate is carried through automatically by `objects.map`,
+  so the script returns only what it computes — labcode's *partial outputs*, see the spec),
+  `store` takes it; the transport scripts perform the move and may read the moved Plate's
+  `view` (its barcode).
+
+labcode runs each script **out-of-process** on a wall clock, discovering completion by
+polling — so a real, slow device operation never blocks the runner.
+
+### Run it
+
+```sh
+lc run examples/plate_line.workflow.yaml --env examples/plate_line.env.yaml --seconds-per-tick 0.2
+```
+
+`--seconds-per-tick` sets the real seconds per environment time tick; it defaults to a
+coarse value suited to real hardware, so a small value here keeps the demo quick. The run
+completes with every activity `completed`; the produced measurement (`od = 0.42`) can be
+written out with `--boundary-out result.yaml`.
+
+> The scripts here are mocks (they just return values / reference their locals). Replace a
+> script's body with real device calls — e.g. `robot.move(from_spot, to_spot)` in a
+> transport, or an instrument read in `read` — to drive real hardware; the code may
+> `import` anything the host Python can.

labcode-0.1.0/examples/plate_line.env.yaml

@@ -0,0 +1,86 @@
+# The labcode environment for plate_line.workflow.yaml: it says *how* each step and
+# each move is carried out, as an `x-labcode.script` (labcode runs these out-of-process).
+# The workflow stays portable v0 (`ofplang-schedule` just tolerates the x- keys).
+#
+# Every process mode AND every transport route carries a script here. The process
+# scripts are Object-bearing: `load` returns the new Plate's view; `read` returns the
+# *same* plate it was given plus the measured `od`; `store` takes it (side-effect only).
+# The transport scripts move the plate and may read its view (the barcode).
+time:
+  unit: second
+
+devices:
+  - { id: loader, spots: [stage] }
+  - { id: reader, spots: [stage] }
+  - { id: sealer, spots: [stage] }
+
+transporters:
+  - { id: arm }
+
+transports:
+  - transporter: arm
+    from: loader.stage
+    to: reader.stage
+    duration: 2
+    x-labcode:
+      script:
+        language: python
+        code: |
+          # from_spot / to_spot / transporter are the physical route; `view` is the
+          # moved Plate's view (barcode). Side-effect only -- no return.
+          barcode = (view or {}).get("barcode")
+          # a real arm would move the plate here; e.g. robot.move(from_spot, to_spot)
+
+  - transporter: arm
+    from: reader.stage
+    to: sealer.stage
+    duration: 2
+    x-labcode:
+      script:
+        language: python
+        code: |
+          barcode = (view or {}).get("barcode")
+
+processes:
+
+  load:
+    modes:
+      - devices: [loader]
+        duration: 3
+        output_spots: { plate: loader.stage }
+        x-labcode:
+          script:
+            language: python
+            code: |
+              # Create the Plate's view (its observable data). Returns the one output port.
+              return {"plate": {"barcode": "P001"}}
+
+  read:
+    modes:
+      - devices: [reader]
+        duration: 3
+        input_spots:  { plate: reader.stage }
+        output_spots: { plate: reader.stage }   # same spot: the plate is read in place
+        x-labcode:
+          script:
+            language: python
+            code: |
+              # Measure the optical density. `plate` is the incoming Plate's view; it is
+              # carried through automatically (objects.map), so the script returns only
+              # what it computes -- `od` (labcode's partial outputs, SPECIFICATIONS.md §1.2).
+              return {"od": 0.42}
+
+  store:
+    modes:
+      - devices: [sealer]
+        duration: 3
+        input_spots: { plate: sealer.stage }
+        x-labcode:
+          script:
+            language: python
+            code: |
+              # `plate` is the incoming Plate's view; storing is side-effect only.
+              return {}
+
+objective:
+  kind: makespan

labcode-0.1.0/examples/plate_line.workflow.yaml

@@ -0,0 +1,71 @@
+# A small labcode example: a Plate flows down a three-station line and a measurement
+# is read off it. Every step's *how* -- both the device operations and the moves --
+# is supplied by the environment as an `x-labcode.script` (see plate_line.env.yaml);
+# this file is portable ofplang v0 (it says only *what* happens).
+#
+#   load ──[move]──> read ──[move]──> store
+#
+# `read` is Object-bearing: it takes the Plate in and passes the *same* Plate out
+# (objects.map -- identity preserved), while also producing a Pure Data measurement
+# `od`. So an Object and a data value flow together (cf. examples/plate_chain in
+# ofplang-run). The Plate is created inside the workflow, so no run boundary is needed.
+spec_version: "0.0"
+
+types:
+  Plate:
+    domain: object
+    view:
+      barcode: { type: String }
+
+processes:
+
+  # A source device: put a fresh Plate on the line.
+  load:
+    kind: atomic
+    outputs:
+      plate: { type: Plate, phase: data }
+    objects:
+      create: [outputs.plate]
+
+  # Object-bearing measurement: the Plate goes in and the *same* Plate comes out
+  # (objects.map), and its optical density `od` is measured as Pure Data.
+  read:
+    kind: atomic
+    inputs:
+      plate: { type: Plate, phase: data }
+    outputs:
+      plate: { type: Plate, phase: data }   # same name as the input: the same plate
+      od:    { type: Float, phase: data }
+    objects:
+      map:
+        outputs.plate: inputs.plate
+
+  # A sink device: take the Plate off the line.
+  store:
+    kind: atomic
+    inputs:
+      plate: { type: Plate, phase: data }
+    objects:
+      consume: [inputs.plate]
+
+  main:
+    kind: composite
+    inputs: {}
+    outputs:
+      od: { type: Float, phase: data }
+    body:
+      nodes:
+        - id: Load
+          process: load
+        - id: Read
+          process: read
+          state:
+            plate: { from: Load.plate }    # Object arc (a move is scheduled for it)
+        - id: Store
+          process: store
+          state:
+            plate: { from: Read.plate }
+      returns:
+        od: { from: Read.od }
+
+entry: main

labcode-0.1.0/labcode/_child.py

@@ -0,0 +1,62 @@
+"""labcode's out-of-process child harness (the partial-output dialect).
+
+Like ``ofplang.run.simulator._child``, but labcode process scripts follow the labcode
+dialect's **partial** output convention (SPECIFICATIONS.md §1.2): a script returns only the
+outputs it computes, and the backend fills the rest -- carrying an Object output through
+``objects.map`` (identity preserved) and defaulting the others. So this child does **no**
+output verification; it just returns the script's raw result mapping. The merge, the
+conformance check, and the rejection of any *extra* (undeclared) output name all happen in
+`labcode.backend.LabcodeBackend`.
+
+A transport script is side-effect only (its return is ignored). Protocol (JSON on stdin,
+outcome to ``result_path``) is identical to the upstream child; only the process branch
+differs (raw, unverified, vs verified-exactly)."""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+
+from ofplang.run.simulator import DeviceComputationError, run_python_script
+
+
+def main() -> int:
+    try:
+        job = json.load(sys.stdin)
+        result_path = job["result_path"]
+    except Exception as exc:  # cannot even read the job -- a harness-level failure
+        print(f"lc child: cannot read job: {exc}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+
+    try:
+        raw = run_python_script(job.get("code") or "", job.get("inputs") or {})
+        if job.get("kind") == "transport":
+            payload: dict = {"outputs": {}}  # side-effect only; the return is ignored
+        elif not isinstance(raw, dict):
+            payload = {"error": {
+                "code": "script_output_names",
+                "message": f"script process {job.get('process')!r} returned "
+                           f"{type(raw).__name__}, not a mapping",
+            }}
+        else:
+            # A partial mapping is allowed: the backend merges and verifies it (§1.2).
+            payload = {"outputs": raw}
+    except DeviceComputationError as exc:
+        payload = {"error": {"code": exc.code, "message": str(exc)}}
+    except Exception as exc:  # a script error run_python_script did not wrap
+        payload = {"error": {"code": "script_error", "message": f"{type(exc).__name__}: {exc}"}}
+
+    try:
+        with open(result_path, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+    except Exception as exc:  # cannot deliver the result -- a harness-level failure
+        print(f"lc child: cannot write result: {exc}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - module entry
+    raise SystemExit(main())