filter-runtime

filter-runtime is the core framework that powers modular filters using an event-driven architecture. It provides foundational tools for:

• ZeroMQ-based communication between filters
• Declarative configuration via environment variables
• Thread-safe lifecycle management
• Logging, metrics, and extensibility
• Multi-filter orchestration

Key Features

• Filter Base Class: All filters inherit from this. Implements lifecycle hooks (setup, process, shutdown), message queuing, and configuration parsing.
• FilterConfig: Type-friendly dictionary-like configuration object.
• Multi-filter Runner: Run multiple filters in parallel with coordinated exit policies.
• ZeroMQ Integration: Stream images and data between filters with source/output routing and load balancing.
• Support for Downloading Resources: Built-in integration for downloading jfrog:// artifacts via dlcache.

Filter Lifecycle

Each filter follows a lifecycle:

1. Initialization via __init__ and normalize_config
2. Setup via setup(config)
3. Frame Processing via process(frames: dict[str, Frame])
4. Shutdown via shutdown()

Communication Patterns

• Sources/Outputs are defined using URIs like:
  • tcp://127.0.0.1
  • ipc://name
  • Topic mapping via ;, e.g. tcp://127.0.0.1;foo>bar
• Filters can be chained together or run in multi-filter configurations.

Environment Variables

filter-runtime supports numerous env vars like:

Variable	Description
LOG_LEVEL	Set log level (INFO, DEBUG, etc.)
AUTO_DOWNLOAD	Enable downloading jfrog:// artifacts
PROP_EXIT, OBEY_EXIT, STOP_EXIT	Control exit behavior
ZMQ_*	Tune ZeroMQ behavior (timeouts, latency, etc.)

Refer to the source for full documentation on advanced options.

Example Usage

FILTER_ID=example-filter \
FILTER_SOURCES="tcp://input" \
FILTER_OUTPUTS="tcp://output" \
python -m my_filter_package.my_filter

Or using run_multi() to run multiple filters together.