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

Skip to content

# Frameworks Module

Compliance framework implementations for EU AI Act, SOC2, and HIPAA.

## Base Types

### ComplianceRule

Definition of a single compliance rule within a framework.

Rules represent specific regulatory requirements that AI systems must satisfy. Each rule has an associated check function that evaluates audit entries for compliance.

Attributes:

Name | Type | Description
--- | --- | ---
`rule_id` | `str` | Unique identifier for this rule within the framework
`name` | `str` | Human-readable name of the rule
`description` | `str` | Detailed description of the requirement
`severity` | `RiskLevel` | Default severity level for violations of this rule
`category` | `str` | Category grouping for the rule
`check_fn` | `Optional[Callable[[AuditEntry], bool]]` | Optional custom check function for specialized validation
`remediation` | `str` | Default remediation guidance for violations
`references` | `List[str]` | External references (regulation sections, standards, etc.)

Definition of a single compliance rule within a framework.

Attributes:

Attribute | Type | Description
--- | --- | ---
`rule_id` | `str` | Unique identifier within framework
`name` | `str` | Human-readable name
`description` | `str` | Detailed requirement description
`severity` | `RiskLevel` | Default severity for violations
`category` | `str` | Category grouping
`check_fn` | `Optional[Callable]` | Custom check function
`remediation` | `str` | Default remediation guidance
`references` | `List[str]` | External references

Example:

    from rotalabs_comply.frameworks.base import ComplianceRule, RiskLevel

    rule = ComplianceRule(
        rule_id="CUSTOM-001",
        name="Custom Requirement",
        description="Description of what's required",
        severity=RiskLevel.MEDIUM,
        category="custom",
        remediation="How to fix violations",
        references=["Internal Policy 1.2.3"],
    )

### ComplianceFramework Protocol

Protocol defining the interface for compliance frameworks.

All compliance frameworks must implement this protocol to ensure consistent behavior across different regulatory standards.

Frameworks evaluate audit entries against their rules and produce compliance check results with any violations found.

## `name` `property`

Get the name of this compliance framework.

Returns:

Type | Description
--- | ---
`str` | Human-readable name (e.g., "EU AI Act", "SOC2 Type II")

## `rules` `property`

Get all rules defined in this framework.

Returns:

Type | Description
--- | ---
`List[ComplianceRule]` | List of all compliance rules

## `version` `property`

Get the version of the framework being implemented.

Returns:

Type | Description
--- | ---
`str` | Version string (e.g., "2024", "2017")

## `check(entry, profile)` `async`

Check an audit entry for compliance violations.

Evaluates the entry against all applicable rules based on the provided compliance profile.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`entry` | `AuditEntry` | The audit entry to evaluate | required
`profile` | `ComplianceProfile` | Configuration profile controlling evaluation | required

Returns:

Type | Description
--- | ---
`ComplianceCheckResult` | ComplianceCheckResult containing any violations found

## `get_rule(rule_id)`

Get a specific rule by its ID.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`rule_id` | `str` | The unique identifier of the rule | required

Returns:

Type | Description
--- | ---
`Optional[ComplianceRule]` | The ComplianceRule if found, None otherwise

## `list_categories()`

List all rule categories in this framework.

Returns:

Type | Description
--- | ---
`List[str]` | List of unique category names

Protocol defining the interface for compliance frameworks.

Properties:

Property | Type | Description
--- | --- | ---
`name` | `str` | Framework name
`version` | `str` | Framework version
`rules` | `List[ComplianceRule]` | All rules

Methods:

Method | Signature | Description
--- | --- | ---
`check` | `async (entry, profile) -> ComplianceCheckResult` | Check entry
`get_rule` | `(rule_id: str) -> Optional[ComplianceRule]` | Get rule by ID
`list_categories` | `() -> List[str]` | List categories

### BaseFramework

Abstract base class for compliance frameworks.

Provides common functionality for all framework implementations including rule management, category listing, and the main check loop. Subclasses must implement the _check_rule method to define framework-specific validation logic.

Attributes:

Name | Type | Description
--- | --- | ---
`_name` |  | Framework name
`_version` |  | Framework version
`_rules` |  | List of rules in this framework
`_rules_by_id` | `Dict[str, ComplianceRule]` | Dictionary mapping rule IDs to rules for fast lookup

## `name` `property`

Get the framework name.

## `rules` `property`

Get all rules in this framework.

## `version` `property`

Get the framework version.

## `__init__(name, version, rules)`

Initialize the base framework.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`name` | `str` | Human-readable framework name | required
`version` | `str` | Framework version string | required
`rules` | `List[ComplianceRule]` | List of compliance rules | required

## `check(entry, profile)` `async`

Check an audit entry for compliance violations.

Evaluates the entry against all applicable rules based on the provided compliance profile, respecting category filters and excluded rules.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`entry` | `AuditEntry` | The audit entry to evaluate | required
`profile` | `ComplianceProfile` | Configuration profile controlling evaluation | required

Returns:

Type | Description
--- | ---
`ComplianceCheckResult` | ComplianceCheckResult containing any violations found

## `get_rule(rule_id)`

Get a specific rule by its ID.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`rule_id` | `str` | The unique identifier of the rule | required

Returns:

Type | Description
--- | ---
`Optional[ComplianceRule]` | The ComplianceRule if found, None otherwise

## `list_categories()`

List all unique rule categories in this framework.

Returns:

Type | Description
--- | ---
`List[str]` | Sorted list of unique category names

Abstract base class for compliance frameworks.

### Constructor

    BaseFramework(name: str, version: str, rules: List[ComplianceRule])

### Abstract Method

Subclasses must implement:

    def _check_rule(
        self, entry: AuditEntry, rule: ComplianceRule
    ) -> Optional[ComplianceViolation]

Example Custom Framework:

    from rotalabs_comply.frameworks.base import BaseFramework, ComplianceRule, RiskLevel

    class MyFramework(BaseFramework):
        def __init__(self):
            rules = [
                ComplianceRule(
                    rule_id="MY-001",
                    name="My Rule",
                    description="Description",
                    severity=RiskLevel.MEDIUM,
                    category="custom",
                ),
            ]
            super().__init__("My Framework", "1.0", rules)

        def _check_rule(self, entry, rule):
            if rule.rule_id == "MY-001":
                if not entry.metadata.get("my_field"):
                    return self._create_violation(entry, rule, "my_field missing")
            return None

### AuditEntry (Frameworks)

Represents a single audit log entry for an AI system interaction.

Audit entries capture the essential metadata about AI system operations that compliance frameworks need to evaluate against regulatory requirements.

Attributes:

Name | Type | Description
--- | --- | ---
`entry_id` | `str` | Unique identifier for this audit entry
`timestamp` | `datetime` | When the event occurred
`event_type` | `str` | Type of event (e.g., "inference", "training", "data_access")
`actor` | `str` | Identifier for the user, system, or agent that triggered the event
`action` | `str` | Description of the action taken
`resource` | `str` | The resource being accessed or modified
`metadata` | `Dict[str, Any]` | Additional context-specific information about the event
`risk_level` | `RiskLevel` | Assessed risk level of this operation
`system_id` | `str` | Identifier for the AI system involved
`data_classification` | `str` | Classification of data involved (e.g., "PII", "PHI", "public")
`user_notified` | `bool` | Whether the user was notified about AI involvement
`human_oversight` | `bool` | Whether human oversight was present
`error_handled` | `bool` | Whether errors were handled gracefully
`documentation_ref` | `Optional[str]` | Reference to related technical documentation

Audit entry structure used by frameworks for compliance checking.

Attributes:

Attribute | Type | Default | Description
--- | --- | --- | ---
`entry_id` | `str` | Required | Unique identifier
`timestamp` | `datetime` | Required | Event time
`event_type` | `str` | Required | Type of event
`actor` | `str` | Required | Who triggered event
`action` | `str` | Required | Action description
`resource` | `str` | `""` | Resource accessed
`metadata` | `Dict[str, Any]` | `{}` | Additional context
`risk_level` | `RiskLevel` | `LOW` | Risk classification
`system_id` | `str` | `""` | AI system identifier
`data_classification` | `str` | `"unclassified"` | Data sensitivity
`user_notified` | `bool` | `False` | User knows about AI
`human_oversight` | `bool` | `False` | Human oversight present
`error_handled` | `bool` | `True` | Errors handled gracefully
`documentation_ref` | `Optional[str]` | `None` | Documentation reference

### ComplianceProfile (Frameworks)

Configuration profile for compliance evaluation.

Profiles define which rules to apply, severity thresholds, and system-specific compliance requirements.

Attributes:

Name | Type | Description
--- | --- | ---
`profile_id` | `str` | Unique identifier for this profile
`name` | `str` | Human-readable profile name
`description` | `str` | Detailed description of the profile's purpose
`enabled_frameworks` | `List[str]` | List of framework names to evaluate against
`enabled_categories` | `List[str]` | Categories of rules to check (empty = all)
`min_severity` | `RiskLevel` | Minimum severity level to report
`system_classification` | `str` | Classification of the AI system being evaluated
`custom_rules` | `List[str]` | Additional custom rule IDs to include
`excluded_rules` | `List[str]` | Rule IDs to exclude from evaluation
`metadata` | `Dict[str, Any]` | Additional profile configuration

Configuration profile for compliance evaluation.

Attributes:

Attribute | Type | Default | Description
--- | --- | --- | ---
`profile_id` | `str` | Required | Unique identifier
`name` | `str` | Required | Profile name
`description` | `str` | `""` | Profile description
`enabled_frameworks` | `List[str]` | `[]` | Frameworks to evaluate
`enabled_categories` | `List[str]` | `[]` | Categories to check
`min_severity` | `RiskLevel` | `LOW` | Minimum severity to report
`system_classification` | `str` | `"standard"` | System classification
`custom_rules` | `List[str]` | `[]` | Additional rule IDs
`excluded_rules` | `List[str]` | `[]` | Rules to skip
`metadata` | `Dict[str, Any]` | `{}` | Additional config

### ComplianceViolation (Frameworks)

Represents a single compliance violation detected during evaluation.

Violations are the output of rule checks that identify non-compliance with regulatory requirements.

Attributes:

Name | Type | Description
--- | --- | ---
`rule_id` | `str` | ID of the rule that was violated
`rule_name` | `str` | Human-readable name of the violated rule
`severity` | `RiskLevel` | Severity level of the violation
`description` | `str` | Detailed description of what was violated
`evidence` | `str` | Specific evidence from the audit entry
`remediation` | `str` | Suggested steps to remediate the violation
`entry_id` | `str` | ID of the audit entry that triggered this violation
`category` | `str` | Category of the violated rule
`framework` | `str` | Name of the framework containing the rule

A compliance violation detected during evaluation.

Attributes:

Attribute | Type | Description
--- | --- | ---
`rule_id` | `str` | Violated rule ID
`rule_name` | `str` | Rule name
`severity` | `RiskLevel` | Violation severity
`description` | `str` | Rule description
`evidence` | `str` | Specific evidence
`remediation` | `str` | How to fix
`entry_id` | `str` | Entry that triggered
`category` | `str` | Rule category
`framework` | `str` | Framework name

### ComplianceCheckResult (Frameworks)

Result of a compliance check against an audit entry.

Contains all violations found, along with summary statistics about the compliance evaluation.

Attributes:

Name | Type | Description
--- | --- | ---
`entry_id` | `str` | ID of the audit entry that was checked
`framework` | `str` | Name of the framework used for evaluation
`framework_version` | `str` | Version of the framework
`timestamp` | `datetime` | When the check was performed
`violations` | `List[ComplianceViolation]` | List of all violations found
`rules_checked` | `int` | Total number of rules evaluated
`rules_passed` | `int` | Number of rules that passed
`is_compliant` | `bool` | Whether the entry is fully compliant (no violations)
`metadata` | `Dict[str, Any]` | Additional check result metadata

## `__post_init__()`

Update is_compliant based on violations.

Result of a compliance check against an audit entry.

Attributes:

Attribute | Type | Description
--- | --- | ---
`entry_id` | `str` | Checked entry ID
`framework` | `str` | Framework name
`framework_version` | `str` | Framework version
`timestamp` | `datetime` | Check time
`violations` | `List[ComplianceViolation]` | Violations found
`rules_checked` | `int` | Total rules evaluated
`rules_passed` | `int` | Rules that passed
`is_compliant` | `bool` | No violations found
`metadata` | `Dict[str, Any]` | Additional data

## EU AI Act Framework

EU AI Act compliance framework.

Implements compliance checks based on the EU AI Act (2024) requirements for high-risk AI systems. The framework evaluates audit entries against the Act's requirements for transparency, human oversight, risk management, documentation, and security.

The EU AI Act classifies AI systems into risk categories: - Unacceptable risk: Prohibited systems - High-risk: Systems subject to strict requirements (this framework's focus) - Limited risk: Systems with transparency obligations - Minimal risk: Most AI systems with few requirements

This implementation focuses on high-risk system requirements as they represent the most comprehensive compliance obligations.

Example

> > > framework = EUAIActFramework() result = await framework.check(entry, profile) if not result.is_compliant: ... for violation in result.violations: ... print(f"{violation.rule_id}: {violation.description}")

## `__init__()`

Initialize the EU AI Act framework with all defined rules.

EU AI Act (2024) compliance framework.

### Categories

Category | Description
--- | ---
`transparency` | User notification requirements
`oversight` | Human oversight requirements
`risk_management` | Risk assessment and handling
`documentation` | Technical documentation
`security` | Cybersecurity measures

### Rules

Rule ID | Name | Severity | Category
--- | --- | --- | ---
`EUAI-001` | Human Oversight Documentation | HIGH | oversight
`EUAI-002` | AI Interaction Notification | HIGH | transparency
`EUAI-003` | Risk Assessment | CRITICAL | risk_management
`EUAI-004` | Technical Documentation | HIGH | documentation
`EUAI-005` | Data Governance | HIGH | documentation
`EUAI-006` | Error Handling | MEDIUM | risk_management
`EUAI-007` | Accuracy Monitoring | MEDIUM | risk_management
`EUAI-008` | Cybersecurity Measures | HIGH | security

### Usage

    from rotalabs_comply.frameworks.eu_ai_act import EUAIActFramework
    from rotalabs_comply.frameworks.base import AuditEntry, ComplianceProfile, RiskLevel
    from datetime import datetime

    framework = EUAIActFramework()

    entry = AuditEntry(
        entry_id="test-001",
        timestamp=datetime.utcnow(),
        event_type="inference",
        actor="user@example.com",
        action="AI response",
        risk_level=RiskLevel.HIGH,
        user_notified=True,
        human_oversight=True,
        metadata={"risk_assessment_documented": True},
    )

    profile = ComplianceProfile(
        profile_id="eu-ai",
        name="EU AI Compliance",
    )

    result = await framework.check(entry, profile)

### Key Requirements

High-risk operations require: - `human_oversight=True` - `metadata["risk_assessment_documented"]=True`

User-facing interactions require: - `user_notified=True`

Inference events require: - `metadata["accuracy_monitored"]=True`

## SOC2 Framework

SOC2 Type II compliance framework.

Implements compliance checks based on the AICPA Trust Service Criteria for SOC2 Type II reporting. This framework evaluates audit entries against the five trust service principles: Security, Availability, Processing Integrity, Confidentiality, and Privacy.

SOC2 Type II reports assess both the design and operating effectiveness of controls over a specified period. This implementation focuses on controls relevant to AI systems and their operational characteristics.

Trust Service Categories: - CC (Common Criteria): Security-related controls - A: Availability controls - PI: Processing Integrity controls - C: Confidentiality controls - P: Privacy controls

Example

> > > framework = SOC2Framework() result = await framework.check(entry, profile) if not result.is_compliant: ... for violation in result.violations: ... print(f"{violation.rule_id}: {violation.description}")

## `__init__()`

Initialize the SOC2 Type II framework with all defined rules.

SOC2 Type II compliance framework.

### Categories

Category | TSC | Description
--- | --- | ---
`security` | CC | Common Criteria - Security controls
`availability` | A | System availability
`processing_integrity` | PI | Data processing accuracy
`confidentiality` | C | Confidential information protection
`privacy` | P | Personal information protection

### Rules

Rule ID | Name | Severity | Category
--- | --- | --- | ---
`SOC2-CC6.1` | Logical Access Controls | HIGH | security
`SOC2-CC6.2` | System Boundary Definition | MEDIUM | security
`SOC2-CC6.3` | Change Management | MEDIUM | security
`SOC2-CC7.1` | System Monitoring | HIGH | security
`SOC2-CC7.2` | Incident Response | HIGH | security
`SOC2-CC8.1` | Availability Monitoring | MEDIUM | availability
`SOC2-A1.1` | Recovery Objectives | MEDIUM | availability
`SOC2-PI1.1` | Processing Integrity | MEDIUM | processing_integrity
`SOC2-C1.1` | Confidentiality Classification | HIGH | confidentiality
`SOC2-P1.1` | Privacy Notice | HIGH | privacy

### Usage

    from rotalabs_comply.frameworks.soc2 import SOC2Framework

    framework = SOC2Framework()

    entry = AuditEntry(
        entry_id="soc2-001",
        timestamp=datetime.utcnow(),
        event_type="data_access",
        actor="admin@company.com",
        action="Query database",
        data_classification="confidential",
        metadata={
            "access_controlled": True,
            "monitored": True,
        },
    )

    result = await framework.check(entry, profile)

### Key Requirements

Access events require: - Authenticated actor (not "anonymous") - `metadata["access_controlled"]=True`

Change events require: - `metadata["change_approved"]=True` - `documentation_ref` set

Data events require: - `data_classification` not "unclassified"

## HIPAA Framework

HIPAA compliance framework.

Implements compliance checks based on HIPAA Security Rule technical safeguards and Privacy Rule requirements. This framework evaluates audit entries for AI systems that process Protected Health Information (PHI) or electronic PHI (ePHI).

HIPAA requires covered entities and business associates to: - Ensure confidentiality, integrity, and availability of ePHI - Protect against anticipated threats and hazards - Protect against unauthorized uses or disclosures - Ensure workforce compliance

This implementation focuses on technical safeguards (164.312) which are most relevant to AI system operations: - Access controls (164.312(a)) - Audit controls (164.312(b)) - Integrity controls (164.312(c)) - Authentication (164.312(d)) - Transmission security (164.312(e))

Example

> > > framework = HIPAAFramework() result = await framework.check(entry, profile) if not result.is_compliant: ... for violation in result.violations: ... print(f"{violation.rule_id}: {violation.description}")

## `__init__()`

Initialize the HIPAA framework with all defined rules.

HIPAA compliance framework for PHI handling.

### Categories

Category | Rule Section | Description
--- | --- | ---
`access_control` | 164.312(a) | System and data access
`audit` | 164.312(b) | Audit controls
`integrity` | 164.312(c) | Data integrity
`authentication` | 164.312(d) | Entity authentication
`transmission` | 164.312(e) | Transmission security
`privacy` | 164.502/514/530 | Privacy rule

### Rules

Rule ID | Name | Severity | Category
--- | --- | --- | ---
`HIPAA-164.312(a)` | Access Control | CRITICAL | access_control
`HIPAA-164.312(b)` | Audit Controls | HIGH | audit
`HIPAA-164.312(c)` | Integrity Controls | HIGH | integrity
`HIPAA-164.312(d)` | Authentication | CRITICAL | authentication
`HIPAA-164.312(e)` | Transmission Security | HIGH | transmission
`HIPAA-164.502` | Uses and Disclosures | CRITICAL | privacy
`HIPAA-164.514` | De-identification | HIGH | privacy
`HIPAA-164.530` | Administrative Requirements | MEDIUM | privacy

### PHI Detection

Rules only apply when `data_classification` contains:

- `"PHI"`
- `"ePHI"`
- `"protected_health_information"`
- `"health_data"`
- `"medical"`
- `"clinical"`

### Usage

    from rotalabs_comply.frameworks.hipaa import HIPAAFramework

    framework = HIPAAFramework()

    # PHI-related entry (rules apply)
    entry = AuditEntry(
        entry_id="hipaa-001",
        timestamp=datetime.utcnow(),
        event_type="inference",
        actor="doctor@hospital.com",
        action="AI diagnostic",
        data_classification="PHI",
        metadata={
            "access_controlled": True,
            "encryption_enabled": True,
            "authenticated": True,
            "purpose_documented": True,
            "minimum_necessary_applied": True,
        },
    )

    result = await framework.check(entry, profile)

### Key Requirements

All PHI access requires: - Authenticated actor - `metadata["access_controlled"]=True` - `metadata["encryption_enabled"]=True`

High-risk PHI operations require: - `metadata["mfa_verified"]=True`

PHI use requires: - `metadata["purpose_documented"]=True` - `metadata["minimum_necessary_applied"]=True`