Documentation
¶
Overview ¶
Package eval handles staghorn eval definitions, parsing, and execution.
Index ¶
- Constants
- Variables
- func CheckPromptfoo() error
- func CountByLevel(errors []ValidationError) (errorCount, warningCount int)
- func GeneratePromptfooConfigAlt(e *Eval, claudeConfig string) ([]byte, error)
- func HasErrors(errors []ValidationError) bool
- func ListTemplates() []string
- func RenderTemplate(t *EvalTemplate, vars TemplateVars) (string, error)
- func RenderTemplateByName(name string, vars TemplateVars) (string, error)
- func WritePromptfooConfig(config *PromptfooConfig, path string) error
- type Assertion
- type Context
- type Eval
- type EvalTemplate
- type FailedTest
- type Formatter
- type GenerateOptions
- type JSONEvalResult
- type JSONOutput
- type JSONTestResult
- type OutputFormat
- type PromptfooAssertion
- type PromptfooAssertionResult
- type PromptfooConfig
- type PromptfooOutput
- type PromptfooResult
- type PromptfooTest
- type Provider
- type RunConfig
- type RunResult
- type Runner
- type Source
- type Summary
- type TemplateVars
- type Test
- type TestResult
- type ValidationError
- type ValidationLevel
Constants ¶
const DefaultTimeout = 10 * time.Minute
DefaultTimeout is the default timeout for eval execution.
Variables ¶
var Templates = []EvalTemplate{
{
Name: "security",
Description: "Security-focused eval for testing security guidelines",
Content: `name: {{.Name}}
description: {{.Description}}
tags:
{{- range .Tags}}
- {{.}}
{{- end}}
tests:
- name: warns-about-hardcoded-secrets
description: Verifies Claude warns about hardcoded API keys and secrets
prompt: |
Review this code:
API_KEY = "sk-12345abcdef"
db_password = "super_secret_123"
assert:
- type: llm-rubric
value: Response warns about hardcoded secrets and suggests using environment variables
- name: identifies-injection-risks
description: Verifies Claude identifies potential injection vulnerabilities
prompt: |
Review this code:
query = f"SELECT * FROM users WHERE id = {user_input}"
assert:
- type: llm-rubric
value: Response identifies SQL injection risk and suggests parameterized queries
`,
},
{
Name: "quality",
Description: "Code quality eval for testing style and best practices",
Content: `name: {{.Name}}
description: {{.Description}}
tags:
{{- range .Tags}}
- {{.}}
{{- end}}
tests:
- name: suggests-clear-naming
description: Verifies Claude suggests better variable names
prompt: |
Review this code:
def f(x, y, z):
a = x + y
b = a * z
return b
assert:
- type: llm-rubric
value: Response suggests more descriptive function and variable names
- name: identifies-code-duplication
description: Verifies Claude identifies duplicated code
prompt: |
Review this code:
def process_user(user):
if user.age > 18:
print("Adult")
return user.name.upper()
def process_admin(admin):
if admin.age > 18:
print("Adult")
return admin.name.upper()
assert:
- type: llm-rubric
value: Response identifies code duplication and suggests refactoring
`,
},
{
Name: "language",
Description: "Language-specific eval template",
Content: `name: {{.Name}}
description: {{.Description}}
tags:
{{- range .Tags}}
- {{.}}
{{- end}}
tests:
- name: follows-language-conventions
description: Verifies Claude follows language-specific conventions
prompt: |
Write a function that calculates the factorial of a number.
assert:
- type: llm-rubric
value: Response follows idiomatic patterns for the target language
- name: uses-appropriate-error-handling
description: Verifies Claude uses proper error handling
prompt: |
Write code to read a file and parse its JSON contents.
assert:
- type: llm-rubric
value: Response includes proper error handling for file and JSON operations
`,
},
{
Name: "blank",
Description: "Minimal blank template to start from scratch",
Content: `name: {{.Name}}
description: {{.Description}}
tags:
{{- range .Tags}}
- {{.}}
{{- end}}
tests:
- name: example-test
description: Replace with your test description
prompt: |
Your prompt here
assert:
- type: llm-rubric
value: Your assertion here
`,
},
}
Templates contains all available eval templates.
var ValidAssertionTypes = []string{
"llm-rubric",
"contains",
"contains-any",
"contains-all",
"not-contains",
"regex",
"javascript",
}
ValidAssertionTypes lists all valid assertion types supported by Promptfoo.
Functions ¶
func CheckPromptfoo ¶
func CheckPromptfoo() error
CheckPromptfoo verifies that Promptfoo is installed and accessible.
func CountByLevel ¶ added in v0.5.0
func CountByLevel(errors []ValidationError) (errorCount, warningCount int)
CountByLevel counts errors and warnings separately.
func GeneratePromptfooConfigAlt ¶
GeneratePromptfooConfigAlt generates an alternative format that puts the system prompt inline with tests for cleaner output.
func HasErrors ¶ added in v0.5.0
func HasErrors(errors []ValidationError) bool
HasErrors returns true if there are any errors (not just warnings).
func ListTemplates ¶ added in v0.5.0
func ListTemplates() []string
ListTemplates returns all available template names.
func RenderTemplate ¶ added in v0.5.0
func RenderTemplate(t *EvalTemplate, vars TemplateVars) (string, error)
RenderTemplate renders a template with the given variables.
func RenderTemplateByName ¶ added in v0.5.0
func RenderTemplateByName(name string, vars TemplateVars) (string, error)
RenderTemplateByName gets a template by name and renders it.
func WritePromptfooConfig ¶
func WritePromptfooConfig(config *PromptfooConfig, path string) error
WritePromptfooConfig writes a Promptfoo config to a file.
Types ¶
type Assertion ¶
type Assertion struct {
Type string `yaml:"type"`
Value interface{} `yaml:"value"`
}
Assertion represents a test assertion.
type Context ¶
type Context struct {
// Layers specifies which config layers to include.
// Options: "team", "personal", "project", or "merged" (default).
Layers []string `yaml:"layers,omitempty"`
// Languages specifies which language configs to include.
Languages []string `yaml:"languages,omitempty"`
}
Context specifies which config layers and languages to test against.
type Eval ¶
type Eval struct {
Name string `yaml:"name"`
Description string `yaml:"description"`
Tags []string `yaml:"tags,omitempty"`
Context Context `yaml:"context,omitempty"`
Provider Provider `yaml:"provider,omitempty"`
Tests []Test `yaml:"tests"`
// Metadata (not from YAML)
Source Source `yaml:"-"`
FilePath string `yaml:"-"`
}
Eval represents a staghorn eval definition.
func LoadFromDirectory ¶
LoadFromDirectory loads all evals from a directory.
func (*Eval) FilterTests ¶
FilterTests returns a copy of the eval with only matching tests. testFilter can be a test name or a prefix pattern ending with *.
func (*Eval) GetEffectiveLayers ¶
GetEffectiveLayers returns the layers to test against.
func (*Eval) ResolveModel ¶
ResolveModel returns the model to use, expanding environment variables.
func (*Eval) Validate ¶ added in v0.5.0
func (e *Eval) Validate() []ValidationError
Validate performs detailed validation of the eval and returns any issues found. Unlike Parse, which fails fast on critical errors, Validate collects all issues including warnings for non-critical problems.
type EvalTemplate ¶ added in v0.5.0
type EvalTemplate struct {
Name string // Template identifier (e.g., "security")
Description string // Human-readable description
Content string // YAML template with Go template placeholders
}
EvalTemplate represents a starter template for creating evals.
func GetTemplate ¶ added in v0.5.0
func GetTemplate(name string) (*EvalTemplate, error)
GetTemplate returns a template by name.
type FailedTest ¶
FailedTest holds info about a failed test.
type Formatter ¶
type Formatter struct {
Writer io.Writer
Format OutputFormat
Debug bool // Show full LLM responses for failures
}
Formatter formats eval results for output.
func NewFormatter ¶
func NewFormatter(w io.Writer, format OutputFormat) *Formatter
NewFormatter creates a new result formatter.
func (*Formatter) FormatResults ¶
FormatResults formats multiple eval results.
type GenerateOptions ¶
type GenerateOptions struct {
// OutputDir is the directory to write the Promptfoo config to.
OutputDir string
// ResultsPath is the path for Promptfoo to write results to.
ResultsPath string
}
GenerateOptions configures Promptfoo config generation.
type JSONEvalResult ¶
type JSONEvalResult struct {
Eval string `json:"eval"`
Total int `json:"total"`
Passed int `json:"passed"`
Failed int `json:"failed"`
Duration string `json:"duration"`
Tests []JSONTestResult `json:"tests"`
}
JSONEvalResult represents a single eval's results in JSON.
type JSONOutput ¶
type JSONOutput struct {
Summary struct {
Total int `json:"total"`
Passed int `json:"passed"`
Failed int `json:"failed"`
PassRate float64 `json:"passRate"`
} `json:"summary"`
Results []JSONEvalResult `json:"results"`
}
JSONOutput represents the JSON output format.
type JSONTestResult ¶
type JSONTestResult struct {
Name string `json:"name"`
Passed bool `json:"passed"`
Duration string `json:"duration,omitempty"`
Error string `json:"error,omitempty"`
Output string `json:"output,omitempty"`
}
JSONTestResult represents a single test result in JSON.
type OutputFormat ¶
type OutputFormat string
OutputFormat specifies the output format for results.
const ( OutputFormatTable OutputFormat = "table" OutputFormatJSON OutputFormat = "json" OutputFormatGitHub OutputFormat = "github" )
type PromptfooAssertion ¶
type PromptfooAssertion struct {
Type string `yaml:"type"`
Value interface{} `yaml:"value,omitempty"`
}
PromptfooAssertion represents an assertion in Promptfoo format.
type PromptfooAssertionResult ¶
PromptfooAssertionResult represents an assertion result.
type PromptfooConfig ¶
type PromptfooConfig struct {
Description string `yaml:"description,omitempty"`
Prompts []string `yaml:"prompts"`
Providers []string `yaml:"providers"`
Tests []PromptfooTest `yaml:"tests"`
OutputPath string `yaml:"outputPath,omitempty"`
}
PromptfooConfig represents a Promptfoo configuration file.
func GeneratePromptfooConfig ¶
func GeneratePromptfooConfig(e *Eval, claudeConfig string, opts GenerateOptions) (*PromptfooConfig, error)
GeneratePromptfooConfig creates a Promptfoo config from an eval definition.
type PromptfooOutput ¶
type PromptfooOutput struct {
Results []PromptfooResult `json:"results"`
Stats struct {
Successes int `json:"successes"`
Failures int `json:"failures"`
} `json:"stats"`
}
PromptfooOutput represents Promptfoo's JSON output format.
type PromptfooResult ¶
type PromptfooResult struct {
Description string `json:"description"`
Success bool `json:"success"`
Response string `json:"response"`
AssertionResults []PromptfooAssertionResult `json:"gradingResult"`
}
PromptfooResult represents a single result in Promptfoo output.
type PromptfooTest ¶
type PromptfooTest struct {
Description string `yaml:"description,omitempty"`
Vars map[string]interface{} `yaml:"vars"`
Assert []PromptfooAssertion `yaml:"assert"`
}
PromptfooTest represents a test case in Promptfoo format.
type Provider ¶
type Provider struct {
// Model is the model identifier, supports env var expansion.
// Default: ${STAGHORN_EVAL_MODEL:-claude-sonnet-4-20250514}
Model string `yaml:"model,omitempty"`
}
Provider configures the LLM provider for evals.
type RunConfig ¶
type RunConfig struct {
// Eval is the eval definition to run.
Eval *Eval
// ClaudeConfig is the merged CLAUDE.md content to use as system prompt.
ClaudeConfig string
}
RunConfig holds configuration for a single eval run.
type RunResult ¶
type RunResult struct {
EvalName string
TotalTests int
Passed int
Failed int
Duration time.Duration
Results []TestResult
RawOutput string
DebugDir string // Set when debug mode is enabled
}
RunResult holds the result of an eval run.
type Runner ¶
type Runner struct {
// WorkDir is the working directory for Promptfoo.
WorkDir string
// Verbose enables verbose output.
Verbose bool
// Debug enables debug mode (preserves temp files, shows full responses).
Debug bool
// Timeout is the timeout for eval execution.
Timeout time.Duration
}
Runner executes evals using Promptfoo.
type Summary ¶
type Summary struct {
TotalEvals int
TotalTests int
Passed int
Failed int
PassRate float64
Duration float64
FailedTests []FailedTest
}
Summary generates a summary of results.
type TemplateVars ¶ added in v0.5.0
TemplateVars holds variables for template rendering.
type Test ¶
type Test struct {
Name string `yaml:"name"`
Description string `yaml:"description,omitempty"`
Vars map[string]string `yaml:"vars,omitempty"`
Prompt string `yaml:"prompt"`
Assert []Assertion `yaml:"assert"`
}
Test represents a single test case in an eval.
type TestResult ¶
type TestResult struct {
Name string
Description string
Passed bool
Duration time.Duration
Error string
Output string
}
TestResult holds the result of a single test.
type ValidationError ¶ added in v0.5.0
type ValidationError struct {
Field string // e.g., "tests[0].assert[0].type"
Message string // Human-readable error message
Level ValidationLevel // error or warning
}
ValidationError represents a single validation issue.
type ValidationLevel ¶ added in v0.5.0
type ValidationLevel string
ValidationLevel indicates the severity of a validation issue.
const ( ValidationLevelError ValidationLevel = "error" ValidationLevelWarning ValidationLevel = "warning" )