Documentation
¶
Overview ¶
Package goal provides evidence-based completion policies for continuation executions.
A Controller evaluates one durable Work result and decides whether the same execution should continue, complete, or block. The package owns no scheduler, lifecycle store, conversation, or background goroutine.
Index ¶
Examples ¶
Constants ¶
const ( // MaxConditionChars is the maximum number of Unicode characters in a Goal // condition. MaxConditionChars = 4000 )
Variables ¶
var ( ErrInvalid = errors.New("goal: invalid value") ErrTooLarge = errors.New("goal: value too large") )
Goal validation errors.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller maps evidence evaluations onto continuation lifecycle actions.
Example ¶
package main
import (
"context"
"fmt"
"github.com/rsbin1178/pips/agent/continuation"
"github.com/rsbin1178/pips/agent/goal"
"github.com/rsbin1178/pips/ai"
)
type exampleWorker func(context.Context, continuation.WorkRequest) (continuation.WorkResult, error)
func (worker exampleWorker) Run(
ctx context.Context,
request continuation.WorkRequest,
) (continuation.WorkResult, error) {
return worker(ctx, request)
}
func main() {
setup, _ := goal.Prepare("tests pass")
controller, _ := goal.NewController(goal.EvaluatorFunc(func(
_ context.Context,
evaluation goal.Evaluation,
) (goal.EvaluationResult, error) {
if string(evaluation.Evidence) == `{"tests":"pass"}` {
return goal.EvaluationResult{
Outcome: goal.OutcomeComplete, Reason: "test evidence is passing",
}, nil
}
return goal.EvaluationResult{
Outcome: goal.OutcomeContinue, Reason: "passing test evidence is missing",
}, nil
}))
store, _ := continuation.NewMemoryStore()
engine, _ := continuation.New(store)
workerRef := continuation.HandlerRef{Kind: "test-worker", Version: "v1"}
controllerRef := continuation.HandlerRef{Kind: "goal", Version: "v1"}
execution, _ := engine.Create(context.Background(), continuation.CreateRequest{
ID: "release-goal", Target: continuation.Target{Kind: "session", ID: "release-1"},
Worker: workerRef, Controller: controllerRef,
ControllerState: setup.ControllerState, Input: setup.WorkInput,
})
finished, _ := engine.Advance(context.Background(), execution.ID, execution.Revision, continuation.Handlers{
WorkerRef: workerRef,
Worker: exampleWorker(func(context.Context, continuation.WorkRequest) (continuation.WorkResult, error) {
return continuation.WorkResult{
Value: ai.JSON(`{"tests":"pass"}`), Progress: continuation.ProgressChanged,
}, nil
}),
ControllerRef: controllerRef, Controller: controller,
})
fmt.Println(finished.Status, finished.Reason)
}
Output: completed test evidence is passing
func NewController ¶
func NewController(evaluator Evaluator) (*Controller, error)
NewController constructs a Goal Controller.
func (*Controller) Decide ¶
func (controller *Controller) Decide( ctx context.Context, request continuation.DecisionRequest, ) (continuation.Decision, error)
Decide implements continuation.Controller.
type Evaluation ¶
type Evaluation struct {
Condition string
Evidence ai.JSON
Attempt int
Activation *continuation.Activation
Limits continuation.Limits
Accounting continuation.Accounting
Previous *EvaluationRecord
}
Evaluation is the immutable input to an Evaluator.
type EvaluationRecord ¶
EvaluationRecord is the bounded durable projection of one evaluation.
type EvaluationResult ¶
type EvaluationResult struct {
Outcome Outcome
Reason string
Feedback ai.JSON
Output ai.JSON
Block *continuation.Block
Usage ai.Usage
}
EvaluationResult controls the Goal action after one Work result.
type Evaluator ¶
type Evaluator interface {
Evaluate(context.Context, Evaluation) (EvaluationResult, error)
}
Evaluator decides whether durable Work evidence satisfies a Goal condition.
type EvaluatorFunc ¶
type EvaluatorFunc func(context.Context, Evaluation) (EvaluationResult, error)
EvaluatorFunc adapts a function to Evaluator.
func (EvaluatorFunc) Evaluate ¶
func (function EvaluatorFunc) Evaluate( ctx context.Context, evaluation Evaluation, ) (EvaluationResult, error)
Evaluate implements Evaluator.
type ModelEvaluator ¶
type ModelEvaluator struct {
// contains filtered or unexported fields
}
ModelEvaluator evaluates Goal evidence with one structured model call and no tools.
func NewModelEvaluator ¶
func NewModelEvaluator( model ai.LanguageModel, options ...ModelEvaluatorOption, ) (*ModelEvaluator, error)
NewModelEvaluator constructs a provider-neutral Goal evaluator.
func (*ModelEvaluator) Evaluate ¶
func (evaluator *ModelEvaluator) Evaluate( ctx context.Context, evaluation Evaluation, ) (EvaluationResult, error)
Evaluate implements Evaluator.
type ModelEvaluatorOption ¶
type ModelEvaluatorOption func(*modelEvaluatorConfig) error
ModelEvaluatorOption configures a ModelEvaluator.
func WithMaxTokens ¶
func WithMaxTokens(maxTokens int) ModelEvaluatorOption
WithMaxTokens bounds one evaluator response.
type State ¶
type State struct {
Version int `json:"version"`
Condition string `json:"condition"`
Evaluations int `json:"evaluations"`
Last *EvaluationRecord `json:"last,omitempty"`
}
State is the versioned Goal projection stored as continuation ControllerState.
Source Files