llm

package
v0.3.112 Latest Latest
Warning

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

Go to latest
Published: Jun 13, 2026 License: MIT Imports: 23 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 ErrStructuredOutputInvalidAfterRetry = errors.New("structured output invalid after retry")

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

Functions

func DecodeRollup

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

DecodeRollup validates and maps Rollup structured output.

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

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

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

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
}

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
}

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
}

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

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

Jump to

Keyboard shortcuts

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