Documentation
¶
Overview ¶
Package webscan is AI Review of what the Drafter's web tools bring back, before its model reads any of it. A text is scanned as model input, with the core's model-input question set, in one of two places:
- Registry: a hosted draft pushes the text to the registry's POST /api/v1/model-input/scan with the job's own credential, and searches through POST /api/v1/model-input/search, which scans every result before it answers. No sandbox host holds the platform's Jev or search key.
- Jev: a local draft scans with the person's own Jev key, through this image's copy of the core's pkg/judge (runnerimage/judge, kept byte for byte by scripts/sync-image-judge.sh), so a local scan asks exactly what the registry asks.
A text that is flagged, or that could not be scanned, is withheld: a caller gives the model its address and the reason, never the text. A scan never fails with an error; a failure is a verdict.
The package is part of the embedded runner-image build context and stays stdlib-only (runnerimage.TestEmbeddedSourcesStdlibOnly). The CLI uses it on the host too, for a hosted draft's scan of the description.
Index ¶
Constants ¶
const ( SourceDescription = judge.SourceDescription SourceSearchResult = judge.SourceSearchResult SourcePage = judge.SourcePage SourceRegistry = judge.SourceRegistry // SourceInputFile is a review's input file (toolsrv's review grant). SourceInputFile = judge.SourceInputFile )
The sources the scans read.
const ( Pass = judge.VerdictPass Withheld = judge.VerdictWithheld NotScanned = judge.VerdictNotScanned )
The verdicts.
const ( FailureTooLarge = "too-large" FailureRefused = "refused" )
Failure words of this package's own, beside the judge's.
const JobTokenHeader = "X-Agentry-Job-Token"
JobTokenHeader carries a hosted job's credential.
const MaxText = 64 << 10
MaxText is the most one scan request carries: the registry route's cap, eight of the judge's 8 KiB chunks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Hit ¶
type Hit struct {
URL string `json:"url"`
Title string `json:"title,omitempty"`
Snippet string `json:"snippet,omitempty"`
Result
}
Hit is one web search result as a model may be shown it. A result that did not pass carries its origin alone in URL, and no title or snippet.
type Jev ¶
type Jev struct {
// contains filtered or unexported fields
}
Jev scans with the person's own key through the core's judge.
func (*Jev) WithMaxText ¶
WithMaxText is the same scanner taking up to n bytes a text: a review's input files (toolsrv's review grant) are scanned whole up to stage S1's text cap, where the Drafter's texts keep the registry route's MaxText.
type ProviderSearch ¶
ProviderSearch searches with the person's own search key and scans every result the way the registry's search route does: as a search result, its title, address and snippet together, a result that did not pass keeping its origin alone.
type Registry ¶
type Registry struct {
// Base is the registry's root, e.g. https://secureagentry.net; the
// routes are under /api/v1.
Base string
// JobToken is the job's credential, presented in JobTokenHeader and
// nowhere else.
JobToken string
// HTTP carries the requests; nil is a client with a 60-second timeout.
// Redirects are never followed: the credential rides on every request.
HTTP *http.Client
}
Registry calls the registry's model-input routes with a hosted job's credential. The registry scans with the deployment's judge and searches with its own provider key; neither key leaves it.
type RegistrySearch ¶
type RegistrySearch struct{ *Registry }
RegistrySearch is the registry's brokered search, as a Searcher.
type Result ¶
type Result struct {
Verdict Verdict `json:"verdict"`
// Score is the highest over every chunk and question, 0 to 3.
Score int `json:"score"`
// Flagged lists the questions that scored 2 or more, sorted.
Flagged []string `json:"flagged,omitempty"`
// Failure is why a text was not scanned, a closed word
// (judge.FailureTimeout, judge.FailureJudgeError, or "too-large",
// "unavailable", "refused"); never a vendor's text.
Failure string `json:"failure,omitempty"`
// Status is the registry route's HTTP status when it answered the call
// with an error (a 429 and a 403 are both "refused"), so a caller can
// tell a rate limit it may ask again after from a refusal it may not;
// 0 otherwise. Never shown to a model.
Status int `json:"-"`
// Model and QuestionSet name what answered and what was asked.
Model string `json:"model,omitempty"`
QuestionSet string `json:"questionSet,omitempty"`
// Requests and InputTokens are what the scan cost the judge, for the
// record. Never a price: AI Review is 1 credit an operation.
Requests int `json:"requests,omitempty"`
InputTokens int64 `json:"inputTokens,omitempty"`
// Unreviewed marks a text that reached the model unread by AI Review,
// because the person switched the review off for the agent (Unreviewed,
// the scanner): its Verdict is Pass and nothing was asked.
Unreviewed bool `json:"unreviewed,omitempty"`
}
Result is one text's scan.
func (Result) Reason ¶
Reason is what the model, and the draft's notes, are told of a text that did not pass: which of AI Review's questions it failed, or that it could not be scanned. It is built from closed words only.
func (Result) Transient ¶
Transient reports whether a text not scanned may pass when asked again: the judge erred or timed out, the route was unavailable, or it held the job to its rate (a 429, which reads as refused). A text too large, or a call the route refused for anything else (the credential, a run's cap of calls), would only be refused again; a verdict is an answer.
type Searcher ¶
type Searcher interface {
// Name is the provider's name, for the record.
Name() string
Search(ctx context.Context, query string, count int) ([]Hit, error)
}
Searcher searches the web and scans every result before it answers.
type Unreviewed ¶ added in v0.7.53
type Unreviewed struct{}
Unreviewed is the scanner of an agent whose person switched AI Review off: it reads nothing and passes every text, marked Unreviewed, so the ledger and the receipt say that no text was read. It is only ever built from a spec whose scan the compiled plan holds to it.