hodlvn 0.1.0__tar.gz

hodlvn-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: hodlvn
+Version: 0.1.0
+Summary: HODL Lab — chỉ báo, chiến lược, backtest danh mục cổ phiếu Việt Nam trên dữ liệu HODL (cần API key hạng Loyalty)
+License: Proprietary
+Project-URL: Homepage, https://hodl.vn/lab
+Project-URL: Documentation, https://hodl.vn/lab/docs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+
+# hodlvn — HODL Lab SDK
+
+Viết chỉ báo, chiến lược và backtest danh mục cổ phiếu Việt Nam trên dữ liệu của HODL. Lõi này cũng là thứ chạy trong
+trình duyệt ở [hodl.vn/lab](https://hodl.vn/lab), nên kết quả ở SDK và trên web giống nhau tới đồng.
+
+```bash
+pip install hodlvn
+export HODL_API_KEY=hodl_...        # tạo ở hodl.vn/tai-khoan/ket-noi-ai (hạng Loyalty)
+```
+
+```python
+import hodl
+lab = hodl.Client()
+res = lab.run('universe("HX-BANK")\nrebalance("M")\npick(top(momentum(63), 3))', kind="portfolio", start="2021-01-04")
+print(res["summary"])
+```
+
+Backtest đã áp sẵn luật thị trường Việt Nam: lô 100, biên độ trần / sàn theo sàn, T+2,5, phí 0,15%, thuế bán 0,1%,
+cổ tức tiền (thuế 5%) và cổ phiếu thưởng theo đúng ngày GDKHQ, khớp lệnh ở giá mở phiên sau tín hiệu, giá thật.
+
+Hướng dẫn đầy đủ: https://hodl.vn/lab/docs

hodlvn-0.1.0/README.md

@@ -0,0 +1,21 @@
+# hodlvn — HODL Lab SDK
+
+Viết chỉ báo, chiến lược và backtest danh mục cổ phiếu Việt Nam trên dữ liệu của HODL. Lõi này cũng là thứ chạy trong
+trình duyệt ở [hodl.vn/lab](https://hodl.vn/lab), nên kết quả ở SDK và trên web giống nhau tới đồng.
+
+```bash
+pip install hodlvn
+export HODL_API_KEY=hodl_...        # tạo ở hodl.vn/tai-khoan/ket-noi-ai (hạng Loyalty)
+```
+
+```python
+import hodl
+lab = hodl.Client()
+res = lab.run('universe("HX-BANK")\nrebalance("M")\npick(top(momentum(63), 3))', kind="portfolio", start="2021-01-04")
+print(res["summary"])
+```
+
+Backtest đã áp sẵn luật thị trường Việt Nam: lô 100, biên độ trần / sàn theo sàn, T+2,5, phí 0,15%, thuế bán 0,1%,
+cổ tức tiền (thuế 5%) và cổ phiếu thưởng theo đúng ngày GDKHQ, khớp lệnh ở giá mở phiên sau tín hiệu, giá thật.
+
+Hướng dẫn đầy đủ: https://hodl.vn/lab/docs

hodlvn-0.1.0/hodl/__init__.py

@@ -0,0 +1,33 @@
+"""hodl — lõi HODL Lab: chạy script chỉ báo / chiến lược / danh mục trên dữ liệu cổ phiếu Việt Nam của HODL.
+
+Trong Lab (trình duyệt) script KHÔNG cần import gì. Dùng như SDK (máy riêng, hạng Loyalty):
+
+    import hodl
+    lab = hodl.Client(api_key="hodl_…")            # hoặc biến môi trường HODL_API_KEY
+    res = lab.run('universe("HX-BANK"); rebalance("M"); pick(top(momentum(63), 3))', kind="portfolio", start="2021-01-01")
+    res["summary"]
+"""
+from __future__ import annotations
+
+import os
+
+from .data import Data, DataError, FnSource, HttpSource, MemorySource
+from .script_env import KINDS, ScriptError, run
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Data", "DataError", "FnSource", "HttpSource", "MemorySource", "ScriptError", "KINDS", "run"]
+
+
+class Client:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+        key = api_key or os.environ.get("HODL_API_KEY")
+        if not key:
+            raise DataError("lab_invalid_key", "Thiếu API key (tham số api_key hoặc biến môi trường HODL_API_KEY)")
+        self.data = Data(HttpSource(key, base_url) if base_url else HttpSource(key))
+
+    def run(self, code: str, kind: str, symbol: str | None = None, start: str | None = None, params: dict | None = None,
+            capital: float = 100_000_000, fee_pct: float = 0.15) -> dict:
+        return run(code, kind, self.data, symbol=symbol, start=start, params=params, capital=capital, fee_pct=fee_pct)
+
+    def bars(self, symbols, start=None, end=None, adjusted=True):
+        return self.data.bars(symbols, start, end, adjusted)

hodlvn-0.1.0/hodl/data.py

@@ -0,0 +1,152 @@
+"""Lấy dữ liệu từ Data API của HODL (`/lab/v1/*`) — một giao diện cho cả hai nơi chạy:
+
+- Trình duyệt (Pyodide): `FnSource(fn)` — `fn(path_query) -> str JSON` là cầu JS ĐỒNG BỘ do Worker cấp, chỉ gọi được
+  `/api/lab/*` cùng nguồn (Worker chặn mọi URL khác).
+- SDK (CPython): `HttpSource(api_key)` — gọi `https://api.totrieu.com/lab/v1` bằng API key hạng Loyalty.
+- Test: `MemorySource({path: json})`.
+
+Lỗi của API (hết lượt, quá hạn mức mã…) ném `DataError` có `code` để giao diện mời nâng hạng / báo rõ.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import date
+from pathlib import Path
+
+import pandas as pd
+
+DEFAULT_BASE = "https://api.totrieu.com/lab/v1"
+
+
+class DataError(RuntimeError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def _query(path: str, params: dict) -> str:
+    q = {k: v for k, v in params.items() if v is not None}
+    return f"{path}?{urllib.parse.urlencode(q)}" if q else path
+
+
+class Source:
+    def get(self, path: str, **params) -> dict:  # pragma: no cover — giao diện
+        raise NotImplementedError
+
+
+class FnSource(Source):
+    def __init__(self, fn):
+        self.fn = fn
+
+    def get(self, path: str, **params) -> dict:
+        data = json.loads(str(self.fn(_query(path, params))))
+        if isinstance(data, dict) and "detail" in data:
+            d = data["detail"]
+            if isinstance(d, dict):
+                raise DataError(d.get("code", "lab_error"), d.get("message", ""))
+            raise DataError("lab_bad_request", f"Tham số không hợp lệ: {d}")
+        return data
+
+
+CACHED_PATHS = ("/bars", "/events", "/universe/history", "/fundamentals")
+
+
+class HttpSource(Source):
+    """SDK: gọi Data API bằng API key. Nến / sự kiện / rổ / chỉ số cơ bản đệm trên đĩa theo NGÀY (`~/.cache/hodl`, đổi bằng
+    `HODL_CACHE_DIR`; `HODL_NO_CACHE=1` để tắt) — chạy lại script trong ngày không tốn lượt gọi."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE, timeout: float = 60, cache_dir: str | None = None):
+        self.api_key, self.base_url, self.timeout = api_key, base_url.rstrip("/"), timeout
+        off = os.environ.get("HODL_NO_CACHE") == "1"
+        self.cache_dir = None if off else Path(cache_dir or os.environ.get("HODL_CACHE_DIR") or Path.home() / ".cache" / "hodl")
+
+    def _cache_file(self, url: str) -> Path | None:
+        if self.cache_dir is None:
+            return None
+        key = hashlib.sha256(f"{date.today().isoformat()}|{self.api_key[-8:]}|{url}".encode()).hexdigest()[:32]
+        return self.cache_dir / f"{key}.json"
+
+    def get(self, path: str, **params) -> dict:
+        url = self.base_url + _query(path, params)
+        cached = self._cache_file(url) if path in CACHED_PATHS else None
+        if cached and cached.is_file():
+            try:
+                return json.loads(cached.read_text(encoding="utf-8"))
+            except ValueError:
+                pass
+        data = self._fetch(url)
+        if cached:
+            try:
+                cached.parent.mkdir(parents=True, exist_ok=True)
+                cached.write_text(json.dumps(data), encoding="utf-8")
+            except OSError:
+                pass
+        return data
+
+    def _fetch(self, url: str) -> dict:
+        req = urllib.request.Request(url, headers={"Authorization": f"Bearer {self.api_key}", "User-Agent": "hodlvn-sdk"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read().decode())
+        except urllib.error.HTTPError as e:
+            try:
+                d = json.loads(e.read().decode()).get("detail") or {}
+            except ValueError:
+                d = {}
+            raise DataError(d.get("code", f"http_{e.code}") if isinstance(d, dict) else f"http_{e.code}",
+                            d.get("message", str(e)) if isinstance(d, dict) else str(d)) from None
+
+
+class MemorySource(Source):
+    def __init__(self, routes: dict):
+        self.routes = routes
+
+    def get(self, path: str, **params) -> dict:
+        return self.routes[path](**params) if callable(self.routes[path]) else self.routes[path]
+
+
+class Data:
+    """Bộ đệm theo lượt chạy: một mã chỉ tải một lần dù script gọi nhiều lần."""
+
+    def __init__(self, source: Source):
+        self.source = source
+        self._bars: dict[tuple, pd.DataFrame] = {}
+        self._events: dict[str, list] = {}
+        self.exchanges: dict[str, str] = {}
+        self.truncated = False
+
+    def bars(self, symbols, start=None, end=None, adjusted=True) -> dict[str, pd.DataFrame]:
+        syms = [symbols] if isinstance(symbols, str) else list(symbols)
+        need = [s.upper() for s in syms if (s.upper(), start, end, adjusted) not in self._bars]
+        for i in range(0, len(need), 30):
+            chunk = need[i:i + 30]
+            res = self.source.get("/bars", symbols=",".join(chunk), start=start, end=end, adjusted=str(adjusted).lower())
+            self.truncated = self.truncated or bool(res.get("truncated"))
+            self.exchanges.update(res.get("exchanges") or {})
+            for s in chunk:
+                rows = res["bars"].get(s, [])
+                df = pd.DataFrame(rows, columns=["date", "open", "high", "low", "close", "volume"])
+                df["date"] = pd.to_datetime(df["date"])
+                self._bars[(s, start, end, adjusted)] = df.set_index("date").astype(float)
+        return {s.upper(): self._bars[(s.upper(), start, end, adjusted)] for s in syms}
+
+    def events(self, symbols) -> dict[str, list]:
+        syms = [s.upper() for s in ([symbols] if isinstance(symbols, str) else symbols)]
+        need = [s for s in syms if s not in self._events]
+        for i in range(0, len(need), 30):
+            chunk = need[i:i + 30]
+            res = self.source.get("/events", symbols=",".join(chunk))["events"]
+            for s in chunk:
+                self._events[s] = res.get(s, [])
+        return {s: self._events[s] for s in syms}
+
+    def universe_history(self, code: str, start) -> dict:
+        return self.source.get("/universe/history", code=code, start=str(start)[:10])
+
+    def fundamentals(self, symbols, fields) -> dict:
+        return self.source.get("/fundamentals", symbols=",".join(symbols), fields=",".join(fields))

hodlvn-0.1.0/hodl/engine_portfolio.py

@@ -0,0 +1,88 @@
+"""Backtest CẢ RỔ (tab Danh mục): mỗi kỳ cân bằng, script chọn mã (+ tỷ trọng) từ dữ liệu tới GIÁ ĐÓNG phiên trước, lệnh
+khớp ở giá MỞ ngày cân bằng, giá thật, luật VN (lô 100, biên độ, T+2,5, phí, thuế, cổ tức).
+
+`picker(asof_index, members) -> dict[mã, tỷ trọng]` do `script_env` cấp (chạy lại script ở từng kỳ).
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from . import rules_vn as R
+from .engine_single import _events_by_date, apply_events
+
+FREQ = {"W": "W", "M": "M", "Q": "Q", "Y": "Y"}
+
+
+def rebalance_days(dates: list[pd.Timestamp], freq: str) -> list[int]:
+    """Chỉ số phiên ĐẦU của mỗi tuần / tháng / quý / năm."""
+    key = {"W": lambda d: (d.isocalendar()[0], d.isocalendar()[1]), "M": lambda d: (d.year, d.month),
+           "Q": lambda d: (d.year, (d.month - 1) // 3), "Y": lambda d: d.year}[freq]
+    out, last = [], None
+    for i, d in enumerate(dates):
+        k = key(d)
+        if k != last:
+            out.append(i)
+            last = k
+    return out
+
+
+def members_at(periods: list[dict], day: str) -> list[str]:
+    cur = periods[0]["symbols"] if periods else []
+    for p in periods:
+        if p["effective_date"] <= day:
+            cur = p["symbols"]
+    return cur
+
+
+def run_portfolio(real: dict[str, pd.DataFrame], periods: list[dict], picker, freq: str = "M",
+                  events: dict[str, list] | None = None, capital: float = 100_000_000, fee_pct: float = R.DEFAULT_FEE_PCT,
+                  exchanges: dict[str, str] | None = None) -> dict:
+    cal = sorted(set().union(*[set(df.index) for df in real.values()])) if real else []
+    days = [d.strftime("%Y-%m-%d") for d in cal]
+    opens = {s: df["open"].reindex(cal).ffill() for s, df in real.items()}
+    closes = {s: df["close"].reindex(cal).ffill() for s, df in real.items()}
+    ev = {s: _events_by_date(e) for s, e in (events or {}).items()}
+    exchanges = exchanges or {}
+    reb = set(rebalance_days(cal, FREQ.get(freq, "M")))
+    cash = float(capital)
+    pos: dict[str, int] = {}
+    bought_at: dict[str, int] = {}
+    trades: list[dict] = []
+    holdings: list[dict] = []
+    equity: list[list] = []
+    for i, day in enumerate(days):
+        for s in list(pos):
+            bonus, div = apply_events(day, pos[s], ev.get(s, {}))
+            pos[s] += bonus
+            cash += div
+        if i in reb and i > 0:
+            members = [m for m in members_at(periods, day) if m in real]
+            target = picker(i - 1, members) or {}
+            px = {s: float(opens[s].iloc[i]) for s in set(pos) | set(target) if s in opens and opens[s].iloc[i] == opens[s].iloc[i]}
+            ref = {s: float(closes[s].iloc[i - 1]) for s in px}
+            # Bán trước (mã rời danh sách hoặc giảm tỷ trọng), rồi mua — không vay tiền.
+            value = cash + sum(q * px.get(s, 0) for s, q in pos.items())
+            want = {s: int(value * w // (px[s] * (1 + fee_pct / 100)) // R.LOT * R.LOT) for s, w in target.items() if px.get(s)}
+            for s in sorted(pos):
+                if s not in px:
+                    continue  # không có giá mở hôm nay (tạm ngừng GD) → giữ nguyên tới kỳ sau
+                diff = pos[s] - want.get(s, 0)
+                if diff > 0 and i - bought_at.get(s, -99) >= R.SETTLEMENT_BARS and not R.at_floor(px[s], ref[s], exchanges.get(s, "HOSE")):
+                    cash += R.sell_proceeds(diff, px[s], fee_pct)
+                    pos[s] -= diff
+                    trades.append({"date": day, "symbol": s, "side": "sell", "qty": diff, "price": px[s]})
+                    if not pos[s]:
+                        del pos[s]
+            for s in sorted(want):
+                diff = want[s] - pos.get(s, 0)
+                diff = min(diff, R.lots(cash, px[s], fee_pct))
+                if diff > 0 and not R.at_ceiling(px[s], ref[s], exchanges.get(s, "HOSE")):
+                    cash -= R.buy_cost(diff, px[s], fee_pct)
+                    pos[s] = pos.get(s, 0) + diff
+                    bought_at[s] = i
+                    trades.append({"date": day, "symbol": s, "side": "buy", "qty": diff, "price": px[s]})
+            holdings.append({"date": day, "weights": {s: round(w, 4) for s, w in target.items()},
+                             "held": {s: q for s, q in sorted(pos.items())}})
+        mark = cash + sum(q * float(closes[s].iloc[i]) for s, q in pos.items() if closes[s].iloc[i] == closes[s].iloc[i])
+        equity.append([day, round(mark)])
+    return {"equity": equity, "trades": trades, "holdings": holdings, "capital": capital}

hodlvn-0.1.0/hodl/engine_single.py

@@ -0,0 +1,81 @@
+"""Backtest MỘT mã (tab Chiến lược): tín hiệu tính ở giá đóng phiên t → khớp ở giá MỞ phiên t+1, giá THẬT, luật VN.
+Lệnh mua chỉ hiệu lực phiên kế tiếp (không khớp được — giá trần — thì huỷ); lệnh bán giữ tới khi bán được (T+2,5, sàn).
+
+Tín hiệu do script tính trên nến hồi tố (khớp biểu đồ); khớp lệnh + định giá theo giá thật, cổ tức tiền / cổ phiếu cộng đúng
+ngày GDKHQ (`rules_vn`). Mỗi lần mua dùng toàn bộ tiền mặt (bội số lô), bán hết vị thế.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from . import rules_vn as R
+
+
+def _events_by_date(events: list[dict]) -> dict[str, list[dict]]:
+    out: dict[str, list[dict]] = {}
+    for e in events:
+        out.setdefault(e["date"], []).append(e)
+    return out
+
+
+def apply_events(day: str, shares: int, events_by_date: dict, tax_pct: float = R.DIVIDEND_TAX_PCT) -> tuple[int, float]:
+    """(cổ phiếu thưởng, cổ tức tiền ròng) cho `shares` đang giữ trước ngày GDKHQ `day`. Quyền mua: không thực hiện."""
+    bonus, cash = 0, 0.0
+    for e in events_by_date.get(day, []):
+        kind = e.get("event_type")
+        if kind == "cash_dividend":
+            per = e.get("amount") or (e.get("ratio_percent") or 0) * 100
+            cash += shares * float(per) * (1 - tax_pct / 100)
+        elif kind in ("stock_dividend", "split"):
+            rf, rt = int(e.get("ratio_from") or 0), int(e.get("ratio_to") or 0)
+            if rf > 0 and rt > 0:
+                bonus += shares * rt // rf
+    return bonus, cash
+
+
+def run_single(real: pd.DataFrame, buy: pd.Series, sell: pd.Series, events: list[dict], capital: float = 100_000_000,
+               fee_pct: float = R.DEFAULT_FEE_PCT, exchange: str = "HOSE") -> dict:
+    """`real`: nến giá thật (index ngày). `buy` / `sell`: tín hiệu bool cùng index (đã căn ngày). Trả equity + lệnh."""
+    dates = [d.strftime("%Y-%m-%d") for d in real.index]
+    o, c = real["open"].tolist(), real["close"].tolist()
+    b = buy.reindex(real.index).fillna(False).astype(bool).tolist()
+    s = sell.reindex(real.index).fillna(False).astype(bool).tolist()
+    ev = _events_by_date(events)
+    cash, shares, cost, entry_i, entry_px = float(capital), 0, 0.0, -1, 0.0
+    pending: str | None = None
+    trades: list[dict] = []
+    equity: list[list] = []
+    dividends = 0.0
+    for i, day in enumerate(dates):
+        if shares:
+            bonus, div = apply_events(day, shares, ev)
+            shares += bonus
+            cash += div
+            dividends += div
+        ref = c[i - 1] if i else o[i]
+        if pending == "buy":
+            # Lệnh mua chỉ hiệu lực phiên ngay sau tín hiệu (như ATO): trần / thiếu tiền → huỷ, chờ tín hiệu mới.
+            pending = None
+            qty = R.lots(cash, o[i], fee_pct) if not shares and not R.at_ceiling(o[i], ref, exchange) else 0
+            if qty:
+                spent = R.buy_cost(qty, o[i], fee_pct)
+                cash -= spent
+                shares, cost, entry_i, entry_px = qty, spent, i, o[i]
+        elif pending == "sell" and shares and i - entry_i >= R.SETTLEMENT_BARS and not R.at_floor(o[i], ref, exchange):
+            got = R.sell_proceeds(shares, o[i], fee_pct)
+            cash += got
+            trades.append({"entry_date": dates[entry_i], "entry_price": entry_px, "exit_date": day, "exit_price": o[i],
+                           "qty": shares, "pnl": round(got - cost), "pnl_pct": round((got / cost - 1) * 100, 2),
+                           "bars": i - entry_i, "open": False})
+            shares, cost, pending = 0, 0.0, None
+        equity.append([day, round(cash + shares * c[i])])
+        if s[i] and shares:
+            pending = "sell"
+        elif b[i] and not shares:
+            pending = "buy"
+    if shares:
+        mark = R.sell_proceeds(shares, c[-1], fee_pct)
+        trades.append({"entry_date": dates[entry_i], "entry_price": entry_px, "exit_date": None, "exit_price": c[-1],
+                       "qty": shares, "pnl": round(mark - cost), "pnl_pct": round((mark / cost - 1) * 100, 2),
+                       "bars": len(dates) - 1 - entry_i, "open": True})
+    return {"equity": equity, "trades": trades, "dividends_net": round(dividends), "capital": capital}

hodlvn-0.1.0/hodl/metrics.py

@@ -0,0 +1,61 @@
+"""Chỉ số kết quả chung cho mọi backtest: lãi, lợi suất năm, Sharpe, lỗ sâu nhất, tỷ lệ thắng, ma trận lãi theo tháng."""
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+
+def _series(equity: list[list]) -> pd.Series:
+    return pd.Series([v for _, v in equity], index=pd.to_datetime([d for d, _ in equity]), dtype=float)
+
+
+def summarize(equity: list[list], trades: list[dict], capital: float, benchmark: list[list] | None = None) -> dict:
+    if not equity:
+        return {}
+    eq = _series(equity)
+    ret = eq.iloc[-1] / capital - 1
+    years = max((eq.index[-1] - eq.index[0]).days / 365.25, 1 / 365.25)
+    daily = eq.pct_change(fill_method=None).dropna()
+    sd = daily.std()
+    peak = eq.cummax()
+    dd = (eq / peak - 1).min()
+    closed = [t for t in trades if not t.get("open")]
+    wins = [t for t in closed if t["pnl"] > 0]
+    ret = float(ret)
+    out = {
+        "return_pct": round(ret * 100, 2),
+        "cagr_pct": round(((1 + ret) ** (1 / years) - 1) * 100, 2) if ret > -1 else -100.0,
+        "sharpe": round(float(daily.mean() / sd) * math.sqrt(250), 2) if sd and not math.isnan(sd) else None,
+        "max_drawdown_pct": round(float(dd) * 100, 2),
+        "trades": len(trades),
+        "win_rate_pct": round(len(wins) / len(closed) * 100, 1) if closed else None,
+        "avg_trade_pct": round(sum(t["pnl_pct"] for t in closed) / len(closed), 2) if closed else None,
+        "final_value": round(float(eq.iloc[-1])),
+        "start": equity[0][0],
+        "end": equity[-1][0],
+    }
+    if benchmark:
+        bm = _series(benchmark)
+        out["benchmark_return_pct"] = round(float(bm.iloc[-1] / bm.iloc[0] - 1) * 100, 2)
+    return out
+
+
+def monthly(equity: list[list]) -> dict[str, dict[str, float]]:
+    """{năm: {tháng: % lãi}} — lưới 'Theo tháng'."""
+    eq = _series(equity)
+    if eq.empty:
+        return {}
+    last = eq.groupby([eq.index.year, eq.index.month]).last()
+    prev = last.shift().fillna(eq.iloc[0])
+    pct = (last / prev - 1) * 100
+    out: dict[str, dict[str, float]] = {}
+    for (y, m), v in pct.items():
+        out.setdefault(str(y), {})[str(m)] = round(float(v), 2)
+    return out
+
+
+def drawdown(equity: list[list]) -> list[list]:
+    eq = _series(equity)
+    dd = (eq / eq.cummax() - 1) * 100
+    return [[d.strftime("%Y-%m-%d"), round(float(v), 2)] for d, v in dd.items()]

hodlvn-0.1.0/hodl/portfolio_ctx.py

@@ -0,0 +1,117 @@
+"""Hàm dùng trong script Danh mục, tính tại MỘT kỳ cân bằng (dữ liệu tới giá đóng phiên trước — không nhìn trước tương lai).
+
+`momentum(63)`, `pe()`, `fundamental("roe")`… trả `pandas.Series` theo mã của rổ tại kỳ đó; `top / bottom` chọn mã;
+`pick(...)` ghi danh sách (chia đều) hoặc dict mã → tỷ trọng.
+"""
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+
+class PortfolioCtx:
+    def __init__(self, adj_close: pd.DataFrame, real_close: pd.DataFrame, fundamentals: dict[str, list[dict]]):
+        self.adj_close, self.real_close, self.fundamentals = adj_close, real_close, fundamentals
+        self.asof: pd.Timestamp | None = None
+        self.members: list[str] = []
+        self.picked: dict[str, float] | None = None
+        self.scores: dict[str, float] = {}
+
+    def at(self, asof: pd.Timestamp | None, members: list[str]) -> "PortfolioCtx":
+        self.asof, self.members, self.picked, self.scores = asof, members, None, {}
+        return self
+
+    def _hist(self, frame: pd.DataFrame) -> pd.DataFrame:
+        if self.asof is None or frame.empty:
+            return pd.DataFrame(columns=self.members)
+        cols = [m for m in self.members if m in frame.columns]
+        return frame.loc[:self.asof, cols]
+
+    # ── dữ liệu theo rổ ──
+    def close(self) -> pd.DataFrame:
+        """Bảng giá đóng cửa (hồi tố) của cả rổ tới phiên trước kỳ cân bằng: cột = mã, hàng = phiên."""
+        return self._hist(self.adj_close)
+
+    def basket(self) -> list[str]:
+        """Danh sách mã của rổ TẠI kỳ cân bằng đang xét (rổ theo thời điểm)."""
+        return list(self.members)
+
+    def momentum(self, n: int = 63) -> pd.Series:
+        """Lãi / lỗ n phiên gần nhất của từng mã (0,12 = +12%). 21 ≈ 1 tháng, 63 ≈ 3 tháng, 252 ≈ 1 năm."""
+        h = self._hist(self.adj_close)
+        if len(h) <= n:
+            return pd.Series(dtype=float)
+        return (h.iloc[-1] / h.iloc[-1 - int(n)] - 1).dropna()
+
+    def volatility(self, n: int = 63) -> pd.Series:
+        """Độ biến động năm hoá (độ lệch chuẩn lãi ngày × √250) của n phiên gần nhất, từng mã."""
+        h = self._hist(self.adj_close)
+        return h.pct_change(fill_method=None).iloc[-int(n):].std().dropna() * math.sqrt(250)
+
+    def fundamental(self, field: str) -> pd.Series:
+        """Chỉ số cơ bản kỳ gần nhất ĐÃ CÔNG BỐ tới ngày xét: "roe", "roa", "eps", "bvps", "net_profit", "revenue", "debt_to_equity"."""
+        day = self.asof.strftime("%Y-%m-%d") if self.asof is not None else ""
+        out = {}
+        for m in self.members:
+            rows = [r for r in self.fundamentals.get(m, []) if r["available_from"] <= day and r.get(field) is not None]
+            if rows:
+                out[m] = rows[-1][field]
+        return pd.Series(out, dtype=float)
+
+    def _eps_ttm(self) -> pd.Series:
+        day = self.asof.strftime("%Y-%m-%d") if self.asof is not None else ""
+        out = {}
+        for m in self.members:
+            q = [r for r in self.fundamentals.get(m, []) if "Q" in r["period"] and r["available_from"] <= day and r.get("eps") is not None]
+            if len(q) >= 4:
+                out[m] = sum(r["eps"] for r in q[-4:])
+        return pd.Series(out, dtype=float)
+
+    def _price(self) -> pd.Series:
+        h = self._hist(self.real_close)
+        return h.iloc[-1].dropna() if len(h) else pd.Series(dtype=float)
+
+    def pe(self) -> pd.Series:
+        """P/E: giá thật chia EPS 4 quý gần nhất đã công bố. Bỏ mã lỗ (EPS ≤ 0)."""
+        eps = self._eps_ttm()
+        eps = eps[eps > 0]
+        return (self._price() / eps).dropna()
+
+    def pb(self) -> pd.Series:
+        """P/B: giá thật chia giá trị sổ sách / cp kỳ gần nhất đã công bố."""
+        bv = self.fundamental("bvps")
+        bv = bv[bv > 0]
+        return (self._price() / bv).dropna()
+
+    # ── chọn ── (điểm xếp hạng của mã được chọn ghi lại để bảng "Nắm giữ" hiện cạnh tỷ trọng)
+    def _ranked(self, series: pd.Series, n: int, ascending: bool) -> list[str]:
+        if not len(series):
+            return []
+        chosen = series.sort_values(ascending=ascending).head(int(n))
+        self.scores = {str(k): round(float(v), 4) for k, v in chosen.items()}
+        return list(chosen.index)
+
+    def top(self, series: pd.Series, n: int = 3) -> list[str]:
+        """n mã có giá trị CAO nhất của chuỗi xếp hạng (động lượng, ROE…)."""
+        return self._ranked(series, n, False)
+
+    def bottom(self, series: pd.Series, n: int = 3) -> list[str]:
+        """n mã có giá trị THẤP nhất (P/E, P/B, biến động…)."""
+        return self._ranked(series, n, True)
+
+    def pick(self, chosen) -> None:
+        """Chốt danh mục kỳ này: danh sách mã (chia đều) hoặc dict mã → tỷ trọng (tự chuẩn hoá về 100%)."""
+        if isinstance(chosen, dict):
+            w = {k: float(v) for k, v in chosen.items() if float(v) > 0}
+        elif isinstance(chosen, pd.Series):
+            w = {k: 1.0 for k in chosen.index}
+        else:
+            w = {k: 1.0 for k in (chosen or [])}
+        total = sum(w.values())
+        self.picked = {k: v / total for k, v in w.items()} if total else {}
+
+    def exports(self) -> dict:
+        return {"momentum": self.momentum, "volatility": self.volatility, "fundamental": self.fundamental, "pe": self.pe,
+                "pb": self.pb, "top": self.top, "bottom": self.bottom, "pick": self.pick, "members": self.basket,
+                "prices": self.close}

hodlvn-0.1.0/hodl/rules_vn.py

@@ -0,0 +1,60 @@
+"""Luật thị trường cổ phiếu Việt Nam áp trong mọi backtest của Lab — người dùng KHÔNG phải tự viết.
+
+- Lô 100; KL làm tròn xuống theo lô, tiền lẻ giữ lại.
+- Biên độ trần / sàn theo sàn (HOSE 7%, HNX 10%, UPCoM 15%): giá mở chạm trần thì không mua được, chạm sàn thì không bán
+  được (không ai bán / mua đối ứng — giả định bảo thủ).
+- T+2,5: mua phiên T, khớp ở giá MỞ phiên sau tín hiệu → bán sớm nhất ở giá mở phiên T+3.
+- Phí mua / bán theo % giá trị (mặc định 0,15%), thuế bán 0,1%, thuế cổ tức tiền 5%.
+- Bước giá HOSE: <10.000 → 10đ, <50.000 → 50đ, còn lại 100đ (HNX/UPCoM 100đ).
+"""
+from __future__ import annotations
+
+LOT = 100
+PRICE_LIMIT = {"HOSE": 0.07, "HNX": 0.10, "UPCOM": 0.15}
+SETTLEMENT_BARS = 3
+DEFAULT_FEE_PCT = 0.15
+SELL_TAX_PCT = 0.1
+DIVIDEND_TAX_PCT = 5.0
+
+
+def tick(price: float, exchange: str = "HOSE") -> int:
+    if exchange != "HOSE":
+        return 100
+    return 10 if price < 10_000 else 50 if price < 50_000 else 100
+
+
+def round_tick(price: float, exchange: str = "HOSE") -> int:
+    t = tick(price, exchange)
+    return int(round(price / t)) * t
+
+
+def limit_band(ref: float, exchange: str = "HOSE") -> tuple[int, int]:
+    """(sàn, trần) từ giá tham chiếu (giá đóng phiên trước); làm tròn vào trong theo bước giá như sở."""
+    pct = PRICE_LIMIT.get(exchange.upper(), 0.07)
+    hi, lo = ref * (1 + pct), ref * (1 - pct)
+    t_hi, t_lo = tick(hi, exchange), tick(lo, exchange)
+    return int(-(-lo // t_lo) * t_lo), int(hi // t_hi * t_hi)
+
+
+def at_ceiling(price: float, ref: float, exchange: str = "HOSE") -> bool:
+    return ref > 0 and price >= limit_band(ref, exchange)[1]
+
+
+def at_floor(price: float, ref: float, exchange: str = "HOSE") -> bool:
+    return ref > 0 and price <= limit_band(ref, exchange)[0]
+
+
+def lots(cash: float, price: float, fee_pct: float) -> int:
+    """Số cổ phiếu mua được (bội số lô) với `cash`, đã tính phí mua."""
+    if price <= 0:
+        return 0
+    n = int(cash // (price * (1 + fee_pct / 100)))
+    return n // LOT * LOT
+
+
+def buy_cost(qty: int, price: float, fee_pct: float) -> float:
+    return qty * price * (1 + fee_pct / 100)
+
+
+def sell_proceeds(qty: int, price: float, fee_pct: float) -> float:
+    return qty * price * (1 - fee_pct / 100 - SELL_TAX_PCT / 100)