# 🚀 MHA Flow - Advanced Meta-Heuristic Algorithms Framework

**Version 2.1.0** | Open Source | 142+ Algorithms | AI-Powered | Flask Web Interface

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md)

A professional, production-ready Python framework for meta-heuristic optimization with **Flask web interface**, **universal Levy flight integration**, **custom algorithm upload to GitHub**, **AI-powered recommendations**, and **SQLite/MongoDB database support**.

---

## ✨ What's New in v2.1.0

📤 **Custom Algorithm Upload** - Upload your own algorithms directly through the web interface with automatic validation and registration

🔧 **Enhanced GitHub Integration** - Improved custom algorithm submission workflow with better error handling and local registry

🛠️ **146 Algorithms Fixed** - All algorithms patched for `np.math.gamma`, bounds handling, and shape mismatches

🌐 **Production Flask App** - Enhanced web interface with custom algorithm management and admin dashboard

🔬 **Universal Levy Flight** - All 142+ algorithms now support Levy flight for enhanced exploration

🤖 **AI-Powered Recommender** - Intelligent algorithm selection based on dataset characteristics

💾 **Flexible Database** - SQLite (local) or MongoDB Atlas (cloud) support

📖 **Complete CLI** - Full command-line interface for headless operation

🔐 **User Authentication** - Secure login with personal optimization history tracking

---

## 📊 Key Features

### Core Capabilities
- ✅ **142+ Metaheuristic Algorithms** including evolutionary, swarm, physics-based, and hybrid variants
- 🧬 **Universal Levy Flight** - Integrated across all algorithms for better convergence
- 🔄 **GitHub-Based Custom Algorithms** - Submit your algorithms via GitHub PR workflow
- 🤖 **AI-Powered Recommendations** - Smart algorithm selection based on problem characteristics
- 📊 **Real-Time Visualization** - Live convergence plots and performance metrics
- 💾 **Complete Session Management** - Save, load, and compare optimization runs
- 🌐 **Flask Web Interface** - Professional UI with REST API and admin dashboard
- 📤 **Multiple Export Formats** - CSV, Excel, JSON, PNG, PDF
- 🔐 **Multi-User Support** - Authentication and personal history tracking
- 🖥️ **Full CLI Support** - Complete command-line interface for automation

### Algorithm Categories
- **Swarm Intelligence**: PSO, GWO, WOA, SSA, ALO, GOA, HHO, JS, HBA, MPA, SMA, ChOA, AO, RSA, GTO
- **Evolutionary**: GA, DE, ABC, EP, ES
- **Physics-Based**: SA, GSA, MVO, EO, AOA
- **Hybrid Algorithms**: PSO-GA, GWO-PSO, DE-PSO, JS-PSO, HBA-GWO, MPA-DE, SMA-GA, AO-WOA
- **Custom**: User-uploaded algorithms with automatic integration

---

## 🚀 Quick Start

### Installation

```bash
# Install from source (recommended for development)
git clone https://github.com/Achyut103040/MHA-Algorithm.git
cd MHA-Algorithm
pip install -e .

# Install with web interface
pip install -e .[ui]

# Install complete (all features)
pip install -e .[complete]
```

### Launch the Application

```bash
# Flask web interface (recommended)
python -m mha_toolbox ui
# Then open http://127.0.0.1:5000

# Or using the installed command
mha-flow ui

# Command-line mode
mha-flow list                              # List all algorithms
mha-flow recommend --interactive           # Get recommendations
mha-flow run pso --dataset breast_cancer   # Run algorithm
mha-flow info gwo                          # Algorithm information
mha-flow version                           # Show version
```

---

## 🖥️ CLI Commands Reference

| Command | Description |
|---------|-------------|
| `mha-flow ui` | Launch Flask web interface |
| `mha-flow list` | List all 142+ algorithms |
| `mha-flow recommend` | AI-powered algorithm recommendations |
| `mha-flow run <algo>` | Run algorithm on dataset |
| `mha-flow info <algo>` | Show algorithm details |
| `mha-flow demo` | Run interactive demo |
| `mha-flow version` | Show version info |

### Examples

```bash
# Start web server on custom port
mha-flow ui --port 8080 --debug

# Filter algorithms by category
mha-flow list --category swarm
mha-flow list --category evolution
mha-flow list --category hybrid

# Run with custom parameters
mha-flow run gwo --dataset iris --population_size 50 --max_iterations 200

# Interactive recommendations
mha-flow recommend --interactive
```

For complete CLI documentation, see [docs/CLI_COMMANDS.md](docs/CLI_COMMANDS.md).

---

## 💡 Usage Examples

### 1. Basic Optimization (Python API)

```python
from mha_toolbox import MHAToolbox
from sklearn.datasets import load_iris

# Load dataset
X, y = load_iris(return_X_y=True)

# Initialize toolbox
toolbox = MHAToolbox()

# Run optimization with Levy flight support
result = toolbox.optimize(
    algorithm='pso',
    X=X, 
    y=y,
    population_size=30,
    max_iterations=100,
    levy_enabled=True  # Enable Levy flight
)

# Access results
print(f"Best fitness: {result.best_fitness_:.6f}")
print(f"Runtime: {result.execution_time_:.2f}s")
print(f"Selected features: {result.n_selected_features_}")
```

### 2. Custom Algorithm Upload

```python
from mha_toolbox.custom_algorithm_manager import CustomAlgorithmManager

# Initialize manager
manager = CustomAlgorithmManager()

# Process uploaded algorithm file
result = manager.process_upload(
    file_path='my_custom_algorithm.py',
    metadata={
        'author': 'Your Name',
        'description': 'My innovative MHA algorithm',
        'year': 2025
    }
)

# Check validation status
if result['success']:
    print(f"✓ Algorithm validated: {result['validation']['main_class_name']}")
    print(f"Parameters detected: {result['parameter_mapping']}")
    
    # Integrate into system
    integration = manager.integrate_algorithm(
        file_path='my_custom_algorithm.py',
        parameter_mapping=result['parameter_mapping'],
        category='custom'
    )
    print(f"✓ Algorithm integrated: {integration['algorithm_id']}")
```

### 3. AI-Powered Algorithm Recommendation

```python
from mha_toolbox import AlgorithmRecommender
from mha_toolbox.dataset_intelligence import DatasetIntelligence

# Initialize recommender
recommender = AlgorithmRecommender()

# Analyze dataset
intelligence = DatasetIntelligence()
profile = intelligence.analyze_dataset(X, y)

# Get recommendations
recommendations = recommender.recommend(
    dataset_profile=profile,
    user_preferences={
        'priority': 'accuracy',  # or 'speed', 'balance'
        'expected_features': ['multimodal', 'complex'],
        'time_limit': 60  # seconds
    },
    top_k=5
)

# Display recommendations
for i, rec in enumerate(recommendations, 1):
    print(f"{i}. {rec['algorithm']} (confidence: {rec['confidence']:.2%})")
    print(f"   Reason: {rec['reasoning']}")
```

### 4. Using Levy Flight Directly

```python
from mha_toolbox.algorithms.levy_flight_universal import add_levy_flight_to_position
import numpy as np

# Your algorithm's iteration
current_position = np.random.rand(10)
best_position = np.zeros(10)
bounds = (-100, 100)

# Apply Levy flight
new_position = add_levy_flight_to_position(
    position=current_position,
    best_position=best_position,
    bounds=bounds,
    iteration=10,
    max_iterations=100,
    beta=1.5  # Levy exponent
)

print(f"Position after Levy flight: {new_position}")
```

### 5. Flask Web Interface Usage

```python
# Start the Flask server
# python app.py

# Then use the REST API
import requests

# Upload custom algorithm
files = {'file': open('my_algorithm.py', 'rb')}
response = requests.post('http://localhost:5000/api/upload-algorithm', files=files)
print(response.json())

# Get algorithm recommendations
data = {
    'dataset_size': 1000,
    'n_features': 20,
    'problem_type': 'classification',
    'complexity': 'high'
}
response = requests.post('http://localhost:5000/api/recommend-algorithm', json=data)
print(response.json()['recommendations'])

# Run optimization
optimization_data = {
    'algorithm': 'pso',
    'population_size': 30,
    'max_iterations': 100,
    'levy_enabled': True
}
response = requests.post('http://localhost:5000/api/optimize', json=optimization_data)
print(response.json()['results'])
```

---

## 📚 Documentation

### For Users
- **[Quick Start Guide](docs/QUICK_START.md)** - Get running in 5 minutes
- **[User Manual](docs/USER_MANUAL.md)** - Complete usage guide
- **[Algorithm Catalog](docs/ALGORITHM_CATALOG.md)** - All available algorithms
- **[API Reference](docs/API_REFERENCE.md)** - Python API documentation
- **[Web UI Guide](docs/WEB_UI_GUIDE.md)** - Using the Flask interface

### For Contributors
- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute
- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards
- **[Development Setup](docs/DEVELOPMENT.md)** - Setting up dev environment
- **[Architecture Overview](docs/ARCHITECTURE.md)** - System design
- **[Adding Algorithms](docs/ADDING_ALGORITHMS.md)** - Contribute new algorithms

---

## 🏗️ Architecture

```
MHA-Algorithm/
├── mha_toolbox/                 # Core library
│   ├── algorithms/              # 137+ algorithm implementations
│   │   ├── levy_flight_universal.py  # Universal Levy flight
│   │   ├── base_algorithm.py    # Base classes
│   │   ├── hybrid/              # Hybrid algorithms
│   │   └── custom/              # User-uploaded algorithms
│   ├── levy_flight_engine.py    # Advanced Levy flight engine
│   ├── custom_algorithm_manager.py  # Algorithm upload system
│   ├── algorithm_recommender.py # AI recommendation system
│   ├── dataset_intelligence.py  # Dataset analysis
│   └── complete_algorithm_registry_v2.py  # Algorithm metadata
├── app.py                       # Flask web application
├── templates/                   # HTML templates
├── static/                      # CSS, JS, assets
├── tests/                       # Test suite
└── docs/                        # Documentation

```

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### Ways to Contribute
1. **Add New Algorithms** - Implement and submit new MHA algorithms
2. **Improve Existing Algorithms** - Optimize performance and fix bugs
3. **Enhance Documentation** - Improve guides and examples
4. **Report Issues** - Help us identify and fix problems
5. **Suggest Features** - Share your ideas for improvements

### Contribution Process
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and test thoroughly
4. Commit with clear messages (`git commit -m 'Add amazing feature'`)
5. Push to your branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## 📈 Algorithm Performance Comparison

| Algorithm | Convergence Speed | Exploration | Exploitation | Best For |
|-----------|------------------|-------------|--------------|----------|
| PSO | ⚡⚡⚡⚡⚡ | ⭐⭐⭐⭐ | ⭐⭐⭐ | Fast, continuous |
| GWO | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Multimodal, complex |
| WOA | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Large search space |
| JS | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Dynamic problems |
| HBA | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Robust optimization |
| DE | ⚡⚡⚡ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Numerical optimization |
| GA | ⚡⚡⚡ | ⭐⭐⭐⭐ | ⭐⭐⭐ | Combinatorial problems |
| PSO-GA | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Complex, multimodal |
| HBA-GWO | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | High-dimensional |

---

## 🔬 Research & Citations

If you use MHA Flow in your research, please cite:

```bibtex
@software{mha_flow_2025,
  title={MHA Flow: Advanced Meta-Heuristic Algorithms Framework},
  author={MHA Flow Development Team},
  year={2025},
  version={3.0.0},
  url={https://github.com/yourusername/MHA-Algorithm}
}
```

### Key Papers Implemented
- Kennedy & Eberhart (1995) - Particle Swarm Optimization
- Mirjalili et al. (2014) - Grey Wolf Optimizer
- Mirjalili & Lewis (2016) - Whale Optimization Algorithm
- Chou & Truong (2020) - Jellyfish Search
- Hashim et al. (2021) - Honey Badger Algorithm
- And 130+ more...

---

## 📊 Project Statistics

- **Lines of Code**: 50,000+
- **Algorithms**: 137+
- **Test Coverage**: 85%+
- **Documentation Pages**: 15+
- **Active Contributors**: Open for community
- **GitHub Stars**: ⭐ Star us!

---

## 🛠️ Technical Requirements

### Minimum Requirements
- Python 3.8 or higher
- NumPy >= 1.19.0
- Pandas >= 1.1.0
- Scikit-learn >= 0.23.0
- Flask >= 2.0.0 (for web interface)
- 4GB RAM
- 1GB disk space

### Recommended Setup
- Python 3.10+
- 8GB RAM
- GPU (optional, for large-scale optimization)
- Modern web browser (Chrome, Firefox, Edge)

---

## 🐛 Known Issues & Limitations

- Large datasets (>100k samples) may require significant memory
- Some algorithms are computationally intensive
- Web interface requires modern browser with JavaScript enabled
- Custom algorithm validation is heuristic-based

See [Issues](https://github.com/yourusername/MHA-Algorithm/issues) for current bugs and feature requests.

---

## 🗺️ Roadmap

### Version 3.1 (Q1 2026)
- [ ] GPU acceleration for algorithms
- [ ] Distributed optimization support
- [ ] More visualization options
- [ ] Mobile app interface

### Version 3.2 (Q2 2026)
- [ ] AutoML integration
- [ ] Neural architecture search
- [ ] Cloud deployment options
- [ ] Enhanced benchmarking suite

### Version 4.0 (Q3 2026)
- [ ] Real-time collaborative optimization
- [ ] Advanced analytics dashboard
- [ ] Plugin system for extensions
- [ ] Commercial support options

---

## 📞 Support & Community

- **Documentation**: [Read the Docs](docs/)
- **Issues**: [GitHub Issues](https://github.com/yourusername/MHA-Algorithm/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/MHA-Algorithm/discussions)
- **Email**: support@mhaflow.com
- **Twitter**: @MHAFlow

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

```
MIT License

Copyright (c) 2025 MHA Flow Development Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## 🙏 Acknowledgments

- All algorithm authors and researchers
- Open-source community contributors
- Scientific Python ecosystem (NumPy, SciPy, Scikit-learn)
- Flask and Streamlit teams
- Our amazing community of users and contributors

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=yourusername/MHA-Algorithm&type=Date)](https://star-history.com/#yourusername/MHA-Algorithm&Date)

---

**Made with ❤️ by the MHA Flow Team**

*Empowering researchers and developers with state-of-the-art optimization algorithms*
