goal

Documentation

Overview

Package goal implements the session-goal judge: a small LLM call that decides whether the user's active goal has been satisfied by recent assistant activity.

The judge is intentionally narrow and stateless: callers pass the goal description and a window of recent chat messages, and the judge returns a boolean verdict plus a short reason. Errors and unparseable verdicts are treated as "not satisfied" (fail-open: keep working), never as "satisfied", so a judge outage cannot accidentally clear a real goal.

Index

• Constants
• type Judger
• type LLMJudger
  • func NewLLMJudger(router RouterClientFor, role llm.Role) *LLMJudger
  • func (j *LLMJudger) Judge(ctx context.Context, goal string, recent []llm.ChatMessage) (Verdict, error)
• type RouterClientFor
• type Verdict
  • func ParseVerdict(raw string) (Verdict, error)

Constants

const DefaultRecentMessageWindow = 6

DefaultRecentMessageWindow is how many trailing chat messages the judge inspects by default.

const MaxRecentMessageContentChars = 2000

MaxRecentMessageContentChars bounds the per-message content slice sent to the judge so that pathological transcripts cannot inflate the prompt.

Types

type Judger

type Judger interface {
	Judge(ctx context.Context, goal string, recent []llm.ChatMessage) (Verdict, error)
}

Judger reports whether a session goal has been satisfied by the recent chat history. Implementations must be safe for concurrent use.

type LLMJudger

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

LLMJudger calls the configured llm.RoleGoalJudge tier with a small structured prompt and parses the JSON verdict.

func NewLLMJudger

func NewLLMJudger(router RouterClientFor, role llm.Role) *LLMJudger

NewLLMJudger returns a Judger that resolves the goal_judge role on the supplied router. The role override is optional and is exposed mostly for tests; pass an empty string to use llm.RoleGoalJudge.

func (*LLMJudger) Judge

func (j *LLMJudger) Judge(ctx context.Context, goal string, recent []llm.ChatMessage) (Verdict, error)

Judge runs the LLM call. It returns Satisfied=false with a non-nil error when something went wrong (network/parse/etc). Callers should treat any non-nil error as a signal to stop auto-continuing (fail-open).

type RouterClientFor

type RouterClientFor interface {
	ClientFor(role llm.Role) (llm.Client, llm.TierResolution, error)
}

RouterClientFor is the subset of llm.Router that the judge needs. Using a narrow interface keeps judge testable without a full router stub.

type Verdict

type Verdict struct {
	Satisfied bool   `json:"satisfied"`
	Reason    string `json:"reason"`
}

Verdict is the structured output of a judge call.

func ParseVerdict

func ParseVerdict(raw string) (Verdict, error)

ParseVerdict tolerantly extracts a Verdict JSON object from raw text. It strips leading/trailing whitespace and code-fence wrappers and looks for the first balanced `{...}` block. Returns an error if no valid JSON object with a boolean "satisfied" field is found.