overmind-mcp 2.0.0 → 2.0.1

package/SWARM_USAGE.md

@@ -0,0 +1,444 @@
+# 🐋 OverMind-MCP Swarm Orchestration - Guide d'Utilisation
+
+## 📚 Table des Matières
+
+1. [Introduction](#introduction)
+2. [Configuration du Swarm](#configuration-du-swarm)
+3. [Allocation de Tâches](#allocation-de-tâches)
+4. [Workflows Long-Running](#workflows-long-running)
+5. [Exemples Pratiques](#exemples-pratiques)
+6. [Monitoring & Debug](#monitoring--debug)
+
+---
+
+## 🎯 Introduction
+
+Le **Swarm Orchestration** d'OverMind-MCP permet :
+- **Allocation dynamique** de tâches aux agents spécialisés
+- **Équilibrage de charge** automatique (load balancing)
+- **Workflows stateful** long-running (OSINT, analyses complètes)
+- **Parallélisme intelligent** avec gestion des ressources
+
+---
+
+## 🏗️ Configuration du Swarm
+
+### 1. Définir les Capacités des Agents
+
+```typescript
+import { createSwarmOrchestrator } from 'overmind-mcp';
+
+const swarm = createSwarmOrchestrator({
+  // Liste des agents disponibles avec leurs capacités
+  agents: [
+    {
+      agentName: 'crypto-analyst',
+      runner: 'claude',
+      capabilities: ['analysis', 'crypto', 'osint', 'data-processing'],
+      maxConcurrentTasks: 3,
+      currentLoad: 0,
+      estimatedCompletionTime: 120000 // 2 minutes par tâche
+    },
+    {
+      agentName: 'web-scraper',
+      runner: 'kilo',
+      capabilities: ['scraping', 'web', 'data-extraction'],
+      maxConcurrentTasks: 5,
+      currentLoad: 0,
+      estimatedCompletionTime: 60000 // 1 minute par tâche
+    },
+    {
+      agentName: 'code-reviewer',
+      runner: 'gemini',
+      capabilities: ['code', 'analysis', 'review', 'security'],
+      maxConcurrentTasks: 2,
+      currentLoad: 0,
+      estimatedCompletionTime: 180000 // 3 minutes par tâche
+    }
+  ],
+
+  // Liste des tâches à exécuter
+  tasks: [
+    {
+      id: 'task-1',
+      type: 'analysis',
+      prompt: 'Analyser le sentiment du marché crypto',
+      priority: 10, // 1-10, 10 = priorité maximale
+      requiresCapabilities: ['analysis', 'crypto'],
+      estimatedDuration: 120000
+    },
+    {
+      id: 'task-2',
+      type: 'scraping',
+      prompt: 'Scraper les derniers articles de CoinDesk',
+      priority: 8,
+      requiresCapabilities: ['scraping', 'web'],
+      estimatedDuration: 60000
+    }
+  ],
+
+  maxParallelTasks: 8,        // Nombre max de tâches en parallèle
+  enableLoadBalancing: true,  // Activer l'équilibrage de charge
+  enableTaskPriority: true    // Respecter les priorités des tâches
+});
+```
+
+### 2. Stratégies d'Allocation
+
+**Load Balancing** (recommandé) :
+- Alloue les tâches en fonction de la charge actuelle des agents
+- Prend en compte le temps d'achèvement estimé
+- Optimise l'utilisation des ressources
+
+**Round Robin** (simple) :
+- Alloue les tâches au premier agent disponible
+- Plus rapide mais moins optimal
+
+---
+
+## 🎮 Allocation de Tâches
+
+### Allocation Automatique
+
+```typescript
+// Allouer les tâches aux agents disponibles
+const allocations = await swarm.allocateTasks();
+
+console.log('Allocations:', allocations);
+// [
+//   {
+//     taskId: 'task-1',
+//     agentName: 'crypto-analyst',
+//     runner: 'claude',
+//     estimatedStart: 1699000000000,
+//     estimatedCompletion: 1699000120000
+//   }
+// ]
+```
+
+### Exécution des Tâches Allouées
+
+```typescript
+// Exécuter une tâche spécifique
+const task = swarm.getTaskStatus('task-1');
+const allocation = swarm.allocations.get('task-1');
+
+if (task && allocation) {
+  const result = await swarm.executeTask(task, allocation);
+
+  console.log('Result:', result);
+  // {
+  //   taskId: 'task-1',
+  //   status: 'completed',
+  //   agentName: 'crypto-analyst',
+  //   result: [...],
+  //   startedAt: 1699000000000,
+  //   completedAt: 1699000120000
+  // }
+}
+```
+
+---
+
+## ⏱️ Workflows Long-Running
+
+### 1. Définir un Workflow Long-Running
+
+```typescript
+import { startLongRunningWorkflow } from 'overmind-mcp';
+
+const workflow = await startLongRunningWorkflow({
+  batches: [
+    {
+      id: 'osint-batch-1',
+      status: 'pending',
+      tasks: [
+        {
+          runner: 'claude',
+          prompt: 'OSINT: Analyser les mentions de BTC sur Twitter/X',
+          agentName: 'crypto-analyst'
+        },
+        {
+          runner: 'kilo',
+          prompt: 'Scraper CoinDesk pour les dernières news crypto',
+          agentName: 'web-scraper'
+        }
+      ]
+    },
+    {
+      id: 'osint-batch-2',
+      status: 'pending',
+      tasks: [
+        {
+          runner: 'gemini',
+          prompt: 'Analyser les on-chain metrics de Ethereum',
+          agentName: 'crypto-analyst'
+        }
+      ]
+    }
+  ],
+  maxParallelBatches: 3,
+  batchTimeout: '24 hours'
+});
+
+console.log('Workflow ID:', workflow.workflowId);
+```
+
+### 2. Contrôler le Workflow
+
+```typescript
+// Obtenir l'état actuel
+const state = await workflow.query(LongRunningWorkflowState);
+console.log('State:', state);
+// {
+//   totalBatches: 2,
+//   completedBatches: 1,
+//   failedBatches: 0,
+//   currentBatch: 'osint-batch-2',
+//   errors: []
+// }
+
+// Signaux de contrôle
+await workflow.signal(cancelSignal);  // Annuler le workflow
+await workflow.signal(pauseSignal);   // Mettre en pause
+await workflow.signal(resumeSignal);  // Reprendre
+```
+
+---
+
+## 💼 Exemples Pratiques
+
+### Exemple 1: Veille Crypto 24/7
+
+```typescript
+import { createSwarmOrchestrator } from 'overmind-mcp';
+
+// Créer un swarm pour surveillance crypto 24/7
+const cryptoSwarm = createSwarmOrchestrator({
+  agents: [
+    {
+      agentName: 'btc-sentiment-analyst',
+      runner: 'claude',
+      capabilities: ['sentiment', 'btc', 'social-media'],
+      maxConcurrentTasks: 5,
+      currentLoad: 0
+    },
+    {
+      agentName: 'eth-onchain-analyst',
+      runner: 'gemini',
+      capabilities: ['onchain', 'eth', 'defi'],
+      maxConcurrentTasks: 3,
+      currentLoad: 0
+    }
+  ],
+  tasks: [
+    {
+      id: 'btc-twitter-sentiment',
+      type: 'sentiment-analysis',
+      prompt: 'Analyser le sentiment BTC sur Twitter (dernières 100 mentions)',
+      priority: 10,
+      requiresCapabilities: ['sentiment', 'btc', 'social-media'],
+      estimatedDuration: 300000
+    },
+    {
+      id: 'eth-whale-tracking',
+      type: 'onchain-analysis',
+      prompt: 'Tracker les mouvements de baleines Ethereum (>1000 ETH)',
+      priority: 9,
+      requiresCapabilities: ['onchain', 'eth'],
+      estimatedDuration: 180000
+    }
+  ],
+  maxParallelTasks: 8,
+  enableLoadBalancing: true,
+  enableTaskPriority: true
+});
+
+// Lancer l'allocation
+const allocations = await cryptoSwarm.allocateTasks();
+console.log('Crypto surveillance lancée:', allocations);
+```
+
+### Exemple 2: Analyse de Repos Entiers
+
+```typescript
+import { startLongRunningWorkflow } from 'overmind-mcp';
+
+// Workflow longue durée pour analyser un repo complet
+const repoAnalysisWorkflow = await startLongRunningWorkflow({
+  batches: [
+    {
+      id: 'code-scanning',
+      status: 'pending',
+      tasks: [
+        {
+          runner: 'kilo',
+          prompt: 'Scanner tous les fichiers TypeScript du repo pour vulnérabilités',
+          agentName: 'security-scanner'
+        },
+        {
+          runner: 'claude',
+          prompt: 'Analyser l\'architecture globale du codebase',
+          agentName: 'architect-analyst'
+        }
+      ]
+    },
+    {
+      id: 'code-quality',
+      status: 'pending',
+      tasks: [
+        {
+          runner: 'gemini',
+          prompt: 'Évaluer la qualité du code (duplication, complexité, documentation)',
+          agentName: 'quality-analyst'
+        }
+      ]
+    }
+  ],
+  maxParallelBatches: 2,
+  batchTimeout: '4 hours'
+});
+
+// Surveiller la progression
+setInterval(async () => {
+  const state = await repoAnalysisWorkflow.query();
+  console.log('Analyse en cours:', state);
+}, 60000); // Toutes les minutes
+```
+
+### Exemple 3: Pipeline de Scraping Distribué
+
+```typescript
+// Pipeline de scraping avec allocation dynamique
+const scrapingPipeline = createSwarmOrchestrator({
+  agents: [
+    {
+      agentName: 'news-scraper',
+      runner: 'kilo',
+      capabilities: ['scraping', 'news', 'html-parsing'],
+      maxConcurrentTasks: 10,
+      currentLoad: 0
+    },
+    {
+      agentName: 'social-scraper',
+      runner: 'claude',
+      capabilities: ['scraping', 'social', 'api'],
+      maxConcurrentTasks: 5,
+      currentLoad: 0
+    }
+  ],
+  tasks: [
+    {
+      id: 'scrape-coindesk',
+      type: 'scraping',
+      prompt: 'Scraper les 50 derniers articles de CoinDesk',
+      priority: 10,
+      requiresCapabilities: ['scraping', 'news'],
+      estimatedDuration: 120000
+    },
+    {
+      id: 'scrape-reddit-crypto',
+      type: 'scraping',
+      prompt: 'Scraper r/CryptoCurrency pour les posts trending',
+      priority: 9,
+      requiresCapabilities: ['scraping', 'social'],
+      estimatedDuration: 180000
+    }
+  ],
+  maxParallelTasks: 15,
+  enableLoadBalancing: true,
+  enableTaskPriority: true
+});
+
+// Exécuter en continu
+setInterval(async () => {
+  const stats = scrapingPipeline.getStatistics();
+  console.log('Pipeline stats:', stats);
+  // {
+  //   totalTasks: 100,
+  //   completed: 45,
+  //   failed: 2,
+  //   running: 10,
+  //   pending: 43,
+  //   totalAgents: 2,
+  //   averageLoad: 3.5
+  // }
+}, 30000); // Toutes les 30 secondes
+```
+
+---
+
+## 🔍 Monitoring & Debug
+
+### Statistiques du Swarm
+
+```typescript
+// Statistiques globales
+const stats = swarm.getStatistics();
+console.log('Swarm Statistics:', stats);
+// {
+//   totalTasks: 50,
+//   completed: 20,
+//   failed: 2,
+//   running: 5,
+//   pending: 23,
+//   totalAgents: 3,
+//   averageLoad: 2.5
+// }
+
+// État d'un agent spécifique
+const agentStatus = swarm.getAgentStatus('crypto-analyst');
+console.log('Agent Status:', agentStatus);
+// {
+//   agentName: 'crypto-analyst',
+//   runner: 'claude',
+//   capabilities: ['analysis', 'crypto', 'osint'],
+//   maxConcurrentTasks: 3,
+//   currentLoad: 2,
+//   estimatedCompletionTime: 120000
+// }
+
+// Résultats de toutes les tâches
+const allResults = swarm.getAllResults();
+console.log('All Results:', allResults);
+
+// Tâches en attente
+const pendingTasks = swarm.getPendingTasks();
+console.log('Pending Tasks:', pendingTasks);
+```
+
+### Debug Workflow Long-Running
+
+```typescript
+// Obtenir un handle sur un workflow existant
+import { getLongRunningWorkflowHandle } from 'overmind-mcp';
+
+const workflow = await getLongRunningWorkflowHandle('long-running-1699000000');
+
+// État actuel
+const state = await workflow.query();
+console.log('Workflow State:', state);
+
+// Historique d'exécution
+const history = await workflow.history();
+console.log('Workflow History:', history.events);
+```
+
+---
+
+## 🚀 Bonnes Pratiques
+
+1. **Capacités des Agents** : Définissez des capacités précises pour une allocation optimale
+2. **Priorités des Tâches** : Utilisez la priorité (1-10) pour les tâches critiques
+3. **Parallelisme** : Ajustez `maxParallelTasks` selon vos ressources (RAM, CPU)
+4. **Timeouts** : Définissez des `estimatedDuration` réalistes pour éviter les blocages
+5. **Monitoring** : Surveillez régulièrement les statistiques du swarm
+6. **Fallback** : Prévoyez des agents de secours pour les tâches critiques
+
+---
+
+## 📚 Ressources Additionnelles
+
+- **API Temporal**: https://docs.temporal.io
+- **Guide Swarm**: https://github.com/DeamonDev888/overmind-mcp
+- **Support Discord**: https://discord.gg/4AR82phtBz

package/docker-compose.overmind.yml

@@ -0,0 +1,172 @@
+version: '3.8'
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OverMind-MCP Docker Compose (Minimal Setup)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Setup minimal pour OverMind-MCP qui RÉUTILISE votre PostgreSQL existant
+# Services: RabbitMQ (Message Broker) + Temporal (Workflow Orchestrator)
+#
+# Prérequis:
+#   - Docker Desktop installé et démarré
+#   - PostgreSQL + pgvector déjà en Docker (container: postgres-pgvector)
+#   - Base de données 'overmind_memory' créée
+#
+# Usage:
+#   docker-compose -f docker-compose.overmind.yml up -d
+# ═══════════════════════════════════════════════════════════════════════════════
+
+services:
+  # ───────────────────────────────────────────────────────────────────────────────
+  # RABBITMQ (Message Broker)
+  # ───────────────────────────────────────────────────────────────────────────────
+  # Gère les files d'attente de messages entre agents
+  # Management UI: http://localhost:15672 (user: overmind, pass: overmind_secret_password)
+  rabbitmq:
+    image: rabbitmq:3.13-management
+    container_name: overmind-rabbitmq
+    hostname: overmind-rabbitmq
+    ports:
+      - "5672:5672"   # AMQP protocol (pour OverMind)
+      - "15672:15672" # Management UI (interface web)
+    environment:
+      # Credentials par défaut (À CHANGER en production !)
+      RABBITMQ_DEFAULT_USER: overmind
+      RABBITMQ_DEFAULT_PASS: overmind_secret_password_change_me
+      # Logs configuration
+      RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: -rabbit log_levels [{connection,error},{default,warning}]
+    volumes:
+      - rabbitmq_data:/var/lib/rabbitmq
+    networks:
+      - overmind-network
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    restart: unless-stopped
+
+  # ───────────────────────────────────────────────────────────────────────────────
+  # TEMPORAL (Workflow Orchestrator)
+  # ───────────────────────────────────────────────────────────────────────────────
+  # Gère les workflows long-running (OSINT, analyses continues)
+  # Web UI: http://localhost:8088
+  temporal:
+    image: temporalio/auto-setup:1.24.0
+    container_name: overmind-temporal
+    hostname: overmind-temporal
+    ports:
+      - "7233:7233"   # gRPC endpoint (pour OverMind)
+      - "8233:8233"   # Web UI (interface web)
+    environment:
+      # Configuration PostgreSQL (votre container existant)
+      DB: postgres
+      POSTGRES_SEEDS: host.docker.internal  # IMPORTANT: Accès à Windows host
+      POSTGRES_USER: postgres
+      POSTGRES_PWD: postgres  # ← À CHANGER avec votre vrai mot de passe
+      POSTGRES_DB: temporal
+      # Configuration Temporal
+      TEMPERAL_ADDRESS: temporal:7233
+      TEMPORAL_CLI_ADDRESS: temporal:7233
+      SERVICES: frontend,history,matching,worker,web-ui
+    networks:
+      - overmind-network
+    restart: unless-stopped
+
+  # ───────────────────────────────────────────────────────────────────────────────
+  # TEMPORAL WEB (UI Temporal)
+  # ───────────────────────────────────────────────────────────────────────────────
+  # Interface web pour visualiser les workflows
+  # URL: http://localhost:8088
+  temporal-web:
+    image: temporalio/web:1.24.0
+    container_name: overmind-temporal-web
+    hostname: overmind-temporal-web
+    ports:
+      - "8088:8088"
+    environment:
+      TEMPORAL_GRPC_ENDPOINT: temporal:7233
+      TEMPORAL_PERMIT_WRITE_API: true
+    networks:
+      - overmind-network
+    depends_on:
+      - temporal
+    restart: unless-stopped
+
+  # ───────────────────────────────────────────────────────────────────────────────
+  # PROMETHEUS (Metrics Collection) - OPTIONNEL
+  # ───────────────────────────────────────────────────────────────────────────────
+  # Collecte les métriques d'OverMind (RAM, queues, tokens)
+  # URL: http://localhost:9090
+  #
+  # Pour activer: Décommentez le service ci-dessous et le service grafana
+  # ───────────────────────────────────────────────────────────────────────────────
+  # prometheus:
+  #   image: prom/prometheus:v2.55.1
+  #   container_name: overmind-prometheus
+  #   hostname: overmind-prometheus
+  #   ports:
+  #     - "9090:9090"
+  #   volumes:
+  #     - ./config/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+  #     - prometheus_data:/prometheus
+  #   command:
+  #     - '--config.file=/etc/prometheus/prometheus.yml'
+  #     - '--storage.tsdb.path=/prometheus'
+  #     - '--web.enable-lifecycle'
+  #   networks:
+  #     - overmind-network
+  #   restart: unless-stopped
+
+  # ───────────────────────────────────────────────────────────────────────────────
+  # GRAFANA (Dashboards) - OPTIONNEL
+  # ───────────────────────────────────────────────────────────────────────────────
+  # Visualise les métriques Prometheus
+  # URL: http://localhost:3000 (user: admin, pass: grafana_password)
+  #
+  # Pour activer: Décommentez le service ci-dessous
+  # ───────────────────────────────────────────────────────────────────────────────
+  # grafana:
+  #   image: grafana/grafana:11.3.1
+  #   container_name: overmind-grafana
+  #   hostname: overmind-grafana
+  #   ports:
+  #     - "3000:3000"
+  #   environment:
+  #     GF_SECURITY_ADMIN_USER: admin
+  #     GF_SECURITY_ADMIN_PASSWORD: grafana_password_change_me
+  #     GF_INSTALL_PLUGINS: grafana-piechart-panel
+  #     GF_USERS_ALLOW_SIGN_UP: "false"
+  #   volumes:
+  #     - grafana_data:/var/lib/grafana
+  #     - ./config/grafana/provisioning:/etc/grafana/provisioning:ro
+  #   networks:
+  #     - overmind-network
+  #   depends_on:
+  #     - prometheus
+  #   restart: unless-stopped
+
+# ─────────────────────────────────────────────────────────────────────────────────
+# NETWORKS
+# ─────────────────────────────────────────────────────────────────────────────────
+networks:
+  overmind-network:
+    driver: bridge
+    name: overmind-network
+    ipam:
+      config:
+        - subnet: 172.20.0.0/16
+
+# ─────────────────────────────────────────────────────────────────────────────────
+# VOLUMES
+# ─────────────────────────────────────────────────────────────────────────────────
+volumes:
+  rabbitmq_data:
+    name: overmind-rabbitmq-data
+    driver: local
+  # prometheus_data:
+  #   name: overmind-prometheus-data
+  #   driver: local
+  # grafana_data:
+  #   name: overmind-grafana-data
+  #   driver: local

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "overmind-mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "preferGlobal": true,
-  "description": "Orchestrateur universel agents IA multi-modeles via MCP. Inclut le protocole 'Custom-Nickname' pour identifier vos agents avec des surnoms originaux (The Chaos Prophet, Shadow Sniper, etc.), l'isolation mémoire (Private Memory Context) et le support pour QwenCli et Nous Hermes.",
+  "description": "Orchestrateur universel agents IA multi-modeles via MCP. Inclut le protocole 'Custom-Nickname' pour identifier vos agents avec des surnoms originaux (The Chaos Prophet, Shadow Sniper, etc.), l'isolation mémoire (Private Memory Context) et le support pour QwenCli et Nous Hermes. Installation automatique des dépendances Docker (PostgreSQL, pgvector) inclus.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "overmind": "dist/bin/cli.js"
+    "overmind": "./dist/bin/cli.js",
+    "overmind-setup": "./scripts/setup.mjs",
+    "overmind-infra": "./scripts/docker-manager.mjs"
   },
   "exports": {
     ".": {
@@ -19,7 +21,18 @@
   "files": [
     "dist",
     "assets",
-    "README.md"
+    "README.md",
+    "SETUP_WINDOWS.md",
+    "DEPLOYMENT.md",
+    "SWARM_USAGE.md",
+    "CHANGELOG.md",
+    "docker-compose.overmind.yml",
+    "scripts",
+    "scripts/setup.js",
+    "scripts/setup-overmind-db.js",
+    "scripts/docker-manager.js",
+    "scripts/install-dependencies.js",
+    "scripts/postinstall.js"
   ],
   "scripts": {
     "build": "tsc",
@@ -39,12 +52,15 @@
     "version": "changeset version",
     "release": "pnpm run build && changeset publish",
     "prepublishOnly": "pnpm run rebuild",
-    "deploy:infra": "docker-compose up -d",
-    "deploy:exporters": "docker-compose -f docker-compose.exporters.yml up -d",
-    "deploy:all": "docker-compose up -d && docker-compose -f docker-compose.exporters.yml up -d",
-    "deploy:down": "docker-compose down",
-    "deploy:logs": "docker-compose logs -f",
-    "deploy:status": "docker-compose ps"
+    "postinstall": "node scripts/postinstall.mjs",
+    "setup": "overmind-setup",
+    "setup:full": "overmind-setup --full",
+    "setup:deps": "node scripts/install-dependencies.mjs",
+    "deploy:infra": "overmind-infra up",
+    "deploy:down": "overmind-infra down",
+    "deploy:status": "overmind-infra status",
+    "deploy:logs": "overmind-infra logs",
+    "deploy:restart": "overmind-infra restart"
   },
   "keywords": [
     "mcp",
@@ -53,7 +69,14 @@
     "ai-agent",
     "llm",
     "orchestration",
-    "automation"
+    "automation",
+    "swarm",
+    "temporal",
+    "rabbitmq",
+    "pgvector",
+    "observability",
+    "docker",
+    "auto-installation"
   ],
   "author": "DeaMoN888",
   "license": "MIT",