darwinagent 0.1.0__tar.gz

darwinagent-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+third_party/
+*.egg-info/
+.DS_Store
+.jdk/
+.env.bak*
+
+# ---- 框架净化（2026-10-07，操作者拍板）：仓库只保留框架代码/文档/任务适配与基准数据 ----
+# 一切实验运行产物与快照种子不入库（磁盘保留＋HF 归档承载）
+datasets/*/runs/
+datasets/locomo/snapshots/
+datasets/loomo_runs_typo_check/
+runs/
+embed_cache.json
+embed_cache.tmp
+
+# ---- 构建产物与本地参考资料 ----
+dist/
+papers/
+
+# Local packaging and test artifacts
+/build/
+.coverage
+.pytest_cache/
+htmlcov/

darwinagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DarwinAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

darwinagent-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: darwinagent
+Version: 0.1.0
+Summary: Evolution for the Agent Era: experience-driven recursive self-improvement for agents
+Project-URL: Repository, https://github.com/gogoingai/DarwinAgent
+Project-URL: Documentation, https://github.com/gogoingai/DarwinAgent#readme
+Project-URL: Issues, https://github.com/gogoingai/DarwinAgent/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-memory,agents,darwinagent,recursive-self-improvement
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: openai>=1.40
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: benchmarks
+Requires-Dist: datasets>=2.20; extra == 'benchmarks'
+Requires-Dist: gradio>=6.0.0; extra == 'benchmarks'
+Requires-Dist: numpy>=1.26; extra == 'benchmarks'
+Requires-Dist: pandas>=2.1; extra == 'benchmarks'
+Requires-Dist: requests>=2.31; extra == 'benchmarks'
+Requires-Dist: rich>=13.0; extra == 'benchmarks'
+Requires-Dist: tqdm>=4.66; extra == 'benchmarks'
+Provides-Extra: formal
+Requires-Dist: owlready2>=0.46; extra == 'formal'
+Provides-Extra: vector
+Requires-Dist: numpy>=1.26; extra == 'vector'
+Requires-Dist: requests>=2.31; extra == 'vector'
+Description-Content-Type: text/markdown
+
+# DarwinAgent
+
+**Evolution for the Agent Era** · **Agent 时代的进化**
+
+An open framework for experience-driven recursive self-improvement of AI agents.
+DarwinAgent takes its name from Charles Darwin and the theory of evolution:
+propose changes to task assets, select through independent evaluation, retain
+effective versions, and use a persistent experience Wiki to inform subsequent
+proposals.
+
+**Version 0.1.0 is experimental.** Improvement is an outcome to measure, and a
+candidate can be rejected. The framework does not train model weights or rewrite
+its own optimizer.
+
+## Install and try the loop
+
+Python 3.11 or newer is required. In your Python environment:
+
+```bash
+python -m pip install darwinagent
+darwinagent --version
+darwinagent doctor --output runs/doctor
+darwinagent demo --mode replay --rounds 2 --output runs/demo-replay
+darwinagent demo --mode replay --rounds 2 --output runs/demo-replay --resume
+```
+
+Replay requires no API key or network. It executes the actual controller, task
+runtime, evaluation, admission, Wiki, and asset publication with scripted model
+responses. In one tiny synthetic maintenance task, the first candidate is accepted
+and the second is rejected on a tie; HTTP attempts are zero. This demonstrates
+the mechanism and does not establish model learning or benchmark gains.
+
+For real model execution, set `DARWINAGENT_API_KEY`, `DARWINAGENT_BASE_URL`, and
+`DARWINAGENT_MODEL` to your OpenAI-compatible Chat Completions endpoint, then run:
+
+```bash
+darwinagent demo --mode live --rounds 2 --output runs/demo-live \
+  --max-requests 40 --timeout 1800
+```
+
+Live mode calls the configured model. The request cap counts dispatched HTTP
+attempts, including retries, and the timeout covers the whole run.
+
+## Bring your own task
+
+Register S/F/C/P assets: schemas, query functions, task checks, and role prompts.
+Connect a dataset adapter and an independent evaluator to the shared `Pipeline`
+and `ExperimentRunner`. The framework's executor, evaluator, permissions, and
+adoption policy remain outside the proposal boundary.
+
+## Documentation
+
+- [English README](https://github.com/gogoingai/DarwinAgent/blob/main/README.md)
+- [中文说明](https://github.com/gogoingai/DarwinAgent/blob/main/README.zh-CN.md)
+- [Quickstart](https://github.com/gogoingai/DarwinAgent/blob/main/docs/en/quickstart.md)
+- [中文快速开始](https://github.com/gogoingai/DarwinAgent/blob/main/docs/zh-CN/quickstart.md)
+- [Acceptance evidence](https://github.com/gogoingai/DarwinAgent/blob/main/docs/acceptance/2026-10-07.md)
+- [Source and issues](https://github.com/gogoingai/DarwinAgent)
+
+DarwinAgent is distributed under the MIT license.

darwinagent-0.1.0/README.md

@@ -0,0 +1,178 @@
+<p align="center"><img src="docs/assets/hero-en.svg" alt="DarwinAgent — Evolution for the Agent Era" width="100%"></p>
+
+# DarwinAgent
+
+**An Open Framework for Experience-Driven Recursive Self-Improvement**
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+[![Offline framework checks](https://github.com/gogoingai/DarwinAgent/actions/workflows/ci.yml/badge.svg)](https://github.com/gogoingai/DarwinAgent/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-0.1.0%20experimental-45635c)](CHANGELOG.md)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.11-45635c)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-45635c)](LICENSE)
+
+DarwinAgent takes its name from Charles Darwin and the theory of evolution. **Evolution for the Agent Era** is its mission: help agents adapt through experience and retain effective capabilities. In this framework, variation comes from proposed task assets, selection comes from independent evaluation and fixed admission rules, and retention comes from versioned assets and a persistent experience Wiki that informs subsequent proposals.
+
+DarwinAgent **0.1.0 is experimental**. It implements an inspectable improvement loop around a shared graph-based agent runtime. Improvement is an outcome to measure; a candidate can be rejected. The current scope is task assets, with fixed framework execution and evaluation boundaries.
+
+## Why DarwinAgent
+
+A useful answer is one run. A useful capability should survive the next run. DarwinAgent records what a candidate changed, which sources supported an answer, how it was evaluated, why it was accepted or rejected, and what experience reaches the next proposal. This makes adaptation a reproducible experiment rather than an untracked prompt edit.
+
+## The evolution loop
+
+![Evolution loop](docs/assets/evolution-loop-en.svg)
+
+1. **Run:** execute a baseline through the common `Pipeline` and score its actual outputs.
+2. **Vary:** propose bounded changes to S/F/C/P assets using training evidence and Wiki feedback.
+3. **Select:** validate contracts and capabilities, run the candidate, and apply the frozen adoption policy.
+4. **Retain:** publish accepted versions atomically; preserve rejection facts and feed experience into the next proposal.
+
+The kernel, evaluator, permissions, and adoption rules stay outside the proposal boundary. DarwinAgent does not train model weights or rewrite its own optimizer. Its name describes the inspiration, not a claim to implement a genetic algorithm.
+
+## What is implemented
+
+| Capability | v0.1.0 behavior |
+| --- | --- |
+| Shared task runtime | `ExtractionAgent` → attributed graph → `AnswerAgent`, through one `Pipeline` |
+| Bounded task assets | **S** schemas, **F** query functions, **C** task checks, **P** role prompts |
+| Experience | Wiki stores observations and accepted/rejected decisions for subsequent proposals |
+| Reproducibility | Content identities, separate provenance, scoped resume and optional strict comparison |
+| Evaluation | Separate `DatasetAdapter` and `Evaluator`; metric names supplied by the task |
+| Experiment control | `ExperimentRunner`; separate `CampaignController` for train/validation/test protocols |
+| Model connection | One explicit OpenAI-compatible Chat Completions endpoint by default; optional tier overrides |
+| Entry points | Installed CLI, Python SDK, offline replay, live mode, maintenance task example |
+
+## Try the loop
+
+Install **from this source checkout**. DarwinAgent 0.1.0 is available on `main` as an experimental source version; it has not been published to PyPI or as a GitHub Release.
+
+```bash
+# Run from this source checkout; Python 3.11+ and uv are required.
+uv sync --frozen
+uv run darwinagent --version
+uv run darwinagent doctor --output runs/doctor
+uv run darwinagent demo --mode replay --rounds 2 --output runs/demo-replay
+```
+
+Expected replay: `status=complete`, first candidate accepted, second rejected for `primary_not_strictly_improved`, and `http_attempts=0`. The independent evaluator scores requested technician/date fields **0.5 → 1.0 → 1.0** in one tiny synthetic task. Replay uses scripted model responses, a seeded B0, and **P-only** proposals through the real controller and runtime. It demonstrates mechanics, not model learning or benchmark gains; it has no held-out evaluation.
+
+The output directory contains:
+
+```text
+runs/demo-replay/
+├── experiment.json                           # original experiment declaration
+├── B0/evaluation/maintenance-demo.json         # baseline score
+├── R1/evaluation/maintenance-demo.json         # candidate score (also R2)
+├── R1/optimization/attempt-0/proposal-call.json # proposal input (also R2)
+├── optimization/wiki.json                     # durable experience
+├── published/current.json                     # accepted asset version
+└── demo-summary.json                          # controller summary
+```
+
+For live execution, configure your endpoint and use a separate output directory:
+
+```bash
+cp .env.example .env
+# Set DARWINAGENT_API_KEY, DARWINAGENT_BASE_URL, DARWINAGENT_MODEL in .env.
+uv run darwinagent demo --mode live --rounds 2 --output runs/demo-live \
+  --max-requests 40 --timeout 1800
+```
+
+The CLI reads the current directory's `.env` without overriding shell variables. Live uses the actual model, with no recorded fallback. The cap counts dispatched HTTP attempts, including retries; the timeout covers the whole run. A live baseline may already be correct, so ties are rejected. Success means the stages execute and decisions are recorded, not that the score must improve.
+
+Daily continuation retains saved work across changes to models and execution controls. Source changes take effect after a safe restart; use `--strict-comparison` when requiring the original frozen comparison conditions:
+
+```bash
+uv run darwinagent demo --mode replay --rounds 2 --output runs/demo-replay --resume
+```
+
+Or call the demo from Python:
+
+```python
+import asyncio
+from pathlib import Path
+from darwinagent.demo import run_demo
+
+asyncio.run(run_demo(Path("runs/python-replay"), mode="replay", rounds=2))
+```
+
+[Full quickstart](docs/en/quickstart.md) · [Configuration](docs/en/configuration.md) · [Dated acceptance evidence](docs/acceptance/2026-10-07.md)
+
+## Bring your own task
+
+Implement the generation boundary and an independent evaluator, then register task assets in `task.yaml` and `assets/index.yaml`. The generation input carries records, questions, and source references; evaluator references stay in the evaluator.
+
+```python
+from darwinagent import (
+    CaseInput, CorpusBlock, QuestionInput, SourceRef, EvaluationResult,
+)
+
+class Records:
+    def generation_input(self, case_id):
+        return CaseInput(case_id,
+            (CorpusBlock(SourceRef("maintenance_record", case_id, "row-1"),
+                         "设备 D-17 于 2026-09-01 由林维护。"),),
+            (QuestionInput("q1", "谁在什么时候维护了 D-17？",
+                           {"serial": "D-17"}),))
+
+class Score:
+    async def evaluate(self, result):
+        correct = sum(a.status == "answered" and "林" in a.answer
+                      and "2026-09-01" in a.answer for a in result.answers)
+        faults = sum(a.status == "execution_error" for a in result.answers)
+        return EvaluationResult({"correct": correct}, len(result.answers),
+                                len(result.answers) - faults, faults, 0)
+```
+
+Load the actual packaged declaration and asset registry:
+
+```python
+from darwinagent import TaskSpec
+from darwinagent.demo import TASK_ROOT
+from darwinagent.kernel.registration import load_assets
+
+assets = load_assets(TASK_ROOT)  # task.yaml + assets/index.yaml + S/F/C/P files
+spec = TaskSpec.load(TASK_ROOT / "task.yaml")
+```
+
+These classes plug into the common runtime; they do not replace the agent execution flow. The [complete offline example](examples/third_domain.py) runs both interfaces with registered S/F/C/P assets:
+
+```bash
+uv run python examples/third_domain.py
+```
+
+See the [custom task guide](docs/en/custom-tasks.md) for a complete live `Pipeline` example and asset contracts. Arbitrary external agent plugins are a future extension, not a v0.1 capability.
+
+## Architecture and documentation
+
+![Architecture](docs/assets/architecture-en.svg)
+
+| Guide | English | 简体中文 |
+| --- | --- | --- |
+| Quickstart | [Read](docs/en/quickstart.md) | [阅读](docs/zh-CN/quickstart.md) |
+| Architecture | [Read](docs/en/architecture.md) | [阅读](docs/zh-CN/architecture.md) |
+| Configuration | [Read](docs/en/configuration.md) | [阅读](docs/zh-CN/configuration.md) |
+| Custom tasks | [Read](docs/en/custom-tasks.md) | [阅读](docs/zh-CN/custom-tasks.md) |
+| Experiments | [Read](docs/en/experiments.md) | [阅读](docs/zh-CN/experiments.md) |
+| Migration | [Read](docs/en/migration.md) | [阅读](docs/zh-CN/migration.md) |
+
+[Historical evidence index](docs/history/README.md) · [Editable graphics and PNG exports](docs/assets/README.md) · [Project introduction](docs/launch/introduction.en.md)
+
+## Status and direction
+
+The local Python 3.11/3.12/3.13 suites and installed-wheel acceptance are documented in the [dated report](docs/acceptance/2026-10-07.md). The workflow badge shows the latest GitHub CI status. Historical dataset scores belong to their original protocols and source revisions.
+
+Next directions are broader independent task examples, controlled held-out studies, and a carefully specified external agent integration boundary. These are research and engineering plans, not shipped capabilities or promised quality gains.
+
+## Research provenance and community
+
+The S/F kernel is inspired by [*Toward Effective and Reliable LLM Agents via Dynamic Ontology*](https://arxiv.org/abs/2608.22974) (OaK). C/P assets and the experience Wiki are engineering extensions in this project. Historical reproduction records remain separately indexed; no paper performance numbers are used as current DarwinAgent results.
+
+[Contributing](CONTRIBUTING.md) · [中文贡献指南](CONTRIBUTING.zh-CN.md) · [Changelog](CHANGELOG.md) · [Software citation](CITATION.cff)
+
+MIT © 2026 DarwinAgent contributors. See [LICENSE](LICENSE); third-party material retains its own license and provenance.
+
+## Durable continuation and Wiki queries
+
+The Workspace APIs and offline CLI retain original evidence, request receipts, human selection history and scoped previews. Wiki queries can return raw evidence or create a resumable regroup task. See [the continuation guide](docs/workspace-continuation.md). Real model smoke remains pending explicit model selection and execution; these interfaces do not establish benchmark gains.

darwinagent-0.1.0/README.pypi.md

@@ -0,0 +1,60 @@
+# DarwinAgent
+
+**Evolution for the Agent Era** · **Agent 时代的进化**
+
+An open framework for experience-driven recursive self-improvement of AI agents.
+DarwinAgent takes its name from Charles Darwin and the theory of evolution:
+propose changes to task assets, select through independent evaluation, retain
+effective versions, and use a persistent experience Wiki to inform subsequent
+proposals.
+
+**Version 0.1.0 is experimental.** Improvement is an outcome to measure, and a
+candidate can be rejected. The framework does not train model weights or rewrite
+its own optimizer.
+
+## Install and try the loop
+
+Python 3.11 or newer is required. In your Python environment:
+
+```bash
+python -m pip install darwinagent
+darwinagent --version
+darwinagent doctor --output runs/doctor
+darwinagent demo --mode replay --rounds 2 --output runs/demo-replay
+darwinagent demo --mode replay --rounds 2 --output runs/demo-replay --resume
+```
+
+Replay requires no API key or network. It executes the actual controller, task
+runtime, evaluation, admission, Wiki, and asset publication with scripted model
+responses. In one tiny synthetic maintenance task, the first candidate is accepted
+and the second is rejected on a tie; HTTP attempts are zero. This demonstrates
+the mechanism and does not establish model learning or benchmark gains.
+
+For real model execution, set `DARWINAGENT_API_KEY`, `DARWINAGENT_BASE_URL`, and
+`DARWINAGENT_MODEL` to your OpenAI-compatible Chat Completions endpoint, then run:
+
+```bash
+darwinagent demo --mode live --rounds 2 --output runs/demo-live \
+  --max-requests 40 --timeout 1800
+```
+
+Live mode calls the configured model. The request cap counts dispatched HTTP
+attempts, including retries, and the timeout covers the whole run.
+
+## Bring your own task
+
+Register S/F/C/P assets: schemas, query functions, task checks, and role prompts.
+Connect a dataset adapter and an independent evaluator to the shared `Pipeline`
+and `ExperimentRunner`. The framework's executor, evaluator, permissions, and
+adoption policy remain outside the proposal boundary.
+
+## Documentation
+
+- [English README](https://github.com/gogoingai/DarwinAgent/blob/main/README.md)
+- [中文说明](https://github.com/gogoingai/DarwinAgent/blob/main/README.zh-CN.md)
+- [Quickstart](https://github.com/gogoingai/DarwinAgent/blob/main/docs/en/quickstart.md)
+- [中文快速开始](https://github.com/gogoingai/DarwinAgent/blob/main/docs/zh-CN/quickstart.md)
+- [Acceptance evidence](https://github.com/gogoingai/DarwinAgent/blob/main/docs/acceptance/2026-10-07.md)
+- [Source and issues](https://github.com/gogoingai/DarwinAgent)
+
+DarwinAgent is distributed under the MIT license.

darwinagent-0.1.0/README.zh-CN.md

@@ -0,0 +1,178 @@
+<p align="center"><img src="docs/assets/hero-zh-CN.svg" alt="DarwinAgent — Agent 时代的进化" width="100%"></p>
+
+# DarwinAgent
+
+**面向 Agent 经验驱动递归自改进的开源框架**
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+[![Offline framework checks](https://github.com/gogoingai/DarwinAgent/actions/workflows/ci.yml/badge.svg)](https://github.com/gogoingai/DarwinAgent/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-0.1.0%20experimental-45635c)](CHANGELOG.md)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.11-45635c)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-45635c)](LICENSE)
+
+DarwinAgent 的名字来自查尔斯·达尔文与进化论。**Agent 时代的进化**是项目的使命：让 Agent 从经验中适应任务，并保留有效的能力。在这个框架里，资产提案产生候选变化，独立评测和固定准入规则负责筛选，版本化资产与持久化经验 Wiki 负责保留结果，并影响下一轮提案。
+
+DarwinAgent **0.1.0 是实验版本**。它围绕基于图的共享 Agent 运行时，实现了可检查的迭代流程。改进是否发生需要测量，候选也可能被拒绝。当前优化范围是任务资产，框架的执行流程和评测边界保持固定。
+
+## 为什么做 DarwinAgent
+
+一次答对说明这次运行成功，有效的能力还应该在下一次运行中保留下来。DarwinAgent 记录候选改了什么、回答依据哪些来源、评测得到了什么结果、为什么采纳或拒绝，以及哪些经验进入下一轮提案。这样，适应过程就能成为可复查的实验，而不只是一次没有记录的提示词修改。
+
+## 进化循环
+
+![进化循环](docs/assets/evolution-loop-zh-CN.svg)
+
+1. **运行：**通过共同的 `Pipeline` 执行基线，按实际输出评分。
+2. **变化：**结合训练证据与 Wiki 反馈，提出有边界的 S/F/C/P 资产修改。
+3. **筛选：**验证契约与能力边界，运行候选，按冻结的采纳策略决定是否保留。
+4. **积累：**原子发布被采纳的版本；保留拒绝记录，让经验进入下一轮提案。
+
+内核、评测器、权限和采纳规则位于提案边界之外。DarwinAgent 不训练模型权重，也不重写自己的优化器。项目名称表达的是进化论带来的启发，并不表示实现了遗传算法。
+
+## 已实现的能力
+
+| 能力 | v0.1.0 的实际行为 |
+| --- | --- |
+| 共享任务运行时 | `ExtractionAgent` → 带来源的图 → `AnswerAgent`，由一个 `Pipeline` 执行 |
+| 有边界的任务资产 | **S** 本体／模式、**F** 查询工具函数、**C** 任务检查、**P** 角色提示词 |
+| 经验积累 | Wiki 保存观察和采纳／拒绝决策，供后续提案使用 |
+| 可复查运行 | 内容编号、独立来源、局部续跑与显式严格比较 |
+| 独立评测 | 分开的 `DatasetAdapter` 和 `Evaluator`，任务自行定义指标名称 |
+| 实验控制 | `ExperimentRunner`；另有 `CampaignController` 管理训练／验证／测试协议 |
+| 模型连接 | 默认共用一个显式配置的 OpenAI 兼容 Chat Completions 端点，可按档位覆盖 |
+| 使用入口 | 安装后的 CLI、Python SDK、离线回放、真实模型模式、设备维护示例 |
+
+## 跑通循环
+
+**从当前源码检出目录安装**。DarwinAgent 0.1.0 已作为实验性源码版本合入 `main`，尚未发布到 PyPI 或创建 GitHub Release。
+
+```bash
+# 在当前源码检出目录运行，需要 Python 3.11+ 和 uv。
+uv sync --frozen
+uv run darwinagent --version
+uv run darwinagent doctor --output runs/doctor
+uv run darwinagent demo --mode replay --rounds 2 --output runs/demo-replay
+```
+
+回放的预期结果：`status=complete`，第一轮采纳，第二轮因 `primary_not_strictly_improved` 拒绝，`http_attempts=0`。独立评测器在一个微型合成任务中，按维护人员／日期两个字段得到 **0.5 → 1.0 → 1.0**。回放使用脚本模型响应、预置 B0 和 **仅 P 资产**的提案，实际执行控制器与运行时。它验证机制，不证明模型学习或基准提升，也没有留出集评测。
+
+输出目录包括：
+
+```text
+runs/demo-replay/
+├── experiment.json                           # original experiment declaration
+├── B0/evaluation/maintenance-demo.json         # baseline score
+├── R1/evaluation/maintenance-demo.json         # candidate score (also R2)
+├── R1/optimization/attempt-0/proposal-call.json # proposal input (also R2)
+├── optimization/wiki.json                     # durable experience
+├── published/current.json                     # accepted asset version
+└── demo-summary.json                          # controller summary
+```
+
+真实模型运行需要配置端点，并使用另一个输出目录：
+
+```bash
+cp .env.example .env
+# 在 .env 中填写 DARWINAGENT_API_KEY、DARWINAGENT_BASE_URL、DARWINAGENT_MODEL。
+uv run darwinagent demo --mode live --rounds 2 --output runs/demo-live \
+  --max-requests 40 --timeout 1800
+```
+
+CLI 读取当前目录的 `.env`，不覆盖已有环境变量。真实模式调用实际模型，不回退到录制响应。请求上限按实际发出的 HTTP 尝试计数，包括重试；超时限制覆盖整个运行。真实模型可能在 B0 就全部答对，同分候选应当被拒绝。验收成功表示各阶段执行且决策留痕，不要求分数必然上升。
+
+日常续跑保留已有成果，模型和执行控制变化不会清空进度。源码修改在安全重启后生效；需要原冻结条件比较时显式添加 `--strict-comparison`：
+
+```bash
+uv run darwinagent demo --mode replay --rounds 2 --output runs/demo-replay --resume
+```
+
+也可以从 Python 调用：
+
+```python
+import asyncio
+from pathlib import Path
+from darwinagent.demo import run_demo
+
+asyncio.run(run_demo(Path("runs/python-replay"), mode="replay", rounds=2))
+```
+
+[完整快速开始](docs/zh-CN/quickstart.md) · [配置](docs/zh-CN/configuration.md) · [带日期的验收证据](docs/acceptance/2026-10-07.md)
+
+## 接入自己的任务
+
+实现生成输入接口和独立评测器，再通过 `task.yaml` 与 `assets/index.yaml` 登记任务资产。生成输入只携带记录、问题和来源；评测参考保留在评测器内部。
+
+```python
+from darwinagent import (
+    CaseInput, CorpusBlock, QuestionInput, SourceRef, EvaluationResult,
+)
+
+class Records:
+    def generation_input(self, case_id):
+        return CaseInput(case_id,
+            (CorpusBlock(SourceRef("maintenance_record", case_id, "row-1"),
+                         "设备 D-17 于 2026-09-01 由林维护。"),),
+            (QuestionInput("q1", "谁在什么时候维护了 D-17？",
+                           {"serial": "D-17"}),))
+
+class Score:
+    async def evaluate(self, result):
+        correct = sum(a.status == "answered" and "林" in a.answer
+                      and "2026-09-01" in a.answer for a in result.answers)
+        faults = sum(a.status == "execution_error" for a in result.answers)
+        return EvaluationResult({"correct": correct}, len(result.answers),
+                                len(result.answers) - faults, faults, 0)
+```
+
+加载实际打包的任务声明与资产登记：
+
+```python
+from darwinagent import TaskSpec
+from darwinagent.demo import TASK_ROOT
+from darwinagent.kernel.registration import load_assets
+
+assets = load_assets(TASK_ROOT)  # task.yaml + assets/index.yaml + S/F/C/P files
+spec = TaskSpec.load(TASK_ROOT / "task.yaml")
+```
+
+这两个类接入共同运行时，不替换 Agent 执行流程。[完整离线示例](examples/third_domain.py) 将这两个接口和已登记的 S/F/C/P 资产一起运行：
+
+```bash
+uv run python examples/third_domain.py
+```
+
+[自定义任务指南](docs/zh-CN/custom-tasks.md)提供完整的真实模型 `Pipeline` 示例及资产契约。任意外部 Agent 的插件接入是后续方向，不是 v0.1 已有能力。
+
+## 架构与文档
+
+![架构](docs/assets/architecture-zh-CN.svg)
+
+| 指南 | English | 简体中文 |
+| --- | --- | --- |
+| 快速开始 | [Read](docs/en/quickstart.md) | [阅读](docs/zh-CN/quickstart.md) |
+| 架构 | [Read](docs/en/architecture.md) | [阅读](docs/zh-CN/architecture.md) |
+| 配置 | [Read](docs/en/configuration.md) | [阅读](docs/zh-CN/configuration.md) |
+| 自定义任务 | [Read](docs/en/custom-tasks.md) | [阅读](docs/zh-CN/custom-tasks.md) |
+| 实验 | [Read](docs/en/experiments.md) | [阅读](docs/zh-CN/experiments.md) |
+| 迁移 | [Read](docs/en/migration.md) | [阅读](docs/zh-CN/migration.md) |
+
+[历史证据索引](docs/history/README.md) · [可编辑图源与 PNG](docs/assets/README.md) · [项目介绍稿](docs/launch/introduction.zh-CN.md)
+
+## 状态与后续方向
+
+本地 Python 3.11／3.12／3.13 测试和安装后 wheel 验收记录见[带日期的报告](docs/acceptance/2026-10-07.md)。工作流徽章显示 GitHub CI 的最新状态。历史数据集成绩属于原来的协议和源码版本。
+
+后续计划包括更多独立任务示例、受控留出集实验，以及明确的外部 Agent 接入边界。这些是研究与工程方向，不是已交付能力，也不承诺质量提升。
+
+## 研究来源与社区
+
+S/F 内核受 [*Toward Effective and Reliable LLM Agents via Dynamic Ontology*](https://arxiv.org/abs/2608.22974)（OaK）启发。C/P 资产与经验 Wiki 是本项目的工程扩展。历史复现记录另行索引；论文中的性能数字不作为当前 DarwinAgent 的结果。
+
+[贡献指南](CONTRIBUTING.zh-CN.md) · [English contribution guide](CONTRIBUTING.md) · [变更记录](CHANGELOG.md) · [软件引用](CITATION.cff)
+
+MIT © 2026 DarwinAgent contributors。见 [LICENSE](LICENSE)，第三方材料保留各自的许可证与来源。
+
+## 人工干预、续跑与 Wiki 补查
+
+Workspace 将原始内容、执行来源和分支选择分别保存，提供人工登记、执行预览、请求恢复及安全导入导出。Wiki 可以返回原件，并建立可续跑的重新归纳任务。操作说明见[续跑与补查指南](docs/workspace-continuation.zh-CN.md)。真实模型仍需操作者指定并实际执行五题冒烟；离线检查不代表真实冒烟通过或指标提升。

darwinagent-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "darwinagent"
+version = "0.1.0"
+description = "Evolution for the Agent Era: experience-driven recursive self-improvement for agents"
+readme = "README.pypi.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["agents", "recursive-self-improvement", "agent-memory", "darwinagent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "openai>=1.40",
+    "httpx>=0.27",
+    "networkx>=3.6.1",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Repository = "https://github.com/gogoingai/DarwinAgent"
+Documentation = "https://github.com/gogoingai/DarwinAgent#readme"
+Issues = "https://github.com/gogoingai/DarwinAgent/issues"
+
+[project.scripts]
+darwinagent = "darwinagent.cli:main"
+
+[project.optional-dependencies]
+vector = ["numpy>=1.26", "requests>=2.31"]
+formal = ["owlready2>=0.46"]
+benchmarks = [
+    "pandas>=2.1",
+    "numpy>=1.26",
+    "datasets>=2.20",
+    "tqdm>=4.66",
+    "rich>=13.0",
+    "gradio>=6.0.0",
+    "requests>=2.31",
+]
+
+[dependency-groups]
+test = ["numpy>=1.26", "pandas>=2.1", "requests>=2.31", "ruff==0.16.10"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+indent-width = 4
+preview = false
+force-exclude = true
+include = ["src/**/*.py", "tests/**/*.py", "datasets/**/*.py", "examples/**/*.py", "scripts/check_installed.py"]
+extend-exclude = [
+    "src/darwinagent/demo/device_maintenance/assets",
+    "tests/fixtures",
+    "tasks",
+    "datasets/*/scripts",
+    "datasets/locomo/data",
+    "datasets/travelplanner/data",
+    "datasets/*/runs",
+    "datasets/*/snapshots",
+    "docs/diagnostics",
+    "docs/history",
+    "mem0",
+    "third_party",
+    "oak",
+]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B006", "B023", "B904"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+docstring-code-format = false
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/darwinagent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/darwinagent",
+    "/pyproject.toml",
+    "/README.pypi.md",
+    "/README.md",
+    "/README.zh-CN.md",
+    "/LICENSE",
+]