Compressor

compressor

WinnowCompressor: the headroom.compressor entry point.

Headroom's content router hands a selected external compressor one block of tool output plus a query (the user's prompt, enriched with the triggering tool call's args), and expects a pure-data :class:CompressOutput back. This class implements that contract (headroom/transforms/compressor_registry.py) with a task-conditioned line pruner:

1. Gate — pass through (compressed=False) without touching the model when there is no query (no task, no basis for relevance), when the block is too short for markers to pay off, when it is too long for the model to score within the latency budget (Headroom's own compressors handle it instead), or when the backend is known to be unavailable.
2. Score — ask the span backend which characters matter for the query.
3. Protect — keep failure lines, tracebacks, neighbours and edges no matter what the model said (:mod:headroom_winnow.selection).
4. Render — replace each dropped run with a <<ccr:HASH N_lines_offloaded>> marker and return hash -> original in recoverable so the router can persist it for retrieval.

The router is already fail-open (it falls back to its built-in path when an external raises, returns empty output, or grows the block), but we never rely on that: compress does not raise, and every "not worth it" outcome is an explicit passthrough so the router's own compressors still get their turn.

WinnowSettings(min_lines=40, context_lines=2, edge_lines=2, min_savings=0.2, max_tokens=None) dataclass

Pruning knobs. Defaults are recall-first.

Attributes:

Name	Type	Description
min_lines	int	Blocks with fewer lines pass through untouched.
context_lines	int	Neighbours kept on each side of every kept line.
edge_lines	int	Lines always kept at the start and at the end.
min_savings	float	Minimum fraction of tokens saved; below it we pass through.
max_tokens	int | None	Blocks larger than this (query included, Headroom's token estimate) pass through without running the model. None uses the backend's max_input_tokens when it has one, else no limit.

WinnowCompressor(backend=None, settings=None)

Task-conditioned line pruner implementing Headroom's Compressor protocol.

Parameters:

Name	Type	Description	Default
backend	SpanBackend | None	Span backend. Defaults to the one :func:~headroom_winnow.backends.make_backend picks ($HEADROOM_WINNOW_BACKEND); constructing it loads nothing, so discovery stays cheap.	None
settings	WinnowSettings | None	Pruning knobs.	None

descriptor property

Return this compressor's static capability metadata.

compress(inp)

Prune inp.content against inp.query; never raises.

Parameters:

Name	Type	Description	Default
inp	CompressInput	The block, its MIME type and the task query.	required

Returns:

Type	Description
CompressOutput	A pruned result with markers and a recovery map, or a passthrough
CompressOutput	(compressed=False, original content) when pruning is skipped.