refactor(workflows): decontaminate inference imports

.github/workflows/unit_tests_inference_x86.yml

@@ -50,7 +50,8 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install --upgrade setuptools
-          pip install -r requirements/_requirements.txt -r requirements/requirements.cpu.txt -r requirements/requirements.sdk.http.txt -r requirements/requirements.test.unit.txt -r requirements/requirements.http.txt -r requirements/requirements.transformers.txt
+          # Composition-root tests also exercise the CLI entry points.
+          pip install -r requirements/requirements.cli.txt -r requirements/_requirements.txt -r requirements/requirements.cpu.txt -r requirements/requirements.sdk.http.txt -r requirements/requirements.test.unit.txt -r requirements/requirements.http.txt -r requirements/requirements.transformers.txt
           pip install --no-deps ./inference_models
       - name: 🧪 Unit Tests of Inference
         timeout-minutes: 30

.github/workflows/unit_tests_workflows_x86.yml

@@ -61,4 +61,4 @@ jobs:
         run: python build_scripts/download_fonts.py
       - name: 🧪 Unit Tests of Workflows
         timeout-minutes: 30
-        run: python -m pytest tests/workflows/unit_tests
+        run: python -m pytest tests/workflows/unit_tests tests/workflows/isolation

development/stream_interface/benchmark_engine_throughput.py

@@ -19,6 +19,7 @@
 If the tensor run now matches (or beats) the numpy run here, while the live pipeline
 showed tensor at half the FPS, the gap is the per-frame numpy->GPU conversion.
 """
+
 import argparse
 import os
 import sys
@@ -42,6 +43,22 @@
     MAX_ACTIVE_MODELS,
     WORKFLOWS_IMAGE_TENSOR_DEVICE,
 )
+from inference.core.interfaces.roboflow_platform_client import (
+    install_workflows_platform_bindings,
+)
+from inference.core.interfaces.workflows_configuration import (
+    server_workflows_configuration,
+)
+from inference.core.interfaces.workflows_execution_observer import (
+    UsageTrackingExecutionObserver,
+)
+from inference.core.interfaces.workflows_image_codec import bind_image_codec
+from inference.core.interfaces.workflows_models_provider import (
+    ModelManagerModelsProvider,
+)
+from inference.core.interfaces.workflows_step_error_handlers import (
+    resolve_step_error_handler,
+)
 from inference.core.managers.base import ModelManager
 from inference.core.managers.decorators.fixed_size_cache import WithFixedSizeCache
 from inference.core.registries.roboflow import RoboflowModelRegistry
@@ -113,7 +130,9 @@ def parse_args() -> argparse.Namespace:
 def build_model_manager() -> ModelManager:
     # Same construction as tests/workflows/integration_tests/conftest.py::model_manager.
     registry = RoboflowModelRegistry(ROBOFLOW_MODEL_TYPES)
-    return WithFixedSizeCache(ModelManager(model_registry=registry), max_size=MAX_ACTIVE_MODELS)
+    return WithFixedSizeCache(
+        ModelManager(model_registry=registry), max_size=MAX_ACTIVE_MODELS
+    )
 
 
 def decode_frames(video_path: str, count: int) -> List[np.ndarray]:
@@ -139,7 +158,10 @@ def to_gpu_tensor(bgr_hwc: np.ndarray, device: torch.device) -> torch.Tensor:
 
 
 def _cuda_sync_if_needed() -> None:
-    if ENABLE_TENSOR_DATA_REPRESENTATION and WORKFLOWS_IMAGE_TENSOR_DEVICE.type == "cuda":
+    if (
+        ENABLE_TENSOR_DATA_REPRESENTATION
+        and WORKFLOWS_IMAGE_TENSOR_DEVICE.type == "cuda"
+    ):
         torch.cuda.synchronize()
 
 
@@ -167,7 +189,10 @@ def main() -> None:
         f"WORKFLOWS_IMAGE_TENSOR_DEVICE = {WORKFLOWS_IMAGE_TENSOR_DEVICE} | "
         f"ENABLE_TENSOR_DATA_REPRESENTATION = {ENABLE_TENSOR_DATA_REPRESENTATION}"
     )
-    if ENABLE_TENSOR_DATA_REPRESENTATION and WORKFLOWS_IMAGE_TENSOR_DEVICE.type != "cuda":
+    if (
+        ENABLE_TENSOR_DATA_REPRESENTATION
+        and WORKFLOWS_IMAGE_TENSOR_DEVICE.type != "cuda"
+    ):
         print(
             "WARNING: tensor mode is on but the tensor device is not CUDA — frames live on "
             f"'{WORKFLOWS_IMAGE_TENSOR_DEVICE}', so the model will still copy to GPU itself."
@@ -193,14 +218,26 @@ def main() -> None:
         )
 
     model_manager = build_model_manager()
+    # The server services a direct caller must bind; `examples/
+    # run_perspective_correction.py` documents what each one buys. The observer
+    # is billed work the engine used to do internally, so it belongs inside the
+    # measured loop, as it was before.
+    init_parameters = {
+        "workflows_core.model_manager": ModelManagerModelsProvider(model_manager),
+        "workflows_core.api_key": args.api_key,
+        "workflows_core.step_execution_mode": StepExecutionMode.LOCAL,
+        "workflows_core.execution_observer": UsageTrackingExecutionObserver(),
+    }
+    install_workflows_platform_bindings(init_parameters)
+    bind_image_codec(init_parameters)
+    init_parameters.setdefault(
+        "workflows_core.configuration", server_workflows_configuration()
+    )
     engine = ExecutionEngine.init(
         workflow_definition=workflow,
-        init_parameters={
-            "workflows_core.model_manager": model_manager,
-            "workflows_core.api_key": args.api_key,
-            "workflows_core.step_execution_mode": StepExecutionMode.LOCAL,
-        },
+        init_parameters=init_parameters,
         workflow_id=args.workflow_id,
+        step_error_handler=resolve_step_error_handler(),
     )
 
     extra_params = {"model_id": args.model_id} if args.model_id else {}
@@ -237,13 +274,17 @@ def run_once(i: int):
     runs_per_s = args.engine_runs / elapsed if elapsed > 0 else 0.0
     frames_per_s = total_frames / elapsed if elapsed > 0 else 0.0
     print("\n=== Summary ===")
-    print(f"data representation : {'TENSOR' if ENABLE_TENSOR_DATA_REPRESENTATION else 'NUMPY'}")
+    print(
+        f"data representation : {'TENSOR' if ENABLE_TENSOR_DATA_REPRESENTATION else 'NUMPY'}"
+    )
     print(f"pre-decoded frames  : {n}")
     print(f"batch size          : {batch_size}")
     print(f"engine runs (timed) : {args.engine_runs}")
     print(f"frames processed    : {total_frames}")
     print(f"elapsed             : {elapsed:.3f} s")
-    print(f"throughput          : {frames_per_s:.1f} frames/s ({runs_per_s:.1f} runs/s)")
+    print(
+        f"throughput          : {frames_per_s:.1f} frames/s ({runs_per_s:.1f} runs/s)"
+    )
     print(f"per-run latency     : {elapsed / args.engine_runs * 1000:.3f} ms")
     print(f"per-frame latency   : {elapsed / total_frames * 1000:.3f} ms")
 

examples/run_perspective_correction.py

@@ -1,3 +1,59 @@
+"""Perspective-correction demo, and the reference for what a direct Python
+caller may bind.
+
+Two supported wirings, permanent. Pick either:
+
+1. Pass a raw `ModelManager` (or `ModelManagerDecorator`) as
+   `workflows_core.model_manager`. `ExecutionEngine.init` invokes the
+   manager's `__workflows_bind__` hook, which installs the historical server
+   bindings (platform client / cache / workspace / inner-workflow resolver,
+   image codec, usage-tracking observer, process configuration and the
+   server's step-error handler). Explicit keys the caller already set
+   survive.
+
+2. Pass an explicit `ModelManagerModelsProvider` (or any other
+   `ModelsProvider` implementation) as `workflows_core.model_manager` and
+   bind the rest of the services yourself. Suits standalone / custom-host
+   integrations that keep provider object identity.
+
+This applies to passing a manager INTO the engine, not to direct
+construction of individual workflow block classes. The script below uses
+form (2); form (1) works without any of the extra `workflows_core.*` calls
+made here.
+
+The Execution Engine takes the server's capabilities as explicit
+`workflows_core.*` init parameters instead of reaching for them itself. Its
+standalone defaults refuse or no-op whatever is missing; the services below
+restore them for a caller who is wiring things by hand:
+
+* `install_workflows_platform_bindings` - Roboflow-managed VLM and notification
+  proxy calls, workflows referenced by ID, workspace identity for authenticated
+  Modal execution, and the shared cache behind sink cooldown/dedup. Unbound, the
+  offline platform client raises and the cache is process-local.
+* `bind_image_codec` - `{"type": "file"}` / `{"type": "url"}` and serialized
+  numpy inputs, plus the later re-load of a stored image reference; the default
+  codec refuses them. Call it AFTER merging overrides, so input deserialization
+  and reference loading share one codec and one SSRF/local-file policy.
+* `UsageTrackingExecutionObserver()` - workflow and custom-block usage plus the
+  run's tracing spans; the default observer records nothing.
+* `resolve_step_error_handler()` - the server's error classification; the
+  engine's own default is the mapping-free legacy handler.
+* `server_workflows_configuration()` - the object the rest of the process uses,
+  so a mis-wire is reported instead of silently diverging.
+
+The usage categories are separate scopes, not substitutes: `request` (one HTTP
+handler call), `workflows` (one observed engine run, with workflow identity, FPS
+and preview), `workflow_block` (one custom-Python block execution) and `model`
+(the existing model-level accounting). Server entry points keep their existing
+layers; a direct caller gets the workflow and block scopes only from the
+observer above. Leaving the observer out on purpose stays supported - execution
+still runs, without workflow/custom-block collection.
+
+An offline platform client is not "no network": blocks calling a third party
+with the user's own provider key, and the REMOTE branches that go through
+`inference_sdk`, keep working on their own terms.
+"""
+
 import argparse
 import os
 from pathlib import Path
@@ -6,6 +62,22 @@
 import numpy as np
 import supervision as sv
 
+from inference.core.interfaces.roboflow_platform_client import (
+    install_workflows_platform_bindings,
+)
+from inference.core.interfaces.workflows_configuration import (
+    server_workflows_configuration,
+)
+from inference.core.interfaces.workflows_execution_observer import (
+    UsageTrackingExecutionObserver,
+)
+from inference.core.interfaces.workflows_image_codec import bind_image_codec
+from inference.core.interfaces.workflows_models_provider import (
+    ModelManagerModelsProvider,
+)
+from inference.core.interfaces.workflows_step_error_handlers import (
+    resolve_step_error_handler,
+)
 from inference.core.managers.base import ModelManager
 from inference.core.registries.roboflow import RoboflowModelRegistry
 from inference.core.workflows.core_steps.common.entities import StepExecutionMode
@@ -224,13 +296,22 @@ def parse_args() -> argparse.Namespace:
     model_registry = RoboflowModelRegistry(ROBOFLOW_MODEL_TYPES)
     model_manager = ModelManager(model_registry=model_registry)
 
+    init_parameters = {
+        "workflows_core.model_manager": ModelManagerModelsProvider(model_manager),
+        "workflows_core.api_key": os.getenv("ROBOFLOW_API_KEY"),
+        "workflows_core.step_execution_mode": StepExecutionMode.LOCAL,
+        "workflows_core.execution_observer": UsageTrackingExecutionObserver(),
+    }
+    install_workflows_platform_bindings(init_parameters)
+    bind_image_codec(init_parameters)
+    init_parameters.setdefault(
+        "workflows_core.configuration", server_workflows_configuration()
+    )
+
     execution_engine = ExecutionEngine.init(
         workflow_definition=WORKFLOW_DEFINITION,
-        init_parameters={
-            "workflows_core.model_manager": model_manager,
-            "workflows_core.api_key": os.getenv("ROBOFLOW_API_KEY"),
-            "workflows_core.step_execution_mode": StepExecutionMode.LOCAL,
-        },
+        init_parameters=init_parameters,
+        step_error_handler=resolve_step_error_handler(),
     )
 
     result = execution_engine.run(

inference/core/__init__.py

@@ -5,9 +5,29 @@
 from packaging import version as packaging_version
 
 from inference.core.env import DISABLE_VERSION_CHECK, VERSION_CHECK_MODE
+
+# Hand the Workflows module its configuration before anything can READ it.
+# The invariant: `install_workflows_configuration()` runs before any import
+# of `inference.core.workflows.environment` (the constants facade) or any
+# other configuration-consuming workflows module, so `core_steps/loader.py`'s
+# import-time tensor branches and every facade constant see the server's
+# values. A few configuration-independent workflows modules are already on
+# the bootstrap path above this point (`inference.core.env` ->
+# `utils/environment.py` -> `core/exceptions.py` ->
+# `workflows/prototypes/platform_errors.py`, and the builder's own import of
+# `workflows/configuration.py`); they must stay configuration-independent -
+# none of them may import the facade. `inference.core.interfaces
+# .workflows_configuration` imports only `inference.core.env` (already fully
+# imported above) and `inference.core.workflows.configuration`, so this adds
+# no import weight.
+from inference.core.interfaces.workflows_configuration import (
+    install_workflows_configuration,
+)
 from inference.core.logger import logger
 from inference.core.version import __version__
 
+install_workflows_configuration()
+
 latest_release = None
 last_checked = 0
 cache_duration = 86400  # 24 hours

inference/core/entities/requests/sam2.py

@@ -1,12 +1,18 @@
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, List, Optional, Union
 
-from pydantic import BaseModel, Field, root_validator, validator
+from pydantic import Field, root_validator, validator
 
 from inference.core.entities.requests.inference import (
     BaseRequest,
     InferenceRequestImage,
 )
 from inference.core.env import SAM2_VERSION_ID
+from inference.core.workflows.core_steps.models.foundation.segment_anything_common.prompts import (  # noqa: F401
+    Box,
+    Point,
+    Sam2Prompt,
+    Sam2PromptSet,
+)
 
 
 class Sam2InferenceRequest(BaseRequest):
@@ -56,72 +62,6 @@ class Sam2EmbeddingRequest(Sam2InferenceRequest):
     )
 
 
-class Box(BaseModel):
-    x: float
-    y: float
-    width: float
-    height: float
-
-
-class Point(BaseModel):
-    x: float
-    y: float
-    positive: bool
-
-    def to_hashable(self) -> Tuple[float, float, bool]:
-        return (self.x, self.y, self.positive)
-
-
-class Sam2Prompt(BaseModel):
-    box: Optional[Box] = Field(default=None)
-    points: Optional[List[Point]] = Field(default=None)
-
-    def num_points(self) -> int:
-        return len(self.points or [])
-
-
-class Sam2PromptSet(BaseModel):
-    prompts: Optional[List[Sam2Prompt]] = Field(
-        default=None,
-        description="An optional list of prompts for masks to predict. Each prompt can include a bounding box and / or a set of postive or negative points",
-    )
-
-    def num_points(self) -> int:
-        if not self.prompts:
-            return 0
-        return sum(prompt.num_points() for prompt in self.prompts)
-
-    def to_sam2_inputs(self):
-        if self.prompts is None:
-            return {"point_coords": None, "point_labels": None, "box": None}
-        return_dict = {"point_coords": [], "point_labels": [], "box": []}
-        for prompt in self.prompts:
-            if prompt.box is not None:
-                x1 = prompt.box.x - prompt.box.width / 2
-                y1 = prompt.box.y - prompt.box.height / 2
-                x2 = prompt.box.x + prompt.box.width / 2
-                y2 = prompt.box.y + prompt.box.height / 2
-                return_dict["box"].append([x1, y1, x2, y2])
-            if prompt.points is not None:
-                return_dict["point_coords"].append(
-                    list([point.x, point.y] for point in prompt.points)
-                )
-                return_dict["point_labels"].append(
-                    list(int(point.positive) for point in prompt.points)
-                )
-            else:
-                return_dict["point_coords"].append([])
-                return_dict["point_labels"].append([])
-
-        if not any(return_dict["point_coords"]):
-            return_dict["point_coords"] = None
-        if not any(return_dict["point_labels"]):
-            return_dict["point_labels"] = None
-
-        return_dict = {k: v if v else None for k, v in return_dict.items()}
-        return return_dict
-
-
 class Sam2SegmentationRequest(Sam2InferenceRequest):
     """SAM segmentation request.