models

package
v0.1.14 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package models defines shared types used across the Samverk system.

Index

Constants

View Source 
const SchemaVersion = "1.0.0"

SchemaVersion is the current issue schema version.

Variables

This section is empty.

Functions

func FormatDuration added in v0.1.14 

func FormatDuration(d time.Duration) string

FormatDuration returns a human-friendly string for a time.Duration. Examples: "just now", "5m", "2h", "3d".

func IsEven added in v0.1.11 

func IsEven(n int) bool

IsEven returns true if n is divisible by 2.

func IsOdd added in v0.1.11 

func IsOdd(n int) bool

IsOdd returns true if n is not divisible by 2.

func RenderFrontmatter 

func RenderFrontmatter(fm *IssueFrontmatter, markdown string) string

RenderFrontmatter produces an issue body with YAML frontmatter followed by markdown.

Types

type AgentType 

type AgentType string

AgentType identifies which agent pool should handle an issue. 

const (
	AgentTypeOrchestrator AgentType = "orchestrator"
	AgentTypeDispatcher   AgentType = "dispatcher"
	AgentTypeCodeGen      AgentType = "code-gen"
	AgentTypeTest         AgentType = "test"
	AgentTypeDocs         AgentType = "docs"
	AgentTypeResearch     AgentType = "research"
	AgentTypeQC           AgentType = "qc"
	AgentTypeHuman        AgentType = "human"
	AgentTypeInfra        AgentType = "infra"
	AgentTypePC           AgentType = "pc"
)

type Complexity 

type Complexity string

Complexity hints at whether work should run locally or in the cloud. 

const (
	ComplexityLocal     Complexity = "local"
	ComplexityCloud     Complexity = "cloud"
	ComplexityAmbiguous Complexity = "ambiguous"
)

type CostRecord 

type CostRecord struct {
	ID           string    `json:"id"`
	SessionID    string    `json:"session_id"`
	Provider     string    `json:"provider"`
	Model        string    `json:"model"`
	InputTokens  int       `json:"input_tokens"`
	OutputTokens int       `json:"output_tokens"`
	CostUSD      float64   `json:"cost_usd"` // 0 for local models
	CreatedAt    time.Time `json:"created_at"`
}

CostRecord tracks token usage for a single API call.

type CostSummary 

type CostSummary struct {
	TotalInputTokens  int     `json:"total_input_tokens"`
	TotalOutputTokens int     `json:"total_output_tokens"`
	TotalCostUSD      float64 `json:"total_cost_usd"`
	RecordCount       int     `json:"record_count"`
}

CostSummary aggregates cost data over a time period.

type FailureClass added in v0.1.14 

type FailureClass string

FailureClass categorises a failure into an actionable class for circuit breakers and automated analysis. 

const (
	FailureClassAuth         FailureClass = "auth"          // 401, OAuth expired, authentication_error
	FailureClassBudget       FailureClass = "budget"        // credit/budget exhausted
	FailureClassPermanent    FailureClass = "permanent"     // model not found, permanent config error
	FailureClassTimeout      FailureClass = "timeout"       // heartbeat timeout / context deadline
	FailureClassProviderDown FailureClass = "provider_down" // connection refused, provider unreachable
	FailureClassOOMKill      FailureClass = "oom_kill"      // signal: killed (OOM or external)
	FailureClassShutdown     FailureClass = "shutdown"      // exit 143 (SIGTERM during graceful shutdown)
	FailureClassPanic        FailureClass = "panic"         // send on closed channel, runtime panic
	FailureClassPostProcess  FailureClass = "post_process"  // PR creation, comment posting failed
	FailureClassClassify     FailureClass = "classify"      // frontmatter parse or agent type validation
	FailureClassCycle        FailureClass = "cycle"         // dependency cycle detected
	FailureClassDecompose    FailureClass = "decompose"     // issue decomposition failed
	FailureClassUnknown      FailureClass = "unknown"       // unrecognised error pattern
)

func (FailureClass) IsPermanent added in v0.1.14 

func (fc FailureClass) IsPermanent() bool

IsPermanent returns true if retrying will never succeed.

func (FailureClass) IsRetryable added in v0.1.14 

func (fc FailureClass) IsRetryable() bool

IsRetryable returns true if this failure class warrants a retry attempt.

type FailureEvent added in v0.1.14 

type FailureEvent struct {
	ID            string        `json:"id"`
	IssueNumber   int           `json:"issue_number"`
	SessionID     string        `json:"session_id,omitempty"` // empty for dispatcher-level failures
	FailureClass  FailureClass  `json:"failure_class"`
	ErrorMessage  string        `json:"error_message"`
	AgentType     string        `json:"agent_type,omitempty"`
	Provider      string        `json:"provider,omitempty"`
	AttemptNumber int           `json:"attempt_number"` // which attempt (1st, 2nd, 3rd, etc.)
	Duration      time.Duration `json:"duration_ms,omitempty"`
	Timestamp     time.Time     `json:"timestamp"`
}

FailureEvent represents a single failure occurrence in the dispatcher or agent runtime. Every failure path emits one of these to the store for aggregation and analysis.

type FailureSummary added in v0.1.14 

type FailureSummary struct {
	TotalFailures  int                  `json:"total_failures"`
	ByClass        map[FailureClass]int `json:"by_class"`
	TopIssues      []IssueFailureCount  `json:"top_issues"`      // issues with most failures
	LoopingIssues  []IssueFailureCount  `json:"looping_issues"`  // issues with 5+ failures
	ProviderHealth map[string]int       `json:"provider_health"` // provider -> failure count
	Since          time.Time            `json:"since"`
}

FailureSummary aggregates failure data for dashboards and digests.

type IssueFailureCount added in v0.1.14 

type IssueFailureCount struct {
	IssueNumber int `json:"issue_number"`
	Count       int `json:"count"`
}

IssueFailureCount pairs an issue number with its failure count.

type IssueFrontmatter 

type IssueFrontmatter struct {
	SchemaVersion   string    `yaml:"schema_version"`
	Type            IssueType `yaml:"type"`
	AgentType       AgentType `yaml:"agent_type"`
	Priority        Priority  `yaml:"priority"`
	ParentIssue     int       `yaml:"parent_issue,omitempty"`
	DependsOn       []int     `yaml:"depends_on,omitempty"`
	EstimatedTokens int       `yaml:"estimated_tokens,omitempty"`
	ActualTokens    int       `yaml:"actual_tokens,omitempty"`
	ModelUsed       string    `yaml:"model_used,omitempty"`
	TimeoutMinutes  int       `yaml:"timeout_minutes,omitempty"`
}

IssueFrontmatter represents the YAML frontmatter parsed from an issue body.

type IssueType 

type IssueType string

IssueType identifies the communication purpose of an issue. 

const (
	IssueTypeTask     IssueType = "task"
	IssueTypeQuestion IssueType = "question"
	IssueTypeResult   IssueType = "result"
	IssueTypeBlock    IssueType = "block"
)

type ParseResult 

type ParseResult struct {
	Frontmatter *IssueFrontmatter
	Body        string // markdown after the closing ---
}

ParseResult holds the parsed frontmatter and remaining body text.

func ParseFrontmatter 

func ParseFrontmatter(body string) (*ParseResult, error)

ParseFrontmatter extracts YAML frontmatter from an issue body. The frontmatter must be delimited by --- on its own line at the start of the body. Returns error if frontmatter is present but malformed. Returns nil Frontmatter (no error) if no frontmatter block exists.

type Priority 

type Priority string

Priority determines scheduling order. 

const (
	PriorityCritical Priority = "critical"
	PriorityHigh     Priority = "high"
	PriorityNormal   Priority = "normal"
	PriorityLow      Priority = "low"
)

type ScalingControl added in v0.1.11 

type ScalingControl struct {
	Paused        bool
	ManualWorkers int
	SetAt         time.Time
	Note          string
}

ScalingControl is a single-row record that holds manual override state written by the REST API or CLI and consumed by the autoscaler on each evaluation cycle. ManualWorkers == 0 means no manual target is set. Paused == true means the autoscaler should hold (take no autonomous action).

type ScalingEvent added in v0.1.11 

type ScalingEvent struct {
	ID          string
	Timestamp   time.Time
	Action      string // "scale-up" | "scale-down" | "manual-override"
	FromWorkers int
	ToWorkers   int
	Reason      string
	Confidence  float64
}

ScalingEvent records a single autoscaler decision.

type Session 

type Session struct {
	ID               string        `json:"id"`
	IssueNumber      int           `json:"issue_number"`
	AgentType        string        `json:"agent_type"` // e.g., "code-gen", "qc", "research"
	Provider         string        `json:"provider"`   // e.g., "ollama", "claude", "openai"
	Model            string        `json:"model"`      // e.g., "qwen2.5-coder:7b"
	Status           SessionStatus `json:"status"`
	StartedAt        time.Time     `json:"started_at"`
	FinishedAt       *time.Time    `json:"finished_at,omitempty"`
	Error            string        `json:"error,omitempty"`
	EstimatedTimeout time.Duration `json:"estimated_timeout_ms,omitempty"` // timeout predicted at dispatch time
	PartialOutput    string        `json:"partial_output,omitempty"`       // last checkpoint of streaming output
	CheckpointHash   string        `json:"checkpoint_hash,omitempty"`      // SHA-256 of posted checkpoint for dedup
	CreatedAt        time.Time     `json:"created_at"`
	UpdatedAt        time.Time     `json:"updated_at"`
}

Session represents a unit of agent work on an issue.

type SessionStatus 

type SessionStatus string

SessionStatus represents the lifecycle state of a work session. 

const (
	SessionStatusPending   SessionStatus = "pending"
	SessionStatusActive    SessionStatus = "active"
	SessionStatusCompleted SessionStatus = "completed"
	SessionStatusFailed    SessionStatus = "failed"
	SessionStatusCancelled SessionStatus = "cancelled"
)

type Status 

type Status string

Status tracks the lifecycle state of an issue. 

const (
	StatusQueued       Status = "queued"
	StatusClaimed      Status = "claimed"
	StatusInProgress   Status = "in-progress"
	StatusBlocked      Status = "blocked"
	StatusNeedsQC      Status = "needs-qc"
	StatusNeedsHuman   Status = "needs-human"
	StatusHumanPending Status = "human-pending"
	StatusDone         Status = "done"
)

type TaskProfile added in v0.1.11 

type TaskProfile struct {
	AgentType   string        `json:"agent_type"`
	Provider    string        `json:"provider"`
	AvgDuration time.Duration `json:"avg_duration"`
	P50Duration time.Duration `json:"p50_duration"`
	P90Duration time.Duration `json:"p90_duration"`
	SampleCount int           `json:"sample_count"`
	AvgTokens   int           `json:"avg_tokens"`
	UpdatedAt   time.Time     `json:"updated_at"`
}

TaskProfile holds rolling performance statistics for a specific (AgentType, Provider) combination, computed from completed sessions. Values are updated after each successful task completion.

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.