Documentation
¶
Overview ¶
Package headroom reduces the token cost of voice search_memory tool results before they are injected into the Gemini Live context window. It is a native Go port of the transferable ideas in https://github.com/chopratejas/headroom — see docs/adr/038-headroom-token-compression.md.
Two mechanisms, both deterministic (no model call):
LossyCompress — markdown-noise-aware truncation of a long Content body to a character budget, on a word boundary. The full body stays retrievable by ID (the existing item-fetch path is the reversible "fetch original" contract, so no separate cache is needed).
Factor — hoist fields that are constant across every row out of the per-row JSON into a shared header, so they are paid for once.
Both are opt-in: with a zero/empty Config the input passes through unchanged.
Headroom's third mechanism — AdaptiveK (Kneedle/SimHash near-duplicate row collapse) — was ported, tested live, and removed: on the X-Ray corpus it omitted zero rows (cells are genuinely distinct), and dropping result rows risks hiding a voice mishear-disambiguation candidate. See ADR-038.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LossyCompress ¶
LossyCompress lossily compresses a single content body: it strips token-wasteful markdown noise and truncates the result to maxChars on a word boundary. It is lossy by design — markdown structure is discarded and the tail is cut — so the result is a compact stand-in, not a faithful copy; the full original stays retrievable by id (the reversible CCR contract). It reports whether anything was dropped (by stripping past maxChars, or by the truncation itself). maxChars <= 0 returns body unchanged.
Stripping is conservative — it removes structure that costs tokens but carries little meaning the model needs from a search snippet:
- image embeds  → alt text only
- inline links [text](url) → text only
- fenced code ```lang\n…\n``` → «code» placeholder
- heading/quote/list markers at line start
- collapsed runs of whitespace
It deliberately does NOT touch inline emphasis or the words themselves.
Types ¶
type Config ¶
type Config struct {
// MaxContentChars caps each row's Content after markdown-noise stripping.
// 0 disables the LossyCompress step (content passes through whole).
MaxContentChars int
}
Config tunes compression. The zero value is a no-op (CompressRows returns the input rows unchanged), so callers can gate the feature with a single flag.
type Result ¶
type Result struct {
Rows []Row
// Constant holds fields whose value was identical across every row. Keys
// are a subset of {"kind","scope"}. Empty when nothing was uniform. A
// factored field is blanked on each Row so the caller's serializer omits it
// (the value lives once in Constant instead).
Constant map[string]string
}
Result is the output of CompressRows: the (possibly compressed) rows, plus the fields that were constant across all of them and so factored out.
func CompressRows ¶
CompressRows lossy-compresses each row's Content to the budget, then factors uniform fields. With a zero Config it returns the rows unchanged and an empty Result.Constant.
Source Files