factor-researcher

FactorMiner

LLM-driven formulaic alpha mining with typed operators, structured memory, strict runtime recomputation, and a Phase 2 Helix research lane

FactorMiner is a research framework for discovering interpretable alpha factors from market data. It combines:

• a typed DSL over OHLCV-style market features
• an LLM-guided mining loop
• structured experience memory
• library admission and replacement based on predictive power and orthogonality
• strict runtime recomputation for analysis and benchmark reporting
• an extended Helix lane for Phase 2 retrieval, canonicalization, and post-admission validation

The implementation is based on FactorMiner: A Self-Evolving Agent with Skills and Experience Memory for Financial Alpha Discovery (Wang et al., 2026), then extended with a cleaner architecture layer and a broader research surface.

Repository Status

Current implementation focus:

• canonical paper-style and research mining lanes
• typed DSL operators for OHLCV-style factor formulas
• 110 paper factors shipped in the built-in catalog
• runtime recomputation for analysis and benchmark reporting
• CI-backed lint, test, package, CLI smoke, and benchmark-smoke checks

For live local counts, run:

uv run pytest --collect-only -q factorminer/tests
uv run python - <<'PY'
from pathlib import Path
files = sorted(Path("factorminer").rglob("*.py"))
lines = sum(p.read_text(errors="ignore").count("\n") + 1 for p in files)
print(f"Python files: {len(files)}")
print(f"Python lines: {lines}")
PY

Primary execution surfaces:

• RalphLoop: canonical paper-style mining loop
• HelixLoop: Phase 2 research loop with optional retrieval and validation extensions
• factorminer.benchmark.runtime: canonical benchmark runner
• factorminer.architecture: canonical contracts, policies, stages, and services

Documentation Map

• Architecture Deep Dive
• Metric Semantics
• Paper Claims Matrix
• Benchmark Baselines
• FAQ
• Reproducibility Guide
• Binance Reproduction Notes
• Bundled Data Notes
• Repo Audit
• Contributing
• Roadmap

Architecture At A Glance

flowchart TD
    A["Market Data"] --> B["DatasetContract"]
    B --> C["Typed DSL + Operator Registry"]
    C --> D["Ralph / Helix Stage Pipeline"]
    D --> E["EvaluationKernel"]
    E --> F["FactorAdmissionService"]
    F --> G["FactorLibrary"]
    D --> H["MemoryPolicy"]
    H --> I["PromptContextBuilder"]
    I --> D
    G --> J["Runtime Analysis"]
    G --> K["Runtime Benchmarks"]
    H --> K
    B --> K

Two execution lanes share the same core contracts:

Lane	Purpose	Canonical loop	Typical use
Paper lane	strict, benchmark-facing mining	RalphLoop	reproducible paper-style runs, library freeze, runtime evaluation
Helix lane	extended research mode	HelixLoop	debate, KG retrieval, family-aware prompts, canonicalization, Phase 2 validation

Core Concepts

1. Typed factor DSL

Factors are formulas over the canonical feature set:

$open, $high, $low, $close, $volume, $amt, $vwap, $returns

The DSL is parsed into expression trees, executed through the operator registry, and recomputed on demand during analysis and benchmarks. Paper appendix operator names such as SignedPower, Med, Rsquare, Slope, Resi, Eq, Min2, Max2, TsDecay, and Scale are accepted by the parser.

2. Memory-guided mining

Mining is not plain prompt-and-filter generation. The loop builds a structured retrieval signal from experience memory and library state, then uses it to steer candidate generation.

Supported memory policies:

• paper
• none
• kg
• family_aware
• regime_aware

3. Strict runtime recomputation

Saved library metadata is not treated as the final source of truth for analysis. The evaluate, combine, visualize, and benchmark paths recompute factor signals from formulas on the supplied dataset.

4. Canonical benchmark surface

factorminer.benchmark.runtime is the canonical benchmark entry point. It supports:

• Top-K freeze evaluation across universes
• memory ablations
• strategy-grid ablations over memory policy × dependence metric × backend
• cost-pressure evaluation
• operator and factor efficiency benchmarking

Canonical Runtime Flow