Preflight Diagnostics#

Run preflight diagnostics before every production to inspect the live capability envelope. The checks surface installed runtimes, configured providers, missing environment variables, and runtime warnings so the agent can select tools accurately.

Running the Registry Preflight#

Use the Makefile target or the direct Python invocation:

make preflight

This is equivalent to:

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

The call to registry.discover() loads .env and auto-registers every BaseTool subclass. See Tool Registry for additional query methods such as provider_menu() and support_envelope().

HyperFrames Diagnostics#

Check the HyperFrames composition runtime separately:

make hyperframes-doctor

Or invoke the tool directly:

python -c "
from tools.video.hyperframes_compose import HyperFramesCompose
r = HyperFramesCompose().execute({'operation': 'doctor'})
import json
print(json.dumps(r.data, indent=2))
"

Interpreting the Summary Output#

provider_menu_summary() returns a compact object with these keys:

composition_runtimes: booleans for ffmpeg, remotion, and hyperframes
capabilities: array of objects showing configured / total counts plus the list of available providers for each capability
setup_offers: short suggestions, typically one-line environment variable additions
runtime_warnings: detected issues such as missing binaries or unsatisfied dependencies

A zero in any configured count or a non-empty runtime_warnings list indicates the agent will fall back or block execution for that capability.

Common Fixes#

Add required keys to .env and re-run the summary when setup_offers lists them. See Configuring Providers for the full list of variables and what each unlocks.

For missing system dependencies (FFmpeg, Node.js, or Remotion), consult Installation Troubleshooting.

Governance-related blocks that appear during preflight are covered in Governance Issues.

Re-run preflight after any change to .env or installed packages so the registry reflects the current state.