Skip to main content

cartridges

Cartridges

IOA Cartridges are modular compliance and governance components that can be plugged into AI systems to ensure regulatory adherence and ethical operation.

Overview​

Cartridges provide:

  • Compliance modules for specific regulations (GDPR, CCPA, HIPAA)
  • Security frameworks (ISO 27001, SOC 2)
  • Ethics modules (bias detection, fairness validation)
  • Industry standards (healthcare, finance, education)

Available Cartridges​

GDPR (General Data Protection Regulation)​

EU data protection and privacy regulation.

# Install GDPR cartridge
ioa cartridge add gdpr

# Check GDPR compliance
ioa score --cartridge gdpr

Features:

  • Data subject rights validation
  • Consent management
  • Data minimization checks
  • Right to be forgotten
  • Data portability
  • Privacy by design

CCPA (California Consumer Privacy Act)​

California consumer privacy protection.

# Install CCPA cartridge
ioa cartridge add ccpa

# CCPA compliance check
ioa score --cartridge ccpa

Features:

  • Consumer rights validation
  • Data collection transparency
  • Opt-out mechanisms
  • Data sale restrictions
  • Non-discrimination compliance

HIPAA (Health Insurance Portability and Accountability Act)​

Healthcare data protection.

# Install HIPAA cartridge
ioa cartridge add hipaa

# HIPAA compliance validation
ioa score --cartridge hipaa

Features:

  • PHI (Protected Health Information) handling
  • Administrative safeguards
  • Physical safeguards
  • Technical safeguards
  • Breach notification

Security Cartridges​

ISO 27001​

Information security management system.

ioa cartridge add iso27001

SOC 2​

Service organization control reporting.

ioa cartridge add soc2

NIST Cybersecurity Framework​

Cybersecurity risk management.

ioa cartridge add nist-csf

Ethics Cartridges​

Bias Detection​

Automated bias identification and mitigation.

ioa cartridge add bias-detection

Fairness Validation​

Statistical fairness measurement.

ioa cartridge add fairness-validation

Explainability​

AI decision explanation and transparency.

ioa cartridge add explainability

Cartridge Management​

Installation​

# Install single cartridge
ioa cartridge add <cartridge-name>

# Install multiple cartridges
ioa cartridge add gdpr ccpa hipaa

# Install with specific version
ioa cartridge add gdpr@2.1.0

Listing Cartridges​

# List installed cartridges
ioa cartridge list

# List available cartridges
ioa cartridge list --available

# List with details
ioa cartridge list --verbose

Updating Cartridges​

# Update all cartridges
ioa cartridge update

# Update specific cartridge
ioa cartridge update gdpr

# Check for updates
ioa cartridge update --check

Removing Cartridges​

# Remove cartridge
ioa cartridge remove <cartridge-name>

# Remove multiple cartridges
ioa cartridge remove gdpr ccpa

# Force removal (ignore dependencies)
ioa cartridge remove <cartridge-name> --force

Cartridge Configuration​

Configuration File​

Each cartridge can be configured via cartridges.yaml:

cartridges:
  gdpr:
    enabled: true
    version: "2.1.0"
    config:
      data_retention_period: "7y"
      consent_mechanism: "explicit"
      dpo_contact: "dpo@company.com"
  
  ccpa:
    enabled: true
    version: "1.5.0"
    config:
      business_purpose: "analytics"
      data_categories: ["personal", "sensitive"]
      opt_out_mechanism: "web_form"
  
  hipaa:
    enabled: true
    version: "1.2.0"
    config:
      covered_entity: true
      business_associate: false
      phi_encryption: "aes-256"

Environment Variables​

# Cartridge-specific settings
export GDPR_DATA_RETENTION_PERIOD="7y"
export CCPA_BUSINESS_PURPOSE="analytics"
export HIPAA_PHI_ENCRYPTION="aes-256"

Custom Cartridges​

Creating a Cartridge​

# Create new cartridge
ioa cartridge create my-custom-cartridge

# This creates the structure:
# cartridges/my-custom-cartridge/
# ├── cartridge.yaml
# ├── requirements.txt
# ├── tests/
# └── src/
#     ├── __init__.py
#     ├── validator.py
#     └── config.py

Cartridge Structure​

# cartridge.yaml
name: "my-custom-cartridge"
version: "1.0.0"
description: "Custom compliance cartridge"
author: "Your Organization"
license: "MIT"

dependencies:
  - ioa-core>=2.5.0
  - python>=3.8

requirements:
  - "Custom compliance requirement 1"
  - "Custom compliance requirement 2"

scoring:
  weight: 0.1
  components:
    - validation
    - reporting
    - monitoring

Implementation​

# cartridges/my-custom-cartridge/src/validator.py
from ioa.cartridge import BaseCartridge
from ioa.scoring import ScoreComponent

class MyCustomCartridge(BaseCartridge):
    def __init__(self, config):
        super().__init__(config)
        self.name = "my-custom-cartridge"
    
    def validate(self, system_state):
        """Validate custom compliance requirements."""
        violations = []
        score = 1.0
        
        # Custom validation logic
        if not self.check_requirement_1(system_state):
            violations.append("Requirement 1 not met")
            score -= 0.3
        
        if not self.check_requirement_2(system_state):
            violations.append("Requirement 2 not met")
            score -= 0.2
        
        return ScoreComponent(
            name=self.name,
            score=max(0.0, score),
            violations=violations
        )
    
    def check_requirement_1(self, system_state):
        """Check custom requirement 1."""
        # Implementation here
        return True
    
    def check_requirement_2(self, system_state):
        """Check custom requirement 2."""
        # Implementation here
        return True

Testing Cartridges​

# cartridges/my-custom-cartridge/tests/test_validator.py
import pytest
from src.validator import MyCustomCartridge

class TestMyCustomCartridge:
    def test_validation_success(self):
        cartridge = MyCustomCartridge({})
        system_state = {"requirement_1": True, "requirement_2": True}
        
        result = cartridge.validate(system_state)
        assert result.score == 1.0
        assert len(result.violations) == 0
    
    def test_validation_failure(self):
        cartridge = MyCustomCartridge({})
        system_state = {"requirement_1": False, "requirement_2": False}
        
        result = cartridge.validate(system_state)
        assert result.score < 1.0
        assert len(result.violations) > 0

Cartridge Registry​

Public Registry​

Cartridges are published to the IOA Cartridge Registry:

# Search cartridges
ioa cartridge search "privacy"

# Show cartridge details
ioa cartridge info gdpr

# Show cartridge documentation
ioa cartridge docs gdpr

Private Registry​

For enterprise use, set up a private registry:

# Configure private registry
ioa cartridge config --registry https://internal-registry.company.com

# Install from private registry
ioa cartridge add internal-cartridge

Best Practices​

Cartridge Selection​

  1. Identify Requirements - Map regulatory needs to cartridges
  2. Version Compatibility - Ensure cartridge versions are compatible
  3. Performance Impact - Consider cartridge performance overhead
  4. Maintenance - Choose well-maintained cartridges
  5. Documentation - Prefer cartridges with good documentation

Configuration Management​

  1. Environment-Specific - Different configs for dev/staging/prod
  2. Secret Management - Use secure secret storage
  3. Version Control - Track configuration changes
  4. Validation - Validate configurations before deployment
  5. Monitoring - Monitor cartridge performance

Development Guidelines​

  1. Single Responsibility - One cartridge per compliance area
  2. Clear Interfaces - Well-defined APIs and contracts
  3. Comprehensive Testing - Full test coverage
  4. Documentation - Clear usage and configuration docs
  5. Error Handling - Graceful error handling and reporting

Troubleshooting​

Common Issues​

Cartridge not found:

# Update cartridge registry
ioa cartridge update --registry

# Check registry connectivity
ioa cartridge ping

Version conflicts:

# Check dependencies
ioa cartridge deps <cartridge-name>

# Resolve conflicts
ioa cartridge resolve

Configuration errors:

# Validate configuration
ioa cartridge validate

# Show configuration errors
ioa cartridge config --check

Debug Mode​

# Enable debug logging
export IOA_LOG_LEVEL=DEBUG
ioa cartridge --debug <command>

Getting Help​