context

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package context provides the Context Assembler for Trace.

The Context Assembler combines graph traversal, symbol index lookups, and optionally library documentation to produce focused, relevant context for LLM prompts within a token budget.

Design principles:

  • Respect token budgets strictly (never exceed)
  • Prioritize relevance using fuzzy matching and graph distance
  • Include type definitions with code to provide complete context
  • Support graceful degradation when library docs are unavailable

Index

Constants

View Source 
const (
	// DefaultInputPricePerMillion is the default cost per million input tokens.
	DefaultInputPricePerMillion = 0.25 // $0.25 per 1M tokens

	// DefaultOutputPricePerMillion is the default cost per million output tokens.
	DefaultOutputPricePerMillion = 1.25 // $1.25 per 1M tokens
)

Default pricing (based on Claude Haiku 2024 pricing). These can be overridden via CostConfig.

View Source 
const (
	// ProjectMaxInputTokens is the maximum input tokens for project summaries.
	ProjectMaxInputTokens = 4000

	// ProjectMaxOutputTokens is the maximum output tokens for project summaries.
	ProjectMaxOutputTokens = 500

	// PackageMaxInputTokens is the maximum input tokens for package summaries.
	PackageMaxInputTokens = 2000

	// PackageMaxOutputTokens is the maximum output tokens for package summaries.
	PackageMaxOutputTokens = 300

	// FileMaxInputTokens is the maximum input tokens for file summaries.
	FileMaxInputTokens = 1000

	// FileMaxOutputTokens is the maximum output tokens for file summaries.
	FileMaxOutputTokens = 150

	// FunctionMaxInputTokens is the maximum input tokens for function summaries.
	FunctionMaxInputTokens = 500

	// FunctionMaxOutputTokens is the maximum output tokens for function summaries.
	FunctionMaxOutputTokens = 100

	// DefaultLLMTemperature is the default temperature for summary generation.
	// Lower temperature produces more focused, deterministic summaries.
	DefaultLLMTemperature = 0.3

	// DefaultLLMTimeout is the default timeout for LLM requests.
	DefaultLLMTimeout = 30 * time.Second
)

Token limits for summary generation by hierarchy level. These limits ensure summaries stay concise and cost-effective.

View Source 
const (
	// DefaultPinnedBudget is the default token budget for the pinned block.
	DefaultPinnedBudget = 2000

	// MinPinnedBudget is the minimum viable pinned block budget.
	MinPinnedBudget = 500

	// MaxFindings is the maximum number of key findings to preserve.
	MaxFindings = 10

	// MaxConstraints is the maximum number of constraints.
	MaxConstraints = 10

	// MaxPlanSteps is the maximum number of plan steps.
	MaxPlanSteps = 20

	// MaxFindingSummaryLen is the maximum characters for a finding summary.
	MaxFindingSummaryLen = 100

	// MaxFindingDetailLen is the maximum characters for a finding detail.
	MaxFindingDetailLen = 500

	// MaxConstraintLen is the maximum characters for a constraint.
	MaxConstraintLen = 200

	// MaxOriginalQueryLen is the maximum characters for the original query.
	MaxOriginalQueryLen = 2000

	// MaxStepDescriptionLen is the maximum characters for a plan step description.
	MaxStepDescriptionLen = 200
)

Constants for bounds enforcement.

View Source 
const (
	// DefaultTokenBudget is the default maximum tokens for assembled context.
	DefaultTokenBudget = 8000

	// DefaultGraphDepth is the default BFS traversal depth.
	DefaultGraphDepth = 2

	// DefaultMaxSymbols is the default maximum symbols to collect.
	DefaultMaxSymbols = 100

	// DefaultTimeout is the default assembly timeout.
	DefaultTimeout = 500 * time.Millisecond

	// MaxQueryLength is the maximum allowed query length in characters.
	// Set to 2000 to accommodate queries with embedded code snippets,
	// error messages, or function signatures while still rejecting
	// absurdly large inputs (e.g., OpenWebUI meta-requests that embed
	// full chat histories).
	MaxQueryLength = 2000

	// TokenSafetyBuffer is the percentage of budget reserved as safety margin.
	TokenSafetyBuffer = 0.10

	// CharsPerToken is the approximation ratio for token counting.
	// Conservative estimate: most tokenizers produce ~1 token per 3-4 chars for code.
	CharsPerToken = 3.5

	// MinCodeBudget is the minimum number of tokens reserved for source code context.
	//
	// This constant addresses the "Pinned Budget Context Squeeze" problem:
	// As a session progresses, PinnedInstructions (plan, findings) grows,
	// and without enforcement the code budget can be squeezed to zero.
	//
	// The agent has perfect memory of WHAT it wants to do but can't see
	// the actual code. MinCodeBudget ensures this never happens.
	//
	// The value of 4096 tokens allows approximately:
	//   - 15,000 characters of code (at 3.5 chars/token)
	//   - ~500 lines of typical code
	//   - Enough for a focused function + dependencies
	MinCodeBudget = 4096
)

Default configuration values.

View Source 
const MinSummaryLength = 20

MinSummaryLength is the minimum acceptable summary content length.

Variables

View Source 
var (
	// ErrGraphNotInitialized indicates the graph is nil or not frozen.
	ErrGraphNotInitialized = errors.New("graph not initialized or not frozen")

	// ErrEmptyQuery indicates an empty or whitespace-only query.
	ErrEmptyQuery = errors.New("query must not be empty")

	// ErrQueryTooLong indicates the query exceeds the maximum length.
	ErrQueryTooLong = errors.New("query exceeds maximum length")

	// ErrInvalidBudget indicates a non-positive token budget.
	ErrInvalidBudget = errors.New("token budget must be positive")

	// ErrAssemblyTimeout indicates the assembly operation timed out.
	ErrAssemblyTimeout = errors.New("context assembly timed out")
)

Sentinel errors for context assembly.

View Source 
var (
	// ErrLLMRateLimited indicates the LLM rate limit was exceeded.
	// This error is retryable with exponential backoff.
	ErrLLMRateLimited = errors.New("LLM rate limit exceeded")

	// ErrLLMTimeout indicates the LLM request timed out.
	// This error is retryable.
	ErrLLMTimeout = errors.New("LLM request timed out")

	// ErrLLMServerError indicates a server error (5xx) from the LLM.
	// This error is retryable.
	ErrLLMServerError = errors.New("LLM server error")

	// ErrLLMInvalidRequest indicates an invalid request to the LLM.
	// This error is NOT retryable.
	ErrLLMInvalidRequest = errors.New("invalid LLM request")

	// ErrLLMEmptyPrompt indicates an empty prompt was provided.
	ErrLLMEmptyPrompt = errors.New("prompt must not be empty")

	// ErrLLMEmptyResponse indicates the LLM returned an empty response.
	ErrLLMEmptyResponse = errors.New("LLM returned empty response")

	// ErrLLMUnavailable indicates the LLM service is unavailable.
	// The circuit breaker may be open.
	ErrLLMUnavailable = errors.New("LLM service unavailable")
)

LLM-related errors for summary generation.

View Source 
var (
	// ErrSummaryTooShort indicates the generated summary is too short.
	ErrSummaryTooShort = errors.New("summary too short")

	// ErrInvalidKeyword indicates a keyword was not found in source.
	ErrInvalidKeyword = errors.New("keyword not found in source")

	// ErrLevelMismatch indicates the summary level doesn't match entity type.
	ErrLevelMismatch = errors.New("summary level mismatch")

	// ErrInvalidChild indicates a child reference is invalid.
	ErrInvalidChild = errors.New("invalid child reference")

	// ErrOrphanedSummary indicates a summary has no valid parent.
	ErrOrphanedSummary = errors.New("summary has no valid parent")

	// ErrStaleSummary indicates the summary hash doesn't match source.
	ErrStaleSummary = errors.New("summary is stale")
)

Summary generation errors.

View Source 
var (
	// ErrCacheNotFound indicates the requested item was not in cache.
	ErrCacheNotFound = errors.New("item not found in cache")

	// ErrCacheVersionConflict indicates an optimistic locking conflict.
	ErrCacheVersionConflict = errors.New("cache version conflict")

	// ErrBatchValidationFailed indicates batch validation failed.
	ErrBatchValidationFailed = errors.New("batch validation failed")
)

Cache errors.

View Source 
var (
	// ErrCostLimitExceeded indicates the operation would exceed cost limits.
	ErrCostLimitExceeded = errors.New("cost limit exceeded")

	// ErrTokenLimitExceeded indicates the operation would exceed token limits.
	ErrTokenLimitExceeded = errors.New("token limit exceeded")

	// ErrConfirmationRequired indicates user confirmation is needed.
	ErrConfirmationRequired = errors.New("confirmation required for expensive operation")
)

Cost-related errors.

View Source 
var (
	// ErrUnsupportedLanguage indicates the language is not supported.
	ErrUnsupportedLanguage = errors.New("unsupported language")

	// ErrInvalidEntityID indicates the entity ID is malformed.
	ErrInvalidEntityID = errors.New("invalid entity ID")

	// ErrNoParent indicates the entity has no parent (is root).
	ErrNoParent = errors.New("entity has no parent")
)

Hierarchy errors.

View Source 
var (
	// ErrQueryAlreadySet indicates the original query has already been set.
	ErrQueryAlreadySet = errors.New("original query already set and is immutable")

	// ErrFindingsLimitReached indicates the maximum findings limit was reached.
	ErrFindingsLimitReached = errors.New("maximum findings limit reached")

	// ErrConstraintsLimitReached indicates the maximum constraints limit was reached.
	ErrConstraintsLimitReached = errors.New("maximum constraints limit reached")

	// ErrPlanStepsLimitReached indicates the maximum plan steps limit was reached.
	ErrPlanStepsLimitReached = errors.New("maximum plan steps limit reached")

	// ErrInvalidStepIndex indicates a step index is out of range.
	ErrInvalidStepIndex = errors.New("step index out of range")

	// ErrNilPinnedInstructions indicates a nil PinnedInstructions was passed.
	ErrNilPinnedInstructions = errors.New("pinned instructions is nil")
)

Pinned instructions errors.

View Source 
var DefaultHierarchyRegistry = NewHierarchyRegistry()

DefaultHierarchyRegistry is the global default registry.

View Source 
var DefaultQueryClassifier = NewPatternClassifier()

DefaultQueryClassifier is the default query classifier.

View Source 
var (
	// ErrCircuitOpen indicates the circuit breaker is open.
	// Requests are being rejected to prevent cascade failures.
	ErrCircuitOpen = errors.New("circuit breaker is open")
)

Circuit breaker errors.

Functions

func ApplyOptions 

func ApplyOptions(opts ...LLMOption) (maxTokens int, temperature float64, timeout time.Duration)

ApplyOptions applies the given options to default settings and returns the configured options. This is exported for use by LLM client implementations.

func ComputeContentHash 

func ComputeContentHash(content string) string

ComputeContentHash computes a hash for content used in summaries.

func ContainsCamelCase 

func ContainsCamelCase(s string) bool

ContainsCamelCase returns true if the string contains CamelCase words.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable returns true if the error is retryable.

func MapReduce 

func MapReduce[T any, R any](
	ctx context.Context,
	pool *WorkerPool,
	items []T,
	mapper func(ctx context.Context, item T) (R, error),
) ([]R, error)

MapReduce processes items in parallel and aggregates results.

Inputs:

  • ctx: Context for cancellation.
  • items: Items to process.
  • mapper: Function to process each item.

Outputs:

  • []R: Results for each item (in same order as input).
  • error: Non-nil if any item failed.

Type parameters:

  • T: Input item type.
  • R: Result type.

func SymbolImportance 

func SymbolImportance(kind ast.SymbolKind) float64

SymbolImportance returns an importance weight for ranking.

Functions and methods are most important for understanding code flow. Types and interfaces define contracts. Fields are least important alone.

func TokenLimitsForLevel 

func TokenLimitsForLevel(level HierarchyLevel) (maxInput, maxOutput int)

TokenLimitsForLevel returns the input and output token limits for a hierarchy level.

Types

type AssembleOption 

type AssembleOption func(*AssembleOptions)

AssembleOption is a functional option for configuring assembly.

func WithBudgetAllocation 

func WithBudgetAllocation(alloc BudgetAllocation) AssembleOption

WithBudgetAllocation sets custom budget allocation.

func WithGraphDepth 

func WithGraphDepth(d int) AssembleOption

WithGraphDepth sets the BFS traversal depth.

func WithLibraryDocs 

func WithLibraryDocs(enabled bool) AssembleOption

WithLibraryDocs enables or disables library documentation lookup.

func WithMaxSymbols 

func WithMaxSymbols(n int) AssembleOption

WithMaxSymbols sets the maximum symbols to collect.

func WithTimeout 

func WithTimeout(d time.Duration) AssembleOption

WithTimeout sets the assembly timeout.

type AssembleOptions 

type AssembleOptions struct {
	// Timeout is the maximum duration for assembly (default: 500ms).
	Timeout time.Duration

	// MaxSymbols is the maximum number of symbols to collect (default: 100).
	MaxSymbols int

	// GraphDepth is the BFS traversal depth (default: 2).
	GraphDepth int

	// BudgetAllocation defines budget distribution (default: 60/20/20).
	BudgetAllocation BudgetAllocation

	// IncludeLibraryDocs enables library documentation lookup (default: true).
	IncludeLibraryDocs bool
}

AssembleOptions configures the assembly operation.

func DefaultAssembleOptions 

func DefaultAssembleOptions() AssembleOptions

DefaultAssembleOptions returns sensible defaults for assembly.

type Assembler 

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

Assembler combines graph traversal, symbol index, and library docs to produce focused context for LLM prompts.

Thread Safety: 

Assembler is safe for concurrent use after construction.
The underlying graph and index must be frozen/read-only.

func NewAssembler 

func NewAssembler(g *graph.Graph, idx *index.SymbolIndex, opts ...AssembleOption) *Assembler

NewAssembler creates a new context assembler.

Description: 

Creates an assembler with the given graph, symbol index, and optional
library documentation provider.

Inputs: 

g - The code graph (must be frozen for queries)
idx - The symbol index
opts - Functional options for configuration

Outputs: 

*Assembler - The configured assembler

Example: 

assembler := NewAssembler(graph, index,
    WithGraphDepth(3),
    WithLibraryDocs(true),
)

func (*Assembler) Assemble 

func (a *Assembler) Assemble(ctx context.Context, query string, budget int) (*ContextResult, error)

Assemble creates context for a query within a token budget.

Description: 

Finds entry point symbols from the query, walks the graph to find
related code, ranks results by relevance, and packs into the token
budget with code, types, and optionally library docs.

Inputs: 

ctx - Context for cancellation and timeout
query - The user's query or task description
budget - Maximum tokens to use (must be positive)

Outputs: 

*ContextResult - Assembled context with metadata
error - Non-nil if validation fails or fatal error occurs

Errors: 

ErrGraphNotInitialized - Graph is nil or not frozen
ErrEmptyQuery - Query is empty or whitespace
ErrQueryTooLong - Query exceeds MaxQueryLength
ErrInvalidBudget - Budget is not positive

Example: 

result, err := assembler.Assemble(ctx, "Add authentication to HandleAgent", 8000)
if err != nil {
    return err
}
fmt.Println(result.Context)

func (*Assembler) GetSymbolSourceCode 

func (a *Assembler) GetSymbolSourceCode(sym *ast.Symbol) string

GetSymbolSourceCode returns the source code for a symbol.

Description: 

Reads the actual source code from disk using the symbol's file path
and line range. Returns the signature as fallback if file read fails.

Inputs: 

sym - The symbol to get source code for.

Outputs: 

string - The source code (or signature as fallback).

Thread Safety: This method is safe for concurrent use.

func (*Assembler) WithLibraryDocProvider 

func (a *Assembler) WithLibraryDocProvider(p LibraryDocProvider) *Assembler

WithLibraryDocProvider sets the library documentation provider.

Description: 

Enables library documentation lookup during context assembly.
If not set, library docs are skipped gracefully.

type BatchResult 

type BatchResult struct {
	// Results contains results for each work item.
	Results []WorkResult

	// SuccessCount is the number of successful items.
	SuccessCount int

	// FailureCount is the number of failed items.
	FailureCount int

	// TotalDuration is the total time for the batch.
	TotalDuration time.Duration

	// Cancelled indicates if the batch was cancelled.
	Cancelled bool
}

BatchResult contains results from a batch operation.

type BudgetAllocation 

type BudgetAllocation struct {
	// CodePercent is the percentage allocated to primary code (default: 60).
	CodePercent int

	// TypesPercent is the percentage allocated to type signatures (default: 20).
	TypesPercent int

	// LibDocsPercent is the percentage allocated to library docs (default: 20).
	LibDocsPercent int
}

BudgetAllocation defines how the token budget is split across content types.

func DefaultBudgetAllocation 

func DefaultBudgetAllocation() BudgetAllocation

DefaultBudgetAllocation returns the default 60/20/20 split.

func (BudgetAllocation) Validate 

func (b BudgetAllocation) Validate() bool

Validate checks that the allocation percentages sum to 100.

type CacheConfig 

type CacheConfig struct {
	// StaleReadEnabled allows returning stale summaries on failure.
	StaleReadEnabled bool `json:"stale_read_enabled"`

	// StaleTTL is how long to keep stale entries readable.
	StaleTTL time.Duration `json:"stale_ttl"`

	// MaxEntries is the maximum number of entries to cache.
	// 0 means unlimited.
	MaxEntries int `json:"max_entries"`

	// FreshTTL is how long summaries are considered fresh.
	FreshTTL time.Duration `json:"fresh_ttl"`
}

CacheConfig configures the summary cache behavior.

func DefaultCacheConfig 

func DefaultCacheConfig() CacheConfig

DefaultCacheConfig returns sensible defaults for the cache.

type CacheStats 

type CacheStats struct {
	Entries   int   `json:"entries"`
	Hits      int64 `json:"hits"`
	Misses    int64 `json:"misses"`
	StaleHits int64 `json:"stale_hits"`
	Evictions int64 `json:"evictions"`
}

CacheStats contains cache statistics.

func (CacheStats) HitRate 

func (s CacheStats) HitRate() float64

HitRate returns the cache hit rate (0.0-1.0).

type ChangeSet 

type ChangeSet struct {
	// AddedFiles are new files added to the project.
	AddedFiles []FileInfo `json:"added_files"`

	// ModifiedFiles are files that were changed.
	ModifiedFiles []FileInfo `json:"modified_files"`

	// DeletedFiles are file paths that were removed.
	DeletedFiles []string `json:"deleted_files"`

	// Timestamp is when the changes were detected.
	Timestamp time.Time `json:"timestamp"`
}

ChangeSet describes a set of code changes.

func (*ChangeSet) IsEmpty 

func (c *ChangeSet) IsEmpty() bool

IsEmpty returns true if there are no changes.

func (*ChangeSet) TotalChanges 

func (c *ChangeSet) TotalChanges() int

TotalChanges returns the total number of changes.

type CircuitBreaker 

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

CircuitBreaker implements the circuit breaker pattern for fault tolerance.

The circuit breaker has three states: - Closed: Normal operation, requests pass through - Open: Failure threshold exceeded, requests are rejected immediately - Half-Open: Testing recovery, limited requests allowed

Thread Safety: Safe for concurrent use.

func NewCircuitBreaker 

func NewCircuitBreaker(config CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreaker creates a new circuit breaker with the given configuration.

Inputs:

  • config: Configuration for thresholds and timeouts.

Outputs:

  • *CircuitBreaker: A new circuit breaker in closed state.

func (*CircuitBreaker) Allow 

func (cb *CircuitBreaker) Allow() bool

Allow checks if a request should be allowed through.

Returns true if the request is allowed, false if it should be rejected. In half-open state, this also tracks the number of probe requests.

Outputs:

  • bool: True if request is allowed.

Thread Safety: Safe for concurrent use.

func (*CircuitBreaker) RecordFailure 

func (cb *CircuitBreaker) RecordFailure()

RecordFailure records a failed request.

Consecutive failures may open the circuit.

Thread Safety: Safe for concurrent use.

func (*CircuitBreaker) RecordSuccess 

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess records a successful request.

In half-open state, consecutive successes may close the circuit.

Thread Safety: Safe for concurrent use.

func (*CircuitBreaker) Reset 

func (cb *CircuitBreaker) Reset()

Reset resets the circuit breaker to closed state.

This is primarily for testing or manual intervention.

Thread Safety: Safe for concurrent use.

func (*CircuitBreaker) State 

func (cb *CircuitBreaker) State() CircuitState

State returns the current circuit state.

Thread Safety: Safe for concurrent use.

func (*CircuitBreaker) Stats 

func (cb *CircuitBreaker) Stats() CircuitBreakerStats

Stats returns current circuit breaker statistics.

Thread Safety: Safe for concurrent use.

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	// FailureThreshold is the number of consecutive failures before opening.
	// Default: 5
	FailureThreshold int

	// ResetTimeout is the duration to wait before transitioning from open to half-open.
	// Default: 30s
	ResetTimeout time.Duration

	// HalfOpenMaxRequests is the max requests allowed in half-open state.
	// Default: 2
	HalfOpenMaxRequests int

	// SuccessThreshold is the number of consecutive successes in half-open to close.
	// Default: 2
	SuccessThreshold int
}

CircuitBreakerConfig configures the circuit breaker behavior.

func DefaultCircuitBreakerConfig 

func DefaultCircuitBreakerConfig() CircuitBreakerConfig

DefaultCircuitBreakerConfig returns sensible defaults for the circuit breaker.

type CircuitBreakerStats 

type CircuitBreakerStats struct {
	State                CircuitState
	ConsecutiveFailures  int
	ConsecutiveSuccesses int
	LastFailureTime      time.Time
	LastStateChange      time.Time
}

CircuitBreakerStats contains circuit breaker statistics.

func (CircuitBreakerStats) TimeSinceLastFailure 

func (s CircuitBreakerStats) TimeSinceLastFailure() time.Duration

TimeSinceLastFailure returns the duration since the last failure.

func (CircuitBreakerStats) TimeSinceStateChange 

func (s CircuitBreakerStats) TimeSinceStateChange() time.Duration

TimeSinceStateChange returns the duration since the last state change.

type CircuitState 

type CircuitState int

CircuitState represents the state of a circuit breaker. 

const (
	// CircuitClosed allows requests through normally.
	CircuitClosed CircuitState = iota

	// CircuitOpen rejects all requests immediately.
	CircuitOpen

	// CircuitHalfOpen allows limited requests to test recovery.
	CircuitHalfOpen
)

func (CircuitState) String 

func (s CircuitState) String() string

String returns the human-readable name for the circuit state.

type ConcurrencyConfig 

type ConcurrencyConfig struct {
	// MaxLLMConcurrency is the maximum concurrent LLM calls.
	// Prevents rate limiting. Default: 5
	MaxLLMConcurrency int `json:"max_llm_concurrency"`

	// MaxWeaviateConcurrency is the maximum concurrent Weaviate operations.
	// Weaviate can handle more than LLM. Default: 10
	MaxWeaviateConcurrency int `json:"max_weaviate_concurrency"`

	// WeaviateBatchSize is the batch size for Weaviate bulk operations.
	// Default: 20
	WeaviateBatchSize int `json:"weaviate_batch_size"`

	// PerEntityTimeout is the timeout for processing a single entity.
	// Default: 30s
	PerEntityTimeout time.Duration `json:"per_entity_timeout"`

	// TotalTimeout is the total timeout for batch operations.
	// Default: 10m
	TotalTimeout time.Duration `json:"total_timeout"`
}

ConcurrencyConfig configures parallel processing limits.

func DefaultConcurrencyConfig 

func DefaultConcurrencyConfig() ConcurrencyConfig

DefaultConcurrencyConfig returns sensible defaults for concurrency.

type ContextResult 

type ContextResult struct {
	// Context is the formatted markdown context for LLM consumption.
	Context string `json:"context"`

	// TokensUsed is the estimated number of tokens used.
	TokensUsed int `json:"tokens_used"`

	// SymbolsIncluded lists the IDs of symbols included in context.
	SymbolsIncluded []string `json:"symbols_included"`

	// LibraryDocsIncluded lists the IDs of library docs included.
	LibraryDocsIncluded []string `json:"library_docs_included"`

	// Suggestions provides "also consider" hints for the user/agent.
	Suggestions []string `json:"suggestions"`

	// AssemblyDurationMs is how long assembly took in milliseconds.
	AssemblyDurationMs int64 `json:"assembly_duration_ms"`

	// Truncated indicates if results were limited by budget or timeout.
	Truncated bool `json:"truncated"`
}

ContextResult contains the assembled context and metadata.

type CostConfig 

type CostConfig struct {
	// InputPricePerMillion is the cost per million input tokens.
	InputPricePerMillion float64 `json:"input_price_per_million"`

	// OutputPricePerMillion is the cost per million output tokens.
	OutputPricePerMillion float64 `json:"output_price_per_million"`
}

CostConfig configures cost calculation.

func DefaultCostConfig 

func DefaultCostConfig() CostConfig

DefaultCostConfig returns default pricing configuration.

type CostEstimate 

type CostEstimate struct {
	// Entity counts by level
	ProjectCount  int `json:"project_count"`
	PackageCount  int `json:"package_count"`
	FileCount     int `json:"file_count"`
	FunctionCount int `json:"function_count,omitempty"` // Usually not summarized individually

	// Total estimated tokens
	EstimatedInputTokens  int `json:"estimated_input_tokens"`
	EstimatedOutputTokens int `json:"estimated_output_tokens"`
	EstimatedTotalTokens  int `json:"estimated_total_tokens"`

	// Cost in USD
	EstimatedCostUSD float64 `json:"estimated_cost_usd"`

	// Breakdown by hierarchy level
	LevelBreakdown map[HierarchyLevel]LevelCost `json:"level_breakdown"`
}

CostEstimate contains estimated costs for summary generation.

type CostEstimator 

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

CostEstimator estimates and tracks LLM costs.

Thread Safety: Safe for concurrent use.

func NewCostEstimator 

func NewCostEstimator(config CostConfig, limits CostLimits) *CostEstimator

NewCostEstimator creates a new cost estimator with the given configuration.

func (*CostEstimator) CheckLimits 

func (e *CostEstimator) CheckLimits(estimate *CostEstimate) error

CheckLimits checks if an operation would exceed limits.

Inputs:

  • estimate: The cost estimate for the operation.

Outputs:

  • error: Non-nil if limits would be exceeded.
  • ErrTokenLimitExceeded: Token limit would be exceeded.
  • ErrCostLimitExceeded: Cost limit would be exceeded.
  • ErrConfirmationRequired: Operation needs confirmation.

func (*CostEstimator) CostSummary 

func (e *CostEstimator) CostSummary() CostSummaryReport

CostSummary returns a human-readable cost summary.

func (*CostEstimator) EnforceLimits 

func (e *CostEstimator) EnforceLimits(estimate *CostEstimate) error

EnforceLimits is a convenience function that checks limits and returns a detailed error if exceeded.

func (*CostEstimator) EstimateForLevel 

func (e *CostEstimator) EstimateForLevel(level HierarchyLevel, count int) *LevelCost

EstimateForLevel estimates costs for summarizing entities at a specific level.

Inputs:

  • level: The hierarchy level.
  • count: Number of entities to summarize.

Outputs:

  • *LevelCost: The cost breakdown for this level.

func (*CostEstimator) EstimateForProject 

func (e *CostEstimator) EstimateForProject(projectCount, packageCount, fileCount int) *CostEstimate

EstimateForProject estimates costs for summarizing an entire project.

Inputs:

  • projectCount: Number of projects (typically 1).
  • packageCount: Number of packages.
  • fileCount: Number of files.

Outputs:

  • *CostEstimate: The cost estimate with breakdowns.

func (*CostEstimator) GetUsage 

func (e *CostEstimator) GetUsage() (inputTokens, outputTokens int64, costUSD float64)

GetUsage returns the current usage totals.

Thread Safety: Safe for concurrent use.

func (*CostEstimator) RecordUsage 

func (e *CostEstimator) RecordUsage(inputTokens, outputTokens int)

RecordUsage records actual token usage.

Thread Safety: Safe for concurrent use.

func (*CostEstimator) RemainingBudget 

func (e *CostEstimator) RemainingBudget() (tokensRemaining int, costRemaining float64)

RemainingBudget returns the remaining token and cost budget.

Thread Safety: Safe for concurrent use.

func (*CostEstimator) ResetUsage 

func (e *CostEstimator) ResetUsage()

ResetUsage resets the usage counters.

Thread Safety: Safe for concurrent use.

func (*CostEstimator) WouldExceedCostLimit 

func (e *CostEstimator) WouldExceedCostLimit(additionalCostUSD float64) bool

WouldExceedCostLimit checks if additional cost would exceed the limit.

Thread Safety: Safe for concurrent use.

func (*CostEstimator) WouldExceedTokenLimit 

func (e *CostEstimator) WouldExceedTokenLimit(additionalTokens int) bool

WouldExceedTokenLimit checks if additional tokens would exceed the limit.

Thread Safety: Safe for concurrent use.

type CostLimits 

type CostLimits struct {
	// MaxTotalTokens is the hard limit on total tokens.
	// Default: 1,000,000
	MaxTotalTokens int `json:"max_total_tokens"`

	// MaxCostUSD is the budget cap in USD.
	// Default: $10.00
	MaxCostUSD float64 `json:"max_cost_usd"`

	// RequireConfirmation enables confirmation prompts for expensive operations.
	RequireConfirmation bool `json:"require_confirmation"`

	// ConfirmationThresholdUSD is the cost threshold for confirmation.
	// Operations exceeding this require confirmation if RequireConfirmation is true.
	// Default: $1.00
	ConfirmationThresholdUSD float64 `json:"confirmation_threshold_usd"`
}

CostLimits configures cost thresholds and controls.

func DefaultCostLimits 

func DefaultCostLimits() CostLimits

DefaultCostLimits returns sensible default cost limits.

type CostSummaryReport 

type CostSummaryReport struct {
	InputTokensUsed   int     `json:"input_tokens_used"`
	OutputTokensUsed  int     `json:"output_tokens_used"`
	TotalTokensUsed   int     `json:"total_tokens_used"`
	CostUSD           float64 `json:"cost_usd"`
	TokensRemaining   int     `json:"tokens_remaining"`
	CostRemainingUSD  float64 `json:"cost_remaining_usd"`
	TokenLimitPercent float64 `json:"token_limit_percent"`
	CostLimitPercent  float64 `json:"cost_limit_percent"`
}

CostSummaryReport contains a summary of cost usage.

type EntityComponents 

type EntityComponents struct {
	// ProjectRoot is the project identifier (Level 0).
	ProjectRoot string

	// Package is the package/module identifier (Level 1).
	Package string

	// File is the file name (Level 2).
	File string

	// Symbol is the symbol name (Level 3).
	Symbol string

	// Level is the inferred hierarchy level.
	Level int
}

EntityComponents contains the parsed parts of an entity ID.

type FileInfo 

type FileInfo struct {
	Path        string       `json:"path"`
	Package     string       `json:"package"`
	Symbols     []SymbolInfo `json:"symbols"`
	LineCount   int          `json:"line_count"`
	ContentHash string       `json:"content_hash"`
}

FileInfo provides file information for summary generation.

type Finding 

type Finding struct {
	// Summary is a short description (max 100 chars, enforced).
	Summary string `json:"summary"`

	// Detail is a longer explanation (max 500 chars, enforced).
	Detail string `json:"detail,omitempty"`

	// Source is the file:line or tool that produced this finding.
	Source string `json:"source"`

	// Timestamp is when the finding was recorded (Unix milliseconds UTC).
	Timestamp int64 `json:"timestamp"`
}

Finding represents a key discovery worth preserving.

type GenerationResult 

type GenerationResult struct {
	Summaries    []*Summary    `json:"summaries"`
	SuccessCount int           `json:"success_count"`
	FailureCount int           `json:"failure_count"`
	PartialCount int           `json:"partial_count"`
	TotalTokens  int           `json:"total_tokens"`
	TotalCost    float64       `json:"total_cost"`
	Duration     time.Duration `json:"duration"`
	Errors       []string      `json:"errors,omitempty"`
}

GenerationResult contains results from batch summary generation.

type GoHierarchy 

type GoHierarchy struct{}

GoHierarchy implements LanguageHierarchy for Go projects.

Go hierarchy structure: - Level 0: Project (directory containing go.mod) - Level 1: Package (directory containing .go files) - Level 2: File (.go file) - Level 3: Symbol (function, type, method, etc.)

Entity ID format: - Project: "" (empty, represents root) - Package: "pkg/auth" or "internal/db" - File: "pkg/auth/validator.go" - Symbol: "pkg/auth/validator.go#ValidateToken"

Thread Safety: Safe for concurrent use (stateless).

func (*GoHierarchy) BuildEntityID 

func (h *GoHierarchy) BuildEntityID(c EntityComponents) string

BuildEntityID constructs an entity ID from components.

func (*GoHierarchy) ChildrenOf 

func (h *GoHierarchy) ChildrenOf(entityID string) ([]string, error)

ChildrenOf returns possible child entity IDs. Note: This returns structural children based on ID pattern, not actual filesystem children.

func (*GoHierarchy) EntityLevel 

func (h *GoHierarchy) EntityLevel(entityID string) int

EntityLevel determines the hierarchy level from an entity ID.

func (*GoHierarchy) IsInternalPackage 

func (h *GoHierarchy) IsInternalPackage(pkgPath string) bool

IsInternalPackage returns true if the package is internal.

func (*GoHierarchy) IsTestFile 

func (h *GoHierarchy) IsTestFile(filePath string) bool

IsTestFile returns true if the file is a Go test file.

func (*GoHierarchy) Language 

func (h *GoHierarchy) Language() string

Language returns "go".

func (*GoHierarchy) LevelCount 

func (h *GoHierarchy) LevelCount() int

LevelCount returns 4 (project, package, file, symbol).

func (*GoHierarchy) LevelName 

func (h *GoHierarchy) LevelName(level int) string

LevelName returns the name for each level.

func (*GoHierarchy) PackageFromFile 

func (h *GoHierarchy) PackageFromFile(filePath string) string

PackageFromFile extracts the package path from a file path.

func (*GoHierarchy) ParentOf 

func (h *GoHierarchy) ParentOf(entityID string) (string, error)

ParentOf returns the parent entity ID.

func (*GoHierarchy) ParseEntityID 

func (h *GoHierarchy) ParseEntityID(entityID string) EntityComponents

ParseEntityID extracts components from a Go entity ID.

func (*GoHierarchy) RootMarkers 

func (h *GoHierarchy) RootMarkers() []string

RootMarkers returns Go project root markers.

type HierarchicalRetriever 

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

HierarchicalRetriever performs hierarchical context retrieval.

Thread Safety: Safe for concurrent use.

func NewHierarchicalRetriever 

func NewHierarchicalRetriever(cache *SummaryCache, classifier QueryClassifier, config RetrieverConfig) *HierarchicalRetriever

NewHierarchicalRetriever creates a new retriever.

Inputs:

  • cache: The summary cache to query.
  • classifier: The query classifier.
  • config: Retriever configuration.

Outputs:

  • *HierarchicalRetriever: A new retriever instance.

func (*HierarchicalRetriever) Retrieve 

func (r *HierarchicalRetriever) Retrieve(ctx context.Context, query string, tokenBudget int) (*RetrievalResult, error)

Retrieve performs hierarchical retrieval for a query.

Inputs:

  • ctx: Context for cancellation.
  • query: The user query.
  • tokenBudget: Maximum tokens to consume.

Outputs:

  • *RetrievalResult: The retrieval results.
  • error: Non-nil if retrieval fails completely.

type HierarchyLevel 

type HierarchyLevel int

HierarchyLevel represents a level in the code hierarchy. 

const (
	// LevelProject is the project root level (Level 0).
	LevelProject HierarchyLevel = iota

	// LevelPackage is the package/module level (Level 1).
	LevelPackage

	// LevelFile is the file level (Level 2).
	LevelFile

	// LevelFunction is the function/symbol level (Level 3).
	LevelFunction
)

func (HierarchyLevel) MaxInputTokens 

func (l HierarchyLevel) MaxInputTokens() int

MaxInputTokens returns the maximum input tokens for this hierarchy level.

func (HierarchyLevel) MaxOutputTokens 

func (l HierarchyLevel) MaxOutputTokens() int

MaxOutputTokens returns the maximum output tokens for this hierarchy level.

func (HierarchyLevel) String 

func (l HierarchyLevel) String() string

String returns the human-readable name for the hierarchy level.

type HierarchyRegistry 

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

HierarchyRegistry manages language hierarchy implementations.

Thread Safety: Safe for concurrent use.

func NewHierarchyRegistry 

func NewHierarchyRegistry() *HierarchyRegistry

NewHierarchyRegistry creates a new registry with default hierarchies.

func (*HierarchyRegistry) DetectLanguage 

func (r *HierarchyRegistry) DetectLanguage(filePath string) string

DetectLanguage attempts to detect the language from a file path.

Inputs:

  • filePath: The file path to analyze.

Outputs:

  • string: The detected language ("go", "python", etc.) or empty if unknown.

func (*HierarchyRegistry) Get 

func (r *HierarchyRegistry) Get(language string) (LanguageHierarchy, bool)

Get returns the hierarchy for a language.

Inputs:

  • language: The language identifier.

Outputs:

  • LanguageHierarchy: The hierarchy, or nil if not found.
  • bool: True if found.

func (*HierarchyRegistry) GetForFile 

func (r *HierarchyRegistry) GetForFile(filePath string) LanguageHierarchy

GetForFile returns the appropriate hierarchy for a file.

Inputs:

  • filePath: The file path.

Outputs:

  • LanguageHierarchy: The hierarchy, or nil if language not supported.

func (*HierarchyRegistry) Languages 

func (r *HierarchyRegistry) Languages() []string

Languages returns all registered language identifiers.

func (*HierarchyRegistry) Register 

func (r *HierarchyRegistry) Register(h LanguageHierarchy)

Register adds a language hierarchy to the registry.

type IntegrityChecker 

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

IntegrityChecker validates the hierarchical summary structure.

Thread Safety: Safe for concurrent use.

func NewIntegrityChecker 

func NewIntegrityChecker(cache *SummaryCache, hierarchy LanguageHierarchy) *IntegrityChecker

NewIntegrityChecker creates a new integrity checker.

Inputs:

  • cache: The summary cache to check.
  • hierarchy: The language hierarchy for validation.

Outputs:

  • *IntegrityChecker: A new checker instance.

func (*IntegrityChecker) Repair 

func (c *IntegrityChecker) Repair(ctx context.Context, report *IntegrityReport) (*RepairResult, error)

Repair attempts to fix integrity issues.

Inputs:

  • ctx: Context for cancellation.
  • report: The integrity report with issues to fix.

Outputs:

  • *RepairResult: Summary of repairs made.
  • error: Non-nil if repair couldn't be completed.

func (*IntegrityChecker) Validate 

func (c *IntegrityChecker) Validate(ctx context.Context) (*IntegrityReport, error)

Validate performs a comprehensive integrity check.

Inputs:

  • ctx: Context for cancellation.

Outputs:

  • *IntegrityReport: The validation report.
  • error: Non-nil if the check couldn't be completed.

func (*IntegrityChecker) ValidateWithHashes 

func (c *IntegrityChecker) ValidateWithHashes(
	ctx context.Context,
	hashProvider func(entityID string) (string, error),
) (*IntegrityReport, error)

ValidateWithHashes performs validation including hash checks.

Inputs:

  • ctx: Context for cancellation.
  • hashProvider: Function to get current hash for an entity.

Outputs:

  • *IntegrityReport: The validation report.
  • error: Non-nil if the check couldn't be completed.

type IntegrityReport 

type IntegrityReport struct {
	// Valid is true if no integrity issues were found.
	Valid bool `json:"valid"`

	// OrphanedChildren are summaries whose parents don't exist.
	OrphanedChildren []string `json:"orphaned_children,omitempty"`

	// MissingChildren are parent-child references where the child doesn't exist.
	MissingChildren []MissingChild `json:"missing_children,omitempty"`

	// LevelMismatches are entities with incorrect hierarchy levels.
	LevelMismatches []LevelMismatch `json:"level_mismatches,omitempty"`

	// StaleEntries are summaries with outdated hashes.
	StaleEntries []StaleEntry `json:"stale_entries,omitempty"`

	// Timestamp is when this check was performed.
	Timestamp time.Time `json:"timestamp"`

	// Duration is how long the check took.
	Duration time.Duration `json:"duration"`

	// TotalChecked is the number of entries checked.
	TotalChecked int `json:"total_checked"`
}

IntegrityReport contains the results of an integrity check.

func (*IntegrityReport) IssueCount 

func (r *IntegrityReport) IssueCount() int

IssueCount returns the total number of issues found.

type LLMClient 

type LLMClient interface {
	// Complete sends a prompt and returns the LLM response.
	//
	// Inputs:
	//   - ctx: Context for cancellation and timeout. Must not be nil.
	//   - prompt: The prompt text to send. Must not be empty.
	//   - opts: Optional parameters (max tokens, temperature, timeout).
	//
	// Outputs:
	//   - *LLMResponse: The completion result. Never nil on success.
	//   - error: Non-nil on failure (rate limit, timeout, invalid input, etc.).
	//
	// Errors:
	//   - ErrLLMRateLimited: Rate limit exceeded (retryable)
	//   - ErrLLMTimeout: Request timed out (retryable)
	//   - ErrLLMServerError: Server error 5xx (retryable)
	//   - ErrLLMInvalidRequest: Invalid request (not retryable)
	//
	// Example:
	//   resp, err := client.Complete(ctx, "Summarize this package...",
	//       WithMaxTokens(300),
	//       WithTemperature(0.3),
	//   )
	Complete(ctx context.Context, prompt string, opts ...LLMOption) (*LLMResponse, error)

	// EstimateTokens returns approximate token count for text.
	//
	// Used for budget management before sending requests.
	// Implementations should use the model's tokenizer or a reasonable
	// approximation (e.g., ~4 chars per token for English).
	//
	// Inputs:
	//   - text: The text to estimate tokens for.
	//
	// Outputs:
	//   - int: Estimated token count. Always >= 0.
	EstimateTokens(text string) int
}

LLMClient abstracts LLM operations for summary generation.

Implementations must handle: - Rate limiting with appropriate backoff - Request timeouts - Context cancellation

Thread Safety: Implementations must be safe for concurrent use.

type LLMOption 

type LLMOption func(*llmOptions)

LLMOption is a functional option for configuring LLM requests.

func WithLLMTimeout 

func WithLLMTimeout(d time.Duration) LLMOption

WithLLMTimeout sets the timeout for the LLM request.

Inputs:

  • d: Timeout duration. Must be positive.

If d <= 0, this option is ignored.

func WithLevelTokenLimits 

func WithLevelTokenLimits(level HierarchyLevel) LLMOption

WithLevelTokenLimits sets token limits appropriate for the hierarchy level.

This is a convenience option that sets MaxTokens based on the hierarchy level.

func WithMaxTokens 

func WithMaxTokens(n int) LLMOption

WithMaxTokens sets the maximum tokens for the response.

Inputs:

  • n: Maximum tokens. Must be positive.

If n <= 0, this option is ignored.

func WithTemperature 

func WithTemperature(t float64) LLMOption

WithTemperature sets the sampling temperature.

Inputs:

  • t: Temperature value. Should be in range [0.0, 2.0].

Lower values (0.0-0.3) produce more focused, deterministic output. Higher values (0.7-1.0) produce more creative, varied output. If t < 0, this option is ignored.

type LLMResponse 

type LLMResponse struct {
	// Content is the generated text content.
	Content string `json:"content"`

	// TokensUsed is the total tokens consumed (input + output).
	TokensUsed int `json:"tokens_used"`

	// InputTokens is the number of input tokens consumed.
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the number of output tokens generated.
	OutputTokens int `json:"output_tokens"`

	// FinishReason indicates why generation stopped.
	// Values: "stop" (natural end), "length" (max tokens), "error"
	FinishReason string `json:"finish_reason"`

	// Model is the model identifier that generated this response.
	Model string `json:"model,omitempty"`
}

LLMResponse represents a completion response from the LLM.

type LanguageHierarchy 

type LanguageHierarchy interface {
	// Language returns the language identifier (e.g., "go", "python").
	Language() string

	// LevelCount returns the number of hierarchy levels (typically 4).
	LevelCount() int

	// LevelName returns human-readable name for a level.
	//
	// Inputs:
	//   - level: Hierarchy level (0-3 typically).
	//
	// Outputs:
	//   - string: Level name (e.g., "package", "module", "file").
	LevelName(level int) string

	// ParentOf returns the parent entity ID for a given entity.
	//
	// Inputs:
	//   - entityID: The entity ID (e.g., "pkg/auth/validator.go").
	//
	// Outputs:
	//   - string: Parent entity ID (e.g., "pkg/auth").
	//   - error: ErrNoParent if entity is root, ErrInvalidEntityID if malformed.
	ParentOf(entityID string) (string, error)

	// ChildrenOf returns child entity IDs for a given entity.
	// This is a structural query - it returns possible children based on ID,
	// not by scanning the filesystem.
	//
	// Inputs:
	//   - entityID: The entity ID.
	//
	// Outputs:
	//   - []string: Child entity IDs.
	//   - error: ErrInvalidEntityID if malformed.
	//
	// Note: For actual file system children, use the graph/manifest instead.
	ChildrenOf(entityID string) ([]string, error)

	// EntityLevel returns the hierarchy level for an entity.
	//
	// Inputs:
	//   - entityID: The entity ID.
	//
	// Outputs:
	//   - int: Level (0=project, 1=package, 2=file, 3=function).
	EntityLevel(entityID string) int

	// RootMarkers returns files that indicate project/package roots.
	//
	// Outputs:
	//   - []string: Marker file names (e.g., ["go.mod"], ["pyproject.toml"]).
	RootMarkers() []string

	// ParseEntityID extracts components from an entity ID.
	//
	// Inputs:
	//   - entityID: The entity ID.
	//
	// Outputs:
	//   - EntityComponents: Parsed components.
	ParseEntityID(entityID string) EntityComponents

	// BuildEntityID constructs an entity ID from components.
	//
	// Inputs:
	//   - components: The components to join.
	//
	// Outputs:
	//   - string: The constructed entity ID.
	BuildEntityID(components EntityComponents) string
}

LanguageHierarchy defines how a language organizes code into levels.

Different languages have different hierarchy structures: - Go: project → package → file → symbol - Python: project → package → module → symbol - TypeScript: project → module → file → symbol

Thread Safety: Implementations must be safe for concurrent use.

func GetHierarchyForLanguage 

func GetHierarchyForLanguage(language string) (LanguageHierarchy, bool)

GetHierarchyForLanguage is a convenience function to get a hierarchy.

type LevelCost 

type LevelCost struct {
	EntityCount  int     `json:"entity_count"`
	InputTokens  int     `json:"input_tokens"`
	OutputTokens int     `json:"output_tokens"`
	CostUSD      float64 `json:"cost_usd"`
}

LevelCost contains cost breakdown for a single hierarchy level.

type LevelMismatch 

type LevelMismatch struct {
	EntityID      string `json:"entity_id"`
	ExpectedLevel int    `json:"expected_level"`
	ActualLevel   int    `json:"actual_level"`
}

LevelMismatch represents an entity with an incorrect hierarchy level.

type LibraryDoc 

type LibraryDoc struct {
	// DocID is a unique identifier for this documentation entry.
	DocID string `json:"doc_id"`

	// Library is the library name (e.g., "github.com/gin-gonic/gin").
	Library string `json:"library"`

	// Version is the library version (e.g., "v1.9.1").
	Version string `json:"version"`

	// SymbolPath is the fully qualified symbol path (e.g., "gin.Context.JSON").
	SymbolPath string `json:"symbol_path"`

	// SymbolKind is the type of symbol (function, type, method, etc.).
	SymbolKind string `json:"symbol_kind"`

	// Signature is the type signature (e.g., "func(code int, obj interface{})").
	Signature string `json:"signature"`

	// DocContent is the documentation text.
	DocContent string `json:"doc_content"`

	// Example is an optional usage example.
	Example string `json:"example,omitempty"`
}

LibraryDoc represents documentation for an external library symbol.

type LibraryDocProvider 

type LibraryDocProvider interface {
	// Search finds library documentation matching the query.
	//
	// Inputs:
	//   ctx - Context for cancellation
	//   query - Search query (library name, symbol name, etc.)
	//   limit - Maximum number of results to return
	//
	// Outputs:
	//   []LibraryDoc - Matching documentation entries
	//   error - Non-nil if search fails
	Search(ctx context.Context, query string, limit int) ([]LibraryDoc, error)
}

LibraryDocProvider is the interface for fetching library documentation.

Implementations may query Weaviate, local caches, or external APIs. The interface allows graceful degradation when the provider is unavailable.

type MissingChild 

type MissingChild struct {
	ParentID string `json:"parent_id"`
	ChildID  string `json:"child_id"`
}

MissingChild represents a parent referencing a non-existent child.

type PackageInfo 

type PackageInfo struct {
	Path      string       `json:"path"`
	Name      string       `json:"name"`
	Symbols   []SymbolInfo `json:"symbols"`
	Imports   []string     `json:"imports,omitempty"`
	FileCount int          `json:"file_count"`
}

PackageInfo provides package information for summary generation.

type PatternClassifier 

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

PatternClassifier implements QueryClassifier using pattern matching.

Thread Safety: Safe for concurrent use (stateless after init).

func NewPatternClassifier 

func NewPatternClassifier() *PatternClassifier

NewPatternClassifier creates a new pattern-based classifier.

func (*PatternClassifier) Classify 

func (c *PatternClassifier) Classify(query string) *QueryClassification

Classify classifies a query based on pattern matching.

type PinnedInstructions 

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

PinnedInstructions contains context that survives all truncation.

Thread Safety: Safe for concurrent use via RWMutex. All mutating methods invalidate the render cache.

func NewPinnedInstructions 

func NewPinnedInstructions(opts ...PinnedOption) *PinnedInstructions

NewPinnedInstructions creates a new pinned instructions block.

Description: 

Creates a PinnedInstructions with the specified options.
Default budget is DefaultPinnedBudget (2000 tokens).

Inputs: 

opts - Functional options for configuration.

Outputs: 

*PinnedInstructions - The configured pinned instructions block.

Example: 

pinned := NewPinnedInstructions(
    WithTokenBudget(3000),
)

func (*PinnedInstructions) AddConstraint 

func (p *PinnedInstructions) AddConstraint(constraint string) error

AddConstraint adds a constraint the agent must respect.

Description: 

Adds a constraint to the pinned block. Constraints are rules
that the agent must follow while working on the task.
Truncates to MaxConstraintLen if too long.

Inputs: 

constraint - The constraint to add.

Outputs: 

error - ErrConstraintsLimitReached if at capacity.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) AddFinding 

func (p *PinnedInstructions) AddFinding(ctx context.Context, f Finding) error

AddFinding adds a key discovery to preserve.

Description: 

Adds a finding to the pinned block. Findings are key discoveries
that should be preserved across context truncation.
Truncates Summary to MaxFindingSummaryLen and Detail to MaxFindingDetailLen.

Inputs: 

ctx - Context for tracing.
f - The finding to add.

Outputs: 

error - ErrFindingsLimitReached if at capacity.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) Clear 

func (p *PinnedInstructions) Clear()

Clear resets the pinned instructions to empty state.

Description: 

Clears all content including the original query.
Use this when starting a completely new session.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) Compress 

func (p *PinnedInstructions) Compress(targetTokens int) int

Compress aggressively reduces token usage by summarizing findings.

Description: 

When the pinned block exceeds its budget, Compress() actively reduces
content size by:
  1. Removing finding details (keeping only summaries)
  2. Grouping similar findings into aggregated bullets
  3. Shortening constraint text

This addresses the "Pinned Budget Context Squeeze" problem where an
ever-growing pinned block squeezes out the code budget:

Before Compress:
  - Finding 1: [long summary] - [long detail]
  - Finding 2: [long summary] - [long detail]
  ...10 findings...

After Compress:
  - Found 10 issues: [brief aggregated summary]

Unlike renderTruncatedLocked() which just removes items, Compress()
preserves information through summarization.

Inputs: 

targetTokens - Target token count to achieve. If 0, uses maxTokenBudget/2.

Outputs: 

int - Tokens freed (difference between old and new token count).

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) CompressToFit 

func (p *PinnedInstructions) CompressToFit(totalWindow, traceTokens int) int

CompressToFit reduces the pinned block to ensure a minimum code budget.

Description: 

Given a total token window and the current trace size, calculates how
much space is available for code. If the pinned block is consuming
too much, it compresses to ensure MinCodeBudget tokens remain.

This is the primary method for enforcing the context budget hierarchy:
  1. MinCodeBudget is guaranteed (code visibility)
  2. Pinned block is compressed if needed
  3. Trace is truncated last (handled by TraceRecorder)

Inputs: 

totalWindow - Total tokens available for the LLM context.
traceTokens - Tokens currently used by the trace/history.

Outputs: 

int - Tokens freed from the pinned block.

Example: 

// Before a session turn, ensure code budget is available
traceTokens := trace.TokenCount()
pinnedTokens := pinned.TokenCount()
codeAvailable := totalWindow - traceTokens - pinnedTokens

if codeAvailable < MinCodeBudget {
    freed := pinned.CompressToFit(totalWindow, traceTokens)
    // If still not enough, truncate trace
}

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) GetConstraints 

func (p *PinnedInstructions) GetConstraints() []string

GetConstraints returns a copy of the current constraints.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) GetFindings 

func (p *PinnedInstructions) GetFindings() []Finding

GetFindings returns a copy of the current findings.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) GetPlan 

func (p *PinnedInstructions) GetPlan() []PlanStep

GetPlan returns a copy of the current plan steps.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) IsEmpty 

func (p *PinnedInstructions) IsEmpty() bool

IsEmpty returns true if the pinned block has no content.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) MarshalJSON 

func (p *PinnedInstructions) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for persistence.

func (*PinnedInstructions) OriginalQuery 

func (p *PinnedInstructions) OriginalQuery() string

OriginalQuery returns the stored original query.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) Render 

func (p *PinnedInstructions) Render() string

Render produces the pinned block text for context injection.

Description: 

Generates a markdown-formatted pinned block containing the original
query, current plan, key findings, and constraints.
Uses cache if valid, otherwise regenerates.
Applies graceful truncation if over budget (removes oldest findings first).

Outputs: 

string - The rendered pinned block markdown.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) SetOriginalQuery 

func (p *PinnedInstructions) SetOriginalQuery(query string) error

SetOriginalQuery stores the user's query (immutable after set).

Description: 

Sets the original query that the agent is working on.
This is immutable after the first call - subsequent calls return ErrQueryAlreadySet.
The query is truncated to MaxOriginalQueryLen if too long.

Inputs: 

query - The user's original query.

Outputs: 

error - ErrQueryAlreadySet if already set, ErrEmptyQuery if empty.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) SetPlan 

func (p *PinnedInstructions) SetPlan(steps []PlanStep) error

SetPlan sets the current plan steps.

Description: 

Sets the plan steps. Replaces any existing plan.
Returns ErrPlanStepsLimitReached if len(steps) > MaxPlanSteps.

Inputs: 

steps - The plan steps to set.

Outputs: 

error - ErrPlanStepsLimitReached if too many steps.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) Stats 

func (p *PinnedInstructions) Stats() PinnedStats

Stats returns statistics about the pinned block.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) TokenCount 

func (p *PinnedInstructions) TokenCount() int

TokenCount returns estimated token count of pinned block.

Description: 

Returns the estimated number of tokens in the rendered pinned block.
Uses cache if valid.

Outputs: 

int - The estimated token count.

Thread Safety: Safe for concurrent use.

func (*PinnedInstructions) UnmarshalJSON 

func (p *PinnedInstructions) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for persistence.

func (*PinnedInstructions) UpdateStepStatus 

func (p *PinnedInstructions) UpdateStepStatus(position int, status StepStatus) error

UpdateStepStatus marks a step as complete/in-progress by position.

Description: 

Updates the status of a plan step at the given position (0-indexed).
Automatically sets StartedAt when moving to InProgress.
Automatically sets CompletedAt when moving to Done or Skipped.

Inputs: 

position - The 0-indexed position of the step.
status - The new status to set.

Outputs: 

error - ErrInvalidStepIndex if position is out of range.

Thread Safety: Safe for concurrent use.

type PinnedOption 

type PinnedOption func(*PinnedInstructions)

PinnedOption is a functional option for configuring PinnedInstructions.

func WithTokenBudget 

func WithTokenBudget(budget int) PinnedOption

WithTokenBudget sets the maximum token budget.

Description: 

Sets the maximum number of tokens the pinned block can use.
If budget < MinPinnedBudget, MinPinnedBudget is used instead.

Inputs: 

budget - The token budget (minimum MinPinnedBudget).

func WithTokenCounter 

func WithTokenCounter(tc TokenCounter) PinnedOption

WithTokenCounter sets a custom token counter.

Description: 

Sets a custom implementation for counting tokens.
Use this to integrate with tiktoken or model-specific counters.

Inputs: 

tc - The token counter implementation. If nil, default is used.

type PinnedStats 

type PinnedStats struct {
	// QueryTokens is the estimated tokens for the original query.
	QueryTokens int `json:"query_tokens"`

	// PlanTokens is the estimated tokens for the plan.
	PlanTokens int `json:"plan_tokens"`

	// FindingsTokens is the estimated tokens for findings.
	FindingsTokens int `json:"findings_tokens"`

	// ConstraintTokens is the estimated tokens for constraints.
	ConstraintTokens int `json:"constraint_tokens"`

	// TotalTokens is the total estimated tokens.
	TotalTokens int `json:"total_tokens"`

	// FindingsCount is the number of findings.
	FindingsCount int `json:"findings_count"`

	// ConstraintsCount is the number of constraints.
	ConstraintsCount int `json:"constraints_count"`

	// PlanStepsCount is the number of plan steps.
	PlanStepsCount int `json:"plan_steps_count"`

	// CacheHit indicates if the last render was from cache.
	CacheHit bool `json:"cache_hit"`

	// TokenBudget is the configured token budget.
	TokenBudget int `json:"token_budget"`
}

PinnedStats contains metrics about the pinned block.

type PlanStep 

type PlanStep struct {
	// Description is the human-readable description of the step.
	Description string `json:"description"`

	// Status is the current state of the step.
	Status StepStatus `json:"status"`

	// StartedAt is when the step began execution (Unix milliseconds UTC).
	StartedAt int64 `json:"started_at,omitempty"`

	// CompletedAt is when the step finished (done or skipped) (Unix milliseconds UTC).
	CompletedAt int64 `json:"completed_at,omitempty"`
}

PlanStep represents one step in the agent's plan. Index is determined by position in the slice, not stored explicitly.

type ProgressCallback 

type ProgressCallback func(completed, total int, lastResult *WorkResult)

ProgressCallback is called to report batch progress.

type ProjectInfo 

type ProjectInfo struct {
	Root     string   `json:"root"`
	Language string   `json:"language"`
	Packages []string `json:"packages"`
}

ProjectInfo provides project information for summary generation.

type PythonHierarchy 

type PythonHierarchy struct{}

PythonHierarchy implements LanguageHierarchy for Python projects.

Python hierarchy structure: - Level 0: Project (directory containing pyproject.toml or setup.py) - Level 1: Package (directory containing __init__.py) - Level 2: Module (.py file) - Level 3: Symbol (function, class, method, etc.)

Entity ID format: - Project: "" (empty, represents root) - Package: "myapp/auth" or "src/handlers" - Module: "myapp/auth/validator.py" - Symbol: "myapp/auth/validator.py#validate_token"

Thread Safety: Safe for concurrent use (stateless).

func (*PythonHierarchy) BuildEntityID 

func (h *PythonHierarchy) BuildEntityID(c EntityComponents) string

BuildEntityID constructs an entity ID from components.

func (*PythonHierarchy) ChildrenOf 

func (h *PythonHierarchy) ChildrenOf(entityID string) ([]string, error)

ChildrenOf returns possible child entity IDs. Note: Returns empty since we can't know children without filesystem access.

func (*PythonHierarchy) EntityLevel 

func (h *PythonHierarchy) EntityLevel(entityID string) int

EntityLevel determines the hierarchy level from an entity ID.

func (*PythonHierarchy) IsPackageInit 

func (h *PythonHierarchy) IsPackageInit(filePath string) bool

IsPackageInit returns true if the file is __init__.py.

func (*PythonHierarchy) IsPrivateModule 

func (h *PythonHierarchy) IsPrivateModule(modulePath string) bool

IsPrivateModule returns true if the module is private (starts with _).

func (*PythonHierarchy) IsTestFile 

func (h *PythonHierarchy) IsTestFile(filePath string) bool

IsTestFile returns true if the file is a Python test file.

func (*PythonHierarchy) Language 

func (h *PythonHierarchy) Language() string

Language returns "python".

func (*PythonHierarchy) LevelCount 

func (h *PythonHierarchy) LevelCount() int

LevelCount returns 4 (project, package, module, symbol).

func (*PythonHierarchy) LevelName 

func (h *PythonHierarchy) LevelName(level int) string

LevelName returns the name for each level.

func (*PythonHierarchy) ModuleNameFromFile 

func (h *PythonHierarchy) ModuleNameFromFile(filePath string) string

ModuleNameFromFile returns the Python module name from a file path. e.g., "myapp/auth/validator.py" → "myapp.auth.validator"

func (*PythonHierarchy) PackageFromFile 

func (h *PythonHierarchy) PackageFromFile(filePath string) string

PackageFromFile extracts the package path from a file path.

func (*PythonHierarchy) ParentOf 

func (h *PythonHierarchy) ParentOf(entityID string) (string, error)

ParentOf returns the parent entity ID.

func (*PythonHierarchy) ParseEntityID 

func (h *PythonHierarchy) ParseEntityID(entityID string) EntityComponents

ParseEntityID extracts components from a Python entity ID.

func (*PythonHierarchy) RootMarkers 

func (h *PythonHierarchy) RootMarkers() []string

RootMarkers returns Python project root markers.

type QueryClassification 

type QueryClassification struct {
	// Type is the classified query type.
	Type QueryType

	// Confidence is the classification confidence (0.0-1.0).
	Confidence float64

	// Signals lists which patterns matched.
	Signals []string

	// ExtractedTerms contains any specific terms extracted
	// (e.g., symbol names, paths).
	ExtractedTerms []string
}

QueryClassification contains the result of query classification.

func ClassifyQuery 

func ClassifyQuery(query string) *QueryClassification

ClassifyQuery is a convenience function to classify a query.

type QueryClassifier 

type QueryClassifier interface {
	// Classify analyzes a query and returns its classification.
	//
	// Inputs:
	//   - query: The user query string.
	//
	// Outputs:
	//   - *QueryClassification: The classification result.
	Classify(query string) *QueryClassification
}

QueryClassifier classifies queries to determine retrieval strategy.

Thread Safety: Implementations must be safe for concurrent use.

type QueryType 

type QueryType int

QueryType represents the classification of a user query. 

const (
	// QueryTypeOverview indicates a high-level overview query.
	// Example: "What does this codebase do?"
	// Strategy: Use Level 0-1 summaries only, skip drill-down.
	QueryTypeOverview QueryType = iota

	// QueryTypeConceptual indicates a conceptual/architectural query.
	// Example: "How does authentication work?"
	// Strategy: Full hierarchical retrieval with drill-down.
	QueryTypeConceptual

	// QueryTypeSpecific indicates a specific symbol lookup query.
	// Example: "Where is ValidateToken defined?"
	// Strategy: Direct symbol lookup, skip hierarchy.
	QueryTypeSpecific

	// QueryTypeLocational indicates a path-based lookup query.
	// Example: "Show me the auth package"
	// Strategy: Direct path lookup, expand children.
	QueryTypeLocational
)

func (QueryType) String 

func (t QueryType) String() string

String returns the human-readable name for the query type.

type RepairResult 

type RepairResult struct {
	// OrphansRemoved is the number of orphaned entries removed.
	OrphansRemoved int `json:"orphans_removed"`

	// StaleInvalidated is the number of stale entries invalidated.
	StaleInvalidated int `json:"stale_invalidated"`

	// LevelsFixed is the number of level mismatches corrected.
	LevelsFixed int `json:"levels_fixed"`

	// ChildrenRegenerated is the number of missing children regenerated.
	// Note: This requires a summarizer, which is not available here.
	ChildrenRegenerated int `json:"children_regenerated"`
}

RepairResult contains the summary of repairs made.

func (*RepairResult) TotalRepairs 

func (r *RepairResult) TotalRepairs() int

TotalRepairs returns the total number of repairs made.

type RetrievalResult 

type RetrievalResult struct {
	// Summaries are the relevant summaries found.
	Summaries []*Summary `json:"summaries"`

	// Path is the drill-down path taken.
	// Example: ["project", "pkg/auth", "pkg/auth/validator.go"]
	Path []string `json:"path"`

	// QueryType is how the query was classified.
	QueryType QueryType `json:"query_type"`

	// Classification is the full classification result.
	Classification *QueryClassification `json:"classification,omitempty"`

	// PartialMatch indicates degraded results (some levels failed).
	PartialMatch bool `json:"partial_match"`

	// Warnings contains any issues encountered during retrieval.
	Warnings []string `json:"warnings,omitempty"`

	// TokensUsed is the estimated context tokens consumed.
	TokensUsed int `json:"tokens_used"`

	// LevelsSearched tracks which levels were searched.
	LevelsSearched []int `json:"levels_searched"`
}

RetrievalResult contains the results of hierarchical retrieval.

type RetrieverConfig 

type RetrieverConfig struct {
	// MaxPackages is the maximum packages to consider at Level 1.
	MaxPackages int `json:"max_packages"`

	// MaxFilesPerPkg is the maximum files per package at Level 2.
	MaxFilesPerPkg int `json:"max_files_per_pkg"`

	// MaxSymbolsPerFile is the maximum symbols per file at Level 3.
	MaxSymbolsPerFile int `json:"max_symbols_per_file"`

	// MinRelevanceScore is the minimum score to include a result.
	MinRelevanceScore float64 `json:"min_relevance_score"`
}

RetrieverConfig configures the hierarchical retriever.

func DefaultRetrieverConfig 

func DefaultRetrieverConfig() RetrieverConfig

DefaultRetrieverConfig returns sensible defaults for retrieval.

type RetryConfig 

type RetryConfig struct {
	// MaxAttempts is the maximum number of attempts (including initial).
	// Default: 3
	MaxAttempts int

	// InitialBackoff is the initial wait duration before first retry.
	// Default: 1s
	InitialBackoff time.Duration

	// MaxBackoff is the maximum wait duration between retries.
	// Default: 30s
	MaxBackoff time.Duration

	// BackoffFactor is the multiplier for exponential backoff.
	// Default: 2.0
	BackoffFactor float64

	// JitterFactor is the maximum jitter as a fraction of backoff (0-1).
	// Adds randomness to prevent thundering herd. Default: 0.2
	JitterFactor float64
}

RetryConfig configures retry behavior with exponential backoff.

func DefaultRetryConfig 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns sensible defaults for retry behavior.

func (RetryConfig) Validate 

func (c RetryConfig) Validate() error

Validate checks if the retry configuration is valid.

type RetryResult 

type RetryResult struct {
	// Attempts is the number of attempts made.
	Attempts int

	// TotalDuration is the total time spent including waits.
	TotalDuration time.Duration

	// LastError is the error from the last attempt (nil if successful).
	LastError error
}

RetryResult contains the outcome of a retry operation.

func Retry 

func Retry(ctx context.Context, config RetryConfig, fn RetryableFunc) (RetryResult, error)

Retry executes the given function with exponential backoff retry.

Inputs:

  • ctx: Context for cancellation. Must not be nil.
  • config: Retry configuration.
  • fn: The function to execute and potentially retry.

Outputs:

  • RetryResult: Statistics about the retry operation.
  • error: The last error if all attempts failed, nil on success.

The function is retried only if it returns a retryable error (as determined by IsRetryable). Non-retryable errors cause immediate return without further attempts.

Example: 

result, err := Retry(ctx, DefaultRetryConfig(), func(ctx context.Context, attempt int) error {
    return client.Complete(ctx, prompt)
})

func RetryWithCircuitBreaker 

func RetryWithCircuitBreaker(
	ctx context.Context,
	cb *CircuitBreaker,
	config RetryConfig,
	fn RetryableFunc,
) (RetryResult, error)

RetryWithCircuitBreaker combines retry logic with circuit breaker protection.

Inputs:

  • ctx: Context for cancellation. Must not be nil.
  • cb: Circuit breaker to check/update.
  • config: Retry configuration.
  • fn: The function to execute.

Outputs:

  • RetryResult: Statistics about the operation.
  • error: The error if failed, nil on success.

If the circuit breaker is open, returns ErrCircuitOpen immediately. Records success/failure to the circuit breaker after each attempt.

type RetryableFunc 

type RetryableFunc func(ctx context.Context, attempt int) error

RetryableFunc is a function that can be retried. It should return nil on success, or an error. Use IsRetryable to determine if the error should trigger a retry.

type ScoredSymbol 

type ScoredSymbol struct {
	// Symbol is the underlying symbol.
	Symbol *ast.Symbol

	// Score is the relevance score (0.0-1.0, higher is better).
	Score float64

	// Depth is the graph distance from entry points.
	Depth int
}

ScoredSymbol represents a symbol with its relevance score.

type Semaphore 

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

Semaphore implements a counting semaphore for bounded concurrency.

Thread Safety: Safe for concurrent use.

func NewSemaphore 

func NewSemaphore(capacity int) *Semaphore

NewSemaphore creates a new semaphore with the given capacity.

Inputs:

  • capacity: Maximum concurrent acquisitions. Must be > 0.

Outputs:

  • *Semaphore: A new semaphore.

func (*Semaphore) Acquire 

func (s *Semaphore) Acquire(ctx context.Context) error

Acquire acquires a slot, blocking until one is available.

Inputs:

  • ctx: Context for cancellation.

Outputs:

  • error: Non-nil if context was cancelled.

func (*Semaphore) Available 

func (s *Semaphore) Available() int

Available returns the number of available slots.

func (*Semaphore) Release 

func (s *Semaphore) Release()

Release releases a slot back to the semaphore. Must be called after Acquire/TryAcquire succeeds.

func (*Semaphore) TryAcquire 

func (s *Semaphore) TryAcquire() bool

TryAcquire attempts to acquire a slot without blocking.

Outputs:

  • bool: True if acquired, false if no slots available.

type SourceInfo 

type SourceInfo struct {
	// Symbols is a list of symbol names in the source.
	Symbols []string

	// EntityIDs is a list of valid entity IDs that can be children.
	EntityIDs []string

	// ParentID is the expected parent for this entity.
	ParentID string

	// Content is the raw source content (for hash verification).
	Content string
}

SourceInfo provides information about the source code being summarized.

func (*SourceInfo) ContainsSymbol 

func (s *SourceInfo) ContainsSymbol(name string) bool

ContainsSymbol checks if a symbol exists in the source.

func (*SourceInfo) EntityExists 

func (s *SourceInfo) EntityExists(id string) bool

EntityExists checks if an entity ID is valid.

type StaleEntry 

type StaleEntry struct {
	ID          string `json:"id"`
	StoredHash  string `json:"stored_hash"`
	CurrentHash string `json:"current_hash"`
}

StaleEntry represents a summary with an outdated hash.

type StepStatus 

type StepStatus string

StepStatus represents the state of a plan step. 

const (
	// StepPending indicates the step has not started.
	StepPending StepStatus = "pending"

	// StepInProgress indicates the step is currently being executed.
	StepInProgress StepStatus = "in_progress"

	// StepDone indicates the step has completed successfully.
	StepDone StepStatus = "done"

	// StepSkipped indicates the step was skipped.
	StepSkipped StepStatus = "skipped"
)

func (StepStatus) IsValid 

func (s StepStatus) IsValid() bool

IsValid returns true if the status is a valid StepStatus.

func (StepStatus) String 

func (s StepStatus) String() string

String returns the string representation of StepStatus.

func (StepStatus) Symbol 

func (s StepStatus) Symbol() string

Symbol returns the display symbol for the status.

type Summarizer 

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

Summarizer generates hierarchical summaries using an LLM.

Thread Safety: Safe for concurrent use.

func NewSummarizer 

func NewSummarizer(
	llm LLMClient,
	cache *SummaryCache,
	hierarchy LanguageHierarchy,
	config SummarizerConfig,
) *Summarizer

NewSummarizer creates a new summarizer.

Inputs:

  • llm: The LLM client for generating summaries.
  • cache: The summary cache for storing results.
  • hierarchy: The language hierarchy.
  • config: Configuration options.

Outputs:

  • *Summarizer: A new summarizer instance.

func (*Summarizer) EstimateCost 

func (s *Summarizer) EstimateCost(ctx context.Context, projectCount, packageCount, fileCount int) *CostEstimate

EstimateCost estimates the cost for generating summaries.

Inputs:

  • ctx: Context for cancellation.
  • projectCount: Number of projects.
  • packageCount: Number of packages.
  • fileCount: Number of files.

Outputs:

  • *CostEstimate: The cost estimate.

func (*Summarizer) GenerateAllPackageSummaries 

func (s *Summarizer) GenerateAllPackageSummaries(
	ctx context.Context,
	packages []*PackageInfo,
	progress ProgressCallback,
) (*GenerationResult, error)

GenerateAllPackageSummaries generates summaries for all packages.

Inputs:

  • ctx: Context for cancellation.
  • packages: Package information for all packages.
  • progress: Optional callback for progress updates.

Outputs:

  • *GenerationResult: Results of the batch operation.
  • error: Non-nil if completely failed.

func (*Summarizer) GenerateFileSummary 

func (s *Summarizer) GenerateFileSummary(ctx context.Context, info *FileInfo) (*Summary, error)

GenerateFileSummary generates a summary for a file.

Inputs:

  • ctx: Context for cancellation.
  • info: File information.

Outputs:

  • *Summary: The generated summary.
  • error: Non-nil if generation fails and no fallback available.

func (*Summarizer) GeneratePackageSummary 

func (s *Summarizer) GeneratePackageSummary(ctx context.Context, info *PackageInfo) (*Summary, error)

GeneratePackageSummary generates a summary for a package.

Inputs:

  • ctx: Context for cancellation.
  • info: Package information.

Outputs:

  • *Summary: The generated summary.
  • error: Non-nil if generation fails and no fallback available.

func (*Summarizer) GenerateProjectSummary 

func (s *Summarizer) GenerateProjectSummary(ctx context.Context, info *ProjectInfo) (*Summary, error)

GenerateProjectSummary generates a summary for the entire project.

Inputs:

  • ctx: Context for cancellation.
  • info: Project information.

Outputs:

  • *Summary: The generated summary.
  • error: Non-nil if generation fails.

type SummarizerConfig 

type SummarizerConfig struct {
	// RetryConfig configures retry behavior for LLM calls.
	RetryConfig RetryConfig `json:"retry_config"`

	// ConcurrencyConfig configures parallel processing.
	ConcurrencyConfig ConcurrencyConfig `json:"concurrency_config"`

	// CostLimits configures cost thresholds.
	CostLimits CostLimits `json:"cost_limits"`

	// ValidateOutputs enables LLM output validation.
	ValidateOutputs bool `json:"validate_outputs"`

	// FallbackToPartial enables partial summary fallback on LLM failure.
	FallbackToPartial bool `json:"fallback_to_partial"`
}

SummarizerConfig configures the summarizer behavior.

func DefaultSummarizerConfig 

func DefaultSummarizerConfig() SummarizerConfig

DefaultSummarizerConfig returns sensible defaults.

type Summary 

type Summary struct {
	// ID is the unique identifier (entity path).
	// Examples: "pkg/auth", "pkg/auth/validator.go", "pkg/auth/validator.go#ValidateToken"
	ID string `json:"id"`

	// Level is the hierarchy level (0=project, 1=package, 2=file, 3=function).
	Level int `json:"level"`

	// Content is the natural language summary.
	Content string `json:"content"`

	// Keywords are key terms for search matching.
	Keywords []string `json:"keywords"`

	// Children are IDs of child summaries.
	Children []string `json:"children"`

	// ParentID is the parent summary ID (empty for project root).
	ParentID string `json:"parent_id"`

	// CreatedAt is when this summary was created (Unix milliseconds UTC).
	CreatedAt int64 `json:"created_at"`

	// UpdatedAt is when this summary was last updated (Unix milliseconds UTC).
	UpdatedAt int64 `json:"updated_at"`

	// Hash is a hash of the source content for invalidation.
	Hash string `json:"hash"`

	// Partial indicates this is a degraded summary (generated without LLM).
	Partial bool `json:"partial"`

	// Language is the source code language.
	Language string `json:"language"`

	// TokensUsed is the LLM tokens consumed to generate this summary.
	TokensUsed int `json:"tokens_used"`

	// Version is for optimistic concurrency control.
	Version int64 `json:"version"`
}

Summary represents a hierarchical summary of code.

func (*Summary) HierarchyLevel 

func (s *Summary) HierarchyLevel() HierarchyLevel

HierarchyLevel returns the hierarchy level as the enum type.

func (*Summary) IsFresh 

func (s *Summary) IsFresh(maxAge time.Duration) bool

IsFresh returns true if the summary was created/updated recently.

func (*Summary) IsStale 

func (s *Summary) IsStale(currentHash string) bool

IsStale returns true if the hash doesn't match the provided hash.

type SummaryBatch 

type SummaryBatch struct {
	// Version is the batch version for idempotency.
	Version int64 `json:"version"`

	// Summaries are the summaries to upsert.
	Summaries []Summary `json:"summaries"`

	// DeleteIDs are summary IDs to delete.
	DeleteIDs []string `json:"delete_ids"`

	// Checksum is for integrity verification.
	Checksum string `json:"checksum"`
}

SummaryBatch represents a batch of summaries for atomic updates.

func (*SummaryBatch) ComputeChecksum 

func (b *SummaryBatch) ComputeChecksum() string

ComputeChecksum calculates the batch checksum.

func (*SummaryBatch) SetChecksum 

func (b *SummaryBatch) SetChecksum()

SetChecksum computes and sets the checksum.

func (*SummaryBatch) Validate 

func (b *SummaryBatch) Validate() error

Validate checks the batch integrity.

type SummaryCache 

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

SummaryCache provides in-memory caching for summaries.

This implementation uses an in-memory map. For production, this should be backed by Weaviate for vector similarity search.

Thread Safety: Safe for concurrent use.

func NewSummaryCache 

func NewSummaryCache(config CacheConfig) *SummaryCache

NewSummaryCache creates a new summary cache.

Inputs:

  • config: Cache configuration.

Outputs:

  • *SummaryCache: A new cache instance.

func (*SummaryCache) ApplyBatch 

func (c *SummaryCache) ApplyBatch(batch *SummaryBatch) error

ApplyBatch applies a batch of changes atomically.

Inputs:

  • batch: The batch of changes to apply.

Outputs:

  • error: Non-nil if validation fails.

This is all-or-nothing: either all changes apply or none do.

func (*SummaryCache) Clear 

func (c *SummaryCache) Clear()

Clear removes all entries from the cache.

func (*SummaryCache) Count 

func (c *SummaryCache) Count() int

Count returns the number of cached entries.

func (*SummaryCache) Delete 

func (c *SummaryCache) Delete(id string)

Delete removes a summary from the cache.

Inputs:

  • id: The summary ID to delete.

func (*SummaryCache) Get 

func (c *SummaryCache) Get(id string) (*Summary, bool)

Get retrieves a fresh summary from the cache.

Inputs:

  • id: The summary ID.

Outputs:

  • *Summary: The summary if found and fresh.
  • bool: True if found.

Returns false if the summary is not found or is stale.

func (*SummaryCache) GetByLevel 

func (c *SummaryCache) GetByLevel(level int) []*Summary

GetByLevel returns all summaries at a specific hierarchy level.

Inputs:

  • level: The hierarchy level to filter by.

Outputs:

  • []*Summary: Summaries at this level.

func (*SummaryCache) GetChildren 

func (c *SummaryCache) GetChildren(parentID string) []*Summary

GetChildren returns child summaries for a parent.

Inputs:

  • parentID: The parent summary ID.

Outputs:

  • []*Summary: Child summaries.

func (*SummaryCache) GetStale 

func (c *SummaryCache) GetStale(id string) (*Summary, bool, bool)

GetStale retrieves a summary, allowing stale entries.

Inputs:

  • id: The summary ID.

Outputs:

  • *Summary: The summary if found (even if stale).
  • bool: True if found.
  • bool: True if the entry is stale.

Use this for graceful degradation when fresh data is unavailable.

func (*SummaryCache) Has 

func (c *SummaryCache) Has(id string) bool

Has returns true if a summary exists (fresh or stale).

func (*SummaryCache) Invalidate 

func (c *SummaryCache) Invalidate(id string) error

Invalidate marks a summary as stale.

Inputs:

  • id: The summary ID to invalidate.

Outputs:

  • error: Always nil (for interface compatibility).

func (*SummaryCache) InvalidateIfStale 

func (c *SummaryCache) InvalidateIfStale(id, currentHash string) bool

InvalidateIfStale invalidates a summary if its hash doesn't match.

Inputs:

  • id: The summary ID.
  • currentHash: The current content hash.

Outputs:

  • bool: True if the summary was invalidated (or didn't exist).

func (*SummaryCache) Set 

func (c *SummaryCache) Set(summary *Summary) error

Set stores a summary in the cache.

Inputs:

  • summary: The summary to cache.

Outputs:

  • error: Non-nil if storage fails.

func (*SummaryCache) SetIfUnchanged 

func (c *SummaryCache) SetIfUnchanged(summary *Summary, expectedVersion int64) (bool, error)

SetIfUnchanged stores a summary only if the version matches.

Inputs:

  • summary: The summary to cache.
  • expectedVersion: The expected current version.

Outputs:

  • bool: True if the update succeeded.
  • error: Non-nil if there's a version conflict.

This implements optimistic concurrency control.

func (*SummaryCache) Stats 

func (c *SummaryCache) Stats() CacheStats

Stats returns cache statistics.

type SummaryUpdater 

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

SummaryUpdater handles incremental summary updates when code changes.

Thread Safety: Safe for concurrent use.

func NewSummaryUpdater 

func NewSummaryUpdater(
	summarizer *Summarizer,
	cache *SummaryCache,
	hierarchy LanguageHierarchy,
) *SummaryUpdater

NewSummaryUpdater creates a new updater.

Inputs:

  • summarizer: The summarizer for generating new summaries.
  • cache: The summary cache.
  • hierarchy: The language hierarchy.

Outputs:

  • *SummaryUpdater: A new updater instance.

func (*SummaryUpdater) RefreshStale 

func (u *SummaryUpdater) RefreshStale(
	ctx context.Context,
	hashProvider func(entityID string) (string, error),
) (*UpdateResult, error)

RefreshStale regenerates all stale summaries.

Inputs:

  • ctx: Context for cancellation.
  • hashProvider: Function to get current hash for an entity.

Outputs:

  • *UpdateResult: Summary of updates made.
  • error: Non-nil if refresh fails.

func (*SummaryUpdater) UpdateChangedSummaries 

func (u *SummaryUpdater) UpdateChangedSummaries(ctx context.Context, changes *ChangeSet) (*UpdateResult, error)

UpdateChangedSummaries updates summaries for changed files.

This method: 1. Deletes summaries for removed files 2. Regenerates summaries for modified files 3. Generates summaries for new files 4. Propagates changes up to package and project summaries

Inputs:

  • ctx: Context for cancellation.
  • changes: The set of changes to process.

Outputs:

  • *UpdateResult: Summary of updates made.
  • error: Non-nil if updates completely failed.

func (*SummaryUpdater) ValidateAndRepair 

func (u *SummaryUpdater) ValidateAndRepair(ctx context.Context) (*IntegrityReport, *RepairResult, error)

ValidateAndRepair validates cache integrity and repairs issues.

Inputs:

  • ctx: Context for cancellation.

Outputs:

  • *IntegrityReport: The validation report.
  • *RepairResult: Results of repairs made.
  • error: Non-nil if validation/repair fails.

func (*SummaryUpdater) WarmCache 

func (u *SummaryUpdater) WarmCache(
	ctx context.Context,
	packages []*PackageInfo,
	progress ProgressCallback,
) (*GenerationResult, error)

WarmCache pre-generates summaries for important entities.

Inputs:

  • ctx: Context for cancellation.
  • packages: Package information to pre-warm.
  • progress: Optional progress callback.

Outputs:

  • *GenerationResult: Results of the warm operation.

type SummaryValidator 

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

SummaryValidator validates LLM-generated summaries before caching.

Thread Safety: Safe for concurrent use (stateless).

func NewSummaryValidator 

func NewSummaryValidator(hierarchy LanguageHierarchy) *SummaryValidator

NewSummaryValidator creates a new validator.

Inputs:

  • hierarchy: The language hierarchy for validation.

Outputs:

  • *SummaryValidator: A new validator instance.

func (*SummaryValidator) Validate 

func (v *SummaryValidator) Validate(summary *Summary, source *SourceInfo) *ValidationResult

Validate validates a summary against source information.

Inputs:

  • summary: The summary to validate.
  • source: Information about the source being summarized.

Outputs:

  • *ValidationResult: The validation result with any errors.

func (*SummaryValidator) ValidateMinimal 

func (v *SummaryValidator) ValidateMinimal(summary *Summary) error

ValidateMinimal performs minimal validation (for partial summaries).

Inputs:

  • summary: The summary to validate.

Outputs:

  • error: Non-nil if summary is completely invalid.

This is more lenient than full validation, used for degraded mode.

type SymbolInfo 

type SymbolInfo struct {
	Name      string `json:"name"`
	Kind      string `json:"kind"` // function, type, method, etc.
	Signature string `json:"signature,omitempty"`
	DocString string `json:"doc_string,omitempty"`
}

SymbolInfo provides symbol information for summary generation.

type TokenCounter 

type TokenCounter interface {
	// Count returns the number of tokens in the text.
	Count(text string) int
}

TokenCounter is the interface for counting tokens.

type UpdateResult 

type UpdateResult struct {
	// FilesUpdated is the number of file summaries updated.
	FilesUpdated int `json:"files_updated"`

	// FilesDeleted is the number of file summaries deleted.
	FilesDeleted int `json:"files_deleted"`

	// PackagesUpdated is the number of package summaries updated.
	PackagesUpdated int `json:"packages_updated"`

	// ProjectUpdated indicates if the project summary was updated.
	ProjectUpdated bool `json:"project_updated"`

	// Duration is how long the update took.
	Duration time.Duration `json:"duration"`

	// Errors contains any errors encountered.
	Errors []string `json:"errors,omitempty"`
}

UpdateResult contains results from updating summaries.

type ValidationError 

type ValidationError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
	Value   any    `json:"value,omitempty"`
}

ValidationError contains details about a validation failure.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Error implements the error interface.

type ValidationResult 

type ValidationResult struct {
	Valid  bool              `json:"valid"`
	Errors []ValidationError `json:"errors,omitempty"`
}

ValidationResult contains the results of summary validation.

func (*ValidationResult) AllErrors 

func (r *ValidationResult) AllErrors() string

AllErrors returns all error messages joined.

func (*ValidationResult) Error 

func (r *ValidationResult) Error() string

Error returns the first error message, or empty string if valid.

type WorkItem 

type WorkItem struct {
	// ID is a unique identifier for this work item.
	ID string

	// Work is the function to execute.
	// It receives the context and should respect cancellation.
	Work func(ctx context.Context) error
}

WorkItem represents a unit of work for the pool.

type WorkResult 

type WorkResult struct {
	// ID is the work item ID.
	ID string

	// Error is non-nil if the work failed.
	Error error

	// Duration is how long the work took.
	Duration time.Duration
}

WorkResult contains the result of processing a work item.

type WorkerPool 

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

WorkerPool manages a pool of concurrent workers.

Thread Safety: Safe for concurrent use.

func LLMWorkerPool 

func LLMWorkerPool(config ConcurrencyConfig) *WorkerPool

LLMWorkerPool is a worker pool configured for LLM operations.

func NewWorkerPool 

func NewWorkerPool(concurrency int, config ConcurrencyConfig) *WorkerPool

NewWorkerPool creates a new worker pool.

Inputs:

  • concurrency: Maximum concurrent workers.
  • config: Configuration for timeouts.

Outputs:

  • *WorkerPool: A new worker pool.

func WeaviateWorkerPool 

func WeaviateWorkerPool(config ConcurrencyConfig) *WorkerPool

WeaviateWorkerPool is a worker pool configured for Weaviate operations.

func (*WorkerPool) ProcessBatch 

func (p *WorkerPool) ProcessBatch(ctx context.Context, items []WorkItem, progress ProgressCallback) *BatchResult

ProcessBatch processes a batch of work items concurrently.

Inputs:

  • ctx: Context for cancellation.
  • items: Work items to process.
  • progress: Optional callback for progress updates.

Outputs:

  • *BatchResult: Results of the batch operation.

The batch continues processing even if some items fail. Cancelling the context will stop new work but allow in-progress work to complete.

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.