numeraire-dataset 0.1.0__tar.gz

numeraire_dataset-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # The single required check. The WRDS + network tests are deselected by default (pyproject
+  # addopts = "-m 'not network and not wrds'"), so CI never touches live credentials or the network.
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      # numeraire is not on PyPI yet; the local uv source ([tool.uv.sources]) pins the sibling
+      # checkout at ../numeraire, so provide both repos side by side exactly as they sit locally.
+      - name: Check out numeraire-dataset
+        uses: actions/checkout@v4
+        with:
+          path: numeraire-dataset
+          fetch-depth: 0   # full history so hatch-vcs derives the version
+      - name: Check out numeraire (dependency)
+        uses: actions/checkout@v4
+        with:
+          repository: py-numeraire/numeraire
+          ref: main
+          path: numeraire
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with: { python-version: "3.12" }
+      - name: Sync
+        working-directory: numeraire-dataset
+        run: uv sync --extra dev
+      - name: Lint & format
+        working-directory: numeraire-dataset
+        run: uv run ruff check . && uv run ruff format --check .
+      - name: Type check
+        working-directory: numeraire-dataset
+        run: uv run basedpyright src
+      - name: Tests
+        working-directory: numeraire-dataset
+        run: uv run pytest
+      - name: Build
+        working-directory: numeraire-dataset
+        run: uv build

numeraire_dataset-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+# Publish to PyPI via Trusted Publishing (OIDC, no stored secrets/tokens).
+#
+# Inert until a PyPI Trusted Publisher is configured for py-numeraire/numeraire-dataset AND a
+# GitHub Release is cut — an ordinary push never publishes. Publishing is decoupled from mainline:
+#
+#   push to main          -> CI only (ci.yml); NOT published
+#   push a tag (e.g. v*)  -> nothing; a bare tag does not publish
+#   create a Release      -> THIS workflow publishes that tag's version
+#
+# The release's tag drives the version (hatch-vcs), so the published version is exactly the tag
+# with no manual version bookkeeping. A Release marked "pre-release" on an rc/beta/alpha tag (e.g.
+# v0.1.0rc1) publishes a PyPI pre-release, which pip installs only with --pre.
+#
+# Release procedure:
+#   1. Move CHANGELOG.md [Unreleased] entries under a new [X.Y.Z] heading (first release: 0.1.0).
+#   2. gh release create vX.Y.Z --generate-notes   (or --notes from CHANGELOG)
+#   3. This workflow builds + publishes; verify `pip install numeraire-dataset==X.Y.Z`.
+#
+# workflow_dispatch is kept only as a manual fallback (e.g. re-run a failed publish); dispatch it
+# against the release tag ref so the version resolves.
+name: Publish
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # required for PyPI Trusted Publishing (OIDC); no secrets
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }   # full history so hatch-vcs derives the version from the tag
+      - uses: astral-sh/setup-uv@v6
+        with: { python-version: "3.12" }
+      - name: Build
+        run: uv build
+      - name: Check distributions
+        run: uvx twine check dist/*   # ephemeral twine; the publish job needs no dev toolchain
+      - uses: pypa/gh-action-pypi-publish@release/v1

numeraire_dataset-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+.pytest_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+
+# Secrets / credentials (WRDS etc.)
+.env
+.env.*
+*.pgpass
+
+# Built data & downloads — never commit bulk outputs; only tiny curated slices are added explicitly.
+*.parquet
+data/
+cache/
+downloads/
+~/.numeraire_data/

numeraire_dataset-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions are tag-driven (`hatch-vcs`); the first tagged release will be `0.1.0`.
+
+## [Unreleased]
+
+Everything below ships in the current tree and is slated for the first tagged release (`0.1.0`).
+
+### Added
+
+- **`sources` — tidyfinance-backed loaders.** Thin loaders over
+  [tidyfinance](https://github.com/tidy-finance/py-tidyfinance) for standard public sources
+  (Fama-French factors, Goyal-Welch predictors, and the FRED / JKP / q-factor / OSAP surface it
+  covers). Frame loaders (`load_ff_factors`, `load_goyal_welch`) return tidy frames and stay
+  `numeraire`-free; the `*_view` helpers (`load_gw_view`) add an optional `numeraire` bridge and a
+  `data_vintage` provenance stamp. This frame-vs-view split is intentional — see the README note.
+- **Raw → clean → view data zones.** A step registry with recipe-hash chaining
+  (`register_step` / `run_step` / `recipe_hash`), deterministic clean builders for the standard
+  WRDS-schema panels (`crsp_monthly_clean`, `compustat_annual_clean`,
+  `compustat_quarterly_clean`, `ccm_links_clean`), a `DataLock` from which a numeraire result's
+  `data_vintage` is derived, and a `zones.view` bridge (`to_cross_section_view`) that lifts a
+  clean panel into a numeraire `CrossSectionView`. The clean builders are pure transforms and run
+  without credentials; only `zones.wrds` performs live, credentialed pulls.
+- **`builders/fredmd` — vintage-aware FRED-MD.** Self-built ETL for what tidyfinance does not
+  cover: FRED-MD monthly vintages (reference period x vintage x series) with McCracken-Ng tcodes
+  applied at build time (`transform=True`), plus vintage archive download/cache helpers.
+- **WRDS zone (`zones.wrds`), optional `[wrds]` extra.** Live CRSP / Compustat pulls into the raw
+  zone from environment-only credentials (nothing written to disk), each cached as parquet with a
+  `_meta.json` query-hash sidecar in the outside-repo data home — licensed bytes never enter git.
+  Deselected in CI (network + wrds markers); the module imports fine without the extra.
+- **Packaging** — BSD-3 license, PEP 561 `py.typed`, per-version classifiers, and CI (lint,
+  format, basedpyright, pytest, build) plus an inert Trusted-Publishing release workflow.
+
+### Notes
+
+- Ships **code, not data.** No licensed or redistributable data is bundled; build outputs land in
+  a local, git-ignored cache. Public/synthetic fixtures and mocked pulls only in tests.

numeraire_dataset-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Yuheng Wu
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

numeraire_dataset-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: numeraire-dataset
+Version: 0.1.0
+Summary: Open data builders for numeraire: fetch + clean public and WRDS-sourced data into tidy, point-in-time tables.
+Project-URL: Homepage, https://github.com/py-numeraire/numeraire-dataset
+Project-URL: Repository, https://github.com/py-numeraire/numeraire-dataset
+Project-URL: Issues, https://github.com/py-numeraire/numeraire-dataset/issues
+Project-URL: Changelog, https://github.com/py-numeraire/numeraire-dataset/blob/main/CHANGELOG.md
+Author-email: Yuheng Wu <wuyuheng20074@live.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: asset-pricing,fred-md,macro,point-in-time,real-time-data,vintage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: tidyfinance>=0.3
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.18; extra == 'dev'
+Requires-Dist: numeraire<0.3,>=0.2; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: numeraire
+Requires-Dist: numeraire<0.3,>=0.2; extra == 'numeraire'
+Provides-Extra: wrds
+Requires-Dist: wrds>=3.2; extra == 'wrds'
+Description-Content-Type: text/markdown
+
+# numeraire-dataset
+
+Open, reproducible **data loaders + builders** for
+[`numeraire`](https://github.com/py-numeraire/numeraire). This package ships **code, not data**: it
+fetches public (and, with your own WRDS credentials, licensed) sources and cleans them into tidy,
+**point-in-time** tables that `numeraire` consumes.
+
+## Install
+
+```bash
+pip install numeraire-dataset               # frame loaders + builders (tidyfinance backend)
+pip install "numeraire-dataset[numeraire]"  # + the point-in-time view helpers (numeraire bridge)
+pip install "numeraire-dataset[wrds]"       # + live CRSP/Compustat pulls (your own WRDS account)
+```
+
+## Two layers
+
+- **`sources`** — [**tidyfinance**](https://github.com/tidy-finance/py-tidyfinance) (MIT) is the
+  primary backend for standard sources (Fama-French, Goyal-Welch, FRED, JKP, q-factors, OSAP).
+  Thin loaders return tidy frames (+ an optional point-in-time view helper) with `data_vintage`
+  provenance — no loader hand-rolling.
+- **`builders`** — self-built ETL for what tidyfinance does *not* cover: **vintage-aware FRED-MD**
+  (reference period × vintage × series, tcodes applied at build time) and, with your own
+  credentials, WRDS panels. (The FRED-MD vintage/tcode design is a candidate to upstream into
+  tidyfinance — once merged, its `sources` path could replace the local builder.)
+
+## Why a separate project
+
+`numeraire` (the framework) bundles only tiny public example slices. Anything that needs to be
+**downloaded, merged across releases, or built from a subscription source** lives here, as
+transparent open-source ETL — so the cleaning is auditable and re-runnable, and no licensed data is
+ever redistributed inside a wheel. Build outputs land in a local cache (git-ignored), never the repo.
+
+## Design: build once, read clean
+
+```
+raw vendor files  ──build (this package)──▶  tidy point-in-time table  ──read──▶  numeraire
+   (download)            clean / tcode                [reference period × vintage × series]
+```
+
+- **The vintage axis is a column.** Each value carries the *reference period* it describes and the
+  *vintage* (data release) it came from, so revisions are first-class and `asof` is leak-safe.
+- **Stationarity transforms (FRED-MD tcodes) are applied at build time, per vintage** — never inside
+  numeraire's main pipeline. `transform=False` keeps raw levels.
+- **Availability lag (`L`) is NOT baked in.** It stays a read-time parameter in numeraire, so you can
+  sweep it for robustness. The table stores only `(reference period, vintage, series…)`.
+
+## Builders
+
+| Builder | Source | License of output | Status |
+|---|---|---|---|
+| `fredmd` | FRED-MD monthly vintages (St. Louis Fed, McCracken-Ng) | public (cite McCracken-Ng 2016) | in progress |
+| `famafrench` | Ken French Data Library | public (cite, carry copyright notice) | planned |
+| `zones.wrds` | CRSP / Compustat panels (your WRDS account) | **not redistributable** — local only | implemented |
+
+## Usage
+
+```python
+# Standard sources via tidyfinance (frames; + a view helper with the `numeraire` extra):
+from numeraire_dataset import load_ff_factors, load_gw_view
+
+ff = load_ff_factors()                       # date, mkt_excess, smb, hml, risk_free  (decimals)
+view, vintage = load_gw_view(start_date="1926-07-01", end_date="2020-12-31")
+# → feed `view` straight into numeraire's backtest_forecast; `vintage` is the provenance stamp.
+
+# Vintage-aware FRED-MD (what tidyfinance lacks) via the local builder:
+from numeraire_dataset.builders import fredmd
+
+paths = fredmd.download(vintages=["2025-01", "2025-02", "2025-03"], dest="~/.numeraire_data")
+table = fredmd.build_table(paths, transform=True)   # tidy [reference, vintage, series…]
+```
+
+### Frame loaders vs. `*_view` helpers
+
+The split is intentional, not an oversight. **Frame loaders** (`load_ff_factors`,
+`load_goyal_welch`) return plain tidy `pandas` frames and carry **no `numeraire` dependency**, so
+they are usable on their own. The **`*_view` helpers** (`load_gw_view`, `zones.view`) add the
+optional bridge into a `numeraire` view plus a `data_vintage` stamp, and only import `numeraire`
+lazily (install the `[numeraire]` extra). A frame loader is therefore a strict subset of the
+work a view helper does — the names differ because their return contracts and dependency footprints
+differ, and both are kept rather than collapsed into one signature.
+
+License: **BSD-3-Clause** (code). Source datasets keep their own terms — see each builder's docstring.

numeraire_dataset-0.1.0/README.md

@@ -0,0 +1,83 @@
+# numeraire-dataset
+
+Open, reproducible **data loaders + builders** for
+[`numeraire`](https://github.com/py-numeraire/numeraire). This package ships **code, not data**: it
+fetches public (and, with your own WRDS credentials, licensed) sources and cleans them into tidy,
+**point-in-time** tables that `numeraire` consumes.
+
+## Install
+
+```bash
+pip install numeraire-dataset               # frame loaders + builders (tidyfinance backend)
+pip install "numeraire-dataset[numeraire]"  # + the point-in-time view helpers (numeraire bridge)
+pip install "numeraire-dataset[wrds]"       # + live CRSP/Compustat pulls (your own WRDS account)
+```
+
+## Two layers
+
+- **`sources`** — [**tidyfinance**](https://github.com/tidy-finance/py-tidyfinance) (MIT) is the
+  primary backend for standard sources (Fama-French, Goyal-Welch, FRED, JKP, q-factors, OSAP).
+  Thin loaders return tidy frames (+ an optional point-in-time view helper) with `data_vintage`
+  provenance — no loader hand-rolling.
+- **`builders`** — self-built ETL for what tidyfinance does *not* cover: **vintage-aware FRED-MD**
+  (reference period × vintage × series, tcodes applied at build time) and, with your own
+  credentials, WRDS panels. (The FRED-MD vintage/tcode design is a candidate to upstream into
+  tidyfinance — once merged, its `sources` path could replace the local builder.)
+
+## Why a separate project
+
+`numeraire` (the framework) bundles only tiny public example slices. Anything that needs to be
+**downloaded, merged across releases, or built from a subscription source** lives here, as
+transparent open-source ETL — so the cleaning is auditable and re-runnable, and no licensed data is
+ever redistributed inside a wheel. Build outputs land in a local cache (git-ignored), never the repo.
+
+## Design: build once, read clean
+
+```
+raw vendor files  ──build (this package)──▶  tidy point-in-time table  ──read──▶  numeraire
+   (download)            clean / tcode                [reference period × vintage × series]
+```
+
+- **The vintage axis is a column.** Each value carries the *reference period* it describes and the
+  *vintage* (data release) it came from, so revisions are first-class and `asof` is leak-safe.
+- **Stationarity transforms (FRED-MD tcodes) are applied at build time, per vintage** — never inside
+  numeraire's main pipeline. `transform=False` keeps raw levels.
+- **Availability lag (`L`) is NOT baked in.** It stays a read-time parameter in numeraire, so you can
+  sweep it for robustness. The table stores only `(reference period, vintage, series…)`.
+
+## Builders
+
+| Builder | Source | License of output | Status |
+|---|---|---|---|
+| `fredmd` | FRED-MD monthly vintages (St. Louis Fed, McCracken-Ng) | public (cite McCracken-Ng 2016) | in progress |
+| `famafrench` | Ken French Data Library | public (cite, carry copyright notice) | planned |
+| `zones.wrds` | CRSP / Compustat panels (your WRDS account) | **not redistributable** — local only | implemented |
+
+## Usage
+
+```python
+# Standard sources via tidyfinance (frames; + a view helper with the `numeraire` extra):
+from numeraire_dataset import load_ff_factors, load_gw_view
+
+ff = load_ff_factors()                       # date, mkt_excess, smb, hml, risk_free  (decimals)
+view, vintage = load_gw_view(start_date="1926-07-01", end_date="2020-12-31")
+# → feed `view` straight into numeraire's backtest_forecast; `vintage` is the provenance stamp.
+
+# Vintage-aware FRED-MD (what tidyfinance lacks) via the local builder:
+from numeraire_dataset.builders import fredmd
+
+paths = fredmd.download(vintages=["2025-01", "2025-02", "2025-03"], dest="~/.numeraire_data")
+table = fredmd.build_table(paths, transform=True)   # tidy [reference, vintage, series…]
+```
+
+### Frame loaders vs. `*_view` helpers
+
+The split is intentional, not an oversight. **Frame loaders** (`load_ff_factors`,
+`load_goyal_welch`) return plain tidy `pandas` frames and carry **no `numeraire` dependency**, so
+they are usable on their own. The **`*_view` helpers** (`load_gw_view`, `zones.view`) add the
+optional bridge into a `numeraire` view plus a `data_vintage` stamp, and only import `numeraire`
+lazily (install the `[numeraire]` extra). A frame loader is therefore a strict subset of the
+work a view helper does — the names differ because their return contracts and dependency footprints
+differ, and both are kept rather than collapsed into one signature.
+
+License: **BSD-3-Clause** (code). Source datasets keep their own terms — see each builder's docstring.

numeraire_dataset-0.1.0/docs/data-zones-design.md

@@ -0,0 +1,104 @@
+# Data zones: raw → clean → view (design)
+
+> Design note for the WRDS-scale data lifecycle in `numeraire-dataset`. Written before the
+> implementation (W3-1). The three-zone split makes preprocessing **reproducible and pinnable**:
+> a numeraire result's `data_vintage` string must trace back, unambiguously, to exactly the bytes
+> and the exact transform recipe that produced its inputs.
+
+## Why three zones
+
+Preprocessing is part of the method. A Sharpe or an alpha is only reproducible if the *cleaning* —
+delisting adjustments, share-code filters, CCM link windows, the accounting-to-return lag — is
+pinned as tightly as the model. So the pipeline is split into three zones with hard boundaries:
+
+```
+raw/     immutable download cache, keyed by (source, vintage)      — bytes as pulled, never edited
+clean/   deterministic transforms of raw → tidy PIT tables         — a recipe hash pins the transform
+view/    numeraire TimeSeriesView / CrossSectionView builders      — lazy numeraire import, no new state
+```
+
+Arrows point one way: `view` reads `clean`, `clean` reads `raw`, `raw` reads the outside world.
+Nothing downstream mutates an upstream zone.
+
+### raw — immutable, pull-stamped
+
+- One directory per `(source, vintage)`, e.g. `raw/crsp_msf/2024-12/`. `vintage` is the pull's
+  identity: a WRDS query date, a FRED-MD month, a Ken French release. Content is the bytes exactly
+  as pulled (parquet/csv), **never edited in place** — a re-pull with different content is a new
+  vintage directory, not an overwrite.
+- Each pull writes a sibling `_meta.json`: `{source, vintage, pulled_at, query_hash, pit_status,
+  row_count, content_digest}`. `pit_status` records whether the pull is itself point-in-time
+  (a dated vintage) or a latest-snapshot convenience pull (revised, not PIT) — so a downstream
+  golden can refuse a non-PIT source.
+- **The cache directory is user-configurable and defaults OUTSIDE the repo** (`$NUMERAIRE_DATA` →
+  platform cache dir, per `paths.data_home`). Licensed data (CRSP/Compustat) lives only here, on
+  the user's machine behind their own WRDS credentials — **never in any git history**.
+
+### clean — deterministic, recipe-hashed
+
+- A `clean` table is produced by one or more **steps**: pure `frame(s) → frame` functions with
+  **all parameters explicitly declared** (no hidden globals, no ambient config). A step is
+  deterministic: same inputs + same params → same output, bit-for-bit.
+- Every step's identity is `(name, version, params)`. Its **recipe hash** is the SHA-256 of the
+  canonical JSON of `{name, version, params, inputs: [<recipe hash of each input>]}`. The hash
+  therefore **chains**: a clean table's recipe hash transitively pins every upstream transform and
+  every raw vintage that fed it. Bump `version` when a step's logic changes in a way that should
+  invalidate downstream caches.
+- Steps register in an **open registry** (the same pattern as numeraire's evaluator registry —
+  `register_step` / `get_step` / `available_steps`, a module-global dict, `KeyError` on a duplicate
+  name unless `overwrite`). No second registration style is invented. A `@step(...)` decorator is
+  sugar over `register_step`.
+
+### view — numeraire builders, lazy
+
+- `view` builders turn a `clean` table into a numeraire `TimeSeriesView` / `CrossSectionView`.
+  They import `numeraire` **lazily** (as `sources.to_timeseries_view` already does), so the clean +
+  raw zones stay numeraire-free and installable without it. `view` adds no persisted state.
+
+## `data.lock.json`
+
+A single lock file records, for each built `clean` (and pinned `raw`) artifact, exactly what it is:
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "crsp_monthly_clean": {
+      "kind": "clean",
+      "step": "crsp_monthly_clean",
+      "step_version": 1,
+      "recipe_hash": "sha256:9f3c…",
+      "content_digest": "sha256:1a2b…",
+      "inputs": ["crsp_msf@2024-12", "crsp_msenames@2024-12"],
+      "rows": 4193021,
+      "built_at": "2026-07-05T…"
+    },
+    "crsp_msf@2024-12": {
+      "kind": "raw", "source": "crsp_msf", "vintage": "2024-12",
+      "content_digest": "sha256:…", "pit_status": "vintage"
+    }
+  }
+}
+```
+
+- `recipe_hash` pins the transform; `content_digest` pins the actual output bytes (so a corrupted
+  or partial build is detectable independently of the recipe).
+- **`data_vintage` derivation (the contract with numeraire).** The `data_vintage` string a numeraire
+  result carries for a table `T` is derived *directly* from `T`'s lock entry:
+  `data_vintage = f"{name}@{recipe_hash[:12]}"` (e.g. `crsp_monthly_clean@9f3c1d2e4a5b`). Given a
+  result's `data_vintage`, the lock entry — and thus the full recipe + raw vintages — is recoverable
+  by name and hash prefix. No provenance is stored in two places that could disagree.
+
+## WRDS goldens ride the `WRDS-CRED` tier
+
+The reproductions that need CRSP/Compustat (W3-2 GKX-lite, W3-3 ALZ empirical, W3-4 HXZ) register
+their targets as `numeraire.golden.GoldenCase(tier=WRDS_CRED, available=<creds+cache present>)`.
+That mechanism (built in F3) makes them **skip in CI** and run verbatim where the user's WRDS
+credentials and raw cache are present — one code path, no forked assertions, no licensed bytes in
+the repo. Live WRDS tests carry `@pytest.mark.wrds` and are deselected by default.
+
+## Boundaries restated (red lines)
+
+- WRDS credentials go through env / the tidyfinance WRDS config — never committed, never in code.
+- The raw cache is user-configurable and outside the repo by default.
+- No licensed data (CRSP/Compustat/JKP returns) in any tracked file or git history — ever.

numeraire_dataset-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "numeraire-dataset"
+dynamic = ["version"]
+description = "Open data builders for numeraire: fetch + clean public and WRDS-sourced data into tidy, point-in-time tables."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+authors = [{ name = "Yuheng Wu", email = "wuyuheng20074@live.com" }]
+keywords = ["asset-pricing", "macro", "real-time-data", "fred-md", "point-in-time", "vintage"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Typing :: Typed",
+]
+dependencies = [
+  "numpy>=1.26",
+  "pandas>=2.0",
+  "pyarrow>=15",
+  "platformdirs>=4.0",
+  # tidyfinance is the primary backend for standard sources (Fama-French, Goyal-Welch, FRED, JKP,
+  # q-factors, OSAP). The local builders cover what it lacks: vintage FRED-MD (until upstreamed) and
+  # licensed WRDS panels.
+  "tidyfinance>=0.3",
+]
+
+[project.optional-dependencies]
+# WRDS-sourced builders (factor panels) bring their own heavy deps; public builders need none.
+wrds = ["wrds>=3.2"]
+# The tidyfinance loaders return tidy frames with no numeraire dependency; install this extra to also
+# get the point-in-time TimeSeriesView helper (numeraire is not on PyPI yet — see [tool.uv.sources]).
+numeraire = ["numeraire>=0.2,<0.3"]
+dev = [
+  "pytest>=8.0", "pytest-cov>=5.0",
+  "ruff>=0.6", "basedpyright>=1.18", "pandas-stubs>=2.0",
+  "numeraire>=0.2,<0.3",  # exercise the view helper in tests
+]
+
+# numeraire is not on PyPI yet — resolve it from the sibling checkout for local dev.
+[tool.uv.sources]
+numeraire = { path = "../numeraire", editable = true }
+
+[project.urls]
+Homepage = "https://github.com/py-numeraire/numeraire-dataset"
+Repository = "https://github.com/py-numeraire/numeraire-dataset"
+Issues = "https://github.com/py-numeraire/numeraire-dataset/issues"
+Changelog = "https://github.com/py-numeraire/numeraire-dataset/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/numeraire_dataset"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "NPY", "PD", "RUF"]
+
+[tool.basedpyright]
+# Standard (not strict): this is a data-prep tool, not numeraire's core spine.
+typeCheckingMode = "standard"
+include = ["src/numeraire_dataset"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not network and not wrds'"
+markers = [
+  "network: hits a live data source (deselected by default; run with -m network)",
+  "wrds: hits live WRDS behind the user's own credentials (deselected; run with -m wrds)",
+]

numeraire_dataset-0.1.0/src/numeraire_dataset/__init__.py

@@ -0,0 +1,28 @@
+"""numeraire-dataset: open, reproducible builders + loaders that fetch and clean data for numeraire.
+
+Ships code, not data. Two layers:
+
+- :mod:`numeraire_dataset.sources` — tidyfinance-backed loaders for standard sources (Fama-French,
+  Goyal-Welch, …), returning tidy frames (+ an optional point-in-time view helper).
+- :mod:`numeraire_dataset.builders` — self-built ETL for what tidyfinance lacks: vintage-aware
+  FRED-MD (reference period x vintage x series, tcodes at build time) and, with your own
+  credentials, WRDS panels.
+"""
+
+from __future__ import annotations
+
+from numeraire_dataset.sources import (
+    data_vintage,
+    load_ff_factors,
+    load_goyal_welch,
+    load_gw_view,
+    to_timeseries_view,
+)
+
+__all__ = [
+    "data_vintage",
+    "load_ff_factors",
+    "load_goyal_welch",
+    "load_gw_view",
+    "to_timeseries_view",
+]

numeraire_dataset-0.1.0/src/numeraire_dataset/builders/__init__.py

@@ -0,0 +1,5 @@
+"""Data builders. Each module fetches one source and emits a tidy point-in-time table."""
+
+from __future__ import annotations
+
+__all__: list[str] = []