orchestrator

package
v1.7.2 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

SPDX-License-Identifier: MIT Purpose: Agent abstraction + mock implementation. Real LLM-backed implementations would call a model API; for now, agents can be run in "mock" mode that produces deterministic placeholder output (useful for testing the dispatcher, planner, and aggregator in isolation).

SPDX-License-Identifier: MIT Purpose: aggregator — combines sub-task results into a final response for the user. Validates success, formats output.

SPDX-License-Identifier: MIT Purpose: dispatcher — runs plan tasks in parallel with dependency-aware scheduling. Tasks whose DependsOn are still running block until those complete. Results are merged into a shared scratchpad.

SPDX-License-Identifier: MIT Purpose: small helpers shared across orchestrator files.

SPDX-License-Identifier: MIT Purpose: orchestrator data model — Plan, Task, Agent, Result, ScratchpadEntry.

SPDX-License-Identifier: MIT Purpose: NIMAgent — Agent implementation backed by NVIDIA NIM (any OpenAI-compatible chat/completions endpoint). Reads its system prompt from AgentConfig.SystemFile (searched on disk), pastes prior scratchpad context into the user prompt, calls the LLM, and writes outputs + token usage back to the scratchpad. Env vars: SIN_NIM_API_KEY, SIN_NIM_BASE_URL, SIN_AGENTS_DIR.

SPDX-License-Identifier: MIT Purpose: top-level Orchestrator — wires together Router, Planner, Dispatcher, Registry, Scratchpad, Aggregator. This is the main entry point.

SPDX-License-Identifier: MIT Purpose: planner — turns a user prompt + classified intent into a Plan with ordered sub-tasks, each bound to a specialized agent.

SPDX-License-Identifier: MIT Purpose: agent registry — loads default agents, merges user agents from ~/.config/sin-code/agents/{name}/agent.toml, picks the right agent for a task type. Uses NIMAgent when SIN_NIM_API_KEY is set, MockAgent otherwise.

SPDX-License-Identifier: MIT Purpose: Pre-LLM router — cheap intent classification using keyword heuristics. In production, this would call a Haiku-class model. For now, deterministic keyword scoring is the fallback when no LLM is configured.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultUserAgentsPath 

func DefaultUserAgentsPath() string

func GenerateID 

func GenerateID(prefix string) string

func UseNIM 

func UseNIM() bool

Types

type Agent 

type Agent interface {
	Name() string
	Config() AgentConfig
	Run(ctx context.Context, task *Task, scratch *Scratchpad) (string, error)
}

type AgentConfig 

type AgentConfig struct {
	Name          string   `toml:"name"`
	Description   string   `toml:"description"`
	Type          TaskType `toml:"type"`
	Model         string   `toml:"model"`
	MaxTokens     int      `toml:"max_tokens"`
	Temperature   float64  `toml:"temperature"`
	SystemFile    string   `toml:"system_file"`
	MaxContext    int      `toml:"max_context_tokens"`
	ToolsAllow    []string `toml:"tools_allow"`
	ToolsDeny     []string `toml:"tools_deny"`
	MemoryNS      string   `toml:"memory_namespace"`
	RetentionDays int      `toml:"retention_days"`
}

func DefaultAgents 

func DefaultAgents() []AgentConfig

func LoadUserAgents 

func LoadUserAgents(baseDir string) ([]AgentConfig, error)

type Aggregator 

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

func NewAggregator 

func NewAggregator(scratch *Scratchpad) *Aggregator

func (*Aggregator) Aggregate 

func (a *Aggregator) Aggregate(plan *Plan) *Result

type Dispatcher 

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

func NewDispatcher 

func NewDispatcher(registry *Registry, scratch *Scratchpad, maxParallel int) *Dispatcher

func (*Dispatcher) Dispatch 

func (d *Dispatcher) Dispatch(ctx context.Context, plan *Plan) error

type Intent 

type Intent string
const (
	IntentCodebase     Intent = "codebase_change"
	IntentTest         Intent = "test_work"
	IntentReview       Intent = "code_review"
	IntentDocs         Intent = "documentation"
	IntentSecurity     Intent = "security_audit"
	IntentArchitecture Intent = "architecture"
	IntentGeneral      Intent = "general_query"
)

type MockAgent 

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

func NewMockAgent 

func NewMockAgent(cfg AgentConfig) *MockAgent

func (*MockAgent) Config 

func (m *MockAgent) Config() AgentConfig

func (*MockAgent) Name 

func (m *MockAgent) Name() string

func (*MockAgent) Run 

func (m *MockAgent) Run(ctx context.Context, task *Task, scratch *Scratchpad) (string, error)

type NIMAgent 

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

func NewNIMAgent 

func NewNIMAgent(cfg AgentConfig) *NIMAgent

func NewNIMAgentWithClient 

func NewNIMAgentWithClient(cfg AgentConfig, client *llm.Client) *NIMAgent

func (*NIMAgent) Config added in v1.7.2 

func (n *NIMAgent) Config() AgentConfig

func (*NIMAgent) Name added in v1.7.2 

func (n *NIMAgent) Name() string

func (*NIMAgent) Run added in v1.7.2 

func (n *NIMAgent) Run(ctx context.Context, task *Task, scratch *Scratchpad) (string, error)

type Orchestrator 

type Orchestrator struct {
	Registry    *Registry
	Planner     *Planner
	Dispatcher  *Dispatcher
	Aggregator  *Aggregator
	Scratchpad  *Scratchpad
	MaxParallel int
}

func New 

func New() *Orchestrator

func NewWithAgents 

func NewWithAgents(extraConfigs []AgentConfig) *Orchestrator

func (*Orchestrator) Plan 

func (o *Orchestrator) Plan(prompt string) *Plan

func (*Orchestrator) Run 

func (o *Orchestrator) Run(ctx context.Context, prompt string, opts ...RunOption) (*Result, error)

func (*Orchestrator) String 

func (o *Orchestrator) String() string

type Plan 

type Plan struct {
	ID         string    `json:"id"`
	Prompt     string    `json:"prompt"`
	Intent     Intent    `json:"intent"`
	Tasks      []*Task   `json:"tasks"`
	Created    time.Time `json:"created"`
	Started    time.Time `json:"started"`
	Completed  time.Time `json:"completed"`
	TotalCost  float64   `json:"total_cost"`
	TokensUsed int       `json:"tokens_used"`
	Success    bool      `json:"success"`
}

type Planner 

type Planner struct {
	Router *Router
	Agents []AgentConfig
}

func NewPlanner 

func NewPlanner(agents []AgentConfig) *Planner

func (*Planner) BuildPlan 

func (p *Planner) BuildPlan(prompt string) *Plan

type Registry 

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

func NewRegistry 

func NewRegistry(agents []Agent) *Registry

func NewRegistryWithDefaults 

func NewRegistryWithDefaults(extraConfigs []AgentConfig) *Registry

func (*Registry) ForType 

func (r *Registry) ForType(tt TaskType) (Agent, bool)

func (*Registry) Get 

func (r *Registry) Get(name string) (Agent, bool)

func (*Registry) List 

func (r *Registry) List() []AgentConfig

func (*Registry) Register 

func (r *Registry) Register(a Agent)

type Result 

type Result struct {
	Plan        *Plan
	Sections    map[string]string
	TotalTasks  int
	OKTasks     int
	FailedTasks int
	Summary     string
}

type Router 

type Router struct {
	Keywords map[Intent][]string
}

func NewRouter 

func NewRouter() *Router

func (*Router) Classify 

func (r *Router) Classify(prompt string) Intent

func (*Router) SubIntents 

func (r *Router) SubIntents(prompt string) []Intent

type RunOption 

type RunOption func(*runConfig)

func WithMaxParallel 

func WithMaxParallel(n int) RunOption

func WithTimeout 

func WithTimeout(d time.Duration) RunOption

type Scratchpad 

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

func NewScratchpad 

func NewScratchpad() *Scratchpad

func (*Scratchpad) Merge 

func (s *Scratchpad) Merge(other *Scratchpad)

func (*Scratchpad) Read 

func (s *Scratchpad) Read(section string) (string, bool)

func (*Scratchpad) ReadAll 

func (s *Scratchpad) ReadAll() map[string]*ScratchpadEntry

func (*Scratchpad) Write 

func (s *Scratchpad) Write(agent, section, content string)

type ScratchpadEntry 

type ScratchpadEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Agent     string    `json:"agent"`
	Section   string    `json:"section"`
	Content   string    `json:"content"`
	Version   int       `json:"version"`
}

type Task 

type Task struct {
	ID          string     `json:"id"`
	Type        TaskType   `json:"type"`
	Description string     `json:"description"`
	AgentName   string     `json:"agent"`
	DependsOn   []string   `json:"depends_on,omitempty"`
	Status      TaskStatus `json:"status"`
	Result      string     `json:"result,omitempty"`
	Error       string     `json:"error,omitempty"`
	Created     time.Time  `json:"created"`
	Started     *time.Time `json:"started,omitempty"`
	Completed   *time.Time `json:"completed,omitempty"`
	TokensUsed  int        `json:"tokens_used"`
	Cost        float64    `json:"cost"`
}

type TaskStatus 

type TaskStatus string
const (
	TaskPending   TaskStatus = "pending"
	TaskRunning   TaskStatus = "running"
	TaskCompleted TaskStatus = "completed"
	TaskFailed    TaskStatus = "failed"
	TaskCancelled TaskStatus = "cancelled"
	TaskBlocked   TaskStatus = "blocked"
)

type TaskType 

type TaskType string
const (
	TaskCode      TaskType = "code"
	TaskTest      TaskType = "test"
	TaskReview    TaskType = "review"
	TaskDocs      TaskType = "docs"
	TaskSecurity  TaskType = "security"
	TaskArchitect TaskType = "architect"
	TaskGeneral   TaskType = "general"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.