@holoscript/framework 6.0.3

package/src/swarm/ACOEngine.ts

@@ -0,0 +1,261 @@
+/**
+ * Ant Colony Optimization Engine
+ *
+ * Implements ACO algorithm for path-finding and task sequencing.
+ * Uses pheromone trails to find optimal ordering of choreography steps.
+ */
+
+export interface ACOConfig {
+  antCount: number;
+  maxIterations: number;
+  convergenceThreshold: number;
+  alpha: number; // Pheromone importance
+  beta: number; // Heuristic importance
+  evaporationRate: number;
+  q: number; // Pheromone deposit factor
+  elitistWeight: number;
+}
+
+export interface ACOResult {
+  bestPath: number[];
+  bestCost: number;
+  converged: boolean;
+  iterations: number;
+  costHistory: number[];
+}
+
+const DEFAULT_CONFIG: ACOConfig = {
+  antCount: 20,
+  maxIterations: 100,
+  convergenceThreshold: 0.001,
+  alpha: 1.0,
+  beta: 2.0,
+  evaporationRate: 0.1,
+  q: 100,
+  elitistWeight: 2.0,
+};
+
+/**
+ * Ant Colony Optimization engine for path/sequence optimization
+ */
+export class ACOEngine {
+  private config: ACOConfig;
+
+  constructor(config: Partial<ACOConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Find optimal path through nodes (e.g., task execution order)
+   *
+   * @param nodes Number of nodes to visit
+   * @param distanceMatrix Distance/cost between nodes [i][j]
+   * @returns Optimization result with best path
+   */
+  async optimize(nodes: number, distanceMatrix: number[][]): Promise<ACOResult> {
+    const { antCount, maxIterations, convergenceThreshold } = this.config;
+
+    // Initialize pheromone trails
+    const pheromones = this.initializePheromones(nodes);
+    const heuristics = this.computeHeuristics(distanceMatrix);
+
+    let bestPath: number[] = [];
+    let bestCost = Infinity;
+    const costHistory: number[] = [];
+    let converged = false;
+    let iteration = 0;
+
+    // Main optimization loop
+    for (iteration = 0; iteration < maxIterations; iteration++) {
+      const paths: number[][] = [];
+      const costs: number[] = [];
+
+      // Each ant constructs a solution
+      for (let ant = 0; ant < antCount; ant++) {
+        const path = this.constructSolution(nodes, pheromones, heuristics);
+        const cost = this.calculatePathCost(path, distanceMatrix);
+
+        paths.push(path);
+        costs.push(cost);
+
+        if (cost < bestCost) {
+          bestCost = cost;
+          bestPath = [...path];
+        }
+      }
+
+      costHistory.push(bestCost);
+
+      // Evaporate pheromones
+      this.evaporatePheromones(pheromones);
+
+      // Deposit pheromones based on path quality
+      this.depositPheromones(pheromones, paths, costs);
+
+      // Elitist reinforcement: extra pheromone on best path
+      this.reinforceBestPath(pheromones, bestPath, bestCost);
+
+      // Check convergence
+      if (iteration > 10) {
+        const recentImprovement = costHistory[iteration - 10] - bestCost;
+        if (Math.abs(recentImprovement) < convergenceThreshold * bestCost) {
+          converged = true;
+          break;
+        }
+      }
+    }
+
+    return {
+      bestPath,
+      bestCost,
+      converged,
+      iterations: iteration + 1,
+      costHistory,
+    };
+  }
+
+  /**
+   * Initialize pheromone matrix with uniform values
+   */
+  private initializePheromones(nodes: number): number[][] {
+    const initial = 1.0 / nodes;
+    return Array.from({ length: nodes }, () => Array.from({ length: nodes }, () => initial));
+  }
+
+  /**
+   * Compute heuristic values (inverse distance)
+   */
+  private computeHeuristics(distanceMatrix: number[][]): number[][] {
+    const nodes = distanceMatrix.length;
+    return Array.from({ length: nodes }, (_, i) =>
+      Array.from({ length: nodes }, (_, j) => {
+        const dist = distanceMatrix[i][j];
+        return dist > 0 ? 1.0 / dist : 0;
+      })
+    );
+  }
+
+  /**
+   * Construct a solution path for one ant
+   */
+  private constructSolution(
+    nodes: number,
+    pheromones: number[][],
+    heuristics: number[][]
+  ): number[] {
+    const { alpha, beta } = this.config;
+    const path: number[] = [];
+    const visited = new Set<number>();
+
+    // Start from random node
+    let current = Math.floor(Math.random() * nodes);
+    path.push(current);
+    visited.add(current);
+
+    // Visit all remaining nodes
+    while (path.length < nodes) {
+      const probabilities: number[] = [];
+      let sum = 0;
+
+      // Calculate selection probabilities
+      for (let next = 0; next < nodes; next++) {
+        if (visited.has(next)) {
+          probabilities.push(0);
+        } else {
+          const phero = Math.pow(pheromones[current][next], alpha);
+          const heur = Math.pow(heuristics[current][next], beta);
+          const prob = phero * heur;
+          probabilities.push(prob);
+          sum += prob;
+        }
+      }
+
+      // Normalize and select next node
+      if (sum === 0) {
+        // Fallback: choose random unvisited
+        const unvisited = Array.from({ length: nodes }, (_, i) => i).filter((n) => !visited.has(n));
+        current = unvisited[Math.floor(Math.random() * unvisited.length)];
+      } else {
+        // Roulette wheel selection
+        const r = Math.random() * sum;
+        let cumulative = 0;
+        for (let next = 0; next < nodes; next++) {
+          cumulative += probabilities[next];
+          if (cumulative >= r) {
+            current = next;
+            break;
+          }
+        }
+      }
+
+      path.push(current);
+      visited.add(current);
+    }
+
+    return path;
+  }
+
+  /**
+   * Calculate total path cost
+   */
+  private calculatePathCost(path: number[], distanceMatrix: number[][]): number {
+    let cost = 0;
+    for (let i = 0; i < path.length - 1; i++) {
+      cost += distanceMatrix[path[i]][path[i + 1]];
+    }
+    return cost;
+  }
+
+  /**
+   * Evaporate pheromones
+   */
+  private evaporatePheromones(pheromones: number[][]): void {
+    const { evaporationRate } = this.config;
+    const minPheromone = 0.001;
+
+    for (let i = 0; i < pheromones.length; i++) {
+      for (let j = 0; j < pheromones[i].length; j++) {
+        pheromones[i][j] *= 1 - evaporationRate;
+        pheromones[i][j] = Math.max(minPheromone, pheromones[i][j]);
+      }
+    }
+  }
+
+  /**
+   * Deposit pheromones based on solution quality
+   */
+  private depositPheromones(pheromones: number[][], paths: number[][], costs: number[]): void {
+    const { q } = this.config;
+
+    for (let ant = 0; ant < paths.length; ant++) {
+      const path = paths[ant];
+      const deposit = q / costs[ant];
+
+      for (let i = 0; i < path.length - 1; i++) {
+        pheromones[path[i]][path[i + 1]] += deposit;
+        pheromones[path[i + 1]][path[i]] += deposit; // Symmetric
+      }
+    }
+  }
+
+  /**
+   * Elitist reinforcement of best path
+   */
+  private reinforceBestPath(pheromones: number[][], bestPath: number[], bestCost: number): void {
+    const { q, elitistWeight } = this.config;
+    const deposit = (q / bestCost) * elitistWeight;
+
+    for (let i = 0; i < bestPath.length - 1; i++) {
+      pheromones[bestPath[i]][bestPath[i + 1]] += deposit;
+      pheromones[bestPath[i + 1]][bestPath[i]] += deposit;
+    }
+  }
+
+  /**
+   * Get recommended ant count for problem
+   */
+  getRecommendedAntCount(nodes: number): number {
+    // Heuristic: roughly equal to node count, min 10, max 50
+    return Math.min(50, Math.max(10, nodes));
+  }
+}

package/src/swarm/CollectiveIntelligence.ts

@@ -0,0 +1,383 @@
+/**
+ * Collective Intelligence Service
+ *
+ * Implements ICollectiveIntelligenceService for collaborative
+ * problem-solving through hive sessions.
+ */
+
+import type {
+  ICollectiveIntelligenceService,
+  IHiveContribution,
+  IHiveSession,
+} from '@holoscript/core';
+import { VotingRound, type VotingResult } from './VotingRound';
+import { ContributionSynthesizer, type SynthesisResult } from './ContributionSynthesizer';
+
+export interface CollectiveIntelligenceConfig {
+  maxParticipants: number;
+  votingThreshold: number;
+  synthesisMinContributions: number;
+  autoCloseOnResolution: boolean;
+  contributionTimeoutMs: number;
+}
+
+const DEFAULT_CONFIG: CollectiveIntelligenceConfig = {
+  maxParticipants: 100,
+  votingThreshold: 0.5,
+  synthesisMinContributions: 3,
+  autoCloseOnResolution: true,
+  contributionTimeoutMs: 300000, // 5 minutes
+};
+
+/**
+ * Collective Intelligence Service
+ *
+ * Enables groups of agents to collaborate on complex problems through
+ * structured sessions with contributions, voting, and synthesis.
+ */
+export class CollectiveIntelligence implements ICollectiveIntelligenceService {
+  private config: CollectiveIntelligenceConfig;
+  private sessions: Map<string, IHiveSession> = new Map();
+  private votingRounds: Map<string, VotingRound> = new Map();
+  private synthesizer: ContributionSynthesizer;
+  private contributionIdCounter = 0;
+
+  constructor(config: Partial<CollectiveIntelligenceConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.synthesizer = new ContributionSynthesizer();
+  }
+
+  /**
+   * Create a new hive session
+   */
+  createSession(topic: string, goal: string, initiator: string): IHiveSession {
+    const id = this.generateSessionId();
+
+    const session: IHiveSession = {
+      id,
+      topic,
+      goal,
+      initiator,
+      status: 'active',
+      participants: [initiator],
+      contributions: [],
+    };
+
+    this.sessions.set(id, session);
+    this.votingRounds.set(
+      id,
+      new VotingRound({
+        superMajorityThreshold: this.config.votingThreshold,
+      })
+    );
+
+    return session;
+  }
+
+  /**
+   * Join an existing session
+   */
+  join(sessionId: string, agentId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    if (session.status !== 'active') {
+      throw new Error(`Session ${sessionId} is ${session.status}`);
+    }
+
+    if (session.participants.length >= this.config.maxParticipants) {
+      throw new Error(`Session ${sessionId} is full`);
+    }
+
+    if (!session.participants.includes(agentId)) {
+      session.participants.push(agentId);
+    }
+  }
+
+  /**
+   * Leave a session
+   */
+  leave(sessionId: string, agentId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    const index = session.participants.indexOf(agentId);
+    if (index !== -1) {
+      session.participants.splice(index, 1);
+    }
+  }
+
+  /**
+   * Contribute to a session
+   */
+  contribute(
+    sessionId: string,
+    contribution: Omit<IHiveContribution, 'id' | 'timestamp'>
+  ): IHiveContribution {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    if (session.status !== 'active') {
+      throw new Error(`Session ${sessionId} is ${session.status}`);
+    }
+
+    // Verify contributor is a participant
+    if (!session.participants.includes(contribution.agentId)) {
+      throw new Error(`Agent ${contribution.agentId} is not a participant`);
+    }
+
+    // Create full contribution
+    const fullContribution: IHiveContribution = {
+      ...contribution,
+      id: this.generateContributionId(),
+      timestamp: Date.now(),
+    };
+
+    session.contributions.push(fullContribution);
+
+    // Register for voting
+    const votingRound = this.votingRounds.get(sessionId);
+    votingRound?.registerContribution(fullContribution);
+
+    return fullContribution;
+  }
+
+  /**
+   * Vote on a contribution
+   */
+  vote(
+    sessionId: string,
+    contributionId: string,
+    voterId: string,
+    vote: 'support' | 'oppose'
+  ): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    if (session.status !== 'active') {
+      throw new Error(`Session ${sessionId} is ${session.status}`);
+    }
+
+    if (!session.participants.includes(voterId)) {
+      throw new Error(`Agent ${voterId} is not a participant`);
+    }
+
+    const votingRound = this.votingRounds.get(sessionId);
+    if (!votingRound) {
+      throw new Error(`No voting round for session ${sessionId}`);
+    }
+
+    // Get voter's contribution confidence for weighting
+    const voterContribution = session.contributions.find((c: any) => c.agentId === voterId);
+    const voterConfidence = voterContribution?.confidence ?? 0.5;
+
+    votingRound.castVote(contributionId, voterId, vote, voterConfidence);
+  }
+
+  /**
+   * Synthesize all contributions
+   */
+  synthesize(sessionId: string): SynthesisResult {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    if (session.contributions.length < this.config.synthesisMinContributions) {
+      return {
+        synthesizedContent: '',
+        sourceContributions: [],
+        synthesisMethod: 'merge',
+        confidence: 0,
+        metadata: {
+          totalContributions: session.contributions.length,
+          ideaCount: 0,
+          critiqueCount: 0,
+          consensusCount: 0,
+          solutionCount: 0,
+          averageConfidence: 0,
+          keyThemes: [],
+        },
+      };
+    }
+
+    return this.synthesizer.synthesize(session);
+  }
+
+  /**
+   * Resolve a session with a final decision
+   */
+  resolve(sessionId: string, resolution: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    session.resolution = resolution;
+    session.status = 'resolved';
+
+    const votingRound = this.votingRounds.get(sessionId);
+    votingRound?.close();
+  }
+
+  /**
+   * Get a session by ID
+   */
+  getSession(sessionId: string): IHiveSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * Get all active sessions
+   */
+  getActiveSessions(): IHiveSession[] {
+    return [...this.sessions.values()].filter((s) => s.status === 'active');
+  }
+
+  /**
+   * Close a session without resolution
+   */
+  closeSession(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    session.status = 'closed';
+
+    const votingRound = this.votingRounds.get(sessionId);
+    votingRound?.close();
+  }
+
+  /**
+   * Get voting results for a session
+   */
+  getVotingResults(sessionId: string): VotingResult[] {
+    const votingRound = this.votingRounds.get(sessionId);
+    if (!votingRound) {
+      return [];
+    }
+    return votingRound.getAllResults();
+  }
+
+  /**
+   * Get the top-voted contribution
+   */
+  getTopContribution(sessionId: string): IHiveContribution | undefined {
+    const votingRound = this.votingRounds.get(sessionId);
+    return votingRound?.getWinner();
+  }
+
+  /**
+   * Get session statistics
+   */
+  getSessionStats(sessionId: string):
+    | {
+        participantCount: number;
+        contributionCount: number;
+        votingStats: ReturnType<VotingRound['getStatistics']>;
+        contributionsByType: Record<IHiveContribution['type'], number>;
+        averageConfidence: number;
+      }
+    | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return undefined;
+    }
+
+    const votingRound = this.votingRounds.get(sessionId);
+
+    const byType: Record<IHiveContribution['type'], number> = {
+      idea: 0,
+      critique: 0,
+      consensus: 0,
+      solution: 0,
+    };
+
+    let totalConfidence = 0;
+    for (const c of session.contributions) {
+      byType[c.type]++;
+      totalConfidence += c.confidence;
+    }
+
+    return {
+      participantCount: session.participants.length,
+      contributionCount: session.contributions.length,
+      votingStats: votingRound?.getStatistics() ?? {
+        totalContributions: 0,
+        totalVotes: 0,
+        participationRate: 0,
+        hasConsensus: false,
+      },
+      contributionsByType: byType,
+      averageConfidence:
+        session.contributions.length > 0 ? totalConfidence / session.contributions.length : 0,
+    };
+  }
+
+  /**
+   * Auto-resolve if consensus reached
+   */
+  checkForConsensus(sessionId: string): boolean {
+    const votingRound = this.votingRounds.get(sessionId);
+    if (!votingRound) {
+      return false;
+    }
+
+    const stats = votingRound.getStatistics();
+    if (stats.hasConsensus && this.config.autoCloseOnResolution) {
+      const winner = votingRound.getWinner();
+      if (winner) {
+        this.resolve(sessionId, `Consensus reached: ${winner.content}`);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get contributions by a specific agent
+   */
+  getAgentContributions(sessionId: string, agentId: string): IHiveContribution[] {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return [];
+    }
+    return session.contributions.filter((c: any) => c.agentId === agentId);
+  }
+
+  /**
+   * Find similar contributions in a session
+   */
+  findSimilarContributions(sessionId: string, contributionId: string): IHiveContribution[] {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return [];
+    }
+
+    const target = session.contributions.find((c: any) => c.id === contributionId);
+    if (!target) {
+      return [];
+    }
+
+    return this.synthesizer.findSimilar(target, session.contributions);
+  }
+
+  private generateSessionId(): string {
+    return `hive-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+  }
+
+  private generateContributionId(): string {
+    this.contributionIdCounter++;
+    return `contrib-${this.contributionIdCounter}-${Date.now()}`;
+  }
+}