Documentation
¶
Overview ¶
Package summary holds the feature summarizer's model calls (features/README.md, "Summarizer"): the input rendered for one feature and for one pull request, the reply schemas, and the validation of a reply. The host supplies its prompt versions (Prompts); Public are the published ones. It makes no call and reads no database.
Index ¶
- Constants
- Variables
- func ContentHash(version, input string) string
- func MaxPullRequestInputBytes() int
- func ParsePullRequestReply(data []byte) (string, error)
- func RenderPullRequest(input PullRequestInput) (string, []int, error)
- func Schema(kind Kind) map[string]any
- func WithCurrent(input, title, description string) (string, error)
- func WithRepository(input, name string) (string, error)
- type Cut
- type Decision
- type FeatureInput
- type Kind
- type Prompts
- func (p Prompts) KnownPromptVersion(version string) bool
- func (p Prompts) PromptVersions() []string
- func (p Prompts) PullRequestVersion(version string) string
- func (p Prompts) Request(version string, kind Kind, input string, maxOutputTokens int64) (decisions.ModelRequest, error)
- func (p Prompts) UsesCurrentText(version string) bool
- func (p Prompts) VersionOf(req decisions.ModelRequest) (string, Kind, bool)
- type PullRequestInfo
- type PullRequestInput
- type RenderedFeature
- type Review
- type ReviewDecision
- type Text
- type Version
Constants ¶
const ( DefaultMaxInputBytes = 200_000 MinInputBytes = 16 << 10 MaxInputBytes = 1 << 20 )
Bounds of a feature's rendered input in bytes, a host's setting.
const ( MaxTitleRunes = 120 MaxDescriptionRunes = 1000 MaxDigestRunes = 3000 MaxSummaryRunes = 1500 // MaxKeyDecisions is how many key decisions are kept. MaxKeyDecisions = 3 )
Bounds of a reply's text; a longer one is invalid.
const MaxCurrentTextBytes = 6*(MaxTitleRunes+MaxDescriptionRunes+maxRepositoryRunes) + 96
MaxCurrentTextBytes bounds what WithRepository and WithCurrent add to an input: every field at its bound, each rune escaped to six bytes, plus the framing. A version that UsesCurrentText renders its input this much smaller.
const MaxOutputTokens = 8192
MaxOutputTokens caps a reply, reasoning included.
const PublicVersion = "feature-summary-public-v1"
PublicVersion is the published prompt version.
Variables ¶
var ErrInvalidReply = errors.New("invalid feature summary reply")
ErrInvalidReply is a reply that does not match its schema or lacks the text it must have.
var ErrTooLarge = errors.New("the feature's input does not fit its bound")
ErrTooLarge is a feature whose input cannot be cut down to its bound.
var Public = Prompts{ PublicVersion: {Feature: publicFeaturePrompt, PullRequest: publicPullRequestPrompt, CurrentText: true}, }
Public are the published prompt versions: one whose feature call reads the feature's current text.
Functions ¶
func ContentHash ¶
ContentHash identifies a pull request's rendered input under a prompt version: an unchanged hash means an unchanged summary.
func MaxPullRequestInputBytes ¶
func MaxPullRequestInputBytes() int
MaxPullRequestInputBytes bounds RenderPullRequest's output: every field at its bound, each rune escaped to six bytes, plus the JSON framing.
func ParsePullRequestReply ¶
ParsePullRequestReply decodes and validates a reply to a pull request's call and returns its summary.
func RenderPullRequest ¶
func RenderPullRequest(input PullRequestInput) (string, []int, error)
RenderPullRequest is the user message of a pull request's call, every field truncated to its bound, superseded decisions left out, at most maxPullRequestDecision decisions. Its size depends on no input's. It also returns the indexes in input.Decisions of the decisions rendered.
func Schema ¶
Schema is the JSON Schema of a reply of the kind, valid under OpenAI strict structured outputs.
func WithCurrent ¶
WithCurrent adds the feature's current title and description to a rendered feature input as its last field, "current", for a version that UsesCurrentText. They are truncated to a reply's bounds, so the input grows by a bounded amount.
func WithRepository ¶
WithRepository adds the name of the feature's repository to a rendered feature input as a field, "repository", for a version that UsesCurrentText, so its text can place the work in its product.
Types ¶
type Cut ¶
type Cut struct {
SupersededDecisions int
ReviewFindings int
ReviewDecisions int
PullRequestDescriptions int
Decisions int
Paths int
PullRequests int
}
Cut counts what was left out of a feature's input to keep it within its bound, in the order it is left out.
type Decision ¶
type Decision struct {
Summary, Category, Who, Trigger, Rationale, RejectedAlternative string
Superseded bool
Files []string
}
Decision is a current decision attributed to the feature: what was decided and why, never a session's prompts or the decision's quoted evidence.
type FeatureInput ¶
type FeatureInput struct {
PullRequests []PullRequestInfo
Decisions []Decision
Paths []string
}
FeatureInput is everything one feature's call is written from. Pull requests and decisions are earliest first.
type Prompts ¶
Prompts are a host's released prompt versions, by name.
func (Prompts) KnownPromptVersion ¶
KnownPromptVersion reports whether version is a released prompt version.
func (Prompts) PromptVersions ¶
PromptVersions lists the released prompt versions, sorted.
func (Prompts) PullRequestVersion ¶
PullRequestVersion is the version whose pull request prompt version uses.
func (Prompts) Request ¶
func (p Prompts) Request(version string, kind Kind, input string, maxOutputTokens int64) (decisions.ModelRequest, error)
Request is the call of the kind for a rendered input under prompt version version.
func (Prompts) UsesCurrentText ¶
UsesCurrentText reports whether version's feature call reads the feature's current text.
type PullRequestInfo ¶
type PullRequestInfo struct {
Number int32
State string
Title, Body string
// Summary is its review's summary, or the one generated for it.
Summary string
// Review is its current review; nil when it has none.
Review *Review
}
PullRequestInfo is one of a feature's pull requests, as the model sees it.
type PullRequestInput ¶
PullRequestInput is what a pull request's generated summary is written from: its title, description and the current decisions attributed to it.
type RenderedFeature ¶
type RenderedFeature struct {
Input string
// Current maps the id of each rendered decision that is not superseded
// to its index in FeatureInput.Decisions; only these can be key
// decisions.
Current map[string]int
// Rendered lists the indexes in FeatureInput.Decisions of every
// rendered decision.
Rendered []int
// PullRequests lists the indexes in FeatureInput.PullRequests of every
// rendered pull request.
PullRequests []int
// ReviewDecisions lists, for each pull request in FeatureInput, the
// indexes in its Review.Decisions of those rendered.
ReviewDecisions [][]int
Cut Cut
}
RenderedFeature is the user message of a feature's call.
func RenderFeature ¶
func RenderFeature(input FeatureInput, maxBytes int) (RenderedFeature, error)
RenderFeature is the user message of a feature's call: the input as JSON, every field truncated to its bound, and at most maxBytes long. When it is longer, superseded decisions are left out first, earliest first; then review findings and then review decisions, of the earliest pull request first; then pull request descriptions, earliest first; then current decisions, earliest first; then paths; then pull requests, earliest first.
type Review ¶
type Review struct {
// Findings are its attention notes.
Findings []string
Decisions []ReviewDecision
}
Review is what a feature's text takes from a pull request's review.
type ReviewDecision ¶
type ReviewDecision struct {
By, Text, Rejected string
}
ReviewDecision is a decision a review cites.
type Text ¶
type Text struct {
Title, Description, Digest string
// KeyDecisions are indexes in FeatureInput.Decisions, at most
// MaxKeyDecisions, each a rendered, current decision.
KeyDecisions []int
// DroppedKeyDecisions counts the ids the reply named that are not a
// rendered, current decision, or past MaxKeyDecisions.
DroppedKeyDecisions int
}
Text is a validated reply to a feature's call.
func ParseFeatureReply ¶
func ParseFeatureReply(data []byte, rendered RenderedFeature) (Text, error)
ParseFeatureReply decodes and validates a reply against the rendered input. A key decision that is not one of its current decisions is dropped.
type Version ¶
type Version struct {
Feature, PullRequest string
// PullRequestVersion names the version whose pull request prompt this
// one reuses, so a generated pull request summary is hashed, and its
// request named, under the version that owns the prompt and stays
// reusable. Empty when it owns its own.
PullRequestVersion string
// CurrentText marks a version whose feature call also reads the
// feature's current title and description (WithCurrent), so its title
// stays stable.
CurrentText bool
}
Version is a released prompt version: its feature and pull request prompt. A released prompt is never edited; a change is a new version.