pyagent-compress API Reference

pyagent_compress.compressor.MessageCompressor

Compress inter-agent messages by removing filler and extracting key sentences.

Parameters:

Name	Type	Description	Default
target_ratio	float	Target compression ratio (0.3 = keep 30% of tokens).	0.5
min_sentence_length	int	Minimum characters for a sentence to be kept.	20
remove_filler	bool	Whether to strip filler phrases.	True

compress(text)

Compress a message text.

Strategy: 1. Remove filler phrases 2. Split into sentences 3. Score sentences by information density 4. Keep top sentences until target ratio met

pyagent_compress.compressor.CompressionResult dataclass

Result of message compression.

Attributes:

Name	Type	Description
original	str	The original text.
compressed	str	The compressed text.
original_tokens	int	Estimated original token count.
compressed_tokens	int	Estimated compressed token count.
savings_pct	float	Percentage of tokens saved (0-1).

pyagent_compress.pruner.AgentPruner

Detect and flag non-contributing agents for removal.

Scores each agent's contribution based on: - Unique information (not repeated from other agents) - Response diversity (different from own previous responses) - Task relevance (overlap with original task keywords)

Parameters:

Name	Type	Description	Default
min_contribution	float	Minimum contribution score (0-1) to keep an agent.	0.3
window_size	int	Number of recent messages to analyze per agent.	5

score_agents(messages, task)

Score each agent's contribution from message history.

should_prune(scores)

Return agent names that should be pruned (below min contribution).

pyagent_compress.pruner.InteractionPruner

Detect early consensus and skip remaining communication rounds.

Analyzes agent outputs to determine if consensus has been reached, allowing patterns like Debate or Voting to terminate early.

Parameters:

Name	Type	Description	Default
consensus_threshold	float	Minimum similarity between agent outputs to consider consensus reached (0-1).	0.7
min_rounds	int	Minimum rounds before early termination is allowed.	1

has_consensus(outputs, current_round)

Check if agents have reached consensus.

Parameters:

Name	Type	Description	Default
outputs	list[str]	Current round's outputs from all agents.	required
current_round	int	The current round number (1-indexed).	required

Returns:

Type	Description
bool	True if consensus is reached and we can stop early.

pyagent_compress.pruner.ContributionScore dataclass

How much an agent is contributing to the conversation.

pyagent_compress.budget.TokenBudget dataclass

Manage token budgets across a multi-agent workflow.

Parameters:

Name	Type	Description	Default
workflow_limit	int	Total token limit across all agents.	100000
per_agent_limit	int	Default per-agent token limit.	20000
strict	bool	If True, raises BudgetExceededError on limit violations.	True

consume(agent_name, tokens)

Record token consumption for an agent.

Parameters:

Name	Type	Description	Default
agent_name	str	The consuming agent's name.	required
tokens	int	Number of tokens consumed.	required

register_agent(name, limit=None)

Register an agent with an optional custom limit.

remaining(agent_name=None)

Get remaining tokens for an agent or the whole workflow.

summary()

Return a summary of all agent budgets.

pyagent_compress.budget.AgentBudget dataclass

Budget tracking for a single agent.

consume(tokens, strict=True)

Consume tokens from budget.

Parameters:

Name	Type	Description	Default
tokens	int	Number of tokens consumed.	required
strict	bool	If True, raises BudgetExceededError. If False, just tracks.	True

pyagent_compress.budget.BudgetExceededError

Bases: Exception

Raised when a token budget is exceeded.

pyagent_compress.middleware.CompressMiddleware

Middleware that wraps agents with automatic output compression.

Usage

middleware = CompressMiddleware(target_ratio=0.5) compressed_agent = middleware.wrap(my_agent)

Parameters:

Name	Type	Description	Default
compressor	MessageCompressor | None	Optional MessageCompressor. Created with defaults if None.	None
budget	TokenBudget | None	Optional TokenBudget for workflow-wide tracking.	None
target_ratio	float	Target compression ratio (used if compressor not provided).	0.5

wrap(agent)

Wrap an agent with compression.

wrap_all(agents)

Wrap multiple agents.

pyagent_compress.middleware.CompressedAgent

Bases: Agent

Agent wrapper that compresses output messages.

Parameters:

Name	Type	Description	Default
agent	Agent	The original agent.	required
compressor	MessageCompressor	MessageCompressor instance.	required
budget	TokenBudget | None	Optional TokenBudget for tracking.	None

run(messages) async

Run the agent and compress the output.