avra-cadavra/.cursor/skills/quantum-matching-algorithms

Quantum Matching Algorithms

Core Principle

Quantum matching uses quantum state inner products to calculate compatibility between entities (users, spots, events).

World Model Transition Notice

IMPORTANT: All hardcoded compatibility formulas (weights like 50/25/25, 60/40, etc.) in this skill are being systematically replaced by learned energy functions per Master Plan Phase 4. The quantum state calculations themselves (inner products, fidelity) are preserved as inputs to the world model's state encoder (Phase 3.1.1: 24D quantum vibe state). Only the weighted combination formulas are replaced.

When implementing new matching logic:

• ✅ Use quantum state calculations (inner products, fidelity) as features
• ✅ Feed quantum features into WorldModelFeatureExtractor → state encoder → energy function
• ❌ Do NOT create new hardcoded weight combinations
• ❌ Do NOT add new weight * score + weight * score formulas

Reference: docs/MASTER_PLAN.md Phase 4.2 (Formula Replacement Schedule)

Quantum State Representation

Create Quantum State

/// Create quantum state from personality dimensions
QuantumState createPersonalityQuantumState(PersonalityProfile profile) {
  // Convert 12-dimensional personality to quantum state
  final dimensions = profile.dimensions;
  
  return QuantumState(
    // Quantum state vector from dimensions
    vector: _dimensionsToQuantumVector(dimensions),
    // Normalize to unit vector
    normalized: true,
  );
}

Quantum State Inner Product

/// Calculate quantum inner product (fidelity)
double calculateQuantumFidelity(
  QuantumState stateA,
  QuantumState stateB,
) {
  // Inner product: <stateA | stateB>
  final innerProduct = _quantumInnerProduct(stateA, stateB);
  
  // Fidelity: |<stateA | stateB>|²
  final fidelity = (innerProduct.abs() * innerProduct.abs());
  
  return fidelity.clamp(0.0, 1.0);
}

Compatibility Calculation

Basic Quantum Compatibility

/// Calculate quantum compatibility between two entities
double calculateQuantumCompatibility(
  PersonalityProfile profileA,
  PersonalityProfile profileB,
) {
  // Create quantum states
  final stateA = createPersonalityQuantumState(profileA);
  final stateB = createPersonalityQuantumState(profileB);
  
  // Calculate fidelity
  final fidelity = calculateQuantumFidelity(stateA, stateB);
  
  return fidelity;
}

Enhanced Quantum Compatibility

/// Enhanced quantum compatibility with multiple factors
double calculateEnhancedQuantumCompatibility({
  required PersonalityProfile profileA,
  required PersonalityProfile profileB,
  double archetypeWeight = 0.25,
  double valueWeight = 0.25,
  double quantumWeight = 0.50,
}) {
  // 1. Quantum dimension compatibility (50%)
  final quantumCompat = calculateQuantumCompatibility(profileA, profileB);
  
  // 2. Archetype compatibility (25%)
  final archetypeCompat = _calculateArchetypeCompatibility(
    profileA.archetype,
    profileB.archetype,
  );
  
  // 3. Value alignment (25%)
  final valueAlignment = _calculateValueAlignment(
    profileA.dimensions,
    profileB.dimensions,
  );
  
  // Combined compatibility
  final compatibility = (
    quantumWeight * quantumCompat +
    archetypeWeight * archetypeCompat +
    valueWeight * valueAlignment
  );
  
  return compatibility.clamp(0.0, 1.0);
}

Hybrid Compatibility (Core + Modifiers)

/// Hybrid compatibility: Core factors (geometric mean) + Modifiers (weighted average)
double calculateHybridCompatibility({
  required double quantumFidelity,
  required double locationCompatibility,
  required double timingCompatibility,
  double? knotCompatibility,
}) {
  // Core factors: Geometric mean (catches critical failures)
  final coreFactors = <double>[quantumFidelity];
  if (knotCompatibility != null) {
    coreFactors.add(knotCompatibility);
  }
  final coreScore = _geometricMean(coreFactors);
  
  // Modifiers: Weighted average (enhance good matches)
  final modifierScore = (
    0.6 * locationCompatibility +
    0.4 * timingCompatibility
  );
  
  // Hybrid combination: core * modifiers
  final compatibility = coreScore * modifierScore;
  
  return compatibility.clamp(0.0, 1.0);
}

double _geometricMean(List<double> values) {
  if (values.isEmpty) return 0.0;
  if (values.any((v) => v <= 0.0)) {
    return 0.0; // Geometric mean requires all positive
  }
  
  final product = values.reduce((a, b) => a * b);
  final mean = pow(product, 1.0 / values.length);
  return mean;
}

Multi-Entity Matching

User-to-Targets Fidelity

/// Calculate compatibility between user and multiple targets
double calculateUserToTargetsFidelity({
  required QuantumEntityState userState,
  required List<QuantumEntityState> allStates,
}) {
  final userVector = _quantumEntityStateToVector(userState);
  var total = 0.0;
  var count = 0;
  
  for (final state in allStates) {
    if (state.entityType == QuantumEntityType.user) {
      continue; // Skip user's own state
    }
    
    final targetVector = _quantumEntityStateToVector(state);
    total += _cosineSimilarity(userVector, targetVector);
    count++;
  }
  
  if (count == 0) return 0.5; // Neutral fallback
  return (total / count).clamp(0.0, 1.0);
}

Location Quantum State

Location Compatibility

/// Calculate location compatibility using quantum states
double calculateLocationCompatibility({
  required Location locationA,
  required Location locationB,
}) {
  // Create location quantum states
  final stateA = _createLocationQuantumState(
    latitude: locationA.latitude,
    longitude: locationA.longitude,
    type: locationA.type,
    accessibility: locationA.accessibility,
    vibe: locationA.vibe,
  );
  
  final stateB = _createLocationQuantumState(
    latitude: locationB.latitude,
    longitude: locationB.longitude,
    type: locationB.type,
    accessibility: locationB.accessibility,
    vibe: locationB.vibe,
  );
  
  // Calculate compatibility
  final compatibility = abs(_innerProduct(stateA, stateB)) * 
                       abs(_innerProduct(stateA, stateB));
  
  return compatibility.clamp(0.0, 1.0);
}

Quantum Matching Service Pattern

/// Quantum matching service
class QuantumMatchingService {
  /// Calculate compatibility between user and event
  Future<double> calculateUserEventCompatibility({
    required User user,
    required Event event,
  }) async {
    // Create quantum states
    final userState = createPersonalityQuantumState(user.personality);
    final eventState = createEventQuantumState(event);
    
    // Calculate quantum fidelity
    final quantumFidelity = calculateQuantumFidelity(userState, eventState);
    
    // Calculate location compatibility
    final locationCompat = calculateLocationCompatibility(
      locationA: user.location,
      locationB: event.location,
    );
    
    // Calculate timing compatibility
    final timingCompat = _calculateTimingCompatibility(
      user.preferences,
      event.timing,
    );
    
    // Hybrid compatibility
    return calculateHybridCompatibility(
      quantumFidelity: quantumFidelity,
      locationCompatibility: locationCompat,
      timingCompatibility: timingCompat,
    );
  }
}

Reference

• lib/core/controllers/quantum_matching_controller.dart - Quantum matching controller
• lib/core/services/quantum/quantum_matching_integration_service.dart - Integration service
• packages/avrai_quantum/ - Quantum calculation packages