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.
- agentdescent-0.1.0/LICENSE +21 -0
- agentdescent-0.1.0/PKG-INFO +375 -0
- agentdescent-0.1.0/README.md +355 -0
- agentdescent-0.1.0/agentdescent/__init__.py +169 -0
- agentdescent-0.1.0/agentdescent/agents.py +112 -0
- agentdescent-0.1.0/agentdescent/aggregator.py +370 -0
- agentdescent-0.1.0/agentdescent/async_evolve.py +215 -0
- agentdescent-0.1.0/agentdescent/async_runtime.py +300 -0
- agentdescent-0.1.0/agentdescent/backends.py +195 -0
- agentdescent-0.1.0/agentdescent/dataloader.py +266 -0
- agentdescent-0.1.0/agentdescent/domains/__init__.py +19 -0
- agentdescent-0.1.0/agentdescent/domains/router.py +157 -0
- agentdescent-0.1.0/agentdescent/evolution.py +511 -0
- agentdescent-0.1.0/agentdescent/evolvable.py +146 -0
- agentdescent-0.1.0/agentdescent/governance.py +95 -0
- agentdescent-0.1.0/agentdescent/ledger.py +273 -0
- agentdescent-0.1.0/agentdescent/orchestrator.py +179 -0
- agentdescent-0.1.0/agentdescent/parallel.py +217 -0
- agentdescent-0.1.0/agentdescent/scheduler.py +278 -0
- agentdescent-0.1.0/agentdescent/staleness.py +109 -0
- agentdescent-0.1.0/agentdescent/stats.py +100 -0
- agentdescent-0.1.0/agentdescent/verifier.py +104 -0
- agentdescent-0.1.0/agentdescent/worker.py +91 -0
- agentdescent-0.1.0/agentdescent.egg-info/PKG-INFO +375 -0
- agentdescent-0.1.0/agentdescent.egg-info/SOURCES.txt +52 -0
- agentdescent-0.1.0/agentdescent.egg-info/dependency_links.txt +1 -0
- agentdescent-0.1.0/agentdescent.egg-info/requires.txt +6 -0
- agentdescent-0.1.0/agentdescent.egg-info/top_level.txt +1 -0
- agentdescent-0.1.0/pyproject.toml +33 -0
- agentdescent-0.1.0/setup.cfg +4 -0
- agentdescent-0.1.0/tests/test_ace_example.py +109 -0
- agentdescent-0.1.0/tests/test_adas_example.py +91 -0
- agentdescent-0.1.0/tests/test_agents.py +57 -0
- agentdescent-0.1.0/tests/test_aggregator.py +83 -0
- agentdescent-0.1.0/tests/test_async.py +57 -0
- agentdescent-0.1.0/tests/test_async_evolve.py +82 -0
- agentdescent-0.1.0/tests/test_backends.py +65 -0
- agentdescent-0.1.0/tests/test_bbh_example.py +61 -0
- agentdescent-0.1.0/tests/test_dataloader.py +142 -0
- agentdescent-0.1.0/tests/test_dgm_example.py +95 -0
- agentdescent-0.1.0/tests/test_duration.py +47 -0
- agentdescent-0.1.0/tests/test_efficiency.py +39 -0
- agentdescent-0.1.0/tests/test_evolution.py +119 -0
- agentdescent-0.1.0/tests/test_evoskill_example.py +79 -0
- agentdescent-0.1.0/tests/test_gepa_example.py +113 -0
- agentdescent-0.1.0/tests/test_governance.py +35 -0
- agentdescent-0.1.0/tests/test_harness.py +53 -0
- agentdescent-0.1.0/tests/test_ledger.py +71 -0
- agentdescent-0.1.0/tests/test_orchestrator.py +32 -0
- agentdescent-0.1.0/tests/test_parallel.py +136 -0
- agentdescent-0.1.0/tests/test_skillopt_example.py +95 -0
- agentdescent-0.1.0/tests/test_staleness.py +46 -0
- agentdescent-0.1.0/tests/test_stats_and_staleness.py +43 -0
- 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
|
+
[](https://birfy.github.io/agentdescent/)
|
|
28
|
+
[](https://github.com/Birfy/agentdescent/actions/workflows/docs.yml)
|
|
29
|
+
[](https://www.python.org/)
|
|
30
|
+
[](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).
|