voice

package
v0.7.11-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 21 Imported by: 0

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

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

View Source
const File = "VOICE.md"

File is the voice's one file, the name AI Review's report places findings in.

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

View Source
const ReportSchema = "agentry.voice-review/v1"

ReportSchema names a review report's shape.

View Source
const ScannerAIReview = "S5/voice"

ScannerAIReview names a finding of the voice question set.

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

View Source
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")
)
View Source
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

func Check(text []byte) error

Check holds text to the format the CLI holds it to: UTF-8 Markdown with something in it, no NUL, at most MaxBytes.

func Digest

func Digest(text []byte) string

Digest is text's digest, "sha256:<hex>", as the CLI computes it.

func Erase

func Erase(ctx context.Context, q *storegen.Queries, user uuid.UUID) (int64, error)

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

type ReviewArgs struct {
	Version uuid.UUID `json:"version"`
}

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

func (r *Reviewer) QuestionSet() string

QuestionSet is the hash of the set a review asks now.

func (*Reviewer) Review

func (r *Reviewer) Review(ctx context.Context, text string) Report

Review reads text and answers its report. It never fails: a stage that failed, or a judge that did not answer, is a report whose verdict is incomplete.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is the registry's store of Writing Voices.

func NewService

func NewService(d Deps) *Service

NewService builds the store.

func (*Service) Configured

func (s *Service) Configured() bool

Configured says whether the store is on: a database, a key wrapper, and a judge to review with.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, user uuid.UUID) error

Delete removes a person's voice, every version of it and its data key.

func (*Service) DiscardPending

func (s *Service) DiscardPending(ctx context.Context, user uuid.UUID) (State, error)

DiscardPending drops a person's pending version, flagged or in review; ErrNotFound when there is none.

func (*Service) Get

func (s *Service) Get(ctx context.Context, user uuid.UUID) (State, error)

Get is a person's voice with every version's text, or ErrNotFound.

func (*Service) Live

func (s *Service) Live(ctx context.Context, user uuid.UUID) (*Version, error)

Live is a person's live version, the one a run attaches, or ErrNotFound.

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

func (s *Service) QuestionSet() string

QuestionSet is the hash of the voice question set a review asks now.

func (*Service) RegisterHandlers

func (s *Service) RegisterHandlers(q queue.Client)

RegisterHandlers wires the review and the sweep onto a queue worker.

func (*Service) Restore

func (s *Service) Restore(ctx context.Context, user uuid.UUID, review bool) (State, error)

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, bool, 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. It reports whether the restore was put up for review: a caller that admitted it for review and finds it was not (the question set moved back between its look and the restore) voids the admission.

func (*Service) RestoreNeedsReview

func (s *Service) RestoreNeedsReview(ctx context.Context, user uuid.UUID) (bool, error)

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

func (s *Service) SetAlwaysAttach(ctx context.Context, user uuid.UUID, on bool) (State, error)

SetAlwaysAttach sets the account's always-attach flag.

func (*Service) SetJudge

func (s *Service) SetJudge(j Judge)

SetJudge replaces the judge a review asks: at start, or a test's stub.

func (*Service) Sweep

func (s *Service) Sweep(ctx context.Context, cutoff time.Time) (int, error)

Sweep queues a review again for every version still in review whose last try is older than cutoff, and reports how many. It is how a review whose job ran out of tries, while the judge could not answer, is tried again.

type Slot

type Slot string

Slot is where a version sits.

const (
	SlotLive     Slot = "live"
	SlotPending  Slot = "pending"
	SlotPrevious Slot = "previous"
)

The three slots.

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).

func (Source) Valid

func (s Source) Valid() bool

Valid says whether s is a source a version may have.

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 Verdict

type Verdict string

Verdict is a review's answer.

const (
	VerdictPass       Verdict = "pass"
	VerdictFlagged    Verdict = "flagged"
	VerdictIncomplete Verdict = "incomplete"
)

A review passes a version, flags it, or did not finish: a stage failed or the judge could not answer, and the version stays in review.

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.

Jump to

Keyboard shortcuts

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