0

Build a Python Integrity Check for AI Video Reference Bundles

A reference image is reviewed and approved for a video-generation task. Before upload, someone replaces it with another export using the same filename.

The approval message still refers to that filename, but the file contents have changed.

This tutorial builds a small Python command-line tool to detect that situation. It records the relative paths and SHA-256 hashes of files in a reference bundle, then compares the bundle against that snapshot before submission.

The implementation uses the Python standard library. It runs locally and does not upload files or call a video-generation API.

1. What problem are we solving?

A video-generation request may contain a prompt, several images, video clips, or audio references.

For example, the Kling 4.0 AI Video Generator on ZMS supports text, mixed references, and ordered keyframes. Reviewing only one image would leave the other inputs outside the process.

The same issue applies to any application that accepts a collection of files.

We need to distinguish two responsibilities:

  • Human review determines whether the inputs are appropriate for the intended task.
  • Integrity verification determines whether the inputs still match the reviewed version.

A matching hash does not mean a file is safe or authorized for upload. It means the file contents match the recorded baseline.

The workflow is:

  1. Prepare the reference bundle.
  2. Create a snapshot.
  3. Review the bundle without changing it.
  4. Verify it immediately before submission.
  5. Submit the matching files.

If review requires an edit, create a new snapshot and review that version.

2. Prepare a working directory

Use Python 3.10 or later. No additional packages are required.

Create the project directory:

mkdir reference-review
cd reference-review
mkdir bundle

Place the intended inputs inside bundle. For a real task, this might include:

  • prompt.txt
  • reference-01.png
  • reference-02.png

Include the complete prompt in a text file so that instruction changes are also detected.

To try the checker without preparing media files, create a sample prompt:

python -c "from pathlib import Path; Path('bundle/prompt.txt').write_text('Slow camera move toward a desk lamp.', encoding='utf-8')"

Keep the manifest outside the bundle directory. Otherwise, it would become part of the content being measured.

3. Implement the checker

Save the following code as bundle_check.py:

import argparse
import hashlib
import json
import sys
from pathlib import Path


def inventory(root):
    if not root.is_dir():
        raise ValueError("Bundle directory does not exist")

    result = {}

    for path in sorted(root.rglob("*")):
        if path.is_symlink():
            raise ValueError(f"Symlink is not allowed: {path}")

        if path.is_file():
            digest = hashlib.sha256()

            with path.open("rb") as stream:
                for block in iter(
                    lambda: stream.read(1024 * 1024), b""
                ):
                    digest.update(block)

            relative = path.relative_to(root).as_posix()
            result[relative] = digest.hexdigest()

        elif not path.is_dir():
            raise ValueError(f"Unsupported file type: {path}")

    if not result:
        raise ValueError("Bundle must contain at least one file")

    return result


def main():
    parser = argparse.ArgumentParser(
        description="Snapshot and check a reference bundle."
    )
    parser.add_argument("action", choices=["snapshot", "check"])
    parser.add_argument("bundle", type=Path)
    parser.add_argument("manifest", type=Path)
    args = parser.parse_args()

    root = args.bundle.resolve()
    manifest = args.manifest.resolve()

    if manifest.is_relative_to(root):
        raise ValueError("Keep the manifest outside the bundle")

    current = inventory(root)

    if args.action == "snapshot":
        with manifest.open("x", encoding="utf-8") as stream:
            json.dump(
                current, stream, indent=2, sort_keys=True
            )

        print("Snapshot created; human review is still required")
        return 0

    expected = json.loads(
        manifest.read_text(encoding="utf-8")
    )

    if current != expected:
        print(
            "FAIL: file names or contents "
            "differ from the snapshot"
        )
        return 1

    print("PASS: file names and contents match the snapshot")
    return 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except (OSError, ValueError) as error:
        print(f"ERROR: {error}", file=sys.stderr)
        sys.exit(2)

The script reads files in one-megabyte blocks rather than loading an entire media file into memory.

Each relative path becomes a key in the manifest. This makes the comparison sensitive to file additions, removals, and renames as well as content changes.

Symbolic links are rejected. This keeps links to other filesystem locations out of the bundle, although the implementation still assumes a controlled local directory without concurrent changes.

The snapshot uses exclusive creation mode, "x", to prevent accidental overwriting of an existing baseline.

4. Create the baseline

Run:

python bundle_check.py snapshot bundle review-v1.json

Expected output:

Snapshot created; human review is still required

The manifest now contains a mapping from relative filenames to SHA-256 digests.

Review the files while keeping the bundle unchanged. Check the complete prompt, every image, and the full duration of any video or audio input.

For screen recordings, inspect notifications, browser tabs, account details, and background windows. A clean opening frame does not establish that the rest of the recording is suitable for sharing.

Record the review decision separately and reference the manifest version. Creating a snapshot is not an approval action.

If a file needs correction, update it and create a new manifest:

python bundle_check.py snapshot bundle review-v2.json

Review the revised bundle before using that baseline.

5. Detect a change

For the unchanged sample bundle, run:

python bundle_check.py check bundle review-v1.json

Expected output:

PASS: file names and contents match the snapshot

Now replace the prompt contents:

python -c "from pathlib import Path; Path('bundle/prompt.txt').write_text('A different scene.', encoding='utf-8')"

Run the check again:

python bundle_check.py check bundle review-v1.json

Expected output:

FAIL: file names or contents differ from the snapshot

The filename is unchanged, but the digest differs.

The same comparison detects a replaced image, an additional audio reference, a renamed file, or a removed asset.

Do not automatically regenerate the manifest after a failure. That would accept the changed bundle without another review.

6. Handle the result in automation

The checker returns:

  • Exit code 0 when snapshot creation succeeds or verification passes.
  • Exit code 1 when the bundle differs from the baseline.
  • Exit code 2 when an input or processing error occurs.

Another Python script can stop when verification fails:

import subprocess

subprocess.run(
    [
        "python",
        "bundle_check.py",
        "check",
        "bundle",
        "review-v1.json",
    ],
    check=True,
)

print("Bundle matches; continue with the next local step.")

With check=True, a nonzero exit code raises CalledProcessError. Unless the caller handles the exception, subsequent statements do not execute.

This example performs verification only. It does not submit the files.

7. Understand the limitations

The manifest is a trusted baseline, not an authenticated approval record. Someone who can replace both the files and the manifest can establish a different baseline.

Store manifests and review decisions with appropriate access controls. A more complete system could bind a manifest digest to an authenticated reviewer and a specific submission purpose.

There is also a gap between checking and uploading. A file can change after verification, or an operator can select a different copy.

For a small manual workflow, keep the reviewed directory unchanged and upload from that location. Stronger implementations should use immutable bundle versions and submit the exact version that passed verification.

The checker does not detect personal information, remove metadata, validate media formats, or establish permission to share. Those remain separate review tasks.

Its purpose is specific: detect when file paths or contents differ from the reviewed snapshot, so that an unnoticed edit becomes a visible verification failure.

References


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí