cognitive-core 0.0.2 → 0.1.2

package/src/search/team-router.ts

@@ -0,0 +1,459 @@
+/**
+ * Team Router
+ *
+ * Recommends team composition for a given task description.
+ * Queries team playbooks and experiences from memory, scores matches,
+ * and applies team meta-strategies to adjust recommendations.
+ *
+ * The team-level analog of TaskRouter.
+ */
+
+import type {
+  TeamPlaybook,
+  RolePlaybook,
+  TeamCompositionGuidance,
+  TeamCoordinationGuidance,
+  TeamRoleSpec,
+} from '../types/index.js';
+import type { TeamExperienceMemory } from '../memory/team-experience.js';
+import type { TeamMetaLearner } from '../learning/team-meta-learner.js';
+
+// ============================================================
+// Configuration
+// ============================================================
+
+export interface TeamRouterConfig {
+  /** Minimum playbook confidence to use directly */
+  minPlaybookConfidence: number;
+  /** How many playbook candidates to retrieve */
+  maxCandidates: number;
+  /** How many role playbooks to include per role */
+  maxRolePlaybooksPerRole: number;
+  /** Whether to include similar experiences in reasoning */
+  includeSimilarExperiences: boolean;
+}
+
+const DEFAULT_CONFIG: TeamRouterConfig = {
+  minPlaybookConfidence: 0.4,
+  maxCandidates: 5,
+  maxRolePlaybooksPerRole: 2,
+  includeSimilarExperiences: true,
+};
+
+// ============================================================
+// Output Types
+// ============================================================
+
+/**
+ * Result from team recommendation.
+ */
+export interface TeamRecommendation {
+  /** Matched team playbook (if any) */
+  playbook?: TeamPlaybook;
+  /** Recommended composition */
+  composition: TeamCompositionGuidance;
+  /** Recommended coordination */
+  coordination: TeamCoordinationGuidance;
+  /** Role playbooks for each recommended role */
+  rolePlaybooks: RolePlaybook[];
+  /** Confidence in this recommendation (0-1) */
+  confidence: number;
+  /** Reasoning for this recommendation */
+  reasoning: string;
+  /** Meta-strategies that were applied */
+  appliedMetaStrategies: string[];
+  /** Export as OpenTeams team.yaml format */
+  asTeamYaml(): string;
+}
+
+/**
+ * Task input for team recommendation.
+ */
+export interface TeamRecommendationInput {
+  description: string;
+  domain: string;
+  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+  constraints?: {
+    maxAgents?: number;
+    maxTokenBudget?: number;
+    preferredTopology?: string;
+  };
+}
+
+// ============================================================
+// Default fallback composition
+// ============================================================
+
+function defaultComposition(
+  input: TeamRecommendationInput
+): TeamCompositionGuidance {
+  // Simple tasks → flat 2-agent team, complex → wave with planner
+  if (input.complexity === 'simple') {
+    return {
+      topology: 'flat',
+      roles: [
+        {
+          role: 'executor',
+          rationale: 'Execute the task directly',
+          capabilities: ['task execution'],
+          optional: false,
+          modelTier: 'balanced',
+          spawnAs: 'root',
+        },
+      ],
+      spawnRules: {},
+      enforcement: 'permissive',
+    };
+  }
+
+  const roles: TeamRoleSpec[] = [
+    {
+      role: 'planner',
+      rationale: 'Decompose and plan the work',
+      capabilities: ['planning', 'decomposition'],
+      optional: false,
+      modelTier: 'capable',
+      spawnAs: 'root',
+    },
+    {
+      role: 'executor',
+      rationale: 'Execute planned tasks',
+      capabilities: ['task execution'],
+      optional: false,
+      modelTier: 'balanced',
+      spawnAs: 'companion',
+    },
+  ];
+
+  if (input.complexity === 'complex' || input.complexity === 'epic') {
+    roles.push({
+      role: 'reviewer',
+      rationale: 'Verify completed work',
+      capabilities: ['review', 'verification'],
+      optional: true,
+      modelTier: 'capable',
+      spawnAs: 'on-demand',
+    });
+  }
+
+  return {
+    topology: input.complexity === 'epic' ? 'hierarchical' : 'wave',
+    roles,
+    spawnRules: { planner: ['executor', 'reviewer'] },
+    enforcement: 'permissive',
+  };
+}
+
+function defaultCoordination(
+  input: TeamRecommendationInput
+): TeamCoordinationGuidance {
+  return {
+    executionModel:
+      input.complexity === 'simple'
+        ? 'sequential'
+        : 'wave-parallel',
+    channels: [],
+    interactionPatterns: [],
+    delegationStrategy: 'auto',
+  };
+}
+
+// ============================================================
+// YAML export
+// ============================================================
+
+function compositionToYaml(
+  rec: Omit<TeamRecommendation, 'asTeamYaml'>
+): string {
+  const lines: string[] = [
+    '# Team configuration generated by cognitive-core',
+    `# Confidence: ${rec.confidence.toFixed(2)}`,
+    '',
+    'team:',
+    `  topology: ${rec.composition.topology}`,
+    `  enforcement: ${rec.composition.enforcement}`,
+    '',
+    '  roles:',
+  ];
+
+  for (const role of rec.composition.roles) {
+    lines.push(`    - name: ${role.role}`);
+    lines.push(`      rationale: "${role.rationale}"`);
+    lines.push(`      optional: ${role.optional}`);
+    if (role.modelTier) {
+      lines.push(`      model_tier: ${role.modelTier}`);
+    }
+    lines.push(`      spawn_as: ${role.spawnAs}`);
+    if (role.capabilities.length > 0) {
+      lines.push(`      capabilities:`);
+      for (const cap of role.capabilities) {
+        lines.push(`        - ${cap}`);
+      }
+    }
+  }
+
+  if (Object.keys(rec.composition.spawnRules).length > 0) {
+    lines.push('');
+    lines.push('  spawn_rules:');
+    for (const [parent, children] of Object.entries(rec.composition.spawnRules)) {
+      lines.push(`    ${parent}: [${children.join(', ')}]`);
+    }
+  }
+
+  lines.push('');
+  lines.push('  coordination:');
+  lines.push(`    execution_model: ${rec.coordination.executionModel}`);
+  lines.push(`    delegation_strategy: ${rec.coordination.delegationStrategy}`);
+
+  if (rec.coordination.channels.length > 0) {
+    lines.push('    channels:');
+    for (const ch of rec.coordination.channels) {
+      lines.push(`      - name: ${ch.name}`);
+      lines.push(`        signals: [${ch.signals.join(', ')}]`);
+      lines.push(`        subscribers: [${ch.subscribers.join(', ')}]`);
+      lines.push(`        emitters: [${ch.emitters.join(', ')}]`);
+    }
+  }
+
+  if (rec.coordination.interactionPatterns.length > 0) {
+    lines.push('    interaction_patterns:');
+    for (const pat of rec.coordination.interactionPatterns) {
+      lines.push(`      - name: ${pat.name}`);
+      lines.push(`        roles: [${pat.roles.join(', ')}]`);
+      lines.push(`        frequency: ${pat.frequency}`);
+    }
+  }
+
+  if (rec.coordination.checkpoints && rec.coordination.checkpoints.length > 0) {
+    lines.push('    checkpoints:');
+    for (const cp of rec.coordination.checkpoints) {
+      lines.push(`      - ${cp}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ============================================================
+// Team Router
+// ============================================================
+
+export class TeamRouter {
+  private memory: TeamExperienceMemory;
+  private config: TeamRouterConfig;
+  private metaLearner?: TeamMetaLearner;
+
+  constructor(
+    memory: TeamExperienceMemory,
+    config?: Partial<TeamRouterConfig>,
+    metaLearner?: TeamMetaLearner
+  ) {
+    this.memory = memory;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Set the team meta learner (can be set after construction).
+   */
+  setMetaLearner(metaLearner: TeamMetaLearner): void {
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Recommend a team composition for a given task.
+   */
+  async recommend(input: TeamRecommendationInput): Promise<TeamRecommendation> {
+    // 1. Find matching team playbooks
+    const playbookMatches = await this.memory.findMatchingTeamPlaybooks({
+      taskType: input.description,
+      domain: input.domain,
+      complexity: input.complexity,
+      topology: input.constraints?.preferredTopology,
+      k: this.config.maxCandidates,
+    });
+
+    // 2. Compute base recommendation
+    let recommendation = this.computeBaseRecommendation(input, playbookMatches);
+
+    // 3. Apply constraints
+    recommendation = this.applyConstraints(recommendation, input);
+
+    // 4. Attach role playbooks for each recommended role
+    const rolePlaybooks = await this.findRolePlaybooks(recommendation, input);
+    recommendation.rolePlaybooks = rolePlaybooks;
+
+    // 5. Apply meta-learning adjustments
+    if (this.metaLearner) {
+      try {
+        recommendation = await this.metaLearner.adjustRecommendation(
+          recommendation,
+          input
+        );
+      } catch (error) {
+        console.error(
+          '[TeamRouter] Meta-learning adjustment failed, using base recommendation:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    return recommendation;
+  }
+
+  /**
+   * Compute base recommendation from playbook matches.
+   */
+  private computeBaseRecommendation(
+    input: TeamRecommendationInput,
+    playbookMatches: Array<{ playbook: TeamPlaybook; score: number }>
+  ): TeamRecommendation {
+    // Filter to playbooks above minimum confidence
+    const viable = playbookMatches.filter(
+      (m) => m.playbook.confidence >= this.config.minPlaybookConfidence
+    );
+
+    if (viable.length > 0) {
+      // Use the best matching playbook
+      const best = viable[0];
+      const rec: Omit<TeamRecommendation, 'asTeamYaml'> = {
+        playbook: best.playbook,
+        composition: best.playbook.composition,
+        coordination: best.playbook.coordination,
+        rolePlaybooks: [],
+        confidence: Math.min(best.score * best.playbook.confidence, 0.95),
+        reasoning: `Matched team playbook "${best.playbook.name}" (score: ${best.score.toFixed(2)}, confidence: ${best.playbook.confidence.toFixed(2)})`,
+        appliedMetaStrategies: [],
+      };
+
+      return { ...rec, asTeamYaml: () => compositionToYaml(rec) };
+    }
+
+    // No viable playbook — build a default recommendation
+    const composition = defaultComposition(input);
+    const coordination = defaultCoordination(input);
+
+    const rec: Omit<TeamRecommendation, 'asTeamYaml'> = {
+      composition,
+      coordination,
+      rolePlaybooks: [],
+      confidence: 0.3,
+      reasoning: 'No matching team playbook found; using default composition based on complexity',
+      appliedMetaStrategies: [],
+    };
+
+    return { ...rec, asTeamYaml: () => compositionToYaml(rec) };
+  }
+
+  /**
+   * Apply user constraints to the recommendation.
+   */
+  private applyConstraints(
+    recommendation: TeamRecommendation,
+    input: TeamRecommendationInput
+  ): TeamRecommendation {
+    const constraints = input.constraints;
+    if (!constraints) return recommendation;
+
+    let modified = false;
+    const reasons: string[] = [];
+
+    // Apply max agents constraint
+    if (
+      constraints.maxAgents &&
+      recommendation.composition.roles.length > constraints.maxAgents
+    ) {
+      // Keep only essential (non-optional) roles, then trim to fit
+      const essential = recommendation.composition.roles.filter((r) => !r.optional);
+      const optional = recommendation.composition.roles.filter((r) => r.optional);
+
+      let roles: TeamRoleSpec[];
+      if (essential.length >= constraints.maxAgents) {
+        roles = essential.slice(0, constraints.maxAgents);
+      } else {
+        const remaining = constraints.maxAgents - essential.length;
+        roles = [...essential, ...optional.slice(0, remaining)];
+      }
+
+      recommendation = {
+        ...recommendation,
+        composition: { ...recommendation.composition, roles },
+      };
+      reasons.push(`Trimmed to ${constraints.maxAgents} agents`);
+      modified = true;
+    }
+
+    // Apply preferred topology
+    if (
+      constraints.preferredTopology &&
+      recommendation.composition.topology !== constraints.preferredTopology
+    ) {
+      recommendation = {
+        ...recommendation,
+        composition: {
+          ...recommendation.composition,
+          topology: constraints.preferredTopology as TeamCompositionGuidance['topology'],
+        },
+      };
+      reasons.push(`Topology set to ${constraints.preferredTopology}`);
+      modified = true;
+    }
+
+    if (modified) {
+      recommendation.reasoning += `. Constraints applied: ${reasons.join('; ')}`;
+      // Slightly lower confidence when constraints override
+      recommendation.confidence = Math.max(0.15, recommendation.confidence * 0.9);
+
+      // Rebuild asTeamYaml with updated data
+      const rec = recommendation;
+      recommendation.asTeamYaml = () => compositionToYaml(rec);
+    }
+
+    return recommendation;
+  }
+
+  /**
+   * Find role playbooks for each role in the recommendation.
+   */
+  private async findRolePlaybooks(
+    recommendation: TeamRecommendation,
+    input: TeamRecommendationInput
+  ): Promise<RolePlaybook[]> {
+    const rolePlaybooks: RolePlaybook[] = [];
+
+    for (const roleSpec of recommendation.composition.roles) {
+      const matches = await this.memory.findMatchingRolePlaybooks({
+        role: roleSpec.role,
+        topology: recommendation.composition.topology,
+        domain: input.domain,
+        taskType: input.description,
+        k: this.config.maxRolePlaybooksPerRole,
+      });
+
+      for (const match of matches) {
+        rolePlaybooks.push(match.playbook);
+      }
+    }
+
+    return rolePlaybooks;
+  }
+
+  /**
+   * Update configuration.
+   */
+  updateConfig(config: Partial<TeamRouterConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+/**
+ * Create a TeamRouter instance.
+ */
+export function createTeamRouter(
+  memory: TeamExperienceMemory,
+  config?: Partial<TeamRouterConfig>,
+  metaLearner?: TeamMetaLearner
+): TeamRouter {
+  return new TeamRouter(memory, config, metaLearner);
+}