gepa_record_trajectory

Instructions

Implementation Reference

• src/mcp/server.ts:749-827 (handler)

  The primary handler function for the 'gepa_record_trajectory' tool. It validates input parameters, constructs an ExecutionTrajectory object, saves it to the TrajectoryStore, conditionally adds a candidate to the ParetoFrontier if successful, and returns a formatted text response with details.

    private async recordTrajectory(params: RecordTrajectoryParams): Promise<{
      content: { type: string; text: string; }[];
    }> {
      const { promptId, taskId, executionSteps, result, metadata } = params;
  
      // Validate required parameters
      if (!promptId || !taskId || !executionSteps || !result) {
        throw new Error('promptId, taskId, executionSteps, and result are required');
      }
  
      // Create trajectory object
      const trajectory: ExecutionTrajectory = {
        id: `trajectory_${Date.now()}_${Math.random().toString(36).substring(7)}`,
        promptId,
        taskId,
        timestamp: new Date(),
        steps: executionSteps,
        finalResult: result,
        llmCalls: [],
        toolCalls: [],
        totalTokens: metadata?.tokenUsage || 0,
        executionTime: metadata?.executionTime || 0,
      };
  
      try {
        // Save trajectory to store
        const saveResult = await this.trajectoryStore.save(trajectory);
  
        // Update Pareto frontier if this is a successful execution
        if (result.success && result.score > 0) {
          const candidate: GEPAPromptCandidate = {
            id: promptId,
            content: '', // Will be retrieved if needed
            generation: 0,
            taskPerformance: new Map([[taskId, result.score]]),
            averageScore: result.score,
            rolloutCount: 1,
            createdAt: new Date(),
            lastEvaluated: new Date(),
            mutationType: 'initial',
          };
  
          this.paretoFrontier.addCandidate(candidate);
        }
  
        return {
          content: [
            {
              type: 'text',
              text: `# Trajectory Recorded Successfully
  
  ## Trajectory Details
  - **Trajectory ID**: ${trajectory.id}
  - **Prompt ID**: ${promptId}
  - **Task ID**: ${taskId}
  - **Execution Steps**: ${executionSteps.length}
  - **Success**: ${result.success ? '✅' : '❌'}
  - **Performance Score**: ${result.score.toFixed(3)}
  
  ## Execution Summary
  - **Total Steps**: ${executionSteps.length}
  - **Successful Steps**: ${executionSteps.filter(step => !step.error).length}
  - **Failed Steps**: ${executionSteps.filter(step => step.error).length}
  - **Execution Time**: ${metadata?.executionTime || 'N/A'}ms
  - **Token Usage**: ${metadata?.tokenUsage || 'N/A'}
  
  ## Storage
  - **File**: ${saveResult.filePath || 'N/A'}
  - **Success**: ${saveResult.success ? 'Yes' : 'No'}
  - **ID**: ${saveResult.id || 'N/A'}
  
  ${result.success && result.score > 0 ? '✨ Candidate added to Pareto frontier for optimization.' : ''}`,
            },
          ],
        };
      } catch (error) {
        throw new Error(`Failed to record trajectory: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }

• src/mcp/server.ts:94-145 (schema)

  The JSON input schema definition for the gepa_record_trajectory tool, including all properties, descriptions, and required fields, used for tool listing and validation.

  {
    name: 'gepa_record_trajectory',
    description: 'Record execution trajectory for prompt evaluation',
    inputSchema: {
      type: 'object',
      properties: {
        promptId: {
          type: 'string',
          description: 'Unique identifier for the prompt candidate'
        },
        taskId: {
          type: 'string',
          description: 'Identifier for the specific task instance'
        },
        executionSteps: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              action: { type: 'string' },
              input: { type: 'object' },
              output: { type: 'object' },
              timestamp: { type: 'string' },
              success: { type: 'boolean' }
            },
            required: ['action', 'timestamp', 'success']
          },
          description: 'Sequence of execution steps'
        },
        result: {
          type: 'object',
          properties: {
            success: { type: 'boolean' },
            score: { type: 'number' },
            output: { type: 'object' }
          },
          required: ['success', 'score'],
          description: 'Final execution result and performance score'
        },
        metadata: {
          type: 'object',
          properties: {
            llmModel: { type: 'string' },
            executionTime: { type: 'number' },
            tokenUsage: { type: 'number' }
          },
          description: 'Additional execution metadata (optional)'
        }
      },
      required: ['promptId', 'taskId', 'executionSteps', 'result']
    }
  },

• src/mcp/server.ts:529-531 (registration)

  The switch case registration that maps incoming tool calls named 'gepa_record_trajectory' to the recordTrajectory handler method.

  case 'gepa_record_trajectory':
    return await this.recordTrajectory(args as unknown as RecordTrajectoryParams);

• src/mcp/types.ts:266-266 (schema)

  Type-safe constant defining the tool name 'gepa_record_trajectory' as RECORD_TRAJECTORY in the TOOL_NAMES object.

  RECORD_TRAJECTORY: 'gepa_record_trajectory',