Birfy/agentdescent

What it claims

agentdescent tries to lift a specific bound: serial self-improvement accepts at most one change per iteration. Its approach is to merge concurrent edits from N workers. The authors call the novelty "a narrow engineering synthesis": a concurrent, staleness-bounded, conflict-resolved, diff-level merge over a git-backed versioned ledger. They state that the throughput premise is "a testable hypothesis rather than community consensus." The project describes itself as a research reference implementation, not a production system.

How it works

The design turns on one fact: gradients add, but diffs do not. Workers roll out tasks against ledger snapshots and emit diffs with "evidence cards." A single aggregator thread runs a five-stage merge and commits the winners. The stages include conflict resolution, fusion, statistical acceptance and a transactional commit. The only feedback edge is bounded by a lag budget.

Whether merging can do anything at all depends on the strategy's key space. The strategy has three methods over a flat {key: value} state. Edits on disjoint keys fuse, and edits on the same key conflict. A one-key artifact like SingleSlot can never fuse.

flowchart LR
  L[Ledger snapshot] --> W1[Worker 1]
  L --> W2[Worker N]
  W1 -->|diff + evidence| A[Aggregator]
  W2 -->|diff + evidence| A
  A --> K{Same key?}
  K -->|disjoint| F[Fuse]
  K -->|same| C[Conflict resolve]
  F --> S[Statistical accept]
  C --> S
  S -->|commit, lag-bounded| L
  G[Governance / evaluator] -.not swappable.-> S

The extension points work as follows:

• Protocol seams. The strategy and the other seams are typing.Protocols, so nothing needs to be inherited. A test re-derives their contracts from the engine's call sites.
• Policies bundle. There are eight policy slots in a Policies bundle. Each one defaults to the shipped rule. A driver refuses a policy it cannot honour rather than silently ignoring it.
• Stateful mechanisms. Mechanisms that need state, such as archives, per-instance scores or island pools, use aggregator_factory.
• Fixed governance. The governance layer is deliberately not a seam: the system cannot replace its own evaluator.

Ported algorithms:

• Benchmark-faithful (8): ACE, GEPA, EvoSkill, SkillOpt, ADAS, DGM, OpenEvolve and ERA.
• Microports or analogues (12): the other twelve. The page says these "are not to be cited as benchmark reproductions."
• Fidelity sources: where the paper and the released code differ, each port follows the released code.
• Offline testing: every port has a --dry-run mode that needs no API key.

How to use it

The core engine needs only Python ≥ 3.9 and has zero required dependencies.

pip install agentdescent

The examples are kept outside the package, so you need to clone the repo to run them:

git clone https://github.com/Birfy/agentdescent && cd agentdescent
pip install -e ".[dev]"
python -m examples.run_demo      # no API key, no network

The demo commits three rounds and then stops because nothing is left to improve. Every run prints the counters commit, fused, stale and confl.

Credentials are read from the environment at call time, and the base URL selects the provider (DeepSeek, GLM, local vLLM or OpenAI):

export OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_API_KEY=sk-...

The API is a single call shaped like evolve(tasks, reward, run=, propose=, strategy=, rounds=, n_workers=, max_concurrency=, held_out_frac=, patience=, target_reward=).

• Reward. It must return a value in [0, 1].
• Agent instead of run/propose. Instead of run/propose, you can pass agent=LLMAgent(claude(...) | openai_compatible(...) | claude_code()).
• Barrier-free mode. Add asynchronous=True, async_ratio=3.
• Results. These come back as result.rendered, result.final_reward and result.outcomes().

The page's HotpotQA example works like this:

• Data. 40 validation rows of the distractor config.
• Model. deepseek-v4-flash, with the exact-match scorer.
• Result. It learned "Respond with only the requested answer, omitting any extra explanation or restatement."

Plugin and MCP mode. Setup and the main commands:

bash scripts/setup-hosts.sh
agentdescent demo
agentdescent doctor

• MCP server commands. The server exposes doctor, plan, start, status, show, apply, cancel and resume.
• Run flow. Inside an agent, it quotes the call count, waits for confirmation, runs detached, and asks again before writing back. If you have no examples yet, it drafts 8–20 cases for you to check.
• Artifact kinds. text, skill_dir, agent_dir, agent_code and plugin. Plugin runs use isolated host copies with frozen hooks and permissions, plus a recursion guard.

The test suite (pytest -q) is offline and deterministic.

Limits

• Reporting. The paper reports intervals rather than p-values where comparisons cannot reach significance. It also includes runs where nothing was left to learn.
• Data. The merge-versus-selection sweeps can be re-measured from the command the paper names, but they cannot be recomputed: their per-run data was not retained. Raw data for most other results is in bench/results/.
• Paper source. The paper's source lives on a separate paper branch, so it may diverge from the code.
• Missing results. The fetched page does not include the results table, so no benchmark numbers are given here.
• Licence. No licence is stated on the page.