> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.

# SelfMoASeq

> Sequential Self-Mixture of Agents that generates multiple candidate responses and synthesizes them using a sliding window approach

## 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.
* **Phase 2**: Aggregate responses in windows with an aggregator agent, biasing toward the current best.
* **Phase 3**: Iterate until all samples are processed or `max_loops` is reached.

## Installation

```bash theme={null}
pip install -U swarms
```

## Attributes

<ParamField path="name" type="str" default="SelfMoASeq">
  Human-readable name for this orchestrator
</ParamField>

<ParamField path="description" type="str" default="Self-MoA-Seq: Sequential Self-Mixture of Agents">
  Short description of the orchestrator
</ParamField>

<ParamField path="model_name" type="str" default="gpt-5.4">
  Base model used when specific proposer/aggregator models are not provided
</ParamField>

<ParamField path="temperature" type="float" default="0.7">
  Sampling temperature for the proposer; must be in \[0, 2]
</ParamField>

<ParamField path="window_size" type="int" default="6">
  Total window size used during aggregation. Must be at least 2.
</ParamField>

<ParamField path="reserved_slots" type="int" default="3">
  Number of slots reserved for the current best (and possibly other fixed items) in the window. Must be less than `window_size`.
</ParamField>

<ParamField path="max_loops" type="int" default="10">
  Maximum aggregation loops. Must be at least 1.
</ParamField>

<ParamField path="max_tokens" type="int" default="2000">
  Token budget to consider for downstream consumers. Not enforced internally.
</ParamField>

<ParamField path="num_samples" type="int" default="30">
  Number of candidate responses to generate overall; must be at least 2
</ParamField>

<ParamField path="enable_logging" type="bool" default="True">
  Enable internal logging via `loguru`
</ParamField>

<ParamField path="log_level" type="str" default="INFO">
  Log level string
</ParamField>

<ParamField path="verbose" type="bool" default="True">
  If True, prints a run summary after completion
</ParamField>

<ParamField path="proposer_model_name" type="Optional[str]" default="None">
  Overrides the model for the proposer agent; falls back to `model_name` if not provided
</ParamField>

<ParamField path="aggregator_model_name" type="Optional[str]" default="None">
  Overrides the model for the aggregator agent; falls back to `model_name` if not provided
</ParamField>

<ParamField path="max_retries" type="int" default="3">
  Stored and range-validated (must be at least 0) at construction time. Not currently applied to retry any operation.
</ParamField>

<ParamField path="retry_delay" type="float" default="1.0">
  Stored and range-validated (must be at least 0) at construction time. Not currently applied to retry any operation.
</ParamField>

<ParamField path="retry_backoff_multiplier" type="float" default="2.0">
  Stored and range-validated (must be at least 1) at construction time. Not currently applied to retry any operation.
</ParamField>

<ParamField path="retry_max_delay" type="float" default="60.0">
  Stored and range-validated (must be at least `retry_delay`) at construction time. Not currently applied to retry any operation.
</ParamField>

<ParamField path="additional_kwargs" type="Dict[str, Any]" default="{}">
  Accepted by the constructor but not currently stored or forwarded to the proposer/aggregator agents.
</ParamField>

<ParamField path="top_p" type="Optional[float]" default="None">
  Top-p (nucleus) sampling parameter passed to the model. Left unset when `None`.
</ParamField>

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

```python theme={null}
def run(self, task: str) -> Dict[str, Any]
```

**Parameters:**

* `task` (str): The task to process; must be a non-empty string

**Returns:** A dictionary with the following keys:

| Key                 | Type             | Description                                  |
| ------------------- | ---------------- | -------------------------------------------- |
| `final_output`      | `str`            | The final synthesized best response          |
| `all_samples`       | `List[str]`      | All generated candidate responses            |
| `aggregation_steps` | `int`            | Number of aggregation iterations executed    |
| `metrics`           | `Dict[str, Any]` | Snapshot of performance metrics for this run |
| `task`              | `str`            | Echoes the original task                     |
| `timestamp`         | `str`            | ISO 8601 timestamp of completion             |

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

```python theme={null}
def get_metrics(self) -> Dict[str, Any]
```

**Returns:** A copy of the current metrics dictionary

### 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).

```python theme={null}
def to_dict(self) -> Dict[str, Any]
```

**Returns:** A dictionary representation of the instance's attributes

### Internal Methods

<Note>
  Methods prefixed with `_` are internal but documented here for completeness.
</Note>

### \_generate\_samples()

Generate `num_samples` candidate responses using the proposer agent.

```python theme={null}
def _generate_samples(self, task: str, num_samples: int) -> List[str]
```

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

```python theme={null}
def _format_aggregation_prompt(self, task: str, samples: List[str], best_so_far: Optional[str] = None) -> str
```

**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`.

```python theme={null}
def _aggregate_window(self, task: str, window_samples: List[str], best_so_far: Optional[str] = None) -> str
```

**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

```python theme={null}
from swarms import SelfMoASeq

# Initialize
moa_seq = SelfMoASeq(
    model_name="gpt-5.4",
    temperature=0.7,
    window_size=6,
    verbose=True,
    num_samples=4,
)

# Run
task = (
    "Describe an effective treatment plan for a patient with a broken rib. "
    "Include immediate care, pain management, expected recovery timeline, and potential complications to watch for."
)

result = moa_seq.run(task)
print(result)
```

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

```python theme={null}
from swarms import SelfMoASeq

# Initialize with medical-focused configuration
medical_moa = SelfMoASeq(
    model_name="claude-sonnet-4-6",
    temperature=0.8,  # Higher creativity for diverse medical perspectives
    window_size=8,    # Larger window for complex medical reasoning
    num_samples=12,   # More samples for comprehensive analysis
    max_loops=15,
    verbose=True,
    proposer_model_name="claude-sonnet-4-6",  # Use same model for consistency
    aggregator_model_name="claude-sonnet-4-6"
)

# Complex medical case
medical_case = """
Patient: 45-year-old female
Symptoms:
- Chest pain for 3 days, worse with deep breathing
- Shortness of breath
- Low-grade fever (100.2°F)
- Recent travel to Southeast Asia
- History of smoking (quit 5 years ago)

Vital signs: BP 140/90, HR 95, RR 22, O2 sat 94% on room air
Physical exam: Decreased breath sounds in right lower lobe, no JVD, no peripheral edema

Lab results pending: CBC, CMP, D-dimer, troponin
Chest X-ray: Small pleural effusion on right side

Provide a comprehensive differential diagnosis, immediate management plan,
and follow-up recommendations.
"""

result = medical_moa.run(medical_case)
print("Medical Diagnosis Analysis:")
print("=" * 50)
print(result["final_output"])
print(f"\nGenerated {len(result['all_samples'])} samples in {result['aggregation_steps']} iterations")
print(f"Execution time: {result['metrics']['execution_time_seconds']:.2f} seconds")
```

### Creative Writing with Different Models

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

```python theme={null}
from swarms import SelfMoASeq

# Initialize with different models for proposer and aggregator
creative_moa = SelfMoASeq(
    model_name="gpt-5.4",  # Base model (fallback)
    temperature=1.2,  # High creativity for writing
    window_size=4,    # Smaller window for focused synthesis
    num_samples=6,    # Moderate number of samples
    max_loops=8,
    verbose=True,
    proposer_model_name="claude-sonnet-4-6",      # Creative model for generation
    aggregator_model_name="gpt-5.4", # Efficient model for synthesis
    max_retries=2,
    retry_delay=0.5
)

# Creative writing prompt
writing_prompt = """
Write a compelling opening chapter for a science fiction novel set in 2150.
The story should involve:
- A protagonist who discovers they can manipulate time in small ways
- A mysterious organization that's been monitoring them
- A world where AI and humans coexist but tensions are rising
- An unexpected twist that challenges the reader's assumptions

Focus on:
- Strong character development
- Immersive world-building
- A hook that makes readers want to continue
- Balance between action and character moments
"""

result = creative_moa.run(writing_prompt)
print("Creative Writing Result:")
print("=" * 40)
print(result["final_output"])
print(f"\nWriting samples generated: {len(result['all_samples'])}")
print(f"Synthesis iterations: {result['aggregation_steps']}")
```

## 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](https://github.com/kyegomez/swarms/blob/master/swarms/structs/self_moa_seq.py)