# How OpenMontage Auto-Detects Available Tool Capabilities at Runtime: A Deep Dive into the Detection Architecture

> Discover how OpenMontage auto detects tool capabilities at runtime. Learn about its innovative detection architecture and global capability registry for efficient resource management.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: deep-dive
- Published: 2026-08-30

---

**OpenMontage auto-detects available tool capabilities at runtime by treating every functionality module as a tool derived from a `BaseTool` class, invoking a special `detect` operation at startup that inspects the environment and aggregates results into a global capability registry.**

OpenMontage adopts a modular architecture where FFmpeg, GPU back-ends, and third-party CLI tools all inherit from a common `BaseTool` class. When the application initializes, the system automatically discovers which tools are usable on the current machine without requiring hard-coded configuration files. This capability detection mechanism ensures that UI panels, CLI flags, and orchestration logic only expose features that are actually available on the host system.

## The BaseTool Architecture and Detection Interface

Every tool in OpenMontage implements a private `_detect()` method that inspects the host environment for specific binaries, libraries, or running services. This method returns a `ToolResult` object containing critical boolean fields:

- **`installed`** – True if the required binary or library is present on the system
- **`running`** – True if the service or daemon is reachable (for tools requiring background processes)

The tool manager orchestrates this process by calling `tool.execute({"operation": "detect"})` on each registered class, which internally triggers the `_detect()` implementation specific to that tool type.

## The Five-Step Runtime Detection Flow

The detection sequence follows a predictable pipeline implemented in [`backlot/server.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/server.py) and [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py):

1. **Dynamic Discovery** – All modules under `tools/` are imported via a glob pattern to populate `TOOL_REGISTRY`
2. **Instantiation** – Each tool class (`CapRecorder`, `VideoStitch`, `ImageGen`, etc.) is instantiated without arguments
3. **Runtime Detection** – The manager calls `tool.execute({"operation": "detect"})`, which delegates to `_detect()`
4. **Result Collection** – The returned `ToolResult` is serialized and stored in the capability registry
5. **Capability Exposure** – UI components and CLI parsers query `CapabilityState` to enable or disable features dynamically

This design creates a **self-healing capability list**: if a user installs a missing dependency, a subsequent restart automatically registers the new tool without manual configuration updates.

## Implementation Examples from the Codebase

### CapRecorder Detection Logic

The `CapRecorder` tool in [`tools/capture/cap_recorder.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/capture/cap_recorder.py) demonstrates how CLI availability checks are implemented. When the detect operation is invoked, the tool verifies whether the "Cap" executable exists on the system PATH:

```python

# Source: tools/capture/cap_recorder.py (lines 260-279)

if operation == "detect":
    return self._detect()

```

The `_detect()` method returns a `ToolResult` indicating whether the capture utility is installed and executable.

### ImageGen Provider Auto-Detection

In [`tools/graphics/image_gen.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/graphics/image_gen.py), the system dynamically selects available image generation providers by inspecting Python package imports:

```python

# Source: tools/graphics/image_gen.py (lines 104-110)

def _detect_provider(self) -> Optional[str]:
    # Look for installed providers (e.g., Stability AI, DALL-E, etc.)

    for name, pkg in self.KNOWN_PROVIDERS.items():
        if importlib.util.find_spec(pkg):
            return name
    return None

```

This approach allows OpenMontage to support multiple AI providers while only exposing those with installed dependencies.

### Central Detection Loop

The aggregation logic in [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py) collects individual tool results into a global capability map:

```python

# Simplified illustration from backlot/server.py and backlot/state.py

from backlot.state import CapabilityState

def detect_all_tools():
    caps = {}
    for ToolCls in TOOL_REGISTRY:
        tool = ToolCls()
        result = tool.execute({"operation": "detect"})
        caps[ToolCls.__name__] = result.data
    CapabilityState.update(caps)

```

This centralizes capability knowledge, allowing downstream components to query a single source of truth via `CapabilityState` rather than probing tools directly.

## Key Files and Their Roles

| File | Role |
|------|------|
| [`backlot/server.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/server.py) | Initializes the server, loads the tool registry, and triggers detection at application launch |
| [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py) | Maintains the global `CapabilityState` singleton accessed by UI components and orchestrators |
| [`tools/capture/cap_recorder.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/capture/cap_recorder.py) | Implements binary detection for the CapRecorder tool via `_detect()` |
| [`tools/graphics/image_gen.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/graphics/image_gen.py) | Provides package-import detection for image generation providers |
| [`tools/video/video_stitch.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_stitch.py) | Demonstrates FFmpeg availability checks for audio stream processing |

## Summary

- **BaseTool inheritance** provides a uniform interface for all functionality modules, requiring each tool to implement `_detect()` for environment inspection.
- **ToolResult objects** encapsulate installation status and running state, creating a standardized communication protocol between tools and the manager.
- **Dynamic registry updates** occur at startup via `detect_all_tools()`, which populates `CapabilityState` without manual configuration.
- **Self-healing behavior** ensures that newly installed dependencies are automatically recognized on application restart.
- **Downstream consumption** allows UI panels and CLI commands to query [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py) for real-time capability awareness.

## Frequently Asked Questions

### How does OpenMontage handle missing dependencies during runtime detection?

When a tool's `_detect()` method cannot locate its required binary or library, it returns a `ToolResult` with `installed=False`. The tool manager records this state in `CapabilityState`, effectively hiding the associated UI panels and CLI flags from the user until the dependency is installed and the application restarts.

### Can users force a manual capability rescan without restarting OpenMontage?

According to the source code in [`backlot/server.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/server.py), detection runs primarily at server initialization. While the `CapabilityState` class in [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py) supports dynamic updates via `CapabilityState.update()`, the standard workflow requires an application restart to trigger the full `detect_all_tools()` loop and refresh the entire capability registry.

### What types of environment checks do tools perform during detection?

Tools implement varied inspection strategies depending on their requirements. For example, `CapRecorder` checks for executable binaries on PATH, `ImageGen` uses `importlib.util.find_spec()` to detect Python packages, and `VideoStitch` verifies FFmpeg availability for audio stream processing. Each tool customizes its `_detect()` method to match its specific runtime dependencies.

### Where is the capability registry stored and how is it accessed?

The capability registry resides in [`backlot/state.py`](https://github.com/calesthio/OpenMontage/blob/main/backlot/state.py) as the `CapabilityState` class, which functions as a global singleton. Downstream components—including UI renderers, orchestrators, and CLI command handlers—import and query this state to determine feature availability, ensuring consistent behavior across the application stack.