Aggregators¶

Aggregators combine a list of agent Response objects (for example from broadcast()) into a single result. They are useful after broadcast or scatter-gather when you need a single answer or summary from many responses.

Unless you pass include_failures=True, every aggregator silently skips responses with success=False.

Categorical¶

majority_vote() — Returns (winner, confidence) where confidence is the fraction of votes for the winner. Response text is stripped and compared case-insensitively.

When to use: Short categorical answers (e.g. yes/no, class labels, single-word choices). Use when you want consensus and a confidence score.

Text¶

concat() — Joins all response texts with a configurable separator (default newline).

When to use: You need one combined string of all answers (e.g. for logging, for feeding into a reduce prompt, or for downstream processing).

Quality selection¶

best_of() — Returns the single Response with the highest score_fn(response) value. You must provide a callable that maps each response to a float (e.g. length, a quality metric).

top_k() — Returns the k highest-scoring responses in descending order.

When to use: When you have a scoring function (e.g. length, readability, model score) and want the best one or the top k.

Structured data¶

structured_merge() — Parses each response text as JSON and merges into a flat list. JSON arrays are flattened; other values are appended. Returns (merged_list, errors) where errors is a list of {agent_index, error} for parse failures.

When to use: Agents return JSON (e.g. lists of items); you want one merged list and optional error reporting.

Numeric¶

statistics() — Computes summary statistics over numeric values. If extract_fn is None, response text is converted to float. Returns a dict with keys mean, std, median, min, max.

When to use: Responses are numbers (or you have an extract_fn to get a number from each response); you want mean, std, median, min, max.

Diagnostics¶

failure_report() — Returns a dict with total, success_count, failure_count, and failures (list of {agent_index, error}). Does not filter by success; use to inspect which agents failed and why.

Usage with broadcast¶

To broadcast the same prompt to a subset of agents (e.g. all except one) and then aggregate in Python:

Build a sub-pool with select() (e.g. exclude one index).
Call broadcast() with the sub-pool and prompt.
Apply one or more aggregators to the returned list of responses.

Example (minimal):

from aurora_swarm import VLLMPool, parse_hostfile
from aurora_swarm.patterns.broadcast import broadcast
from aurora_swarm.aggregators import majority_vote, concat

endpoints = parse_hostfile("agents.hostfile")
async with VLLMPool(endpoints, model="...") as pool:
    exclude_index = 0
    indices = [i for i in range(pool.size) if i != exclude_index]
    sub_pool = pool.select(indices)
    responses = await broadcast(sub_pool, "Answer with one word: yes or no. Is the sky blue?")
winner, confidence = majority_vote(responses)
combined = concat(responses, separator=" | ")

A full runnable example that broadcasts to all hosts except one and prints both majority_vote and concat results is in the repo: examples/broadcast_aggregators.py. Launch it with examples/broadcast_aggregators.sh <hostfile> (see the script and docstring for options).