Skip to main content

Module agent_ops

Module agent_ops 

Source
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-only therefore 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 --filter predicate grammar
  • reduce — 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§

pub use filter::Filter;
pub use filter::FilterOp;

Modules§

filter
Path addressing and the --filter predicate grammar.

Structs§

AgentOps
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.