How to Generate Human-Readable Reports from Semantica

Use the ReportGenerator class in 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. 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.

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), allowing you to set defaults for chart inclusion and output directories.

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.

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. 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. 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 and the test suite in 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 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, controlling output paths, chart inclusion, and template directories.
• High-level integrations in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}