Documentation
¶
Overview ¶
Package voice is the registry's store of Writing Voices: the one VOICE.md a person keeps in Agentry, the instructions a run follows for how it writes and nothing else. A person has at most three versions of it: the live one, a pending one (in review, or flagged with its findings) and the previous one, for Restore. Each is sealed at rest under a data key of the voice's own, wrapped for the person by the knowledge store's key wrapper, and a version goes live only when AI Review passed it: the pack scan's rule stages over the text and the judge's voice question set. A judge that cannot answer leaves the version in review, retried; nothing goes live unreviewed.
A voice is not a knowledge pack: no name, no tree, no listing, one a person, and it is the one attached text that is instruction-shaped. The open core carries the whole object and its review; an extension adds the hosted Voice Writer, its price and the charge for a review (pkg/extension AdmitsVoice, Voice).
Index ¶
- Constants
- Variables
- func Check(text []byte) error
- func Digest(text []byte) string
- func Erase(ctx context.Context, q *storegen.Queries, user uuid.UUID) (int64, error)
- type AIReview
- type Deps
- type Finding
- type InvalidError
- type Judge
- type ProseScanner
- type Report
- type ReviewArgs
- type ReviewState
- type Reviewer
- type Service
- func (s *Service) Configured() bool
- func (s *Service) Delete(ctx context.Context, user uuid.UUID) error
- func (s *Service) DiscardPending(ctx context.Context, user uuid.UUID) (State, error)
- func (s *Service) Get(ctx context.Context, user uuid.UUID) (State, error)
- func (s *Service) Live(ctx context.Context, user uuid.UUID) (*Version, error)
- func (s *Service) Put(ctx context.Context, user uuid.UUID, text []byte, source Source) (State, error)
- func (s *Service) PutAdmitted(ctx context.Context, user uuid.UUID, text []byte, source Source, ticket string) (State, error)
- func (s *Service) QuestionSet() string
- func (s *Service) RegisterHandlers(q queue.Client)
- func (s *Service) Restore(ctx context.Context, user uuid.UUID, review bool) (State, error)
- func (s *Service) RestoreAdmitted(ctx context.Context, user uuid.UUID, review bool, ticket string) (State, error)
- func (s *Service) RestoreNeedsReview(ctx context.Context, user uuid.UUID) (bool, error)
- func (s *Service) SetAlwaysAttach(ctx context.Context, user uuid.UUID, on bool) (State, error)
- func (s *Service) SetJudge(j Judge)
- func (s *Service) Sweep(ctx context.Context, cutoff time.Time) (int, error)
- type Slot
- type Source
- type State
- type Verdict
- type Version
Constants ¶
const ( JobReview = "voice.review" JobSweep = "voice.review.sweep" )
The job kinds: the review runs on the sandbox queue, as a pack's scan does, because it reads what a person wrote; the sweep that queues a stalled review again reads nothing and runs on the core queue.
const File = "VOICE.md"
File is the voice's one file, the name AI Review's report places findings in.
const MaxBytes = judge.VoiceMaxBytes
MaxBytes caps a VOICE.md: the most AI Review reads in its one request, so a voice is never cut. The CLI holds the same cap (agentry-cli pkg/voice).
const ReportSchema = "agentry.voice-review/v1"
ReportSchema names a review report's shape.
const ScannerAIReview = "S5/voice"
ScannerAIReview names a finding of the voice question set.
const StallAfter = time.Hour
StallAfter is how long a version waits in review since its last try before the sweep queues its review again.
Variables ¶
var ( // ErrNotFound is a person with no voice, or no version in the slot // asked for. ErrNotFound = errors.New("voice: no such voice") // ErrUnconfigured is a deployment that keeps no voices: no key // wrapper (the knowledge store is off) or no judge to review them. ErrUnconfigured = errors.New("voice: the voice store is off") // ErrTooLarge is a voice past MaxBytes. ErrTooLarge = fmt.Errorf("voice: a Writing Voice is at most %d KiB", MaxBytes>>10) // ErrNoPrevious is a Restore with no previous version. ErrNoPrevious = errors.New("voice: there is no previous version to restore") )
var ErrRestoreNeedsReview = errors.New("voice: the previous version needs a review under the current question set")
ErrRestoreNeedsReview is a Restore its caller did not admit for review although the previous version needs one: the question set moved between the caller's look and the restore.
Functions ¶
func Check ¶
Check holds text to the format the CLI holds it to: UTF-8 Markdown with something in it, no NUL, at most MaxBytes.
func Erase ¶
Erase deletes a person's voice on q, the caller's transaction: the account erasure and a data clear. It runs whether or not the store is on, so turning it off strands nothing an erasure should remove. The key that opened it goes with the knowledge store's erasure of the same person (its salt, or an extension wrapper's Destroy).
Types ¶
type AIReview ¶
type AIReview struct {
Model string `json:"model,omitempty"`
QuestionSet string `json:"questionSet,omitempty"`
Scores map[string]int `json:"scores,omitempty"`
Failure string `json:"failure,omitempty"`
Requests int `json:"requests"`
InputTokens int `json:"inputTokens"`
}
AIReview is the voice question set's record: the model, the set's hash, each question's score, and why it did not answer when it did not.
type Deps ¶
type Deps struct {
Store *store.Store
// Wrapper is the knowledge store's key wrapper as it stands when asked,
// so an extension's, set after the server is built, is the one used.
Wrapper func() knowledge.KeyWrapper
// Rules runs the pack scan's rule stages; Judge asks the voice question
// set, nil when the deployment's judge is not Jev, which leaves the
// store off.
Rules ProseScanner
Judge Judge
Jobs queue.Client
Log *slog.Logger
}
Deps is what the service is built from.
type Finding ¶
type Finding struct {
Scanner string `json:"scanner"`
Severity string `json:"severity"`
Title string `json:"title"`
Line int `json:"line,omitempty"`
Question string `json:"question,omitempty"`
Score int `json:"score,omitempty"`
Flags bool `json:"flags"`
}
Finding is one thing the review found. Flags says whether it is what keeps the version from going live: a rule finding of medium severity or above, or a question of the voice set scored at the withhold line.
type InvalidError ¶
type InvalidError struct{ Reason string }
InvalidError is text that is not a voice, and why.
func (*InvalidError) Error ¶
func (e *InvalidError) Error() string
type Judge ¶
type Judge interface {
Scan(ctx context.Context, voice string) judge.VoiceResult
QuestionSet() string
}
Judge asks the voice question set: *judge.VoiceScanner.
type ProseScanner ¶
type ProseScanner interface {
ScanProse(ctx context.Context, files []scan.PackFile) scan.PackReport
}
ProseScanner runs the pack scan's rule stages over text files: the scan orchestrator's ScanProse.
type Report ¶
type Report struct {
Schema string `json:"schema"`
Verdict Verdict `json:"verdict"`
Stages []scan.PackStage `json:"stages"`
Findings []Finding `json:"findings"`
AIReview AIReview `json:"aiReview"`
}
Report is what a version's review read and found. It keeps no excerpt: it is in the clear beside a sealed text, so it says where a finding is (a line, or a question of AI Review), never the words there.
type ReviewArgs ¶
ReviewArgs names the version a review job reads.
type ReviewState ¶
type ReviewState string
ReviewState is where a version is in its review: a pending version is reviewing or flagged; a live or previous one passed.
const ( ReviewReviewing ReviewState = "reviewing" ReviewFlagged ReviewState = "flagged" ReviewPassed ReviewState = "passed" )
The review states.
type Reviewer ¶
type Reviewer struct {
// contains filtered or unexported fields
}
Reviewer reviews a version: the rule stages, then the voice set.
func NewReviewer ¶
func NewReviewer(rules ProseScanner, j Judge) *Reviewer
NewReviewer builds a reviewer; with no judge there is none, and the store is off, since no version could ever pass.
func (*Reviewer) QuestionSet ¶
QuestionSet is the hash of the set a review asks now.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the registry's store of Writing Voices.
func (*Service) Configured ¶
Configured says whether the store is on: a database, a key wrapper, and a judge to review with.
func (*Service) DiscardPending ¶
DiscardPending drops a person's pending version, flagged or in review; ErrNotFound when there is none.
func (*Service) Put ¶
func (s *Service) Put(ctx context.Context, user uuid.UUID, text []byte, source Source) (State, error)
Put makes text a person's pending version and queues its review: the pending version it replaces, if any, goes, and the live one stays live until this one passes. The person's voice row, and its data key wrapped for them, is made with their first version.
func (*Service) PutAdmitted ¶
func (s *Service) PutAdmitted(ctx context.Context, user uuid.UUID, text []byte, source Source, ticket string) (State, error)
PutAdmitted is Put for a review an extension admitted: ticket, when not empty, is recorded as stored (admitted_stores, kind "voice") in the transaction that stores the version, so a ticket with no row stored nothing.
func (*Service) QuestionSet ¶
QuestionSet is the hash of the voice question set a review asks now.
func (*Service) RegisterHandlers ¶
RegisterHandlers wires the review and the sweep onto a queue worker.
func (*Service) Restore ¶
Restore puts a person's previous version back. Reviewed under the set in use now, it and the live one trade places at once; reviewed under another, it becomes the pending version, source restore, and is reviewed like any other, which the caller must have admitted (review).
func (*Service) RestoreAdmitted ¶
func (s *Service) RestoreAdmitted(ctx context.Context, user uuid.UUID, review bool, ticket string) (State, error)
RestoreAdmitted is Restore for a review an extension admitted: ticket, when not empty, is recorded as stored (admitted_stores, kind "voice") in the transaction that puts the previous version up for review. A restore that swaps live and previous at once reviews nothing and records nothing.
func (*Service) RestoreNeedsReview ¶
RestoreNeedsReview says whether a Restore of a person's previous version is a new version to review — it was reviewed under a question set other than the one in use — or a swap of live and previous. ErrNoPrevious when there is none.
func (*Service) SetAlwaysAttach ¶
SetAlwaysAttach sets the account's always-attach flag.
type Source ¶
type Source string
Source is how a version came to be.
const ( SourceBuild Source = "build" SourceAIEdit Source = "ai-edit" SourceEdit Source = "edit" SourceUpload Source = "upload" SourceRestore Source = "restore" )
The sources a version can have: the Voice Writer run In Agentry (build: Create or Improve; ai-edit), the person's own text saved on the web (edit) or sent from a client (upload), and the previous version put back under a question set it was not reviewed by (restore).
type State ¶
type State struct {
AlwaysAttach bool
WentLive bool
Live *Version
Pending *Version
Previous *Version
UpdatedAt time.Time
}
State is a person's voice: the account's flags and its versions.
type Version ¶
type Version struct {
ID uuid.UUID
Slot Slot
ReviewState ReviewState
Source Source
Digest string
Bytes int
Text []byte
// Report is the review's, nil while the first try is to come.
Report *Report
QuestionSet string
CreatedAt time.Time
ReviewedAt *time.Time
}
Version is one version of a person's voice, its text opened.