Documentation
¶
Overview ¶
Package core provides the loop engine execution logic.
Package core provides loop event types for the loop engine.
Package core provides interfaces for dependency injection.
Package core implements the Ralph loop engine and business logic.
This package contains the core loop execution engine that orchestrates iterative AI development loops. It manages state transitions, promise detection, and event emission.
The LoopEngine follows a state machine pattern with the following states:
- StateIdle: Initial state, ready to start
- StateRunning: Loop is executing iterations
- StateComplete: Successfully completed (promise detected)
- StateFailed: Failed due to error, timeout, or max iterations
- StateCancelled: Cancelled by user
See specs/loop-engine.md for detailed specification.
Package core provides promise detection for the loop engine.
Index ¶
- Variables
- func BuildSystemPrompt(promisePhrase string) string
- type AIResponseEvent
- type ErrorEvent
- type IterationCompleteEvent
- type IterationStartEvent
- type LoopCancelledEvent
- type LoopCompleteEvent
- type LoopConfig
- type LoopEngine
- type LoopFailedEvent
- type LoopResult
- type LoopStartEvent
- type LoopState
- type PromiseDetectedEvent
- type SDKClient
- type ToolEvent
- type ToolExecutionEvent
- type ToolExecutionStartEvent
Constants ¶
This section is empty.
Variables ¶
var ErrLoopCancelled = errors.New("loop cancelled")
ErrLoopCancelled indicates the loop was cancelled by the user.
var ErrLoopTimeout = errors.New("loop timeout exceeded")
ErrLoopTimeout indicates the loop exceeded the configured timeout.
var ErrMaxIterations = errors.New("maximum iterations reached")
ErrMaxIterations indicates the maximum iterations were reached.
Functions ¶
func BuildSystemPrompt ¶
BuildSystemPrompt constructs the system prompt from the embedded template. It replaces {{.Task}} with the actual user task and {{.Promise}} with the completion phrase.
Types ¶
type AIResponseEvent ¶
type AIResponseEvent struct {
// Text is the AI response text.
Text string
// Iteration is the current iteration number.
Iteration int
}
AIResponseEvent indicates AI response text was received.
func NewAIResponseEvent ¶
func NewAIResponseEvent(text string, iteration int) *AIResponseEvent
NewAIResponseEvent creates a new AIResponseEvent.
type ErrorEvent ¶
type ErrorEvent struct {
// Error is the error that occurred.
Error error
// Iteration is the current iteration number (0 if not in iteration).
Iteration int
// Recoverable indicates if the error is recoverable.
Recoverable bool
}
ErrorEvent indicates an error occurred.
func NewErrorEvent ¶
func NewErrorEvent(err error, iteration int, recoverable bool) *ErrorEvent
NewErrorEvent creates a new ErrorEvent.
type IterationCompleteEvent ¶
type IterationCompleteEvent struct {
// Iteration is the iteration number (1-based).
Iteration int
// Duration is how long the iteration took.
Duration time.Duration
}
IterationCompleteEvent indicates an iteration completed.
func NewIterationCompleteEvent ¶
func NewIterationCompleteEvent(iteration int, duration time.Duration) *IterationCompleteEvent
NewIterationCompleteEvent creates a new IterationCompleteEvent.
type IterationStartEvent ¶
type IterationStartEvent struct {
// Iteration is the iteration number (1-based).
Iteration int
// MaxIterations is the maximum number of iterations.
MaxIterations int
}
IterationStartEvent indicates an iteration has started.
func NewIterationStartEvent ¶
func NewIterationStartEvent(iteration, maxIterations int) *IterationStartEvent
NewIterationStartEvent creates a new IterationStartEvent.
type LoopCancelledEvent ¶
type LoopCancelledEvent struct {
// Result contains partial loop result.
Result *LoopResult
}
LoopCancelledEvent indicates the loop was cancelled by the user.
func NewLoopCancelledEvent ¶
func NewLoopCancelledEvent(result *LoopResult) *LoopCancelledEvent
NewLoopCancelledEvent creates a new LoopCancelledEvent.
type LoopCompleteEvent ¶
type LoopCompleteEvent struct {
// Result contains the loop result.
Result *LoopResult
}
LoopCompleteEvent indicates the loop completed successfully.
func NewLoopCompleteEvent ¶
func NewLoopCompleteEvent(result *LoopResult) *LoopCompleteEvent
NewLoopCompleteEvent creates a new LoopCompleteEvent.
type LoopConfig ¶
type LoopConfig struct {
Prompt string
PromisePhrase string
Model string
WorkingDir string
LogLevel string
SystemPrompt string
SystemPromptMode string
MaxIterations int
Timeout time.Duration
DryRun bool
Streaming bool
}
LoopConfig contains configuration for loop execution.
func DefaultLoopConfig ¶
func DefaultLoopConfig() *LoopConfig
DefaultLoopConfig returns a LoopConfig with default values.
type LoopEngine ¶
type LoopEngine struct {
// contains filtered or unexported fields
}
LoopEngine manages the execution of AI development loops. It coordinates with the Copilot SDK, detects completion promises, and handles state transitions.
func NewLoopEngine ¶
func NewLoopEngine(config *LoopConfig, sdk SDKClient) *LoopEngine
NewLoopEngine creates a new loop engine with the given configuration. If sdk is nil, the engine will run in dry-run mode.
func (*LoopEngine) Config ¶
func (e *LoopEngine) Config() *LoopConfig
Config returns the loop configuration.
func (*LoopEngine) Events ¶
func (e *LoopEngine) Events() <-chan any
Events returns a read-only channel for receiving loop events. Subscribers should read from this channel to receive updates.
func (*LoopEngine) Iteration ¶
func (e *LoopEngine) Iteration() int
Iteration returns the current iteration number (1-based). Returns 0 if the loop hasn't started yet.
func (*LoopEngine) Start ¶
func (e *LoopEngine) Start(ctx context.Context) (*LoopResult, error)
Start begins loop execution and runs until completion, failure, or cancellation. It returns the loop result containing statistics and outcome. The provided context can be used to cancel execution externally.
func (*LoopEngine) State ¶
func (e *LoopEngine) State() LoopState
State returns the current loop state.
type LoopFailedEvent ¶
type LoopFailedEvent struct {
// Error is the error that caused the failure.
Error error
// Result contains partial loop result.
Result *LoopResult
}
LoopFailedEvent indicates the loop failed.
func NewLoopFailedEvent ¶
func NewLoopFailedEvent(err error, result *LoopResult) *LoopFailedEvent
NewLoopFailedEvent creates a new LoopFailedEvent.
type LoopResult ¶
LoopResult contains the outcome of loop execution.
type LoopStartEvent ¶
type LoopStartEvent struct {
// Config is the loop configuration.
Config *LoopConfig
}
LoopStartEvent indicates the loop has started.
func NewLoopStartEvent ¶
func NewLoopStartEvent(config *LoopConfig) *LoopStartEvent
NewLoopStartEvent creates a new LoopStartEvent.
type LoopState ¶
type LoopState string
LoopState represents the current state of the loop.
const ( // StateIdle indicates the loop is ready to start. StateIdle LoopState = "idle" // StateRunning indicates the loop is executing iterations. StateRunning LoopState = "running" // StateComplete indicates the loop completed successfully. StateComplete LoopState = "complete" // StateFailed indicates the loop failed. StateFailed LoopState = "failed" // StateCancelled indicates the loop was cancelled. StateCancelled LoopState = "cancelled" )
type PromiseDetectedEvent ¶
type PromiseDetectedEvent struct {
// Phrase is the promise phrase that was detected.
Phrase string
// Source is where the promise was found (e.g., "ai_response", "tool_output").
Source string
// Iteration is the iteration number where promise was found.
Iteration int
}
PromiseDetectedEvent indicates the promise phrase was found.
func NewPromiseDetectedEvent ¶
func NewPromiseDetectedEvent(phrase, source string, iteration int) *PromiseDetectedEvent
NewPromiseDetectedEvent creates a new PromiseDetectedEvent.
type SDKClient ¶
type SDKClient interface {
// Start initializes the SDK client.
Start() error
// Stop closes the SDK client and releases resources.
Stop() error
// CreateSession creates a new SDK session.
// The implementation should initialize any SDK session resources and return an error if it fails.
CreateSession(ctx context.Context) error
// DestroySession destroys the current session.
DestroySession(ctx context.Context) error
// SendPrompt sends a prompt to the AI and returns an event stream.
SendPrompt(ctx context.Context, prompt string) (<-chan sdk.Event, error)
// Model returns the configured AI model name.
Model() string
}
SDKClient defines the interface for the Copilot SDK client. This interface abstracts the SDK implementation for testability.
type ToolExecutionEvent ¶
ToolExecutionEvent indicates a tool was executed.
type ToolExecutionStartEvent ¶
type ToolExecutionStartEvent struct {
ToolEvent
}
ToolExecutionStartEvent indicates a tool execution has started.
func NewToolExecutionStartEvent ¶
func NewToolExecutionStartEvent(toolName string, params map[string]any, iteration int) *ToolExecutionStartEvent
NewToolExecutionStartEvent creates a new ToolExecutionStartEvent.