crewroute

type Allowed struct {
	Base Base
	// MaxIn and MaxOut are the price rule's two ceilings, dollars per million
	// tokens. Zero on every other base.
	MaxIn  float64
	MaxOut float64
	// Members are an explicit list's words.
	Members []string
	// Mods are the `+x` / `-x` words, in the order they were written.
	Mods []Mod
}

type Base string

type Candidate struct {
	Model  Model
	Routes []Route
}

type Canon struct {
	ID      string
	Variant string
}

type Class string

type Decision struct {
	Class  Class
	Why    string
	Sure   bool
	Effort Effort
	Steps  int
	// Lambda is the price of a quality point the crew was picked at.
	Lambda float64
	Crew   []Pick
	// EstUSD is the crew's estimated cost for an ordinary task of its class.
	EstUSD  float64
	Quality float64
	// OneOff is a stronger redo of a crew whose every seat was pinned: the
	// pins were stepped over for this one run and are unchanged.
	OneOff bool
	// Considered is how many candidates the decision chose among.
	Considered int
	// Ladder is, for each unpinned seat, where the seat goes when its call
	// fails to start, in order: the same model on its next routes, then the
	// next qualified models at a similar cost. The caller adds what only it
	// knows — the last crew that worked, the model the person is talking to.
	Ladder map[Seat][]Pick `json:"-"`
	// Retried are the seats that moved down their ladder during the task, in
	// the order they moved, so the line can say so.
	Retried []Retry `json:",omitempty"`
	// Rungs are what a redo or an effort word changed against the crew it
	// would otherwise have run, seat by seat.
	Rungs []Retry `json:",omitempty"`
	// Note is one plain sentence the line ends on: an effort word that changed
	// nothing, or the free routes taken because nothing paid could be.
	Note string `json:",omitempty"`
	// Stopped is the one action a task stopped on when a seat had nowhere
	// left to go and the failure said why — credit, a key, a limit. The line
	// leads with it and offers no stronger redo, which could not help.
	Stopped string `json:",omitempty"`
	// Redo is whether this crew was asked for by a redo of a task that ran
	// before. Its own acceptance is the redo's, not a later task's: it must
	// not take back the step the redo just taught.
	Redo bool `json:",omitempty"`
	// Subclass is, for a bugfix, "complex" or "simple" ([complexFix]), with
	// Reach the signals that made it complex. The log keeps it; every line a
	// person reads still says bugfix.
	Subclass string `json:",omitempty"`
	Reach    string `json:",omitempty"`
	// CostFactor is what this install's own tasks of the class have cost
	// against their estimates ([router.CrewLog.CostFactor]); EstUSD carries
	// it. Zero is none learned yet.
	CostFactor float64 `json:",omitempty"`
}

type Effort string

type Gap struct {
	Class Class
	Seat  Seat
	Line  string
}

type Mod struct {
	Add  bool
	Word string
}

type Model struct {
	ID              string
	Open            bool
	PromptPrice     float64
	CompletionPrice float64
	CacheReadPrice  float64
	Intelligence    float64
	Coding          float64
	Agentic         float64
	// ArenaElo is the best design-arena Elo the row publishes, zero for none.
	ArenaElo float64
	Context  int
	// Released is when the model was released, the zero time when the row
	// does not say.
	Released time.Time
	// Tools is whether the model takes tool calls. A crew seat is an agent
	// loop, so a model that cannot call a tool cannot sit one.
	Tools bool
}

type NoCandidateError struct{ Seat Seat }

type Pick struct {
	Seat     Seat
	Model    string
	Provider string
	Send     string
	Kind     RouteKind
	Pinned   bool
	Quality  float64
	// SD is the standard deviation of Quality under the weights.
	SD float64 `json:",omitempty"`
	// Learned is the part of Quality this install's own outcomes moved.
	Learned float64 `json:",omitempty"`
	CostUSD float64
	// EstUSD is what this seat is expected to cost the task ([table.classCost]):
	// nothing on a plan, a local model or a free pool.
	EstUSD float64 `json:",omitempty"`
}

type Pin struct {
	Model    string
	Provider string
	Send     string
	Kind     RouteKind
}

type ProvidersOff map[string]bool

type Reading struct {
	Class Class
	Why   string
	Sure  bool
	// Complex is, for a bugfix, the signals that make it a fix with reach
	// ([complexFix]), in words; empty is a simple fix. It names no class of
	// its own — the task is still a bugfix on every line a person reads — and
	// it moves only the worker ([Decide]).
	Complex string
}

type Request struct {
	Task Task
	// Class, when set, is taken as given and the classifier is not asked — a
	// replay, or a caller that already knows.
	Class Class
	// Reading, when set, is the classifier's whole answer as the caller
	// already read it — the class, why, how sure, and a fix's reach — and is
	// taken as it stands. A caller that classifies first to key its learned
	// offset hands the reading on here rather than the class alone, which
	// dropped the reach and ran every complex fix on the simple fix's worker.
	Reading *Reading
	// Candidates are the allowed models reachable on a connected provider.
	Candidates []Candidate
	// Pins are the seats the person fixed. A pinned seat always runs its pin.
	Pins   map[Seat]Pin
	Effort Effort
	// Steps is how many escalation steps above the knee to start: the learned
	// offset for this repository and class, which decays as tasks are accepted.
	Steps int
	// Pace multiplies λ as a daily cap is approached ([Pace]); zero is one.
	Pace float64
	// Stronger is the crew that ran, when the person asked to redo the task
	// stronger: every unpinned seat is picked at least as strong, and the crew
	// as a whole strictly stronger, or the decision says it cannot be.
	Stronger *Decision
	// Again is the crew that ran and NEVER STARTED — its seats' first calls
	// were refused — when the person asks to redo it: the task never ran, so it
	// is asked again at the same λ on the next-best models, not escalated.
	Again *Decision
	// Avoid are model lineages that failed to start on this install recently
	// ([Lineage]). An unpinned seat is not given one while anything else can
	// sit it; a pin is never overruled.
	Avoid map[string]bool
	// Learned is this install's move to a model's quality in a seat, by
	// [LearnKey]: what its tasks kept or redid there ([router.CrewLog]).
	Learned map[string]float64
	// TaskCap is the most one task may be estimated to cost; zero is none. A
	// crew estimated over it is not chosen, whatever the effort word.
	TaskCap float64
	// CostFactor is this install's learned ratio of what its tasks of the
	// class cost to their estimates; zero is none learned.
	CostFactor float64
	// Rescue is a seat's LAST RUNG being picked — the free pools when nothing
	// paid can be reached — rather than a crew being chosen: any model that
	// can sit the seat (tools, context, a route) is taken, best first, though
	// it publishes too little for the router to trust it as a first pick. A
	// seat that runs on a thinly described model says so on its line; a seat
	// that does not run at all says nothing useful.
	Rescue bool
}

type Retry struct {
	Seat Seat
	From string
	To   string
	Why  string `json:",omitempty"`
}

type Route struct {
	Provider string
	Send     string
	Kind     RouteKind
	// FailRate is this install's learned chance that the route refuses a
	// task's first call, zero when nothing is known — a free route then reads
	// [freeFailPrior].
	FailRate float64
}

type RouteKind string

type Scored struct {
	Model    string    `json:"m"`
	Provider string    `json:"p,omitempty"`
	Kind     RouteKind `json:"k,omitempty"`
	Quality  float64   `json:"q"`
	CostUSD  float64   `json:"c"`
	Score    float64   `json:"s"`
}

type Seat string

type Task struct {
	Text   string
	Labels []string
}