evolution

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package evolution provides GA mode integration for the DreamCycle orchestrator. This file contains the GA-specific evolution path and adapters.

Package evolution provides automatic experience extraction from flight recorder diagnostics. It bridges the flight recording system with the experience store to enable continuous learning from agent execution failures and anomalies.

Package evolution provides automatic experience extraction from flight recorder diagnostics. It bridges the flight recording system with the experience store to enable continuous learning from agent execution failures and anomalies.

genome_wiring_genealogy.go contains the GenomeMutatorAdapter (wraps a genome mutator for population use), the ScoreRollingWindow helper, the PopulationGenealogyRecorder (records strategy lineage from genome evolution), and the RecordPopulationLineage extraction function.

genome_wiring_run.go contains the GenomePopulationAdapter runtime logic: the Run cycle, scorer construction, guardrail checkpoints, outcome recording, coordinator submission, and related helper functions.

Package evolution provides production guardrails for the autonomous evolution system. These guardrails detect dangerous conditions and trigger protective actions before they cause harm.

Package evolution provides automatic experience extraction from flight recorder diagnostics. It bridges the flight recording system with the experience store to enable continuous learning from agent execution failures and anomalies.

Package evolution provides autonomous evolution system components.

Package evolution — PGStrategyStore: PostgreSQL-backed persistent strategy store.

Package evolution provides data-driven evolution reports derived from real run statistics, not template claims.

Package evolution provides rollback policies and strategy management for the autonomous evolution system. RollbackPolicy detects performance degradation and recommends reverting to a previous strategy.

Package evolution provides automatic experience extraction from flight recorder diagnostics. It bridges the flight recording system with the experience store to enable continuous learning from agent execution failures and anomalies.

Index

Constants

View Source 
const (
	TypeFailure = "failure"
)

Experience type constants used by the evolution package.

Variables

View Source 
var ErrAllCandidatesRejected = errors.New("dream cycle: all candidates rejected")

ErrAllCandidatesRejected is returned by findWinner when no candidate passes the win-rate threshold during quick-reject or full evaluation. Callers should treat this as "no winner" rather than a hard error.

View Source 
var ErrNilSystem = fmt.Errorf("system must not be nil")

ErrNilSystem is returned when a nil WiredEvolutionSystem is passed to GenerateReport.

View Source 
var ErrNoActiveStrategy = errors.New("pg strategy store: no active strategy")

ErrNoActiveStrategy is returned by GetActive when no strategy has been stored yet. Callers can errors.Is(err, ErrNoActiveStrategy) to distinguish "empty store" from a real failure.

Functions

func BestStrategyFromSystem 

func BestStrategyFromSystem(system *WiredEvolutionSystem) (*mutation.Strategy, error)

BestStrategyFromSystem returns the highest-scoring strategy from the population.

func RecordPopulationLineage 

func RecordPopulationLineage(
	ctx context.Context,
	pop *genome.Population,
	recorder GenealogyRecorder,
	parentSnapshot []*mutation.Strategy,
	prevGeneration int,
) (int, error)

RecordPopulationLineage extracts parent-child relationships from a genome population after evolution and records them into the genealogy system. This bridges genome.Population's ParentID tracking with evolution.GenealogyRecorder.

Args: 

ctx - operation context.
pop - the post-evolution population to extract lineage from.
parentSnapshot - pre-evolution snapshot for parent score lookup (may be nil).
prevGeneration - the generation number before evolution (for filtering).

Returns: 

int - number of new lineage records created.
error - non-nil if recording fails.

func RegisterScheduler 

func RegisterScheduler(system *WiredEvolutionSystem) error

RegisterScheduler attaches the system's scheduler to its EventStore by subscribing for agent lifecycle events. Returns nil if no scheduler is configured.

func ReportString 

func ReportString(r *EvolutionReport) string

ReportString returns a human-readable summary of the evolution report. Suitable for logging and CLI output.

Args: 

r - the evolution report (must not be nil).

Returns: 

string - formatted report text.

func RunIdleEvolution 

func RunIdleEvolution(ctx context.Context, system *WiredEvolutionSystem, n int) error

RunIdleEvolution runs N generations of idle evolution on the wired system.

func SaveReport added in v0.2.5 

func SaveReport(ctx context.Context, r *EvolutionReport, path string) error

SaveReport writes the human-readable evolution report to a file. Creates parent directories if they don't exist. Returns an error if the file cannot be written or context is cancelled.

Args: 

ctx - operation context (checked before I/O).
r - the evolution report (must not be nil).
path - absolute or relative file path.

Returns: 

error - non-nil if write fails or context cancelled.

func Shutdown 

func Shutdown(system *WiredEvolutionSystem)

Shutdown gracefully shuts down the evolution scheduler if configured.

func ValidateStrategySize added in v0.2.4 

func ValidateStrategySize(s *mutation.Strategy) error

ValidateStrategySize checks a mutation.Strategy against size limits. Returns an error if any field exceeds its maximum allowed size.

Args:

  • s: the strategy to validate (must not be nil).

Returns:

  • error: non-nil if the strategy exceeds size limits.

Types

type ASMOption added in v0.2.4 

type ASMOption func(*ActiveStrategyManager)

ASMOption configures an ActiveStrategyManager instance.

func WithASMGuardrails added in v0.2.4 

func WithASMGuardrails(guardrails *EvolutionGuardrails) ASMOption

WithASMGuardrails attaches guardrails to the active strategy manager. When set, Deploy checks PostEvolveCheck and auto-rollbacks on critical events.

Args:

  • guardrails: the guardrail instance (may be nil, in which case this is a no-op).

Returns:

  • ASMOption: the configuration function.

type ActiveStrategyManager added in v0.2.4 

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

ActiveStrategyManager manages strategy deployment and rollback using a StrategyStore for persistence. It tracks the current and previous strategies, and uses a RollbackPolicy to detect degradation.

func NewActiveStrategyManager added in v0.2.4 

func NewActiveStrategyManager(store StrategyStore, rollbackPolicy *RollbackPolicy, opts ...ASMOption) (*ActiveStrategyManager, error)

NewActiveStrategyManager creates a new strategy manager with the given store and rollback policy.

Args:

  • store: persistent strategy store (must not be nil).
  • rollbackPolicy: rollback policy for degradation detection (may be nil).
  • opts: optional configuration functions.

Returns:

  • *ActiveStrategyManager: the configured manager.
  • error: non-nil if store is nil.

func (*ActiveStrategyManager) Current added in v0.2.4 

func (m *ActiveStrategyManager) Current() *mutation.Strategy

Current returns the currently active strategy (cloned).

Returns:

  • *mutation.Strategy: clone of the current strategy, or nil if none deployed.

func (*ActiveStrategyManager) Deploy added in v0.2.4 

func (m *ActiveStrategyManager) Deploy(ctx context.Context, strategy *mutation.Strategy) error

Deploy stores the given strategy as the active strategy and saves the previous active strategy (if any) for potential rollback. The strategy is persisted via the StrategyStore.

Args:

  • ctx: operation context for cancellation.
  • strategy: the strategy to deploy (must not be nil).

Returns:

  • error: non-nil if strategy is nil or store operation fails.

func (*ActiveStrategyManager) Previous added in v0.2.4 

func (m *ActiveStrategyManager) Previous() *mutation.Strategy

Previous returns the previously active strategy (cloned).

Returns:

  • *mutation.Strategy: clone of the previous strategy, or nil if none.

func (*ActiveStrategyManager) RecordScore added in v0.2.4 

func (m *ActiveStrategyManager) RecordScore(generation int, score float64)

RecordScore records a score snapshot in the rollback policy for degradation trend analysis.

Args:

  • generation: the generation number.
  • score: the observed score.

func (*ActiveStrategyManager) Rollback added in v0.2.4 

func (m *ActiveStrategyManager) Rollback(ctx context.Context) (*mutation.Strategy, error)

Rollback restores the previous strategy as the active one. Returns the rolled-back strategy. If no previous strategy exists, returns an error.

Args:

  • ctx: operation context for cancellation.

Returns:

  • *mutation.Strategy: the restored previous strategy.
  • error: non-nil if no previous strategy exists or store operation fails.

func (*ActiveStrategyManager) RollbackPolicy added in v0.2.4 

func (m *ActiveStrategyManager) RollbackPolicy() *RollbackPolicy

RollbackPolicy returns the underlying rollback policy for score recording and evaluation. The returned policy shares the same state.

Returns:

  • *RollbackPolicy: the rollback policy instance.

type AdapterRunner 

type AdapterRunner interface {
	// Run starts the adapter's event consumption loop.
	Run(ctx context.Context) error
}

AdapterRunner defines the interface for running an evolution adapter. This allows the scheduler to work with any adapter implementation.

type BatchScorer added in v0.2.5 

type BatchScorer func(ctx context.Context, strategies []*mutation.Strategy) []float64

BatchScorer scores multiple internal strategies in a single call. Used to reduce LLM API calls by batching strategies together. The returned slice length must match the input slice length.

type CallbackData 

type CallbackData struct {
	// AgentID is the identifier of the agent that triggered the event.
	AgentID string
}

CallbackData holds data passed to callback handlers during evolution triggers.

type DependencyConfig added in v0.2.4 

type DependencyConfig struct {
	StrategyStore        StrategyStore                         `json:"-"`
	Guardrails           *EvolutionGuardrails                  `json:"-"`
	Metrics              *ares_observability.PrometheusMetrics `json:"-"`
	FeedbackService      *aresExperience.FeedbackService       `json:"-"`
	HintProvider         mutation.HintProvider                 `json:"-"`
	RollbackPolicyConfig RollbackPolicyConfig                  `json:"rollback_policy,omitempty"`
	ShadowEvalConfig     ShadowEvaluationConfig                `json:"shadow_eval_config,omitempty"`
}

DependencyConfig groups externally injected dependencies.

type DiagnosticRecord 

type DiagnosticRecord struct {
	// ID is the unique identifier of the diagnostic record.
	ID string

	// AgentID is the identifier of the agent that generated this record.
	AgentID string

	// TaskID is the identifier of the task associated with this record.
	TaskID string

	// Category classifies the type of issue (e.g., "tool_timeout", "llm_error").
	Category string

	// RootCause describes the underlying cause of the issue.
	RootCause string

	// Suggestion provides a recommended fix or workaround.
	Suggestion string

	// Severity indicates how severe the issue is (1-10, higher is more severe).
	Severity int
}

DiagnosticRecord represents a single diagnostic entry from the flight recorder.

type DiagnosticsAccessor 

type DiagnosticsAccessor interface {
	// Get retrieves the diagnostic report for a specific agent.
	// Returns nil if no diagnostics exist for the agent.
	Get(agentID string) *DiagnosticsReport
}

DiagnosticsAccessor provides read access to diagnostic results.

type DiagnosticsReport 

type DiagnosticsReport struct {
	// AgentID is the identifier of the agent this report covers.
	AgentID string

	// Records contains individual diagnostic records.
	Records []DiagnosticRecord

	// HasIssues indicates whether any problematic diagnostics were found.
	HasIssues bool
}

DiagnosticsReport represents aggregated diagnostic data for an agent.

type DreamCycle 

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

DreamCycle orchestrates the full autonomous evolution loop. It connects: Callback trigger -> Flight->Exp Adapter -> Scheduler -> Mutator -> Arena Regression -> Genealogy recording. In GA mode, it uses genome.Population for full genetic algorithm cycles.

func NewDreamCycle 

func NewDreamCycle(
	scheduler *EvolutionScheduler,
	mutator MutatorInterface,
	tester TesterInterface,
	genealogy GenealogyRecorder,
	opts ...DreamCycleOption,
) (*DreamCycle, error)

NewDreamCycle creates a new dream cycle orchestrator with required dependencies.

All dependencies must be non-nil except genealogy which is optional (lineage recording will be skipped if nil).

When EvolutionMode is ModeGeneticAlgorithm, a genome.Population is initialized automatically from the GA configuration fields in DreamCycleConfig.

Args: 

scheduler - the evolution scheduler that triggers this cycle.
mutator - the strategy mutator for generating candidate variants.
tester - the arena regression tester for evaluating candidates.
genealogy - optional recorder for strategy lineage (may be nil).
opts - optional configuration functions.

Returns: 

*DreamCycle - the configured dream cycle instance.
error - non-nil if required dependencies are missing or GA initialization fails.

func (*DreamCycle) IsEnabled 

func (dc *DreamCycle) IsEnabled() bool

IsEnabled returns whether the dream cycle is currently enabled. Thread-safe: uses mutex to protect concurrent access to config.Enabled.

Returns: 

bool - true if enabled, false otherwise.

func (*DreamCycle) Run 

func (dc *DreamCycle) Run(ctx context.Context, data CallbackData) error

Run executes one full dream cycle when triggered by the scheduler.

In ES mode (default): mutate parent → test candidates → deploy best. In GA mode: score population → evolve (selection/crossover/mutation) → deploy best.

This is the main orchestration method that coordinates all evolution components.

Args: 

ctx - operation context for cancellation and timeout.
data - callback data from the triggering event.

Returns: 

error - non-nil if a critical error occurs during orchestration.

func (*DreamCycle) SetEnabled 

func (dc *DreamCycle) SetEnabled(enabled bool)

SetEnabled enables or disables the dream cycle at runtime. Thread-safe: uses mutex to protect concurrent access to config.Enabled.

Args: 

enabled - true to enable, false to disable.

func (*DreamCycle) TaskCount 

func (dc *DreamCycle) TaskCount() int64

TaskCount returns the number of tasks processed since creation. Thread-safe: uses mutex to protect concurrent access.

Returns: 

int64 - the accumulated task count.

type DreamCycleConfig 

type DreamCycleConfig struct {
	// Enabled is the master switch for dream cycle execution.
	Enabled bool

	// MinTasksBeforeEvolve is the minimum number of completed tasks before first evolution.
	MinTasksBeforeEvolve int

	// MinScoreDrop is the score drop threshold to trigger evolution (e.g., 0.15 = 15% drop).
	MinScoreDrop float64

	// MaxMutations is the maximum number of candidate strategies generated per cycle.
	MaxMutations int

	// MinWinRate is the minimum win rate required to accept a mutation.
	MinWinRate float64

	// Cooldown is the minimum time between consecutive dream cycles.
	Cooldown time.Duration

	// TaskSampleSize is the number of scoring runs per strategy for the final evaluation.
	// Default 50. With adaptive batching, actual calls may be less.
	TaskSampleSize int

	// QuickRejectRuns is the number of runs for the first-pass screening.
	// Candidates below MinWinRate after this many runs are discarded without full eval.
	// Default 5. Set to 0 to skip quick rejection.
	QuickRejectRuns int

	// EvolutionMode selects the evolution algorithm: ModeEvolutionStrategy or ModeGeneticAlgorithm.
	// Default: ModeEvolutionStrategy (backward compatible).
	EvolutionMode EvolutionMode

	// PopulationSize is the number of individuals in the GA population.
	// Default: 20.
	PopulationSize int

	// EliteCount is the number of top individuals preserved each generation.
	// Default: 3.
	EliteCount int

	// MutationRate is the probability of mutating each offspring [0, 1].
	// Default: 0.2.
	MutationRate float64

	// SurvivalRate is the fraction of population that survives each generation [0, 1].
	// Default: 0.6.
	SurvivalRate float64

	// SelectionStrategy selects the parent selection algorithm.
	// Supported: "tournament", "rank", "roulette", "sus", "truncation", "" (random).
	// Default: "tournament".
	SelectionStrategy string

	// TournamentSize is the number of competitors per tournament (only for tournament selection).
	// Default: 3.
	TournamentSize int

	// MaxGenerations is the maximum number of GA generations to run.
	// 0 means unlimited (run until manually stopped).
	MaxGenerations int

	// TargetFitness stops evolution when the best score reaches this threshold.
	// 0 means no target (run until MaxGenerations).
	TargetFitness float64

	// CrossoverType selects the parameter recombination strategy for GA evolution.
	// Supported: "uniform", "two_point", "segment". Default: "uniform".
	CrossoverType string

	// SteadyState enables steady-state GA mode: each generation replaces only
	// a fraction of the population (SteadyStateReplaceRate) instead of full
	// generational replacement. Default: false (full generational GA).
	SteadyState bool

	// SteadyStateReplaceRate is the fraction of the population replaced each
	// generation in steady-state mode [0, 1]. Default: 0.3.
	// Only used when SteadyState is true.
	SteadyStateReplaceRate float64
}

DreamCycleConfig holds configuration for the dream cycle orchestrator.

func DefaultDreamCycleConfig 

func DefaultDreamCycleConfig() DreamCycleConfig

DefaultDreamCycleConfig returns sensible defaults for dream cycle configuration. ES mode is the default for backward compatibility.

type DreamCycleOption 

type DreamCycleOption func(*DreamCycle) error

DreamCycleOption configures a DreamCycle instance.

func WithDreamCycleConfig 

func WithDreamCycleConfig(cfg DreamCycleConfig) DreamCycleOption

WithDreamCycleConfig applies a full DreamCycleConfig to the DreamCycle.

Args: 

cfg - the configuration to apply.

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleGuardrails added in v0.2.4 

func WithDreamCycleGuardrails(guardrails *EvolutionGuardrails) DreamCycleOption

WithDreamCycleGuardrails attaches a guardrail checker to the dream cycle.

Args: 

guardrails - the evolution guardrails instance (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleHintProvider added in v0.2.5 

func WithDreamCycleHintProvider(provider mutation.HintProvider) DreamCycleOption

WithDreamCycleHintProvider attaches a hint provider for recording strategy outcomes after each evolution cycle. The hint provider learns from real execution outcomes and provides better hints for future mutations.

Args: 

provider - the hint provider (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleMetrics added in v0.2.4 

func WithDreamCycleMetrics(metrics MetricsRecorder) DreamCycleOption

WithDreamCycleMetrics attaches a metrics recorder for evolution event counters.

Args: 

metrics - the metrics recorder (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleShadowEvaluator added in v0.2.4 

func WithDreamCycleShadowEvaluator(se *ShadowEvaluator) DreamCycleOption

WithDreamCycleShadowEvaluator attaches a shadow evaluator for safe deployment.

Args: 

se - the shadow evaluator instance (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleStrategyManager added in v0.2.4 

func WithDreamCycleStrategyManager(mgr *ActiveStrategyManager) DreamCycleOption

WithDreamCycleStrategyManager attaches a strategy manager for deployment.

Args: 

mgr - the active strategy manager (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithDreamCycleTester added in v0.2.4 

func WithDreamCycleTester(tester TesterInterface) DreamCycleOption

WithDreamCycleTester attaches a regression tester for candidate evaluation.

Args: 

tester - the arena regression tester (may be nil to disable).

Returns: 

DreamCycleOption - the option function.

func WithStrategyStore 

func WithStrategyStore(store StrategyStore) DreamCycleOption

WithStrategyStore sets the strategy store for persisting evolved strategies.

Args: 

store - the strategy store implementation (may be nil to disable persistence).

Returns: 

DreamCycleOption - the option function.

type EventStoreSubscriber 

type EventStoreSubscriber interface {
	// Subscribe returns a channel that receives ares_events matching the filter.
	// The channel is closed when ctx is cancelled.
	Subscribe(ctx context.Context, filter ares_events.EventFilter) (<-chan *ares_events.Event, error)
}

EventStoreSubscriber defines the subscription interface for event stores.

type EvolutionGuardrails 

type EvolutionGuardrails struct {

	// BaselineScore is the score to beat; strategies below this are regressions.
	BaselineScore float64

	// MaxStagnantGenerations triggers warning after this many gens without improvement.
	MaxStagnantGenerations int

	// MaxLineageShare is the maximum allowed share for a single lineage (0-1, 0=disabled).
	MaxLineageShare float64

	// MaxEvents limits stored events (0=unlimited).
	MaxEvents int
	// contains filtered or unexported fields
}

EvolutionGuardrails runs safety checks before and after each evolution cycle.

func NewEvolutionGuardrails 

func NewEvolutionGuardrails(opts ...GuardrailOption) (*EvolutionGuardrails, error)

NewEvolutionGuardrails creates a new guardrail checker.

Args:

  • opts: configuration options for the guardrail checker

Returns:

  • *EvolutionGuardrails: configured guardrail instance
  • error: always nil (reserved for future validation)

func (*EvolutionGuardrails) Events 

func (g *EvolutionGuardrails) Events() []GuardrailEvent

Events returns all recorded events (copy).

Returns:

  • []GuardrailEvent: copy of all stored events

func (*EvolutionGuardrails) PostEvolveCheck 

func (g *EvolutionGuardrails) PostEvolveCheck(ctx context.Context, newBest float64, generation int, lineageShares map[string]int) *GuardrailResult

PostEvolveCheck runs guardrails AFTER an evolution cycle.

Checks:

  1. Best regression — if new best < BaselineScore, return Critical ("strategy failed to beat baseline")
  2. Improvement tracking — update stagnation counter
  3. Lineage concentration — if top lineage > MaxLineageShare, return Warning

Args:

  • ctx: context for cancellation
  • newBest: new population's best score after evolution
  • generation: generation number
  • lineageShares: map[lineageID]count (can be nil if unavailable)

Returns:

  • *GuardrailResult: result containing any triggered guardrails and stop recommendation

func (*EvolutionGuardrails) PostEvolveCheckForSource added in v0.3.0 

func (g *EvolutionGuardrails) PostEvolveCheckForSource(ctx context.Context, source string, newBest float64, generation int, lineageShares map[string]int) *GuardrailResult

PostEvolveCheckForSource runs guardrails after an evolution cycle for a specific evolution path. The source distinguishes score scales (dream_cycle winRate [0,1] vs genome BestScore), so baseline regression compares against the path's own best instead of a cross-scale value.

func (*EvolutionGuardrails) PreEvolveCheck 

func (g *EvolutionGuardrails) PreEvolveCheck(ctx context.Context, currentBest float64, generation int, totalPop, unevaluatedCount int) *GuardrailResult

PreEvolveCheck runs guardrails BEFORE an evolution cycle.

Checks:

  1. All individuals evaluated guardrail — if >50% of population has Score==-1 (unevaluated), return Critical
  2. Stagnation check — if stagnantCount >= MaxStagnantGenerations, return Warning

Args:

  • ctx: context for cancellation
  • currentBest: current population's best score
  • generation: current generation number
  • totalPop: total population size
  • unevaluatedCount: number of individuals with Score == -1

Returns:

  • *GuardrailResult: result containing any triggered guardrails and stop recommendation

func (*EvolutionGuardrails) RecordEvent 

func (g *EvolutionGuardrails) RecordEvent(event GuardrailEvent)

RecordEvent stores a guardrail event for later review.

Args:

  • event: the guardrail event to record

func (*EvolutionGuardrails) Reset 

func (g *EvolutionGuardrails) Reset()

Reset clears stagnation counters and events.

func (*EvolutionGuardrails) StagnantCount 

func (g *EvolutionGuardrails) StagnantCount() int

StagnantCount returns the current stagnation counter.

Returns:

  • int: number of consecutive generations without improvement

func (*EvolutionGuardrails) ToGuardrailError added in v0.2.4 

func (g *EvolutionGuardrails) ToGuardrailError(event GuardrailEvent) *GuardrailError

ToGuardrailError converts a guardrail event to a machine-readable error for automated retry, alert, downgrade, or rollback decisions.

Returns nil if the event has no error code or if the event's Rule is unrecognized. When non-nil, the returned *GuardrailError implements the error interface and can be used in type-switch or errors.Is logic.

Args:

  • event: the guardrail event to convert

Returns:

  • *GuardrailError: machine-readable error with score and threshold metadata, or nil

type EvolutionHint added in v0.2.4 

type EvolutionHint struct {
	// ID is the unique identifier of this hint.
	ID string

	// TaskType is the type of task this hint applies to.
	TaskType string

	// Problem is the abstract problem statement.
	Problem string

	// Solution is the concise solution approach that worked.
	Solution string

	// Constraints are important constraints or context for the solution.
	Constraints []string

	// FailedPatterns are patterns that led to failure and should be avoided.
	FailedPatterns []string

	// PreferredTools are tool configurations that worked well.
	PreferredTools []string

	// PromptSnippets are prompt text snippets that contributed to success.
	PromptSnippets []string

	// ParamHints maps parameter names to suggested values.
	ParamHints map[string]float64

	// Confidence is the confidence score for this hint (0.0 to 1.0).
	Confidence float64

	// SourceExperienceIDs are the IDs of the experiences that produced this hint.
	SourceExperienceIDs []string
}

EvolutionHint represents a distilled guidance hint derived from past experiences. It captures what worked, what failed, and what parameter biases should be applied during strategy mutation.

func HintFromNormalizedExperience added in v0.2.7 

func HintFromNormalizedExperience(exp experience.NormalizedExperience) EvolutionHint

HintFromNormalizedExperience converts a NormalizedExperience into an EvolutionHint. This is a simpler conversion than HintFromRankedExperience, using the experience's Score directly as the confidence.

func HintFromRankedExperience added in v0.2.4 

func HintFromRankedExperience(ranked *aresExperience.RankedExperience) EvolutionHint

HintFromRankedExperience converts an ares_experience.RankedExperience into an EvolutionHint. Fields that have no direct counterpart in RankedExperience (e.g., FailedPatterns, PreferredTools, PromptSnippets, ParamHints) are left as zero values, since these are populated by more sophisticated providers.

The Confidence is derived from the ranked experience's FinalScore, clamped to [0.0, 1.0]. The SourceExperienceIDs contains the original experience ID.

Returns an empty EvolutionHint (with zero Confidence) if the input is nil or has a nil Experience field.

type EvolutionMode added in v0.2.7 

type EvolutionMode int

EvolutionMode selects the strategy evolution algorithm used by DreamCycle. 

const (
	// ModeEvolutionStrategy uses the current (1+λ) evolution strategy:
	// mutate parent → test candidates → deploy best.
	ModeEvolutionStrategy EvolutionMode = iota

	// ModeGeneticAlgorithm uses the full genetic algorithm pipeline:
	// population → selection → crossover → mutation → score → next generation.
	// Requires genome.Population to be initialized via GA config fields.
	ModeGeneticAlgorithm
)

type EvolutionReport 

type EvolutionReport struct {
	// TotalGenerations is the total number of generations evolved.
	TotalGenerations int `json:"total_generations"`

	// BestEverScore is the highest score seen across all generations.
	BestEverScore float64 `json:"best_ever_score"`

	// BestEverGeneration is the generation where best-ever score appeared.
	BestEverGeneration int `json:"best_ever_generation"`

	// FinalBestScore is the best score in the final generation.
	FinalBestScore float64 `json:"final_best_score"`

	// GenerationTrajectory is per-generation stats in order.
	// When population history is enabled (WithHistoryEnabled), this contains
	// one entry per recorded generation. Otherwise, only the current generation
	// is included.
	GenerationTrajectory []GenerationStats `json:"generation_trajectory"`

	// ScorerCostSummary holds scoring cost information (if tiered scorer used).
	ScorerCostSummary *ScorerCostSummary `json:"scorer_cost_summary,omitempty"`

	// LineageConcentration tracks dominant lineage share (if available).
	LineageConcentration *LineageConcentration `json:"lineage_concentration,omitempty"`

	// WinnerStrategyID is the ID of the best strategy at run completion.
	WinnerStrategyID string `json:"winner_strategy_id,omitempty"`
	// WinnerScore is the final score of the best strategy.
	WinnerScore float64 `json:"winner_score,omitempty"`
	// PromotionState is the state of the winner (candidate/shadow/champion/demoted).
	PromotionState string `json:"promotion_state,omitempty"`
	// PromotionReason explains the promotion decision.
	PromotionReason string `json:"promotion_reason,omitempty"`
	// SuccessRate from evidence aggregation.
	SuccessRate float64 `json:"success_rate,omitempty"`
	// SampleCount from evidence aggregation.
	SampleCount int64 `json:"sample_count,omitempty"`
	// Confidence from evidence aggregation.
	Confidence float64 `json:"confidence,omitempty"`

	// MetaDecisionHistory records meta-controller decisions during the run.
	// Each entry documents a tuning action, its reason, and parameter change.
	MetaDecisionHistory []MetaDecision `json:"meta_decision_history,omitempty"`
}

EvolutionReport is a comprehensive data-driven report for an evolution run.

func GenerateReport 

func GenerateReport(ctx context.Context, system *WiredEvolutionSystem, opts ...ReportOption) (*EvolutionReport, error)

GenerateReport builds a data-driven evolution report from a wired system. It collects real statistics from the population, genealogy, and optionally the scoring infrastructure. Every claim in the report is backed by stored metrics.

Args: 

ctx - operation context.
system - the wired evolution system to report on (must not be nil).
opts - optional report configuration (e.g., WithScoringStats for scorer cost data).

Returns: 

*EvolutionReport - the generated report (never nil if error is nil).
error - non-nil if system is nil.

type EvolutionScheduler 

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

EvolutionScheduler triggers evolution cycles based on agent lifecycle events. It subscribes to the shared EventStore (filtering on EventAgentStopped plus task outcome events) and decides when to run the adapter based on configurable trigger conditions. Task completed/failed events feed the score window via RecordScore, giving TriggerOnThreshold / TriggerOnIdle degradation detection a real production score source.

func NewEvolutionScheduler 

func NewEvolutionScheduler(subscriber EventStoreSubscriber, adapter AdapterRunner, opts ...SchedulerOption) *EvolutionScheduler

NewEvolutionScheduler creates a new scheduler with sensible defaults.

Default configuration:

  • minInterval: 5 minutes
  • trigger: TriggerOnIdle
  • enabled: false (must be explicitly enabled)

Args: 

subscriber - the event store subscriber for listening to agent lifecycle
   events (implements EventStoreSubscriber; typically an ares_events.EventStore).
adapter - the adapter runner to execute on evolution cycles (implements AdapterRunner).
opts - optional configuration functions.

Returns: 

*EvolutionScheduler - the configured scheduler instance.

func (*EvolutionScheduler) DreamCycle 

func (s *EvolutionScheduler) DreamCycle() *DreamCycle

DreamCycle returns the attached dream cycle orchestrator, if any.

Returns: 

*DreamCycle - the dream cycle instance, or nil if not set.

func (*EvolutionScheduler) IsEnabled 

func (s *EvolutionScheduler) IsEnabled() bool

IsEnabled returns whether the scheduler is currently enabled.

Returns: 

bool - true if enabled, false otherwise.

func (*EvolutionScheduler) LastRunTime 

func (s *EvolutionScheduler) LastRunTime() time.Time

LastRunTime returns the timestamp of the last evolution cycle. Thread-safe: uses mutex to protect concurrent access.

Returns: 

time.Time - the last run time, or zero value if never run.

func (*EvolutionScheduler) OnAgentEnd 

func (s *EvolutionScheduler) OnAgentEnd(ctx context.Context, data CallbackData)

OnAgentEnd handles agent completion events as a callback handler. It checks if an evolution cycle should be triggered and runs the adapter if so.

Args: 

ctx - operation context.
data - the callback data containing agent completion information.

func (*EvolutionScheduler) RecordScore 

func (s *EvolutionScheduler) RecordScore(score float64)

RecordScore adds a task score to the sliding window for trend detection. Thread-safe. Keeps only the most recent scoreWindowSize scores.

Args: 

score - the task execution score to record (0-100).

func (*EvolutionScheduler) Register 

func (s *EvolutionScheduler) Register()

Register subscribes the scheduler to the EventStore for agent lifecycle events. It listens for EventAgentStopped (the event that agents actually emit when they finish) so evolution cycles fire on real agent completion. The subscription runs in a managed goroutine until Shutdown cancels its context; the EventStore closes the channel on cancellation.

func (*EvolutionScheduler) SetAdapter added in v0.2.7 

func (s *EvolutionScheduler) SetAdapter(adapter AdapterRunner)

SetAdapter replaces the evolution adapter at runtime. Used by bootstrap to wire the GA population adapter after construction.

Args: 

adapter - the new adapter to use for evolution cycles.

func (*EvolutionScheduler) SetDreamCycle 

func (s *EvolutionScheduler) SetDreamCycle(dc *DreamCycle)

SetDreamCycle attaches a dream cycle orchestrator to the scheduler. When set, the scheduler delegates evolution execution to the dream cycle instead of directly running the adapter.

Args: 

dc - the dream cycle orchestrator (may be nil to detach).

func (*EvolutionScheduler) SetEnabled 

func (s *EvolutionScheduler) SetEnabled(enabled bool)

SetEnabled enables or disables the scheduler at runtime.

Args: 

enabled - true to enable, false to disable.

func (*EvolutionScheduler) ShouldEvolve added in v0.2.4 

func (s *EvolutionScheduler) ShouldEvolve(ctx context.Context, data CallbackData) bool

ShouldEvolve delegates to the internal shouldEvolve logic. This is the exported entry point for DreamCycle to check evolution conditions.

Args: 

ctx - operation context.
data - callback data from the triggering event.

Returns: 

bool - true if evolution should run.

func (*EvolutionScheduler) Shutdown 

func (s *EvolutionScheduler) Shutdown()

Shutdown gracefully stops the scheduler and cancels all pending evolution goroutines and the event subscription loop. It should be called when the scheduler is no longer needed to prevent goroutine leaks.

func (*EvolutionScheduler) TriggerMode added in v0.2.4 

func (s *EvolutionScheduler) TriggerMode() EvolutionTrigger

TriggerMode returns the current trigger mode. Thread-safe: uses mutex to protect concurrent access.

Returns: 

EvolutionTrigger - the current trigger mode.

type EvolutionTrigger 

type EvolutionTrigger int

EvolutionTrigger defines when to trigger evolution cycles. 

const (
	// TriggerOnIdle triggers evolution when the system is idle.
	TriggerOnIdle EvolutionTrigger = iota + 1

	// TriggerOnThreshold triggers evolution when diagnostic count exceeds threshold.
	TriggerOnThreshold

	// TriggerOnDemand triggers evolution only when explicitly requested.
	TriggerOnDemand
)

func (EvolutionTrigger) String 

func (t EvolutionTrigger) String() string

String returns the string representation of EvolutionTrigger.

type Experience 

type Experience struct {
	// TenantID is the tenant identifier for multi-tenancy isolation.
	TenantID string

	// Type is the experience type (e.g., "failure", "solution", "heuristic").
	Type string

	// Problem is the abstract problem statement derived from diagnostics.
	Problem string

	// Solution is the suggested solution approach from diagnostics.
	Solution string

	// Score is the importance score (0-1), inversely related to severity.
	Score float64

	// Source indicates where this experience originated.
	Source string

	// AgentID is the identifier of the agent that generated this experience.
	AgentID string

	// Metadata holds additional structured data.
	Metadata map[string]interface{}
}

Experience represents an extracted experience to be stored.

type ExperienceRepository 

type ExperienceRepository interface {
	// Create persists a new experience entry.
	Create(ctx context.Context, exp *Experience) error
}

ExperienceRepository defines the persistence interface for experiences.

type FeedbackRecorder added in v0.2.4 

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

FeedbackRecorder bridges strategy outcomes to the experience feedback system. It records outcomes both locally and to the external feedback service, enabling experience reinforcement through bandit feedback.

Circuit breaker: when the feedback service returns N consecutive errors, the recorder enters a cool-down period and skips further service calls until the cooldown expires.

When a refine.Refiner is attached (WithRefiner), each Register also applies a small-step Harness proposal updating the strategy's latest score, giving the evolution loop a rollback-capable, baseline-checked feedback trail (primitive 1: small-step evolution).

func NewFeedbackRecorder added in v0.2.4 

func NewFeedbackRecorder(feedbackService *aresExperience.FeedbackService, opts ...FeedbackRecorderOption) *FeedbackRecorder

NewFeedbackRecorder creates a FeedbackRecorder that records strategy outcomes to the given feedback service.

Args: 

feedbackService - the feedback service for experience reinforcement.

Returns: 

*FeedbackRecorder - the configured recorder instance.

func (*FeedbackRecorder) Get added in v0.3.0 

func (r *FeedbackRecorder) Get(_ context.Context, target string) (any, bool)

Get implements refine.Store for strategy score entries ("strategy:<id>").

func (*FeedbackRecorder) Register added in v0.2.4 

func (r *FeedbackRecorder) Register(ctx context.Context, outcome StrategyOutcome) error

Register records a strategy outcome both locally and in the feedback service. For each non-empty experience ID in the outcome:

  • If successful, RecordSuccess increments the usage count.
  • If failed, RecordFailure decrements the rank.

Empty experience IDs are silently skipped. A nil feedback service is also silently skipped, allowing the recorder to operate in offline mode.

Args: 

ctx - operation context for cancellation.
outcome - the strategy outcome to record.

Returns: 

error - delegation error from the feedback service, or nil.

func (*FeedbackRecorder) Set added in v0.3.0 

func (r *FeedbackRecorder) Set(_ context.Context, target string, value any) error

Set implements refine.Store for strategy score entries.

func (*FeedbackRecorder) String added in v0.2.4 

func (r *FeedbackRecorder) String() string

String returns a human-readable summary of recent outcomes.

Returns: 

string - summary showing total outcomes, success rate, and recent results.

type FeedbackRecorderOption added in v0.3.0 

type FeedbackRecorderOption func(*FeedbackRecorder)

FeedbackRecorderOption configures a FeedbackRecorder.

func WithRefiner added in v0.3.0 

func WithRefiner(ref *refine.Refiner) FeedbackRecorderOption

WithRefiner attaches a refine.Refiner so every registered outcome is applied as a baseline-checked, rollback-capable score update. The refiner's store must be this recorder (it implements refine.Store).

type FlightRecorder 

type FlightRecorder interface {
	// Diagnostics returns access to diagnostic reports for agents.
	Diagnostics() DiagnosticsAccessor

	// EventStore returns the event store for subscribing to ares_events.
	EventStore() EventStoreSubscriber
}

FlightRecorder defines the interface for accessing flight recorder diagnostics.

type FlightToExperienceAdapter 

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

FlightToExperienceAdapter converts Flight Recorder diagnostic data into Experience entries. It subscribes to task completion/failure ares_events and generates experiences from diagnostics, but only for tasks that have diagnostic issues (normal executions are not learned from).

func NewFlightToExperienceAdapter 

func NewFlightToExperienceAdapter(flight FlightRecorder, expRepo ExperienceRepository) *FlightToExperienceAdapter

NewFlightToExperienceAdapter creates a new adapter with required dependencies.

Args: 

flight - the flight recorder interface for accessing diagnostics.
expRepo - the experience repository for persisting experiences.

Returns: 

*FlightToExperienceAdapter - the configured adapter instance.

func (*FlightToExperienceAdapter) Run 

func (a *FlightToExperienceAdapter) Run(ctx context.Context) error

Run starts the adapter's event consumption loop. It subscribes to task failure ares_events and generates experiences from diagnostics. The loop runs until ctx is cancelled.

Args: 

ctx - operation context. Cancelling it stops the event consumption loop.

Returns: 

error - any error encountered during subscription or processing.

type FuncGuidanceProvider added in v0.2.7 

type FuncGuidanceProvider struct {
	HintsFunc  func(ctx context.Context, taskType string, limit int) ([]EvolutionHint, error)
	RecordFunc func(ctx context.Context, outcome StrategyOutcome) error
}

FuncGuidanceProvider adapts functions to the GuidanceProvider interface. Useful for injecting simple implementations in bootstrap without creating a full struct type.

func (*FuncGuidanceProvider) HintsForTask added in v0.2.7 

func (p *FuncGuidanceProvider) HintsForTask(ctx context.Context, taskType string, limit int) ([]EvolutionHint, error)

HintsForTask delegates to the wrapped HintsFunc.

func (*FuncGuidanceProvider) RecordStrategyOutcome added in v0.2.7 

func (p *FuncGuidanceProvider) RecordStrategyOutcome(ctx context.Context, outcome StrategyOutcome) error

RecordStrategyOutcome delegates to the wrapped RecordFunc.

type GenealogyRecorder 

type GenealogyRecorder interface {
	// Record persists a strategy lineage entry for future analysis.
	Record(ctx context.Context, lineage StrategyLineage) error
}

GenealogyRecorder abstracts strategy lineage recording capability. Implementations persist strategy evolution history for traceability.

type GenerationStats 

type GenerationStats struct {
	Generation     int            `json:"generation"`
	PopulationSize int            `json:"population_size"`
	BestScore      float64        `json:"best_score"`
	AvgScore       float64        `json:"avg_score"`
	WorstScore     float64        `json:"worst_score"`
	Diversity      float64        `json:"diversity"`      // overall diversity metric
	NumDiverse     int            `json:"num_diverse"`    // count of diverse lineages
	MutationTypes  map[string]int `json:"mutation_types"` // mutation type distribution

	// RecoveryActions records diversity recovery actions taken this generation.
	// Keys are action names (e.g., "mutation_rate_boost", "fresh_injection"),
	// values are counts. Populated from population generation history.
	RecoveryActions map[string]int `json:"recovery_actions,omitempty"`
}

GenerationStats holds per-generation statistics collected during evolution.

type GenomeAdapterOption 

type GenomeAdapterOption func(*GenomePopulationAdapter)

GenomeAdapterOption configures a GenomePopulationAdapter.

func WithActiveStrategyManager added in v0.2.7 

func WithActiveStrategyManager(mgr *ActiveStrategyManager) GenomeAdapterOption

WithActiveStrategyManager attaches an ActiveStrategyManager to the adapter. When set, Run() deploys the current best strategy to the active strategy store after each evolution cycle, enabling the live agent to consume it. Without this, evolved strategies are never persisted for runtime use.

Args: 

mgr - the active strategy manager (must not be nil).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterAdaptiveDistribution added in v0.2.4 

func WithAdapterAdaptiveDistribution(ad *mutation.AdaptiveDistribution) GenomeAdapterOption

WithAdapterAdaptiveDistribution sets the adaptive mutation distribution for outcome-driven probability adjustment. When set, Run() records outcome feedback after each evolution cycle.

Args: 

ad - the adaptive distribution instance (may be nil to disable).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterBatchScoring added in v0.2.5 

func WithAdapterBatchScoring(bs BatchScorer) GenomeAdapterOption

WithAdapterBatchScoring sets a batch scorer that scores all unevaluated strategies in a single call before the tiered scorer runs. This pre-fills the score cache so the tiered scorer finds cache hits during Phase 1 of EvolveAfterScoring, reducing N per-agent LLM calls to ceil(N/batchSize) batched calls.

Requires tieredScorer and scoreCache to be set (via WithAdapterTieredScoring).

Args: 

bs - the batch scorer function.

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterCoordinator added in v0.2.7 

func WithAdapterCoordinator(coord *coordinator.EvolutionCoordinator, diffReg *diff.Registry, genomeReg *evogenome.Registry) GenomeAdapterOption

WithAdapterCoordinator attaches the new system's coordinator bridge to the adapter. When set, Run() generates diff patches from the GA population's evolution results and submits them to the coordinator for decision and deployment.

Args: 

coord - the evolution coordinator to submit patches to.
diffReg - the diff registry for generating patches from genome snapshots.
genomeReg - the genome registry with all registered genomes.

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterFeedbackRecorder added in v0.2.4 

func WithAdapterFeedbackRecorder(fr *FeedbackRecorder) GenomeAdapterOption

WithAdapterFeedbackRecorder sets the feedback recorder for experience reinforcement. When set, Run() records strategy outcomes to the feedback service after each evolution cycle.

Args: 

fr - the feedback recorder instance (may be nil to disable).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterGuardrails 

func WithAdapterGuardrails(g *EvolutionGuardrails) GenomeAdapterOption

WithAdapterGuardrails sets the evolution guardrails for pre/post safety checks. When set, Run() calls PreEvolveCheck before evolution and PostEvolveCheck after. Without this, guardrails are disabled and behavior is unchanged.

Args: 

g - the configured guardrails instance (may be nil to disable).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterMemoryAwareScoring added in v0.2.4 

func WithAdapterMemoryAwareScoring(ms *scoring.MemoryAwareScorer) GenomeAdapterOption

WithAdapterMemoryAwareScoring configures the adapter to wrap the tiered scorer with memory-aware scoring adjustments. The MemoryAwareScorer adds evidence-based bonuses and cost/latency penalties to the fitness score.

This must be used together with WithAdapterTieredScoring. The memory-aware scorer wraps the tiered pipeline, preserving all tiered scoring stats (cache hits, LLM calls, fallbacks) and proper context propagation.

Args: 

ms - the configured memory-aware scorer (must not be nil).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterMetrics added in v0.2.4 

func WithAdapterMetrics(metrics *ares_observability.PrometheusMetrics) GenomeAdapterOption

WithAdapterMetrics sets the metrics recorder for evolution event counters.

Args: 

metrics - the Prometheus metrics instance (may be nil).

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterScorer 

func WithAdapterScorer(scorer func(*mutation.Strategy) float64) GenomeAdapterOption

WithAdapterScorer sets a scoring function that is called after each evolution cycle to assign scores to newly generated offspring (IsScoreEvaluated() == false). Without this, the scheduler path produces unevaluated agents that distort selection and diversity metrics.

Args: 

scorer - function that takes an internal strategy and returns its fitness score.

Returns: 

GenomeAdapterOption - the configuration function.

func WithAdapterTieredScoring 

func WithAdapterTieredScoring(ts *scoring.TieredScorer, budget *scoring.Budget, cache *scoring.ScoreCache) GenomeAdapterOption

WithAdapterTieredScoring configures the adapter to use a TieredScorer pipeline instead of the plain scorer. This enables LLM budget control, score caching, and automatic fallback from LLM to heuristic scoring.

Args: 

ts - the configured tiered scorer (must not be nil).
budget - the budget tracker (must not be nil).
cache - the shared score cache (must not be nil).

Returns: 

GenomeAdapterOption - the configuration function.

type GenomeConfig added in v0.2.4 

type GenomeConfig struct {
	PopulationSize         int     `json:"population_size"`
	EliteCount             int     `json:"elite_count"`
	MutationRate           float64 `json:"mutation_rate"`
	MinMutationRate        float64 `json:"min_mutation_rate,omitempty"`
	MaxMutationRate        float64 `json:"max_mutation_rate,omitempty"`
	SurvivalRate           float64 `json:"survival_rate"`
	PopulationSeed         int64   `json:"population_seed,omitempty"`
	UseDeterministicIDs    bool    `json:"use_deterministic_ids,omitempty"`
	MaxStagnantGenerations int     `json:"max_stagnant_generations"`
	DiversityThreshold     float64 `json:"diversity_threshold"`
	BreedingPoolRatio      float64 `json:"breeding_pool_ratio"`
	HistoryMaxSize         int     `json:"history_max_size"`
	SelectionStrategy      string  `json:"selection_strategy,omitempty"`
}

GenomeConfig groups population-level genetic algorithm settings.

type GenomeMutatorAdapter 

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

GenomeMutatorAdapter wraps a genome.MutatorInterface-compatible mutator to implement genome.MutatorInterface. This enables genome.Population to use both the production mutator and the experience-guided mutator.

func NewGenomeMutatorAdapter 

func NewGenomeMutatorAdapter(m genome.MutatorInterface) (*GenomeMutatorAdapter, error)

NewGenomeMutatorAdapter creates a genome-compatible mutator adapter. The provided mutator must implement the genome.MutatorInterface (both *mutation.Mutator and *mutation.ExperienceGuidedMutator satisfy this).

Args: 

m - the mutator to wrap (must not be nil).

Returns: 

*GenomeMutatorAdapter - the adapter instance.
error - non-nil if mutator is nil.

func (*GenomeMutatorAdapter) Mutate 

func (a *GenomeMutatorAdapter) Mutate(
	ctx context.Context,
	parent *mutation.Strategy,
	n int,
) ([]*mutation.Strategy, error)

Mutate delegates to the wrapped mutator. The signature matches genome.MutatorInterface (uses *mutation.Strategy).

Args: 

ctx - operation context for cancellation.
parent - the parent strategy to mutate.
n - number of children to generate.

Returns: 

[]*mutation.Strategy - the generated child strategies.
error - delegation error from the wrapped mutator.

type GenomePopulationAdapter 

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

GenomePopulationAdapter wraps a genome.Population to implement AdapterRunner. It allows the EvolutionScheduler to trigger genome-based evolution cycles when agents complete tasks.

When a scorer is set, new offspring (IsScoreEvaluated() == false) are automatically scored after each evolution cycle, closing the scoring loop for the scheduler path.

func NewGenomePopulationAdapter 

func NewGenomePopulationAdapter(
	pop *genome.Population,
	mutator genome.MutatorInterface,
	crosser genome.CrossoverInterface,
	opts ...GenomeAdapterOption,
) (*GenomePopulationAdapter, error)

NewGenomePopulationAdapter creates an adapter around a genome population.

Args: 

pop - the managed population (must not be nil).
mutator - the genome-compatible mutator (must not be nil).
crosser - the genome-compatible crossover engine (must not be nil).

Returns: 

*GenomePopulationAdapter - the configured adapter.
error - non-nil if any required dependency is nil.

func (*GenomePopulationAdapter) Population 

func (a *GenomePopulationAdapter) Population() *genome.Population

Population returns the underlying genome population for direct access.

Returns: 

*genome.Population - the managed population.

func (*GenomePopulationAdapter) PopulationSize added in v0.2.4 

func (a *GenomePopulationAdapter) PopulationSize() int

PopulationSize returns the current population size for guardrail checks.

func (*GenomePopulationAdapter) Run 

func (a *GenomePopulationAdapter) Run(ctx context.Context) error

Run executes one atomic genome evolution cycle (EvolveAfterScoring) when triggered by scheduler. The atomic API handles pre-scoring, evolution, and post-scoring in a single call, eliminating the risk of evolving unevaluated agents.

Args: 

ctx - operation context for cancellation.

Returns: 

error - non-nil if evolution fails.

Run executes one atomic genome evolution cycle (EvolveAfterScoring) when triggered by scheduler. The atomic API handles pre-scoring, evolution, and post-scoring in a single call, eliminating the risk of evolving unevaluated agents. After evolution, the best strategy is deployed to the active strategy store (when an ActiveStrategyManager is wired) so the live agent can consume it.

Args: 

ctx - operation context for cancellation.

Returns: 

error - non-nil if evolution fails.

type GuardrailError added in v0.2.4 

type GuardrailError struct {
	Code       GuardrailErrorCode
	Message    string
	Generation int
	Score      float64
	Threshold  float64
}

GuardrailError wraps an error code with metadata for automated handling.

func (*GuardrailError) Error added in v0.2.4 

func (e *GuardrailError) Error() string

Error returns a formatted string describing the guardrail error.

Returns:

  • string: formatted error message including code, message, generation, score, and threshold.

type GuardrailErrorCode added in v0.2.4 

type GuardrailErrorCode string

GuardrailErrorCode is a machine-readable identifier for guardrail events. 

const (
	// ErrCodeUnevaluatedPopulation indicates a majority of the population is unevaluated.
	ErrCodeUnevaluatedPopulation GuardrailErrorCode = "EVAL_UNEVALUATED_POPULATION"
	// ErrCodeStagnation indicates no improvement for too many generations.
	ErrCodeStagnation GuardrailErrorCode = "EVAL_STAGNATION"
	// ErrCodeBaselineRegression indicates the best score regressed below baseline.
	ErrCodeBaselineRegression GuardrailErrorCode = "EVAL_BASELINE_REGRESSION"
	// ErrCodeLineageConcentration indicates a single lineage dominates the population.
	ErrCodeLineageConcentration GuardrailErrorCode = "EVAL_LINEAGE_CONCENTRATION"
	// ErrCodeScoreDecline indicates a significant score decline.
	ErrCodeScoreDecline GuardrailErrorCode = "EVAL_SCORE_DECLINE"
	// ErrCodeDiversityCollapse indicates critically low population diversity.
	ErrCodeDiversityCollapse GuardrailErrorCode = "EVAL_DIVERSITY_COLLAPSE"
)

type GuardrailEvent 

type GuardrailEvent struct {
	// Level is the severity level.
	Level GuardrailLevel
	// Rule is the name of the guardrail rule that triggered.
	Rule string
	// Message describes what happened.
	Message string
	// ErrorCode is the machine-readable error code for automated handling.
	ErrorCode GuardrailErrorCode
	// Score is the relevant score at the time of the event (e.g., best score).
	Score float64
	// Generation when this event occurred.
	Generation int
	// Timestamp when this event occurred.
	Timestamp time.Time
	// SuggestedAction is the recommended remediation.
	SuggestedAction string
}

GuardrailEvent records a guardrail trigger with context.

type GuardrailEventHandler added in v0.2.4 

type GuardrailEventHandler func(event GuardrailEvent)

GuardrailEventHandler is called when a guardrail event fires. Implementations can record metrics, send alerts, or trigger other actions.

type GuardrailLevel 

type GuardrailLevel int

GuardrailLevel indicates the severity of a guardrail trigger. 

const (
	// GuardrailInfo is informational; no action required.
	GuardrailInfo GuardrailLevel = iota + 1
	// GuardrailWarning indicates a concerning condition that should be monitored.
	GuardrailWarning
	// GuardrailCritical requires immediate intervention (e.g., stop evolution).
	GuardrailCritical
)

type GuardrailOption 

type GuardrailOption func(*EvolutionGuardrails)

GuardrailOption configures EvolutionGuardrails.

func WithBaselineScore 

func WithBaselineScore(score float64) GuardrailOption

WithBaselineScore sets the minimum acceptable strategy score.

func WithGuardrailEventHandler added in v0.2.4 

func WithGuardrailEventHandler(handler GuardrailEventHandler) GuardrailOption

WithGuardrailEventHandler sets a callback for guardrail events. The handler is invoked synchronously after each event is recorded.

func WithMaxLineageShare 

func WithMaxLineageShare(share float64) GuardrailOption

WithMaxLineageShare sets the maximum allowed lineage concentration.

func WithMaxStagnantGenerations 

func WithMaxStagnantGenerations(n int) GuardrailOption

WithMaxStagnantGenerations sets the stagnation detection threshold.

type GuardrailResult 

type GuardrailResult struct {
	// ShouldStop indicates evolution should halt immediately.
	ShouldStop bool
	// Events lists all triggered guardrails (may include non-critical ones).
	Events []GuardrailEvent
}

GuardrailResult is the outcome of running all guardrails.

type GuidanceProvider added in v0.2.4 

type GuidanceProvider interface {
	// HintsForTask returns evolution hints relevant to the given task type.
	// The implementation should return up to limit hints, ordered by relevance.
	// Returns empty slice with nil error when no hints are available.
	HintsForTask(ctx context.Context, taskType string, limit int) ([]EvolutionHint, error)

	// RecordStrategyOutcome persists a strategy outcome for future learning.
	RecordStrategyOutcome(ctx context.Context, outcome StrategyOutcome) error
}

GuidanceProvider abstracts the ability to query evolution hints from past experiences and record strategy outcomes. Implementations must not depend on concrete memory repositories, allowing the evolution system to request hints without direct import of storage packages.

type LineageConcentration 

type LineageConcentration struct {
	TopLineageShare float64        `json:"top_lineage_share"`
	TopLineageID    string         `json:"top_lineage_id"`
	LineageCounts   map[string]int `json:"lineage_counts"`
	UniqueLineages  int            `json:"unique_lineages"`
}

LineageConcentration tracks lineage distribution in the population.

type MemoryStrategyStore added in v0.2.7 

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

MemoryStrategyStore is an in-memory implementation of StrategyStore. It requires no external database and is safe for concurrent use, making it suitable for the default deployment where no persistent store is configured.

func NewMemoryStrategyStore added in v0.2.7 

func NewMemoryStrategyStore(maxHistory int) *MemoryStrategyStore

NewMemoryStrategyStore creates an in-memory strategy store. A non-positive maxHistory retains unlimited history.

Args: 

maxHistory - maximum number of historical strategies to retain.

Returns: 

*MemoryStrategyStore - the configured store.

func (*MemoryStrategyStore) GetActive added in v0.2.7 

func (s *MemoryStrategyStore) GetActive(_ context.Context) (*Strategy, error)

GetActive returns the currently deployed strategy. Returns nil (and no error) if no strategy has been stored yet.

func (*MemoryStrategyStore) GetHistory added in v0.2.7 

func (s *MemoryStrategyStore) GetHistory(_ context.Context, id string, n int) ([]*Strategy, error)

GetHistory returns the last n strategies for the given strategy ID, ordered by version descending (newest first).

Args: 

ctx - operation context for cancellation.
id - the strategy identifier to filter by.
n - maximum number of entries to return (0 = all matched).

Returns: 

[]*Strategy - matched history entries, newest first.
error - always nil for this in-memory implementation.

func (*MemoryStrategyStore) SetActive added in v0.2.7 

func (s *MemoryStrategyStore) SetActive(ctx context.Context, strategy *Strategy) error

SetActive persists a strategy as the active deployment.

Args: 

ctx - operation context for cancellation.
strategy - the strategy to persist (must not be nil).

Returns: 

error - non-nil if strategy is nil.

type MetaDecision added in v0.2.5 

type MetaDecision struct {
	// Generation when the decision was made.
	Generation int `json:"generation"`
	// Action describes what was changed (e.g., "mutation_rate", "selection_strategy").
	Action string `json:"action"`
	// Reason explains why the change was made.
	Reason string `json:"reason"`
	// OldValue is the parameter value before the change.
	OldValue string `json:"old_value"`
	// NewValue is the parameter value after the change.
	NewValue string `json:"new_value"`
}

MetaDecision records a single meta-controller decision during the evolution run.

type MetricsRecorder added in v0.2.4 

type MetricsRecorder interface {
	RecordEvolutionDeploy(status string)
	RecordEvolutionShadow(result string)
	SetEvolutionScore(strategyID string, score float64)
}

MetricsRecorder abstracts Prometheus metrics recording for evolution events. The observability.PrometheusMetrics type satisfies this interface.

type MutationAdapter 

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

MutationAdapter wraps a mutation.Mutator to implement evolution.MutatorInterface. It handles type conversion between evolution.Strategy and mutation.Strategy.

func NewMutationAdapter 

func NewMutationAdapter(m *mutation.Mutator) (*MutationAdapter, error)

NewMutationAdapter creates an adapter from a mutation.Mutator.

Args: 

m - the mutation mutator to wrap (must not be nil).

Returns: 

*MutationAdapter - the adapter instance.
error - non-nil if mutator is nil.

func (*MutationAdapter) Mutate 

func (a *MutationAdapter) Mutate(ctx context.Context, parent Strategy, n int) ([]Strategy, error)

Mutate delegates to the wrapped mutator and converts types. It converts the evolution.Strategy parent to mutation.Strategy before calling the mutator, then converts the resulting []*mutation.Strategy back to []evolution.Strategy.

Args: 

ctx - operation context for cancellation.
parent - the parent strategy in evolution package format.
n - number of candidate strategies to generate.

Returns: 

[]Strategy - the generated child strategies in evolution package format.
error - delegation error from the wrapped mutator or conversion error.

type MutationConfig added in v0.2.4 

type MutationConfig struct {
	MutatorSeed                    int64                               `json:"mutator_seed,omitempty"`
	CrossoverSeed                  int64                               `json:"crossover_seed,omitempty"`
	PromptCrossoverMode            int                                 `json:"prompt_crossover_mode"`
	PromptTemplates                []string                            `json:"prompt_templates,omitempty"`
	EnableExperienceGuidedMutation bool                                `json:"enable_experience_guided_mutation,omitempty"`
	GuidanceProvider               GuidanceProvider                    `json:"-"`
	AdaptiveDistConfig             mutation.AdaptiveDistributionConfig `json:"adaptive_distribution,omitempty"`
}

MutationConfig groups mutation and crossover settings.

type MutatorInterface 

type MutatorInterface interface {
	// Mutate generates n candidate strategies from the given parent strategy.
	Mutate(ctx context.Context, parent Strategy, n int) ([]Strategy, error)
}

MutatorInterface abstracts strategy mutation capability. Implementations generate candidate strategies by applying mutations to a parent strategy.

type PGStrategyStore added in v0.2.4 

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

PGStrategyStore is a PostgreSQL-backed implementation of StrategyStore. It persists strategies to a database table, enabling cross-restart continuity of the evolution system's deployed strategies. When no DB is configured, the in-memory MemoryStrategyStore is used instead.

func NewPGStrategyStore added in v0.2.4 

func NewPGStrategyStore(db *sql.DB, tableName string, maxHistory int) (*PGStrategyStore, error)

NewPGStrategyStore creates a PostgreSQL-backed strategy store. The table is created automatically if it does not exist.

Args: 

db         - active database connection pool.
tableName  - name of the table to store strategies in.
maxHistory - maximum history entries per strategy (0 = unlimited).

Returns: 

*PGStrategyStore - the configured store.
error - non-nil if table creation fails.

func (*PGStrategyStore) GetActive added in v0.2.4 

func (s *PGStrategyStore) GetActive(ctx context.Context) (*Strategy, error)

GetActive returns the currently deployed strategy. Returns nil (and no error) if no strategy has been stored yet.

func (*PGStrategyStore) GetHistory added in v0.2.4 

func (s *PGStrategyStore) GetHistory(ctx context.Context, id string, n int) ([]*Strategy, error)

GetHistory returns the last n strategies for the given strategy ID, ordered by version descending (newest first).

func (*PGStrategyStore) SetActive added in v0.2.4 

func (s *PGStrategyStore) SetActive(ctx context.Context, strategy *Strategy) error

SetActive persists a strategy as the active deployment. Marks all existing active strategies as inactive first, then inserts the new one.

type PopulationGenealogyRecorder 

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

PopulationGenealogyRecorder records strategy lineage from genome evolution into the evolution package's genealogy system. It implements GenealogyRecorder by extracting lineage data from population state after each evolution cycle.

func NewPopulationGenealogyRecorder 

func NewPopulationGenealogyRecorder() *PopulationGenealogyRecorder

NewPopulationGenealogyRecorder creates a new genealogy recorder.

Returns: 

*PopulationGenealogyRecorder - the recorder instance.

func (*PopulationGenealogyRecorder) Count 

func (r *PopulationGenealogyRecorder) Count() int

Count returns the number of recorded lineage entries.

Returns: 

int - number of lineages.

func (*PopulationGenealogyRecorder) Lineages 

func (r *PopulationGenealogyRecorder) Lineages() []StrategyLineage

Lineages returns all recorded lineage entries (thread-safe).

Returns: 

[]StrategyLineage - copy of recorded lineages.

func (*PopulationGenealogyRecorder) Record 

func (r *PopulationGenealogyRecorder) Record(ctx context.Context, lineage StrategyLineage) error

Record persists a strategy lineage entry from genome evolution results. It extracts parent-child relationships from evolved population agents.

Args: 

ctx - operation context.
lineage - the lineage record to persist.

Returns: 

error - always nil for in-memory implementation.

func (*PopulationGenealogyRecorder) RecordScore added in v0.2.7 

func (r *PopulationGenealogyRecorder) RecordScore(agentID string, score float64)

RecordScore adds an agent's score to its rolling window for noise-robust improvement computation. The window retains the most recent scores.

func (*PopulationGenealogyRecorder) RollingMeanScore added in v0.2.7 

func (r *PopulationGenealogyRecorder) RollingMeanScore(agentID string) float64

RollingMeanScore returns the rolling mean of the last N scores for an agent. Returns 0 if no history exists for the given agent ID.

type RegressionConfig 

type RegressionConfig struct {
	// Candidate is the strategy variant to test against the baseline.
	Candidate Strategy

	// Baseline is the current active strategy used as comparison reference.
	Baseline Strategy

	// TaskSampleSize is the number of historical tasks to replay for testing.
	TaskSampleSize int

	// AdaptiveBatchSize enables batched scoring with early stopping.
	// When > 0, scores are collected in batches of this size and significance
	// is checked after each batch. Stops early if the outcome is already clear.
	AdaptiveBatchSize int
}

RegressionConfig holds configuration for arena regression testing.

type RegressionResult 

type RegressionResult struct {
	// CandidateScore is the average score achieved by the candidate strategy.
	CandidateScore float64

	// BaselineScore is the average score achieved by the baseline strategy.
	BaselineScore float64

	// WinRate is the proportion of tasks where candidate outperformed baseline (0-1).
	WinRate float64

	// TotalTasks is the total number of tasks used in the regression test.
	TotalTasks int
}

RegressionResult holds the outcome of an arena regression test.

type RegressionTester added in v0.2.4 

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

RegressionTester implements TesterInterface by scoring candidate and baseline strategies using a provided scorer function.

func NewRegressionTester added in v0.2.4 

func NewRegressionTester(scorer func(*mutation.Strategy) float64) (*RegressionTester, error)

NewRegressionTester creates a regression tester for arena strategy comparison.

Args: 

scorer - scoring function for strategy evaluation (must not be nil).

Returns: 

*RegressionTester - the configured tester.
error - non-nil if scorer is nil.

func (*RegressionTester) Run added in v0.2.4 

func (t *RegressionTester) Run(ctx context.Context, cfg RegressionConfig) (*RegressionResult, error)

Run executes a regression test comparing a candidate strategy against a baseline. With TaskSampleSize > 1, it runs multiple trials with slight score perturbation to produce a meaningful win rate.

Args: 

ctx - operation context for cancellation.
cfg - regression test configuration.

Returns: 

*RegressionResult - evaluation result with win rate and scores.
error - non-nil if scoring fails.

type ReportOption 

type ReportOption func(*reportConfig)

ReportOption configures GenerateReport behavior.

func WithScoringStats 

func WithScoringStats(stats map[string]int64, budgetUsage ...int) ReportOption

WithScoringStats injects scorer cost data into the report.

Args: 

stats - tiered scorer Stats() output (map[string]int64).
budgetUsage - budget.Usage() output as variadic: used, max, cacheHits, fallbacks.

Returns: 

ReportOption - the configuration function.

type RollbackDecision added in v0.2.4 

type RollbackDecision struct {
	// ShouldRollback indicates whether a rollback is recommended.
	ShouldRollback bool
	// Reason is the human-readable explanation for the decision.
	Reason string
	// CurrentScore is the most recent score observed.
	CurrentScore float64
	// ReferenceScore is the score used as the baseline for comparison.
	ReferenceScore float64
	// Degradation is the absolute difference between reference and current scores.
	Degradation float64
	// Threshold is the maximum allowed degradation before rollback triggers.
	Threshold float64
	// RecommendedAction describes what action to take.
	RecommendedAction string
}

RollbackDecision describes the outcome of a rollback evaluation.

type RollbackOption added in v0.2.4 

type RollbackOption func(*RollbackPolicy)

RollbackOption configures a RollbackPolicy instance.

func WithDegradationThreshold added in v0.2.4 

func WithDegradationThreshold(threshold float64) RollbackOption

WithDegradationThreshold sets the maximum allowed score degradation before rollback is triggered (default 0.15).

Args:

  • threshold: the degradation threshold (must be >= 0).

Returns:

  • RollbackOption: the configuration function.

func WithMinRollbackSamples added in v0.2.4 

func WithMinRollbackSamples(n int) RollbackOption

WithMinRollbackSamples sets the minimum number of score samples required before a rollback evaluation can trigger (default 3).

Args:

  • n: the minimum sample count (must be >= 1).

Returns:

  • RollbackOption: the configuration function.

func WithRollbackWindowSize added in v0.2.4 

func WithRollbackWindowSize(size int) RollbackOption

WithRollbackWindowSize sets the number of recent generations to consider for trend analysis (default 5).

Args:

  • size: the window size (must be >= 2).

Returns:

  • RollbackOption: the configuration function.

type RollbackPolicy added in v0.2.4 

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

RollbackPolicy evaluates score trends and recommends rollback when degradation exceeds a configurable threshold. It detects both gradual decline (over a sliding window) and sudden drops below baseline.

func NewRollbackPolicy added in v0.2.4 

func NewRollbackPolicy(opts ...RollbackOption) *RollbackPolicy

NewRollbackPolicy creates a new rollback policy with default settings.

Default configuration:

  • degradationThreshold: 0.15
  • windowSize: 5
  • minSamples: 3

Args:

  • opts: optional configuration functions.

Returns:

  • *RollbackPolicy: the configured rollback policy.

func (*RollbackPolicy) Evaluate added in v0.2.4 

func (p *RollbackPolicy) Evaluate() *RollbackDecision

Evaluate checks whether rollback is needed based on:

  • Gradual degradation: score consistently declining over the window.
  • Sudden drop: current score below baseline minus threshold.

Returns a RollbackDecision with a clear recommendation. Returns a no-rollback decision with explanation when insufficient samples are available or when the score history is empty.

Returns:

  • *RollbackDecision: the evaluation result (never nil).

func (*RollbackPolicy) RecordScore added in v0.2.4 

func (p *RollbackPolicy) RecordScore(generation int, score float64)

RecordScore records a score snapshot for a given generation and appends it to the sliding window history.

Args:

  • generation: the generation number when the score was observed.
  • score: the observed score value.

func (*RollbackPolicy) Reset added in v0.2.4 

func (p *RollbackPolicy) Reset()

Reset clears all recorded score history.

func (*RollbackPolicy) ScoreHistory added in v0.2.4 

func (p *RollbackPolicy) ScoreHistory() []ScoreSnapshot

ScoreHistory returns a copy of all recorded score snapshots.

Returns:

  • []ScoreSnapshot: a copy of the score history (never nil).

type RollbackPolicyConfig added in v0.2.4 

type RollbackPolicyConfig struct {
	// Enabled enables the rollback policy when true.
	Enabled bool `json:"enabled"`
	// DegradationThreshold is the max allowed score drop before rollback (default 0.15).
	DegradationThreshold float64 `json:"degradation_threshold"`
	// WindowSize is the number of generations to consider for trend (default 5).
	WindowSize int `json:"window_size"`
	// MinSamples is the minimum samples before rollback triggers (default 3).
	MinSamples int `json:"min_samples"`
}

RollbackPolicyConfig holds configuration for creating a RollbackPolicy within the wired evolution system.

type SchedulerConfig added in v0.2.4 

type SchedulerConfig struct {
	EnableScheduler      bool                 `json:"enable_scheduler"`
	EnableDreamCycle     bool                 `json:"enable_dream_cycle"`
	SchedulerTrigger     EvolutionTrigger     `json:"scheduler_trigger"`
	MinTasksBeforeEvolve int                  `json:"min_tasks_before_evolve"`
	MaxMutations         int                  `json:"max_mutations"`
	EventStore           EventStoreSubscriber `json:"-"`
}

SchedulerConfig groups scheduler and dream cycle settings.

type SchedulerOption 

type SchedulerOption func(*EvolutionScheduler)

SchedulerOption configures the EvolutionScheduler.

func WithEnabled 

func WithEnabled(enabled bool) SchedulerOption

WithEnabled sets whether the scheduler is enabled.

Args: 

enabled - true to enable, false to disable.

Returns: 

SchedulerOption - the option function.

func WithMinInterval 

func WithMinInterval(d time.Duration) SchedulerOption

WithMinInterval sets the minimum interval between evolution cycles.

Args: 

d - the minimum duration between cycles.

Returns: 

SchedulerOption - the option function.

func WithSchedulerGuardrails added in v0.2.4 

func WithSchedulerGuardrails(guardrails *EvolutionGuardrails) SchedulerOption

WithSchedulerGuardrails attaches guardrails to the scheduler for pre-evolution checks.

Args: 

guardrails - the evolution guardrails instance (may be nil to disable).

Returns: 

SchedulerOption - the option function.

func WithTrigger 

func WithTrigger(trigger EvolutionTrigger) SchedulerOption

WithTrigger sets the evolution trigger mode.

Args: 

trigger - the trigger mode to use.

Returns: 

SchedulerOption - the option function.

type ScoreRollingWindow added in v0.2.7 

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

ScoreRollingWindow maintains a sliding window of recent scores for an agent. It provides a rolling mean that smooths out noise in fitness evaluations.

func (*ScoreRollingWindow) Add added in v0.2.7 

func (w *ScoreRollingWindow) Add(score float64)

Add appends a score and evicts the oldest if at capacity.

func (*ScoreRollingWindow) Mean added in v0.2.7 

func (w *ScoreRollingWindow) Mean() float64

Mean returns the rolling average of all scores in the window. Returns 0 if the window is empty.

type ScoreSnapshot added in v0.2.4 

type ScoreSnapshot struct {
	// Generation is the generation number when this score was recorded.
	Generation int
	// Score is the observed score value.
	Score float64
	// Timestamp is when this snapshot was recorded.
	Timestamp time.Time
}

ScoreSnapshot captures a score observation at a given generation for degradation trend analysis.

type ScorerCostSummary 

type ScorerCostSummary struct {
	TotalLLMCalls  int `json:"total_llm_calls"`
	TotalCacheHits int `json:"total_cache_hits"`
	TotalFallbacks int `json:"total_fallbacks"`
	LLMBudgetUsed  int `json:"llm_budget_used"`
	LLMBudgetMax   int `json:"llm_budget_max"`
}

ScorerCostSummary summarizes scorer resource usage.

type ScoringConfig added in v0.2.4 

type ScoringConfig struct {
	Scorer                   genome.ScorerFunc                `json:"-"`
	HeuristicScorer          genome.ScorerFunc                `json:"-"`
	BatchScorer              BatchScorer                      `json:"-"`
	MaxLLMCallsPerGeneration int                              `json:"max_llm_calls_per_generation,omitempty"`
	ScoreCacheSize           int                              `json:"score_cache_size,omitempty"`
	MemoryAwareScoringConfig scoring.MemoryAwareScoringConfig `json:"memory_aware_scoring,omitempty"`
	MemoryExperienceProvider scoring.ExperienceProvider       `json:"-"`
}

ScoringConfig groups scorer pipeline settings.

type ShadowComparison added in v0.2.4 

type ShadowComparison struct {
	// ActiveScore is the score achieved by the active (current) strategy.
	ActiveScore float64

	// ShadowScore is the score achieved by the shadow (candidate) strategy.
	ShadowScore float64

	// ShadowWon indicates whether the shadow strategy outperformed the active one.
	ShadowWon bool

	// Timestamp records when this comparison was made.
	Timestamp time.Time
}

ShadowComparison records the result of comparing active vs shadow strategy performance on a single evaluation.

type ShadowEvaluationConfig added in v0.2.4 

type ShadowEvaluationConfig struct {
	// Enabled enables shadow evaluation when true.
	Enabled bool `json:"enabled"`

	// MinSamples is the minimum number of comparison samples required before
	// making a deployment decision. Default is 10.
	MinSamples int `json:"min_samples"`

	// MinWinRate is the minimum win rate required for the shadow strategy to
	// be recommended for deployment. Default is 0.55.
	MinWinRate float64 `json:"min_win_rate"`

	// EvaluationInterval is the time between evaluation rounds.
	EvaluationInterval time.Duration `json:"evaluation_interval"`
}

ShadowEvaluationConfig configures the shadow evaluation behavior for safe strategy deployment.

func DefaultShadowEvaluationConfig added in v0.2.4 

func DefaultShadowEvaluationConfig() ShadowEvaluationConfig

DefaultShadowEvaluationConfig returns sensible defaults for shadow evaluation.

Returns: 

ShadowEvaluationConfig - configuration with default values.

type ShadowEvaluator added in v0.2.4 

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

ShadowEvaluator enables safe deployment comparison by running the active and a candidate strategy side by side, collecting comparison results, and recommending deployment only when the candidate demonstrates sufficient improvement.

func NewShadowEvaluator added in v0.2.4 

func NewShadowEvaluator(cfg ShadowEvaluationConfig) *ShadowEvaluator

NewShadowEvaluator creates a ShadowEvaluator for safe strategy comparison.

Args: 

cfg - configuration for shadow evaluation behavior.

Returns: 

*ShadowEvaluator - the configured evaluator instance.

func (*ShadowEvaluator) ActiveStrategy added in v0.2.4 

func (e *ShadowEvaluator) ActiveStrategy() *mutation.Strategy

ActiveStrategy returns the active strategy.

Returns: 

*mutation.Strategy - the active strategy, or nil if not set.

func (*ShadowEvaluator) Evaluate added in v0.2.4 

func (e *ShadowEvaluator) Evaluate(ctx context.Context) (float64, float64)

Evaluate scores both active and shadow strategies using the independent scorer (if set) and records the comparison result. Returns the active and shadow scores. If no scorer is set, returns (-1, -1) without recording.

Args:

  • ctx: operation context for cancellation.

Returns:

  • activeScore: the score from the active strategy.
  • shadowScore: the score from the shadow strategy.

func (*ShadowEvaluator) HasIndependentScorer added in v0.2.4 

func (e *ShadowEvaluator) HasIndependentScorer() bool

HasIndependentScorer returns true if an independent scorer is configured. When true, Evaluate() can be used instead of manual RecordResult() calls.

Returns: 

bool - true if an independent scorer is set.

func (*ShadowEvaluator) RecordResult added in v0.2.4 

func (e *ShadowEvaluator) RecordResult(activeScore, shadowScore float64)

RecordResult records a comparison result between the active and shadow strategies.

Args: 

activeScore - the score from the active strategy.
shadowScore - the score from the shadow strategy.

func (*ShadowEvaluator) Reset added in v0.2.4 

func (e *ShadowEvaluator) Reset()

Reset clears all evaluation state.

func (*ShadowEvaluator) Results added in v0.2.4 

func (e *ShadowEvaluator) Results() []ShadowComparison

Results returns a copy of all recorded comparison results.

Returns: 

[]ShadowComparison - copy of all recorded comparisons.

func (*ShadowEvaluator) SetActiveStrategy added in v0.2.4 

func (e *ShadowEvaluator) SetActiveStrategy(s *mutation.Strategy)

SetActiveStrategy sets the active strategy for comparison.

Args: 

s - the active strategy.

func (*ShadowEvaluator) SetShadowScorer added in v0.2.4 

func (e *ShadowEvaluator) SetShadowScorer(scorer func(context.Context, *mutation.Strategy) float64)

SetShadowScorer sets an independent scoring function for shadow evaluation. When set, Evaluate() uses this scorer to compare active vs shadow strategies independently of the caller-provided scores. The scorer receives a context for cancellation and tracing.

Args:

  • scorer: scoring function (use nil to clear). Signature: func(ctx, *Strategy) float64.

func (*ShadowEvaluator) ShadowStrategy added in v0.2.4 

func (e *ShadowEvaluator) ShadowStrategy() *mutation.Strategy

ShadowStrategy returns the shadow (candidate) strategy.

Returns: 

*mutation.Strategy - the shadow strategy, or nil if not set.

func (*ShadowEvaluator) ShouldDeploy added in v0.2.4 

func (e *ShadowEvaluator) ShouldDeploy() (bool, *ShadowReport)

ShouldDeploy determines whether the shadow strategy should be deployed based on accumulated comparison results. It uses majority voting with a configurable minimum sample count and win rate threshold.

Returns: 

bool - true if the shadow strategy should be deployed.
*ShadowReport - detailed report of the evaluation, or nil if no results exist.

func (*ShadowEvaluator) StartShadow added in v0.2.4 

func (e *ShadowEvaluator) StartShadow(candidate *mutation.Strategy)

StartShadow begins shadow evaluation of a candidate strategy. The active strategy should be set before calling this.

Args: 

candidate - the candidate strategy to evaluate.

type ShadowReport added in v0.2.4 

type ShadowReport struct {
	// TotalComparisons is the number of comparison results collected.
	TotalComparisons int

	// ShadowWins is the count of comparisons where the shadow strategy won.
	ShadowWins int

	// WinRate is the proportion of comparisons won by the shadow strategy.
	WinRate float64

	// Recommendation describes the suggested action based on evaluation results.
	Recommendation string
}

ShadowReport summarizes shadow evaluation results and provides a deployment recommendation.

type Strategy 

type Strategy struct {
	// ID is the unique identifier of this strategy.
	ID string `json:"id"`

	// Name is the human-readable name of the strategy.
	Name string `json:"name,omitempty"`

	// Version is the version number of this strategy (monotonically increasing).
	Version int `json:"version"`

	// Params holds the configurable parameters of the strategy.
	Params map[string]any `json:"params,omitempty"`

	// ParentID references the parent strategy this was evolved from (empty for root strategies).
	ParentID string `json:"parent_id,omitempty"`

	// PromptTemplate is the behavior prompt template for the agent.
	PromptTemplate string `json:"prompt_template,omitempty"`

	// StrategyMutationType records the mutation type that created this strategy.
	StrategyMutationType string `json:"strategy_mutation_type"`

	// MutationDesc is a human-readable description of the mutation applied.
	MutationDesc string `json:"mutation_desc,omitempty"`

	// Score is the current evaluation score (-1 = unevaluated).
	Score float64 `json:"score"`

	// CreatedAt is the timestamp when this strategy was created.
	CreatedAt time.Time `json:"created_at"`
}

Strategy represents an agent decision strategy that can be mutated and evolved.

type StrategyLineage 

type StrategyLineage struct {
	// ParentID is the ID of the parent (source) strategy.
	ParentID string `json:"parent_id"`

	// ChildID is the ID of the new (mutated) strategy.
	ChildID string `json:"child_id"`

	// MutationType describes what kind of mutation was applied.
	MutationType string `json:"mutation_type"`

	// WinRate achieved by the child strategy in arena testing.
	WinRate float64 `json:"win_rate"`

	// ScoreImprovement is the delta between child and parent scores.
	ScoreImprovement float64 `json:"score_improvement"`

	// ParentScore is the evaluated score of the parent strategy.
	ParentScore float64 `json:"parent_score"`

	// ChildScore is the evaluated score of the child strategy.
	ChildScore float64 `json:"child_score"`

	// ImprovementSignificant indicates whether the score improvement
	// meets the configured significance threshold (MinLineageImprovement).
	ImprovementSignificant bool `json:"improvement_significant"`

	// Timestamp when this lineage record was created.
	Timestamp int64 `json:"timestamp"`
}

StrategyLineage records the genealogical relationship between strategies.

type StrategyOutcome added in v0.2.4 

type StrategyOutcome struct {
	// StrategyID is the ID of the strategy that was deployed.
	StrategyID string

	// TaskType is the type of task this strategy was used for.
	TaskType string

	// Success indicates whether the strategy deployment was successful.
	Success bool

	// Score is the fitness score achieved by this strategy.
	Score float64

	// Cost is the computational cost incurred.
	Cost float64

	// LatencyMs is the execution latency in milliseconds.
	LatencyMs int64

	// MutationType describes what kind of mutation produced this strategy.
	MutationType string

	// ExperienceIDs are the IDs of experiences that influenced this strategy.
	ExperienceIDs []string

	// Timestamp is when this outcome was recorded.
	Timestamp time.Time
}

StrategyOutcome records the result of deploying a strategy mutation, enabling the experience provider to learn from real execution outcomes.

type StrategyStore 

type StrategyStore interface {
	// GetActive returns the currently deployed strategy.
	// Returns nil if no strategy has been stored yet.
	GetActive(ctx context.Context) (*Strategy, error)

	// SetActive persists a strategy as the active deployment.
	SetActive(ctx context.Context, strategy *Strategy) error

	// GetHistory returns the last n strategies for the given strategy ID,
	// ordered by version descending.
	GetHistory(ctx context.Context, id string, n int) ([]*Strategy, error)
}

StrategyStore abstracts persistent strategy storage. Implementations load and save strategies across system restarts.

type SystemConfig 

type SystemConfig struct {
	GenomeConfig
	ScoringConfig
	MutationConfig
	SchedulerConfig
	DependencyConfig
}

SystemConfig holds configuration for creating a wired evolution system. Sub-configs are anonymous-embedded so all fields are accessible directly.

func DefaultSystemConfig 

func DefaultSystemConfig() SystemConfig

DefaultSystemConfig returns sensible defaults.

type TesterInterface 

type TesterInterface interface {
	// Run executes a regression test with the given configuration and returns results.
	Run(ctx context.Context, cfg RegressionConfig) (*RegressionResult, error)
}

TesterInterface abstracts arena regression testing capability. Implementations compare candidate strategies against the current baseline.

type WiredEvolutionSystem 

type WiredEvolutionSystem struct {
	Scheduler             *EvolutionScheduler
	DreamCycle            *DreamCycle
	PopAdapter            *GenomePopulationAdapter
	Population            *genome.Population
	Genealogy             *PopulationGenealogyRecorder
	StrategyStore         StrategyStore
	ActiveStrategyManager *ActiveStrategyManager
	ShadowEvaluator       *ShadowEvaluator
	FeedbackRecorder      *FeedbackRecorder
	AdaptiveDist          *mutation.AdaptiveDistribution
	TieredScorer          *scoring.TieredScorer
	Budget                *scoring.Budget
	ScoreCache            *scoring.ScoreCache
	Metrics               *ares_observability.PrometheusMetrics

	// Intelligence components (Phase 3-5). Set to nil to disable.
	Reflector     *genome.LLMReflector        `json:"-"`
	HypothesisGen *genome.HypothesisGenerator `json:"-"`
	MetaCtrl      *genome.MetaController      `json:"-"`

	// Phase 6: Diff Engine + Coordinator for graph structure evolution.
	// When set, each generation's mutation is diffed and patches submitted.
	DiffReg     *diff.Registry                    `json:"-"`
	Coordinator *coordinator.EvolutionCoordinator `json:"-"`
	GenomeReg   *evogenome.Registry               `json:"-"`

	// AfterGeneration is called after each idle evolution generation with
	// the generation index and the system. When non-nil, it receives the
	// fully evolved state (population already scored, lineage recorded).
	// Can be used for promotion evaluation, report generation, or metrics.
	// Returning an error is non-fatal — the error is logged and evolution
	// continues to the next generation.
	AfterGeneration func(ctx context.Context, gen int, system *WiredEvolutionSystem) error `json:"-"`

	// AfterRun is called once after RunIdleEvolution completes all generations.
	// When non-nil, it receives the final system state after the evolution loop
	// ends. Can be used for final report generation, persistence, or cleanup.
	// Returning an error is non-fatal — the error is logged but not propagated.
	AfterRun func(ctx context.Context, system *WiredEvolutionSystem) error `json:"-"`
}

WiredEvolutionSystem holds a fully wired autonomous evolution system.

func NewWiredEvolutionSystem 

func NewWiredEvolutionSystem(base *mutation.Strategy, cfg SystemConfig) (*WiredEvolutionSystem, error)

NewWiredEvolutionSystem creates and wires a complete evolution system.

Source Files

View all Source files

Directories

Path Synopsis
Package experience provides evidence aggregation for the GA/Memory/Tool fusion system.
 Package experience provides evidence aggregation for the GA/Memory/Tool fusion system.
Package genome provides genetic algorithm crossover (recombination) operators for combining two parent strategies into a child strategy.
 Package genome provides genetic algorithm crossover (recombination) operators for combining two parent strategies into a child strategy.
Package mutation ...
 Package mutation ...
Package promotion provides strategy promotion and demotion logic.
 Package promotion provides strategy promotion and demotion logic.
Package refine implements Harness-style small-step evolution of supplement state (memory / skill / context entries): plan → apply → rollback with baseline conflict detection (primitive 1).
 Package refine implements Harness-style small-step evolution of supplement state (memory / skill / context entries): plan → apply → rollback with baseline conflict detection (primitive 1).
Package scoring ...
 Package scoring ...
Package evolution provides error definitions for the evolution service.
 Package evolution provides error definitions for the evolution service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.