llm

package
v0.10.255 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package llm defines provider-neutral LLM adapter contracts and structured output validation for review planning.

Index

Constants

View Source 
const (
	// SchemaVersion is the structured-output schema version supported by this package.
	SchemaVersion = 1

	// DefaultMaxFindingsPerAgent is the default per-agent findings cap.
	DefaultMaxFindingsPerAgent = 50

	// DefaultMaxFindingBodyLen is the default max finding body length in runes.
	DefaultMaxFindingBodyLen = 8000

	// DefaultMaxResolvedThreads is the default selected thread resolution cap.
	DefaultMaxResolvedThreads = 25
)

Variables

View Source 
var ErrReviewerWorkspaceUnsupported = errors.New("llm adapter: missing reviewer workspace capability")

ErrReviewerWorkspaceUnsupported reports that an adapter cannot use a prepared reviewer workspace.

View Source 
var ErrStructuredOutputInvalidAfterRetry = errors.New("structured output invalid after retry")

ErrStructuredOutputInvalidAfterRetry marks a structured-output request whose initial response and single validation retry both failed decoding.

View Source 
var ErrTransient = errors.New("llm: transient provider error")

ErrTransient marks a provider failure that is likely temporary (an overloaded model, a 5xx, a rate limit, or a transport timeout) and therefore safe to retry. Concrete adapters wrap their transport/model errors with this sentinel so callers can classify retryable outcomes without knowing wire details, mirroring the gitprovider ErrRetryable taxonomy.

Functions

func DecodeRollup 

func DecodeRollup(data []byte, opts RollupOptions) (review.Rollup, error)

DecodeRollup validates and maps Rollup structured output.

func RequireReviewerWorkspace added in v0.10.196 

func RequireReviewerWorkspace(adapter Adapter) error

RequireReviewerWorkspace returns a stable error when adapter cannot inspect a prepared reviewer workspace.

func SupportsReviewerWorkspace added in v0.10.196 

func SupportsReviewerWorkspace(adapter Adapter) bool

SupportsReviewerWorkspace reports whether adapter can use a prepared reviewer workspace.

Types

type Adapter 

type Adapter interface {
	Name() string
	SupportsResume() bool
	SupportsCacheAccounting() bool
	SupportsCostReporting() bool
	Quota(context.Context) (Quota, bool, error)
	Start(context.Context, Request) (Stream, error)
	Resume(context.Context, string, Request) (Stream, error)
}

Adapter is the provider-neutral LLM boundary.

type BaseStream added in v0.10.255 

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

BaseStream provides shared cancellation, result, logging, and cleanup state.

func NewBaseStream added in v0.10.255 

func NewBaseStream(cancel context.CancelFunc) BaseStream

NewBaseStream creates stream state for a non-subprocess adapter.

func NewProcessStream added in v0.10.255 

func NewProcessStream(process *LaunchedProcess, cleanup func() error) BaseStream

NewProcessStream creates stream state owned by a launched subprocess.

func (*BaseStream) Cancel added in v0.10.255 

func (s *BaseStream) Cancel()

Cancel cancels the adapter operation.

func (*BaseStream) Cleanup added in v0.10.255 

func (s *BaseStream) Cleanup()

Cleanup runs the stream cleanup once.

func (*BaseStream) CloseLog added in v0.10.255 

func (s *BaseStream) CloseLog()

CloseLog closes the optional adapter log.

func (*BaseStream) CloseProcessGroup added in v0.10.255 

func (s *BaseStream) CloseProcessGroup()

CloseProcessGroup releases platform-specific process-group resources.

func (*BaseStream) Finish added in v0.10.255 

func (s *BaseStream) Finish(response Response, err error)

Finish publishes a stream result and wakes waiters.

func (*BaseStream) HasLog added in v0.10.255 

func (s *BaseStream) HasLog() bool

HasLog reports whether the stream has an adapter log.

func (*BaseStream) SessionID added in v0.10.255 

func (s *BaseStream) SessionID() string

SessionID returns the first provider session ID reported by the stream.

func (*BaseStream) SetSessionID added in v0.10.255 

func (s *BaseStream) SetSessionID(id string)

SetSessionID records the first non-empty provider session ID.

func (*BaseStream) Wait added in v0.10.255 

func (s *BaseStream) Wait(ctx context.Context) (Response, error)

Wait waits for the adapter result or context cancellation.

func (*BaseStream) WithLogFile added in v0.10.255 

func (s *BaseStream) WithLogFile(write func(*os.File) (int, error)) (int, error)

WithLogFile serializes a write operation against the optional adapter log.

func (*BaseStream) Write added in v0.10.255 

func (s *BaseStream) Write(p []byte) (int, error)

func (*BaseStream) WriteLog added in v0.10.255 

func (s *BaseStream) WriteLog(p []byte)

WriteLog appends bytes to the optional adapter log.

type Decoder 

type Decoder[T any] func([]byte) (T, error)

Decoder validates and maps structured output bytes.

type FakeAdapter 

type FakeAdapter struct {
	NameValue                    string
	SupportsResumeValue          bool
	ReviewerWorkspaceModeSet     bool
	ReviewerWorkspaceModeValue   ReviewerWorkspaceMode
	SupportsCacheAccountingValue bool
	SupportsCostReportingValue   bool

	QuotaValue     Quota
	QuotaSupported bool
	QuotaErr       error
	// contains filtered or unexported fields
}

FakeAdapter is a deterministic Adapter test double. Configure exported fields before concurrent use; adapter methods lock around captured requests/results.

func (*FakeAdapter) Name 

func (f *FakeAdapter) Name() string

Name returns the configured adapter name.

func (*FakeAdapter) Queue 

func (f *FakeAdapter) Queue(result FakeResult)

Queue appends one result for a future Start call.

func (*FakeAdapter) Quota 

func (f *FakeAdapter) Quota(context.Context) (Quota, bool, error)

Quota returns the configured quota tuple.

func (*FakeAdapter) Requests 

func (f *FakeAdapter) Requests() []Request

Requests returns captured Start requests.

func (*FakeAdapter) Resume 

func (f *FakeAdapter) Resume(ctx context.Context, sessionID string, req Request) (Stream, error)

Resume is unsupported by the fake unless the caller explicitly opts in.

func (*FakeAdapter) Resumes 

func (f *FakeAdapter) Resumes() []ResumeRequest

Resumes returns captured Resume requests.

func (*FakeAdapter) ReviewerWorkspaceMode added in v0.10.196 

func (f *FakeAdapter) ReviewerWorkspaceMode() ReviewerWorkspaceMode

ReviewerWorkspaceMode reports the fake's reviewer workspace mode.

func (*FakeAdapter) Start 

func (f *FakeAdapter) Start(ctx context.Context, req Request) (Stream, error)

Start captures req and returns the next queued fake stream.

func (*FakeAdapter) SupportsCacheAccounting 

func (f *FakeAdapter) SupportsCacheAccounting() bool

SupportsCacheAccounting reports whether cache usage metrics are supported.

func (*FakeAdapter) SupportsCostReporting 

func (f *FakeAdapter) SupportsCostReporting() bool

SupportsCostReporting reports whether cost metrics are supported.

func (*FakeAdapter) SupportsResume 

func (f *FakeAdapter) SupportsResume() bool

SupportsResume reports whether the fake supports session resume.

type FakeResult 

type FakeResult struct {
	SessionID string
	Response  Response
	StartErr  error
	WaitErr   error
}

FakeResult is one queued fake Start result.

type FindingIDGenerator 

type FindingIDGenerator func() (review.FindingID, error)

FindingIDGenerator assigns harness-owned finding IDs.

type Findings 

type Findings struct {
	AgentID        string
	Findings       []review.Finding
	InspectedFiles []string
	SkippedFiles   []string
	Constraints    []string
}

Findings is validated reviewer findings output.

func DecodeFindings 

func DecodeFindings(data []byte, opts FindingsOptions) (Findings, error)

DecodeFindings validates and maps Findings structured output.

type FindingsOptions 

type FindingsOptions struct {
	KnownAgents  map[string]bool
	ChangedFiles map[string]bool
	NewFindingID FindingIDGenerator
	// MaxFindingsPerAgent uses DefaultMaxFindingsPerAgent when zero.
	MaxFindingsPerAgent int
	// MaxBodyLength uses DefaultMaxFindingBodyLen when zero.
	MaxBodyLength int
	SeverityCaps  map[review.Severity]int
}

FindingsOptions contains context needed to validate finding output.

type LaunchedProcess added in v0.10.255 

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

LaunchedProcess is shared process-launch state for subprocess adapters.

func LaunchProcess added in v0.10.255 

func LaunchProcess(ctx context.Context, command string, args []string, dir string, env []string, timeout time.Duration, logPath string, cleanup func() error, withStdin bool) (*LaunchedProcess, error)

LaunchProcess starts an adapter subprocess with shared cancellation, logging, and platform-specific process-group handling.

func (*LaunchedProcess) Abort added in v0.10.255 

func (p *LaunchedProcess) Abort(cleanup func() error)

Abort terminates a launched process and releases all launch resources.

func (*LaunchedProcess) Command added in v0.10.255 

func (p *LaunchedProcess) Command() *exec.Cmd

Command returns the started command.

func (*LaunchedProcess) Context added in v0.10.255 

func (p *LaunchedProcess) Context() context.Context

Context returns the process context.

func (*LaunchedProcess) Stderr added in v0.10.255 

func (p *LaunchedProcess) Stderr() io.ReadCloser

Stderr returns the process stderr pipe.

func (*LaunchedProcess) Stdin added in v0.10.255 

func (p *LaunchedProcess) Stdin() io.WriteCloser

Stdin returns the optional process stdin pipe.

func (*LaunchedProcess) Stdout added in v0.10.255 

func (p *LaunchedProcess) Stdout() io.ReadCloser

Stdout returns the process stdout pipe.

type Quota 

type Quota struct {
	BlockRemainingPct  float64
	WeeklyRemainingPct float64
}

Quota records adapter quota state. A value of -1 means unknown.

type Request 

type Request struct {
	Model   string
	Effort  string
	Prompt  string
	LogPath string
	Fast    bool

	DurableSession              bool
	ReviewerWorkspace           *ReviewerWorkspaceRequest
	FreshValidationRetrySession bool
	OnValidationRetry           func(*Request) error
}

Request describes one LLM invocation.

type Response 

type Response struct {
	StructuredOutput []byte
	Usage            Usage
	DurationMS       int64
}

Response is the completed LLM result.

type ResumeRequest 

type ResumeRequest struct {
	SessionID string
	Request   Request
}

ResumeRequest is one captured Resume invocation.

type ReviewerWorkspaceCapable added in v0.10.196 

type ReviewerWorkspaceCapable interface {
	ReviewerWorkspaceMode() ReviewerWorkspaceMode
}

ReviewerWorkspaceCapable reports the adapter's reviewer workspace support.

type ReviewerWorkspaceMode added in v0.10.196 

type ReviewerWorkspaceMode string

ReviewerWorkspaceMode identifies how an adapter can use a prepared reviewer workspace. 

const (
	// ReviewerWorkspaceNone means the adapter cannot inspect a caller-provided workspace.
	ReviewerWorkspaceNone ReviewerWorkspaceMode = "none"
	// ReviewerWorkspacePermissionBounded means the adapter can inspect a workspace
	// through adapter/tool permissions.
	ReviewerWorkspacePermissionBounded ReviewerWorkspaceMode = "permission_bounded"
	// ReviewerWorkspaceWrite means the adapter can run against a writable
	// disposable workspace.
	ReviewerWorkspaceWrite ReviewerWorkspaceMode = "workspace_write"
)

func AdapterReviewerWorkspaceMode added in v0.10.196 

func AdapterReviewerWorkspaceMode(adapter Adapter) ReviewerWorkspaceMode

AdapterReviewerWorkspaceMode returns the adapter's reviewer workspace mode.

type ReviewerWorkspaceRequest added in v0.10.196 

type ReviewerWorkspaceRequest struct {
	RepoDir            string
	ScratchDir         string
	Env                []string
	AllowedFiles       []string
	MaxToolOutputBytes int
}

ReviewerWorkspaceRequest describes the disposable workspace for one reviewer task. RepoDir is the reviewer-visible working tree root and ScratchDir owns per-invocation writable directories. Env is appended before invocation-owned toolchain paths are applied.

type RollupOptions 

type RollupOptions struct {
	FindingSeverities         map[review.FindingID]review.Severity
	MajorEventRequestsChanges bool
}

RollupOptions contains context needed to validate rollup output.

type ScratchDirFactory 

type ScratchDirFactory func() (string, func() error, error)

ScratchDirFactory creates an empty working directory and returns its cleanup.

type SelectedAgent 

type SelectedAgent struct {
	AgentID      string
	Rationale    string
	Files        []string
	AllowedFiles []string
}

SelectedAgent is one selected reviewer agent.

type Selection 

type Selection struct {
	SelectedAgents []SelectedAgent
	ThreadActions  []review.ThreadAction
	Reasoning      string
}

Selection is validated orchestrator selection output.

func DecodeSelection 

func DecodeSelection(data []byte, opts SelectionOptions) (Selection, error)

DecodeSelection validates and maps Selection structured output.

type SelectionOptions 

type SelectionOptions struct {
	KnownAgents  map[string]bool
	ChangedFiles map[string]bool
	KnownThreads map[string]bool
	// MaxResolvedThreads uses DefaultMaxResolvedThreads when zero.
	MaxResolvedThreads int
}

SelectionOptions contains context needed to validate selection output.

type Stream 

type Stream interface {
	SessionID() string
	Wait(context.Context) (Response, error)
}

Stream is a started LLM request.

type StructuredResult 

type StructuredResult[T any] struct {
	Value              T
	Response           Response
	SessionID          string
	ValidationAttempts []StructuredValidationAttempt
	AcceptedOutput     []byte
}

StructuredResult contains the validated structured value and adapter metadata.

func RunStructuredWithSessionResume 

func RunStructuredWithSessionResume[T any](ctx context.Context, adapter Adapter, resumeSessionID string, req Request, decode Decoder[T]) (StructuredResult[T], error)

RunStructuredWithSessionResume runs a structured request, starting from an existing provider session ID when provided.

type StructuredValidationAttempt added in v0.9.176 

type StructuredValidationAttempt struct {
	Label       string
	SessionID   string
	Response    Response
	DecodeError error
}

StructuredValidationAttempt records one failed schema-validation attempt.

type StructuredValidationError added in v0.9.176 

type StructuredValidationError struct {
	Attempts []StructuredValidationAttempt
}

StructuredValidationError carries both invalid structured-output attempts when the validation correction retry also fails.

func (*StructuredValidationError) Error added in v0.9.176 

func (e *StructuredValidationError) Error() string

func (*StructuredValidationError) Is added in v0.9.176 

func (e *StructuredValidationError) Is(target error) bool

Is matches ErrStructuredOutputInvalidAfterRetry for errors.Is callers.

type Usage 

type Usage struct {
	TokensIn    *int
	TokensOut   *int
	CacheRead   *int
	CacheCreate *int
	CostUSD     *float64
	Speed       string
}

Usage records nullable usage metrics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.