agentdescent 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. agentdescent-0.1.0/LICENSE +21 -0
  2. agentdescent-0.1.0/PKG-INFO +375 -0
  3. agentdescent-0.1.0/README.md +355 -0
  4. agentdescent-0.1.0/agentdescent/__init__.py +169 -0
  5. agentdescent-0.1.0/agentdescent/agents.py +112 -0
  6. agentdescent-0.1.0/agentdescent/aggregator.py +370 -0
  7. agentdescent-0.1.0/agentdescent/async_evolve.py +215 -0
  8. agentdescent-0.1.0/agentdescent/async_runtime.py +300 -0
  9. agentdescent-0.1.0/agentdescent/backends.py +195 -0
  10. agentdescent-0.1.0/agentdescent/dataloader.py +266 -0
  11. agentdescent-0.1.0/agentdescent/domains/__init__.py +19 -0
  12. agentdescent-0.1.0/agentdescent/domains/router.py +157 -0
  13. agentdescent-0.1.0/agentdescent/evolution.py +511 -0
  14. agentdescent-0.1.0/agentdescent/evolvable.py +146 -0
  15. agentdescent-0.1.0/agentdescent/governance.py +95 -0
  16. agentdescent-0.1.0/agentdescent/ledger.py +273 -0
  17. agentdescent-0.1.0/agentdescent/orchestrator.py +179 -0
  18. agentdescent-0.1.0/agentdescent/parallel.py +217 -0
  19. agentdescent-0.1.0/agentdescent/scheduler.py +278 -0
  20. agentdescent-0.1.0/agentdescent/staleness.py +109 -0
  21. agentdescent-0.1.0/agentdescent/stats.py +100 -0
  22. agentdescent-0.1.0/agentdescent/verifier.py +104 -0
  23. agentdescent-0.1.0/agentdescent/worker.py +91 -0
  24. agentdescent-0.1.0/agentdescent.egg-info/PKG-INFO +375 -0
  25. agentdescent-0.1.0/agentdescent.egg-info/SOURCES.txt +52 -0
  26. agentdescent-0.1.0/agentdescent.egg-info/dependency_links.txt +1 -0
  27. agentdescent-0.1.0/agentdescent.egg-info/requires.txt +6 -0
  28. agentdescent-0.1.0/agentdescent.egg-info/top_level.txt +1 -0
  29. agentdescent-0.1.0/pyproject.toml +33 -0
  30. agentdescent-0.1.0/setup.cfg +4 -0
  31. agentdescent-0.1.0/tests/test_ace_example.py +109 -0
  32. agentdescent-0.1.0/tests/test_adas_example.py +91 -0
  33. agentdescent-0.1.0/tests/test_agents.py +57 -0
  34. agentdescent-0.1.0/tests/test_aggregator.py +83 -0
  35. agentdescent-0.1.0/tests/test_async.py +57 -0
  36. agentdescent-0.1.0/tests/test_async_evolve.py +82 -0
  37. agentdescent-0.1.0/tests/test_backends.py +65 -0
  38. agentdescent-0.1.0/tests/test_bbh_example.py +61 -0
  39. agentdescent-0.1.0/tests/test_dataloader.py +142 -0
  40. agentdescent-0.1.0/tests/test_dgm_example.py +95 -0
  41. agentdescent-0.1.0/tests/test_duration.py +47 -0
  42. agentdescent-0.1.0/tests/test_efficiency.py +39 -0
  43. agentdescent-0.1.0/tests/test_evolution.py +119 -0
  44. agentdescent-0.1.0/tests/test_evoskill_example.py +79 -0
  45. agentdescent-0.1.0/tests/test_gepa_example.py +113 -0
  46. agentdescent-0.1.0/tests/test_governance.py +35 -0
  47. agentdescent-0.1.0/tests/test_harness.py +53 -0
  48. agentdescent-0.1.0/tests/test_ledger.py +71 -0
  49. agentdescent-0.1.0/tests/test_orchestrator.py +32 -0
  50. agentdescent-0.1.0/tests/test_parallel.py +136 -0
  51. agentdescent-0.1.0/tests/test_skillopt_example.py +95 -0
  52. agentdescent-0.1.0/tests/test_staleness.py +46 -0
  53. agentdescent-0.1.0/tests/test_stats_and_staleness.py +43 -0
  54. agentdescent-0.1.0/tests/test_strategy.py +83 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AgentDescent
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,375 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentdescent
3
+ Version: 0.1.0
4
+ Summary: A parallel, self-evolving framework for accelerating recursive self-improvement (RSI)
5
+ Author: AgentDescent
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Birfy/agentdescent
8
+ Keywords: rsi,self-evolving-agents,parallel,aggregation,staleness
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Intended Audience :: Science/Research
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Provides-Extra: dev
16
+ Requires-Dist: pytest>=7.0; extra == "dev"
17
+ Provides-Extra: docs
18
+ Requires-Dist: mkdocs-material>=9.5; extra == "docs"
19
+ Dynamic: license-file
20
+
21
+ # AgentDescent
22
+
23
+ > **Gradient descent — but the parameters are agents.** A parallel, asynchronous
24
+ > framework for self-evolving agents (skills, prompts, harnesses) where **diffs
25
+ > are the gradients** and **the aggregator is the optimizer**.
26
+
27
+ [![docs](https://img.shields.io/badge/docs-mkdocs--material-1f6feb)](https://birfy.github.io/agentdescent/)
28
+ [![CI](https://github.com/Birfy/agentdescent/actions/workflows/docs.yml/badge.svg)](https://github.com/Birfy/agentdescent/actions/workflows/docs.yml)
29
+ [![python](https://img.shields.io/badge/python-%E2%89%A53.9-1f6feb)](https://www.python.org/)
30
+ [![license](https://img.shields.io/badge/license-MIT-3fb950)](https://github.com/Birfy/agentdescent/blob/main/LICENSE)
31
+
32
+ AgentDescent puts the deep-learning **training stack** on top of agents. The
33
+ "parameters" are a **library of evolvable artifacts** (skills, prompts, harness
34
+ modules, verifiers); the "gradients" are **diffs carrying evidence cards**; the
35
+ "optimizer step" is a **merge decision**. *N* workers propose diffs **in
36
+ parallel**, and a **barrier-free asynchronous** merger aggregates them into a
37
+ shared, version-controlled artifact library — targeting **O(N / T_iter)**
38
+ improvement throughput, where serial self-improvement is bounded at 1 diff / T_iter.
39
+
40
+ > The one place the analogy *must* break defines the whole system: **gradients
41
+ > add, diffs do not.** Aggregation is therefore not averaging but **conflict
42
+ > resolution + statistical acceptance + transactional commit**.
43
+
44
+ ## Highlights
45
+
46
+ - **One entry point — `evolve()`.** Describe *what evolves* (a `Strategy`) and the
47
+ *rules of evolution* (`run` / `reward` / `propose`); the parallel, merge-based
48
+ loop (ledger → workers → aggregator → commit) runs for you.
49
+ - **Parallel *and* asynchronous.** Concurrent workers within a round
50
+ (`max_concurrency`) and a **barrier-free** async runtime across rounds
51
+ (`asynchronous=True`) — a ROLL-Flash-style lag budget plus Full / Guarded /
52
+ Reflective staleness policies keep stale diffs safe.
53
+ - **The aggregator is a discrete-space optimizer.** Staleness filter → conflict
54
+ resolution → fusion tournament → Beta-posterior acceptance → transactional
55
+ commit — and fully swappable via `aggregator_factory`.
56
+ - **Governed by blast radius.** Skills (L2) merge freely; harnesses/verifiers (L1)
57
+ are forced through an oracle; safety/permissions (L0) are frozen.
58
+ - **Provider-agnostic.** Any `prompt -> text` is a completion — Claude,
59
+ OpenAI-compatible endpoints (GLM / DeepSeek), or a tool-using agent (OpenHands).
60
+ - **Faithful algorithm ports.** Runnable, offline-tested examples of ACE, GEPA,
61
+ EvoSkill, SkillOpt, ADAS, and DGM — faithful to each repo's algorithm *and*
62
+ dataset choice.
63
+
64
+ ## Install
65
+
66
+ ```bash
67
+ pip install -e ".[dev]" # from source · PyPI name: agentdescent · Python ≥ 3.9
68
+ ```
69
+
70
+ The core engine has **zero required dependencies**; `[dev]` adds pytest, `[docs]`
71
+ adds MkDocs Material.
72
+
73
+ ## Quickstart
74
+
75
+ ```python
76
+ from agentdescent.evolution import evolve, LLMAgent
77
+ from agentdescent.agents import claude
78
+
79
+ result = evolve(
80
+ tasks, reward, # your task set + scorer
81
+ agent=LLMAgent(claude(model="claude-haiku-4-5")),
82
+ rounds=15, n_workers=4, max_concurrency=4, # parallel workers
83
+ # asynchronous=True, async_ratio=3, # ...or barrier-free async
84
+ )
85
+ print(result.rendered) # the evolved artifact
86
+ print(result.final_reward) # held-out reward
87
+ ```
88
+
89
+ ## 📖 Documentation
90
+
91
+ Full docs live in [`docs/`](https://github.com/Birfy/agentdescent/tree/main/docs/) and render as a website via MkDocs Material:
92
+
93
+ | Page | What's in it |
94
+ |---|---|
95
+ | [Home](https://github.com/Birfy/agentdescent/blob/main/docs/index.md) | Overview and 30-second tour |
96
+ | [Architecture](https://github.com/Birfy/agentdescent/blob/main/docs/architecture.md) | Components, data-flow diagram, the two runtimes, concurrency model |
97
+ | [Concepts](https://github.com/Birfy/agentdescent/blob/main/docs/concepts.md) | The training↔RSI analogy, staleness, the aggregator, the three long tails, governance |
98
+ | [Usage & extending](https://github.com/Birfy/agentdescent/blob/main/docs/usage.md) | Running the demos, config reference, **plugging in your own `Evolvable` domain** |
99
+ | [Evolving anything](https://github.com/Birfy/agentdescent/blob/main/docs/evolution.md) | The general engine — evolve any artifact by writing its `Strategy` + `run`/`reward`/`propose` |
100
+ | [Connecting agents & LLMs](https://github.com/Birfy/agentdescent/blob/main/docs/agents.md) | The provider-agnostic completion layer |
101
+ | [Loading datasets](https://github.com/Birfy/agentdescent/blob/main/docs/dataloader.md) | The `agentdescent.dataloader` data layer — HF datasets-server + raw-file fetch, cached, dependency-free |
102
+ | [Customizable parallelism](https://github.com/Birfy/agentdescent/blob/main/docs/parallelism.md) | Pluggable DP / TP / PP strategies — or write your own |
103
+ | [Duration-aware scheduling](https://github.com/Birfy/agentdescent/blob/main/docs/duration-scheduling.md) | Estimate rollout cost from task size; LPT dispatch + straggler checkpointing |
104
+ | [Efficiency experiments](https://github.com/Birfy/agentdescent/blob/main/docs/efficiency.md) | Measured parallel scaling and async tail-hiding |
105
+ | [Example: skill evolution](https://github.com/Birfy/agentdescent/blob/main/docs/skill-evolution.md) | One complete run — real dataset, real LLM, every module |
106
+ | [Self-evolution algorithms](https://github.com/Birfy/agentdescent/blob/main/docs/self-evolution-examples.md) | Faithful ports of ACE, GEPA, EvoSkill, SkillOpt, ADAS, DGM |
107
+
108
+ ```bash
109
+ pip install -e ".[docs]"
110
+ mkdocs serve # live preview at http://127.0.0.1:8000
111
+ mkdocs build # static HTML into ./site
112
+ ```
113
+
114
+ A GitHub Actions workflow ([`.github/workflows/docs.yml`](https://github.com/Birfy/agentdescent/blob/main/.github/workflows/docs.yml))
115
+ builds and deploys the site to GitHub Pages — enable it under *Settings → Pages
116
+ → Source: GitHub Actions*.
117
+
118
+ ## Evolve anything — the general engine
119
+
120
+ The core is the ledger + aggregator + schedulers + governance.
121
+ [`agentdescent.evolution`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/evolution.py) is the domain-agnostic engine on
122
+ top: describe **what evolves** (a `Strategy`) and the **rules of evolution**
123
+ (`run` / `reward` / `propose`), and it runs the parallel, merge-based loop.
124
+
125
+ ```python
126
+ from agentdescent.evolution import evolve, AppendRules
127
+
128
+ result = evolve(
129
+ tasks, reward,
130
+ agent=my_agent, # or run=/propose= plain functions
131
+ strategy=AppendRules(), # or KeyedRules / your own
132
+ blast_radius=0.2, # 0.2 = L2 skill; 0.6 = L1 harness/verifier
133
+ rounds=15, n_workers=4,
134
+ )
135
+ print(result.rendered, result.final_reward)
136
+ ```
137
+
138
+ The strategy maps a proposal into diff ops, so distinct edits **fuse** and
139
+ conflicting edits are **resolved** on held-out score — for free. `blast_radius`
140
+ picks the governance layer (a skill is L2; a harness/verifier at `0.6` is L1,
141
+ where merges are forced through the oracle). Same `evolve` call for either —
142
+ only the artifact, strategy, and blast radius differ.
143
+
144
+ **Connect any agent/LLM** — [`agentdescent.agents`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/agents.py) is the
145
+ separate provider layer; any `prompt -> text` is a completion (`claude(...)`,
146
+ `openai_compatible(...)` for GLM/OpenAI-style endpoints, `from_callable(...)`,
147
+ `with_retries(...)`).
148
+
149
+ The one complete end-to-end run — real dataset, real LLM, every module — is
150
+ [`examples/skill_evolution.py`](https://github.com/Birfy/agentdescent/blob/main/examples/skill_evolution.py)
151
+ (`python -m examples.skill_evolution --dry-run` for the no-API preview).
152
+ Guides: [the engine](https://github.com/Birfy/agentdescent/blob/main/docs/evolution.md) · [skill example](https://github.com/Birfy/agentdescent/blob/main/docs/skill-evolution.md)
153
+ · [agents](https://github.com/Birfy/agentdescent/blob/main/docs/agents.md).
154
+
155
+ ## Faithful ports of the latest self-evolution algorithms
156
+
157
+ To show the engine is faithful to the field, AgentDescent ships one runnable example
158
+ per representative **skill** and **harness** self-evolution algorithm — each
159
+ faithful to the original repo's *algorithm* and *dataset choice*, each with a
160
+ `--dry-run` (no-API) mode and an offline test suite. Every one loads its benchmark
161
+ through the shared [`agentdescent.dataloader`](https://github.com/Birfy/agentdescent/blob/main/docs/dataloader.md) data layer
162
+ (HF datasets-server + raw files, cached, dependency-free). Full guide:
163
+ [docs/self-evolution-examples.md](https://github.com/Birfy/agentdescent/blob/main/docs/self-evolution-examples.md).
164
+
165
+ | Algorithm | Kind | Dataset | Example |
166
+ |---|---|---|---|
167
+ | **ACE** (Agentic Context Engineering) | skill / context | FiNER-139 | [`ace_context_evolution.py`](https://github.com/Birfy/agentdescent/blob/main/examples/ace_context_evolution.py) |
168
+ | **GEPA** (Reflective Prompt Evolution) | skill / prompt | HotpotQA | [`gepa_prompt_evolution.py`](https://github.com/Birfy/agentdescent/blob/main/examples/gepa_prompt_evolution.py) |
169
+ | **EvoSkill** (Automated Skill Discovery) | skill library | OfficeQA | [`evoskill_skill_discovery.py`](https://github.com/Birfy/agentdescent/blob/main/examples/evoskill_skill_discovery.py) |
170
+ | **SkillOpt** (ReflACT) | skill document | SearchQA | [`skillopt_skill_training.py`](https://github.com/Birfy/agentdescent/blob/main/examples/skillopt_skill_training.py) |
171
+ | **ADAS** (Meta Agent Search) | harness | MGSM | [`adas_meta_agent_search.py`](https://github.com/Birfy/agentdescent/blob/main/examples/adas_meta_agent_search.py) |
172
+ | **DGM** (Darwin Gödel Machine) | harness | SWE-bench Verified | [`dgm_self_improve.py`](https://github.com/Birfy/agentdescent/blob/main/examples/dgm_self_improve.py) |
173
+
174
+ ```bash
175
+ python -m examples.ace_context_evolution --dry-run # skill/context self-evolution (ACE)
176
+ python -m examples.dgm_self_improve # harness self-evolution (DGM), offline
177
+ ```
178
+
179
+ Fidelity is to the **released code**, not just the paper (e.g. EvoSkill's frontier
180
+ is top-K aggregate, not per-instance Pareto — the example follows the code and
181
+ says so); where a full setup needs heavy infra (SWE-bench Docker, gated data), the
182
+ boundary is documented, never hidden.
183
+
184
+ ## Efficiency (measured)
185
+
186
+ [`examples/efficiency.py`](https://github.com/Birfy/agentdescent/blob/main/examples/efficiency.py) — **parallel scaling** is
187
+ near-linear (efficiency ≥ 0.99 through 8 workers, 7.9× speedup), and the
188
+ **async pipeline** is **2.5× faster than a sync barrier** under heavy-tailed
189
+ rollout latency (100% vs 40% worker utilization). See
190
+ [docs/efficiency.md](https://github.com/Birfy/agentdescent/blob/main/docs/efficiency.md).
191
+
192
+ ## The central analogy
193
+
194
+ | Model training | AgentDescent (parallel RSI) |
195
+ |---|---|
196
+ | parameter tensor θ | library of `Evolvable` artifacts |
197
+ | gradient *g* | `Diff` + `EvidenceCard` |
198
+ | parameter server | git-backed, version-vectored `Ledger` |
199
+ | optimizer step | `Aggregator` merge decision |
200
+ | per-param adaptive LR (Adam) | per-artifact Beta-posterior test |
201
+ | staleness / decoupled PPO | per-diff η + rebase re-verify |
202
+ | partial rollout | turn-level checkpoint / `ResumeQueue` |
203
+ | EMA (weight averaging) | stable/dev dual branch |
204
+ | training code (not self-modifiable) | L0 frozen layer |
205
+
206
+ ## Running the examples
207
+
208
+ ```bash
209
+ # RQ1 — merge vs fork, end to end (synchronous DP)
210
+ python -m examples.run_demo
211
+
212
+ # Async stage orchestration — Full/Guarded/Reflective policies + async_ratio sweep
213
+ python -m examples.run_async
214
+
215
+ # The flagship: evolve a skill on a real dataset with a real LLM (--dry-run: no API)
216
+ python -m examples.skill_evolution --dry-run
217
+
218
+ # Efficiency: parallel throughput scaling + async vs sync-barrier tail-hiding
219
+ python -m examples.efficiency
220
+
221
+ # Customizable parallelism: DP / TP / PP (+ a custom strategy)
222
+ python -m examples.parallelism
223
+
224
+ # Duration-aware scheduling: online estimator + LPT dispatch + straggler checkpointing
225
+ python -m examples.duration_scheduling
226
+
227
+ # RQ2 — staleness tolerance sweep (alpha in {0,1,5,inf})
228
+ python -m examples.rq2_staleness
229
+
230
+ # tests
231
+ pytest
232
+ ```
233
+
234
+ No external services or model APIs are required: the reference domain
235
+ ([`agentdescent/domains/router.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/domains/router.py)) is a fully
236
+ deterministic keyword-router skill, so the entire parallel loop runs in-process
237
+ and is unit-tested — while still producing genuine diffs that measurably improve
238
+ a held-out metric.
239
+
240
+ ## Architecture → code map
241
+
242
+ Every module cites the design section it implements.
243
+
244
+ | Component | Module | Design § |
245
+ |---|---|---|
246
+ | `Evolvable` unit, `Diff`, `EvidenceCard`, version vectors | [`evolvable.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/evolvable.py) | 3.2, 3.3 |
247
+ | Git-backed Ledger: version vectors, CAS, 2PC, dual branch | [`ledger.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/ledger.py) | 3.1, 4.5 |
248
+ | Aggregator: staleness → conflict → fusion → Beta accept → commit | [`aggregator.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/aggregator.py) | 4 |
249
+ | **Staleness policies: Full / Guarded / Reflective** | [`staleness.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/staleness.py) | 4.2 |
250
+ | **Async stage-orchestration runtime + `async_ratio`** | [`async_runtime.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/async_runtime.py) | 3.1 |
251
+ | **Parallel paradigms: DP / TP / PP** | [`parallel.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/parallel.py) | 8 |
252
+ | Statistics: Beta posterior, `P(Δ>0)`, annealed δ, UCB | [`stats.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/stats.py) | 4.4, 5.2 |
253
+ | Three schedulers: UCB task / audit / resume queue | [`scheduler.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/scheduler.py) | 5 |
254
+ | Three-layer verifier (rule / learned / oracle) | [`verifier.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/verifier.py) | 3.1, 5.3 |
255
+ | Layered governance by blast radius (L0/L1/L2) | [`governance.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/governance.py) | 6 |
256
+ | Worker: rollout + propose | [`worker.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/worker.py) | 3.1 |
257
+ | Orchestrator (sync DP) + fork baseline | [`orchestrator.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/orchestrator.py) | 3.1, RQ1 |
258
+ | **Agent/LLM connection layer (provider-agnostic)** | [`agents.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/agents.py) | — |
259
+ | **General evolution engine + pluggable `Strategy`** | [`evolution.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/evolution.py) | 3.2 |
260
+
261
+ ## How aggregation works (the `Aggregator` pipeline)
262
+
263
+ Cards are bucketed **by artifact**. When a bucket triggers (batch size `B`, or a
264
+ `T_max` timeout so cold artifacts don't starve), the aggregator runs one
265
+ optimizer step:
266
+
267
+ 1. **Staleness filter (§4.2)** — per-diff `η = max(head − base)` over touched
268
+ artifacts. `η = 0` proceeds; `0 < η ≤ α` is **rebased and cheaply
269
+ re-verified** (does the delta still hold on the new head?); `η > α` is
270
+ discarded and its evidence *settled back* into the pool. `α` adapts to
271
+ artifact heat; contract-breaking diffs force `α = 0`.
272
+ 2. **Conflict resolution (§4.3)** — syntactic (hunk overlap) and semantic
273
+ (contradictory ops) detection; contradictions are projected out PCGrad-style,
274
+ keeping the better of the pair on a shared subset.
275
+ 3. **Fusion tournament (§4.3)** — complementary diffs are fused (model-soup
276
+ analogy) and run against the individual candidates on held-out data.
277
+ 4. **Statistical acceptance (§4.4)** — commit only if
278
+ `P(Δ > 0) > 1 − δ` under a per-artifact Beta posterior, not a point threshold.
279
+ `δ` anneals with version (LR decay); a trust-region caps diff size.
280
+ 5. **Commit (§4.1)** — compare-and-swap on `dev` (2PC for contract-breaking
281
+ multi-artifact diffs).
282
+ 6. **Dual-branch promotion (§4.5)** — `dev → stable` after *K* regression-free
283
+ rounds (EMA-style confirmation).
284
+ 7. **Audit (§5.3)** — the merge decision is itself submitted to the
285
+ `AuditScheduler`; high-blast-radius / low-trust merges are forced through the
286
+ oracle. The optimizer audits itself.
287
+
288
+ ## Parallelism & asynchrony
289
+
290
+ AgentDescent ships two execution runtimes and a set of pluggable strategies, so a
291
+ run can be moved along the sync↔async and DP↔TP↔PP axes without touching the
292
+ merge pipeline.
293
+
294
+ ### Two runtimes
295
+
296
+ - **Synchronous DP** ([`orchestrator.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/orchestrator.py)) — a round
297
+ barrier: all workers step, then one `aggregator.step()`, then the next round.
298
+ Deterministic; the RQ1/RQ2 baseline.
299
+ - **Asynchronous stage orchestration** ([`async_runtime.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/async_runtime.py),
300
+ FlashEvolve-style) — **no barrier**. Worker threads keep producing evidence
301
+ while a dedicated aggregator thread keeps merging, connected by the
302
+ thread-safe `EvidenceBuffer`. The rollout/propose and aggregate/commit stages
303
+ overlap instead of stalling.
304
+
305
+ ### Staleness policies ([`staleness.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/staleness.py), FlashEvolve Full/Guarded/Reflective)
306
+
307
+ The active policy is the only thing that changes between async regimes — the
308
+ aggregator asks it `ACCEPT / REBASE / DISCARD` from each diff's `η` and `α`:
309
+
310
+ | Policy | Behaviour | Cost |
311
+ |---|---|---|
312
+ | **Full** | use stale diffs directly (η ignored) | max throughput, min safety |
313
+ | **Guarded** | version-gated: accept `η=0`, rebase `η≤α`, discard beyond | AReaL bounded-staleness |
314
+ | **Reflective** | always rebase + re-verify; discard only if the delta no longer holds | recovers otherwise-wasted proposals |
315
+
316
+ ### `async_ratio` — the ROLL Flash lag budget
317
+
318
+ A worker refreshes its snapshot only once head has drifted more than
319
+ `async_ratio` versions ahead of it. Small ratio → near-synchronous, few stale
320
+ diffs; large ratio → highly asynchronous, many stale diffs the policy must
321
+ handle. A **backpressure** signal forces a global sync if the pipeline stalls
322
+ (evidence keeps arriving but nothing commits).
323
+
324
+ `python -m examples.run_async` shows the trade-off — all three policies converge
325
+ to 1.000, but at `async_ratio=4`:
326
+
327
+ | policy | rollouts | stale discarded | wall-clock |
328
+ |---|---|---|---|
329
+ | Full | ~8k | 0 | ~3.2s |
330
+ | Reflective | ~7.8k | ~0.7k | ~3.3s |
331
+ | Guarded | ~20k | ~17k | ~5.1s |
332
+
333
+ ### DP / TP / PP ([`parallel.py`](https://github.com/Birfy/agentdescent/blob/main/agentdescent/parallel.py), §8)
334
+
335
+ - **DP (data parallel)** — same snapshot, task-sharded, diffs merged. The default
336
+ the async runtime runs.
337
+ - **TP (tensor parallel)** — split one *hot* artifact into disjoint sections;
338
+ each worker owns a section, so edits are conflict-free **by construction** and
339
+ the merge is concatenation + a consistency reviewer (`TensorParallelMerge`).
340
+ - **PP (pipeline parallel)** — artifacts form a dependency chain; a downstream
341
+ failure back-propagates blame to the earliest failing upstream stage
342
+ (`PipelineChain.blame`, shared with the §7 counterfactual-replay attribution).
343
+
344
+ ## The three long tails (§5)
345
+
346
+ AgentDescent treats "the long tail" as three separate problems:
347
+
348
+ - **L-traj** (system): heavy-tailed rollout durations → turn-level checkpoint +
349
+ `ResumeQueue`, resumed against the latest ledger (a free cross-version A/B
350
+ signal).
351
+ - **L-task** (data): Zipfian artifact triggering → **UCB over
352
+ (cluster × artifact)** so starved tail artifacts get an exploration bonus,
353
+ plus a difficulty filter and a tail canary set.
354
+ - **L-value** (signal): most diffs are marginal → `AuditScheduler` spends the
355
+ scarce oracle budget on `blast_radius × uncertainty / trust`.
356
+
357
+ ## Governance (§6)
358
+
359
+ Artifacts sort into layers automatically by `blast_radius`:
360
+
361
+ - **L2 fast** — local skills/prompts → full async merge.
362
+ - **L1 slow** — harness/verifier → serialized in-flight changes + staged rollout.
363
+ - **L0 frozen** — oracle, audit budget, merge permissions, safety constraints →
364
+ read-only to the loop. Without a frozen layer, the self-referential loop
365
+ eventually pollutes itself (a verifier that learns to pass itself).
366
+
367
+ ## Scope & honesty
368
+
369
+ This is a **research reference implementation**, not a production system. It is
370
+ faithful to the design's *mechanisms* and runs end-to-end on a synthetic domain
371
+ so the mechanisms are observable and testable. AgentDescent's novelty is a
372
+ **narrow, defensible engineering synthesis** — concurrent, staleness-bounded,
373
+ conflict-resolved **diff-level merge** over a git-backed versioned ledger — and
374
+ its throughput premise is a *testable engineering hypothesis*, not community
375
+ consensus (cf. FlashEvolve / SkillClaw / CoEvoSkills).