{"id":25437703,"url":"https://github.com/christianlin0420/multi-agent-universal","last_synced_at":"2026-02-12T02:09:37.980Z","repository":{"id":270955811,"uuid":"910705745","full_name":"ChristianLin0420/multi-agent-universal","owner":"ChristianLin0420","description":"A comprehensive Multi-Agent Reinforcement Learning framework for research and development, featuring distributed training and multiple environment support.","archived":false,"fork":false,"pushed_at":"2025-01-04T10:04:40.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-03T02:34:53.317Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChristianLin0420.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-01T06:14:03.000Z","updated_at":"2025-01-09T01:37:34.000Z","dependencies_parsed_at":"2025-01-04T21:33:07.695Z","dependency_job_id":null,"html_url":"https://github.com/ChristianLin0420/multi-agent-universal","commit_stats":null,"previous_names":["christianlin0420/multi-agent-universal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChristianLin0420/multi-agent-universal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianLin0420%2Fmulti-agent-universal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianLin0420%2Fmulti-agent-universal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianLin0420%2Fmulti-agent-universal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianLin0420%2Fmulti-agent-universal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChristianLin0420","download_url":"https://codeload.github.com/ChristianLin0420/multi-agent-universal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianLin0420%2Fmulti-agent-universal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29354709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-17T09:19:29.074Z","updated_at":"2026-02-12T02:09:37.966Z","avatar_url":"https://github.com/ChristianLin0420.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-Agent-Universal 🤖\n\n\u003e A comprehensive Multi-Agent Reinforcement Learning framework for research and development, featuring distributed training and multiple environment support.\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n## 🌟 Introduction\n\nMARL Framework is a scalable and modular platform designed for Multi-Agent Reinforcement Learning research and applications. It provides a unified interface for training, evaluating, and deploying MARL agents across various environments.\n\n### Why MARL Framework?\n\n- **Unified Interface**: Consistent API across different algorithms and environments\n- **Scalability**: From single-GPU training to distributed multi-GPU setups\n- **Modularity**: Easy to extend with new algorithms and environments\n- **Research Ready**: Built-in logging, visualization, and experiment management\n- **Production Grade**: Deployment tools for model serving\n\n### Key Design Principles\n\n1. **Flexibility**: \n   - Plug-and-play architecture for algorithms and environments\n   - Customizable reward functions and observation spaces\n   - Configurable training parameters\n\n2. **Reproducibility**:\n   - Comprehensive logging system\n   - Configuration management\n   - Experiment tracking\n   - Seed control\n\n3. **Performance**:\n   - Optimized data handling\n   - Efficient experience replay\n   - Distributed training support\n   - GPU acceleration\n\n### Core Components\n\n```\nmarl_framework/\n├── algorithms/          # MARL algorithms (QMIX, MAPPO)\n├── environments/        # Environment wrappers\n├── training/           # Training infrastructure\n├── evaluation/         # Evaluation tools\n├── deployment/         # Deployment utilities\n└── utils/             # Common utilities\n```\n\n### Supported Tasks\n\n1. **Cooperative Navigation**\n   - Multi-agent pathfinding\n   - Formation control\n   - Swarm behavior\n\n2. **Team Sports**\n   - Football scenarios\n   - Strategic team play\n   - Role-based coordination\n\n3. **Combat Scenarios**\n   - StarCraft II battles\n   - Tactical decision making\n   - Resource management\n\n## 🌟 Features\n\nOur framework provides a comprehensive suite of features designed to support both research and practical applications in multi-agent reinforcement learning.\n\n### 🎮 Supported Environments\nEach environment is carefully wrapped to provide consistent interfaces while maintaining their unique characteristics:\n\n- **StarCraft II (SMAC)**\n  - Challenging micro-management scenarios\n  - Rich observation and state spaces\n  - Multiple battle scenarios (3m, 8m, 2s3z, etc.)\n  - Configurable difficulty levels (1-7)\n  - Built-in reward shaping options\n  - Detailed battle statistics tracking\n\n- **Google Research Football**\n  - Realistic football simulation\n  - Multiple game formats (3v3, 5v5, 11v11)\n  - Academy learning scenarios for skill development\n  - Customizable rewards and scenarios\n  - Built-in performance metrics\n  - Replay saving and analysis\n\n- **Multi-Agent Particle (MPE)**\n  - Lightweight 2D physics simulation\n  - Perfect for algorithm prototyping\n  - Cooperative/competitive scenarios\n  - Customizable agent dynamics\n  - Easy visualization\n  - Fast execution speed\n\n### 🧠 Algorithms\nOur implemented algorithms represent state-of-the-art approaches in MARL:\n\n- **QMIX**\n  - Value-based MARL algorithm\n  - Monotonic value function factorization\n  - Centralized training with decentralized execution\n  - Efficient experience replay system\n  - Hyperparameter optimization ready\n\n- **MAPPO**\n  - Policy-based MARL algorithm\n  - Multi-agent version of PPO\n  - Shared critic network architecture\n  - GAE advantage estimation\n  - Adaptive learning rate\n\n### 🛠️ Core Features\nEssential tools and utilities for effective MARL development:\n\n- **Distributed Training**\n  - PyTorch DDP integration\n  - Multi-GPU synchronization\n  - Efficient batch processing\n  - Customizable worker processes\n  - Automatic checkpoint management\n\n- **Visualization Tools**\n  - Real-time training curves\n  - Agent trajectory visualization\n  - Interactive environment rendering\n  - Custom metric plotting\n  - WandB integration\n\n## 📦 Installation\n\nOur installation process is streamlined to get you started quickly while ensuring all dependencies are properly set up.\n\n### Prerequisites\n- Python 3.8 or higher\n- CUDA-capable GPU (for distributed training)\n- StarCraft II (for SMAC environment)\n- Git\n\n```bash\n# Clone repository\ngit clone https://github.com/username/marl_framework.git\ncd multi-agent-universal\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # Linux/Mac\n# or\n.\\venv\\Scripts\\activate   # Windows\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install environment dependencies\nbash install_environments.sh\n```\n\n## 🚀 Quick Start\n\nGet started with MARL Framework in minutes. Our quick start guide covers the essential workflows:\n\n### Training\nThe training system supports both single-GPU and distributed training modes with automatic logging and checkpointing:\n\n```bash\n# Single GPU training\npython scripts/train.py \\\n    --config configs/qmix_smac.yaml \\\n    --experiment_name my_first_run\n\n# Distributed training (multi-GPU)\npython scripts/train.py \\\n    --config configs/mappo_football.yaml \\\n    --distributed \\\n    --world_size 2\n```\n\n### Advanced Training Options\n```bash\n# Training with custom hyperparameters\npython scripts/train.py \\\n    --config configs/qmix_smac.yaml \\\n    --experiment_name custom_run \\\n    --override_config training.batch_size=64 algorithm.lr=0.0001\n\n# Training with specific GPU devices\nCUDA_VISIBLE_DEVICES=0,1 python scripts/train.py \\\n    --config configs/mappo_football.yaml \\\n    --distributed \\\n    --world_size 2\n```\n\n### Evaluation\n\n```bash\n# Evaluate model\npython scripts/evaluate.py \\\n    --config configs/eval.yaml \\\n    --checkpoint path/to/model.pt \\\n    --render\n```\n\n### Deployment\n\n```bash\n# Start model server\npython scripts/deploy.py \\\n    --config configs/deploy.yaml \\\n    --port 8000\n```\n\n## 📝 Configuration Guide\n\nOur configuration system is designed to be flexible and maintainable, supporting inheritance and override capabilities.\n\n### Configuration Hierarchy\n```\nconfigs/\n├── base/                  # Base configurations\n│   ├── algorithm/        # Algorithm-specific bases\n│   └── environment/      # Environment-specific bases\n├── experiments/          # Experiment configurations\n└── deployment/          # Deployment configurations\n```\n\n### Basic Structure\n```yaml\n# configs/example.yaml\nalgorithm:\n  type: \"qmix\"\n  hidden_dim: 64\n  lr: 0.001\n\nenvironment:\n  type: \"smac\"\n  map_name: \"3m\"\n  difficulty: \"7\"\n\ntraining:\n  max_episodes: 10000\n  batch_size: 32\n```\n\n### Config Inheritance\n```yaml\n# Base config (base.yaml)\nalgorithm:\n  type: \"qmix\"\n  gamma: 0.99\n\n# Extended config (extended.yaml)\nincludes: [\"base.yaml\"]\nenvironment:\n  type: \"smac\"\n```\n\n## 📊 Experiment Management\n\nOur experiment management system helps track, analyze, and compare different runs:\n\n### Features\n- Automatic experiment versioning\n- Comprehensive metric logging\n- Resource usage tracking\n- Visualization tools\n- Easy experiment comparison\n\n### Directory Structure\n```\nexperiments/\n├── run_name/\n│   ├── checkpoints/     # Model checkpoints\n│   ├── logs/           # Training logs\n│   ├── plots/          # Visualizations\n│   └── config.json     # Experiment config\n```\n\n### Logging Example\n```python\nfrom marl_framework.utils.logger import Logger\n\nlogger = Logger(\n    config=config,\n    experiment_name=\"my_experiment\"\n)\n\n# Log metrics\nlogger.log_metrics(\n    metrics={\"reward\": 10.5},\n    step=100\n)\n```\n\n## 🔧 Development Guide\n\n### Adding New Algorithm\n\n1. Create directory structure:\n```bash\nmkdir -p algorithms/new_algo\n```\n\n2. Implement algorithm:\n```python\nfrom ..base import MARLAlgorithm\n\nclass NewAlgo(MARLAlgorithm):\n    def __init__(self, config):\n        super().__init__(config)\n```\n\n### Adding New Environment\n\n```python\nfrom ..base import MARLEnvironment\n\nclass NewEnvironment(MARLEnvironment):\n    def __init__(self, config):\n        super().__init__(config)\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n#### CUDA Out of Memory\n```yaml\n# Reduce batch size in config\ntraining:\n  batch_size: 16\n  grad_accumulation_steps: 2\n```\n\n#### Distributed Training\n```bash\n# Test NCCL installation\npython -c \"import torch; print(torch.cuda.nccl.version())\"\n```\n\n## 📚 Documentation\n\nFor detailed documentation, visit our [Wiki](https://github.com/username/marl_framework/wiki).\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push branch (`git push origin feature/amazing`)\n5. Open Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- StarCraft II environment by DeepMind\n- Google Research Football\n- OpenAI MPE","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristianlin0420%2Fmulti-agent-universal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristianlin0420%2Fmulti-agent-universal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristianlin0420%2Fmulti-agent-universal/lists"}