optimize

type AgentArtifacts ¶

type AgentArtifacts struct {
	Text map[ArtifactKey]string
	Int  map[string]int
	Bool map[string]bool
}

AgentArtifacts groups mutable agent configuration surfaced to optimizers.

func (a AgentArtifacts) Clone() AgentArtifacts

type AgentEvaluator ¶

type AgentEvaluator interface {
	Evaluate(ctx context.Context, agent OptimizableAgent, ex AgentExample) (*EvalResult, error)
}

AgentEvaluator evaluates an agent on a concrete task and returns score plus ASI.

type AgentExample ¶

type AgentExample struct {
	ID       string
	Inputs   map[string]interface{}
	Outputs  map[string]interface{}
	Metadata map[string]interface{}
}

AgentExample describes a single evaluation task for an optimizable agent.

type ArtifactKey ¶

type ArtifactKey string

ArtifactKey identifies a mutable artifact on an optimizable agent.

const (
	ArtifactSkillPack          ArtifactKey = "skill_pack"
	ArtifactPlannerPrompt      ArtifactKey = "planner_prompt"
	ArtifactToolPolicy         ArtifactKey = "tool_policy"
	ArtifactMemoryTemplate     ArtifactKey = "memory_template"
	ArtifactReflectionPrompt   ArtifactKey = "reflection_prompt"
	ArtifactContextPolicy      ArtifactKey = "context_policy"
	ArtifactRLMOuterPrompt     ArtifactKey = "rlm_outer_prompt"
	ArtifactRLMIterationPrompt ArtifactKey = "rlm_iteration_prompt"
)

type ComparisonResult ¶

type ComparisonResult struct {
	Score       float64
	Scores      map[string]float64
	Diagnostics map[string]interface{}
	PassedTests []string
	FailedTests []string
}

ComparisonResult captures deterministic output-comparison details.

type DeterministicEvaluator ¶

type DeterministicEvaluator struct {
	Comparator OutputComparator
}

DeterministicEvaluator runs an agent on concrete examples and attaches structured side information suitable for downstream optimization.

func NewDeterministicEvaluator(comparator OutputComparator) *DeterministicEvaluator

func (e *DeterministicEvaluator) Evaluate(ctx context.Context, agent OptimizableAgent, ex AgentExample) (*EvalResult, error)

type EvalResult ¶

type EvalResult struct {
	Score    float64
	SideInfo *SideInfo
}

EvalResult is the output of an AgentEvaluator.

type ExactMatchComparator ¶

type ExactMatchComparator struct{}

ExactMatchComparator scores outputs by exact per-key equality against the example's Outputs map. If no expected outputs are provided, any successful execution receives a score of 1.0.

Matching uses reflect.DeepEqual, so callers should expect Go's normal type sensitivity here. For example, int(1) and float64(1) do not match.

func (ExactMatchComparator) Compare(ex AgentExample, actual map[string]interface{}) (*ComparisonResult, error)

type GEPAAdapterConfig ¶

type GEPAAdapterConfig struct {
	PopulationSize             int
	MaxGenerations             int
	ReflectionFreq             int
	SearchBatchSize            int
	StagnationLimit            int
	ValidationSplit            float64
	ValidationFrequency        int
	ArtifactKeys               []ArtifactKey
	EvalConcurrency            int
	PassThreshold              float64
	PrimaryArtifact            ArtifactKey
	MaxMetricCalls             int
	ScoreThreshold             float64
	MaxRuntime                 time.Duration
	GenerationLLM              core.LLM
	ReflectionLLM              core.LLM
	FeedbackEvaluator          optimizers.GEPAFeedbackEvaluator
	AddFormatFailureAsFeedback bool
	IntMutationPlans           map[string]IntMutationConfig
}

GEPAAdapterConfig configures the agent-to-GEPA bridge layer.

func DefaultGEPAAdapterConfig() GEPAAdapterConfig

type GEPAAgentOptimizer ¶

type GEPAAgentOptimizer struct {
	// contains filtered or unexported fields
}

GEPAAgentOptimizer holds the shared translation logic between agent evaluation and GEPA's candidate, trace, and fitness types.

func NewGEPAAgentOptimizer(baseAgent OptimizableAgent, evaluator AgentEvaluator, cfg GEPAAdapterConfig) *GEPAAgentOptimizer

func (o *GEPAAgentOptimizer) CandidateArtifacts(candidate *optimizers.GEPACandidate) (AgentArtifacts, error)

func (o *GEPAAgentOptimizer) EvaluateCandidate(ctx context.Context, candidate *optimizers.GEPACandidate, examples []AgentExample) (*GEPACandidateEvaluation, error)

func (o *GEPAAgentOptimizer) MaterializeAgent(artifacts AgentArtifacts) (OptimizableAgent, error)

func (o *GEPAAgentOptimizer) Optimize(ctx context.Context, req GEPAOptimizeRequest) (*GEPAOptimizeResult, error)

func (o *GEPAAgentOptimizer) SeedCandidate(seed AgentArtifacts) (*optimizers.GEPACandidate, error)

func (o *GEPAAgentOptimizer) WithFactory(factory func(AgentArtifacts) (OptimizableAgent, error)) *GEPAAgentOptimizer

type GEPACandidateEvaluation ¶

type GEPACandidateEvaluation struct {
	Candidate    *optimizers.GEPACandidate
	Artifacts    AgentArtifacts
	Run          *HarnessRunResult
	Fitness      *optimizers.MultiObjectiveFitness
	Traces       []optimizers.ExecutionTrace
	AverageScore float64
}

GEPACandidateEvaluation captures the GEPA-shaped output of evaluating one agent candidate.

type GEPAOptimizeRequest ¶

type GEPAOptimizeRequest struct {
	SeedArtifacts      AgentArtifacts
	TrainingExamples   []AgentExample
	ValidationExamples []AgentExample
	ProgressReporter   core.ProgressReporter
}

GEPAOptimizeRequest configures one end-to-end GEPA optimization run for an agent artifact set.

SeedArtifacts and examples are treated as trusted harness inputs. They may be embedded into model prompts during optimization, so callers should source them from trusted corpora or explicitly sanitize them before invoking Optimize.

type GEPAOptimizeResult ¶

type GEPAOptimizeResult struct {
	BestCandidate            *optimizers.GEPACandidate
	BestArtifacts            AgentArtifacts
	BestValidationEvaluation *GEPACandidateEvaluation
	TrainingExampleCount     int
	ValidationExampleCount   int
	OptimizationState        *optimizers.GEPAState
}

GEPAOptimizeResult captures the best candidate and resulting artifacts from a GEPA run.

type GEPAWorkflowRequest ¶ added in v0.83.1

type GEPAWorkflowRequest struct {
	Evaluator          AgentEvaluator
	TrainingExamples   []AgentExample
	ValidationExamples []AgentExample
	BaselineExamples   []AgentExample
	ReplayExamples     []AgentExample
	PassThreshold      float64
	Config             GEPAAdapterConfig
	ProgressReporter   core.ProgressReporter
	ApplyBest          bool
	ArtifactPath       string
}

GEPAWorkflowRequest describes one baseline -> optimize -> save/restore -> replay optimization flow for an optimizable agent.

type GEPAWorkflowResult ¶ added in v0.83.1

type GEPAWorkflowResult struct {
	BaselineRun      *HarnessRunResult
	Optimization     *GEPAOptimizeResult
	OptimizedProgram *OptimizedAgentProgram
	ReplayRun        *HarnessRunResult
}

GEPAWorkflowResult captures the user-facing outputs of a full optimization workflow.

func RunGEPAWorkflow(ctx context.Context, baseAgent OptimizableAgent, req GEPAWorkflowRequest) (*GEPAWorkflowResult, error)

type Harness ¶

type Harness struct {
	Evaluator     AgentEvaluator
	PassThreshold float64
}

Harness runs an evaluator across a fixed example set while isolating each run behind a fresh agent clone.

func (h *Harness) Run(ctx context.Context, baseAgent OptimizableAgent, examples []AgentExample) (*HarnessRunResult, error)

type HarnessExampleResult ¶

type HarnessExampleResult struct {
	ExampleID string
	Result    *EvalResult
}

HarnessExampleResult records one evaluator outcome for one example.

type HarnessRunResult ¶

type HarnessRunResult struct {
	Results           []HarnessExampleResult
	AverageScore      float64
	PassedExamples    int
	FailedExamples    int
	CompletedExamples int
	EvaluationErrors  int
}

HarnessRunResult aggregates a deterministic evaluation run.

type IntMutationConfig ¶

type IntMutationConfig struct {
	Min  int
	Max  int
	Step int
}

IntMutationConfig defines a bounded deterministic search neighborhood for an integer artifact that GEPA itself does not mutate natively.

type OptimizableAgent ¶

type OptimizableAgent interface {
	agents.Agent

	GetArtifacts() AgentArtifacts
	SetArtifacts(AgentArtifacts) error
	Clone() (OptimizableAgent, error)
}

OptimizableAgent is a parallel interface that exposes mutable artifacts without widening the base agents.Agent contract.

Implementations that also expose LastExecutionTrace() *agents.ExecutionTrace allow evaluators to attach richer step-level side information without forcing that method into the base interface.

type OptimizationTargetDescriptor ¶ added in v0.83.1

type OptimizationTargetDescriptor struct {
	ID          string                 `json:"id"`
	Kind        OptimizationTargetKind `json:"kind"`
	Description string                 `json:"description,omitempty"`
	ArtifactKey ArtifactKey            `json:"artifact_key,omitempty"`
	IntKey      string                 `json:"int_key,omitempty"`
	BoolKey     string                 `json:"bool_key,omitempty"`
}

OptimizationTargetDescriptor maps a stable user-facing target ID onto one mutable artifact slot.

type OptimizationTargetKind ¶ added in v0.83.1

type OptimizationTargetKind string

OptimizationTargetKind identifies the value family represented by a target.

const (
	OptimizationTargetText OptimizationTargetKind = "text"
	OptimizationTargetInt  OptimizationTargetKind = "int"
	OptimizationTargetBool OptimizationTargetKind = "bool"
)

type OptimizedAgentProgram ¶ added in v0.83.1

type OptimizedAgentProgram struct {
	Schema      string                 `json:"schema"`
	Version     int                    `json:"version"`
	AgentType   string                 `json:"agent_type,omitempty"`
	TargetOrder []string               `json:"target_order,omitempty"`
	Text        map[string]string      `json:"text,omitempty"`
	Int         map[string]int         `json:"int,omitempty"`
	Bool        map[string]bool        `json:"bool,omitempty"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
}

OptimizedAgentProgram is the shared persisted envelope for optimized agent artifacts across native, ReAct, and RLM-backed agents.

func ExportOptimizedAgentProgram(agent OptimizableAgent) (*OptimizedAgentProgram, error)

func ExportOptimizedAgentProgramFromArtifacts(agent OptimizableAgent, artifacts AgentArtifacts) (*OptimizedAgentProgram, error)

func ReadOptimizedAgentProgram(path string) (*OptimizedAgentProgram, error)

func (p *OptimizedAgentProgram) ToArtifacts(descriptors []OptimizationTargetDescriptor) (AgentArtifacts, error)

func (p *OptimizedAgentProgram) Validate() error

type OutputComparator ¶

type OutputComparator interface {
	Compare(ex AgentExample, actual map[string]interface{}) (*ComparisonResult, error)
}

OutputComparator compares an agent execution result against an example's expectations.

type OutputComparatorFunc ¶

type OutputComparatorFunc func(ex AgentExample, actual map[string]interface{}) (*ComparisonResult, error)

OutputComparatorFunc adapts a function to the OutputComparator interface.

func (f OutputComparatorFunc) Compare(ex AgentExample, actual map[string]interface{}) (*ComparisonResult, error)

type SideInfo ¶

type SideInfo struct {
	Trace       *agents.ExecutionTrace
	Diagnostics map[string]interface{}
	Scores      map[string]float64
	Cost        float64
	LatencyMS   float64
	Tokens      map[string]int64
	PassedTests []string
	FailedTests []string
}

SideInfo carries diagnostic information beyond the scalar evaluation score.