추가: allFilings HF dataset 업/다운로드 파이프라인 — pushAllFilings + lazy _ensureFromHf + 일일 cron 업로드.

eddmpython · eddmpython · commit 6dea9d69e090 · 2026-05-28T19:38:52.000+09:00
직전 PR 까지 allFilings 가 로컬 누적만 가능, HF dataset 동기화 부재. 본 PR 로 sectionsStorage / fieldIndexRebuild 와 동일 패턴 HF 업/다운로드 박음.

본 변경:
- pushAllFilings(periods=None, *, token=None) — 일자 list 받아 huggingface_hub.HfApi upload_file 로 {HF_REPO}:dart/allFilings/{period}.parquet 경로에 업로드. periods=None 이면 로컬 전체. HF_TOKEN env 부재 시 즉시 0 반환 (graceful skip).
- _ensureFromHf(period=None) — 로컬 부재 시 huggingface_hub.snapshot_download 로 lazy 다운로드. period 지정 시 단일 파일, None 이면 디렉토리 전체. DARTLAB_NO_HF_DOWNLOAD=1 env 로 offline 강제 skip + _HF_DOWNLOAD_ATTEMPTED set 으로 한 키 1 회만 시도 (실패 retry 회피).
- loadDay / loadAll wire — 로컬 부재 시 _ensureFromHf 자동 호출 → 사용자가 별도 prebuild 없이 첫 호출 시 자동 다운로드.
- .github/scripts/search/buildSearchDelta.py Phase 2.5 추가 — fillContent 직후 lookback 기간 (기본 30일) parquet 일괄 HF 업로드. HF_TOKEN 부재 시 skip.

설계 결정:
- 분리 디렉토리 X — sectionsStorage 동일 패턴. {HF_REPO}:dart/allFilings/{YYYYMMDD}.parquet 단일 경로.
- lookback 기간만 업로드 — 옛 immutable parquet 매일 재업로드 비용 회피. 일자당 ~6 MB × 30일 = 180 MB upload (HF Hub 의 diff-based commit 으로 변경 없는 파일 skip).
- snapshot_download local_dir=dataDir — 옛 sectionsStorage 동일.

회귀 가드 5 종 신규:
- test_push_all_filings_callable / test_ensure_from_hf_callable — import + callable smoke
- test_push_all_filings_no_token — HF_TOKEN 부재 시 0 반환 (외부 호출 차단)
- test_ensure_from_hf_env_skip — DARTLAB_NO_HF_DOWNLOAD=1 즉시 False
- test_ensure_from_hf_local_exists_short_circuit — 로컬 .parquet 있으면 snapshot_download 호출 0

실측 검증:
- 27일 재수집 (직전 백필 누락분): 390 rows
- HF push (5/26 5.9 MB): 1.1초, eddmpython/dartlab-data:dart/allFilings/20260526.parquet 박힘
- Lazy download (5/26 로컬 삭제 → loadDay): 1.29초, 5.9 MB 복원 + schema 검증 (content_raw + fetch_status 포함)
- 22 unit test 통과 (test-lock wrapper)
diff --git a/.github/scripts/search/buildSearchDelta.py b/.github/scripts/search/buildSearchDelta.py
@@ -2,8 +2,9 @@
 
 매일 실행:
 1. 최근 N일 allFilings 수집 (collectMeta + fillContent)
-2. content delta 세그먼트 빌드 (rebuildContentDelta)
-3. HF `eddmpython/dartlab-data` 에 `dart/contentIndex/delta.*` 업로드
+2. allFilings parquet HF 업로드 (lookback 기간 — 신규/정정/error retry 모두 반영)
+3. content delta 세그먼트 빌드 (rebuildContentDelta)
+4. HF `eddmpython/dartlab-data` 에 `dart/contentIndex/delta.*` 업로드
 
 main 풀리빌드는 별도 워크플로우 (월 1회).
 
@@ -49,6 +50,23 @@ def main() -> int:
     fillContent()
     print(f"  content 채우기 완료, {time.perf_counter() - t0:.0f}초")
 
+    # Phase 2.5: allFilings parquet HF 업로드 (lookback 기간 신규/정정/retry 반영)
+    if hfToken:
+        print("[delta] Phase 2.5: allFilings HF 업로드")
+        from datetime import datetime as _dt
+        from datetime import timedelta as _td
+
+        from dartlab.providers.dart.openapi.allFilingsCollector import pushAllFilings
+
+        # lookback 기간의 일자만 — 옛 immutable parquet 재업로드 비용 회피.
+        _today = _dt.now()
+        _lookbackDates = [(_today - _td(days=i)).strftime("%Y%m%d") for i in range(lookback)]
+        t0 = time.perf_counter()
+        nUp = pushAllFilings(_lookbackDates, token=hfToken)
+        print(f"  allFilings 업로드: {nUp} 파일, {time.perf_counter() - t0:.0f}초")
+    else:
+        print("[delta] Phase 2.5: HF_TOKEN 없음 — allFilings 업로드 skip")
+
     # Phase 3: delta 인덱스 빌드
     print("[delta] Phase 3: content delta 세그먼트 빌드")
     t0 = time.perf_counter()
diff --git a/src/dartlab/providers/dart/openapi/allFilingsCollector.py b/src/dartlab/providers/dart/openapi/allFilingsCollector.py
@@ -562,30 +562,154 @@ def pendingDates() -> list[str]:
     return dates
 
 
+# ═══════════════════════════════════════════
+# HF 동기화 (push / lazy pull)
+# ═══════════════════════════════════════════
+
+# 다운로드 1 회 시도 가드 (period 또는 "_ALL_") — 실패 시 무한 retry 회피.
+_HF_DOWNLOAD_ATTEMPTED: set[str] = set()
+
+
+def pushAllFilings(periods: list[str] | None = None, *, token: str | None = None) -> int:
+    """allFilings parquet 을 HF dataset 에 업로드.
+
+    sectionsStorage / fieldIndexRebuild 의 push 패턴과 동일 — `huggingface_hub.HfApi`
+    `upload_file` 로 일자별 `.parquet` 을 `{HF_REPO}:dart/allFilings/{period}.parquet`
+    경로에 저장. 옛 파일 같은 경로면 자동 덮어쓰기 (HF Hub 의 commit-based 업로드).
+
+    Args:
+        periods: 업로드 일자 list (YYYYMMDD). None 이면 로컬 `data/dart/allFilings/`
+            에 있는 모든 `.parquet` (정기 `*_meta.parquet` 제외).
+        token: HF token. None 이면 env `HF_TOKEN`.
+
+    Returns:
+        int — 업로드 성공 파일 수.
+
+    Raises:
+        없음 — HF 호출 실패는 warning 로그 후 다음 파일 진행.
+
+    Example:
+        >>> pushAllFilings(["20260527", "20260528"], token=os.environ["HF_TOKEN"])  # doctest: +SKIP
+    """
+    import os as _os
+
+    hfToken = token or _os.environ.get("HF_TOKEN", "")
+    if not hfToken:
+        _log.warning("[HF↑] HF_TOKEN 없음 — 업로드 skip")
+        return 0
+
+    outDir = _allFilingsDir()
+    if periods is None:
+        files = sorted(f for f in outDir.glob("*.parquet") if _META_SUFFIX not in f.stem)
+    else:
+        files = [outDir / f"{p}.parquet" for p in periods]
+        files = [f for f in files if f.exists()]
+
+    if not files:
+        _log.info("[HF↑] 업로드 대상 0")
+        return 0
+
+    from huggingface_hub import HfApi
+
+    from dartlab.core.dataConfig import HF_REPO
+
+    relDir = DATA_RELEASES[_ALLFILINGS_DIR_KEY]["dir"]
+    api = HfApi(token=hfToken)
+    ok = 0
+    for f in files:
+        dst = f"{relDir}/{f.name}"
+        try:
+            api.upload_file(
+                path_or_fileobj=str(f),
+                path_in_repo=dst,
+                repo_id=HF_REPO,
+                repo_type="dataset",
+            )
+            ok += 1
+            _log.info("[HF↑] %s (%.1f MB)", dst, f.stat().st_size / 1024 / 1024)
+        except Exception as exc:  # noqa: BLE001
+            _log.warning("[HF↑] %s 실패: %s", dst, exc)
+    _log.info("[HF↑] 완료: %d/%d 파일", ok, len(files))
+    return ok
+
+
+def _ensureFromHf(period: str | None = None) -> bool:
+    """artifact 부재 시 HF dataset 에서 lazy 다운로드.
+
+    sectionsStorage `_ensureFromHf` 동일 패턴 — `huggingface_hub.snapshot_download`
+    로 `{HF_REPO}:dart/allFilings/` 의 parquet 받음.
+
+    Args:
+        period: 특정 일자만 (YYYYMMDD) 받기. None 이면 디렉토리 전체.
+
+    Returns:
+        bool — 다운로드 성공 (또는 이미 로컬에 있음).
+
+    Raises:
+        없음 — 네트워크 / 인증 / 부재 실패는 warning 로그 후 False.
+
+    환경변수 `DARTLAB_NO_HF_DOWNLOAD=1` 시 즉시 skip. 한 (period or "_ALL_") 1 회만 시도.
+    """
+    import os as _os
+
+    outDir = _allFilingsDir()
+    if period is not None:
+        if (outDir / f"{period}.parquet").exists():
+            return True
+
+    if _os.environ.get("DARTLAB_NO_HF_DOWNLOAD", "").strip() in ("1", "true", "True"):
+        return False
+
+    key = period or "_ALL_"
+    if key in _HF_DOWNLOAD_ATTEMPTED:
+        return False
+    _HF_DOWNLOAD_ATTEMPTED.add(key)
+
+    try:
+        from huggingface_hub import snapshot_download
+
+        from dartlab.core.dataConfig import HF_REPO
+
+        relDir = DATA_RELEASES[_ALLFILINGS_DIR_KEY]["dir"]
+        pattern = f"{relDir}/{period}.parquet" if period else f"{relDir}/*.parquet"
+        snapshot_download(
+            repo_id=HF_REPO,
+            repo_type="dataset",
+            allow_patterns=[pattern],
+            local_dir=str(Path(_cfg.dataDir)),
+        )
+        return True
+    except Exception as exc:  # noqa: BLE001
+        _log.warning("[HF↓] allFilings 다운로드 실패 (%s): %s", period or "ALL", exc)
+        return False
+
+
 def loadDay(period: str) -> pl.DataFrame | None:
-    """수집된 하루치 데이터 로드.
+    """수집된 하루치 데이터 로드. 로컬 부재 시 HF 에서 lazy 다운로드.
 
     Args:
-        period: 인자.
+        period: YYYYMMDD.
 
     Raises:
         없음.
 
     Example:
-        >>> loadDay(...)
+        >>> loadDay("20260527")  # doctest: +SKIP
 
     Returns:
         pl.DataFrame 또는 None — 수집 결과.
     """
     path = _allFilingsDir() / f"{period}.parquet"
+    if not path.exists():
+        _ensureFromHf(period)
     if not path.exists():
         return None
     return pl.read_parquet(path)
 
 
 @withMemoryBudget(limitMb=500)
 def loadAll() -> pl.DataFrame:
-    """원문 수집 완료된 전체 데이터 로드.
+    """원문 수집 완료된 전체 데이터 로드. 로컬 디렉토리 비어있으면 HF 에서 lazy 다운로드.
 
     Args:
         (인자 자동 생성).
@@ -594,13 +718,16 @@ def loadAll() -> pl.DataFrame:
         없음.
 
     Example:
-        >>> loadAll(...)
+        >>> loadAll()  # doctest: +SKIP
 
     Returns:
         pl.DataFrame — 결과.
     """
     outDir = _allFilingsDir()
     files = sorted(f for f in outDir.glob("*.parquet") if _META_SUFFIX not in f.stem)
+    if not files:
+        _ensureFromHf()
+        files = sorted(f for f in outDir.glob("*.parquet") if _META_SUFFIX not in f.stem)
     if not files:
         return pl.DataFrame()
     return pl.scan_parquet(files).collect(engine="streaming")
diff --git a/tests/providers/dart/openapi/test_allFilingsCollector.py b/tests/providers/dart/openapi/test_allFilingsCollector.py
@@ -76,6 +76,61 @@ def test_stats_callable() -> None:
     assert callable(stats)
 
 
+def test_push_all_filings_callable() -> None:
+    """pushAllFilings() callable smoke."""
+    from dartlab.providers.dart.openapi.allFilingsCollector import pushAllFilings
+
+    assert callable(pushAllFilings)
+
+
+def test_ensure_from_hf_callable() -> None:
+    """_ensureFromHf() callable smoke."""
+    from dartlab.providers.dart.openapi.allFilingsCollector import _ensureFromHf
+
+    assert callable(_ensureFromHf)
+
+
+def test_push_all_filings_no_token(monkeypatch, tmp_path) -> None:
+    """HF_TOKEN 없으면 즉시 0 반환 — 외부 호출 없음."""
+    import dartlab.config as _cfg
+    from dartlab.providers.dart.openapi import allFilingsCollector as mod
+
+    monkeypatch.setattr(_cfg, "dataDir", str(tmp_path))
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+    n = mod.pushAllFilings()
+    assert n == 0
+
+
+def test_ensure_from_hf_env_skip(monkeypatch) -> None:
+    """DARTLAB_NO_HF_DOWNLOAD=1 환경에서 즉시 False — 외부 호출 없음."""
+    from dartlab.providers.dart.openapi import allFilingsCollector as mod
+
+    monkeypatch.setenv("DARTLAB_NO_HF_DOWNLOAD", "1")
+    mod._HF_DOWNLOAD_ATTEMPTED.clear()
+    result = mod._ensureFromHf("20990101")
+    assert result is False
+
+
+def test_ensure_from_hf_local_exists_short_circuit(monkeypatch, tmp_path) -> None:
+    """로컬에 이미 .parquet 있으면 HF 호출 없이 True."""
+    import dartlab.config as _cfg
+    from dartlab.providers.dart.openapi import allFilingsCollector as mod
+
+    monkeypatch.setattr(_cfg, "dataDir", str(tmp_path))
+    outDir = mod._allFilingsDir()
+    (outDir / "20260527.parquet").write_bytes(b"stub")
+
+    # snapshot_download 가 호출되면 실패 — 호출 없음 검증.
+    def shouldNotBeCalled(*args, **kwargs):
+        raise AssertionError("snapshot_download 호출됨 — short-circuit 실패")
+
+    import huggingface_hub
+
+    monkeypatch.setattr(huggingface_hub, "snapshot_download", shouldNotBeCalled)
+    mod._HF_DOWNLOAD_ATTEMPTED.clear()
+    assert mod._ensureFromHf("20260527") is True
+
+
 _STUB_DART_014 = (
     b'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
     b"<result><status>014</status><message>\xed\x8c\x8c\xec\x9d\xbc\xec\x9d\xb4 "
