diff --git a/docs/getting-started/gaia-toolkit/gaia-toolkit.md b/docs/getting-started/gaia-toolkit/gaia-toolkit.md new file mode 100644 index 00000000..980b24b8 --- /dev/null +++ b/docs/getting-started/gaia-toolkit/gaia-toolkit.md @@ -0,0 +1,318 @@ +--- +sidebar_position: 9 +--- + + +# Gaia CLI Toolkit + +The Gaia CLI Toolkit is a comprehensive command-line interface tool for managing and running various AI models through GaiaNet nodes. It provides intelligent model selection, system-aware recommendations, and seamless setup for your own AI infrastructure. + +## Installation + +Install the toolkit globally via npm: + +```bash +npm install -g gaia-toolkit +``` + +### Prerequisites + +- Node.js environment +- Sufficient system RAM (see [System Requirements](#system-requirements)) +- Internet connection for initial setup +- Terminal with TTY support for interactive prompts + +## Quick Start + +Get started with these essential commands: + +```bash +# Show welcome banner and available commands +gaia + +# Browse available models with filtering options +gaia list + +# Get detailed information about a specific model +gaia info llama3-8b + +# Quick model deployment (install and run) +gaia run llama3-8b + +# Start interactive setup process +gaia setup + +# Get personalized model recommendations +gaia recommend +``` + +## Key Features + +### Smart Model Management +- **Dynamic Model Discovery**: Automatically fetches available models from the GaiaNet repository +- **Command-Line Model Browsing**: List and filter models by size and use case +- **Intelligent Categorization**: Models categorized by size with clear RAM requirements +- **Use Case Analysis**: Models tagged with specific use cases (coding, chat, creative writing, etc.) +- **Direct Model Deployment**: One-command installation and execution with `gaia run` +- **Fallback Support**: Includes reliable fallback models when online repository is unavailable + +### System-Aware Intelligence +- **RAM Analysis**: Automatically detects your system's available memory +- **Smart Recommendations**: Provides personalized suggestions based on your hardware +- **Resource Warnings**: Warns about potential performance issues before installation +- **Safety Mechanisms**: Blocks oversized models that exceed system RAM +- **Compatibility Checks**: Validates system requirements against model requirements + +### Interactive User Experience +- **Beautiful ASCII Art Banner**: Professional welcome screen with Gaia branding +- **Interactive Prompts**: Guided setup process with clear choices +- **Progress Indicators**: Real-time feedback during installation and setup +- **Error Handling**: Graceful fallback and helpful error messages + +## Command Reference + +### `gaia` +Shows the welcome banner with available commands and quick start information. + +```bash +gaia +``` + +### `gaia list` +Browse available models with filtering options. Models are organized by size category with use cases clearly displayed. + +```bash +gaia list [options] +``` + +**Options:** +- `-s, --size `: Filter by size (small, standard, medium, heavy, big, max) +- `-u, --use-case `: Filter by use case (coding, chat, creative, etc.) +- `-f, --format `: Output format (table or json) + +**Examples:** +```bash +gaia list --size small --use-case coding +gaia list --format json +``` + +### `gaia info ` +Get detailed model information including specifications, use cases, system requirements, and compatibility check. + +```bash +gaia info +``` + +**Example:** +```bash +gaia info llama3-8b +``` + +This command provides: +- Model specifications (ID, name, and size category) +- Use cases and capabilities +- System requirements (RAM requirements and performance characteristics) +- Compatibility check against your system +- Step-by-step installation instructions + +### `gaia run ` +Quick model deployment - directly install and run any model with built-in safety mechanisms. + +```bash +gaia run [options] +``` + +**Options:** +- `--skip-install`: Skip GaiaNet installation if already installed +- `--force`: Override safety check ⚠️ **EXTREMELY DANGEROUS** - see [Force Flag Security](#force-flag-security) + +**Examples:** +```bash +gaia run phi3-mini +gaia run phi3-mini --skip-install +``` + +**Workflow:** Validate → Install → Initialize → Start + +#### Force Flag Security (`--force`) + +:::danger +The `--force` flag requires multiple security confirmations to prevent system crashes. Use with extreme caution. +::: + +The force flag protection includes: +1. **System Analysis Display**: Shows exact RAM shortage +2. **Risk Acknowledgment**: Must confirm understanding of crash risks +3. **5-Second Cooling Period**: Enforced wait time to read warnings +4. **Explicit Selection**: Choose from cancel or accept responsibility +5. **Type Confirmation**: Must type "I accept all risks" exactly +6. **Final Countdown**: 3-second countdown with last chance to cancel + +Potential consequences include: +- System freezes requiring hard reset +- Loss of unsaved work in other applications +- Potential hardware stress from memory overload + +### `gaia setup` +Interactive model selection and installation process with guided steps. + +```bash +gaia setup +``` + +This command provides: +1. **System Analysis**: Checks your RAM and provides recommendations +2. **Category Selection**: Choose from Small, Medium, or Big model categories +3. **Model Selection**: Pick a specific model from your chosen category +4. **Installation**: Automatically installs GaiaNet node and configures your model +5. **Launch**: Starts your AI node with the selected model + +### `gaia recommend` +Get personalized model recommendations based on your specific use case. + +```bash +gaia recommend +``` + +Available recommendation categories: +- **Coding & Programming**: Specialized models for development tasks +- **General Chat & Conversation**: Models optimized for natural dialogue +- **Creative Writing**: Models designed for creative content generation +- **Research & Analysis**: Models suited for analytical tasks +- **Resource-Constrained Environment**: Small/lightweight models for limited hardware +- **General Purpose**: Versatile models for various tasks + +### `gaia help` +Comprehensive model selection guide with detailed information. + +```bash +gaia help +``` + +Includes: +- System requirements breakdown +- Performance vs resource trade-offs +- Use case-specific recommendations +- Quick selection tips for beginners + +### `gaia welcome` +Displays the welcome banner with command overview. + +```bash +gaia welcome +``` + +## System Requirements + +### RAM-Based Recommendations + +| System RAM | Supported Models | Recommendations | +|------------|------------------|-----------------| +| < 8GB | Very limited | Consider upgrading for AI model support | +| 8-16GB | Small models (1B-5B parameters) | Recommended for basic tasks | +| 16GB | Small and Standard models (up to 9B parameters) | Good for most use cases | +| 24GB | Small, Standard, and Medium models (up to 16B parameters) | Enhanced capabilities | +| 32GB | Small through Heavy models (up to 24B parameters) | Professional workloads | +| 64GB | Small through Big models (up to 70B parameters) | Enterprise tasks | +| 128GB+ | All model categories including Max models (70B+) | Maximum capabilities | + +### Model Categories + +#### 🟢 Small Models (1B-5B parameters) - 8-16GB RAM +- **Phi-3 Mini**: Excellent performance-to-size ratio +- **ExaOne 2.4B**: Good for multilingual tasks +- **Ideal for**: Quick responses, basic tasks, mobile/edge deployment + +#### 🟡 Standard Models (6B-9B parameters) - 16GB RAM +- **Llama 3 8B**: Versatile and well-tested +- **9B models**: Run comfortably on 16GB systems +- **Ideal for**: Balanced performance, most common use cases + +#### 🟠 Medium Models (10B-16B parameters) - 24GB RAM +- **13B models**: Enhanced capabilities +- **Ideal for**: Advanced features, better context understanding + +#### 🔵 Heavy Models (17B-24B parameters) - 32GB RAM +- **Codestral 22B**: Specialized for programming tasks +- **Ideal for**: Complex reasoning, professional workloads + +#### 🔴 Big Models (25B-70B parameters) - 64GB RAM +- **30B-70B models**: Maximum performance +- **Ideal for**: Enterprise tasks, research, complex analysis + +#### ⚫ Max Models (70B+ parameters) - 128GB+ RAM +- **DeepSeek, Llama 70B+**: Top-tier capabilities +- **Ideal for**: Contact team for enterprise/cloud deployment + +## Use Case Recommendations + +### 🔧 Coding & Programming +- **Small models**: Basic code completion, syntax help +- **Medium models**: Better code understanding, debugging assistance +- **Big models**: Advanced code generation, complex problem solving +- **Recommended**: Codestral 22B (if RAM > 24GB) or Llama 3 8B + +### 💬 General Chat & Conversation +- **Small models**: Quick responses, basic conversations +- **Medium models**: More natural conversations, better context +- **Big models**: Human-like interactions, complex discussions +- **Recommended**: Llama 3 8B or Phi-3 Mini (for faster responses) + +### ✍️ Creative Writing +- **Small models**: Simple creative tasks, short stories +- **Medium models**: Better storytelling, character development +- **Big models**: Complex narratives, nuanced writing styles +- **Recommended**: Medium or Big instruct models for best creativity + +### ⚡ Resource-Constrained Environments +- Focus on **Small models** (1B-5B parameters) +- **Phi-3 Mini**: Excellent performance-to-size ratio +- **ExaOne 2.4B**: Good for multilingual tasks + +## Safety Features + +The toolkit includes comprehensive safety mechanisms: + +- **Resource Validation**: Checks system capabilities before model selection +- **Performance Warnings**: Alerts when selected model may exceed system limits +- **Multi-Layer Safety**: `gaia run` blocks oversized models with 6-step override process +- **Force Flag Protection**: Requires explicit acknowledgment, typing test, and countdown +- **System Crash Prevention**: Clear warnings about RAM shortage and potential consequences +- **Graceful Fallbacks**: Handles network issues and repository unavailability +- **Error Recovery**: Provides helpful error messages and recovery options + +## Troubleshooting + +### Common Issues + +**TTY Error** +Ensure you're running in a terminal with TTY support. + +**Memory Issues** +Check system RAM and consider smaller models. Use `gaia recommend` for suggestions based on your hardware. + +**Network Issues** +The toolkit includes fallback models for offline scenarios. + +**Permission Errors** +Ensure proper file permissions for installation. You may need to run with `sudo` on some systems. + +### Getting Help + +- Run `gaia help` for comprehensive guidance +- Use `gaia recommend` for personalized suggestions +- Check system requirements before model selection +- Join the [Gaia community](https://t.me/+a0bJInD5lsYxNDJl) for support + +## Next Steps + +After setting up your model with the CLI toolkit: + +1. **Explore Node Configuration**: Learn how to [customize your node](/category/node-guide) +2. **Domain Setup**: Deploy your node to a [custom domain](/category/node-guide/quick-start#configure-the-subdomain) +3. **API Integration**: Use your node with various [frameworks and integrations](/category/gaianet-domain) +4. **Build Applications**: Start building with [decentralized AI agents](/category/agent-frameworks) + +--- + +*The Gaia CLI Toolkit is an open-source project. Contributions are welcome on [GitHub](https://github.com/GaiaNet-AI/gaia-toolkit).* \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index afbf2ddb..5ca3a1af 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -31,6 +31,7 @@ If you are interested in running Gaia nodes, you can * [Get started with a Gaia node](/getting-started/quick-start). * [Customize the Gaia node with a finetuned model and custom knowledge base](/getting-started/customize). * [Join the Gaia Protocol](/getting-started/register) +* [Explore the Gaia CLI toolkit](/getting-started/gaia-toolkit) ### Domain operators diff --git a/docs/tutorial/gaia-toolkit/gaia-toolkit.md b/docs/tutorial/gaia-toolkit/gaia-toolkit.md new file mode 100644 index 00000000..980b24b8 --- /dev/null +++ b/docs/tutorial/gaia-toolkit/gaia-toolkit.md @@ -0,0 +1,318 @@ +--- +sidebar_position: 9 +--- + + +# Gaia CLI Toolkit + +The Gaia CLI Toolkit is a comprehensive command-line interface tool for managing and running various AI models through GaiaNet nodes. It provides intelligent model selection, system-aware recommendations, and seamless setup for your own AI infrastructure. + +## Installation + +Install the toolkit globally via npm: + +```bash +npm install -g gaia-toolkit +``` + +### Prerequisites + +- Node.js environment +- Sufficient system RAM (see [System Requirements](#system-requirements)) +- Internet connection for initial setup +- Terminal with TTY support for interactive prompts + +## Quick Start + +Get started with these essential commands: + +```bash +# Show welcome banner and available commands +gaia + +# Browse available models with filtering options +gaia list + +# Get detailed information about a specific model +gaia info llama3-8b + +# Quick model deployment (install and run) +gaia run llama3-8b + +# Start interactive setup process +gaia setup + +# Get personalized model recommendations +gaia recommend +``` + +## Key Features + +### Smart Model Management +- **Dynamic Model Discovery**: Automatically fetches available models from the GaiaNet repository +- **Command-Line Model Browsing**: List and filter models by size and use case +- **Intelligent Categorization**: Models categorized by size with clear RAM requirements +- **Use Case Analysis**: Models tagged with specific use cases (coding, chat, creative writing, etc.) +- **Direct Model Deployment**: One-command installation and execution with `gaia run` +- **Fallback Support**: Includes reliable fallback models when online repository is unavailable + +### System-Aware Intelligence +- **RAM Analysis**: Automatically detects your system's available memory +- **Smart Recommendations**: Provides personalized suggestions based on your hardware +- **Resource Warnings**: Warns about potential performance issues before installation +- **Safety Mechanisms**: Blocks oversized models that exceed system RAM +- **Compatibility Checks**: Validates system requirements against model requirements + +### Interactive User Experience +- **Beautiful ASCII Art Banner**: Professional welcome screen with Gaia branding +- **Interactive Prompts**: Guided setup process with clear choices +- **Progress Indicators**: Real-time feedback during installation and setup +- **Error Handling**: Graceful fallback and helpful error messages + +## Command Reference + +### `gaia` +Shows the welcome banner with available commands and quick start information. + +```bash +gaia +``` + +### `gaia list` +Browse available models with filtering options. Models are organized by size category with use cases clearly displayed. + +```bash +gaia list [options] +``` + +**Options:** +- `-s, --size `: Filter by size (small, standard, medium, heavy, big, max) +- `-u, --use-case `: Filter by use case (coding, chat, creative, etc.) +- `-f, --format `: Output format (table or json) + +**Examples:** +```bash +gaia list --size small --use-case coding +gaia list --format json +``` + +### `gaia info ` +Get detailed model information including specifications, use cases, system requirements, and compatibility check. + +```bash +gaia info +``` + +**Example:** +```bash +gaia info llama3-8b +``` + +This command provides: +- Model specifications (ID, name, and size category) +- Use cases and capabilities +- System requirements (RAM requirements and performance characteristics) +- Compatibility check against your system +- Step-by-step installation instructions + +### `gaia run ` +Quick model deployment - directly install and run any model with built-in safety mechanisms. + +```bash +gaia run [options] +``` + +**Options:** +- `--skip-install`: Skip GaiaNet installation if already installed +- `--force`: Override safety check ⚠️ **EXTREMELY DANGEROUS** - see [Force Flag Security](#force-flag-security) + +**Examples:** +```bash +gaia run phi3-mini +gaia run phi3-mini --skip-install +``` + +**Workflow:** Validate → Install → Initialize → Start + +#### Force Flag Security (`--force`) + +:::danger +The `--force` flag requires multiple security confirmations to prevent system crashes. Use with extreme caution. +::: + +The force flag protection includes: +1. **System Analysis Display**: Shows exact RAM shortage +2. **Risk Acknowledgment**: Must confirm understanding of crash risks +3. **5-Second Cooling Period**: Enforced wait time to read warnings +4. **Explicit Selection**: Choose from cancel or accept responsibility +5. **Type Confirmation**: Must type "I accept all risks" exactly +6. **Final Countdown**: 3-second countdown with last chance to cancel + +Potential consequences include: +- System freezes requiring hard reset +- Loss of unsaved work in other applications +- Potential hardware stress from memory overload + +### `gaia setup` +Interactive model selection and installation process with guided steps. + +```bash +gaia setup +``` + +This command provides: +1. **System Analysis**: Checks your RAM and provides recommendations +2. **Category Selection**: Choose from Small, Medium, or Big model categories +3. **Model Selection**: Pick a specific model from your chosen category +4. **Installation**: Automatically installs GaiaNet node and configures your model +5. **Launch**: Starts your AI node with the selected model + +### `gaia recommend` +Get personalized model recommendations based on your specific use case. + +```bash +gaia recommend +``` + +Available recommendation categories: +- **Coding & Programming**: Specialized models for development tasks +- **General Chat & Conversation**: Models optimized for natural dialogue +- **Creative Writing**: Models designed for creative content generation +- **Research & Analysis**: Models suited for analytical tasks +- **Resource-Constrained Environment**: Small/lightweight models for limited hardware +- **General Purpose**: Versatile models for various tasks + +### `gaia help` +Comprehensive model selection guide with detailed information. + +```bash +gaia help +``` + +Includes: +- System requirements breakdown +- Performance vs resource trade-offs +- Use case-specific recommendations +- Quick selection tips for beginners + +### `gaia welcome` +Displays the welcome banner with command overview. + +```bash +gaia welcome +``` + +## System Requirements + +### RAM-Based Recommendations + +| System RAM | Supported Models | Recommendations | +|------------|------------------|-----------------| +| < 8GB | Very limited | Consider upgrading for AI model support | +| 8-16GB | Small models (1B-5B parameters) | Recommended for basic tasks | +| 16GB | Small and Standard models (up to 9B parameters) | Good for most use cases | +| 24GB | Small, Standard, and Medium models (up to 16B parameters) | Enhanced capabilities | +| 32GB | Small through Heavy models (up to 24B parameters) | Professional workloads | +| 64GB | Small through Big models (up to 70B parameters) | Enterprise tasks | +| 128GB+ | All model categories including Max models (70B+) | Maximum capabilities | + +### Model Categories + +#### 🟢 Small Models (1B-5B parameters) - 8-16GB RAM +- **Phi-3 Mini**: Excellent performance-to-size ratio +- **ExaOne 2.4B**: Good for multilingual tasks +- **Ideal for**: Quick responses, basic tasks, mobile/edge deployment + +#### 🟡 Standard Models (6B-9B parameters) - 16GB RAM +- **Llama 3 8B**: Versatile and well-tested +- **9B models**: Run comfortably on 16GB systems +- **Ideal for**: Balanced performance, most common use cases + +#### 🟠 Medium Models (10B-16B parameters) - 24GB RAM +- **13B models**: Enhanced capabilities +- **Ideal for**: Advanced features, better context understanding + +#### 🔵 Heavy Models (17B-24B parameters) - 32GB RAM +- **Codestral 22B**: Specialized for programming tasks +- **Ideal for**: Complex reasoning, professional workloads + +#### 🔴 Big Models (25B-70B parameters) - 64GB RAM +- **30B-70B models**: Maximum performance +- **Ideal for**: Enterprise tasks, research, complex analysis + +#### ⚫ Max Models (70B+ parameters) - 128GB+ RAM +- **DeepSeek, Llama 70B+**: Top-tier capabilities +- **Ideal for**: Contact team for enterprise/cloud deployment + +## Use Case Recommendations + +### 🔧 Coding & Programming +- **Small models**: Basic code completion, syntax help +- **Medium models**: Better code understanding, debugging assistance +- **Big models**: Advanced code generation, complex problem solving +- **Recommended**: Codestral 22B (if RAM > 24GB) or Llama 3 8B + +### 💬 General Chat & Conversation +- **Small models**: Quick responses, basic conversations +- **Medium models**: More natural conversations, better context +- **Big models**: Human-like interactions, complex discussions +- **Recommended**: Llama 3 8B or Phi-3 Mini (for faster responses) + +### ✍️ Creative Writing +- **Small models**: Simple creative tasks, short stories +- **Medium models**: Better storytelling, character development +- **Big models**: Complex narratives, nuanced writing styles +- **Recommended**: Medium or Big instruct models for best creativity + +### ⚡ Resource-Constrained Environments +- Focus on **Small models** (1B-5B parameters) +- **Phi-3 Mini**: Excellent performance-to-size ratio +- **ExaOne 2.4B**: Good for multilingual tasks + +## Safety Features + +The toolkit includes comprehensive safety mechanisms: + +- **Resource Validation**: Checks system capabilities before model selection +- **Performance Warnings**: Alerts when selected model may exceed system limits +- **Multi-Layer Safety**: `gaia run` blocks oversized models with 6-step override process +- **Force Flag Protection**: Requires explicit acknowledgment, typing test, and countdown +- **System Crash Prevention**: Clear warnings about RAM shortage and potential consequences +- **Graceful Fallbacks**: Handles network issues and repository unavailability +- **Error Recovery**: Provides helpful error messages and recovery options + +## Troubleshooting + +### Common Issues + +**TTY Error** +Ensure you're running in a terminal with TTY support. + +**Memory Issues** +Check system RAM and consider smaller models. Use `gaia recommend` for suggestions based on your hardware. + +**Network Issues** +The toolkit includes fallback models for offline scenarios. + +**Permission Errors** +Ensure proper file permissions for installation. You may need to run with `sudo` on some systems. + +### Getting Help + +- Run `gaia help` for comprehensive guidance +- Use `gaia recommend` for personalized suggestions +- Check system requirements before model selection +- Join the [Gaia community](https://t.me/+a0bJInD5lsYxNDJl) for support + +## Next Steps + +After setting up your model with the CLI toolkit: + +1. **Explore Node Configuration**: Learn how to [customize your node](/category/node-guide) +2. **Domain Setup**: Deploy your node to a [custom domain](/category/node-guide/quick-start#configure-the-subdomain) +3. **API Integration**: Use your node with various [frameworks and integrations](/category/gaianet-domain) +4. **Build Applications**: Start building with [decentralized AI agents](/category/agent-frameworks) + +--- + +*The Gaia CLI Toolkit is an open-source project. Contributions are welcome on [GitHub](https://github.com/GaiaNet-AI/gaia-toolkit).* \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index a758ff5e..8c81883c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,6 +14,7 @@ "@docusaurus/plugin-google-tag-manager": "^3.8.1", "@docusaurus/preset-classic": "^3.8.1", "@easyops-cn/docusaurus-search-local": "^0.40.1", + "@gracefullight/docusaurus-plugin-microsoft-clarity": "^1.0.0", "@mdx-js/react": "^3.0.0", "cheerio": "1.0.0-rc.12", "clsx": "^2.0.0", @@ -3938,6 +3939,15 @@ "tslib": "^2.4.0" } }, + "node_modules/@gracefullight/docusaurus-plugin-microsoft-clarity": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@gracefullight/docusaurus-plugin-microsoft-clarity/-/docusaurus-plugin-microsoft-clarity-1.0.0.tgz", + "integrity": "sha512-tOFMgF8GdWL4VgdkuPiT/mDYbi4GgtOpq4hVWCg4O3XfSUd7TNGSrzNXnLiOzcO64gQSrBMpB3aQwIpi4gshdw==", + "license": "MIT", + "dependencies": { + "@docusaurus/utils-validation": "^3" + } + }, "node_modules/@hapi/hoek": { "version": "9.3.0", "resolved": "https://registry.npmmirror.com/@hapi/hoek/-/hoek-9.3.0.tgz",