Agentic Architectures

Catalogue / Multi-agent Coordination

Map-Reduce

Code splits the input, workers read the parts alone, one call merges

Shape
fan-out
Model calls
parts + collapse calls (often 0) + 1 reduce
Latency
low
Complexity
medium

Also known as Sectioning, Parallel fan-out and gather, Scatter-gather, LLM×MapReduce

1

What if the input is too long or too wide for one call to cover?

Plain code cuts the input into parts that each fit one call. A separate worker reads each part alone, all at the same time, and returns a short finding in a fixed form. One reduce call then reads only the findings and writes the result. Every part is read once, by a worker that looks at nothing else.

You may need it if

  • The document, log or data set does not fit in one call, or fits and the middle gets skimmed.
  • One reviewer is asked to check security, performance and style at once and does each one thinly.
  • The same instruction applies to every part, and the parts can be read in any order.
  • Search returns a few passages, but the question needs every page looked at.
2

When does cutting the work into parallel parts go wrong?

Use it when

  • The input is far longer than one call can read well, and the same question applies to every part of it.
  • A task has aspects fixed in advance, such as security, performance and style, that each deserve their own call.
  • A part can be judged without the others, so workers do not need each other's results.
  • Elapsed time matters and you can afford to run every part at the same moment.

Avoid it when

  • A part only makes sense in the light of earlier parts, as in a story or a long argument. Workers that read alone cannot know what came before.
    Use Chain of Agents instead
  • Every worker would get the same input and the same task, to cancel out individual bias. That is a vote, not a split.
    Use Ensemble instead
  • The parts cannot be fixed by code in advance. A model must read the task first to decide what the subtasks are and who does them.
    Use Supervisor & Specialists instead
  • Only a few passages matter and a search can find them. Reading every page is then wasted spend.
    Use Agentic RAG instead
  • Findings from different parts will often conflict and there is no rule for settling it. The reduce call would have to guess.

What it costs

Model calls
parts + collapse calls (often 0) + 1 reduce
Latency
low
Complexity
medium
3

How do the split, the parallel reads and the merge fit together?

A fan-out and a fan-in. Code splits the input. One mapper per part returns a finding in a fixed form with a confidence score. Code drops the empty findings and checks the rest fit one call. If not, collapsers merge them by groups and the check runs again. A reducer writes the result.

fitstoo longmerged findingsLong input: The instruction or question, with the input that is too long or too wide for one call.Long inputSplitter: Plain code. Cuts the input into parts that each fit one call. Every piece lands in exactly one part.SplitterMappers: One per part, all at once. Each reads the question and its own part, and returns facts, reasoning, a partial answer and a confidence score.MappersFits one call?: Plain code. Drops findings that report no information and measures whether the rest fit in one call.Fits onecall?Collapsers: Used only when the findings are too long. Each merges one group of findings into a single finding of the same form.CollapsersReducer: Reads the question and the findings only. Settles conflicts with the confidence scores and writes the result.ReducerResult: The combined answer or document, with the parts each statement comes from.Result
  1. Step 1 of 6

    Code cuts the contract

    A 300-page supply contract arrives with a question. Which clauses let the supplier raise prices? Plain code cuts it into 30 chunks of ten pages. Each page is in exactly one chunk, and the code can prove it.

  2. Step 2 of 6

    Thirty mappers start at once

    Each mapper receives the question and its own ten pages, nothing else. None of them knows what the others read, so all thirty can run at the same time.

  3. Step 3 of 6

    Each returns a finding in a fixed form

    Chunk 2 reports that prices are fixed for 36 months, confidence 5 because the clause says so. Chunk 21 reports that yearly indexation seems allowed, confidence 3 because it infers this from a definition. 26 chunks reply NO INFORMATION.

  4. Step 4 of 6

    Code checks the size

    The gate drops the 26 empty findings and measures the four that remain. They fit in one call with room to spare, so they go straight to the reducer.

  5. Step 5 of 6

    Too many findings are merged by groups

    On a 3,000-page file the findings alone would overflow one call. Code then groups them, a collapser merges each group into one finding of the same form, and the size is checked again, three rounds at most.

  6. Step 6 of 6

    The reducer settles the conflict

    The reducer reads four findings, not 300 pages. Chunks 2 and 21 disagree. It follows the clause that is stated outright, reports the indexation reading as a point to check, and gives the pages for both.

What each part does
Long input
The instruction or question, with the input that is too long or too wide for one call.
Splitter
Plain code. Cuts the input into parts that each fit one call. Every piece lands in exactly one part.
Mappers
One per part, all at once. Each reads the question and its own part, and returns facts, reasoning, a partial answer and a confidence score.
Fits one call?
Plain code. Drops findings that report no information and measures whether the rest fit in one call.
Collapsers
Used only when the findings are too long. Each merges one group of findings into a single finding of the same form.
Reducer
Reads the question and the findings only. Settles conflicts with the confidence scores and writes the result.
Result
The combined answer or document, with the parts each statement comes from.
  • Splitter → Mappers: one part each
  • Mappers → Fits one call?: findings
  • Fits one call? → Reducer: fits
  • Fits one call? → Collapsers: too long
  • Collapsers → Fits one call?: merged findings

Where it connects

Entry
request
TaskQuestionDocument

An instruction or question, plus an input too long or too wide for one call, such as a long document, a set of records or a fixed list of aspects to cover.

Exit
result
AnswerDocument

When: The reducer has combined the findings that came out of the map and collapse stages.

The answer or the combined document, the parts each statement relies on, conflicts between parts with the side taken, and the count of parts read and parts with nothing to report.

4

What do I ask my assistant to set up?

The agents to launch

Mapper, one per part, all launched at the same time

Read the one part you are given and answer the question from it alone. Return the facts that bear on the question, how they lead to an answer, the partial answer, and a confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related. If the part says nothing useful, answer NO INFORMATION.

Sees: The question and its own part. Not the other parts, not the other mappers' findings, and no tools.

Collapser, one per group of findings, only when the findings do not fit one call

Merge the findings you are given into one finding of the same form. Keep every fact that bears on the question and the parts it came from. Where two findings conflict, keep both sides with their confidence. Do not answer the question beyond what the findings support.

Sees: The question and one group of findings. Not the source text.

Reducer

Write the result from the findings only. Where findings conflict, follow the one with the higher confidence, say that you did and name the other. Give the parts each statement relies on. If no finding answers the question, say so plainly.

Sees: The question and the findings that survived, each with its part reference and confidence. Not the source text.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Map-Reduce" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Map-Reduce
Code splits the input, workers read the parts alone, one call merges.
Input: the task above. It must provide: An instruction or question, plus an input too long or too wide for one call, such as a long document, a set of records or a fixed list of aspects to cover. If something essential is missing, ask for it before starting.

Agents to launch:
- Mapper (one per part, all launched at the same time): Read the one part you are given and answer the question from it alone. Return the facts that bear on the question, how they lead to an answer, the partial answer, and a confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related. If the part says nothing useful, answer NO INFORMATION.
  Context for this agent: The question and its own part. Not the other parts, not the other mappers' findings, and no tools.
- Collapser (one per group of findings, only when the findings do not fit one call): Merge the findings you are given into one finding of the same form. Keep every fact that bears on the question and the parts it came from. Where two findings conflict, keep both sides with their confidence. Do not answer the question beyond what the findings support.
  Context for this agent: The question and one group of findings. Not the source text.
- Reducer: Write the result from the findings only. Where findings conflict, follow the one with the higher confidence, say that you did and name the other. Give the parts each statement relies on. If no finding answers the question, say so plainly.
  Context for this agent: The question and the findings that survived, each with its part reference and confidence. Not the source text.

Procedure:
1. Split the input with plain code into parts that each fit one call with room for the question. Check that every piece of the input is in exactly one part.
2. Fix the form of a finding before launching anything. It holds the part reference, facts, reasoning, a partial answer and a confidence from 1 to 5. Give every mapper the same scoring rule.
3. Launch one mapper per part, all at the same time, each in a fresh context with the question and its own part only.
4. Retry once any mapper that fails or returns a malformed finding. Then drop the findings that say NO INFORMATION and keep count of them.
5. Measure the remaining findings. If they do not fit one call, group them so each group fits, launch one collapser per group, and measure again. Do at most 3 rounds.
6. Launch the reducer once on the question and the findings. Do not send any part back for a second read.

Stop rule: One map pass, one retry per failed mapper, at most 3 collapse rounds, one reduce call. If the findings still do not fit after round 3, reduce the highest-confidence ones that fit and report the rest as left out.

Exit:
- `result`, when: The reducer has combined the findings that came out of the map and collapse stages. Deliver: The answer or the combined document, the parts each statement relies on, conflicts between parts with the side taken, and the count of parts read and parts with nothing to report.

# Final deliverable
The result, then the parts it relies on, the conflicts and how each was settled, the number of parts read, the number with no information, and any part that failed twice.

The same thing in code

LangGraph, python, package langgraph
import asyncio
import operator
from typing import Annotated, Literal, TypedDict

from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from langgraph.types import Send
from pydantic import BaseModel

PART_CHARS = 24_000  # one part must fit one call, with room for the question
BUDGET_CHARS = 24_000  # what the reducer can read in one call
MAX_COLLAPSE_ROUNDS = 3
FORM = ("Return the facts that bear on the question, how they lead to an answer, the partial answer, and a "
        "confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related.")
MAP = f"Read this one part and answer the question from it alone. {FORM} If it says nothing useful, answer NO INFORMATION."
COLLAPSE = ("Merge these findings into one finding of the same form. Keep every fact that bears on the question "
            f"and the parts it came from. Where two conflict, keep both sides with their confidence. {FORM}")
REDUCE = ("Write the result from the findings only. Where findings conflict, follow the higher confidence, say "
          "that you did and name the other. Give the parts each statement relies on.")


class Finding(BaseModel):
    parts: str  # which parts of the input this finding covers
    facts: str
    reasoning: str
    answer: str  # the partial answer, or NO INFORMATION
    confidence: int


class State(TypedDict):
    question: str
    document: str
    mapped: Annotated[list[Finding], operator.add]  # fan-in: each mapper appends its own
    findings: list[Finding]
    rounds: int
    left_out: int
    result: str


class MapIn(TypedDict):
    question: str
    index: int
    part: str


llm = init_chat_model("anthropic:claude-sonnet-5-5")


async def ask(prompt: str) -> Finding:
    for _ in range(2):  # one retry for a failed or malformed finding
        try:
            return Finding.model_validate(await llm.with_structured_output(Finding).ainvoke(prompt))
        except Exception:
            continue
    return Finding(parts="", facts="", reasoning="", answer="FAILED", confidence=0)


def split(document: str) -> list[str]:
    # plain code: every character lands in exactly one part
    return [document[i:i + PART_CHARS] for i in range(0, len(document), PART_CHARS)]


def size(findings: list[Finding]) -> int:
    return sum(len(f.model_dump_json()) for f in findings)


def groups(findings: list[Finding]) -> list[list[Finding]]:
    out: list[list[Finding]] = [[]]
    for f in findings:
        if out[-1] and size(out[-1] + [f]) > BUDGET_CHARS:
            out.append([])
        out[-1].append(f)
    return out


def fan_out(state: State) -> list[Send]:
    return [Send("mapper", {"question": state["question"], "index": i, "part": p})
            for i, p in enumerate(split(state["document"]))]


async def mapper(state: MapIn) -> dict:
    # a fresh context: the question and one part, nothing from the other mappers
    f = await ask(f"{MAP}\n\nQuestion: {state['question']}\n\nPart {state['index']}:\n{state['part']}")
    f.parts = f"part {state['index']}"
    return {"mapped": [f]}


def screen(state: State) -> dict:
    return {"findings": [f for f in state["mapped"] if f.answer != "FAILED" and "NO INFORMATION" not in f.answer.upper()]}


def fits(state: State) -> Literal["collapse", "reducer"]:
    if size(state["findings"]) <= BUDGET_CHARS or state["rounds"] >= MAX_COLLAPSE_ROUNDS:
        return "reducer"
    return "collapse"


async def collapse(state: State) -> dict:
    async def merge(group: list[Finding]) -> list[Finding]:
        listing = "\n".join(f.model_dump_json() for f in group)
        f = await ask(f"{COLLAPSE}\n\nQuestion: {state['question']}\n\nFindings:\n{listing}")
        return group if f.answer == "FAILED" else [f]  # a failed merge keeps its group as it was
    merged = await asyncio.gather(*(merge(g) for g in groups(state["findings"])))
    return {"findings": [f for batch in merged for f in batch], "rounds": state["rounds"] + 1}


async def reducer(state: State) -> dict:
    kept: list[Finding] = []
    for f in sorted(state["findings"], key=lambda f: -f.confidence):  # still too long: best first
        if size(kept + [f]) <= BUDGET_CHARS:
            kept.append(f)
    listing = "\n".join(f.model_dump_json() for f in kept)
    msg = await llm.ainvoke(f"{REDUCE}\n\nQuestion: {state['question']}\n\nFindings:\n{listing}")
    return {"result": msg.text, "left_out": len(state["findings"]) - len(kept)}


g = StateGraph(State)
g.add_node("mapper", mapper)
g.add_node("screen", screen)
g.add_node("collapse", collapse)
g.add_node("reducer", reducer)
g.add_conditional_edges(START, fan_out, ["mapper"])  # one mapper per part, in parallel
g.add_edge("mapper", "screen")
g.add_conditional_edges("screen", fits, ["collapse", "reducer"])
g.add_conditional_edges("collapse", fits, ["collapse", "reducer"])
g.add_edge("reducer", END)
app = g.compile()


async def run(question: str, document: str) -> dict:
    s = await app.ainvoke({"question": question, "document": document, "mapped": [], "findings": [],
                           "rounds": 0, "left_out": 0, "result": ""})
    failed = [f.parts for f in s["mapped"] if f.answer == "FAILED"]
    return {"result": s["result"], "parts_read": len(s["mapped"]), "with_information": len(s["findings"]),
            "collapse_rounds": s["rounds"], "left_out": s["left_out"], "failed_parts": failed}

The split is by character count for brevity. Cut on section or record boundaries in a real system, and throttle the fan-out to your rate limit.

Claude Agent SDK, python, package claude-agent-sdk
import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel

PART_CHARS = 24_000  # one part must fit one call, with room for the question
BUDGET_CHARS = 24_000  # what the reducer can read in one call
MAX_COLLAPSE_ROUNDS = 3
FORM = ("Return the facts that bear on the question, how they lead to an answer, the partial answer, and a "
        "confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related.")
MAP = f"Read the one part you are given and answer the question from it alone. {FORM} If it says nothing useful, answer NO INFORMATION."
COLLAPSE = ("Merge the findings you are given into one finding of the same form. Keep every fact that bears on the "
            f"question and the parts it came from. Where two conflict, keep both sides with their confidence. {FORM}")
REDUCE = ("Write the result from the findings only. Where findings conflict, follow the higher confidence, say "
          "that you did and name the other. Give the parts each statement relies on.")


class Finding(BaseModel):
    parts: str  # which parts of the input this finding covers
    facts: str
    reasoning: str
    answer: str  # the partial answer, or NO INFORMATION
    confidence: int


async def find(system: str, prompt: str) -> Finding:
    # each call is its own session: a fresh context with no tools
    options = ClaudeAgentOptions(system_prompt=system, tools=[],
                                 output_format={"type": "json_schema", "schema": Finding.model_json_schema()})
    for _ in range(2):  # one retry for a failed or malformed finding
        try:
            async for msg in query(prompt=prompt, options=options):
                if isinstance(msg, ResultMessage):
                    return Finding.model_validate(msg.structured_output)
        except Exception:
            continue
    return Finding(parts="", facts="", reasoning="", answer="FAILED", confidence=0)


def split(document: str) -> list[str]:
    # plain code: every character lands in exactly one part
    return [document[i:i + PART_CHARS] for i in range(0, len(document), PART_CHARS)]


def size(findings: list[Finding]) -> int:
    return sum(len(f.model_dump_json()) for f in findings)


def groups(findings: list[Finding]) -> list[list[Finding]]:
    out: list[list[Finding]] = [[]]
    for f in findings:
        if out[-1] and size(out[-1] + [f]) > BUDGET_CHARS:
            out.append([])
        out[-1].append(f)
    return out


async def run(question: str, document: str) -> dict:
    async def one(index: int, part: str) -> Finding:
        f = await find(MAP, f"Question: {question}\n\nPart {index}:\n{part}")
        f.parts = f"part {index}"
        return f

    async def merge(group: list[Finding]) -> list[Finding]:
        f = await find(COLLAPSE, f"Question: {question}\n\nFindings:\n" + "\n".join(x.model_dump_json() for x in group))
        return group if f.answer == "FAILED" else [f]  # a failed merge keeps its group as it was

    # the fan-out: one mapper per part, all at once, none sees another part
    mapped = await asyncio.gather(*(one(i, p) for i, p in enumerate(split(document))))
    failed = [f.parts for f in mapped if f.answer == "FAILED"]
    findings = [f for f in mapped if f.answer != "FAILED" and "NO INFORMATION" not in f.answer.upper()]

    rounds = 0
    while size(findings) > BUDGET_CHARS and rounds < MAX_COLLAPSE_ROUNDS:  # the gate
        merged = await asyncio.gather(*(merge(group) for group in groups(findings)))
        findings = [f for batch in merged for f in batch]
        rounds += 1

    kept: list[Finding] = []
    for f in sorted(findings, key=lambda f: -f.confidence):  # still too long: best first
        if size(kept + [f]) <= BUDGET_CHARS:
            kept.append(f)
    listing = "\n".join(f.model_dump_json() for f in kept)
    result = ""
    async for msg in query(prompt=f"Question: {question}\n\nFindings:\n{listing}",
                           options=ClaudeAgentOptions(system_prompt=REDUCE, tools=[])):
        if isinstance(msg, ResultMessage):
            result = msg.result or ""
    return {"result": result, "parts_read": len(mapped), "with_information": len(findings),
            "collapse_rounds": rounds, "left_out": len(findings) - len(kept), "failed_parts": failed}

Plain code launches one session per part, so isolation does not depend on a prompt. Throttle the gather to your rate limit and cut on section boundaries.

OpenAI Agents SDK, python, package openai-agents
import asyncio

from agents import Agent, Runner
from pydantic import BaseModel

PART_CHARS = 24_000  # one part must fit one call, with room for the question
BUDGET_CHARS = 24_000  # what the reducer can read in one call
MAX_COLLAPSE_ROUNDS = 3
FORM = ("Return the facts that bear on the question, how they lead to an answer, the partial answer, and a "
        "confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related.")


class Finding(BaseModel):
    parts: str  # which parts of the input this finding covers
    facts: str
    reasoning: str
    answer: str  # the partial answer, or NO INFORMATION
    confidence: int


mapper = Agent(name="Mapper", output_type=Finding,
               instructions=f"Read the one part you are given and answer the question from it alone. {FORM} "
                            "If it says nothing useful, answer NO INFORMATION.")
collapser = Agent(name="Collapser", output_type=Finding,
                  instructions="Merge the findings you are given into one finding of the same form. Keep every "
                               "fact that bears on the question and the parts it came from. Where two conflict, "
                               f"keep both sides with their confidence. {FORM}")
reducer = Agent(name="Reducer",
                instructions="Write the result from the findings only. Where findings conflict, follow the higher "
                             "confidence, say that you did and name the other. Give the parts each statement "
                             "relies on.")


async def find(agent: Agent, prompt: str) -> Finding:
    for _ in range(2):  # one retry for a failed or malformed finding
        try:
            return (await Runner.run(agent, prompt)).final_output_as(Finding)
        except Exception:
            continue
    return Finding(parts="", facts="", reasoning="", answer="FAILED", confidence=0)


def split(document: str) -> list[str]:
    # plain code: every character lands in exactly one part
    return [document[i:i + PART_CHARS] for i in range(0, len(document), PART_CHARS)]


def size(findings: list[Finding]) -> int:
    return sum(len(f.model_dump_json()) for f in findings)


def groups(findings: list[Finding]) -> list[list[Finding]]:
    out: list[list[Finding]] = [[]]
    for f in findings:
        if out[-1] and size(out[-1] + [f]) > BUDGET_CHARS:
            out.append([])
        out[-1].append(f)
    return out


async def run(question: str, document: str) -> dict:
    async def one(index: int, part: str) -> Finding:
        f = await find(mapper, f"Question: {question}\n\nPart {index}:\n{part}")
        f.parts = f"part {index}"
        return f

    async def merge(group: list[Finding]) -> list[Finding]:
        f = await find(collapser, f"Question: {question}\n\nFindings:\n" + "\n".join(x.model_dump_json() for x in group))
        return group if f.answer == "FAILED" else [f]  # a failed merge keeps its group as it was

    # the fan-out: one separate run per part, all at once, none sees another part
    mapped = await asyncio.gather(*(one(i, p) for i, p in enumerate(split(document))))
    failed = [f.parts for f in mapped if f.answer == "FAILED"]
    findings = [f for f in mapped if f.answer != "FAILED" and "NO INFORMATION" not in f.answer.upper()]

    rounds = 0
    while size(findings) > BUDGET_CHARS and rounds < MAX_COLLAPSE_ROUNDS:  # the gate
        merged = await asyncio.gather(*(merge(group) for group in groups(findings)))
        findings = [f for batch in merged for f in batch]
        rounds += 1

    kept: list[Finding] = []
    for f in sorted(findings, key=lambda f: -f.confidence):  # still too long: best first
        if size(kept + [f]) <= BUDGET_CHARS:
            kept.append(f)
    listing = "\n".join(f.model_dump_json() for f in kept)
    out = await Runner.run(reducer, f"Question: {question}\n\nFindings:\n{listing}")  # one reduce call
    return {"result": out.final_output_as(str), "parts_read": len(mapped), "with_information": len(findings),
            "collapse_rounds": rounds, "left_out": len(findings) - len(kept), "failed_parts": failed}

The three agents have no tools and no handoffs: the fan-out is plain asyncio. Throttle the gather to your rate limit and cut on section boundaries.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const PART_CHARS = 24_000; // one part must fit one call, with room for the question
const BUDGET_CHARS = 24_000; // what the reducer can read in one call
const MAX_COLLAPSE_ROUNDS = 3;
const model = anthropic('claude-sonnet-5-5');
const FORM =
  'Return the facts that bear on the question, how they lead to an answer, the partial answer, and a ' +
  'confidence from 1 to 5: 5 if the text states it, 3 if you infer it, 1 if it is barely related.';
const MAP = `Read the one part you are given and answer the question from it alone. ${FORM} If it says nothing useful, answer NO INFORMATION.`;
const COLLAPSE =
  'Merge the findings you are given into one finding of the same form. Keep every fact that bears on the ' +
  `question and the parts it came from. Where two conflict, keep both sides with their confidence. ${FORM}`;
const REDUCE =
  'Write the result from the findings only. Where findings conflict, follow the higher confidence, say ' +
  'that you did and name the other. Give the parts each statement relies on.';

const findingSchema = z.object({
  parts: z.string().describe('which parts of the input this finding covers'),
  facts: z.string(),
  reasoning: z.string(),
  answer: z.string().describe('the partial answer, or NO INFORMATION'),
  confidence: z.number().int(),
});
type Finding = z.infer<typeof findingSchema>;

async function find(instructions: string, prompt: string): Promise<Finding> {
  for (let attempt = 0; attempt < 2; attempt++) { // one retry for a failed or malformed finding
    try {
      const { output } = await generateText({ model, instructions, prompt, output: Output.object({ schema: findingSchema }) });
      return output;
    } catch {
      continue;
    }
  }
  return { parts: '', facts: '', reasoning: '', answer: 'FAILED', confidence: 0 };
}

function split(document: string): string[] {
  // plain code: every character lands in exactly one part
  const parts: string[] = [];
  for (let i = 0; i < document.length; i += PART_CHARS) parts.push(document.slice(i, i + PART_CHARS));
  return parts;
}

const size = (findings: Finding[]) => findings.reduce((n, f) => n + JSON.stringify(f).length, 0);
const listing = (findings: Finding[]) => findings.map((f) => JSON.stringify(f)).join('\n');

function groups(findings: Finding[]): Finding[][] {
  const out: Finding[][] = [[]];
  for (const f of findings) {
    if (out[out.length - 1].length > 0 && size([...out[out.length - 1], f]) > BUDGET_CHARS) out.push([]);
    out[out.length - 1].push(f);
  }
  return out;
}

export async function run(question: string, document: string) {
  // the fan-out: one isolated call per part, all at once, none sees another part
  const mapped = await Promise.all(
    split(document).map(async (part, index) => {
      const f = await find(MAP, `Question: ${question}\n\nPart ${index}:\n${part}`);
      return { ...f, parts: `part ${index}` };
    }),
  );
  const failedParts = mapped.filter((f) => f.answer === 'FAILED').map((f) => f.parts);
  let findings = mapped.filter((f) => f.answer !== 'FAILED' && !f.answer.toUpperCase().includes('NO INFORMATION'));

  let rounds = 0;
  while (size(findings) > BUDGET_CHARS && rounds < MAX_COLLAPSE_ROUNDS) { // the gate
    const merged = await Promise.all(
      groups(findings).map(async (group) => {
        const f = await find(COLLAPSE, `Question: ${question}\n\nFindings:\n${listing(group)}`);
        return f.answer === 'FAILED' ? group : [f]; // a failed merge keeps its group as it was
      }),
    );
    findings = merged.flat();
    rounds += 1;
  }

  const kept: Finding[] = [];
  for (const f of [...findings].sort((a, b) => b.confidence - a.confidence)) { // still too long: best first
    if (size([...kept, f]) <= BUDGET_CHARS) kept.push(f);
  }
  // one reduce call: the question and the findings, never the source text
  const { text } = await generateText({
    model,
    instructions: REDUCE,
    prompt: `Question: ${question}\n\nFindings:\n${listing(kept)}`,
  });
  return {
    result: text,
    partsRead: mapped.length,
    withInformation: findings.length,
    collapseRounds: rounds,
    leftOut: findings.length - kept.length,
    failedParts,
  };
}

The split is by character count for brevity. Cut on section or record boundaries in a real system, and throttle the fan-out to your rate limit.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • A cut in the middle of a clause or a table hides it from both neighbours. Split on natural boundaries, or let adjacent parts overlap a little.
  • Without a shared scoring rule, one mapper's 5 is another's 3 and the reducer cannot compare them. Put the rule and an example in every mapper's prompt.
  • A mapper that is unsure tends to answer anyway. Make NO INFORMATION an explicit, acceptable reply.
  • The reducer sees findings, not text. If a mapper leaves out a detail, it is gone. Ask for facts with their location, not for summaries.
  • A failed mapper is a silent hole in the coverage. Count the findings against the parts before reducing.

Chain it

Its result can feed

Source