Documentation
¶
Overview ¶
Package assign holds the feature assigner's model call (features/README.md, "Assigner"): the input it renders for one pull request or session and its candidate features, the reply schema, and the validation of a reply; and the batch path, which assigns several pull requests in one call under the same rules (batch.go). The host supplies its prompt versions (Prompts); Public are the published ones. It makes no call and reads no database.
Index ¶
- Constants
- Variables
- func BatchSchema() map[string]any
- func CutDefinition(single string) (definition, rest string, err error)
- func MaxInputBytes(candidates int) int
- func MentionedPullRequests(title, body string) []int32
- func SampledPullRequests(n int) []int
- func SearchQuery(item Item) string
- type Batch
- type BatchChoice
- type BatchItem
- type BatchReply
- type Candidate
- type CandidatePullRequest
- type Choice
- type Decision
- type Item
- type Limits
- type Links
- type NewFeature
- type Prompts
- func (p *Prompts) BatchVersion(version string) (string, bool)
- func (p *Prompts) KnownBatchPromptVersion(version string) bool
- func (p *Prompts) KnownPromptVersion(version string) bool
- func (p *Prompts) LimitsOf(version string) (Limits, bool)
- func (p *Prompts) ListsCandidates(version string) bool
- func (p *Prompts) ParseReply(version string, data []byte, candidates []Candidate) (Choice, error)
- func (p *Prompts) Prompt(version string) (string, bool)
- func (p *Prompts) PromptVersions() []string
- func (p *Prompts) Render(version string, item Item, candidates []Candidate) (string, error)
- func (p *Prompts) RenderBatch(version string, items []BatchItem, candidates []Candidate) (string, error)
- func (p *Prompts) Request(version, input string, maxOutputTokens int64) (decisions.ModelRequest, error)
- func (p *Prompts) Schema(version string) map[string]any
- func (p *Prompts) SeededBatch(batch string) string
- func (p *Prompts) VersionOf(req decisions.ModelRequest) (string, bool)
- type PullRequest
- type Session
- type Version
Constants ¶
const ( MaxNewTitleRunes = 120 MaxNewDescriptionRunes = 1000 )
Bounds of a new feature's text in a reply; a longer one is invalid.
const ( MaxBatchItems = 50 MaxBatchCandidates = 48 MaxBatchInputBytes = 768 << 10 MaxBatchOutputTokens = 32768 )
Bounds of a batch: its items and candidates, the rendered input, and the reply, reasoning included. The input bound is in bytes: at the two to three bytes a token that JSON of paths and identifiers runs at, 768 KiB is about the default context of the decision service's models (272000 tokens), so most batches too large for the model are refused here, where the caller can split them; a caller still treats a provider's refusal as a reason to split. It is well inside the decision service's request limit.
const ( PublicVersion = "feature-assign-public-v1" PublicBatchVersion = PublicVersion + "-batch" )
PublicVersion is the published single-item prompt version, and PublicBatchVersion its batch version.
const BatchSchemaName = "feature_assignment_batch"
BatchSchemaName names BatchSchema in decisions.ModelRequest.SchemaName.
const CandidatesEnd = "There may be no candidates."
CandidatesEnd ends a batch frame's description of the candidates; a seeded note follows it.
const MaxCandidates = 32
MaxCandidates bounds the number of candidates a host offers one call.
const MaxOutputTokens = 4096
MaxOutputTokens caps a reply, reasoning included; a reply needs a few hundred.
const SchemaName = "feature_assignment"
SchemaName names Schema in decisions.ModelRequest.SchemaName.
Variables ¶
var ErrBatchTooLarge = errors.New("the feature assignment batch is too large")
ErrBatchTooLarge is a batch whose rendered input is over MaxBatchInputBytes; the caller assigns fewer items at once.
var ErrInvalidReply = errors.New("invalid feature assignment reply")
ErrInvalidReply is a reply that does not match the schema, names no candidate, or starts a feature without a usable title or description.
var Public = NewPrompts( map[string]Version{PublicVersion: {Prompt: publicPrompt, Skips: true, Lists: true}}, map[string]Batch{PublicBatchVersion: { Single: PublicVersion, Frame: publicBatchFrame, Seeded: PublicBatchVersion + "-2", SeededNote: publicSeededNote, }}, )
Public are the published prompt versions: one that skips and lists, its batch version and that version's seeded form.
Functions ¶
func BatchSchema ¶
BatchSchema is the JSON Schema of a batch reply, valid under OpenAI strict structured outputs.
func CutDefinition ¶
CutDefinition is a single-item prompt's definition of a feature and the rest of the prompt after its reply instruction.
func MaxInputBytes ¶
MaxInputBytes bounds the size of Render's output for candidates candidates under any version: every field at its bound, each rune escaped to six bytes, plus the JSON framing.
func MentionedPullRequests ¶
MentionedPullRequests are the distinct pull request numbers a pull request's title or description mentions as #N, at most maxMentions, in order of appearance.
func SampledPullRequests ¶
SampledPullRequests are the indexes, among a candidate's n pull requests, of those a listing version shows with their summaries, so a host reads only those summaries.
func SearchQuery ¶
SearchQuery is the full-text query candidates are ranked by: the distinct words of at least three letters or digits of a pull request's title, the start of its description and its branch, or of a session's decision summaries, lower-cased and OR-ed in to_tsquery syntax, at most maxSearchWords of them in order of appearance. Only letters and digits reach it, so it always parses. Empty when there is no such word.
Types ¶
type Batch ¶
type Batch struct {
Single, Frame string
// Seeded names the version a rebuild uses for a call that offers seeded
// features (features/README.md, "Batch"): the same prompt with SeededNote after
// the description of the candidates. Empty for none.
Seeded, SeededNote string
}
Batch is a released batch version: the single-item version whose rules it applies, the frame they are set in, and its seeded form.
type BatchChoice ¶
type BatchChoice struct {
FeatureID string
// New is the index in BatchReply.New of the feature the item is in when
// it starts one or joins one an earlier item started; -1 otherwise.
New int
Skip bool
Reason string
}
BatchChoice is the validated choice for one item of a batch: a candidate's id, a feature the reply starts (New, by its index in BatchReply.New), or a skip.
type BatchItem ¶
type BatchItem struct {
PullRequest
Number int32
// Links are, by candidate id, its links to that candidate's pull
// requests.
Links map[string]Links
// Mentions are the indexes of the other items of the batch its title or
// description mentions.
Mentions []int
}
BatchItem is one pull request of a batch.
type BatchReply ¶
type BatchReply struct {
Choices []BatchChoice
New []NewFeature
}
BatchReply is a validated batch reply: a choice per item, in the order of the items, and the features it starts, in the order it starts them.
func ParseBatchReply ¶
func ParseBatchReply(data []byte, items int, candidates []Candidate) (BatchReply, error)
ParseBatchReply decodes and validates a batch reply for items items against the candidates the input listed. Every item is answered exactly once; a new feature's id is defined once, and joined only by an item after the one that started it; nothing outside the candidates and the reply's own features is ever chosen. Any violation fails the whole reply.
type Candidate ¶
type Candidate struct {
ID string
Title, Description string
Paths []string
// Current marks the feature the item is in now.
Current bool
// Withheld is a feature whose text may not be shown: it is rendered
// with its paths and withheldText as its title, and no description.
Withheld bool
// Digest is its digest; empty when withheld.
Digest string
// PullRequests are its pull requests, earliest opened first; a listing
// version shows their number and a sample.
PullRequests []CandidatePullRequest
// Links are its pull requests linked to the item pull request, which a
// listing version shows.
Links Links
}
Candidate is an existing feature the item may join.
type CandidatePullRequest ¶
type CandidatePullRequest struct {
Title, Summary string
}
CandidatePullRequest is one of a candidate's pull requests: its title and the summary its feature text may be written from, empty for none.
type Choice ¶
type Choice struct {
// FeatureID is the chosen candidate's id; empty for a new feature or a
// skip.
FeatureID string
New *NewFeature
Skip bool
Reason string
}
Choice is a validated reply: a candidate's id, a new feature, or a small change to leave in no feature.
type Decision ¶
Decision is one of a session's current decisions, as the model sees it: what was decided and the files it cites, never the session's prompts or the decision's quoted evidence.
type Item ¶
type Item struct {
PullRequest *PullRequest
Session *Session
}
Item is the one pull request or session one call assigns.
type Links ¶
type Links struct {
Links are a candidate's pull requests, by number, that the item pull request is stacked on or that are stacked on it, that share an agent session with its commits, or that its title or description mentions.
type NewFeature ¶
type NewFeature struct {
Title, Description string
}
NewFeature is the provisional text of a feature the reply starts.
type Prompts ¶
type Prompts struct {
// contains filtered or unexported fields
}
Prompts are a host's released prompt versions, single-item and batch (batch.go), by name.
func NewPrompts ¶
NewPrompts composes the batch versions' prompts from the single-item versions and the frames. It panics when a batch version names an unknown single-item version or its prompt or frame cannot be composed, so a host fails at start-up.
func (*Prompts) BatchVersion ¶
BatchVersion is the batch version of single-item version version, if it has one.
func (*Prompts) KnownBatchPromptVersion ¶
KnownBatchPromptVersion reports whether version is a batch version. A batch version is never a host's configured single-item version.
func (*Prompts) KnownPromptVersion ¶
KnownPromptVersion reports whether version is a released prompt version.
func (*Prompts) LimitsOf ¶
LimitsOf are the bounds of a call under version, single-item or batch; false for an unknown version.
func (*Prompts) ListsCandidates ¶
ListsCandidates reports whether version's input shows each candidate's digest and pull requests, which the caller must then supply.
func (*Prompts) ParseReply ¶
ParseReply decodes and validates a reply under prompt version version against the candidates the input listed. Nothing outside them is ever chosen, and only a skipping version skips.
func (*Prompts) PromptVersions ¶
PromptVersions lists the released prompt versions, sorted.
func (*Prompts) Render ¶
Render is the user message of one call under prompt version version: the item and its candidates as JSON, every field truncated to its bound. A candidate's paths list those the item touches first. A listing version also shows each candidate's digest, its number of pull requests and at most maxCandidatePullRequests of them with their summaries, spread over its history and always including its latest. A withheld candidate's digest and summaries are never shown.
func (*Prompts) RenderBatch ¶
func (p *Prompts) RenderBatch(version string, items []BatchItem, candidates []Candidate) (string, error)
RenderBatch is the user message of one batch call under batch version version: the items and the candidates as JSON, every field truncated to its bound. Candidates are rendered as a listing version renders them, their paths that an item shows first; links are on the items, never on the candidates. ErrBatchTooLarge when the result is over MaxBatchInputBytes.
func (*Prompts) Request ¶
func (p *Prompts) Request(version, input string, maxOutputTokens int64) (decisions.ModelRequest, error)
Request is the call for a rendered input under prompt version version, a single-item or a batch version.
func (*Prompts) Schema ¶
Schema is the JSON Schema of a reply under prompt version version, valid under OpenAI strict structured outputs: every field required, "" where a field does not apply. Only a skipping version offers "skip".
func (*Prompts) SeededBatch ¶
SeededBatch is the version a batch call offering seeded features uses: batch's seeded form, or batch itself when it has none.
type PullRequest ¶
PullRequest is a pull request to assign, as the model sees it.
type Session ¶
type Session struct {
Decisions []Decision
}
Session is a root session with no pull request to assign: its decisions and the paths they cite.
type Version ¶
type Version struct {
Prompt string
// Skips marks a version whose reply may skip a small change, leaving it
// in no feature.
Skips bool
// Lists marks a version whose input shows each candidate's digest, its
// number of pull requests and a sample of them with their summaries.
Lists bool
}
Version is a released single-item prompt version. A released prompt is never edited; a change is a new version.