evaluator

type BackgroundState struct {
	// Started is true once RunBackground was called (the goroutine exists).
	Started bool `json:"started"`
	// Primary is whether this instance owned the DB writer at the last tick.
	Primary bool `json:"primary"`
	// BackfillDone is true once the one-shot startup backfill ran.
	BackfillDone bool `json:"backfill_done"`
	// BackfillEvaluated is how many sessions the startup backfill scored.
	BackfillEvaluated int `json:"backfill_evaluated"`
	// LastSweepAt is the unix time of the last idle sweep (0 = none yet).
	LastSweepAt int64 `json:"last_sweep_at"`
	// LastSweepEvaluated is how many sessions the last idle sweep scored.
	LastSweepEvaluated int `json:"last_sweep_evaluated"`
}

type Breakdown struct {
	// Components holds the score of every component that was available.
	Components map[string]float64 `json:"components"`
	// Weights holds the weight applied to each available component.
	Weights map[string]float64 `json:"weights"`
	// PatternHits are the user turns flagged as corrections.
	PatternHits []PatternHit `json:"patternHits,omitempty"`
	// Feedback is the explicit user rating ("good"/"bad") when present.
	Feedback     string `json:"feedback,omitempty"`
	FeedbackNote string `json:"feedbackNote,omitempty"`
	// Raw counters behind the components.
	UserTurns  int `json:"userTurns"`
	ToolCalls  int `json:"toolCalls"`
	ToolErrors int `json:"toolErrors"`
	Cancels    int `json:"cancels"`
	Repeats    int `json:"repeats"`
	// Baseline is the mean token count of recent sessions (0 when unknown).
	Baseline float64 `json:"baseline,omitempty"`
	// WeightedTotal is the total before any explicit-feedback override.
	WeightedTotal float64 `json:"weightedTotal"`
}

type ComponentScore struct {
	Name   string
	Score  float64
	Weight float64
}

type ContextProfile struct {
	// TaskType is the classified task type (e.g. "code", "debug", "refactor").
	TaskType string
	// RelevantToolNames lists the tool names to keep for this task.
	// An empty slice means keep all tools (no filtering).
	RelevantToolNames []string
	// SkipSections lists prompt section names that are not needed for this task.
	SkipSections []string
	// Confidence is a 0.0–1.0 measure of the trimmer's certainty.
	// Profiles with Confidence < 0.5 should be ignored and defaults used.
	Confidence float64
}

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

type DailyMetric struct {
	Day                   string  `json:"day"`
	Evaluations           int64   `json:"evaluations"`
	AvgReward             float64 `json:"avg_reward"`
	JudgeCalls            int64   `json:"judge_calls"`
	JudgePromptTokens     int64   `json:"judge_prompt_tokens"`
	JudgeCompletionTokens int64   `json:"judge_completion_tokens"`
}

type DiagnoseOptions struct {
	// Config is the evaluator config as loaded (not defaulted).
	Config config.EvaluatorConfig
	// DB reads sessions and scores; nil skips the database checks.
	DB db.Querier
	// Service is the running evaluator, when there is one in this process. It
	// supplies the in-memory failures and the background worker state.
	Service *EvaluatorService
	// WorkDir is the project directory (variants, learned skills).
	WorkDir string
	// Now overrides the clock (tests).
	Now time.Time
}

type DoctorBackground struct {
	IdleTimeout      string `json:"idle_timeout"`
	BackfillLimit    int    `json:"backfill_limit"`
	IncludeSubagents bool   `json:"include_subagents"`
	// Known is true when the report came from a process running the workers.
	Known bool `json:"known"`
	BackgroundState
}

type DoctorError struct {
	Message string `json:"message"`
	At      int64  `json:"at"`
}

type DoctorJudge struct {
	// Configured is true when a judge model is set and the judge initialised
	// (or, without a service, when a model is set).
	Configured          bool         `json:"configured"`
	HighReward          float64      `json:"high_reward"`
	LowReward           float64      `json:"low_reward"`
	MinTurns            int          `json:"min_turns"`
	DailyCalls          int          `json:"daily_calls"`
	DailyTokens         int64        `json:"daily_tokens"`
	CallsToday          int64        `json:"calls_today"`
	TokensToday         int64        `json:"tokens_today"`
	BudgetExhausted     bool         `json:"budget_exhausted"`
	LastError           *DoctorError `json:"last_error,omitempty"`
	BackfillJudge       bool         `json:"backfill_judge"`
	MaxTranscriptTokens int          `json:"max_transcript_tokens"`
}

type DoctorSkills struct {
	Directory string `json:"directory"`
	Pending   int    `json:"pending"`
	Approved  int    `json:"approved"`
	Rejected  int    `json:"rejected"`
}

type DoctorVariants struct {
	Enabled bool `json:"enabled"`
	// Directories are the variant roots that exist on disk.
	Directories []string          `json:"directories"`
	Sections    []SectionVariants `json:"sections"`
	// Competing counts sections with two or more candidates.
	Competing int `json:"competing"`
}

type EvaluateOptions struct {
	// Force bypasses the completion guards (minimum user turns, subagent
	// sessions). Idempotency is never bypassed.
	Force bool
	// SkipJudge disables the LLM judge for this evaluation.
	SkipJudge bool
	// Rescore replaces an existing session score in place instead of skipping
	// the session as already evaluated (used after explicit feedback). The
	// judge never runs on a re-score.
	Rescore bool
}

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

type Feedback struct {
	Rating string
	Note   string
}

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

type JudgeError struct {
	Message string
	At      time.Time
}

type JudgeMeta struct {
	TemplateName    string
	TemplateVersion int
	Corrections     int
	Tokens          int64
	Transcript      string
}

type JudgeOutput struct {
	Reasoning  string   `json:"reasoning"`
	KeyPoints  []string `json:"key_points"`
	NewSkill   string   `json:"new_skill"`
	TaskType   string   `json:"task_type"`
	Confidence float64  `json:"confidence"`
}

type JudgeResult struct {
	Output           *JudgeOutput
	Model            string
	PromptTokens     int64
	CompletionTokens int64
}

type PatternHit struct {
	// Index is the position of the message in the session (0-based).
	Index   int     `json:"index"`
	Pattern string  `json:"pattern"`
	Weight  float64 `json:"weight"`
	// AfterAssistant is true when the turn directly follows an assistant turn.
	AfterAssistant bool   `json:"afterAssistant"`
	Snippet        string `json:"snippet"`
}

type PatternIssue struct {
	// Kind is PatternIssueCompile or PatternIssueDoubleBackslash.
	Kind string `json:"kind"`
	// Source is the config key holding the pattern.
	Source  string `json:"source"`
	Pattern string `json:"pattern"`
	Message string `json:"message"`
	// Hint tells how to fix it.
	Hint string `json:"hint"`
}

type Report struct {
	Enabled  bool   `json:"enabled"`
	Model    string `json:"model,omitempty"`
	Provider string `json:"provider,omitempty"`
	// DisabledReasons explain why the loop is off or cannot run.
	DisabledReasons []string `json:"disabled_reasons,omitempty"`
	// Warnings are problems that do not stop the loop but need attention.
	Warnings []string `json:"warnings,omitempty"`

	EligibleSessions  int64 `json:"eligible_sessions"`
	EvaluatedSessions int64 `json:"evaluated_sessions"`
	// NeverEvaluated counts eligible sessions without a score.
	NeverEvaluated int64 `json:"never_evaluated"`
	// RecentWindow / RecentEvaluated: of the last RecentWindow idle eligible
	// sessions, how many have a score.
	RecentWindow    int64 `json:"recent_window"`
	RecentEvaluated int64 `json:"recent_evaluated"`
	// LastEvaluatedAt is the unix time of the newest score (0 = none).
	LastEvaluatedAt     int64        `json:"last_evaluated_at"`
	LastEvaluationError *DoctorError `json:"last_evaluation_error,omitempty"`

	Judge             DoctorJudge      `json:"judge"`
	Variants          DoctorVariants   `json:"variants"`
	Skills            DoctorSkills     `json:"skills"`
	ContextTrimmer    bool             `json:"context_trimmer"`
	Background        DoctorBackground `json:"background"`
	PatternIssues     []PatternIssue   `json:"pattern_issues,omitempty"`
	CollectionErrors  []string         `json:"collection_errors,omitempty"`
	GeneratedAt       int64            `json:"generated_at"`
	SessionsAvailable bool             `json:"sessions_available"`
}

type Result struct {
	SessionID string
	// Skipped is non-empty when no score was written; it holds the reason.
	Skipped string
	// Reward is the decomposition of the persisted score (zero when Skipped).
	Reward RewardResult
	// Judged reports whether the LLM judge ran.
	Judged bool
}

type RewardResult struct {
	Total            float64
	SuccessScore     float64
	EfficiencyScore  float64
	PromptTokens     int64
	CompletionTokens int64
	MessageCount     int64
	UserCorrections  int
	// Breakdown is the explainable decomposition persisted with the score.
	Breakdown Breakdown
}

type SectionVariants struct {
	Section string `json:"section"`
	// Files is the number of variant files (the embedded default is extra).
	Files int `json:"files"`
	// Competing is true when the section has the default plus at least one file,
	// i.e. two or more candidates, so A/B selection actually happens.
	Competing bool `json:"competing"`
}

type Service interface {
	// EvaluateSession triggers evaluation of a session on explicit request
	// (async if configured). It bypasses the completion guards of MarkCompleted.
	EvaluateSession(ctx context.Context, sessionID string) error

	// MarkCompleted is the entry point for session-completion triggers (session
	// switch, idle sweep, shutdown). It applies the evaluation guards (minimum
	// user turns, subagent sessions, idempotency, in-flight dedupe) and
	// evaluates asynchronously when configured. reason is only used for logging.
	MarkCompleted(ctx context.Context, sessionID, reason string) error

	// SelectVariant returns the prompt variant id chosen for a section of a
	// session among candidates (candidates[0] is the default variant). The choice
	// is made once per (session, section), persisted and frozen; it is the
	// default when the feature is off or there is nothing to choose from.
	SelectVariant(ctx context.Context, sessionID, section string, candidates []string) (string, error)

	// GetActiveSkills returns the approved skills for a task type.
	GetActiveSkills(ctx context.Context, taskType string) ([]Skill, error)

	// ListSkills returns the learned skills (files + statistics), optionally
	// filtered by status (pending|approved|rejected) and task type.
	ListSkills(ctx context.Context, status, taskType string) ([]Skill, error)

	// ReviewSkill approves or rejects a learned skill by id.
	ReviewSkill(ctx context.Context, id, status string) (*Skill, error)

	// GetStats returns current UCB rankings and skill library summary.
	GetStats(ctx context.Context) (*Stats, error)

	// IsEnabled returns whether the evaluator is active.
	IsEnabled() bool

	// ClassifyTask returns a task type label from the user's first message.
	// Returns "general" if no pattern matches.
	ClassifyTask(text string) string
}

type SessionDetail struct {
	SessionID       string  `json:"session_id"`
	Title           string  `json:"title"`
	Reward          float64 `json:"reward"`
	SuccessScore    float64 `json:"success_score"`
	EfficiencyScore float64 `json:"efficiency_score"`
	MessageCount    int64   `json:"message_count"`
	UserCorrections int64   `json:"user_corrections"`
	EvaluatedAt     int64   `json:"evaluated_at"`
	// Breakdown is the parsed components JSON (zero for legacy rows).
	Breakdown Breakdown `json:"breakdown"`
	// Components is the persisted components JSON as stored.
	Components json.RawMessage `json:"components"`
	// JudgeAnalysis is the stored judge output, JSON null when the judge did not run.
	JudgeAnalysis         json.RawMessage   `json:"judge_analysis"`
	JudgeModel            string            `json:"judge_model,omitempty"`
	JudgePromptTokens     int64             `json:"judge_prompt_tokens"`
	JudgeCompletionTokens int64             `json:"judge_completion_tokens"`
	Variants              []SessionVariant  `json:"variants"`
	Skills                []SessionSkillRef `json:"skills"`
}

type SessionSkillRef struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

type SessionVariant struct {
	Section string `json:"section"`
	Variant string `json:"variant"`
}

type Skill struct {
	ID       string
	Title    string
	Content  string
	TaskType string
	// SuccessRate is the mean reward of the evaluated sessions the skill was
	// injected in (EvalCount of them); UsageCount counts sessions it was injected in.
	SuccessRate float64
	UsageCount  int
	EvalCount   int
	// Status is the review state: pending, approved or rejected.
	Status        string
	Confidence    float64
	JudgeModel    string
	SourceSession string
	Created       time.Time
}

type SkillFile struct {
	ID            string
	Title         string
	Status        string
	TaskType      string
	Confidence    float64
	SourceSession string
	JudgeModel    string
	Created       time.Time
	// Content is the rule text (the file body).
	Content string
	// Path is the absolute file path.
	Path string
}

type Stats struct {
	TotalEvaluations int
	Templates        []TemplateStats
	SkillCount       int
	TopSkills        []Skill
	AvgReward        float64
	LastEvaluation   time.Time
	IsEnabled        bool
	// RecentSessions are the latest evaluated sessions with their reward
	// components, variants and skills.
	RecentSessions []SessionDetail
	// Daily is evaluations and mean reward per day for the last 14 days.
	Daily []DailyMetric
	// Problem is the one-line doctor warning ("" when healthy).
	Problem string
}

type SweepOptions struct {
	// IdleFor is how long a session must have been idle to be picked up.
	IdleFor time.Duration
	// Limit bounds the number of sessions evaluated in this sweep.
	Limit int
	// SkipJudge disables the LLM judge for the sweep.
	SkipJudge bool
	// Pause is slept between evaluations to rate-limit the sweep.
	Pause time.Duration
	// OnResult, when set, receives every successfully scored session.
	OnResult func(*Result)
}

type TemplateStats struct {
	// VariantID is "<section>#<variant>"; "<section>#default" is the embedded template.
	VariantID string
	Section   string
	Variant   string
	TimesUsed int
	AvgReward float64
	UCBScore  float64
	Rank      int
}

type ToolInfo struct {
	Name        string
	Description string
}