File size: 18,633 Bytes
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
444bc2b
 
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
444bc2b
af26f09
 
 
 
 
 
 
 
adad9b6
444bc2b
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
419e0a5
 
 
 
 
 
 
 
 
 
 
 
 
 
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
419e0a5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
75d0c53
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
adad9b6
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
75d0c53
 
 
af26f09
 
adad9b6
 
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
419e0a5
af26f09
419e0a5
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
75d0c53
af26f09
 
 
 
 
 
 
 
adad9b6
 
 
 
 
 
 
 
75d0c53
 
 
 
 
 
 
 
 
af26f09
 
 
adad9b6
af26f09
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
75d0c53
 
 
af26f09
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
#!/usr/bin/env python
"""One local generation (mps/cpu) through the app's own ``generate()``.

    python scripts/local_generate.py --mode text_to_video --prompt "a red tram ..." \\
        --width 704 --height 480 --num-frames 121 --device mps \\
        --snapshot-dir <LTX-2.5-Diffusers snapshot> \\
        [--transformer-gguf <...-Q8_0.gguf>] [--dry-run] [--json run.json]

The local runner (``ltx25_studio.local_runtime``) is handed to ``generate()``
through its ``pipeline_factory`` seam, so this works whether or not
``pipelines.get_pipeline`` knows about local devices yet.

Prints the resolved plan, every memory-preflight line, the wall time of each
phase, the peak committed memory (``vm_stat``, sampled every 0.5 s) and MPS
driver memory, the files written and the stream verdict; ``--json`` writes the
same. ``--dry-run`` prints the plan and the preflight arithmetic and loads
nothing. Nothing is ever downloaded: a missing file is reported with the exact
``hf download`` command.

Exit codes: 0 ok, 2 refused (memory preflight, validation, missing files, an
MPS PyTorch that fails the numerics self-test), 3 generation error.
"""

from __future__ import annotations

import argparse
import contextlib
import importlib.util
import json
import sys
import threading
import time
import traceback
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
if str(REPO_ROOT) not in sys.path:
    sys.path.insert(0, str(REPO_ROOT))

from ltx25_studio import device, local_runtime, memory, modes  # noqa: E402
from ltx25_studio.errors import ConfigError, ConstraintError, LoRAError  # noqa: E402

EXIT_OK, EXIT_REFUSED, EXIT_ERROR = 0, 2, 3

#: Refusals: the run was stopped before or instead of generating, for a reason the
#: operator can act on. Everything else is a generation error.
REFUSALS = (
    memory.MemoryPreflightError,
    memory.MpsWatermarkError,
    device.MpsNumericsError,
    ConstraintError,
    ConfigError,
    LoRAError,
    local_runtime.UnsupportedLocalDeviceError,
    local_runtime.LocalFilesMissingError,
)


def _parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    p.add_argument("--mode", required=True, choices=sorted(modes.MODES))
    p.add_argument("--prompt", default="")
    p.add_argument("--image", type=Path)
    p.add_argument("--video", type=Path)
    p.add_argument("--audio", type=Path)
    p.add_argument("--width", type=int, default=704)
    p.add_argument("--height", type=int, default=480)
    p.add_argument("--num-frames", type=int, default=121)
    p.add_argument("--seed", type=int, default=-1, help="-1 picks one at random")
    p.add_argument("--auto-duration", action="store_true")
    p.add_argument("--min-seconds", type=float, default=1.0)
    p.add_argument("--max-seconds", type=float, default=5.0)
    p.add_argument(
        "--noise-scale",
        type=float,
        default=None,
        help="how much to change the input: video_to_video's clip, audio_to_audio's sound "
        "(default: the mode's own level; snapped to the supported levels)",
    )
    p.add_argument(
        "--strength",
        type=float,
        default=0.8,
        help="read by no mode now (video_to_video takes --noise-scale); kept so scripts "
        "that pass it still parse",
    )
    p.add_argument("--enhance", action="store_true", help="rewrite the prompt with the enhancer")
    p.add_argument("--lora", action="append", default=[], metavar="PATH[:WEIGHT]")
    p.add_argument("--device", choices=local_runtime.LOCAL_DEVICES, default="mps")
    p.add_argument("--dtype", default="bfloat16")
    p.add_argument("--snapshot-dir", type=Path, required=True)
    p.add_argument("--transformer-gguf", type=Path)
    p.add_argument("--residency", choices=local_runtime.RESIDENCIES, default="staged")
    p.add_argument("--memory-limit-gb", type=float)
    p.add_argument("--out", type=Path, help="output root (default: the app's own)")
    p.add_argument("--json", type=Path, help="write the report here as JSON")
    p.add_argument("--dry-run", action="store_true", help="print the plan; load nothing")
    return p


def _artifacts(result) -> dict:
    """What the run wrote, for the report and its --json file."""
    return {
        "output": str(result.output_path),
        "video": str(result.video_path) if result.video_path else None,
        "audio": str(result.audio_path) if result.audio_path else None,
        "seed": result.seed,
        "warnings": list(result.warnings),
    }


def _record(result) -> dict | None:
    """The run record (``generate.RunRecord``) as a dict, for the --json file."""
    import dataclasses

    record = getattr(result, "record", None)
    return dataclasses.asdict(record) if dataclasses.is_dataclass(record) else None


def _lora(spec: str) -> dict:
    path, sep, weight = spec.rpartition(":")
    if sep and path:
        try:
            return {"source": path, "weight": float(weight)}
        except ValueError:
            pass
    return {"source": spec, "weight": 1.0}


class _Report:
    def __init__(self):
        self.data: dict = {"preflight": [], "log": []}

    def line(self, text: str = "") -> None:
        print(text, flush=True)

    def log(self, text: str) -> None:
        self.data["log"].append(text)
        if text.startswith("preflight["):
            self.data["preflight"].append(text)
        self.line(f"  | {text}")


class _Sampler(threading.Thread):
    """Peak committed memory and MPS driver memory, sampled every 0.5 s."""

    def __init__(self, interval: float = 0.5):
        super().__init__(daemon=True)
        self.interval = interval
        self.peak_committed_gb = None
        self.peak_mps_driver_gb = None
        self._halt = threading.Event()

    def _sample(self) -> None:
        committed = memory.committed_gb()
        if committed is not None:
            self.peak_committed_gb = max(self.peak_committed_gb or 0.0, committed)
        stats = memory.mps_stats()
        if stats is not None:
            self.peak_mps_driver_gb = max(self.peak_mps_driver_gb or 0.0, stats["driver_gb"])

    def run(self) -> None:
        while not self._halt.is_set():
            with contextlib.suppress(Exception):  # a gauge must never kill the run
                self._sample()
            self._halt.wait(self.interval)

    def stop(self) -> None:
        self._halt.set()
        self.join(timeout=5)
        with contextlib.suppress(Exception):
            self._sample()


def _verify_streams():
    spec = importlib.util.spec_from_file_location(
        "_ltx25_verify_streams", REPO_ROOT / "tests" / "verify_streams.py"
    )
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module  # dataclasses resolve annotations through sys.modules
    spec.loader.exec_module(module)
    return module


def _release_file_cache(args, report: _Report, when: str) -> None:
    """Give back the page-cache pages of every file this run loads; print the gauge."""
    files = local_runtime.run_files(args.snapshot_dir, args.transformer_gguf)
    before = memory.committed_gb()
    released = memory.release_file_cache(files)
    after = memory.committed_gb()

    def gb(value):
        return f"{value:.1f} GB" if value is not None else "n/a"

    line = (
        f"file cache {when}: released {released / memory.GB:.1f} GB across {len(files)} files; "
        f"committed {gb(before)} -> {gb(after)}"
    )
    report.data.setdefault("file_cache", []).append(
        {
            "when": when,
            "released_gb": released / memory.GB,
            "committed_before_gb": before,
            "committed_after_gb": after,
            "files": len(files),
        }
    )
    report.line(f"== {line}")


def _classify(exc: BaseException) -> int:
    seen = set()
    while exc is not None and id(exc) not in seen:
        seen.add(id(exc))
        if isinstance(exc, REFUSALS):
            return EXIT_REFUSED
        exc = exc.__cause__ or exc.__context__
    return EXIT_ERROR


def _plan(args, report: _Report) -> tuple[list[tuple[str, str]], bool]:
    """Print the plan and the projected preflight; return (missing, every step fits)."""
    spec = modes.get_mode(args.mode)
    dtype_bytes = 4 if args.dtype.lower() in ("float32", "fp32", "float") else 2
    if args.auto_duration:
        frames = local_runtime.frames_for_estimate(
            {"max_seconds": args.max_seconds}, {"frame_rate": 24.0}
        )
    else:
        frames = args.num_frames
    width, height = (
        (modes.MIN_RESOLUTION, modes.MIN_RESOLUTION)
        if spec.min_resolution
        else (args.width, args.height)
    )
    sizes = local_runtime.weight_sizes(args.snapshot_dir, args.transformer_gguf)
    missing = local_runtime.missing_files(args.snapshot_dir, transformer_gguf=args.transformer_gguf)
    limit = args.memory_limit_gb if args.memory_limit_gb is not None else memory.default_limit_gb()
    watermarks = memory.mps_watermarks()

    report.line("== plan")
    plan = {
        "mode": args.mode,
        "pipeline_kind": spec.pipeline,
        "device": args.device,
        "dtype": args.dtype,
        "residency": args.residency,
        "size": f"{width}x{height}x{frames}"
        + (" (upper bound, auto duration)" if args.auto_duration else ""),
        "snapshot_dir": str(args.snapshot_dir),
        "transformer": str(args.transformer_gguf)
        if args.transformer_gguf
        else "snapshot transformer/",
        "memory_limit_gb": limit,
        "load_spike_factor": {
            source: memory.load_spike_factor(source) for source in memory.LOAD_SPIKE_FACTORS
        },
        "activation_calibration": memory.activation_calibration(),
        "stage_2": "not available locally (CUDA-only decoder)",
        "mps_watermarks": {"high": watermarks.high, "low": watermarks.low},
        "recommended_max_gb": (memory.mps_stats() or {}).get("recommended_max_gb"),
        "loras": [_lora(item) for item in args.lora],
        "weights_gb": {name: round(size / memory.GB, 3) for name, (size, _) in sizes.items()},
        "weights_source": {name: source for name, (_, source) in sizes.items()},
    }
    for key, value in plan.items():
        report.line(f"  {key}: {value}")
    report.data["plan"] = plan
    terms = memory.activation_terms(width, height, frames, dtype_bytes=dtype_bytes)
    report.line(
        "  activation terms (GB): "
        + ", ".join(f"{name} {value:.3f}" for name, value in terms.items())
        + f", fixed {memory.FIXED_ACTIVATION_GB:.1f}"
    )
    report.data["activation_terms_gb"] = terms

    if missing:
        report.line(f"== {len(missing)} file(s) missing (nothing is downloaded)")
        for path, command in missing:
            report.line(f"  {path}\n      {command}")
    report.data["missing"] = [{"path": str(p), "command": c} for p, c in missing]

    committed_now = memory.committed_gb()
    report.line(
        "== preflight arithmetic (projected; committed now "
        + (f"{committed_now:.1f} GB" if committed_now is not None else "n/a")
        + " + what earlier steps leave resident)"
    )
    steps = local_runtime.preflight_plan(
        args.snapshot_dir,
        transformer_gguf=args.transformer_gguf,
        residency=args.residency,
        width=width,
        height=height,
        num_frames=frames,
        dtype_bytes=dtype_bytes,
    )
    fits = True
    projected = []
    for step in steps:
        result = memory.preflight(
            step.phase,
            need_gb=step.need_gb,
            limit_gb=limit,
            committed_gb=None if committed_now is None else committed_now + step.resident_before_gb,
        )
        fits = fits and result.verdict != "FAIL"
        line = f"{result.describe()}  [resident before: {step.resident_before_gb:.1f} GB]"
        projected.append(line)
        report.line(f"  {line}")
    report.data["projected_preflight"] = projected
    return missing, fits


def _run(args, report: _Report) -> int:
    spec = modes.get_mode(args.mode)
    from ltx25_studio import generate as generate_module

    loras = tuple(_lora(item) for item in args.lora)

    def factory(*, pipeline, **_):
        runner = local_runtime.build_local_runner(
            kind=pipeline,
            device=args.device,
            dtype=args.dtype,
            snapshot_dir=args.snapshot_dir,
            transformer_gguf=args.transformer_gguf,
            residency=args.residency,
            memory_limit_gb=args.memory_limit_gb,
            log=report.log,
        )
        if loras:
            runner.ensure_transformer()  # adapters attach to a loaded transformer
        report.data["runner"] = runner
        return runner

    fields = {
        "mode": args.mode,
        "prompt": args.prompt,
        "width": args.width,
        "height": args.height,
        "num_frames": args.num_frames,
        "seed": args.seed,
        "auto_duration": args.auto_duration,
        "min_seconds": args.min_seconds,
        "max_seconds": args.max_seconds,
        "noise_scale": args.noise_scale,
        "strength": args.strength,
        "enhance_prompt": args.enhance,
        "loras": loras,
    }
    if args.image is not None:
        from PIL import Image

        with Image.open(args.image) as opened:
            fields["image"] = opened.convert("RGB")
    if args.video is not None:
        fields["video"] = str(args.video)
    if args.audio is not None:
        fields["audio"] = str(args.audio)

    report.line("== generating")
    sampler = _Sampler()
    sampler.start()
    started = time.perf_counter()
    try:
        result = generate_module.generate(
            pipeline_factory=factory,
            output_root=args.out,
            **fields,
        )
    finally:
        sampler.stop()
        report.data["wall_seconds_generate"] = round(time.perf_counter() - started, 3)
        report.data["peak_committed_gb"] = sampler.peak_committed_gb
        report.data["peak_mps_driver_gb"] = sampler.peak_mps_driver_gb
        runner = report.data.pop("runner", None)
        report.data["phases"] = list(runner.timings) if runner is not None else []
        vocoder = getattr(getattr(runner, "pipeline", None), "vocoder", None)

    report.line("== phases")
    for entry in report.data["phases"]:
        report.line(f"  {entry['phase']}: {entry['seconds']:.2f} s")
    report.line(f"  generate() total: {report.data['wall_seconds_generate']:.2f} s")
    report.line(
        "  peak committed: "
        + (
            f"{sampler.peak_committed_gb:.1f} GB"
            if sampler.peak_committed_gb is not None
            else "n/a"
        )
        + " | peak MPS driver: "
        + (
            f"{sampler.peak_mps_driver_gb:.2f} GB"
            if sampler.peak_mps_driver_gb is not None
            else "n/a"
        )
    )

    artifacts = _artifacts(result)
    report.data["artifacts"] = artifacts
    report.data["record"] = _record(result)
    report.line("== artifacts")
    for key, value in artifacts.items():
        report.line(f"  {key}: {value}")

    verify_streams = _verify_streams()
    rate = None
    if "audio" in spec.exports:
        rate = getattr(getattr(vocoder, "config", None), "output_sampling_rate", None)
    geometry = None
    if "video" in spec.exports and not spec.min_resolution:
        geometry = (args.width, args.height)
    verdict = verify_streams.verify(
        args.mode, result.output_path, frame_rate=24.0, sampling_rate=rate, geometry=geometry
    )
    report.data["verify_streams"] = {
        "exit_code": verdict.exit_code,
        "ok": verdict.ok,
        "expected": verdict.expected,
        "actual": verdict.actual,
        "problems": verdict.problems,
    }
    report.line("== verify_streams")
    report.line("  " + verdict.render().replace("\n", "\n  "))
    return EXIT_OK


def main(argv=None) -> int:
    args = _parser().parse_args(argv)
    report = _Report()
    report.data["argv"] = list(sys.argv if argv is None else argv)
    code = EXIT_OK
    live = False
    try:
        for flag in ("image", "video", "audio"):
            path = getattr(args, flag)
            if path is not None and not path.is_file():
                raise ConstraintError(f"--{flag} {path} does not exist")
        for item in args.lora:
            if not Path(_lora(item)["source"]).is_file():
                raise ConstraintError(f"--lora {item}: no such file")
        watermarks = memory.mps_watermarks()
        report.line(
            f"== MPS allocator: {memory.HIGH_WATERMARK_ENV}="
            f"{watermarks.high if watermarks.high is not None else 'unset'}, "
            f"{memory.LOW_WATERMARK_ENV}={watermarks.low if watermarks.low is not None else 'unset'}"
        )
        if not args.dry_run:
            watermarks.require()  # before anything is touched
        if args.dry_run:
            report.line(
                "== file cache: left alone (dry run); a live run first gives back the page-cache "
                "pages of every file it will load, so 'committed now' is not inflated by an "
                "earlier run, and gives them back again at exit"
            )
        else:
            live = True
            _release_file_cache(args, report, "before the run")
        missing, fits = _plan(args, report)
        if args.dry_run:
            report.line("== dry run: nothing was loaded")
            watermarks.require()
            code = EXIT_REFUSED if (missing or not fits) else EXIT_OK
        elif missing:
            raise local_runtime.LocalFilesMissingError(missing=missing)
        else:
            code = _run(args, report)
    except BaseException as exc:  # noqa: BLE001 - every failure becomes an exit code and a record
        if isinstance(exc, KeyboardInterrupt):
            raise
        code = _classify(exc)
        report.data["error"] = {
            "type": type(exc).__name__,
            "message": str(exc),
            "traceback": traceback.format_exc(),
        }
        report.line(
            f"== {'refused' if code == EXIT_REFUSED else 'error'}: {type(exc).__name__}: {exc}"
        )
    if live:
        with contextlib.suppress(Exception):
            _release_file_cache(args, report, "at exit")
    report.data["exit_code"] = code
    if args.json is not None:
        args.json.parent.mkdir(parents=True, exist_ok=True)
        args.json.write_text(json.dumps(report.data, indent=2, default=str))
        report.line(f"== report written to {args.json}")
    return code


if __name__ == "__main__":
    sys.exit(main())