worldquant-harness

A harness-based framework for WorldQuant-style alpha research agents.

Agent generates candidates -> harness records, gates, evaluates, remembers, and evolves -> human explicitly selects what can reach real submission.

中文说明 · Quick Start · Visual Guide · Public Demo · Alpha-GPT Harness · Alpha Search Memory · Harness Contract · Agent Roles · Architecture · API · MCP · WQ Workflow · Safety

worldquant-harness is not a one-shot alpha generator. It is an explicit-submit, memory-driven Alpha-GPT-style research harness for WorldQuant-oriented alpha workflows.

The agent can propose hypotheses, candidate specs, batches, and reviews. The harness owns the lifecycle: candidate identity, sandbox execution, no-submit gates, review queues, rejection reasons, historical memory, profile evolution, and the explicit boundary before any real WQ BRAIN action.

中文摘要：本项目不是一次性的 alpha 生成器，而是一个带显式提交边界、可复盘记忆、可审阅工件的 WorldQuant 风格研究 harness。Agent 可以提出假设和候选，但真实提交必须由人工明确选择。

This project is not affiliated with or endorsed by WorldQuant or WorldQuant BRAIN. Review Disclaimer, Security, and Responsible Use before connecting credentials or publishing artifacts.

Most AI quant workflows stop at idea -> expression -> backtest. That leaves the hard parts outside the system: traceability, rejection memory, duplicate control, platform boundary control, and reproducible review.

worldquant-harness treats factor mining as a controlled research loop:

The 2026-07 update adds a semantic Alpha-GPT layer above the existing harness: hypothesis records, constrained candidate specs, review decisions, reflection memory, and explicit submit evidence are now first-class artifacts. Community triage and local WQ run history are converted into reusable skill memory instead of staying in chat context.

中文架构说明：新的设计把系统拆成三层：底层 harness contract 管生命周期和 no-submit 边界；Alpha-GPT 语义层管假设、候选规格、审阅和反思；memory 层把社区经验和本地运行轨迹转成可复用的 skills、repair queue 和 submit/check queue。

The default public path does not submit anything. Real WQ BRAIN actions require explicit credentials and explicit submission commands.

The public demo is the reproducible contract. It uses synthetic fixtures and guarded adapters, so it does not require WQ BRAIN, DeepSeek, Wind, or private market data.

git clone https://github.com/gyx09212214-prog/worldquant-harness.git
cd worldquant-harness
pip install -e ".[dev]"
python scripts/run_public_harness_demo.py --output-root reports/public_harness_demo
python scripts/validate_public_harness_artifacts.py reports/public_harness_demo
python scripts/run_public_harness_eval.py --output-root reports/public_harness_eval

The demo writes a complete no-submit research bundle:

The smallest no-submit Alpha-GPT loop does not need WQ BRAIN credentials:

python scripts/wq_alpha_gpt_workflow.py demo --topic "analyst revision momentum"

It writes hypothesis, placeholder template, candidate spec, local validation, review queue, reflection memory, profile patch, and submit-evidence artifacts under reports/examples/alpha_gpt_demo/.

This branch adds the first full Alpha-GPT-style memory workflow. The important change is architectural: research state now moves through explicit semantic records instead of remaining as loose prompt text.

本次更新的重点是把研究过程结构化：从研究假设、候选生成、审阅决策、失败记忆、profile patch 到显式提交证据，每一步都有可审计 artifact。

Key reusable skills / 关键 skills:

Update commits on this branch:

For details, see Alpha-GPT Harness, Alpha Search Memory, and WQ Workflow.

The visual pack is generated from public-safe artifacts. It is meant to explain the harness rather than disclose private research.

The public demo proves the harness contract. The examples below are selected active validation records for strategy display. They are included to show that harness-controlled research can reach submit-quality candidates. Exact alpha expressions and platform code panels are intentionally omitted.

_{Historical validation metrics. Alpha expressions are not published.}

Past factor performance does not guarantee future returns. These validation records are not required to run the open-source demo and do not constitute investment advice.

The agent can explore, but it works inside a contract. The harness owns state and creates reviewable artifacts.

The executable contract is implemented through HarnessRun, HarnessStep, HarnessEvent, ArtifactRef, DecisionGate, MemoryDelta, ProfilePatch, and the Alpha-GPT semantic records for hypothesis, candidate spec, review decision, reflection, and submit evidence. See Agent Harness Contract, Alpha-GPT Harness, and Agent Roles.

Start the HTTP server:

python -m worldquant_harness --transport http

Use MCP from Claude Code or Claude Desktop:

{
  "mcpServers": {
    "worldquant-harness": {
      "command": "python",
      "args": ["-m", "worldquant_harness"]
    }
  }
}

For the full local setup, Windows notes, optional PostgreSQL, optional DeepSeek configuration, and API examples, use Quick Start.

worldquant-harness/
├── worldquant_harness/          # Backend, parser, harness contracts, MCP, API
├── frontend/                    # React monitoring dashboard
├── scripts/                     # Public demo, visual pack, review, WQ workflows
├── tests/                       # Parser, backtest, workflow, API, harness tests
├── example_factor/              # Sanitized historical validation screenshots
└── docs/                        # Architecture, API, MCP, workflow, safety docs

• Use your own credentials for external services and follow their terms, policies, rate limits, and data restrictions.
• Keep .env, .secrets/, local databases, raw platform exports, submit/check ledgers, and full research reports private.
• Do not publish alpha expressions, private platform exports, or unsanitized screenshots without review.
• Do not present generated factors, screenshots, or backtests as guaranteed returns.
• Review Open Source Audit and Release Checklist before publishing a fork or release.

MIT. Copyright and attribution details are recorded in NOTICE.

This public release is maintained as worldquant-harness. Derivative works should retain the copyright notice and comply with the MIT License terms.

See NOTICE, DISCLAIMER, SECURITY, and CODE_OF_CONDUCT for details.