Documentation
¶
Overview ¶
Package patterns compiles the patterns allowed in harness config (design/03-domain-model.md §Patterns in harness config) and resolves a constraint, a request and an agent's offer into one concrete harness config.
The package is pure: no I/O, no clock, no global mutable state.
Index ¶
Constants ¶
const DefaultEffort = "medium"
DefaultEffort is the effort chosen when the request does not rank efforts (e.g. `*`) and the agent offers it; otherwise the first offered candidate is chosen.
const RegexPrefix = "re:"
RegexPrefix opts a pattern into Go RE2 syntax, e.g. `re:^gpt-5(\.\d+)?-codex$`. The regex is used as written: it is not anchored for you.
Variables ¶
var ErrNoMatch = errors.New("no match")
ErrNoMatch is matched by every *NoMatchError, so errors.Is(err, ErrNoMatch) tells the scheduler the agent cannot run the task (no-capable-agent once no agent can).
Functions ¶
func Subsumes ¶
func Subsumes(c Constraint, req Request, known []string) (ok bool, witness string)
Subsumes reports whether at least one of the known models (an adapter's capabilities file) satisfies both the constraint and the request, and returns the first such model as the witness. Catalog validation uses it to flag requests that can never fit their constraint.
Types ¶
type Constraint ¶
Constraint bounds what one harness may run (from TaskSpec.harness.allowed). A nil Pattern matches anything.
func ConstraintFrom ¶
func ConstraintFrom(c v1alpha1.HarnessConstraint) (Constraint, error)
ConstraintFrom compiles a TaskSpec harness constraint. An unset field matches anything.
func ConstraintsFrom ¶
func ConstraintsFrom(cs []v1alpha1.HarnessConstraint) ([]Constraint, error)
ConstraintsFrom compiles every constraint of a TaskSpec's harness.allowed, in order.
type NoMatchError ¶
NoMatchError says why an offer cannot satisfy a request within its constraints.
func (*NoMatchError) Error ¶
func (e *NoMatchError) Error() string
func (*NoMatchError) Is ¶
func (e *NoMatchError) Is(target error) bool
Is makes errors.Is(err, ErrNoMatch) true.
type Offer ¶
Offer is what an agent can run with one harness: concrete values, in the agent's order.
func OfferFrom ¶
func OfferFrom(o v1alpha1.HarnessOffer) Offer
OfferFrom builds an Offer from an agent's probed HarnessOffer.
type Pattern ¶
type Pattern interface {
// Match reports whether s matches the pattern. Matching is case-sensitive.
Match(s string) bool
// String returns the pattern as written.
String() string
}
Pattern matches strings. Patterns are immutable and safe for concurrent use.
func Compile ¶
Compile compiles v, which is a string, a []string or a v1alpha1.StringOrList.
A string is one of:
- `*`: matches anything;
- `re:<regex>`: a Go RE2 regex, anchored as written;
- a glob, if it contains `*`, `?`, `{`, `}` or `\`: `*` matches any run of characters, `?` exactly one, `{a,b}` either alternative (alternatives may nest and contain globs), `\` escapes the next character; the glob must match the whole string;
- otherwise an exact string.
A list matches when any element does; earlier elements are preferred (see Resolve). Empty strings, empty lists, invalid UTF-8, bad regexes and unbalanced braces are reported as a *PatternError.
type PatternError ¶
type PatternError struct {
Pattern string // the offending pattern (or list element) as written
Reason string // what is wrong with it
Err error // the underlying regexp error, if any
}
PatternError reports a pattern that does not compile.
func (*PatternError) Error ¶
func (e *PatternError) Error() string
func (*PatternError) Unwrap ¶
func (e *PatternError) Unwrap() error
Unwrap returns the underlying regexp error, if any.
type Request ¶
Request asks for a harness config (rule, ruleset or TaskSpec default). A nil Pattern matches anything. Prefer lists exact model ids, most preferred first.
func RequestFrom ¶
func RequestFrom(r v1alpha1.HarnessRequest) (Request, error)
RequestFrom compiles a harness request. A nil config or an unset field matches anything.
type Resolved ¶
type Resolved struct {
Harness, Model, Effort string
}
Resolved is the concrete harness config chosen for a task.
func Resolve ¶
func Resolve(cs []Constraint, req Request, off Offer) (Resolved, error)
Resolve picks the harness config an agent's offer runs for a request, within the first constraint for the requested harness (design/workstreams/dispatcher-core/LLD/patterns.md):
- the offer and some constraint must be for the requested harness;
- candidate models = offer ∩ constraint ∩ request, in offer order;
- the model is the first candidate in req.Prefer; else, when req.Model is a list, the candidates matching its earliest matching element are kept; then the offer's default model if it is still a candidate; else the highest version (see compareVersions);
- candidate efforts = offer ∩ constraint ∩ request; when req.Effort is a list, those matching its earliest matching element are kept; then DefaultEffort if it is still a candidate, else the first one in offer order;
- the result.
When a step has no candidate, the error is a *NoMatchError with that step's Reason.
func (Resolved) HarnessResolved ¶
func (r Resolved) HarnessResolved(off v1alpha1.HarnessOffer) v1alpha1.HarnessResolved
HarnessResolved returns r as written into Task.spec.harness.resolved, taking the harness version and auth from the offer it was resolved against.