Skip to content

Installation Guide

Jump to bottom
maheshvaikri edited this page Aug 29, 2025 · 1 revision

🛠️ MAPLE Installation Guide

Creator: Mahesh Vaijainthymala Krishnamoorthy (Mahesh Vaikri)

📋 Prerequisites

System Requirements

  • Python: 3.8+ (recommended: 3.11+)
  • OS: Windows 10/11, macOS 10.15+, Linux (Ubuntu 20.04+)
  • Memory: Minimum 4GB RAM (recommended: 8GB+)
  • Storage: 500MB free space

Dependencies

MAPLE has minimal dependencies by design:

  • asyncio (Python standard library)
  • json (Python standard library)
  • threading (Python standard library)
  • cryptography (for security features)
  • websockets (for broker communication)

🚀 Quick Installation

Option 1: From GitHub (Recommended)

# Clone the repository
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss

# Create virtual environment
python -m venv maple-env

# Activate virtual environment
# On Windows:
maple-env\Scripts\activate
# On macOS/Linux:
source maple-env/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "import maple; print('MAPLE installed successfully!')"

Option 2: Development Installation

# Clone with development branches
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss

# Switch to development branch (optional)
git checkout develop

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests to verify
python -m pytest tests/ -v

🐳 Docker Installation

Using Pre-built Image

# Pull the latest MAPLE image
docker pull maple/maple-oss:latest

# Run MAPLE container
docker run -p 8080:8080 maple/maple-oss:latest

# Run with custom configuration
docker run -p 8080:8080 -v /path/to/config:/app/config maple/maple-oss:latest

Build from Source

# Clone repository
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss

# Build Docker image
docker build -t maple-local .

# Run your local build
docker run -p 8080:8080 maple-local

⚙️ Configuration

Basic Configuration

Create a maple_config.json file:

{
  "broker": {
    "host": "localhost",
    "port": 8080,
    "protocol": "websocket"
  },
  "security": {
    "authentication": "jwt",
    "encryption": "AES256",
    "require_links": true
  },
  "performance": {
    "connection_pool_size": 10,
    "max_concurrent_requests": 50,
    "message_buffer_size": 1000
  },
  "logging": {
    "level": "INFO",
    "format": "json",
    "file": "maple.log"
  }
}

Environment Variables

# Basic configuration
export MAPLE_BROKER_HOST=localhost
export MAPLE_BROKER_PORT=8080
export MAPLE_LOG_LEVEL=INFO

# Security settings
export MAPLE_SECURITY_KEY=/path/to/security.key
export MAPLE_REQUIRE_AUTHENTICATION=true

# Performance tuning
export MAPLE_MAX_AGENTS=1000
export MAPLE_MESSAGE_TIMEOUT=30

🧪 Verification

Run Basic Tests

# Test core functionality
python -m maple.tests.test_core

# Test message system
python -m maple.tests.test_messages

# Run all tests (this should show 32/32 passed)
python -m pytest tests/ -v --tb=short

Quick Functionality Check

# test_installation.py
from maple import Agent, Message, Config, Priority

def test_basic_functionality():
    # Create test configuration
    config = Config(
        agent_id="test_agent",
        broker_url="localhost:8080"
    )
    
    # Create agent
    agent = Agent(config)
    
    # Test message creation
    message = Message(
        message_type="TEST",
        priority=Priority.HIGH,
        payload={"test": "data"}
    )
    
    print("✅ Basic functionality verified!")
    return True

if __name__ == "__main__":
    test_basic_functionality()

🔧 Platform-Specific Setup

Windows

# Install Python from python.org (3.11+ recommended)
# Open PowerShell as Administrator

# Install Git
winget install Git.Git

# Clone and setup
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss
python -m venv maple-env
.\maple-env\Scripts\Activate.ps1
pip install -r requirements.txt

# Add to PATH (optional)
$env:PATH += ";C:\path\to\maple-oss"

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python and Git
brew install python@3.11 git

# Clone and setup
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss
python3.11 -m venv maple-env
source maple-env/bin/activate
pip install -r requirements.txt

# Add to shell profile (optional)
echo 'export PATH="/path/to/maple-oss:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux (Ubuntu/Debian)

# Update package lists
sudo apt update

# Install dependencies
sudo apt install python3.11 python3.11-venv python3-pip git

# Clone and setup
git clone https://github.com/maheshvaikri-code/maple-oss.git
cd maple-oss
python3.11 -m venv maple-env
source maple-env/bin/activate
pip install -r requirements.txt

# Install system-wide (optional)
sudo pip install -e .

🚀 Performance Optimization

Production Settings

{
  "performance": {
    "connection_pool_size": 50,
    "max_concurrent_requests": 200,
    "message_buffer_size": 10000,
    "enable_compression": true,
    "batch_processing": true,
    "async_mode": true
  }
}

Memory Optimization

# maple_config.py
import maple

# Configure for high-performance
maple.configure({
    'memory_limit': '4GB',
    'gc_threshold': 10000,
    'message_cache_size': 50000,
    'enable_memory_profiling': True
})

🐛 Troubleshooting

Common Issues

Issue: Import Error

ImportError: No module named 'maple'

Solution:

# Ensure virtual environment is activated
source maple-env/bin/activate  # Linux/macOS
# or
maple-env\Scripts\activate     # Windows

# Reinstall if necessary
pip install -e .

Issue: Broker Connection Failed

ConnectionError: Unable to connect to broker at localhost:8080

Solution:

# Check if broker is running
netstat -an | grep 8080

# Start broker manually
python -m maple.broker --host localhost --port 8080

Issue: Permission Denied

PermissionError: [Errno 13] Permission denied

Solution:

# Fix file permissions
chmod +x maple-oss/bin/*
chmod 755 maple-oss/

# Or run as administrator (Windows)

Getting Help

If you encounter issues:

  1. Check the logs: tail -f maple.log
  2. Run diagnostics: python -m maple.diagnostics
  3. Search existing issues: [GitHub Issues](https://github.com/maheshvaikri-code/maple-oss/issues)
  4. Ask the community: [Discord](https://discord.gg/maple) or [Discussions](https://github.com/maheshvaikri-code/maple-oss/discussions)

✅ Installation Complete!

Once installed, you should see:

✅ MAPLE Core: Ready
✅ Message System: Active  
✅ Security Layer: Enabled
✅ Broker Connection: Established
✅ All Tests: 32/32 Passed

🎉 MAPLE is ready to use!

Next Steps:

Ready to revolutionize multi-agent communication?

[Start Building →](Quick-Start-Tutorial)

Copyright (C) 2025 Mahesh Vaijainthymala Krishnamoorthy (Mahesh Vaikri) License AGPL 3.0

Clone this wiki locally