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

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 and 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 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:

# 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, the system dynamically selects available image generation providers by inspecting Python package imports:

# 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 collects individual tool results into a global capability map:

# 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	Initializes the server, loads the tool registry, and triggers detection at application launch
backlot/state.py	Maintains the global CapabilityState singleton accessed by UI components and orchestrators
tools/capture/cap_recorder.py	Implements binary detection for the CapRecorder tool via _detect()
tools/graphics/image_gen.py	Provides package-import detection for image generation providers
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 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, detection runs primarily at server initialization. While the CapabilityState class in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}