forge

package
v0.0.0-...-071fe3b Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package forge provides the self-learning framework for NemesisBot. It follows a Read → Execute → Reflect → Write cycle to learn from daily tasks, generate Skills, scripts, and MCP modules automatically.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildDiagnosisForTest 

func BuildDiagnosisForTest(validation *ArtifactValidation) string

BuildDiagnosisForTest exposes buildDiagnosis for testing.

func CleanPathsForTest 

func CleanPathsForTest(content string) string

CleanPathsForTest exposes cleanPaths for testing.

func CleanPublicIPsForTest 

func CleanPublicIPsForTest(content string) string

CleanPublicIPsForTest exposes cleanPublicIPs for testing.

func ComputePatternHash 

func ComputePatternHash(toolName string, args map[string]interface{}) string

ComputePatternHash generates a SHA256 hash from a tool name and its args keys.

func ExtractJSONFromResponse 

func ExtractJSONFromResponse(response string) (map[string]interface{}, error)

ExtractJSONFromResponse attempts to extract JSON from an LLM response.

func ExtractToolSignatureFromChainForTest 

func ExtractToolSignatureFromChainForTest(description string) []string

ExtractToolSignatureFromChainForTest exposes extractToolSignatureFromChain for testing.

func FormatLearningInsightsForTest 

func FormatLearningInsightsForTest(cycle *LearningCycle) string

FormatLearningInsightsForTest exposes formatLearningInsights for testing.

func FormatReport 

func FormatReport(report *ReflectionReport) string

FormatReport generates a Markdown reflection report.

func FormatTraceInsightsForTest 

func FormatTraceInsightsForTest(ts *TraceStats) string

FormatTraceInsightsForTest exposes formatTraceInsights for testing.

func GenerateSkillNameForTest 

func GenerateSkillNameForTest(toolChain string) string

GenerateSkillNameForTest exposes generateSkillName for testing.

func IncrementVersionForTest 

func IncrementVersionForTest(v string) string

IncrementVersionForTest exposes incrementVersion for testing.

func IsPrivateIPForTest 

func IsPrivateIPForTest(ip string) bool

IsPrivateIPForTest exposes isPrivateIP for testing.

func LoadVersionSnapshot 

func LoadVersionSnapshot(artifactPath, version string) (string, error)

LoadVersionSnapshot loads a version backup from the .versions directory.

func MatchesToolSignatureForTest 

func MatchesToolSignatureForTest(trace *ConversationTrace, signature []string) bool

MatchesToolSignatureForTest exposes matchesToolSignature for testing.

func NewForgeTools 

func NewForgeTools(f *Forge) []tools.Tool

NewForgeTools creates all Forge tools for registration with the tool registry.

func ParseLLMInsights 

func ParseLLMInsights(response string) []string

ParseLLMInsights extracts structured suggestions from LLM response.

func PatternFingerprintForTest 

func PatternFingerprintForTest(prefix, data string) string

PatternFingerprintForTest exposes patternFingerprint for testing.

func RedactSensitiveValuesForTest 

func RedactSensitiveValuesForTest(config *ForgeConfig, content string) string

RedactSensitiveValuesForTest exposes redactSensitiveValues for testing.

func SanitizeArgs 

func SanitizeArgs(args map[string]interface{}, sanitizeFields []string) map[string]interface{}

SanitizeArgs removes sensitive fields from arguments based on config.

func SanitizeReportForTest 

func SanitizeReportForTest(config *ForgeConfig, content string) string

SanitizeReportForTest exposes SanitizeReport as a package-level function for testing.

func SaveForgeConfig 

func SaveForgeConfig(path string, cfg *ForgeConfig) error

SaveForgeConfig saves forge configuration to the given path.

func SaveVersionSnapshot 

func SaveVersionSnapshot(artifactPath, version string) error

SaveVersionSnapshot saves a version backup of the artifact file.

func SemanticAnalysisForTest 

func SemanticAnalysisForTest(ctx context.Context, provider providers.LLMProvider, stats *ReflectionStats, artifacts []Artifact, traceStats *TraceStats, cycle *LearningCycle, config *ForgeConfig) (string, error)

SemanticAnalysisForTest exposes semanticAnalysis for testing.

Types

type ActionOutcome 

type ActionOutcome struct {
	ActionID         string    `json:"action_id"`
	ArtifactID       string    `json:"artifact_id"`
	MeasuredAt       time.Time `json:"measured_at"`
	SampleSize       int       `json:"sample_size"`
	RoundsBeforeAvg  float64   `json:"rounds_before_avg"`
	RoundsAfterAvg   float64   `json:"rounds_after_avg"`
	SuccessBefore    float64   `json:"success_before"`
	SuccessAfter     float64   `json:"success_after"`
	DurationBeforeMs int64     `json:"duration_before_ms"`
	DurationAfterMs  int64     `json:"duration_after_ms"`
	ImprovementScore float64   `json:"improvement_score"`
	Verdict          string    `json:"verdict"` // "positive"/"neutral"/"negative"/"insufficient_data"/"observing"
}

ActionOutcome measures the effect of a deployed artifact.

type ActionSummary 

type ActionSummary struct {
	ID         string `json:"id"`
	Type       string `json:"type"`
	Priority   string `json:"priority"`
	Status     string `json:"status"`
	ArtifactID string `json:"artifact_id,omitempty"`
}

ActionSummary is a compact representation of a learning action for cycle storage.

type ActionType 

type ActionType string

ActionType identifies the type of learning action. 

const (
	ActionCreateSkill   ActionType = "create_skill"
	ActionSuggestPrompt ActionType = "suggest_prompt"
	ActionDeprecate     ActionType = "deprecate_artifact"
)

type AggregatedExperience 

type AggregatedExperience struct {
	PatternHash   string    `json:"pattern_hash"`
	ToolName      string    `json:"tool_name"`
	Count         int       `json:"count"`
	AvgDurationMs int64     `json:"avg_duration_ms"`
	SuccessRate   float64   `json:"success_rate"`
	LastSeen      time.Time `json:"last_seen"`
}

AggregatedExperience represents a deduplicated pattern aggregate.

type Artifact 

type Artifact struct {
	ID          string              `json:"id"`
	Type        ArtifactType        `json:"type"`
	Name        string              `json:"name"`
	Version     string              `json:"version"`
	Status      ArtifactStatus      `json:"status"`
	UsageCount  int                 `json:"usage_count"`
	SuccessRate float64             `json:"success_rate"`
	Path        string              `json:"path"`
	CreatedAt   time.Time           `json:"created_at"`
	UpdatedAt   time.Time           `json:"updated_at"`
	Evolution   []Evolution         `json:"evolution,omitempty"`
	Validation  *ArtifactValidation `json:"validation,omitempty"`

	// Phase 6: Closed-loop learning fields
	ToolSignature              []string   `json:"tool_signature,omitempty"`
	LastDegradedAt             *time.Time `json:"last_degraded_at,omitempty"`
	ConsecutiveObservingRounds int        `json:"consecutive_observing_rounds,omitempty"`
}

Artifact represents a self-learning artifact tracked in the registry.

type ArtifactStatus 

type ArtifactStatus string

ArtifactStatus represents the lifecycle state of a Forge artifact. 

const (
	StatusDraft      ArtifactStatus = "draft"
	StatusTesting    ArtifactStatus = "testing"
	StatusActive     ArtifactStatus = "active"
	StatusDeprecated ArtifactStatus = "deprecated"
)

type ArtifactType 

type ArtifactType string

ArtifactType represents the type of Forge artifact. 

const (
	ArtifactSkill  ArtifactType = "skill"
	ArtifactScript ArtifactType = "script"
	ArtifactMCP    ArtifactType = "mcp"
)

type ArtifactValidation 

type ArtifactValidation struct {
	Stage1Static     *StaticValidationResult     `json:"stage1_static,omitempty"`
	Stage2Functional *FunctionalValidationResult `json:"stage2_functional,omitempty"`
	Stage3Quality    *QualityValidationResult    `json:"stage3_quality,omitempty"`
	LastValidated    time.Time                   `json:"last_validated,omitempty"`
}

ArtifactValidation aggregates all three validation stages.

type ArtifactsConfig 

type ArtifactsConfig struct {
	AutoSkill     bool   `json:"auto_skill"`
	MaxSkills     int    `json:"max_skills"`
	MaxScripts    int    `json:"max_scripts"`
	DefaultStatus string `json:"default_status"`
}

ArtifactsConfig controls artifact generation behavior.

type ClusterForgeBridge 

type ClusterForgeBridge interface {
	// ShareToPeer sends an RPC call to a specific peer.
	ShareToPeer(ctx context.Context, peerID, action string, payload map[string]interface{}) ([]byte, error)
	// GetOnlinePeers returns currently online peer nodes.
	GetOnlinePeers() []PeerInfo
	// IsClusterEnabled returns true if the cluster subsystem is running.
	IsClusterEnabled() bool
}

ClusterForgeBridge is the interface for Forge to communicate with the cluster without importing the cluster package directly (avoids circular dependency).

func NewClusterForgeBridge 

func NewClusterForgeBridge(c *cluster.Cluster) ClusterForgeBridge

NewClusterForgeBridge creates a bridge that connects Forge to the cluster subsystem.

type CollectionConfig 

type CollectionConfig struct {
	Enabled              bool     `json:"enabled"`
	BufferSize           int      `json:"buffer_size"`
	FlushInterval        Duration `json:"flush_interval"`
	MaxExperiencesPerDay int      `json:"max_experiences_per_day"`
	SanitizeFields       []string `json:"sanitize_fields"`
}

CollectionConfig controls experience collection behavior.

type Collector 

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

Collector asynchronously collects tool invocation experiences. It uses a buffered channel for non-blocking writes and aggregates duplicate patterns in memory before flushing to disk.

func NewCollector 

func NewCollector(store *ExperienceStore, config *ForgeConfig) *Collector

NewCollector creates a new experience collector.

func (*Collector) Flush 

func (c *Collector) Flush()

Flush writes aggregated patterns to disk and resets the in-memory state.

func (*Collector) InputChannel 

func (c *Collector) InputChannel() chan<- *ExperienceRecord

InputChannel returns the channel for submitting experience records.

func (*Collector) ProcessRecord 

func (c *Collector) ProcessRecord(rec *ExperienceRecord)

ProcessRecord handles deduplication and aggregation for a single record.

func (*Collector) Record 

func (c *Collector) Record(rec *ExperienceRecord) bool

Record submits an experience record asynchronously. Returns false if the channel is full (back-pressure).

type ConversationPattern 

type ConversationPattern struct {
	ID          string      `json:"id"`
	Type        PatternType `json:"type"`
	Fingerprint string      `json:"fingerprint"`
	Frequency   int         `json:"frequency"`
	Confidence  float64     `json:"confidence"`
	FirstSeen   time.Time   `json:"first_seen"`
	LastSeen    time.Time   `json:"last_seen"`

	// Type-specific fields
	ToolChain       string   `json:"tool_chain,omitempty"`
	AvgRounds       float64  `json:"avg_rounds,omitempty"`
	AvgDurationMs   int64    `json:"avg_duration_ms,omitempty"`
	SuccessRate     float64  `json:"success_rate,omitempty"`
	ErrorTool       string   `json:"error_tool,omitempty"`
	ErrorCode       string   `json:"error_code,omitempty"`
	RecoveryTool    string   `json:"recovery_tool,omitempty"`
	EfficiencyScore float64  `json:"efficiency_score,omitempty"`
	CommonArgKeys   []string `json:"common_arg_keys,omitempty"`
	Description     string   `json:"description,omitempty"`
}

ConversationPattern represents a recurring pattern detected in conversation traces.

func ExtractPatternsForTest 

func ExtractPatternsForTest(traces []*ConversationTrace, minFrequency int) []*ConversationPattern

ExtractPatternsForTest exposes extractPatterns for testing.

type ConversationTrace 

type ConversationTrace struct {
	TraceID     string          `json:"trace_id"`
	SessionKey  string          `json:"session_key"` // SHA256 hash
	Channel     string          `json:"channel"`
	StartTime   time.Time       `json:"start_time"`
	EndTime     time.Time       `json:"end_time"`
	DurationMs  int64           `json:"duration_ms"`
	TotalRounds int             `json:"total_rounds"`
	ToolSteps   []ToolStep      `json:"tool_steps"`
	Signals     []SessionSignal `json:"signals,omitempty"`
	TokensUsed  int             `json:"tokens_used,omitempty"`
}

ConversationTrace holds metadata for a complete conversation (no raw content).

type CycleStore 

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

CycleStore persists learning cycles as JSONL files. Directory structure: learning/202604/20260421.jsonl

func NewCycleStore 

func NewCycleStore(forgeDir string, config *ForgeConfig) *CycleStore

NewCycleStore creates a new CycleStore rooted at forgeDir/learning.

func (*CycleStore) Append 

func (s *CycleStore) Append(cycle *LearningCycle) error

Append writes a learning cycle to today's JSONL file.

func (*CycleStore) Cleanup 

func (s *CycleStore) Cleanup(maxAgeDays int) error

Cleanup removes cycle files older than maxAgeDays.

func (*CycleStore) LoadLatestCycle 

func (s *CycleStore) LoadLatestCycle() (*LearningCycle, error)

LoadLatestCycle returns the most recent learning cycle.

func (*CycleStore) ReadCycles 

func (s *CycleStore) ReadCycles(since time.Time) ([]*LearningCycle, error)

ReadCycles reads all learning cycles since the given time.

type DeploymentMonitor 

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

DeploymentMonitor evaluates the effectiveness of deployed Forge artifacts by comparing conversation traces before and after deployment.

func NewDeploymentMonitor 

func NewDeploymentMonitor(traceStore *TraceStore, registry *Registry, config *ForgeConfig) *DeploymentMonitor

NewDeploymentMonitor creates a new DeploymentMonitor.

func (*DeploymentMonitor) ClassifyVerdictForTest 

func (dm *DeploymentMonitor) ClassifyVerdictForTest(improvementScore float64, artifact *Artifact) string

ClassifyVerdictForTest exposes classifyVerdict for testing.

func (*DeploymentMonitor) EvaluateOutcomes 

func (dm *DeploymentMonitor) EvaluateOutcomes() []*ActionOutcome

EvaluateOutcomes measures the effect of all active Forge Skills with ToolSignatures. Returns ActionOutcome for each evaluated artifact.

type Duration 

type Duration struct {
	time.Duration
}

Duration wraps time.Duration for JSON serialization.

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(data []byte) error

type Evolution 

type Evolution struct {
	Version string    `json:"version"`
	Date    time.Time `json:"date"`
	Change  string    `json:"change"`
}

Evolution records a version change for an artifact.

type ExperienceRecord 

type ExperienceRecord struct {
	Timestamp         time.Time              `json:"timestamp"`
	SessionID         string                 `json:"session_id"`
	ToolName          string                 `json:"tool_name"`
	Args              map[string]interface{} `json:"args"`
	Success           bool                   `json:"success"`
	DurationMs        int64                  `json:"duration_ms"`
	PatternHash       string                 `json:"pattern_hash"`
	PositionInSession int                    `json:"position_in_session"`
}

ExperienceRecord captures a single tool invocation for later analysis.

func (*ExperienceRecord) ToJSON 

func (r *ExperienceRecord) ToJSON() ([]byte, error)

ToJSON serializes an experience record to JSON bytes.

type ExperienceStore 

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

ExperienceStore manages JSONL-based persistence of experience data. Files are organized by month: experiences/202604/20260420.jsonl

func NewExperienceStore 

func NewExperienceStore(forgeDir string, config *ForgeConfig) *ExperienceStore

NewExperienceStore creates a new experience store rooted at forgeDir.

func (*ExperienceStore) AppendAggregated 

func (s *ExperienceStore) AppendAggregated(rec *AggregatedExperience) error

AppendAggregated writes an aggregated experience record to today's JSONL file.

func (*ExperienceStore) Cleanup 

func (s *ExperienceStore) Cleanup(maxAgeDays int) error

Cleanup removes experience files older than maxAgeDays.

func (*ExperienceStore) GetStats 

func (s *ExperienceStore) GetStats() (totalRecords int, uniquePatterns int, err error)

GetStats returns summary statistics for the experience store.

func (*ExperienceStore) GetTopPatterns 

func (s *ExperienceStore) GetTopPatterns(since time.Time, topN int) ([]*AggregatedExperience, error)

GetTopPatterns returns the top N patterns by count in the given time range.

func (*ExperienceStore) ReadAggregated 

func (s *ExperienceStore) ReadAggregated(since time.Time) ([]*AggregatedExperience, error)

ReadAggregated reads all aggregated experiences for the given time range.

func (*ExperienceStore) ReadAggregatedByDay 

func (s *ExperienceStore) ReadAggregatedByDay(since time.Time) (map[string][]*AggregatedExperience, error)

ReadAggregatedByDay reads aggregated experiences grouped by day.

type ExportManifest 

type ExportManifest struct {
	ID         string   `json:"id"`
	Type       string   `json:"type"`
	Name       string   `json:"name"`
	Version    string   `json:"version"`
	ExportedAt string   `json:"exported_at"`
	Files      []string `json:"files"`
}

ExportManifest describes an exported artifact's metadata.

type Exporter 

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

Exporter handles exporting Forge artifacts to shareable formats.

func NewExporter 

func NewExporter(workspace string, registry *Registry) *Exporter

NewExporter creates a new Exporter for the given workspace.

func (*Exporter) ExportAll 

func (e *Exporter) ExportAll(targetDir string) (int, error)

ExportAll exports all active artifacts to a target directory.

func (*Exporter) ExportArtifact 

func (e *Exporter) ExportArtifact(artifactID string, targetDir string) error

ExportArtifact exports a single artifact to a target directory.

type Forge 

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

Forge is the core self-learning system that runs alongside AgentLoop and Cluster. It consists of four subsystems: Collector, Reflector, Factory, and Registry. Phase 4 adds Syncer for cluster learning (cross-node reflection sharing). Phase 5 adds TraceCollector for conversation-level trace collection. Phase 6 adds LearningEngine for closed-loop self-learning.

func NewForge 

func NewForge(workspace string, pluginMgr *plugin.Manager) (*Forge, error)

NewForge creates a new Forge instance with the given workspace and plugin manager. The plugin manager is used to register the ForgePlugin for experience collection.

func (*Forge) CreateSkill 

func (f *Forge) CreateSkill(ctx context.Context, name, content, description string, toolSignature []string) (Artifact, error)

CreateSkill creates and registers a Skill artifact. This is a shared method used by both the forge_create tool and the LearningEngine to avoid code duplication.

func (*Forge) GetCollector 

func (f *Forge) GetCollector() *Collector

GetCollector returns the experience collector for plugin integration.

func (*Forge) GetConfig 

func (f *Forge) GetConfig() *ForgeConfig

GetConfig returns the forge configuration.

func (*Forge) GetCycleStore 

func (f *Forge) GetCycleStore() *CycleStore

GetCycleStore returns the Phase 6 cycle store.

func (*Forge) GetDeploymentMonitor 

func (f *Forge) GetDeploymentMonitor() *DeploymentMonitor

GetDeploymentMonitor returns the Phase 6 deployment monitor.

func (*Forge) GetExporter 

func (f *Forge) GetExporter() *Exporter

GetExporter returns the artifact exporter.

func (*Forge) GetLearningEngine 

func (f *Forge) GetLearningEngine() *LearningEngine

GetLearningEngine returns the Phase 6 learning engine.

func (*Forge) GetMCPInstaller 

func (f *Forge) GetMCPInstaller() *MCPInstaller

GetMCPInstaller returns the MCP installer for config registration.

func (*Forge) GetPipeline 

func (f *Forge) GetPipeline() *Pipeline

GetPipeline returns the validation pipeline.

func (*Forge) GetReflector 

func (f *Forge) GetReflector() *Reflector

GetReflector returns the reflection engine.

func (*Forge) GetRegistry 

func (f *Forge) GetRegistry() *Registry

GetRegistry returns the artifact registry.

func (*Forge) GetSyncer 

func (f *Forge) GetSyncer() *Syncer

GetSyncer returns the cluster syncer for Phase 4 cross-node sharing.

func (*Forge) GetTraceCollector 

func (f *Forge) GetTraceCollector() *TraceCollector

GetTraceCollector returns the trace collector for Phase 5 conversation-level analysis.

func (*Forge) GetTraceStore 

func (f *Forge) GetTraceStore() *TraceStore

GetTraceStore returns the trace store.

func (*Forge) GetWorkspace 

func (f *Forge) GetWorkspace() string

GetWorkspace returns the forge workspace directory.

func (*Forge) ReceiveReflection 

func (f *Forge) ReceiveReflection(payload map[string]interface{}) error

ReceiveReflection receives a remote reflection report (used by RPC handler).

func (*Forge) ReflectNow 

func (f *Forge) ReflectNow(ctx context.Context, period string, focus string) (string, error)

ReflectNow triggers an immediate reflection, returning the report path.

func (*Forge) SetBridge 

func (f *Forge) SetBridge(bridge ClusterForgeBridge)

SetBridge injects the cluster bridge for cross-node reflection sharing (Phase 4).

func (*Forge) SetProvider 

func (f *Forge) SetProvider(provider providers.LLMProvider)

SetProvider sets the LLM provider for semantic reflection and quality evaluation.

func (*Forge) Start 

func (f *Forge) Start()

Start launches the collector and reflector goroutines.

func (*Forge) Stop 

func (f *Forge) Stop()

Stop gracefully shuts down Forge, flushing remaining experiences.

type ForgeConfig 

type ForgeConfig struct {
	Collection CollectionConfig `json:"collection"`
	Storage    StorageConfig    `json:"storage"`
	Reflection ReflectionConfig `json:"reflection"`
	Artifacts  ArtifactsConfig  `json:"artifacts"`
	Validation ValidationConfig `json:"validation"`
	Trace      TraceConfig      `json:"trace"`
	Learning   LearningConfig   `json:"learning"` // Phase 6: closed-loop learning
}

ForgeConfig holds all configuration for the Forge self-learning system. It is loaded from workspace/forge/forge.json.

func DefaultForgeConfig 

func DefaultForgeConfig() *ForgeConfig

DefaultForgeConfig returns sensible defaults.

func LoadForgeConfig 

func LoadForgeConfig(path string) (*ForgeConfig, error)

LoadForgeConfig loads forge configuration from the given path.

type ForgePlugin 

type ForgePlugin struct {
	*plugin.BasePlugin
	// contains filtered or unexported fields
}

ForgePlugin implements the Plugin interface to intercept tool invocations and collect experience data for the Forge self-learning system.

func NewForgePlugin 

func NewForgePlugin(collector *Collector) *ForgePlugin

NewForgePlugin creates a new Forge experience collection plugin.

func (*ForgePlugin) Execute 

func (p *ForgePlugin) Execute(ctx context.Context, invocation *plugin.ToolInvocation) (bool, error, bool)

Execute intercepts tool invocations to collect experience data. It never blocks or denies the operation - it only observes.

type FunctionalValidationResult 

type FunctionalValidationResult struct {
	ValidationStage
	TestsRun    int `json:"tests_run,omitempty"`
	TestsPassed int `json:"tests_passed,omitempty"`
}

FunctionalValidationResult holds the result of Stage 2 (functional testing).

type LearningAction 

type LearningAction struct {
	ID          string     `json:"id"`
	Type        ActionType `json:"type"`
	Priority    string     `json:"priority"` // "high"/"medium"/"low"
	Confidence  float64    `json:"confidence"`
	PatternID   string     `json:"pattern_id"`
	Status      string     `json:"status"` // "pending"/"executed"/"skipped"/"failed"
	ArtifactID  string     `json:"artifact_id,omitempty"`
	DraftName   string     `json:"draft_name,omitempty"`
	Description string     `json:"description"`
	Rationale   string     `json:"rationale"`
	CreatedAt   time.Time  `json:"created_at"`
	ExecutedAt  *time.Time `json:"executed_at,omitempty"`
	ErrorMsg    string     `json:"error_msg,omitempty"`
}

LearningAction represents an action to be taken based on detected patterns.

type LearningConfig 

type LearningConfig struct {
	Enabled             bool    `json:"enabled"`
	MinPatternFrequency int     `json:"min_pattern_frequency"`      // minimum occurrences to qualify as pattern (default 5)
	HighConfThreshold   float64 `json:"high_confidence_threshold"`  // auto-generate threshold (default 0.8)
	MaxAutoCreates      int     `json:"max_auto_creates_per_cycle"` // max auto-creates per cycle (default 3)
	MaxRefineRounds     int     `json:"max_refine_rounds"`          // max refine iterations (default 3)
	MinOutcomeSamples   int     `json:"min_outcome_samples"`        // min samples for evaluation (default 5)
	MonitorWindowDays   int     `json:"monitor_window_days"`        // observation window in days (default 7)
	DegradeThreshold    float64 `json:"deprecation_threshold"`      // deprecation threshold (default -0.2)
	DegradeCooldownDays int     `json:"deprecate_cooldown_days"`    // cooldown before re-deprecating (default 7)
	LLMBudgetTokens     int     `json:"llm_budget_tokens"`          // token budget for Skill draft generation (default 2000)
}

LearningConfig controls closed-loop self-learning (Phase 6).

type LearningCycle 

type LearningCycle struct {
	ID               string           `json:"id"`
	StartedAt        time.Time        `json:"started_at"`
	CompletedAt      *time.Time       `json:"completed_at,omitempty"`
	CycleNumber      int              `json:"cycle_number"`
	PatternsFound    int              `json:"patterns_found"`
	ActionsCreated   int              `json:"actions_created"`
	ActionsExecuted  int              `json:"actions_executed"`
	ActionsSkipped   int              `json:"actions_skipped"`
	PreviousOutcomes []*ActionOutcome `json:"previous_outcomes,omitempty"`
	PatternSummary   []PatternSummary `json:"pattern_summary,omitempty"`
	ActionSummary    []ActionSummary  `json:"action_summary,omitempty"`
}

LearningCycle records a single learning cycle execution.

type LearningEngine 

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

LearningEngine orchestrates the closed-loop self-learning cycle.

func NewLearningEngine 

func NewLearningEngine(forgeDir string, registry *Registry, traceStore *TraceStore, pipeline *Pipeline, cycleStore *CycleStore, monitor *DeploymentMonitor, config *ForgeConfig) *LearningEngine

NewLearningEngine creates a new LearningEngine.

func (*LearningEngine) AdjustConfidenceForTest 

func (le *LearningEngine) AdjustConfidenceForTest(outcomes []*ActionOutcome)

AdjustConfidenceForTest exposes adjustConfidence for testing.

func (*LearningEngine) ExecuteCreateSkillForTest 

func (le *LearningEngine) ExecuteCreateSkillForTest(ctx context.Context, action *LearningAction)

ExecuteCreateSkillForTest exposes executeCreateSkill for testing.

func (*LearningEngine) ExecuteSuggestPromptForTest 

func (le *LearningEngine) ExecuteSuggestPromptForTest(action *LearningAction)

ExecuteSuggestPromptForTest exposes executeSuggestPrompt for testing.

func (*LearningEngine) GenerateActionsForTest 

func (le *LearningEngine) GenerateActionsForTest(patterns []*ConversationPattern) []*LearningAction

GenerateActionsForTest exposes generateActions for testing.

func (*LearningEngine) GetLatestCycle 

func (le *LearningEngine) GetLatestCycle() *LearningCycle

GetLatestCycle returns the most recent learning cycle.

func (*LearningEngine) RunCycle 

func (le *LearningEngine) RunCycle(ctx context.Context, traces []*ConversationTrace, traceStats *TraceStats, stats *ReflectionStats) *LearningCycle

RunCycle executes one full learning cycle. It runs with an internal timeout and does not block the caller on failure.

func (*LearningEngine) SetForge 

func (le *LearningEngine) SetForge(f *Forge)

SetForge injects the parent Forge instance for CreateSkill shared method.

func (*LearningEngine) SetProvider 

func (le *LearningEngine) SetProvider(provider providers.LLMProvider)

SetProvider injects the LLM provider for Skill draft generation.

type MCPInstaller 

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

MCPInstaller manages MCP server registration in config.mcp.json.

func NewMCPInstaller 

func NewMCPInstaller(workspace string) *MCPInstaller

NewMCPInstaller creates a new MCPInstaller for the given workspace.

func (*MCPInstaller) Install 

func (inst *MCPInstaller) Install(artifact *Artifact, mcpDir string) error

Install adds or updates an MCP server in config.mcp.json.

func (*MCPInstaller) IsInstalled 

func (inst *MCPInstaller) IsInstalled(artifactName string) bool

IsInstalled checks if an MCP server is already registered in config.mcp.json.

func (*MCPInstaller) Uninstall 

func (inst *MCPInstaller) Uninstall(artifactName string) error

Uninstall removes an MCP server from config.mcp.json.

type MergedInsights 

type MergedInsights struct {
	LocalPatterns     []*PatternInsight
	RemotePatterns    []*PatternInsight
	MergedPatterns    []*PatternInsight
	CommonTools       map[string]int
	UniqueRemoteTools []string
}

MergedInsights holds the result of merging local and remote reflection reports.

type PatternInsight 

type PatternInsight struct {
	PatternHash   string
	ToolName      string
	Count         int
	AvgDurationMs int64
	SuccessRate   float64
	Suggestion    string
}

PatternInsight holds insight data for a tool usage pattern.

type PatternSummary 

type PatternSummary struct {
	ID          string  `json:"id"`
	Type        string  `json:"type"`
	Fingerprint string  `json:"fingerprint"`
	Frequency   int     `json:"frequency"`
	Confidence  float64 `json:"confidence"`
}

PatternSummary is a compact representation of a detected pattern for cycle storage.

type PatternType 

type PatternType string

PatternType identifies the category of a detected conversation pattern. 

const (
	PatternToolChain       PatternType = "tool_chain"
	PatternErrorRecovery   PatternType = "error_recovery"
	PatternEfficiencyIssue PatternType = "efficiency_issue"
	PatternSuccessTemplate PatternType = "success_template"
)

type PeerInfo 

type PeerInfo struct {
	ID   string
	Name string
}

PeerInfo holds basic information about a cluster peer node.

type Pipeline 

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

Pipeline orchestrates the three-stage validation process.

func NewPipeline 

func NewPipeline(registry *Registry, config *ForgeConfig) *Pipeline

NewPipeline creates a new validation Pipeline.

func (*Pipeline) DetermineStatus 

func (p *Pipeline) DetermineStatus(validation *ArtifactValidation) ArtifactStatus

DetermineStatus determines the artifact status based on validation results.

func (*Pipeline) Run 

func (p *Pipeline) Run(ctx context.Context, artifactID string) (*ArtifactValidation, error)

Run executes the full validation pipeline for an artifact by ID.

func (*Pipeline) RunFromContent 

func (p *Pipeline) RunFromContent(ctx context.Context, artifact *Artifact, content string) *ArtifactValidation

RunFromContent executes the full validation pipeline with provided content.

func (*Pipeline) SetProvider 

func (p *Pipeline) SetProvider(provider providers.LLMProvider)

SetProvider sets the LLM provider for quality evaluation.

type QualityEvaluator 

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

QualityEvaluator performs Stage 3 quality evaluation using LLM-as-Judge.

func NewQualityEvaluator 

func NewQualityEvaluator(provider providers.LLMProvider, config *ForgeConfig) *QualityEvaluator

NewQualityEvaluator creates a new QualityEvaluator.

func (*QualityEvaluator) Evaluate 

func (e *QualityEvaluator) Evaluate(ctx context.Context, artifact *Artifact, content string) *QualityValidationResult

Evaluate performs quality evaluation on an artifact using LLM-as-Judge.

func (*QualityEvaluator) SetProvider 

func (e *QualityEvaluator) SetProvider(provider providers.LLMProvider)

SetProvider updates the LLM provider.

type QualityValidationResult 

type QualityValidationResult struct {
	ValidationStage
	Score      int            `json:"score,omitempty"`
	Notes      string         `json:"notes,omitempty"`
	Dimensions map[string]int `json:"dimensions,omitempty"`
}

QualityValidationResult holds the result of Stage 3 (LLM quality evaluation).

type ReflectionConfig 

type ReflectionConfig struct {
	Interval         Duration `json:"interval"`
	MinExperiences   int      `json:"min_experiences"`
	UseLLM           bool     `json:"use_llm"`
	LLMBudgetTokens  int      `json:"llm_budget_tokens"`
	MaxReportAgeDays int      `json:"max_report_age_days"`
}

ReflectionConfig controls the reflection engine.

type ReflectionReport 

type ReflectionReport struct {
	Date          string
	Period        string
	Focus         string
	Stats         *ReflectionStats
	Artifacts     []Artifact
	LLMInsights   string
	TraceStats    *TraceStats    // Phase 5: conversation-level insights
	LearningCycle *LearningCycle `json:"-"` // Phase 6: not serialized, for report generation only
}

ReflectionReport represents a generated reflection report.

type ReflectionStats 

type ReflectionStats struct {
	TotalRecords   int
	UniquePatterns int
	AvgSuccessRate float64
	TopPatterns    []*PatternInsight
	LowSuccess     []*PatternInsight
	ToolFrequency  map[string]int
}

ReflectionStats holds statistical analysis results.

type Reflector 

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

Reflector analyzes experience data to generate insights and improvement suggestions. It has two levels: statistical (pure code, zero tokens) and semantic (LLM-based).

func NewReflector 

func NewReflector(forgeDir string, store *ExperienceStore, registry *Registry, config *ForgeConfig) *Reflector

NewReflector creates a new reflection engine.

func (*Reflector) AnalyzeTracesForTest 

func (r *Reflector) AnalyzeTracesForTest(since time.Time) *TraceStats

AnalyzeTracesForTest exposes analyzeTraces for testing.

func (*Reflector) CleanupReports 

func (r *Reflector) CleanupReports(maxAgeDays int) error

CleanupReports removes reflection reports older than maxAgeDays.

func (*Reflector) GetLatestReport 

func (r *Reflector) GetLatestReport() (string, error)

GetLatestReport returns the path to the most recent reflection report.

func (*Reflector) MergeRemoteReflections 

func (r *Reflector) MergeRemoteReflections(remoteReports []string) *MergedInsights

MergeRemoteReflections reads remote reflection reports and merges their insights with local patterns. It extracts tool usage patterns from remote reports and combines them with local data for richer analysis.

func (*Reflector) Reflect 

func (r *Reflector) Reflect(ctx context.Context, period string, focus string) (string, error)

Reflect performs a full reflection cycle and returns the report file path.

func (*Reflector) SetLearningEngine 

func (r *Reflector) SetLearningEngine(engine *LearningEngine)

SetLearningEngine injects the Phase 6 learning engine (post-injection pattern).

func (*Reflector) SetProvider 

func (r *Reflector) SetProvider(provider providers.LLMProvider)

SetProvider sets the LLM provider for semantic reflection.

func (*Reflector) SetTraceStore 

func (r *Reflector) SetTraceStore(store *TraceStore)

SetTraceStore injects a trace store for conversation-level analysis.

type Registry 

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

Registry manages the artifact registry stored in registry.json.

func NewRegistry 

func NewRegistry(path string) *Registry

NewRegistry creates or loads a registry from the given path.

func (*Registry) Add 

func (r *Registry) Add(artifact Artifact) error

Add adds a new artifact to the registry.

func (*Registry) Count 

func (r *Registry) Count(artifactType ArtifactType) int

Count returns the number of artifacts, optionally filtered by type.

func (*Registry) Delete 

func (r *Registry) Delete(id string) error

Delete removes an artifact from the registry.

func (*Registry) Get 

func (r *Registry) Get(id string) (Artifact, bool)

Get retrieves an artifact by ID.

func (*Registry) List 

func (r *Registry) List(artifactType ArtifactType, status ArtifactStatus) []Artifact

List returns all artifacts, optionally filtered by type and/or status.

func (*Registry) ListAll 

func (r *Registry) ListAll() []Artifact

ListAll returns all artifacts.

func (*Registry) Update 

func (r *Registry) Update(id string, fn func(*Artifact)) error

Update updates an existing artifact.

type RegistryData 

type RegistryData struct {
	Version   string     `json:"version"`
	Artifacts []Artifact `json:"artifacts"`
}

RegistryData is the top-level structure for registry.json.

type ReportSanitizer 

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

ReportSanitizer cleans sensitive information from reflection reports before sharing them with remote cluster nodes.

func NewReportSanitizer 

func NewReportSanitizer(config *ForgeConfig) *ReportSanitizer

NewReportSanitizer creates a sanitizer using the Forge config's SanitizeFields.

func NewReportSanitizerForTest 

func NewReportSanitizerForTest(config *ForgeConfig) *ReportSanitizer

NewReportSanitizerForTest creates a ReportSanitizer with the given config for testing.

func (*ReportSanitizer) SanitizeReport 

func (s *ReportSanitizer) SanitizeReport(content string) string

SanitizeReport applies all privacy filters to the report content.

type RetryPattern 

type RetryPattern struct {
	ToolName    string
	RetryCount  int
	SuccessRate float64 // success rate after retry
}

RetryPattern represents a tool that was retried after failure.

type SessionSignal 

type SessionSignal struct {
	Type      string    `json:"type"` // "retry", "backtrack"
	Timestamp time.Time `json:"timestamp"`
	Round     int       `json:"round"`
}

SessionSignal marks an interesting pattern detected during conversation.

type StaticValidationResult 

type StaticValidationResult struct {
	ValidationStage
	Warnings []string `json:"warnings,omitempty"`
}

StaticValidationResult holds the result of Stage 1 (static validation).

type StaticValidator 

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

StaticValidator performs Stage 1 static content validation.

func NewStaticValidator 

func NewStaticValidator(registry *Registry) *StaticValidator

NewStaticValidator creates a new StaticValidator.

func (*StaticValidator) Validate 

func (v *StaticValidator) Validate(artifactType ArtifactType, name string, content string) *StaticValidationResult

Validate performs static validation on artifact content.

type StorageConfig 

type StorageConfig struct {
	MaxExperienceAgeDays int      `json:"max_experience_age_days"`
	MaxReportAgeDays     int      `json:"max_report_age_days"`
	CleanupInterval      Duration `json:"cleanup_interval"`
}

StorageConfig controls data retention.

type Syncer 

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

Syncer handles sharing reflection reports across cluster nodes.

func NewSyncer 

func NewSyncer(forgeDir string, registry *Registry, config *ForgeConfig) *Syncer

NewSyncer creates a new Syncer instance.

func (*Syncer) GetLocalReflections 

func (s *Syncer) GetLocalReflections() ([]string, error)

GetLocalReflections returns file paths of all local reflection reports for sharing.

func (*Syncer) GetReflectionsListPayload 

func (s *Syncer) GetReflectionsListPayload() map[string]interface{}

GetReflectionsListPayload returns a serializable list of available local reflections.

func (*Syncer) GetRemoteReflections 

func (s *Syncer) GetRemoteReflections() ([]string, error)

GetRemoteReflections returns file paths of all remote reflection reports.

func (*Syncer) IsEnabled 

func (s *Syncer) IsEnabled() bool

IsEnabled returns true if the syncer can share reflections (bridge present + cluster running).

func (*Syncer) ReadReflectionContent 

func (s *Syncer) ReadReflectionContent(filename string) (string, error)

ReadReflectionContent reads a specific reflection report content.

func (*Syncer) ReceiveReflection 

func (s *Syncer) ReceiveReflection(payload map[string]interface{}) error

ReceiveReflection receives and stores a remote reflection report.

func (*Syncer) SanitizeContent 

func (s *Syncer) SanitizeContent(content string) string

SanitizeContent sanitizes reflection content before sharing with remote peers.

func (*Syncer) SetBridge 

func (s *Syncer) SetBridge(bridge ClusterForgeBridge)

SetBridge injects the cluster bridge for RPC communication.

func (*Syncer) ShareReflection 

func (s *Syncer) ShareReflection(ctx context.Context, reportPath string) error

ShareReflection reads a reflection report, sanitizes it, and broadcasts to all online peers.

type TestRunner 

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

TestRunner performs Stage 2 functional validation. On Windows, it does pure content checks without executing scripts.

func NewTestRunner 

func NewTestRunner(registry *Registry) *TestRunner

NewTestRunner creates a new TestRunner.

func (*TestRunner) RunTests 

func (r *TestRunner) RunTests(ctx context.Context, artifact *Artifact) *FunctionalValidationResult

RunTests performs functional validation on an artifact.

type ToolChainPattern 

type ToolChainPattern struct {
	Chain       string // "read_file→edit_file→exec"
	Count       int
	AvgRounds   float64
	SuccessRate float64
}

ToolChainPattern represents a frequently occurring tool call sequence.

type ToolStep 

type ToolStep struct {
	ToolName   string   `json:"tool_name"`
	Success    bool     `json:"success"`
	DurationMs int64    `json:"duration_ms"`
	LLMRound   int      `json:"llm_round"`
	ChainPos   int      `json:"chain_pos"`
	ArgKeys    []string `json:"arg_keys"`
	ErrorCode  string   `json:"error_code,omitempty"`
}

ToolStep records a single tool invocation within a conversation.

type TraceCollector 

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

TraceCollector observes conversation lifecycle events and builds traces. It implements the observer.Observer interface.

func NewTraceCollector 

func NewTraceCollector(store *TraceStore, config *ForgeConfig) *TraceCollector

NewTraceCollector creates a new TraceCollector.

func (*TraceCollector) Name 

func (t *TraceCollector) Name() string

func (*TraceCollector) OnEvent 

func (t *TraceCollector) OnEvent(ctx context.Context, event observer.ConversationEvent)

type TraceConfig 

type TraceConfig struct {
	Enabled              bool `json:"enabled"`
	MaxTraceAgeDays      int  `json:"max_trace_age_days"`
	MinTracesForAnalysis int  `json:"min_traces_for_analysis"`
}

TraceConfig controls conversation-level trace collection (Phase 5).

type TraceStats 

type TraceStats struct {
	TotalTraces       int
	AvgRounds         float64
	AvgDurationMs     int64
	ToolChainPatterns []*ToolChainPattern
	RetryPatterns     []*RetryPattern
	EfficiencyScore   float64 // 0-1, higher is better
	SignalSummary     map[string]int
}

TraceStats holds conversation-level statistical analysis results.

type TraceStore 

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

TraceStore persists conversation traces as JSONL files. Directory structure: traces/202604/20260421.jsonl

func NewTraceStore 

func NewTraceStore(forgeDir string, config *ForgeConfig) *TraceStore

NewTraceStore creates a new TraceStore rooted at forgeDir/traces.

func (*TraceStore) Append 

func (s *TraceStore) Append(trace *ConversationTrace) error

Append writes a conversation trace to today's JSONL file.

func (*TraceStore) Cleanup 

func (s *TraceStore) Cleanup(maxAgeDays int) error

Cleanup removes trace files older than maxAgeDays.

func (*TraceStore) ReadTraces 

func (s *TraceStore) ReadTraces(since time.Time) ([]*ConversationTrace, error)

ReadTraces reads all traces since the given time.

type ValidationConfig 

type ValidationConfig struct {
	AutoValidate    bool     `json:"auto_validate"`
	MinQualityScore int      `json:"min_quality_score"`
	LLMMaxTokens    int      `json:"llm_max_tokens"`
	Timeout         Duration `json:"timeout"`
}

ValidationConfig controls the three-stage validation pipeline.

type ValidationStage 

type ValidationStage struct {
	Passed    bool      `json:"passed"`
	Timestamp time.Time `json:"timestamp"`
	Errors    []string  `json:"errors,omitempty"`
}

ValidationStage is the common base for all validation result stages.

Source Files

View all Source files

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.