quantskills/agent-quantspace/report

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

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

Complete research archive

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:

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 sidecar files written by scripts/run_strategy_reports, not by write_research_bundle.

Dashboard preview

from skills.report import ReportRenderer, charts
renderer = ReportRenderer()
ranking_png = charts.plot_factor_ranking(ranking_df, value_col="IC_IR")
html = renderer.render(
    "factor_report",
    {
        "title": "Macro universe — weekly factor screen",
        "namespace": "macro_weekly",
        "n": 5,
        "as_of": "2026-05-08",
        "ranking_chart": ranking_png,
        "ranking_html": ranking_df.to_html(),
    },
)
path = renderer.save(html, "macro_weekly_2026-05-08.html")

Pass a template name with or without .html. Relative output paths resolve against reports/; absolute paths are respected as-is.

Available charts

All helpers return bytes (PNG). The headless Agg backend is pinned at import time so reports render without a display.

Importing skills.report.charts (or calling charts.configure_cjk_matplotlib()) selects a system Han font so Chinese titles in PNG files render on macOS (PingFang / Hiragino Sans GB), Windows (Microsoft YaHei / SimHei from %WINDIR%\\Fonts), and Linux (Noto / Source Han / WenQuanYi). On Windows the file is registered with fontManager.addfont and applied by file path, not by font name alone — that is what makes msyh.ttc work with matplotlib. Custom figures should go through charts.fig_to_png(fig) instead of savefig. If no CJK font is installed (for example an English Windows image without the Chinese language pack), charts still save; glyphs may fall back to boxes.

Windows and paths

• Write HTML/JSON/CSV as UTF-8 with \n newlines. Catalog reads tolerate

a UTF-8 BOM (utf-8-sig).

• Study directories use pathlib.Path (reports_root / namespace / slug).
• Catalog href values are POSIX (namespace/slug/index.html) so they work

in browsers on Windows.

Template conventions

• Inline CSS only — reports must render standalone without external assets.
• Header band uses #4f81bd; table header background #f4f4f4.
• Body font stack includes PingFang / YaHei / Noto so HTML Chinese is visible

on macOS and Windows.

• Every HTML report includes a relative link back to catalog.html

(../../catalog.html from namespace/slug/index.html).

• Optional chart blocks are wrapped in {% if chart %} … {% endif %}.
• Safe-render pre-built tables via {{ table.html | safe }}.

CLI command reference

<!-- BEGIN GENERATED: qs commands -->

Transport: --input-json FILE|-, --preview N, and --log-level LEVEL; flags override JSON. Use --print-template [FIELD] for fillable templates.

uv run qs report list

List research studies that have index.html and params.json.

Priority: P0. Side effects: read-only.

Output data fields: reports_root, count, studies.

Inspect schemas: uv run qs schema report.list (add --part input|output or --file-field FIELD).

uv run qs report bundle

Write a nine-section HTML research archive with write_research_bundle.

Priority: P1. Side effects: writes-output.