# How to Generate Human-Readable Reports from Semantica

> Generate human-readable reports from Semantica easily. Convert knowledge graph data to HTML, Markdown, JSON, or text using the ReportGenerator class and Jinja2 templates.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Use the `ReportGenerator` class in [`semantica/export/report_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/report_generator.py) to convert exported knowledge graph data into HTML, Markdown, JSON, or plain text using Jinja2 templates and optional Plotly visualizations.**

Semantica is an open-source semantic analysis framework that provides a modular reporting engine for knowledge graph visualization. To generate human-readable reports from Semantica, you chain data exporters with the `ReportGenerator` class, which renders the final output using template-based formatting. This guide details the implementation patterns and source file locations within the `semantica-agi/semantica` repository.

## Understanding the Report Architecture

Semantica implements a two-stage pipeline for report creation: **data export** followed by **document generation**. This separation allows the same underlying knowledge graph to be rendered in multiple human-readable formats without code duplication.

### The Export Layer

The first stage uses specialized exporter classes located in `semantica/export/` to transform internal graph objects into serializable Python dictionaries. Each exporter implements an `export` method that returns a standardized payload containing entities, relationships, and metadata. Available exporters include:

- **`JSONExporter`** – Returns nested dictionaries suitable for web APIs and JavaScript consumption.
- **`CSVExporter`** – Flattens graph data into tabular structures for spreadsheet analysis.
- **`RDFExporter`** – Generates semantic triples for linked data applications.
- **`ParquetExporter`** – Creates columnar storage formats for big data pipelines.

### The ReportGenerator Class

The second stage is handled by **`ReportGenerator`** in [`semantica/export/report_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/report_generator.py). This class receives the exported payload via its `generate_report` method and applies format-specific rendering logic. The method signature accepts parameters including `format` (specifying HTML, markdown, json, or text), `output_path` for file destination, and `include_charts` for toggling visualization embedding.

## Step-by-Step Report Generation

Follow this workflow to create reports from any populated knowledge graph instance.

### Step 1: Export Your Knowledge Graph

Instantiate your preferred exporter and call the `export` method with your knowledge graph object `kg`.

```python
from semantica.export import JSONExporter

exporter = JSONExporter()
payload = exporter.export(kg)  # Returns a serializable dict

```

### Step 2: Configure the ReportGenerator

Initialize `ReportGenerator` with your desired output format. The constructor reads configuration options from `ReportConfig` (defined in [`semantica/export/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/config.py)), allowing you to set defaults for chart inclusion and output directories.

```python
from semantica.export import ReportGenerator

generator = ReportGenerator(
    format="html",        # Options: "html", "markdown", "json", "text"

    include_charts=True   # Embeds Plotly interactive charts in HTML output

)

```

### Step 3: Generate the Final Output

Call `generate_report` with the exported payload and destination path. For HTML and Markdown formats, the generator uses Jinja2 templates stored in `semantica/export/templates/` to render the document structure.

```python
generator.generate_report(
    payload,
    output_path="outputs/knowledge_graph_report.html"
)

```

## Supported Output Formats and Templates

The `ReportGenerator` supports four distinct human-readable formats, each optimized for specific consumption contexts.

### HTML Reports with Interactive Charts

When `format="html"`, the generator loads Jinja2 templates from the templates directory and embeds Plotly JavaScript visualizations if `include_charts=True`. This produces standalone `.html` files viewable in any browser, suitable for stakeholder presentations and dashboard integration.

### Markdown for Documentation Pipelines

Setting `format="markdown"` generates syntax-compatible files for GitHub, GitLab, or static site generators. The templates preserve hierarchical heading structures based on graph ontology depth, making them ideal for README files and technical documentation. Chart generation defaults to static images or ASCII representations when `include_charts=False`.

### JSON and Plain Text for APIs

The `json` and `text` formats bypass template rendering in favor of direct serialization. JSON output uses pretty-printing with configurable indentation, while text mode generates human-readable ASCII tables and bullet lists suitable for terminal display or log files.

## Configuration and Customization

Report behavior is controlled through the **`ReportConfig`** class in [`semantica/export/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/config.py). Key configuration options include:

- **`include_charts`** – Boolean flag controlling whether Plotly visualizations are embedded in HTML/Markdown outputs.
- **`output_path`** – Default directory or filename prefix for generated reports.
- **`template_dir`** – Override path for custom Jinja2 templates, allowing corporate branding or specialized layouts.

To apply custom configurations, pass a config instance to the `ReportGenerator` constructor or set environment variables read by the config parser.

## CLI Integration and High-Level APIs

End users typically interact with reporting functionality through the Semantica CLI or convenience wrappers in **[`semantica/export/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/methods.py)**. These high-level functions instantiate the appropriate exporter and `ReportGenerator` in a single call, reading format preferences from command-line arguments or configuration files.

Example patterns from [`examples/capability_gap_context_graphs_example.py`](https://github.com/semantica-agi/semantica/blob/main/examples/capability_gap_context_graphs_example.py) and the test suite in [`tests/test_export_module.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_export_module.py) demonstrate how CLI commands ultimately invoke `ReportGenerator` through these helper methods, making report creation a single-line operation for standard use cases.

## Summary

- **`ReportGenerator`** in [`semantica/export/report_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/report_generator.py) is the core class for converting exported graph data into human-readable documents.
- The reporting pipeline requires a two-step process: first export data using classes like `JSONExporter` or `RDFExporter`, then call `generate_report` with your format preference.
- Supported formats include **HTML** (with optional Plotly charts), **Markdown**, **JSON**, and **text**, each using templates or direct serialization as appropriate.
- Configuration is managed through **`ReportConfig`** in [`semantica/export/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/config.py), controlling output paths, chart inclusion, and template directories.
- High-level integrations in [`semantica/export/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/methods.py) and the CLI abstract the exporter-generator chain for common workflows.

## Frequently Asked Questions

### How do I enable charts in my HTML reports?

Set `include_charts=True` when initializing `ReportGenerator` or configure it in `ReportConfig`. This embeds interactive Plotly visualizations using templates from `semantica/export/templates/`. The charts render directly in the browser without external dependencies.

### Can I use custom templates for corporate branding?

Yes. The `ReportGenerator` accepts a custom template directory path through `ReportConfig`. Place your Jinja2 templates in the specified directory following the naming conventions used in the default `semantica/export/templates/` folder, and the generator will prioritize your custom layouts over the built-in defaults.

### Which exporter should I use for API integrations?

Use **`JSONExporter`** for REST API responses because it produces standard JSON structures that JavaScript clients can parse natively. For semantic web applications requiring linked data standards, choose **`RDFExporter`** instead, then pass either payload to `ReportGenerator(format="json")` for pretty-printed output.

### Is it possible to generate reports without writing Python code?

Yes. The Semantica CLI uses helper functions in [`semantica/export/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/methods.py) to expose report generation commands. You can run `semantica export --format html --output report.html` from the terminal, which internally instantiates the appropriate exporter and `ReportGenerator` using your configuration file settings.