HTML output formatter for benchmark results.
Builds a fully self-contained HTML report (inline CSS/JS, no CDN) with customer- facing throughput and latency visualizations, multi-run comparison charts, optional multi-turn breakdowns, and specialty detail tables.
GenerativeBenchmarkerHTML
Bases: GenerativeBenchmarkerOutput
Self-contained HTML report formatter for generative benchmarks.
Embeds compact chart/table JSON into a packaged HTML/CSS/JS template so the resulting file can be shared without network access or versioned UI assets.
Attributes:
| Name | Type | Description |
DEFAULT_FILE | str | Default filename when path is a directory |
Source code in src/guidellm/benchmark/outputs/html.py
| @GenerativeBenchmarkerOutput.register("html")
class GenerativeBenchmarkerHTML(GenerativeBenchmarkerOutput):
"""
Self-contained HTML report formatter for generative benchmarks.
Embeds compact chart/table JSON into a packaged HTML/CSS/JS template so the
resulting file can be shared without network access or versioned UI assets.
:cvar DEFAULT_FILE: Default filename when ``path`` is a directory
"""
DEFAULT_FILE: ClassVar[str] = "benchmarks.html"
output_path: Path = Field(
default_factory=Path.cwd,
description=(
"Directory or file path for saving the HTML report, "
"defaults to current working directory"
),
)
@classmethod
def from_args(cls, args: BenchmarkOutputArgs) -> GenerativeBenchmarkerHTML:
"""
Create an HTML output formatter from output arguments.
:param args: Output configuration with path
:return: Configured HTML output formatter
"""
if not isinstance(args, HTMLBenchmarkOutputArgs):
raise TypeError(f"Expected HTMLBenchmarkOutputArgs, got {type(args)}")
return cls(output_path=args.path)
async def finalize(self, report: GenerativeBenchmarksReport) -> Path:
"""
Generate and save the self-contained HTML benchmark report.
:param report: Completed benchmark report containing all results
:return: Path to the saved HTML report file
"""
output_path = self.output_path
if output_path.is_dir():
output_path = output_path / self.DEFAULT_FILE
output_path.parent.mkdir(parents=True, exist_ok=True)
view = build_report_view(report)
html = render_html_report(view)
output_path.write_text(html, encoding="utf-8")
logger.debug("Saved HTML report to {}", output_path)
return output_path
|
finalize(report) async
Generate and save the self-contained HTML benchmark report.
Parameters:
Returns:
| Type | Description |
Path | Path to the saved HTML report file |
Source code in src/guidellm/benchmark/outputs/html.py
| async def finalize(self, report: GenerativeBenchmarksReport) -> Path:
"""
Generate and save the self-contained HTML benchmark report.
:param report: Completed benchmark report containing all results
:return: Path to the saved HTML report file
"""
output_path = self.output_path
if output_path.is_dir():
output_path = output_path / self.DEFAULT_FILE
output_path.parent.mkdir(parents=True, exist_ok=True)
view = build_report_view(report)
html = render_html_report(view)
output_path.write_text(html, encoding="utf-8")
logger.debug("Saved HTML report to {}", output_path)
return output_path
|
from_args(args) classmethod
Create an HTML output formatter from output arguments.
Parameters:
Returns:
Source code in src/guidellm/benchmark/outputs/html.py
| @classmethod
def from_args(cls, args: BenchmarkOutputArgs) -> GenerativeBenchmarkerHTML:
"""
Create an HTML output formatter from output arguments.
:param args: Output configuration with path
:return: Configured HTML output formatter
"""
if not isinstance(args, HTMLBenchmarkOutputArgs):
raise TypeError(f"Expected HTMLBenchmarkOutputArgs, got {type(args)}")
return cls(output_path=args.path)
|
HTMLBenchmarkOutputArgs
Bases: BenchmarkOutputArgs
Model for HTML benchmark output arguments.
Source code in src/guidellm/schemas/benchmark/outputs/html.py
| @BenchmarkOutputArgs.register("html")
class HTMLBenchmarkOutputArgs(BenchmarkOutputArgs):
"""Model for HTML benchmark output arguments."""
kind: Literal["html"] = Field(
default="html",
description="The kind of output.",
)
path: Path = Field(
default_factory=lambda: settings.default_results_dir / "benchmarks.html",
description="The file to save the output to.",
)
|
build_report_view(report)
Build the compact JSON view embedded in the HTML report.
Parameters:
Returns:
| Type | Description |
dict[str, Any] | Dictionary consumed by the inlined report JavaScript |
Source code in src/guidellm/benchmark/outputs/html.py
| def build_report_view(report: GenerativeBenchmarksReport) -> dict[str, Any]:
"""
Build the compact JSON view embedded in the HTML report.
:param report: Benchmark report to summarize
:return: Dictionary consumed by the inlined report JavaScript
"""
benchmarks = report.benchmarks
runs = [
_build_run_row(benchmark, index) for index, benchmark in enumerate(benchmarks)
]
peak_index = _peak_throughput_index(runs)
peak_run = runs[peak_index] if runs else None
by_turn: list[dict[str, Any]] | None = None
turn_note: str | None = None
turn_agents: list[dict[str, Any]] | None = None
turn_samples: list[dict[str, Any]] | None = None
turn_peak_note: str | None = None
if benchmarks:
source = benchmarks[peak_index]
turn_bundle = _build_metrics_by_turn(source)
if turn_bundle is not None:
by_turn = turn_bundle["rows"]
turn_agents = turn_bundle["turn_agents"]
turn_samples = turn_bundle["turn_samples"]
note_parts: list[str] = []
# Note the default filter only when sub-agents exist (control is shown).
if turn_bundle["has_subagents"]:
note_parts.append(turn_bundle["default_note"])
if len(benchmarks) > 1:
turn_peak_note = (
"Peak-throughput run "
f"(#{peak_index + 1}: "
f"{peak_run['label'] if peak_run else 'n/a'})."
)
note_parts.append(turn_peak_note)
turn_note = " ".join(note_parts) if note_parts else None
header = _build_header(report, runs, peak_index, has_multi_turn=bool(by_turn))
details = _build_details(benchmarks, runs)
return {
"header": header,
"runs": runs,
"by_turn": by_turn,
"turn_note": turn_note,
"turn_agents": turn_agents,
"turn_samples": turn_samples,
"turn_peak_note": turn_peak_note,
"details": details,
}
|
render_html_report(view)
Render the packaged HTML template with report view data.
Parameters:
| Name | Type | Description | Default |
view | dict[str, Any] | Compact report dictionary from :func:build_report_view | required |
Returns:
| Type | Description |
str | Complete HTML document string |
Source code in src/guidellm/benchmark/outputs/html.py
| def render_html_report(view: dict[str, Any]) -> str:
"""
Render the packaged HTML template with report view data.
:param view: Compact report dictionary from :func:`build_report_view`
:return: Complete HTML document string
"""
pkg = files("guidellm.benchmark.outputs.html_report")
template = (pkg / "template.html").read_text(encoding="utf-8")
css = (pkg / "report.css").read_text(encoding="utf-8")
js = (pkg / "report.js").read_text(encoding="utf-8")
payload = json.dumps(view, ensure_ascii=False, allow_nan=False).replace(
"<", "\\u003c"
)
html = (
template.replace("__GUIDELLM_REPORT_CSS__", css)
.replace("__GUIDELLM_REPORT_JS__", js)
.replace("__GUIDELLM_REPORT_JSON__", payload)
.replace(
"__GUIDELLM_STATIC_TABLE__",
_build_static_summary_table(view.get("runs") or []),
)
)
for token, value in _static_text_defaults(view).items():
html = html.replace(token, value)
return html
|