llm

package
v0.9.192 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 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 ErrCheckoutReadonlyUnsupported = errors.New("llm adapter: missing checkout-readonly capability")

ErrCheckoutReadonlyUnsupported reports that an adapter cannot safely provide checkout-readonly review access.

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 RequireCheckoutReadonly added in v0.9.184 

func RequireCheckoutReadonly(adapter Adapter) error

RequireCheckoutReadonly returns a stable error when adapter does not expose the supplemental checkout-readonly capability.

func SupportsCheckoutReadonly added in v0.9.184 

func SupportsCheckoutReadonly(adapter Adapter) bool

SupportsCheckoutReadonly reports whether adapter exposes the supplemental checkout-readonly capability.

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 APITokenStore, opts APIOptions) (*APIAdapter, error)

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

func NewAnthropicAPIAdapter 

func NewAnthropicAPIAdapter(opts APIOptions) (*APIAdapter, error)

NewAnthropicAPIAdapter returns an Anthropic Messages API adapter.

func NewOpenAIAPIAdapter 

func NewOpenAIAPIAdapter(opts APIOptions) (*APIAdapter, error)

NewOpenAIAPIAdapter returns an OpenAI Responses API adapter.

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
}

APIOptions configures direct HTTP LLM adapters.

type APITokenStore 

type APITokenStore interface {
	Get(profile string, key string) (string, error)
}

APITokenStore is the minimal credential-store dependency for API 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 CheckoutReadonlyCapable added in v0.9.184 

type CheckoutReadonlyCapable interface {
	SupportsCheckoutReadonly() bool
}

CheckoutReadonlyCapable reports whether an adapter can safely inspect a caller-provided read-only checkout with writes limited to a caller-owned scratch root.

type CheckoutReadonlyRequest added in v0.9.184 

type CheckoutReadonlyRequest struct {
	RootDir            string
	ScratchDir         string
	AllowedFiles       []string
	MaxToolOutputBytes int
}

CheckoutReadonlyRequest describes bounded checkout access for a single LLM invocation. RootDir is the reviewer-visible read root; ScratchDir is the writable scratch root owned by the harness; AllowedFiles preserves the orchestrator's optional narrowing intent for logs and smoke-path assertions.

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
	SupportsCheckoutReadonlySet   bool
	SupportsCheckoutReadonlyValue bool
	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) 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) SupportsCheckoutReadonly added in v0.9.184 

func (f *FakeAdapter) SupportsCheckoutReadonly() bool

SupportsCheckoutReadonly reports whether the fake supports checkout-readonly invocation mode.

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
	// 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

	CheckoutReadonly *CheckoutReadonlyRequest
}

Request describes one LLM invocation.

type Response 

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

Response is the completed LLM result.

func RunStructured 

func RunStructured[T any](ctx context.Context, adapter Adapter, req Request, decode Decoder[T]) (T, Response, error)

RunStructured runs a structured-output request and retries one validation failure with a deterministic correction prompt. On retry success, the returned Response is the final successful attempt's response; this helper does not aggregate usage or duration across attempts.

type ResumeRequest 

type ResumeRequest struct {
	SessionID string
	Request   Request
}

ResumeRequest is one captured Resume invocation.

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 RunStructuredWithSession 

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

RunStructuredWithSession is RunStructured plus the provider session id from the successful attempt. It preserves the same retry-once validation behavior.

func RunStructuredWithSessionResume 

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

RunStructuredWithSessionResume is RunStructuredWithSession 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) 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) SupportsCheckoutReadonly added in v0.9.184 

func (a *SubprocessAdapter) SupportsCheckoutReadonly() bool

SupportsCheckoutReadonly reports whether subprocess adapter can safely mount a caller-owned read-only checkout and keep writes inside caller-owned scratch. Codex CLI can do this with a read-only sandbox plus caller-owned scratch; the current Claude background path cannot because it relies on a different launch model and writable result-file handoff.

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
	// 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
}

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.