labcode 0.0.1__tar.gz → 0.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.0.1
+Version: 0.1.1
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -20,9 +20,9 @@ Classifier: Typing :: Typed
 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-validate>=0.1.2
+Requires-Dist: ofplang-schedule>=0.1.3
+Requires-Dist: ofplang-run>=0.1.9
 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.1}/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.1/SPECIFICATIONS.md

@@ -0,0 +1,188 @@
+# 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. Object identity — the reserved `_id` view key
+
+labcode gives every Object a stable, value-layer identity so it can be traced across
+steps and in the observation document. The identity lives in the Object's **view** under
+the reserved key **`_id`** (a `String`). This is a dialect feature layered on portable
+v0: the workflow the user writes carries no `_id`; `lc run` injects and mints it.
+
+### 4.1 Type rewrite
+
+Before running, `lc run` rewrites the workflow in memory: it adds `_id: { type: String }`
+to the `view` of **every `domain: object` type** (creating `view` if the type had none).
+`_id` is an ordinary legal v0 view field (a leading-underscore identifier, not reserved
+in core, and a primitive `String`), so the rewritten document validates and schedules
+unchanged, and the runner's closed-shape view conformance treats `_id` as a normal
+declared field. labcode runs this rewritten document directly (no temp file:
+`ofplang.run.run_workflow` accepts an in-memory document).
+
+**Reserved (error).** A user type that itself declares a `_id` view field is rejected at
+the dialect front door — labcode owns `_id`, and silently clobbering the field would be
+worse than a clear error.
+
+### 4.2 Where an id comes from
+
+An Object's `_id` is set at its two points of origin, then **carried** everywhere else —
+`objects.map` and transport copy the whole view, so `_id` propagates for free:
+
+- **`objects.create`** — a newly created Object's `_id` is minted when the operation
+  produces it (in the backend's output fill). A device script need not know about `_id`:
+  it returns only what it computes, and the fill supplies `_id` (like any other unset
+  output, §1.2).
+- **run boundary** — a whole-workflow Object *input* enters at the boundary; `lc run`
+  mints its `_id` (filling any other declared view field with a typed default so the
+  seeded value conforms), **unless the boundary already carries one** — so a result
+  boundary fed back in round-trips its ids.
+- **`objects.map`** — a mapped Object output carries its input's `_id` unchanged
+  (identity preserved), even if a §22.2-strict script returned the port explicitly.
+
+### 4.3 Reproducibility
+
+Ids come from a swappable generator (`labcode.idgen.IdGenerator`). The default
+(`SeededUuid4Generator`) mints **reproducible** uuid4-shaped ids from a seed and a
+*provenance key* — the node instance + output port for a create, the port name for a
+boundary input — **not** draw order. So the same workflow yields the same ids on every
+run, and the wall-clock backend's jittering completion order cannot change them (which is
+what keeps checked-in example observations stable). A real run wanting globally-unique
+ids per physical Object swaps in `RealUuid4Generator` (via
+`labcode_backend_factory(id_generator=...)`).
+
+> The provenance key is the runner's node-instance identity + port. Today each create
+> node runs once, so node-path + port is unique; when dynamic control flow (e.g.
+> `do_while`) is added, that node-instance identity must include the iteration index so
+> ids stay unique and reproducible.
+
+## 5. 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.1/examples/README.md

@@ -0,0 +1,85 @@
+# labcode examples
+
+## `plate_line` — an Object-bearing line, driven by environment scripts
+
+A `Plate` flows down a four-station line, a `Tube` is dispensed into it, and a
+measurement is read off it:
+
+```
+         (in) tube ──────────────┐
+                                  ▼
+load ──[move]──> dispense ──[move]──> read ──[move]──> store
+                     │                   │
+                (out) tube           (out) od
+```
+
+- [`plate_line.workflow.yaml`](plate_line.workflow.yaml) is **portable ofplang v0** — it
+  says only *what* happens. The whole workflow takes one `Tube` in and passes the *same*
+  Tube back out, alongside the Pure Data measurement `od`. `dispense` and `read` are
+  **Object-bearing**: their Objects go in and the *same* Objects come out (`objects.map` —
+  identity preserved). The Plate is created inside the workflow by `load`; the Tube enters
+  at the run boundary.
+- [`plate_line.boundary.yaml`](plate_line.boundary.yaml) is the **run boundary** (dev-notes
+  D28). It supplies the `Tube` input — an Object, so it names a `spot`: a standalone tube
+  `rack` slot bound to no process, where the Tube starts and returns (`Tube` has no view
+  fields, so no `view`). The arm carries it to the dispenser and back. It also names the
+  outputs `od` and `tube`, whose produced values are echoed in the result boundary.
+- [`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, `dispense` dispenses the Tube into the Plate (both Objects are carried through by
+  `objects.map`, so its script returns nothing), `read` measures `od` (the Plate is
+  carried, 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 \
+  --boundary examples/plate_line.boundary.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`.
+
+### Produce the outputs
+
+[`render_plate_line.py`](render_plate_line.py) drives the same run on the labcode backend
+and writes its artifacts under [`outputs/`](outputs/):
+
+```sh
+python examples/render_plate_line.py
+```
+
+- [`outputs/plate_line.plan.yaml`](outputs/plate_line.plan.yaml) — the **final execution
+  schedule** (the §6/§7 status document: every activity, `completed`).
+- [`outputs/plate_line.observation.yaml`](outputs/plate_line.observation.yaml) — the
+  **observation document** (D38): each completed activity's I/O views, as `lc run
+  --observation-out` would stream it.
+- [`outputs/plate_line.svg`](outputs/plate_line.svg) — a **Gantt chart** of that schedule
+  (device view), drawn by the scheduler's visualizer. (The ofplang toolchain renders
+  SVG/HTML; open it in a browser, or convert to PNG with any SVG rasterizer.)
+- [`outputs/plate_line.boundary.yaml`](outputs/plate_line.boundary.yaml) — the **result
+  boundary**, echoing the produced `od` and the returned `tube` (as `--boundary-out`
+  writes it).
+
+Because the labcode backend runs each op out-of-process on a wall clock, the exact times
+(and makespan) may vary slightly between runs; the sequence and produced values do not.
+
+Every Object's view carries a reserved **`_id`** — labcode's implicit, value-layer Object
+identity (see [`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §4). In the observation you can
+follow the *same* Plate (one `_id`) from `load` through `dispense`/`read` to `store`, and
+the Tube's `_id` round-trips from the input boundary to the output. The ids are
+reproducible (a seeded, provenance-keyed generator), so these outputs are stable to
+re-generate.
+
+> 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.1/examples/outputs/plate_line.boundary.yaml

@@ -0,0 +1,13 @@
+boundary:
+  inputs:
+    tube:
+      spot: rack.slot
+      view:
+        _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+  outputs:
+    od:
+      view: 0.42
+    tube:
+      spot: rack.slot
+      view:
+        _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5

labcode-0.1.1/examples/outputs/plate_line.observation.yaml

@@ -0,0 +1,202 @@
+schema: ofplang-observation/v0
+time:
+  unit: second
+interface:
+  inputs:
+    tube: rack.slot
+  outputs:
+    tube: rack.slot
+---
+kind: transport
+from_spot: rack.slot
+to_spot: dispenser.tube
+transporter: arm
+arc:
+  from:
+    node: []
+    port: tube
+  to:
+    node:
+    - Dispense
+    port: tube
+start: 0
+end: 1
+moved:
+  view:
+    _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: processing
+process: load
+mode: m0
+node:
+- Load
+devices:
+- loader
+output_spots:
+  plate: loader.stage
+start: 0
+end: 1
+inputs: {}
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: transport
+from_spot: loader.stage
+to_spot: dispenser.deck
+transporter: arm
+arc:
+  from:
+    node:
+    - Load
+    port: plate
+  to:
+    node:
+    - Dispense
+    port: plate
+start: 1
+end: 3
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: processing
+process: dispense
+mode: m0
+node:
+- Dispense
+devices:
+- dispenser
+input_spots:
+  plate: dispenser.deck
+  tube: dispenser.tube
+output_spots:
+  plate: dispenser.deck
+  tube: dispenser.tube
+start: 3
+end: 5
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  tube:
+    view:
+      _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  tube:
+    view:
+      _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: transport
+from_spot: dispenser.deck
+to_spot: reader.stage
+transporter: arm
+arc:
+  from:
+    node:
+    - Dispense
+    port: plate
+  to:
+    node:
+    - Read
+    port: plate
+start: 5
+end: 7
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: transport
+from_spot: dispenser.tube
+to_spot: rack.slot
+transporter: arm
+arc:
+  from:
+    node:
+    - Dispense
+    port: tube
+  to:
+    node: []
+    port: tube
+start: 7
+end: 9
+moved:
+  view:
+    _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: processing
+process: read
+mode: m0
+node:
+- Read
+devices:
+- reader
+input_spots:
+  plate: reader.stage
+output_spots:
+  plate: reader.stage
+start: 7
+end: 10
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  od:
+    view: 0.42
+---
+kind: transport
+from_spot: reader.stage
+to_spot: sealer.stage
+transporter: arm
+arc:
+  from:
+    node:
+    - Read
+    port: plate
+  to:
+    node:
+    - Store
+    port: plate
+start: 10
+end: 12
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: processing
+process: store
+mode: m0
+node:
+- Store
+devices:
+- sealer
+input_spots:
+  plate: sealer.stage
+start: 12
+end: 14
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+outputs: {}
+---
+final: true
+now: 14
+outcome: completed