diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a3addc2..642c36b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -151,8 +151,12 @@ extra (`pip install -e ".[delegate]"`). Four tools: These are the first three slices of a [scatter-gather roadmap](https://github.com/Jason-Vaughan/TangleBrain/issues/39): the orchestrator routes a sub-task to any configured backend (by id or capability) and fans batches -out concurrently. Still ahead: an explicit synthesis/reduce step and orchestration-tree observability -(which also adds the deferred non-local delegate metering). +out concurrently. The **reduce step is deliberately not TangleBrain's** — the orchestrator synthesises +the `delegate_many` results itself (it holds the original task context that makes for good synthesis), +and offloads the stitch with an ordinary `delegate(task=…)` call when the reduction is mechanical and +large. No dedicated reducer tool: the existing primitives cover it, and frontier-side synthesis is the +better default until usage proves otherwise. Still ahead: orchestration-tree observability (which also +adds the deferred non-local delegate metering) — whose data would tell us if a reducer ever earns code. ### Measurement — per-task records (`measurement.py`) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ba440d..ce9a1be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Internal + +- **Documented the synthesis/reduce pattern (scatter-gather roadmap #39, slice 4).** README + + ARCHITECTURE now spell out that the orchestrator synthesises `delegate_many` results itself (it + holds the original task context), and offloads a *mechanical* stitch with an ordinary + `delegate(task=…)` call — so no dedicated reducer tool ships. Documentation of existing behaviour; + no code change. The reduce step stays the orchestrator's by design until observability data (a later + slice) shows a TB-side reducer would earn its keep. + ## [0.13.0] - 2026-06-18 ### Added diff --git a/README.md b/README.md index 1576a2f..e3612ab 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,16 @@ observability is on the [scatter-gather roadmap](https://github.com/Jason-Vaugha Any non-local target is opt-in and your responsibility under that provider's terms — see [DISCLAIMER.md](DISCLAIMER.md). +**Synthesising fan-out results.** The full pattern is decompose → fan out (`delegate_many`) → +**reduce** → answer. TangleBrain ships the dispatch primitives but deliberately does *not* own the +reduce step: the orchestrator gets the results array back and combines it itself, because it holds +the original task context that makes for good synthesis — something a fresh reduce backend lacks. If +the reduction is instead **mechanical and large** (concatenating generated files, merging many +summaries into one list — where the original intent doesn't matter), offload that stitch too with a +normal `delegate(prompt="Combine these results: …", task="summarization")` call, keeping the heavy +formatting off your frontier budget. No separate "reduce" tool is needed — the existing `delegate` +covers it. + It needs the optional `mcp` dependency: ```sh