example.py

"""
Minimal usage example for hv-ttu.

    python example.py

Prints TTU across all delivery modes for two content types (a definition
and a procedure), shows the fit-penalty effect, and demonstrates
calibration.
"""

from hv_ttu import HVTTU, MODES


DEFINITION = (
    "A black hole is a region of spacetime where gravity is so strong "
    "that nothing - no particles or even electromagnetic radiation such as "
    "light - can escape from it. The theory of general relativity predicts "
    "that a sufficiently compact mass can deform spacetime to form a black "
    "hole. The boundary of the region from which no escape is possible is "
    "called the event horizon. Although the event horizon has profound "
    "effects on the fate of an object that crosses it, it has no locally "
    "detectable features. A black hole acts as a perfect black body, and "
    "moreover, it emits Hawking radiation. Note: results may vary depending "
    "on the observer's frame of reference."
)

PROCEDURE = (
    "To change a flat tire, first park on level ground and engage the "
    "parking brake. Then loosen the lug nuts slightly with the wrench. "
    "Next, jack up the car until the tire clears the ground. Remove the "
    "lug nuts and take off the tire. Mount the spare tire and hand-tighten "
    "the lug nuts. Finally, lower the car and tighten the lug nuts fully. "
    "Note: check the spare's pressure first. Warning: do not use the "
    "lug wrench as a lever."
)


def report(title, text):
    m = HVTTU()
    print("=" * 60)
    print(title)
    print("=" * 60)
    rpt = m.report(text)
    print(f"  content_type : {rpt['content_type']}")
    print(f"  best_mode    : {rpt['best_mode']}")
    print(f"  best_ttu     : {rpt['best_ttu']:.2f}s")
    print(f"  baseline_ttu : {rpt['baseline_ttu']:.2f}s")
    print(f"  speedup      : {rpt['speedup_vs_text']:.2f}x")
    print()
    baseline = rpt["baseline_ttu"]
    for mode in MODES:
        t = rpt["ttu_per_mode"][mode]
        sp = baseline / t if t > 0 else 1.0
        mark = "  ★" if mode == rpt["best_mode"] else ""
        print(f"  {mode:<14} {t:>7.2f}s  ({sp:>5.2f}x){mark}")
    print()


def main():
    report("DEFINITION (best should be svg_tree)", DEFINITION)
    report("PROCEDURE (best should be svg_strip)", PROCEDURE)

    # Reader mismatch example
    m = HVTTU()
    print("=" * 60)
    print("Reader mismatch on the definition, delivered as text")
    print("=" * 60)
    for rm in ["text-first", "visual-first", "music-first"]:
        t = m.ttu(DEFINITION, mode="text", reader_mode=rm)
        print(f"  {rm:<16} {t:.2f}s")
    print()

    # Calibration example
    print("=" * 60)
    print("Calibration (recover a 1.4x multiplier)")
    print("=" * 60)
    m = HVTTU()
    print(f"  scale before : {m.scale:.4f}")
    obs = [
        (DEFINITION, "text",       m.ttu(DEFINITION, "text") * 1.4),
        (DEFINITION, "card_deck",  m.ttu(DEFINITION, "card_deck") * 1.4),
        (PROCEDURE,  "svg_strip",  m.ttu(PROCEDURE,  "svg_strip") * 1.4),
    ]
    new_scale = m.calibrate(obs)
    print(f"  scale after  : {new_scale:.4f}")
    print(f"  target       : 1.4000")


if __name__ == "__main__":
    main()