yinglong-cash-forecaster

The cash forecaster (M5) of YINGLONG, an AI agent wallet that pays only inside spending rules the owner locked. For a small company's treasury it forecasts the account balance for the next 28 days as a band (eleven quantiles, 5% to 95%) and gives the chance that the balance falls below the reserve floor within 14 days.

Important: this model is advisory and can only escalate. In YINGLONG the forecast can make the treasurer agent more careful (for example, ask the board before a large payment when a breach looks likely). It never approves anything; the deterministic projection and the on-chain reserve-floor rule decide. Do not use it as the only defence of anything.

How to use

# pip install lightgbm huggingface_hub numpy
from huggingface_hub import hf_hub_download
import importlib.util
spec = importlib.util.spec_from_file_location("yinglong_m5", hf_hub_download("ABRUBAB/yinglong-cash-forecaster", "yinglong_m5.py"))
m5 = importlib.util.module_from_spec(spec); spec.loader.exec_module(m5)
model = m5.CashForecaster()
# history: at least 29 days of {"balance_fen": int}; future: one dict per day with "date" and known outflows in fen

Amounts are integers in fen (1/100 of a yuan), as everywhere in YINGLONG. Inputs: the last 29+ daily balances and, for each future day, the date and known scheduled outflows (payroll, supplier bills, utilities, forwarders, cloud, sweeps) plus weekend and holiday flags. yinglong_m5.py holds the exact feature code the live service runs.

Files

m5_lgbm_q0.05.txt ... m5_lgbm_q0.95.txt: eleven LightGBM quantile models (plain text, the same files the live service runs; their SHA-256 are in results.json). yinglong_m5.py: the forecasting function. results.json: the full evaluation.

Results (held-out test origins)

8 synthetic company ledgers, 312 test forecast origins, 28-day horizon. Lower is better except coverage (target 90%).

Method	Scaled pinball	Pinball, days 1-7 (CNY)	Pinball, days 8-28 (CNY)	90% band coverage (after CQR)	Brier, 14-day breach
LightGBM quantile (this model)	0.077	52,239	131,231	86.7%	0.061
Chronos-2 (zero-shot)	0.093	78,053	154,270	88.7%	0.084
Seasonal naive	0.145	114,428	242,325	89.3%	0.101

This model beats the zero-shot Chronos-2 foundation model on pinball loss and breach Brier score on these ledgers. Its raw 90% band is too narrow (74.3% coverage); conformalized quantile regression (CQR) widens it to 86.7%, still a little under target. Breach base rate on the test split: 13.1%.

Training data

Synthetic only (synthetic ledgers (fictional SMEs, CNY on a simulator rail)), generated by ml/forecast/ledger.py and trained and evaluated by ml/forecast/train_eval.py in https://github.com/ABRUBAB/YINGLONG. No real company's data. Live system: https://app.yinglong-agent.tech (treasury page).