factor-researcher

FactorMiner

A governed research engine for discovering, evaluating, and documenting interpretable alpha factors.

FactorMiner combines a typed formula DSL, LLM-guided search, structured memory, strict runtime recomputation, and reviewable research artifacts. It follows the system described in FactorMiner: A Self-Evolving Agent with Skills and Experience Memory for Financial Alpha Discovery and extends it with explicit architecture contracts, stronger validation, and a model-agnostic agent integration surface.

FactorMiner is research infrastructure. It proposes and evaluates artifacts; it does not recommend trades, size positions, bind risk limits, route orders, or operate an autonomous account.

What is included

Surface	Purpose
Typed DSL and operator registry	Safe, interpretable formulas over OHLCV and registered feature leaves
RalphLoop	Canonical paper-style generate/evaluate/evolve lane
HelixLoop	Extended retrieval, debate, canonicalization, and validation lane
Policy-based memory	Paper, none, KG, family-, regime-, and edit-aware policies
Runtime evaluation	Formula recomputation on the supplied dataset; saved summaries are not trusted as truth
Benchmark runtime	Top-K freeze, memory/strategy ablations, CPCV/PBO, cost pressure, and efficiency
Research extensions	EDGAR/futures data, crowding, capacity, sensitivity, model-risk, and provenance artifacts
Agent gateway	MCP server plus a plugin and managed-agent reference integration

The built-in catalog contains 110 normalized paper factors. Named third-party baselines are not all faithful reproductions; manifests label catalog subsets, proxies, runtime loops, and saved libraries explicitly. See Reproducibility before interpreting benchmark output.

Install

The recommended contributor setup uses uv:

git clone https://github.com/minihellboy/factorminer.git
cd factorminer
uv sync --group dev --all-extras

For a smaller local environment:

uv sync --group dev
uv sync --group dev --extra llm   # add hosted/local LLM providers
uv sync --group dev --extra mcp   # add the MCP server

The portable default backend is NumPy. The CUDA extra is Linux-oriented; use --gpu only where CUDA is available. A pip editable install also works:

python3 -m pip install -e ".[llm,mcp]"

Quick start

No API key is required for the deterministic demo and mock workflow:

uv run python scripts/run_demo.py
uv run factorminer quickstart
uv run factorminer doctor --json

quickstart writes a small library and static report under /tmp/factorminer-quickstart. To mine directly:

uv run factorminer -o /tmp/factorminer-run mine --mock -n 2 -b 8 -t 10
uv run factorminer session inspect /tmp/factorminer-run --telemetry

For real data, validate the schema first:

uv run factorminer validate-data path/to/market_data.csv
uv run factorminer -c factorminer.local.yaml -o output-real \
  mine --data path/to/market_data.csv

The minimum panel fields are:

datetime, asset_id, open, high, low, close, volume, amount

Identifier aliases such as symbol, ticker, code, and ts_code are accepted. Missing vwap and returns can be derived by the runtime layer.

Core workflows

Run the extended research lane:

uv run factorminer --cpu helix --mock --debate --canonicalize -n 2 -b 8 -t 10

Recompute and evaluate a saved library:

uv run factorminer --cpu evaluate output/factor_library.json \
  --mock --period both --top-k 10

Build a composite on explicit fit/evaluation splits:

uv run factorminer --cpu combine output/factor_library.json \
  --mock --fit-period train --eval-period test --method all \
  --selection lasso --top-k 20

Run a benchmark or the standalone Phase 2 report builder:

uv run factorminer --cpu --config factorminer/configs/paper_repro.yaml \
  benchmark table1 --mock --baseline factor_miner
uv run factorminer --cpu benchmark ablation-strategy --mock \
  --baseline factor_miner
uv run python scripts/run_phase2_benchmark.py --mock

The CLI also exposes data validation/resampling, visualization, CPCV, portfolio construction, crowding and sensitivity diagnostics, EDGAR/futures attachment, research ingestion, RFT dataset export, sealed search, model co-optimization, and MCP transports. Use uv run factorminer --help and command-level --help as the authoritative command reference.

Architecture