report
/report
Przygotowuje kompletne raporty badawcze w HTML, dashboardy, pomocnicze wykresy PNG i pliki w katalogu raportów badawczych.
- Autor
- quantskills ↗
- Repozytorium
- agent-quantspace ↗
- Licencja
- GPL-3.0
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 13
- Skrypty
- 6
- Komentarze HTML
- 2
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
GPL-3.0, otwarta.
- 6 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
Skrypty: __init__.py, charts.py, cli.py, fonts.py, renderer.py, research_report.py
Co robi i kiedy
Przygotowuje kompletne raporty badawcze w HTML, dashboardy, pomocnicze wykresy PNG i pliki w katalogu raportów badawczych.
Oryginalny opis (EN)
Use when tasks need complete HTML research reports, HTML dashboards, PNG chart helpers, or files under the research reports directory.
Jak działa
- Two output paths
- Complete research archive
- Agent interpretation before rendering
- Dashboard preview
- Available charts
- Windows and paths
- Template conventions
- CLI command reference
Podgląd SKILL.md
---
name: report
description: Use when tasks need complete HTML research reports, HTML dashboards, PNG chart helpers, or files under the research reports directory.
---
# 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
sidecar files written by `scripts/run_strategy_reports`, not by
`write_research_bundle`.
## Dashboard preview
```python
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
| Function | Returns |
|----------|---------|
| `plot_equity_curve(returns, title)` | Cumulative `(1+r).cumprod()` equity curve |
| `plot_backtest_performance(result_df, title)` | Backtest equity curve plus drawdown |
| `plot_factor_diagnostics(ic_series, ic_stats, group_returns, turnover, title, rolling_ir_window)` | IC, rolling IR, layered NAV, and turnover dashboard |
| `plot_ic_heatmap(ic_df, title)` | RdBu_r symmetric heatmap (rows=factors, cols=periods or other groups) |
| `plot_rolling_pair_correlation(history, title)` | Small-multiple histories from Analyze's tidy rolling factor correlations |
| `plot_horizon_ic(summary, factors, segment)` | Multi-factor Horizon IC term structure |
| `plot_lagged_ic(summary, factors, horizons, segment)` | Four-panel signal-delay decay curves |
| `plot_rebalance_comparison(comparison, segment, selected_days)` | Net Sharpe and turnover by rebalance interval |
| `plot_factor_weight_history(factor_weights, method, start)` | Stacked dynamic factor weights |
| `plot_equity_comparison(equities, start, title)` | Rebased equity curves for multiple combination methods |
| `plot_factor_ranking(ranking_df, value_col, label_col, title, top_n)` | Horizontal bar chart of top factors, colored by sign |
| `plot_regime_states(prices, states, title)` | Price line with colored bands per regime |
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.
| Option | Type / default | Description |
|---|---|---|
| `--reports-root` | `path?` / `null` | Reports root; otherwise QUANTSPACE_REPORTS_ROOT or repository reports/. |
| `--namespace` | `string?` / `null` | Only studies in this namespace. |
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.
| Option | Type / default | Description |
|---|---|---|
| `--namespace` | `string` / `required` | Safe path segment: reports/<namespace>/<slug>/. |
| `--slug` | `string` / `required` | Safe path segment naming the study directory. |
| `--title` | `string` / `required` | Report title. |
| `--question` | `string` / `required` | Testable research question. |
| `--universe` | `list[string]` / `required` | Symbols studied. |
| `--frequency` | `string` / `required` | Bar frequency, e.g. 1d. |
| `--sample-start` | `string` / `required` | Sample start date. |
| `--sample-end` | `string` / `required` | Sample end date. |
| `--in-sample-end` | `string?` / `null` | In-sample end, if split. |
| `--out-of-sample-start` | `string?` / `null` | Out-of-sample start, if split. |
| `--hypothesis` | `string` / `required` | Why the signal might work and what it predicts. |
| `--method-notes` | `list[string]` / `required` | Implementation details. |
| `--execution` | `object` / `required` | Execution conventions such as trade_at, signal_lag, commission, slippage_bp. |
| `--metrics` | `object` / `required` | Metrics read from a backtest result; never invented. |
| `--metrics-source` | `string` / `required` | Where metrics came from, e.g. BacktestResult.metrics. |
| `--figures` | `list[FigureItem]` / `required` | Figures from PNG files; may be empty. |
| `--tables` | `list[TableItem]` / `required` | Evidence tables; may be empty. |
| `--caveats` | `list[string]` / `required` | Weaknesses and confounders. |
| `--next-steps` | `list[string]` / `required` | Concrete follow-up tests. |
| `--reproduce-command` | `string` / `required` | Command that regenerates the evidence. |
| `--visibility` | `private\|public_example` / `private` | private by default; public_example for shared examples. |
| `--domain` | `string` / `` | Strategy domain label. |
| `--kind` | `research\|dashboard\|public_example` / `research` | Study kind. |
| `--tags` | `list[string]` / `factory` | Catalog tags. |
| `--as-of` | `string?` / `null` | As-of date label. |
| `--notes` | `list[string]` / `factory` | Extra notes; robustness notes render in section 7. |
| `--reports-root` | `path?` / `null` | Reports root; otherwise QUANTSPACE_REPORTS_ROOT or repository reports/. |
| `--catalog` | `boolean` / `false` | Also rewrite catalog.html and catalog.json afterwards. |
| `--overwrite` | `boolean` / `false` | Replace an existing study directory. |
Output data fields: `study_dir`, `files`, `catalog`.
Inspect schemas: `uv run qs schema report.bundle` (add `--part input|output` or `--file-field FIELD`).
### `uv run qs report catalog`
Rewrite catalog.html and catalog.json under the reports root.
Priority: P1. Side effects: writes-output.
| Option | Type / default | Description |
|---|---|---|
| `--reports-root` | `path?` / `null` | Reports root; otherwise QUANTSPACE_REPORTS_ROOT or repository reports/. |
Output data fields: `catalog`, `count`.
Inspect schemas: `uv run qs schema report.catalog` (add `--part input|output` or `--file-field FIELD`).
### `uv run qs report chart`
Render one skills.report.charts PNG from a table.
Priority: P1. Side effects: writes-output.
| Option | Type / default | Description |
|---|---|---|
| `--kind` | `equity-curve\|backtest-performance\|factor-ranking\|ic-heatmap\|horizon-ic\|lagged-ic\|factor-weight-history` / `required` | equity-curve: one return column; backtest-performance: a backtest result table; factor-ranking: a factor ranking table; ic-heatmap: factors by periods; horizon-ic and lagged-ic: an ic-surface summary; factor-weight-history: tidy eob/method/factor/weight records, or the wide factor_weights from strategy combine (labelled with params method). |
| `--table` | `path` / `required` | Input CSV or Parquet table. |
| `--column` | `string` / `return` | Return column for equity-curve. |
| `--title` | `string?` / `null` | Chart title; the chart default if omitted. |
| `--params` | `object` / `factory` | Other keyword arguments of the charts function, e.g. factors=[...] for horizon-ic or value_col for factor-ranking. |
| `--output` | `path` / `required` | Destination PNG file. |
| `--overwrite` | `boolean` / `false` | Replace an existing PNG. |
Output data fields: `kind`, `function`, `bytes`.
Inspect schemas: `uv run qs schema report.chart` (add `--part input|output` or `--file-field FIELD`).
<!-- END GENERATED: qs commands -->
Pliki w paczce (13)
- SKILL.md 14 KB
- __init__.py 1 KB
- charts.py 19 KB
- cli.py 13 KB
- fonts.py 9 KB
- renderer.py 4 KB
- research_report.py 15 KB
- templates/backtest_report.html 2 KB
- templates/catalog.html 2 KB
- templates/catalog_nav.html 1 KB
- templates/factor_report.html 2 KB
- templates/research_report.html 5 KB
- templates/signal_digest.html 2 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · quantskills/agent-quantspace | 100 | GPL-3.0 |
| petrbouda/jeffrey | 100 | Apache-2.0 |
| petrbouda/jeffrey | 100 | Apache-2.0 |
| onmax/comark-ui | 100 | MIT |
| renzrollon/interlock | 100 | MIT |
| digital-stoic-org/agent-skills | 100 | MIT |
| 90p-labs/harness | 100 | MIT |
| emaballarin/ccplugins | 100 | MIT |
| magnifito/domain-name-engine | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki b7514726e851 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100report-generator
Generuje raporty PDF i HTML z szablonów i danych: raporty dla klientów, cotygodniowe podsumowania i raporty wyników marketingowych. - 100html-report
Tworzy dopracowane samodzielne dokumenty HTML, takie jak memoranda badawcze, mapy literatury, dashboardy, raporty z audytu i porównania, z renderowaniem wzorów w MathJax i listą kontrolną walidacji. - 100html-research-reports
Syntetyzuje badania z wielu źródeł (kod, historia git, Slack, sieć, MCP) w czytelne raporty HTML: wyjaśnienia pojęć, raporty statusu i incydentów, analizy techniczne i memoranda decyzyjne. - 100report-bundle-builder
Łączy wielostronicowy raport HTML (strona główna, podstrony i obrazy PNG) w trzy produkty końcowe: jeden samodzielny plik HTML, PDF do druku i archiwum oraz XLSX z danymi, dla raportów wielkości rynku chorób. - 100report-generator
Generuje profesjonalne raporty z wykresami, tabelami i wizualizacjami: raporty PDF i HTML oparte na danych, tygodniowe raporty statusu, podsumowania zarządcze i cykliczne aktualizacje zespołu. - 100html-export
Eksportuje strony HTML, decki, makiety i animacje do PNG, wektorowego PDF, MP4 lub GIF przez parametr --to.