alagent-hku/x2strategy

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   │
                        └──────────────────────────────────────────────────────────────┘

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

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

[!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// 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 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:

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.

[!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

x2strategy/
├── paper2spec/                 # Phase 1: Document → Structured Spec
│   ├── __init__.py
│   ├── config.py               #   Environment and library path configuration
│   ├── parser.py               #   Multi-format parser (PDF / MD / DOCX / TXT)
│   ├── pdf_utils.py            #   PDF extraction helpers
│   ├── extractor.py            #   PaperContent → ExtractionResult (L0-L4)
│   ├── models.py               #   Data models (PaperContent, StrategySpec, etc.)
│   ├── prompts.py              #   5-layer extraction prompt templates
│   ├── operator_pitfall.py      #   Semantic retrieval for repair pitfall checks
│   ├── resources/
│   │   └── operator_pitfall_index.md # Editable pitfall corpus for retrieval
│   ├── llm.py                  #   LiteLLM unified interface
│   ├── render.py               #   JSON → Markdown rendering
│   └── search.py               #   arXiv + SSRN paper search
│
├── spec2code/                  # Phase 2 support: agent-driven codegen validation
│   ├── __init__.py
│   ├── validator.py            #   AST + structural + indicator validation
│   ├── config.py               #   Codegen and backtest configuration
│   └── models.py               #   CodeModules, ValidationResult, BacktestMetrics
│
├── references/                 # Verified domain knowledge (not LLM hallucinations)
│   ├── backtrader_patterns.md  #   Source-verified Backtrader patterns
│   ├── indicator_cookbook.md    #   Official indicator params (from bt source code)
│   ├── data_sources.md         #   yfinance + akshare API docs
│   ├── extraction_quality.md    #   Grounded extraction / repair quality rules
│   ├── paper2spec.md           #   Paper2Spec deep-dive guide
│   ├── spec2code.md            #   Spec2Code deep-dive guide
│   └── skill-internals.md      #   Skill setup and environment details
│
├── scripts/                    # CLI entry points
│   ├── analyze.py              #   Full paper2spec pipeline
│   ├── extract.py              #   Extract specs from parsed content
│   ├── parse.py                #   Parse documents into PaperContent
│   ├── search.py               #   Search for papers
│   ├── operator_pitfalls.py     #   Retrieve matched operator-pitfall context
│   ├── generate_schemas.py     #   Generate JSON schemas
│   ├── run_full_tests.sh       #   Test runner helper
│   └── validate_strategy.py    #   Standalone validation
│
├── docs/                       # Architecture and design docs
│   └── ARCHITECTURE.md
│
├── assets/                     # README / skill images
├── schemas/                    # JSON Schema definitions
├── examples/                   # Pre-generated reference outputs
├── tests/                      # 180+ unit & integration tests
├── .env.example                # Environment variable template
├── requirements.txt            # pip fallback dependencies
├── README_CN.md                # Chinese README
├── SKILL.md                    # Agent Skill entry point
├── pyproject.toml              # Project config & dependencies
└── uv.lock                     # Locked uv dependency graph

Key Design Decisions

Why Reference Docs, Not Prompts?

LLMs frequently hallucinate Backtrader API details:

• SMA default period is 30, not 20
• RSI uses SmoothedMovingAverage, not EMA
• BollingerBands lines are .top/.mid/.bot, not .upper/.lower

Our references/ directory contains source-code-verified knowledge. The agent reads these docs on demand instead of relying on improvised API recall.

Why Structured Specs as Intermediate?

Going directly from paper → code loses auditability. The StrategySpec intermediate:

• Auditable — humans can review the spec before code generation
• Reusable — the same spec can target different backtest engines
• Testable — extraction and code generation are independently verifiable

Grounded Extraction and Repair

paper2spec supports optional instruction/clarification context during extraction. Use this when a paper has appendix-only formulas, missing constants, ambiguous allocation logic, or the user wants to customize extraction requirements.

• The skill should ask for instruction files, clarifications, or reference notes before extraction when the input is ambiguous.
• references/extraction_quality.md is the canonical audit guide for manual review.
• For repair-style RAG, use only the pitfalls retrieved from paper2spec/resources/operator_pitfall_index.md, not the full index.
• Ground truth still comes from the paper, selected plan, user clarifications, and approved customization notes. The pitfall index is only an audit aid.

Configuration

All scripts accept --model to override PAPER2SPEC_MODEL.

Documentation

Testing

pytest tests/ -v              # 180+ deterministic tests
pytest tests/ -v --run-real   # + real API tests (requires DEEPSEEK_API_KEY)

Contributing

We welcome contributions! Please see the Architecture Doc for codebase orientation.

git clone https://github.com/ALAGENT-HKU/x2strategy.git && cd x2strategy
uv sync --all-extras
cp .env.example .env  # add API key
pytest tests/ -v      # verify everything passes

License

Apache-2.0 · Built by ALAGENT AI 优彦智能 — Verifiable & Trustworthy Financial AI

---