Documentation
¶
Overview ¶
Package cost provides token-cost estimation for common AI model providers. Prices are per 1M tokens and are approximate — they may lag behind official pricing changes. Always verify with your provider's pricing page.
Index ¶
- Constants
- func AppendLedger(workDir string, entry LedgerEntry) error
- func Estimate(model string, inputTokens, outputTokens int) (usd float64, ok bool)
- func EstimateSessionCost(provider, model string, inputTokens, outputTokens int) float64
- func FormatCost(usd float64) string
- func FormatCostWithLimit(usd, limit float64) string
- func MonthlyTotal(workDir string) (float64, error)
- type LedgerEntry
- type ModelPricing
Constants ¶
const IdentityLocal = "local"
IdentityLocal is the sentinel for spend nobody authenticated: a bare `cloop run` from a terminal, or a hub with OIDC switched off.
A sentinel rather than an empty string because the two mean different things and a report has to tell them apart. "local" is a positive claim — this ran outside any identity system, and on a single-user install that is every row. Empty means the row predates attribution entirely (migration 0035) and cloop genuinely does not know. Folding the second into the first would put historical spend under a name, which is a guess dressed as a fact.
It cannot collide with a real identity: OwnerKey yields either a lowercased email (contains "@") or a "sub:"-prefixed subject, and "local" is neither.
const IdentityUnattributed = "(unattributed)"
IdentityUnattributed is how reports label rows with no identity at all.
Variables ¶
This section is empty.
Functions ¶
func AppendLedger ¶
func AppendLedger(workDir string, entry LedgerEntry) error
AppendLedger appends a cost entry to the project's SQLite database (primary) and to .cloop/costs.jsonl (legacy fallback for backward compatibility). It also mirrors to the global ledger at ~/.config/cloop/costs.jsonl.
func Estimate ¶
Estimate returns the estimated cost in USD for the given token counts. model is matched case-insensitively; unrecognised models return (0, false).
func EstimateSessionCost ¶
EstimateSessionCost returns the estimated cost in USD for the session. provider is used as a hint: "ollama" always returns 0 (local). For unknown models the function returns 0. Returns 0 when cost cannot be determined.
func FormatCost ¶
FormatCost returns a human-readable cost string, e.g. "$0.0042" or "$1.23".
func FormatCostWithLimit ¶
FormatCostWithLimit returns a human-readable cost string with optional limit info. e.g. "$0.0042 / $1.00" when limit > 0.
func MonthlyTotal ¶
MonthlyTotal returns the total estimated USD spent in the current calendar month.
Types ¶
type LedgerEntry ¶
type LedgerEntry struct {
Timestamp time.Time `json:"timestamp"`
TaskID int `json:"task_id"`
TaskTitle string `json:"task_title"`
Provider string `json:"provider"`
Model string `json:"model"`
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
ThinkingTokens int `json:"thinking_tokens,omitempty"`
EstimatedUSD float64 `json:"estimated_usd"`
// Identity attributes this spend to whoever initiated the run: an
// oidcauth OwnerKey (lowercased email, or "sub:<subject>"), or
// IdentityLocal. Empty means unattributed — see migration 0035.
Identity string `json:"identity,omitempty"`
}
LedgerEntry records the cost of one task execution.
func ReadLedger ¶
func ReadLedger(workDir string) ([]LedgerEntry, error)
ReadLedger reads all cost entries. When a SQLite state.db exists it reads from the costs table (primary). It then merges any JSONL-only entries that are not yet in the database (legacy migration path). Returns an empty slice (not an error) when neither source has data.
type ModelPricing ¶
ModelPricing holds the input and output cost in USD per 1M tokens.
Source Files