Documentation
¶
Overview ¶
Package learn implements BroCode's self-improving control layer: it observes each turn's context utilization and nudges the global efficiency knobs (today: the compaction trigger ratio) so the agent gets smarter about its own token budget the longer it is used — without any user tuning.
Why this matters vs. the big players: Claude Code / Cursor ship a fixed compaction threshold. BroCode measures reality (how full the window actually gets) and converges the threshold to keep context utilization in a high-signal band — compacting earlier when the window runs hot, keeping more context when there is headroom. The tuned value persists per user (~/.config/brocode) so every future session starts warm.
The same Learner is the natural home for future adaptive knobs (tool-description budget, model-routing thresholds, parallel fan-out width) — each one gets an Observe* call and a clamped nudge, all persisted in one JSON file.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultPath ¶
func DefaultPath() string
DefaultPath returns ~/.config/brocode/learn.json (matching BroCode's other global-state files). It returns "" if the home dir is unavailable, in which case the caller should use an in-memory-only Learner.
func ExtractErrorPattern ¶ added in v0.1.32
ExtractErrorPattern simplifies and normalizes a compiler/test error string into a compact pattern.
func FormatPlaybookHint ¶ added in v0.1.32
FormatPlaybookHint formats a discovered playbook into a high-value prompt hint.
Types ¶
type Config ¶
type Config struct {
CompactionRatio float64 `json:"compaction_ratio"`
// Rolling stats (diagnostic + future tuning). Kept across sessions so the
// learner has history to converge from on the very first turn of a new day.
Turns int `json:"turns"`
SumUtil float64 `json:"sum_util"` // sum of per-turn utilizations
OverflowHits int `json:"overflow_hits"` // turns that hit the hard fitMessages guard
}
Config is the persisted, self-tuning state.
type Learner ¶
type Learner struct {
// contains filtered or unexported fields
}
Learner owns the adaptive config and persists it to disk. It is safe for concurrent use (the engine may observe from the turn goroutine while the UI reads stats).
func NewLearner ¶
NewLearner loads the config from path (or seeds defaults when missing). A path of "" yields an in-memory learner that still adapts within the process but never persists.
func (*Learner) CompactionRatio ¶
CompactionRatio returns the current tuned trigger threshold.
func (*Learner) ObserveOverflow ¶
func (l *Learner) ObserveOverflow()
ObserveOverflow marks a turn that hit the hard fitMessages guard (the window was genuinely too big even after compaction) — an even stronger signal to compact earlier next time.
func (*Learner) ObserveTurn ¶
ObserveTurn feeds one finished turn's context utilization (0..1+) into the learner. It nudges the compaction ratio toward the target band and persists (throttled to every 5 turns to avoid disk thrash).
Source Files