mageagent-local 2.0.1

package/bin/mageagent.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+/**
+ * MageAgent CLI
+ * Multi-Model AI Orchestration for Apple Silicon
+ */
+
+import { spawn, execSync } from 'child_process';
+import { existsSync, mkdirSync, copyFileSync, chmodSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = join(__dirname, '..');
+
+const CLAUDE_DIR = join(homedir(), '.claude');
+const MAGEAGENT_DIR = join(CLAUDE_DIR, 'mageagent');
+const SCRIPTS_DIR = join(CLAUDE_DIR, 'scripts');
+const DEBUG_DIR = join(CLAUDE_DIR, 'debug');
+const MODELS_DIR = join(homedir(), '.cache', 'mlx-models');
+const SERVER_SCRIPT = join(SCRIPTS_DIR, 'mageagent-server.sh');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${COLORS[color]}${message}${COLORS.reset}`);
+}
+
+function checkAppleSilicon() {
+  try {
+    const arch = execSync('uname -m').toString().trim();
+    if (arch !== 'arm64') {
+      log('Error: MageAgent requires Apple Silicon (M1/M2/M3/M4)', 'red');
+      process.exit(1);
+    }
+  } catch (e) {
+    log('Error: Could not detect system architecture', 'red');
+    process.exit(1);
+  }
+}
+
+function checkPython() {
+  try {
+    execSync('python3 --version', { stdio: 'pipe' });
+    return true;
+  } catch (e) {
+    log('Error: Python 3 is required but not installed', 'red');
+    log('Install from: https://www.python.org/', 'yellow');
+    return false;
+  }
+}
+
+function ensureDirectories() {
+  [CLAUDE_DIR, MAGEAGENT_DIR, SCRIPTS_DIR, DEBUG_DIR, MODELS_DIR].forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      log(`Created: ${dir}`, 'green');
+    }
+  });
+}
+
+function copyServerFiles() {
+  const serverSrc = join(packageRoot, 'mageagent', 'server.py');
+  const serverDst = join(MAGEAGENT_DIR, 'server.py');
+
+  const scriptSrc = join(packageRoot, 'scripts', 'mageagent-server.sh');
+  const scriptDst = SERVER_SCRIPT;
+
+  if (existsSync(serverSrc)) {
+    copyFileSync(serverSrc, serverDst);
+    log(`Installed: ${serverDst}`, 'green');
+  }
+
+  if (existsSync(scriptSrc)) {
+    copyFileSync(scriptSrc, scriptDst);
+    chmodSync(scriptDst, '755');
+    log(`Installed: ${scriptDst}`, 'green');
+  }
+}
+
+function installPythonDeps() {
+  log('\nInstalling Python dependencies...', 'cyan');
+  try {
+    execSync('pip3 install --quiet mlx mlx-lm fastapi uvicorn pydantic huggingface_hub', {
+      stdio: 'inherit'
+    });
+    log('Python dependencies installed', 'green');
+    return true;
+  } catch (e) {
+    log('Failed to install Python dependencies', 'red');
+    return false;
+  }
+}
+
+function runServerCommand(command) {
+  if (!existsSync(SERVER_SCRIPT)) {
+    log('Error: MageAgent not installed. Run: mageagent install', 'red');
+    process.exit(1);
+  }
+
+  const child = spawn(SERVER_SCRIPT, [command], {
+    stdio: 'inherit',
+    shell: true
+  });
+
+  child.on('close', (code) => {
+    process.exit(code);
+  });
+}
+
+function downloadModels() {
+  log('\nDownloading MLX models (~110GB total)...', 'cyan');
+  log('This will take 30-60 minutes depending on your connection.\n', 'yellow');
+
+  const models = [
+    { name: 'Hermes-3-Llama-3.1-8B-8bit', size: '9GB', role: 'Tool calling' },
+    { name: 'Qwen2.5-Coder-7B-Instruct-4bit', size: '5GB', role: 'Validation' },
+    { name: 'Qwen2.5-Coder-32B-Instruct-4bit', size: '18GB', role: 'Code generation' },
+    { name: 'Qwen2.5-72B-Instruct-8bit', size: '77GB', role: 'Primary reasoning' },
+  ];
+
+  for (const model of models) {
+    const modelPath = join(MODELS_DIR, model.name);
+    if (existsSync(modelPath)) {
+      log(`Skipping ${model.name} (already exists)`, 'yellow');
+      continue;
+    }
+
+    log(`Downloading ${model.name} (${model.size}) - ${model.role}...`, 'blue');
+
+    try {
+      execSync(`python3 -c "
+from huggingface_hub import snapshot_download
+snapshot_download('mlx-community/${model.name}', local_dir='${modelPath}')
+"`, { stdio: 'inherit' });
+      log(`Downloaded: ${model.name}`, 'green');
+    } catch (e) {
+      log(`Failed to download ${model.name}`, 'red');
+    }
+  }
+}
+
+function showHelp() {
+  console.log(`
+${COLORS.cyan}MageAgent - Multi-Model AI Orchestration for Apple Silicon${COLORS.reset}
+
+${COLORS.yellow}Usage:${COLORS.reset}
+  mageagent <command>
+
+${COLORS.yellow}Commands:${COLORS.reset}
+  install     Install MageAgent server and dependencies
+  start       Start the MageAgent server
+  stop        Stop the MageAgent server
+  restart     Restart the MageAgent server
+  status      Check server status
+  logs        View server logs
+  models      Download required MLX models
+  test        Test the API endpoint
+  help        Show this help message
+
+${COLORS.yellow}Examples:${COLORS.reset}
+  mageagent install    # First-time setup
+  mageagent start      # Start server on port 3457
+  mageagent status     # Check if running
+
+${COLORS.yellow}After installation:${COLORS.reset}
+  curl http://localhost:3457/health
+
+${COLORS.yellow}More info:${COLORS.reset}
+  https://github.com/adverant/nexus-local-mageagent
+`);
+}
+
+function testApi() {
+  log('\nTesting MageAgent API...', 'cyan');
+  try {
+    const result = execSync('curl -s http://localhost:3457/health').toString();
+    const health = JSON.parse(result);
+    log('\nServer Status: ' + health.status, 'green');
+    log('Loaded Models: ' + health.loaded_models.join(', '), 'blue');
+    log('Available Models: ' + health.available_models.join(', '), 'blue');
+  } catch (e) {
+    log('Error: Could not connect to MageAgent server', 'red');
+    log('Make sure the server is running: mageagent start', 'yellow');
+    process.exit(1);
+  }
+}
+
+// Main CLI
+const command = process.argv[2] || 'help';
+
+switch (command) {
+  case 'install':
+    log('\n=== MageAgent Installation ===\n', 'cyan');
+    checkAppleSilicon();
+    if (!checkPython()) process.exit(1);
+    ensureDirectories();
+    copyServerFiles();
+    installPythonDeps();
+    log('\nInstallation complete!', 'green');
+    log('\nNext steps:', 'yellow');
+    log('  1. Download models: mageagent models', 'reset');
+    log('  2. Start server:    mageagent start', 'reset');
+    log('  3. Test:            mageagent test\n', 'reset');
+    break;
+
+  case 'models':
+    checkAppleSilicon();
+    downloadModels();
+    break;
+
+  case 'start':
+    runServerCommand('start');
+    break;
+
+  case 'stop':
+    runServerCommand('stop');
+    break;
+
+  case 'restart':
+    runServerCommand('restart');
+    break;
+
+  case 'status':
+    runServerCommand('status');
+    break;
+
+  case 'logs':
+    runServerCommand('logs');
+    break;
+
+  case 'test':
+    testApi();
+    break;
+
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+
+  default:
+    log(`Unknown command: ${command}`, 'red');
+    showHelp();
+    process.exit(1);
+}

package/bin/postinstall.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * MageAgent Post-Install Script
+ * Shows helpful information after npm install
+ */
+
+const COLORS = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+console.log(`
+${COLORS.cyan}═══════════════════════════════════════════════════════════════${COLORS.reset}
+${COLORS.green}  MageAgent installed successfully!${COLORS.reset}
+${COLORS.cyan}═══════════════════════════════════════════════════════════════${COLORS.reset}
+
+${COLORS.yellow}Quick Start:${COLORS.reset}
+
+  1. Complete installation:
+     ${COLORS.green}mageagent install${COLORS.reset}
+
+  2. Download MLX models (~110GB):
+     ${COLORS.green}mageagent models${COLORS.reset}
+
+  3. Start the server:
+     ${COLORS.green}mageagent start${COLORS.reset}
+
+  4. Test it:
+     ${COLORS.green}mageagent test${COLORS.reset}
+
+${COLORS.yellow}Requirements:${COLORS.reset}
+  - Apple Silicon Mac (M1/M2/M3/M4)
+  - 64GB+ unified memory (128GB recommended)
+  - Python 3.9+
+
+${COLORS.yellow}Documentation:${COLORS.reset}
+  https://github.com/adverant/nexus-local-mageagent
+
+${COLORS.cyan}═══════════════════════════════════════════════════════════════${COLORS.reset}
+`);

package/config/com.adverant.mageagent.plist

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adverant.mageagent</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/python3</string>
+        <string>/Users/don/.claude/mageagent/server.py</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/don/.claude/debug/mageagent.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/Users/don/.claude/debug/mageagent.error.log</string>
+
+    <key>WorkingDirectory</key>
+    <string>/Users/don/.claude/mageagent</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>30</integer>
+</dict>
+</plist>

package/config/config.example.json

@@ -0,0 +1,41 @@
+{
+  "providers": [
+    {
+      "name": "mageagent",
+      "api_base_url": "http://localhost:3457/v1/chat/completions",
+      "api_key": "local",
+      "models": [
+        "mageagent:auto",
+        "mageagent:hybrid",
+        "mageagent:validated",
+        "mageagent:compete",
+        "mageagent:tools",
+        "mageagent:primary",
+        "mageagent:validator",
+        "mageagent:competitor"
+      ]
+    },
+    {
+      "name": "ollama",
+      "api_base_url": "http://localhost:11434/v1/chat/completions",
+      "api_key": "ollama",
+      "models": [
+        "qwen2.5:72b",
+        "qwen2.5-coder:32b",
+        "qwen2.5-coder:1.5b"
+      ]
+    },
+    {
+      "name": "anthropic",
+      "api_base_url": "https://api.anthropic.com",
+      "api_key": "${ANTHROPIC_API_KEY}",
+      "models": [
+        "claude-opus-4-5-20251101",
+        "claude-sonnet-4-5-20250929"
+      ]
+    }
+  ],
+  "Router": {
+    "default": "mageagent,mageagent:hybrid"
+  }
+}

package/docs/AUTOSTART.md

@@ -0,0 +1,300 @@
+# Auto-Start Configuration
+
+> Configure MageAgent to start automatically on macOS boot
+
+## Overview
+
+MageAgent can be configured to start automatically when your Mac boots using macOS LaunchAgents. This ensures the server is always available without manual intervention.
+
+## Quick Setup
+
+The install script can set this up for you:
+
+```bash
+./scripts/install.sh
+# Answer "y" when prompted about auto-start
+```
+
+## Manual Setup
+
+### Step 1: Create the LaunchAgent
+
+Create the plist file at `~/Library/LaunchAgents/com.adverant.mageagent.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adverant.mageagent</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/python3</string>
+        <string>/Users/YOUR_USERNAME/.claude/mageagent/server.py</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/YOUR_USERNAME/.claude/debug/mageagent.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/Users/YOUR_USERNAME/.claude/debug/mageagent.error.log</string>
+
+    <key>WorkingDirectory</key>
+    <string>/Users/YOUR_USERNAME/.claude/mageagent</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+    </dict>
+</dict>
+</plist>
+```
+
+**Important**: Replace `YOUR_USERNAME` with your actual username (e.g., `/Users/don/`).
+
+### Step 2: Load the LaunchAgent
+
+```bash
+# Unload if already loaded
+launchctl unload ~/Library/LaunchAgents/com.adverant.mageagent.plist 2>/dev/null
+
+# Load the agent
+launchctl load ~/Library/LaunchAgents/com.adverant.mageagent.plist
+```
+
+### Step 3: Verify It's Running
+
+```bash
+# Check if loaded
+launchctl list | grep mageagent
+
+# Check if server is responding
+curl http://localhost:3457/health
+```
+
+## LaunchAgent Options Explained
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `Label` | `com.adverant.mageagent` | Unique identifier for this service |
+| `ProgramArguments` | Array | Command to run (python3 + script path) |
+| `RunAtLoad` | `true` | Start when agent is loaded (at boot) |
+| `KeepAlive` | `true` | Restart if process exits |
+| `StandardOutPath` | Path | Where to write stdout logs |
+| `StandardErrorPath` | Path | Where to write stderr logs |
+| `WorkingDirectory` | Path | Working directory for the process |
+| `EnvironmentVariables` | Dict | Environment variables to set |
+
+## Managing the Service
+
+### Start the Service
+
+```bash
+launchctl start com.adverant.mageagent
+```
+
+### Stop the Service
+
+```bash
+launchctl stop com.adverant.mageagent
+```
+
+### Restart the Service
+
+```bash
+launchctl stop com.adverant.mageagent
+launchctl start com.adverant.mageagent
+```
+
+### Disable Auto-Start
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.adverant.mageagent.plist
+```
+
+### Re-Enable Auto-Start
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.adverant.mageagent.plist
+```
+
+### Remove Auto-Start Completely
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.adverant.mageagent.plist
+rm ~/Library/LaunchAgents/com.adverant.mageagent.plist
+```
+
+## Viewing Logs
+
+### Real-time Server Logs
+
+```bash
+tail -f ~/.claude/debug/mageagent.log
+```
+
+### Error Logs
+
+```bash
+tail -f ~/.claude/debug/mageagent.error.log
+```
+
+### System Logs (launchd)
+
+```bash
+log show --predicate 'subsystem == "com.apple.launchd"' --last 5m | grep mageagent
+```
+
+## Troubleshooting
+
+### Service Won't Start
+
+1. **Check the plist syntax**:
+   ```bash
+   plutil -lint ~/Library/LaunchAgents/com.adverant.mageagent.plist
+   ```
+
+2. **Verify paths exist**:
+   ```bash
+   ls -la ~/.claude/mageagent/server.py
+   ls -la ~/.claude/debug/
+   ```
+
+3. **Check Python is accessible**:
+   ```bash
+   /usr/bin/python3 --version
+   ```
+
+4. **Check error logs**:
+   ```bash
+   cat ~/.claude/debug/mageagent.error.log
+   ```
+
+### Service Keeps Restarting
+
+If `KeepAlive` is true and the service crashes, launchd will restart it. Check logs for crash reasons:
+
+```bash
+# View recent crashes
+cat ~/.claude/debug/mageagent.error.log | tail -100
+```
+
+Common causes:
+- Missing Python dependencies
+- Port 3457 already in use
+- Insufficient memory for models
+
+### Port Already in Use
+
+```bash
+# Find what's using port 3457
+lsof -i :3457
+
+# Kill the process if needed
+kill -9 <PID>
+```
+
+### Memory Issues
+
+If the server crashes due to memory, you may need to:
+
+1. Close other applications
+2. Use smaller models (edit server.py)
+3. Increase swap space
+
+Check memory usage:
+```bash
+# Current memory pressure
+memory_pressure
+
+# Top memory consumers
+top -l 1 -o mem | head -20
+```
+
+## Advanced Configuration
+
+### Delay Start Until Network Ready
+
+Add these keys to wait for network:
+
+```xml
+<key>NetworkState</key>
+<true/>
+```
+
+### Run Only When Logged In
+
+The default configuration in `~/Library/LaunchAgents/` only runs when you're logged in. For system-wide (all users), use `/Library/LaunchDaemons/` instead (requires admin).
+
+### Resource Limits
+
+Add resource limits if needed:
+
+```xml
+<key>HardResourceLimits</key>
+<dict>
+    <key>NumberOfFiles</key>
+    <integer>1024</integer>
+</dict>
+
+<key>SoftResourceLimits</key>
+<dict>
+    <key>NumberOfFiles</key>
+    <integer>1024</integer>
+</dict>
+```
+
+### Throttle Restarts
+
+Prevent rapid restart loops:
+
+```xml
+<key>ThrottleInterval</key>
+<integer>30</integer>
+```
+
+This waits 30 seconds between restart attempts.
+
+## Verification Checklist
+
+After setup, verify everything works:
+
+- [ ] LaunchAgent file exists at correct path
+- [ ] File syntax is valid (`plutil -lint`)
+- [ ] Agent is loaded (`launchctl list | grep mageagent`)
+- [ ] Server responds (`curl http://localhost:3457/health`)
+- [ ] Logs are being written (`ls -la ~/.claude/debug/`)
+- [ ] Service survives reboot (restart and check)
+
+## Alternative: Using the Management Script
+
+Instead of launchctl directly, you can use the provided script:
+
+```bash
+# Start server
+~/.claude/scripts/mageagent-server.sh start
+
+# Stop server
+~/.claude/scripts/mageagent-server.sh stop
+
+# Check status
+~/.claude/scripts/mageagent-server.sh status
+
+# View logs
+~/.claude/scripts/mageagent-server.sh logs
+```
+
+The management script provides a simpler interface but doesn't persist across reboots unless combined with LaunchAgents.
+
+---
+
+*Made with care by [Adverant](https://github.com/adverant)*