Documentation
¶
Index ¶
- Constants
- Variables
- func APIKeys() map[string]string
- func BaseURLs() map[string]string
- func IsLLMSDocsURL(u string) bool
- func LookupEnv(names ...string) (value, source string)
- func LookupEnvFrom(cwd string, names ...string) (value, source string)
- func NotifyReroutedLLMS(cfg Config)
- func SaveDefaultRole(model, provider string) error
- type A2AAgentConfig
- type A2AConfig
- type AutoCompactConfig
- type CompactorConfig
- type Config
- func (c *Config) LLMSSources() *LLMSConfig
- func (c *Config) ResolveBaseURLs() map[string]string
- func (c Config) ResolveCompressor() (name string, ok bool)
- func (c Config) ResolveRateLimits(providerName, modelName string) ratelimit.Limits
- func (c *Config) ResolveRole(role string) (model string, prov string, advisorModel string, advisorMaxUses int, ...)
- func (c *Config) Save() error
- type HookConfig
- type LLMSConfig
- type LLMSSource
- type MCPConfig
- type MCPServer
- type MemoryConfig
- type PalaceConfig
- type RateLimitConfig
- type RoleConfig
Constants ¶
const ( // CompressorNone records observations without any model call. CompressorNone = "none" // CompressorSubagent compresses each observation with the bundled // memory-compressor subagent, one child process per tool call. CompressorSubagent = "subagent" )
Compressor values accepted in MemoryConfig.Compressor.
Variables ¶
var ErrNoDefaultRole = errors.New("no default model role configured")
ErrNoDefaultRole is returned when no default role is configured.
Functions ¶
func APIKeys ¶
APIKeys returns detected API keys from environment variables. For Anthropic, checks ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN (Ollama compatibility).
func BaseURLs ¶
BaseURLs returns provider base URLs from environment variables. Supports ANTHROPIC_BASE_URL (Ollama compatibility), OPENAI_BASE_URL, GEMINI_BASE_URL, and OLLAMA_HOST (Ollama server address override).
func IsLLMSDocsURL ¶ added in v0.0.77
IsLLMSDocsURL reports whether u points at an llms.txt documentation index rather than an MCP endpoint. Such a URL serves plain text over GET and answers the MCP "initialize" POST with 405 Method Not Allowed, so treating it as an MCP server can only ever fail.
The convention (llmstxt.org) fixes the file name, not the host or path, so the base name is the deciding test: "llms.txt" and the expanded "llms-full.txt". The URL must also be one fetch_docs could actually read — https with a host — since that is the only tool that would serve it.
func LookupEnv ¶ added in v0.0.75
LookupEnv resolves one setting from the process environment and from the .env files pi already reads, returning the value and where it came from.
It exists because pi has two ways to hold a credential and only one of them was reachable from a command's own flag handling. `pi login` writes keys to ~/.pi-go/.env, config substitution reads .env files for MCP server URLs — yet a command calling os.Getenv directly sees none of that, so a key that pi itself saved reads as "not set" unless the user also exported it. Anything asking for a credential should ask here.
Precedence is the process environment first, then the nearest project file, then the home file: an explicit export for one run must beat a file, and a project's own key must beat the account-wide one. Files searched, in order:
<cwd or a parent>/.pi-go/.env — the project key <cwd or a parent>/.env — the plain dotenv a project may already have ~/.pi-go/.env — what `pi login` writes
names are tried in order, so a caller can accept an alias (GEMINI_API_KEY, then GOOGLE_API_KEY) in one call. The returned source is meant for a log line telling the operator which file supplied the value — never the value itself.
func LookupEnvFrom ¶ added in v0.0.75
LookupEnvFrom is LookupEnv rooted at an explicit directory, which is what a server serving a project other than its own working directory needs.
func NotifyReroutedLLMS ¶ added in v0.0.77
func NotifyReroutedLLMS(cfg Config)
NotifyReroutedLLMS announces the MCP servers that load-time rerouting moved to the llms.txt sources. It is separate from LoadFrom so the message is raised only once a front end has claimed the notice sink — in the TUI that means after runInteractive installs it, since anything written before the first frame is erased by the terminal reset.
It is safe to call more than once only if the caller intends to repeat the message; each call emits.
func SaveDefaultRole ¶ added in v0.0.23
SaveDefaultRole updates the "default" role in the global config and saves it. If the default role doesn't exist, it creates it. If a model is already set, it updates only the model field (preserving provider, advisor, etc.).
Types ¶
type A2AAgentConfig ¶ added in v0.0.15
A2AAgentConfig defines a single A2A-capable agent endpoint.
type A2AConfig ¶ added in v0.0.15
type A2AConfig struct {
Agents []A2AAgentConfig `json:"agents,omitempty"`
}
A2AConfig holds configuration for A2A agent connections.
type AutoCompactConfig ¶ added in v0.0.48
type AutoCompactConfig struct {
Enabled *bool `json:"enabled,omitempty"`
// ShedPercent is the context-window share at which superseded tool results
// are dropped. Cheap: no LLM call, prompt cache preserved.
ShedPercent int `json:"shed_percent,omitempty"`
// SummarizePercent is the share at which a summarizing rebuild runs.
// Clamped to 95 — beyond that the summarization request itself may not fit.
SummarizePercent int `json:"summarize_percent,omitempty"`
// KeepUserMessageTokens caps user messages carried across a rebuild.
KeepUserMessageTokens int `json:"keep_user_message_tokens,omitempty"`
// KeepRecentEvents is the conversation tail compaction never touches.
KeepRecentEvents int `json:"keep_recent_events,omitempty"`
}
AutoCompactConfig holds user-overridable auto-compaction settings. When nil in config, the session package's two-stage defaults apply: shed superseded tool results at 60% of the context window, run a full summarizing rebuild at 88%.
type CompactorConfig ¶ added in v0.0.4
type CompactorConfig struct {
Enabled *bool `json:"enabled,omitempty"`
SourceCodeFiltering string `json:"source_code_filtering,omitempty"` // "none", "minimal", "aggressive"
MaxChars int `json:"max_chars,omitempty"`
MaxLines int `json:"max_lines,omitempty"`
}
CompactorConfig holds user-overridable compaction settings. When nil in config, defaults are applied by the tools package.
type Config ¶
type Config struct {
Roles map[string]RoleConfig `json:"roles,omitempty"`
DefaultModel string `json:"defaultModel,omitempty"` // deprecated: use roles
DefaultProvider string `json:"defaultProvider"`
ThinkingLevel string `json:"thinkingLevel"`
Theme string `json:"theme"`
BaseURLs map[string]string `json:"baseURLs,omitempty"` // provider → base URL; overridden by env
ExtraHeaders map[string]string `json:"extraHeaders,omitempty"`
InsecureSkipTLS bool `json:"insecureSkipTLS,omitempty"`
// MaxOutputTokens caps a reply on the OpenAI-compatible provider paths,
// in tokens. Zero uses the provider default (64000), which is the output
// ceiling of the current Claude and GPT models. Lower it for a backend
// whose models stop below that and reject the request rather than
// clamping it. This is an output cap, not a context window.
MaxOutputTokens int64 `json:"maxOutputTokens,omitempty"`
// CACertPath is a PEM bundle trusted in addition to the system roots, for
// TLS-intercepting corporate proxies. Prefer it over insecureSkipTLS,
// which turns verification off for every endpoint.
CACertPath string `json:"caCertPath,omitempty"`
// DisableSystemCAs narrows trust to caCertPath alone.
DisableSystemCAs bool `json:"disableSystemCAs,omitempty"`
// TraceHTTP logs every LLM request and response in full — headers and
// bodies — to the session log and to OTel span events. Equivalent to
// --trace-http, which can enable it but never turn it off.
//
// The resulting log contains the entire conversation, system prompt and
// tool output in cleartext. Credentials are masked; nothing else is.
TraceHTTP bool `json:"traceHTTP,omitempty"`
// PlanAutoFix runs the automatic plan-repair loop. When a /plan session ends
// with a spec that fails the PDD contract, the blocking findings are fed
// back to the planner as its next prompt rather than waiting for a human to
// notice and continue. Bounded by PI_PLAN_MAX_FIX_CYCLES (default 10).
//
// A pointer so "unset" is distinguishable from an explicit false: the
// default is on, and a plain bool would make it impossible to turn off.
PlanAutoFix *bool `json:"planAutoFix,omitempty"`
Tools map[string]any `json:"tools,omitempty"`
MCP *MCPConfig `json:"mcp,omitempty"`
Hooks []HookConfig `json:"hooks,omitempty"`
MaxDailyTokens int64 `json:"maxDailyTokens,omitempty"` // 0 = unlimited
// ContextWindow overrides the model's context window in tokens. Needed for
// models absent from the embedded catalog (notably the opencode ones):
// auto-compaction measures a percentage of the window, so it stays off
// rather than guess at an unknown budget.
ContextWindow int64 `json:"contextWindow,omitempty"`
// RateLimits paces outbound requests, keyed by provider name ("gemini",
// "agentgateway", …) with "*" as the fallback for the rest.
RateLimits map[string]RateLimitConfig `json:"rateLimits,omitempty"`
Compactor *CompactorConfig `json:"compactor,omitempty"`
AutoCompact *AutoCompactConfig `json:"autoCompact,omitempty"`
Memory *MemoryConfig `json:"memory,omitempty"`
Palace *PalaceConfig `json:"palace,omitempty"`
A2A *A2AConfig `json:"a2a,omitempty"`
LLMS *LLMSConfig `json:"llms,omitempty"`
// ReroutedLLMS names the MCP servers whose URL is an llms.txt index and
// which were therefore given a fetch_docs source during load.
ReroutedLLMS []string `json:"-"`
// InferredLLMS holds those generated sources. They are deliberately kept
// out of LLMS, which is serialized: Save marshals the whole config, so an
// inference drawn from a project's mcp.json would otherwise be written
// into the global config file by an unrelated operation such as
// SaveDefaultRole. Read both together with LLMSSources.
InferredLLMS []LLMSSource `json:"-"`
}
Config holds all pi-go configuration.
func Defaults ¶
func Defaults() Config
Defaults returns a Config with default values. The default model is the latest top-tier entry in the embedded OpenAI catalog (modeldata/llm-prices-openai.json): gpt-5.6-sol is the current frontier at the time of writing. Bump this in lockstep with the catalog.
func Load ¶
Load reads config from global (~/.pi-go/config.json) and project (.pi-go/config.json) relative to the current process working directory.
func LoadFrom ¶ added in v0.0.25
LoadFrom reads config from global (~/.pi-go/config.json) and the nearest project .pi-go/config.json relative to cwd, merging project overrides onto global. MCP servers are also loaded from separate .pi-go/mcp.json files if present.
func (*Config) LLMSSources ¶ added in v0.0.77
func (c *Config) LLMSSources() *LLMSConfig
LLMSSources returns the llms.txt sources to serve, both those the user configured and those inferred from MCP entries during load. It returns nil when there are none, so callers can test it directly to decide whether to register the fetch_docs tool at all.
The two are kept apart in the struct and joined only here, so nothing that marshals a Config can persist an inference.
func (*Config) ResolveBaseURLs ¶ added in v0.0.46
ResolveBaseURLs returns provider base URLs from the config's baseURLs map merged with the environment, environment winning. This lets a self-hosted endpoint (e.g. an Ollama server on the LAN) live in config.json instead of requiring a shell export, while keeping the env vars usable as a per-shell or CI override. An empty env var does not mask a configured value.
func (Config) ResolveCompressor ¶ added in v0.1.6
ResolveCompressor returns the configured compressor name, falling back to the default when config carries none. An unrecognized value also falls back rather than erroring: memory is best-effort, and refusing to record anything because of a mistyped knob would be a worse outcome than recording the model-free default.
Callers that need to tell an unknown value apart from an absent one log it themselves; this returns only the resolved name.
func (Config) ResolveRateLimits ¶ added in v0.0.91
ResolveRateLimits returns the pacing budget for one provider/model pair.
Resolution is per field, not per entry: an entry that only sets requestsPerMinute keeps the built-in input-token budget rather than silently switching it off. That matters because the token budget is the one that binds — a user adding an RPM cap is tightening the limits, and dropping the default underneath them would loosen them instead.
Precedence for each field: the provider's own entry, then the "*" entry, then ratelimit.DefaultsFor.
func (*Config) ResolveRole ¶
func (c *Config) ResolveRole(role string) (model string, prov string, advisorModel string, advisorMaxUses int, advisorCaching bool, err error)
ResolveRole returns the model name, provider, and advisor settings for a given role. Falls back: requested role → "default" role → error.
type HookConfig ¶
type HookConfig struct {
Event string `json:"event"`
Command string `json:"command"`
Tools []string `json:"tools,omitempty"`
Timeout int `json:"timeout,omitempty"`
}
HookConfig defines a shell command hook for tool call events.
type LLMSConfig ¶ added in v0.0.76
type LLMSConfig struct {
Sources []LLMSSource `json:"sources,omitempty"`
}
LLMSConfig holds configuration for llms.txt documentation sources.
type LLMSSource ¶ added in v0.0.76
type LLMSSource struct {
Name string `json:"name"`
URL string `json:"url"`
// ExactURLOnly restricts fetch_docs to this exact URL rather than any
// page on the same host. It is set on sources pi-go inferred rather than
// ones the user wrote, and is not serialized: configuring a source is a
// deliberate grant of the whole host, whereas an inference drawn from a
// file name is a guess, and a guess must not quietly widen what the model
// can reach.
ExactURLOnly bool `json:"-"`
}
LLMSSource defines a single llms.txt documentation source.
type MCPServer ¶
type MCPServer struct {
Name string `json:"name"`
Command string `json:"command,omitempty"`
Args []string `json:"args,omitempty"`
URL string `json:"url,omitempty"` // HTTP transport (e.g., cloudflare-api)
Headers map[string]string `json:"headers,omitempty"` // Custom HTTP headers for the URL (Streamable HTTP) transport
OAuth bool `json:"oauth,omitempty"` // run the OAuth authorization-code flow on first connect
// contains filtered or unexported fields
}
func LoadMCPServers ¶ added in v0.0.22
func LoadMCPServers() []MCPServer
LoadMCPServers reads MCP server configurations from standalone mcp.json files relative to the current process working directory.
func LoadMCPServersFrom ¶ added in v0.0.25
LoadMCPServersFrom reads MCP server configurations from standalone mcp.json files relative to cwd. Resolution order: project .pi-go/mcp.json overrides global ~/.pi-go/mcp.json. Supports both the Claude Desktop object format (servers keyed by name) and the legacy array format.
type MemoryConfig ¶ added in v0.0.10
type MemoryConfig struct {
Enabled *bool `json:"enabled,omitempty"`
DBPath string `json:"db_path,omitempty"`
TokenBudget int `json:"token_budget,omitempty"`
CompressionRole string `json:"compression_model_role,omitempty"`
// Compressor selects how a recorded tool call becomes an observation.
//
// "none" (the default) records the raw event with no model call.
// "subagent" spawns the bundled memory-compressor as a child process per
// tool call. Per-tool inference is off by default because it costs a
// process spawn and an uncached provider round trip for every tool call in
// a session; the session summary supplies the narrative instead.
Compressor string `json:"compressor,omitempty"`
MaxPending int `json:"max_pending_observations,omitempty"`
LookbackHours int `json:"context_lookback_hours,omitempty"`
ExcludedTools []string `json:"excluded_tools,omitempty"`
ExcludedProjects []string `json:"excluded_projects,omitempty"`
}
MemoryConfig holds settings for the persistent memory system.
func MemoryDefaults ¶ added in v0.0.10
func MemoryDefaults() MemoryConfig
MemoryDefaults returns a MemoryConfig with default values.
type PalaceConfig ¶ added in v0.0.15
type PalaceConfig struct {
Enabled *bool `json:"enabled,omitempty"`
DBPath string `json:"db_path,omitempty"`
ModelPath string `json:"model_path,omitempty"`
// OllamaURL overrides the embedding daemon address. Empty uses the palace
// default (http://localhost:11434).
OllamaURL string `json:"ollama_url,omitempty"`
// OllamaModel overrides the embedding model. Empty uses the palace default.
// Changing it invalidates every stored vector — embeddings from different
// models are not comparable — so a change means re-running `pi memory mine`.
OllamaModel string `json:"ollama_model,omitempty"`
// LocalEmbedder forces the slower in-process model instead of Ollama.
LocalEmbedder bool `json:"local_embedder,omitempty"`
}
PalaceConfig holds settings for the MemPalace memory system.
type RateLimitConfig ¶ added in v0.0.91
type RateLimitConfig struct {
// RequestsPerMinute caps request count. Unset for every provider by
// default — the limits pi-go has actually been rejected by are token
// budgets, not request counts.
RequestsPerMinute *int `json:"requestsPerMinute,omitempty"`
// InputTokensPerMinute caps input tokens sent per minute. This is the
// budget that binds in practice; see ratelimit.DefaultsFor.
InputTokensPerMinute *int `json:"inputTokensPerMinute,omitempty"`
}
RateLimitConfig paces pi-go's outbound requests to one provider so a turn stays inside the provider's quota instead of discovering it by being rejected. See internal/ratelimit for why retrying is not a substitute.
Fields are pointers so that "not configured" and "explicitly unlimited" stay distinguishable: a missing field inherits the built-in default for the provider, and an explicit 0 turns that budget off.
type RoleConfig ¶
type RoleConfig struct {
Model string `json:"model"`
Provider string `json:"provider,omitempty"`
AdvisorModel string `json:"advisorModel,omitempty"` // Advisor model for advisor tool (e.g., "claude-opus-4-7")
AdvisorMaxUses int `json:"advisorMaxUses,omitempty"` // Max advisor calls per request (0 = unlimited)
AdvisorCaching bool `json:"advisorCaching,omitempty"` // Enable advisor prompt caching
}
RoleConfig maps a role to a specific model and optional provider override.