goal

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
const (

	// MaxConditionChars is the maximum number of Unicode characters in a Goal
	// condition.
	MaxConditionChars = 4000
)

Variables

View Source
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
	// Transcript is the bounded rendering of the session conversation the
	// assessment reads. It is untrusted data, and it is empty when the embedder
	// supplies none.
	Transcript string
	// Plan is the Goal's plan text as the assessment receives it. A Goal with no
	// plan artifact carries a placeholder rather than nothing.
	Plan       string
	Attempt    int
	Activation *continuation.Activation
	Limits     continuation.Limits
	Accounting continuation.Accounting
	Previous   *EvaluationRecord
}

Evaluation is the immutable input to an Evaluator.

type EvaluationRecord

type EvaluationRecord struct {
	Outcome    Outcome `json:"outcome"`
	Reason     string  `json:"reason"`
	NextStep   string  `json:"next_step,omitempty"`
	BlockerKey string  `json:"blocker_key,omitempty"`
}

EvaluationRecord is the bounded durable projection of one evaluation.

type EvaluationResult

type EvaluationResult struct {
	Outcome Outcome
	Reason  string
	// NextStep is the single best next action the evaluation named. It is
	// required for a blocked decision, where the block message hands it to the
	// user, and optional otherwise.
	NextStep string
	// BlockerKey identifies the blocker a blocked decision named, so the same
	// blocker can be counted across rounds.
	BlockerKey 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. An answer it cannot use — not one JSON object, an unknown decision, a field outside the document's contract, or a response with no usage — is attempted once more, exactly as the reference's evaluation round is; a second unusable answer is returned as an error so the Goal stops for the user instead of continuing on a guess. A transport failure is not retried here, because the model middleware already owns that.

type ModelEvaluatorOption

type ModelEvaluatorOption func(*modelEvaluatorConfig) error

ModelEvaluatorOption configures a ModelEvaluator.

func WithMaxTokens

func WithMaxTokens(maxTokens int) ModelEvaluatorOption

WithMaxTokens caps one evaluator response. The cap is opt-in: without it the request carries none and the provider's own default applies, because a model that reasons before answering must not be cut off mid-answer. The Goal's own token budget still bounds the run.

type Outcome

type Outcome string

Outcome is an Evaluator's completion decision.

const (
	OutcomeContinue Outcome = "continue"
	// OutcomeComplete is a candidate completion: the deliverable looks complete
	// enough to verify. Its spelling is the reference's own decision value.
	OutcomeComplete Outcome = "candidate_complete"
	OutcomeBlocked  Outcome = "blocked"
)

Goal evaluation outcomes.

type Setup

type Setup struct {
	ControllerState ai.JSON
	WorkInput       ai.JSON
}

Setup contains the two payloads required to create a Goal continuation execution.

func Prepare

func Prepare(condition string) (Setup, error)

Prepare validates a condition and creates its initial durable state and Worker input.

type State

type State struct {
	Version     int               `json:"version"`
	Condition   string            `json:"condition"`
	Evaluations int               `json:"evaluations"`
	Last        *EvaluationRecord `json:"last,omitempty"`
	// BlockerKey is the blocker the last blocked evaluation named and
	// BlockerStreak is how many consecutive evaluations named it, so only a
	// repeated declaration of the same blocker blocks the Goal. Both fields are
	// additive: a state written before them decodes with no key and a zero streak.
	BlockerKey    string `json:"blocker_key,omitempty"`
	BlockerStreak int    `json:"blocker_streak,omitempty"`
}

State is the versioned Goal projection stored as continuation ControllerState.

func DecodeState

func DecodeState(data ai.JSON) (State, error)

DecodeState validates and decodes Goal ControllerState.

type WorkInput

type WorkInput struct {
	Kind       string  `json:"kind"`
	Condition  string  `json:"condition"`
	Evaluation int     `json:"evaluation"`
	Reason     string  `json:"reason,omitempty"`
	Feedback   ai.JSON `json:"feedback,omitempty"`
}

WorkInput is the stable Goal envelope supplied to one Worker invocation.

func DecodeWorkInput

func DecodeWorkInput(data ai.JSON) (WorkInput, error)

DecodeWorkInput validates and decodes a Goal Worker input envelope.

Jump to

Keyboard shortcuts

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