profiles

package
v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Jul 6, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package profiles provides agent-specific initialization profiles.

Index

Constants

This section is empty.

Variables

View Source
var (
	// DefaultProfile is the default agent profile with no restrictions.
	DefaultProfile = &BootstrapProfile{
		Name:        "default",
		Description: "Default profile with no restrictions",
	}

	// RestrictedProfile limits tool access and context size.
	RestrictedProfile = &BootstrapProfile{
		Name:               "restricted",
		Description:        "Restricted profile with limited tools and context",
		DeniedTools:        []string{"shell", "browser", "file_write"},
		MaxContextMessages: 20,
		MaxContextTokens:   4000,
	}

	// ReadOnlyProfile only allows read operations.
	ReadOnlyProfile = &BootstrapProfile{
		Name:        "readonly",
		Description: "Read-only profile that prevents modifications",
		AllowedTools: []string{
			"search", "read", "glob", "grep", "web_fetch",
		},
	}

	// CodeAssistantProfile is optimized for code assistance.
	CodeAssistantProfile = &BootstrapProfile{
		Name:        "code_assistant",
		Description: "Profile optimized for code assistance tasks",
		SystemPromptSuffix: `You are a code assistant. Focus on:
- Writing clean, maintainable code
- Following best practices and conventions
- Explaining code changes clearly
- Suggesting tests when appropriate`,
		AllowedTools: []string{
			"read", "write", "edit", "glob", "grep", "shell",
		},
	}
)

Predefined profiles for common use cases.

View Source
var (
	// LeanModeDisabled is a convenience for disabling lean mode.
	LeanModeDisabled = &LeanMode{Enabled: false, Level: LeanLevelOff}

	// LeanModeForOllama is optimized for Ollama local models.
	LeanModeForOllama = &LeanMode{
		Enabled:           true,
		Level:             LeanLevelModerate,
		MaxContextTokens:  2048,
		MaxResponseTokens: 512,
		CompactPrompts:    true,
		BatchSize:         4,
	}

	// LeanModeForLMStudio is optimized for LM Studio local models.
	LeanModeForLMStudio = &LeanMode{
		Enabled:           true,
		Level:             LeanLevelLight,
		MaxContextTokens:  4096,
		MaxResponseTokens: 1024,
	}

	// LeanModeForLlamaCpp is optimized for llama.cpp direct usage.
	LeanModeForLlamaCpp = &LeanMode{
		Enabled:           true,
		Level:             LeanLevelAggressive,
		MaxContextTokens:  512,
		MaxResponseTokens: 256,
		CompactPrompts:    true,
		DisableHistory:    true,
		StreamingDisabled: true,
		CacheDisabled:     true,
	}
)

Predefined lean mode configurations.

Functions

This section is empty.

Types

type AutoReplyConfig added in v0.10.0

type AutoReplyConfig struct {
	// Enabled turns on auto-reply mode.
	Enabled bool

	// CommentaryMode controls inter-tool commentary verbosity.
	CommentaryMode CommentaryMode

	// InterToolDelay is the delay between tool executions for readability.
	InterToolDelay time.Duration

	// PersistCommentary saves commentary to the session for later review.
	PersistCommentary bool

	// MaxRounds limits the number of autonomous rounds before pausing.
	MaxRounds int

	// PauseOnError pauses auto-reply on tool errors.
	PauseOnError bool

	// PauseOnAmbiguity pauses when the agent is uncertain.
	PauseOnAmbiguity bool

	// NotifyOnCompletion sends a notification when auto-reply completes.
	NotifyOnCompletion bool

	// Callbacks for various auto-reply events.
	OnStart      func(ctx context.Context)
	OnRound      func(ctx context.Context, round int)
	OnPause      func(ctx context.Context, reason string)
	OnComplete   func(ctx context.Context)
	OnCommentary func(ctx context.Context, c *Commentary)
}

AutoReplyConfig configures the auto-reply behavior.

func DefaultAutoReplyConfig added in v0.10.0

func DefaultAutoReplyConfig() AutoReplyConfig

DefaultAutoReplyConfig returns the default auto-reply configuration.

type AutoReplyManager added in v0.10.0

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

AutoReplyManager manages auto-reply behavior for an agent.

func NewAutoReplyManager added in v0.10.0

func NewAutoReplyManager(config AutoReplyConfig, progress *ProgressReporter) *AutoReplyManager

NewAutoReplyManager creates a new auto-reply manager.

func (*AutoReplyManager) BeginRound added in v0.10.0

func (m *AutoReplyManager) BeginRound(ctx context.Context) bool

BeginRound marks the start of a new round.

func (*AutoReplyManager) Complete added in v0.10.0

func (m *AutoReplyManager) Complete(ctx context.Context)

Complete ends the auto-reply session.

func (*AutoReplyManager) Config added in v0.10.0

func (m *AutoReplyManager) Config() AutoReplyConfig

Config returns the auto-reply configuration.

func (*AutoReplyManager) Emitter added in v0.10.0

func (m *AutoReplyManager) Emitter() *CommentaryEmitter

Emitter returns the commentary emitter.

func (*AutoReplyManager) GetCommentary added in v0.10.0

func (m *AutoReplyManager) GetCommentary() []*Commentary

GetCommentary returns all commentary from the session.

func (*AutoReplyManager) IsActive added in v0.10.0

func (m *AutoReplyManager) IsActive() bool

IsActive returns whether auto-reply is currently active.

func (*AutoReplyManager) OnAmbiguity added in v0.10.0

func (m *AutoReplyManager) OnAmbiguity(ctx context.Context, description string)

OnAmbiguity handles uncertainty in the agent.

func (*AutoReplyManager) OnDecision added in v0.10.0

func (m *AutoReplyManager) OnDecision(ctx context.Context, decision string, options []string)

OnDecision records a decision point.

func (*AutoReplyManager) OnThinking added in v0.10.0

func (m *AutoReplyManager) OnThinking(ctx context.Context, thought string)

OnThinking records agent thinking/reasoning.

func (*AutoReplyManager) OnToolComplete added in v0.10.0

func (m *AutoReplyManager) OnToolComplete(ctx context.Context, toolName string, result any, err error)

OnToolComplete records a tool completing.

func (*AutoReplyManager) OnToolStart added in v0.10.0

func (m *AutoReplyManager) OnToolStart(ctx context.Context, toolName string)

OnToolStart records a tool starting.

func (*AutoReplyManager) Pause added in v0.10.0

func (m *AutoReplyManager) Pause(ctx context.Context, reason string)

Pause pauses the auto-reply session.

func (*AutoReplyManager) Resume added in v0.10.0

func (m *AutoReplyManager) Resume(ctx context.Context)

Resume resumes a paused auto-reply session.

func (*AutoReplyManager) Start added in v0.10.0

func (m *AutoReplyManager) Start(ctx context.Context)

Start begins an auto-reply session.

func (*AutoReplyManager) State added in v0.10.0

func (m *AutoReplyManager) State() AutoReplyState

State returns the current auto-reply state.

func (*AutoReplyManager) UpdateConfig added in v0.10.0

func (m *AutoReplyManager) UpdateConfig(config AutoReplyConfig)

UpdateConfig updates the auto-reply configuration.

type AutoReplyState added in v0.10.0

type AutoReplyState struct {
	// Active indicates if auto-reply is currently running.
	Active bool

	// StartTime is when the auto-reply session started.
	StartTime time.Time

	// CurrentRound is the current round number.
	CurrentRound int

	// TotalRounds is the total number of rounds executed.
	TotalRounds int

	// ToolsExecuted counts the tools executed.
	ToolsExecuted int

	// LastError holds the last error encountered.
	LastError error

	// PauseReason explains why auto-reply is paused.
	PauseReason string

	// Commentary contains the accumulated commentary.
	Commentary []*Commentary
}

AutoReplyState tracks the state of an auto-reply session.

func (*AutoReplyState) Duration added in v0.10.0

func (s *AutoReplyState) Duration() time.Duration

Duration returns the duration of the auto-reply session.

type BootstrapProfile

type BootstrapProfile struct {
	// Name is the unique identifier for this profile.
	Name string

	// Description provides a human-readable description of the profile.
	Description string

	// SystemPrompt overrides the agent's default system prompt.
	// If empty, the agent's configured system prompt is used.
	SystemPrompt string

	// SystemPromptPrefix is prepended to the system prompt.
	SystemPromptPrefix string

	// SystemPromptSuffix is appended to the system prompt.
	SystemPromptSuffix string

	// AllowedTools limits which tools are available to the agent.
	// If empty, all registered tools are available.
	AllowedTools []string

	// DeniedTools prevents specific tools from being used.
	// Takes precedence over AllowedTools.
	DeniedTools []string

	// MaxContextMessages limits the conversation history length.
	// Zero means use the agent's default.
	MaxContextMessages int

	// MaxContextTokens limits the total token count in context.
	// Zero means use the agent's default.
	MaxContextTokens int

	// Temperature overrides the LLM temperature setting.
	// Nil means use the agent's default.
	Temperature *float64

	// MaxTokens overrides the LLM max tokens setting.
	// Nil means use the agent's default.
	MaxTokens *int

	// Model overrides the LLM model.
	// Empty means use the agent's default.
	Model string

	// ToolPolicies defines per-tool configuration.
	ToolPolicies map[string]ToolPolicy

	// OnInit is called when the profile is activated.
	OnInit func(ctx context.Context) error

	// OnClose is called when the profile is deactivated.
	OnClose func(ctx context.Context) error

	// Metadata holds arbitrary profile-specific data.
	Metadata map[string]any
}

BootstrapProfile defines agent-specific initialization configuration. Each profile can customize system prompts, tools, context limits, and other agent behaviors.

func (*BootstrapProfile) BuildSystemPrompt

func (p *BootstrapProfile) BuildSystemPrompt(basePrompt string) string

BuildSystemPrompt constructs the final system prompt with prefix/suffix.

func (*BootstrapProfile) Clone

func (p *BootstrapProfile) Clone() *BootstrapProfile

Clone creates a deep copy of the profile.

func (*BootstrapProfile) FilterTools

func (p *BootstrapProfile) FilterTools(tools []provider.Tool) []provider.Tool

FilterTools returns tools filtered by the profile's allow/deny lists.

func (*BootstrapProfile) GetToolPolicy

func (p *BootstrapProfile) GetToolPolicy(toolName string) (ToolPolicy, bool)

GetToolPolicy returns the policy for a specific tool.

type Commentary added in v0.10.0

type Commentary struct {
	// ID is a unique identifier for this commentary.
	ID string `json:"id"`

	// Type identifies the type of commentary.
	Type CommentaryType `json:"type"`

	// Content is the commentary text.
	Content string `json:"content"`

	// ToolName is the associated tool name (for tool-related commentary).
	ToolName string `json:"tool_name,omitempty"`

	// Timestamp is when the commentary was created.
	Timestamp time.Time `json:"timestamp"`

	// Metadata contains additional key-value data.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Commentary represents a single commentary entry.

type CommentaryCallback added in v0.10.0

type CommentaryCallback func(*Commentary)

CommentaryCallback is called when commentary is emitted.

type CommentaryEmitter added in v0.10.0

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

CommentaryEmitter manages emission of commentary during agent execution.

func NewCommentaryEmitter added in v0.10.0

func NewCommentaryEmitter(mode CommentaryMode) *CommentaryEmitter

NewCommentaryEmitter creates a new commentary emitter.

func (*CommentaryEmitter) Buffer added in v0.10.0

func (e *CommentaryEmitter) Buffer() []*Commentary

Buffer returns all buffered commentary.

func (*CommentaryEmitter) Clear added in v0.10.0

func (e *CommentaryEmitter) Clear()

Clear empties the buffer without returning.

func (*CommentaryEmitter) EmitDecision added in v0.10.0

func (e *CommentaryEmitter) EmitDecision(ctx context.Context, decision string, options []string)

EmitDecision emits a decision point commentary.

func (*CommentaryEmitter) EmitProgress added in v0.10.0

func (e *CommentaryEmitter) EmitProgress(ctx context.Context, content string)

EmitProgress emits a progress commentary.

func (*CommentaryEmitter) EmitThinking added in v0.10.0

func (e *CommentaryEmitter) EmitThinking(ctx context.Context, content string)

EmitThinking emits a thinking/reasoning commentary.

func (*CommentaryEmitter) EmitToolSummary added in v0.10.0

func (e *CommentaryEmitter) EmitToolSummary(ctx context.Context, toolName string, result any)

EmitToolSummary emits a summary of tool execution.

func (*CommentaryEmitter) EmitTransition added in v0.10.0

func (e *CommentaryEmitter) EmitTransition(ctx context.Context, from, to string)

EmitTransition emits a step transition commentary.

func (*CommentaryEmitter) Flush added in v0.10.0

func (e *CommentaryEmitter) Flush() []*Commentary

Flush clears the commentary buffer and returns its contents.

func (*CommentaryEmitter) Mode added in v0.10.0

Mode returns the current commentary mode.

func (*CommentaryEmitter) SetDispatch added in v0.10.0

func (e *CommentaryEmitter) SetDispatch(dispatch CommentaryCallback)

SetDispatch sets the callback for immediate commentary dispatch.

func (*CommentaryEmitter) SetMode added in v0.10.0

func (e *CommentaryEmitter) SetMode(mode CommentaryMode)

SetMode changes the commentary mode.

type CommentaryMode added in v0.10.0

type CommentaryMode int

CommentaryMode controls the verbosity of inter-tool commentary.

const (
	// CommentaryNone disables all commentary.
	CommentaryNone CommentaryMode = iota

	// CommentaryBrief shows only key decisions and transitions.
	CommentaryBrief

	// CommentaryVerbose shows thinking, reasoning, and detailed summaries.
	CommentaryVerbose
)

func ParseCommentaryMode added in v0.10.0

func ParseCommentaryMode(s string) CommentaryMode

ParseCommentaryMode parses a string into a CommentaryMode.

func (CommentaryMode) String added in v0.10.0

func (m CommentaryMode) String() string

String returns the string representation of the commentary mode.

type CommentaryType added in v0.10.0

type CommentaryType string

CommentaryType identifies the type of commentary.

const (
	// CommentaryThinking represents internal reasoning/thinking.
	CommentaryThinking CommentaryType = "thinking"

	// CommentaryProgress represents progress updates.
	CommentaryProgress CommentaryType = "progress"

	// CommentaryToolSummary represents a summary of tool execution.
	CommentaryToolSummary CommentaryType = "tool_summary"

	// CommentaryDecision represents a decision point.
	CommentaryDecision CommentaryType = "decision"

	// CommentaryTransition represents a transition between steps.
	CommentaryTransition CommentaryType = "transition"
)

type LeanLevel

type LeanLevel int

LeanLevel represents the aggressiveness of lean mode optimizations.

const (
	// LeanLevelOff disables lean mode.
	LeanLevelOff LeanLevel = iota

	// LeanLevelLight applies minimal optimizations.
	// - Reduces context to 2048 tokens
	// - Limits response to 512 tokens
	LeanLevelLight

	// LeanLevelModerate applies balanced optimizations.
	// - Reduces context to 1024 tokens
	// - Limits response to 256 tokens
	// - Compacts prompts
	LeanLevelModerate

	// LeanLevelAggressive applies maximum optimizations.
	// - Reduces context to 512 tokens
	// - Limits response to 128 tokens
	// - Disables history
	// - Skips system prompt
	LeanLevelAggressive
)

func ParseLeanLevel

func ParseLeanLevel(s string) (LeanLevel, error)

ParseLeanLevel parses a string into a LeanLevel.

func (LeanLevel) String

func (l LeanLevel) String() string

String returns the string representation of the lean level.

type LeanMode

type LeanMode struct {
	// Enabled activates lean mode optimizations.
	Enabled bool

	// Level controls the aggressiveness of optimizations.
	// Higher levels reduce more resources but may impact quality.
	Level LeanLevel

	// MaxContextTokens limits the context window size.
	// Lower values reduce memory usage.
	MaxContextTokens int

	// MaxResponseTokens limits the response length.
	MaxResponseTokens int

	// DisableTools disables all tool usage when true.
	DisableTools bool

	// ToolAllowlist limits which tools are available.
	// Empty means all tools (unless DisableTools is true).
	ToolAllowlist []string

	// DisableHistory prevents storing conversation history.
	DisableHistory bool

	// CompactPrompts removes whitespace and shortens prompts.
	CompactPrompts bool

	// SkipSystemPrompt omits the system prompt to save tokens.
	SkipSystemPrompt bool

	// BatchSize controls how many messages to process at once.
	// Lower values reduce peak memory usage.
	BatchSize int

	// StreamingDisabled prevents streaming responses.
	// Useful when streaming adds overhead.
	StreamingDisabled bool

	// CacheDisabled prevents caching of responses.
	CacheDisabled bool
}

LeanMode defines resource optimization settings for local models. This reduces memory usage and improves performance for constrained environments.

func NewLeanMode

func NewLeanMode(level LeanLevel) *LeanMode

NewLeanMode creates a LeanMode with default settings for the given level.

func (*LeanMode) Apply

func (m *LeanMode) Apply(profile *BootstrapProfile)

Apply applies lean mode settings to a bootstrap profile.

func (*LeanMode) EstimateMemorySavings

func (m *LeanMode) EstimateMemorySavings() float64

EstimateMemorySavings returns an estimated percentage of memory savings.

type LeanModeConfig

type LeanModeConfig struct {
	// Level is the lean mode level.
	Level LeanLevel

	// CustomSettings override the level defaults.
	CustomSettings *LeanMode

	// ModelSpecific maps model names to lean mode settings.
	// Allows different settings per model.
	ModelSpecific map[string]*LeanMode
}

LeanModeConfig configures lean mode behavior.

func (*LeanModeConfig) GetForModel

func (c *LeanModeConfig) GetForModel(model string) *LeanMode

GetForModel returns lean mode settings for a specific model.

type ProfileRegistry

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

ProfileRegistry manages bootstrap profiles.

func NewProfileRegistry

func NewProfileRegistry() *ProfileRegistry

NewProfileRegistry creates a new profile registry.

func (*ProfileRegistry) Get

func (r *ProfileRegistry) Get(name string) (*BootstrapProfile, bool)

Get retrieves a profile by name.

func (*ProfileRegistry) List

func (r *ProfileRegistry) List() []string

List returns all registered profile names.

func (*ProfileRegistry) Register

func (r *ProfileRegistry) Register(profile *BootstrapProfile) error

Register adds a profile to the registry.

func (*ProfileRegistry) SetLogger

func (r *ProfileRegistry) SetLogger(logger *slog.Logger)

SetLogger sets the logger for the registry.

func (*ProfileRegistry) Unregister

func (r *ProfileRegistry) Unregister(name string)

Unregister removes a profile from the registry.

type ProfileSession

type ProfileSession struct {
	Profile *BootstrapProfile
	Active  bool
}

ProfileSession represents an active profile session.

func (*ProfileSession) Activate

func (s *ProfileSession) Activate(ctx context.Context) error

Activate initializes the profile session.

func (*ProfileSession) Deactivate

func (s *ProfileSession) Deactivate(ctx context.Context) error

Deactivate closes the profile session.

type ProgressCallback

type ProgressCallback func(progress *ToolProgress)

ProgressCallback is called when tool progress changes.

type ProgressConfig

type ProgressConfig struct {
	// Mode is the detail level for progress output.
	Mode ProgressDetailMode

	// Output is where progress is written (default: os.Stderr).
	Output io.Writer

	// ToolModes allows per-tool mode overrides.
	ToolModes map[string]ProgressDetailMode

	// Callbacks receive progress updates.
	Callbacks []ProgressCallback
}

ProgressConfig configures progress reporting behavior.

func (*ProgressConfig) GetModeForTool

func (c *ProgressConfig) GetModeForTool(toolName string) ProgressDetailMode

GetModeForTool returns the progress mode for a specific tool.

type ProgressDetailMode

type ProgressDetailMode int

ProgressDetailMode controls how much detail is shown during tool execution.

const (
	// ProgressModeQuiet shows no progress output.
	ProgressModeQuiet ProgressDetailMode = iota

	// ProgressModeMinimal shows only tool names and completion status.
	ProgressModeMinimal

	// ProgressModeNormal shows tool names, parameters, and results summary.
	ProgressModeNormal

	// ProgressModeVerbose shows full details including parameters and results.
	ProgressModeVerbose

	// ProgressModeDebug shows all details plus timing and internal state.
	ProgressModeDebug
)

func ParseProgressMode

func ParseProgressMode(s string) (ProgressDetailMode, error)

ParseProgressMode parses a string into a ProgressDetailMode.

func (ProgressDetailMode) String

func (m ProgressDetailMode) String() string

String returns the string representation of the progress mode.

type ProgressReporter

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

ProgressReporter handles reporting tool execution progress.

func NewProgressReporter

func NewProgressReporter(mode ProgressDetailMode, output io.Writer) *ProgressReporter

NewProgressReporter creates a new progress reporter.

func (*ProgressReporter) Active

func (r *ProgressReporter) Active() []*ToolProgress

Active returns the currently active tool executions.

func (*ProgressReporter) Cancel

func (r *ProgressReporter) Cancel(id string)

Cancel reports that a tool execution was cancelled.

func (*ProgressReporter) Complete

func (r *ProgressReporter) Complete(id string, result string, err error)

Complete reports that a tool has finished executing.

func (*ProgressReporter) Mode

Mode returns the current progress detail mode.

func (*ProgressReporter) OnProgress

func (r *ProgressReporter) OnProgress(cb ProgressCallback)

OnProgress registers a callback for progress updates.

func (*ProgressReporter) SetLogger

func (r *ProgressReporter) SetLogger(logger *slog.Logger)

SetLogger sets the logger for the reporter.

func (*ProgressReporter) SetMode

func (r *ProgressReporter) SetMode(mode ProgressDetailMode)

SetMode changes the progress detail mode.

func (*ProgressReporter) Start

func (r *ProgressReporter) Start(ctx context.Context, toolName string, params map[string]any) string

Start reports that a tool has started executing.

func (*ProgressReporter) Update

func (r *ProgressReporter) Update(id string, percentComplete int, message string)

Update reports progress on an ongoing tool execution.

type ToolPolicy

type ToolPolicy struct {
	// Enabled controls whether the tool is available.
	Enabled bool

	// RateLimit is the maximum calls per minute. Zero means unlimited.
	RateLimit int

	// Timeout overrides the tool's default timeout in seconds.
	// Zero means use the tool's default.
	Timeout int

	// RequiresConfirmation indicates the user must confirm before execution.
	RequiresConfirmation bool
}

ToolPolicy defines per-tool configuration within a profile.

type ToolProgress

type ToolProgress struct {
	// ToolName is the name of the tool being executed.
	ToolName string

	// Status is the current execution status.
	Status ToolProgressStatus

	// StartTime is when the tool started executing.
	StartTime time.Time

	// EndTime is when the tool finished executing.
	EndTime time.Time

	// Parameters are the tool input parameters (may be redacted).
	Parameters map[string]any

	// Result is the tool output (may be truncated).
	Result string

	// Error is any error that occurred.
	Error string

	// BytesProcessed is the number of bytes processed (for streaming tools).
	BytesProcessed int64

	// Progress is the completion percentage (0-100) if known.
	Progress int

	// Message is a human-readable status message.
	Message string
}

ToolProgress represents progress information for a tool execution.

func (*ToolProgress) Duration

func (p *ToolProgress) Duration() time.Duration

Duration returns the execution duration.

type ToolProgressStatus

type ToolProgressStatus string

ToolProgressStatus represents the status of a tool execution.

const (
	ToolProgressPending   ToolProgressStatus = "pending"
	ToolProgressRunning   ToolProgressStatus = "running"
	ToolProgressCompleted ToolProgressStatus = "completed"
	ToolProgressFailed    ToolProgressStatus = "failed"
	ToolProgressCancelled ToolProgressStatus = "cancelled"
)

Jump to

Keyboard shortcuts

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