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

# Method Templates

> Use built-in method templates (Self-Refine, Reflexion, LATS, MoA, Magentic-One) to implement proven agent patterns with minimal boilerplate.

QitOS provides **method templates** — ready-made Agent + Critic pairs that implement well-known agentic reasoning patterns. Each template packages a specialized state, critic, and agent so you can apply the pattern without rewriting the control loop.

## What is a method template?

A method template combines:

| Component  | Role                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| **State**  | A `StateSchema` subclass with pattern-specific fields (reflections, drafts, refinement counts)                    |
| **Critic** | A `Critic` subclass that drives the pattern's loop by returning `retry`, `continue`, or `stop` at the right times |
| **Agent**  | An `AgentModule` subclass with pattern-aware `build_system_prompt()`, `prepare()`, and `reduce()`                 |

The critic is the key: it evaluates each step and decides whether to retry (with an instruction patch), continue, or stop. The agent enriches prompts with pattern context (previous reflections, draft versions, critiques).

## Self-Refine

The **Self-Refine** pattern (Madaan et al. 2023) iterates: **generate → critique → refine** until quality meets a threshold or max refinements are reached.

### When to use it

* Text generation tasks where quality matters more than speed
* Summarization, translation, code generation with self-evaluation
* Any task where iterative improvement reliably produces better output

### Quick start

```python theme={null}
from qitos.recipes.self_refine import SelfRefineAgent, SelfRefineCritic

agent = SelfRefineAgent(llm=my_llm)
result = agent.run(
    task="Write a concise summary of the research paper on ...",
    critics=[SelfRefineCritic(max_refinements=3, quality_threshold=0.7)],
    max_steps=10,
    return_state=True,
)
print(result.state.draft)       # the refined output
print(result.state.final_result) # FINAL ANSWER if extracted
```

### How it works

1. **Generate**: The agent produces an initial draft.
2. **Critique**: `SelfRefineCritic` evaluates the draft quality using heuristic scoring (longer drafts after more refinements score higher; very short drafts are penalized). In production, replace heuristics with an LLM-based scorer.
3. **Refine**: If the score is below `quality_threshold` and refinements remain, the critic returns `retry` with an `instruction_patch` asking the agent to improve. The agent sees its previous draft and the critique in the next prompt.
4. **Accept**: When the score meets the threshold or `max_refinements` is reached, the critic returns `continue` or `stop`.

### SelfRefineCritic parameters

| Parameter           | Default | Description                                 |
| ------------------- | ------- | ------------------------------------------- |
| `max_refinements`   | 3       | Maximum refinement iterations               |
| `quality_threshold` | 0.7     | Minimum score (0.0–1.0) to accept the draft |

### SelfRefineState fields

| Field              | Type        | Description                  |
| ------------------ | ----------- | ---------------------------- |
| `draft`            | `str`       | Current draft text           |
| `refinement_count` | `int`       | Number of refinements so far |
| `max_refinements`  | `int`       | Refinement budget            |
| `critique_history` | `List[str]` | Accumulated critiques        |

### Customizing the quality scorer

The built-in critic uses heuristics. For production use, subclass and override `evaluate()`:

```python theme={null}
from qitos.recipes.self_refine import SelfRefineCritic, SelfRefineState
from qitos.engine.critic_result import CriticResult

class LLMScorerCritic(SelfRefineCritic):
    def evaluate(self, state, decision, results):
        refine_state = state if isinstance(state, SelfRefineState) else None
        if refine_state is None:
            return CriticResult(action="continue")

        # Call an LLM to score the draft
        score = self._llm_score(refine_state.draft, refine_state.task)

        if score < self.quality_threshold and refine_state.refinement_count < self.max_refinements:
            return CriticResult(
                action="retry",
                score=score,
                instruction_patch="Critique and improve the draft.",
                state_patch={"refinement_count": refine_state.refinement_count + 1},
            )
        return CriticResult(action="stop", score=score)
```

## Reflexion

The **Reflexion** pattern (Shinn et al. 2023) iterates: **act → evaluate → reflect → retry with memory**. On failure, the critic generates a verbal reflection stored in state and injected into future prompts.

### When to use it

* Debugging and error-correction tasks where the agent must learn from failures
* Tasks where different strategies should be tried after failure
* Multi-attempt problems (coding, reasoning) where reflections improve subsequent attempts

### Quick start

```python theme={null}
from qitos.recipes.reflexion import ReflexionAgent, ReflexionCritic

agent = ReflexionAgent(llm=my_llm)
result = agent.run(
    task="Debug the failing test in tests/test_module.py",
    critics=[ReflexionCritic(max_reflections=3)],
    max_steps=15,
    return_state=True,
)
print(result.state.reflections)    # list of verbal reflections
print(result.state.final_result)  # FINAL ANSWER if extracted
```

### How it works

1. **Act**: The agent takes an action toward the task.
2. **Evaluate**: `ReflexionCritic` checks for failures (errors, non-zero return codes, empty results).
3. **Reflect**: On failure, the critic generates a verbal reflection from the error context and returns `retry` with the reflection as an `instruction_patch`. The reflection is stored in `state.reflections`.
4. **Retry with memory**: The agent's `build_system_prompt()` includes all previous reflections, so the LLM can avoid repeating the same mistakes.

### ReflexionCritic parameters

| Parameter           | Default | Description                                         |
| ------------------- | ------- | --------------------------------------------------- |
| `max_reflections`   | 3       | Maximum reflection iterations before forced stop    |
| `success_threshold` | 0.6     | Minimum score to consider the trajectory successful |

### ReflexionState fields

| Field                 | Type        | Description                     |
| --------------------- | ----------- | ------------------------------- |
| `reflections`         | `List[str]` | Accumulated verbal reflections  |
| `reflection_count`    | `int`       | Number of reflections generated |
| `max_reflections`     | `int`       | Reflection budget               |
| `last_action_success` | `bool`      | Whether the last step succeeded |
| `attempt`             | `int`       | Current attempt number          |

## LATS

The **LATS** pattern (Zhou et al. 2023) applies Monte Carlo Tree Search to language agents: **select → expand → evaluate → backpropagate**. Failed trajectories generate reflections that guide future exploration away from similar mistakes.

### When to use it

* Tasks requiring systematic exploration of multiple solution paths
* Logic puzzles, coding challenges, and multi-step reasoning
* Problems where trying different strategies improves success

### Quick start

```python theme={null}
from qitos.recipes.lats import LATSAgent, LATSCritic

agent = LATSAgent(llm=my_llm)
result = agent.run(
    task="Solve the logic puzzle ...",
    critics=[LATSCritic(max_simulations=5, exploration_weight=1.41)],
    max_steps=20,
    return_state=True,
)
print(result.state.best_answer)    # best answer found
print(result.state.best_reward)    # best reward score
```

### How it works

1. **Simulate**: The agent takes an action, producing a result.
2. **Evaluate**: `LATSCritic` computes a reward from the result (errors → low reward, FINAL ANSWER → high reward).
3. **Reflect**: Failed paths (reward \< 0.3) generate reflections stored in `state.reflections`.
4. **Guide**: On retry, the critic provides an `instruction_patch` that includes reflections and UCB1-style exploration guidance.
5. **Stop**: When a path succeeds (reward ≥ success\_threshold) or `max_simulations` is reached.

### LATSCritic parameters

| Parameter            | Default | Description                     |
| -------------------- | ------- | ------------------------------- |
| `max_simulations`    | 5       | Maximum simulation iterations   |
| `exploration_weight` | 1.41    | UCB1 exploration constant (c)   |
| `success_threshold`  | 0.8     | Reward value for early stopping |

### LATSState fields

| Field                | Type        | Description                     |
| -------------------- | ----------- | ------------------------------- |
| `simulations_done`   | `int`       | Number of simulations completed |
| `max_simulations`    | `int`       | Simulation budget               |
| `exploration_weight` | `float`     | UCB1 c parameter                |
| `best_reward`        | `float`     | Best reward found so far        |
| `best_answer`        | `str`       | Answer from the best trajectory |
| `failed_paths`       | `List[str]` | Descriptions of failed paths    |
| `reflections`        | `List[str]` | Reflections from failures       |

## MoA (Mixture-of-Agents)

The **MoA** pattern (Wang et al. 2024) runs multiple proposers independently and synthesizes their outputs: **propose → aggregate**. Diversity of proposals improves quality, even when individual proposers are weaker models.

### When to use it

* Tasks benefiting from diverse perspectives or creative responses
* Analysis, evaluation, and synthesis problems
* Quality improvement through ensemble reasoning

### Quick start

```python theme={null}
from qitos.recipes.moa import MoAOrchestrator, MoACritic

agent = MoAOrchestrator(llm=my_llm)
result = agent.run(
    task="Evaluate the system architecture design for ...",
    critics=[MoACritic(proposer_count=3, max_rounds=1)],
    max_steps=15,
    return_state=True,
)
print(result.state.synthesis)  # the aggregated answer
```

### How it works

1. **Collect**: `MoACritic` checks if enough proposals have been gathered. If not, it returns `retry` with an instruction to gather more proposals.
2. **Aggregate**: When all proposals are collected, the critic prompts for synthesis.
3. **Output**: When synthesis is complete and meets the quality threshold, the critic returns `stop`.

For parallel proposer execution with actual multi-agent delegation, use `qitos.kit.patterns.moa.build_moa_system()`.

### MoACritic parameters

| Parameter           | Default | Description                         |
| ------------------- | ------- | ----------------------------------- |
| `proposer_count`    | 3       | Expected number of proposals        |
| `max_rounds`        | 1       | Maximum proposal-aggregation rounds |
| `quality_threshold` | 0.6     | Minimum score to accept synthesis   |

### MoARecipeState fields

| Field            | Type         | Description                                   |
| ---------------- | ------------ | --------------------------------------------- |
| `proposals`      | `List[Dict]` | Collected proposals with proposer and content |
| `synthesis`      | `str`        | Final synthesized answer                      |
| `round_count`    | `int`        | Current round number                          |
| `max_rounds`     | `int`        | Round budget                                  |
| `proposer_count` | `int`        | Expected proposal count                       |

## Magentic-One

The **Magentic-One** pattern (Furtado et al. 2024) uses an orchestrator with a dual-ledger architecture: **plan → delegate → track progress → re-plan when stuck**. The orchestrator maintains a Fact Bank and Task Ledger, delegates to specialist agents, and re-plans when progress stalls.

### When to use it

* Complex, multi-step tasks requiring coordination of different capabilities
* Tasks where an orchestrator needs to adapt its plan based on intermediate results
* Open-ended problems with research, coding, and analysis subtasks

### Quick start

```python theme={null}
from qitos.recipes.magentic_one import (
    MagenticOneOrchestrator,
    ProgressCritic,
    MagenticOneState,
)

agent = MagenticOneOrchestrator(llm=my_llm)
result = agent.run(
    task="Research and summarize the latest findings on ...",
    critics=[ProgressCritic(max_stalls=3)],
    max_steps=30,
    return_state=True,
)
print(result.state.fact_bank)        # accumulated facts
print(result.state.completed_tasks)  # finished subtasks
```

### How it works

1. **Plan**: The orchestrator creates a task ledger and gathers initial facts.
2. **Delegate**: At each step, a subtask is assigned to a specialist.
3. **Track**: `ProgressCritic` evaluates whether new facts have been gathered or tasks completed.
4. **Re-plan**: If no progress is detected for `max_stalls` consecutive steps, the critic returns `retry` with re-planning guidance.
5. **Stop**: When a FINAL ANSWER is provided, or when stall budget is exhausted.

### ProgressCritic parameters

| Parameter            | Default | Description                           |
| -------------------- | ------- | ------------------------------------- |
| `max_stalls`         | 3       | Maximum consecutive no-progress steps |
| `progress_threshold` | 0.5     | Minimum score to consider progress    |

### MagenticOneState fields

| Field              | Type        | Description                            |
| ------------------ | ----------- | -------------------------------------- |
| `fact_bank`        | `List[str]` | Accumulated facts and educated guesses |
| `task_ledger`      | `List[str]` | Current plan of subtasks               |
| `completed_tasks`  | `List[str]` | Finished subtasks                      |
| `stall_count`      | `int`       | Consecutive no-progress steps          |
| `max_stalls`       | `int`       | Stall budget before forced stop        |
| `specialist_calls` | `int`       | Number of specialist delegations       |
| `current_subtask`  | `str`       | Currently active subtask               |

## Scaffolding a new agent

Use the `qit new` CLI command to scaffold a new agent project from the built-in cookiecutter template:

```bash theme={null}
# Create a new agent with default settings
pip install qitos[cookiecutter]
qit new --agent-name my_agent --agent-description "My custom agent"

# List available templates
qit list-templates

# Create with full customization
qit new \
  --agent-name code_reviewer \
  --agent-description "Reviews code for security issues" \
  --author "My Team" \
  --default-model qwen-plus \
  --max-steps 20
```

The scaffolded project includes:

* `src/agent.py` — Agent class with State, init\_state, build\_system\_prompt, reduce
* `configs/default.yaml` — Default model and step configuration
* `tests/test_agent.py` — Basic smoke tests
* `snowl_compat.py` — Snowl evaluation compatibility adapter
* `eval_config.yaml` — Evaluation configuration

## Building your own method template

To create a custom method template, follow the same Agent + Critic pattern:

1. **Define a state** that extends `StateSchema` with your pattern's tracking fields
2. **Implement a critic** that returns `retry` with `instruction_patch` and `state_patch` when the pattern requires iteration
3. **Implement an agent** whose `build_system_prompt()` injects pattern context from state

```python theme={null}
from dataclasses import dataclass, field
from typing import Any, Dict, List
from qitos import AgentModule, Decision, StateSchema
from qitos.engine.critic import Critic
from qitos.engine.critic_result import CriticResult
from qitos.kit.parser import ReActTextParser

@dataclass
class MyMethodState(StateSchema):
    iteration: int = 0
    max_iterations: int = 5
    history: List[str] = field(default_factory=list)

class MyMethodCritic(Critic):
    def evaluate(self, state, decision, results):
        if not isinstance(state, MyMethodState):
            return CriticResult(action="continue")
        if state.iteration < state.max_iterations:
            return CriticResult(
                action="retry",
                score=0.5,
                instruction_patch="Try again with a different approach.",
                state_patch={"iteration": state.iteration + 1},
            )
        return CriticResult(action="stop", reason="Max iterations reached.")

class MyMethodAgent(AgentModule[MyMethodState, Dict[str, Any], Any]):
    def __init__(self, llm=None, **kwargs):
        super().__init__(llm=llm, model_parser=ReActTextParser(), **kwargs)

    def init_state(self, task, **kwargs):
        return MyMethodState(task=task, max_steps=kwargs.get("max_steps", 10))

    def build_system_prompt(self, state):
        prompt = "You are a method agent. Iterate until done."
        if state.history:
            prompt += "\n\nPrevious attempts:\n" + "\n".join(state.history)
        return prompt

    def prepare(self, state, observation):
        return f"Task: {state.task}\nIteration: {state.iteration}"

    def reduce(self, state, observation, decision, action_results):
        return state
```