patterns

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

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

View Source
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.

View Source
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

View Source
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.

func Validate

func Validate(v any) error

Validate reports whether v compiles; it is Compile for callers that only check the catalog.

Types

type Constraint

type Constraint struct {
	Harness string
	Models  Pattern
	Effort  Pattern
}

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

type NoMatchError struct {
	Reason  Reason
	Harness string
}

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

type Offer struct {
	Harness      string
	Models       []string
	Efforts      []string
	DefaultModel string
}

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 Any

func Any() Pattern

Any returns the pattern that matches every string (`*`).

func Compile

func Compile(v any) (Pattern, error)

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 Reason

type Reason string

Reason says which step of Resolve found no candidate.

const (
	ReasonHarness Reason = "harness"
	ReasonModel   Reason = "model"
	ReasonEffort  Reason = "effort"
)

The reasons a NoMatchError carries.

type Request

type Request struct {
	Harness string
	Model   Pattern
	Effort  Pattern
	Prefer  []string
}

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):

  1. the offer and some constraint must be for the requested harness;
  2. candidate models = offer ∩ constraint ∩ request, in offer order;
  3. 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);
  4. 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;
  5. 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL