llm

package
v0.10.240 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2026 License: MIT Imports: 25 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 (
	// ErrToolUse reports a subprocess no-IO contract violation.
	ErrToolUse = errors.New("llm subprocess: tool use event")

	// ErrUnsafeSubprocessConfig reports a launch spec missing required safety flags.
	ErrUnsafeSubprocessConfig = errors.New("llm subprocess: unsafe configuration")
)
View Source 
var ErrAPIAdapterConfig = errors.New("llm api: invalid configuration")

ErrAPIAdapterConfig reports invalid direct API adapter configuration.

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 APIAdapter 

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

APIAdapter calls a direct provider HTTP API as an LLM adapter.

func NewAPIAdapterFromConfig 

func NewAPIAdapterFromConfig(llmConfig config.LLMConfig, store credentials.Reader, opts APIOptions) (*APIAdapter, error)

NewAPIAdapterFromConfig resolves an API-key LLM adapter from profile config.

func (*APIAdapter) Name 

func (a *APIAdapter) Name() string

Name returns the adapter name.

func (*APIAdapter) Quota 

func (a *APIAdapter) Quota(context.Context) (Quota, bool, error)

Quota reports unsupported quota for direct API adapters.

func (*APIAdapter) Resume 

func (a *APIAdapter) Resume(context.Context, string, Request) (Stream, error)

Resume is unsupported until API session persistence is designed.

func (*APIAdapter) Start 

func (a *APIAdapter) Start(ctx context.Context, req Request) (Stream, error)

Start begins one provider HTTP request and returns its stream handle.

func (*APIAdapter) SupportsCacheAccounting 

func (a *APIAdapter) SupportsCacheAccounting() bool

SupportsCacheAccounting reports whether provider usage can include cache fields.

func (*APIAdapter) SupportsCostReporting 

func (a *APIAdapter) SupportsCostReporting() bool

SupportsCostReporting reports whether provider responses include cost.

func (*APIAdapter) SupportsResume 

func (a *APIAdapter) SupportsResume() bool

SupportsResume reports whether API session resume is implemented.

type APIOptions 

type APIOptions struct {
	APIKey           string
	HTTPClient       *http.Client
	BaseURL          string
	MaxTokens        int
	AnthropicVersion string
	FastModeModels   []string
}

APIOptions configures direct HTTP LLM adapters.

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 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 PiRPCAdapter added in v0.1.42 

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

PiRPCAdapter runs Pi in RPC mode as an LLM adapter.

func NewPiRPCAdapter added in v0.1.42 

func NewPiRPCAdapter(opts PiRPCOptions) *PiRPCAdapter

NewPiRPCAdapter returns a Pi RPC subprocess adapter.

func (*PiRPCAdapter) Name added in v0.1.42 

func (a *PiRPCAdapter) Name() string

Name returns the adapter name.

func (*PiRPCAdapter) Quota added in v0.1.42 

func (a *PiRPCAdapter) Quota(context.Context) (Quota, bool, error)

Quota reports unsupported quota for Pi RPC.

func (*PiRPCAdapter) Resume added in v0.1.42 

func (a *PiRPCAdapter) Resume(context.Context, string, Request) (Stream, error)

Resume is unsupported until Pi RPC session persistence is designed.

func (*PiRPCAdapter) Start added in v0.1.42 

func (a *PiRPCAdapter) Start(ctx context.Context, req Request) (Stream, error)

Start launches Pi in RPC mode in a fresh scratch directory.

func (*PiRPCAdapter) SupportsCacheAccounting added in v0.1.42 

func (a *PiRPCAdapter) SupportsCacheAccounting() bool

SupportsCacheAccounting reports whether provider usage can include cache fields.

func (*PiRPCAdapter) SupportsCostReporting added in v0.1.42 

func (a *PiRPCAdapter) SupportsCostReporting() bool

SupportsCostReporting reports whether provider responses include cost.

func (*PiRPCAdapter) SupportsResume added in v0.1.42 

func (a *PiRPCAdapter) SupportsResume() bool

SupportsResume reports whether Pi RPC session resume is implemented.

type PiRPCOptions added in v0.1.42 

type PiRPCOptions struct {
	Command           string
	Env               []string
	Timeout           time.Duration
	ScratchDirFactory ScratchDirFactory
	FastModeModels    []string
	// contains filtered or unexported fields
}

PiRPCOptions configures the Pi RPC subprocess adapter.

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 SubprocessAdapter 

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

SubprocessAdapter runs a subscription CLI as an LLM adapter.

func NewClaudeCLIAdapter 

func NewClaudeCLIAdapter(opts SubprocessOptions) *SubprocessAdapter

NewClaudeCLIAdapter returns a Claude Code subprocess adapter.

func NewCodexCLIAdapter 

func NewCodexCLIAdapter(opts SubprocessOptions) *SubprocessAdapter

NewCodexCLIAdapter returns a Codex CLI subprocess adapter.

func (*SubprocessAdapter) Name 

func (a *SubprocessAdapter) Name() string

Name returns the adapter name.

func (*SubprocessAdapter) Quota 

func (a *SubprocessAdapter) Quota(context.Context) (Quota, bool, error)

Quota reports unsupported quota for subscription CLI adapters.

func (*SubprocessAdapter) Resume 

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

Resume starts a subprocess request from an existing provider session when the adapter supports provider-side session reuse.

func (*SubprocessAdapter) ReviewerWorkspaceMode added in v0.10.196 

func (a *SubprocessAdapter) ReviewerWorkspaceMode() ReviewerWorkspaceMode

ReviewerWorkspaceMode reports the subprocess adapter's reviewer workspace mode.

func (*SubprocessAdapter) Start 

func (a *SubprocessAdapter) Start(ctx context.Context, req Request) (Stream, error)

Start launches the configured subprocess in a fresh scratch directory.

func (*SubprocessAdapter) SupportsCacheAccounting 

func (a *SubprocessAdapter) SupportsCacheAccounting() bool

SupportsCacheAccounting reports whether cache usage metrics are guaranteed.

func (*SubprocessAdapter) SupportsCostReporting 

func (a *SubprocessAdapter) SupportsCostReporting() bool

SupportsCostReporting reports whether cost metrics are guaranteed.

func (*SubprocessAdapter) SupportsResume 

func (a *SubprocessAdapter) SupportsResume() bool

SupportsResume reports whether subprocess session resume is implemented.

type SubprocessOptions 

type SubprocessOptions struct {
	Command                string
	Env                    []string
	Timeout                time.Duration
	ScratchDirFactory      ScratchDirFactory
	AllowBestEffortNoTools bool
	FastModeModels         []string
	// contains filtered or unexported fields
}

SubprocessOptions configures subprocess LLM adapters.

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.