cognitive-core 0.2.5 → 0.3.1

package/src/search/team-router.ts

@@ -1,459 +0,0 @@
-/**
- * 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);
-}