feat(stock-lab): VcpLite 노드 — 변동성 수축률 백분위

stock-lab/app/screener/nodes/vcp_lite.py

@@ -0,0 +1,40 @@
+"""VCP-lite — 단기/장기 일중 변동성 비율 기반 수축률."""
+
+import pandas as pd
+
+from .base import ScoreNode, percentile_rank
+
+
+class VcpLite(ScoreNode):
+    name  = "vcp_lite"
+    label = "VCP-lite (변동성 수축)"
+    default_params = {"short_window": 40, "long_window": 252}
+    param_schema = {
+        "type": "object",
+        "properties": {
+            "short_window": {"type": "integer", "minimum": 10, "maximum": 120, "default": 40},
+            "long_window":  {"type": "integer", "minimum": 60, "maximum": 504, "default": 252},
+        },
+    }
+
+    def compute(self, ctx, params: dict) -> pd.Series:
+        short_w = int(params.get("short_window", 40))
+        long_w  = int(params.get("long_window", 252))
+        prices = ctx.prices
+        if prices.empty:
+            return pd.Series(dtype=float)
+
+        ordered = prices.sort_values("date").copy()
+        ordered["range_pct"] = (ordered["high"] - ordered["low"]) / ordered["close"]
+
+        def _ratio(s: pd.Series) -> float:
+            if len(s) < long_w:
+                return float("nan")
+            short_vol = s.tail(short_w).mean()
+            long_vol  = s.tail(long_w).mean()
+            if long_vol == 0 or pd.isna(long_vol):
+                return float("nan")
+            return 1 - (short_vol / long_vol)
+
+        raw = ordered.groupby("ticker", group_keys=False)["range_pct"].apply(_ratio)
+        return percentile_rank(raw).fillna(50.0)

stock-lab/app/test_screener_nodes_vcp_lite.py

@@ -0,0 +1,36 @@
+import datetime as dt
+import pandas as pd
+
+from app.screener.engine import ScreenContext
+from app.screener.nodes.vcp_lite import VcpLite
+from app.screener._test_fixtures import make_master, make_prices, make_flow
+
+
+def _ctx(master, prices, flow):
+    return ScreenContext(master=master, prices=prices, flow=flow,
+                         kospi=pd.Series(dtype=float, name="kospi"),
+                         asof=dt.date(2026, 5, 12))
+
+
+def test_contracting_stock_scores_higher_than_expanding():
+    asof = dt.date(2026, 5, 12)
+    master = make_master(["CON", "EXP"])
+    prices = make_prices(["CON", "EXP"], days=260, asof=asof)
+
+    # CON: 최근 40일 변동성 축소 (high/low 좁힘)
+    mask_recent_con = (prices["ticker"] == "CON") & (
+        prices["date"] >= (asof - dt.timedelta(days=40)).isoformat()
+    )
+    prices.loc[mask_recent_con, "high"] = (prices.loc[mask_recent_con, "close"] * 1.003).astype(int)
+    prices.loc[mask_recent_con, "low"]  = (prices.loc[mask_recent_con, "close"] * 0.997).astype(int)
+
+    # EXP: 최근 40일 변동성 확대
+    mask_recent_exp = (prices["ticker"] == "EXP") & (
+        prices["date"] >= (asof - dt.timedelta(days=40)).isoformat()
+    )
+    prices.loc[mask_recent_exp, "high"] = (prices.loc[mask_recent_exp, "close"] * 1.05).astype(int)
+    prices.loc[mask_recent_exp, "low"]  = (prices.loc[mask_recent_exp, "close"] * 0.95).astype(int)
+
+    flow = make_flow(["CON", "EXP"], days=260, asof=asof)
+    out = VcpLite().compute(_ctx(master, prices, flow), VcpLite.default_params)
+    assert out["CON"] > out["EXP"]