Documentation
¶
Overview ¶
Package savings implements the append-only token-savings ledger (lean-ctx context-intelligence Phase 5). Every token-reduction event — a compressed `view` read, an unchanged-re-read F-reference, an RTK shell-output filter — is recorded as one JSON line in <data-dir>/savings/ledger.jsonl so the savings are measurable via `pando gain`, the `pando_stats` MCP tool and the Token Optimization settings widget.
The ledger is strictly observational and fail-safe: recording never blocks the agent hot path (entries are handed to a background writer and dropped if its buffer is full) and any I/O error is swallowed. It is on by default and turned off by TokenOptimization.SavingsLedgerDisabled.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Close ¶
func Close()
Close flushes and stops the background writer. Safe to call when never started.
func LedgerPath ¶
LedgerPath returns the ledger file path for a data directory.
func Record ¶
func Record(e Entry)
Record appends a saving to the ledger unless the ledger is disabled. It never blocks: if the background writer is saturated the entry is dropped. Saved is derived from baseline-actual so callers need not set it.
func TokensFromChars ¶
TokensFromChars converts a character/byte count into an estimated token count using the same ~4-chars-per-token heuristic Pando uses elsewhere, so totals are consistent across sources.
Types ¶
type DayTotal ¶
type DayTotal struct {
Day string `json:"day"` // YYYY-MM-DD
Events int `json:"events"`
Saved int `json:"saved_tokens"`
Baseline int `json:"baseline_tokens"`
}
DayTotal aggregates the savings of one calendar day (UTC).
type Entry ¶
type Entry struct {
TS time.Time `json:"ts"`
Source Source `json:"source"`
Detail string `json:"detail,omitempty"`
BaselineTokens int `json:"baseline_tokens"`
ActualTokens int `json:"actual_tokens"`
Mode string `json:"mode,omitempty"`
Saved int `json:"saved"`
}
Entry is one ledger record. Token counts are estimated with a consistent chars→tokens heuristic (see TokensFromChars) so cross-source totals are comparable.
type Report ¶
type Report struct {
Events int `json:"events"`
BaselineTokens int `json:"baseline_tokens"`
ActualTokens int `json:"actual_tokens"`
SavedTokens int `json:"saved_tokens"`
ReductionPct float64 `json:"reduction_pct"`
BySource []SourceTotal `json:"by_source"`
ByDay []DayTotal `json:"by_day"`
Since *time.Time `json:"since,omitempty"`
}
Report is the aggregated view of the ledger.
func Summarize ¶
func Summarize(dataDir string, opts SummaryOptions) (Report, error)
Summarize reads and aggregates the ledger under dataDir. A missing ledger yields a zero-value report (no error). Malformed lines are skipped. Both the active ledger and its rotated ".1" backup are read so totals survive rotation.
func (Report) EstimatedUSD ¶
EstimatedUSD converts saved tokens to an estimated dollar amount given a price per million tokens. Purely indicative — actual cost depends on the model.
type Source ¶
type Source string
Source identifies which subsystem produced a saving.
const ( // SourceView is a compressed `view` read (signatures/map/auto). SourceView Source = "view" // SourceDedup is an unchanged-re-read F-reference (or changed-window diff). SourceDedup Source = "dedup" // SourceBash is an RTK-style shell-output filter application. SourceBash Source = "bash" // SourceSearch is a compacted code/search result. SourceSearch Source = "search" )
type SourceTotal ¶
type SourceTotal struct {
Source Source `json:"source"`
Events int `json:"events"`
Baseline int `json:"baseline_tokens"`
Actual int `json:"actual_tokens"`
Saved int `json:"saved_tokens"`
}
SourceTotal aggregates the savings of one source.
type SummaryOptions ¶
type SummaryOptions struct {
// Since, when non-zero, ignores entries older than it.
Since time.Time
}
SummaryOptions filters the aggregation.
Source Files