assign

package
v0.1.0-rc.2 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
const (
	MaxNewTitleRunes       = 120
	MaxNewDescriptionRunes = 1000
)

Bounds of a new feature's text in a reply; a longer one is invalid.

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

View Source
const (
	PublicVersion      = "feature-assign-public-v1"
	PublicBatchVersion = PublicVersion + "-batch"
)

PublicVersion is the published single-item prompt version, and PublicBatchVersion its batch version.

View Source
const BatchSchemaName = "feature_assignment_batch"

BatchSchemaName names BatchSchema in decisions.ModelRequest.SchemaName.

View Source
const CandidatesEnd = "There may be no candidates."

CandidatesEnd ends a batch frame's description of the candidates; a seeded note follows it.

View Source
const MaxCandidates = 32

MaxCandidates bounds the number of candidates a host offers one call.

View Source
const MaxOutputTokens = 4096

MaxOutputTokens caps a reply, reasoning included; a reply needs a few hundred.

View Source
const SchemaName = "feature_assignment"

SchemaName names Schema in decisions.ModelRequest.SchemaName.

Variables

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

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

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

func BatchSchema() map[string]any

BatchSchema is the JSON Schema of a batch reply, valid under OpenAI strict structured outputs.

func CutDefinition

func CutDefinition(single string) (definition, rest string, err error)

CutDefinition is a single-item prompt's definition of a feature and the rest of the prompt after its reply instruction.

func MaxInputBytes

func MaxInputBytes(candidates int) int

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

func MentionedPullRequests(title, body string) []int32

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

func SampledPullRequests(n int) []int

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

func SearchQuery(item Item) string

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

type Decision struct {
	Category, Summary string
	Files             []string
}

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.

func (Item) Paths

func (i Item) Paths() []string

Paths are the item's touched paths: a pull request's, or the files a session's decisions cite. Sorted and without duplicates.

type Limits

type Limits struct {
	MaxInputBytes   int
	MaxOutputTokens int64
}

Limits are the bounds of a call under a version: its rendered input and its reply.

type Links struct {
	Stacked, SharedSessions, Mentioned []int32
}

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

func NewPrompts(single map[string]Version, batches map[string]Batch) *Prompts

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

func (p *Prompts) BatchVersion(version string) (string, bool)

BatchVersion is the batch version of single-item version version, if it has one.

func (*Prompts) KnownBatchPromptVersion

func (p *Prompts) KnownBatchPromptVersion(version string) bool

KnownBatchPromptVersion reports whether version is a batch version. A batch version is never a host's configured single-item version.

func (*Prompts) KnownPromptVersion

func (p *Prompts) KnownPromptVersion(version string) bool

KnownPromptVersion reports whether version is a released prompt version.

func (*Prompts) LimitsOf

func (p *Prompts) LimitsOf(version string) (Limits, bool)

LimitsOf are the bounds of a call under version, single-item or batch; false for an unknown version.

func (*Prompts) ListsCandidates

func (p *Prompts) ListsCandidates(version string) bool

ListsCandidates reports whether version's input shows each candidate's digest and pull requests, which the caller must then supply.

func (*Prompts) ParseReply

func (p *Prompts) ParseReply(version string, data []byte, candidates []Candidate) (Choice, error)

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

func (p *Prompts) Prompt(version string) (string, bool)

Prompt is single-item version version's prompt.

func (*Prompts) PromptVersions

func (p *Prompts) PromptVersions() []string

PromptVersions lists the released prompt versions, sorted.

func (*Prompts) Render

func (p *Prompts) Render(version string, item Item, candidates []Candidate) (string, error)

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

func (p *Prompts) Schema(version string) map[string]any

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

func (p *Prompts) SeededBatch(batch string) string

SeededBatch is the version a batch call offering seeded features uses: batch's seeded form, or batch itself when it has none.

func (*Prompts) VersionOf

func (p *Prompts) VersionOf(req decisions.ModelRequest) (string, bool)

VersionOf returns the prompt version, single-item or batch, req was built with by Request, so a model that sends only the input can name it to the far side.

type PullRequest

type PullRequest struct {
	Title, Body, Branch string
	Paths               []string
}

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.

Jump to

Keyboard shortcuts

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