docs
Advanced Usage

Advanced Usage

Development

Building from Source

git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
make build
make build-all
make install

Testing

make test
make test-coverage

Code Quality

make fmt
make lint

Troubleshooting

Common Issues

"python3 not found"

  • Ensure Python 3.10+ is installed and in PATH
  • Use python3 --version to verify

"Requirements installation failed"

  • Ensure requirements.txt exists in your RL Swarm directory
  • Check network connectivity for pip install

"Permission denied"

  • Make sure all files are executable as needed
  • Ensure proper file permissions

"gswarm command not found"

  • Ensure Go is installed and $GOPATH/bin is in your PATH
  • Reinstall with: go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest

"HF token prompt appears when not expected"

  • Use --hf-token YOUR_TOKEN to provide the token via command line
  • The prompt only appears when no token is provided

"Invalid model-size value"

  • Use one of the valid values: 0.5, 1.5, 7, 32, 72
  • Example: gswarm --model-size 7

"Invalid game type"

  • Use either gsm8k or dapo for the game parameter
  • Example: gswarm --game gsm8k

Debug Mode

Set environment variable for verbose logging:

export SWARM_DEBUG=1
gswarm

Requirements

System Requirements

  • Go 1.21+
  • Python 3.10+
  • Network connectivity for dependency installation

File Structure

your-gensyn-rl-swarm-project/
├── requirements.txt          # Python dependencies
├── config.yaml              # Configuration file
└── ...                      # Other RL Swarm files

Advanced Configuration

Environment Variables

All configuration options can be set via environment variables for automated deployments:

# Core configuration
export GSWARM_TESTNET=true
export GSWARM_BIG_SWARM=true
export GSWARM_MODEL_SIZE=7
export GSWARM_ORG_ID=your-org-id
export GSWARM_IDENTITY_PATH=/path/to/identity.pem
export GSWARM_CONTRACT_ADDRESS=0x...
export GSWARM_GAME=gsm8k
export GSWARM_CONFIG_PATH=config.yaml
export GSWARM_CPU_ONLY=false
export GSWARM_REQUIREMENTS=requirements-gpu.txt
 
# HuggingFace configuration
export HUGGINGFACE_ACCESS_TOKEN=your-token
export GSWARM_HF_TOKEN=your-token
 
# Telegram configuration
export GSWARM_TELEGRAM=true
export GSWARM_USER_DATA_PATH=/path/to/userData.json
export GSWARM_TELEGRAM_CONFIG_PATH=telegram-config.json
export GSWARM_UPDATE_TELEGRAM_CONFIG=false
 
# Debug mode
export SWARM_DEBUG=1

Configuration Profiles

You can create configuration profiles for different environments:

# Development profile
export GSWARM_PROFILE=dev
export GSWARM_TESTNET=true
export GSWARM_MODEL_SIZE=0.5
export GSWARM_CPU_ONLY=true
 
# Production profile
export GSWARM_PROFILE=prod
export GSWARM_TESTNET=false
export GSWARM_MODEL_SIZE=7
export GSWARM_BIG_SWARM=true

Automated Deployment

For automated deployments, you can use scripts:

#!/bin/bash
# deploy.sh
 
# Set environment variables
export GSWARM_ORG_ID=$ORG_ID
export GSWARM_HF_TOKEN=$HF_TOKEN
export GSWARM_MODEL_SIZE=7
export GSWARM_BIG_SWARM=true
 
# Start supervisor
gswarm --non-interactive

Docker Integration

You can run GSwarm in a Docker container:

FROM golang:1.21-alpine
 
# Install Python
RUN apk add --no-cache python3 py3-pip
 
# Install GSwarm
RUN go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest
 
# Set working directory
WORKDIR /app
 
# Copy requirements
COPY requirements.txt .
 
# Install Python dependencies
RUN pip3 install -r requirements.txt
 
# Run GSwarm
CMD ["gswarm"]

Performance Optimization

Memory Management

  • Monitor memory usage during training
  • Use appropriate model sizes for your hardware
  • Consider CPU-only mode for memory-constrained systems

Network Optimization

  • Use stable internet connections for dependency installation
  • Configure proxy settings if needed
  • Monitor network usage during model downloads

Process Management

  • GSwarm automatically handles process restarts
  • Monitor log files for performance issues
  • Use debug mode for detailed logging

Contributing

Fork the Repository

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a feature branch

Development Workflow

# Clone your fork
git clone https://github.com/your-username/gswarm.git
cd gswarm
 
# Create feature branch
git checkout -b feature/your-feature-name
 
# Make your changes
# ...
 
# Run tests
make test
 
# Format code
make fmt
 
# Lint code
make lint
 
# Commit your changes
git commit -m "Add your feature"
 
# Push to your fork
git push origin feature/your-feature-name

Submit a Pull Request

  1. Create a pull request on GitHub
  2. Describe your changes clearly
  3. Include tests if applicable
  4. Follow the project's coding standards

Roadmap

Current Development Focus (Q3 2025)

  • Enhanced Monitoring: Real-time performance metrics collection
  • Configuration Profiles: Save/load configuration presets
  • Improved Error Handling: Better error classification and recovery
  • Multi-Node Support: Basic management of multiple GPU nodes
  • Telegram Enhancements: More detailed notifications and analytics

Upcoming Features

  • Local GUI Application: Desktop application for monitoring and control
  • Real-time Dashboard: Visual monitoring with charts and graphs
  • Configuration Management: Visual profile editor and templates
  • System Integration: System tray, notifications, and auto-start
  • Advanced Telegram Features: Custom notification schedules and filters

Support

Getting Help

  • GitHub Issues: Report bugs and request features
  • Documentation: Check this documentation for answers
  • Community: Join discussions on GitHub

Reporting Issues

When reporting issues, please include:

  • GSwarm version (gswarm --version)
  • Operating system and version
  • Python version (python3 --version)
  • Go version (go version)
  • Error messages and logs
  • Steps to reproduce the issue

Feature Requests

For feature requests:

  • Describe the feature clearly
  • Explain the use case
  • Consider if it fits within the project's scope
  • Check if similar features already exist

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

Telegram MonitoringAPI Reference