cognitive-core 0.2.4 → 0.3.1

package/src/learning/team-ingester.ts

@@ -1,499 +0,0 @@
-/**
- * Team Trajectory Ingester
- *
- * Computational pre-processing of team trajectories before agentic analysis.
- * Builds interaction graphs, computes structural metrics, compresses
- * per-agent trajectories, and scores critical steps/interactions.
- *
- * No LLM calls — purely structural/heuristic processing.
- */
-
-import type {
-  TeamTrajectory,
-  TeamEvent,
-  TeamEventType,
-  InteractionEdge,
-  MemberTrajectory,
-  AgentInteraction,
-  GraphStructuralMetrics,
-} from '../types/index.js';
-import type { Step } from '../types/step.js';
-
-// ============================================================
-// Configuration
-// ============================================================
-
-export interface CompressionConfig {
-  /** Max tokens per agent trajectory after compression */
-  maxTokensPerAgent: number;
-  /** Always preserve steps at interaction boundaries */
-  preserveInteractionBoundaries: boolean;
-  /** Max consecutive non-interaction steps before folding */
-  foldThreshold: number;
-  /** Fraction of steps to mark as critical */
-  maxCriticalRatio: number;
-  /** Minimum score threshold for critical steps */
-  criticalStepThreshold: number;
-  /** Minimum score threshold for critical interactions */
-  criticalInteractionThreshold: number;
-}
-
-const DEFAULT_COMPRESSION_CONFIG: CompressionConfig = {
-  maxTokensPerAgent: 5000,
-  preserveInteractionBoundaries: true,
-  foldThreshold: 5,
-  maxCriticalRatio: 0.25,
-  criticalStepThreshold: 0.3,
-  criticalInteractionThreshold: 0.3,
-};
-
-// ============================================================
-// Output Types
-// ============================================================
-
-export interface CriticalStep {
-  agentId: string;
-  role: string;
-  eventIndex: number;
-  event: TeamEvent;
-  scores: {
-    position: number;
-    actionType: number;
-    interactionBonus: number;
-    total: number;
-  };
-  // Graph-enriched fields (present when trajectory has members[])
-  /** Index within the member's trajectory.steps */
-  stepIndex?: number;
-  /** Actual step content from the agent's trajectory */
-  stepContent?: { thought?: string; action: string; observation: string };
-  /** Content-based scoring bonus (e.g. error mentions, key decisions) */
-  contentScore?: number;
-}
-
-export interface CriticalInteraction {
-  edge: InteractionEdge;
-  scores: {
-    volume: number;
-    diversityBonus: number;
-    latencyPenalty: number;
-    total: number;
-  };
-  // Graph-enriched fields (present when trajectory has interactions[])
-  /** The step-level AgentInteraction this corresponds to */
-  interaction?: AgentInteraction;
-  /** Whether downstream steps after this interaction led to success */
-  downstreamSuccessScore?: number;
-}
-
-export interface StructuralMetrics {
-  teamSize: number;
-  totalEvents: number;
-  totalInteractions: number;
-  interactionDensity: number;
-  maxInDegree: { role: string; count: number };
-  maxOutDegree: { role: string; count: number };
-  parallelismRatio: number;
-  totalWallTimeSeconds: number;
-  totalTokens: number;
-}
-
-export interface IngestionResult {
-  /** The team trajectory (passed through) */
-  teamTrajectory: TeamTrajectory;
-  /** Structural metrics computed from events and interactions */
-  structuralMetrics: StructuralMetrics;
-  /** Critical steps identified by scoring */
-  criticalSteps: CriticalStep[];
-  /** Critical interactions identified by scoring */
-  criticalInteractions: CriticalInteraction[];
-  /** Compression statistics */
-  compressionStats: {
-    originalEventCount: number;
-    criticalEventCount: number;
-    criticalRatio: number;
-  };
-  /** Graph-level structural metrics */
-  graphMetrics: GraphStructuralMetrics;
-}
-
-// ============================================================
-// Ingester
-// ============================================================
-
-export class TeamTrajectoryIngester {
-  private config: CompressionConfig;
-
-  constructor(config?: Partial<CompressionConfig>) {
-    this.config = { ...DEFAULT_COMPRESSION_CONFIG, ...config };
-  }
-
-  /**
-   * Ingest a team trajectory: compute metrics, score steps/interactions,
-   * identify critical moments.
-   *
-   * Uses graph data (members[], interactions[]) for content-based scoring.
-   */
-  ingest(trajectory: TeamTrajectory): IngestionResult {
-    // 1. Compute structural metrics from graph data
-    const structuralMetrics = this.computeStructuralMetrics(trajectory);
-
-    // 2. Score and identify critical steps from member trajectories
-    const scoredSteps = this.scoreGraphSteps(trajectory.members, trajectory);
-    const criticalSteps = this.selectCritical(
-      scoredSteps,
-      this.config.criticalStepThreshold,
-      this.config.maxCriticalRatio
-    );
-
-    // 3. Score and identify critical interactions
-    const scoredInteractions = this.scoreGraphInteractions(
-      trajectory.interactions,
-      trajectory.members,
-      trajectory
-    );
-    const criticalInteractions = this.selectCriticalInteractions(
-      scoredInteractions,
-      this.config.criticalInteractionThreshold
-    );
-
-    const totalItems = trajectory.members.reduce((s, m) => s + m.trajectory.steps.length, 0);
-
-    return {
-      teamTrajectory: trajectory,
-      structuralMetrics,
-      criticalSteps,
-      criticalInteractions,
-      compressionStats: {
-        originalEventCount: totalItems,
-        criticalEventCount: criticalSteps.length,
-        criticalRatio: totalItems > 0 ? criticalSteps.length / totalItems : 0,
-      },
-      graphMetrics: trajectory.graphMetrics,
-    };
-  }
-
-  /**
-   * Compute structural metrics from graph data.
-   */
-  private computeStructuralMetrics(trajectory: TeamTrajectory): StructuralMetrics {
-    const gm = trajectory.graphMetrics;
-    return {
-      teamSize: gm.teamSize,
-      totalEvents: gm.totalSteps,
-      totalInteractions: gm.totalInteractions,
-      interactionDensity: gm.interactionDensity,
-      maxInDegree: { role: gm.maxInDegree.agentId, count: gm.maxInDegree.count },
-      maxOutDegree: { role: gm.maxOutDegree.agentId, count: gm.maxOutDegree.count },
-      parallelismRatio: gm.parallelismRatio,
-      totalWallTimeSeconds: gm.totalWallTimeSeconds,
-      totalTokens: gm.totalTokens,
-    };
-  }
-
-  /**
-   * Select critical steps above threshold, respecting max ratio.
-   */
-  private selectCritical(
-    scored: CriticalStep[],
-    threshold: number,
-    maxRatio: number
-  ): CriticalStep[] {
-    const aboveThreshold = scored
-      .filter((s) => s.scores.total >= threshold)
-      .sort((a, b) => b.scores.total - a.scores.total);
-
-    const maxCount = Math.max(1, Math.ceil(scored.length * maxRatio));
-    return aboveThreshold.slice(0, maxCount);
-  }
-
-  /**
-   * Select critical interactions above threshold.
-   */
-  private selectCriticalInteractions(
-    scored: CriticalInteraction[],
-    threshold: number
-  ): CriticalInteraction[] {
-    return scored
-      .filter((i) => i.scores.total >= threshold)
-      .sort((a, b) => b.scores.total - a.scores.total);
-  }
-
-  // ============================================================
-  // Graph-Aware Scoring (when members[] / interactions[] available)
-  // ============================================================
-
-  /**
-   * Score actual trajectory steps from member trajectories.
-   * Uses content-based heuristics (thought/action/observation text)
-   * in addition to position and interaction scoring.
-   */
-  private scoreGraphSteps(
-    members: MemberTrajectory[],
-    trajectory: TeamTrajectory
-  ): CriticalStep[] {
-    const interactionSteps = new Set<string>();
-    if (trajectory.interactions) {
-      for (const interaction of trajectory.interactions) {
-        interactionSteps.add(`${interaction.from.agentId}:${interaction.from.stepIndex}`);
-        interactionSteps.add(`${interaction.to.agentId}:${interaction.to.stepIndex}`);
-      }
-    }
-
-    const allScored: CriticalStep[] = [];
-
-    for (const member of members) {
-      const steps = member.trajectory.steps;
-      const totalSteps = steps.length;
-      if (totalSteps === 0) continue;
-
-      for (let i = 0; i < totalSteps; i++) {
-        const step = steps[i];
-
-        // Position score: early and late steps are more important
-        const normalizedPos = totalSteps > 1 ? i / (totalSteps - 1) : 0.5;
-        const positionScore = 1 - 4 * Math.pow(normalizedPos - 0.5, 2);
-
-        // Action type score based on step content
-        const actionScore = this.scoreStepAction(step);
-
-        // Interaction bonus: is this step involved in an agent interaction?
-        const isInteractionStep = interactionSteps.has(`${member.agentId}:${i}`);
-        const interactionBonus = isInteractionStep ? 0.3 : 0;
-
-        // Content-based score: look at thought/action/observation text
-        const contentScore = this.scoreStepContent(step);
-
-        // Weighted total (content replaces some of the action weight)
-        const total =
-          positionScore * 0.2 +
-          actionScore * 0.25 +
-          interactionBonus * 0.25 +
-          contentScore * 0.3;
-
-        // Create a synthetic TeamEvent for backward compatibility
-        const syntheticEvent: TeamEvent = {
-          timestamp: step.timestamp ?? new Date(),
-          type: this.stepActionToEventType(step),
-          agentId: member.agentId,
-          role: member.role,
-          payload: { action: step.action, observation: step.observation },
-        };
-
-        allScored.push({
-          agentId: member.agentId,
-          role: member.role,
-          eventIndex: i, // maps to step index within the flattened event list
-          event: syntheticEvent,
-          scores: {
-            position: positionScore,
-            actionType: actionScore,
-            interactionBonus,
-            total,
-          },
-          // Graph-enriched fields
-          stepIndex: i,
-          stepContent: {
-            thought: step.thought,
-            action: step.action,
-            observation: step.observation,
-          },
-          contentScore,
-        });
-      }
-    }
-
-    return allScored;
-  }
-
-  /**
-   * Score a step's action text for importance.
-   */
-  private scoreStepAction(step: Step): number {
-    const action = step.action.toLowerCase();
-    if (action.includes('delegate') || action.includes('assign')) return 0.7;
-    if (action.includes('error') || action.includes('fail')) return 0.8;
-    if (action.includes('complete') || action.includes('finish')) return 0.7;
-    if (action.includes('decide') || action.includes('choose')) return 0.6;
-    if (action.includes('plan') || action.includes('design')) return 0.5;
-    if (action.includes('signal') || action.includes('emit')) return 0.4;
-    if (action.includes('read') || action.includes('search')) return 0.2;
-    return 0.3;
-  }
-
-  /**
-   * Content-based scoring: analyze thought/action/observation text
-   * for indicators of importance.
-   */
-  private scoreStepContent(step: Step): number {
-    let score = 0;
-    const text = [step.thought ?? '', step.action, step.observation].join(' ').toLowerCase();
-
-    // Error/failure indicators are highly important
-    if (text.includes('error') || text.includes('exception') || text.includes('failed')) {
-      score += 0.3;
-    }
-    // Decision points
-    if (text.includes('decided') || text.includes('choosing') || text.includes('selected')) {
-      score += 0.2;
-    }
-    // Coordination events
-    if (text.includes('delegat') || text.includes('coordin') || text.includes('handoff')) {
-      score += 0.2;
-    }
-    // Success/completion
-    if (text.includes('success') || text.includes('completed') || text.includes('resolved')) {
-      score += 0.2;
-    }
-    // Thought present (reasoning visible)
-    if (step.thought && step.thought.length > 50) {
-      score += 0.1;
-    }
-
-    return Math.min(score, 1.0);
-  }
-
-  /**
-   * Map step action text to TeamEventType.
-   */
-  private stepActionToEventType(step: Step): TeamEventType {
-    const action = step.action.toLowerCase();
-    if (action.includes('delegate')) return 'task_delegated';
-    if (action.includes('signal') || action.includes('emit')) return 'signal_emitted';
-    if (action.includes('message') || action.includes('send')) return 'message_sent';
-    if (action.includes('plan')) return 'plan_proposed';
-    if (action.includes('escalat')) return 'escalation';
-    return 'task_completed';
-  }
-
-  /**
-   * Score step-level AgentInteraction objects.
-   * Richer than flat InteractionEdge scoring: uses content, latency,
-   * wasExpected flag, and downstream success analysis.
-   */
-  private scoreGraphInteractions(
-    interactions: AgentInteraction[],
-    members: MemberTrajectory[],
-    trajectory: TeamTrajectory
-  ): CriticalInteraction[] {
-    if (interactions.length === 0) return [];
-
-    // Build a map of member trajectories for downstream analysis
-    const memberMap = new Map<string, MemberTrajectory>();
-    for (const m of members) {
-      memberMap.set(m.agentId, m);
-    }
-
-    // Also build flat edge map for backward-compatible CriticalInteraction.edge
-    const edgeMap = new Map<string, InteractionEdge>();
-    for (const edge of trajectory.interactionGraph) {
-      edgeMap.set(`${edge.from}->${edge.to}`, edge);
-    }
-
-    return interactions.map((interaction) => {
-      // Volume score: normalize by total interactions
-      const volume = 1 / interactions.length;
-
-      // Type diversity bonus: certain types are more critical
-      const typeBonuses: Record<string, number> = {
-        delegation: 0.3,
-        result_return: 0.25,
-        escalation: 0.35,
-        signal: 0.15,
-        message: 0.1,
-        spawn: 0.2,
-      };
-      const typeBonus = typeBonuses[interaction.type] ?? 0.1;
-
-      // Latency penalty
-      const latencyPenalty = interaction.latencyMs
-        ? Math.min(interaction.latencyMs / 10000, 0.3)
-        : 0;
-
-      // Expected pattern bonus: unexpected interactions are more noteworthy
-      const unexpectedBonus = interaction.wasExpected ? 0 : 0.15;
-
-      // Downstream success: check if the target agent succeeded after this interaction
-      const downstreamSuccessScore = this.computeDownstreamSuccess(
-        interaction,
-        memberMap
-      );
-
-      const total = Math.max(
-        0,
-        volume * 0.2 +
-          typeBonus * 0.25 +
-          unexpectedBonus * 0.15 +
-          downstreamSuccessScore * 0.2 -
-          latencyPenalty * 0.2
-      );
-
-      // Find the matching flat edge for backward compatibility
-      const edgeKey = `${interaction.from.role}->${interaction.to.role}`;
-      const edge = edgeMap.get(edgeKey) ?? {
-        from: interaction.from.role,
-        to: interaction.to.role,
-        count: 1,
-        types: [],
-      };
-
-      return {
-        edge,
-        scores: {
-          volume,
-          diversityBonus: typeBonus + unexpectedBonus,
-          latencyPenalty,
-          total,
-        },
-        // Graph-enriched fields
-        interaction,
-        downstreamSuccessScore,
-      };
-    });
-  }
-
-  /**
-   * Check downstream success: did the target agent complete steps
-   * successfully after receiving this interaction?
-   */
-  private computeDownstreamSuccess(
-    interaction: AgentInteraction,
-    memberMap: Map<string, MemberTrajectory>
-  ): number {
-    const targetMember = memberMap.get(interaction.to.agentId);
-    if (!targetMember) return 0.5;
-
-    const steps = targetMember.trajectory.steps;
-    const startIdx = interaction.to.stepIndex;
-
-    // Look at up to 5 steps after the interaction
-    const downstreamSteps = steps.slice(startIdx, startIdx + 5);
-    if (downstreamSteps.length === 0) return 0.5;
-
-    let successIndicators = 0;
-    let failureIndicators = 0;
-    for (const step of downstreamSteps) {
-      const text = [step.action, step.observation].join(' ').toLowerCase();
-      if (text.includes('success') || text.includes('completed') || text.includes('pass')) {
-        successIndicators++;
-      }
-      if (text.includes('error') || text.includes('fail') || text.includes('exception')) {
-        failureIndicators++;
-      }
-    }
-
-    if (successIndicators > failureIndicators) return 0.8;
-    if (failureIndicators > successIndicators) return 0.2;
-    // Also consider overall trajectory outcome
-    return targetMember.trajectory.outcome?.success ? 0.6 : 0.4;
-  }
-}
-
-/**
- * Create a TeamTrajectoryIngester instance.
- */
-export function createTeamTrajectoryIngester(
-  config?: Partial<CompressionConfig>
-): TeamTrajectoryIngester {
-  return new TeamTrajectoryIngester(config);
-}