judge

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

type CategoryEvaluationResponse struct {
	Findings []FindingResponse `json:"findings"`
}

type CategoryResult struct {
	// Name is the category identifier.
	Name string `json:"name"`

	// Score is the category's aggregate score (0.0-1.0).
	Score float64 `json:"score"`

	// Findings contains rule evaluations in this category.
	Findings []Finding `json:"findings"`
}

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

type CompletionRequest struct {
	// SystemPrompt sets the system/context instruction.
	SystemPrompt string

	// UserPrompt is the main user message/question.
	UserPrompt string

	// Model specifies the model to use (provider-specific).
	Model string

	// Temperature controls randomness (0.0-1.0).
	Temperature float64

	// MaxTokens limits response length.
	MaxTokens int

	// StopSequences are strings that stop generation.
	StopSequences []string

	// Metadata is optional context for logging/tracing.
	Metadata map[string]string
}

type CompletionResponse struct {
	// Content is the generated text.
	Content string

	// Model is the model that was used.
	Model string

	// Usage contains token usage statistics.
	Usage *TokenUsage

	// FinishReason indicates why generation stopped.
	FinishReason string
}

type Criterion struct {
	// RuleID links back to the source rule.
	RuleID string

	// RuleTitle is the rule's display name.
	RuleTitle string

	// Category is the rule's category for grouping.
	Category string

	// Prompt is the evaluation instruction for the LLM.
	Prompt string

	// Weight influences scoring (0.0-1.0, default 1.0).
	Weight float64

	// Severity is the rule's severity level.
	Severity types.Severity

	// RequiresContext indicates if broader context is needed.
	RequiresContext bool

	// Examples from the rule (if available).
	GoodExamples []string
	BadExamples  []string

	// Rationale from the rule (if available).
	Rationale string

	// References from the rule.
	References []types.Reference
}

type EvaluationReport struct {
	// Status indicates overall evaluation outcome.
	Status types.Status `json:"status"`

	// Summary provides aggregate statistics.
	Summary EvaluationSummary `json:"summary"`

	// Categories contains results grouped by category.
	Categories []CategoryResult `json:"categories"`

	// Findings contains all individual rule evaluations.
	Findings []Finding `json:"findings"`

	// Metadata contains evaluation context.
	Metadata ReportMetadata `json:"metadata"`
}

type EvaluationSummary struct {
	// TotalRules is the number of rules evaluated.
	TotalRules int `json:"totalRules"`

	// PassedRules is the number of rules that passed.
	PassedRules int `json:"passedRules"`

	// FailedRules is the number of rules that failed.
	FailedRules int `json:"failedRules"`

	// SkippedRules is the number of rules skipped.
	SkippedRules int `json:"skippedRules"`

	// OverallScore is the weighted average score (0.0-1.0).
	OverallScore float64 `json:"overallScore"`

	// CategoryScores maps category names to their scores.
	CategoryScores map[string]float64 `json:"categoryScores,omitempty"`
}

type Evaluator interface {
	// Evaluate assesses an API specification against the configured rubric.
	Evaluate(ctx context.Context, specBytes []byte, opts *Options) (*EvaluationReport, error)

	// EvaluateCategory evaluates a single category of rules.
	EvaluateCategory(ctx context.Context, specBytes []byte, category string, opts *Options) (*CategoryResult, error)
}

type Finding struct {
	// RuleID is the evaluated rule's identifier.
	RuleID string `json:"ruleId"`

	// RuleTitle is the rule's display name.
	RuleTitle string `json:"ruleTitle"`

	// Category is the rule's category.
	Category string `json:"category"`

	// Score is the evaluation score (0.0-1.0).
	Score float64 `json:"score"`

	// Passed indicates if the rule passed (score >= 0.5).
	Passed bool `json:"passed"`

	// Reasoning explains the evaluation decision.
	Reasoning string `json:"reasoning,omitempty"`

	// Examples are specific instances found in the spec.
	Examples []string `json:"examples,omitempty"`

	// Suggestions provides improvement recommendations.
	Suggestions []string `json:"suggestions,omitempty"`

	// Locations identifies paths in the spec related to findings.
	Locations []string `json:"locations,omitempty"`

	// Severity reflects the rule's configured severity.
	Severity types.Severity `json:"severity"`

	// Weight is the rule's evaluation weight.
	Weight float64 `json:"weight"`
}

type FindingResponse struct {
	RuleID      string   `json:"ruleId"`
	Score       float64  `json:"score"`
	Passed      bool     `json:"passed"`
	Reasoning   string   `json:"reasoning"`
	Examples    []string `json:"examples"`
	Suggestions []string `json:"suggestions"`
	Locations   []string `json:"locations"`
}

type Options struct {
	// Categories limits evaluation to specific categories.
	// If empty, all categories are evaluated.
	Categories []string

	// RuleIDs limits evaluation to specific rules.
	// If empty, all rules with Judge criteria are evaluated.
	RuleIDs []string

	// FileName is the name of the spec file (for context in prompts).
	FileName string

	// IncludeReasoning enables detailed reasoning in results.
	IncludeReasoning bool

	// MaxConcurrency limits parallel LLM calls (default: 1).
	MaxConcurrency int

	// Model specifies the LLM model to use.
	// Provider-specific (e.g., "claude-3-haiku-20240307" for Anthropic).
	Model string

	// Temperature controls response randomness (0.0-1.0).
	Temperature float64

	// MaxTokens limits response length.
	MaxTokens int
}

type PromptBuilder struct {
	// SystemPrompt is the base system instruction.
	SystemPrompt string
}

type Provider interface {
	// Complete sends a completion request to the LLM.
	Complete(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error)

	// Name returns the provider name (e.g., "anthropic", "openai").
	Name() string

	// DefaultModel returns the provider's default model.
	DefaultModel() string
}

type ProviderConfig struct {
	// APIKey is the authentication key.
	APIKey string

	// BaseURL overrides the default API endpoint.
	BaseURL string

	// DefaultModel sets the default model for requests.
	DefaultModel string

	// Timeout in seconds for API calls.
	Timeout int

	// MaxRetries for failed requests.
	MaxRetries int

	// RetryDelay in milliseconds between retries.
	RetryDelay int
}

type ReportMetadata struct {
	// FileName is the evaluated spec file name.
	FileName string `json:"fileName,omitempty"`

	// ProfileName is the style profile used.
	ProfileName string `json:"profileName,omitempty"`

	// Model is the LLM model used.
	Model string `json:"model,omitempty"`

	// Duration is the total evaluation time.
	Duration string `json:"duration,omitempty"`

	// Timestamp is when the evaluation was performed.
	Timestamp string `json:"timestamp,omitempty"`
}

type RubricSet struct {
	// Name is the rubric set identifier (from spec name).
	Name string

	// Criteria contains all evaluation criteria keyed by rule ID.
	Criteria map[string]*Criterion

	// Categories groups criteria by category name.
	Categories map[string][]*Criterion
}

type SingleEvaluationResponse struct {
	Score       float64  `json:"score"`
	Passed      bool     `json:"passed"`
	Reasoning   string   `json:"reasoning"`
	Examples    []string `json:"examples"`
	Suggestions []string `json:"suggestions"`
	Locations   []string `json:"locations"`
}

type TokenUsage struct {
	// InputTokens is the number of tokens in the request.
	InputTokens int

	// OutputTokens is the number of tokens in the response.
	OutputTokens int

	// TotalTokens is the sum of input and output tokens.
	TotalTokens int
}