Skip to main content

Overview

SelfMoASeq (Self-MoA-Seq: Sequential Self-Mixture of Agents) is an ensemble method that generates multiple candidate responses from a single high-performing model and synthesizes them sequentially using a sliding window approach. This keeps context within bounds while leveraging diversity across samples for a high-quality final output.
  • Phase 1: Generate num_samples responses using a proposer agent. The proposer’s conversation is reset before every sample, so each sample is an independent draw that never sees the earlier ones.
  • Phase 2: Aggregate responses in windows with an aggregator agent, biasing toward the current best. The aggregator’s conversation is also reset before every window.
  • Phase 3: Iterate until all samples are processed or max_loops is reached.
Both agents are built with output_type="final", so each sample and each aggregation is the agent’s final answer rather than its full transcript.
SelfMoASeq emits OpenTelemetry spans when it is constructed and on each run() call. See Telemetry to turn tracing off.

Installation

Attributes

str
default:"SelfMoASeq"
Human-readable name for this orchestrator. Accepted but not currently stored on the instance
str
default:"Self-MoA-Seq: Sequential Self-Mixture of Agents"
Short description of the orchestrator. Accepted but not currently stored on the instance
str
default:"gpt-5.4"
Base model used when specific proposer/aggregator models are not provided
float
default:"0.7"
Sampling temperature for the proposer; must be in [0, 2]. The aggregator always runs at temperature 0.0
int
default:"6"
Total window size used during aggregation. Must be at least 2.
int
default:"3"
Slots held back from each window. Each aggregation step takes window_size - reserved_slots new samples and prepends the current best output. Must be less than window_size.
int
default:"10"
Maximum aggregation loops. Must be at least 1. When the limit is hit, any samples not yet aggregated are left out of final_output.
int
default:"2000"
Token budget to consider for downstream consumers. Not enforced internally.
int
default:"30"
Number of candidate responses to generate overall; must be at least 2
bool
default:"True"
Stored on the instance but not read. Logging is controlled by verbose
str
default:"INFO"
Stored on the instance but not read
bool
default:"True"
When True, logs progress and the final result through loguru, and turns on verbose output for the proposer and aggregator agents. When False, nothing is logged
Optional[str]
default:"None"
Overrides the model for the proposer agent; falls back to model_name if not provided
Optional[str]
default:"None"
Overrides the model for the aggregator agent; falls back to model_name if not provided
int
default:"3"
Stored and range-validated (must be at least 0) at construction time. Not currently applied to retry any operation.
float
default:"1.0"
Stored and range-validated (must be at least 0) at construction time. Not currently applied to retry any operation.
float
default:"2.0"
Stored and range-validated (must be at least 1) at construction time. Not currently applied to retry any operation.
float
default:"60.0"
Stored and range-validated (must be at least retry_delay) at construction time. Not currently applied to retry any operation.
Dict[str, Any]
default:"{}"
Accepted by the constructor but not currently stored or forwarded to the proposer/aggregator agents.
Optional[float]
default:"None"
Top-p (nucleus) sampling parameter passed to both the proposer and the aggregator. Left unset when None.
Raises:
  • ValueError for invalid parameter ranges (e.g., window_size < 2, reserved_slots >= window_size, temperature outside [0, 2], etc.)

Methods

run()

Execute the full Self-MoA-Seq process: sample generation, sliding-window aggregation, and final synthesis.
Parameters:
  • task (str): The task to process; must be a non-empty string
Returns: A dictionary with the following keys: Raises:
  • ValueError if task is not a non-empty string
  • Propagates any exceptions from generation/aggregation without retrying

get_metrics()

Get a snapshot of the internal metrics counters.
Returns: A copy of the current metrics dictionary
total_samples_generated and total_aggregations accumulate across every run() on the same instance. execution_time_seconds holds the duration of the latest run. total_tokens_used is not updated and stays 0.

to_dict()

Inherited from SerializableMixin. Serializes the instance’s __dict__ into a JSON-friendly dictionary (callables are represented by name/docstring, nested objects with their own to_dict() are recursed into, non-serializable values are stringified).
Returns: A dictionary representation of the instance’s attributes

Internal Methods

Methods prefixed with _ are internal but documented here for completeness.

_generate_samples()

Generate num_samples candidate responses using the proposer agent. The proposer’s conversation is reset before each sample.
Parameters:
  • task (str): The task description to pass to the proposer agent
  • num_samples (int): Number of samples to generate
Returns: The generated samples in generation order

_format_aggregation_prompt()

Create the prompt that the aggregator agent will receive for a given window.
Parameters:
  • task (str): The original task string
  • samples (List[str]): Window of candidate responses to synthesize
  • best_so_far (Optional[str]): Previously synthesized best output, if any
Returns: Aggregation prompt text to be sent to the aggregator agent

_aggregate_window()

Aggregate a window of samples using the aggregator agent, biased by best_so_far. The aggregator’s conversation is reset before each call.
Parameters:
  • task (str): The original task string
  • window_samples (List[str]): Current window, typically [best_output] + current_window
  • best_so_far (Optional[str]): Current best aggregation to bias the synthesizer
Returns: The synthesized output for this window

Usage Examples

Basic Usage

Medical Diagnosis with High Sample Count

This example demonstrates using SelfMoASeq for a complex medical diagnosis task with a larger number of samples for comprehensive analysis.

Creative Writing with Different Models

This example shows how to use different models for the proposer and aggregator, with a creative writing task.

Retry Configuration

The constructor accepts max_retries, retry_delay, retry_backoff_multiplier, and retry_max_delay, and validates them in setup() (e.g. max_retries >= 0, retry_backoff_multiplier >= 1, retry_max_delay >= retry_delay). These values are stored on the instance but are not currently used to retry run(), _generate_samples(), or _aggregate_window() — exceptions from those methods are logged and re-raised immediately without a retry loop.

When to Choose SelfMoASeq

Choose SelfMoASeq when you need:
  • High-quality outputs that benefit from multiple perspectives
  • To work within context length constraints
  • Reliable, production-ready ensemble methods
  • Fine-grained control over the generation and synthesis process
  • Comprehensive observability and error handling
For simpler tasks or when context limits are not a concern, consider using single-agent approaches or other ensemble methods like MixtureOfAgents for more straightforward aggregation strategies.

Source Code

View the source code on GitHub