API Reference

Command Line Interface

GSwarm provides a comprehensive command-line interface with various options and flags for different use cases.

Main Command

`gswarm`

The main command to start the GSwarm supervisor.

gswarm [flags]

Command Options

Core Configuration Flags

Flag	Type	Default	Description	Environment Variable
`--testnet`	bool	`false`	Connect to the Testnet	`GSWARM_TESTNET`
`--big-swarm`	bool	`false`	Use big swarm (Math Hard) instead of small swarm (Math)	`GSWARM_BIG_SWARM`
`--model-size`	string	`0.5`	Parameter count in billions (0.5, 1.5, 7, 32, 72)	`GSWARM_MODEL_SIZE`
`--hf-token`	string		HuggingFace access token for model pushing	`HUGGINGFACE_ACCESS_TOKEN`, `GSWARM_HF_TOKEN`
`--org-id`	string		Modal ORG_ID (required for testnet)	`GSWARM_ORG_ID`
`--identity-path`	string	`swarm.pem`	Path to identity PEM file	`GSWARM_IDENTITY_PATH`
`--contract-address`	string		Override smart contract address	`GSWARM_CONTRACT_ADDRESS`
`--game`	string		Game type ('gsm8k' or 'dapo')	`GSWARM_GAME`
`--config-path`	string		Path to YAML config file	`GSWARM_CONFIG_PATH`
`--cpu-only`	bool	`false`	Force CPU-only mode	`GSWARM_CPU_ONLY`
`--requirements`	string		Requirements file path (overrides default)	`GSWARM_REQUIREMENTS`
`--interactive`	bool	`false`	Force interactive mode (prompt for all options)	`GSWARM_INTERACTIVE`

Telegram Monitoring Flags

Flag	Type	Default	Description	Environment Variable
`--telegram`	bool	`false`	Start Telegram monitoring service	`GSWARM_TELEGRAM`
`--user-data-path`	string		Path to userData.json file	`GSWARM_USER_DATA_PATH`
`--telegram-config-path`	string	`telegram-config.json`	Path to telegram-config.json	`GSWARM_TELEGRAM_CONFIG_PATH`
`--update-telegram-config`	bool	`false`	Force update of Telegram config	`GSWARM_UPDATE_TELEGRAM_CONFIG`

Utility Commands

Command	Description
`gswarm --version`	Show version information
`gswarm --help`	Show help information
`gswarm version`	Show version information
`gswarm help version`	Show help for specific command

Environment Variables

All command-line flags can be set via environment variables with the GSWARM_ prefix:

# 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 File Format

GSwarm can use YAML configuration files for complex setups:

# config.yaml
testnet: true
big_swarm: true
model_size: 7
org_id: "your-org-id"
identity_path: "swarm.pem"
contract_address: "0x..."
game: "gsm8k"
cpu_only: false
requirements: "requirements-gpu.txt"

Usage Examples

Basic Usage

# Interactive mode (default)
gswarm
 
# Non-interactive mode with all options
gswarm --testnet --big-swarm --model-size 7 --org-id YOUR_ORG_ID --hf-token YOUR_TOKEN
 
# CPU-only mode
gswarm --cpu-only --model-size 0.5
 
# Custom requirements file
gswarm --requirements requirements-gpu.txt

Telegram Monitoring

# Basic Telegram monitoring
gswarm --telegram
 
# Telegram with custom paths
gswarm --telegram \
  --user-data-path /path/to/userData.json \
  --telegram-config-path /path/to/telegram-config.json
 
# Update Telegram configuration
gswarm --telegram --update-telegram-config

Advanced Configuration

# Full configuration with all options
gswarm \
  --org-id YOUR_ORG_ID \
  --identity-path /path/to/identity.pem \
  --hf-token YOUR_HF_TOKEN \
  --model-size 7 \
  --big-swarm \
  --cpu-only \
  --telegram
 
# Environment-based configuration
export GSWARM_ORG_ID=your-org-id
export GSWARM_HF_TOKEN=your-token
export GSWARM_MODEL_SIZE=7
gswarm

Return Codes

GSwarm uses standard exit codes:

Code	Description
`0`	Success
`1`	General error
`2`	Configuration error
`3`	Python environment error
`4`	Process management error
`5`	Telegram service error

Logging

Log File Location

Logs are written to logs/gensyn_rl_swarm_go.log by default.

Log Format

2024-01-01 12:00:00.000000 [LEVEL] Message

Log Levels

INFO: General information
WARN: Warning messages
ERROR: Error messages
DEBUG: Debug information (when SWARM_DEBUG=1)

Error Handling

Common Error Messages

Error	Description	Solution
`python3 not found`	Python 3.10+ not in PATH	Install Python 3.10+
`requirements installation failed`	Failed to install dependencies	Check network and requirements.txt
`invalid model-size value`	Invalid model size specified	Use: 0.5, 1.5, 7, 32, 72
`invalid game type`	Invalid game type specified	Use: gsm8k or dapo
`bot token invalid`	Invalid Telegram bot token	Verify token with @BotFather

Debug Mode

Enable debug mode for detailed logging:

export SWARM_DEBUG=1
gswarm

Integration Examples

Shell Script Integration

#!/bin/bash
# start-gswarm.sh
 
# Set configuration
export GSWARM_ORG_ID=$1
export GSWARM_HF_TOKEN=$2
export GSWARM_MODEL_SIZE=${3:-7}
 
# Start GSwarm
gswarm --non-interactive
 
# Check exit code
if [ $? -eq 0 ]; then
    echo "GSwarm started successfully"
else
    echo "GSwarm failed to start"
    exit 1
fi

Docker Integration

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"]

Systemd Service

[Unit]
Description=GSwarm Supervisor
After=network.target
 
[Service]
Type=simple
User=gswarm
Environment=GSWARM_ORG_ID=your-org-id
Environment=GSWARM_HF_TOKEN=your-token
Environment=GSWARM_MODEL_SIZE=7
WorkingDirectory=/path/to/gensyn-rl-swarm
ExecStart=/usr/local/bin/gswarm
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target

API Stability

The command-line interface is considered stable for the following:

Core flags and options
Environment variable support
Basic configuration options
Telegram monitoring flags

The following may change in future versions:

Internal implementation details
Log format and location
Error message text
Debug output format

Version Compatibility

GSwarm maintains backward compatibility for:

Command-line flags
Environment variables
Configuration file format
Basic functionality

Breaking changes will be documented in release notes and may require migration steps.

Advanced Usage FAQ