{"repo": "alagent-hku/x2strategy", "files": {"pyproject.toml": {"e9cd907da492cde5cc5c4e70c78c71e78b288d4f": {"t": 1785745317.1394212, "n": 1210, "h": "0cc5d34adeaf6530", "c": "[project]\nname = \"x2strategy\"\nversion = \"0.4.0\"\ndescription = \"End-to-end: quantitative finance research paper → strategy specification → executable Backtrader code → backtest → diagnosis\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"backtrader>=1.9.78.123\",\n \"litellm>=1.40\",\n \"matplotlib>=3.11.0\",\n \"numpy>=2.4.3\",\n \"pandas>=3.0.1\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n \"python-dotenv>=1.0\",\n \"yfinance>=1.2.0\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ncodegen = [\n \"backtrader>=1.9\",\n \"yfinance>=0.2\",\n \"akshare>=1.10\",\n]\ndocx = [\n \"python-docx>=1.0\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\", \"spec2code\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}, "d0f28e62c42990b0a2e39ab197bd606f0d09ea89": {"t": 1785750073.0625243, "n": 1090, "h": "1570ceec5f4c85c0", "c": "[project]\nname = \"x2strategy\"\nversion = \"0.4.0\"\ndescription = \"End-to-end: quantitative finance research paper → strategy specification → executable Backtrader code → backtest → diagnosis\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"litellm>=1.40\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n \"python-dotenv>=1.0\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ncodegen = [\n \"backtrader>=1.9\",\n \"yfinance>=0.2\",\n \"akshare>=1.10\",\n]\ndocx = [\n \"python-docx>=1.0\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\", \"spec2code\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}, "c44b7a736f9338f38583e41166d68d674859a9a4": {"t": 1785750074.324076, "n": 1096, "h": "8dacd9dfcbf4ed32", "c": "[project]\nname = \"quant-paper2code\"\nversion = \"0.4.0\"\ndescription = \"End-to-end: quantitative finance research paper → strategy specification → executable Backtrader code → backtest → diagnosis\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"litellm>=1.40\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n \"python-dotenv>=1.0\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ncodegen = [\n \"backtrader>=1.9\",\n \"yfinance>=0.2\",\n \"akshare>=1.10\",\n]\ndocx = [\n \"python-docx>=1.0\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\", \"spec2code\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}, "b3975d6f01c1216b80a47ffc20b21bf1c9c4a0c8": {"t": 1785750075.5828288, "n": 1061, "h": "c2a80758414332df", "c": "[project]\nname = \"quant-paper2code\"\nversion = \"0.4.0\"\ndescription = \"End-to-end: quantitative finance research paper → strategy specification → executable Backtrader code → backtest → diagnosis\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"litellm>=1.40\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n \"python-dotenv>=1.0\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ncodegen = [\n \"backtrader>=1.9\",\n \"yfinance>=0.2\",\n \"akshare>=1.10\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\", \"spec2code\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}, "5edbe37f019827e56840e9191e985fcb4e35bf1d": {"t": 1785750077.713447, "n": 923, "h": "46f23c59eae2bce8", "c": "[project]\nname = \"paper2spec\"\nversion = \"0.3.0\"\ndescription = \"Extract structured strategy specifications from quantitative finance research papers\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"litellm>=1.40\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n \"python-dotenv>=1.0\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}, "4714ff55a4096cf9af4eb2fdba8228d9f555f301": {"t": 1785750078.9403918, "n": 897, "h": "34e5d3e9cd4ee666", "c": "[project]\nname = \"paper2spec\"\nversion = \"0.3.0\"\ndescription = \"Extract structured strategy specifications from quantitative finance research papers\"\nreadme = \"README.md\"\nlicense = {text = \"Apache-2.0\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"litellm>=1.40\",\n \"PyMuPDF>=1.24\",\n \"pymupdf4llm>=0.0.10\",\n]\n\n[project.optional-dependencies]\nagent = [\n \"langchain-community>=0.2\",\n \"langchain-text-splitters>=0.2\",\n \"sentence-transformers>=2.2\",\n \"faiss-cpu>=1.7\",\n]\ndev = [\n \"pytest>=8\",\n \"pytest-asyncio>=0.23\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"paper2spec\"]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\ntestpaths = [\"tests\"]\nmarkers = [\n \"network: requires internet access\",\n \"slow: takes >5s\",\n \"real: real API calls (costs credits, requires DEEPSEEK_API_KEY)\",\n]\n"}}, "SKILL.md": {"e9cd907da492cde5cc5c4e70c78c71e78b288d4f": {"t": 1785747212.0070622, "n": 16779, "h": "481982b04071b925", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.1\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny finance-related input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"Would you like me to implement the second strategy as well?\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Input confirmation (proceed / add clarification / adjust settings)\n- Review checkpoints and implementation approval\n- `needs_human_review` resolution after extraction or repair\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n### Progress Marker Protocol\n\nRun tools silently, but make long pipelines **traceable**. While working through\nthe eight-step workflow, prefix status lines with one of three structured\nmarkers so the user (and any outer parser) can follow phase progress without\nreading raw command output. The markers carry the discipline; the surrounding\nprose stays natural-language.\n\n| Marker | When to emit | Format |\n|--------|-------------|--------|\n| `[PROGRESS]` | Entering or finishing a workflow step | `[PROGRESS] — ` |\n| `[ARTIFACT]` | A concrete file was written | `[ARTIFACT] — ` |\n| `[ERROR]` | A step failed or a check did not pass | `[ERROR] — — ` |\n\nRules:\n- One marker per line, at the start of the line, then plain language.\n- Every `[ARTIFACT]` must name a concrete workspace-relative path that was\n actually written (this satisfies the Output Paths contract below).\n- `[ERROR]` must always be followed by what you will do next (retry once,\n stop and report, ask the user) — never a bare failure.\n- Markers supplement natural-language reporting; they do not replace it. Still\n explain *what you found*, not *how you ran it*. Never show the CLI command.\n\nExample:\n\n```\n[PROGRESS] paper2spec/extract — extracting strategy specs from content.json\n[ARTIFACT] library/upsa/spec.json — 1 strategy, 4 indicators, 3 logic steps\n[PROGRESS] HITL review — 1 open needs_human_review item, asking for resolution\n```\n\n### Iteration & Retry Discipline\n\nGeneration and repair must be bounded. Translate the backend's hard turn gate\n(`--max-turns`) into agent discipline:\n\n- **Generate once, then at most one smoke-test repair round.** Write the code,\n validate, run. If it fails, apply one targeted fix round (see the triage flow\n in [references/spec2code.md](references/spec2code.md)) and re-run.\n- **If it still fails after that one repair round, stop and report.** Emit an\n `[ERROR]` line, summarize what failed and the most likely root cause, and ask\n the user how to proceed. Do not keep patching incrementally.\n- **A single runtime-error category gets at most 3 fix attempts.** If the same\n error class persists, the strategy logic likely needs a fundamentally\n different approach — say so rather than tweaking further.\n- Never silently loop. Each retry must be visible via a `[PROGRESS]` or\n `[ERROR]` marker so the user can see the gate working.\n\n### First Response Contract\n\nFor 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.\n\n---\n\n## First-Run Setup\n\nOn 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.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`,\nor `ANTHROPIC_API_KEY`.\nIf none found, present via interactive tool:\n\n```\nAn LLM API key is required for strategy extraction and code generation. Recommended options:\n 1. DeepSeek (best cost-performance, about ¥0.7 per paper) → https://platform.deepseek.com\n 2. OpenRouter (one key for access to multiple models) → https://openrouter.ai/keys\nPlease provide your API key and tell me which provider it belongs to.\n```\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ Setup complete. You can now ask me for tasks directly, for example:\n\n • \"Analyze this paper\" + attach a PDF file\n • \"Search for papers about momentum trading\"\n • \"Implement this strategy based on this paper\" + provide the file path\n • \"I wrote a strategy draft in Markdown; extract the spec and generate code\"\n • \"Compare the strategy differences between these two papers\"\n\nJust tell me what you want to do, and I will handle the rest.\n```\n\n---\n\n## Single Workflow\n\nUse one workflow for all tasks. Do not choose between competing routers.\n\n1. **Setup** — verify `.env`, library path, API key if needed, Python environment, and user-selected scope.\n2. **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.\n3. **paper2spec: PDF/text to content** — parse the selected document into grounded content artifacts.\n4. **paper2spec: extract** — extract candidate strategy specs/plans from the content plus user instructions.\n5. **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.\n6. **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.\n7. **spec2code** — after HITL approval, confirm the implementation target and generate code for that target.\n8. **Validation/backtest/diagnosis** — validate generated code, run available checks/backtests, compare against expected or reference outputs, summarize mismatches, then ask what to do next.\n\nNo 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.\n\nWhen 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.\n\n## Output Paths\n\nDefault generated artifacts go under `PAPER2SPEC_LIBRARY_PATH//`, where `` is the paper or task slug confirmed with the user. If a custom output path is requested, confirm it before writing files.\n\nExpected artifact paths:\n\n- `content.json` and `content.md` from paper2spec parsing\n- `spec.json` and `spec.md` from extraction and repair\n- `operator_pitfall_context.md` when pitfall retrieval is used\n- `strategy.py`, `strategy_1.py`, or the user-confirmed implementation filename from spec2code\n- `data/` for any data used by generated strategy code\n- `results/backtest_output.txt`, `results/metrics.json`, and `results/diagnosis_report.md` from validation/backtest/diagnosis\n- `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)\n- `results/key_pred/` with one CSV and one PNG per key observerable factors used by the strategy\n\nEvery status update after file generation should name the concrete workspace-relative path that was written.\n\n## Spec2Code Metrics\n\nFor 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.\n\nSpec2Code-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\ncurves. \n\nFor 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.\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Setup: confirm environment, library path, keys if needed, and task scope\n2. Confirm inputs: paper/spec/data/instructions/search result + clarifications\n3. paper2spec: parse PDF/text/doc to content artifacts\n4. paper2spec: extract candidate specs/plans\n5. paper2spec: select target plan/spec and repair with extraction_quality + matched pitfalls\n6. HITL: inspect needs_human_review and resolve through interactive dialog\n7. spec2code: confirm output contract, generate code, validate, run checks/backtest\n8. Diagnose results and ask next action\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\nAgent-only. Run silently; present results in natural language.\n\n```bash\n# Document → spec\nuv run python scripts/analyze.py -o library//\n\n# Step-by-step paper2spec\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n\n# Matched operator-pitfall context for repair/review\nuv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/extraction_quality.md](references/extraction_quality.md) — Mandatory review/repair and `needs_human_review` rules\n- [paper2spec/resources/operator_pitfall_index.md](paper2spec/resources/operator_pitfall_index.md) — Retrieval corpus for high-risk formula pitfalls\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "5be2d0f02c1c51d01396725ef6c98bfe6335433a": {"t": 1785750075.2843416, "n": 14329, "h": "855a8f4a03aa2d29", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.1\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny finance-related input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"Would you like me to implement the second strategy as well?\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Input confirmation (proceed / add clarification / adjust settings)\n- Review checkpoints and implementation approval\n- `needs_human_review` resolution after extraction or repair\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n### First Response Contract\n\nFor 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.\n\n---\n\n## First-Run Setup\n\nOn 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.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`,\nor `ANTHROPIC_API_KEY`.\nIf none found, present via interactive tool:\n\n```\nAn LLM API key is required for strategy extraction and code generation. Recommended options:\n 1. DeepSeek (best cost-performance, about ¥0.7 per paper) → https://platform.deepseek.com\n 2. OpenRouter (one key for access to multiple models) → https://openrouter.ai/keys\nPlease provide your API key and tell me which provider it belongs to.\n```\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ Setup complete. You can now ask me for tasks directly, for example:\n\n • \"Analyze this paper\" + attach a PDF file\n • \"Search for papers about momentum trading\"\n • \"Implement this strategy based on this paper\" + provide the file path\n • \"I wrote a strategy draft in Markdown; extract the spec and generate code\"\n • \"Compare the strategy differences between these two papers\"\n\nJust tell me what you want to do, and I will handle the rest.\n```\n\n---\n\n## Single Workflow\n\nUse one workflow for all tasks. Do not choose between competing routers.\n\n1. **Setup** — verify `.env`, library path, API key if needed, Python environment, and user-selected scope.\n2. **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.\n3. **paper2spec: PDF/text to content** — parse the selected document into grounded content artifacts.\n4. **paper2spec: extract** — extract candidate strategy specs/plans from the content plus user instructions.\n5. **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.\n6. **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.\n7. **spec2code** — after HITL approval, confirm the implementation target and generate code for that target.\n8. **Validation/backtest/diagnosis** — validate generated code, run available checks/backtests, compare against expected or reference outputs, summarize mismatches, then ask what to do next.\n\nNo 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.\n\nWhen 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.\n\n## Output Paths\n\nDefault generated artifacts go under `PAPER2SPEC_LIBRARY_PATH//`, where `` is the paper or task slug confirmed with the user. If a custom output path is requested, confirm it before writing files.\n\nExpected artifact paths:\n\n- `content.json` and `content.md` from paper2spec parsing\n- `spec.json` and `spec.md` from extraction and repair\n- `operator_pitfall_context.md` when pitfall retrieval is used\n- `strategy.py`, `strategy_1.py`, or the user-confirmed implementation filename from spec2code\n- `data/` for any data used by generated strategy code\n- `results/backtest_output.txt`, `results/metrics.json`, and `results/diagnosis_report.md` from validation/backtest/diagnosis\n- `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)\n- `results/key_pred/` with one CSV and one PNG per key observerable factors used by the strategy\n\nEvery status update after file generation should name the concrete workspace-relative path that was written.\n\n## Spec2Code Metrics\n\nFor 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.\n\nSpec2Code-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\ncurves. \n\nFor 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.\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Setup: confirm environment, library path, keys if needed, and task scope\n2. Confirm inputs: paper/spec/data/instructions/search result + clarifications\n3. paper2spec: parse PDF/text/doc to content artifacts\n4. paper2spec: extract candidate specs/plans\n5. paper2spec: select target plan/spec and repair with extraction_quality + matched pitfalls\n6. HITL: inspect needs_human_review and resolve through interactive dialog\n7. spec2code: confirm output contract, generate code, validate, run checks/backtest\n8. Diagnose results and ask next action\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\nAgent-only. Run silently; present results in natural language.\n\n```bash\n# Document → spec\nuv run python scripts/analyze.py -o library//\n\n# Step-by-step paper2spec\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n\n# Matched operator-pitfall context for repair/review\nuv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/extraction_quality.md](references/extraction_quality.md) — Mandatory review/repair and `needs_human_review` rules\n- [paper2spec/resources/operator_pitfall_index.md](paper2spec/resources/operator_pitfall_index.md) — Retrieval corpus for high-risk formula pitfalls\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "273ace853c0e583fccb2697bacad54cbfb369d1a": {"t": 1785750076.3684192, "n": 13002, "h": "ca2b0b4e543988a7", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.1\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny finance-related input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"Would you like me to implement the second strategy as well?\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Input confirmation (proceed / add clarification / adjust settings)\n- Review checkpoints and implementation approval\n- `needs_human_review` resolution after extraction or repair\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n### First Response Contract\n\nFor 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.\n\n---\n\n## First-Run Setup\n\nOn 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.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`,\nor `ANTHROPIC_API_KEY`.\nIf none found, present via interactive tool:\n\n```\nAn LLM API key is required for strategy extraction and code generation. Recommended options:\n 1. DeepSeek (best cost-performance, about ¥0.7 per paper) → https://platform.deepseek.com\n 2. OpenRouter (one key for access to multiple models) → https://openrouter.ai/keys\nPlease provide your API key and tell me which provider it belongs to.\n```\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ Setup complete. You can now ask me for tasks directly, for example:\n\n • \"Analyze this paper\" + attach a PDF file\n • \"Search for papers about momentum trading\"\n • \"Implement this strategy based on this paper\" + provide the file path\n • \"I wrote a strategy draft in Markdown; extract the spec and generate code\"\n • \"Compare the strategy differences between these two papers\"\n\nJust tell me what you want to do, and I will handle the rest.\n```\n\n---\n\n## Single Workflow\n\nUse one workflow for all tasks. Do not choose between competing routers.\n\n1. **Setup** — verify `.env`, library path, API key if needed, Python environment, and user-selected scope.\n2. **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.\n3. **paper2spec: PDF/text to content** — parse the selected document into grounded content artifacts.\n4. **paper2spec: extract** — extract candidate strategy specs/plans from the content plus user instructions.\n5. **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.\n6. **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.\n7. **spec2code** — after HITL approval, confirm the implementation target and generate code for that target.\n8. **Validation/backtest/diagnosis** — validate generated code, run available checks/backtests, compare against expected or reference outputs, summarize mismatches, then ask what to do next.\n\nNo 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.\n\nWhen 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.\n\n## Output Paths\n\nDefault generated artifacts go under `PAPER2SPEC_LIBRARY_PATH//`, where `` is the paper or task slug confirmed with the user. If a custom output path is requested, confirm it before writing files.\n\nExpected artifact paths:\n\n- `content.json` and `content.md` from paper2spec parsing\n- `spec.json` and `spec.md` from extraction and repair\n- `operator_pitfall_context.md` when pitfall retrieval is used\n- `strategy.py`, `strategy_1.py`, or the user-confirmed implementation filename from spec2code\n- `results/backtest_output.txt`, `results/metrics.json`, and `results/diagnosis_report.md` from validation/backtest/diagnosis\n\nEvery status update after file generation should name the concrete workspace-relative path that was written.\n\n## Spec2Code Metrics\n\nFor 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.\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Setup: confirm environment, library path, keys if needed, and task scope\n2. Confirm inputs: paper/spec/data/instructions/search result + clarifications\n3. paper2spec: parse PDF/text/doc to content artifacts\n4. paper2spec: extract candidate specs/plans\n5. paper2spec: select target plan/spec and repair with extraction_quality + matched pitfalls\n6. HITL: inspect needs_human_review and resolve through interactive dialog\n7. spec2code: confirm output contract, generate code, validate, run checks/backtest\n8. Diagnose results and ask next action\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\nAgent-only. Run silently; present results in natural language.\n\n```bash\n# Document → spec\nuv run python scripts/analyze.py -o library//\n\n# Step-by-step paper2spec\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n\n# Matched operator-pitfall context for repair/review\nuv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/extraction_quality.md](references/extraction_quality.md) — Mandatory review/repair and `needs_human_review` rules\n- [paper2spec/resources/operator_pitfall_index.md](paper2spec/resources/operator_pitfall_index.md) — Retrieval corpus for high-risk formula pitfalls\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "481cada53f6bd3b40342dd6c7a9fddf734af8161": {"t": 1785750077.7850575, "n": 12482, "h": "89a9235367e04fcb", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny research input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"Would you like me to implement the second strategy as well?\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Gate 1 confirmation (proceed / adjust settings)\n- Gate 2 action menu (implement / deep dive / compare / adjust / export / re-extract)\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n---\n\n## First-Run Setup\n\nOn first use, walk through three steps. Skip any already-configured step.\nPersist all choices to `.env` (gitignored) for session stability.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`.\nIf none found, present via interactive tool:\n\n```\nAn LLM API key is required for strategy extraction and code generation. Recommended options:\n 1. DeepSeek (best cost-performance, about ¥0.7 per paper) → https://platform.deepseek.com\n 2. OpenRouter (one key for access to multiple models) → https://openrouter.ai/keys\nPlease provide your API key and tell me which provider it belongs to.\n```\n\n> Do NOT check for or suggest `ANTHROPIC_API_KEY`.\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ Setup complete. You can now ask me for tasks directly, for example:\n\n • \"Analyze this paper\" + attach a PDF file\n • \"Search for papers about momentum trading\"\n • \"Implement this strategy based on this paper\" + provide the file path\n • \"I wrote a strategy draft in Markdown; extract the spec and generate code\"\n • \"Compare the strategy differences between these two papers\"\n\nJust tell me what you want to do, and I will handle the rest.\n```\n\n---\n\n## Routing\n\n| User Intent | Route | Action |\n|-------------|-------|--------|\n| \"Analyze this paper/doc\" | paper2spec | Parse + extract specs |\n| \"Search for papers about X\" | paper2spec | Search → **Gate 1** |\n| \"Here's my strategy draft\" (MD/DOCX/TXT) | paper2spec | Auto-detect format, extract |\n| \"Generate code / Implement this\" | spec2code | Spec → code → validate → backtest |\n| \"Run a backtest\" | spec2code | Execute strategy.py |\n| \"End to end from paper\" | both | paper2spec → **Gate 2** → spec2code |\n| \"Compare results with paper\" | spec2code | Read backtest output + spec, compare metrics |\n\n---\n\n## Interaction Gates\n\nTwo mandatory HITL gates. Skip only when user says \"fully automatic\" /\n\"end to end without stopping\".\n\n**Always present gate choices through interactive tools when available.**\n\n### Gate 1 — Input Confirmation\n\n**When:** After receiving/finding input, BEFORE extraction.\n\nThree scenarios — present via interactive tool (or numbered text menu):\n\n**Scenario A — User provided a file:**\n```\n📄 Received: \"Tactical Asset Allocation\" (Faber, 2007)\n Format: PDF, 18 pages\n Abstract: [first 2 sentences]\n\nI'll extract trading strategies. ~30-60s, ~$0.01.\n→ Proceed with extraction?\n→ Or adjust settings first? (parser mode, model, output location)\n```\n\n**Scenario B — Search results returned:**\n```\n🔍 Found 8 papers for \"momentum trading strategy\":\n 1. ⭐ \"Time Series Momentum\" (Moskowitz et al., 2012) — 847 citations\n 2. \"Momentum Crashes\" (Daniel & Moskowitz, 2016) — 523 citations\n ...\nWhich paper to analyze? (pick number, \"1, 3\" for multiple, or refine search)\n```\nDo NOT auto-analyze. Always let user pick.\n\n**Scenario C — Raw text / strategy idea:**\n```\n📝 I see you've described: \"[brief summary]\"\n I'll structure this into a formal spec. → Proceed? → Add more details first?\n```\n\nKeep it light for straightforward inputs — single confirm with default-proceed.\n\n### Gate 2 — Spec Review & Action Menu\n\n**When:** After extraction completes, BEFORE code generation.\n\nShow extraction summary, then present action menu via interactive tool:\n\n```\n✅ Strategy Extraction Complete\n📋 Paper: \"Pairs Trading: Does Volatility Timing Matter?\"\n Detected: 3 independent strategies\n\n [1] Minimum Distance Method\n • 4 indicators (spread, SMA, Z-score, distance)\n • Entry: spread Z-score > 2σ, Exit: mean reversion\n\n [2] Stationarity-Based (ADF Test)\n • 3 indicators, Entry: cointegrated pair + spread deviation\n\n [3] Cointegration (Johansen)\n • 5 indicators, Entry: Johansen test + Z-score threshold\n```\n\nThen 6 actions:\n\n1. 🚀 **Implement** — Generate executable code (pick strategy # or \"all\")\n2. 🔍 **Deep dive** — Explain a strategy's logic in detail\n3. 📊 **Compare** — Side-by-side of detected strategies\n4. ✏️ **Adjust** — Modify spec parameters/constraints\n5. 💾 **Export only** — Save specs, stop here\n6. 🔄 **Re-extract** — Different model or parser mode\n\n**Key behaviors:**\n- \"Implement\" → confirm which strategy index before generating code.\n- \"Deep dive\" → explain, then return to the same menu.\n- After code gen + backtest → present results, offer next decision.\n- Never silently chain extraction → code generation.\n\n### Gate Bypass\n\nIf user says \"end to end\" / \"fully automatic\" / \"don't stop\", collapse\ngates into inline status:\n\n```\n📄 Parsing paper... ✓ (3 strategies detected)\n💻 Generating code for strategy 1... ✓\n📊 Running backtest... ✓\n📈 Results ready — see below.\n```\n\nStill stop on unexpected issues (0 strategies, errors, validation failures).\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Receive input (file / search query / text)\n2. ── Gate 1: Input Confirmation ──\n3. [paper2spec] Parse document, extract strategy specs\n4. ── Gate 2: Spec Review & Action Menu ──\n5. User selects strategy + action\n6. [spec2code] For each selected strategy:\n a. Read spec.json + reference docs\n b. Generate self-contained Backtrader strategy.py\n c. Validate (AST + structural checks)\n d. Run backtest, compare metrics vs paper\n7. Present results + diagnosis\n8. Offer next actions\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\n> Agent-only. Run silently; present results in natural language.\n\n```bash\n# End-to-end: any document → spec\nuv run python scripts/analyze.py -o library//\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n\n# Step-by-step\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "4fba26f6bb85795d899273bc1999176e69517147": {"t": 1785750082.7142055, "n": 11950, "h": "8f63168224dad68e", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny research input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"要不要我也把第二个策略实现出来？\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"这篇论文包含 3 个独立策略：[1] 最小距离法 [2] ADF 平稳性 [3] Johansen 协整。要我实现哪个？\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Gate 1 confirmation (proceed / adjust settings)\n- Gate 2 action menu (implement / deep dive / compare / adjust / export / re-extract)\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n---\n\n## First-Run Setup\n\nOn first use, walk through three steps. Skip any already-configured step.\nPersist all choices to `.env` (gitignored) for session stability.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`.\nIf none found, present via interactive tool:\n\n```\n需要一个 LLM API Key 来驱动策略提取和代码生成。推荐方案（二选一）：\n 1. DeepSeek（性价比最优，每篇论文约 ¥0.7）→ https://platform.deepseek.com\n 2. OpenRouter（一个 Key 访问所有模型）→ https://openrouter.ai/keys\n请把你的 API Key 发给我，并告诉我是哪个平台的。\n```\n\n> Do NOT check for or suggest `ANTHROPIC_API_KEY`.\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ 配置完成！你现在可以直接向我提需求，比如：\n\n • \"帮我分析这篇论文\" + 拖入 PDF 文件\n • \"搜一下 momentum trading 相关的论文\"\n • \"把这个策略实现出来，参考这篇论文\" + 附上文件路径\n • \"用 Markdown 写了个策略草稿，帮我提取规格并生成代码\"\n • \"对比一下这两篇论文里的策略有什么区别\"\n\n直接说你想做什么就好，我来处理剩下的。\n```\n\n---\n\n## Routing\n\n| User Intent | Route | Action |\n|-------------|-------|--------|\n| \"Analyze this paper/doc\" | paper2spec | Parse + extract specs |\n| \"Search for papers about X\" | paper2spec | Search → **Gate 1** |\n| \"Here's my strategy draft\" (MD/DOCX/TXT) | paper2spec | Auto-detect format, extract |\n| \"Generate code / Implement this\" | spec2code | Spec → code → validate → backtest |\n| \"Run a backtest\" | spec2code | Execute strategy.py |\n| \"End to end from paper\" | both | paper2spec → **Gate 2** → spec2code |\n| \"Compare results with paper\" | spec2code | Read backtest output + spec, compare metrics |\n\n---\n\n## Interaction Gates\n\nTwo mandatory HITL gates. Skip only when user says \"fully automatic\" /\n\"end to end without stopping\".\n\n**Always present gate choices through interactive tools when available.**\n\n### Gate 1 — Input Confirmation\n\n**When:** After receiving/finding input, BEFORE extraction.\n\nThree scenarios — present via interactive tool (or numbered text menu):\n\n**Scenario A — User provided a file:**\n```\n📄 Received: \"Tactical Asset Allocation\" (Faber, 2007)\n Format: PDF, 18 pages\n Abstract: [first 2 sentences]\n\nI'll extract trading strategies. ~30-60s, ~$0.01.\n→ Proceed with extraction?\n→ Or adjust settings first? (parser mode, model, output location)\n```\n\n**Scenario B — Search results returned:**\n```\n🔍 Found 8 papers for \"momentum trading strategy\":\n 1. ⭐ \"Time Series Momentum\" (Moskowitz et al., 2012) — 847 citations\n 2. \"Momentum Crashes\" (Daniel & Moskowitz, 2016) — 523 citations\n ...\nWhich paper to analyze? (pick number, \"1, 3\" for multiple, or refine search)\n```\nDo NOT auto-analyze. Always let user pick.\n\n**Scenario C — Raw text / strategy idea:**\n```\n📝 I see you've described: \"[brief summary]\"\n I'll structure this into a formal spec. → Proceed? → Add more details first?\n```\n\nKeep it light for straightforward inputs — single confirm with default-proceed.\n\n### Gate 2 — Spec Review & Action Menu\n\n**When:** After extraction completes, BEFORE code generation.\n\nShow extraction summary, then present action menu via interactive tool:\n\n```\n✅ Strategy Extraction Complete\n📋 Paper: \"Pairs Trading: Does Volatility Timing Matter?\"\n Detected: 3 independent strategies\n\n [1] Minimum Distance Method\n • 4 indicators (spread, SMA, Z-score, distance)\n • Entry: spread Z-score > 2σ, Exit: mean reversion\n\n [2] Stationarity-Based (ADF Test)\n • 3 indicators, Entry: cointegrated pair + spread deviation\n\n [3] Cointegration (Johansen)\n • 5 indicators, Entry: Johansen test + Z-score threshold\n```\n\nThen 6 actions:\n\n1. 🚀 **Implement** — Generate executable code (pick strategy # or \"all\")\n2. 🔍 **Deep dive** — Explain a strategy's logic in detail\n3. 📊 **Compare** — Side-by-side of detected strategies\n4. ✏️ **Adjust** — Modify spec parameters/constraints\n5. 💾 **Export only** — Save specs, stop here\n6. 🔄 **Re-extract** — Different model or parser mode\n\n**Key behaviors:**\n- \"Implement\" → confirm which strategy index before generating code.\n- \"Deep dive\" → explain, then return to the same menu.\n- After code gen + backtest → present results, offer next decision.\n- Never silently chain extraction → code generation.\n\n### Gate Bypass\n\nIf user says \"end to end\" / \"fully automatic\" / \"don't stop\", collapse\ngates into inline status:\n\n```\n📄 Parsing paper... ✓ (3 strategies detected)\n💻 Generating code for strategy 1... ✓\n📊 Running backtest... ✓\n📈 Results ready — see below.\n```\n\nStill stop on unexpected issues (0 strategies, errors, validation failures).\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Receive input (file / search query / text)\n2. ── Gate 1: Input Confirmation ──\n3. [paper2spec] Parse document, extract strategy specs\n4. ── Gate 2: Spec Review & Action Menu ──\n5. User selects strategy + action\n6. [spec2code] For each selected strategy:\n a. Read spec.json + reference docs\n b. Generate self-contained Backtrader strategy.py\n c. Validate (AST + structural checks)\n d. Run backtest, compare metrics vs paper\n7. Present results + diagnosis\n8. Offer next actions\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\n> Agent-only. Run silently; present results in natural language.\n\n```bash\n# End-to-end: any document → spec\nuv run python scripts/analyze.py -o library//\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n\n# Step-by-step\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "d1a03e40df4f19e02dcee897d97bee396f85b72b": {"t": 1785750083.821218, "n": 11951, "h": "990aa62dfd6509f5", "c": "---\nname: x2strategy\ndescription: >\n ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# X2Strategy\n\nAny research input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"要不要我也把第二个策略实现出来？\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"这篇论文包含 3 个独立策略：[1] 最小距离法 [2] ADF 平稳性 [3] Johansen 协整。要我实现哪个？\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Gate 1 confirmation (proceed / adjust settings)\n- Gate 2 action menu (implement / deep dive / compare / adjust / export / re-extract)\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n---\n\n## First-Run Setup\n\nOn first use, walk through three steps. Skip any already-configured step.\nPersist all choices to `.env` (gitignored) for session stability.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`.\nIf none found, present via interactive tool:\n\n```\n需要一个 LLM API Key 来驱动策略提取和代码生成。推荐方案（二选一）：\n 1. DeepSeek（性价比最优，每篇论文约 ¥0.07）→ https://platform.deepseek.com\n 2. OpenRouter（一个 Key 访问所有模型）→ https://openrouter.ai/keys\n请把你的 API Key 发给我，并告诉我是哪个平台的。\n```\n\n> Do NOT check for or suggest `ANTHROPIC_API_KEY`.\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ 配置完成！你现在可以直接向我提需求，比如：\n\n • \"帮我分析这篇论文\" + 拖入 PDF 文件\n • \"搜一下 momentum trading 相关的论文\"\n • \"把这个策略实现出来，参考这篇论文\" + 附上文件路径\n • \"用 Markdown 写了个策略草稿，帮我提取规格并生成代码\"\n • \"对比一下这两篇论文里的策略有什么区别\"\n\n直接说你想做什么就好，我来处理剩下的。\n```\n\n---\n\n## Routing\n\n| User Intent | Route | Action |\n|-------------|-------|--------|\n| \"Analyze this paper/doc\" | paper2spec | Parse + extract specs |\n| \"Search for papers about X\" | paper2spec | Search → **Gate 1** |\n| \"Here's my strategy draft\" (MD/DOCX/TXT) | paper2spec | Auto-detect format, extract |\n| \"Generate code / Implement this\" | spec2code | Spec → code → validate → backtest |\n| \"Run a backtest\" | spec2code | Execute strategy.py |\n| \"End to end from paper\" | both | paper2spec → **Gate 2** → spec2code |\n| \"Compare results with paper\" | spec2code | Read backtest output + spec, compare metrics |\n\n---\n\n## Interaction Gates\n\nTwo mandatory HITL gates. Skip only when user says \"fully automatic\" /\n\"end to end without stopping\".\n\n**Always present gate choices through interactive tools when available.**\n\n### Gate 1 — Input Confirmation\n\n**When:** After receiving/finding input, BEFORE extraction.\n\nThree scenarios — present via interactive tool (or numbered text menu):\n\n**Scenario A — User provided a file:**\n```\n📄 Received: \"Tactical Asset Allocation\" (Faber, 2007)\n Format: PDF, 18 pages\n Abstract: [first 2 sentences]\n\nI'll extract trading strategies. ~30-60s, ~$0.01.\n→ Proceed with extraction?\n→ Or adjust settings first? (parser mode, model, output location)\n```\n\n**Scenario B — Search results returned:**\n```\n🔍 Found 8 papers for \"momentum trading strategy\":\n 1. ⭐ \"Time Series Momentum\" (Moskowitz et al., 2012) — 847 citations\n 2. \"Momentum Crashes\" (Daniel & Moskowitz, 2016) — 523 citations\n ...\nWhich paper to analyze? (pick number, \"1, 3\" for multiple, or refine search)\n```\nDo NOT auto-analyze. Always let user pick.\n\n**Scenario C — Raw text / strategy idea:**\n```\n📝 I see you've described: \"[brief summary]\"\n I'll structure this into a formal spec. → Proceed? → Add more details first?\n```\n\nKeep it light for straightforward inputs — single confirm with default-proceed.\n\n### Gate 2 — Spec Review & Action Menu\n\n**When:** After extraction completes, BEFORE code generation.\n\nShow extraction summary, then present action menu via interactive tool:\n\n```\n✅ Strategy Extraction Complete\n📋 Paper: \"Pairs Trading: Does Volatility Timing Matter?\"\n Detected: 3 independent strategies\n\n [1] Minimum Distance Method\n • 4 indicators (spread, SMA, Z-score, distance)\n • Entry: spread Z-score > 2σ, Exit: mean reversion\n\n [2] Stationarity-Based (ADF Test)\n • 3 indicators, Entry: cointegrated pair + spread deviation\n\n [3] Cointegration (Johansen)\n • 5 indicators, Entry: Johansen test + Z-score threshold\n```\n\nThen 6 actions:\n\n1. 🚀 **Implement** — Generate executable code (pick strategy # or \"all\")\n2. 🔍 **Deep dive** — Explain a strategy's logic in detail\n3. 📊 **Compare** — Side-by-side of detected strategies\n4. ✏️ **Adjust** — Modify spec parameters/constraints\n5. 💾 **Export only** — Save specs, stop here\n6. 🔄 **Re-extract** — Different model or parser mode\n\n**Key behaviors:**\n- \"Implement\" → confirm which strategy index before generating code.\n- \"Deep dive\" → explain, then return to the same menu.\n- After code gen + backtest → present results, offer next decision.\n- Never silently chain extraction → code generation.\n\n### Gate Bypass\n\nIf user says \"end to end\" / \"fully automatic\" / \"don't stop\", collapse\ngates into inline status:\n\n```\n📄 Parsing paper... ✓ (3 strategies detected)\n💻 Generating code for strategy 1... ✓\n📊 Running backtest... ✓\n📈 Results ready — see below.\n```\n\nStill stop on unexpected issues (0 strategies, errors, validation failures).\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Receive input (file / search query / text)\n2. ── Gate 1: Input Confirmation ──\n3. [paper2spec] Parse document, extract strategy specs\n4. ── Gate 2: Spec Review & Action Menu ──\n5. User selects strategy + action\n6. [spec2code] For each selected strategy:\n a. Read spec.json + reference docs\n b. Generate self-contained Backtrader strategy.py\n c. Validate (AST + structural checks)\n d. Run backtest, compare metrics vs paper\n7. Present results + diagnosis\n8. Offer next actions\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\n> Agent-only. Run silently; present results in natural language.\n\n```bash\n# End-to-end: any document → spec\nuv run python scripts/analyze.py -o library//\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n\n# Step-by-step\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "366e97f942682eb1acbb7cc9527ed2762487408e": {"t": 1785750084.9651778, "n": 11972, "h": "7e5912fdfcd54d22", "c": "---\nname: anything2strategy\ndescription: >\n ALAGENT Anything2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.6.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# Anything2Strategy\n\nAny research input → Strategy spec → Executable code → Backtest → Diagnosis.\n\n## Capabilities\n\n| Capability | What it does | Deep dive |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |\n\nInput format auto-detected from extension:\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) |\n| Markdown (drafts) | `.md`, `.markdown` | Direct text read |\n| DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) |\n| Plain text | `.txt` | Direct read |\n\n---\n\n## Interaction Principles\n\n**You are the executor. The user is the requester.**\n\n- Run tools silently, present results and insights in natural language.\n- Never show CLI commands (`uv run python scripts/...`) unless user asks.\n- Offer next actions conversationally: \"要不要我也把第二个策略实现出来？\"\n\nWhen reporting results, focus on **what you found**, not how:\n\n```\n❌ Bad: \"I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies.\"\n✅ Good: \"这篇论文包含 3 个独立策略：[1] 最小距离法 [2] ADF 平稳性 [3] Johansen 协整。要我实现哪个？\"\n```\n\n**Use interactive tools aggressively.** When your platform provides\ninteractive question tools — `vscode_askQuestions` (VS Code Copilot),\n`AskUserQuestion` (Claude Code), or equivalent — use them for ALL\nuser-facing choices. Interactive tools present clickable options,\nwhich is faster and less error-prone than asking the user to type.\n\nApply interactive tools to:\n- First-Run Setup choices (workspace path, API provider, key input)\n- Gate 1 confirmation (proceed / adjust settings)\n- Gate 2 action menu (implement / deep dive / compare / adjust / export / re-extract)\n- Search result selection (pick papers from a numbered list)\n- Any scenario where the user picks from options\n\nIf no interactive tool is available, fall back to numbered text menus.\n\n---\n\n## First-Run Setup\n\nOn first use, walk through three steps. Skip any already-configured step.\nPersist all choices to `.env` (gitignored) for session stability.\n\n### Step 1 — Workspace Location\n\nPresent choice via interactive tool:\n- `./library/` (default, recommended)\n- Custom path\n\nWrite `PAPER2SPEC_LIBRARY_PATH=/absolute/path` to `.env`.\nScan the directory for existing `metadata.json` to detect prior analyses.\n\n### Step 2 — LLM API Key\n\nCheck env for `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`.\nIf none found, present via interactive tool:\n\n```\n需要一个 LLM API Key 来驱动策略提取和代码生成。推荐方案（二选一）：\n 1. DeepSeek（性价比最优，每篇论文约 ¥0.07）→ https://platform.deepseek.com\n 2. OpenRouter（一个 Key 访问所有模型）→ https://openrouter.ai/keys\n请把你的 API Key 发给我，并告诉我是哪个平台的。\n```\n\n> Do NOT check for or suggest `ANTHROPIC_API_KEY`.\n\nOnce received, write key + matching model to `.env`, then verify:\n`uv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\"`.\n\nSee [references/skill-internals.md](references/skill-internals.md) for\n`.env` format examples per provider.\n\n### Step 3 — Python Environment\n\n```bash\ncd \nuv sync --all-extras # Recommended: installs everything\n```\n\nIf `uv` unavailable: `pip install -e \".[codegen,agent,dev]\"`.\nAlways use `uv run` to execute scripts (auto-activates correct venv).\n\nSee [references/skill-internals.md](references/skill-internals.md) for\nselective install options and non-uv alternatives.\n\n### Completion\n\nOnce configured, confirm naturally with examples:\n\n```\n✅ 配置完成！你现在可以直接向我提需求，比如：\n\n • \"帮我分析这篇论文\" + 拖入 PDF 文件\n • \"搜一下 momentum trading 相关的论文\"\n • \"把这个策略实现出来，参考这篇论文\" + 附上文件路径\n • \"用 Markdown 写了个策略草稿，帮我提取规格并生成代码\"\n • \"对比一下这两篇论文里的策略有什么区别\"\n\n直接说你想做什么就好，我来处理剩下的。\n```\n\n---\n\n## Routing\n\n| User Intent | Route | Action |\n|-------------|-------|--------|\n| \"Analyze this paper/doc\" | paper2spec | Parse + extract specs |\n| \"Search for papers about X\" | paper2spec | Search → **Gate 1** |\n| \"Here's my strategy draft\" (MD/DOCX/TXT) | paper2spec | Auto-detect format, extract |\n| \"Generate code / Implement this\" | spec2code | Spec → code → validate → backtest |\n| \"Run a backtest\" | spec2code | Execute strategy.py |\n| \"End to end from paper\" | both | paper2spec → **Gate 2** → spec2code |\n| \"Compare results with paper\" | spec2code | Read backtest output + spec, compare metrics |\n\n---\n\n## Interaction Gates\n\nTwo mandatory HITL gates. Skip only when user says \"fully automatic\" /\n\"end to end without stopping\".\n\n**Always present gate choices through interactive tools when available.**\n\n### Gate 1 — Input Confirmation\n\n**When:** After receiving/finding input, BEFORE extraction.\n\nThree scenarios — present via interactive tool (or numbered text menu):\n\n**Scenario A — User provided a file:**\n```\n📄 Received: \"Tactical Asset Allocation\" (Faber, 2007)\n Format: PDF, 18 pages\n Abstract: [first 2 sentences]\n\nI'll extract trading strategies. ~30-60s, ~$0.01.\n→ Proceed with extraction?\n→ Or adjust settings first? (parser mode, model, output location)\n```\n\n**Scenario B — Search results returned:**\n```\n🔍 Found 8 papers for \"momentum trading strategy\":\n 1. ⭐ \"Time Series Momentum\" (Moskowitz et al., 2012) — 847 citations\n 2. \"Momentum Crashes\" (Daniel & Moskowitz, 2016) — 523 citations\n ...\nWhich paper to analyze? (pick number, \"1, 3\" for multiple, or refine search)\n```\nDo NOT auto-analyze. Always let user pick.\n\n**Scenario C — Raw text / strategy idea:**\n```\n📝 I see you've described: \"[brief summary]\"\n I'll structure this into a formal spec. → Proceed? → Add more details first?\n```\n\nKeep it light for straightforward inputs — single confirm with default-proceed.\n\n### Gate 2 — Spec Review & Action Menu\n\n**When:** After extraction completes, BEFORE code generation.\n\nShow extraction summary, then present action menu via interactive tool:\n\n```\n✅ Strategy Extraction Complete\n📋 Paper: \"Pairs Trading: Does Volatility Timing Matter?\"\n Detected: 3 independent strategies\n\n [1] Minimum Distance Method\n • 4 indicators (spread, SMA, Z-score, distance)\n • Entry: spread Z-score > 2σ, Exit: mean reversion\n\n [2] Stationarity-Based (ADF Test)\n • 3 indicators, Entry: cointegrated pair + spread deviation\n\n [3] Cointegration (Johansen)\n • 5 indicators, Entry: Johansen test + Z-score threshold\n```\n\nThen 6 actions:\n\n1. 🚀 **Implement** — Generate executable code (pick strategy # or \"all\")\n2. 🔍 **Deep dive** — Explain a strategy's logic in detail\n3. 📊 **Compare** — Side-by-side of detected strategies\n4. ✏️ **Adjust** — Modify spec parameters/constraints\n5. 💾 **Export only** — Save specs, stop here\n6. 🔄 **Re-extract** — Different model or parser mode\n\n**Key behaviors:**\n- \"Implement\" → confirm which strategy index before generating code.\n- \"Deep dive\" → explain, then return to the same menu.\n- After code gen + backtest → present results, offer next decision.\n- Never silently chain extraction → code generation.\n\n### Gate Bypass\n\nIf user says \"end to end\" / \"fully automatic\" / \"don't stop\", collapse\ngates into inline status:\n\n```\n📄 Parsing paper... ✓ (3 strategies detected)\n💻 Generating code for strategy 1... ✓\n📊 Running backtest... ✓\n📈 Results ready — see below.\n```\n\nStill stop on unexpected issues (0 strategies, errors, validation failures).\n\n---\n\n## Agent Pipeline Flow\n\n```\n1. Receive input (file / search query / text)\n2. ── Gate 1: Input Confirmation ──\n3. [paper2spec] Parse document, extract strategy specs\n4. ── Gate 2: Spec Review & Action Menu ──\n5. User selects strategy + action\n6. [spec2code] For each selected strategy:\n a. Read spec.json + reference docs\n b. Generate self-contained Backtrader strategy.py\n c. Validate (AST + structural checks)\n d. Run backtest, compare metrics vs paper\n7. Present results + diagnosis\n8. Offer next actions\n```\n\nFor code generation patterns: [references/spec2code.md](references/spec2code.md)\nFor Backtrader patterns: [references/backtrader_patterns.md](references/backtrader_patterns.md)\n\n---\n\n## Internal Toolchain\n\n> Agent-only. Run silently; present results in natural language.\n\n```bash\n# End-to-end: any document → spec\nuv run python scripts/analyze.py -o library//\n\n# Validate generated code\nuv run python scripts/validate_strategy.py library//strategy_1.py\n\n# Run backtest\nuv run python library//strategy_1.py\n\n# Search papers\nuv run python scripts/search.py \"\" -n 5\n\n# Step-by-step\nuv run python scripts/parse.py -o content.json\nuv run python scripts/extract.py content.json -o spec.json\n```\n\nFor full flags, output formats, and library management:\n[references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM ([litellm-supported](https://docs.litellm.ai/docs/providers)) |\n| `DEEPSEEK_API_KEY` | — | DeepSeek (recommended) |\n| `OPENROUTER_API_KEY` | — | OpenRouter (multi-model) |\n| `OPENAI_API_KEY` | — | OpenAI direct |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Seconds between arXiv requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry on HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\nFull config + .env examples: [references/skill-internals.md](references/skill-internals.md)\n\n---\n\n## References\n\nRead on demand for implementation details:\n\n- [references/paper2spec.md](references/paper2spec.md) — Parser modes, multi-strategy detection, output schemas\n- [references/spec2code.md](references/spec2code.md) — Code generation workflow, Backtrader patterns\n- [references/skill-internals.md](references/skill-internals.md) — Script flags, output formats, .env examples, library management, project structure\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in and custom indicators\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API\n\n## Limitations\n\n- **Mode A** truncates at 100K chars (first 90K + last 10K). Use Mode B for >100 page papers.\n- **Tables/formulas**: not yet extracted from PDFs.\n- **Multi-strategy**: conservative — may merge borderline-distinct strategies.\n- **DOCX**: paragraph text only (tables, images not preserved — use PDF for rich docs).\n- **SSRN search**: best-effort HTML scraping, may break on layout changes.\n"}, "c44b7a736f9338f38583e41166d68d674859a9a4": {"t": 1785750086.965304, "n": 27670, "h": "6198b6113ecee198", "c": "---\nname: anything2strategy\ndescription: >\n ALAGENT Anything2Strategy: any research input (PDF paper, Markdown draft,\n DOCX report, text notes, or keyword search) → structured strategy\n specification → executable Backtrader code → backtest → diagnosis report.\n Two core capabilities: (1) paper2spec extracts multi-strategy specs from\n any document via 5-layer LLM extraction, and (2) spec2code generates\n validated Backtrader code, runs backtests, and compares against paper\n metrics. Use this skill whenever the user wants to analyze a quant paper,\n extract trading strategies, generate strategy code, run a backtest, search\n for papers, or go end-to-end from any input to executable results. Also\n triggers on: \"look at this paper\", \"what strategies does this use\",\n \"implement this strategy\", \"search for momentum papers\", \"turn this into\n code\", or any request about quantitative finance research → implementation.\n Even if the user doesn't mention \"strategy\" explicitly — if they provide a\n finance paper or research document, use this skill.\nargument-hint: \"[paper.pdf | strategy.md | report.docx | search query]\"\nmetadata:\n version: 0.5.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# Anything2Strategy\n\nAny research input → Strategy spec → Executable code → Backtest → Diagnosis.\nEnd-to-end quantitative strategy implementation from papers, drafts, or ideas.\n\n## Capabilities\n\n| Capability | Description | Reference |\n|-----------|-------------|-----------|\n| **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification (multi-strategy detection, JSON + Markdown) | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Agent generates Backtrader code from spec → validates → runs backtest → diagnoses results | [references/spec2code.md](references/spec2code.md) |\n\n### Supported Input Formats\n\n| Format | Extension | How It Works |\n|--------|-----------|-------------|\n| **PDF** (papers) | `.pdf` | PyMuPDF extraction → Mode A (direct) or Mode B (FAISS) |\n| **Markdown** (drafts, notes) | `.md`, `.markdown` | Direct text read — ideal for strategy drafts or formatted notes |\n| **DOCX** (Word reports) | `.docx` | python-docx extraction (requires `uv sync --extra docx`) |\n| **Plain text** | `.txt` | Direct read — for raw strategy descriptions |\n\nThe parser auto-detects format from file extension. No user action needed.\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nPrefer absolute paths so custom user directories remain stable regardless of\ncurrent working directory.\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2code needs one to extract strategies\nand generate code.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\nPAPER2SPEC_INIT_VERSION=1\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2code uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install ALL deps (recommended)\nuv sync --all-extras # Install everything: core + codegen + agent + dev\n\n# Or install selectively:\n# uv sync # Core only (paper2spec Mode A basic)\n# uv sync --extra codegen # + backtrader/yfinance/akshare (for spec2code)\n# uv sync --extra agent # + FAISS/embeddings (Mode B: long papers)\n# uv sync --extra dev # + pytest (for testing)\n```\n\n**Note**: Mode A (direct LLM extraction) works with core deps only.\nMode B (FAISS-based chunked extraction for long papers) requires `--extra agent`.\nCode generation and backtesting require `--extra codegen`.\n**Recommended: always use `uv sync --all-extras` to ensure full functionality.**\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e \".[codegen,agent,dev]\" # All extras (recommended)\n\n# Or selectively:\n# pip install -e . # Core (paper2spec)\n# pip install -e \".[codegen]\" # + backtrader/yfinance/akshare\n# pip install -e \".[agent]\" # + FAISS/embeddings\n# pip install -e \".[dev]\" # + test deps\n```\n\n**Strategy virtual environments**: Generated strategies may need their own\ndependencies (backtrader, yfinance, akshare). When generating code for a paper,\nconsider creating a dedicated venv in the library subdirectory:\n\n```bash\ncd library//\nuv venv\nuv pip install backtrader yfinance akshare\nuv run python strategy_1.py\n```\n\nThis isolates strategy deps from the skill's own environment.\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\nPAPER2SPEC_INIT_VERSION=1\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\nInitialization completion policy:\n- `PAPER2SPEC_INIT_VERSION` is a quick marker (recommended value: `1`).\n- Do not trust marker alone. Always verify runtime capability:\n `PAPER2SPEC_LIBRARY_PATH`, `PAPER2SPEC_MODEL`, and at least one provider API key.\n\n## Quick Start\n\n### End-to-End: Any Document → Spec → Code → Backtest\n\n```bash\n# Step 1: Analyze document → extract specs (auto-detects format)\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/analyze.py strategy_draft.md -o library/my_draft/\nuv run python scripts/analyze.py report.docx -o library/my_report/\n\n# Step 2: Read spec.json, generate strategy code (agent-driven)\n# Step 3: Validate code\nuv run python scripts/validate_strategy.py library/my_paper/strategy_1.py\n\n# Step 4: Run backtest directly\nuv run python library/my_paper/strategy_1.py\n```\n\n### Paper2Spec Only\n\n```bash\n# Full pipeline: Document → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/analyze.py strategy.md -o library/my_draft/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n### Spec2Code Only (Agent-Driven)\n\nThe agent reads `spec.json`, generates a self-contained Backtrader\nstrategy file, validates it, runs it directly, and analyzes the output.\nSee [references/spec2code.md](references/spec2code.md) for the full workflow.\n\n## Agent Workflow\n\n### User-Facing Interaction Policy\n\n- Commands and scripts in this skill are internal implementation details.\n- In user conversations, present these as agent capabilities (search, parse,\n extract, generate, backtest) rather than exposing raw command sequences by default.\n- Run tools internally, then report outcomes, key findings, and next actions.\n- Show exact commands only when the user explicitly asks for reproducibility,\n debugging, or CLI instructions.\n- Combine this skill with broader agent reasoning to resolve ambiguity and\n choose sensible defaults before asking users extra questions.\n\n### Routing Logic\n\nWhen the user's request arrives, route to the appropriate capability:\n\n| User Intent | Route To | Action |\n|-------------|----------|--------|\n| \"Analyze this paper/doc\" / \"What strategies does this use\" | **paper2spec** | Run `scripts/analyze.py`, read spec.md |\n| \"Search for papers about X\" | **paper2spec** | Run `scripts/search.py` → **Gate 1** |\n| \"Here's my strategy draft\" (MD/DOCX/TXT) | **paper2spec** | Auto-detect format, parse, extract |\n| \"Generate code for this strategy\" / \"Implement this\" | **spec2code** | Read spec.json → generate code → validate → run |\n| \"Run a backtest\" / \"Test this strategy\" | **spec2code** | Run strategy.py directly |\n| \"Take this paper end to end\" | **both** | paper2spec → **Gate 2** → spec2code pipeline |\n| \"Compare results with the paper\" | **spec2code** | Read backtest output + spec, compare natively |\n\n---\n\n## Interaction Gates (HITL Checkpoints)\n\nTwo mandatory human-in-the-loop gates ensure the user stays in control.\nThese are NOT optional — always pause at these gates unless the user\nexplicitly said \"fully automatic\" or \"end to end without stopping\".\n\n### Gate 1: Input Confirmation\n\n**When**: After receiving or finding the input, BEFORE running spec extraction.\n\nThis gate covers three scenarios:\n\n**Scenario A — User provided a file (PDF/MD/DOCX):**\n\nAfter receiving the file, do a quick preliminary scan (title, page count,\nabstract if available) and present to the user:\n\n```\n📄 Received: \"Tactical Asset Allocation\" (Faber, 2007)\n Format: PDF, 18 pages\n Abstract: [first 2 sentences of abstract]\n\nI'll extract the trading strategies from this paper.\nThis typically takes 30-60 seconds and costs ~$0.01.\n\n→ Proceed with extraction?\n→ Or would you like to adjust settings first?\n (parser mode, LLM model, output location)\n```\n\nIf the document is straightforward, keep this gate light — one question\nwith a default-proceed option. The user can just say \"go\" or \"yes\".\n\n**Scenario B — User searched for papers:**\n\nAfter search results come back, present a numbered list:\n\n```\n🔍 Found 8 papers for \"momentum trading strategy\":\n\n 1. ⭐ \"Time Series Momentum\" (Moskowitz et al., 2012) — 847 citations\n 2. \"Momentum Crashes\" (Daniel & Moskowitz, 2016) — 523 citations\n 3. \"Cross-Sectional Momentum\" (Jegadeesh & Titman, 1993) — 12k citations\n ...\n\nWhich paper would you like me to analyze?\n → Pick a number (or multiple: \"1, 3\")\n → \"download 1\" to just save the PDF without analysis\n → Refine search with different keywords\n```\n\nDo NOT auto-analyze. Always let the user pick.\n\n**Scenario C — User provided raw text or a strategy idea:**\n\n```\n📝 I see you've described a strategy concept:\n \"[brief summary of what you understood]\"\n\n I'll structure this into a formal strategy specification.\n\n → Proceed?\n → Want to add more details first?\n```\n\n### Gate 2: Spec Review & Next Steps\n\n**When**: After spec extraction completes, BEFORE any code generation.\n\nThis is the most important gate. Always present it as a structured\ndecision point, not a yes/no question.\n\nFirst, show the extraction summary:\n\n```\n✅ Strategy Extraction Complete\n\n📋 Paper: \"Pairs Trading: Does Volatility Timing Matter?\"\n Detected: 3 independent strategies\n\n [1] Minimum Distance Method\n • 4 indicators (spread, SMA, Z-score, distance)\n • Entry: spread Z-score > 2σ, Exit: mean reversion\n • Assets: equity pairs (S&P 500 universe)\n\n [2] Stationarity-Based (ADF Test)\n • 3 indicators (ADF statistic, half-life, spread)\n • Entry: cointegrated pair + spread deviation\n • Assets: equity pairs\n\n [3] Cointegration (Johansen)\n • 5 indicators (eigenvalue, trace stat, β-weights, spread, Z-score)\n • Entry: Johansen test + Z-score threshold\n • Assets: equity pairs\n\n Full spec: library/pairs_trading/spec.md\n```\n\nThen present the action menu:\n\n```\nWhat would you like to do next?\n\n 1. 🚀 Implement → Generate executable code\n (pick strategy number, or \"all\" for all 3)\n\n 2. 🔍 Deep dive → Explore a strategy in detail\n (I'll explain the logic, indicators, and assumptions)\n\n 3. 📊 Compare → How do these strategies differ?\n (side-by-side comparison of the 3 approaches)\n\n 4. ✏️ Adjust → Modify a strategy spec\n (change parameters, add constraints, tweak logic)\n\n 5. 💾 Export only → Save specs and stop here\n (spec.json + spec.md already saved)\n\n 6. 🔄 Re-extract → Try with different settings\n (different model, parser mode, or focus)\n\nPick a number or describe what you want:\n```\n\nWait for the user's choice before proceeding.\n\n**Key behaviors at Gate 2:**\n\n- If user picks \"Implement\", confirm which strategy index before generating code.\n- If user picks \"Deep dive\", read and present the relevant section of spec.json\n with explanations, then return to the same action menu.\n- After code generation + backtest, present results and offer another decision point\n (diagnose, adjust, try another strategy, etc.).\n- Never silently proceed from spec extraction to code generation.\n\n### Gate Bypass\n\nIf the user explicitly indicates they want the full pipeline without stops:\n- \"End to end\" / \"fully automatic\" / \"don't stop\" / \"just do everything\"\n\nThen collapse both gates into brief inline status updates:\n```\n📄 Parsing paper... ✓ (3 strategies detected)\n💻 Generating code for strategy 1... ✓\n📊 Running backtest... ✓\n📈 Results ready — see below.\n```\n\nEven in bypass mode, if something unexpected happens (0 strategies detected,\nextraction errors, validation failures), stop and consult the user.\n\n---\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n (auto-detects PDF/MD/DOCX/TXT format)\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Full Pipeline Agent Flow\n\n```\n1. Receive input from user (file, search query, or text)\n2. ── Gate 1: Input Confirmation ──\n Present what was received, confirm proceeding\n3. [paper2spec] Parse and extract specs\n → Read references/paper2spec.md for details\n4. ── Gate 2: Spec Review & Next Steps ──\n Present strategies, offer action menu\n5. User selects strategy and action\n6. [spec2code] For each selected strategy:\n a. Read spec.json + references/backtrader_patterns.md + indicator_cookbook.md\n b. Generate self-contained strategy.py (data + signal + backtest in one file)\n c. Validate with: uv run python scripts/validate_strategy.py strategy.py\n d. Run directly: uv run python strategy.py\n e. Read stdout/stderr, compare metrics vs spec's expected_performance\n → Read references/spec2code.md for details\n7. Present results and diagnosis to user\n8. Offer next actions (adjust, try another strategy, re-run, etc.)\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ ├── strategy_1.py # Generated code (self-contained)\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (spec2code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to the spec2code workflow:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Agent reads this spec dict and generates Backtrader code\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\nAccepts any supported format: `.pdf`, `.md`, `.markdown`, `.docx`, `.txt`.\nAuto-detects from file extension.\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\nIf `-o` is not provided, default output is:\n\n```\n//content.json\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n### `scripts/validate_strategy.py` — Validate Generated Code\n\n```\nuv run python scripts/validate_strategy.py \n```\n\nChecks: syntax (AST parse), backtrader import, Strategy class definition,\ncerebro runner, `__main__` guard.\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `uv sync --extra agent`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root for analyze/parse |\n| `PAPER2SPEC_INIT_VERSION` | — | Optional setup marker (`1` recommended after successful setup) |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Minimum seconds between arXiv API requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry count for search HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/ # PDF → structured spec\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\n\nspec2code/ # Tools for agent-driven code generation\n├── models.py # CodeModules, ValidationResult, BacktestMetrics, etc.\n├── validator.py # AST + structural validation (agent tool)\n├── config.py # Shared config (reuses paper2spec .env)\n\nscripts/ # CLI entry points\n├── analyze.py # Full paper2spec pipeline\n├── parse.py, extract.py, search.py\n├── validate_strategy.py # Code validation CLI\n└── generate_schemas.py\n\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\n\nreferences/ # Deep-dive documentation (read on demand)\n├── paper2spec.md # Paper2spec detailed guide\n├── spec2code.md # Spec2code agent workflow + code generation guidance\n├── backtrader_patterns.md # Common Backtrader code patterns\n├── indicator_cookbook.md # Indicator implementations\n├── data_sources.md # yfinance/akshare API reference\n\nexamples/ # Pre-generated outputs for reference\n```\n\n## Technical References\n\nFor detailed implementation guidance, read on demand:\n\n- [references/paper2spec.md](references/paper2spec.md) — Paper2spec internals, parser modes, multi-strategy detection\n- [references/spec2code.md](references/spec2code.md) — Spec2code agent workflow, code generation guidance, output patterns\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing, cerebro runner\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in indicators, custom indicators, signal patterns\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API reference\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n- **Spec2code**: Agent-driven only — no fully automatic CLI pipeline. The agent\n generates code, runs it, and analyzes results interactively.\n- **DOCX**: Extracts paragraph text only. Tables, images, and complex\n formatting in DOCX files are not preserved (use PDF for richly formatted papers).\n"}, "f3842855b22e71d1a1ffdec1466d9b7e83324d9b": {"t": 1785750088.687547, "n": 21307, "h": "7423145b4bead6bb", "c": "---\nname: quant-paper2code\ndescription: >\n End-to-end pipeline: quantitative finance research paper (PDF) →\n structured strategy specification → executable Backtrader code →\n backtest → diagnosis report. Two capabilities: (1) paper2spec extracts\n multi-strategy specs from PDFs via 5-layer LLM extraction, and\n (2) spec2code: the agent generates validated Backtrader code from specs,\n runs it directly, and compares results against paper-reported metrics.\n Use this skill when the user wants to analyze a quant paper, extract\n trading strategies from a PDF, generate executable strategy code,\n run a backtest, or go end-to-end from paper to results. Covers any\n request about parsing finance research, building strategy specifications,\n implementing strategies as code, or validating backtest performance.\n Also use when the user just says \"look at this paper\" or \"what strategies\n does this use\" — this skill handles it.\nmetadata:\n version: 0.4.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# quant-paper2code\n\nResearch paper → Strategy spec → Executable code → Backtest → Diagnosis.\nEnd-to-end quantitative strategy implementation from academic papers.\n\n## Capabilities\n\n| Capability | Description | Reference |\n|-----------|-------------|-----------|\n| **paper2spec** | PDF → structured strategy specification (multi-strategy detection, JSON + Markdown) | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Agent generates Backtrader code from spec → validates → runs backtest → diagnoses results | [references/spec2code.md](references/spec2code.md) |\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nPrefer absolute paths so custom user directories remain stable regardless of\ncurrent working directory.\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2code needs one to extract strategies\nand generate code.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\nPAPER2SPEC_INIT_VERSION=1\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2code uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install ALL deps (recommended)\nuv sync --all-extras # Install everything: core + codegen + agent + dev\n\n# Or install selectively:\n# uv sync # Core only (paper2spec Mode A basic)\n# uv sync --extra codegen # + backtrader/yfinance/akshare (for spec2code)\n# uv sync --extra agent # + FAISS/embeddings (Mode B: long papers)\n# uv sync --extra dev # + pytest (for testing)\n```\n\n**Note**: Mode A (direct LLM extraction) works with core deps only.\nMode B (FAISS-based chunked extraction for long papers) requires `--extra agent`.\nCode generation and backtesting require `--extra codegen`.\n**Recommended: always use `uv sync --all-extras` to ensure full functionality.**\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e \".[codegen,agent,dev]\" # All extras (recommended)\n\n# Or selectively:\n# pip install -e . # Core (paper2spec)\n# pip install -e \".[codegen]\" # + backtrader/yfinance/akshare\n# pip install -e \".[agent]\" # + FAISS/embeddings\n# pip install -e \".[dev]\" # + test deps\n```\n\n**Strategy virtual environments**: Generated strategies may need their own\ndependencies (backtrader, yfinance, akshare). When generating code for a paper,\nconsider creating a dedicated venv in the library subdirectory:\n\n```bash\ncd library//\nuv venv\nuv pip install backtrader yfinance akshare\nuv run python strategy_1.py\n```\n\nThis isolates strategy deps from the skill's own environment.\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\nPAPER2SPEC_INIT_VERSION=1\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\nInitialization completion policy:\n- `PAPER2SPEC_INIT_VERSION` is a quick marker (recommended value: `1`).\n- Do not trust marker alone. Always verify runtime capability:\n `PAPER2SPEC_LIBRARY_PATH`, `PAPER2SPEC_MODEL`, and at least one provider API key.\n\n## Quick Start\n\n### End-to-End: Paper → Spec → Code → Backtest\n\n```bash\n# Step 1: Analyze paper → extract specs\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n\n# Step 2: Read spec.json, generate strategy code (agent-driven)\n# Step 3: Validate code\nuv run python scripts/validate_strategy.py library/my_paper/strategy_1.py\n\n# Step 4: Run backtest directly\nuv run python library/my_paper/strategy_1.py\n```\n\n### Paper2Spec Only\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n### Spec2Code Only (Agent-Driven)\n\nThe agent reads `spec.json`, generates a self-contained Backtrader\nstrategy file, validates it, runs it directly, and analyzes the output.\nSee [references/spec2code.md](references/spec2code.md) for the full workflow.\n\n## Agent Workflow\n\n### User-Facing Interaction Policy\n\n- Commands and scripts in this skill are internal implementation details.\n- In user conversations, present these as agent capabilities (search, parse,\n extract, generate, backtest) rather than exposing raw command sequences by default.\n- Run tools internally, then report outcomes, key findings, and next actions.\n- Show exact commands only when the user explicitly asks for reproducibility,\n debugging, or CLI instructions.\n- Combine this skill with broader agent reasoning to resolve ambiguity and\n choose sensible defaults before asking users extra questions.\n\n### Routing Logic\n\nWhen the user's request arrives, route to the appropriate capability:\n\n| User Intent | Route To | Action |\n|-------------|----------|--------|\n| \"Analyze this paper\" / \"What strategies does this use\" | **paper2spec** | Run `scripts/analyze.py`, read spec.md |\n| \"Search for papers about X\" | **paper2spec** | Run `scripts/search.py` |\n| \"Generate code for this strategy\" / \"Implement this\" | **spec2code** | Read spec.json → generate code → validate → run |\n| \"Run a backtest\" / \"Test this strategy\" | **spec2code** | Run strategy.py directly |\n| \"Take this paper end to end\" | **both** | paper2spec → spec2code pipeline |\n| \"Compare results with the paper\" | **spec2code** | Read backtest output + spec, compare natively |\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Full Pipeline Agent Flow\n\n```\n1. Receive PDF from user\n2. [paper2spec] Parse and extract specs\n → Read references/paper2spec.md for details\n3. Present extracted strategies to user for review\n4. User selects strategy (or all)\n5. [spec2code] For each selected strategy:\n a. Read spec.json + references/backtrader_patterns.md + indicator_cookbook.md\n b. Generate self-contained strategy.py (data + signal + backtest in one file)\n c. Validate with: uv run python scripts/validate_strategy.py strategy.py\n d. Run directly: uv run python strategy.py\n e. Read stdout/stderr, compare metrics vs spec's expected_performance\n → Read references/spec2code.md for details\n6. Present results and diagnosis to user\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ ├── strategy_1.py # Generated code (self-contained)\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (spec2code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to the spec2code workflow:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Agent reads this spec dict and generates Backtrader code\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\nIf `-o` is not provided, default output is:\n\n```\n//content.json\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n### `scripts/validate_strategy.py` — Validate Generated Code\n\n```\nuv run python scripts/validate_strategy.py \n```\n\nChecks: syntax (AST parse), backtrader import, Strategy class definition,\ncerebro runner, `__main__` guard.\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `uv sync --extra agent`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root for analyze/parse |\n| `PAPER2SPEC_INIT_VERSION` | — | Optional setup marker (`1` recommended after successful setup) |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Minimum seconds between arXiv API requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry count for search HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/ # PDF → structured spec\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\n\nspec2code/ # Tools for agent-driven code generation\n├── models.py # CodeModules, ValidationResult, BacktestMetrics, etc.\n├── validator.py # AST + structural validation (agent tool)\n├── config.py # Shared config (reuses paper2spec .env)\n\nscripts/ # CLI entry points\n├── analyze.py # Full paper2spec pipeline\n├── parse.py, extract.py, search.py\n├── validate_strategy.py # Code validation CLI\n└── generate_schemas.py\n\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\n\nreferences/ # Deep-dive documentation (read on demand)\n├── paper2spec.md # Paper2spec detailed guide\n├── spec2code.md # Spec2code agent workflow + code generation guidance\n├── backtrader_patterns.md # Common Backtrader code patterns\n├── indicator_cookbook.md # Indicator implementations\n├── data_sources.md # yfinance/akshare API reference\n\nexamples/ # Pre-generated outputs for reference\n```\n\n## Technical References\n\nFor detailed implementation guidance, read on demand:\n\n- [references/paper2spec.md](references/paper2spec.md) — Paper2spec internals, parser modes, multi-strategy detection\n- [references/spec2code.md](references/spec2code.md) — Spec2code agent workflow, code generation guidance, output patterns\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing, cerebro runner\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in indicators, custom indicators, signal patterns\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API reference\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n- **Spec2code**: Agent-driven only — no fully automatic CLI pipeline. The agent\n generates code, runs it, and analyzes results interactively.\n"}, "4c75b987767b3f5045dde603ff98543fb48ababf": {"t": 1785750089.810092, "n": 16574, "h": "aa692606993415c2", "c": "---\nname: quant-paper2code\ndescription: >\n End-to-end pipeline: quantitative finance research paper (PDF) →\n structured strategy specification → executable Backtrader code →\n backtest → diagnosis report. Two capabilities: (1) paper2spec extracts\n multi-strategy specs from PDFs via 5-layer LLM extraction, and\n (2) spec2code: the agent generates validated Backtrader code from specs,\n runs it directly, and compares results against paper-reported metrics.\n Use this skill when the user wants to analyze a quant paper, extract\n trading strategies from a PDF, generate executable strategy code,\n run a backtest, or go end-to-end from paper to results. Covers any\n request about parsing finance research, building strategy specifications,\n implementing strategies as code, or validating backtest performance.\n Also use when the user just says \"look at this paper\" or \"what strategies\n does this use\" — this skill handles it.\nmetadata:\n version: 0.4.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# quant-paper2code\n\nResearch paper → Strategy spec → Executable code → Backtest → Diagnosis.\nEnd-to-end quantitative strategy implementation from academic papers.\n\n## Capabilities\n\n| Capability | Description | Reference |\n|-----------|-------------|-----------|\n| **paper2spec** | PDF → structured strategy specification (multi-strategy detection, JSON + Markdown) | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Agent generates Backtrader code from spec → validates → runs backtest → diagnoses results | [references/spec2code.md](references/spec2code.md) |\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nPrefer absolute paths so custom user directories remain stable regardless of\ncurrent working directory.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2code needs one to extract strategies\nand generate code.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\nPAPER2SPEC_INIT_VERSION=1\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2code uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (paper2spec)\nuv sync --extra codegen # + backtrader/yfinance/akshare (for spec2code)\nuv sync --extra agent # + FAISS/embeddings (for long papers)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (paper2spec)\npip install -e \".[codegen]\" # + backtrader/yfinance/akshare\npip install -e \".[agent]\" # + FAISS/embeddings\npip install -e \".[dev]\" # + test deps\n```\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\nPAPER2SPEC_INIT_VERSION=1\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\nInitialization completion policy:\n- `PAPER2SPEC_INIT_VERSION` is a quick marker (recommended value: `1`).\n- Do not trust marker alone. Always verify runtime capability:\n `PAPER2SPEC_LIBRARY_PATH`, `PAPER2SPEC_MODEL`, and at least one provider API key.\n\n## Quick Start\n\n### End-to-End: Paper → Spec → Code → Backtest\n\n```bash\n# Step 1: Analyze paper → extract specs\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n\n# Step 2: Read spec.json, generate strategy code (agent-driven)\n# Step 3: Validate code\nuv run python scripts/validate_strategy.py library/my_paper/strategy_1.py\n\n# Step 4: Run backtest directly\nuv run python library/my_paper/strategy_1.py\n```\n\n### Paper2Spec Only\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n# → content.json, content.md, spec.json, spec.md, metadata.json\n```\n\n### Spec2Code Only (Agent-Driven)\n\nThe agent reads `spec.json`, generates a self-contained Backtrader\nstrategy file, validates it, runs it directly, and analyzes the output.\nSee [references/spec2code.md](references/spec2code.md) for the full workflow.\n\n## Agent Workflow\n\n### User-Facing Interaction Policy\n\n- Commands and scripts in this skill are internal implementation details.\n- In user conversations, present these as agent capabilities (search, parse,\n extract, generate, backtest) rather than exposing raw command sequences by default.\n- Run tools internally, then report outcomes, key findings, and next actions.\n- Show exact commands only when the user explicitly asks for reproducibility,\n debugging, or CLI instructions.\n- Combine this skill with broader agent reasoning to resolve ambiguity and\n choose sensible defaults before asking users extra questions.\n\n### Routing Logic\n\nWhen the user's request arrives, route to the appropriate capability:\n\n| User Intent | Route To | Action |\n|-------------|----------|--------|\n| \"Analyze this paper\" / \"What strategies does this use\" | **paper2spec** | Run `scripts/analyze.py`, read spec.md |\n| \"Search for papers about X\" | **paper2spec** | Run `scripts/search.py` |\n| \"Generate code for this strategy\" / \"Implement this\" | **spec2code** | Read spec.json → generate code → validate → run |\n| \"Run a backtest\" / \"Test this strategy\" | **spec2code** | Run strategy.py directly |\n| \"Take this paper end to end\" | **both** | paper2spec → spec2code pipeline |\n| \"Compare results with the paper\" | **spec2code** | Read backtest output + spec, compare natively |\n\n### Full Pipeline Agent Flow\n\n```\n1. Receive PDF from user\n2. [paper2spec] Parse and extract specs\n → Read references/paper2spec.md for details\n3. Present extracted strategies to user for review\n4. User selects strategy (or all)\n5. [spec2code] For each selected strategy:\n a. Read spec.json + references/backtrader_patterns.md + indicator_cookbook.md\n b. Generate self-contained strategy.py (data + signal + backtest in one file)\n c. Validate with: uv run python scripts/validate_strategy.py strategy.py\n d. Run directly: uv run python strategy.py\n e. Read stdout/stderr, compare metrics vs spec's expected_performance\n → Read references/spec2code.md for details\n6. Present results and diagnosis to user\n```\n\n### Library Management\n\n```\nlibrary/\n├── pairs_trading/\n│ ├── paper.pdf # Original PDF (auto-copied)\n│ ├── content.json, content.md, spec.json, spec.md\n│ ├── strategy_1.py # Generated code (self-contained)\n│ └── metadata.json\n├── momentum_crashes/\n│ └── ...\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (spec2code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to the spec2code workflow:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Agent reads this spec dict and generates Backtrader code\n```\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `PAPER2SPEC_INIT_VERSION` | — | Setup completion marker |\n| `OPENAI_API_KEY` | — | OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | arXiv rate limiting (seconds) |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Paper2Spec Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval) |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/validate_strategy.py` — Validate Generated Code\n\n```\nuv run python scripts/validate_strategy.py \n```\n\nChecks: syntax (AST parse), backtrader import, Strategy class definition,\ncerebro runner, `__main__` guard.\n\n### Other Scripts\n\n| Script | Description |\n|--------|-------------|\n| `scripts/parse.py` | PDF → PaperContent (standalone parsing) |\n| `scripts/extract.py` | PaperContent → ExtractionResult (standalone extraction) |\n| `scripts/search.py` | Academic paper search (arXiv + SSRN) |\n\n## Project Structure\n\n```\npaper2spec/ # PDF → structured spec\n├── models.py # PaperContent, StrategySpec, ExtractionResult\n├── parser.py # PDF → PaperContent\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py, llm.py, prompts.py, search.py, pdf_utils.py\n\nspec2code/ # Tools for agent-driven code generation\n├── models.py # CodeModules, ValidationResult, BacktestMetrics, etc.\n├── validator.py # AST + structural validation (agent tool)\n├── config.py # Shared config (reuses paper2spec .env)\n\nscripts/ # CLI entry points\n├── analyze.py # Full paper2spec pipeline\n├── parse.py, extract.py, search.py\n├── validate_strategy.py # Code validation CLI\n\nreferences/ # Deep-dive documentation (read on demand)\n├── paper2spec.md # Paper2spec detailed guide\n├── spec2code.md # Spec2code agent workflow + code generation guidance\n├── backtrader_patterns.md # Common Backtrader code patterns\n├── indicator_cookbook.md # Indicator implementations\n├── data_sources.md # yfinance/akshare API reference\n```\n\n## Technical References\n\nFor detailed implementation guidance, read on demand:\n\n- [references/paper2spec.md](references/paper2spec.md) — Paper2spec internals, parser modes, multi-strategy detection\n- [references/spec2code.md](references/spec2code.md) — Spec2code agent workflow, code generation guidance, output patterns\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing, cerebro runner\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in indicators, custom indicators, signal patterns\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API reference\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars. |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Requires `uv sync --extra agent`. |\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. Detection rules (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n }\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Spec2code**: Agent-driven only — no fully automatic CLI pipeline. The agent\n generates code, runs it, and analyzes results interactively.\n"}, "b3975d6f01c1216b80a47ffc20b21bf1c9c4a0c8": {"t": 1785750092.264052, "n": 8553, "h": "4c108c293dc7a3ed", "c": "---\nname: quant-paper2code\ndescription: >\n End-to-end pipeline: quantitative finance research paper (PDF) →\n structured strategy specification → executable Backtrader code →\n backtest → diagnosis report. Two capabilities: (1) paper2spec extracts\n multi-strategy specs from PDFs via 5-layer LLM extraction, and\n (2) spec2code generates validated, runnable backtest code from specs, \n executes it locally, and compares results against paper-reported metrics.\n Use this skill when the user wants to analyze a quant paper, extract\n trading strategies from a PDF, generate executable strategy code,\n run a backtest, or go end-to-end from paper to results. Covers any\n request about parsing finance research, building strategy specifications,\n implementing strategies as code, or validating backtest performance.\nmetadata:\n version: 0.4.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]\n---\n\n# quant-paper2code\n\nResearch paper → Strategy spec → Executable code → Backtest → Diagnosis.\nEnd-to-end quantitative strategy implementation from academic papers.\n\n## Capabilities\n\n| Capability | Description | Reference |\n|-----------|-------------|-----------|\n| **paper2spec** | PDF → structured strategy specification (multi-strategy detection, JSON + Markdown) | [references/paper2spec.md](references/paper2spec.md) |\n| **spec2code** | Specification → validated Backtrader code → local backtest → diagnosis report | [references/spec2code.md](references/spec2code.md) |\n\n## First-Run Setup\n\nOn first use, walk the user through these steps. Skip any already configured.\nPersist choices in `.env`.\n\n### Step 1: Workspace Location\n\nAsk where to store PDFs and results. Default: `./library/`.\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n```\n\n### Step 2: LLM API Key\n\nCheck for existing keys (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).\nIf none found, ask the user:\n\n```\nNo LLM API key detected. This skill needs one for extraction and code generation.\n\nRecommended: DeepSeek (~$0.01 per paper)\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key and tell me which provider:\n```\n\nWrite to `.env` (gitignored). Verify with:\n\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\n```bash\ncd \n\n# Install all dependencies\nuv sync --extra codegen # Core + backtrader/yfinance/akshare\nuv sync --extra agent # + FAISS/embeddings for long papers\nuv sync --extra dev # + pytest\n\n# Or minimal (paper2spec only)\nuv sync\n```\n\nAlways use `uv run` to execute scripts.\n\n### Persistent Config (.env)\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\nSPEC2CODE_BACKTEST_TIMEOUT=300\nPAPER2SPEC_INIT_VERSION=1\n```\n\n## Quick Start\n\n### End-to-End: Paper → Spec → Code → Backtest\n\n```bash\n# Step 1: Analyze paper → extract specs\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n\n# Step 2: Generate code from spec (agent-driven or CLI)\nuv run python scripts/generate.py library/my_paper/spec.json --strategy-index 0\n\n# Step 3: Validate code\nuv run python scripts/validate_strategy.py library/my_paper/strategy.py\n\n# Step 4: Run backtest\nuv run python scripts/backtest.py library/my_paper/strategy.py -o library/my_paper/results/\n```\n\n### Paper2Spec Only\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n# → content.json, content.md, spec.json, spec.md, metadata.json\n```\n\n### Spec2Code Only\n\n```bash\nuv run python scripts/generate.py library/my_paper/spec.json --strategy-index 0\n# → strategy.py, validation report, backtest results, diagnosis report\n```\n\n## Agent Workflow\n\n### User-Facing Interaction Policy\n\n- Commands and scripts are internal implementation details.\n- Present capabilities to users as agent actions, not raw CLI commands.\n- Run tools internally, report outcomes and findings.\n- Show exact commands only when the user asks for reproducibility.\n\n### Routing Logic\n\nWhen the user's request arrives, route to the appropriate capability:\n\n| User Intent | Route To | Action |\n|-------------|----------|--------|\n| \"Analyze this paper\" / \"What strategies does this use\" | **paper2spec** | Run `scripts/analyze.py`, read spec.md |\n| \"Search for papers about X\" | **paper2spec** | Run `scripts/search.py` |\n| \"Generate code for this strategy\" / \"Implement this\" | **spec2code** | Generate code using LLM + validate + execute |\n| \"Run a backtest\" / \"Test this strategy\" | **spec2code** | Run `scripts/backtest.py` |\n| \"Take this paper end to end\" | **both** | paper2spec → spec2code pipeline |\n| \"Compare results with the paper\" | **spec2code** | Run analyzer/diagnosis |\n\n### Full Pipeline Agent Flow\n\n```\n1. Receive PDF from user\n2. [paper2spec] Parse and extract specs\n → Read references/paper2spec.md for details\n3. Present extracted strategies to user for review\n4. User selects strategy (or all)\n5. [spec2code] For each selected strategy:\n a. Generate data module → signal module → backtest module\n b. Integrate into single script\n c. Validate (AST + structural checks)\n d. Execute backtest (subprocess, timeout-guarded)\n e. Diagnose: compare metrics vs paper\n → Read references/spec2code.md for details\n6. Present diagnosis report to user\n```\n\n### Library Management\n\n```\nlibrary/\n├── pairs_trading/\n│ ├── paper.pdf, content.json, spec.json, spec.md\n│ ├── strategy_0.py # Generated code\n│ ├── results/ # Backtest outputs\n│ └── metadata.json\n├── momentum_crashes/\n│ └── ...\n```\n\nBefore analyzing a new paper, check for existing entries in `library/`.\nUse descriptive slugs for directories.\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `PAPER2SPEC_INIT_VERSION` | — | Setup completion marker |\n| `SPEC2CODE_BACKTEST_TIMEOUT` | `300` | Backtest timeout (seconds) |\n| `SPEC2CODE_DATA_CACHE` | `/data_cache` | Data download cache |\n| `OPENAI_API_KEY` | — | OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | arXiv rate limiting (seconds) |\n\n## Project Structure\n\n```\npaper2spec/ # PDF → structured spec\n├── models.py # PaperContent, StrategySpec, ExtractionResult\n├── parser.py # PDF → PaperContent\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py, llm.py, prompts.py, search.py, pdf_utils.py\n\nspec2code/ # Spec → executable code → backtest → diagnosis\n├── models.py # CodeModules, BacktestResult, DiagnosisReport\n├── prompts.py # Data/Signal/Backtest/Integration templates\n├── validator.py # AST + structural validation\n├── executor.py # Subprocess-based backtest execution\n├── analyzer.py # Result comparison + report\n\nscripts/ # CLI entry points\n├── analyze.py # Full paper2spec pipeline\n├── parse.py # PDF → PaperContent\n├── extract.py # PaperContent → ExtractionResult\n├── search.py # Academic paper search\n├── generate.py # Full spec2code pipeline\n├── validate_strategy.py # Code validation\n├── backtest.py # Backtest execution\n\nreferences/ # Deep-dive documentation (read on demand)\n├── paper2spec.md # Paper2spec detailed guide\n├── spec2code.md # Spec2code detailed guide\n├── backtrader_patterns.md # Common Backtrader code patterns\n├── indicator_cookbook.md # Indicator implementations\n├── data_sources.md # yfinance/akshare API reference\n```\n\n## Technical References\n\nFor detailed implementation guidance, read on demand:\n\n- [references/paper2spec.md](references/paper2spec.md) — Paper2spec internals, parser modes, multi-strategy detection\n- [references/spec2code.md](references/spec2code.md) — Spec2code agent workflow, output formats, diagnosis\n- [references/backtrader_patterns.md](references/backtrader_patterns.md) — Strategy class, data loading, position sizing, cerebro runner\n- [references/indicator_cookbook.md](references/indicator_cookbook.md) — Built-in indicators, custom indicators, signal patterns\n- [references/data_sources.md](references/data_sources.md) — yfinance, akshare, FRED API reference\n"}, "ef75eecb292aaf0669a7a4f26d76a249a9ca38f2": {"t": 1785750093.3870735, "n": 16458, "h": "d389cda320e990fa", "c": "---\nname: quant-paper-reader\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nmetadata:\n version: 0.3.0\n author: ALAGENT AI (alagent-ai)\n tags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nPrefer absolute paths so custom user directories remain stable regardless of\ncurrent working directory.\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\nPAPER2SPEC_INIT_VERSION=1\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\nPAPER2SPEC_INIT_VERSION=1\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\nInitialization completion policy:\n- `PAPER2SPEC_INIT_VERSION` is a quick marker (recommended value: `1`).\n- Do not trust marker alone. Always verify runtime capability:\n `PAPER2SPEC_LIBRARY_PATH`, `PAPER2SPEC_MODEL`, and at least one provider API key.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\n### User-Facing Interaction Policy\n\n- Commands and scripts in this skill are internal implementation details.\n- In user conversations, present these as agent capabilities (search, parse,\n extract, summarize, compare) rather than exposing raw command sequences by default.\n- Run tools internally, then report outcomes, key findings, and next actions.\n- Show exact commands only when the user explicitly asks for reproducibility,\n debugging, or CLI instructions.\n- Combine this skill with broader agent reasoning to resolve ambiguity and\n choose sensible defaults before asking users extra questions.\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\nIf `-o` is not provided, default output is:\n\n```\n//content.json\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root for analyze/parse |\n| `PAPER2SPEC_INIT_VERSION` | — | Optional setup marker (`1` recommended after successful setup) |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Minimum seconds between arXiv API requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry count for search HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}, "4de4e6af30e3bc78d4331ac536b6aba8f0c5782a": {"t": 1785750095.5012527, "n": 15282, "h": "836723ad310452f3", "c": "---\nname: quant-paper-reader\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nversion: 0.3.0\nauthor: ALAGENT AI (alagent-ai)\ntags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=./library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_LIBRARY_PATH=./library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=./library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\nIf `-o` is not provided, default output is:\n\n```\n//content.json\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root for analyze/parse |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Minimum seconds between arXiv API requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry count for search HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}, "5edbe37f019827e56840e9191e985fcb4e35bf1d": {"t": 1785750096.6391108, "n": 14677, "h": "a47e78bf9ea76414", "c": "---\nname: paper2spec\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nversion: 0.3.0\nauthor: ALAGENT AI (alagent-ai)\ntags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Persist choices in the project `.env` so\nfuture runs remain stable across sessions.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\n\nPersist this choice to `.env`:\n\n```\nPAPER2SPEC_LIBRARY_PATH=./library\n```\n\nIf `.env` does not exist, create it from `.env.example` first.\n\nOn every run, scripts should read `PAPER2SPEC_LIBRARY_PATH` as the default\noutput root. This avoids path drift across sessions.\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`,\n`ANTHROPIC_API_KEY`). If none found, guide the user:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n → Set: export DEEPSEEK_API_KEY=\"sk-...\"\n → Set: export PAPER2SPEC_MODEL=\"deepseek/deepseek-chat\"\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n```\n\n**Preferred: write a `.env` file** so keys persist across sessions. The project\nauto-loads `.env` from the project root (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then edit .env with the user's chosen model + API key\n```\n\nThe `.env` file format:\n```\nPAPER2SPEC_LIBRARY_PATH=./library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\n```\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Persistent Config (Environment)\n\nPrimary persistent config is `.env` (gitignored):\n\n```\nPAPER2SPEC_LIBRARY_PATH=./library\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\n```\n\nOn subsequent runs, read `.env` first and skip setup questions for already\nconfigured values.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\nIf `-o` is not provided, default output is:\n\n```\n//content.json\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_LIBRARY_PATH` | `./library` | Default output root for analyze/parse |\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n| `PAPER2SPEC_ARXIV_MIN_INTERVAL` | `3.0` | Minimum seconds between arXiv API requests |\n| `PAPER2SPEC_SEARCH_MAX_RETRIES` | `3` | Retry count for search HTTP 429/5xx |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}, "7aa48546174b83c1bcb688096c9efceedd7bf58f": {"t": 1785750097.9125178, "n": 14568, "h": "d4da64e8de1e2a6f", "c": "---\nname: quant-paper-reader\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nversion: 0.3.0\nauthor: ALAGENT AI (alagent-ai)\ntags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Save choices to `.paper2spec.json` in the\nproject root so future runs remember them.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set in the environment (`DEEPSEEK_API_KEY`,\n`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). If none found, **you must ask the\nuser to provide their API key** before proceeding — do not silently skip\nthis step or assume they will set it later. Prompt the user like this:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n\nPlease paste your API key now (e.g. sk-...) and tell me which provider\nit belongs to (DeepSeek / OpenAI / Anthropic):\n```\n\nWait for the user to reply with their key. Once received, **write it into\na `.env` file** at the project root so the key persists across sessions.\nThe project auto-loads `.env` (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then replace the placeholder values with the user's actual key and model\n```\n\nFor example, if the user provides a DeepSeek key, the `.env` should contain:\n```\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-actualKeyFromUser\n```\n\nIf the user provides an OpenAI key:\n```\nPAPER2SPEC_MODEL=openai/gpt-4o-mini\nOPENAI_API_KEY=sk-actualKeyFromUser\n```\n\n**Important**: Never write a `.env` with placeholder values like `sk-...`.\nAlways wait until you have the real key from the user, then write the file.\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Config File (`.paper2spec.json`)\n\nAfter setup, write this to the project root:\n```json\n{\n \"library_path\": \"./library\",\n \"model\": \"deepseek/deepseek-chat\",\n \"default_parser_mode\": \"auto\"\n}\n```\n\nOn subsequent runs, read this file first and skip setup.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `.//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}, "840b201a98840d1452f95e86e35694822aad8282": {"t": 1785750099.0321097, "n": 13971, "h": "481a9975697864a4", "c": "---\nname: quant-paper-reader\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nversion: 0.3.0\nauthor: ALAGENT AI (alagent-ai)\ntags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Save choices to `.paper2spec.json` in the\nproject root so future runs remember them.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`,\n`ANTHROPIC_API_KEY`). If none found, guide the user:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n → Set: export DEEPSEEK_API_KEY=\"sk-...\"\n → Set: export PAPER2SPEC_MODEL=\"deepseek/deepseek-chat\"\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n```\n\n**Preferred: write a `.env` file** so keys persist across sessions. The project\nauto-loads `.env` from the project root (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then edit .env with the user's chosen model + API key\n```\n\nThe `.env` file format:\n```\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\n```\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Config File (`.paper2spec.json`)\n\nAfter setup, write this to the project root:\n```json\n{\n \"library_path\": \"./library\",\n \"model\": \"deepseek/deepseek-chat\",\n \"default_parser_mode\": \"auto\"\n}\n```\n\nOn subsequent runs, read this file first and skip setup.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `.//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}, "4714ff55a4096cf9af4eb2fdba8228d9f555f301": {"t": 1785750100.2927532, "n": 13963, "h": "8af868f2fdb6be0b", "c": "---\nname: paper2spec\ndescription: >\n Extract structured, executable strategy specifications from quantitative\n finance research papers (PDF). Multi-strategy detection, 5-layer LLM\n extraction, dual-format output (JSON + Markdown). Use this skill whenever\n the user mentions analyzing a quant paper, extracting trading strategies\n from a PDF, understanding what strategies a paper describes, parsing\n academic finance research, or preparing a paper for code generation.\n Also use when the user has a PDF of a trading/investment paper and wants\n to know what's in it, compare strategies across papers, or build a\n library of strategy specifications. Even if they just say \"look at this\n paper\" or \"what strategies does this use\" — this skill handles it.\nversion: 0.3.0\nauthor: ALAGENT AI (alagent-ai)\ntags: [quantitative-finance, paper-parsing, strategy-extraction, research, multi-strategy]\n---\n\n# paper2spec\n\nConvert quantitative finance research papers into structured, machine-readable\nstrategy specifications — with automatic multi-strategy detection.\n\n## What This Skill Does\n\nGiven a **PDF** of a quantitative finance paper, this skill:\n\n1. **Parses** the paper into structured sections (methodology, signal logic,\n data requirements) via dual-mode extraction (direct LLM or FAISS RAG).\n2. **Detects** if the paper contains multiple independent strategies (Layer 0).\n3. **Extracts** a complete specification per strategy through 4 focused LLM\n calls (metadata → indicators → logic pipeline → execution plan).\n4. **Renders** all outputs in dual format: machine-readable JSON +\n human-readable Markdown.\n\nThe output is designed to be directly consumable by code generation agents\n(e.g., for Backtrader, Zipline, or other backtesting frameworks).\n\n## First-Run Setup\n\nOn first use, walk the user through these three steps. Skip any step\nthat's already configured. Save choices to `.paper2spec.json` in the\nproject root so future runs remember them.\n\n### Step 1: Workspace Location\n\nAsk the user where they want to store PDFs and analysis results.\nDefault: `./library/` in the current working directory.\n\n```\nWhere should I store paper analyses?\n 1. ./library/ (default, recommended)\n 2. Custom path\n```\n\nScan the chosen directory for any existing `metadata.json` files to\ndetect previously analyzed papers. Report what's already there.\n\n### Step 2: LLM API Key\n\nCheck if any API key is already set (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`,\n`ANTHROPIC_API_KEY`). If none found, guide the user:\n\n```\nNo LLM API key detected. paper2spec needs one to extract strategies.\n\nRecommended: DeepSeek (best cost-performance ratio for this task)\n → ~$0.01 per paper, API key from https://platform.deepseek.com\n → Set: export DEEPSEEK_API_KEY=\"sk-...\"\n → Set: export PAPER2SPEC_MODEL=\"deepseek/deepseek-chat\"\n\nAlternatives: OpenAI GPT-4o, Anthropic Claude, any litellm-supported model.\n```\n\n**Preferred: write a `.env` file** so keys persist across sessions. The project\nauto-loads `.env` from the project root (gitignored by default):\n\n```bash\ncp .env.example .env\n# Then edit .env with the user's chosen model + API key\n```\n\nThe `.env` file format:\n```\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=sk-...\n```\n\nVerify the key works by running:\n```bash\nuv run python -c \"from paper2spec.llm import chat; print(chat('Say OK'))\" 2>&1 | head -1\n```\n\n### Step 3: Python Environment\n\npaper2spec uses **uv** for dependency management. The project contains a\n`.python-version` (3.11) and `pyproject.toml` — uv handles everything.\n\n```bash\ncd \n\n# Check if already set up\n.venv/bin/python -c \"import paper2spec; print(paper2spec.__version__)\" 2>/dev/null\n\n# If not set up: create venv + install deps (one command)\nuv sync # Core only (Mode A)\nuv sync --extra agent # + FAISS/embeddings (Mode B)\nuv sync --extra dev # + pytest (for testing)\n```\n\n**Running scripts**: Always use `uv run` so the correct venv is activated\nautomatically — no need to manually activate `.venv/`:\n\n```bash\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\nuv run python scripts/search.py \"momentum trading\" -n 5\n```\n\n**Alternative (no uv)**: If `uv` is not available, use pip directly:\n```bash\ncd \npython -m venv .venv && source .venv/bin/activate\npip install -e . # Core (Mode A)\npip install -e \".[agent]\" # + Mode B deps\npip install -e \".[dev]\" # + test deps\n```\n\n### Config File (`.paper2spec.json`)\n\nAfter setup, write this to the project root:\n```json\n{\n \"library_path\": \"./library\",\n \"model\": \"deepseek/deepseek-chat\",\n \"default_parser_mode\": \"auto\"\n}\n```\n\nOn subsequent runs, read this file first and skip setup.\n\n## Quick Start\n\n### One-Shot Analysis (recommended)\n\n```bash\n# Full pipeline: PDF → content (JSON+MD) + spec (JSON+MD) + metadata\nuv run python scripts/analyze.py paper.pdf -o library/my_paper/\n```\n\nThis produces:\n```\nlibrary/my_paper/\n├── paper.pdf # Original PDF (auto-copied for self-contained library)\n├── content.json # PaperContent (machine-readable)\n├── content.md # PaperContent (human-readable)\n├── spec.json # ExtractionResult with all strategies (machine-readable)\n├── spec.md # Strategy summary (human-readable)\n└── metadata.json # Analysis metadata (model, version, pdf_file, etc.)\n```\n\n### Step-by-Step Pipeline\n\n```bash\n# 1. Search for papers (optional)\nuv run python scripts/search.py \"momentum trading strategy\" -n 5\n\n# 2. Parse PDF → PaperContent\nuv run python scripts/parse.py paper.pdf -o content.json\n\n# 3. Extract PaperContent → ExtractionResult (multi-strategy)\nuv run python scripts/extract.py content.json -o spec.json\n```\n\n## Agent Workflow\n\nWhen using this skill as an AI agent, follow this workflow:\n\n### Standard Analysis\n\n```\n1. Run: uv run python scripts/analyze.py -o library//\n2. Read the generated spec.md for a quick summary\n3. Read spec.json for machine-readable details\n```\n\n### Managing Multiple Papers (Library Pattern)\n\nOrganize analyzed papers in a `library/` directory. Each paper gets its own\nsubdirectory with all outputs:\n\n```\nlibrary/\n├── tactical_asset_allocation/\n│ ├── faber_2007.pdf # Original PDF\n│ ├── content.json, content.md # Parsed paper\n│ ├── spec.json, spec.md # Strategy specs\n│ └── metadata.json # Metadata (pdf_file, model, strategies, ...)\n├── pairs_trading/\n│ ├── goncalves_2023.pdf\n│ └── ... (3 strategies detected)\n└── value_momentum/\n ├── asness_2013.pdf\n └── ... (2 strategies detected)\n```\n\nEach directory is **self-contained**: the original PDF is copied in, so the\nlibrary can be moved or shared without losing the source paper. The\n`metadata.json` field `pdf_file` records the filename within the directory.\n\n**Agent guidelines for library management:**\n\n- Before analyzing a new paper, check if `library/` already has an entry\n for it (scan `metadata.json` files for matching titles or `pdf_file`).\n- Use descriptive slugs for directories (e.g., `momentum_crashes` not `paper1`).\n- When the user asks to compare strategies across papers, read the relevant\n `spec.json` files and synthesize.\n- When the user wants to proceed to code generation (Spec2Code), point them\n to the specific `spec.json` path and strategy index.\n- To re-analyze a paper with different settings, the PDF is already in the\n directory — no need to locate the original file again.\n\n### Handing Off to Spec2Code\n\nThe `spec.json` output is designed for downstream code generation. To pass a\nspecific strategy to a Spec2Code agent:\n\n```python\nimport json\nresult = json.load(open(\"library/pairs_trading/spec.json\"))\nstrategy = result[\"strategies\"][0] # Pick strategy by index\n# Pass `strategy` dict to Spec2Code agent\n```\n\n## Scripts Reference\n\n### `scripts/analyze.py` — Full Pipeline (recommended)\n\n```\nuv run python scripts/analyze.py [-o DIR] [--parser-mode builtin|agent] [--model MODEL]\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o, --output-dir` | `.//` | Output directory |\n| `--parser-mode` | `builtin` | `builtin` (fast, <40 pages) or `agent` (FAISS semantic retrieval, for long/dense papers). See **Parser Mode Selection** below. |\n| `--extractor-mode` | `multilayer` | `multilayer` (recommended) or `single` (legacy) |\n| `--model` | env `PAPER2SPEC_MODEL` | Override LLM model |\n\n**Outputs**: `content.json`, `content.md`, `spec.json`, `spec.md`, `metadata.json`\n\n### `scripts/parse.py` — PDF → PaperContent\n\n```\nuv run python scripts/parse.py [--mode builtin|agent] [--model MODEL] [-o FILE]\n```\n\n### `scripts/extract.py` — PaperContent → ExtractionResult\n\n```\nuv run python scripts/extract.py [--mode multilayer|single] [--model MODEL] [-o FILE]\n```\n\n### `scripts/search.py` — Academic Paper Search\n\n```\nuv run python scripts/search.py [--sources arxiv ssrn] [-n 10] [-o FILE]\n```\n\n## Output Formats\n\n### ExtractionResult (from extract.py / analyze.py)\n\n```json\n{\n \"paper_title\": \"Pairs Trading: Does Volatility Timing Matter?\",\n \"num_detected\": 3,\n \"strategies\": [\n {\n \"strategy_name\": \"Minimum Distance Pairs Trading\",\n \"strategy_type\": \"technical\",\n \"asset_class\": [\"equity\"],\n \"description\": \"...\",\n \"indicators\": [...],\n \"logic_pipeline\": [...],\n \"execution_plan\": [...],\n \"risk_management\": [...]\n },\n ...\n ]\n}\n```\n\n### PaperContent (from parse.py / analyze.py)\n\n```json\n{\n \"title\": \"...\",\n \"abstract\": \"...\",\n \"methodology\": \"...\",\n \"data_description\": \"...\",\n \"signal_logic\": \"...\",\n \"full_text\": \"...\"\n}\n```\n\n### Markdown Outputs\n\n`spec.md` renders each strategy with tables for indicators, numbered logic\nsteps, execution plans, and risk rules — designed for quick human review.\n\n`content.md` renders the parsed paper sections for verifying extraction quality.\n\n## Parser Mode Selection\n\nThe parser has two modes. **Do not ask the user to choose** — pick\nautomatically based on paper length, and explain your choice:\n\n| Condition | Mode | Reason |\n|-----------|------|--------|\n| PDF ≤ 60 pages | `builtin` (Mode A) | Fast. 100K char threshold covers ~33 pages of markdown-extracted text without truncation. 3 parallel LLM calls. |\n| PDF 60-100 pages | `builtin` (Mode A) | Still works — truncation keeps first 90K + last 10K chars, covering methodology (front) + results (back). |\n| PDF > 100 pages, or user reports missing content | `agent` (Mode B) | FAISS semantic retrieval. Chunks text (1500/200), embeds with bge-small-en, retrieves top-k per query. Requires `pip install paper2spec[agent]`. |\n\n**How Mode A works**: Extracts full PDF text → if >100K chars, takes first\n90K + last 10K (skips middle). Sends 3 parallel LLM prompts (methodology,\ndata description, signal logic) each with the full context window.\n\n**How Mode B works**: Extracts full PDF text → chunks at 1500 chars /\n200 overlap → builds FAISS index with bge-small-en-v1.5 embeddings →\nfor each section, runs 5 semantic queries to retrieve the most relevant\nchunks → sends retrieved chunks (not full text) to LLM. Better recall\nfor buried details in very long papers, but slower (embedding + retrieval\noverhead) and requires ~500MB extra dependencies.\n\n**Rule of thumb**: Mode A works for 95% of papers. Only switch to Mode B\nif the user says \"the spec is missing something I can see in the paper\"\nor the PDF is genuinely book-length (>100 pages).\n\n## Multi-Strategy Detection\n\nThe extractor automatically detects when a paper contains multiple independent\nstrategies. For example:\n\n| Paper | Strategies Detected |\n|-------|-------------------|\n| Tactical Asset Allocation (Faber) | 1: GTAA with SMA timing |\n| Pairs Trading (Goncalves-Pinto et al.) | 3: Distance, Stationarity (ADF), Cointegration (Johansen) |\n| Value and Momentum Everywhere (Asness et al.) | 2: Value Factor, Momentum Factor |\n\n**Detection rules** (conservative — false splits are worse than missing a split):\n- Parameter variations (3-month vs 12-month) → same strategy\n- Long-only vs long-short variants → same strategy, different execution plans\n- Fundamentally different signal logic → separate strategies\n\n## Configuration\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `PAPER2SPEC_MODEL` | `openai/gpt-4o-mini` | Default LLM model |\n| `OPENAI_API_KEY` | — | For OpenAI / OpenRouter models |\n| `DEEPSEEK_API_KEY` | — | For DeepSeek models |\n| `ANTHROPIC_API_KEY` | — | For Anthropic models |\n\nAny [litellm-supported model](https://docs.litellm.ai/docs/providers) works.\nThe `--model` flag on any script overrides `PAPER2SPEC_MODEL`.\n\n## Project Structure\n\n```\npaper2spec/\n├── __init__.py # v0.3.0\n├── models.py # PaperContent, StrategySpec, ExtractionResult, StrategyBrief\n├── parser.py # PDF → PaperContent (Mode A: builtin, Mode B: FAISS)\n├── extractor.py # PaperContent → ExtractionResult (Layer 0-4)\n├── render.py # JSON → Markdown renderers\n├── pdf_utils.py # Hybrid PDF extraction (pymupdf4llm + fitz)\n├── llm.py # litellm wrapper\n├── prompts.py # Layer 0-4 prompt templates\n└── search.py # arXiv + SSRN search\nscripts/\n├── analyze.py # Full pipeline: PDF → all outputs\n├── parse.py # CLI: parse PDF\n├── extract.py # CLI: extract spec\n├── search.py # CLI: search papers\n└── generate_schemas.py\nschemas/\n├── paper_content.schema.json\n└── strategy_spec.schema.json\nexamples/ # Pre-generated outputs for reference\n```\n\n## Limitations\n\n- **Mode A** (builtin): Truncates to first 90K + last 10K chars when text exceeds 100K.\n For very long papers (>100 pages), use `--parser-mode agent`.\n- **SSRN search**: Best-effort HTML scraping — may break if SSRN changes layout.\n- **Tables/formulas**: Not yet extracted (reserved fields in PaperContent).\n- **Multi-strategy**: Conservative detector — may merge borderline-distinct strategies.\n"}}, ".env.example": {"e9cd907da492cde5cc5c4e70c78c71e78b288d4f": {"t": 1785747423.4901512, "n": 1082, "h": "a3e71ceed2af4395", "c": "# x2strategy — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n\n# ── Init Marker ──\n# Set after first successful setup. Agent can use this as a quick signal,\n# but should still verify required keys/path at runtime.\nPAPER2SPEC_INIT_VERSION=1\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENROUTER_API_KEY=sk-or-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n\n# ── Spec2Code Settings ──\n# SPEC2CODE_BACKTEST_TIMEOUT=300\n# SPEC2CODE_DATA_CACHE=/absolute/path/to/data_cache\n"}, "273ace853c0e583fccb2697bacad54cbfb369d1a": {"t": 1785750074.312591, "n": 1082, "h": "a3e71ceed2af4395", "c": "# x2strategy — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n\n# ── Init Marker ──\n# Set after first successful setup. Agent can use this as a quick signal,\n# but should still verify required keys/path at runtime.\nPAPER2SPEC_INIT_VERSION=1\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENROUTER_API_KEY=sk-or-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n\n# ── Spec2Code Settings ──\n# SPEC2CODE_BACKTEST_TIMEOUT=300\n# SPEC2CODE_DATA_CACHE=/absolute/path/to/data_cache\n"}, "d0f28e62c42990b0a2e39ab197bd606f0d09ea89": {"t": 1785750076.1444495, "n": 1051, "h": "29c908fdcc344073", "c": "# x2strategy — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n\n# ── Init Marker ──\n# Set after first successful setup. Agent can use this as a quick signal,\n# but should still verify required keys/path at runtime.\nPAPER2SPEC_INIT_VERSION=1\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n\n# ── Spec2Code Settings ──\n# SPEC2CODE_BACKTEST_TIMEOUT=300\n# SPEC2CODE_DATA_CACHE=/absolute/path/to/data_cache\n"}, "b3975d6f01c1216b80a47ffc20b21bf1c9c4a0c8": {"t": 1785750077.534961, "n": 1057, "h": "29d6ccd41b782b87", "c": "# quant-paper2code — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n\n# ── Init Marker ──\n# Set after first successful setup. Agent can use this as a quick signal,\n# but should still verify required keys/path at runtime.\nPAPER2SPEC_INIT_VERSION=1\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n\n# ── Spec2Code Settings ──\n# SPEC2CODE_BACKTEST_TIMEOUT=300\n# SPEC2CODE_DATA_CACHE=/absolute/path/to/data_cache\n"}, "ef75eecb292aaf0669a7a4f26d76a249a9ca38f2": {"t": 1785750078.7907126, "n": 938, "h": "1b80c59ef53067c4", "c": "# paper2spec — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=/absolute/path/to/library\n\n# ── Init Marker ──\n# Set after first successful setup. Agent can use this as a quick signal,\n# but should still verify required keys/path at runtime.\nPAPER2SPEC_INIT_VERSION=1\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n"}, "5edbe37f019827e56840e9191e985fcb4e35bf1d": {"t": 1785750082.0983865, "n": 744, "h": "d159c826417d0dba", "c": "# paper2spec — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── Output Library ──\n# Default root used by scripts/analyze.py and scripts/parse.py\nPAPER2SPEC_LIBRARY_PATH=./library\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n\n# ── Optional: Search Tuning (429/5xx resilience) ──\n# PAPER2SPEC_ARXIV_MIN_INTERVAL=3.0\n# PAPER2SPEC_SEARCH_MAX_RETRIES=3\n# PAPER2SPEC_SEARCH_TIMEOUT_SECONDS=30\n"}, "4714ff55a4096cf9af4eb2fdba8228d9f555f301": {"t": 1785750083.2064364, "n": 460, "h": "3fd5a76526bf0a9f", "c": "# paper2spec — Environment Configuration\n# Copy this file to .env and fill in your values.\n# The .env file is gitignored and loaded automatically.\n\n# ── LLM Model ──\nPAPER2SPEC_MODEL=deepseek/deepseek-chat\n\n# ── API Keys (set the one matching your model provider) ──\nDEEPSEEK_API_KEY=sk-...\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n\n# ── Optional: Custom OpenAI-compatible endpoint (e.g. local vLLM) ──\n# OPENAI_API_BASE=http://localhost:8000/v1\n"}}}}