Documentation
¶
Overview ¶
Package stats provides token savings tracking for grepai commands. It records each search and trace invocation locally and computes savings estimates compared to a traditional grep-based workflow.
Index ¶
Constants ¶
const CostPerMTokenUSD = 5.00
CostPerMTokenUSD is the reference cost per million input tokens used for estimating USD savings on cloud providers (conservative middle-ground rate).
const DefaultChunkTokens = 512
DefaultChunkTokens is the default chunk size in tokens used for grep estimation. Mirrors indexer.DefaultChunkSize.
const GrepExpansionFactor = 3
GrepExpansionFactor is the multiplier applied to result count when estimating how many tokens a grep-based workflow would have consumed. A factor of 3 accounts for grep returning full file sections rather than isolated chunks.
const LockFileName = "stats.json.lock"
LockFileName is the name of the lock file used for safe concurrent writes.
const MinGrepTokens = 50
MinGrepTokens is the minimum grep-equivalent token estimate when result count is zero, to avoid division-by-zero in savings percentage.
const StatsFileName = "stats.json"
StatsFileName is the name of the NDJSON stats file inside .grepai/.
Variables ¶
This section is empty.
Functions ¶
func GrepEquivalentTokens ¶
GrepEquivalentTokens estimates how many tokens a grep-based workflow would have consumed for a given number of results.
func IsCloudProvider ¶
IsCloudProvider returns true when the given provider name has a token cost.
Types ¶
type CommandType ¶
type CommandType = string
CommandType represents the type of grepai command that was executed.
const ( Search CommandType = "search" TraceCallers CommandType = "trace-callers" TraceCallees CommandType = "trace-callees" TraceGraph CommandType = "trace-graph" )
type DaySummary ¶
type DaySummary struct {
Date string `json:"date"`
QueryCount int `json:"query_count"`
OutputTokens int `json:"output_tokens"`
GrepTokens int `json:"grep_tokens"`
TokensSaved int `json:"tokens_saved"`
}
DaySummary holds per-day aggregated stats for the --history view.
func HistoryByDay ¶
func HistoryByDay(entries []Entry) []DaySummary
HistoryByDay groups entries by calendar day (UTC) and returns a slice sorted in descending order (most recent first).
type Entry ¶
type Entry struct {
Timestamp string `json:"timestamp"` // RFC3339 UTC
CommandType string `json:"command_type"` // search | trace-callers | trace-callees | trace-graph
OutputMode string `json:"output_mode"` // full | compact | toon
ResultCount int `json:"result_count"`
OutputTokens int `json:"output_tokens"` // estimated tokens in grepai output
GrepTokens int `json:"grep_tokens"` // estimated tokens for grep equivalent
}
Entry represents a single recorded command event.
type OutputMode ¶
type OutputMode = string
OutputMode represents the output format used for the command result.
const ( Full OutputMode = "full" Compact OutputMode = "compact" Toon OutputMode = "toon" )
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder appends stat entries to the local NDJSON stats file.
func NewRecorder ¶
NewRecorder creates a Recorder that writes to the stats file inside projectRoot.
type Summary ¶
type Summary struct {
TotalQueries int `json:"total_queries"`
OutputTokens int `json:"output_tokens"`
GrepTokens int `json:"grep_tokens"`
TokensSaved int `json:"tokens_saved"`
SavingsPct float64 `json:"savings_pct"`
CostSavedUSD *float64 `json:"cost_saved_usd"`
ByCommandType map[string]int `json:"by_command_type"`
ByOutputMode map[string]int `json:"by_output_mode"`
}
Summary is the aggregated view of all recorded entries.
Source Files