Skip to content

[ESSREDUCE] Minimal implementation-independent workflow specifications - #690

Open
SimonHeybrock wants to merge 1 commit into
mainfrom
653-minimal-workflow-spec
Open

[ESSREDUCE] Minimal implementation-independent workflow specifications#690
SimonHeybrock wants to merge 1 commit into
mainfrom
653-minimal-workflow-spec

Conversation

@SimonHeybrock

Copy link
Copy Markdown
Member

Fresh counter-proposal for #653, as announced in the review on #689 — I propose closing that PR in favor of this one.

The core difference to #689: the spec is pure interface. No workflow factory, no sciline keys, no use_workflow_default — nothing that presumes a particular implementation or execution location. The same spec must make sense whether the workflow runs as a local sciline pipeline, behind a web service, or as a cluster job; compute binding is a parallel mechanism, deliberately out of scope here.

Main decisions (full rationale in ADR 0001, included in this PR):

  • One pydantic params model per workflow instead of per-sciline-key Parameter entries. Enables cross-parameter validation and JSON Schema for free. The graph-derived "select outputs → see relevant params" feature is dropped, not ported: it treats output selection as workflow slicing, which only the sciline implementation can express.
  • title and description mandatory; identity is name + version — no instrument, no WorkflowId class. Scoping and global uniqueness are the enumerating context's responsibility.
  • Two forms with a one-way projection: WorkflowSpec (in-process, holds the params model class, full validation) and SerializedWorkflowSpec (plain data, params as JSON Schema, JSON-round-trippable). No inverse — validators don't survive JSON Schema, so authoritative validation stays with the process owning the model class; remote consumers validate optimistically. This matches the announcement-as-contract design from Rethink workflow registration: move schema ownership to domain packages esslivedata#889.
  • Outputs declared structurally via ArraySpec (dims, unit, coord units) — plain data, no scipp, replacing sc.DataArray default-factory templates. Scalars with units are the 0-d case.
  • Scipp-free shared parameter vocabulary (unit enums, range/edges models with cross-field validation); scipp conversions quarantined in spec.conversions. Value defaults are set by workflow authors at the use site, not by the vocabulary.
  • No registry: enumeration mechanisms are out of scope, any works against the same spec type.
  • Explicit goal: ess.livedata WorkflowSpec eventually inherits from this, gated on its planned ArraySpec migration; base field names are a strict subset of livedata's for that reason.

Adds pydantic>=2.5 as an essreduce dependency (already present in the locked CI environments). The existing ess.reduce.parameter/workflow/widgets machinery is superseded but untouched; removal is a later hard break — no one depends on it currently.

🤖 Generated with Claude Code

WorkflowSpec describes a workflow's user-facing interface (identity,
title/description, one pydantic params model, structural output
descriptions) without factories, sciline keys, or registries, so generic
UIs can be generated from it regardless of where compute happens.
serialize() projects one-way onto SerializedWorkflowSpec (params as JSON
Schema) for cross-process consumers; authoritative validation stays with
the process owning the model class.

Includes a scipp-free shared parameter vocabulary (unit enums,
range/edges models with cross-field validation) with scipp conversions
quarantined in spec.conversions, and ADR 0001 recording the design and
its rationale (see #653, scipp/esslivedata#889).

Adds pydantic as an essreduce dependency. The existing
ess.reduce.parameter/workflow machinery is superseded but untouched;
removal is a later hard break.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@SimonHeybrock

Copy link
Copy Markdown
Member Author

Reminder of the extensions the essapps architecture sketch (scipp/essapps, branch architecture-sketch, docs/developer/architecture.md, decision D13) needs from this spec, so they are not lost while the PR is open. A prototype of all of them lives in ess.apps.spec on that branch.

  • Outputs as a typed model. outputs becomes a pydantic model class in the same vocabulary as params, with title and description as field metadata and optional fields allowed. Chaining is then a type check between an output field and a parameter field. As proposed, non-array outputs have no type, which breaks "outputs can be inputs" for exactly the values that most often feed the next workflow (beam centre, direct beam).
  • A data-reference field type. A field marked with a kind (raw NeXus file, opaque file, scipp array) holds a reference to another record's output at submission and the materialized value (path or scipp object) inside the workflow. Arrays are constrained by the same ArraySpec outputs use. A field may be a union of a literal and a reference. The prototype validates this without importing scipp in the spec layer.
  • Collections on both sides. list[...] and dict[str, ...] of one declared type as parameters and as outputs; a reference may name one element of a collection output by key.
  • ArraySpec.binned, so consumers know event data that must not be plotted directly.
  • Two small spec fields: cheap: frozenset[str], the parameters a warm workflow can change without recomputing the expensive part (what lets a UI offer a slider), and an optional code_revision.
  • Entry points split by role: specs in one group, workflow factories in another under the same name, so a service can load and validate every spec without importing workflow code. This matches the ADR's "the backend never imports a factory" and the esslivedata split.

None of this changes the ADR's core: pure interface, one params model, one-way serialization, identity by name and version.

SimonHeybrock added a commit to scipp/essapps that referenced this pull request Sep 8, 2026
The spike on D3 and D6 the architecture sketch calls for, built as a real
package under packages/essapps (import ess.apps) so it can move into the
scipp/ess monorepo unchanged.

What is in: the spec vocabulary with data-reference fields and collections
(a local copy of the shape in scipp/ess#690 plus the D13 extensions, to be
replaced once that merges); run requests and records; a SQLite record store
with a single-writer lock and the registry of disk copies; a data store with
a private memory cache and a scipp HDF5 disk tier; the binding registry;
one runner for both execution shapes; a session launcher (outputs stay in
memory) and a subprocess launcher (outputs to disk with a completion marker,
reconciled by the backend); the backend with three-layer validation, atomic
group submit with pending outputs, failure and cancellation propagation,
explicit recompute, stand-in resolution for local files, and slots as a
label plus a latest query; views as plain arrays; the Python client
interface; and example workflows for load, rebin, and map-combine.

Repo tooling copied from the monorepo: ruff config, pre-commit, the test
file name check.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
SimonHeybrock added a commit to scipp/essapps that referenced this pull request Sep 8, 2026
ArrayValue, and Array(spec) with a structure constraint, accept a reference
or an in-process data object and reject plain data, without the spec module
naming scipp. Data-reference fields are now found through optionals, unions,
and collections, so an optional array input is materialized like any other.
as_ref is the one place that decides whether a plain value is a reference;
walk_refs, group rewriting, literal inlining, and materialization all use
it, and ref_fields lists the fields of a model that may hold one.

This is the vocabulary feedback for scipp/ess#690 in code form.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

essreduce Issues for essreduce.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant