Reports - rotalabs-comply
Description: AI compliance and audit logging infrastructure

Skip to content

# Reports Module

Report generation and templates for compliance reporting.

## ReportGenerator

Generator for compliance reports from audit data.

ReportGenerator retrieves audit entries from storage, runs compliance checks against configured frameworks, and produces comprehensive reports.

Attributes:

Name | Type | Description
--- | --- | ---
`storage` |  | Storage backend for retrieving audit entries.
`frameworks` |  | Dictionary mapping framework names to implementations.

Example

> > > from rotalabs_comply.audit.storage import MemoryStorage from rotalabs_comply.frameworks.eu_ai_act import EUAIActFramework

> > > storage = MemoryStorage() frameworks = { ... "eu_ai_act": EUAIActFramework(), ... } generator = ReportGenerator(storage, frameworks)

> > > ## Generate a report

> > > report = await generator.generate( ... period_start=datetime(2026, 1, 1), ... period_end=datetime(2026, 1, 31), ... profile=profile, ... framework="eu_ai_act", ... )

## `__init__(audit_logger, frameworks=None)`

Initialize the report generator.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`audit_logger` | `StorageProtocol` | Storage backend implementing list_entries method. | required
`frameworks` | `Optional[Dict[FrameworkName, ComplianceFramework]]` | Optional dict mapping framework names to implementations. If not provided, compliance checks will be skipped. | `None`

Example

> > > generator = ReportGenerator(storage) generator = ReportGenerator(storage, {"soc2": SOC2Framework()})

## `export_html(report)`

Export report to HTML format.

Creates a standalone HTML document with embedded styles, suitable for viewing in a browser or embedding in web applications.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`report` | `ComplianceReport` | ComplianceReport to export. | required

Returns:

Type | Description
--- | ---
`str` | HTML formatted string.

Example

> > > html = generator.export_html(report) with open("report.html", "w") as f: ... f.write(html)

## `export_json(report)`

Export report to JSON format.

Creates a JSON document with all report data, suitable for programmatic processing or API responses.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`report` | `ComplianceReport` | ComplianceReport to export. | required

Returns:

Type | Description
--- | ---
`str` | JSON formatted string (pretty-printed).

Example

> > > json_str = generator.export_json(report) data = json.loads(json_str) print(data["compliance_score"])

## `export_markdown(report)`

Export report to Markdown format.

Creates a well-formatted Markdown document with proper headings, tables, and structure suitable for documentation or rendering.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`report` | `ComplianceReport` | ComplianceReport to export. | required

Returns:

Type | Description
--- | ---
`str` | Markdown formatted string.

Example

> > > md = generator.export_markdown(report) with open("report.md", "w") as f: ... f.write(md)

## `generate(period_start, period_end, profile, framework=None, format='markdown')` `async`

Generate a comprehensive compliance report.

Retrieves audit entries for the specified period, runs compliance checks, and generates a full report with all standard sections.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`period_start` | `datetime` | Start of the analysis period (inclusive). | required
`period_end` | `datetime` | End of the analysis period (inclusive). | required
`profile` | `ComplianceProfile` | ComplianceProfile defining evaluation parameters. | required
`framework` | `Optional[FrameworkName]` | Specific framework to report on (None = all in profile). | `None`
`format` | `Literal['markdown', 'json', 'html']` | Output format hint (used for template selection). | `'markdown'`

Returns:

Type | Description
--- | ---
`ComplianceReport` | ComplianceReport with all sections populated.

Example

> > > report = await generator.generate( ... period_start=datetime(2026, 1, 1), ... period_end=datetime(2026, 1, 31), ... profile=profile, ... format="markdown", ... ) print(f"Generated: {report.title}") print(f"Entries: {report.total_entries}") print(f"Score: {report.compliance_score:.2%}")

## `generate_executive_summary(period_start, period_end, profile)` `async`

Generate a high-level executive summary report.

Creates a condensed report suitable for executive audiences, focusing on key metrics and critical findings without technical details.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`period_start` | `datetime` | Start of the analysis period. | required
`period_end` | `datetime` | End of the analysis period. | required
`profile` | `ComplianceProfile` | ComplianceProfile defining evaluation parameters. | required

Returns:

Type | Description
--- | ---
`ComplianceReport` | ComplianceReport with executive-focused sections.

Example

> > > report = await generator.generate_executive_summary( ... period_start=datetime(2026, 1, 1), ... period_end=datetime(2026, 3, 31), ... profile=profile, ... ) print(f"Status: {report.status}") print(f"Score: {report.compliance_score:.2%}")

Generator for compliance reports from audit data.

### Constructor

    ReportGenerator(
        audit_logger: StorageProtocol,
        frameworks: Optional[Dict[str, ComplianceFramework]] = None,
    )

Parameters:

Parameter | Type | Description
--- | --- | ---
`audit_logger` | `StorageProtocol` | Storage backend with `list_entries` method
`frameworks` | `Optional[Dict]` | Framework name -> implementation mapping

Example:

    from rotalabs_comply import ReportGenerator
    from rotalabs_comply.audit import MemoryStorage
    from rotalabs_comply.frameworks.eu_ai_act import EUAIActFramework
    from rotalabs_comply.frameworks.soc2 import SOC2Framework

    storage = MemoryStorage()
    generator = ReportGenerator(
        audit_logger=storage,
        frameworks={
            "eu_ai_act": EUAIActFramework(),
            "soc2": SOC2Framework(),
        },
    )

### Methods

#### generate

    async def generate(
        period_start: datetime,
        period_end: datetime,
        profile: ComplianceProfile,
        framework: Optional[str] = None,
        format: Literal["markdown", "json", "html"] = "markdown",
    ) -> ComplianceReport

Generate a comprehensive compliance report.

Parameters:

Parameter | Type | Default | Description
--- | --- | --- | ---
`period_start` | `datetime` | Required | Analysis start (inclusive)
`period_end` | `datetime` | Required | Analysis end (inclusive)
`profile` | `ComplianceProfile` | Required | Evaluation configuration
`framework` | `Optional[str]` | `None` | Specific framework (None=all)
`format` | `str` | `"markdown"` | Output format hint

Returns: `ComplianceReport`

Example:

    from datetime import datetime, timedelta

    end = datetime.utcnow()
    start = end - timedelta(days=30)

    report = await generator.generate(
        period_start=start,
        period_end=end,
        profile=profile,
        framework="eu_ai_act",
    )

#### generate_executive_summary

    async def generate_executive_summary(
        period_start: datetime,
        period_end: datetime,
        profile: ComplianceProfile,
    ) -> ComplianceReport

Generate a condensed executive summary report.

Example:

    report = await generator.generate_executive_summary(
        period_start=start,
        period_end=end,
        profile=profile,
    )

#### export_markdown

    def export_markdown(report: ComplianceReport) -> str

Export report to Markdown format.

Example:

    markdown = generator.export_markdown(report)
    with open("report.md", "w") as f:
        f.write(markdown)

#### export_json

    def export_json(report: ComplianceReport) -> str

Export report to JSON format (pretty-printed).

Example:

    json_str = generator.export_json(report)

#### export_html

    def export_html(report: ComplianceReport) -> str

Export report to standalone HTML format.

Example:

    html = generator.export_html(report)
    with open("report.html", "w") as f:
        f.write(html)

## ComplianceReport

A complete compliance report with all sections and metadata.

ComplianceReport contains the full results of a compliance evaluation, including all sections, summary statistics, and compliance scoring.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `str` | Unique identifier for this report.
`title` | `str` | Report title.
`framework` | `Optional[FrameworkName]` | Framework evaluated (None for multi-framework reports).
`period_start` | `datetime` | Start of the analysis period.
`period_end` | `datetime` | End of the analysis period.
`generated_at` | `datetime` | When the report was generated.
`profile` | `ComplianceProfile` | ComplianceProfile used for evaluation.
`summary` | `Dict[str, Any]` | Summary statistics dictionary.
`sections` | `List[ReportSection]` | List of report sections.
`total_entries` | `int` | Total audit entries analyzed.
`violations_count` | `int` | Number of violations found.
`compliance_score` | `float` | Overall compliance score (0.0 to 1.0).
`status` | `Literal['compliant', 'non_compliant', 'needs_review']` | Overall compliance status.

Example

> > > report = ComplianceReport( ... id="rpt-001", ... title="Q1 2026 Compliance Report", ... framework=None, # Multi-framework ... period_start=datetime(2026, 1, 1), ... period_end=datetime(2026, 3, 31), ... generated_at=datetime.utcnow(), ... profile=profile, ... summary={"total": 10000, "violations": 5}, ... sections=[executive_summary, risk_assessment], ... total_entries=10000, ... violations_count=5, ... compliance_score=0.9995, ... status="compliant", ... ) print(f"Compliance: {report.compliance_score:.2%}") Compliance: 99.95%

## `to_dict()`

Convert report to dictionary for serialization.

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dict containing all report data.

Example

> > > data = report.to_dict() print(data["status"]) 'compliant'

A complete compliance report with all sections and metadata.

Attributes:

Attribute | Type | Description
--- | --- | ---
`id` | `str` | Unique report identifier
`title` | `str` | Report title
`framework` | `Optional[str]` | Framework evaluated (None=multiple)
`period_start` | `datetime` | Analysis period start
`period_end` | `datetime` | Analysis period end
`generated_at` | `datetime` | When report was generated
`profile` | `ComplianceProfile` | Profile used for evaluation
`summary` | `Dict[str, Any]` | Summary statistics
`sections` | `List[ReportSection]` | Report sections
`total_entries` | `int` | Entries analyzed
`violations_count` | `int` | Violations found
`compliance_score` | `float` | Score 0.0-1.0
`status` | `str` | "compliant", "non_compliant", "needs_review"

Methods:

Method | Returns | Description
--- | --- | ---
`to_dict()` | `Dict[str, Any]` | Convert to dictionary

## Templates

### ReportSection

A section within a compliance report.

Report sections can contain nested subsections to create hierarchical report structures. Each section has a title, content, and optional metadata for additional context.

Attributes:

Name | Type | Description
--- | --- | ---
`title` | `str` | Section heading/title.
`content` | `str` | Main content of the section (text, markdown, etc.).
`subsections` | `List['ReportSection']` | Nested sections within this section.
`metadata` | `Dict[str, Any]` | Additional data about the section (charts, tables, etc.).

Example

> > > section = ReportSection( ... title="Risk Assessment", ... content="This section analyzes identified compliance risks.", ... subsections=[ ... ReportSection( ... title="Critical Risks", ... content="No critical risks identified.", ... ), ... ReportSection( ... title="High Risks", ... content="2 high-risk violations require attention.", ... ), ... ], ... metadata={"risk_count": 2, "max_severity": "high"}, ... )

> > > ## Access nested sections

> > > for sub in section.subsections: ... print(f"- {sub.title}") - Critical Risks - High Risks

## `to_dict()`

Convert section to dictionary for serialization.

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dict containing all section data including nested subsections.

Example

> > > section = ReportSection(title="Test", content="Content") data = section.to_dict() print(data["title"]) 'Test'

## `to_markdown(level=2)`

Render section as markdown with appropriate heading levels.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`level` | `int` | Heading level (default 2 = ##). Subsections use level + 1. | `2`

Returns:

Type | Description
--- | ---
`str` | Markdown formatted string of the section.

Example

> > > section = ReportSection(title="Summary", content="All good.") print(section.to_markdown())

#### Summary

All good.

A section within a compliance report.

Attributes:

Attribute | Type | Description
--- | --- | ---
`title` | `str` | Section heading
`content` | `str` | Main content (text/markdown)
`subsections` | `List[ReportSection]` | Nested sections
`metadata` | `Dict[str, Any]` | Additional data

Methods:

Method | Returns | Description
--- | --- | ---
`to_dict()` | `Dict[str, Any]` | Convert to dictionary
`to_markdown(level=2)` | `str` | Render as markdown

Example:

    from rotalabs_comply.reports.templates import ReportSection

    section = ReportSection(
        title="Risk Assessment",
        content="Analysis of identified risks...",
        subsections=[
            ReportSection(title="Critical Risks", content="None found."),
            ReportSection(title="High Risks", content="2 issues identified."),
        ],
        metadata={"risk_count": 2},
    )

    print(section.to_markdown())

### ReportTemplate

Template defining the structure and format of a compliance report.

Templates specify which framework the report covers, its title, which sections to include, and the output format.

Attributes:

Name | Type | Description
--- | --- | ---
`framework` | `FrameworkType` | The compliance framework this template is for.
`title` | `str` | Default title for reports using this template.
`sections` | `List[str]` | List of section names to include in the report.
`format` | `Literal['markdown', 'json', 'html']` | Output format for the report (markdown, json, or html).

Example

> > > template = ReportTemplate( ... framework="eu_ai_act", ... title="EU AI Act Compliance Report", ... sections=[ ... "executive_summary", ... "risk_assessment", ... "compliance_matrix", ... "recommendations", ... ], ... format="markdown", ... )

> > > ## Check what sections will be included

> > > "risk_assessment" in template.sections True

## `to_dict()`

Convert template to dictionary.

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dict containing template configuration.

Template defining report structure and format.

Attributes:

Attribute | Type | Description
--- | --- | ---
`framework` | `str` | Target framework
`title` | `str` | Default title
`sections` | `List[str]` | Section names to include
`format` | `str` | Output format

### Pre-defined Templates

#### EU_AI_ACT_TEMPLATE

Template for EU AI Act compliance reports.

Includes sections required for demonstrating compliance with the European Union's Artificial Intelligence Act, focusing on risk classification, transparency, and human oversight requirements.

Example

> > > from rotalabs_comply.reports.templates import EU_AI_ACT_TEMPLATE print(EU_AI_ACT_TEMPLATE.title) 'EU AI Act Compliance Report'

Template for EU AI Act compliance reports.

Sections: - executive_summary - risk_classification - risk_assessment - transparency_obligations - human_oversight - compliance_matrix - data_governance - technical_documentation - recommendations - audit_summary

#### SOC2_TEMPLATE

Template for SOC2 Type II compliance reports.

Covers the five Trust Service Criteria: Security, Availability, Processing Integrity, Confidentiality, and Privacy.

Example

> > > from rotalabs_comply.reports.templates import SOC2_TEMPLATE "security_controls" in SOC2_TEMPLATE.sections True

Template for SOC2 Type II compliance reports.

Sections: - executive_summary - system_overview - risk_assessment - security_controls - availability_controls - processing_integrity - confidentiality_controls - privacy_controls - compliance_matrix - recommendations - audit_summary

#### HIPAA_TEMPLATE

Template for HIPAA compliance reports.

Covers the Security Rule requirements including Administrative, Physical, and Technical Safeguards for Protected Health Information (PHI).

Example

> > > from rotalabs_comply.reports.templates import HIPAA_TEMPLATE "phi_handling" in HIPAA_TEMPLATE.sections True

Template for HIPAA compliance reports.

Sections: - executive_summary - risk_assessment - administrative_safeguards - physical_safeguards - technical_safeguards - breach_notification - phi_handling - compliance_matrix - recommendations - audit_summary

#### EXECUTIVE_SUMMARY_TEMPLATE

Template for high-level executive summary reports.

Designed for executive audiences, focusing on key metrics, critical findings, and high-priority recommendations without technical details.

Example

> > > from rotalabs_comply.reports.templates import EXECUTIVE_SUMMARY_TEMPLATE len(EXECUTIVE_SUMMARY_TEMPLATE.sections) 5

Template for executive summary reports.

Sections: - executive_summary - key_metrics - risk_assessment - critical_findings - recommendations

## Section Generators

### generate_executive_summary

    def generate_executive_summary(stats: Dict[str, Any]) -> ReportSection

Generate executive summary from statistics.

Expected stats keys: - `total_entries`: int - `violations_count`: int - `compliance_rate`: float (0-100) - `critical_violations`: int - `high_violations`: int - `period_start`: str - `period_end`: str - `frameworks`: List[str]

Example:

    from rotalabs_comply.reports.templates import generate_executive_summary

    stats = {
        "total_entries": 10000,
        "violations_count": 15,
        "compliance_rate": 99.85,
        "critical_violations": 0,
        "high_violations": 2,
        "period_start": "2026-01-01",
        "period_end": "2026-01-31",
        "frameworks": ["EU AI Act", "SOC2"],
    }

    section = generate_executive_summary(stats)
    print(section.metadata["status"])  # "NEEDS REVIEW"

### generate_risk_assessment

    def generate_risk_assessment(violations: Sequence[ComplianceViolation]) -> ReportSection

Generate risk assessment from violations.

Returns section with metadata: - `overall_risk`: str - `severity_counts`: Dict[str, int] - `category_counts`: Dict[str, int] - `violation_count`: int

### generate_compliance_matrix

    def generate_compliance_matrix(results: Sequence[ComplianceCheckResult]) -> ReportSection

Generate compliance matrix from check results.

Returns section with metadata: - `frameworks`: List[str] - `total_checks`: int - `total_passed`: int - `total_violations`: int - `compliance_rate`: float

### generate_recommendations

    def generate_recommendations(violations: Sequence[ComplianceViolation]) -> ReportSection

Generate prioritized recommendations from violations.

Returns section with metadata: - `recommendation_count`: int - `immediate_count`: int - `short_term_count`: int - `long_term_count`: int

### generate_metrics_summary

    def generate_metrics_summary(entries: Sequence[Any]) -> ReportSection

Generate metrics summary from audit entries.

Returns section with metadata: - `entry_count`: int - `safety_rate`: float - `avg_latency`: float - `p50_latency`: float - `p95_latency`: float - `p99_latency`: float

### generate_audit_summary

    def generate_audit_summary(entries: Sequence[Any], period: str) -> ReportSection

Generate audit summary for a period.

Returns section with metadata: - `period`: str - `entry_count`: int - `days_active`: int - `avg_daily`: float - `peak_daily`: int