README
¶
features
The rules for grouping a repository's pull requests and agent sessions into
features, without storage: the model calls of the assigner, summarizer and
consolidation, and the pure rules a host applies around them. A host reads
and writes its own store and calls a model through decisions.Model.
Prompts
Each model call package (assign, summary, consolidate) takes its
prompt versions from the host as a Prompts value, so a host keeps its own
versions and their names. A released prompt is never edited; a change is a
new version. Each package also embeds published versions, Public:
| Package | Published version | Traits |
|---|---|---|
assign |
feature-assign-public-v1, its batch version -batch and seeded form -batch-2 |
may skip a small change; lists each candidate's digest and pull requests |
summary |
feature-summary-public-v1 |
the feature call reads the feature's current text; owns its pull request prompt |
consolidate |
feature-consolidate-public-v1 |
the merge call sees each feature's digest and pull request summaries |
discover |
feature-discover-public-v1 |
composed from feature-assign-public-v1's definition of a feature |
A version's name is part of what a host keys stored results on (for example
summary.ContentHash), so published and hosted results never mix.
Assigner
assign renders one pull request or session and its candidate features,
named F1, F2, … so the model never copies an id, every field truncated to
its bound. A reply chooses a candidate, starts a new feature with a title of
at most 120 and a description of at most 1000 characters, or, under a
version that skips, leaves a small change in no feature. Anything else is
invalid.
Batch
A batch version assigns up to 50 pull requests in one call under the rules of
its single-item version: the single-item prompt's definition of a feature and
its # Choosing rules, cut out unchanged, set in a frame that describes the
batch input and reply. A batch version's seeded form adds one note on
candidates with no pull requests (proposed features); a rebuild uses it for
calls that offer them. A reply answers every item exactly once; a new feature
is started once and joined only by a later item. A rendered batch over
768 KiB is refused (ErrBatchTooLarge) for the caller to split.
Summarizer
summary renders one feature (its pull requests, their reviews, its current
decisions and paths) within a byte bound, leaving out superseded decisions,
review findings, review decisions, pull request descriptions, current
decisions, paths and pull requests, in that order. A reply gives a title,
description, digest and at most three key decisions, each a rendered current
decision. A pull request without a summary gets one from its own call.
Consolidation
consolidate renders a repository's features for a merge call, which groups
duplicates, and one oversized feature's pull requests for a split call, which
partitions them. A reply places every member at most once (merge) or exactly
once (split). A reply is bounded by MaxOutputTokens unless the host asks for
more, up to MaxHostOutputTokens.
Discovery
discover holds feature discovery's pure parts. Discovery is an agent task
over a read-only checkout of the default branch (head/) and
history.jsonl, the repository's pull request history digest. Its reply is
a taxonomy: at most 300 features, each with a title of at most 120 and a
description of at most 1000 characters, the path prefixes its code lives
under and example pull requests. ComposePrompt sets the definition of a
feature of an assigner prompt, cut out unchanged, in a frame, so discovery
and assignment group at the same level.
The digest is JSON Lines: a header with the repository, its counts and what was trimmed, then one pull request per line, oldest first, with its number, date opened, state, title, branch and the files its commits touched. Over 4 MiB it drops every branch, then replaces each pull request's files with the five directories (three levels deep) holding most of them, oldest first, then drops the oldest pull requests, each until it fits. It holds no description.
A build seeds its version with the taxonomy's features. A seed is offered to
a pull request by its path score (PathScores): over the item's distinct
paths under a seed's prefixes (Under), one over the number of seeds holding
the path.
Decision attribution
SessionLinks.Attributor gives each current decision of a session exactly
one feature, or none when the session has none:
- Pull requests of one feature linked to the session: that feature.
- Of several features: the pull request whose paths contain most of the
files the decision cites (
decisions.CitedPaths: exactly, or as the one path the file is a/-suffix of); ties to the more dominant feature, then the earlier pull request. - No cited file in any of them: the dominant feature, the one with most of the session's linked commits, ties to the earliest opened pull request.
- No feature pull request: the feature the session is in on its own.
Attributor.PullRequest is the pull request of that feature a decision is
shown under: the one whose paths contain most of its cited files, ties and
no match to the earliest opened.
Status
DeriveStatus: in progress while any pull request is open or there is none
yet, shipped once one merged and none is open, abandoned when all closed
unmerged.
Large update
LargeUpdate: a pull request is assigned again when, with A the paths it
was assigned with and B those it touches now, at least the given share of
A ∪ B and at least the given number of paths are in only one of them.
Documentation
¶
Overview ¶
Package features holds the pure rules of grouping work into features (README.md): which feature a session's decision is attributed to, a feature's status, and when a pull request changed enough to be assigned again. Its subpackages hold the model calls. It reads no database.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LargeUpdate ¶
LargeUpdate reports whether a pull request's paths changed enough since its assignment to assign it again: the path change (1 - |A ∩ B| / |A ∪ B|) is at least minChange and at least minPaths paths differ. A host that selects pending items in its store applies the same rule.
func PathChange ¶
PathChange compares the paths a pull request was assigned with to those it touches now: how many paths are in one set only, and how many are in either.
Types ¶
type Attributor ¶
type Attributor struct {
// contains filtered or unexported fields
}
Attributor attributes one session's decisions to exactly one feature each; it is built once per session, not per decision.
func (Attributor) Attribute ¶
func (a Attributor) Attribute(files []string) string
Attribute is the one feature a decision citing files goes to, "" when the session belongs to none. With pull requests of several features, it goes to the pull request whose paths contain most of the cited files, matched by decisions.CitedPaths, since a cited file may be relative to the session's working directory (ties to the more dominant feature, then the earlier pull request); with no file in any of them, or one feature, to the dominant feature.
func (Attributor) PullRequest ¶
func (a Attributor) PullRequest(featureID string, files []string) string
PullRequest is the pull request of the feature a decision citing files is shown under: of the session's linked pull requests in that feature, the one whose paths contain most of the files, ties (and no match) to the earliest. "" when the session has none in it.
type LinkedPullRequest ¶
type LinkedPullRequest struct {
FeatureID, PullRequestID string
Number int32
OpenedAt time.Time
Commits, Paths []string
}
LinkedPullRequest is a feature's pull request holding commits linked (matched) to a session, and the paths it touches.
type SessionLinks ¶
type SessionLinks struct {
PullRequests []LinkedPullRequest
OwnFeature string
}
SessionLinks is what attributes a session's decisions: the feature pull requests linked to it and the feature it is in on its own.
func (SessionLinks) Attributor ¶
func (s SessionLinks) Attributor() Attributor
Attributor builds the session's Attributor.
func (SessionLinks) Features ¶
func (s SessionLinks) Features() []string
Features are the session's features, dominant first: by the session's linked commits in each feature's pull requests, most first, then by the earliest of those pull requests. A session with no feature pull request has the one it is in on its own, if any.
type Status ¶
type Status string
Status is derived from a feature's pull requests (README.md, "Status").
func DeriveStatus ¶
DeriveStatus is in progress while any pull request is open or there is none yet, shipped once one merged and none is open, and abandoned when all closed unmerged.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
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).
|
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). |
|
Package consolidate holds the feature consolidation's model calls (features/README.md, "Consolidation"): the input rendered for a repository's merge call and for one feature's split call, the reply schemas, and the validation of a reply.
|
Package consolidate holds the feature consolidation's model calls (features/README.md, "Consolidation"): the input rendered for a repository's merge call and for one feature's split call, the reply schemas, and the validation of a reply. |
|
Package discover holds feature discovery's pure parts (features/README.md, "Discovery"): the taxonomy a discovery task replies with and its bounds, the pull request history digest the task reads, the task's prompt and reply schema, and the path score a seeded feature is offered by.
|
Package discover holds feature discovery's pure parts (features/README.md, "Discovery"): the taxonomy a discovery task replies with and its bounds, the pull request history digest the task reads, the task's prompt and reply schema, and the path score a seeded feature is offered by. |
|
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.
|
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. |