ACCURACY_VALIDATION.md

Accuracy validation

This is a validation layer, not a second predictive engine. It intentionally does not change the API response or the production calculation path.

Reproduce locally

From the API directory:

python -m pip install -r requirements.txt
python accuracy_validation.py --no-shadow

To install the optional shadow engines in a separate environment:

python -m pip install -r requirements-accuracy.txt
python accuracy_validation.py
python accuracy_validation.py --strict-shadow

The command prints a JSON report and exits non-zero when a local golden case or the explicit late-Zi/midnight contract fails. --strict-shadow additionally fails when an installed shadow engine disagrees.

What is covered

• Five civil-date cases taken from the Hong Kong Observatory's Gregorian/lunar conversion table, including the 2033 leap-month boundary.
• Current BaZi and Da Yun regression anchors from lunar-python==1.4.8.
• The current product policy at 22:59, 23:00, 23:59, 00:00, and 00:59.
• Optional Tyme4py comparison using LunarSect2EightCharProvider for the chart and LunarSect1ChildLimitProvider for 起运, matching the current product contract.
• Optional sxtwl comparison for civil-calendar and four-pillar fields. sxtwl shares the ShouXing lineage with lunar-python, so a pass only catches port or interface drift; it is not an independent astronomical truth source.
• A validation-only Da Yun rule registry records each current score signal, its implementation owner, double-count group, and evidence status. The weighted rules intentionally remain marked unvalidated until a blinded, labelled outcome dataset exists.

Contract currently made explicit

chart sect: 2 (late 子时 keeps the birth day's 日柱)
yun sect:   1 (3 days = 1 year; 1 day = 4 months; 1 时辰 = 10 days)

This distinction matters: lunar-python defaults the chart object to sect 2, while getYun(..., sect=1) is the current API's 起运 policy. A future change must update the contract and its fixtures deliberately.

Authority and limitations

• GB/T 33661-2017 is the modern Chinese-calendar policy reference.
• Hong Kong Observatory conversion tables provide reproducible 1901–2100 civil-date fixtures.
• sxtwl_cpp and Tyme4py are comparison implementations; both share the 寿星天文历 lineage with the current lunar-python path, so they detect drift but do not constitute independent proof of the fortune rules.
• The fixture set does not prove that a 0–100 fortune score predicts life outcomes. That requires a separate blinded, labelled evaluation dataset. The same limitation applies to every weighted entry in rule_contract.py; its purpose is auditability and change detection, not endorsement of a predictive rule.

For the next phase, use DAYUN_CALIBRATION.md to collect blinded, dated outcome labels and compare the score against a constant 50 baseline.

Rule-contract check

PYTHONDONTWRITEBYTECODE=1 python -m pytest -q -p no:cacheprovider test_rule_contract.py
PYTHONDONTWRITEBYTECODE=1 python rule_contract.py