Documentation
¶
Overview ¶
Package tune works out, from what one user's agents really did, the settings that would have cost that user the fewest tokens: when each agent compacts its conversation, and how long Claude Code keeps its prompt cache. Every setting is tried on the user's own calls of the period, replayed one by one: the same prompts growing by the same amounts at the same times, compacted or read from the cache as the setting would have had them. What it says is so for this user and this agent only; another's habits give other answers.
Tokens are weighed by what the vendor charges for them against a plain input token, which is what a subscription's quota and an API bill both count: a cache read is a tenth of one, a cache write a quarter more (two for an hour's), an output token several.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Call ¶
type Call struct {
Time time.Time
Stream string // the conversation it is in: its file, a subagent's its own
Sub bool // a subagent's, a workflow's or a helper's, not the main conversation
Model string // as the agent asked for it, without [1m]
Long bool // asked for with the long context ([1m])
Prompt int // the prompt, all of it: input, cache read and cache write
Out int
Wrote int // of Prompt, written to the cache
Wrote1 int // of Wrote, kept an hour
// Compact is how long a compaction kept the agent waiting, in ms, on the
// call its file tells it with; 0 when none or the agent doesn't say
Compact int64
}
Call is one model call of an agent's conversation, as tune replays it.
type CompactOpts ¶
type CompactOpts struct {
Min, Max int
Step int
// Reserve is what the agent keeps free under the window: Claude Code
// compacts at the window less its output's room (167K of a 200K one,
// 967K of 1M); Codex at the limit itself
Reserve int
// Current is the window it runs with now; 0 when nothing sets one,
// and tune takes it from where its compactions were made
Current int
// Window is the model's whole window, the most a setting can give; 0
// when it isn't known, and then nothing short of Max caps a setting
// (zhemu on Discord: a 1M model magpie had no window for was offered
// no more than the largest prompt it had been sent, 412K)
Window int
}
CompactOpts says how an agent compacts: the windows it takes, and how far below the window it sets it really compacts.
type Compaction ¶
type Compaction struct {
Model string `json:"model"`
Current int `json:"current"` // the window it runs with
Window int `json:"window"` // the model's, which caps a setting
Best int `json:"best"`
Cost float64 `json:"cost"` // with Current, the period's weighted tokens
Low float64 `json:"low"` // with Best
Curve []Point `json:"curve"`
Facts Facts `json:"facts"`
// with compactions timed, the seconds they would have waited: with
// Current, and with Best
Wait int `json:"wait,omitempty"`
WaitBest int `json:"wait_best,omitempty"`
// with compactions timed, the cheapest window and its wait, which
// the advice passes over when it would wait longer than now
Cheapest int `json:"cheapest,omitempty"`
WaitCheapest int `json:"wait_cheapest,omitempty"`
}
Compaction is the window advised for one model of an agent.
func Compact ¶
func Compact(cs []Call, o CompactOpts) *Compaction
Compact advises the window to compact at for one model's calls of an agent, or nil when there is too little to go on: a few calls, or none that ever came near a window.
type Facts ¶
type Facts struct {
Calls int `json:"calls"`
Streams int `json:"streams"`
Compacts int `json:"compacts,omitempty"` // seen in the period
Peak int `json:"peak,omitempty"` // the median prompt a compaction was made at
After int `json:"after,omitempty"` // the median prompt right after one
Growth int `json:"growth,omitempty"` // the median a prompt grows by from one call to the next
Rework int `json:"rework,omitempty"` // what a compaction costs to read back, in the calls after it
Long float64 `json:"long,omitempty"` // of the calls, the share that reached past the window advised
Quick float64 `json:"quick,omitempty"` // of the gaps between calls, the share under 5 minutes
Pause float64 `json:"pause,omitempty"` // between 5 minutes and an hour
Away float64 `json:"away,omitempty"` // over an hour
Hour float64 `json:"hour,omitempty"` // of the cache writes, the share kept an hour
Sessions int `json:"sessions,omitempty"` // streams that reached a compaction
// Took is the median seconds a compaction kept the agent waiting, of
// Timed compactions its files timed; 0 when fewer than minTimed were
Took int `json:"took,omitempty"`
Timed int `json:"timed,omitempty"`
}
Facts are what a replay found of the user's habits, said beside the advice so it reads as theirs.
type Point ¶
type Point struct {
Value int `json:"value"`
Cost float64 `json:"cost"`
Compacts int `json:"compacts"`
Wait int `json:"wait,omitempty"`
}
Point is one setting tried and what the period would have cost with it, and how many compactions it would have made there: what a window over the leanest buys, said beside what it costs (#1860). Wait is the seconds those compactions would have kept the user waiting, when the agent's files time them (Facts.Took).
type TTL ¶
type TTL struct {
Current string `json:"current"` // 5m or 1h
Best string `json:"best"`
Cost float64 `json:"cost"`
Low float64 `json:"low"`
Short float64 `json:"short"` // with 5m
Hour float64 `json:"hour"` // with 1h
Facts Facts `json:"facts"`
}
TTL is the cache lifetime advised for one part of Claude Code's calls: its main conversation, or what runs beside it (subagents, workflows).
type Weights ¶
type Weights struct {
Read, Write, Write1h, Out float64
}
Weights is what a vendor charges for each kind of token against one of plain input.
func WeightsFor ¶
WeightsFor is the weights of the vendor of a model: Anthropic charges a quarter more to write its cache (twice for an hour's) and a tenth to read it; OpenAI writes it at the input's price and reads it at a tenth.
Source Files