cognitive-core 0.0.2 → 0.1.2

package/src/learning/team-meta-learner.ts

@@ -0,0 +1,558 @@
+/**
+ * Team Meta-Learner
+ *
+ * Learns about team formation and coordination decisions.
+ * Analyzes TeamMetaObservations to generate TeamMetaStrategies.
+ * Adjusts team recommendations based on learned patterns.
+ *
+ * The team-level analog of MetaLearner.
+ */
+
+import type {
+  TeamMetaObservation,
+  TeamMetaStrategy,
+  TeamTrajectory,
+  TeamCompositionGuidance,
+} from '../types/index.js';
+import { createTeamMetaObservation, createTeamMetaStrategy } from '../types/index.js';
+import type { TeamExperienceMemory } from '../memory/team-experience.js';
+import type {
+  TeamRecommendation,
+  TeamRecommendationInput,
+} from '../search/team-router.js';
+
+// ============================================================
+// Configuration
+// ============================================================
+
+export interface TeamMetaLearnerConfig {
+  /** Minimum observations before generating strategies */
+  minObservationsForStrategies: number;
+  /** How often to run strategy generation (in observations) */
+  strategyGenerationInterval: number;
+  /** Minimum success rate for a topology to generate a prefer-strategy */
+  preferTopologyThreshold: number;
+  /** Maximum coordination overhead before flagging */
+  highOverheadThreshold: number;
+}
+
+const DEFAULT_CONFIG: TeamMetaLearnerConfig = {
+  minObservationsForStrategies: 5,
+  strategyGenerationInterval: 5,
+  preferTopologyThreshold: 0.75,
+  highOverheadThreshold: 0.4,
+};
+
+// ============================================================
+// Team Meta-Learner
+// ============================================================
+
+export class TeamMetaLearner {
+  private memory: TeamExperienceMemory;
+  private config: TeamMetaLearnerConfig;
+  private observationCount = 0;
+
+  constructor(memory: TeamExperienceMemory, config?: Partial<TeamMetaLearnerConfig>) {
+    this.memory = memory;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Generate a meta-observation from a completed team trajectory and
+   * the recommendation that was used to form the team (if any).
+   */
+  async generateReflection(
+    trajectory: TeamTrajectory,
+    recommendation?: TeamRecommendation
+  ): Promise<TeamMetaObservation> {
+    // Assess composition effectiveness from graph data
+    const roleUtilization: Record<string, number> = {};
+    const redundantRoles: string[] = [];
+    const missingRoles: string[] = [];
+
+    for (const member of trajectory.members) {
+      const traj = member.trajectory;
+      roleUtilization[member.role] = traj.outcome?.success ? 1.0 :
+        (traj.outcome?.partialScore ?? 0);
+
+      // Redundant if no steps and minimal tokens
+      if (traj.steps.length === 0 && (traj.totalTokens ?? 0) < 1000) {
+        redundantRoles.push(member.role);
+      }
+    }
+
+    // Team size assessment
+    let teamSizeAssessment: 'too-small' | 'right-sized' | 'too-large';
+    if (redundantRoles.length > 0) {
+      teamSizeAssessment = 'too-large';
+    } else if (
+      !trajectory.outcome.success &&
+      trajectory.metrics.reDelegationCount > 0
+    ) {
+      teamSizeAssessment = 'too-small';
+    } else {
+      teamSizeAssessment = 'right-sized';
+    }
+
+    // Topology assessment from graph data
+    const parallelismRatio = trajectory.graphMetrics.parallelismRatio;
+    const topologyAssessment =
+      trajectory.outcome.success && parallelismRatio > 0.3
+        ? 'effective' as const
+        : trajectory.outcome.success
+          ? 'neutral' as const
+          : 'hindering' as const;
+
+    // Coordination effectiveness
+    const coordOverhead = trajectory.metrics.coordinationOverheadRatio;
+    const enforcementAssessment =
+      coordOverhead > this.config.highOverheadThreshold
+        ? 'too-strict' as const
+        : 'appropriate' as const;
+
+    // Bottleneck detection from graph metrics
+    const bottlenecks: string[] = [];
+    if (trajectory.graphMetrics.maxInDegree.count > 0) {
+      bottlenecks.push(trajectory.graphMetrics.maxInDegree.agentId);
+    }
+
+    // Outcome observation
+    const speedupEstimate =
+      trajectory.teamSize > 1
+        ? trajectory.teamSize * parallelismRatio
+        : 1;
+
+    const costEfficiency =
+      trajectory.outcome.totalTokens > 0
+        ? trajectory.outcome.partialScore / (trajectory.outcome.totalTokens / 10000)
+        : 0;
+
+    // Lessons
+    const whatWorked: string[] = [];
+    const whatFailed: string[] = [];
+    const formationSuggestions: string[] = [];
+    const coordinationSuggestions: string[] = [];
+
+    if (trajectory.outcome.success) {
+      whatWorked.push(
+        `${trajectory.topologyType} topology with ${trajectory.teamSize} agents succeeded`
+      );
+      if (parallelismRatio > 0.5) {
+        whatWorked.push('Good parallelism achieved');
+      }
+    } else {
+      whatFailed.push(
+        `${trajectory.topologyType} topology with ${trajectory.teamSize} agents failed`
+      );
+      if (trajectory.metrics.reDelegationCount > 0) {
+        whatFailed.push(
+          `${trajectory.metrics.reDelegationCount} task re-delegations occurred`
+        );
+        formationSuggestions.push('Consider adding specialist roles to reduce re-delegation');
+      }
+    }
+
+    if (redundantRoles.length > 0) {
+      whatFailed.push(`Redundant roles: ${redundantRoles.join(', ')}`);
+      formationSuggestions.push(
+        `Consider removing roles: ${redundantRoles.join(', ')}`
+      );
+    }
+
+    if (coordOverhead > this.config.highOverheadThreshold) {
+      coordinationSuggestions.push(
+        `High coordination overhead (${(coordOverhead * 100).toFixed(0)}%); consider looser enforcement or fewer channels`
+      );
+    }
+
+    const observation = createTeamMetaObservation({
+      teamTrajectoryId: trajectory.id,
+      formation: {
+        playbookUsed: recommendation?.playbook?.id,
+        formationMethod: recommendation?.playbook ? 'playbook' : 'manual',
+        confidence: recommendation?.confidence ?? 0.3,
+        reasoning:
+          recommendation?.reasoning ?? 'Team formed without recommendation',
+        wasEffective: trajectory.outcome.success,
+        topologyUsed: trajectory.topologyType,
+        domain: trajectory.domain,
+      },
+      compositionEffectiveness: {
+        roleUtilization,
+        missingRoles,
+        redundantRoles,
+        teamSizeAssessment,
+        topologyAssessment,
+      },
+      coordinationEffectiveness: {
+        enforcementAssessment,
+        channelEffectiveness: 'neutral',
+        bottlenecks,
+        coordinationOverhead: coordOverhead,
+      },
+      outcome: {
+        success: trajectory.outcome.success,
+        quality: trajectory.outcome.quality,
+        speedupEstimate,
+        costEfficiency,
+      },
+      lessons: {
+        whatWorked,
+        whatFailed,
+        formationSuggestions,
+        coordinationSuggestions,
+      },
+    });
+
+    // Store the observation
+    await this.memory.recordMetaObservation(observation);
+    this.observationCount++;
+
+    // Periodically generate new meta-strategies
+    if (
+      this.observationCount > 0 &&
+      this.observationCount % this.config.strategyGenerationInterval === 0
+    ) {
+      await this.learn();
+    }
+
+    return observation;
+  }
+
+  /**
+   * Analyze accumulated observations and generate team meta-strategies.
+   */
+  async learn(): Promise<TeamMetaStrategy[]> {
+    const observations = await this.memory.getMetaObservations();
+
+    if (observations.length < this.config.minObservationsForStrategies) {
+      return [];
+    }
+
+    const newStrategies: TeamMetaStrategy[] = [];
+
+    // Analyze topology effectiveness across observations
+    const topologyStats = this.analyzeTopologyEffectiveness(observations);
+    for (const [topology, stats] of Object.entries(topologyStats)) {
+      if (stats.total < 3) continue;
+
+      const successRate = stats.successful / stats.total;
+
+      if (successRate >= this.config.preferTopologyThreshold) {
+        const strategy = createTeamMetaStrategy({
+          name: `prefer-${topology}-high-success`,
+          condition: {
+            taskCharacteristics: [],
+            resourceConstraints: [],
+            domains: stats.domains,
+          },
+          adjustment: {
+            topologyBias: { [topology]: 0.3 },
+            teamSizeAdjustment: 'maintain',
+            roleAdjustments: [],
+            coordinationHints: [
+              `${topology} topology has ${(successRate * 100).toFixed(0)}% success rate`,
+            ],
+          },
+        });
+        newStrategies.push(strategy);
+      } else if (successRate < 0.4 && stats.total >= 3) {
+        const strategy = createTeamMetaStrategy({
+          name: `avoid-${topology}-low-success`,
+          condition: {
+            taskCharacteristics: [],
+            resourceConstraints: [],
+            domains: stats.domains,
+          },
+          adjustment: {
+            topologyBias: { [topology]: -0.3 },
+            teamSizeAdjustment: 'maintain',
+            roleAdjustments: [],
+            coordinationHints: [
+              `${topology} topology has only ${(successRate * 100).toFixed(0)}% success rate`,
+            ],
+          },
+        });
+        newStrategies.push(strategy);
+      }
+    }
+
+    // Analyze team size patterns
+    const sizeAnalysis = this.analyzeTeamSizePatterns(observations);
+    if (sizeAnalysis) {
+      newStrategies.push(sizeAnalysis);
+    }
+
+    // Analyze coordination overhead patterns
+    const overheadAnalysis = this.analyzeOverheadPatterns(observations);
+    if (overheadAnalysis) {
+      newStrategies.push(overheadAnalysis);
+    }
+
+    // Store new strategies (deduplicating by name)
+    const existingStrategies = await this.memory.getMetaStrategies();
+    const existingNames = new Set(existingStrategies.map((s) => s.name));
+
+    for (const strategy of newStrategies) {
+      if (!existingNames.has(strategy.name)) {
+        await this.memory.storeMetaStrategy(strategy);
+        existingNames.add(strategy.name);
+      }
+    }
+
+    return newStrategies;
+  }
+
+  /**
+   * Adjust a team recommendation based on learned meta-strategies.
+   */
+  async adjustRecommendation(
+    recommendation: TeamRecommendation,
+    input: TeamRecommendationInput
+  ): Promise<TeamRecommendation> {
+    const strategies = await this.memory.getMatchingMetaStrategies({
+      domains: [input.domain],
+      taskCharacteristics: this.extractTaskCharacteristics(input),
+    });
+
+    if (strategies.length === 0) {
+      return recommendation;
+    }
+
+    let adjustedConfidence = recommendation.confidence;
+    const adjustmentReasons: string[] = [];
+    const strategyNames: string[] = [];
+
+    for (const strategy of strategies) {
+      strategyNames.push(strategy.name);
+
+      // Apply topology bias
+      if (strategy.adjustment.topologyBias) {
+        const currentTopology = recommendation.composition.topology;
+        const currentBias = strategy.adjustment.topologyBias[currentTopology] ?? 0;
+        adjustedConfidence += currentBias * 0.2;
+
+        // Check if another topology is strongly preferred
+        for (const [topology, bias] of Object.entries(
+          strategy.adjustment.topologyBias
+        )) {
+          if (
+            bias > 0.2 &&
+            topology !== currentTopology &&
+            recommendation.confidence < 0.5
+          ) {
+            recommendation = {
+              ...recommendation,
+              composition: {
+                ...recommendation.composition,
+                topology: topology as TeamCompositionGuidance['topology'],
+              },
+            };
+            adjustmentReasons.push(
+              `Meta-strategy "${strategy.name}" suggests ${topology} topology`
+            );
+          }
+        }
+      }
+
+      // Apply team size adjustment
+      if (strategy.adjustment.teamSizeAdjustment !== 'maintain') {
+        adjustmentReasons.push(
+          `Meta-strategy "${strategy.name}" suggests ${strategy.adjustment.teamSizeAdjustment} team size`
+        );
+      }
+
+      // Apply coordination hints
+      for (const hint of strategy.adjustment.coordinationHints) {
+        adjustmentReasons.push(hint);
+      }
+
+      // Apply enforcement bias
+      if (
+        strategy.adjustment.enforcementBias &&
+        recommendation.composition.enforcement !== strategy.adjustment.enforcementBias
+      ) {
+        recommendation = {
+          ...recommendation,
+          composition: {
+            ...recommendation.composition,
+            enforcement: strategy.adjustment.enforcementBias,
+          },
+        };
+        adjustmentReasons.push(
+          `Enforcement set to ${strategy.adjustment.enforcementBias}`
+        );
+      }
+    }
+
+    // Clamp confidence
+    adjustedConfidence = Math.max(0.1, Math.min(0.95, adjustedConfidence));
+
+    return {
+      ...recommendation,
+      confidence: adjustedConfidence,
+      reasoning:
+        adjustmentReasons.length > 0
+          ? `${recommendation.reasoning}. Meta-adjustments: ${adjustmentReasons.join('; ')}`
+          : recommendation.reasoning,
+      appliedMetaStrategies: [
+        ...recommendation.appliedMetaStrategies,
+        ...strategyNames,
+      ],
+    };
+  }
+
+  // === Private helpers ===
+
+  private extractTaskCharacteristics(input: TeamRecommendationInput): string[] {
+    const characteristics: string[] = [];
+    characteristics.push(`domain: ${input.domain}`);
+    characteristics.push(`complexity: ${input.complexity}`);
+
+    const desc = input.description.toLowerCase();
+    if (desc.includes('refactor')) characteristics.push('refactoring');
+    if (desc.includes('implement') || desc.includes('create'))
+      characteristics.push('new feature');
+    if (desc.includes('test')) characteristics.push('testing');
+    if (desc.includes('bug') || desc.includes('fix'))
+      characteristics.push('bug fix');
+    if (desc.includes('multiple') || desc.includes('across'))
+      characteristics.push('cross-cutting');
+
+    return characteristics;
+  }
+
+  private analyzeTopologyEffectiveness(
+    observations: TeamMetaObservation[]
+  ): Record<string, { total: number; successful: number; domains: string[] }> {
+    const stats: Record<
+      string,
+      { total: number; successful: number; domains: Set<string> }
+    > = {};
+
+    for (const obs of observations) {
+      // Use structured topology field (preferred) with regex fallback for older observations
+      const actualTopology = obs.formation.topologyUsed
+        ?? obs.formation.reasoning.match(/topology[:\s]+(\w+)/i)?.[1]
+        ?? 'unknown';
+
+      if (!stats[actualTopology]) {
+        stats[actualTopology] = { total: 0, successful: 0, domains: new Set() };
+      }
+
+      stats[actualTopology].total++;
+      if (obs.outcome.success) {
+        stats[actualTopology].successful++;
+      }
+
+      // Use structured domain field (preferred) with regex fallback
+      const domain = obs.formation.domain
+        ?? obs.formation.reasoning.match(/domain[:\s]+(\w+)/i)?.[1];
+      if (domain) {
+        stats[actualTopology].domains.add(domain);
+      }
+    }
+
+    // Convert Set to Array for return
+    const result: Record<
+      string,
+      { total: number; successful: number; domains: string[] }
+    > = {};
+    for (const [k, v] of Object.entries(stats)) {
+      result[k] = { total: v.total, successful: v.successful, domains: [...v.domains] };
+    }
+    return result;
+  }
+
+  private analyzeTeamSizePatterns(
+    observations: TeamMetaObservation[]
+  ): TeamMetaStrategy | null {
+    // Check if "too-large" assessments dominate
+    const tooLargeCount = observations.filter(
+      (o) => o.compositionEffectiveness.teamSizeAssessment === 'too-large'
+    ).length;
+
+    if (tooLargeCount >= 3 && tooLargeCount / observations.length > 0.4) {
+      return createTeamMetaStrategy({
+        name: 'reduce-team-size-frequent-redundancy',
+        condition: {
+          taskCharacteristics: [],
+          resourceConstraints: [],
+          domains: [],
+        },
+        adjustment: {
+          teamSizeAdjustment: 'decrease',
+          roleAdjustments: ['Remove optional roles by default'],
+          coordinationHints: [
+            'Teams frequently have redundant roles; prefer smaller teams',
+          ],
+        },
+      });
+    }
+
+    const tooSmallCount = observations.filter(
+      (o) => o.compositionEffectiveness.teamSizeAssessment === 'too-small'
+    ).length;
+
+    if (tooSmallCount >= 3 && tooSmallCount / observations.length > 0.4) {
+      return createTeamMetaStrategy({
+        name: 'increase-team-size-frequent-overload',
+        condition: {
+          taskCharacteristics: [],
+          resourceConstraints: [],
+          domains: [],
+        },
+        adjustment: {
+          teamSizeAdjustment: 'increase',
+          roleAdjustments: ['Add specialist roles for complex subtasks'],
+          coordinationHints: [
+            'Teams frequently too small; consider adding roles',
+          ],
+        },
+      });
+    }
+
+    return null;
+  }
+
+  private analyzeOverheadPatterns(
+    observations: TeamMetaObservation[]
+  ): TeamMetaStrategy | null {
+    const highOverhead = observations.filter(
+      (o) =>
+        o.coordinationEffectiveness.coordinationOverhead >
+        this.config.highOverheadThreshold
+    );
+
+    if (highOverhead.length >= 3 && highOverhead.length / observations.length > 0.5) {
+      return createTeamMetaStrategy({
+        name: 'reduce-coordination-overhead',
+        condition: {
+          taskCharacteristics: [],
+          resourceConstraints: [],
+          domains: [],
+        },
+        adjustment: {
+          teamSizeAdjustment: 'maintain',
+          enforcementBias: 'permissive',
+          roleAdjustments: [],
+          coordinationHints: [
+            'High coordination overhead detected; use permissive enforcement and fewer channels',
+          ],
+        },
+      });
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Create a TeamMetaLearner instance.
+ */
+export function createTeamMetaLearner(
+  memory: TeamExperienceMemory,
+  config?: Partial<TeamMetaLearnerConfig>
+): TeamMetaLearner {
+  return new TeamMetaLearner(memory, config);
+}