akg-factor-bridge/freeze.py

199 lines
9.3 KiB
Python
Raw Normal View History

2026-07-27 09:49:05 +08:00
"""输入冻结(G0.5 · 评审 §5)——把每日「不可复原的上游」落成不可变快照。
**为什么必须有这个模块。** 桥内写入是幂等的,但上游不是:
1. `transmission_candidates` 的 quiet 集合与 moved_ratio 依赖 Neo4j 返回序
(基座 `topic_context` 的 Cypher 是 `LIMIT $cap` 且无 ORDER BY),同日重跑可能不同;
2. `industry_pools` 只存最新态、每周一 refresh_pools 自动长大,没有时点版本;
3. `gp_day_data` 是**前复权**、锚在最新日——每次有股票除权,历史 close 会被整体
重写,于是 `akg_upside` 的历史值今天回填和三个月后回填不是同一组数;
4. `consensus_daily` 的 asof 行会随 sync_consensus 重跑而覆盖。
于是「可复现」唯一诚实可达的定义是:**能从冻结的输入重算出同一个值**。
这个模块就是那份冻结,一次性满足三件事——判收标准 §10 的「重跑不产生漂移」、
「赛道成员快照可审计」、以及未来任何回溯需求(含 §10 里 GRU 复活所需的
「≥1 年 live 传导史」——那个计时器只在开始存快照的那天启动)。
落点:桥工程自身 `data/frozen/<YYYY-MM-DD>/`(config.FROZEN_ROOT),
不落基座、不落平台,守 §4 的三层边界。
格式:装了 pyarrow 就 parquet,否则 csv.gz(零新增依赖)。
每天一个 manifest.json 记录各源行数、告警与代码版本——**manifest 才是可 diff 的
审计线**,建议 git 跟踪 manifest.json、忽略数据文件。
用法(全程 Docker):
docker compose exec akg-factor-bridge python run.py freeze --date 2026-07-24
docker compose exec akg-factor-bridge python run.py freeze # 默认今天
# 日更链里 `build ... --mode daily` 跑完会自动冻结(--no-freeze 可关)
"""
from __future__ import annotations
import datetime as dt
import json
from pathlib import Path
import pandas as pd
import config
import db
import version
import market_scope as scope
2026-07-27 09:49:05 +08:00
try: # parquet 更省更快,但不强制装 pyarrow
import pyarrow # noqa: F401
_FMT, _EXT = "parquet", ".parquet"
except Exception: # noqa: BLE001
_FMT, _EXT = "csv.gz", ".csv.gz"
# ---------------------------------------------------------------- 落盘
def _write(df: pd.DataFrame, path: Path) -> int:
path.parent.mkdir(parents=True, exist_ok=True)
df = pd.DataFrame() if df is None else scope.frozen_frame(df)
2026-07-27 09:49:05 +08:00
# 空也要留痕:0 行本身是信息("那天上游真的没有数据" ≠ "那天没跑")
if _FMT == "parquet":
df.to_parquet(path, index=False)
else:
df.to_csv(path, index=False, compression="gzip")
return len(df)
def _git_rev() -> str:
"""记录冻结时的代码版本——快照可复算的前提是知道当时的口径。
2026-09-03 改用 version.git_short_rev():容器镜像没装 git,原来调 git 命令在容器里恒为
unknown(155 的 manifest.json 实测);version.py 直接解析挂载进来的 .git 文件,与计划快照的
plan_version 同一来源,任何失败返回 "unknown",不让冻结失败。"""
return version.git_short_rev()
2026-07-27 09:49:05 +08:00
# ---------------------------------------------------------------- 各源抓取
def _cap_universe(_day: str) -> pd.DataFrame:
"""覆盖池当日成员(industry_pools 无历史版本 → 只能靠这里留时点)。"""
return scope.frame(db.read_pg("SELECT ts_code FROM v_factor_universe WHERE " +
scope.sql_filter("ts_code", postgres=True) + " ORDER BY ts_code"), "ts_code")
2026-07-27 09:49:05 +08:00
def _cap_transmission(day: str) -> pd.DataFrame:
"""传导原始行仅冻结沪深证券;上游结构与日期保持。"""
rows = db.read_pg("SELECT * FROM v_factor_transmission WHERE scan_date = %s AND " +
scope.sql_filter("ts_code", postgres=True) + " ORDER BY ts_code", (day,))
return scope.frozen_frame(rows)
2026-07-27 09:49:05 +08:00
def _cap_consensus(day: str) -> pd.DataFrame:
"""当日可见的最新一致预期(as-of 口径与 build_upside 一致,每股留最新一行)。"""
rows = db.read_pg(
2026-07-27 09:49:05 +08:00
"SELECT DISTINCT ON (ts_code) ts_code, asof_date, target_mid_avg, "
" eps_med, np_med, n_orgs, n_reports_90d "
"FROM v_factor_consensus WHERE asof_date <= %s AND " +
scope.sql_filter("ts_code", postgres=True) + " ORDER BY ts_code, asof_date DESC", (day,))
return scope.frame(rows, "ts_code")
2026-07-27 09:49:05 +08:00
def _cap_price(day: str) -> pd.DataFrame:
"""当日收盘(**前复权**,会被后续除权整体重写 → 必须冻结当时看到的值)。"""
import factors # 复用同一套代码列探测,口径不分叉
col = factors._price_code_col() # noqa: SLF001
rows = db.read_mysql(
2026-07-27 09:49:05 +08:00
"price",
f"SELECT `timestamp` AS trade_date, `{col}` AS code, close "
f"FROM gp_day_data WHERE `timestamp` = %s AND " + scope.sql_filter(f"`{col}`"), (day,))
return scope.frame(rows, "code")
2026-07-27 09:49:05 +08:00
def _cap_heat(day: str) -> pd.DataFrame:
"""与因子计算同一沪深日频批次,空结果仍按原口径留痕。"""
from factors import _read_heat_rows
return _read_heat_rows(day, day)
2026-07-27 09:49:05 +08:00
def _cap_optional(sql: str):
"""可选视图(第五/六个插槽视图还没建时不该让冻结失败)。"""
def _f(_day: str) -> pd.DataFrame:
try:
return scope.frozen_frame(db.read_pg(sql))
2026-07-27 09:49:05 +08:00
except Exception: # noqa: BLE001
return pd.DataFrame()
return _f
_SOURCES = {
"universe": _cap_universe,
"transmission": _cap_transmission,
"consensus": _cap_consensus,
"price_close": _cap_price,
"heat": _cap_heat,
# 第五/六个插槽视图建好后自动开始冻结(没建 → 空 DataFrame,不报错)
"segment_members": _cap_optional("SELECT * FROM v_factor_segment_members WHERE " +
scope.sql_filter("ts_code", postgres=True)),
2026-07-27 09:49:05 +08:00
"segment_edges": _cap_optional("SELECT * FROM v_factor_segment_edges"),
}
# ---------------------------------------------------------------- 体检断言
def _audit(day: str, tr: pd.DataFrame) -> list[str]:
"""把评审里那几个「静默失真」写成显式告警,冻结当时就看见。"""
warns: list[str] = []
if tr is None or tr.empty:
return warns
if "mkt_trade_date" in tr.columns and tr["mkt_trade_date"].notna().any():
bad = sorted({str(x) for x in tr["mkt_trade_date"].dropna()
if str(x) != day})
if bad:
warns.append(f"传导用的 mkt 快照日 {bad} ≠ scan_date {day}"
f"——movers 陈旧,该日传导项不可信(评审 §6.2)")
if "members_total" in tr.columns:
hit = tr[pd.to_numeric(tr["members_total"], errors="coerce")
>= config.UPSTREAM_MEMBER_CAP]
if not hit.empty:
n = hit["target"].nunique() if "target" in hit.columns else len(hit)
warns.append(f"{n} 个环节 members_total >= {config.UPSTREAM_MEMBER_CAP},"
f"撞上游 topic_context cap——moved_ratio 建立在任意顺序的抽样上"
f"(评审 硬伤1)")
2026-08-03 16:52:42 +08:00
# quiet 截断检查已删(08-03):基座 07-28 二批改造后 quiet 已全量落库,
# 不再有 quiet[:12] 截断,原检查引用的 UPSTREAM_QUIET_CAP 也随之从 config
# 移除——保留只会让每晚冻结在这里抛 AttributeError,写不出 manifest.json。
2026-07-27 09:49:05 +08:00
return warns
# ---------------------------------------------------------------- 入口
def snapshot(day: str | None = None, extra_frames: dict | None = None) -> dict:
"""冻结 day 当日的全部上游输入 +(可选)当日算出的因子值。
extra_frames: {"factor_akg_heat": df, ...} —— run.py build 完顺手传进来,
这样「输入 + 输出」在同一目录里,任何一行因子值都能被逐步复算。
"""
day = day or dt.date.today().isoformat()
out = Path(config.FROZEN_ROOT) / day
manifest = {"date": day, "format": _FMT, "git_rev": _git_rev(),
"subfactor_universe": config.SUBFACTOR_UNIVERSE,
"frozen_at": dt.datetime.now().astimezone().isoformat(),
"rows": {}, "errors": {}, "warnings": []}
frames: dict[str, pd.DataFrame] = {}
for name, fn in _SOURCES.items():
try:
df = scope.frozen_frame(fn(day))
2026-07-27 09:49:05 +08:00
frames[name] = df
manifest["rows"][name] = _write(df, out / f"{name}{_EXT}")
except Exception as e: # noqa: BLE001 —— 单源失败不拖累其余源
manifest["errors"][name] = repr(e)
print(f" ❌ 冻结 {name} 失败: {e!r}")
for name, df in (extra_frames or {}).items():
try:
manifest["rows"][name] = _write(df, out / f"{name}{_EXT}")
except Exception as e: # noqa: BLE001
manifest["errors"][name] = repr(e)
manifest["warnings"] = _audit(day, frames.get("transmission"))
out.mkdir(parents=True, exist_ok=True)
(out / "manifest.json").write_text(
json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
print(f" ❄️ 冻结 {day} → {out}")
for k, v in manifest["rows"].items():
print(f" {k}: {v} 行")
for w in manifest["warnings"]:
print(f" ⚠️ {w}")
return manifest