astrologybazi-api / ACCURACY_VALIDATION.md
th
feat(bazi): add evidence-first dayun assessment
0d792fe
|
Raw History Blame Contribute Delete
3.4 kB
# 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:
```bash
python -m pip install -r requirements.txt
python accuracy_validation.py --no-shadow
```
To install the optional shadow engines in a separate environment:
```bash
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
```text
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](https://openstd.samr.gov.cn/bzgk/std/newGbInfo?hcno=E107EA4DE9725EDF819F33C60A44B296)
is the modern Chinese-calendar policy reference.
- [Hong Kong Observatory conversion tables](https://www.hko.gov.hk/en/gts/time/conversion.htm)
provide reproducible 1901–2100 civil-date fixtures.
- [sxtwl_cpp](https://github.com/yuangu/sxtwl_cpp) and
[Tyme4py](https://github.com/6tail/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`](./rule_contract.py); its purpose is auditability and
change detection, not endorsement of a predictive rule.
For the next phase, use [`DAYUN_CALIBRATION.md`](./DAYUN_CALIBRATION.md) to
collect blinded, dated outcome labels and compare the score against a constant
50 baseline.
## Rule-contract check
```bash
PYTHONDONTWRITEBYTECODE=1 python -m pytest -q -p no:cacheprovider test_rule_contract.py
PYTHONDONTWRITEBYTECODE=1 python rule_contract.py
```