videoflow.components package

Submodules

videoflow.components.descriptor module

Loading and validation of component descriptors (component.yaml).

A descriptor is how a language-agnostic component describes itself so videoflow can wire it into a graph, pick its image, and validate its use — without importing any of the component’s code (which may not even be Python). See spec/descriptor/component-schema.json for the full schema and Phase 2 of the migration plan.

This module deliberately avoids a hard dependency on jsonschema: it validates component params against the descriptor’s declared JSON Schema with a small built-in checker covering the common subset (type/required/enum/default), and uses jsonschema for full validation only if it happens to be installed.

class videoflow.components.descriptor.ComponentDescriptor(raw: dict, source: str | None = None)[source]

Bases: object

A parsed, validated component descriptor. Construct via load_descriptor (from a path) or ComponentDescriptor.from_dict (from an already-parsed mapping).

all_inputs_accept(capability: str) → bool[source]

command: List[str] | None

description: str | None

device: List[str]

finite: bool

classmethod from_dict(raw: dict, source: str | None = None) → ComponentDescriptor[source]

image_for(device_type: str) → str | None[source]: The image ref for a device type (‘cpu’/’gpu’), or None if not declared.

images: Dict[str, str]

input_accepts(index: int, capability: str) → bool[source]: Whether input index declares it accepts 'missing' or 'collected' inputs (default False).

inputs: List[dict]

property is_native: bool

runs its own image entrypoint and must speak the protobuf wire.

Type:: A native (non-Python) component

license: str | None

local_command: List[str] | None

name: str

output: dict | None

params_schema: dict

partitionable: bool

protocol: int

python_class: str | None

role: str

singleton: bool

validate_params(params: dict | None) → dict[source]: Validate params against the descriptor’s JSON Schema and return a copy with defaults filled in. Raises ValueError on a violation, naming the component so the error is actionable at graph-build time.

version: str

videoflow.components.descriptor.IO_ANY = 'any': Payload-type token meaning “any payload” in a descriptor’s io section.

videoflow.components.descriptor.load_descriptor(ref: str) → ComponentDescriptor[source]

Load a descriptor from a reference:

a path to a component.yaml file, or
a path to a directory containing component.yaml.

oci://... refs (a descriptor published as an OCI artifact) are resolved in Phase 6; for now they raise a clear error.

videoflow.components.oci module

Distribution of component descriptors as OCI artifacts (marketplace foundation).

A component’s component.yaml is pushed to any OCI registry as an artifact with media type application/vnd.videoflow.component.v1+yaml, referencing its cpu/gpu container images (which are pushed separately as normal images). Users then pull a component by reference — oci://ghcr.io/vendor/name:1.2.0 — and videoflow resolves the descriptor (and, through it, the image) without the component’s source.

This module is intentionally thin: it wraps ORAS-py for push/pull and shells out to cosign for optional signature verification, rather than reimplementing either. Pulled descriptors are cached under ~/.videoflow/components/ so a repeated component('oci://...') resolve is offline after the first fetch.

videoflow.components.oci.COMPONENT_ARTIFACT_TYPE = 'application/vnd.videoflow.component.v1': artifactType set on the artifact manifest (helps registries/tools classify it).

videoflow.components.oci.COMPONENT_MEDIA_TYPE = 'application/vnd.videoflow.component.v1+yaml': OCI media type for a videoflow component descriptor artifact.

videoflow.components.oci.cache_dir_for(ref: str, cache_root: str | None = None) → str[source]: A stable per-ref cache directory (the ref sanitized into a filesystem-safe key).

videoflow.components.oci.cosign_verify(target: str, extra_args: List[str] | None = None) → None[source]: Verify an OCI artifact/image signature with cosign. extra_args carries the trust policy (e.g. --key cosign.pub or --certificate-identity=... --certificate-oidc-issuer=...). Raises on failure.

videoflow.components.oci.default_cache_root() → str[source]

videoflow.components.oci.inspect_component(ref: str, **pull_kwargs: Any) → ComponentDescriptor[source]: Pull (cached) and return the parsed ComponentDescriptor for ref.

videoflow.components.oci.is_oci_ref(ref: str) → bool[source]

videoflow.components.oci.parse_oci_ref(ref: str) → str[source]: oci://ghcr.io/vendor/name:1.2.0 -> ghcr.io/vendor/name:1.2.0 (the registry target).

videoflow.components.oci.pull_component(ref: str, cache_root: str | None = None, force: bool = False, verify: bool = False, cosign_args: List[str] | None = None) → str[source]: Resolve ref to a local component.yaml path, pulling + caching it on first use. With verify, the artifact’s signature is checked via cosign before the descriptor is trusted. Returns the path to the cached descriptor.

videoflow.components.oci.push_component(descriptor_path: str, ref: str, annotations: dict | None = None) → str[source]: Push a component.yaml to ref as an OCI artifact. The descriptor is validated first (a broken descriptor is never published). Returns the target.