x2strategy

X2Strategy

Any Research Input → Strategy Spec → Executable Code → Backtest → Diagnosis

Getting Started · How It Works · Examples · Docs · 简体中文

---

Turn quantitative finance research — papers, drafts, reports, or strategy ideas — into validated, executable trading strategies. Automatically.

Highlights

• 🔬 Multi-Format Input — PDF papers, Markdown drafts, DOCX reports, plain text. Auto-detected.
• 🧠 5-Layer LLM Extraction — Multi-strategy detection → indicators → signal logic → execution plan → risk controls.
• 🧾 Grounded Extraction Quality — Optional instruction/customization/clarification context, retrieved repair-time operator-pitfall checks, canonical portfolio_weights, and structured needs_human_review flags.
• ✅ Verified Code Generation — AST validation + Backtrader structural checks + indicator registry, not just "generate and hope".
• 📊 Automated Backtesting — Execute, extract metrics, and diagnose against paper-reported performance.
• 🤖 Agent-Native — Works as an Agent Skill (/x2strategy) in VS Code Copilot, Claude Code, or any compatible agent.
• 💰 ~$0.1 per paper — DeepSeek-powered. Any LiteLLM-supported provider works.

How It Works

                        ┌──────────────────────────────────────────────────────────────┐
                        │                    X2Strategy                              │
                        │                                                              │
  PDF / MD / DOCX / TXT │   ┌─────────┐   ┌───────────┐   ┌──────────┐   ┌─────────┐ │
  ─────────────────────►│   │  Parse   ├──►│  Extract   ├──►│ Generate ├──►│Backtest │ │
                        │   │ (parser) │   │ (L0 → L4) │   │  (code)  │   │+ Diagnose││
                        │   └─────────┘   └───────────┘   └──────────┘   └─────────┘ │
                        │        ▼              ▼               ▼             ▼        │
                        │   PaperContent   StrategySpec   Backtrader.py   Report.md   │
                        └──────────────────────────────────────────────────────────────┘

Stage	Input	Output	What Happens
Parse	Any document	PaperContent	Format-aware extraction (PyMuPDF / direct read / python-docx)
Extract	PaperContent	StrategySpec[]	5-layer LLM with optional instruction grounding: detect strategies → extract indicators, logic, execution, risk
Generate	StrategySpec	strategy.py	Data module → signal module → backtest module → integration
Validate	strategy.py	Pass / Fail	AST syntax + Backtrader structure + indicator existence checks
Backtest	strategy.py	Metrics	Subprocess execution with timeout, metric extraction
Diagnose	Metrics	report.md	Compare against paper-reported results, flag deviations

Getting Started

As an Agent Skill

Agent Skills is an open standard. Clone into the agent's skill directory — it auto-discovers SKILL.md and registers the /x2strategy slash command.

Install to OpenClaw / OpenClaw Users

For OpenClaw users, install directly from ClawHub:

openclaw skills install patrick-lew/x2strategy

Or use the ClawHub CLI:

npx clawhub@latest install x2strategy

For remote or guided setup, paste this prompt into OpenClaw:

Install the skill "X2strategy" (patrick-lew/x2strategy) from ClawHub.
Skill page: https://clawhub.ai/patrick-lew/x2strategy
Keep the work scoped to this skill only.
After install, inspect the skill metadata and help me finish setup.
Use only the metadata you can verify from ClawHub; do not invent missing requirements.
Ask before making any broader environment changes.

Install to Claude Code / Codex / Copilot

git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.copilot/skills/x2strategy

git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.claude/skills/x2strategy

git clone https://github.com/ALAGENT-HKU/x2strategy.git .github/skills/x2strategy

Then install dependencies. After successful skill installation, the agent may auto-install them during initialization, but manual setup is the most predictable path:

cd ~/.copilot/skills/x2strategy   # or wherever you cloned
# if you haven't installed uv, run `pip install uv`
uv sync --all-extras

# minimum skill runtime
uv sync --extra agent --extra codegen

# add DOCX parsing support
uv sync --extra agent --extra codegen --extra docx

# pip alternative
python -m venv .venv && source .venv/bin/activate
pip install -e ".[codegen,agent,docx,dev]"

[!IMPORTANT] The directory name must be x2strategy (matching the name field in SKILL.md). Once installed, type /x2strategy in chat or the agent auto-activates when relevant.

Skill Quick Start

# 1. Configure the skill workspace
cp .env.example .env          # add your API key (DEEPSEEK_API_KEY recommended)

# 2. Start the skill in your agent
# /x2strategy

Then ask for work in natural language, for example:

"Analyze this paper and implement the main strategy." + attach a PDF + optional data files + optional clarification/user-customization prompts such as "When the paper underspecifies a formula, you can either explicitly ask me or refer to the sample_instruction.md file."

The skill handles parsing, extraction, code generation, validation, backtesting, and diagnosis. Before extraction, it should ask whether you want to add custom instructions, implementation constraints, known pitfalls, or reference files. After extraction and strategy/plan selection, it must read references/extraction_quality.md before any repair, code generation, or deterministic local implementation. It should also use the same interactive flow when you pick search results, add repair-time pitfall notes or clarifications, approve inferred defaults, or resolve any needs_human_review items surfaced by compare/repair. After code generation and diagnosis, it should present an interactive next-action menu instead of assuming the workflow is finished.

Generated files should be written under PAPER2SPEC_LIBRARY_PATH/<slug>/ by default, for example content.json, spec.json, the generated implementation file, and results/metrics.json. If a referenced Copilot/VS Code log path is empty or incomplete, regenerate the artifacts from the original paper, instructions, and data instead of relying on the log summary.

Spec2Code outputs should include Sharpe ratio, maximum drawdown, total return, and return value/final portfolio value whenever those metrics are meaningful for the confirmed implementation target.

Here, “custom instructions” means extra extraction requirements you want the skill to follow, not shell commands or implementation details.

• Use them to say which rules or assumptions must be preserved.
• Use them to point out mistakes or pitfalls the skill should avoid.
• Use them to add background context that you have already confirmed.

Examples: "Only implement the main strategy in the paper, not the appendix variants." "If the weighting rule is ambiguous, prefer equal weight." "Treat the rebalance frequency as monthly, not weekly."

If extraction, compare, or repair leaves needs_human_review questions, it should ask them through an interactive dialog before generating code. In VS Code Copilot, that means vscode_askQuestions when available rather than only writing the questions in prose. If validation or diagnosis still leaves unresolved decisions, it should ask again before silently retrying or stopping.

Supported Input Formats

Format	Extensions	Parser	Notes
PDF	.pdf	PyMuPDF → Mode A (direct) or Mode B (FAISS)	Full support, covering 95%+ of papers
Markdown	.md .markdown	Direct text read	Ideal for strategy drafts and notes
Word	.docx	python-docx (uv sync --extra docx)	Internal research reports
Plain text	.txt	Direct read	Raw strategy descriptions

Format is auto-detected from file extension. No configuration needed.

Examples

The primary shipped example in examples/ is the UPSA paper2code case, generated by Copilot GPT-5.4:

Paper	Strategies Detected	Artifacts
Universal Portfolio Shrinkage Approximation (Kelly, Malamud, Pourmohammadi & Trojani 2025)	1 — UPSA ridge-ensemble portfolio	content + spec + paper2code contract

The UPSA example lives in examples/upsa/. Reproducible inputs are stored in examples/upsa/input/, and the generated implementation is examples/upsa/universal_portfolio_shrinkage_approximation.py.

examples/upsa/
├── README.md
├── upsa_content.json
├── upsa_content.md
├── upsa_spec.json
├── upsa_spec.md
├── upsa_operator_pitfall_context.md
├── upsa_review_and_diagnosis.md
├── upsa_metadata.json
├── universal_portfolio_shrinkage_approximation.py
└── input/
    ├── P10_Kelly_Malamud_Pourmohammadi_Trojani_2025_NBER.pdf
    ├── sample_instruction.md
    ├── jkp_factors_wide.csv
    ├── jkp_factors_long.csv
    └── upsa_weights.csv

[!IMPORTANT] Not every strategy extracted by this skill is suitable for direct broker-connected (live/paper) trading. Many research strategies consume factor returns, synthetic portfolios, ranking panels, or other non-tradable inputs; some are portfolio-construction or SDF/asset-pricing procedures rather than order-generating live strategies. The open-source skill focuses on grounded extraction, code generation, validation, and research backtests. ALAGENT's website can generate broker-connected strategies when the selected strategy and data contract are suitable for live/paper trading.

Project Structure