webscan

package
v0.7.1-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 13 Imported by: 0

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

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

View Source
const (
	Pass       = judge.VerdictPass
	Withheld   = judge.VerdictWithheld
	NotScanned = judge.VerdictNotScanned
)

The verdicts.

View Source
const (
	FailureTooLarge    = "too-large"
	FailureUnavailable = "unavailable"
	FailureRefused     = "refused"
)

Failure words of this package's own, beside the judge's.

View Source
const JobTokenHeader = "X-Agentry-Job-Token"

JobTokenHeader carries a hosted job's credential.

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

func NewJev(key, baseURL string, hc *http.Client) (*Jev, error)

NewJev builds a scanner over the person's Jev key; baseURL empty is TypeSafe's API.

func (*Jev) Limit

func (j *Jev) Limit() int

Limit is the most text one scan takes.

func (*Jev) Scan

func (j *Jev) Scan(ctx context.Context, source Source, text string) Result

Scan implements Scanner.

func (*Jev) WithMaxText

func (j *Jev) WithMaxText(n int) *Jev

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

type ProviderSearch struct {
	Provider websearch.Provider
	Scanner  Scanner
}

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.

func (ProviderSearch) Name

func (p ProviderSearch) Name() string

Name implements Searcher.

func (ProviderSearch) Search

func (p ProviderSearch) Search(ctx context.Context, query string, count int) ([]Hit, error)

Search implements Searcher.

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.

func (*Registry) Scan

func (r *Registry) Scan(ctx context.Context, source Source, text string) Result

Scan pushes text to POST /api/v1/model-input/scan. Anything but a 200 with a known verdict is not scanned.

type RegistrySearch

type RegistrySearch struct{ *Registry }

RegistrySearch is the registry's brokered search, as a Searcher.

func (RegistrySearch) Name

func (RegistrySearch) Name() string

Name implements Searcher.

func (RegistrySearch) Search

func (s RegistrySearch) Search(ctx context.Context, query string, count int) ([]Hit, error)

Search asks POST /api/v1/model-input/search. The registry scanned every result; a result it did not pass comes back as its origin, and one whose verdict this client does not know is held to the same rule.

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"`
}

Result is one text's scan.

func (Result) Passed

func (r Result) Passed() bool

Passed reports whether the text may reach a model.

func (Result) Reason

func (r Result) Reason() string

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

func (r Result) Transient() bool

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 Scanner

type Scanner interface {
	Scan(ctx context.Context, source Source, text string) Result
}

Scanner scans a text as model input. Scan never returns an error.

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 Source

type Source = judge.Source

Source is what kind of text a scan reads, the core's closed list.

type Verdict

type Verdict = judge.Verdict

Verdict is a scan's answer.

Jump to

Keyboard shortcuts

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