x2strategy
Extract structured strategy specifications from quantitative finance research papers — Agent Skill for GitHub Copilot & Claude Code
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/alagent-hku--x2strategy)HTML
<a href="/listings/alagent-hku--x2strategy"><img src="/api/listings/alagent-hku--x2strategy/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.
As an Agent Skill
[Agent Skills](https://agentskills.io/) 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
<table> <tr><td><b>GitHub Copilot</b></td><td>
git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.copilot/skills/x2strategy
</td></tr> <tr><td><b>Claude Code</b></td><td>
git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.claude/skills/x2strategy
</td></tr> <tr><td><b>Project-scoped</b></td><td>
git clone https://github.com/ALAGENT-HKU/x2strategy.git .github/skills/x2strategy
</td></tr> </table>
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
<details> <summary>Manual dependency variants</summary>
# 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]"
</details>
> [!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](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.
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.
SKILL.md · Manifest · 325 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: x2strategy
- description: >
- ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,
- DOCX report, text notes, or keyword search) → structured strategy
- specification → executable Backtrader code → backtest → diagnosis report.
- Two core capabilities: (1) paper2spec extracts multi-strategy specs from
- any document via 5-layer LLM extraction, and (2) spec2code generates
- validated Backtrader code, runs backtests, and compares against paper
- metrics. Use this skill whenever the user wants to analyze a quant paper,
- extract trading strategies, generate strategy code, run a backtest, search
- for papers, or go end-to-end from any input to executable results. Also
- triggers on: "look at this paper", "what strategies does this use",
- "implement this strategy", "search for momentum papers", "turn this into
- code", or any request about quantitative finance research → implementation.
- Even if the user doesn't mention "strategy" explicitly — if they provide a
- finance paper or research document, use this skill.
- argument-hint: "[paper.pdf | strategy.md | report.docx | search query]"
- metadata:
- version: 0.6.1
- author: ALAGENT AI (alagent-ai)
- tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]
- ---
- # X2Strategy
- Any finance-related input → Strategy spec → Executable code → Backtest → Diagnosis.
- ## Capabilities
- | Capability | What it does | Deep dive |
- |-----------|-------------|-----------|
- | **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |
- | **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |
- Input format auto-detected from extension:
- | Format | Extension | Notes |
- |--------|-----------|-------|
- | PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |
- | Markdown (drafts) | `.md`, `.markdown` | Direct text read |
- | DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |
- | Plain text | `.txt` | Direct read |
- ---
- ## Interaction Principles
- **You are the executor. The user is the requester.**
- - Run tools silently, present results and insights in natural language.
- - Never show CLI commands (`uv run python scripts/...`) unless user asks.
- - Offer next actions conversationally: "Would you like me to implement the second strategy as well?"
- When reporting results, focus on **what you found**, not how:
- ```
- ❌ Bad: "I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies."
- ✅ Good: "This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?"
- ```
- **Use interactive tools aggressively.** When your platform provides
- interactive question tools — `vscode_askQuestions` (VS Code Copilot),
- `AskUserQuestion` (Claude Code), or equivalent — use them for ALL
- user-facing choices. Interactive tools present clickable options,
- which is faster and less error-prone than asking the user to type.
- Apply interactive tools to:
- - First-Run Setup choices (workspace path, API provider, key input)
- - Input confirmation (proceed / add clarification / adjust settings)
- - Review checkpoints and implementation approval
- - `needs_human_review` resolution after extraction or repair
- - Search result selection (pick papers from a numbered list)
- - Any scenario where the user picks from options
- If no interactive tool is available, fall back to numbered text menus.
- ### Progress Marker Protocol
- Run tools silently, but make long pipelines **traceable**. While working through
- the eight-step workflow, prefix status lines with one of three structured
- markers so the user (and any outer parser) can follow phase progress without
- reading raw command output. The markers carry the discipline; the surrounding
- prose stays natural-language.
- | Marker | When to emit | Format |
- |--------|-------------|--------|
- | `[PROGRESS]` | Entering or finishing a workflow step | `[PROGRESS] <step> — <one-line status>` |
- | `[ARTIFACT]` | A concrete file was written | `[ARTIFACT] <workspace-relative-path> — <what it is>` |
- | `[ERROR]` | A step failed or a check did not pass | `[ERROR] <step> — <what failed> — <next action>` |
- Rules:
- - One marker per line, at the start of the line, then plain language.
- - Every `[ARTIFACT]` must name a concrete workspace-relative path that was
- actually written (this satisfies the Output Paths contract below).
- - `[ERROR]` must always be followed by what you will do next (retry once,
- stop and report, ask the user) — never a bare failure.
- - Markers supplement natural-language reporting; they do not replace it. Still
- explain *what you found*, not *how you ran it*. Never show the CLI command.
- Example:
- ```
- [PROGRESS] paper2spec/extract — extracting strategy specs from content.json
- [ARTIFACT] library/upsa/spec.json — 1 strategy, 4 indicators, 3 logic steps
- [PROGRESS] HITL review — 1 open needs_human_review item, asking for resolution
- ```
- ### Iteration & Retry Discipline
- Generation and repair must be bounded. Translate the backend's hard turn gate
- (`--max-turns`) into agent discipline:
- - **Generate once, then at most one smoke-test repair round.** Write the code,
- validate, run. If it fails, apply one targeted fix round (see the triage flow
- in [references/spec2code.md](references/spec2code.md)) and re-run.
- - **If it still fails after that one repair round, stop and report.** Emit an
- `[ERROR]` line, summarize what failed and the most likely root cause, and ask
- the user how to proceed. Do not keep patching incrementally.
- - **A single runtime-error category gets at most 3 fix attempts.** If the same
- error class persists, the strategy logic likely needs a fundamentally
- different approach — say so rather than tweaking further.
- - Never silently loop. Each retry must be visible via a `[PROGRESS]` or
- `[ERROR]` marker so the user can see the gate working.
- ### First Response Contract
- For any paper2code, research-to-code, or “use this skill” request, the first response must not promise immediate implementation. First identify the visible inputs, then use an interactive dialog to confirm setup status, input files, extra instructions/clarifications, and intended workflow scope. Only proceed after that confirmation.
- ---
- ## First-Run Setup
- On first use, walk through three steps. If a step is already configured, report the detected value and ask the user to confirm or change it. Always confirm task scope before extraction or implementation. Persist all choices to `.env` (gitignored) for session stability.
- ### Step 1 — Workspace Location
- Present choice via interactive tool:
- - `./library/` (default, recommended)
- - Custom path
- Write `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.
- Scan the directory for existing `metadata.json` to detect prior analyses.
- ### Step 2 — LLM API Key
- Check env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`,
- or `ANTHROPIC_API_KEY`.
- If none found, present via interactive tool:
- ```
- An LLM API key is required for strategy extraction and code generation. Recommended options:
- 1. DeepSeek (best cost-performance, about ¥0.7 per paper) → https://platform.deepseek.com
- 2. OpenRouter (one key for access to multiple models) → https://openrouter.ai/keys
- Please provide your API key and tell me which provider it belongs to.
- ```
- Once received, write key + matching model to `.env`, then verify:
- `uv run python -c "from paper2spec.llm import chat; print(chat('Say OK'))"`.
- See [references/skill-internals.md](references/skill-internals.md) for
- `.env` format examples per provider.
- ### Step 3 — Python Environment
- ```bash
- cd <skill-path>
- uv sync --all-extras # Recommended: installs everything
- ```
- If `uv` unavailable: `pip install -e ".[codegen,agent,dev]"`.
- Always use `uv run` to execute scripts (auto-activates correct venv).
- See [references/skill-internals.md](references/skill-internals.md) for
- selective install options and non-uv alternatives.
- ### Completion
- Once configured, confirm naturally with examples:
- ```
- ✅ Setup complete. You can now ask me for tasks directly, for example:
- • "Analyze this paper" + attach a PDF file
- • "Search for papers about momentum trading"
- • "Implement this strategy based on this paper" + provide the file path
- • "I wrote a strategy draft in Markdown; extract the spec and generate code"
- • "Compare the strategy differences between these two papers"
- Just tell me what you want to do, and I will handle the rest.
- ```
- ---
- ## Single Workflow
- Use one workflow for all tasks. Do not choose between competing routers.
- 1. **Setup** — verify `.env`, library path, API key if needed, Python environment, and user-selected scope.
- 2. **Input confirmation** — identify the paper/spec/data/instruction files or search results; ask whether to add clarification, constraints, selected-plan preferences, known pitfalls, or reference files.
- 3. **paper2spec: PDF/text to content** — parse the selected document into grounded content artifacts.
- 4. **paper2spec: extract** — extract candidate strategy specs/plans from the content plus user instructions.
- 5. **paper2spec: repair/review** — read `references/extraction_quality.md`, retrieve relevant operator pitfalls when high-risk formulas are present, and repair only the selected plan/spec with grounded evidence.
- 6. **HITL review** — after repair, always inspect `needs_human_review`. If any item exists, present it through the interactive dialog and do not continue until answered or explicitly accepted. If none exists, still report that review found no open items and ask for implementation approval.
- 7. **spec2code** — after HITL approval, confirm the implementation target and generate code for that target.
- 8. **Validation/backtest/diagnosis** — validate generated code, run available checks/backtests, compare against expected or reference outputs, summarize mismatches, then ask what to do next.
- No bypass: never silently chain extraction → repair → implementation. User-provided papers, instructions, data files, existing specs, or reference outputs are evidence, not permission to skip review or HITL.
- When previous Copilot, VS Code, or agent logs are mentioned, verify that the referenced path exists and contains the needed files before using them. If the path is missing, empty, or incomplete, regenerate the required artifacts from the original paper/instructions/data instead of relying on the log summary.
- ## Output Paths
- Default generated artifacts go under `PAPER2SPEC_LIBRARY_PATH/<slug>/`, where `<slug>` is the paper or task slug confirmed with the user. If a custom output path is requested, confirm it before writing files.
- Expected artifact paths:
- - `content.json` and `content.md` from paper2spec parsing
- - `spec.json` and `spec.md` from extraction and repair
- - `operator_pitfall_context.md` when pitfall retrieval is used
- - `strategy.py`, `strategy_1.py`, or the user-confirmed implementation filename from spec2code
- - `data/` for any data used by generated strategy code
- - `results/backtest_output.txt`, `results/metrics.json`, and `results/diagnosis_report.md` from validation/backtest/diagnosis
- - `results/portfolio_vs_assets.csv` and `results/portfolio_vs_assets.png` comparing the strategy portfolio value against same-capital buy-and-hold curves for every used equity/ETF/asset in one image; asset curves must use distinguishable colors and symbol labels/legend entries, and SPY and portfolio must be boldface (comparing same-parameter portfolio curves at 0%, 0.01%, and 0.05% commission in one image)
- - `results/key_pred/` with one CSV and one PNG per key observerable factors used by the strategy
- Every status update after file generation should name the concrete workspace-relative path that was written.
- ## Spec2Code Metrics
- For every runnable strategy, spec2code should compute and report at least: Sharpe ratio, maximum drawdown, total return, and return value/final portfolio value. If a strategy is not runnable as a broker-connected strategy, report why and still compute the metrics that are meaningful for the confirmed research/backtest contract.
- Spec2Code-generated code must cache all network data locally, save headless-safe visual diagnostics, plot all used asset prices together, compare the strategy account value against same-capital buy-and-hold curves for all used assets, include a 0% / 0.01% / 0.05% commission equity-curve comparison for trading strategies, and include a combined portfolio-vs-assets chart where all three commission portfolio curves are plotted with all asset buy-and-hold
- curves.
- For US equity strategies, SPY must be included and highlighted as the market baseline in asset and portfolio-vs-assets plots. See [references/spec2code.md](references/spec2code.md) and [references/data_sources.md](references/data_sources.md) for the required data cache and visualization contract.
- ---
- ## Agent Pipeline Flow
- ```
- 1. Setup: confirm environment, library path, keys if needed, and task scope
- 2. Confirm inputs: paper/spec/data/instructions/search result + clarifications
- 3. paper2spec: parse PDF/text/doc to content artifacts
- 4. paper2spec: extract candidate specs/plans
- 5. paper2spec: select target plan/spec and repair with extraction_quality + matched pitfalls
- 6. HITL: inspect needs_human_review and resolve through interactive dialog
- 7. spec2code: confirm output contract, generate code, validate, run checks/backtest
- 8. Diagnose results and ask next action
- ```
- For code generation patterns: [references/spec2code.md](references/spec2code.md)
- For Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)
- ---
- ## Internal Toolchain
- Agent-only. Run silently; present results in natural language.
- ```bash
- # Document → spec
- uv run python scripts/analyze.py <file> -o library/<slug>/
- # Step-by-step paper2spec
- uv run python scripts/parse.py <file> -o content.json
- uv run python scripts/extract.py content.json -o spec.json
- # Matched operator-pitfall context for repair/review
- uv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md
- # Validate generated code
- uv run python scripts/validate_strategy.py library/<slug>/strategy_1.py
- # Run backtest
- uv run python library/<slug>/strategy_1.py
- # Search papers
- uv run python scripts/search.py "<query>" -n 5
- ```
- For full flags, output formats, and library management:
- [references/skill-internals.md](references/skill-internals.md)
- ---
- ## Configuration
- | Variable | Default | Purpose |
- |----------|---------|---------|
- | `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |
- | `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |
- | `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |
- | `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |
- | `OPENAI_API_KEY` | — | OpenAI direct |
- | `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |
- | `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |
- Any [litellm-supported model](https://docs.litellm.ai/docs/providers) works.
- The `--model` flag on any script overrides `PAPER2SPEC_MODEL`.
- Full config + .env examples: [references/skill-internals.md](references/skill-internals.md)
- ---
- ## References
- Read on demand for implementation details:
- - [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas
- - [references/extraction_quality.md](references/extraction_quality.md) — Mandatory review/repair and `needs_human_review` rules
- - [paper2spec/resources/operator_pitfall_index.md](paper2spec/resources/operator_pitfall_index.md) — Retrieval corpus for high-risk formula pitfalls
- - [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns
- - [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure
- - [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing
- - [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators
- - [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API
- ## Limitations
- - **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.
- - **Tables/formulas**: not yet extracted from PDFs.
- - **Multi-strategy**: conservative — may merge borderline-distinct strategies.
- - **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).
- - **SSRN search**: best-effort HTML scraping, may break on layout changes.
README.md · README · 378 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <img src="assets/alagent_logo.png" alt="ALAGENT Logo" width="120">
- # X2Strategy
- **Any Research Input → Strategy Spec → Executable Code → Backtest → Diagnosis**
- [](https://python.org)
- [](LICENSE)
- [](https://agentskills.io/)
- []()
- [](https://docs.litellm.ai/docs/providers)
- [Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Examples](#-examples) · [Docs](#-documentation) · [简体中文](README_CN.md)
- ---
- *Turn quantitative finance research — papers, drafts, reports, or strategy ideas — into validated, executable trading strategies. Automatically.*
- </div>
- ## 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](https://agentskills.io/) (`/x2strategy`) in VS Code Copilot, Claude Code, or any compatible agent.
- - **💰 ~$0.1 per paper** — DeepSeek-powered. Any [LiteLLM-supported provider](https://docs.litellm.ai/docs/providers) 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](https://agentskills.io/) 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:
- ```bash
- openclaw skills install patrick-lew/x2strategy
- ```
- Or use the ClawHub CLI:
- ```bash
- npx clawhub@latest install x2strategy
- ```
- For remote or guided setup, paste this prompt into OpenClaw:
- ```text
- 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
- <table>
- <tr><td><b>GitHub Copilot</b></td><td>
- ```bash
- git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.copilot/skills/x2strategy
- ```
- </td></tr>
- <tr><td><b>Claude Code</b></td><td>
- ```bash
- git clone https://github.com/ALAGENT-HKU/x2strategy.git ~/.claude/skills/x2strategy
- ```
- </td></tr>
- <tr><td><b>Project-scoped</b></td><td>
- ```bash
- git clone https://github.com/ALAGENT-HKU/x2strategy.git .github/skills/x2strategy
- ```
- </td></tr>
- </table>
- Then install dependencies. After successful skill installation, the agent may auto-install them during initialization, but manual setup is the most predictable path:
- ```bash
- cd ~/.copilot/skills/x2strategy # or wherever you cloned
- # if you haven't installed uv, run `pip install uv`
- uv sync --all-extras
- ```
- <details>
- <summary>Manual dependency variants</summary>
- ```bash
- # 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]"
- ```
- </details>
- > [!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
- ```bash
- # 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](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/`](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`.
- <details>
- <summary>Example output structure</summary>
- ```
- 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
- ```
- </details>
- > [!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](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](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
- | Variable | Default | Description |
- |:---------|:--------|:------------|
- | `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root directory |
- | `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | LLM model ([LiteLLM format](https://docs.litellm.ai/docs/providers)) |
- | `SPEC2CODE_BACKTEST_TIMEOUT` | `300` | Backtest timeout in seconds |
- | `DEEPSEEK_API_KEY` | — | DeepSeek (recommended: best cost/quality) |
- | `OPENROUTER_API_KEY` | — | OpenRouter (one key, all models) |
- | `OPENAI_API_KEY` | — | OpenAI direct |
- | `ANTHROPIC_API_KEY` | — | Anthropic direct |
- All scripts accept `--model` to override `PAPER2SPEC_MODEL`.
- ## Documentation
- | Resource | Description |
- |:---------|:------------|
- | [SKILL.md](SKILL.md) | Agent skill instructions — setup, single workflow, HITL review, output paths |
- | [references/paper2spec.md](references/paper2spec.md) | Paper → Spec extraction deep-dive |
- | [references/extraction_quality.md](references/extraction_quality.md) | Grounded extraction and repair quality rules |
- | [paper2spec/resources/operator_pitfall_index.md](paper2spec/resources/operator_pitfall_index.md) | Editable semantic retrieval corpus for high-risk formula pitfalls |
- | [references/spec2code.md](references/spec2code.md) | Spec → Code generation deep-dive |
- | [references/backtrader_patterns.md](references/backtrader_patterns.md) | Source-verified Backtrader patterns |
- | [references/indicator_cookbook.md](references/indicator_cookbook.md) | Official indicator parameter reference |
- | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline architecture |
- ## Testing
- ```bash
- 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](docs/ARCHITECTURE.md) for codebase orientation.
- ```bash
- 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](LICENSE) · Built by **[ALAGENT AI 优彦智能](http://home.alagent.cloud)** — Verifiable & Trustworthy Financial AI
- ---
- <div align="center">
- ## 💬 Join the Community
- <a href="https://home.alagent.cloud">🌐 Website</a> · <a href="https://github.com/ALAGENT-HKU">GitHub</a> · <a href="mailto:contact@alagent.cloud">📧 contact@alagent.cloud</a>
- <br>
- <img src="assets/wechat_QR.jpg" alt="WeChat Group QR" width="260">
- **Scan to join the ALAGENT Open-Source WeChat Group**
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.