polaris-cli-tool/example.README.md

Polaris CLI - Modern Development Workspace Manager for Distributed Compute Resources

# Polaris CLI

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://semver.org)

> ⚡ A powerful CLI tool for managing distributed compute resources in the Polaris network

## 📚 Table of Contents

- [Overview](#overview)
- [System Architecture](#system-architecture)
- [Features](#features)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Operations](#operations)
  - [Register Miner](#register-miner)
  - [Add Compute Resources](#add-compute-resources)
  - [Run Polaris Subnet](#run-polaris-subnet)
  - [View Miner Compute](#view-miner-compute)
- [Resource Data Format](#resource-data-format)
  - [Excel Structure](#excel-structure)
  - [Field Specifications](#field-specifications)
  - [Sample Data](#sample-data)
- [Integration Architecture](#integration-architecture)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [FAQ](#faq)
- [Support](#support)

## Overview

Polaris CLI is a command-line interface tool designed to manage distributed compute subnets. It serves as the bridge between miners and the Polaris Subnet Manager, enabling seamless registration, resource management, and subnet operations.

### System Architecture

```mermaid
graph TB
    subgraph CLI["Polaris CLI"]
        UI[Interactive Interface]
        RM[Resource Manager]
        MM[Miner Manager]
        CM[Config Manager]
    end

    subgraph SM["Subnet Manager"]
        API[API Gateway]
        Auth[Auth Service]
        ResM[Resource Manager]
        Valid[Validator]
        DB[(Database)]
    end

    subgraph Miners["Compute Subnet"]
        M1[Miner 1]
        M2[Miner 2]
        M3[Miner 3]
    end

    UI --> RM
    RM --> MM
    MM --> CM
    
    CLI -->|API Requests| SM
    SM -->|Resource Allocation| Miners
    Miners -->|Status Updates| SM
    
    API --> Auth
    Auth --> ResM
    ResM --> DB
    ResM --> Valid
```

## Installation

### Prerequisites

- **Node.js**: Version 14.x or higher
- **npm**: Comes bundled with Node.js
- **Python**: Version 3.11+ (optional, for extending functionality)
- **Excel**: For resource template files

### Dependencies

Core Node.js packages:
```json
{
  "dependencies": {
    "boxen": "^7.1.0",
    "chalk": "^5.3.0",
    "cli-progress": "^3.12.0",
    "cli-table3": "^0.6.3",
    "commander": "^11.0.0",
    "figlet": "^1.6.0",
    "gradient-string": "^2.0.2",
    "inquirer": "^9.2.10",
    "node-fetch": "^3.3.2",
    "ora": "^7.0.1",
    "xlsx": "^0.18.5"
  }
}
```

### Setup Steps

1. **Clone Repository**
   ```bash
   git clone https://github.com/BANADDA/polaris-cli.git
   cd polaris-cli
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Configure Environment**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

4. **Set Permissions**
   ```bash
   chmod +x index.js
   ```

## Operations

### Register Miner

Detailed steps for miner registration:

1. **Basic Information**
   ```bash
   Enter miner name: <name>
   Enter location: <location>
   Enter internal IP: <ip>
   Enter SSH string: ssh://user@hostname:port
   ```

2. **Port Configuration**
   ```bash
   Enter port number (or press enter to finish): 22
   Enter port number (or press enter to finish): 80
   Enter port number (or press enter to finish): 443
   ```

3. **Resource Definition**
   Excel file format requirements:

   | Field | Type | Required | Description |
   |-------|------|----------|-------------|
   | id | string | Yes | Unique identifier |
   | resource_type | string | Yes | CPU/GPU |
   | location | string | Yes | Geographic location |
   | hourly_price | number | Yes | Cost per hour |
   | ram | string | Yes | Memory amount |
   | storage_type | string | Yes | Storage type |
   | storage_capacity | string | Yes | Storage size |
   | storage_read_speed | string | Yes | Read speed |
   | storage_write_speed | string | Yes | Write speed |

4. **CPU-Specific Fields**
   When resource_type is "CPU":
   ```json
   {
     "cpu_specs": {
       "op_modes": "32-bit, 64-bit",
       "address_sizes": "46 bits physical, 48 bits virtual",
       "byte_order": "Little Endian",
       "total_cpus": 16,
       "online_cpus": "0-7",
       "vendor_id": "GenuineIntel",
       "cpu_name": "Intel(R) Xeon(R) W-2123",
       "cpu_family": 6,
       "model": 85,
       "threads_per_core": 2,
       "cores_per_socket": 4,
       "sockets": 1,
       "stepping": 4,
       "cpu_max_mhz": 3900.0,
       "cpu_min_mhz": 1200.0
     }
   }
   ```

5. **GPU-Specific Fields**
   When resource_type is "GPU":
   ```json
   {
     "gpu_specs": {
       "gpu_name": "NVIDIA A100",
       "memory_size": "40GB",
       "cuda_cores": 6912,
       "clock_speed": "1.41 GHz",
       "tensor_cores": 432,
       "power_consumption": "400W"
     }
   }
   ```

### Add Compute Resources

Steps to add new compute resources:

1. **Resource Format**
   ```bash
   polaris-cli start
   # Select "Add Compute Resources"
   ```

2. **Validation Rules**
   - All IDs must be unique
   - Resource types must be "CPU" or "GPU"
   - RAM must include unit (GB/TB)
   - Prices must be positive numbers
   - Storage speeds must include units

3. **Processing Steps**
   ```plaintext
   [1/4] Validating resource specifications
   [2/4] Processing compute capabilities
   [3/4] Configuring network settings
   [4/4] Establishing secure connection
   ```

### Run Subnet

Subnet initialization process:

1. **Authentication**
   ```bash
   Enter Miner ID: <miner_id>
   ```

2. **Network Configuration**
   ```plaintext
   - Authenticating Miner
   - Connecting to network
   - Synchronizing nodes
   - Establishing secure channels
   - Loading compute resources
   ```

3. **Status Monitoring**
   ```json
   {
     "network_status": {
       "active_nodes": 156,
       "total_compute": "1.2 PetaFLOPS",
       "network_health": "98.5%",
       "connected_miners": 45
     }
   }
   ```

### View Miner Details

Comprehensive miner information display:

1. **Basic Info**
   ```plaintext
   Miner ID: <id>
   Location: <location>
   Status: Active/Inactive
   Registration Date: <date>
   ```

2. **Resource Summary**
   ```plaintext
   Total Resources: X
   CPU Units: Y
   GPU Units: Z
   Total Storage: W TB
   ```

3. **Performance Metrics**
   ```plaintext
   CPU Utilization: X%
   Memory Usage: Y%
   Network Bandwidth: Z Gbps
   Storage I/O: W MB/s
   ```
## Resource Data Format

### Excel Structure

The Excel file should contain the following columns for each compute resource:

#### Required Base Fields
| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique identifier for the resource |
| resource_type | string | Must be either "CPU" or "GPU" |
| location | string | Physical location of the resource |
| hourly_price | number | Cost per hour |
| ram | string | RAM specification (e.g., "64GB") |

#### Network Configuration Fields
| Field | Type | Description |
|-------|------|-------------|
| internal_ip | string | Internal IP address |
| ssh | string | SSH connection string (format: ssh://user@ip:port) |
| open_ports | string | Comma-separated list of ports (e.g., "22,80,443") |

#### Storage Fields
| Field | Type | Description |
|-------|------|-------------|
| storage_type | string | Storage type (NVME/SSD/HDD) |
| storage_capacity | string | Storage size with unit |
| storage_read_speed | string | Read speed with unit |
| storage_write_speed | string | Write speed with unit |

#### CPU-Specific Fields (Required if resource_type is "CPU")
| Field | Type | Description |
|-------|------|-------------|
| cpu_op_modes | string | CPU operation modes |
| cpu_address_sizes | string | Physical and virtual address sizes |
| cpu_byte_order | string | Byte order |
| total_cpus | number | Total number of CPUs |
| online_cpus | string | Range of online CPUs |
| vendor_id | string | CPU vendor identifier |
| cpu_name | string | Full CPU model name |
| cpu_family | number | CPU family number |
| model | number | CPU model number |
| threads_per_core | number | Number of threads per core |
| cores_per_socket | number | Number of cores per socket |
| sockets | number | Number of CPU sockets |
| stepping | number | CPU stepping information |
| cpu_max_mhz | number | Maximum CPU frequency |
| cpu_min_mhz | number | Minimum CPU frequency |

#### GPU-Specific Fields (Required if resource_type is "GPU")
| Field | Type | Description |
|-------|------|-------------|
| gpu_name | string | GPU model name |
| memory_size | string | GPU memory size |
| cuda_cores | number | Number of CUDA cores |
| clock_speed | string | GPU clock speed |
| power_consumption | string | Power consumption |

### Sample Data Examples

1. **CPU Resource Row:**
```plaintext
id: compute1
resource_type: CPU
location: NYC-RACK-01
internal_ip: 192.168.1.10
ssh: ssh://user@192.168.1.10:22
open_ports: 22,80,443,3000
hourly_price: 2.0
ram: 128GB
storage_type: NVME
storage_capacity: 4TB
storage_read_speed: 7000MB/s
storage_write_speed: 5000MB/s
cpu_op_modes: 32-bit, 64-bit
cpu_address_sizes: 46 bits physical, 48 bits virtual
cpu_byte_order: Little Endian
total_cpus: 32
online_cpus: 0-31
vendor_id: GenuineIntel
cpu_name: Intel(R) Xeon(R) Platinum 8380 CPU @ 2.30GHz
cpu_family: 6
model: 85
threads_per_core: 2
cores_per_socket: 8
sockets: 2
stepping: 4
cpu_max_mhz: 3400.0
cpu_min_mhz: 1000.0
```

2. **GPU Resource Row:**
```plaintext
id: compute2
resource_type: GPU
location: NYC-RACK-02
internal_ip: 192.168.1.11
ssh: ssh://user@192.168.1.11:22
open_ports: 22,80,443,8080
hourly_price: 3.5
ram: 256GB
storage_type: NVME
storage_capacity: 8TB
storage_read_speed: 7000MB/s
storage_write_speed: 5000MB/s
gpu_name: NVIDIA A100
memory_size: 80GB
cuda_cores: 6912
clock_speed: 1410MHz
power_consumption: 400W
```

### Validation Rules

1. **Network Configuration**
   - Internal IP must be a valid IPv4 address
   - SSH string must follow format: ssh://user@ip:port
   - Ports must be valid numbers between 1-65535

2. **Resource Type Validation**
   - Must be either "CPU" or "GPU" (case insensitive)
   - CPU resources must include all CPU-specific fields
   - GPU resources must include all GPU-specific fields

3. **Storage Validation**
   - Storage type must be one of: NVME, SSD, HDD
   - All storage values must include units
   - Read/Write speeds must include MB/s or GB/s

4. **General Rules**
   - All IDs must be unique
   - Hourly price must be a positive number
   - RAM must include unit (GB/TB)

### Common Validation Errors

```plaintext
❌ Missing required fields
❌ Invalid resource type (must be CPU or GPU)
❌ Missing units in measurements
❌ Invalid price format
❌ Duplicate resource IDs
❌ Inconsistent speed formats
```

You can download a sample Excel template from our repository at: [resource-template.xlsx](https://github.com/BANADDA/polaris-cli/blob/main/templates/resource-template.xlsx)

## Integration Architecture

```mermaid
sequenceDiagram
    participant CLI
    participant SM as Subnet Manager
    participant DB as Database
    participant Miners

    CLI->>SM: Register Miner
    SM->>DB: Store Registration
    SM->>Miners: Validate Resources
    Miners-->>SM: Resource Confirmation
    SM-->>CLI: Registration Complete

    loop Resource Monitoring
        SM->>Miners: Health Check
        Miners-->>SM: Status Update
        SM->>DB: Update Metrics
    end
```

## Error Handling

Common errors and solutions:

1. **Connection Errors**
   ```plaintext
   Error: Failed to connect to API
   Solution: Check if API server is running on http://localhost:8000
   ```

2. **Validation Errors**
   ```plaintext
   Error: Invalid resource specification
   Solution: Review Excel file format and required fields
   ```

3. **Authentication Errors**
   ```plaintext
   Error: Invalid Miner ID
   Solution: Verify Miner ID and try again
   ```

## Error Handling (continued)

4. **Resource Errors**
   ```plaintext
   Error: Insufficient resources
   Details: Requested: CPU cores=8, RAM=32GB
           Available: CPU cores=4, RAM=16GB
   Solution: Adjust resource requirements or add more resources
   ```

5. **File Format Errors**
   ```plaintext
   Error: Invalid Excel format
   Details: Missing required columns - 'resource_type', 'ram'
   Solution: Use the provided template and ensure all required fields
   ```

6. **Network Errors**
   ```plaintext
   Error: Subnet synchronization failed
   Details: Unable to reach peers
   Solution: Check network connectivity and firewall settings
   ```

## API Integration

### Base URL
```plaintext
http://localhost:8000/api/v1
```

### Endpoints

1. **Miner Registration**
   ```http
   POST /miners/
   Content-Type: application/json
   
   {
     "name": "string",
     "location": "string",
     "internal_ip": "string",
     "ssh": "string",
     "open_ports": "string",
     "description": "string",
     "compute_resources": [
       {
         "id": "string",
         "resource_type": "string",
         "location": "string",
         "hourly_price": 0,
         "ram": "string",
         "storage": {
           "type": "string",
           "capacity": "string",
           "read_speed": "string",
           "write_speed": "string"
         }
       }
     ]
   }
   ```

2. **Resource Update**
   ```http
   PUT /miners/{miner_id}/resources
   Content-Type: application/json
   
   {
     "compute_resources": [
       {
         "id": "string",
         "status": "active|inactive",
         "metrics": {
           "cpu_usage": 0,
           "memory_usage": 0,
           "storage_usage": 0
         }
       }
     ]
   }
   ```

3. **Miner Status**
   ```http
   GET /miners/{miner_id}/status
   
   Response:
   {
     "status": "active|inactive",
     "last_seen": "timestamp",
     "resource_metrics": {
       "total_resources": 0,
       "active_resources": 0,
       "total_compute_power": "string",
       "network_bandwidth": "string"
     }
   }
   ```

## Advanced Configuration

### Environment Variables
```bash
# API Configuration
POLARIS_API_URL=http://localhost:8000
POLARIS_API_VERSION=v1
POLARIS_TIMEOUT=30000

# Resource Limits
MAX_CPU_CORES=64
MAX_GPU_UNITS=8
MAX_RAM_GB=512
MAX_STORAGE_TB=100

# Network Settings
PORT_RANGE=1024-65535
ALLOWED_PROTOCOLS=tcp,udp
MAX_BANDWIDTH=10000 # Mbps

# Security
AUTH_TOKEN_EXPIRY=3600
MAX_LOGIN_ATTEMPTS=3
ENCRYPTION_KEY=your-secret-key
```

### Resource Templates

1. **CPU Resource Template**
   ```yaml
   resource_type: CPU
   specifications:
     min_cores: 1
     max_cores: 64
     min_threads: 1
     max_threads: 128
     architectures:
       - x86_64
       - ARM64
     features:
       - AVX
       - SSE4
       - AES-NI
   ```

2. **GPU Resource Template**
   ```yaml
   resource_type: GPU
   specifications:
     min_memory: 4GB
     max_memory: 80GB
     compute_capabilities:
       - CUDA
       - OpenCL
     features:
       - Tensor Cores
       - RT Cores
     power_profiles:
       - low: 100W
       - medium: 250W
       - high: 400W
   ```

## Performance Optimization

### Resource Allocation Strategy
```mermaid
flowchart TD
    A[Resource Request] --> B{Check Local Cache}
    B -->|Cache Hit| C[Return Cached Data]
    B -->|Cache Miss| D[Query API]
    D --> E{Available Resources?}
    E -->|Yes| F[Allocate Resources]
    E -->|No| G[Resource Wait Queue]
    G --> H{Timeout?}
    H -->|Yes| I[Allocation Failed]
    H -->|No| E
    F --> J[Update Cache]
    J --> K[Return Resource Data]
```

### Monitoring and Metrics

1. **Resource Metrics**
   ```json
   {
     "compute_metrics": {
       "cpu_utilization": {
         "current": 45.5,
         "average_1h": 42.3,
         "peak_24h": 78.9
       },
       "memory_usage": {
         "current": 28.7,
         "available": 71.3,
         "swap_used": 0.5
       },
       "gpu_metrics": {
         "utilization": 65.2,
         "memory_used": 35.8,
         "temperature": 72
       }
     },
     "network_metrics": {
       "bandwidth_in": "2.5 Gbps",
       "bandwidth_out": "1.8 Gbps",
       "latency": "12ms"
     }
   }
   ```

2. **Performance Alerts**
   ```yaml
   alerts:
     high_usage:
       threshold: 90%
       duration: 5m
       action: notify_admin
     
     low_resources:
       threshold: 10%
       duration: 15m
       action: scale_resources
     
     network_congestion:
       threshold: 85%
       duration: 2m
       action: throttle_new_requests
   ```

## Security Considerations

### Authentication Flow
```mermaid
sequenceDiagram
    participant Miner
    participant CLI
    participant Auth
    participant API
    
    Miner->>CLI: Register Request
    CLI->>Auth: Validate Credentials
    Auth->>Auth: Generate Token
    Auth-->>CLI: Return Token
    CLI->>API: API Request + Token
    API->>Auth: Verify Token
    Auth-->>API: Token Valid
    API-->>CLI: Process Request
```

### Security Measures

1. **Network Security**
   ```yaml
   security_measures:
     encryption:
       - TLS 1.3
       - AES-256-GCM
     authentication:
       - JWT
       - Certificate-based
     network_protection:
       - DDoS protection
       - Rate limiting
       - IP whitelisting
   ```

2. **Access Control**
   ```json
   {
     "roles": {
       "admin": {
         "permissions": ["read", "write", "execute", "delete"],
         "resource_access": "all"
       },
       "miner": {
         "permissions": ["read", "write"],
         "resource_access": "own"
       },
       "viewer": {
         "permissions": ["read"],
         "resource_access": "assigned"
       }
     }
   }
   ```

## Contributing

### Development Setup
```bash
# Fork and clone the repository
git clone https://github.com/BANADDA/polaris-cli.git

# Install development dependencies
npm install --dev

# Create a new branch
git checkout -b feature/your-feature-name

# Run tests
npm test

# Submit PR
git push origin feature/your-feature-name
```

### Testing Guidelines

1. **Unit Tests**
   ```javascript
   describe('Resource Manager', () => {
     it('should validate resource specifications', () => {
       // Test code
     });
     
     it('should handle invalid resources', () => {
       // Test code
     });
   });
   ```

2. **Integration Tests**
   ```javascript
   describe('API Integration', () => {
     it('should register new miner', async () => {
       // Test code
     });
     
     it('should handle API errors', async () => {
       // Test code
     });
   });
   ```

## Support Channels

### Community Support
- GitHub Issues
- Discord Community
- Documentation Wiki
- Stack Overflow Tag: `polaris-cli`

### Enterprise Support
- Premium Support SLA
- Direct Engineer Access
- Custom Feature Development
- Training and Workshops

## License

MIT License - see [LICENSE.md](LICENSE.md)

---

## Frequently Asked Questions

### **Q: Can I register multiple miners?**
**A:** Yes, you can register multiple miners. Each miner requires a unique combination of name, internal IP, and SSH connection string. The system will generate a unique Miner ID for each registration. Keep track of which Miner ID corresponds to which physical machine or cluster.

### **Q: How do I update existing resources?**
**A:** To update existing compute resources:
1. Use the "View Miner Details" option to check current resources
2. Prepare an Excel file with the updated resource specifications
3. Select "Add Compute Resources" from the main menu
4. Enter your Miner ID
5. Upload the new Excel file with modifications
6. The system will validate and merge the changes

Note: Updating critical specifications (like ID or resource type) will create new resources rather than modifying existing ones.

### **Q: What if I lose my Miner ID?**
**A:** If you lose your Miner ID:
1. Check the `~/.polaris/config.json` file where IDs are cached locally
2. If not found, you can recover it using:
   - Your registered internal IP address
   - SSH connection string
   - Original registration email
3. Contact our support team at mubarakabanadda68@gmail.com with these details

### **Q: Can I migrate my resources between miners?**
**A:** Yes, you can migrate resources between miners by:
1. Exporting the resource configuration from the source miner
2. Creating a new Excel file with updated miner assignments
3. Registering the resources with the target miner

### **Q: How do I monitor resource performance?**
**A:** Use the "View Miner Details" option to:
- Check real-time resource utilization
- View historical performance metrics
- Monitor network status
- Track resource availability

## Support

### Community Support
- 📧 **Email:** mubarakabanadda68@gmail.com
- 📝 **GitHub Issues:** [https://github.com/BANADDA/polaris-cli/issues](https://github.com/BANADDA/polaris-cli/issues)
- 📚 **Documentation:** [https://github.com/BANADDA/polaris-cli/blob/main/readme.md](https://github.com/BANADDA/polaris-cli/blob/main/readme.md)

### Contributing
We welcome contributions! Please see our [CONTRIBUTING.md](https://github.com/BANADDA/polaris-cli/blob/main/CONTRIBUTING.md) for guidelines.

### Bug Reports
When reporting issues, please include:
- Polaris CLI version
- Operating system details
- Steps to reproduce
- Error messages
- Log files (if applicable)

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/BANADDA/polaris-cli/blob/main/LICENSE) file for details.

### MIT License Summary
- ✅ Commercial use
- ✅ Modification
- ✅ Distribution
- ✅ Private use
- ⚠️ Comes with no warranty
- ⚠️ Must include original license and copyright notice

---

**Note:** For enterprise support or custom development inquiries, please contact mubarakabanadda68@gmail.com