Tool System#

OpenMontage exposes production capabilities exclusively through Python tools. The LLM coding assistant acts as orchestrator: it reads a pipeline manifest to determine stage order, consults the matching stage-director skill, then calls tools from the live registry. Python supplies only the executable surface and persistence; all decision logic lives in the skills and manifests.

BaseTool Contract#

Every tool inherits from BaseTool and must declare a fixed set of fields plus implement one method.

Key identity and classification fields:

• name and version — unique identifier and semantic version.
• tier — one of CORE, VOICE, ENHANCE, GENERATE, SOURCE, ANALYZE, or PUBLISH.
• capability — high-level function such as tts, image_generation, or video_generation.
• provider — backend (e.g., elevenlabs, fal, ffmpeg, selector).
• runtime — LOCAL, LOCAL_GPU, API, or HYBRID.
• stability — EXPERIMENTAL, BETA, or PRODUCTION.

Operational fields:

• dependencies — list of required commands (cmd:ffmpeg), environment variables (env:ELEVENLABS_API_KEY), or packages (python:torch).
• input_schema and output_schema — JSON Schema definitions for inputs and outputs.
• fallback_tools — ordered list of alternatives the registry can resolve.
• agent_skills — references to Layer 3 knowledge skills the agent must read before use.
• resource_profile — CPU, RAM, VRAM, disk, and network requirements.
• retry_policy — maximum retries and backoff strategy.

The single required method is execute(inputs) -> ToolResult. The result object carries success, data, artifacts (file paths), error, cost_usd, duration_seconds, seed, and model.

Tool Registry and Auto-Discovery#

ToolRegistry is a singleton that discovers every concrete BaseTool subclass automatically via pkgutil.walk_packages. No manual registration is required; adding a new tool file makes it visible immediately.

After registry.discover(), common queries include:

• get_by_capability("tts") — all tools for that capability.
• get_by_provider("elevenlabs").
• get_available() — only tools whose declared dependencies are satisfied.
• find_fallback("elevenlabs_tts") — first usable entry in the fallback chain.
• support_envelope() — complete contract dump for agent consumption.

The registry also surfaces gpu_required_tools() and network_required_tools() for preflight planning.

Selector Pattern#

Three selector tools abstract families that have multiple providers:

• tts_selector
• image_selector
• video_selector

Each selector queries the live registry, then ranks providers by task fit, output quality, control, reliability, cost efficiency, latency, and continuity. An explicit preferred_provider (when supplied and available) takes precedence; otherwise the scored ranking determines the choice. Selectors adapt input keys transparently (for example, prompt versus query) and return the selected tool name, provider, selection reason, and scored alternatives.

Tier and Capability Classification#

Tiers group tools by role in the production flow. Capabilities further subdivide them for routing and governance.

Analysis tools (transcriber, scene_detect, frame_sampler, video_understand) sit in the ANALYZE tier. Audio tools (multiple TTS providers plus music_gen, audio_mixer) are primarily VOICE. Graphics and video generation tools fall under GENERATE. Composition and stitching tools are CORE. Enhancement tools (upscale, bg_remove, face_restore, color_grade) occupy ENHANCE.

The registry exposes tier_summary() and capability_catalog() so agents and preflight checks can enumerate exactly what is configured for the current environment.

To inspect the live capability envelope before starting a pipeline, run:

make preflight

or directly:

python -c "
from tools.tool_registry import registry
import json
registry.discover()
print(json.dumps(registry.provider_menu_summary(), indent=2))
"

This reports composition runtimes, per-capability configured versus total counts, and any immediate setup suggestions.

See Architecture for the overall agent-first model and 3-Layer Knowledge for how tool agent_skills entries connect to external technology documentation. For the full list of concrete tools and their current stability, consult the Tool Inventory. Detailed registry query methods and reporting shapes are documented in the Tool Registry Reference.