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

Reports Module

ReportGenerator

Generate a report

__init__(audit_logger, frameworks=None)

export_html(report)

export_json(report)

export_markdown(report)

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

generate_executive_summary(period_start, period_end, profile) async

Constructor

Methods

generate

generate_executive_summary

export_markdown

export_json

export_html

ComplianceReport

to_dict()

Templates

ReportSection

Access nested sections

to_dict()

to_markdown(level=2)

Summary

ReportTemplate

Check what sections will be included

to_dict()

Pre-defined Templates

EU_AI_ACT_TEMPLATE

SOC2_TEMPLATE

HIPAA_TEMPLATE

EXECUTIVE_SUMMARY_TEMPLATE

Section Generators

generate_executive_summary

generate_risk_assessment

generate_compliance_matrix

generate_recommendations

generate_metrics_summary

generate_audit_summary

`init(audit_logger, frameworks=None)`

`export_html(report)`

`export_json(report)`

`export_markdown(report)`

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

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

`to_dict()`

`to_dict()`

`to_markdown(level=2)`

`to_dict()`