config

Documentation

Overview

Package config loads and validates gantry configuration from the environment. Boot is fail-fast: missing required values return a clear error.

Index

• Constants
• type Config
  • func Load() (*Config, error)
  • func (c *Config) Validate() error

Constants

const (
	ChannelTelegram = "telegram"
	ChannelDiscord  = "discord"
	ChannelSlack    = "slack"
	ChannelStdio    = "stdio"
)

Channel names accepted by CHANNEL.

Types

type Config

type Config struct {
	LLMBaseURL string `env:"LLM_BASE_URL,required"`
	LLMAPIKey  string `env:"LLM_API_KEY,required"`
	LLMModel   string `env:"LLM_MODEL,required"`
	// LLMMaxTokens caps completion output (incl. tool-call args). 0 = provider default.
	LLMMaxTokens int `env:"LLM_MAX_TOKENS" envDefault:"4096"`
	// LLMReasoningEffort is sent as reasoning_effort when non-empty (Ollama/Qwen:
	// "none" disables thinking so max_tokens is not eaten by hidden chain-of-thought).
	LLMReasoningEffort string `env:"LLM_REASONING_EFFORT"`

	TelegramBotToken     string  `env:"TELEGRAM_BOT_TOKEN"`
	TelegramAllowedUsers []int64 `env:"TELEGRAM_ALLOWED_USERS" envSeparator:","`
	// TelegramErrorReporting tees slog ERROR (or WARN+) into the Tim Telegram
	// chat as an expandable HTML alert. off|error|warn. Only when CHANNEL=telegram.
	TelegramErrorReporting string `env:"TELEGRAM_ERROR_REPORTING" envDefault:"off"`

	DiscordBotToken     string   `env:"DISCORD_BOT_TOKEN"`
	DiscordAllowedUsers []string `env:"DISCORD_ALLOWED_USERS" envSeparator:","`

	SlackBotToken     string   `env:"SLACK_BOT_TOKEN"` // xoxb-
	SlackAppToken     string   `env:"SLACK_APP_TOKEN"` // xapp- (Socket Mode)
	SlackAllowedUsers []string `env:"SLACK_ALLOWED_USERS" envSeparator:","`

	Channel     string `env:"CHANNEL" envDefault:"telegram"`
	PersonaDir  string `env:"PERSONA_DIR" envDefault:"/persona"`
	DataDir     string `env:"DATA_DIR" envDefault:"/data"`
	MCPManifest string `env:"MCP_MANIFEST" envDefault:"/etc/gantry/mcp.toml"`

	HistoryMaxMessages int `env:"HISTORY_MAX_MESSAGES" envDefault:"200"`
	HistoryMaxTokens   int `env:"HISTORY_MAX_TOKENS" envDefault:"128000"` // estimated (chars/4)
	ToolResultMaxChars int `env:"TOOL_RESULT_MAX_CHARS" envDefault:"6000"`
	ToolMaxIterations  int `env:"TOOL_MAX_ITERATIONS" envDefault:"20"`
	// ToolSchemaMaxTokens is an optional hard cap on estimated tool-schema tokens
	// (chars/4 of name+description+parameters). 0 = log estimate only.
	ToolSchemaMaxTokens int `env:"TOOL_SCHEMA_MAX_TOKENS" envDefault:"0"`

	// ToolsEnabled controls whether tool schemas are sent to the model.
	// false omits MCP, memory_*, and cron_* tools from every completion — required
	// for models that reject tools (e.g. Ollama gemma3). Memory/cron backends may
	// still start; only the agent tool surface is cleared.
	ToolsEnabled bool `env:"TOOLS_ENABLED" envDefault:"true"`

	MemoryEnabled            bool   `env:"MEMORY_ENABLED" envDefault:"true"`
	MemoryBackend            string `env:"MEMORY_BACKEND" envDefault:"builtin"`
	MemoryConsolidateMinutes int    `env:"MEMORY_CONSOLIDATE_MINUTES" envDefault:"30"` // 0 = off

	CronEnabled     bool   `env:"CRON_ENABLED" envDefault:"true"`
	CronTZ          string `env:"CRON_TZ" envDefault:"UTC"`
	CronMaxJobs     int    `env:"CRON_MAX_JOBS" envDefault:"50"`
	CronTickSeconds int    `env:"CRON_TICK_SECONDS" envDefault:"15"`

	// Spark of life (opt-in). Empty SPARK_QTY = disabled. Examples: "5", "4-6".
	SparkQty               string `env:"SPARK_QTY" envDefault:""`
	SparkStartHour         int    `env:"SPARK_START_HOUR" envDefault:"6"`
	SparkEndHour           int    `env:"SPARK_END_HOUR" envDefault:"21"`
	SparkPrompt            string `env:"SPARK_PROMPT" envDefault:""`
	SparkSkipRecentMinutes int    `env:"SPARK_SKIP_RECENT_MINUTES" envDefault:"15"`

	StreamReplies bool `env:"STREAM_REPLIES" envDefault:"true"`

	// ShowThinking controls whether chain-of-thought is rendered in the Telegram
	// stream bubble (live italics → final expandable blockquote). On by default;
	// set false for a quieter bubble. Pair with LLM_REASONING_EFFORT=none on
	// slow local models so CoT is not generated (and therefore not shown).
	// Needs STREAM_REPLIES=true. Does not change model-side think on/off.
	ShowThinking bool `env:"SHOW_THINKING" envDefault:"true"`

	// ToolTrace controls user-visible tool activity when STREAM_REPLIES is on.
	// compact = Making Calls: ✓, ✗ (default); full = → name / ✓ timing lines;
	// off = hide tool activity entirely. Journal logs are unaffected.
	ToolTrace string `env:"TOOL_TRACE" envDefault:"compact"`

	// CoalesceSettleMS is quiet time after the last chat bubble before running
	// one joined turn (interrupt + coalesce). 0 disables. Default 2000ms.
	CoalesceSettleMS int `env:"COALESCE_SETTLE_MS" envDefault:"2000"`

	// SpinupNoticeMS posts a "still working" line once a turn has gone this
	// long without model output. The first turn after start posts immediately.
	// Needs STREAM_REPLIES=true. 0 disables. Default 4000ms.
	SpinupNoticeMS int `env:"SPINUP_NOTICE_MS" envDefault:"4000"`

	LogLevel string `env:"LOG_LEVEL" envDefault:"info"`
}

Config is the complete env-driven configuration surface. Secrets and scalars live here; structure (persona, MCP manifest) is mounts.

func Load

func Load() (*Config, error)

Load parses environment variables into Config and validates channel-specific requirements. Returns a descriptive error on any failure.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks cross-field and channel-specific rules after env parsing.