report

Files (12)

• SKILL.md
• __init__.py
• charts.py
• fonts.py
• renderer.py
• research_report.py
• backtest_report.html · templates/
• catalog.html · templates/
• catalog_nav.html · templates/
• factor_report.html · templates/
• research_report.html · templates/
• signal_digest.html · templates/

SKILL.md (first lines)

# Report Skill

Render research outputs into self-contained HTML using Jinja2 templates and
matplotlib charts. Install with `uv sync --extra report`. Default output uses
`QUANTSPACE_REPORTS_ROOT` when set, otherwise the workspace `reports/` path.

Complete research archives are **HTML only**. Do not write them as Markdown or
PDF. Do not use a database. Other skills must not write HTML; they return
objects, and the caller fills `ResearchReport` then calls
`write_research_bundle`.

## Two output paths

| Path | Entry | Output | Use for |
|------|-------|--------|---------|
| Complete research archive | `ResearchReport` + `write_research_bundle` | `reports/<namespace>/<slug>/index.html` | Takeaway research document, including public examples |
| Dashboard preview | `ReportRenderer` + `factor_report` / `backtest_report` / `signal_digest` | one HTML file | Quick look, not an archive |

Charts are inlined as base64 data URIs via the `png_data_uri` Jinja filter.

## Complete research archive

```python
from skills.report import (
    ReportFigure,
    ReportTable,
    ResearchReport,
    charts,
    write_research_bundle,
    write_research_catalog,
)

equity_png = charts.plot_backtest_performance(result_df, title="Performance")
report = ResearchReport(
    namespace="lesson_09",
    slug="if_ma10_atr",
    title="IF MA10 + ATR",
    question="Does this rule beat buy-and-hold under the stated costs?",
    universe=["CFFEX.IF99"],
    frequency="1d",
    sample_start="2024-01-01",
    sample_end="2026-07-01",
    in_sample_end=None,
    out_of_sample_start=None,
    hypothesis="A short dip below MA10 may revert; a rising ATR trailing stop limits persistent declines. Both effects need comparison tests.",
    method_notes=["Enter below MA10; exit at the entry-to-date high minus 2 ATR(14), using strategies.time_series.rules."],
    execution={
        "trade_at": "close",
        "signal_lag": 1,
        "commission": 0.0002,
        "slippage_bp": 2.0,
        "return_mode": "forward",
    },
    metrics=execution.metrics,  # from VectorBacktester, do not invent numbers
    metrics_source="BacktestResult.metrics",
    figures=[ReportFigure(name="equity", caption="Equity and drawdown", png=equity_png)],
    tables=[],
    caveats=["Single IF contract and sample window; no no-stop comparison yet."],
    next_steps=["Compare the same entry rule without the ATR stop and at higher costs."],
    reproduce_command="uv run python -m strategies.time_series.workflows.run_demo",
    visibility="private",
    domain="time_series",
)
study_dir = write_research_bundle(report)
write_research_catalog()
```

Directory contract:

```text
reports/<namespace>/<slug>/index.html
reports/<namespace>/<slug>/params.json
reports/<namespace>/<slug>/artifacts/metrics.csv   # only when metrics is non-empty
reports/catalog.html
reports/catalog.json
```

`index.html` is the human-readable nine-section report. `params.json` is the
catalog sidecar. `list_research_studies` only accepts folders that have both
files. CSV-only experiment folders are ignored. `write_research_bundle` does
not write the catalog; call `write_research_catalog` after a batch.

Required HTML sections: 研究问题, 数据与样本, 假设与方法, 执行约定,
证据与指标, 图表, 对照与稳健性, 限制与下一步, 复现与产物.
If there is no comparison or robustness evidence, section 7 still renders
`本报告未做`.

## Agent interpretation before rendering

`write_research_bundle` only renders supplied fields. The calling AI agent
must read the strategy implementation, data and actual backtest results before
filling `ResearchReport`; a deterministic report script cannot supply a fresh
AI assessment on each run. In particular:

- State the testable question in `question`; write a distinct `hypothesis` that
  explains why the signal might work, what it predicts, and how positions are
  opened, sized and exited. Put implementation details in `method_notes`.
- Interpret actual metrics against their sample and trading activity; identify
  specific weaknesses, missing comparisons and possible confounders in
  `caveats`. Use `next_steps` for concrete tests that could challenge the
  strategy's explanation. Do not present a hypothesized mechanism as a proven
  source of return or invent an unseen AI analysis.
- Keep a regeneration command in `reproduce_command` only. Do not use the
  same disclaimer and rerun instruction as the analysis for every strategy.
- If a saved report was generated by an older strategy version, interpret its
  recorded method and results; reconcile version differences before rerunning
  or claiming that current code reproduces those numbers.

Hard rules:

- Fill `metrics` from `BacktestResult`, CSV, JSON, or `result_df`. Never invent Sharpe.
- `metrics_source` is required.
- `namespace` and `slug` are safe path segments only.
- Pass `visibility="private"` unless publishing a public example (the Python field is required; `qs report bundle` defaults to `private`). Do not git-add private studies.
- Public examples use `namespace="strategy_examples"`, `visibility="public_example"` and `kind="public_example"`. They still write `reports/<namespace>/<slug>/`.
- Do not import `strategies/` from this skill.
- Do not export PDF.

README gallery PNGs (`strategy_examples/<slug>_performance.png`) are extra

From quantskills/agent-quantspace, GPL-3.0.

More from quantskills/agent-quantspace