roboflow-workflows 0.2.3rc2__tar.gz → 0.2.4__tar.gz

roboflow_workflows-0.2.4/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: roboflow-workflows
+Version: 0.2.4
+Summary: Roboflow Workflows execution engine and block library
+License: LICENSE.core (Apache 2.0) applies to all files in this repository
+        except for files in or under any directory that contains a superseding
+        license file (such as the models located in `inference/models/`
+        which are governed by their own individual licenses and
+        the files and folders in the `inference/enterprise/` and `inference_cli/lib/enterprise/` directories which are
+        governed by the Roboflow Enterprise License located at
+        `inference/enterprise/LICENSE.txt`).
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<2.12.0,>=2.8.0
+Requires-Dist: typing-extensions<=4.15.0,>=4.8.0
+Requires-Dist: networkx<4.0.0,>=3.0.0
+Requires-Dist: packaging~=24.0
+Requires-Dist: numpy<2.4,>=1.26
+Requires-Dist: supervision<0.31.0,>=0.30.6
+Requires-Dist: opencv-python<4.13.0,>=4.8.1.78
+Requires-Dist: pillow<13.0.0,>=12.3.0
+Requires-Dist: shapely<2.1.0,>=2.0.4
+Requires-Dist: scikit-image<=0.25.2,>=0.19.0
+Requires-Dist: pycocotools<2.1.0,>=2.0.10
+Requires-Dist: pybase64~=1.0.0
+Requires-Dist: filelock<=4.0.0,>=3.20.3
+Requires-Dist: requests<3.0.0,>=2.33.0
+Requires-Dist: urllib3<3.0.0,>=2.7.0
+Requires-Dist: torch<3.0.0,>=2.0.1
+Requires-Dist: torchvision
+Requires-Dist: inference-models>=0.37.1
+Requires-Dist: inference-sdk>=1.7.0
+Requires-Dist: msgpack
+Requires-Dist: websocket-client~=1.9.0
+Requires-Dist: openai<2.0.0,>=1.17.0
+Requires-Dist: anthropic~=0.49.0
+Requires-Dist: boto3<=1.41.5,>=1.40.0
+Requires-Dist: botocore<=1.41.5,>=1.40.0
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: pandas<3.0.0,>=2.2.3
+Requires-Dist: matplotlib
+Requires-Dist: qrcode~=8.0.0
+Requires-Dist: zxing-cpp~=2.2.0; python_version < "3.13"
+Requires-Dist: zxing-cpp==2.3.0; python_version >= "3.13"
+Requires-Dist: trackers~=2.4.0
+Requires-Dist: onvif-zeep-async==2.0.0
+Requires-Dist: zeep<5.0,>=4.0
+Requires-Dist: simple-pid~=2.0.1
+Requires-Dist: slack-sdk~=3.33.4
+Requires-Dist: twilio~=9.3.7
+Provides-Extra: enterprise
+Requires-Dist: asyncua~=1.1.5; extra == "enterprise"
+Requires-Dist: paho-mqtt~=1.6.1; extra == "enterprise"
+Requires-Dist: pylogix==1.0.5; extra == "enterprise"
+Requires-Dist: pymodbus<=3.8.3,>=3.6.9; extra == "enterprise"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "enterprise"
+Requires-Dist: confluent-kafka<3,>=2.5; extra == "enterprise"
+Requires-Dist: aws-msk-iam-sasl-signer-python<2,>=1.0.2; extra == "enterprise"
+Requires-Dist: fastapi<0.142,>=0.134; extra == "enterprise"
+Provides-Extra: test
+Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "test"
+Requires-Dist: requests-mock~=1.12.1; extra == "test"
+Dynamic: license-file
+
+# roboflow-workflows
+
+Roboflow Workflows execution engine and block library.
+
+`roboflow-workflows` is the Python distribution for the Workflows engine that
+powers [Roboflow Inference](https://github.com/roboflow/inference).  It can be
+installed independently for use in standalone pipelines or embedded in the
+full Inference server.
+
+## Changelog and versions
+
+[CHANGELOG.md](CHANGELOG.md) records package changes, including an Execution
+engine subsection for compile/run behavior changes. Each release records its
+bundled engine version, starting with package `0.2.2`. The package version
+identifies the distribution; the separate engine version controls workflow and
+block compatibility. Block-only releases can leave the engine version unchanged.
+
+Earlier engine changes and migration examples remain in the
+[historical engine changelog](https://docs.roboflow.com/workflows/developer-guide/developer-guide/execution-engine-changelog).
+
+## Installation
+
+```bash
+pip install roboflow-workflows
+```
+
+Optional extras:
+
+```bash
+pip install "roboflow-workflows[enterprise]"  # enterprise sink blocks
+pip install "roboflow-workflows[test]"        # test-only dependencies
+```
+
+## Local development (from this repository)
+
+```bash
+# Provision font assets (required by visualization blocks).
+python workflows/build_scripts/download_fonts.py
+
+# Install the package in editable mode with test + enterprise deps.
+pip install -e './workflows[test,enterprise]'
+
+# Run package unit and isolation tests.
+cd workflows
+python -m pytest tests/unit_tests tests/isolation
+
+# Build a wheel from the same project directory (fonts already provisioned).
+uv lock --check
+uv build --out-dir ../dist
+```
+
+For editing `roboflow_workflows` source while running the full Inference
+server, install both projects together from the repository root:
+
+```bash
+pip install -e ./inference_models -e './workflows[test,enterprise]' -e .
+```
+
+The dev images also support mounting `workflows/roboflow_workflows` at
+`/app/roboflow_workflows`, alongside the existing `/app/inference` mount.
+Provision local fonts first, since a bind mount replaces bundled image files.
+
+## Font assets
+
+Visualization blocks require pre-provisioned font files.  Font binaries are
+downloaded by `workflows/build_scripts/download_fonts.py` (or
+`make download_fonts` at the repository root) and are gitignored.  They are
+embedded as package-data in the published wheel so that offline environments
+work without a checkout.

roboflow_workflows-0.2.4/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "roboflow-workflows"
+version = "0.2.4"
+description = "Roboflow Workflows execution engine and block library"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10,<3.14"
+dependencies = [
+  "pydantic>=2.8.0,<2.12.0",
+  "typing-extensions>=4.8.0,<=4.15.0",
+  "networkx>=3.0.0,<4.0.0",
+  "packaging~=24.0",
+  "numpy>=1.26,<2.4",
+  "supervision>=0.30.6,<0.31.0",
+  "opencv-python>=4.8.1.78,<4.13.0",
+  "pillow>=12.3.0,<13.0.0",
+  "shapely>=2.0.4,<2.1.0",
+  "scikit-image>=0.19.0,<=0.25.2",
+  "pycocotools>=2.0.10,<2.1.0",
+  "pybase64~=1.0.0",
+  "filelock>=3.20.3,<=4.0.0",
+  "requests>=2.33.0,<3.0.0",
+  "urllib3>=2.7.0,<3.0.0",
+  "torch>=2.0.1,<3.0.0",
+  "torchvision",
+  "inference-models>=0.37.1",
+  "inference-sdk>=1.7.0",
+  "msgpack",
+  "websocket-client~=1.9.0",
+  "openai>=1.17.0,<2.0.0",
+  "anthropic~=0.49.0",
+  "boto3>=1.40.0,<=1.41.5",
+  "botocore>=1.40.0,<=1.41.5",
+  "httpx~=0.28.1",
+  "pandas>=2.2.3,<3.0.0",
+  "matplotlib",
+  "qrcode~=8.0.0",
+  "zxing-cpp~=2.2.0; python_version < '3.13'",
+  "zxing-cpp==2.3.0; python_version >= '3.13'",
+  "trackers~=2.4.0",
+  "onvif-zeep-async==2.0.0",
+  "zeep>=4.0,<5.0",
+  "simple-pid~=2.0.1",
+  "slack-sdk~=3.33.4",
+  "twilio~=9.3.7",
+]
+
+[project.optional-dependencies]
+enterprise = [
+  "asyncua~=1.1.5",
+  "paho-mqtt~=1.6.1",
+  "pylogix==1.0.5",
+  "pymodbus>=3.6.9,<=3.8.3",
+  "psycopg[binary]>=3.2,<4",
+  "confluent-kafka>=2.5,<3",
+  "aws-msk-iam-sasl-signer-python>=1.0.2,<2",
+  "fastapi>=0.134,<0.142",
+]
+test = [
+  "pytest>=9.0.3,<10.0.0",
+  "requests-mock~=1.12.1",
+]
+
+[build-system]
+requires = ["setuptools>=83.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["roboflow_workflows*"]
+exclude = ["tests*", "build_scripts*", "scripts*"]
+
+[tool.setuptools.package-data]
+roboflow_workflows = [
+  "core_steps/visualizations/common/fonts/assets/*/*",
+  "core_steps/visualizations/common/fonts/README.md",
+]

roboflow_workflows-0.2.4/roboflow_workflows/configuration.py

@@ -0,0 +1,377 @@
+"""Injected configuration for `inference/core/workflows`.
+
+Every value the module used to take from `inference.core.env` is a field of
+`WorkflowsConfiguration`, which the host builds from its own already-resolved
+settings and installs once per process with `configure_process`.
+
+The configuration is PROCESS-WIDE in its entirety. Every configuration value
+is read from a module constant frozen at import - `core_steps/loader.py`
+branches on the tensor flag while it is being imported, `offline.py:34` reads
+`SECURE_GATEWAY`, `block_assembler.py:100` reads the custom-Python
+authorization flag - so there is no field a second, differing configuration
+could change after the fact. `ensure_process_configuration_matches` therefore
+refuses ANY difference rather than accepting a value nothing would honour.
+
+Per-engine variance lives where it already did: the named init parameters
+`workflows_core.{step_execution_mode, api_key, disable_sinks,
+allow_access_to_file_system, allowed_write_directory,
+allow_access_to_environmental_variables}`, resolved by
+`steps_initialiser.retrieve_init_parameter_values`.
+
+`default_configuration()` is the STANDALONE fallback, not the production path.
+Its values are the ones `inference/core/env.py` resolves for an EMPTY
+environment. Every normalisation `env.py` performs - `str2bool`, `.lower()`,
+the `OFFLINE_MODE` / `SECURE_GATEWAY` rewrites, the `PROJECT`-dependent hosted
+URLs, the api-key-transport validation - stays in `env.py`; the host builder
+copies the RESOLVED attributes. `resolve_image_tensor_device` is the single
+copied piece of logic and is pinned by a differential test against `env.py`.
+"""
+
+import threading
+from dataclasses import dataclass, field, fields, is_dataclass
+from typing import Any, List, Optional, Tuple
+
+from roboflow_workflows.errors import WorkflowEnvironmentConfigurationError
+
+# The values `inference/core/env.py` accepts for
+# `WORKFLOWS_CUSTOM_PYTHON_EXECUTION_MODE`, after its `.strip().lower()`.
+CUSTOM_PYTHON_EXECUTION_MODES = ("local", "modal")
+
+
+@dataclass(frozen=True)
+class EngineConfiguration:
+    """Engine-level values, copied from the host's resolved settings.
+
+    Raises:
+        WorkflowEnvironmentConfigurationError: If `custom_python_execution_mode`
+            is not exactly one of `CUSTOM_PYTHON_EXECUTION_MODES`. The value is
+            not normalised here: a host passes the value it already resolved.
+    """
+
+    step_execution_mode: str = "local"
+    async_future_result_timeout: float = 60.0
+    max_inner_workflow_depth: int = 4
+    max_inner_workflow_count: int = 32
+    allow_custom_python_execution: bool = True
+    custom_python_execution_mode: str = "local"
+    allow_blocks_accessing_local_storage: bool = True
+    allow_blocks_accessing_environmental_variables: bool = True
+    blocks_write_directory: Optional[str] = None
+    # Tuples, not lists: the configuration is frozen and compared by value. The
+    # facade re-materialises the `list` the call sites see today.
+    disabled_block_types: Tuple[str, ...] = ()
+    disabled_block_patterns: Tuple[str, ...] = ()
+    allow_webhook_sink_to_non_global_addresses: bool = True
+    # PostgreSQL sink policy. Optional[Tuple] mirrors env.py's None-vs-set
+    # distinction (empty env var / unset). The sink reconstructs a `set`.
+    allow_postgresql_sink_to_non_global_addresses: bool = True
+    postgresql_sink_blacklisted_addresses: Optional[Tuple[str, ...]] = None
+    postgresql_sink_whitelisted_addresses: Optional[Tuple[str, ...]] = None
+    # Kafka sinks bootstrap-server policy. Optional[Tuple] mirrors env.py's
+    # None-vs-list distinction; the facade rebuilds the ORDERED list.
+    allow_kafka_sinks_user_provided_bootstrap_servers: bool = True
+    kafka_sinks_whitelisted_bootstrap_servers: Optional[Tuple[str, ...]] = None
+    # MQTT blocks broker-address policy, same shape as the Kafka pair: the
+    # facade rebuilds the ORDERED list and the first entry is the operator's
+    # broker when user-provided hosts are not allowed.
+    allow_mqtt_blocks_user_provided_host: bool = True
+    mqtt_blocks_whitelisted_hosts: Optional[Tuple[str, ...]] = None
+
+    def __post_init__(self) -> None:
+        # Consumers compare against "modal" only, so any other value would
+        # silently run custom Python locally.
+        if self.custom_python_execution_mode not in CUSTOM_PYTHON_EXECUTION_MODES:
+            raise WorkflowEnvironmentConfigurationError(
+                public_message=(
+                    "`engine.custom_python_execution_mode` must be one of "
+                    f"{list(CUSTOM_PYTHON_EXECUTION_MODES)}, got "
+                    f"{self.custom_python_execution_mode!r}."
+                ),
+                context="workflow_configuration | engine_configuration",
+            )
+
+
+@dataclass(frozen=True)
+class TensorConfiguration:
+    """Selects which block classes `core_steps/loader.py` imports and how
+    `WorkflowImageData` stores pixels. Block loading is process-global and
+    cached (`blocks_loader.py:252`), so these can never be per-engine."""
+
+    representation_enabled: bool = False
+    # `torch.device` when the flag is on and torch is importable, else None.
+    # Typed `Any` so this module never imports torch (an OPTIONAL dependency).
+    image_tensor_device: Optional[Any] = None
+    visualisation_validate_owners: bool = False
+    sam_video_mask_representation: str = "rle"
+    enforce_dense_instance_masks: bool = False
+
+
+@dataclass(frozen=True)
+class RemoteExecutionConfiguration:
+    api_target: str = "hosted"
+    api_key_transport: str = "both"
+    local_inference_api_url: str = "http://127.0.0.1:9001"
+    hosted_detect_url: str = "https://detect.roboflow.com"
+    hosted_classification_url: str = "https://classify.roboflow.com"
+    hosted_instance_segmentation_url: str = "https://outline.roboflow.com"
+    hosted_semantic_segmentation_url: str = "https://segment.roboflow.com"
+    hosted_core_model_url: str = "https://infer.roboflow.com"
+    max_step_batch_size: int = 1
+    max_step_concurrent_requests: int = 8
+    inner_workflow_remote_target: str = "https://serverless.roboflow.com"
+    inner_workflow_remote_dispatch_request_timeout: float = 300.0
+    openai_compatible_allowed_base_urls: Tuple[str, ...] = ("*",)
+
+
+@dataclass(frozen=True)
+class PlatformConfiguration:
+    api_base_url: str = "https://api.roboflow.com"
+    offline_mode: bool = False
+    secure_gateway: Optional[str] = None
+    gcp_serverless: bool = False
+    # LAMBDA runtime flag, mirrors inference.core.env.LAMBDA. Used by the
+    # PostgreSQL sink hosted-runtime gate together with gcp_serverless.
+    lambda_runtime: bool = False
+
+
+@dataclass(frozen=True)
+class FontsConfiguration:
+    allow_download: bool = True
+    model_cache_dir: str = "/tmp/cache"
+
+
+@dataclass(frozen=True)
+class ModelsConfiguration:
+    lmm_enabled: bool = False
+    vlm_segmentation_max_polygon_vertices: int = 500
+    clip_version_id: str = "ViT-B-16"
+    core_model_sam2_enabled: bool = True
+    core_model_sam3_enabled: bool = True
+    core_model_pe_enabled: bool = True
+    core_model_gaze_enabled: bool = True
+    sam3_exec_mode: str = "local"
+    sam3_3d_objects_enabled: bool = False
+    florence2_enabled: bool = True
+    qwen_2_5_enabled: bool = True
+    qwen_3_enabled: bool = True
+    qwen_3_5_enabled: bool = True
+    smolvlm2_enabled: bool = True
+    moondream2_enabled: bool = True
+    depth_estimation_enabled: bool = True
+    cosmos3_enabled: bool = True
+    glm_ocr_enabled: bool = True
+
+
+@dataclass(frozen=True)
+class ModalConfiguration:
+    token_id: Optional[str] = None
+    token_secret: Optional[str] = field(default=None, repr=False)
+    workspace_name: str = "roboflow"
+    allow_anonymous_execution: bool = False
+    anonymous_workspace_name: str = "anonymous"
+    app_name: str = "webexec-roboflow-platform"
+    executor_idle_ttl_seconds: int = 1800
+    jpeg_quality: int = 95
+    transport: str = "http"
+    ws_connect_timeout_seconds: int = 30
+    ws_read_timeout_seconds: int = 720
+    ws_connection_pool_size: int = 1
+    ws_fail_on_session_loss: bool = False
+    ws_idle_release_seconds: int = 120
+
+
+@dataclass(frozen=True)
+class SecretsConfiguration:
+    api_key: Optional[str] = field(default=None, repr=False)
+    roboflow_internal_service_name: Optional[str] = None
+    roboflow_internal_service_secret: Optional[str] = field(default=None, repr=False)
+
+
+@dataclass(frozen=True)
+class DebugConfiguration:
+    output_dir: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class WorkflowsConfiguration:
+    engine: EngineConfiguration = field(default_factory=EngineConfiguration)
+    tensor: TensorConfiguration = field(default_factory=TensorConfiguration)
+    remote: RemoteExecutionConfiguration = field(
+        default_factory=RemoteExecutionConfiguration
+    )
+    platform: PlatformConfiguration = field(default_factory=PlatformConfiguration)
+    fonts: FontsConfiguration = field(default_factory=FontsConfiguration)
+    models: ModelsConfiguration = field(default_factory=ModelsConfiguration)
+    modal: ModalConfiguration = field(default_factory=ModalConfiguration)
+    secrets: SecretsConfiguration = field(default_factory=SecretsConfiguration)
+    debug: DebugConfiguration = field(default_factory=DebugConfiguration)
+
+
+def default_configuration() -> WorkflowsConfiguration:
+    """The standalone fallback: every field at its documented default."""
+    return WorkflowsConfiguration()
+
+
+def resolve_image_tensor_device(
+    representation_enabled: bool, device: Optional[str] = None
+) -> Optional[Any]:
+    """Materialise the tensor device exactly as `inference/core/env.py:1535-1547`.
+
+    `torch` is an OPTIONAL dependency, so both the import and the device are
+    deferred behind the flag AND guarded on torch's presence. Off-flag or
+    torch-less the value is `None`. An invalid device string raises whatever
+    `torch.device` raises, which is what `env.py` does too - it does not guard
+    that call either.
+
+    The `try` deliberately spans the import, the cuda autodetect AND the
+    materialisation, catching only `ImportError`, because that is exactly
+    `env.py:1536-1547`'s boundary (round-2 defect 5: the round-1 copy protected
+    only the import, so a `torch.cuda.is_available()` raising `ImportError`
+    would have propagated from the copy while `env.py` swallowed it).
+    `test_the_copy_preserves_the_originals_exception_boundary` pins both shapes.
+    """
+    if not representation_enabled:
+        return None
+    try:
+        import torch
+
+        if device is None:
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        return torch.device(device)
+    except ImportError:
+        return None
+
+
+def describe_configuration_difference(
+    installed: WorkflowsConfiguration, candidate: WorkflowsConfiguration
+) -> List[str]:
+    """`['group.field: <installed> != <candidate>', ...]`, empty when equal.
+
+    Secret fields are compared but never rendered - the message says the field
+    differs, not what either value is.
+    """
+    differences = []
+    for group in fields(WorkflowsConfiguration):
+        installed_group = getattr(installed, group.name)
+        candidate_group = getattr(candidate, group.name)
+        if installed_group == candidate_group:
+            continue
+        if not is_dataclass(candidate_group):
+            differences.append(f"{group.name}: differs")
+            continue
+        for member in fields(installed_group):
+            left = getattr(installed_group, member.name)
+            right = getattr(candidate_group, member.name)
+            if left == right:
+                continue
+            if member.repr is False:
+                differences.append(f"{group.name}.{member.name}: differs (redacted)")
+            else:
+                differences.append(f"{group.name}.{member.name}: {left!r} != {right!r}")
+    return differences
+
+
+_CONFIGURATION: Optional[WorkflowsConfiguration] = None
+# One lock guards installation, the sticky fallback initialisation in
+# `get_configuration` (which also assigns) and `reset_configuration`. Round-1
+# review reproduced two conflicting installs both succeeding through an
+# unlocked check-then-assign; Phase 10's image-codec registry locks for the
+# same reason.
+_INSTALL_LOCK = threading.RLock()
+
+
+def configure_process(configuration: WorkflowsConfiguration) -> None:
+    """Install the process-wide configuration. Set-once, by value.
+
+    Installing the identical object, or an EQUAL one, is a no-op - frozen
+    dataclasses compare by value and the server memoises its instance.
+    Installing a DIFFERING one raises, naming every group and field that
+    differs.
+    """
+    global _CONFIGURATION
+    with _INSTALL_LOCK:
+        if _CONFIGURATION is not None and _CONFIGURATION != configuration:
+            differences = describe_configuration_difference(
+                _CONFIGURATION, configuration
+            )
+            raise WorkflowEnvironmentConfigurationError(
+                public_message=(
+                    "A different WorkflowsConfiguration is already installed in "
+                    "this process. Workflows configuration is process-level: "
+                    "block registration and the image representation are decided "
+                    "once, at import time, and every other value is frozen into "
+                    "module constants. Install the configuration before importing "
+                    "any workflows module, and install the same one everywhere. "
+                    f"Differences: {differences}"
+                ),
+                context="workflow_configuration | process_installation",
+            )
+        _CONFIGURATION = configuration
+
+
+def get_configuration() -> WorkflowsConfiguration:
+    """The installed configuration, falling back to the standalone default.
+
+    The fallback is STICKY: once read, it becomes the process configuration, so
+    a later `configure_process` with different values raises instead of
+    silently disagreeing with values already frozen into module constants.
+    """
+    global _CONFIGURATION
+    with _INSTALL_LOCK:
+        if _CONFIGURATION is None:
+            _CONFIGURATION = default_configuration()
+        return _CONFIGURATION
+
+
+def reset_configuration() -> None:
+    """Test-only hook: forget the installed configuration."""
+    global _CONFIGURATION
+    with _INSTALL_LOCK:
+        _CONFIGURATION = None
+
+
+def ensure_process_configuration_matches(configuration: Any) -> None:
+    """Refuse an engine-supplied configuration that differs from the process one.
+
+    `init_parameters["workflows_core.configuration"]` is a CONSISTENCY
+    ASSERTION, not an override channel: the composition roots pass the object
+    the host installed, and a mismatch means the process is mis-wired. Because
+    every value is read from a module constant frozen at import, accepting a
+    differing value would mean accepting a value nothing honours.
+
+    The caller decides PRESENCE (the engine calls this only when the key is in
+    `init_parameters`); this function judges the VALUE, and `None` is not a
+    valid value: an explicit `None` would be handed to every block that
+    declares `configuration` ahead of the registered default
+    (`steps_initialiser.py:124-125` prefers explicit values), so it is refused
+    like any other non-`WorkflowsConfiguration` (round-4 defect 1).
+    """
+    if not isinstance(configuration, WorkflowsConfiguration):
+        # Only ever reached through the DEDICATED init-parameter keys, so a
+        # foreign value there is a mis-wiring, never a plugin's own parameter
+        # (`v1/core.py` deliberately does not fall back to the bare name).
+        raise WorkflowEnvironmentConfigurationError(
+            public_message=(
+                "`workflows_core.configuration` must be a WorkflowsConfiguration, "
+                f"got {type(configuration).__name__}."
+            ),
+            context="workflow_compilation | engine_initialisation",
+        )
+    installed = get_configuration()
+    if configuration == installed:
+        return
+    differences = describe_configuration_difference(installed, configuration)
+    raise WorkflowEnvironmentConfigurationError(
+        public_message=(
+            "`workflows_core.configuration` differs from the WorkflowsConfiguration "
+            "installed in this process. Workflows configuration is process-level "
+            "and cannot be varied per engine; use the named init parameters "
+            "(`workflows_core.step_execution_mode`, `workflows_core.api_key`, "
+            "`workflows_core.disable_sinks`, "
+            "`workflows_core.allow_access_to_file_system`, "
+            "`workflows_core.allowed_write_directory`, "
+            "`workflows_core.allow_access_to_environmental_variables`) for "
+            f"per-engine values. Differences: {differences}"
+        ),
+        context="workflow_compilation | engine_initialisation",
+    )