Documentation
¶
Index ¶
- Constants
- Variables
- func CompileReplicationMap(path string) (map[string]any, error)
- func CompileReplicationYAML(body []byte) (map[string]any, error)
- func EnsureEcomParquet() error
- func EnsureFreshSlingBin(bin string) (string, error)
- func FindSlingBin() (string, error)
- func FormatSummary(s SuiteSummary) string
- func GenerateEcomParquet(dir string) error
- func HostHasClaudeAuth() bool
- func HostHasCodexAuth() bool
- func HostHasGrokAuth() bool
- func HostHasOpenCode2Auth() bool
- func LinkHostAuth(home, arm string) error
- func LoadFixtureRegistry(path string) (map[string]FixtureDef, error)
- func NewRunID() string
- func PreflightConns(bin string, names []string, env []string) map[string]bool
- func RunTimed(name string, args []string, dir string, envv []string, timeout time.Duration) (stdout string, err error)
- func RunTimedStdout(name string, args []string, dir string, envv []string, timeout time.Duration) (stdout string, err error)
- func SeedHome(home, fixture string, noSkills bool) error
- func SmokeFlipFail(flips []Flip, gating map[string]bool) bool
- func TrialPasses(graders []GraderResult) bool
- func ValidateCase(c Case, fixtures map[string]FixtureDef) []string
- func WeightedScore(graders []GraderResult) float64
- func YAMLMap(path string) (map[string]any, error)
- type ArmAvail
- type ArmSummary
- type Case
- func (c Case) DefaultArms() []string
- func (c Case) ExpectedPath() string
- func (c Case) HasTag(tag string) bool
- func (c Case) IsGating() bool
- func (c Case) IsNegative() bool
- func (c Case) IsSmoke() bool
- func (c Case) MutantPaths() []string
- func (c Case) TaskID() string
- func (c Case) TimeoutDur() time.Duration
- func (c Case) TrialCount(override int) int
- func (c Case) UsedConnections() []string
- type CaseGraders
- type CaseMeta
- type CaseMetrics
- type CompareResult
- type FixtureDef
- type FixtureServer
- type Flags
- type Flip
- type GradeContext
- type GraderResult
- type GraderSpec
- type MatchPolicy
- type MockHints
- type Provisioner
- type ReadyCheck
- type ResultsWriter
- type Suite
- type SuiteSummary
- type TrialResult
Constants ¶
const ( TierSmoke = "smoke" TierCore = "core" TierDeep = "deep" )
ValidTier values. Replaces the old smoke tag.
Variables ¶
var DefaultTierCostCaps = map[string]float64{ TierSmoke: 5, TierCore: 15, TierDeep: 40, }
DefaultTierCostCaps is the suite-level spend cap per selected tier.
var DefaultTierThresholds = map[string]float64{ TierSmoke: 0.90, TierCore: 0.80, TierDeep: 0.70, }
DefaultTierThresholds apply to gating cases only.
var KnownConnections = map[string]bool{ "POSTGRES": true, "MYSQL": true, "CLICKHOUSE": true, "DUCKDB": true, "SQLITE": true, "LOCAL": true, "AWS_S3_TEST": true, "MOCK_API": true, }
KnownConnections is the eval suite connection set.
var KnownGraderNames = map[string]bool{ "file_exists": true, "file_absent": true, "yaml_valid": true, "sling": true, "expected": true, "dry_run": true, "transcript_contains": true, "transcript_absent": true, "transcript_absent_raw": true, "yq": true, "sql_equiv": true, "skeleton": true, "outcome": true, "query": true, "rows_equal": true, "dag": true, "tests_pass": true, "api_spec": true, }
KnownGraderNames is the set of grader kinds RunGraders accepts.
Functions ¶
func CompileReplicationMap ¶
CompileReplicationMap loads a replication YAML and expands defaults. It uses sling.LoadReplicationConfig and SetStreamDefaults (the product path). Full Compile() needs a live source conn; we fall back to defaults-only when Compile fails so mock trials stay local.
func CompileReplicationYAML ¶
CompileReplicationYAML compiles from bytes (tests / in-memory).
func EnsureEcomParquet ¶
func EnsureEcomParquet() error
EnsureEcomParquet writes deterministic dirty ecommerce parquet if missing.
func EnsureFreshSlingBin ¶
EnsureFreshSlingBin rebuilds cmd/sling when the binary is older than any core/ source file. A live run against a stale binary must not happen silently.
func FindSlingBin ¶
FindSlingBin locates the built sling binary.
func GenerateEcomParquet ¶
GenerateEcomParquet writes dirty ecommerce tables as parquet via DuckDB.
func HostHasClaudeAuth ¶
func HostHasClaudeAuth() bool
HostHasClaudeAuth is true when an env key or a host login file exists.
func HostHasCodexAuth ¶
func HostHasCodexAuth() bool
HostHasCodexAuth is true when an env key or the host auth file exists.
func HostHasGrokAuth ¶
func HostHasGrokAuth() bool
HostHasGrokAuth is true when an env key or host ~/.grok/auth.json exists.
func HostHasOpenCode2Auth ¶
func HostHasOpenCode2Auth() bool
HostHasOpenCode2Auth is true when a provider env key or an opencode auth file exists. v2 stores credentials at $XDG_DATA_HOME/opencode/auth.json (default ~/.local/share/opencode/auth.json).
func LinkHostAuth ¶
LinkHostAuth points the sandbox HOME at the host login files. It does not copy the full ~/.claude or ~/.grok trees.
func LoadFixtureRegistry ¶
func LoadFixtureRegistry(path string) (map[string]FixtureDef, error)
LoadFixtureRegistry reads tests/evals/fixtures/registry.yaml.
func PreflightConns ¶
PreflightConns runs `sling conns test` for each name. Down conns are skipped, not failed.
func RunTimed ¶
func RunTimed(name string, args []string, dir string, envv []string, timeout time.Duration) (stdout string, err error)
RunTimed starts name+args in a new process group and kills the whole group when timeout elapses. CommandContext only signals the parent. Stdout and stderr are merged (legacy graders parse the combined log).
func RunTimedStdout ¶
func RunTimedStdout(name string, args []string, dir string, envv []string, timeout time.Duration) (stdout string, err error)
RunTimedStdout is RunTimed but keeps stderr off the returned transcript.
func SmokeFlipFail ¶
SmokeFlipFail is true when any gating case went pass→fail. A "removed" flip does not fail the gate.
func TrialPasses ¶
func TrialPasses(graders []GraderResult) bool
TrialPasses is true only when every required (non-skip, non-optional, non-judge) grader passes.
func ValidateCase ¶
func ValidateCase(c Case, fixtures map[string]FixtureDef) []string
ValidateCase lints one loaded case. Returns error strings (empty = ok).
func WeightedScore ¶
func WeightedScore(graders []GraderResult) float64
WeightedScore: required=1.0, optional=0.5, judge=0.5. Skip is ignored.
Types ¶
type ArmSummary ¶
type ArmSummary struct {
Cases int `json:"cases"`
PassAt1 float64 `json:"pass_at_1"`
PassHatK float64 `json:"pass_hat_k"`
CostUSD float64 `json:"cost_usd"`
Flips string `json:"flips,omitempty"`
}
ArmSummary is one row of the headline table.
type Case ¶
type Case struct {
ID string `yaml:"id"`
Task string `yaml:"task"`
Tier string `yaml:"tier"`
Gating *bool `yaml:"gating"`
Tags []string `yaml:"tags"`
Intention string `yaml:"intention"`
EditPath string `yaml:"edit_path"`
Arms []string `yaml:"arms"`
Trials int `yaml:"trials"`
BudgetUSD float64 `yaml:"budget_usd"`
Timeout string `yaml:"timeout"`
Setup []any `yaml:"setup"`
Teardown []any `yaml:"teardown"`
Fixtures []string `yaml:"fixtures"`
Connections []string `yaml:"conns"`
Env map[string]string `yaml:"env"`
Artifact string `yaml:"artifact"`
Graders CaseGraders `yaml:"graders"`
Mock MockHints `yaml:"mock"`
SeedFiles map[string]string `yaml:"seed_files"`
ResetSchemas []string `yaml:"reset_schemas"`
Path string `yaml:"-"` // case.yaml path
CaseDir string `yaml:"-"` // folder that holds case.yaml
}
Case is one eval YAML file.
func SelectCases ¶
SelectCases filters loaded cases by flags.
func (Case) DefaultArms ¶
func (Case) ExpectedPath ¶
func (Case) IsNegative ¶
func (Case) MutantPaths ¶
func (Case) TimeoutDur ¶
func (Case) TrialCount ¶
func (Case) UsedConnections ¶
type CaseGraders ¶
type CaseGraders struct {
Required []GraderSpec `yaml:"required"`
Optional []GraderSpec `yaml:"optional"`
Judge []string `yaml:"judge"`
}
CaseGraders is the graders block.
type CaseMetrics ¶
type CaseMetrics struct {
Case string `json:"case"`
Arm string `json:"arm"`
Trials int `json:"trials"`
Passed int `json:"passed"`
PassAtK bool `json:"pass_at_k"`
PassHatK bool `json:"pass_hat_k"`
MeanScore float64 `json:"mean_score"`
MeanCost float64 `json:"mean_cost"`
MeanDur float64 `json:"mean_duration_s"`
SkipReason string `json:"skip_reason,omitempty"`
Gating bool `json:"gating"`
Tier string `json:"tier,omitempty"`
Timeouts int `json:"timeouts,omitempty"`
}
CaseMetrics aggregates k trials for one case+arm.
func AggregateCase ¶
func AggregateCase(caseID, arm string, trials []TrialResult, gating bool) CaseMetrics
AggregateCase computes pass@k / pass^k for one case+arm.
func AggregateCaseMeta ¶
func AggregateCaseMeta(caseID, arm string, trials []TrialResult, meta CaseMeta) CaseMetrics
type CompareResult ¶
CompareResult is one path check.
func CompareCompiled ¶
func CompareCompiled(actual, expected map[string]any, policy MatchPolicy) []CompareResult
CompareCompiled walks two compiled maps with the match policy.
func CompareCompiledFiles ¶
func CompareCompiledFiles(actualPath, expectedPath string, policy MatchPolicy) ([]CompareResult, error)
CompareCompiledFiles compiles both YAML files then applies the policy.
type FixtureDef ¶
type FixtureDef struct {
Connection string `yaml:"connection"`
Requires []string `yaml:"requires"`
Provision []GraderSpec `yaml:"provision"`
ReadyCheck ReadyCheck `yaml:"ready_check"`
}
FixtureDef is one named dataset in fixtures/registry.yaml.
type FixtureServer ¶
type FixtureServer struct {
URL string
// contains filtered or unexported fields
}
FixtureServer is the hermetic API used by spec cases.
func StartFixtureServer ¶
func StartFixtureServer() (*FixtureServer, error)
StartFixtureServer binds 127.0.0.1:0 and serves fixture routes.
func (*FixtureServer) Close ¶
func (fs *FixtureServer) Close()
type Flags ¶
type Flags struct {
Arms []string
Tags []string
Tiers []string
Cases []string
Trials int
Baseline string
MaxSuiteUSD float64
Parallel int
ResetFixtures bool
RetryFailed bool
}
Flags are TestEvalAssist CLI flags (args after --).
type Flip ¶
type Flip struct {
Case string `json:"case"`
Arm string `json:"arm"`
From string `json:"from"` // pass | fail
To string `json:"to"` // pass | fail | removed
Delta float64 `json:"score_delta"`
}
Flip is a per-case pass/fail transition vs a baseline run.
func PairedDiff ¶
func PairedDiff(current, baseline []TrialResult, gating map[string]bool) []Flip
PairedDiff reports pass→fail / fail→pass vs a baseline run. A baseline case id absent from current is "removed", not "failed".
type GradeContext ¶
type GradeContext struct {
WorkDir string
Artifact string // relative to WorkDir
CaseDir string // case folder with case.yaml, expected/, mutants/
Transcript string
SlingBin string
Env []string
ConnDown map[string]bool // name → down
SkipExecute bool // mock arm: do not run L5 execute graders
FixtureBaseURL string
FixtureToken string
APIPageCap int
APITimeout time.Duration
}
GradeContext is the trial sandbox the graders see.
type GraderResult ¶
type GraderResult struct {
Name string `json:"name"`
Pass bool `json:"pass"`
Skip bool `json:"skip,omitempty"`
Optional bool `json:"optional,omitempty"`
Judge bool `json:"judge,omitempty"`
Detail string `json:"detail,omitempty"`
Critique string `json:"critique,omitempty"`
}
GraderResult is one grader outcome.
func RunGraders ¶
func RunGraders(ctx GradeContext, required, optional []GraderSpec) []GraderResult
RunGraders executes required then optional specs. Judge is separate.
func RunJudge ¶
func RunJudge(questions []string, intention, artifact, transcript string, persistDir ...string) []GraderResult
RunJudge batches questions into one claude -p call. Results never gate. Skip when the judge binary is missing. persistDir, when set, stores the raw request and response for triage.
type GraderSpec ¶
GraderSpec is one YAML grader item (one primary key).
type MatchPolicy ¶
type MatchPolicy struct {
MustMatch []string `yaml:"must_match"`
MustNotExist []string `yaml:"must_not_exist"`
}
MatchPolicy is the compiled-form compare rule set.
type MockHints ¶
type MockHints struct {
Transcript string `yaml:"transcript"`
MutantTranscript string `yaml:"mutant_transcript"`
}
MockHints control the mock arm plant/transcript.
type Provisioner ¶
type Provisioner struct {
Bin string
Env []string
Logf func(string, ...any)
Registry map[string]FixtureDef
// contains filtered or unexported fields
}
Provisioner loads and caches named fixtures once per suite.
func NewProvisioner ¶
func (*Provisioner) Ensure ¶
func (p *Provisioner) Ensure(names []string) error
Ensure provisions names (and requires) unless ready_check already passes.
func (*Provisioner) Ready ¶
func (p *Provisioner) Ready(name string) bool
func (*Provisioner) Reset ¶
func (p *Provisioner) Reset() error
Reset drops eval_* schemas and the local TPC-H duckdb file.
func (*Provisioner) Skipped ¶
func (p *Provisioner) Skipped(name string) string
type ReadyCheck ¶
type ReadyCheck struct {
Connection string `yaml:"connection"`
SQL string `yaml:"sql"`
Equals any `yaml:"equals"`
}
ReadyCheck is an idempotent probe.
type ResultsWriter ¶
type ResultsWriter struct {
// contains filtered or unexported fields
}
ResultsWriter appends JSONL and can aggregate.
func NewResultsWriter ¶
func NewResultsWriter(dir, runID string) (*ResultsWriter, error)
NewResultsWriter creates the JSONL file.
func (*ResultsWriter) Append ¶
func (w *ResultsWriter) Append(tr TrialResult) error
func (*ResultsWriter) Path ¶
func (w *ResultsWriter) Path() string
func (*ResultsWriter) Replace ¶
func (w *ResultsWriter) Replace(tr TrialResult) error
Replace swaps the last row matching case+arm+trial with tr and rewrites the JSONL file.
func (*ResultsWriter) RunID ¶
func (w *ResultsWriter) RunID() string
func (*ResultsWriter) Trials ¶
func (w *ResultsWriter) Trials() []TrialResult
type Suite ¶
type Suite struct {
Flags Flags
Bin string
Writer *ResultsWriter
Logf func(string, ...any)
Server *FixtureServer
Provisioner *Provisioner
// contains filtered or unexported fields
}
Suite is the eval run coordinator.
type SuiteSummary ¶
type SuiteSummary struct {
Run string `json:"run"`
Arms map[string]ArmSummary `json:"arms"`
Cases []CaseMetrics `json:"cases"`
Flips []Flip `json:"flips,omitempty"`
Threshold float64 `json:"threshold"`
TierRates map[string]float64 `json:"tier_rates,omitempty"`
Verdict string `json:"verdict"`
CostUSD float64 `json:"cost_usd"`
SkillsDelta string `json:"skills_delta,omitempty"`
CostByFamily map[string]float64 `json:"cost_by_family,omitempty"`
Judge string `json:"judge,omitempty"`
Binary string `json:"binary,omitempty"`
Timeouts int `json:"timeouts,omitempty"`
GatingN int `json:"gating_n,omitempty"`
GatingPass int `json:"gating_pass,omitempty"`
GatingRate float64 `json:"gating_rate,omitempty"`
SchemaReset string `json:"schema_reset,omitempty"`
}
SuiteSummary is printed and written as summary.json.
func AggregateSuite ¶
func AggregateSuite(runID string, trials []TrialResult, gating map[string]bool, threshold float64) SuiteSummary
AggregateSuite groups trials into case metrics and arm headlines.
func AggregateSuiteMeta ¶
func AggregateSuiteMeta(runID string, trials []TrialResult, meta map[string]CaseMeta, threshold float64, tierThresholds map[string]float64) SuiteSummary
type TrialResult ¶
type TrialResult struct {
Run string `json:"run"`
Case string `json:"case"`
Arm string `json:"arm"`
Trial int `json:"trial"`
Invariant string `json:"invariant,omitempty"` // passable | sensitivity (mock)
Pass bool `json:"pass"`
Score float64 `json:"score"`
Graders []GraderResult `json:"graders"`
CostUSD float64 `json:"cost_usd"`
DurationS float64 `json:"duration_s"`
Turns int `json:"turns,omitempty"`
PromptMD5 string `json:"prompt_md5,omitempty"`
SkillsVersion string `json:"skills_version,omitempty"`
Model string `json:"model,omitempty"`
SkipReason string `json:"skip_reason,omitempty"`
Error string `json:"error,omitempty"`
InfraError bool `json:"infra_error,omitempty"`
Retried bool `json:"retried,omitempty"`
Timeout bool `json:"timeout,omitempty"`
Binary string `json:"binary,omitempty"`
Transcript string `json:"-"`
}
TrialResult is one JSONL line.