f

Automatically generated by python-semantic-release

.github/scripts/aggregate_benchmarks.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Aggregate and merge benchmark JSON files.
+
+The workflow runs the same benchmark suite on multiple independent runners.
+This script reads every JSON file produced by those attempts, normalizes the
+contained benchmark values, and writes a compact mapping JSON where each value is
+the median across attempts. It can also merge independent hyperfine JSON files
+from one runner into a single hyperfine-style JSON file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+from pathlib import Path
+from typing import Any
+
+from compare_benchmarks import Benchmark, extract_benchmarks
+
+
+def collect_benchmarks(paths: list[Path]) -> dict[str, list[Benchmark]]:
+    """Collect benchmarks from multiple JSON files.
+
+    Args:
+        paths (list[Path]): Paths to hyperfine, pytest-benchmark, or compact
+            mapping JSON files.
+
+    Returns:
+        dict[str, list[Benchmark]]: Benchmarks grouped by benchmark name.
+    """
+
+    collected: dict[str, list[Benchmark]] = {}
+    for path in paths:
+        for name, benchmark in extract_benchmarks(path).items():
+            collected.setdefault(name, []).append(benchmark)
+    return collected
+
+
+def aggregate(collected: dict[str, list[Benchmark]]) -> dict[str, dict[str, object]]:
+    """Aggregate grouped benchmarks using the median value.
+
+    Args:
+        collected (dict[str, list[Benchmark]]): Benchmarks grouped by benchmark
+            name.
+
+    Returns:
+        dict[str, dict[str, object]]: Compact mapping JSON data. Each benchmark
+        contains ``value``, ``unit``, ``metric``, ``attempts``, and
+        ``attempt_values``.
+    """
+
+    aggregated: dict[str, dict[str, object]] = {}
+    for name, benchmarks in sorted(collected.items()):
+        values = [benchmark.value for benchmark in benchmarks]
+        unit = next((benchmark.unit for benchmark in benchmarks if benchmark.unit), "")
+        metric = next((benchmark.metric for benchmark in benchmarks if benchmark.metric), "value")
+        aggregated[name] = {
+            "value": statistics.median(values),
+            "unit": unit,
+            "metric": f"median-of-attempt-{metric}",
+            "attempts": len(values),
+            "attempt_values": values,
+        }
+    return aggregated
+
+
+def merge_hyperfine_results(paths: list[Path]) -> dict[str, Any]:
+    """Merge hyperfine result files.
+
+    Args:
+        paths (list[Path]): Hyperfine JSON files to merge.
+
+    Returns:
+        dict[str, Any]: Hyperfine-style JSON object containing all result rows.
+
+    Raises:
+        ValueError: If any file has no hyperfine ``results`` list.
+    """
+
+    merged: dict[str, Any] = {"results": []}
+    for path in paths:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        results = data.get("results", []) if isinstance(data, dict) else None
+        if not isinstance(results, list):
+            raise ValueError(f"{path} has no hyperfine results list")
+        merged["results"].extend(results)
+    return merged
+
+
+def main_from_paths(input_dir: Path, output: Path) -> int:
+    """Aggregate all JSON files in a directory and write the result.
+
+    Args:
+        input_dir (Path): Directory containing benchmark JSON files.
+        output (Path): Path where the aggregate JSON should be written.
+
+    Returns:
+        int: Always ``0`` on success.
+
+    Raises:
+        ValueError: If no JSON files are found in ``input_dir``.
+    """
+
+    paths = sorted(input_dir.rglob("*.json"))
+    if not paths:
+        raise ValueError(f"No benchmark JSON files found in {input_dir}")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(
+        json.dumps(aggregate(collect_benchmarks(paths)), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return 0
+
+
+def merge_from_paths(input_dir: Path, output: Path) -> int:
+    """Merge all hyperfine JSON files in a directory and write the result.
+
+    Args:
+        input_dir (Path): Directory containing hyperfine JSON files.
+        output (Path): Path where the merged JSON should be written.
+
+    Returns:
+        int: Always ``0`` on success.
+
+    Raises:
+        ValueError: If no JSON files are found in ``input_dir``.
+    """
+
+    paths = sorted(input_dir.glob("*.json"))
+    if not paths:
+        raise ValueError(f"No hyperfine JSON files found in {input_dir}")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(
+        json.dumps(merge_hyperfine_results(paths), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return 0
+
+
+def main() -> int:
+    """Run the benchmark aggregation command line interface.
+
+    Returns:
+        int: Always ``0`` on success.
+    """
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--mode",
+        choices=("aggregate", "merge-hyperfine"),
+        default="aggregate",
+        help="Operation to perform.",
+    )
+    parser.add_argument("--input-dir", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+    if args.mode == "merge-hyperfine":
+        return merge_from_paths(input_dir=args.input_dir, output=args.output)
+    return main_from_paths(input_dir=args.input_dir, output=args.output)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/compare_benchmarks.py

@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""Compare benchmark JSON files and write a GitHub Actions summary.
+
+The script supports JSON emitted by hyperfine, JSON emitted by pytest-benchmark,
+and a compact mapping format generated by ``aggregate_benchmarks.py``. Timing
+formats prefer median values and fall back to mean values when median values are
+not present.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Benchmark:
+    """Normalized benchmark result.
+
+    Attributes:
+        name (str): Stable benchmark name used to match baseline and current results.
+        value (float): Numeric benchmark value used for comparison.
+        unit (str): Display unit for the value, for example ``"s"``.
+        metric (str): Source metric name, for example ``"median"`` or ``"mean"``.
+    """
+
+    name: str
+    value: float
+    unit: str
+    metric: str = "value"
+
+
+@dataclass(frozen=True)
+class Comparison:
+    """Comparison between one baseline benchmark and one current benchmark.
+
+    Attributes:
+        name (str): Benchmark name.
+        baseline (float): Baseline benchmark value.
+        current (float): Current benchmark value.
+        delta_percent (float): Percent change from baseline to current.
+        unit (str): Display unit for both values.
+        metric (str): Current result metric used for comparison.
+        regressed (bool): Whether the change exceeds the configured threshold in
+            the worse direction.
+        improved (bool): Whether the change exceeds the configured threshold in
+            the better direction.
+    """
+
+    name: str
+    baseline: float
+    current: float
+    delta_percent: float
+    unit: str
+    metric: str
+    regressed: bool
+    improved: bool
+
+
+def _read_json(path: Path) -> Any:
+    """Read JSON data from a file.
+
+    Args:
+        path (Path): Path to the JSON file.
+
+    Returns:
+        Any: Parsed JSON value.
+    """
+
+    with path.open("r", encoding="utf-8") as stream:
+        return json.load(stream)
+
+
+def _as_float(value: Any) -> float | None:
+    """Convert a value to a finite float.
+
+    Args:
+        value (Any): Value to convert.
+
+    Returns:
+        float | None: Converted finite float, or ``None`` if conversion fails.
+    """
+
+    try:
+        result = float(value)
+    except (TypeError, ValueError):
+        return None
+    if math.isfinite(result):
+        return result
+    return None
+
+
+def _extract_hyperfine(data: dict[str, Any]) -> dict[str, Benchmark]:
+    """Extract normalized benchmarks from hyperfine JSON.
+
+    Args:
+        data (dict[str, Any]): Parsed hyperfine JSON object.
+
+    Returns:
+        dict[str, Benchmark]: Benchmarks keyed by command name.
+    """
+
+    benchmarks: dict[str, Benchmark] = {}
+    for result in data.get("results", []):
+        if not isinstance(result, dict):
+            continue
+        name = str(result.get("command") or result.get("name") or "").strip()
+        metric = "median"
+        value = _as_float(result.get(metric))
+        if value is None:
+            metric = "mean"
+            value = _as_float(result.get(metric))
+        if name and value is not None:
+            benchmarks[name] = Benchmark(name=name, value=value, unit="s", metric=metric)
+    return benchmarks
+
+
+def _extract_pytest_benchmark(data: dict[str, Any]) -> dict[str, Benchmark]:
+    """Extract normalized benchmarks from pytest-benchmark JSON.
+
+    Args:
+        data (dict[str, Any]): Parsed pytest-benchmark JSON object.
+
+    Returns:
+        dict[str, Benchmark]: Benchmarks keyed by full benchmark name.
+    """
+
+    benchmarks: dict[str, Benchmark] = {}
+    for benchmark in data.get("benchmarks", []):
+        if not isinstance(benchmark, dict):
+            continue
+
+        name = str(benchmark.get("fullname") or benchmark.get("name") or "").strip()
+        stats = benchmark.get("stats", {})
+        value = None
+        metric = "median"
+        if isinstance(stats, dict):
+            value = _as_float(stats.get(metric))
+            if value is None:
+                metric = "mean"
+                value = _as_float(stats.get(metric))
+        if name and value is not None:
+            benchmarks[name] = Benchmark(name=name, value=value, unit="s", metric=metric)
+    return benchmarks
+
+
+def _extract_simple_mapping(data: dict[str, Any]) -> dict[str, Benchmark]:
+    """Extract normalized benchmarks from a compact mapping JSON object.
+
+    Args:
+        data (dict[str, Any]): Parsed mapping where each benchmark is either a
+            raw number or an object containing ``value``, ``unit``, and ``metric``.
+
+    Returns:
+        dict[str, Benchmark]: Benchmarks keyed by mapping key.
+    """
+
+    benchmarks: dict[str, Benchmark] = {}
+
+    for name, raw_value in data.items():
+        if name in {"version", "context", "commit", "timestamp"}:
+            continue
+
+        value = _as_float(raw_value)
+        unit = ""
+        metric = "value"
+        if value is None and isinstance(raw_value, dict):
+            value = _as_float(raw_value.get("value"))
+            unit = str(raw_value.get("unit") or "")
+            metric = str(raw_value.get("metric") or "value")
+
+        if value is not None:
+            benchmarks[str(name)] = Benchmark(name=str(name), value=value, unit=unit, metric=metric)
+
+    return benchmarks
+
+
+def extract_benchmarks(path: Path) -> dict[str, Benchmark]:
+    """Extract normalized benchmarks from a supported JSON file.
+
+    Args:
+        path (Path): Path to a hyperfine, pytest-benchmark, or compact mapping
+            JSON file.
+
+    Returns:
+        dict[str, Benchmark]: Normalized benchmarks keyed by name.
+
+    Raises:
+        ValueError: If the JSON root is not an object or no supported benchmark
+            entries can be extracted.
+    """
+
+    data = _read_json(path)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+
+    extractors = (_extract_hyperfine, _extract_pytest_benchmark, _extract_simple_mapping)
+    for extractor in extractors:
+        benchmarks = extractor(data)
+        if benchmarks:
+            return benchmarks
+
+    raise ValueError(f"No supported benchmark entries found in {path}")
+
+
+def compare_benchmarks(
+    baseline: dict[str, Benchmark],
+    current: dict[str, Benchmark],
+    threshold_percent: float,
+    higher_is_better: bool,
+) -> tuple[list[Comparison], list[str], list[str]]:
+    """Compare baseline benchmarks with current benchmarks.
+
+    Args:
+        baseline (dict[str, Benchmark]): Baseline benchmarks keyed by name.
+        current (dict[str, Benchmark]): Current benchmarks keyed by name.
+        threshold_percent (float): Regression threshold in percent.
+        higher_is_better (bool): If ``True``, lower current values are treated as
+            regressions. If ``False``, higher current values are treated as
+            regressions.
+
+    Returns:
+        tuple[list[Comparison], list[str], list[str]]: Comparisons for common
+        benchmark names, names missing from current results, and names newly
+        present in current results.
+    """
+
+    comparisons: list[Comparison] = []
+    missing_in_current: list[str] = []
+    new_in_current: list[str] = []
+
+    for name, baseline_benchmark in sorted(baseline.items()):
+        current_benchmark = current.get(name)
+        if current_benchmark is None:
+            missing_in_current.append(name)
+            continue
+
+        if baseline_benchmark.value == 0:
+            delta_percent = 0.0
+        else:
+            delta_percent = (
+                (current_benchmark.value - baseline_benchmark.value)
+                / abs(baseline_benchmark.value)
+                * 100
+            )
+
+        if higher_is_better:
+            regressed = delta_percent <= -threshold_percent
+            improved = delta_percent >= threshold_percent
+        else:
+            regressed = delta_percent >= threshold_percent
+            improved = delta_percent <= -threshold_percent
+
+        comparisons.append(
+            Comparison(
+                name=name,
+                baseline=baseline_benchmark.value,
+                current=current_benchmark.value,
+                delta_percent=delta_percent,
+                unit=current_benchmark.unit or baseline_benchmark.unit,
+                metric=current_benchmark.metric,
+                regressed=regressed,
+                improved=improved,
+            )
+        )
+
+    for name in sorted(set(current) - set(baseline)):
+        new_in_current.append(name)
+
+    return comparisons, missing_in_current, new_in_current
+
+
+def _format_value(value: float, unit: str) -> str:
+    """Format a benchmark value for Markdown output.
+
+    Args:
+        value (float): Numeric benchmark value.
+        unit (str): Display unit.
+
+    Returns:
+        str: Formatted value with optional unit suffix.
+    """
+
+    suffix = f" {unit}" if unit else ""
+    return f"{value:.6g}{suffix}"
+
+
+def _format_status(comparison: Comparison) -> str:
+    """Format a comparison status for Markdown output."""
+
+    if comparison.regressed:
+        return ":red_circle: regressed"
+    if comparison.improved:
+        return ":green_circle: improved"
+    return "ok"
+
+
+def write_summary(
+    path: Path,
+    comparisons: list[Comparison],
+    missing_in_current: list[str],
+    new_in_current: list[str],
+    threshold_percent: float,
+    higher_is_better: bool,
+) -> None:
+    """Write a Markdown benchmark comparison summary.
+
+    Args:
+        path (Path): Path where the summary should be written.
+        comparisons (list[Comparison]): Comparison rows for matching benchmarks.
+        missing_in_current (list[str]): Baseline benchmark names missing from the
+            current result.
+        new_in_current (list[str]): Current benchmark names not present in the
+            baseline result.
+        threshold_percent (float): Regression threshold in percent.
+        higher_is_better (bool): Whether higher benchmark values are considered
+            better.
+    """
+
+    regressions = [comparison for comparison in comparisons if comparison.regressed]
+    improvements = [comparison for comparison in comparisons if comparison.improved]
+    direction = "higher is better" if higher_is_better else "lower is better"
+    sorted_comparisons = sorted(comparisons, key=lambda comparison: comparison.name)
+
+    lines = [
+        "<!-- bw-benchmark-comment -->",
+        "## Benchmark comparison",
+        "",
+        f"Threshold: {threshold_percent:g}% ({direction}).",
+        f"Result: {len(regressions)} regression(s), {len(improvements)} improvement(s) beyond threshold.",
+    ]
+    lines.append("")
+
+    if regressions:
+        lines.extend(
+            [
+                f"{len(regressions)} benchmark(s) regressed beyond the configured threshold.",
+                "",
+                "| Benchmark | Baseline | Current | Change |",
+                "| --- | ---: | ---: | ---: |",
+            ]
+        )
+        for comparison in regressions:
+            lines.append(
+                "| "
+                f"{comparison.name} | "
+                f"{_format_value(comparison.baseline, comparison.unit)} | "
+                f"{_format_value(comparison.current, comparison.unit)} | "
+                f"{comparison.delta_percent:+.2f}% |"
+            )
+    else:
+        lines.append("No benchmark regression exceeded the configured threshold.")
+
+    lines.append("")
+
+    if improvements:
+        lines.extend(
+            [
+                f"{len(improvements)} benchmark(s) improved beyond the configured threshold.",
+                "",
+                "| Benchmark | Baseline | Current | Change |",
+                "| --- | ---: | ---: | ---: |",
+            ]
+        )
+        for comparison in improvements:
+            lines.append(
+                "| "
+                f"{comparison.name} | "
+                f"{_format_value(comparison.baseline, comparison.unit)} | "
+                f"{_format_value(comparison.current, comparison.unit)} | "
+                f"{comparison.delta_percent:+.2f}% |"
+            )
+    else:
+        lines.append("No benchmark improvement exceeded the configured threshold.")
+
+    if sorted_comparisons:
+        lines.extend(
+            [
+                "",
+                "<details>",
+                "<summary>All benchmark results</summary>",
+                "",
+                "| Benchmark | Baseline | Current | Change | Status |",
+                "| --- | ---: | ---: | ---: | --- |",
+            ]
+        )
+        for comparison in sorted_comparisons:
+            lines.append(
+                "| "
+                f"{comparison.name} | "
+                f"{_format_value(comparison.baseline, comparison.unit)} | "
+                f"{_format_value(comparison.current, comparison.unit)} | "
+                f"{comparison.delta_percent:+.2f}% | "
+                f"{_format_status(comparison)} |"
+            )
+        lines.extend(["", "</details>"])
+
+    if missing_in_current:
+        lines.extend(["", "Missing benchmarks in the current run:"])
+        lines.extend(f"- `{name}`" for name in missing_in_current)
+
+    if new_in_current:
+        lines.extend(["", "New benchmarks in the current run:"])
+        lines.extend(f"- `{name}`" for name in new_in_current)
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    """Run the benchmark comparison command line interface.
+
+    Returns:
+        int: ``1`` when a regression exceeds the threshold, otherwise ``0``.
+    """
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--baseline", required=True, type=Path)
+    parser.add_argument("--current", required=True, type=Path)
+    parser.add_argument("--summary", required=True, type=Path)
+    parser.add_argument("--threshold-percent", required=True, type=float)
+    parser.add_argument("--higher-is-better", action="store_true")
+    args = parser.parse_args()
+
+    baseline = extract_benchmarks(args.baseline)
+    current = extract_benchmarks(args.current)
+    comparisons, missing_in_current, new_in_current = compare_benchmarks(
+        baseline=baseline,
+        current=current,
+        threshold_percent=args.threshold_percent,
+        higher_is_better=args.higher_is_better,
+    )
+
+    write_summary(
+        path=args.summary,
+        comparisons=comparisons,
+        missing_in_current=missing_in_current,
+        new_in_current=new_in_current,
+        threshold_percent=args.threshold_percent,
+        higher_is_better=args.higher_is_better,
+    )
+
+    return 1 if any(comparison.regressed for comparison in comparisons) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/run_benchmarks.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p benchmark-results
+benchmark_json="${BENCHMARK_JSON:-benchmark-results/current.json}"
+benchmark_root="$(dirname "$benchmark_json")"
+hyperfine_benchmark_dir="${BENCHMARK_HYPERFINE_DIR:-tests/benchmarks/hyperfine}"
+pytest_benchmark_dirs="${BENCHMARK_PYTEST_DIRS:-${BENCHMARK_PYTEST_DIR:-}}"
+benchmark_work_dir="$benchmark_root/raw-results"
+hyperfine_json_dir="$benchmark_work_dir/hyperfine"
+pytest_json="$benchmark_work_dir/pytest.json"
+
+shopt -s nullglob
+benchmark_scripts=()
+benchmark_scripts=("$hyperfine_benchmark_dir"/benchmark_*.sh)
+shopt -u nullglob
+
+pytest_dirs=()
+for pytest_benchmark_dir in $pytest_benchmark_dirs; do
+  if [ -d "$pytest_benchmark_dir" ]; then
+    pytest_dirs+=("$pytest_benchmark_dir")
+  else
+    echo "Pytest benchmark directory not found: $pytest_benchmark_dir" >&2
+    exit 1
+  fi
+done
+
+if [ "${#benchmark_scripts[@]}" -eq 0 ] && [ "${#pytest_dirs[@]}" -eq 0 ]; then
+  echo "No benchmark scripts or pytest benchmarks found" >&2
+  exit 1
+fi
+
+echo "Benchmark Python: $(command -v python)"
+python -c 'import sys; print(sys.version)'
+
+rm -rf "$benchmark_work_dir"
+mkdir -p "$hyperfine_json_dir"
+
+if [ "${#benchmark_scripts[@]}" -gt 0 ]; then
+  for benchmark_script in "${benchmark_scripts[@]}"; do
+    title="$(sed -n 's/^# BENCHMARK_TITLE:[[:space:]]*//p' "$benchmark_script" | head -n 1)"
+    if [ -z "$title" ]; then
+      title="$(basename "$benchmark_script" .sh)"
+    fi
+    benchmark_name="$(basename "$benchmark_script" .sh)"
+    benchmark_result_json="$hyperfine_json_dir/$benchmark_name.json"
+    echo "Preflight benchmark script: $benchmark_script"
+    bash "$benchmark_script"
+
+    hyperfine \
+      --show-output \
+      --warmup 1 \
+      --runs 5 \
+      --command-name "$title" \
+      --export-json "$benchmark_result_json" \
+      "bash $(printf "%q" "$benchmark_script")"
+  done
+fi
+
+if [ "${#pytest_dirs[@]}" -gt 0 ]; then
+  pytest \
+    -q "${pytest_dirs[@]}" \
+    --benchmark-only \
+    --benchmark-json "$pytest_json"
+fi
+
+python .github/scripts/aggregate_benchmarks.py \
+  --input-dir "$benchmark_work_dir" \
+  --output "$benchmark_json"

.github/scripts/run_with_bec_servers.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Run a command with BEC e2e services available."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+import bec_lib
+from bec_ipython_client import BECIPythonClient
+from bec_lib.redis_connector import RedisConnector
+from bec_lib.service_config import ServiceConfig, ServiceConfigModel
+from redis import Redis
+
+
+def _wait_for_redis(host: str, port: int) -> None:
+    client = Redis(host=host, port=port)
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        try:
+            if client.ping():
+                return
+        except Exception:
+            time.sleep(0.1)
+    raise RuntimeError(f"Redis did not start on {host}:{port}")
+
+
+def _start_redis(files_path: Path, host: str, port: int) -> subprocess.Popen:
+    redis_server = shutil.which("redis-server")
+    if redis_server is None:
+        raise RuntimeError("redis-server executable not found")
+
+    return subprocess.Popen(
+        [
+            redis_server,
+            "--bind",
+            host,
+            "--port",
+            str(port),
+            "--save",
+            "",
+            "--appendonly",
+            "no",
+            "--dir",
+            str(files_path),
+        ]
+    )
+
+
+def _write_configs(files_path: Path, host: str, port: int) -> Path:
+    test_config = files_path / "test_config.yaml"
+    services_config = files_path / "services_config.yaml"
+
+    bec_lib_path = Path(bec_lib.__file__).resolve().parent
+    shutil.copyfile(bec_lib_path / "tests" / "test_config.yaml", test_config)
+
+    service_config = ServiceConfigModel(
+        redis={"host": host, "port": port}, file_writer={"base_path": str(files_path)}
+    )
+    services_config.write_text(service_config.model_dump_json(indent=4), encoding="utf-8")
+    return services_config
+
+
+def _load_demo_config(services_config: Path) -> None:
+    bec = BECIPythonClient(ServiceConfig(services_config), RedisConnector, forced=True)
+    bec.start()
+    try:
+        bec.config.load_demo_config()
+    finally:
+        bec.shutdown()
+        bec._client._reset_singleton()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+
+    if args.command[:1] == ["--"]:
+        args.command = args.command[1:]
+    if not args.command:
+        raise ValueError("No command provided")
+
+    host = "127.0.0.1"
+    port = 6379
+
+    with tempfile.TemporaryDirectory(prefix="bec-benchmark-") as tmp:
+        files_path = Path(tmp)
+        services_config = _write_configs(files_path, host, port)
+        redis_process = _start_redis(files_path, host, port)
+        processes = None
+        service_handler = None
+        try:
+            _wait_for_redis(host, port)
+
+            from bec_server.bec_server_utils.service_handler import ServiceHandler
+
+            service_handler = ServiceHandler(
+                bec_path=files_path, config_path=services_config, interface="subprocess"
+            )
+            processes = service_handler.start()
+            _load_demo_config(services_config)
+
+            env = os.environ.copy()
+            return subprocess.run(args.command, env=env, check=False).returncode
+        finally:
+            if service_handler is not None and processes is not None:
+                service_handler.stop(processes)
+            redis_process.terminate()
+            try:
+                redis_process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                redis_process.kill()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/workflows/benchmark.yml

@@ -0,0 +1,239 @@
+name: BW Benchmarks
+
+on: [workflow_call]
+
+permissions:
+  contents: read
+
+env:
+  BENCHMARK_JSON: benchmark-results/current.json
+  BENCHMARK_BASELINE_JSON: gh-pages-benchmark-data/benchmarks/latest.json
+  BENCHMARK_SUMMARY: benchmark-results/summary.md
+  BENCHMARK_COMMAND: "bash .github/scripts/run_benchmarks.sh"
+  BENCHMARK_THRESHOLD_PERCENT: 10
+  BENCHMARK_HIGHER_IS_BETTER: false
+
+jobs:
+  benchmark_attempt:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash -el {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        attempt: [1, 2, 3]
+
+    env:
+      BENCHMARK_JSON: benchmark-results/current-${{ matrix.attempt }}.json
+      BEC_CORE_BRANCH: main
+      OPHYD_DEVICES_BRANCH: main
+      PLUGIN_REPO_BRANCH: main
+      BENCHMARK_PYTEST_DIRS: tests/unit_tests/benchmarks
+      QTWEBENGINE_DISABLE_SANDBOX: 1
+      QT_QPA_PLATFORM: "offscreen"
+
+    steps:
+      - name: Checkout BEC Widgets
+        uses: actions/checkout@v4
+        with:
+          repository: bec-project/bec_widgets
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Set up Conda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          auto-activate-base: true
+          python-version: "3.11"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgl1 libegl1 x11-utils libxkbcommon-x11-0 libdbus-1-3 xvfb
+          sudo apt-get -y install libnss3 libxdamage1 libasound2t64 libatomic1 libxcursor1
+          sudo apt-get -y install ttyd hyperfine redis-server
+
+      - name: Install full e2e environment
+        run: |
+          echo -e "\033[35;1m Using branch $BEC_CORE_BRANCH of BEC CORE \033[0;m";
+          git clone --branch "$BEC_CORE_BRANCH" https://github.com/bec-project/bec.git
+          echo -e "\033[35;1m Using branch $OPHYD_DEVICES_BRANCH of OPHYD_DEVICES \033[0;m";
+          git clone --branch "$OPHYD_DEVICES_BRANCH" https://github.com/bec-project/ophyd_devices.git
+          export OHPYD_DEVICES_PATH=$PWD/ophyd_devices
+          echo -e "\033[35;1m Using branch $PLUGIN_REPO_BRANCH of bec_testing_plugin \033[0;m";
+          git clone --branch "$PLUGIN_REPO_BRANCH" https://github.com/bec-project/bec_testing_plugin.git
+          cd ./bec
+          conda create -q -n test-environment python=3.11
+          conda activate test-environment
+          source ./bin/install_bec_dev.sh -t
+          cd ../
+          python -m pip install -e ./ophyd_devices -e .[dev,pyside6] -e ./bec_testing_plugin pytest-benchmark
+
+          mkdir -p "$(dirname "$BENCHMARK_JSON")"
+          python .github/scripts/run_with_bec_servers.py -- bash -lc "$BENCHMARK_COMMAND"
+          test -s "$BENCHMARK_JSON"
+
+      - name: Upload benchmark artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: bw-benchmark-json-${{ matrix.attempt }}
+          path: ${{ env.BENCHMARK_JSON }}
+
+  benchmark:
+    needs: [benchmark_attempt]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout BEC Widgets
+        uses: actions/checkout@v4
+        with:
+          repository: bec-project/bec_widgets
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Download benchmark attempts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: bw-benchmark-json-*
+          path: benchmark-results/attempts
+          merge-multiple: true
+
+      - name: Aggregate benchmark attempts
+        run: |
+          python .github/scripts/aggregate_benchmarks.py \
+            --input-dir benchmark-results/attempts \
+            --output "$BENCHMARK_JSON"
+
+      - name: Upload aggregate benchmark artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: bw-benchmark-json
+          path: ${{ env.BENCHMARK_JSON }}
+
+      - name: Fetch gh-pages benchmark data
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages; then
+            git clone --depth=1 --branch gh-pages "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git" gh-pages-benchmark-data
+          else
+            mkdir -p gh-pages-benchmark-data
+          fi
+
+      - name: Compare with latest gh-pages benchmark
+        id: compare
+        continue-on-error: true
+        run: |
+          if [ ! -s "$BENCHMARK_BASELINE_JSON" ]; then
+            mkdir -p "$(dirname "$BENCHMARK_SUMMARY")"
+            {
+              echo "<!-- bw-benchmark-comment -->"
+              echo "## Benchmark comparison"
+              echo
+              echo "No benchmark baseline was found on gh-pages."
+            } > "$BENCHMARK_SUMMARY"
+            exit 0
+          fi
+
+          args=(
+            --baseline "$BENCHMARK_BASELINE_JSON"
+            --current "$BENCHMARK_JSON"
+            --summary "$BENCHMARK_SUMMARY"
+            --threshold-percent "$BENCHMARK_THRESHOLD_PERCENT"
+          )
+
+          if [ "$BENCHMARK_HIGHER_IS_BETTER" = "true" ]; then
+            args+=(--higher-is-better)
+          fi
+
+          set +e
+          python .github/scripts/compare_benchmarks.py "${args[@]}"
+          status=$?
+          set -e
+
+          if [ ! -s "$BENCHMARK_SUMMARY" ]; then
+            mkdir -p "$(dirname "$BENCHMARK_SUMMARY")"
+            {
+              echo "<!-- bw-benchmark-comment -->"
+              echo "## Benchmark comparison"
+              echo
+              echo "Benchmark comparison failed before writing a summary."
+            } > "$BENCHMARK_SUMMARY"
+          fi
+
+          exit "$status"
+
+      - name: Find existing benchmark PR comment
+        if: github.event_name == 'pull_request'
+        id: fc
+        uses: peter-evans/find-comment@v3
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: github-actions[bot]
+          body-includes: "<!-- bw-benchmark-comment -->"
+
+      - name: Create or update benchmark PR comment
+        if: github.event_name == 'pull_request'
+        uses: peter-evans/create-or-update-comment@v5
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          body-path: ${{ env.BENCHMARK_SUMMARY }}
+          edit-mode: replace
+
+      - name: Fail on benchmark regression
+        if: github.event_name == 'pull_request' && steps.compare.outcome == 'failure'
+        run: exit 1
+
+  publish:
+    needs: [benchmark]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout BEC Widgets
+        uses: actions/checkout@v4
+        with:
+          repository: bec-project/bec_widgets
+          ref: ${{ github.sha }}
+
+      - name: Download aggregate benchmark artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: bw-benchmark-json
+          path: .
+
+      - name: Prepare gh-pages for publishing
+        run: |
+          # Clean up any existing worktree/directory
+          if [ -d gh-pages-benchmark-data ]; then
+            git worktree remove gh-pages-benchmark-data --force || rm -rf gh-pages-benchmark-data
+          fi
+
+          if git ls-remote --exit-code --heads origin gh-pages; then
+            git fetch --depth=1 origin gh-pages
+            git worktree add gh-pages-benchmark-data FETCH_HEAD
+          else
+            git worktree add --detach gh-pages-benchmark-data
+            git -C gh-pages-benchmark-data checkout --orphan gh-pages
+            git -C gh-pages-benchmark-data rm -rf .
+          fi
+
+      - name: Publish benchmark data to gh-pages
+        working-directory: gh-pages-benchmark-data
+        run: |
+          mkdir -p benchmarks/history
+          cp "../$BENCHMARK_JSON" benchmarks/latest.json
+          cp "../$BENCHMARK_JSON" "benchmarks/history/${GITHUB_SHA}.json"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add benchmarks/latest.json "benchmarks/history/${GITHUB_SHA}.json"
+          git commit -m "Update BW benchmark data for ${GITHUB_SHA}" || exit 0
+          git push origin HEAD:gh-pages

.github/workflows/ci.yml

@@ -1,19 +1,19 @@
 name: Full CI
-on: 
+on:
   push:
   pull_request:
   workflow_dispatch:
     inputs:
       BEC_WIDGETS_BRANCH:
-        description: 'Branch of BEC Widgets to install'
+        description: "Branch of BEC Widgets to install"
         required: false
         type: string
       BEC_CORE_BRANCH:
-        description: 'Branch of BEC Core to install'
+        description: "Branch of BEC Core to install"
         required: false
         type: string
       OPHYD_DEVICES_BRANCH:
-        description: 'Branch of Ophyd Devices to install'
+        description: "Branch of Ophyd Devices to install"
         required: false
         type: string
 
@@ -23,6 +23,7 @@ concurrency:
 
 permissions:
   pull-requests: write
+  contents: read
 
 jobs:
   check_pr_status:
@@ -33,6 +34,15 @@ jobs:
     if: needs.check_pr_status.outputs.branch-pr == ''
     uses: ./.github/workflows/formatter.yml
 
+  benchmark:
+    needs: [check_pr_status]
+    if: needs.check_pr_status.outputs.branch-pr == ''
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    uses: ./.github/workflows/benchmark.yml
+
   unit-test:
     needs: [check_pr_status, formatter]
     if: needs.check_pr_status.outputs.branch-pr == ''
@@ -69,9 +79,9 @@ jobs:
     uses: ./.github/workflows/child_repos.yml
     with:
       BEC_CORE_BRANCH: ${{ inputs.BEC_CORE_BRANCH || 'main' }}
-      OPHYD_DEVICES_BRANCH: ${{ inputs.OPHYD_DEVICES_BRANCH || 'main'}} 
+      OPHYD_DEVICES_BRANCH: ${{ inputs.OPHYD_DEVICES_BRANCH || 'main'}}
       BEC_WIDGETS_BRANCH: ${{ inputs.BEC_WIDGETS_BRANCH || github.head_ref || github.sha }}
-  
+
   plugin_repos:
     needs: [check_pr_status, formatter]
     if: needs.check_pr_status.outputs.branch-pr == ''
@@ -81,4 +91,4 @@ jobs:
       BEC_WIDGETS_BRANCH: ${{ inputs.BEC_WIDGETS_BRANCH || github.head_ref || github.sha }}
 
     secrets:
-      GH_READ_TOKEN: ${{ secrets.GH_READ_TOKEN }}
+      GH_READ_TOKEN: ${{ secrets.GH_READ_TOKEN }}

.github/workflows/pytest-matrix.yml

@@ -1,25 +1,25 @@
 name: Run Pytest with different Python versions
-on: 
+on:
   workflow_call:
     inputs:
       pr_number:
-        description: 'Pull request number'
+        description: "Pull request number"
         required: false
         type: number
       BEC_CORE_BRANCH:
-        description: 'Branch of BEC Core to install'
+        description: "Branch of BEC Core to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
       OPHYD_DEVICES_BRANCH:
-        description: 'Branch of Ophyd Devices to install'
+        description: "Branch of Ophyd Devices to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
       BEC_WIDGETS_BRANCH:
-        description: 'Branch of BEC Widgets to install'
+        description: "Branch of BEC Widgets to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
 
 jobs:
@@ -30,15 +30,14 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
 
     env:
-      BEC_WIDGETS_BRANCH: main  # Set the branch you want for bec_widgets
-      BEC_CORE_BRANCH: main        # Set the branch you want for bec
-      OPHYD_DEVICES_BRANCH: main   # Set the branch you want for ophyd_devices
+      BEC_WIDGETS_BRANCH: main # Set the branch you want for bec_widgets
+      BEC_CORE_BRANCH: main # Set the branch you want for bec
+      OPHYD_DEVICES_BRANCH: main # Set the branch you want for ophyd_devices
       PROJECT_PATH: ${{ github.repository }}
       QTWEBENGINE_DISABLE_SANDBOX: 1
       QT_QPA_PLATFORM: "offscreen"
 
     steps:
-
       - name: Checkout BEC Widgets
         uses: actions/checkout@v4
         with:
@@ -56,4 +55,4 @@ jobs:
       - name: Run Pytest
         run: |
           pip install pytest pytest-random-order
-          pytest -v --junitxml=report.xml --random-order ./tests/unit_tests
+          pytest -v --junitxml=report.xml --random-order --ignore=tests/unit_tests/benchmarks ./tests/unit_tests

.github/workflows/pytest.yml

@@ -1,32 +1,30 @@
 name: Run Pytest with Coverage
-on: 
+on:
   workflow_call:
     inputs:
       pr_number:
-        description: 'Pull request number'
+        description: "Pull request number"
         required: false
         type: number
       BEC_CORE_BRANCH:
-        description: 'Branch of BEC Core to install'
+        description: "Branch of BEC Core to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
       OPHYD_DEVICES_BRANCH:
-        description: 'Branch of Ophyd Devices to install'
+        description: "Branch of Ophyd Devices to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
       BEC_WIDGETS_BRANCH:
-        description: 'Branch of BEC Widgets to install'
+        description: "Branch of BEC Widgets to install"
         required: false
-        default: 'main'
+        default: "main"
         type: string
     secrets:
       CODECOV_TOKEN:
         required: true
 
-
-
 permissions:
   pull-requests: write
 
@@ -55,7 +53,7 @@ jobs:
 
       - name: Run Pytest with Coverage
         id: coverage
-        run: pytest --random-order --cov=bec_widgets --cov-config=pyproject.toml --cov-branch --cov-report=xml --no-cov-on-fail tests/unit_tests/
+        run: pytest --random-order --cov=bec_widgets --cov-config=pyproject.toml --cov-branch --cov-report=xml --no-cov-on-fail --ignore=tests/unit_tests/benchmarks tests/unit_tests/
 
       - name: Upload test artifacts
         uses: actions/upload-artifact@v4
@@ -69,4 +67,4 @@ jobs:
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          slug: bec-project/bec_widgets
+          slug: bec-project/bec_widgets

CHANGELOG.md

@@ -1,6 +1,32 @@
 # CHANGELOG
 
 
+## v3.7.1 (2026-04-21)
+
+### Bug Fixes
+
+- **heatmap**: Fix access to status from metadata
+  ([`55694ff`](https://github.com/bec-project/bec_widgets/commit/55694ff2b96581e03c63c8b8e068e2db79bcf780))
+
+### Testing
+
+- Fix exit status and status access in tests
+  ([`91afc77`](https://github.com/bec-project/bec_widgets/commit/91afc775d59b4ba31bed3585847a67c301acf9b0))
+
+
+## v3.7.0 (2026-04-21)
+
+### Features
+
+- Move companion app to applications
+  ([`0cf84cd`](https://github.com/bec-project/bec_widgets/commit/0cf84cd1d839ac4a39ffb5fb9ba57d432e04348a))
+
+### Refactoring
+
+- Cleanup of imports
+  ([`3e77f54`](https://github.com/bec-project/bec_widgets/commit/3e77f540345f56b9f184a332fcdd50d4d4c8c621))
+
+
 ## v3.6.0 (2026-04-21)
 
 ### Bug Fixes

bec_widgets/__init__.py

@@ -1,19 +1,13 @@
-import os
-import sys
-
-import bec_widgets.widgets.containers.qt_ads as QtAds
-from bec_widgets.utils.bec_widget import BECWidget
-from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
-
-if sys.platform.startswith("linux"):
-    qt_platform = os.environ.get("QT_QPA_PLATFORM", "")
-    if qt_platform != "offscreen":
-        os.environ["QT_QPA_PLATFORM"] = "xcb"
-
-# Default QtAds configuration
-QtAds.CDockManager.setConfigFlag(QtAds.CDockManager.eConfigFlag.FocusHighlighting, True)
-QtAds.CDockManager.setConfigFlag(
-    QtAds.CDockManager.eConfigFlag.RetainTabSizeWhenCloseButtonHidden, True
-)
-
 __all__ = ["BECWidget", "SafeSlot", "SafeProperty"]
+
+
+def __getattr__(name):
+    if name == "BECWidget":
+        from bec_widgets.utils.bec_widget import BECWidget
+
+        return BECWidget
+    if name in {"SafeSlot", "SafeProperty"}:
+        from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
+
+        return {"SafeSlot": SafeSlot, "SafeProperty": SafeProperty}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

bec_widgets/applications/__init__.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+import bec_widgets.widgets.containers.qt_ads as QtAds
+
+if sys.platform.startswith("linux"):
+    qt_platform = os.environ.get("QT_QPA_PLATFORM", "")
+    if qt_platform != "offscreen":
+        os.environ["QT_QPA_PLATFORM"] = "xcb"
+
+# Default QtAds configuration
+QtAds.CDockManager.setConfigFlag(QtAds.CDockManager.eConfigFlag.FocusHighlighting, True)
+QtAds.CDockManager.setConfigFlag(
+    QtAds.CDockManager.eConfigFlag.RetainTabSizeWhenCloseButtonHidden, True
+)

bec_widgets/applications/companion_app.py

@@ -19,8 +19,8 @@ from qtpy.QtWidgets import QApplication
 
 import bec_widgets
 from bec_widgets.applications.launch_window import LaunchWindow
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.utils.bec_dispatcher import BECDispatcher
+from bec_widgets.utils.rpc_register import RPCRegister
 
 logger = bec_logger.logger
 

bec_widgets/applications/launch_window.py

@@ -20,13 +20,13 @@ from qtpy.QtWidgets import (
 )
 
 import bec_widgets
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.utils.bec_plugin_helper import get_all_plugin_widgets
 from bec_widgets.utils.container_utils import WidgetContainerUtils
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.name_utils import pascal_to_snake
 from bec_widgets.utils.plugin_utils import get_plugin_auto_updates
 from bec_widgets.utils.round_frame import RoundedFrame
+from bec_widgets.utils.rpc_register import RPCRegister
 from bec_widgets.utils.screen_utils import apply_window_geometry, centered_geometry_for_app
 from bec_widgets.utils.toolbars.toolbar import ModularToolBar
 from bec_widgets.utils.ui_loader import UILoader

bec_widgets/cli/__init__.py

@@ -0,0 +1 @@
+from bec_widgets.cli.rpc import rpc_base

bec_widgets/examples/jupyter_console/jupyter_console_window.py

@@ -25,8 +25,8 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from bec_widgets.cli.rpc.rpc_widget_handler import widget_handler
 from bec_widgets.utils.colors import apply_theme
+from bec_widgets.utils.rpc_widget_handler import widget_handler
 from bec_widgets.utils.widget_io import WidgetHierarchy as wh
 from bec_widgets.widgets.editors.jupyter_console.jupyter_console import BECJupyterConsole
 

bec_widgets/utils/__init__.py

@@ -1,13 +1 @@
-from qtpy.QtWebEngineWidgets import QWebEngineView
 
-from .bec_connector import BECConnector, ConnectionConfig
-from .bec_dispatcher import BECDispatcher
-from .bec_table import BECTable
-from .colors import Colors
-from .container_utils import WidgetContainerUtils
-from .crosshair import Crosshair
-from .entry_validator import EntryValidator
-from .layout_manager import GridLayoutManager
-from .rpc_decorator import register_rpc_methods, rpc_public
-from .ui_loader import UILoader
-from .validator_delegate import DoubleValidationDelegate

bec_widgets/utils/bec_connector.py

@@ -15,9 +15,9 @@ from pydantic import BaseModel, Field, field_validator
 from qtpy.QtCore import Property, QObject, QRunnable, QThreadPool, Signal
 from qtpy.QtWidgets import QApplication
 
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.utils.error_popups import ErrorPopupUtility, SafeSlot
 from bec_widgets.utils.name_utils import sanitize_namespace
+from bec_widgets.utils.rpc_register import RPCRegister
 from bec_widgets.utils.widget_io import WidgetHierarchy
 from bec_widgets.utils.yaml_dialog import load_yaml, load_yaml_gui, save_yaml, save_yaml_gui
 

bec_widgets/utils/bec_widget.py

@@ -10,11 +10,11 @@ from qtpy.QtGui import QFont, QPixmap
 from qtpy.QtWidgets import QApplication, QFileDialog, QLabel, QVBoxLayout, QWidget
 
 import bec_widgets.widgets.containers.qt_ads as QtAds
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
 from bec_widgets.utils.busy_loader import install_busy_loader
 from bec_widgets.utils.error_popups import SafeConnect, SafeSlot
 from bec_widgets.utils.rpc_decorator import rpc_timeout
+from bec_widgets.utils.rpc_register import RPCRegister
 from bec_widgets.utils.widget_io import WidgetHierarchy
 from bec_widgets.widgets.utility.spinner.spinner import SpinnerWidget
 

bec_widgets/utils/plugin_utils.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Iterable
 from bec_lib.plugin_helper import _get_available_plugins
 from qtpy.QtWidgets import QWidget
 
-from bec_widgets.utils import BECConnector
+from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.bec_widget import BECWidget
 
 if TYPE_CHECKING:  # pragma: no cover

bec_widgets/utils/rpc_server.py

@@ -14,11 +14,11 @@ from qtpy.QtCore import Qt, QTimer
 from qtpy.QtWidgets import QWidget
 from redis.exceptions import RedisError
 
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
-from bec_widgets.utils import BECDispatcher
 from bec_widgets.utils.bec_connector import BECConnector
+from bec_widgets.utils.bec_dispatcher import BECDispatcher
 from bec_widgets.utils.container_utils import WidgetContainerUtils
 from bec_widgets.utils.error_popups import ErrorPopupUtility
+from bec_widgets.utils.rpc_register import RPCRegister
 from bec_widgets.utils.screen_utils import apply_window_geometry
 from bec_widgets.widgets.containers.dock_area.dock_area import BECDockArea
 from bec_widgets.widgets.containers.main_window.main_window import BECMainWindow, BECMainWindowNoRPC

bec_widgets/utils/widget_io.py

@@ -26,7 +26,7 @@ from qtpy.QtWidgets import (
 from bec_widgets.widgets.utility.toggle.toggle import ToggleSwitch
 
 if TYPE_CHECKING:  # pragma: no cover
-    from bec_widgets.utils import BECConnector
+    from bec_widgets.utils.bec_connector import BECConnector
 
 logger = bec_logger.logger
 
@@ -418,7 +418,7 @@ class WidgetHierarchy:
             only_bec_widgets(bool, optional): Whether to print only widgets that are instances of BECWidget.
             show_parent(bool, optional): Whether to display which BECWidget is the parent of each discovered BECWidget.
         """
-        from bec_widgets.utils import BECConnector
+        from bec_widgets.utils.bec_connector import BECConnector
         from bec_widgets.widgets.plots.waveform.waveform import Waveform
 
         for node in WidgetHierarchy.iter_widget_tree(
@@ -468,7 +468,7 @@ class WidgetHierarchy:
 
         from qtpy.QtWidgets import QApplication
 
-        from bec_widgets.utils import BECConnector
+        from bec_widgets.utils.bec_connector import BECConnector
         from bec_widgets.widgets.plots.plot_base import PlotBase
 
         # 1) Gather ALL QWidget-based BECConnector objects
@@ -534,7 +534,7 @@ class WidgetHierarchy:
         Returns:
             The nearest ancestor that is a BECConnector, or None if not found.
         """
-        from bec_widgets.utils import BECConnector
+        from bec_widgets.utils.bec_connector import BECConnector
 
         # Guard against deleted/invalid Qt wrappers
         if not shb.isValid(widget):
@@ -636,7 +636,7 @@ class WidgetHierarchy:
         Return all BECConnector instances whose closest BECConnector ancestor is the given widget,
         including the widget itself if it is a BECConnector.
         """
-        from bec_widgets.utils import BECConnector
+        from bec_widgets.utils.bec_connector import BECConnector
 
         connectors: list[BECConnector] = []
         if isinstance(widget, BECConnector):
@@ -664,7 +664,7 @@ class WidgetHierarchy:
             return None
 
         try:
-            from bec_widgets.utils import BECConnector  # local import to avoid cycles
+            from bec_widgets.utils.bec_connector import BECConnector  # local import to avoid cycles
 
             is_bec_target = False
             if isinstance(ancestor_class, str):

bec_widgets/widgets/containers/dock_area/basic_dock_area.py

@@ -13,9 +13,9 @@ from shiboken6 import isValid
 
 import bec_widgets.widgets.containers.qt_ads as QtAds
 from bec_widgets import BECWidget, SafeSlot
-from bec_widgets.cli.rpc.rpc_widget_handler import widget_handler
 from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.property_editor import PropertyEditor
+from bec_widgets.utils.rpc_widget_handler import widget_handler
 from bec_widgets.utils.toolbars.actions import MaterialIconAction
 from bec_widgets.widgets.containers.qt_ads import (
     CDockAreaWidget,

bec_widgets/widgets/containers/dock_area/dock_area.py

@@ -20,10 +20,10 @@ from qtpy.QtWidgets import (
 import bec_widgets.widgets.containers.qt_ads as QtAds
 from bec_widgets import BECWidget, SafeProperty, SafeSlot
 from bec_widgets.applications.views.view import ViewTourSteps
-from bec_widgets.cli.rpc.rpc_widget_handler import widget_handler
-from bec_widgets.utils import BECDispatcher
+from bec_widgets.utils.bec_dispatcher import BECDispatcher
 from bec_widgets.utils.colors import apply_theme
 from bec_widgets.utils.rpc_decorator import rpc_timeout
+from bec_widgets.utils.rpc_widget_handler import widget_handler
 from bec_widgets.utils.toolbars.actions import (
     ExpandableMenuAction,
     MaterialIconAction,

bec_widgets/widgets/containers/layout_manager/layout_manager.py

@@ -22,7 +22,7 @@ from qtpy.QtWidgets import (
 )
 from typeguard import typechecked
 
-from bec_widgets.cli.rpc.rpc_widget_handler import widget_handler
+from bec_widgets.utils.rpc_widget_handler import widget_handler
 
 
 class LayoutManagerWidget(QWidget):

bec_widgets/widgets/containers/main_window/addons/notification_center/notification_banner.py

@@ -28,7 +28,7 @@ from qtpy.QtCore import QObject, QTimer
 from qtpy.QtWidgets import QApplication, QFrame, QMainWindow, QScrollArea, QWidget
 
 from bec_widgets import SafeProperty, SafeSlot
-from bec_widgets.utils import BECConnector
+from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.colors import apply_theme
 from bec_widgets.utils.widget_io import WidgetIO
 

bec_widgets/widgets/containers/main_window/main_window.py

@@ -18,10 +18,10 @@ from qtpy.QtWidgets import (
 )
 
 import bec_widgets
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.colors import apply_theme
 from bec_widgets.utils.error_popups import SafeSlot
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.widgets.containers.main_window.addons.hover_widget import HoverWidget
 from bec_widgets.widgets.containers.main_window.addons.notification_center.notification_banner import (
     BECNotificationBroker,

bec_widgets/widgets/control/device_control/positioner_box/positioner_box/positioner_box.py

@@ -11,9 +11,9 @@ from qtpy.QtCore import Qt, Signal
 from qtpy.QtGui import QDoubleValidator
 from qtpy.QtWidgets import QDoubleSpinBox
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.colors import apply_theme, get_accent_colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.widgets.control.device_control.positioner_box.positioner_box_base import (
     DeviceUpdateUIComponents,
     PositionerBoxBase,

bec_widgets/widgets/control/device_control/positioner_box/positioner_box_2d/positioner_box_2d.py

@@ -12,9 +12,9 @@ from qtpy.QtCore import Signal
 from qtpy.QtGui import QDoubleValidator
 from qtpy.QtWidgets import QDoubleSpinBox
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.colors import apply_theme
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.widgets.control.device_control.positioner_box.positioner_box_base import (
     DeviceUpdateUIComponents,
     PositionerBoxBase,

bec_widgets/widgets/control/device_input/base_classes/device_input_base.py

@@ -7,7 +7,7 @@ from bec_lib.device import Signal as BECSignal
 from bec_lib.logger import bec_logger
 from pydantic import field_validator
 
-from bec_widgets.utils import ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.filter_io import FilterIO

bec_widgets/widgets/control/device_input/base_classes/device_signal_input_base.py

@@ -3,7 +3,7 @@ from bec_lib.device import Signal
 from bec_lib.logger import bec_logger
 from qtpy.QtCore import Property
 
-from bec_widgets.utils import ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.filter_io import FilterIO

bec_widgets/widgets/control/scan_control/scan_control.py

@@ -19,12 +19,13 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from bec_widgets.utils import ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.colors import apply_theme, get_accent_colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.widgets.control.buttons.stop_button.stop_button import StopButton
 from bec_widgets.widgets.control.scan_control.scan_group_box import ScanGroupBox
+from bec_widgets.widgets.control.scan_control.scan_info_adapter import ScanInfoAdapter
 from bec_widgets.widgets.editors.scan_metadata.scan_metadata import ScanMetadata
 from bec_widgets.widgets.utility.toggle.toggle import ToggleSwitch
 
@@ -97,6 +98,7 @@ class ScanControl(BECWidget, QWidget):
         self._hide_scan_control_buttons = False
         self._hide_metadata = False
         self._hide_scan_selection_combobox = False
+        self._scan_info_adapter = ScanInfoAdapter()
 
         # Create and set main layout
         self._init_UI()
@@ -191,11 +193,12 @@ class ScanControl(BECWidget, QWidget):
             MessageEndpoints.available_scans()
         ).resource
         if self.config.allowed_scans is None:
-            supported_scans = ["ScanBase", "SyncFlyScanBase", "AsyncFlyScanBase"]
+            supported_scans = ["ScanBase", "SyncFlyScanBase", "AsyncFlyScanBase", "ScanBaseV4"]
             allowed_scans = [
                 scan_name
                 for scan_name, scan_info in self.available_scans.items()
-                if scan_info["base_class"] in supported_scans and len(scan_info["gui_config"]) > 0
+                if scan_info["base_class"] in supported_scans
+                and self._scan_info_adapter.has_scan_ui_config(scan_info)
             ]
 
         else:
@@ -390,14 +393,14 @@ class ScanControl(BECWidget, QWidget):
         self.reset_layout()
         selected_scan_info = self.available_scans.get(scan_name, {})
 
-        gui_config = selected_scan_info.get("gui_config", {})
-        self.arg_group = gui_config.get("arg_group", None)
-        self.kwarg_groups = gui_config.get("kwarg_groups", None)
+        gui_config = self._scan_info_adapter.build_scan_ui_config(selected_scan_info)
+        arg_group = gui_config.get("arg_group", None)
+        kwarg_groups = gui_config.get("kwarg_groups", [])
 
-        if bool(self.arg_group["arg_inputs"]):
-            self.add_arg_group(self.arg_group)
-        if len(self.kwarg_groups) > 0:
-            self.add_kwargs_boxes(self.kwarg_groups)
+        if arg_group and bool(arg_group.get("arg_inputs")):
+            self.add_arg_group(arg_group)
+        if kwarg_groups:
+            self.add_kwargs_boxes(kwarg_groups)
 
         self.update()
         self.adjustSize()

bec_widgets/widgets/control/scan_control/scan_group_box.py

@@ -209,6 +209,8 @@ class ScanGroupBox(QGroupBox):
 
         self.labels = []
         self.widgets = []
+        self._widget_configs = {}
+        self._column_labels = {}
         self.selected_devices = {}
 
         self.init_box(self.config)
@@ -247,6 +249,7 @@ class ScanGroupBox(QGroupBox):
             label = QLabel(text=display_name)
             self.layout.addWidget(label, row, column_index)
             self.labels.append(label)
+            self._column_labels[column_index] = label
 
     def add_input_widgets(self, group_inputs: dict, row) -> None:
         """
@@ -272,21 +275,30 @@ class ScanGroupBox(QGroupBox):
             if default == "_empty":
                 default = None
             widget = widget_class(parent=self.parent(), arg_name=arg_name, default=default)
+            self._apply_numeric_precision(widget, item)
+            self._apply_numeric_limits(widget, item)
             if isinstance(widget, DeviceLineEdit):
                 widget.set_device_filter(BECDeviceFilter.DEVICE)
                 self.selected_devices[widget] = ""
                 widget.device_selected.connect(self.emit_device_selected)
+                widget.textChanged.connect(
+                    lambda text, device_widget=widget: self._handle_device_text_changed(
+                        device_widget, text
+                    )
+                )
             if isinstance(widget, ScanLiteralsComboBox):
                 widget.set_literals(item["type"].get("Literal", []))
-            tooltip = item.get("tooltip", None)
-            if tooltip is not None:
-                widget.setToolTip(item["tooltip"])
+            self._widget_configs[widget] = item
+            self._apply_unit_metadata(widget, item)
             self.layout.addWidget(widget, row, column_index)
             self.widgets.append(widget)
 
     @Slot(str)
     def emit_device_selected(self, device_name):
-        self.selected_devices[self.sender()] = device_name.strip()
+        sender = self.sender()
+        self.selected_devices[sender] = device_name.strip()
+        if isinstance(sender, DeviceLineEdit):
+            self._update_reference_units(sender, self._device_units(sender.get_current_device()))
         selected_devices_str = " ".join(self.selected_devices.values())
         self.device_selected.emit(selected_devices_str)
 
@@ -313,6 +325,7 @@ class ScanGroupBox(QGroupBox):
         for widget in self.widgets[-len(self.inputs) :]:
             if isinstance(widget, DeviceLineEdit):
                 self.selected_devices[widget] = ""
+            self._widget_configs.pop(widget, None)
             widget.close()
             widget.deleteLater()
         self.widgets = self.widgets[: -len(self.inputs)]
@@ -325,6 +338,7 @@ class ScanGroupBox(QGroupBox):
         for widget in list(self.widgets):
             if isinstance(widget, DeviceLineEdit):
                 self.selected_devices.pop(widget, None)
+            self._widget_configs.pop(widget, None)
             widget.close()
             widget.deleteLater()
             self.layout.removeWidget(widget)
@@ -423,3 +437,119 @@ class ScanGroupBox(QGroupBox):
                 if widget.arg_name == key:
                     WidgetIO.set_value(widget, value)
                     break
+
+    @staticmethod
+    def _unit_tooltip(item: dict, units: str | None = None) -> str | None:
+        tooltip = item.get("tooltip", None)
+        reference_units = item.get("reference_units", None)
+        units = units or item.get("units", None)
+        tooltip_parts = [tooltip] if tooltip else []
+        if units:
+            tooltip_parts.append(f"Units: {units}")
+        elif reference_units:
+            tooltip_parts.append(f"Units from: {reference_units}")
+        if tooltip_parts:
+            return "\n".join(tooltip_parts)
+        return None
+
+    def _apply_unit_metadata(self, widget, item: dict, units: str | None = None) -> None:
+        units = units or item.get("units", None)
+        tooltip = self._unit_tooltip(item, units)
+        widget.setToolTip(tooltip or "")
+        if hasattr(widget, "setSuffix"):
+            widget.setSuffix(f" {units}" if units else "")
+
+    def _refresh_column_label(self, column: int, item: dict) -> None:
+        if column not in self._column_labels:
+            return
+        self._column_labels[column].setText(item.get("display_name", item.get("name", None)))
+
+    @staticmethod
+    def _device_units(device) -> str | None:
+        egu = getattr(device, "egu", None)
+        if not callable(egu):
+            return None
+        try:
+            return egu()
+        except Exception:
+            logger.exception("Failed to fetch engineering units from device %s", device)
+            return None
+
+    def _widget_position(self, widget) -> tuple[int, int] | None:
+        for row in range(self.layout.rowCount()):
+            for column in range(self.layout.columnCount()):
+                item = self.layout.itemAtPosition(row, column)
+                if item is not None and item.widget() is widget:
+                    return row, column
+        return None
+
+    def _update_reference_units(self, device_widget: DeviceLineEdit, units: str | None) -> None:
+        position = self._widget_position(device_widget)
+        if position is None:
+            return
+        source_row, _ = position
+        source_name = device_widget.arg_name
+
+        for widget in self.widgets:
+            item = self._widget_configs.get(widget, {})
+            if item.get("reference_units") != source_name:
+                continue
+            widget_position = self._widget_position(widget)
+            if widget_position is None:
+                continue
+            row, column = widget_position
+            if self.box_type == "args" and row != source_row:
+                continue
+            self._apply_unit_metadata(widget, item, units)
+            self._refresh_column_label(column, item)
+
+    def _handle_device_text_changed(self, device_widget: DeviceLineEdit, device_name: str) -> None:
+        if not device_widget.validate_device(device_name):
+            self.selected_devices[device_widget] = ""
+            self._update_reference_units(device_widget, None)
+
+    @staticmethod
+    def _apply_numeric_precision(widget: ScanDoubleSpinBox, item: dict) -> None:
+        if not isinstance(widget, ScanDoubleSpinBox):
+            return
+
+        precision = item.get("precision")
+        if precision is None:
+            return
+
+        try:
+            widget.setDecimals(max(0, int(precision)))
+        except (TypeError, ValueError):
+            logger.warning(
+                "Ignoring invalid precision %r for parameter %s", precision, item.get("name")
+            )
+
+    @staticmethod
+    def _apply_numeric_limits(widget: ScanDoubleSpinBox | ScanSpinBox, item: dict) -> None:
+        if isinstance(widget, ScanSpinBox):
+            minimum = -2147483647  # largest int which qt allows
+            maximum = 2147483647
+            if item.get("ge") is not None:
+                minimum = int(item["ge"])
+            if item.get("gt") is not None:
+                minimum = int(item["gt"]) + 1
+            if item.get("le") is not None:
+                maximum = int(item["le"])
+            if item.get("lt") is not None:
+                maximum = int(item["lt"]) - 1
+            widget.setRange(minimum, maximum)
+            return
+
+        if isinstance(widget, ScanDoubleSpinBox):
+            minimum = -float("inf")
+            maximum = float("inf")
+            step = 10 ** (-widget.decimals())
+            if item.get("ge") is not None:
+                minimum = float(item["ge"])
+            if item.get("gt") is not None:
+                minimum = float(item["gt"]) + step
+            if item.get("le") is not None:
+                maximum = float(item["le"])
+            if item.get("lt") is not None:
+                maximum = float(item["lt"]) - step
+            widget.setRange(minimum, maximum)

bec_widgets/widgets/control/scan_control/scan_info_adapter.py

@@ -0,0 +1,243 @@
+"""Helpers for translating BEC scan metadata into ScanControl UI configuration."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+AnnotationValue = str | dict[str, Any] | list[Any] | None
+ScanArgumentMetadata = dict[str, Any]
+SignatureEntry = dict[str, Any]
+ScanInputConfig = dict[str, Any]
+ScanInfo = dict[str, Any]
+ScanUIConfig = dict[str, Any]
+
+
+class ScanInfoAdapter:
+    """Normalize available-scan payloads into the structure consumed by ``ScanControl``."""
+
+    @staticmethod
+    def has_scan_ui_config(scan_info: ScanInfo) -> bool:
+        """Check whether a scan exposes enough metadata to build a UI.
+
+        Args:
+            scan_info (ScanInfo): Available-scan payload for one scan.
+
+        Returns:
+            bool: ``True`` when a supported GUI metadata field is present.
+        """
+        return bool(scan_info.get("gui_visibility") or scan_info.get("gui_config"))
+
+    @staticmethod
+    def format_display_name(name: str) -> str:
+        """Convert a parameter name into a user-facing label.
+
+        Args:
+            name (str): Raw parameter name.
+
+        Returns:
+            str: Formatted display label such as ``Exp Time``.
+        """
+        parts = re.split(r"(_|\d+)", name)
+        return " ".join(part.capitalize() for part in parts if part.isalnum()).strip()
+
+    @staticmethod
+    def resolve_tooltip(scan_argument: ScanArgumentMetadata) -> str | None:
+        """Resolve the tooltip text from parsed ``ScanArgument`` metadata.
+
+        Args:
+            scan_argument (ScanArgumentMetadata): Parsed ``ScanArgument`` metadata.
+
+        Returns:
+            str | None: Explicit tooltip text if provided, otherwise the description fallback.
+        """
+        return scan_argument.get("tooltip") or scan_argument.get("description")
+
+    @staticmethod
+    def parse_annotation(
+        annotation: AnnotationValue,
+    ) -> tuple[AnnotationValue, ScanArgumentMetadata]:
+        """Extract the serialized base annotation and ``ScanArgument`` metadata.
+
+        Args:
+            annotation (AnnotationValue): Serialized annotation payload from BEC.
+
+        Returns:
+            tuple[AnnotationValue, ScanArgumentMetadata]: The unwrapped annotation and parsed
+            ``ScanArgument`` metadata.
+        """
+        scan_argument: ScanArgumentMetadata = {}
+        if isinstance(annotation, list):
+            annotation = next(
+                (entry for entry in annotation if entry != "NoneType"),
+                annotation[0] if annotation else "_empty",
+            )
+        if isinstance(annotation, dict) and "Annotated" in annotation:
+            annotated = annotation["Annotated"]
+            annotation = annotated.get("type", "_empty")
+            scan_argument = annotated.get("metadata", {}).get("ScanArgument", {}) or {}
+        return annotation, scan_argument
+
+    @staticmethod
+    def scan_arg_type_from_annotation(annotation: AnnotationValue) -> AnnotationValue:
+        """Normalize an annotation value to the widget type expected by ``ScanControl``.
+
+        Args:
+            annotation (AnnotationValue): Serialized or parsed annotation value.
+
+        Returns:
+            AnnotationValue: The normalized type identifier used by the widget layer.
+        """
+        if isinstance(annotation, dict):
+            return annotation
+        if annotation in ("_empty", None):
+            return "str"
+        return annotation
+
+    def scan_input_from_signature(
+        self, param: SignatureEntry, arg: bool = False
+    ) -> ScanInputConfig:
+        """Build one ScanControl input description from a signature entry.
+
+        Args:
+            param (SignatureEntry): Serialized signature entry.
+            arg (bool): Whether the parameter belongs to the positional arg bundle.
+
+        Returns:
+            ScanInputConfig: Normalized input configuration for ``ScanControl``.
+        """
+        annotation, scan_argument = self.parse_annotation(param.get("annotation"))
+        return self._build_scan_input(
+            name=param["name"],
+            annotation=annotation,
+            scan_argument=scan_argument,
+            arg=arg,
+            default=None if arg else param.get("default", None),
+        )
+
+    def scan_input_from_arg_input(
+        self, name: str, item_type: AnnotationValue, signature_by_name: dict[str, SignatureEntry]
+    ) -> ScanInputConfig:
+        """Build one arg-bundle input description from ``arg_input`` metadata.
+
+        Args:
+            name (str): Argument name from ``arg_input``.
+            item_type (AnnotationValue): Serialized argument type from ``arg_input``.
+            signature_by_name (dict[str, SignatureEntry]): Signature entries indexed by
+                parameter name.
+
+        Returns:
+            ScanInputConfig: Normalized input configuration for one arg-bundle field.
+        """
+        if name in signature_by_name:
+            scan_input = self.scan_input_from_signature(signature_by_name[name], arg=True)
+            scan_input["type"] = self.scan_arg_type_from_annotation(
+                self.parse_annotation(signature_by_name[name].get("annotation"))[0]
+            )
+        else:
+            annotation, scan_argument = self.parse_annotation(item_type)
+            scan_input = self._build_scan_input(
+                name=name,
+                annotation=annotation,
+                scan_argument=scan_argument,
+                arg=True,
+                default=None,
+            )
+        if scan_input["type"] in ("_empty", None):
+            scan_input["type"] = item_type
+        return scan_input
+
+    def _build_scan_input(
+        self,
+        name: str,
+        annotation: AnnotationValue,
+        scan_argument: ScanArgumentMetadata,
+        *,
+        arg: bool,
+        default: Any,
+    ) -> ScanInputConfig:
+        """Build one normalized ScanControl input configuration.
+
+        Args:
+            name (str): Parameter name.
+            annotation (AnnotationValue): Parsed annotation value.
+            scan_argument (ScanArgumentMetadata): Parsed ``ScanArgument`` metadata.
+            arg (bool): Whether the parameter belongs to the positional arg bundle.
+            default (Any): Default value for the parameter.
+
+        Returns:
+            ScanInputConfig: Normalized input configuration.
+        """
+        return {
+            "arg": arg,
+            "name": name,
+            "type": self.scan_arg_type_from_annotation(annotation),
+            "display_name": scan_argument.get("display_name") or self.format_display_name(name),
+            "tooltip": self.resolve_tooltip(scan_argument),
+            "default": default,
+            "expert": scan_argument.get("expert", False),
+            "precision": scan_argument.get("precision"),
+            "units": scan_argument.get("units"),
+            "reference_units": scan_argument.get("reference_units"),
+            "gt": scan_argument.get("gt"),
+            "ge": scan_argument.get("ge"),
+            "lt": scan_argument.get("lt"),
+            "le": scan_argument.get("le"),
+            "alternative_group": scan_argument.get("alternative_group"),
+        }
+
+    def build_scan_ui_config(self, scan_info: ScanInfo) -> ScanUIConfig:
+        """Normalize one available-scan entry into the widget UI configuration.
+
+        Args:
+            scan_info (ScanInfo): Available-scan payload for one scan.
+
+        Returns:
+            ScanUIConfig: Legacy group structure consumed by ``ScanControl`` and
+            ``ScanGroupBox``.
+        """
+        gui_visualization = (
+            scan_info.get("gui_visualization") or scan_info.get("gui_visibility") or {}
+        )
+        if not gui_visualization and scan_info.get("gui_config"):
+            return scan_info["gui_config"]
+
+        signature = scan_info.get("signature", [])
+        signature_by_name = {entry["name"]: entry for entry in signature}
+
+        arg_group = None
+        arg_input = scan_info.get("arg_input", {})
+        if isinstance(arg_input, dict) and arg_input:
+            bundle_size = scan_info.get("arg_bundle_size", {})
+            inputs = [
+                self.scan_input_from_arg_input(name, item_type, signature_by_name)
+                for name, item_type in arg_input.items()
+            ]
+            arg_group = {
+                "name": "Scan Arguments",
+                "bundle": bundle_size.get("bundle"),
+                "arg_inputs": arg_input,
+                "inputs": inputs,
+                "min": bundle_size.get("min"),
+                "max": bundle_size.get("max"),
+            }
+
+        kwarg_groups = []
+        arg_names = set(arg_input) if isinstance(arg_input, dict) else set()
+        for group_name, input_names in gui_visualization.items():
+            inputs = []
+            for input_name in input_names:
+                if input_name in arg_names or input_name not in signature_by_name:
+                    continue
+                param = signature_by_name[input_name]
+                if param.get("kind") in ("VAR_POSITIONAL", "VAR_KEYWORD"):
+                    continue
+                inputs.append(self.scan_input_from_signature(param))
+            if inputs:
+                kwarg_groups.append({"name": group_name, "inputs": inputs})
+
+        return {
+            "scan_class_name": scan_info.get("class"),
+            "arg_group": arg_group,
+            "kwarg_groups": kwarg_groups,
+        }

bec_widgets/widgets/dap/lmfit_dialog/lmfit_dialog.py

@@ -5,10 +5,10 @@ from bec_lib.logger import bec_logger
 from qtpy.QtCore import Signal
 from qtpy.QtWidgets import QPushButton, QSizePolicy, QTreeWidgetItem, QVBoxLayout, QWidget
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.colors import get_accent_colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
+from bec_widgets.utils.ui_loader import UILoader
 
 logger = bec_logger.logger
 

bec_widgets/widgets/plots/heatmap/heatmap.py

@@ -19,8 +19,8 @@ from scipy.interpolate import (
 from scipy.spatial import cKDTree
 from toolz import partition
 
-from bec_widgets.utils import Colors
 from bec_widgets.utils.bec_connector import ConnectionConfig
+from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.settings_dialog import SettingsDialog
 from bec_widgets.utils.toolbars.actions import MaterialIconAction
@@ -611,7 +611,7 @@ class Heatmap(ImageBase):
             scan_msg = self.scan_item.status_message
         elif hasattr(self.scan_item, "metadata"):
             metadata = self.scan_item.metadata["bec"]
-            status = metadata["exit_status"]
+            status = metadata["status"]
             scan_id = metadata["scan_id"]
             scan_name = metadata["scan_name"]
             scan_type = metadata["scan_type"]

bec_widgets/widgets/plots/heatmap/settings/heatmap_setting.py

@@ -4,9 +4,9 @@ import os
 
 from qtpy.QtWidgets import QFrame, QScrollArea, QVBoxLayout
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 
 
 class HeatmapSettings(SettingWidget):

bec_widgets/widgets/plots/image/image.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel, Field, field_validator
 from qtpy.QtCore import QTimer
 from qtpy.QtWidgets import QWidget
 
-from bec_widgets.utils import ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.colors import Colors, apply_theme
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.widgets.plots.image.image_base import ImageBase

bec_widgets/widgets/plots/image/image_base.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, ConfigDict, Field, ValidationError
 from qtpy.QtCore import QPointF, Signal, SignalInstance
 from qtpy.QtWidgets import QDialog, QVBoxLayout
 
-from bec_widgets.utils import Colors
+from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.container_utils import WidgetContainerUtils
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.side_panel import SidePanel

bec_widgets/widgets/plots/image/image_item.py

@@ -9,7 +9,8 @@ from pydantic import Field, ValidationError, field_validator
 from qtpy.QtCore import Signal
 from qtpy.QtGui import QTransform
 
-from bec_widgets.utils import BECConnector, Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
+from bec_widgets.utils.colors import Colors
 from bec_widgets.widgets.plots.image.image_processor import (
     ImageProcessor,
     ImageStats,

bec_widgets/widgets/plots/image/setting_widgets/image_roi_tree.py

@@ -20,7 +20,8 @@ from qtpy.QtWidgets import (
 )
 
 from bec_widgets import BECWidget
-from bec_widgets.utils import BECDispatcher, ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
+from bec_widgets.utils.bec_dispatcher import BECDispatcher
 from bec_widgets.utils.toolbars.actions import WidgetAction
 from bec_widgets.utils.toolbars.bundles import ToolbarBundle
 from bec_widgets.utils.toolbars.toolbar import MaterialIconAction, ModularToolBar

bec_widgets/widgets/plots/motor_map/motor_map.py

@@ -10,8 +10,8 @@ from qtpy.QtCore import Signal
 from qtpy.QtGui import QColor
 from qtpy.QtWidgets import QHBoxLayout, QMainWindow, QWidget
 
-from bec_widgets.utils import Colors, ConnectionConfig
-from bec_widgets.utils.colors import apply_theme
+from bec_widgets.utils.bec_connector import ConnectionConfig
+from bec_widgets.utils.colors import Colors, apply_theme
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.settings_dialog import SettingsDialog
 from bec_widgets.utils.toolbars.toolbar import MaterialIconAction

bec_widgets/widgets/plots/motor_map/settings/motor_map_settings.py

@@ -2,9 +2,9 @@ import os
 
 from qtpy.QtWidgets import QFrame, QScrollArea, QVBoxLayout, QWidget
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.utils.widget_io import WidgetIO
 
 

bec_widgets/widgets/plots/multi_waveform/multi_waveform.py

@@ -10,7 +10,8 @@ from pydantic import Field, ValidationError, field_validator
 from qtpy.QtCore import Signal
 from qtpy.QtWidgets import QWidget
 
-from bec_widgets.utils import Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
+from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.side_panel import SidePanel
 from bec_widgets.widgets.control.device_input.device_combobox.device_combobox import DeviceComboBox

bec_widgets/widgets/plots/multi_waveform/settings/control_panel.py

@@ -2,9 +2,9 @@ import os
 
 from qtpy.QtWidgets import QVBoxLayout, QWidget
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.utils.widget_io import WidgetIO
 
 

bec_widgets/widgets/plots/plot_base.py

@@ -8,8 +8,10 @@ from bec_lib import bec_logger
 from qtpy.QtCore import QPoint, QPointF, Qt, Signal
 from qtpy.QtWidgets import QHBoxLayout, QLabel, QMainWindow, QVBoxLayout, QWidget
 
-from bec_widgets.utils import ConnectionConfig, Crosshair, EntryValidator
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
+from bec_widgets.utils.crosshair import Crosshair
+from bec_widgets.utils.entry_validator import EntryValidator
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.fps_counter import FPSCounter
 from bec_widgets.utils.plot_indicator_items import BECArrowItem, BECTickItem

bec_widgets/widgets/plots/roi/image_roi.py

@@ -10,7 +10,7 @@ from qtpy import QtCore
 from qtpy.QtCore import QObject, Signal
 
 from bec_widgets import SafeProperty
-from bec_widgets.utils import BECConnector, ConnectionConfig
+from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
 from bec_widgets.utils.colors import Colors
 
 if TYPE_CHECKING:

bec_widgets/widgets/plots/scatter_waveform/scatter_curve.py

@@ -8,7 +8,8 @@ from bec_lib import bec_logger
 from pydantic import BaseModel, Field, ValidationError, field_validator
 from qtpy import QtCore
 
-from bec_widgets.utils import BECConnector, Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
+from bec_widgets.utils.colors import Colors
 
 if TYPE_CHECKING:  # pragma: no cover
     from bec_widgets.widgets.plots.scatter_waveform.scatter_waveform import ScatterWaveform

bec_widgets/widgets/plots/scatter_waveform/scatter_waveform.py

@@ -7,7 +7,8 @@ from pydantic import Field, ValidationError, field_validator
 from qtpy.QtCore import QTimer, Signal
 from qtpy.QtWidgets import QHBoxLayout, QMainWindow, QWidget
 
-from bec_widgets.utils import Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
+from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.settings_dialog import SettingsDialog
 from bec_widgets.utils.toolbars.toolbar import MaterialIconAction

bec_widgets/widgets/plots/scatter_waveform/settings/scatter_curve_setting.py

@@ -2,9 +2,9 @@ import os
 
 from qtpy.QtWidgets import QFrame, QScrollArea, QVBoxLayout
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 
 
 class ScatterCurveSettings(SettingWidget):

bec_widgets/widgets/plots/setting_menus/axis_settings.py

@@ -2,9 +2,9 @@ import os
 
 from qtpy.QtWidgets import QFrame, QScrollArea, QVBoxLayout, QWidget
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.utils.widget_io import WidgetIO
 
 

bec_widgets/widgets/plots/waveform/curve.py

@@ -8,7 +8,8 @@ from bec_lib import bec_logger
 from pydantic import BaseModel, Field, field_validator
 from qtpy import QtCore
 
-from bec_widgets.utils import BECConnector, Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
+from bec_widgets.utils.colors import Colors
 
 if TYPE_CHECKING:  # pragma: no cover
     from bec_widgets.widgets.plots.waveform.waveform import Waveform

bec_widgets/widgets/plots/waveform/settings/curve_settings/curve_tree.py

@@ -50,9 +50,10 @@ from qtpy.QtWidgets import (
 )
 
 from bec_widgets import SafeSlot
-from bec_widgets.utils import ConnectionConfig, EntryValidator
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.colors import Colors
+from bec_widgets.utils.entry_validator import EntryValidator
 from bec_widgets.utils.toolbars.actions import WidgetAction
 from bec_widgets.utils.toolbars.bundles import ToolbarBundle
 from bec_widgets.utils.toolbars.toolbar import MaterialIconAction, ModularToolBar

bec_widgets/widgets/plots/waveform/waveform.py

@@ -25,7 +25,7 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from bec_widgets.utils import ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_signal_proxy import BECSignalProxy
 from bec_widgets.utils.colors import Colors, apply_theme
 from bec_widgets.utils.container_utils import WidgetContainerUtils

bec_widgets/widgets/progress/ring_progress_bar/ring_progress_bar.py

@@ -6,8 +6,8 @@ from bec_lib.logger import bec_logger
 from qtpy.QtCore import QPointF, QSize, Qt
 from qtpy.QtWidgets import QHBoxLayout, QLabel, QVBoxLayout, QWidget
 
-from bec_widgets.utils import Colors
 from bec_widgets.utils.bec_widget import BECWidget
+from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.error_popups import SafeProperty
 from bec_widgets.utils.settings_dialog import SettingsDialog
 from bec_widgets.utils.toolbars.actions import MaterialIconAction

bec_widgets/widgets/progress/ring_progress_bar/ring_progress_settings_cards.py

@@ -19,9 +19,9 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from bec_widgets.utils import UILoader
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.settings_dialog import SettingWidget
+from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.widgets.progress.ring_progress_bar.ring import Ring
 from bec_widgets.widgets.utility.visual.colormap_widget.colormap_widget import BECColorMapWidget
 

bec_widgets/widgets/services/device_browser/device_browser.py

@@ -12,10 +12,10 @@ from pyqtgraph import SignalProxy
 from qtpy.QtCore import QThreadPool, Signal
 from qtpy.QtWidgets import QFileDialog, QListWidget, QToolButton, QVBoxLayout, QWidget
 
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.error_popups import SafeSlot
 from bec_widgets.utils.list_of_expandable_frames import ListOfExpandableFrames
+from bec_widgets.utils.rpc_register import RPCRegister
 from bec_widgets.utils.ui_loader import UILoader
 from bec_widgets.widgets.services.device_browser.device_item import DeviceItem
 from bec_widgets.widgets.services.device_browser.device_item.device_config_dialog import (

bec_widgets/widgets/utility/visual/colormap_widget/colormap_widget.py

@@ -3,8 +3,8 @@ from qtpy import QtCore, QtGui
 from qtpy.QtCore import Property, Signal, Slot
 from qtpy.QtWidgets import QSizePolicy, QVBoxLayout, QWidget
 
-from bec_widgets.utils import Colors
 from bec_widgets.utils.bec_widget import BECWidget
+from bec_widgets.utils.colors import Colors
 
 
 class RoundedColorMapButton(ColorMapButton):

bec_widgets/widgets/utility/widget_hierarchy_tree/widget_hierarchy_tree.py

@@ -19,7 +19,7 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from bec_widgets.utils import BECConnector
+from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.widget_highlighter import WidgetHighlighter
 from bec_widgets.utils.widget_io import WidgetHierarchy
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bec_widgets"
-version = "3.6.0"
+version = "3.7.1"
 description = "BEC Widgets"
 requires-python = ">=3.11"
 classifiers = [
@@ -12,19 +12,19 @@ dependencies = [
   "PyJWT~=2.9",
   "PySide6==6.9.0",
   "PySide6-QtAds==4.4.0",
-  "bec_ipython_client~=3.107,>=3.107.2",  # needed for jupyter console
+  "bec_ipython_client~=3.107,>=3.107.2", # needed for jupyter console
   "bec_lib~=3.107,>=3.107.2",
   "bec_qthemes~=1.0, >=1.3.4",
-  "black>=26,<27",  # needed for bw-generate-cli
+  "black>=26,<27",                       # needed for bw-generate-cli
   "copier~=9.7",
   "darkdetect~=0.8",
-  "isort>=5.13, <9.0",  # needed for bw-generate-cli
+  "isort>=5.13, <9.0",                   # needed for bw-generate-cli
   "markdown~=3.9",
   "ophyd_devices~=1.29, >=1.29.1",
   "pydantic~=2.0",
   "pylsp-bec~=1.2",
   "pyqtgraph==0.13.7",
-  "qtconsole~=5.5, >=5.5.1",  # needed for jupyter console
+  "qtconsole~=5.5, >=5.5.1",             # needed for jupyter console
   "qtmonaco~=0.8, >=0.8.1",
   "qtpy~=2.4",
   "thefuzz~=0.22",
@@ -38,13 +38,13 @@ Homepage = "https://gitlab.psi.ch/bec/bec_widgets"
 [project.scripts]
 bec-app = "bec_widgets.applications.main_app:main"
 bec-designer = "bec_widgets.utils.bec_designer:main"
-bec-gui-server = "bec_widgets.cli.server:main"
-bw-generate-cli = "bec_widgets.cli.generate_cli:main"
+bec-gui-server = "bec_widgets.applications.companion_app:main"
+bw-generate-cli = "bec_widgets.utils.generate_cli:main"
 
 [project.optional-dependencies]
 dev = [
   "coverage~=7.0",
-  "fakeredis==2.34.1",
+  "fakeredis~=2.23, >=2.23.2",
   "pytest-bec-e2e>=2.21.4, <=4.0",
   "pytest-qt~=4.4",
   "pytest-random-order~=1.1",
@@ -52,12 +52,11 @@ dev = [
   "pytest-xvfb~=3.0",
   "pytest~=8.0",
   "pytest-cov~=6.1.1",
+  "pytest-benchmark~=5.2",
   "watchdog~=6.0",
   "pre_commit~=4.2",
 ]
-qtermwidget = [
-  "pyside6_qtermwidget",
-]
+qtermwidget = ["pyside6_qtermwidget"]
 
 [build-system]
 requires = ["hatchling"]
@@ -68,7 +67,7 @@ line-length = 100
 skip-magic-trailing-comma = true
 
 [tool.coverage.report]
-skip_empty = true  # exclude empty *files*, e.g. __init__.py, from the report
+skip_empty = true # exclude empty *files*, e.g. __init__.py, from the report
 exclude_lines = [
   "pragma: no cover",
   "if TYPE_CHECKING:",

tests/benchmarks/hyperfine/benchmark_import_bec_widgets.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# BENCHMARK_TITLE: Import bec_widgets
+set -euo pipefail
+
+python -c 'import bec_widgets; print(bec_widgets.__file__)'

tests/benchmarks/hyperfine/benchmark_launch_bec_with_companion.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# BENCHMARK_TITLE: BEC IPython client with companion app
+set -euo pipefail
+
+bec --post-startup-file tests/benchmarks/hyperfine/utils/exit_bec_startup.py

tests/benchmarks/hyperfine/benchmark_launch_bec_without_companion.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# BENCHMARK_TITLE: BEC IPython client without companion app
+set -euo pipefail
+
+bec --nogui --post-startup-file tests/benchmarks/hyperfine/utils/exit_bec_startup.py

tests/benchmarks/hyperfine/utils/exit_bec_startup.py

@@ -0,0 +1,5 @@
+import time
+
+_ip = get_ipython()
+_ip.confirm_exit = False
+_ip.ask_exit()

tests/unit_tests/benchmarks/test_dock_area_benchmark.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import pytest
+
+from bec_widgets.widgets.containers.dock_area.dock_area import BECDockArea
+from bec_widgets.widgets.plots.waveform.waveform import Waveform
+from tests.unit_tests.client_mocks import mocked_client
+
+
+@pytest.fixture
+def dock_area(qtbot, mocked_client):
+    widget = BECDockArea(client=mocked_client)
+    qtbot.addWidget(widget)
+    qtbot.waitExposed(widget)
+    yield widget
+
+
+def test_add_waveform_to_dock_area(benchmark, dock_area, qtbot, mocked_client):
+    """Benchmark adding a Waveform widget to an existing dock area."""
+
+    def add_waveform():
+        dock_area.new("Waveform")
+        return dock_area
+
+    dock = benchmark(add_waveform)
+
+    assert dock is not None

tests/unit_tests/conftest.py

@@ -23,11 +23,11 @@ from pytestqt.exceptions import TimeoutError as QtBotTimeoutError
 from qtpy.QtCore import QEvent, QEventLoop
 from qtpy.QtWidgets import QApplication, QMessageBox
 
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
 from bec_widgets.tests.utils import DEVICES, DMMock
 from bec_widgets.utils import bec_dispatcher as bec_dispatcher_module
 from bec_widgets.utils import error_popups
 from bec_widgets.utils.bec_dispatcher import QtRedisConnector
+from bec_widgets.utils.rpc_register import RPCRegister
 
 # Patch to set default RAISE_ERROR_DEFAULT to True for tests
 # This means that by default, error popups will raise exceptions during tests
@@ -227,7 +227,7 @@ def create_history_file(file_path, data: dict, metadata: dict) -> messages.ScanH
     msg = messages.ScanHistoryMessage(
         scan_id=metadata["scan_id"],
         scan_name=metadata["scan_name"],
-        exit_status=metadata["exit_status"],
+        exit_status=metadata["status"],
         file_path=file_path,
         scan_number=metadata["scan_number"],
         dataset_number=metadata["dataset_number"],
@@ -274,7 +274,7 @@ def grid_scan_history_msg(tmpdir):
         "scan_id": "test_scan",
         "scan_name": "grid_scan",
         "scan_type": "step",
-        "exit_status": "closed",
+        "status": "closed",
         "scan_number": 1,
         "dataset_number": 1,
         "request_inputs": {
@@ -354,7 +354,7 @@ def scan_history_factory(tmpdir):
             "scan_id": scan_id,
             "scan_name": scan_name,
             "scan_type": scan_type,
-            "exit_status": "closed",
+            "status": "closed",
             "scan_number": scan_number,
             "dataset_number": dataset_number,
             "request_inputs": {

tests/unit_tests/test_bec_connector.py

@@ -5,7 +5,7 @@ import pytest
 from qtpy.QtCore import QObject
 from qtpy.QtWidgets import QApplication, QWidget
 
-from bec_widgets.utils import BECConnector
+from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.error_popups import SafeProperty
 from bec_widgets.utils.error_popups import SafeSlot as Slot
 

tests/unit_tests/test_color_utils.py

@@ -4,9 +4,9 @@ from pydantic import ValidationError
 from qtpy.QtGui import QColor
 from qtpy.QtWidgets import QVBoxLayout, QWidget
 
-from bec_widgets.utils import Colors, ConnectionConfig
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.bec_widget import BECWidget
-from bec_widgets.utils.colors import apply_theme
+from bec_widgets.utils.colors import Colors, apply_theme
 from bec_widgets.widgets.plots.waveform.curve import CurveConfig
 from tests.unit_tests.client_mocks import mocked_client
 from tests.unit_tests.conftest import create_widget

tests/unit_tests/test_crosshair.py

@@ -4,7 +4,7 @@ import pytest
 from qtpy.QtCore import QPointF, Qt
 from qtpy.QtGui import QTransform
 
-from bec_widgets.utils import Crosshair
+from bec_widgets.utils.crosshair import Crosshair
 from bec_widgets.widgets.plots.image.image_item import ImageItem
 from bec_widgets.widgets.plots.waveform.waveform import Waveform
 from tests.unit_tests.client_mocks import mocked_client

tests/unit_tests/test_generate_cli_client.py

@@ -5,7 +5,7 @@ import black
 import isort
 import pytest
 
-from bec_widgets.cli.generate_cli import ClientGenerator
+from bec_widgets.utils.generate_cli import ClientGenerator
 from bec_widgets.utils.plugin_utils import BECClassContainer, BECClassInfo
 
 # pylint: disable=missing-function-docstring

tests/unit_tests/test_ring_progress_bar.py

@@ -8,7 +8,7 @@ from qtpy.QtCore import QEvent, QPoint, QPointF, Qt
 from qtpy.QtGui import QColor, QMouseEvent
 from qtpy.QtWidgets import QApplication
 
-from bec_widgets.utils import Colors
+from bec_widgets.utils.colors import Colors
 from bec_widgets.widgets.progress.ring_progress_bar.ring_progress_bar import (
     RingProgressBar,
     RingProgressContainerWidget,

tests/unit_tests/test_rpc_register.py

@@ -1,4 +1,4 @@
-from bec_widgets.cli.rpc.rpc_register import RPCRegister
+from bec_widgets.utils.rpc_register import RPCRegister
 
 
 class FakeObject:

tests/unit_tests/test_rpc_server.py

@@ -5,7 +5,7 @@ import pytest
 from bec_lib.service_config import ServiceConfig
 from qtpy.QtWidgets import QWidget
 
-from bec_widgets.cli.server import GUIServer
+from bec_widgets.applications.companion_app import GUIServer
 from bec_widgets.utils.bec_connector import BECConnector
 from bec_widgets.utils.rpc_server import RegistryNotReadyError, RPCServer, SingleshotRPCRepeat
 

tests/unit_tests/test_rpc_widget_handler.py

@@ -1,8 +1,8 @@
 from unittest.mock import patch
 
-from bec_widgets.cli.rpc.rpc_widget_handler import RPCWidgetHandler
 from bec_widgets.utils.bec_widget import BECWidget
 from bec_widgets.utils.plugin_utils import BECClassContainer, BECClassInfo
+from bec_widgets.utils.rpc_widget_handler import RPCWidgetHandler
 
 
 def test_rpc_widget_handler():
@@ -16,7 +16,7 @@ class _TestPluginWidget(BECWidget): ...
 
 
 @patch(
-    "bec_widgets.cli.rpc.rpc_widget_handler.get_all_plugin_widgets",
+    "bec_widgets.utils.rpc_widget_handler.get_all_plugin_widgets",
     return_value=BECClassContainer(
         [
             BECClassInfo(name="DeviceComboBox", obj=_TestPluginWidget, module="", file=""),

tests/unit_tests/test_scan_control.py

@@ -3,7 +3,6 @@ from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 import pytest
-from bec_lib.client import BECClient
 from bec_lib.endpoints import MessageEndpoints
 from bec_lib.messages import AvailableResourceMessage, ScanHistoryMessage
 from qtpy.QtCore import QModelIndex, Qt
@@ -256,10 +255,11 @@ scan_history = ScanHistoryMessage(
 
 
 @pytest.fixture(scope="function")
-def scan_control(qtbot, mocked_client: BECClient):
-    mocked_client.connector._redis_conn.flushall()
+def scan_control(qtbot, mocked_client):  # , mock_dev):
     mocked_client.connector.set(MessageEndpoints.available_scans(), available_scans_message)
-    mocked_client.connector.xadd(MessageEndpoints.scan_history(), msg_dict={"data": scan_history})
+    mocked_client.connector.xadd(
+        topic=MessageEndpoints.scan_history(), msg_dict={"data": scan_history}
+    )
     widget = ScanControl(client=mocked_client)
     qtbot.addWidget(widget)
     qtbot.waitExposed(widget)
@@ -277,6 +277,133 @@ def test_populate_scans(scan_control, mocked_client):
     assert sorted(items) == sorted(expected_scans)
 
 
+def test_scan_control_uses_gui_visibility_and_signature(qtbot, mocked_client):
+    scan_info = {
+        "class": "AnnotatedScan",
+        "base_class": "ScanBase",
+        "arg_input": {
+            "device": "DeviceBase",
+            "start": {
+                "Annotated": {
+                    "type": "float",
+                    "metadata": {
+                        "ScanArgument": {
+                            "display_name": "Start Position",
+                            "description": "Start position",
+                            "tooltip": "Custom start tooltip",
+                            "expert": False,
+                            "alternative_group": None,
+                            "units": None,
+                            "reference_units": "device",
+                        }
+                    },
+                }
+            },
+            "stop": {
+                "Annotated": {
+                    "type": "float",
+                    "metadata": {
+                        "ScanArgument": {
+                            "display_name": None,
+                            "description": "Stop position",
+                            "tooltip": None,
+                            "expert": False,
+                            "alternative_group": None,
+                            "units": None,
+                            "reference_units": "device",
+                        }
+                    },
+                }
+            },
+        },
+        "arg_bundle_size": {"bundle": 3, "min": 1, "max": None},
+        "gui_visibility": {
+            "Movement Parameters": ["steps", "step_size"],
+            "Acquisition Parameters": ["exp_time", "relative"],
+        },
+        "required_kwargs": [],
+        "signature": [
+            {"name": "args", "kind": "VAR_POSITIONAL", "default": "_empty", "annotation": "_empty"},
+            {"name": "steps", "kind": "KEYWORD_ONLY", "default": 10, "annotation": "int"},
+            {
+                "name": "step_size",
+                "kind": "KEYWORD_ONLY",
+                "default": None,
+                "annotation": {
+                    "Annotated": {
+                        "type": "float",
+                        "metadata": {
+                            "ScanArgument": {
+                                "display_name": "Step Size Custom",
+                                "description": "Step size",
+                                "tooltip": "Custom step tooltip",
+                                "expert": False,
+                                "alternative_group": "scan_resolution",
+                                "units": "mm",
+                                "reference_units": None,
+                            }
+                        },
+                    }
+                },
+            },
+            {
+                "name": "exp_time",
+                "kind": "KEYWORD_ONLY",
+                "default": 0,
+                "annotation": {
+                    "Annotated": {
+                        "type": "float",
+                        "metadata": {
+                            "ScanArgument": {
+                                "display_name": None,
+                                "description": None,
+                                "tooltip": "Exposure time",
+                                "expert": False,
+                                "alternative_group": None,
+                                "units": "s",
+                                "reference_units": None,
+                            }
+                        },
+                    }
+                },
+            },
+            {"name": "relative", "kind": "KEYWORD_ONLY", "default": False, "annotation": "bool"},
+            {"name": "kwargs", "kind": "VAR_KEYWORD", "default": "_empty", "annotation": "_empty"},
+        ],
+    }
+    mocked_client.connector.set(
+        MessageEndpoints.available_scans(),
+        AvailableResourceMessage(resource={"annotated_scan": scan_info}),
+    )
+
+    widget = ScanControl(client=mocked_client)
+    qtbot.addWidget(widget)
+    qtbot.waitExposed(widget)
+    widget.comboBox_scan_selection.setCurrentText("annotated_scan")
+
+    assert widget.comboBox_scan_selection.count() == 1
+    assert widget.arg_box.layout.itemAtPosition(0, 1).widget().text() == "Start Position"
+    assert widget.arg_box.widgets[1].toolTip() == "Custom start tooltip\nUnits from: device"
+    with patch.object(mocked_client.device_manager.devices.samx, "egu", return_value="mm"):
+        WidgetIO.set_value(widget.arg_box.widgets[0], "samx")
+    assert widget.arg_box.layout.itemAtPosition(0, 1).widget().text() == "Start Position"
+    assert widget.arg_box.widgets[1].suffix() == " mm"
+    assert widget.arg_box.widgets[1].toolTip() == "Custom start tooltip\nUnits: mm"
+    widget.arg_box.widgets[0].setText("not_a_device")
+    assert widget.arg_box.layout.itemAtPosition(0, 1).widget().text() == "Start Position"
+    assert widget.arg_box.widgets[1].suffix() == ""
+    assert widget.arg_box.widgets[1].toolTip() == "Custom start tooltip\nUnits from: device"
+    assert [box.title() for box in widget.kwarg_boxes] == [
+        "Movement Parameters",
+        "Acquisition Parameters",
+    ]
+    assert widget.kwarg_boxes[0].layout.itemAtPosition(0, 1).widget().text() == "Step Size Custom"
+    assert widget.kwarg_boxes[0].widgets[1].suffix() == " mm"
+    assert widget.kwarg_boxes[0].widgets[1].toolTip() == "Custom step tooltip\nUnits: mm"
+    assert widget.kwarg_boxes[1].layout.itemAtPosition(0, 0).widget().text() == "Exp Time"
+    assert widget.kwarg_boxes[1].widgets[0].toolTip() == "Exposure time\nUnits: s"
+
+
 def test_current_scan(scan_control, mocked_client):
     current_scan = scan_control.current_scan
     wrong_scan = "error_scan"
@@ -501,29 +628,17 @@ def test_changing_scans_remember_parameters(scan_control, mocked_client):
     assert grid_kwargs["burst_at_each_point"] == kwargs["burst_at_each_point"]
 
 
-def test_get_scan_parameters_from_redis(qtbot, scan_control: ScanControl, mocked_client):
-    scan_control.comboBox_scan_selection.setCurrentIndex(-1)
-    assert "line_scan" in [
-        scan_control.comboBox_scan_selection.itemText(i)
-        for i in range(scan_control.comboBox_scan_selection.count())
-    ]
+@pytest.mark.skip(reason="Unreliable - GH issue #1134")
+def test_get_scan_parameters_from_redis(scan_control, mocked_client):
     scan_name = "line_scan"
     scan_control.comboBox_scan_selection.setCurrentText(scan_name)
-    qtbot.wait(100)
-    slot_hit = False
 
-    def mock_request(*args):
-        ScanControl.request_last_executed_scan_parameters(scan_control, *args)
-        nonlocal slot_hit
-        slot_hit = True
-
-    scan_control.request_last_executed_scan_parameters = mock_request
-    # Trigger restore of parameters from history
     scan_control.toggle.checked = True
 
-    qtbot.waitUntil(lambda: slot_hit, timeout=1000)
-    args = ["samx", 0.0, 2.0]
-    kwargs = {
+    args, kwargs = scan_control.get_scan_parameters(bec_object=False)
+
+    assert args == ["samx", 0.0, 2.0]
+    assert kwargs == {
         "steps": 10,
         "relative": False,
         "exp_time": 2.0,
@@ -531,10 +646,6 @@ def test_get_scan_parameters_from_redis(qtbot, scan_control: ScanControl, mocked
         "metadata": {"comment": "", "sample_name": "", "scan_name": "line_scan"},
     }
 
-    qtbot.waitUntil(
-        lambda: scan_control.get_scan_parameters(bec_object=False) == (args, kwargs), timeout=5000
-    )
-
 
 TEST_MD = {
     "comment": "",
@@ -602,7 +713,8 @@ def test_scan_metadata_is_passed_to_scan_function(scan_control: ScanControl):
     scans.grid_scan.assert_called_once_with(metadata=TEST_MD)
 
 
-def test_restore_parameters_with_fewer_arg_bundles(scan_control: ScanControl, qtbot):
+@pytest.mark.skip(reason="Unreliable - GH issue #1134")
+def test_restore_parameters_with_fewer_arg_bundles(scan_control, qtbot):
     """
     Ensure that when more argument bundles are present than exist in the
     stored history, restoring parameters regenerates the arg box to the
@@ -610,36 +722,19 @@ def test_restore_parameters_with_fewer_arg_bundles(scan_control: ScanControl, qt
     This is a check for the previous infinite loop bug.
     """
     # Select the scan type that has history with only one arg bundle
-    scan_control.comboBox_scan_selection.setCurrentIndex(-1)
-    assert "line_scan" in [
-        scan_control.comboBox_scan_selection.itemText(i)
-        for i in range(scan_control.comboBox_scan_selection.count())
-    ]
-    scan_control.current_scan = "line_scan"
-    qtbot.waitUntil(lambda: scan_control.arg_box.count_arg_rows() == 1, timeout=1000)
+    scan_control.comboBox_scan_selection.setCurrentText("line_scan")
 
     # Manually add bundles so we end up with three rows
     while scan_control.arg_box.count_arg_rows() < 3:
         scan_control.arg_box.add_widget_bundle()
     assert scan_control.arg_box.count_arg_rows() == 3
 
-    scan_control.client.connector.xadd(
-        MessageEndpoints.scan_history(), msg_dict={"data": scan_history}
-    )
-    slot_hit = False
-
-    def mock_request(*args):
-        ScanControl.request_last_executed_scan_parameters(scan_control, *args)
-        nonlocal slot_hit
-        slot_hit = True
-
-    scan_control.request_last_executed_scan_parameters = mock_request
     # Trigger restore of parameters from history
     scan_control.toggle.checked = True
+    qtbot.wait(200)
 
-    qtbot.waitUntil(lambda: slot_hit, timeout=1000)
     # After restore, arg_box should have only one bundle (the history size)
-    qtbot.waitUntil(lambda: scan_control.arg_box.count_arg_rows() == 1, timeout=1000)
+    assert scan_control.arg_box.count_arg_rows() == 1
 
     # Verify that the restored parameter values match the history
     args, kwargs = scan_control.get_scan_parameters(bec_object=False)

tests/unit_tests/test_scan_control_group_box.py

@@ -157,3 +157,81 @@ def test_arg_box(qtbot):
     # Widget 2
     assert arg_box.widgets[2].__class__.__name__ == "ScanSpinBox"
     assert arg_box.widgets[2].arg_name
+
+
+def test_spinbox_limits_from_scan_info(qtbot):
+    group_input = {
+        "name": "Kwarg Test",
+        "inputs": [
+            {
+                "arg": False,
+                "name": "exp_time",
+                "type": "float",
+                "display_name": "Exp Time",
+                "tooltip": "Exposure time in seconds",
+                "default": 2.0,
+                "expert": False,
+                "precision": 3,
+                "gt": 1.5,
+                "ge": None,
+                "lt": 5.0,
+                "le": None,
+            },
+            {
+                "arg": False,
+                "name": "num_points",
+                "type": "int",
+                "display_name": "Num Points",
+                "tooltip": "Number of points",
+                "default": 4,
+                "expert": False,
+                "gt": None,
+                "ge": 3,
+                "lt": 9,
+                "le": None,
+            },
+            {
+                "arg": False,
+                "name": "settling_time",
+                "type": "float",
+                "display_name": "Settling Time",
+                "tooltip": "Settling time in seconds",
+                "default": 0.5,
+                "expert": False,
+                "gt": None,
+                "ge": 0.2,
+                "lt": None,
+                "le": 3.5,
+            },
+            {
+                "arg": False,
+                "name": "steps",
+                "type": "int",
+                "display_name": "Steps",
+                "tooltip": "Number of steps",
+                "default": 4,
+                "expert": False,
+                "gt": 0,
+                "ge": None,
+                "lt": None,
+                "le": 10,
+            },
+        ],
+    }
+
+    kwarg_box = ScanGroupBox(box_type="kwargs", config=group_input)
+
+    exp_time = kwarg_box.widgets[0]
+    num_points = kwarg_box.widgets[1]
+    settling_time = kwarg_box.widgets[2]
+    steps = kwarg_box.widgets[3]
+
+    assert exp_time.decimals() == 3
+    assert exp_time.minimum() == 1.501
+    assert exp_time.maximum() == 4.999
+    assert num_points.minimum() == 3
+    assert num_points.maximum() == 8
+    assert settling_time.minimum() == 0.2
+    assert settling_time.maximum() == 3.5
+    assert steps.minimum() == 1
+    assert steps.maximum() == 10