Understanding the `support_envelope()` Method in OpenMontage’s Tool Registry

The support_envelope() method acts as a Boolean capability flag that tells the OpenMontage framework whether a specific tool can accept and process enveloped payloads—data structures wrapped with metadata such as timestamps, user IDs, and routing hints.

The OpenMontage repository implements a dynamic plugin architecture to manage video processing workflows. Within this system, the support_envelope() method defined in tools/tool_registry.py serves as the primary mechanism for tools to advertise their ability to handle wrapped metadata containers, enabling the dispatcher to route messages correctly without forcing non-compliant tools to parse complex envelope structures.

What Is Envelope Support in OpenMontage?

In OpenMontage, an envelope is a standardized container that wraps raw processing data with additional metadata fields. These fields may include timestamps, user IDs, session context, or routing hints necessary for pipeline orchestration.

The support_envelope() method returns a Boolean value indicating whether a tool instance can properly unpack and interpret these wrapped payloads. According to the source code in tools/tool_registry.py, the default implementation on the BaseTool class returns False, signifying that the tool expects only raw, unwrapped data.

Implementation in the OpenMontage Source Code

In tools/tool_registry.py, the BaseTool class defines the support_envelope() method as a lightweight hook that subclasses override to opt-in to envelope processing:

class BaseTool:
    """Abstract base class for all OpenMontage processing tools."""
    
    def support_envelope(self) -> bool:
        """
        Return True if the tool can accept an Envelope-wrapped payload.
        
        The default implementation returns False, meaning the tool only
        expects a raw payload without metadata wrapping.
        """
        return False

Concrete tool implementations override this method to return True when they implement the logic necessary to extract the .data attribute from envelope objects and handle associated metadata responsibly.

How the Registry Uses support_envelope()

The OpenMontage engine queries this method during two critical phases: startup registration and runtime dispatch.

Startup Capability Detection

During the initialization sequence, the ToolRegistry iterates over all registered tool classes and instantiates temporary objects to invoke support_envelope(). Tools returning True are cataloged as envelope-aware, while those returning False are flagged for the plain execution path. This classification happens in tools/tool_registry.py and persists for the application lifetime.

Runtime Message Routing

In pipeline/dispatcher.py, the dispatcher checks a tool’s envelope support before transmitting data:

• Envelope-aware path: If tool.support_envelope() returns True, the dispatcher sends an Envelope instance containing both the payload and metadata context.
• Plain path: If the method returns False, the dispatcher extracts only the raw .data field from the envelope, ensuring the receiving tool receives a compatible input structure.

This bifurcation prevents non-envelope-aware tools from crashing when encountering unexpected metadata fields while allowing sophisticated tools to leverage full context information.

Practical Usage Examples

Checking Tool Capabilities at Runtime

Before sending data to a dynamically loaded tool, query its envelope support to determine the appropriate payload format:

from tools.tool_registry import registry

tool = registry.get('noise_reduction_filter')
if tool.support_envelope():
    # Send full envelope with temporal metadata

    payload = Envelope(data=video_frame, meta={'timestamp': 1234, 'track': 'main'})
    result = tool.process(payload)
else:
    # Send only the raw frame data

    result = tool.process(video_frame)

Implementing Envelope Support in Custom Tools

To create a tool that receives full metadata context, subclass BaseTool and override the method:

from tools.tool_registry import BaseTool

class MetadataAwareScaler(BaseTool):
    """A video scaler that respects frame timing metadata."""
    
    def support_envelope(self) -> bool:
        """Signal that we can handle enveloped inputs."""
        return True
    
    def process(self, envelope):
        """Process method receives the full Envelope object."""
        frame_data = envelope.data
        timestamp = envelope.meta.get('timestamp')
        
        # Perform scaling while preserving metadata for downstream tools

        scaled_data = self._scale(frame_data)
        return Envelope(data=scaled_data, meta=envelope.meta)

Pipeline Construction with Registry Queries

When building processing pipelines programmatically, use the registry to separate envelope-aware stages:

from tools.tool_registry import registry

# Categorize tools during pipeline construction

envelope_stages = []
plain_stages = []

for tool_name, tool_class in registry.all():
    tool_instance = tool_class()
    if tool_instance.support_envelope():
        envelope_stages.append(tool_class)
    else:
        plain_stages.append(tool_class)

# Execute with appropriate data wrapping

for stage in envelope_stages:
    payload = Envelope(data=current_data, meta=context)
    current_data = stage().process(payload)

Summary

• Purpose: The support_envelope() method serves as a capability flag in tools/tool_registry.py that advertises whether a tool can process metadata-wrapped payloads.
• Default behavior: The BaseTool implementation returns False, ensuring backward compatibility for tools expecting raw data only.
• Framework integration: The dispatcher in pipeline/dispatcher.py uses this Boolean to route data correctly, sending full Envelope objects only to tools that explicitly opt-in via this method.

Frequently Asked Questions

What is an enveloped payload in OpenMontage?

An enveloped payload is a container object that wraps raw processing data with a metadata dictionary containing context such as timestamps, user IDs, and routing information. The envelope pattern allows metadata to propagate through the pipeline without polluting the raw data structure itself.

What happens if a tool does not implement support_envelope()?

If a tool class does not override the method, it inherits the default implementation from BaseTool in tools/tool_registry.py, which returns False. The OpenMontage dispatcher treats this as a signal that the tool requires raw data only, automatically extracting the payload from any envelope before transmission to prevent parsing errors.

How does the dispatcher use support_envelope()?

According to the source code implementation in pipeline/dispatcher.py, the dispatcher invokes tool.support_envelope() before calling the tool's process() method. If the return value is True, the dispatcher passes the complete Envelope object; otherwise, it unwraps the data attribute to maintain compatibility with legacy tools.

Can a tool change its envelope support dynamically at runtime?

While the method is called on an instance and could theoretically be implemented with dynamic logic, the OpenMontage registry queries this capability during initialization and caches the result for pipeline optimization. Changing the return value after registration would produce inconsistent behavior, so implementations should return a constant Boolean reflecting the tool's static capabilities.

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