Guardrails

Guardrails Execution Pipeline
    ├── 1. Task Initialization
    │   ├── Input Validation
    │   ├── Parameter Sanitization
    │   └── Pre-Execution Checks
    │
    ├── 2. Agent Execution
    │   ├── Resource Monitoring
    │   ├── Rate Limit Tracking
    │   └── Progress Validation
    │
    ├── 3. Output Generation
    │   ├── Content Generation
    │   └── Initial Output
    │
    ├── 4. Guardrail Validation ← All outputs validated
    │   ├── Content Safety Checks
    │   ├── PII Detection
    │   ├── Token Limit Enforcement
    │   ├── Custom Validations
    │   └── Compliance Checks
    │
    ├── 5. Validation Result
    │   ├── Approved → Task Complete
    │   ├── Partially Approved → Refinement
    │   ├── Needs Revision → Retry
    │   └── Failed → Error
    │
    └── 6. Task Completion
        └── Return Validated Output

public enum ValidationStrictness: String, Codable {
    case lenient   // Partial approvals accepted
    case standard  // Balanced validation (default)
    case strict    // Even partial approvals require revision
}

public enum TaskValidationResult {
    case approved
    case partiallyApproved(feedback: String)
    case needsRevision(feedback: String)
    case validationFailed
}

import OrbitAI

// Content safety configuration
let contentSafetyAgent = Agent(
    role: "Content Moderator",
    purpose: "Generate safe, appropriate content",
    context: """
    Expert content creator who:
    - Avoids harmful, offensive, or inappropriate content
    - Respects cultural sensitivities
    - Maintains professional tone
    - Follows community guidelines
    """,
    guardrails: [
        .noHarmfulContent,
        .contentFilter,
        CustomSensitivityGuardrail(level: .high)
    ]
)

// Custom sensitivity guardrail
final class CustomSensitivityGuardrail: OrbitGuardrail {
    enum SensitivityLevel {
        case low, medium, high
    }

    let level: SensitivityLevel

    init(level: SensitivityLevel) {
        self.level = level
    }

    func check(context: GuardrailContext) async throws -> GuardrailResult {
        guard let output = context.output else {
            return .validationFailed
        }

        // Check sentiment
        let sentiment = analyzeSentiment(output)

        switch level {
        case .high:
            if sentiment.negativity > 0.2 || sentiment.controversy > 0.1 {
                return .needsRevision(
                    feedback: "Content tone is too negative or controversial"
                )
            }

        case .medium:
            if sentiment.negativity > 0.4 || sentiment.controversy > 0.3 {
                return .partiallyApproved(
                    feedback: "Consider adjusting tone for broader audience"
                )
            }

        case .low:
            if sentiment.negativity > 0.6 {
                return .partiallyApproved(
                    feedback: "Content may benefit from more positive framing"
                )
            }
        }

        return .approved
    }

    private func analyzeSentiment(_ text: String) -> (negativity: Double, controversy: Double) {
        // Sentiment analysis implementation
        return (0.0, 0.0)
    }
}

final class PrivacyComplianceGuardrail: OrbitGuardrail {
    let regulations: Set<PrivacyRegulation>

    enum PrivacyRegulation {
        case gdpr      // EU General Data Protection Regulation
        case ccpa      // California Consumer Privacy Act
        case hipaa     // Health Insurance Portability and Accountability Act
        case coppa     // Children's Online Privacy Protection Act
    }

    init(regulations: Set<PrivacyRegulation>) {
        self.regulations = regulations
    }

    func check(context: GuardrailContext) async throws -> GuardrailResult {
        guard let output = context.output else {
            return .validationFailed
        }

        var violations: [String] = []

        // GDPR compliance
        if regulations.contains(.gdpr) {
            let gdprIssues = checkGDPRCompliance(output)
            violations.append(contentsOf: gdprIssues)
        }

        // HIPAA compliance
        if regulations.contains(.hipaa) {
            let hipaaIssues = checkHIPAACompliance(output)
            violations.append(contentsOf: hipaaIssues)
        }

        // COPPA compliance
        if regulations.contains(.coppa) {
            let coppaIssues = checkCOPPACompliance(output)
            violations.append(contentsOf: coppaIssues)
        }

        if !violations.isEmpty {
            return .needsRevision(
                feedback: "Privacy violations detected: \(violations.joined(separator: "; "))"
            )
        }

        return .approved
    }

    private func checkGDPRCompliance(_ output: String) -> [String] {
        var issues: [String] = []

        // Check for PII
        if detectsPII(output) {
            issues.append("Contains PII without consent")
        }

        // Check for data minimization
        if containsExcessiveData(output) {
            issues.append("Violates data minimization principle")
        }

        // Check for right to erasure
        if containsUndeletableReferences(output) {
            issues.append("Contains data that cannot be erased")
        }

        return issues
    }

    private func checkHIPAACompliance(_ output: String) -> [String] {
        var issues: [String] = []

        // Protected Health Information (PHI) detection
        let phiPatterns = [
            "medical record",
            "diagnosis:",
            "prescription:",
            "treatment plan",
            "lab results"
        ]

        for pattern in phiPatterns {
            if output.lowercased().contains(pattern) {
                // Check if properly encrypted/secured
                if !isProperlySecured(output, pattern: pattern) {
                    issues.append("Unsecured PHI: \(pattern)")
                }
            }
        }

        return issues
    }

    private func checkCOPPACompliance(_ output: String) -> [String] {
        var issues: [String] = []

        // Age-inappropriate content
        if containsAgeInappropriateContent(output) {
            issues.append("Contains content inappropriate for children")
        }

        // Personal info collection
        if requestsPersonalInfo(output) {
            issues.append("Requests personal information from minors")
        }

        return issues
    }

    private func detectsPII(_ text: String) -> Bool {
        // PII detection logic
        return false
    }

    private func containsExcessiveData(_ text: String) -> Bool {
        // Data minimization check
        return false
    }

    private func containsUndeletableReferences(_ text: String) -> Bool {
        // Erasure compliance check
        return false
    }

    private func isProperlySecured(_ text: String, pattern: String) -> Bool {
        // Security check for PHI
        return true
    }

    private func containsAgeInappropriateContent(_ text: String) -> Bool {
        // Age appropriateness check
        return false
    }

    private func requestsPersonalInfo(_ text: String) -> Bool {
        // Personal info request detection
        return false
    }
}

// Usage
let healthcareAgent = Agent(
    role: "Medical Information Assistant",
    purpose: "Provide health information",
    context: "HIPAA-compliant medical assistant",
    guardrails: [
        .noPII,
        PrivacyComplianceGuardrail(regulations: [.hipaa, .gdpr])
    ]
)

public protocol OrbitGuardrail {
    func check(context: GuardrailContext) async throws -> GuardrailResult
}

public struct GuardrailContext {
    public let inputs: [String: String]
    public let output: String?
    public let metadata: [String: String]
    public let agent: Agent?
    public let task: ORTask?
}

public enum GuardrailResult {
    case approved
    case partiallyApproved(feedback: String)
    case needsRevision(feedback: String)
    case validationFailed
}

// Enable guardrails in environment
// .env file
ORBIT_ENABLE_GUARDRAILS=true

// Verify guardrails are enabled
guard ProcessInfo.processInfo.environment["ORBIT_ENABLE_GUARDRAILS"] == "true" else {
    fatalError("Guardrails must be enabled in production")
}

// Use strict validation
let productionTask = ORTask(
    description: "Production task",
    expectedOutput: "Production output",
    validationStrictness: .strict,  // Always strict in production
    guardrails: [
        .noHarmfulContent,
        .noPII,
        .contentFilter,
        ComplianceGuardrail()
    ]
)

// Log all guardrail violations
extension OrbitGuardrail {
    func checkWithLogging(
        context: GuardrailContext
    ) async throws -> GuardrailResult {
        let result = try await check(context: context)

        // Log violations
        switch result {
        case .needsRevision(let feedback),
             .partiallyApproved(let feedback):
            logger.warning("Guardrail violation: \(feedback)")
            GuardrailMonitor.shared.recordViolation(
                guardrail: String(describing: type(of: self)),
                task: context.task?.description ?? "Unknown",
                feedback: feedback
            )
        case .validationFailed:
            logger.error("Guardrail validation failed")
        case .approved:
            break
        }

        return result
    }
}