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

> Discover the purpose of OpenMontage's support_envelope() method. Learn how this Boolean flag indicates if a tool can process enveloped payloads with metadata for efficient data handling.

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

---

**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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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:

```python
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`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py) and persists for the application lifetime.

### Runtime Message Routing

In [`pipeline/dispatcher.py`](https://github.com/calesthio/OpenMontage/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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.