evalengine

README

evalengine

Documentation

Index

• func ComputeFingerprint(reads []FieldRef, msg proto.Message) string
• func ToCachedResults(results []Result, evaluatedAt time.Time) map[string]CachedResult
• type CELEvaluator
  • func NewCELEvaluator(env *cel.Env, def EvalDefinition) (*CELEvaluator, error)
  • func (e *CELEvaluator) CacheTTL() time.Duration
  • func (e *CELEvaluator) Evaluate(activation map[string]any) Result
  • func (e *CELEvaluator) Name() string
  • func (e *CELEvaluator) Reads() []FieldRef
  • func (e *CELEvaluator) ResolutionWorkflow() string
  • func (e *CELEvaluator) Writes() FieldRef
• type CachedResult
• type Engine
  • func NewEngine(cfg *EvalConfig, input proto.Message, opts ...cel.EnvOption) (*Engine, error)
  • func NewEngineFromBytes(data []byte, input proto.Message, opts ...cel.EnvOption) (*Engine, error)
  • func NewEngineFromFile(path string, input proto.Message, opts ...cel.EnvOption) (*Engine, error)
  • func (e *Engine) DeriveStatus(results []Result) Status
  • func (e *Engine) Evaluators() []Evaluator
  • func (e *Engine) Graph() *EvalGraph
  • func (e *Engine) Run(input proto.Message) []Result
  • func (e *Engine) RunMap(input proto.Message) map[string]Result
  • func (e *Engine) RunWithCache(input proto.Message, cache map[string]CachedResult, now time.Time) ([]Result, map[string]bool)
  • func (e *Engine) RunWithCacheMap(input proto.Message, cache map[string]CachedResult, now time.Time) (map[string]Result, map[string]bool)
  • func (e *Engine) ToCachedResults(results []Result, input proto.Message, evaluatedAt time.Time) map[string]CachedResult
• type EvalConfig
  • func LoadDefinitions(r io.Reader) (*EvalConfig, error)
  • func LoadDefinitionsFromFile(path string) (*EvalConfig, error)
• type EvalDefinition
• type EvalGraph
  • func BuildGraph(evaluators []Evaluator) (*EvalGraph, error)
  • func (g *EvalGraph) BlockedBy(name string, results map[string]Result) []string
  • func (g *EvalGraph) DependenciesMet(name string, results map[string]Result) bool
  • func (g *EvalGraph) ExecutionOrder() []string
  • func (g *EvalGraph) Issues() []Issue
  • func (g *EvalGraph) MaxDepth() int
• type Evaluator
• type FieldRef
  • func (f FieldRef) String() string
• type Issue
• type Result
• type Status
  • func DeriveStatus(results []Result, graph *EvalGraph) Status

Functions

func ComputeFingerprint

func ComputeFingerprint(reads []FieldRef, msg proto.Message) string

ComputeFingerprint hashes the values of the declared input fields from the given proto message. If the hash matches a cached value, the previous evaluation result can be reused.

func ToCachedResults

func ToCachedResults(results []Result, evaluatedAt time.Time) map[string]CachedResult

ToCachedResults converts a slice of results into a cache map keyed by name, stamped with the given evaluation time. No fingerprints are computed; use Engine.ToCachedResults for fingerprint-aware caching.

Types

type CELEvaluator

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

CELEvaluator implements Evaluator using a compiled CEL program.

func NewCELEvaluator

func NewCELEvaluator(env *cel.Env, def EvalDefinition) (*CELEvaluator, error)

NewCELEvaluator compiles a CEL expression and returns an evaluator.

func (*CELEvaluator) CacheTTL

func (e *CELEvaluator) CacheTTL() time.Duration

func (*CELEvaluator) Evaluate

func (e *CELEvaluator) Evaluate(activation map[string]any) Result

func (*CELEvaluator) Name

func (e *CELEvaluator) Name() string

Name returns the writes field — the canonical identifier used as the result key, CEL variable name for downstream evaluators, and execution order node.

func (*CELEvaluator) Reads

func (e *CELEvaluator) Reads() []FieldRef

func (*CELEvaluator) ResolutionWorkflow

func (e *CELEvaluator) ResolutionWorkflow() string

func (*CELEvaluator) Writes

func (e *CELEvaluator) Writes() FieldRef

type CachedResult

type CachedResult struct {
	Result      Result
	EvaluatedAt time.Time
	Fingerprint string // hash of proto input fields; empty if not computed
}

CachedResult wraps a Result with the time it was evaluated and an optional fingerprint of the input fields used to produce it. The caller owns persistence — the engine is stateless.

type Engine

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

Engine loads evaluation definitions, compiles CEL expressions, builds the dependency graph, and runs all evaluators against a proto input.

func NewEngine

func NewEngine(cfg *EvalConfig, input proto.Message, opts ...cel.EnvOption) (*Engine, error)

NewEngine creates an evaluation engine from a config and a proto message that serves as the input type. The proto is registered in the CEL environment as the variable "input" — YAML expressions reference fields as "input.<field>". Extra opts are forwarded to NewCELEnvironment for additional declarations.

func NewEngineFromBytes

func NewEngineFromBytes(data []byte, input proto.Message, opts ...cel.EnvOption) (*Engine, error)

NewEngineFromBytes loads evaluation definitions from raw YAML bytes.

func NewEngineFromFile

func NewEngineFromFile(path string, input proto.Message, opts ...cel.EnvOption) (*Engine, error)

NewEngineFromFile loads evaluation definitions from a YAML file.

func (*Engine) DeriveStatus

func (e *Engine) DeriveStatus(results []Result) Status

DeriveStatus derives the overall status from evaluation results.

func (*Engine) Evaluators

func (e *Engine) Evaluators() []Evaluator

Evaluators returns all registered evaluators.

func (*Engine) Graph

func (e *Engine) Graph() *EvalGraph

Graph returns the dependency graph.

func (*Engine) Run

func (e *Engine) Run(input proto.Message) []Result

Run executes all evaluators in dependency order against the given input. The proto is bound to the "input" CEL variable. Upstream evaluator results are injected by their writes-field name for downstream expressions.

func (*Engine) RunMap

func (e *Engine) RunMap(input proto.Message) map[string]Result

RunMap executes all evaluators and returns results indexed by name.

func (*Engine) RunWithCache

func (e *Engine) RunWithCache(input proto.Message, cache map[string]CachedResult, now time.Time) ([]Result, map[string]bool)

RunWithCache executes evaluators, reusing cached results that are still within their CacheTTL. The caller owns the cache — the engine is stateless. Pass time.Now() as now; a zero now disables caching (equivalent to Run). Returns the full result set and a map indicating which evaluators were served from cache (true = reused, absent = re-evaluated).

func (*Engine) RunWithCacheMap

func (e *Engine) RunWithCacheMap(input proto.Message, cache map[string]CachedResult, now time.Time) (map[string]Result, map[string]bool)

RunWithCacheMap is like RunWithCache but returns results indexed by name.

func (*Engine) ToCachedResults

func (e *Engine) ToCachedResults(results []Result, input proto.Message, evaluatedAt time.Time) map[string]CachedResult

ToCachedResults converts results into a cache map with fingerprints computed from the evaluator's input reads and the proto message.

type EvalConfig

type EvalConfig struct {
	Evaluations []EvalDefinition `yaml:"evaluations"`
}

EvalConfig is the top-level YAML structure.

func LoadDefinitions

func LoadDefinitions(r io.Reader) (*EvalConfig, error)

LoadDefinitions parses evaluation definitions from a reader.

func LoadDefinitionsFromFile

func LoadDefinitionsFromFile(path string) (*EvalConfig, error)

LoadDefinitionsFromFile loads evaluation definitions from a YAML file.

type EvalDefinition

type EvalDefinition struct {
	Name               string        `yaml:"name"`
	Description        string        `yaml:"description"`
	Expression         string        `yaml:"expression"`
	Reads              []FieldRef    `yaml:"reads"`
	Writes             FieldRef      `yaml:"writes"`
	ResolutionWorkflow string        `yaml:"resolution_workflow"`
	Resolution         string        `yaml:"resolution"`
	Severity           string        `yaml:"severity"`
	Category           string        `yaml:"category"`
	CacheTTL           string        `yaml:"cache_ttl"`
	CacheTTLDuration   time.Duration `yaml:"-"`
}

EvalDefinition is a single evaluator loaded from YAML.

type EvalGraph

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

EvalGraph holds the auto-calculated dependency graph derived from evaluator reads/writes declarations.

func BuildGraph

func BuildGraph(evaluators []Evaluator) (*EvalGraph, error)

BuildGraph derives the dependency graph from evaluator declarations. Reads prefixed with "input." are treated as raw proto field references — no producer dependency is created for them.

func (*EvalGraph) BlockedBy

func (g *EvalGraph) BlockedBy(name string, results map[string]Result) []string

BlockedBy returns the names of upstream evaluators that have not passed.

func (*EvalGraph) DependenciesMet

func (g *EvalGraph) DependenciesMet(name string, results map[string]Result) bool

DependenciesMet returns true if all upstream dependencies of the given evaluator have passed.

func (*EvalGraph) ExecutionOrder

func (g *EvalGraph) ExecutionOrder() []string

ExecutionOrder returns the topologically sorted evaluator names.

func (*EvalGraph) Issues

func (g *EvalGraph) Issues() []Issue

Issues returns all validation issues found during graph construction.

func (*EvalGraph) MaxDepth

func (g *EvalGraph) MaxDepth() int

MaxDepth returns the longest dependency chain length.

type Evaluator

type Evaluator interface {
	Name() string
	Reads() []FieldRef
	Writes() FieldRef
	CacheTTL() time.Duration
	ResolutionWorkflow() string
	Evaluate(activation map[string]any) Result
}

Evaluator is the interface for all evaluators.

type FieldRef

type FieldRef string

FieldRef is a dependency reference — either an evaluator output (bare name like "score_sufficient") or an input field path (like "input.email_verified"). Reads prefixed with "input." refer to the proto passed to Engine.Run.

func (FieldRef) String

func (f FieldRef) String() string

String returns the string representation.

type Issue

type Issue struct {
	Type     string // "circular_dependency", "missing_producer", "duplicate_producer", "orphan_output"
	Severity string // "error", "warning", "info"
	Message  string
}

Issue represents a validation issue found in the dependency graph.

type Result

type Result struct {
	Name               string
	Passed             bool
	Error              string
	Resolution         string
	ResolutionWorkflow string
	Severity           string
	Category           string
}

Result represents the outcome of a single evaluator run.

type Status

type Status string

Status represents the logical outcome of evaluating all results.

const (
	StatusAllPassed      Status = "StatusAllPassed"      // every evaluation passed
	StatusWorkflowActive Status = "StatusWorkflowActive" // a resolution workflow is running
	StatusActionRequired Status = "StatusActionRequired" // a failing eval needs manual action
	StatusBlocked        Status = "StatusBlocked"        // a failing eval's dependencies aren't met
)

func DeriveStatus

func DeriveStatus(results []Result, graph *EvalGraph) Status

DeriveStatus determines the overall status from evaluation results. Status is derived, never stored directly — it reflects the current state of all evaluations.