Expand description
Agent-native payload reduction applied to the JSON envelope before it is written.
§Why this exists
docsrs-cli is consumed by LLM agents. Forcing an agent to pipe stdout through
jaq/sed to reach two fields burns tokens on data the agent never wanted. The
reduction knobs live in the binary so the cut happens before the envelope is
handed to the caller.
§Fixed application order
filter → sort-by → dedupe-by → max-items → select → count-only →
truncate-content → max-output-bytes. The order is a contract, and each step
sits where it does for a reason:
- sorting before deduplication decides which duplicate survives, so the surviving row is the ranked one rather than whichever came first upstream;
- limiting after deduplication stops a duplicate from consuming a slot the caller wanted spent on a distinct element;
- limiting before projection avoids projecting rows that are about to be cut;
--count-onlytherefore counts what survived filtering, deduplication and the limit — never the raw upstream total.
Sorting is what makes limiting meaningful: --max-items without an order returns
an arbitrary slice of the matches, which is a worse answer than the full set.
§Result-array location
Reduction targets the result array inside envelope.data. The array is located by
probing RESULT_ARRAY_KEYS in order, then falling back to the first array of
objects on the payload. When data is itself an array it is used directly; when no
array exists at all, projection applies to the data object itself.
§Failure envelopes
An envelope with ok: false is passed through byte-for-byte. --filter never
silences a failure — a filtered-away error would look like an empty success.
§Module layout
filter— dotted-path addressing and the--filterpredicate grammarreduce— the envelope transformations (locate, dedupe, project, truncate)- this module — the plan (
AgentOps) and the order in which it is applied
§Examples
use docsrs_cli::agent_ops::AgentOps;
use docsrs_cli::cli::AgentArgs;
let args = AgentArgs {
select: vec!["name".to_string()],
..AgentArgs::default()
};
let ops = AgentOps::from_args(&args).expect("valid knobs");
assert!(ops.is_active());Re-exports§
Modules§
- filter
- Path addressing and the
--filterpredicate grammar.
Structs§
- Agent
Ops - Resolved set of agent-native reduction knobs for one invocation.
Constants§
- EMITTED_
COUNT_ KEYS - Sibling integer keys that count the result array and must follow it when it shrinks.
- RESULT_
ARRAY_ KEYS - Keys probed, in order, when locating the result array inside
envelope.data.