Skip to content
Back to search

factorminer

MarketplaceWorks with Claude CodeGitHub

A Self-Evolving Agent with Skills and Experience Memory for Financial Alpha Discovery

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/minihellboy/factorminer with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/minihellboy/factorminer'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/minihellboy--factorminer/badge.svg)](/listings/minihellboy--factorminer)

HTML

<a href="/listings/minihellboy--factorminer"><img src="/api/listings/minihellboy--factorminer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/):

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

NumPy is the default backend. Optional extras include `mcp`, `research`, `embeddings`, `visualization`, and `gpu`; the CUDA extra targets Linux. `uv sync --frozen --extra gpu` installs patched PyTorch with CUDA 12.6 and CuPy for CUDA 12. The base install needs neither Torch nor a GPU. See [backend scope](docs/architecture.md#numerical-backends) and [platform setup and checks](CONTRIBUTING.md#optional-model-and-gpu-environments).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "factorminer",
  3. "owner": {
  4. "name": "FactorMiner Team"
  5. },
  6. "plugins": [
  7. {
  8. "name": "factor-researcher",
  9. "source": "./integrations/factor-researcher/plugin",
  10. "description": "Systematic quantitative alpha-factor research: validate market data, mine a factor library, evaluate IC/ICIR, backtest a composite, benchmark, and report — powered by the FactorMiner engine"
  11. }
  12. ]
  13. }
README.md · README · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # FactorMiner
  2. **Symbolic factor discovery with LLM-guided search, reproducible evaluation,
  3. and transferable research memory.**
  4. [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  6. [![CI](https://github.com/minihellboy/factorminer/actions/workflows/ci.yml/badge.svg)](https://github.com/minihellboy/factorminer/actions/workflows/ci.yml)
  7. FactorMiner generates interpretable formulas, evaluates them on market data,
  8. and records their lineage, metrics, and admission decisions. Shared evaluation
  9. and memory contracts support local mining, controlled experiments, and agent
  10. integrations. Outputs are research artifacts; the project does not execute trades.
  11. ## Capabilities
  12. | Component | Function |
  13. | --- | --- |
  14. | Formula engine | Typed DSL with NumPy evaluation; optional compiled operators and Torch kernels |
  15. | Mining | Ralph and Helix loops with generation, evaluation, memory, and checkpoints |
  16. | Experiment selection | Opt-in generation, refinement, delay challenges, and stopping |
  17. | Research skills | Versioned procedures with applicability, uncertainty, and contradiction tracking |
  18. | Evaluation | Runtime recomputation, split-aware metrics, dependence, costs, and statistical diagnostics |
  19. | Evidence | Formula lineage, trial ledgers, content-addressed evidence packs, and verifiable releases |
  20. | Integration | CLI, Python API, MCP server, and reference agent packages |
  21. ## Install
  22. Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/):
  23. ```bash
  24. git clone https://github.com/minihellboy/factorminer.git
  25. cd factorminer
  26. uv sync --group dev --extra llm
  27. ```
  28. NumPy is the default backend. Optional extras include `mcp`, `research`,
  29. `embeddings`, `visualization`, and `gpu`; the CUDA extra targets Linux.
  30. `uv sync --frozen --extra gpu` installs patched PyTorch with CUDA 12.6 and
  31. CuPy for CUDA 12. The base install needs neither Torch nor a GPU.
  32. See [backend scope](docs/architecture.md#numerical-backends) and
  33. [platform setup and checks](CONTRIBUTING.md#optional-model-and-gpu-environments).
  34. ## Quick start
  35. Run a local workflow without credentials:
  36. ```bash
  37. uv run factorminer doctor --json
  38. uv run factorminer quickstart
  39. ```
  40. `quickstart` writes a sample library and HTML report to
  41. `/tmp/factorminer-quickstart`. For a controlled mock campaign:
  42. ```bash
  43. uv run factorminer -o output/mock mine --mock -n 2 -b 8 -t 10
  44. uv run factorminer session inspect output/mock --telemetry
  45. ```
  46. To run the action planner with DeepSeek Flash, set `DEEPSEEK_API_KEY` in `.env`:
  47. ```bash
  48. uv run --env-file .env factorminer \
  49. -c factorminer/configs/research_actions_deepseek.yaml \
  50. -o output/deepseek-research mine --data data/binance_crypto_5m.csv
  51. ```
  52. The bundled data is a workflow sample. Mining uses only the configured training
  53. split and purges forward-target overlap. Local mining resumes in the
  54. same output directory and defaults to no iteration ceiling or model-call/wall-time
  55. quota. A positive `-n` sets a total campaign iteration boundary for experiments.
  56. See [research actions](docs/research-actions.md) and
  57. [research skills](docs/research-skills.md) for configuration and recovery.
  58. ## Data and evaluation
  59. Input panels require:
  60. ```text
  61. datetime, asset_id, open, high, low, close, volume, amount
  62. ```
  63. Validate a panel, then recompute a saved library on it:
  64. ```bash
  65. uv run factorminer validate-data path/to/market_data.csv --strict
  66. uv run factorminer -c path/to/config.yaml evaluate output/run/factor_library.json \
  67. --data path/to/market_data.csv --period both --top-k 10
  68. ```
  69. Configure targets and train/test periods for the supplied data. Saved scores
  70. remain metadata; analysis recomputes formulas through the evaluation kernel.
  71. See [reproducibility](docs/reproducibility.md) for field aliases, metric semantics,
  72. frozen comparisons, and baseline provenance. Command-level `--help` lists the
  73. available mining, analysis, benchmark, and data workflows.
  74. ## Documentation
  75. | Guide | Contents |
  76. | --- | --- |
  77. | [Architecture](docs/architecture.md) | Components, ownership, execution, and persistence |
  78. | [Research actions](docs/research-actions.md) | Experiment selection and campaign recovery |
  79. | [Research skills](docs/research-skills.md) | Compile, transfer, and inspect procedure memory |
  80. | [Reproducibility](docs/reproducibility.md) | Data, metrics, splits, and benchmarks |
  81. | [Evidence protocol](docs/evidence-protocol.md) | Inference, risk residualization, and cost diagnostics |
  82. | [Qlib CN benchmark](docs/qlib-cn-benchmark.md) | A-share panels and PIT fundamentals, Qlib-conformant splits, Alpha158 lift and top-50 book evaluation |
  83. | [Security](docs/security.md) | Input, model, credential, and MCP boundaries |
  84. | [Agent integration](integrations/factor-researcher/README.md) | Plugin, managed-agent, and MCP setup |
  85. Optional workflows: [public evidence releases](docs/public-evidence-release.md),
  86. [partner review](docs/design-partner-pilot.md), and
  87. [hosted pilot operations](docs/hosted-pilot.md).
  88. ## Repository
  89. | Path | Purpose |
  90. | --- | --- |
  91. | `factorminer/` | Engine, CLI, configuration, and tests |
  92. | `docs/` | Technical contracts and workflow guides |
  93. | `data/` | Onboarding sample and provenance manifest |
  94. | `examples/` | Public-data specifications and checksum locks |
  95. | `integrations/` | Reference agent packages |
  96. | `scripts/` | Checks, demos, benchmark entry point, and type baseline |
  97. `output/` contains ignored runtime state. Keep each campaign in its own
  98. directory; archive completed campaigns with their manifests and checkpoints.
  99. ## License and reference
  100. FactorMiner is [MIT-licensed](LICENSE). Its original research foundation is
  101. [*FactorMiner: A Self-Evolving Agent with Skills and Experience Memory for
  102. Financial Alpha Discovery*](https://arxiv.org/abs/2602.14670). The project adds
  103. experiment selection, transferable procedures, and evidence/recovery contracts.
  104. Paper-specific profiles and baseline coverage are documented in
  105. [reproducibility](docs/reproducibility.md#paper-compatibility).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.