seq-quince 0.1.1__tar.gz

seq_quince-0.1.1/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `seq-quince` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+### Added
+
+- Initial standalone package, extracted from the `monopy` `src/scheduler` sub-package.
+  - Python imports use `seq_quince`.
+  - Console scripts: `scheduler_runner` and `device_runner`.
+

seq_quince-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to seq_quince
+
+Seq-quince runs configurable device sequences for beamline operation using asyncio,
+EPICS, and kiwi-scan. These guidelines are written for contributors and AI agents.
+
+## Making changes
+
+- Read the relevant implementation, configuration, and tests before editing.
+- Keep changes focused. Preserve unrelated work and avoid incidental refactoring.
+- Preserve public APIs, YAML keys, defaults, and execution order unless the task
+  explicitly changes them. Document intentional behavior changes.
+- Keep Python 3.8 compatibility. For example, use `run_in_executor()` instead of
+  `asyncio.to_thread()`.
+- Comment on context, e.g. reasons or hardware assumptions that the code cannot explain.
+- User output can use unicode symbols from doc/misc/symbols.md for better readability
+
+## Devices and scheduling
+
+- Default device implementations are located in `src/seq_quince/device_concrete/`. Follow
+  `DeviceABC` in `src/seq_quince/device/device_abs.py` and register new device types
+  through `DeviceFactory` in `src/seq_quince/device/factory.py`.
+- New devices are usually tested as external device, register them with DEVICE_CLASSES and 
+  set the SEQ_QUINCE_DEVICE_PATH environment variable.
+- Keep blocking hardware operations out of the asyncio event loop. Preserve
+  cancellation, stop, cleanup, and rollback behavior.
+- Logging: lazy formatting, and restrained output in polling loops.
+
+## Validation
+
+Run:
+
+```bash
+make lint && make test
+```
+
+### Unit tests
+
+Unittests are located in tests.  Use unittest.TestCase (CoreTestCase or DeviceTestCase)
+Do not use real CA.
+
+## Notes
+
+- Code must run on Python 3.8: no `match`, no `list[int]` at runtime, no parenthesized context managers, no `str.removeprefix`.
+  Check both syntax and standard-library availability.
+- Keep CLI layers thin. Put reusable behavior in library functions and reuse existing configuration models, readers, and formatters.
+- Verify the change. Add focused tests. 
+- Validate configuration before the run starts. 

seq_quince-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helmholtz-Zentrum Berlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seq_quince-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+exclude CLAUDE.md AGENTS.md mkvenv.sh .gitignore

seq_quince-0.1.1/Makefile

@@ -0,0 +1,110 @@
+SHELL := /bin/bash
+VERSION ?= 0.1.0
+.DEFAULT_GOAL := help
+
+BASH_COMPLETION_DIR ?= ~/.bash_completion.d
+WITH_VENV = if [ -z "$$VIRTUAL_ENV" ]; then source "$(CURDIR)/mkvenv.sh"; fi
+
+# set COMMIT for tagging
+COMMIT ?= HEAD
+
+# Completion files expected in bash-completion/ (copy them over from monopy/bash-completion).
+SCRIPTS = \
+    scheduler_runner \
+    device_runner
+# ...
+
+SCRIPT_PATHS = $(foreach script,$(SCRIPTS),$(BASH_COMPLETION_DIR)/$(script))
+
+.PHONY: help all install_completion uninstall_completion clean cscope tag lint test build
+
+help: ## Show available development targets
+	@echo "seq_quince development targets"
+	@echo
+	@awk 'BEGIN {FS = ":.*## "} /^[a-zA-Z0-9_.-]+:.*## / { printf "  %-22s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+all: install_completion ## Install bash completion scripts
+
+install_completion: ## Install bash completion files and add source lines to ~/.bashrc
+	@mkdir -p $(BASH_COMPLETION_DIR)
+	@for script in $(SCRIPTS); do \
+		if [ ! -f bash-completion/$$script ]; then echo "Skipping $$script (not found in bash-completion/)"; continue; fi; \
+		cp bash-completion/$$script $(BASH_COMPLETION_DIR)/$$script; \
+		grep -q "$$script" ~/.bashrc || echo "source $(BASH_COMPLETION_DIR)/$$script" >> ~/.bashrc; \
+	done
+	@echo "Bash completion for $(SCRIPTS) installed. Reload your shell to activate."
+
+uninstall_completion: ## Remove installed bash completion files
+	@for script in $(SCRIPTS); do \
+		rm -f $(BASH_COMPLETION_DIR)/$$script; \
+	done
+	@echo "Bash completion for $(SCRIPTS) removed. Edit your .bashrc and remove the source lines."
+
+clean: ## Remove local virtualenv, caches, tags, and egg-info
+	@rm -rf .venv
+	@rm -rf dist build
+	@rm -f tags cscope.files cscope.out
+	@find src -maxdepth 1 -type d -name "*.egg-info" -exec rm -rf {} +
+	@find . -type d -name "__pycache__" -exec rm -r {} +
+
+cscope: ## Build cscope and ctags indexes (optionally includes ../kiwi-scan)
+	find . \( -path ./.venv -o -path ./build -o -path ./dist \) -prune \
+		-o -name "*.py" -print > cscope.files
+	if [ -d ../kiwi-scan ]; then \
+		find ../kiwi-scan/ \
+			\( -path ../kiwi-scan/.venv \
+			-o -path ../kiwi-scan/build \
+			-o -path ../kiwi-scan/dist \) -prune \
+			-o -name "*.py" -print >> cscope.files; \
+	fi
+	cscope -b -i cscope.files
+	ctags -R --languages=Python .
+
+tag: ## Create a version+timestamp git tag from COMMIT
+	@base="$(VERSION)"; \
+	commit="$(COMMIT)"; \
+	if git rev-parse "$$base" >/dev/null 2>&1; then \
+		echo "ERROR: release tag $$base already exists"; \
+		exit 1; \
+	fi; \
+	ts=$$(git show -s --format=%cd --date=format:%Y%m%d%H%M%S "$$commit"); \
+	tag="$$base+$$ts"; \
+	if git rev-parse "$$tag" >/dev/null 2>&1; then \
+		echo "ERROR: tag $$tag already exists"; \
+		exit 1; \
+	fi; \
+	echo "Creating tag $$tag"; \
+	git tag -a "$$tag" "$$commit" -m "Release $$tag"
+
+build: ## Build sdist and wheel into dist/
+	@$(WITH_VENV); \
+	python -m build
+
+lint: ## Run pylint, ruff, and pyright (uses mkvenv.sh when needed)
+	@echo
+	@echo '========================================================================'
+	@echo '  PYLINT'
+	@echo '========================================================================'
+	@$(WITH_VENV); \
+	PYTHONPATH=src pylint src/seq_quince
+	@echo '========================================================================'
+	@echo
+	@echo '========================================================================'
+	@echo '  RUFF'
+	@echo '========================================================================'
+	@$(WITH_VENV); \
+	ruff check src/seq_quince tests/
+	@echo '========================================================================'
+	@echo
+	@echo '========================================================================'
+	@echo '  PYRIGHT'
+	@echo '========================================================================'
+	@$(WITH_VENV); \
+	pyright src/seq_quince
+	@echo '========================================================================'
+	@echo
+	@echo 'Lint complete.'
+
+test: ## Run the test suite (uses mkvenv.sh when needed)
+	@$(WITH_VENV); \
+	PYTHONPATH=src python -m pytest --cov=src/seq_quince --cov-report=term

seq_quince-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.1
+Name: seq-quince
+Version: 0.1.1
+Summary: An asynchronous, YAML-configured device scheduler for EPICS beamlines, built on kiwi-scan.
+Author: Helmholtz-Zentrum Berlin
+Project-URL: Homepage, https://github.com/hz-b/seq-quince
+Project-URL: Repository, https://github.com/hz-b/seq-quince
+Project-URL: Issues, https://github.com/hz-b/seq-quince/issues
+Keywords: epics,scientific,instrumentation,beamline,control-system,scheduler,sequence,data-acquisition,scan,automation,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kiwi-scan>=0.6.1
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jinja2
+Requires-Dist: pyepics>=3.5
+Requires-Dist: ophyd
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: caproto[complete]; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+
+# seq-quince
+
+`seq-quince`: An asynchronous, YAML-configured device scheduler for EPICS beamlines, built on [kiwi-scan](https://github.com/hz-b/kiwi-scan).
+
+Devices (motors, actuators, hexapods, PV sequences, scans, wait conditions, …) are declared in a
+`beamline.yaml`. Named **presets** map devices to target poses. The scheduler turns a preset into a sequence of move
+steps, runs them serially or in parallel groups, and rolls completed steps back to their pre-run snapshot if a step fails.
+
+
+## Overview of Features
+
+-   **YAML + Jinja2 configuration** – `beamline.yaml` and `presets.yaml` are rendered as Jinja2 templates; both `${TOKEN}` and
+    `{{ TOKEN }}` placeholders are supported, as well as `{% include %}` from sibling/parent directories.
+-   **Device abstraction** – every device implements `DeviceABC` (`process`, `snapshot`, `busy`, `stop`, optional capabilities).
+-   **Device factory** – devices are created from config by their `type:` key; custom types can be registered at runtime.
+-   **Custom device extensions** — Load external device modules and packages via SEQ_QUINCE_DEVICE_PATH, with explicit registration through DEVICE_CLASSES.
+-   **Sequences** – presets are converted into `MoveStep` lists with `serial` or `parallel` grouping and barriers.
+-   **Async scheduler** – concurrent execution per group, optional per-step timeouts, best-effort rollback on failure.
+-   **Snapshots** – current device read-backs can be saved as a new preset (`presets.yaml`).
+-   **kiwi-scan integration** – `ScanDevice` runs any kiwi-scan scan type, `ActuatorDevice`/`HexapodDevice` use kiwi-scan actuators.
+
+## Installation
+
+```bash
+pip install seq-quince
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+pip install -e .
+```
+
+
+## Command line tools
+
+| Command | Purpose |
+|---------|---------|
+| `scheduler_runner` | Run a preset (`--config`, `--preset`, `--loop`, `--delay`, `--snapshot`, `--replace`) |
+| `device_runner` | Run one device from a preset; see [device runner](https://github.com/hz-b/seq-quince/blob/master/docs/device_runner.md). |
+
+Example:
+
+```bash
+scheduler_runner --config u171dcm1 --preset branch --replace BL=U171
+```
+
+## Configuration
+
+See [docs/devices.md](https://github.com/hz-b/seq-quince/blob/master/docs/devices.md) and [docs/devices](https://github.com/hz-b/seq-quince/tree/master/docs/devices) for configuration details.
+
+```yaml
+# beamline.yaml
+devices:
+  - name: simulation
+    type: SimDevice
+    delay: 0.1
+  - name: mono_energy
+    type: ActuatorDevice
+    config: { ... }          # kiwi-scan ActuatorConfig
+
+presets:
+  branch:
+    simulation:  { position: 10.0 }
+    mono_energy: { position: 400.0 }
+```
+
+Presets from `presets.yaml` (written by `--snapshot`) override presets of the same name in `beamline.yaml`.
+Unknown preset names raise `ValueError`; an explicitly configured empty preset
+(`empty: {}`) remains valid. Device names must be unique: duplicates are rejected
+before any devices are constructed.
+
+After template rendering, YAML is parsed with `yaml.safe_load()`. Python-specific
+YAML tags are rejected. Normal loading does not print the rendered configuration.
+
+Environment variables used by the code:
+
+| Variable               | Used for                                                        |
+|------------------------|-----------------------------------------------------------------|
+| `SCHEDULER_CONFIG_DIR` | Direct configuration directory; overrides beamline-name lookup. |
+| `SEQ_QUINCE_CONFIG_DIR` | Existing base directory; looks in `<dir>/scheduler_config/beamlines/<config>` when no direct override is set. |
+| `SCAN_CONFIG_DIR`      | kiwi-scan config directory for `ScanDevice`                     |
+| `SCAN_DATA_DIR`        | Output directory for `ScanDevice` scans                         |
+
+See [docs/devices.md](https://github.com/hz-b/seq-quince/blob/master/docs/devices.md) for the built-in device types and their configuration keys.
+
+## Development
+
+```bash
+make help      # list targets
+make lint      # pylint, ruff, pyright
+make test      # pytest
+make build     # sdist + wheel
+make install_completion # install bash completion scripts
+make uninstall_completion # uninstall bash completion scripts
+make clean     # Remove local virtualenv and python generated files
+make cscope    # Build cscope and ctags indexes
+make tag       # create git tag
+```
+## License
+
+MIT – see [LICENSE](https://github.com/hz-b/seq-quince/blob/master/LICENSE).

seq_quince-0.1.1/README.md

@@ -0,0 +1,102 @@
+# seq-quince
+
+`seq-quince`: An asynchronous, YAML-configured device scheduler for EPICS beamlines, built on [kiwi-scan](https://github.com/hz-b/kiwi-scan).
+
+Devices (motors, actuators, hexapods, PV sequences, scans, wait conditions, …) are declared in a
+`beamline.yaml`. Named **presets** map devices to target poses. The scheduler turns a preset into a sequence of move
+steps, runs them serially or in parallel groups, and rolls completed steps back to their pre-run snapshot if a step fails.
+
+
+## Overview of Features
+
+-   **YAML + Jinja2 configuration** – `beamline.yaml` and `presets.yaml` are rendered as Jinja2 templates; both `${TOKEN}` and
+    `{{ TOKEN }}` placeholders are supported, as well as `{% include %}` from sibling/parent directories.
+-   **Device abstraction** – every device implements `DeviceABC` (`process`, `snapshot`, `busy`, `stop`, optional capabilities).
+-   **Device factory** – devices are created from config by their `type:` key; custom types can be registered at runtime.
+-   **Custom device extensions** — Load external device modules and packages via SEQ_QUINCE_DEVICE_PATH, with explicit registration through DEVICE_CLASSES.
+-   **Sequences** – presets are converted into `MoveStep` lists with `serial` or `parallel` grouping and barriers.
+-   **Async scheduler** – concurrent execution per group, optional per-step timeouts, best-effort rollback on failure.
+-   **Snapshots** – current device read-backs can be saved as a new preset (`presets.yaml`).
+-   **kiwi-scan integration** – `ScanDevice` runs any kiwi-scan scan type, `ActuatorDevice`/`HexapodDevice` use kiwi-scan actuators.
+
+## Installation
+
+```bash
+pip install seq-quince
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+pip install -e .
+```
+
+
+## Command line tools
+
+| Command | Purpose |
+|---------|---------|
+| `scheduler_runner` | Run a preset (`--config`, `--preset`, `--loop`, `--delay`, `--snapshot`, `--replace`) |
+| `device_runner` | Run one device from a preset; see [device runner](https://github.com/hz-b/seq-quince/blob/master/docs/device_runner.md). |
+
+Example:
+
+```bash
+scheduler_runner --config u171dcm1 --preset branch --replace BL=U171
+```
+
+## Configuration
+
+See [docs/devices.md](https://github.com/hz-b/seq-quince/blob/master/docs/devices.md) and [docs/devices](https://github.com/hz-b/seq-quince/tree/master/docs/devices) for configuration details.
+
+```yaml
+# beamline.yaml
+devices:
+  - name: simulation
+    type: SimDevice
+    delay: 0.1
+  - name: mono_energy
+    type: ActuatorDevice
+    config: { ... }          # kiwi-scan ActuatorConfig
+
+presets:
+  branch:
+    simulation:  { position: 10.0 }
+    mono_energy: { position: 400.0 }
+```
+
+Presets from `presets.yaml` (written by `--snapshot`) override presets of the same name in `beamline.yaml`.
+Unknown preset names raise `ValueError`; an explicitly configured empty preset
+(`empty: {}`) remains valid. Device names must be unique: duplicates are rejected
+before any devices are constructed.
+
+After template rendering, YAML is parsed with `yaml.safe_load()`. Python-specific
+YAML tags are rejected. Normal loading does not print the rendered configuration.
+
+Environment variables used by the code:
+
+| Variable               | Used for                                                        |
+|------------------------|-----------------------------------------------------------------|
+| `SCHEDULER_CONFIG_DIR` | Direct configuration directory; overrides beamline-name lookup. |
+| `SEQ_QUINCE_CONFIG_DIR` | Existing base directory; looks in `<dir>/scheduler_config/beamlines/<config>` when no direct override is set. |
+| `SCAN_CONFIG_DIR`      | kiwi-scan config directory for `ScanDevice`                     |
+| `SCAN_DATA_DIR`        | Output directory for `ScanDevice` scans                         |
+
+See [docs/devices.md](https://github.com/hz-b/seq-quince/blob/master/docs/devices.md) for the built-in device types and their configuration keys.
+
+## Development
+
+```bash
+make help      # list targets
+make lint      # pylint, ruff, pyright
+make test      # pytest
+make build     # sdist + wheel
+make install_completion # install bash completion scripts
+make uninstall_completion # uninstall bash completion scripts
+make clean     # Remove local virtualenv and python generated files
+make cscope    # Build cscope and ctags indexes
+make tag       # create git tag
+```
+## License
+
+MIT – see [LICENSE](https://github.com/hz-b/seq-quince/blob/master/LICENSE).

seq_quince-0.1.1/bash-completion/device_runner

@@ -0,0 +1,19 @@
+# Bash completion for device_runner.
+_seq_quince_device_runner()
+{
+    local current="${COMP_WORDS[COMP_CWORD]}"
+    local previous="${COMP_WORDS[COMP_CWORD-1]}"
+    COMPREPLY=()
+    case "$previous" in
+        --log-level)
+            mapfile -t COMPREPLY < <(compgen -W '0 1 2 3 4 5' -- "$current")
+            ;;
+        --config|--device|--preset|--replace)
+            ;;
+        *)
+            mapfile -t COMPREPLY < <(compgen -W \
+                '--config --device --preset --replace --log-level --help' -- "$current")
+            ;;
+    esac
+}
+complete -F _seq_quince_device_runner device_runner

seq_quince-0.1.1/bash-completion/scheduler_runner

@@ -0,0 +1,111 @@
+_scheduler_runner_complete()
+{
+    local cur prev opts loop_values preset_values expecting word i
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    opts="--help -h --replace --config --preset --snapshot --loop --delay --log-level"
+    loop_values="infinite inf forever 1 2 5 10 100"
+    preset_values="default test prod dev"
+
+    case "$prev" in
+        --config)
+            # Complete files for config
+            COMPREPLY=( $(compgen -f -- "$cur") )
+            return 0
+            ;;
+        --preset)
+            # Optionally, offer static completions or load dynamically
+            COMPREPLY=( $(compgen -W "${preset_values}" -- "$cur") )
+            return 0
+            ;;
+        --delay)
+            # Numeric value expected
+            COMPREPLY=()
+            return 0
+            ;;
+        --loop)
+            # Optional argument: either suggest loop values or allow another option
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${loop_values}" -- "$cur") )
+            fi
+            return 0
+            ;;
+        --replace)
+            # User is likely entering KEY=VALUE, but allow switching to another option
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "$cur") )
+            else
+                COMPREPLY=()
+            fi
+            return 0
+            ;;
+    esac
+
+    # Track whether we are currently collecting values for an option.
+    expecting=""
+    for ((i=1; i<COMP_CWORD; i++)); do
+        word="${COMP_WORDS[i]}"
+
+        if [[ -n "$expecting" ]]; then
+            case "$expecting" in
+                replace)
+                    if [[ "$word" == -* ]]; then
+                        expecting=""
+                    else
+                        continue
+                    fi
+                    ;;
+                loop)
+                    if [[ "$word" == -* ]]; then
+                        expecting=""
+                    else
+                        expecting=""
+                        continue
+                    fi
+                    ;;
+                config|preset|delay)
+                    expecting=""
+                    continue
+                    ;;
+            esac
+        fi
+
+        case "$word" in
+            --replace)
+                expecting="replace"
+                ;;
+            --config)
+                expecting="config"
+                ;;
+            --preset)
+                expecting="preset"
+                ;;
+            --delay)
+                expecting="delay"
+                ;;
+            --loop)
+                expecting="loop"
+                ;;
+        esac
+    done
+
+    if [[ "$expecting" == "replace" && "$cur" != -* ]]; then
+        COMPREPLY=()
+        return 0
+    fi
+
+    # If current word starts with '-', complete options
+    if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "${opts}" -- "$cur") )
+        return 0
+    fi
+
+    # Default to completing files for last positional argument (if any)
+    COMPREPLY=( $(compgen -f -- "$cur") )
+}
+
+complete -F _scheduler_runner_complete scheduler_runner

seq_quince-0.1.1/docs/device_runner.md

@@ -0,0 +1,84 @@
+# Run one device preset
+
+Run only one configured device's entry from a named preset:
+
+```bash
+device_runner --config my_beamline --device mono --preset alignment
+device_runner --config my_beamline --device mono --preset alignment --replace IOC=TEST
+```
+
+The configuration name and directory resolution match `scheduler_runner`:
+`SCHEDULER_CONFIG_DIR` overrides the directory, otherwise the usual
+`SEQ_QUINCE_CONFIG_DIR` or packaged beamline directory is used. The files are
+`beamline.yaml` and optional `presets.yaml`; saved presets retain their normal
+precedence. `--config` takes the beamline name, as in the existing CLI.
+
+For example, given this `beamline.yaml`:
+
+```yaml
+devices:
+  - name: mono
+    type: SimDevice
+    initial_pose: {position: 1.0}
+    delay: 0
+  - name: slit
+    type: SimDevice
+    initial_pose: {position: 0.0}
+    delay: 0
+presets:
+  alignment:
+    mono: {position: 5.0}
+    slit: {position: 2.0}
+```
+
+The example command constructs `mono` and runs it with `{position: 5.0}`.
+It does not construct `slit`. Selecting a composite device, such as
+`SequenceDevice`, still executes that device's configured internal operations.
+Empty entries (`mono: {}`) are accepted for devices that use configured defaults.
+
+The selection is validated before the factory constructs the device. An
+unknown preset or device, a duplicate device name, a missing device entry,
+or an entry that is not a mapping causes an error. Selected config and pose
+data are copied before use, preserving the loaded manager's configuration.
+
+The existing scheduler executes one step and applies the device's scheduler
+timeout. Device implementations retain their normal processing and error
+cleanup. The scheduler rolls back completed steps; a single failing step
+has no completed step to roll back. Cancelling the async operation attempts
+`device.stop()` before propagating cancellation. A stop failure is logged
+without hiding cancellation. Ctrl-C uses this cancellation path during
+execution and exits with status 130; a repeated interrupt can abort cleanup.
+
+| Option | Meaning |
+| --- | --- |
+| `--config NAME` | Required beamline configuration name |
+| `--device NAME` | Required configured device name |
+| `--preset NAME` | Required named preset containing that device |
+| `--replace KEY=VALUE ...` | Standard configuration replacements |
+| `--log-level 0-5` | Same logging control as `scheduler_runner` |
+
+Exit codes: 0 for success, 1 for configuration or execution failure, 2 for
+argument errors, and 130 for interruption. Execution runs once.
+
+## Python use
+
+```python
+from seq_quince.runner import run_device
+
+run_device("my_beamline", "mono", "alignment", replacements={"IOC": "TEST"})
+```
+
+For an application that already owns an event loop:
+
+```python
+from seq_quince.runner import create_config_manager, run_device_preset
+
+async def align_mono():
+    manager = create_config_manager("my_beamline", {"IOC": "TEST"})
+    await run_device_preset(manager, "mono", "alignment")
+```
+
+`run_device()` owns an event loop; use the async helper inside a running loop.
+Device construction happens inside the execution loop, including on Python 3.8.
+`create_device_step()` is also available for applications building their own
+scheduler steps; call it inside the loop used to execute the device.