cognitive-core 0.1.0 → 0.2.0

package/src/learning/team-ingester.ts

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