mcp-adr-analysis-server/dist/src/types/ape-framework.d.ts

MCP server for analyzing Architectural Decision Records and project architecture

/**
 * TypeScript interfaces for Automatic Prompt Engineer (APE) Framework
 * Implements automatic prompt generation, evaluation, and optimization
 */
import { z } from 'zod';
/**
 * Base prompt object structure used throughout the APE framework
 */
export interface PromptObject {
    /** The main prompt text */
    prompt: string;
    /** Instructions for how to use the prompt */
    instructions: string;
    /** Additional context data */
    context: any;
}
export type GenerationStrategy = 'template-variation' | 'semantic-variation' | 'style-variation' | 'length-variation' | 'structure-variation' | 'hybrid-approach';
export type EvaluationCriterion = 'task-completion' | 'clarity' | 'specificity' | 'robustness' | 'efficiency' | 'context-awareness';
export type SelectionStrategy = 'highest-score' | 'multi-criteria' | 'ensemble' | 'context-aware' | 'balanced';
export type OptimizationPhase = 'candidate-generation' | 'evaluation' | 'selection' | 'refinement' | 'validation';
/**
 * Configuration interface for APE optimization process
 */
export interface APEConfig {
    /** Number of candidates to generate (default: 5) */
    candidateCount: number;
    /** Criteria used for evaluating prompt candidates */
    evaluationCriteria: EvaluationCriterion[];
    /** Number of optimization iterations (default: 3) */
    optimizationRounds: number;
    /** Strategy for selecting best candidates */
    selectionStrategy: SelectionStrategy;
    /** Whether to enable caching of results */
    cacheEnabled: boolean;
    /** Whether to track performance metrics */
    performanceTracking: boolean;
    /** Maximum time in milliseconds for optimization */
    maxOptimizationTime: number;
    /** Minimum quality score (0-1) to accept candidates */
    qualityThreshold: number;
    /** Weight for candidate diversity (0-1) */
    diversityWeight: number;
}
export declare const APEConfigSchema: z.ZodObject<{
    candidateCount: z.ZodNumber;
    evaluationCriteria: z.ZodArray<z.ZodEnum<{
        "task-completion": "task-completion";
        clarity: "clarity";
        specificity: "specificity";
        robustness: "robustness";
        efficiency: "efficiency";
        "context-awareness": "context-awareness";
    }>>;
    optimizationRounds: z.ZodNumber;
    selectionStrategy: z.ZodEnum<{
        "highest-score": "highest-score";
        "multi-criteria": "multi-criteria";
        ensemble: "ensemble";
        "context-aware": "context-aware";
        balanced: "balanced";
    }>;
    cacheEnabled: z.ZodBoolean;
    performanceTracking: z.ZodBoolean;
    maxOptimizationTime: z.ZodNumber;
    qualityThreshold: z.ZodNumber;
    diversityWeight: z.ZodNumber;
}, z.core.$strip>;
/**
 * Configuration for optimizing prompts for specific tools
 */
export interface ToolOptimizationConfig {
    /** Name of the tool being optimized */
    toolName: string;
    /** Type of task the tool performs */
    taskType: string;
    /** APE configuration to use */
    apeConfig: APEConfig;
    /** Required context elements for the tool */
    contextRequirements: string[];
    /** Criteria for determining optimization success */
    successCriteria: string[];
    /** Custom evaluators for tool-specific metrics */
    customEvaluators?: CustomEvaluator[];
}
/**
 * Represents a generated prompt candidate during optimization
 */
export interface PromptCandidate {
    /** Unique identifier for the candidate */
    id: string;
    /** The generated prompt text */
    prompt: string;
    /** Instructions for using the prompt */
    instructions: string;
    /** Context data for the prompt */
    context: any;
    /** Strategy used to generate this candidate */
    generationStrategy: GenerationStrategy;
    /** Metadata about the generation process */
    metadata: CandidateMetadata;
    /** ID of parent candidate (for refined candidates) */
    parentId?: string;
    /** Generation number in optimization process */
    generation: number;
}
/**
 * Metadata about how a prompt candidate was generated
 */
export interface CandidateMetadata {
    /** Timestamp when candidate was generated */
    generatedAt: string;
    /** Time taken to generate candidate (milliseconds) */
    generationTime: number;
    /** Strategy used for generation */
    strategy: GenerationStrategy;
    /** Template used as base (if any) */
    templateUsed?: string;
    /** Variations applied during generation */
    variationApplied?: string[];
    /** Complexity score (0-1 scale) */
    complexity: number;
    /** Estimated quality score (0-1 scale) */
    estimatedQuality: number;
    /** Approximate token count */
    tokens: number;
}
/**
 * Request for generating prompt candidates
 */
export interface GenerationRequest {
    /** Base prompt to generate variations from */
    basePrompt: PromptObject;
    /** Strategies to use for generation */
    strategies: GenerationStrategy[];
    /** Number of candidates to generate */
    candidateCount: number;
    /** Context for generation */
    context: GenerationContext;
    /** Constraints to apply during generation */
    constraints: GenerationConstraints;
}
/**
 * Context information for prompt generation
 */
export interface GenerationContext {
    /** Type of task the prompt will be used for */
    taskType: string;
    /** Domain or subject area */
    domain: string;
    /** Intended audience for the prompt */
    targetAudience: string;
    /** Complexity level of the prompt */
    complexity: 'simple' | 'moderate' | 'complex';
    /** Writing style to use */
    style: 'formal' | 'conversational' | 'technical';
    /** Target length of the prompt */
    length: 'short' | 'medium' | 'long';
}
/**
 * Constraints to apply during prompt generation
 */
export interface GenerationConstraints {
    /** Maximum length in characters */
    maxLength: number;
    /** Minimum length in characters */
    minLength: number;
    /** Keywords that must be included */
    requiredKeywords: string[];
    /** Terms that must not be included */
    forbiddenTerms: string[];
    /** Style requirements to follow */
    styleRequirements: string[];
    /** Format requirements to follow */
    formatRequirements: string[];
}
/**
 * Result of evaluating a prompt candidate
 */
export interface EvaluationResult {
    /** ID of the candidate that was evaluated */
    candidateId: string;
    /** Scores for each evaluation criterion (0-1) */
    scores: Record<EvaluationCriterion, number>;
    /** Weighted average overall score (0-1) */
    overallScore: number;
    /** Detailed feedback for each criterion */
    feedback: EvaluationFeedback[];
    /** Time taken for evaluation (milliseconds) */
    evaluationTime: number;
    /** Version of the evaluator used */
    evaluatorVersion: string;
    /** Additional evaluation metadata */
    metadata: EvaluationMetadata;
}
/**
 * Detailed feedback for a specific evaluation criterion
 */
export interface EvaluationFeedback {
    /** The criterion this feedback relates to */
    criterion: EvaluationCriterion;
    /** Score for this criterion (0-1) */
    score: number;
    /** Explanation of why this score was given */
    reasoning: string;
    /** Suggestions for improvement */
    suggestions: string[];
    /** Examples to illustrate the feedback */
    examples?: string[];
}
export interface EvaluationMetadata {
    evaluatedAt: string;
    evaluationMethod: string;
    confidence: number;
    reliability: number;
    contextMatch: number;
    biasScore: number;
}
export interface CustomEvaluator {
    name: string;
    criterion: EvaluationCriterion;
    weight: number;
    evaluationPrompt: string;
    expectedOutputFormat: string;
    validationRules: ValidationRule[];
}
export interface ValidationRule {
    type: 'length' | 'keyword' | 'format' | 'score';
    condition: string;
    errorMessage: string;
}
export interface SelectionResult {
    selectedCandidates: PromptCandidate[];
    selectionReasoning: string;
    diversityScore: number;
    qualityScore: number;
    selectionTime: number;
    metadata: SelectionMetadata;
}
export interface SelectionMetadata {
    strategy: SelectionStrategy;
    candidatesConsidered: number;
    selectionCriteria: EvaluationCriterion[];
    weights: Record<EvaluationCriterion, number>;
    diversityWeight: number;
    qualityThreshold: number;
}
export interface OptimizationResult {
    optimizedPrompt: PromptObject;
    originalPrompt: PromptObject;
    improvementScore: number;
    optimizationRounds: number;
    candidatesEvaluated: number;
    totalOptimizationTime: number;
    cacheKey: string;
    metadata: OptimizationMetadata;
    performanceMetrics: PerformanceMetrics;
}
export interface OptimizationMetadata {
    optimizedAt: string;
    apeVersion: string;
    configUsed: APEConfig;
    strategiesApplied: GenerationStrategy[];
    evaluationCriteria: EvaluationCriterion[];
    selectionStrategy: SelectionStrategy;
    qualityImprovement: number;
    convergenceRound: number;
}
export interface PerformanceMetrics {
    generationTime: number;
    evaluationTime: number;
    selectionTime: number;
    totalTime: number;
    candidatesGenerated: number;
    candidatesEvaluated: number;
    cacheHits: number;
    cacheMisses: number;
    memoryUsage: number;
    successRate: number;
}
export interface OptimizationHistory {
    optimizationId: string;
    timestamp: string;
    toolName: string;
    taskType: string;
    originalPrompt: PromptObject;
    optimizedPrompt: PromptObject;
    improvementScore: number;
    config: APEConfig;
    metrics: PerformanceMetrics;
    userFeedback?: UserFeedback;
}
export interface UserFeedback {
    rating: number;
    comments: string;
    usefulnessScore: number;
    clarityScore: number;
    effectivenessScore: number;
    wouldRecommend: boolean;
    submittedAt: string;
}
export interface APECacheEntry {
    key: string;
    type: 'candidate' | 'evaluation' | 'optimization' | 'performance';
    data: any;
    timestamp: string;
    ttl: number;
    accessCount: number;
    lastAccessed: string;
    metadata: CacheEntryMetadata;
}
export interface CacheEntryMetadata {
    version: string;
    compressed: boolean;
    size: number;
    tags: string[];
    priority: 'low' | 'medium' | 'high';
    context: string;
}
export interface APEError {
    code: string;
    message: string;
    phase: OptimizationPhase;
    candidateId?: string;
    timestamp: string;
    recoverable: boolean;
    context?: any;
}
export interface OptimizationStatus {
    status: 'pending' | 'generating' | 'evaluating' | 'selecting' | 'optimizing' | 'completed' | 'failed';
    progress: number;
    currentPhase: OptimizationPhase;
    candidatesGenerated: number;
    candidatesEvaluated: number;
    estimatedTimeRemaining: number;
    errors: APEError[];
    warnings: string[];
}
export declare const PromptCandidateSchema: z.ZodObject<{
    id: z.ZodString;
    prompt: z.ZodString;
    instructions: z.ZodString;
    context: z.ZodAny;
    generationStrategy: z.ZodEnum<{
        "template-variation": "template-variation";
        "semantic-variation": "semantic-variation";
        "style-variation": "style-variation";
        "length-variation": "length-variation";
        "structure-variation": "structure-variation";
        "hybrid-approach": "hybrid-approach";
    }>;
    metadata: z.ZodObject<{
        generatedAt: z.ZodString;
        generationTime: z.ZodNumber;
        strategy: z.ZodString;
        templateUsed: z.ZodOptional<z.ZodString>;
        variationApplied: z.ZodOptional<z.ZodArray<z.ZodString>>;
        complexity: z.ZodNumber;
        estimatedQuality: z.ZodNumber;
        tokens: z.ZodNumber;
    }, z.core.$strip>;
    parentId: z.ZodOptional<z.ZodString>;
    generation: z.ZodNumber;
}, z.core.$strip>;
export declare const OptimizationResultSchema: z.ZodObject<{
    optimizedPrompt: z.ZodObject<{
        prompt: z.ZodString;
        instructions: z.ZodString;
        context: z.ZodAny;
    }, z.core.$strip>;
    originalPrompt: z.ZodObject<{
        prompt: z.ZodString;
        instructions: z.ZodString;
        context: z.ZodAny;
    }, z.core.$strip>;
    improvementScore: z.ZodNumber;
    optimizationRounds: z.ZodNumber;
    candidatesEvaluated: z.ZodNumber;
    totalOptimizationTime: z.ZodNumber;
    cacheKey: z.ZodString;
    metadata: z.ZodObject<{
        optimizedAt: z.ZodString;
        apeVersion: z.ZodString;
        configUsed: z.ZodObject<{
            candidateCount: z.ZodNumber;
            evaluationCriteria: z.ZodArray<z.ZodEnum<{
                "task-completion": "task-completion";
                clarity: "clarity";
                specificity: "specificity";
                robustness: "robustness";
                efficiency: "efficiency";
                "context-awareness": "context-awareness";
            }>>;
            optimizationRounds: z.ZodNumber;
            selectionStrategy: z.ZodEnum<{
                "highest-score": "highest-score";
                "multi-criteria": "multi-criteria";
                ensemble: "ensemble";
                "context-aware": "context-aware";
                balanced: "balanced";
            }>;
            cacheEnabled: z.ZodBoolean;
            performanceTracking: z.ZodBoolean;
            maxOptimizationTime: z.ZodNumber;
            qualityThreshold: z.ZodNumber;
            diversityWeight: z.ZodNumber;
        }, z.core.$strip>;
        strategiesApplied: z.ZodArray<z.ZodString>;
        evaluationCriteria: z.ZodArray<z.ZodString>;
        selectionStrategy: z.ZodString;
        qualityImprovement: z.ZodNumber;
        convergenceRound: z.ZodNumber;
    }, z.core.$strip>;
    performanceMetrics: z.ZodObject<{
        generationTime: z.ZodNumber;
        evaluationTime: z.ZodNumber;
        selectionTime: z.ZodNumber;
        totalTime: z.ZodNumber;
        candidatesGenerated: z.ZodNumber;
        candidatesEvaluated: z.ZodNumber;
        cacheHits: z.ZodNumber;
        cacheMisses: z.ZodNumber;
        memoryUsage: z.ZodNumber;
        successRate: z.ZodNumber;
    }, z.core.$strip>;
}, z.core.$strip>;
//# sourceMappingURL=ape-framework.d.ts.map