rlm

type AdaptiveIterationConfig struct {
	// Enabled turns on adaptive iteration (default: false).
	Enabled bool

	// BaseIterations is the base number of iterations before context scaling.
	// Default: 10.
	BaseIterations int

	// MaxIterations caps the total iterations regardless of context size.
	// Default: 50.
	MaxIterations int

	// ContextScaleFactor determines how much context size increases iterations.
	// iterations = BaseIterations + (contextSize / ContextScaleFactor)
	// Default: 100000 (100KB per additional iteration).
	ContextScaleFactor int

	// EnableEarlyTermination allows early exit when model signals confidence.
	// Default: true.
	EnableEarlyTermination bool

	// ConfidenceThreshold is the number of confidence signals needed for early termination.
	// Default: 1.
	ConfidenceThreshold int

	// ConfidenceDetector is a custom function to detect confidence signals in responses.
	// If nil, a default heuristic based on FINAL markers is used.
	// The function returns true if the response indicates high confidence.
	ConfidenceDetector func(response string) bool
}

type AnalyzerConfig struct {
	// SmallContextThreshold is the size below which no chunking is needed.
	SmallContextThreshold int

	// TokenEstimateRatio is the character-to-token ratio estimate.
	TokenEstimateRatio float64
}

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

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

type Chunk struct {
	ID        int       // Unique identifier
	Content   string    // The actual text content
	StartLine int       // Starting line number (1-indexed)
	EndLine   int       // Ending line number (1-indexed)
	Summary   string    // Optional summary of the chunk
	Embedding []float32 // Embedding vector for semantic search
}

type ChunkConfig struct {
	// MaxChunkSize is the maximum number of characters per chunk
	MaxChunkSize int
	// OverlapSize is the number of characters to overlap between chunks
	OverlapSize int
	// ChunkByLines if true, chunks by line count instead of character count
	ChunkByLines bool
	// LinesPerChunk when ChunkByLines is true
	LinesPerChunk int
}

type ChunkStrategy string

type CodeBlock struct {
	Code   string
	Result ExecutionResult
}

type CompletionResult struct {
	Response   string
	Iterations int
	Duration   time.Duration
	Usage      core.TokenUsage
}

type Config struct {
	// OuterInstruction overrides the top-level RLM module instruction.
	// Empty string uses the default outer instruction.
	OuterInstruction string

	// IterationInstruction overrides the iteration module instruction.
	// Empty string uses the compact/full built-in instruction based on config.
	IterationInstruction string

	// MaxIterations is the maximum number of iteration loops (default: 30).
	MaxIterations int

	// MaxTokens is the maximum cumulative token budget across root, sub-LLM,
	// and nested sub-RLM calls for a single completion. Zero disables the limit.
	MaxTokens int

	// Verbose enables verbose logging.
	Verbose bool

	// Timeout is the maximum duration for the entire RLM completion.
	// Zero means no timeout (default).
	Timeout time.Duration

	// TraceDir is the directory for RLM trace logs (JSONL format compatible with rlm-viewer).
	// Empty string disables tracing.
	TraceDir string

	// UseIterationDemos enables few-shot demos for the iteration module.
	// Disabled by default to avoid repeating large static prompt examples on every iteration.
	UseIterationDemos bool

	// CompactIterationInstructions uses a shorter runtime instruction for the
	// iteration module. Enabled by default to reduce repeated prompt overhead.
	CompactIterationInstructions bool

	// HistoryCompression configures incremental history compression.
	// When enabled, older iterations are replayed as checkpoint summaries while
	// recent iterations stay verbatim.
	HistoryCompression *HistoryCompressionConfig

	// ContextPolicy controls how iteration history is replayed into subsequent
	// prompts. "full" replays everything verbatim, "checkpointed" summarizes
	// older entries and keeps recent entries verbatim, and "adaptive" switches
	// between the two based on history size and compression settings.
	ContextPolicy ContextPolicyPreset

	// AdaptiveCheckpointThreshold is the history-entry count where the adaptive
	// context policy switches from full replay to checkpointed replay when no
	// explicit HistoryCompression policy is configured. Values <= 0 use the
	// built-in default.
	AdaptiveCheckpointThreshold int

	// AdaptiveIteration configures adaptive iteration strategy.
	// When enabled, max iterations are dynamically calculated based on context size.
	AdaptiveIteration *AdaptiveIterationConfig

	// SubRLM configures nested sub-RLM behavior.
	// When enabled, allows spawning nested RLM loops that share REPL state.
	SubRLM *SubRLMConfig

	// OutputTruncation configures output truncation settings.
	// Controls max lengths for execution output, variable previews, and history entries.
	OutputTruncation *OutputTruncationConfig

	// ContextInfoPreviewChars controls how many characters of the loaded context are
	// exposed in context_info metadata. Set to 0 to disable raw preview text.
	ContextInfoPreviewChars int

	// MaxFullContextQueryChars limits Query()/QueryBatched() calls that auto-prepend the
	// full loaded context. Zero disables the guardrail.
	MaxFullContextQueryChars int

	// OnProgress is called at the start of each iteration with progress info.
	// Can be used to display progress to users or implement custom termination logic.
	OnProgress func(progress IterationProgress)

	// REPLSetup is called after REPL creation and context loading, but before
	// the iteration loop starts. Use this to inject additional REPL symbols.
	REPLSetup func(repl *YaegiREPL) error
}

type ContextAnalysis struct {
	// Type is the detected primary content type.
	Type ContextType

	// SecondaryTypes are additional types detected in mixed content.
	SecondaryTypes []ContextType

	// Size is the total size in bytes.
	Size int

	// EstimatedTokens is the estimated token count (rough approximation).
	EstimatedTokens int

	// RecommendedStrategy is the suggested chunking strategy.
	RecommendedStrategy ChunkStrategy

	// RecommendedChunkSize is the suggested chunk size in bytes.
	RecommendedChunkSize int

	// Delimiters are natural delimiters found in the content.
	Delimiters []string

	// Structure provides hints about the content structure.
	Structure StructureHints

	// LLMHint is a string hint to prepend to LLM prompts about the context.
	LLMHint string
}

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

type ContextPolicyPreset string

type ContextType string

type EmbeddingFunc func(ctx context.Context, texts []string) ([][]float32, error)

type ExecutionResult struct {
	Stdout   string
	Stderr   string
	Duration time.Duration
}

type FinalAnswer struct {
	Type    FinalAnswerType
	Content string
}

type FinalAnswerType string

type HistoryCompressionConfig struct {
	// Enabled turns on checkpointed replay (default: false).
	Enabled bool

	// VerbatimIterations is the number of recent iterations to keep verbatim.
	// Older iterations will be summarized. Default: 3.
	VerbatimIterations int

	// MaxSummaryTokens is the approximate maximum tokens for summarized history.
	// Default: 500.
	MaxSummaryTokens int
}

type HistoryEntry struct {
	Iteration int       // 1-indexed iteration number
	Timestamp time.Time // When this iteration started
	Action    string    // Action type: explore, query, compute, final, subrlm
	Code      string    // Code that was executed (if any)
	Output    string    // Execution output (truncated)
	Duration  time.Duration
	Success   bool
	Error     string
	SubRLM    *SubRLMEntry // Non-nil if this was a subrlm action
}

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

type IterationProgress struct {
	// CurrentIteration is the current iteration number (1-indexed).
	CurrentIteration int

	// MaxIterations is the computed maximum iterations for this request.
	MaxIterations int

	// ConfidenceSignals counts how many times the model has signaled confidence.
	ConfidenceSignals int

	// HasFinalAttempt indicates the model tried to give a final answer.
	HasFinalAttempt bool

	// ContextSize is the size of the input context in bytes.
	ContextSize int

	// RootPromptTokens is the prompt token count for this iteration's root LLM call,
	// as reported by the provider via LLMResponse.Usage.PromptTokens.
	// This is the per-call value (not cumulative) — divide by context window size
	// to get context_fill_ratio for this iteration.
	RootPromptTokens int
}

type LLMCall struct {
	Prompt           string        `json:"prompt"`
	Response         string        `json:"response"`
	Duration         time.Duration `json:"duration"`
	PromptTokens     int           `json:"prompt_tokens"`
	CompletionTokens int           `json:"completion_tokens"`
}

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

type Option func(*Config)

type OutputFieldSpec struct {
	Type        string // Expected type: "string", "int", "float", "bool", "[]string", "map"
	Required    bool   // Whether the field is required
	Description string // Description of what this field should contain
}

type OutputTruncationConfig struct {
	// Enabled turns on output truncation (default: true).
	Enabled bool

	// MaxOutputLen is the maximum characters in execution output (default: 5000).
	MaxOutputLen int

	// MaxVarPreviewLen is the maximum characters in variable preview (default: 100).
	MaxVarPreviewLen int

	// MaxHistoryEntryLen is the maximum characters per history entry (default: 1000).
	MaxHistoryEntryLen int
}

type QueryResponse struct {
	Response         string
	PromptTokens     int
	CompletionTokens int
}

type REPLEnvironment interface {
	// LoadContext loads the context payload into the REPL environment.
	LoadContext(payload any) error

	// Execute runs Go code in the interpreter and returns the result.
	Execute(ctx context.Context, code string) (*ExecutionResult, error)

	// GetVariable retrieves a variable value from the interpreter.
	GetVariable(name string) (string, error)

	// SetVariable sets a variable in the interpreter.
	SetVariable(name, value string) error

	// Reset clears the interpreter state.
	Reset() error

	// ContextInfo returns metadata about the loaded context.
	ContextInfo() string

	// GetLocals extracts commonly used variables from the interpreter.
	GetLocals() map[string]any

	// GetVariableMetadata returns rich metadata about REPL variables.
	GetVariableMetadata() []REPLVariable

	// HasFinal returns true if FINAL() or FINAL_VAR() has been called.
	// This provides state-verified completion detection (Nightjar Algorithm 1 Gap 1).
	HasFinal() bool

	// Final returns the value passed to FINAL() or FINAL_VAR().
	// Returns empty string if not set.
	Final() string

	// ClearFinal resets the final state.
	ClearFinal()

	// HasSubmit returns true if SUBMIT() has been called with valid output.
	HasSubmit() bool

	// GetSubmitOutput returns the submitted output fields.
	GetSubmitOutput() map[string]any

	// SetSubmitSchema sets the expected output schema for SUBMIT validation.
	SetSubmitSchema(schema map[string]OutputFieldSpec)

	// GetLLMCalls returns the LLM calls made during code execution.
	GetLLMCalls() []LLMCall
}

type REPLVariable struct {
	Name        string // Variable name
	Value       any    // The actual value
	Type        string // Type description (string, int, []string, map, etc.)
	Length      int    // Length/size for strings and collections (-1 if N/A)
	Preview     string // Truncated representation for display
	IsImportant bool   // True for key variables (result, answer, etc.)
}

type RLM struct {
	core.BaseModule
	// contains filtered or unexported fields
}

type RLMTrace struct {
	Input             map[string]any
	Output            map[string]any
	Steps             []RLMTraceStep
	StartedAt         time.Time
	CompletedAt       time.Time
	ProcessingTime    time.Duration
	Iterations        int
	Usage             core.TokenUsage
	RootUsage         core.TokenUsage
	SubUsage          core.TokenUsage
	SubRLMUsage       core.TokenUsage
	RootSnapshots     []RootIterationSnapshot
	SubLLMCallCount   int
	SubRLMCallCount   int
	ConfidenceSignals int
	CompressionCount  int
	TerminationCause  string
	Error             string
	// contains filtered or unexported fields
}

type RLMTraceStep struct {
	Index       int
	Thought     string
	Action      string
	Code        string
	SubQuery    string
	Observation string
	Duration    time.Duration
	Success     bool
	Error       string
}

type RootIterationSnapshot struct {
	Iteration        int `json:"iteration"`         // 1-indexed iteration number
	PromptTokens     int `json:"prompt_tokens"`     // Root LLM prompt tokens for this iteration
	CompletionTokens int `json:"completion_tokens"` // Root LLM completion tokens for this iteration
}

type StructureHints struct {
	// HasHeaders indicates if the content has section headers.
	HasHeaders bool

	// HeaderCount is the number of headers detected.
	HeaderCount int

	// HasCodeBlocks indicates if code blocks are present.
	HasCodeBlocks bool

	// CodeBlockCount is the number of code blocks detected.
	CodeBlockCount int

	// HasLists indicates if lists are present.
	HasLists bool

	// ListCount is the number of lists detected.
	ListCount int

	// HasTables indicates if tables are present.
	HasTables bool

	// NestingDepth is the maximum nesting depth for structured content.
	NestingDepth int

	// LineCount is the total number of lines.
	LineCount int

	// AvgLineLength is the average line length.
	AvgLineLength int
}

type SubLLMClient interface {
	// Query makes a single LLM query.
	Query(ctx context.Context, prompt string) (QueryResponse, error)
	// QueryBatched makes concurrent LLM queries.
	QueryBatched(ctx context.Context, prompts []string) ([]QueryResponse, error)
}

type SubRLMCall struct {
	Query            string        `json:"query"`
	Result           string        `json:"result"`
	Iterations       int           `json:"iterations"`
	Depth            int           `json:"depth"`
	Duration         time.Duration `json:"duration"`
	PromptTokens     int           `json:"prompt_tokens"`
	CompletionTokens int           `json:"completion_tokens"`
}

type SubRLMConfig struct {
	// MaxDepth is the maximum nesting depth for sub-RLM calls (default: 3).
	// A value of 1 means no nesting allowed, 2 means one level of nesting, etc.
	MaxDepth int

	// CurrentDepth tracks the current nesting level (0 = root RLM).
	// This is set internally and should not be configured by users.
	CurrentDepth int

	// MaxIterationsPerSubRLM limits iterations for each sub-RLM call.
	// Default: 10. Use 0 to inherit parent's max iterations.
	MaxIterationsPerSubRLM int

	// MaxDirectSubRLMCalls limits direct child sub-RLM invocations from one RLM
	// node. Zero disables the budget.
	MaxDirectSubRLMCalls int

	// MaxTotalSubRLMCalls limits total sub-RLM invocations across the whole
	// request tree. Zero disables the budget.
	MaxTotalSubRLMCalls int
}

type SubRLMEntry struct {
	Query      string        // The sub-RLM query
	Result     string        // The sub-RLM result
	Iterations int           // How many iterations the sub-RLM took
	Duration   time.Duration // How long the sub-RLM ran
}

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

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