tot

Documentation

Index

• func BuildAssessPrompt(p agent.Personality, state *game.State, validActions []ActionOption, ...) string
• func BuildEvaluatePrompt(p agent.Personality, state *game.State, situation string, option AssessOption, ...) string
• type ActionOption
  • func ValidActions(state *game.State) []ActionOption
• type AssessOption
• type AssessResponse
• type AxisScores
• type AxisWeights
  • func DeriveWeights(p agent.Personality) AxisWeights
  • func (w AxisWeights) WeightedScore(s AxisScores) float64
• type ConnectedSystem
• type EvaluateResponse
• type Evaluator
  • func NewEvaluator(llm LLMGenerator, model string) *Evaluator
  • func (e *Evaluator) Evaluate(ctx context.Context, personality agent.Personality, state *game.State, ...) (*ThoughtTree, error)
  • func (e *Evaluator) SetOnUpdate(cb UpdateCallback)
• type LLMGenerator
• type NodeStatus
• type PlanStep
• type PromptContext
• type RunnerAdapter
  • func (a *RunnerAdapter) EvaluateToT(ctx context.Context, personality agent.Personality, es agent.EnrichedState, ...) (agent.Decision, any, error)
• type ThoughtNode
• type ThoughtTree
  • func (tree *ThoughtTree) ToDecision() agent.Decision
• type UpdateCallback

Functions

func BuildAssessPrompt

func BuildAssessPrompt(p agent.Personality, state *game.State, validActions []ActionOption, pctx *PromptContext) string

BuildAssessPrompt constructs the Stage 1 prompt with full context.

func BuildEvaluatePrompt

func BuildEvaluatePrompt(p agent.Personality, state *game.State, situation string, option AssessOption, validActions []ActionOption) string

BuildEvaluatePrompt constructs a Stage 2 prompt for one option.

Types

type ActionOption

type ActionOption struct {
	Action      string   `json:"action"`
	Description string   `json:"description"`
	Targets     []string `json:"targets,omitempty"`
}

ActionOption represents a valid action the agent can take right now.

func ValidActions

func ValidActions(state *game.State) []ActionOption

ValidActions returns the set of actions that are valid for the current game state. Action names MUST match the cases in pkg/agent/runner.go executeDecision().

type AssessOption

type AssessOption struct {
	Action    string `json:"action"`
	Target    string `json:"target"`
	Rationale string `json:"rationale"`
}

AssessOption is one option returned by Stage 1.

type AssessResponse

type AssessResponse struct {
	Situation string         `json:"situation"`
	Options   []AssessOption `json:"options"`
}

AssessResponse is the parsed Stage 1 LLM output.

type AxisScores

type AxisScores struct {
	Survival     float64 `json:"survival"`
	Profit       float64 `json:"profit"`
	GoalProgress float64 `json:"goal_progress"`
	Risk         float64 `json:"risk"`
	Efficiency   float64 `json:"efficiency"`
}

AxisScores holds multi-criteria evaluation scores (0-100 scale).

type AxisWeights

type AxisWeights struct {
	Survival     float64 `json:"survival"`
	Profit       float64 `json:"profit"`
	GoalProgress float64 `json:"goal_progress"`
	Risk         float64 `json:"risk"`
	Efficiency   float64 `json:"efficiency"`
}

AxisWeights holds personality-derived weights for scoring (0-1 scale).

func DeriveWeights

func DeriveWeights(p agent.Personality) AxisWeights

DeriveWeights computes AxisWeights from an agent's personality traits and motivations. All returned weights are in the [0, 1] range.

func (AxisWeights) WeightedScore

func (w AxisWeights) WeightedScore(s AxisScores) float64

WeightedScore computes the combined score for an AxisScores using these weights.

type ConnectedSystem

type ConnectedSystem struct {
	ID       string
	Name     string
	Security string // "High Security", "Medium Security", "Low Security", "Lawless"
	Distance int
	Notes    string // e.g., "has asteroid belts", "visited before", "unknown"
}

ConnectedSystem holds enriched info about a system reachable by jump.

type EvaluateResponse

type EvaluateResponse struct {
	Action   string     `json:"action"`
	Target   string     `json:"target"`
	Analysis string     `json:"analysis"`
	Scores   AxisScores `json:"scores"`
	Plan     []PlanStep `json:"plan"`
	// Legacy single next_step — converted to Plan if present
	NextStep struct {
		Action string `json:"action"`
		Target string `json:"target"`
	} `json:"next_step"`
}

EvaluateResponse is the parsed Stage 2 LLM output.

type Evaluator

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

Evaluator orchestrates the three-stage Thought Engine pipeline.

func NewEvaluator

func NewEvaluator(llm LLMGenerator, model string) *Evaluator

NewEvaluator creates a new Evaluator with the given LLM generator and model name.

func (*Evaluator) Evaluate

func (e *Evaluator) Evaluate(
	ctx context.Context,
	personality agent.Personality,
	state *game.State,
	validActions []ActionOption,
	weights AxisWeights,
	pctx *PromptContext,
) (*ThoughtTree, error)

Evaluate runs the full pipeline: Assess → Evaluate (parallel) → Select.

func (*Evaluator) SetOnUpdate

func (e *Evaluator) SetOnUpdate(cb UpdateCallback)

SetOnUpdate sets a callback that fires with partial tree state as the pipeline progresses.

type LLMGenerator

type LLMGenerator interface {
	Generate(ctx context.Context, prompt string) (string, error)
}

LLMGenerator is the interface for making LLM calls.

type NodeStatus

type NodeStatus string

NodeStatus represents the state of a thought node in the tree.

const (
	StatusPending    NodeStatus = "pending"    // stub node, not yet evaluated
	StatusEvaluating NodeStatus = "evaluating" // currently being evaluated by LLM
	StatusActive     NodeStatus = "active"     // evaluated, has scores
	StatusPruned     NodeStatus = "pruned"     // did not win selection
	StatusWinner     NodeStatus = "winner"     // selected as best option
)

type PlanStep

type PlanStep struct {
	Action string `json:"action"`
	Target string `json:"target"`
}

PlanStep is one step in a multi-action plan.

type PromptContext

type PromptContext struct {
	// RecentActions is the last N actions taken (most recent first).
	RecentActions []agent.HistoryEntry

	// Goal is the agent's current strategic goal.
	Goal *agent.Goal

	// Priority is the agent's current priority and constraints.
	Priority *agent.Priority

	// BiographyExcerpt is a short excerpt from the personality biography
	// that captures the agent's character and decision-making style.
	BiographyExcerpt string

	// SystemSecurity is the security level of the current system
	// ("High Security", "Medium Security", "Low Security", "Lawless").
	SystemSecurity string

	// QueuedPlan is the current action queue (from a previous ToT evaluation).
	// Shown in the prompt so the LLM knows what's already planned.
	QueuedPlan []agent.PlannedAction

	// ConnectedSystemInfo provides enriched info about neighboring systems.
	ConnectedSystemInfo []ConnectedSystem
}

PromptContext carries additional context beyond personality and game state that enriches the ToT prompts with memory, goals, and strategic context.

type RunnerAdapter

type RunnerAdapter struct {
	Eval     *Evaluator
	OnUpdate func(agentID string, eventType string, data any) // wired to runner.emitEvent
}

RunnerAdapter wraps an Evaluator to satisfy agent.ToTEvaluator. This bridges the circular import between pkg/agent and pkg/tot.

func (*RunnerAdapter) EvaluateToT

func (a *RunnerAdapter) EvaluateToT(ctx context.Context, personality agent.Personality, es agent.EnrichedState, totCtx *agent.ToTContext) (agent.Decision, any, error)

EvaluateToT implements agent.ToTEvaluator.

type ThoughtNode

type ThoughtNode struct {
	ID          string         `json:"id"`
	Action      string         `json:"action"`
	Target      string         `json:"target"`
	Reasoning   string         `json:"reasoning"`
	Scores      AxisScores     `json:"scores"`
	Combined    float64        `json:"combined"`
	Status      NodeStatus     `json:"status"`
	Children    []*ThoughtNode `json:"children,omitempty"`
	Depth       int            `json:"depth"`
	EvalTime    time.Duration  `json:"eval_time_ms"`
	Prompt      string         `json:"prompt,omitempty"`
	RawResponse string         `json:"raw_response,omitempty"`
}

ThoughtNode represents one option in the decision tree.

type ThoughtTree

type ThoughtTree struct {
	ID        string         `json:"id"`
	AgentID   string         `json:"agent_id"`
	Timestamp time.Time      `json:"timestamp"`
	Situation string         `json:"situation"`
	Stage     string         `json:"stage"` // assessing, evaluating N/M, selecting, complete
	Root      []*ThoughtNode `json:"root"`
	WinnerID  string         `json:"winner_id"`
	Duration  time.Duration  `json:"duration_ms"`
	Model     string         `json:"model"`
	Weights   AxisWeights    `json:"weights"`
}

ThoughtTree holds the complete decision tree for one cycle.

func (*ThoughtTree) ToDecision

func (tree *ThoughtTree) ToDecision() agent.Decision

ToDecision converts the winning branch to an agent.Decision.

type UpdateCallback

type UpdateCallback func(tree *ThoughtTree)

UpdateCallback is called with a partial ThoughtTree as each stage progresses.