Apply Composer changes: comprehensive API updates, migrations, middleware, and infrastructure improvements
- Add comprehensive database migrations (001-024) for schema evolution - Enhance API schema with expanded type definitions and resolvers - Add new middleware: audit logging, rate limiting, MFA enforcement, security, tenant auth - Implement new services: AI optimization, billing, blockchain, compliance, marketplace - Add adapter layer for cloud integrations (Cloudflare, Kubernetes, Proxmox, storage) - Update Crossplane provider with enhanced VM management capabilities - Add comprehensive test suite for API endpoints and services - Update frontend components with improved GraphQL subscriptions and real-time updates - Enhance security configurations and headers (CSP, CORS, etc.) - Update documentation and configuration files - Add new CI/CD workflows and validation scripts - Implement design system improvements and UI enhancements
This commit is contained in:
defiQUG
181
docs/fairness-audit/ORCHESTRATION_ENGINE.md
Normal file
181
docs/fairness-audit/ORCHESTRATION_ENGINE.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Fairness Audit Orchestration Engine
|
||||
|
||||
## Overview
|
||||
|
||||
The Fairness Audit Orchestration Engine uses a **3-variable model** to size and schedule fairness audit processes. The engine designs from outputs backwards, calculating the total process load and validating feasibility against requested timelines.
|
||||
|
||||
## The 3-Variable Model
|
||||
|
||||
### Variables
|
||||
|
||||
1. **I (Input)**: Input size/effort
|
||||
- Dataset size
|
||||
- Number of sensitive attributes
|
||||
- Date range complexity
|
||||
- Filter complexity
|
||||
|
||||
2. **O (Output)**: Total output effort
|
||||
- Sum of all selected outputs (reports, dashboards, exports, alerts)
|
||||
- Each output type has a weight
|
||||
|
||||
3. **T (Timeline)**: Runtime allocation
|
||||
- Execution mode (now, scheduled, continuous)
|
||||
- SLA/time limit
|
||||
- Deadline
|
||||
|
||||
## Backend Logic
|
||||
|
||||
### Formula
|
||||
|
||||
```
|
||||
Total Process Load ≈ O + 2I ≈ 3.2I
|
||||
```
|
||||
|
||||
Where:
|
||||
- **O** = Sum of all output weights
|
||||
- **2I** = Two input passes (ingestion + enrichment + fairness evaluation)
|
||||
- **3.2I** = Target total load (design target: O ≈ 1.2 × I)
|
||||
|
||||
### Calculation Flow
|
||||
|
||||
1. **Start with Outputs**
|
||||
- User selects desired outputs
|
||||
- Engine sums output weights → **O**
|
||||
|
||||
2. **Calculate Input Load**
|
||||
- Engine analyzes input specification
|
||||
- Calculates input complexity → **I**
|
||||
|
||||
3. **Calculate Total Load**
|
||||
- Total = O + 2I
|
||||
- Validates against target: ≈ 3.2I
|
||||
|
||||
4. **Estimate Time**
|
||||
- Uses processing rates to estimate runtime
|
||||
- Validates against timeline constraints
|
||||
|
||||
5. **Feasibility Check**
|
||||
- Compares estimated time vs. requested timeline
|
||||
- Checks output load vs. recommended (1.2 × I)
|
||||
- Provides warnings and suggestions
|
||||
|
||||
## Output Types and Weights
|
||||
|
||||
| Output Type | Weight | Description |
|
||||
|------------|--------|-------------|
|
||||
| Fairness Audit PDF | 2.5 | Comprehensive fairness audit report |
|
||||
| Metrics Export (SPD, TPR, FPR) | 1.0 | Statistical parity difference, rates |
|
||||
| Flagged Cases CSV | 1.5 | Cases flagged for potential bias |
|
||||
| Executive Summary Slides | 2.0 | Executive presentation slides |
|
||||
| Detailed Report (JSON) | 1.2 | Machine-readable detailed analysis |
|
||||
| Alert Configuration | 0.8 | Automated alert rules |
|
||||
| Dashboard Export | 1.8 | Interactive dashboard |
|
||||
| Compliance Report | 2.2 | Regulatory compliance documentation |
|
||||
|
||||
## Input Load Calculation
|
||||
|
||||
```typescript
|
||||
Input Load = Base (100)
|
||||
+ Sensitive Attributes (20 each)
|
||||
+ Date Range (5 per day)
|
||||
+ Filters (10 each)
|
||||
```
|
||||
|
||||
Or use pre-calculated `estimatedSize` if available.
|
||||
|
||||
## Processing Rates
|
||||
|
||||
- **Input Processing**: 15 units/second
|
||||
- **Output Processing**: 8 units/second
|
||||
- **Average Rate**: ~11.5 units/second
|
||||
|
||||
## User-Facing Messages
|
||||
|
||||
### Feasible Configuration
|
||||
> "This fairness audit will process approximately X input units and generate Y output units, taking approximately Z to complete."
|
||||
|
||||
### Feasible with Warnings
|
||||
> "This audit is feasible but has some considerations: [warnings]. Estimated time: Z."
|
||||
|
||||
### Not Feasible
|
||||
> "This audit configuration may not be feasible within the requested timeline. [warnings]. Estimated time: Z."
|
||||
|
||||
## Example Scenarios
|
||||
|
||||
### Scenario 1: Small Dataset, Few Outputs
|
||||
- **Input**: 100 units (small dataset, 2 attributes)
|
||||
- **Outputs**: Metrics Export (1.0) + Flagged Cases CSV (1.5) = 2.5 units
|
||||
- **Total Load**: 2.5 + (2 × 100) = 202.5 units
|
||||
- **Estimated Time**: ~18 seconds
|
||||
- **Result**: ✅ Feasible
|
||||
|
||||
### Scenario 2: Large Dataset, Many Outputs
|
||||
- **Input**: 500 units (large dataset, 5 attributes, 30-day range)
|
||||
- **Outputs**: All 8 outputs = 13.0 units
|
||||
- **Total Load**: 13.0 + (2 × 500) = 1013.0 units
|
||||
- **Estimated Time**: ~88 seconds
|
||||
- **Result**: ⚠️ May need timeline adjustment
|
||||
|
||||
### Scenario 3: Output-Heavy Request
|
||||
- **Input**: 200 units
|
||||
- **Outputs**: All outputs = 13.0 units
|
||||
- **Target Output**: 200 × 1.2 = 240 units
|
||||
- **Actual Output**: 13.0 units
|
||||
- **Result**: ✅ Within target (O < 1.2 × I)
|
||||
|
||||
## Implementation
|
||||
|
||||
### Backend Engine
|
||||
- Location: `api/src/services/fairness-orchestration/engine.ts`
|
||||
- Provides: `orchestrate()`, calculation functions, feasibility checks
|
||||
|
||||
### Frontend Component
|
||||
- Location: `portal/src/components/fairness/FairnessOrchestrationWizard.tsx`
|
||||
- 3-column layout: Output | Input | Timeline
|
||||
- Real-time orchestration calculation
|
||||
- Visual feedback on feasibility
|
||||
|
||||
### Client Library
|
||||
- Location: `portal/src/lib/fairness-orchestration.ts`
|
||||
- Shared types and calculation functions
|
||||
- Can be used client-side or called via API
|
||||
|
||||
## API Endpoints (To Be Implemented)
|
||||
|
||||
```
|
||||
POST /api/fairness/orchestrate
|
||||
Body: OrchestrationRequest
|
||||
Response: OrchestrationResult
|
||||
|
||||
GET /api/fairness/outputs
|
||||
Response: OutputType[]
|
||||
|
||||
POST /api/fairness/run
|
||||
Body: OrchestrationRequest
|
||||
Response: Job ID and status
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Adjustable Constants
|
||||
|
||||
```typescript
|
||||
INPUT_PASS_MULTIPLIER = 2.0 // 2 × I for input passes
|
||||
TOTAL_LOAD_MULTIPLIER = 3.2 // Target: O + 2I ≈ 3.2I
|
||||
OUTPUT_TARGET_MULTIPLIER = 1.2 // Design target: O ≈ 1.2 × I
|
||||
INPUT_PROCESSING_RATE = 15 // units/second
|
||||
OUTPUT_PROCESSING_RATE = 8 // units/second
|
||||
```
|
||||
|
||||
### Tuning Recommendations
|
||||
|
||||
- **High-volume scenarios**: Increase processing rates
|
||||
- **Complex outputs**: Adjust output weights
|
||||
- **Strict SLAs**: Add buffer time (20% recommended)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Orchestration Engine Design](./ORCHESTRATION_DESIGN.md)
|
||||
- [Output Weight Guidelines](./OUTPUT_WEIGHTS.md)
|
||||
- [User Guide](../fairness-audit/USER_GUIDE.md)
|
||||
|
||||
Reference in New Issue
Block a user