core

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Apr 26, 2026 License: MIT Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrLoopCancelled = errors.New("loop cancelled")

ErrLoopCancelled indicates the loop was cancelled by the user.

View Source
var ErrLoopTimeout = errors.New("loop timeout exceeded")

ErrLoopTimeout indicates the loop exceeded the configured timeout.

View Source
var ErrMaxIterations = errors.New("maximum iterations reached")

ErrMaxIterations indicates the maximum iterations were reached.

Functions

func BuildSystemPrompt

func BuildSystemPrompt(promisePhrase string) string

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

type LoopResult struct {
	Error      error
	State      LoopState
	Iterations int
	Duration   time.Duration
}

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"
)

func (LoopState) String

func (s LoopState) String() string

String returns the string representation of the state.

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 ToolEvent

type ToolEvent struct {
	Parameters map[string]any
	ToolName   string
	Iteration  int
}

ToolEvent describes a tool invocation request observed by the loop engine.

func (*ToolEvent) Info

func (e *ToolEvent) Info(emoji string) string

Info returns a formatted string describing the tool execution based on parameters. This provides human-readable information about what the tool is doing.

type ToolExecutionEvent

type ToolExecutionEvent struct {
	Error error
	ToolEvent
	Result   string
	Duration time.Duration
}

ToolExecutionEvent indicates a tool was executed.

func NewToolExecutionEvent

func NewToolExecutionEvent(toolName string, params map[string]any, result string, err error, duration time.Duration, iteration int) *ToolExecutionEvent

NewToolExecutionEvent creates a new ToolExecutionEvent.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL