build

package
v0.7.22-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package build makes or extends a knowledge pack with the Knowledge Creator: it stages the documents, decodes them before any agent sees them (pkg/runner/decode), runs the built-in Creator over their text with the pack as it stands attached (pkg/runner/localrun, pkg/runner/engine), and applies the pages it wrote — with the documents themselves and their decoded text, which only this step, never the model, puts in the pack's sources/ — through pkg/knowledge's apply step. The CLI's `agentry knowledge create|add` drives it today; the desktop and the cloud build are its other callers.

Locally the Creator runs against the model the runner policy names, for no credits, and neither the documents nor the pack are scanned: the pack records "not scanned". What the web tools bring back is read by AI Review before the model reads it.

A build takes documents, a brief, or both: the brief is staged as one more text document (brief.md), so its claims are cited and kept like any document's. And a build may search the web, with the built-ins' web tools and every result read by AI Review first: Options.Web is that run's configuration, and a build without it runs the Creator without the tools.

Index

Constants

View Source
const MaxBriefBytes = 8 << 10

MaxBriefBytes is the most a brief may hold: 8 KiB.

View Source
const MaxRepos = 10

MaxRepos bounds the repositories one build takes.

View Source
const MaxURLs = 20

MaxURLs bounds the addresses one build takes.

View Source
const PageReserve = 300

PageReserve is the room in a pack's 2,000 files a build keeps for the pages it writes, its index and its log, when it fetches a source: a source is fetched within what is left after it and the documents.

Variables

View Source
var ErrNothingToBuild = errors.New("a knowledge build needs documents, a brief, or both")

ErrNothingToBuild is CheckBrief's answer for a build given neither documents nor a brief.

Functions

func CheckBrief

func CheckBrief(documents []string, brief string) error

CheckBrief refuses a brief past MaxBriefBytes, and a build given neither documents nor a brief; the clients ask it before anything runs.

func ParseSources

func ParseSources(repos, urls []string) ([]*sources.Source, error)

ParseSources turns the repositories (an https address, with @ref or #ref for a branch, a tag or a commit other than the default branch) and the file addresses a build was given into sources, each with the id its documents are staged under: repo-<host>-<path> for a repository, which is also the folder the pack keeps it in, and url-<n> for a file, whose document is the file's own name once it is fetched. Tokens are not resolved here (sources.ResolveTokens).

Types

type FetchedSource

type FetchedSource struct {
	// Kind is repository or url.
	Kind manifest.IntakeType `json:"kind"`
	// URL is the address as shown (a query hidden); Ref the ref asked for,
	// Commit the commit a repository resolved to.
	URL    string `json:"url"`
	Ref    string `json:"ref,omitempty"`
	Commit string `json:"commit,omitempty"`
	// Document is what the pack cites it under: a repository's folder, or
	// a file's name.
	Document string `json:"document"`
	Files    int    `json:"files"`
	Bytes    int64  `json:"bytes"`
	// LeftOut counts what a repository's fetch left out, by reason.
	LeftOut map[string]int `json:"leftOut,omitempty"`
	// Token says where the token came from (flag, keychain, prompt),
	// empty for an anonymous fetch.
	Token string        `json:"token,omitempty"`
	Took  time.Duration `json:"-"`
	// contains filtered or unexported fields
}

FetchedSource is one source a build fetched, as the build reports it. It never holds the token.

func (FetchedSource) At

func (f FetchedSource) At() string

At is the ref a repository was fetched at, in words.

func (FetchedSource) Words

func (f FetchedSource) Words() string

Words say what a build brought in: a repository with its ref and commit, or a file, each with the document the pack cites it under.

type Options

type Options struct {
	// PackDir is the pack to extend, or where to make a new one.
	PackDir string
	// Name names a new pack; ignored when PackDir holds one.
	Name string
	// Documents are the files and directories to ingest.
	Documents []string
	// Brief is what the pack should cover and for whom, in the person's
	// words, at most MaxBriefBytes: kept as sources/brief.md (or
	// brief-N.md when the pack holds one already) and read as a document.
	// A build takes documents, a brief, or both.
	Brief string
	// Sources are the repositories and the files at web addresses to
	// ingest beside the documents (ParseSources), each with its token
	// resolved (sources.ResolveBuildTokens). They are fetched before the
	// decode and kept in the pack as documents are.
	Sources []*sources.Source
	// Web, when set, grants the Creator web_search and web_read for this
	// build, every result read by AI Review first (engine.WebRun); nil
	// runs it without them.
	Web *engine.WebRun

	Home       string
	Policy     *policy.Policy
	PolicySHA  string
	PolicyFile *policy.File
	// Build is the client's build identity: the receipt's and the pack's
	// record of what made it.
	Build string
	// Now dates the pages and the log entry.
	Now time.Time
	// OutDir receives the run's reports and receipts.
	OutDir string
	// Budgets, when set, replace the Creator plan's.
	Budgets *spec.Budgets
	// MaxBytes caps the pack, documents included: knowledge.MaxBytes when
	// zero, Agentry's cap, which a build In Agentry keeps; a build on this
	// computer passes knowledge.MaxLocalBytes.
	MaxBytes int64
	RunID    string
	Stderr   io.Writer
	OnUsage  func(receipt.Usage)
	// Hosted is a sandbox host's build, which never spends a model sign-in
	// (localrun.Run.Hosted).
	Hosted bool
	// Credits is the credits-session client for a policy that pays with
	// Agentry credits (model provider agentry); see localrun.Run.Credits.
	Credits *inference.Client
	// Render lets a hosted build render a page drawn by scripts: its host
	// dispatched it as a browser job. A build on this computer renders
	// without it.
	Render bool
}

Options configure one build.

type Result

type Result struct {
	// Envelope is the Creator run's receipt; nil when the run never began.
	Envelope *receipt.Envelope
	// Decoded is the decode step over the documents.
	Decoded *decode.Result
	// Applied is the apply step's account; nil when nothing was applied.
	Applied *knowledge.Result
	// Documents are the documents the Creator was given, by the name the
	// pack cites them under; Skipped are those no decoder could read.
	Documents, Skipped []string
	// Sources are the repositories and files the build fetched, each with
	// what it resolved to; nil when the build was given none.
	Sources []FetchedSource
	// RunErr is the Creator run's own failure when the build applied what
	// it wrote before it stopped (a budget, a timeout); the pack is valid,
	// and a further build with the same documents continues it.
	RunErr error
}

Result is what one build did.

func Build

func Build(ctx context.Context, d dockerx.Client, o Options) (*Result, error)

Build makes or extends the pack.

Jump to

Keyboard shortcuts

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