# Factor Mining

> Discover alpha factors by running the FactorMiner research engine — the paper-faithful Ralph loop or the enhanced Helix loop (causal validation, regime conditioning, multi-specialist debate, canonicalization). Use to generate a new factor library from a validated dataset. Triggers on "mine factors", "discover factors", "run mining", "find alpha", "helix loop", "ralph loop", "build a factor librar…

- **Type:** Skill
- **Install:** `agentstack add skill-minihellboy-factorminer-factor-mining`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [minihellboy](https://agentstack.voostack.com/s/minihellboy)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [minihellboy](https://github.com/minihellboy)
- **Source:** https://github.com/minihellboy/factorminer/tree/main/plugins/agent-plugins/factor-researcher/skills/factor-mining

## Install

```sh
agentstack add skill-minihellboy-factorminer-factor-mining
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Factor Mining

This skill runs FactorMiner's self-evolving discovery loop: it retrieves memory priors, proposes candidate factor formulas with an LLM, evaluates them, and admits the survivors to a factor library.

See `references/loop-architecture.md` for the stage-by-stage loop design and `references/dsl-operators.md` for the factor-formula operator vocabulary.

## Choosing the loop

| Use | When |
|---|---|
| `mine` (Ralph loop) | Default. Paper-faithful Algorithm 1 — retrieve, generate, evaluate, admit, evolve memory. |
| `helix` (Helix loop) | When you want Phase 2 features: do-calculus causal validation, regime-conditional evaluation, multi-specialist debate generation, or SymPy canonicalization. Drop-in superset of Ralph. |

## Workflow

### 1. Confirm prerequisites

The dataset must already pass `factor-data` validation. Confirm the iteration budget — mining cost scales with `iterations × batch-size`.

### 2. Run the Ralph loop

```bash
factorminer -o output/run1 mine \
  --data path/to/market_data.csv \
  --iterations 40 --batch-size 16 --target 30
```

- `--iterations` — maximum mining iterations (the loop also stops early once `--target` factors are admitted).
- `--batch-size` — candidate factors proposed per iteration.
- `--target` — desired library size.
- `--resume path/to/factor_library.json` — continue a previous run.
- `--mock` — synthetic data + mock LLM, no API calls. Use only for smoke tests.

### 3. Or run the Helix loop

```bash
factorminer -o output/run1 helix \
  --data path/to/market_data.csv \
  --iterations 40 --batch-size 16 --target 30 \
  --causal --regime --debate --canonicalize
```

Each `--feature / --no-feature` flag overrides the config; omit a flag to keep the config default. Phase 2 features cost extra compute and LLM calls — enable the ones the research question needs.

### 4. Inspect the result

```bash
factorminer session inspect output/run1 --json
```

Report library size, iteration count, and yield rate. The factor library is written to `output/run1/factor_library.json`; the run log to `session_log.json`.

## Guardrails

- Mining proposes formulas; it does not prove them. Always follow with `factor-evaluation` on the held-out split.
- A low yield rate usually means thresholds are too strict for the dataset, not that the data is bad — tune `ic_threshold` / `correlation_threshold` in config, do not silently relax them in a report.
- `--mock` output is never a research result; never present mock metrics as real.

## MCP alternative

When the FactorMiner MCP server is connected, `mine_factors` and `helix_mine` expose the same workflow as tools, returning a structured session summary directly.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [minihellboy](https://github.com/minihellboy)
- **Source:** [minihellboy/factorminer](https://github.com/minihellboy/factorminer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-minihellboy-factorminer-factor-mining
- Seller: https://agentstack.voostack.com/s/minihellboy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.