orchestrator

package
v1.10.0 Latest Latest
Warning

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

Go to latest
Published: Jun 5, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package orchestrator coordinates multiple agent runners and model routing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentRunner

type AgentRunner interface {
	RunGoal(ctx context.Context, goal string) (string, error)
}

AgentRunner is the interface the orchestrator uses to execute a goal. The real implementation wraps agent.Runner; tests supply fakes.

type DebateManager

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

DebateManager tracks debate turns and produces a verdict.

func NewDebateManager

func NewDebateManager(opts DebateOptions) *DebateManager

NewDebateManager creates a DebateManager with the given options.

func (*DebateManager) AddTurn

func (d *DebateManager) AddTurn(turn DebateTurn)

AddTurn appends a turn to the debate.

func (*DebateManager) MaxRounds

func (d *DebateManager) MaxRounds() int

MaxRounds returns the configured maximum debate rounds.

func (*DebateManager) RoundsCompleted

func (d *DebateManager) RoundsCompleted() int

RoundsCompleted returns the number of full rounds (reviewer + primary) completed.

func (*DebateManager) Turns

func (d *DebateManager) Turns() []DebateTurn

Turns returns all turns added so far.

func (*DebateManager) Verdict

func (d *DebateManager) Verdict(issues []Issue) DebateResult

Verdict produces a DebateResult from the given open issues.

type DebateOptions

type DebateOptions struct {
	MaxRounds int // default 3
}

DebateOptions configures a DebateManager.

type DebateResult

type DebateResult struct {
	Kind   VerdictKind
	Issues []Issue
	Score  float64 // 0.0–1.0; higher = cleaner code
}

DebateResult is the final outcome of all debate rounds.

type DebateRole

type DebateRole int

DebateRole identifies which side is speaking in a review debate.

const (
	RoleReviewer DebateRole = iota
	RolePrimary
)

type DebateTurn

type DebateTurn struct {
	Round  int
	Role   DebateRole
	Input  string
	Output string
}

DebateTurn is one side's contribution to a debate round.

type EventKind

type EventKind int

EventKind identifies the type of an OrchestratorEvent.

const (
	EventClassified  EventKind = iota // goal classified into a task lane
	EventAction                       // agent took a discrete action
	EventToolCall                     // agent called a tool
	EventFileDiff                     // agent wrote or modified a file
	EventReviewDraft                  // reviewer produced a critique
	EventDefense                      // primary agent responded to critique
	EventVerdict                      // reviewer issued a final verdict
	EventComplete                     // orchestrator run finished
	EventError                        // orchestrator run failed
	EventDebateStart                  // debate round beginning (carries round number and reviewer model)
)

type Issue

type Issue struct {
	File        string
	Line        int
	Severity    string // "low", "medium", "high"
	Description string
}

Issue is a code issue raised by the reviewer.

type ModelAssignment

type ModelAssignment struct {
	Primary         string
	PrimaryBaseURL  string
	PrimaryAPIKey   string
	Reviewer        string
	ReviewerBaseURL string
	ReviewerAPIKey  string
}

ModelAssignment describes which models to use for a given run. Per-role BaseURL and APIKey allow cross-provider orchestration.

func (ModelAssignment) HasReviewer

func (m ModelAssignment) HasReviewer() bool

HasReviewer returns true when a non-blank reviewer model is assigned.

type Option

type Option func(*Orchestrator)

Option configures an Orchestrator.

func WithRunnerFactory

func WithRunnerFactory(f RunnerFactory) Option

WithRunnerFactory overrides the AgentRunner factory (useful in tests).

type Orchestrator

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

Orchestrator manages multi-model agent execution.

func New

func New(cfg *config.Config, opts ...Option) *Orchestrator

New creates an Orchestrator backed by the given config.

func (*Orchestrator) OnEvent

func (o *Orchestrator) OnEvent(fn func(OrchestratorEvent))

OnEvent registers a callback for all orchestrator events.

func (*Orchestrator) Run

func (o *Orchestrator) Run(ctx context.Context, goal string) (*Result, error)

Run classifies the goal, routes to models, executes the primary agent, and optionally runs a reviewer debate. Returns the final Result.

type OrchestratorEvent

type OrchestratorEvent struct {
	Kind         EventKind
	Lane         TaskLane
	Text         string        // human-readable description
	Model        string        // model name — non-empty where role matters (primary/reviewer)
	Duration     time.Duration // per-turn API call elapsed time (EventTurnStats)
	InputTokens  int           // prompt tokens for this turn
	OutputTokens int           // completion tokens for this turn
	Response     string        // full assistant response text for this turn (live code output)
	FilePath     string        // non-empty for EventFileDiff
	Diff         string        // unified diff content for EventFileDiff
	Turn         int
	MaxTurns     int
	Score        float64 // 0.0–1.0 for EventVerdict
	VerdictErr   string  // non-empty if verdict is Contested or NeedsWork
}

OrchestratorEvent is emitted by the orchestrator state machine.

type Result

type Result struct {
	Lane    TaskLane
	Primary string        // final response from primary agent
	Verdict *DebateResult // nil when no debate was run
}

Result is the final output of an orchestrator run.

type Router

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

Router maps TaskLanes to ModelAssignments using the user's config.

func NewRouter

func NewRouter(cfg *config.Config) *Router

NewRouter creates a Router backed by the given config.

func (*Router) Resolve

func (r *Router) Resolve(lane TaskLane) (ModelAssignment, error)

Resolve returns the ModelAssignment for the given lane. Falls back to cfg.Model as primary with no reviewer when the lane is unconfigured.

type RunnerFactory

type RunnerFactory func(model string) AgentRunner

RunnerFactory creates an AgentRunner for the given model name.

type TaskLane

type TaskLane string

TaskLane identifies the type of task being performed.

const (
	LaneCode     TaskLane = "code"
	LaneContent  TaskLane = "content"
	LaneMedia    TaskLane = "media"
	LaneReview   TaskLane = "review"
	LaneResearch TaskLane = "research"
	LaneUnknown  TaskLane = "unknown"
)

func ClassifyHeuristic

func ClassifyHeuristic(goal string) (TaskLane, float64)

ClassifyHeuristic returns the best-guess TaskLane and a confidence score (0.0–1.0) based purely on keyword matching. Confidence < 0.5 means the goal is ambiguous.

type VerdictKind

type VerdictKind int

VerdictKind is the outcome of a review debate.

const (
	VerdictApproved VerdictKind = iota
	VerdictNeedsWork
	VerdictContested
)

func (VerdictKind) String

func (v VerdictKind) String() string

Jump to

Keyboard shortcuts

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