fidelity_check_template.py

"""
Template: assess alignment between a script's emitted events and a Plan.

Usage:
1) Copy this file into your project.
2) Replace PLAN import and the script invocation block.
3) Run the script to print the assessment report.
"""

from __future__ import annotations

from typing import Callable, Iterable

from fidelity_framework_v1 import (
    AssessmentResult,
    ObligationLedger,
    assess_plan,
    clear_events,
    findings_to_obligations,
    get_events,
    render_report,
    set_correlation_id,
)


def run_component() -> None:
    """
    TODO: Replace with actual script/component invocation that emits events.

    Example:
        from my_script import main
        main(["--input", "in.csv", "--out", "out.csv", "--force"])
    """
    raise NotImplementedError("Replace run_component() with your script invocation.")


def assess_alignment(
    *,
    plan,
    code_reference: str,
    component_runner: Callable[[], None],
) -> tuple[AssessmentResult, ObligationLedger, str]:
    """
    Execute the component, collect events, and assess against the Plan.
    """
    clear_events()
    set_correlation_id("assessment-run")

    component_runner()

    result = assess_plan(
        plan=plan,
        events=get_events(),
        code_reference=code_reference,
    )
    ledger = findings_to_obligations(result, owner=plan.owner)
    report_text = render_report(result, ledger)
    return result, ledger, report_text


def main() -> int:
    # TODO: Replace with your Plan import
    # from my_plan_file import PLAN
    PLAN = None  # type: ignore[assignment]

    if PLAN is None:
        raise ValueError("Replace PLAN with your actual Plan definition.")

    _, _, report_text = assess_alignment(
        plan=PLAN,
        code_reference="path/to/your_script.py",
        component_runner=run_component,
    )
    print(report_text)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())