JSON Report Renderer

The JSON Report Renderer is a robust and flexible Python library designed to transform complex data and a declarative JSON configuration into high-quality, structured documents (such as AsciiDoc, with future support for LaTeX and HTML).

It functions as a powerful middleware pipeline, orchestrating the entire reporting workflow:

  1. Data Ingestion: Securely loading and integrating data from diverse external sources (CSV, JSON, raw text files).

  2. Transformation: Applying sophisticated data manipulation using Pandas, including filtering, aggregation, pivoting, and custom preprocessing functions.

  3. Rendering: Utilizing Jinja2 templating to generate a cohesive document, embedding dynamic content nodes like tables, plots, and formatted text.

This approach ensures the separation of data logic from presentation, providing a highly maintainable and adaptable reporting solution.

1. ✨ Features

The JSON Report Engine provides a robust and flexible system for generating professional, data-driven documents.

Declarative and Validated Configuration

  • Single-File Report Definition: Define the entire report structure, content order, and data processing rules using a single, clear JSON configuration file.

  • Guaranteed Structure: The configuration is rigorously checked against a fixed schema, ensuring your report definition is correct and executable before the generation process even begins.

  • Clean Workflow: The reporting logic is kept entirely separate from your raw data and the final document style, leading to highly maintainable and adaptable reports.

Powerful Data Management

  • Multi-Source Data Loading: Easily load and integrate data from various sources, including CSV, JSON, and raw text files, directly into your reporting process.

  • Custom Data Preparation: Use a simple configuration to apply custom Python functions to clean, reshape, or transform your loaded data immediately before it is used in a table or figure.

  • Advanced Data Restructuring: Configure powerful built-in transformations to prepare your data for reporting, including:

  • Filtering data rows based on precise conditions.

  • Calculating summarized values (e.g., averages, sums) by grouping results.

  • Pivoting and reorganizing data for cross-tabulation.

Flexible Output and Content

  • Multi-Format Document Generation: The Engine is built to support various output types, with primary support for generating highly-structured AsciiDoc documents (and future potential for formats like LaTeX and HTML).

  • Dynamic Content Integration: Embed specific calculated values or data points directly into your narrative text using a simple, readable placeholder syntax, ensuring your reports are always up-to-date with the underlying data.

  • Rich Content Nodes: Construct professional reports using a variety of specialized content blocks:

  • Sections: For creating hierarchical document structures.

  • Data Tables: Fully configurable tables with custom sorting, filtering, and style alignment.

  • Figures and Plots: Declarative definitions for all data visualizations.

  • Mathematical Content: Direct inclusion of LaTeX code for complex equations or symbols.

2. ⬇️ Installation

The JSON Report Engine is currently distributed as part of the feelpp-benchmarking Python suite. Installing this package provides access to the engine and all its dependencies, including the necessary data processing libraries.

To install, execute the following command:

pip install feelpp-benchmarking

3. 🚀 Basic Usage

The JSON Report Engine is designed for simple, fast report generation. There are two primary ways to interact with the engine: the command-line interface (CLI) for standalone use, and the Python API for script integration.

💻 CLI (Recommended Standalone Use)

The Command-Line Interface is the easiest way to generate a report from a configuration file.

Run the json-report-render command, specifying your configuration file (REPORT_FILE).

json-report-render REPORT_FILE [OPTIONS]

Options :

Key Option Description Default

REPORT_FILE

The path to the JSON configuration file.

Required

-o, --output-dir

The directory to save the final report.

. (Current directory)

-n, --output-name

A specific filename for the output.

Inferred from REPORT_FILE

-f, --output-format

The format of the final document to be generated. Currently supports: adoc.

adoc

⚙️ Python API

For developers integrating the engine into automated workflows or custom Python environments, the JsonReportController class provides programmatic control.

  1. Initialize the controller with the configuration file path.

  2. Call .render() to execute the pipeline (data loading, transformation, and document generation).

import os
from feelpp.benchmarking.json_report.renderer import JsonReportController

# 1. Paths and Initialization
report_file = "my_report.json"
output_dir = "report_output"

controller = JsonReportController(
    report_filepath=report_file,
    output_format="adoc" # Defaults to "adoc"
)

# 2. Render and output the file
output_path = controller.render(
output_dirpath=output_dir,
    # output_filename=None (auto-named my_report.adoc)
)

print(f"Report generated at: {output_path}")

4. ⚡ Quickstart

This guide shows you how to quickly define a simple report configuration and generate your first AsciiDoc document using the Command-Line Interface (CLI).

4.1. Step 1: Set Up Files

Create a project directory and add the following two files: config.json and data.csv.

my_report_project/
├── config.json
└── data.csv

4.2. Step 2: Create Data Source (data.csv)

This is the sample data your report will read. The engine automatically recognizes this as CSV data.

Scenario,Time_s,Memory_MB
Run A,12.5,1024
Run B,25.1,2048
Run C,15.9,1536

4.3. Step 3: Create Report Configuration (config.json)

This JSON file tells the engine where to find the data ("timings") and how to display it (as a text snippet and a basic formatted table).

{
  "title": "Simple Quickstart Report",
  "data": [
    { "name": "timings", "filepath": "data.csv" }
  ],
  "contents": [
    {
      "type": "text", "ref": "timings",
      "text": "The report analyzes @{timings | length}@ data entries."
    },
    {
      "type":"section",
      "title": "Performance Summary",
      "contents":[
        {
          "type": "table", "ref": "timings",
          "layout": {
            "rename": { "Time_s": "Time (s)" }
          }
        }
      ]
    }
  ]
}

4.4. Step 4: Run the Engine (CLI)

Execute the json-report-render command from your project directory.

json-report-render config.json

4.4.1. Results

The command successfully generates the report, saving your rendered document as ./config.adoc and having the following content:

:docdatetime: 2025-12-05 10:16:21

= Simple Quickstart Report

The report analyzes 3 data entries.

== Performance Summary

--
[cols="<3,<3,<3",options="header"]
|===

|Scenario|Time (s)|Memory_MB
|Run A|12.5|1024
|Run B|25.1|2048
|Run C|15.9|1536

|===
--

5. ⏭️ Next Steps