Quant Factor Mining Framework

An auditable, point-in-time quantitative factor discovery framework for equities, futures, funds, digital assets, and other panel datasets.

The project implements a persistent generate - review - validate loop with typed expression trees, five proposal sources, structural diversity control, point-in-time data contracts, multiple-testing correction, append-only candidate provenance, and recoverable checkpoints.

What it provides

• Five candidate sources: mutation, crossover, parameter perturbation, random exploration, and LLM-guided proposals.
• Safe typed expressions instead of arbitrary generated code.
• Rule review for future-field access, complexity, lookback, dimensional consistency, and redundant structure.
• Point-in-time validation through available_at <= signal_time.
• Purged and embargoed discovery/validation/pre-confirmation/blind-test partitions.
• Rank IC, cross-sectional spread, tail removal, stability, correlation pruning, and Benjamini-Hochberg FDR.
• Append-only candidate ledgers and atomic checkpoints for unattended loops.
• A reference-replication mode for the supplied Loop Engineering article, with every disclosure gap explicitly fail-closed.
• An installable Codex Skill under skills/quant-factor-mining/.

The framework is deliberately asset- and strategy-agnostic. Portfolio construction, execution simulation, and domain-specific data adapters belong in downstream research projects.

Install

conda run -n base python -m pip install -e . --no-deps
conda run -n base python -m pytest -q

Smoke tests

Generic protocol and expression smoke:

conda run -n base qfmf smoke --config configs/example_research.yaml

Reference article loop smoke (100 synthetic candidates, no market data):

conda run -n base qfmf article-smoke --config configs/article_replication.yaml --output-dir artifacts/article-smoke

The article smoke is expected to certify zero candidates because the article states that it uses eleven gates but numerically defines only nine. The two unnamed gates are not guessed.

Codex Skill

Copy or symlink skills/quant-factor-mining into your Codex skills directory, then invoke it as $quant-factor-mining.

cp -R skills/quant-factor-mining "${CODEX_HOME:-$HOME/.codex}/skills/"

Research integrity

• Never open a blind partition before candidate expressions, direction, preprocessing, costs, and selection gates are content-locked.
• Never compound overlapping forward labels into a tradable return path.
• Treat every generated expression as part of the multiple-testing family, including rejected and failed candidates.
• Keep LLM explanations as review metadata, not empirical evidence.
• Do not label a replication exact when the source omits operators, gates, data definitions, or execution details.

See the locked protocol and the article disclosure matrix.

License

MIT. See LICENSE.