superquantx 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

superquantx/__init__.py

@@ -1,38 +1,49 @@
 """SuperQuantX: Experimental Quantum AI Research Platform.
 
-⚠️ RESEARCH SOFTWARE WARNING: This is experimental research software developed by 
-SuperXLab (Superagentic AI Research Division). NOT intended for production use. 
+⚠️ RESEARCH SOFTWARE WARNING: This is experimental research software developed by
+SuperXLab (Superagentic AI Research Division). NOT intended for production use.
 For research and educational purposes only.
 
-Part of SuperXLab's comprehensive quantum research program - the practical implementation 
+Part of SuperXLab's comprehensive quantum research program - the practical implementation
 platform for validating theoretical research in:
     🔬 Quantum-Inspired Agentic Systems: Superposition, interference, entanglement in agents
-    🔬 Quantum Neural Networks (QNNs): Hardware-validated quantum neural architectures  
+    🔬 Quantum Neural Networks (QNNs): Hardware-validated quantum neural architectures
     🔬 QuantumML for AI Training: Quantum-accelerated machine learning techniques
     🔬 Quantinuum Integration: Real hardware validation on H-Series quantum computers
 
 Research Examples:
     Experimental quantum agent research:
         >>> import superquantx as sqx  # EXPERIMENTAL
-        >>> agent = sqx.QuantumTradingAgent(strategy="quantum_portfolio", backend="simulator") 
+        >>> agent = sqx.QuantumTradingAgent(strategy="quantum_portfolio", backend="simulator")
         >>> results = agent.solve(research_data)  # Research use only
         >>> print(f"Research findings: {results.metadata}")
-        
+
     Quantum neural network experiments:
         >>> qnn = sqx.QuantumNN(architecture='hybrid', backend='pennylane')  # EXPERIMENTAL
         >>> qnn.fit(X_research, y_research)  # Research data only
         >>> analysis = qnn.analyze_expressivity()  # Research analysis
-        
+
     Quantum algorithm benchmarking:
-        >>> qsvm = sqx.QuantumSVM(backend='simulator')  # EXPERIMENTAL  
+        >>> qsvm = sqx.QuantumSVM(backend='simulator')  # EXPERIMENTAL
         >>> benchmark = sqx.benchmark_algorithm(qsvm, classical_baseline)
 """
 
 import logging
-from typing import Any, Dict
+from typing import Any
 
 # Core imports - make available at top level
-from . import algorithms, backends, cli, datasets, utils
+from . import algorithms, backends, cli, utils
+
+
+# Import datasets lazily to avoid circular imports
+try:
+    from . import datasets
+except ImportError:
+    # If datasets import fails, create a placeholder
+    import sys
+    import types
+    datasets = types.ModuleType('datasets')
+    sys.modules[f'{__name__}.datasets'] = datasets
 from .config import config, configure
 from .version import __version__
 
@@ -164,7 +175,7 @@ __title__ = "SuperQuantX"
 __description__ = "Experimental Quantum AI Research Platform - NOT for production use"
 __author__ = "SuperXLab - Superagentic AI Research Division"
 __author_email__ = "research@superagentic.ai"
-__license__ = "MIT (Research and Educational Use)"
+__license__ = "Apache-2.0"
 __url__ = "https://github.com/superagentic/superquantx"
 
 # Version information
@@ -172,7 +183,7 @@ def get_version() -> str:
     """Get SuperQuantX version."""
     return __version__
 
-def get_backend_info() -> Dict[str, Any]:
+def get_backend_info() -> dict[str, Any]:
     """Get information about available backends."""
     info = {}
 
@@ -288,6 +299,7 @@ __all__ = [
     "HybridClassifier",
 
     # Common backends
+    "BaseBackend",
     "AutoBackend",
     "QiskitBackend",
     "PennyLaneBackend",

superquantx/algorithms/__init__.py

@@ -6,7 +6,7 @@ make decisions and optimize complex problems independently.
 
 The module is organized in layers:
 - Quantum ML Algorithms: QSVM, VQE, QAOA, Quantum NN
-- Quantum AI Models: Advanced neural networks and transformers  
+- Quantum AI Models: Advanced neural networks and transformers
 - Quantum Agents: Autonomous systems for trading, research, optimization
 - Hybrid Intelligence: Quantum-classical integrated systems
 """

superquantx/algorithms/base_algorithm.py

@@ -8,7 +8,7 @@ import logging
 import time
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Any, Dict, Optional, Union
+from typing import Any
 
 import numpy as np
 
@@ -18,10 +18,10 @@ logger = logging.getLogger(__name__)
 @dataclass
 class QuantumResult:
     """Container for quantum algorithm results.
-    
+
     This class provides a standardized way to return results from quantum
     algorithms, including the main result, metadata, and performance metrics.
-    
+
     Attributes:
         result: The main algorithm result
         metadata: Additional information about the computation
@@ -33,11 +33,11 @@ class QuantumResult:
     """
 
     result: Any
-    metadata: Dict[str, Any]
+    metadata: dict[str, Any]
     execution_time: float
-    backend_info: Dict[str, Any]
-    error: Optional[str] = None
-    intermediate_results: Optional[Dict[str, Any]] = None
+    backend_info: dict[str, Any]
+    error: str | None = None
+    intermediate_results: dict[str, Any] | None = None
 
     def __post_init__(self):
         """Validate and process result after initialization."""
@@ -48,10 +48,10 @@ class QuantumResult:
 
 class BaseQuantumAlgorithm(ABC):
     """Abstract base class for all quantum machine learning algorithms.
-    
+
     This class defines the common interface that all quantum algorithms must
     implement, providing consistency across different algorithm types and backends.
-    
+
     Args:
         backend: Quantum backend to use for computation
         shots: Number of measurement shots (default: 1024)
@@ -63,9 +63,9 @@ class BaseQuantumAlgorithm(ABC):
 
     def __init__(
         self,
-        backend: Union[str, Any],
+        backend: str | Any,
         shots: int = 1024,
-        seed: Optional[int] = None,
+        seed: int | None = None,
         optimization_level: int = 1,
         **kwargs
     ) -> None:
@@ -90,7 +90,7 @@ class BaseQuantumAlgorithm(ABC):
 
         logger.info(f"Initialized {self.__class__.__name__} with backend {type(self.backend).__name__}")
 
-    def _initialize_backend(self, backend: Union[str, Any]) -> Any:
+    def _initialize_backend(self, backend: str | Any) -> Any:
         """Initialize the quantum backend."""
         if isinstance(backend, str):
             # Import here to avoid circular imports
@@ -99,14 +99,14 @@ class BaseQuantumAlgorithm(ABC):
         return backend
 
     @abstractmethod
-    def fit(self, X: np.ndarray, y: Optional[np.ndarray] = None, **kwargs) -> 'BaseQuantumAlgorithm':
+    def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'BaseQuantumAlgorithm':
         """Train the quantum algorithm.
-        
+
         Args:
             X: Training data features
             y: Training data labels (for supervised learning)
             **kwargs: Additional training parameters
-            
+
         Returns:
             Self for method chaining
 
@@ -116,11 +116,11 @@ class BaseQuantumAlgorithm(ABC):
     @abstractmethod
     def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
         """Make predictions using the trained algorithm.
-        
+
         Args:
             X: Input data for prediction
             **kwargs: Additional prediction parameters
-            
+
         Returns:
             Predictions array
 
@@ -129,12 +129,12 @@ class BaseQuantumAlgorithm(ABC):
 
     def score(self, X: np.ndarray, y: np.ndarray, **kwargs) -> float:
         """Compute the algorithm's score on the given test data.
-        
+
         Args:
             X: Test data features
             y: True test data labels
             **kwargs: Additional scoring parameters
-            
+
         Returns:
             Algorithm score (higher is better)
 
@@ -147,12 +147,12 @@ class BaseQuantumAlgorithm(ABC):
         from sklearn.metrics import accuracy_score
         return accuracy_score(y_true, predictions)
 
-    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+    def get_params(self, deep: bool = True) -> dict[str, Any]:
         """Get algorithm parameters.
-        
+
         Args:
             deep: Whether to return deep copy of parameters
-            
+
         Returns:
             Parameter dictionary
 
@@ -168,10 +168,10 @@ class BaseQuantumAlgorithm(ABC):
 
     def set_params(self, **params) -> 'BaseQuantumAlgorithm':
         """Set algorithm parameters.
-        
+
         Args:
             **params: Parameters to set
-            
+
         Returns:
             Self for method chaining
 
@@ -185,7 +185,7 @@ class BaseQuantumAlgorithm(ABC):
 
     def save_model(self, filepath: str) -> None:
         """Save the trained model to disk.
-        
+
         Args:
             filepath: Path where to save the model
 
@@ -212,10 +212,10 @@ class BaseQuantumAlgorithm(ABC):
     @classmethod
     def load_model(cls, filepath: str) -> 'BaseQuantumAlgorithm':
         """Load a trained model from disk.
-        
+
         Args:
             filepath: Path to the saved model
-            
+
         Returns:
             Loaded algorithm instance
 
@@ -235,14 +235,14 @@ class BaseQuantumAlgorithm(ABC):
         logger.info(f"Model loaded from {filepath}")
         return instance
 
-    def benchmark(self, X: np.ndarray, y: Optional[np.ndarray] = None, runs: int = 5) -> Dict[str, Any]:
+    def benchmark(self, X: np.ndarray, y: np.ndarray | None = None, runs: int = 5) -> dict[str, Any]:
         """Benchmark algorithm performance.
-        
+
         Args:
             X: Test data
             y: Test labels (optional)
             runs: Number of benchmark runs
-            
+
         Returns:
             Benchmark results dictionary
 
@@ -281,9 +281,9 @@ class BaseQuantumAlgorithm(ABC):
 
         return results
 
-    def get_circuit_info(self) -> Dict[str, Any]:
+    def get_circuit_info(self) -> dict[str, Any]:
         """Get information about the quantum circuit.
-        
+
         Returns:
             Circuit information dictionary
 
@@ -348,7 +348,7 @@ class UnsupervisedQuantumAlgorithm(BaseQuantumAlgorithm):
         self.n_features_ = None
         self.n_samples_ = None
 
-    def fit(self, X: np.ndarray, y: Optional[np.ndarray] = None, **kwargs) -> 'UnsupervisedQuantumAlgorithm':
+    def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'UnsupervisedQuantumAlgorithm':
         """Fit unsupervised algorithm."""
         self._validate_data(X)
         self.n_features_ = X.shape[1]
@@ -369,14 +369,14 @@ class OptimizationQuantumAlgorithm(BaseQuantumAlgorithm):
         self.optimal_value_ = None
         self.optimization_history_ = []
 
-    def optimize(self, objective_function, initial_params: Optional[np.ndarray] = None, **kwargs) -> QuantumResult:
+    def optimize(self, objective_function, initial_params: np.ndarray | None = None, **kwargs) -> QuantumResult:
         """Optimize objective function.
-        
+
         Args:
             objective_function: Function to optimize
             initial_params: Initial parameter values
             **kwargs: Additional optimization parameters
-            
+
         Returns:
             Optimization result
 

superquantx/algorithms/hybrid_classifier.py

@@ -5,7 +5,7 @@ machine learning components for enhanced performance and flexibility.
 """
 
 import logging
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any
 
 import numpy as np
 from sklearn.ensemble import GradientBoostingClassifier, RandomForestClassifier
@@ -24,14 +24,14 @@ logger = logging.getLogger(__name__)
 
 class HybridClassifier(SupervisedQuantumAlgorithm):
     """Hybrid Classical-Quantum Classifier.
-    
+
     This classifier combines classical and quantum machine learning algorithms
     to leverage the strengths of both approaches. It can operate in different modes:
     - Ensemble: Combines predictions from multiple quantum and classical models
     - Sequential: Uses quantum features as input to classical models
-    - Voting: Majority voting among quantum and classical predictions  
+    - Voting: Majority voting among quantum and classical predictions
     - Stacking: Uses meta-learner to combine quantum and classical predictions
-    
+
     Args:
         backend: Quantum backend for quantum components
         hybrid_mode: Mode of operation ('ensemble', 'sequential', 'voting', 'stacking')
@@ -42,7 +42,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
         meta_learner: Meta-learning algorithm for stacking mode
         shots: Number of measurement shots
         **kwargs: Additional parameters
-        
+
     Example:
         >>> hybrid = HybridClassifier(
         ...     backend='pennylane',
@@ -57,10 +57,10 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
     def __init__(
         self,
-        backend: Union[str, Any],
+        backend: str | Any,
         hybrid_mode: str = 'ensemble',
-        quantum_algorithms: Optional[List[str]] = None,
-        classical_algorithms: Optional[List[str]] = None,
+        quantum_algorithms: list[str] | None = None,
+        classical_algorithms: list[str] | None = None,
         quantum_weight: float = 0.5,
         feature_selection: bool = False,
         meta_learner: str = 'logistic_regression',
@@ -153,7 +153,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
             from sklearn.feature_selection import SelectKBest, f_classif
             self.feature_selector = SelectKBest(score_func=f_classif, k='all')
 
-    def _apply_feature_selection(self, X: np.ndarray, y: Optional[np.ndarray] = None) -> np.ndarray:
+    def _apply_feature_selection(self, X: np.ndarray, y: np.ndarray | None = None) -> np.ndarray:
         """Apply quantum-inspired feature selection."""
         if not self.feature_selection or self.feature_selector is None:
             return X
@@ -172,7 +172,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
         logger.info(f"Feature selection: {X.shape[1]} -> {X_selected.shape[1]} features")
         return X_selected
 
-    def _train_quantum_models(self, X: np.ndarray, y: np.ndarray) -> Dict[str, float]:
+    def _train_quantum_models(self, X: np.ndarray, y: np.ndarray) -> dict[str, float]:
         """Train quantum models and return their scores."""
         scores = {}
 
@@ -194,7 +194,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
         return scores
 
-    def _train_classical_models(self, X: np.ndarray, y: np.ndarray) -> Dict[str, float]:
+    def _train_classical_models(self, X: np.ndarray, y: np.ndarray) -> dict[str, float]:
         """Train classical models and return their scores."""
         scores = {}
 
@@ -216,7 +216,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
         return scores
 
-    def _get_base_predictions(self, X: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    def _get_base_predictions(self, X: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
         """Get predictions from all base models."""
         quantum_preds = []
         classical_preds = []
@@ -367,12 +367,12 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
     def fit(self, X: np.ndarray, y: np.ndarray, **kwargs) -> 'HybridClassifier':
         """Train the hybrid classifier.
-        
+
         Args:
             X: Training data features
             y: Training data labels
             **kwargs: Additional training parameters
-            
+
         Returns:
             Self for method chaining
 
@@ -460,11 +460,11 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
     def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
         """Make predictions using the hybrid classifier.
-        
+
         Args:
             X: Input data for prediction
             **kwargs: Additional prediction parameters
-            
+
         Returns:
             Predicted labels
 
@@ -496,11 +496,11 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
     def predict_proba(self, X: np.ndarray, **kwargs) -> np.ndarray:
         """Predict class probabilities.
-        
+
         Args:
             X: Input data for prediction
             **kwargs: Additional parameters
-            
+
         Returns:
             Predicted class probabilities
 
@@ -556,7 +556,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
         return prob_matrix
 
-    def get_model_performance(self) -> Dict[str, Any]:
+    def get_model_performance(self) -> dict[str, Any]:
         """Get detailed performance metrics for all models."""
         performance = {
             'quantum_scores': self.quantum_scores.copy(),
@@ -580,11 +580,11 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
 
         return performance
 
-    def get_feature_importance(self) -> Optional[np.ndarray]:
+    def get_feature_importance(self) -> np.ndarray | None:
         """Get feature importance from feature selection."""
         return self.feature_importance_
 
-    def cross_validate(self, X: np.ndarray, y: np.ndarray, cv: int = 5) -> Dict[str, Any]:
+    def cross_validate(self, X: np.ndarray, y: np.ndarray, cv: int = 5) -> dict[str, Any]:
         """Perform cross-validation on the hybrid classifier."""
         if not self.is_fitted:
             raise ValueError("Model must be fitted before cross-validation")
@@ -604,7 +604,7 @@ class HybridClassifier(SupervisedQuantumAlgorithm):
             logger.error(f"Cross-validation failed: {e}")
             return {'error': str(e)}
 
-    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+    def get_params(self, deep: bool = True) -> dict[str, Any]:
         """Get hybrid classifier parameters."""
         params = super().get_params(deep)
         params.update({

superquantx/algorithms/qaoa.py

@@ -5,7 +5,8 @@ problems using quantum circuits with parameterized gates.
 """
 
 import logging
-from typing import Any, Callable, Dict, Optional, Tuple, Union
+from collections.abc import Callable
+from typing import Any
 
 import numpy as np
 from scipy.optimize import minimize
@@ -17,28 +18,28 @@ logger = logging.getLogger(__name__)
 
 class QAOA(OptimizationQuantumAlgorithm):
     """Quantum Approximate Optimization Algorithm for combinatorial optimization.
-    
+
     QAOA is a hybrid quantum-classical algorithm that alternates between
     quantum evolution and classical parameter optimization to find approximate
     solutions to combinatorial optimization problems.
-    
+
     The algorithm works by:
     1. Preparing an initial superposition state
     2. Applying alternating problem and mixer Hamiltonians
     3. Measuring the quantum state
     4. Classically optimizing the parameters
-    
+
     Args:
         backend: Quantum backend for circuit execution
         p: Number of QAOA layers (depth)
         problem_hamiltonian: Problem Hamiltonian function
-        mixer_hamiltonian: Mixer Hamiltonian function  
+        mixer_hamiltonian: Mixer Hamiltonian function
         initial_state: Initial quantum state preparation
         optimizer: Classical optimizer ('COBYLA', 'L-BFGS-B', etc.)
         shots: Number of measurement shots
         maxiter: Maximum optimization iterations
         **kwargs: Additional parameters
-        
+
     Example:
         >>> # Define Max-Cut problem
         >>> def problem_ham(gamma, graph):
@@ -50,10 +51,10 @@ class QAOA(OptimizationQuantumAlgorithm):
 
     def __init__(
         self,
-        backend: Union[str, Any],
+        backend: str | Any,
         p: int = 1,
-        problem_hamiltonian: Optional[Callable] = None,
-        mixer_hamiltonian: Optional[Callable] = None,
+        problem_hamiltonian: Callable | None = None,
+        mixer_hamiltonian: Callable | None = None,
         initial_state: str = 'uniform_superposition',
         optimizer: str = 'COBYLA',
         shots: int = 1024,
@@ -109,10 +110,10 @@ class QAOA(OptimizationQuantumAlgorithm):
 
     def _create_qaoa_circuit(self, params: np.ndarray) -> Any:
         """Create QAOA circuit with given parameters.
-        
+
         Args:
             params: Array of [gamma_1, beta_1, ..., gamma_p, beta_p]
-            
+
         Returns:
             Quantum circuit
 
@@ -147,10 +148,10 @@ class QAOA(OptimizationQuantumAlgorithm):
 
     def _objective_function(self, params: np.ndarray) -> float:
         """QAOA objective function to minimize.
-        
+
         Args:
             params: Circuit parameters
-            
+
         Returns:
             Negative expectation value (for minimization)
 
@@ -188,14 +189,14 @@ class QAOA(OptimizationQuantumAlgorithm):
         logger.warning("Using fallback circuit execution")
         return np.random.random()  # Placeholder
 
-    def fit(self, X: np.ndarray, y: Optional[np.ndarray] = None, **kwargs) -> 'QAOA':
+    def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'QAOA':
         """Fit QAOA to problem instance.
-        
+
         Args:
             X: Problem instance data (e.g., adjacency matrix for Max-Cut)
             y: Not used in QAOA
             **kwargs: Additional parameters
-            
+
         Returns:
             Self for method chaining
 
@@ -222,11 +223,11 @@ class QAOA(OptimizationQuantumAlgorithm):
 
     def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
         """Get optimal solution from QAOA results.
-        
+
         Args:
             X: Problem instance (not used if same as training)
             **kwargs: Additional parameters
-            
+
         Returns:
             Optimal bit string solution
 
@@ -249,14 +250,14 @@ class QAOA(OptimizationQuantumAlgorithm):
 
         return best_solution
 
-    def _run_optimization(self, objective_function, initial_params: Optional[np.ndarray] = None, **kwargs):
+    def _run_optimization(self, objective_function, initial_params: np.ndarray | None = None, **kwargs):
         """Run QAOA optimization.
-        
+
         Args:
             objective_function: Function to optimize (ignored, uses internal)
             initial_params: Initial parameter guess
             **kwargs: Additional optimization parameters
-            
+
         Returns:
             Optimization result
 
@@ -313,13 +314,13 @@ class QAOA(OptimizationQuantumAlgorithm):
         betas = np.random.uniform(*self.beta_bounds, self.p)
         return np.concatenate([gammas, betas])
 
-    def get_optimization_landscape(self, param_range: Tuple[float, float], resolution: int = 50) -> Dict[str, Any]:
+    def get_optimization_landscape(self, param_range: tuple[float, float], resolution: int = 50) -> dict[str, Any]:
         """Compute optimization landscape for visualization.
-        
+
         Args:
             param_range: Range of parameters to explore
             resolution: Number of points per dimension
-            
+
         Returns:
             Dictionary with landscape data
 
@@ -345,12 +346,12 @@ class QAOA(OptimizationQuantumAlgorithm):
             'optimal_params': self.optimal_params_ if hasattr(self, 'optimal_params_') else None
         }
 
-    def analyze_solution_quality(self, true_optimum: Optional[float] = None) -> Dict[str, Any]:
+    def analyze_solution_quality(self, true_optimum: float | None = None) -> dict[str, Any]:
         """Analyze quality of QAOA solution.
-        
+
         Args:
             true_optimum: Known optimal value for comparison
-            
+
         Returns:
             Analysis results
 
@@ -384,7 +385,7 @@ class QAOA(OptimizationQuantumAlgorithm):
 
         return analysis
 
-    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+    def get_params(self, deep: bool = True) -> dict[str, Any]:
         """Get QAOA parameters."""
         params = super().get_params(deep)
         params.update({