featurebench 0.2.2__tar.gz → 0.3.0__tar.gz

featurebench-0.3.0/.env.example

@@ -0,0 +1,8 @@
+# GitHub API discovery only. Multiple tokens may be comma-separated.
+GITHUB_TOKEN=
+
+# Set only the provider credentials required by the configured Agent model.
+OPENAI_BASE_URL=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=

{featurebench-0.2.2 → featurebench-0.3.0}/.gitignore

@@ -8,11 +8,7 @@ cases_filter/*
 *log/
 *logs/
 featurebench/resources/repos
-featurebench/resources/constants/*
-!featurebench/resources/constants/python_example.py
-!featurebench/resources/constants/full_images.txt
-!featurebench/resources/constants/lite_images.txt
-!featurebench/resources/constants/fast_images.txt
+.featurebench/
 config.toml
 tmp/
 runs/

featurebench-0.3.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: featurebench
+Version: 0.3.0
+Summary: Build reproducible coding environments, generate FeatureBench tasks, and evaluate coding agents.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: datasets>=3.3.3
+Requires-Dist: docker>=5.0.3
+Requires-Dist: genai-prices>=0.0.72
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: huggingface-hub>=0.26.5
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: ortools>=9.12.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic-ai-harness<0.13,>=0.12.0
+Requires-Dist: pydantic-ai<2.20,>=2.19.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich<16,>=15.0.0
+Requires-Dist: textual<9,>=8.0.0
+Requires-Dist: toml>=0.10.2
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.2.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=8.4.2; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/pics/logo.png" style="height: 10em" alt="logo" />
+</p>
+
+<p align="center">
+  <a href="https://arxiv.org/abs/2602.10975"><img src="https://img.shields.io/badge/arXiv-2602.10975-b31b1b.svg" alt="arXiv"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+  <a href="https://hub.docker.com/u/libercoders"><img src="https://img.shields.io/badge/DockerHub-Images-blue.svg" alt="DockerHub"></a>
+  <a href="https://huggingface.co/datasets/LiberCoders/FeatureBench"><img src="https://img.shields.io/badge/HuggingFace-datasets-yellow.svg" alt="HuggingFace"></a>
+  <a href="https://libercoders.github.io/FeatureBench/leaderboard/"><img src="https://img.shields.io/badge/Leaderboard-view-purple.svg" alt="Leaderboard"></a>
+</p>
+
+---
+
+FeatureBench combines a feature-level coding benchmark with a fully automated, **Universal Coding
+Data Factory**. With one CLI, it continuously discovers GitHub repositories, builds reproducible
+environments across languages, and generates validated coding tasks for training and evaluation
+through extensible Adapters.
+
+## 📰 News
+
+🏭 **2026.10.30**: We launched a **Universal Coding Data Factory**—fully automated, language-agnostic, and Adapter-driven—to continuously turn GitHub repositories into validated training data for any coding task format.
+
+📈 **2026.10.30**: In internal mixed-task RL experiments using data from our **Universal Coding Data Factory**, Qwen3.8-27B improved SWE-bench Verified Pass@1 from **70.2% to a peak of 79.8%** and FeatureBench 1.1 Tests Passed from **50.3% to a peak of 60.3%**.
+
+📦 **2026.08.24**: We released **FeatureBench Dataset V1.1**, primarily correcting inconsistencies and omissions in task problem statements.
+
+📊 **2026.05.18**: We added **lite split** evaluation results for frontier models including **GPT-5.5, Claude Opus 4.7, DeepSeek-V4, GLM-5.1, Kimi-2.6, Mimo-V2.5-Pro**, and more to the leaderboard.
+
+🚀 **2026.03.27**: We released the **fast split** containing 100 instances (a subset of full split). These instances require no GPU and are optimized for rapid evaluation. On an Intel Xeon Platinum 8457C with 944GB RAM, the average evaluation time per instance using gold patches is **57.2 seconds**.
+
+🎁 **2026.02.06**: We added one-click inference for mainstream agent frameworks, including **OpenHands, Claude Code, Codex, Gemini CLI, and mini-swe-agent**. All supported agent frameworks can be found [here](featurebench/infer/agents/).
+
+<!-- LEADERBOARD_START -->
+## 🏆 Leaderboard
+
+[Full interactive leaderboard](https://libercoders.github.io/FeatureBench/leaderboard/) with tabs, filters, and sorting (Dataset V1.0).
+
+<details open>
+<summary><b>Lite split results, ranked by %PASSED</b></summary>
+
+| Rank | Model | Scaffold | %PASSED | %RESOLVED |
+|---:|---|---|---:|---:|
+| 1 | Claude Opus 4.7 | OpenHands | 78.2 | 46.7 |
+| 2 | GPT-5.5 | OpenHands | 69.8 | 26.7 |
+| 3 | Claude Opus 4.6 | OpenHands | 69.5 | 20 |
+| 4 | Claude Opus 4.5 | OpenHands | 67.2 | 20 |
+| 5 | GPT-5.4 | OpenHands | 66.2 | 23.3 |
+| 6 | GPT-5.1-Codex | Codex | 60.2 | 20 |
+| 7 | DeepSeek-V4-Pro | OpenHands | 59.6 | 26.7 |
+| 8 | Claude Opus 4.5 | Claude Code | 59.1 | 20 |
+| 9 | Kimi-2.6 | OpenHands | 49.4 | 20 |
+| 10 | Mimo-V2.5-Pro | OpenHands | 47.8 | 13.3 |
+| 11 | Gemini-3-Pro-Preview | OpenHands | 45.1 | 10 |
+| 12 | GLM-5.1 | OpenHands | 44.2 | 13.3 |
+| 13 | Gemini-3-Pro-Preview | Gemini-CLI | 43.4 | 10 |
+| 14 | DeepSeek-V4-Flash | OpenHands | 41.9 | 16.7 |
+| 15 | MiniMax M2.1 | Mini-SWE-Agent | 41.9 | 10 |
+| 16 | GLM 4.7 | Mini-SWE-Agent | 41.2 | 6.7 |
+| 17 | Qwen3-Coder-480B-A35B-Instruct | OpenHands | 38.3 | 6.7 |
+| 18 | DeepSeek V3.2 | OpenHands | 35.9 | 6.7 |
+| 19 | Qwen3.5-27B | OpenHands | 34.8 | 10.0 |
+| 20 | Qwen3-Coder-30B-A3B-Instruct | OpenHands | 23 | 3.3 |
+
+</details>
+<!-- LEADERBOARD_END -->
+
+## 🚀 Quickstart
+
+**Prerequisites:**
+
+- Python 3.12 or later
+- [Docker](https://docs.docker.com/engine/install/) for reproducible builds and evaluation
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) when using uv or installing from source
+
+```bash
+# Install from PyPI
+pip install featurebench
+
+# Or install the CLI with uv
+uv tool install featurebench
+
+# Install from source
+git clone https://github.com/LiberCoders/FeatureBench.git
+cd FeatureBench
+uv sync
+source .venv/bin/activate
+```
+
+Create `config.toml` from [config_example.toml](config_example.toml). From a source checkout:
+
+```bash
+cp config_example.toml config.toml
+```
+
+Optionally pre-pull the benchmark images:
+
+```bash
+fb pull --mode fast
+```
+
+Run inference:
+
+```bash
+fb infer \
+    --config-path config.toml \
+    --data-version v1.1 \
+    --agent mini_swe_agent \
+    --model openai/qwen3-coder-480b-a35b-instruct \
+    --split fast
+```
+
+Evaluate the generated patches:
+
+```bash
+fb eval \
+    -p runs/<timestamp>/output.jsonl \
+    --split fast
+```
+
+## 🏭 Universal Coding Data Factory
+
+The factory automatically discovers GitHub repositories, builds reproducible environments, and
+generates validated coding tasks. Adapters define the task format; FeatureBench is included by
+default. This workflow is optional for benchmark users.
+
+Put provider credentials in `.env`. From a source checkout:
+
+```bash
+cp .env.example .env
+```
+
+The default settings work out of the box and can be customized through
+`configs/default/*.yaml` or `--config`.
+
+```bash
+fb discover
+fb build outputs/discover-YYYYMMDD-HHMMSS/repositories.jsonl
+fb generate outputs/build-YYYYMMDD-HHMMSS/environments.jsonl \
+  --adapter featurebench
+```
+
+## 🧭 CLI
+
+**Benchmark:**
+
+- `fb infer` runs coding agents on FeatureBench tasks ([Documentation](docs/infer.md)).
+- `fb eval` evaluates generated patches ([Documentation](docs/eval.md)).
+- `fb pull` pre-pulls benchmark Docker images ([Documentation](docs/pull.md)).
+
+**Data factory:**
+
+- `fb discover` finds candidate GitHub repositories ([Documentation](docs/discover.md)).
+- `fb build` creates reusable, validated environments ([Documentation](docs/build.md)).
+- `fb generate` generates tasks through an Adapter ([Documentation](docs/generate.md)).
+- `fb configure` edits an inactive run before resuming it
+  ([Documentation](docs/configure.md)).
+- `fb --resume` continues an interrupted run ([Documentation](docs/reference/resume.md)).
+
+## ✍️ Citation
+
+If you found FeatureBench useful, please cite us as:
+
+```bibtex
+@article{zhou2026featurebench,
+  title={FeatureBench: Benchmarking Agentic Coding for Complex Feature Development},
+  author={Zhou, Qixing and Zhang, Jiacheng and Wang, Haiyang and Hao, Rui and Wang, Jiahe and Han, Minghao and Yang, Yuxue and Wu, Shuzhe and Pan, Feiyang and Fan, Lue and others},
+  journal={arXiv preprint arXiv:2602.10975},
+  year={2026}
+}
+```
+
+## 📧 Contact
+
+If you have any questions, feel free to contact [qixing.zhou@smail.nju.edu.cn](mailto:qixing.zhou@smail.nju.edu.cn) or [zjcheng2022@gmail.com](mailto:zjcheng2022@gmail.com).

featurebench-0.2.2/PKG-INFO → featurebench-0.3.0/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.5
-Name: featurebench
-Version: 0.2.2
-Summary: FeatureBench Pipeline - A test-driven data generation pipeline for building and evaluating feature-level coding benchmarks
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: datasets>=3.3.3
-Requires-Dist: docker>=5.0.3
-Requires-Dist: filelock>=3.20.0
-Requires-Dist: huggingface-hub>=0.26.5
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: matplotlib>=3.10.7
-Requires-Dist: openai>=2.6.1
-Requires-Dist: pandas>=2.2.3
-Requires-Dist: pyarrow>=18.1.0
-Requires-Dist: pytest>=8.4.2
-Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: rich>=13.0.0
-Requires-Dist: scipy>=1.16.3
-Requires-Dist: seaborn>=0.13.2
-Requires-Dist: toml>=0.10.2
-Requires-Dist: tqdm>=4.67.1
-Description-Content-Type: text/markdown
-
 <p align="center">
   <img src="docs/pics/logo.png" style="height: 10em" alt="logo" />
 </p>
@@ -36,23 +12,29 @@ Description-Content-Type: text/markdown
 
 ---
 
-FeatureBench is a test-driven data generation and evaluation pipeline for feature-level coding benchmarks.
-It provides a unified CLI to run inference, evaluation, and dataset generation.
+FeatureBench combines a feature-level coding benchmark with a fully automated, **Universal Coding
+Data Factory**. With one CLI, it continuously discovers GitHub repositories, builds reproducible
+environments across languages, and generates validated coding tasks for training and evaluation
+through extensible Adapters.
 
 ## 📰 News
 
+🏭 **2026.10.30**: We launched a **Universal Coding Data Factory**—fully automated, language-agnostic, and Adapter-driven—to continuously turn GitHub repositories into validated training data for any coding task format.
+
+📈 **2026.10.30**: In internal mixed-task RL experiments using data from our **Universal Coding Data Factory**, Qwen3.8-27B improved SWE-bench Verified Pass@1 from **70.2% to a peak of 79.8%** and FeatureBench 1.1 Tests Passed from **50.3% to a peak of 60.3%**.
+
 📦 **2026.08.24**: We released **FeatureBench Dataset V1.1**, primarily correcting inconsistencies and omissions in task problem statements.
 
 📊 **2026.05.18**: We added **lite split** evaluation results for frontier models including **GPT-5.5, Claude Opus 4.7, DeepSeek-V4, GLM-5.1, Kimi-2.6, Mimo-V2.5-Pro**, and more to the leaderboard.
 
 🚀 **2026.03.27**: We released the **fast split** containing 100 instances (a subset of full split). These instances require no GPU and are optimized for rapid evaluation. On an Intel Xeon Platinum 8457C with 944GB RAM, the average evaluation time per instance using gold patches is **57.2 seconds**.
 
-🎁 **2026.02.06**: We now support one-click inference for mainstream agent frameworks, including **OpenHands, Claude Code, Codex, Gemini CLI, and mini-swe-agent**. All supported agent frameworks can be found [here](featurebench/infer/agents/). We have also open-sourced the FeatureBench **data pipeline**.
+🎁 **2026.02.06**: We added one-click inference for mainstream agent frameworks, including **OpenHands, Claude Code, Codex, Gemini CLI, and mini-swe-agent**. All supported agent frameworks can be found [here](featurebench/infer/agents/).
 
 <!-- LEADERBOARD_START -->
 ## 🏆 Leaderboard
 
-[Full interactive leaderboard](https://libercoders.github.io/FeatureBench/leaderboard/) with tabs, filters, and sorting.
+[Full interactive leaderboard](https://libercoders.github.io/FeatureBench/leaderboard/) with tabs, filters, and sorting (Dataset V1.0).
 
 <details open>
 <summary><b>Lite split results, ranked by %PASSED</b></summary>
@@ -86,40 +68,39 @@ It provides a unified CLI to run inference, evaluation, and dataset generation.
 ## 🚀 Quickstart
 
 **Prerequisites:**
-- [uv](https://docs.astral.sh/uv/getting-started/installation/) for Python environment management
-- [docker](https://docs.docker.com/engine/install/) for reproducible builds and evaluation
+
+- Python 3.12 or later
+- [Docker](https://docs.docker.com/engine/install/) for reproducible builds and evaluation
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) when using uv or installing from source
 
 ```bash
-# pypi
+# Install from PyPI
 pip install featurebench
-# or uv add featurebench
 
-# local
+# Or install the CLI with uv
+uv tool install featurebench
+
+# Install from source
 git clone https://github.com/LiberCoders/FeatureBench.git
 cd FeatureBench
 uv sync
 source .venv/bin/activate
 ```
 
-**Configure:**
+Create `config.toml` from [config_example.toml](config_example.toml). From a source checkout:
+
 ```bash
 cp config_example.toml config.toml
 ```
-See [docs/config.md](docs/config.md) for a comprehensive reference (harness, infer, data pipeline) with examples.
 
-**Optional: pre-pull images to reduce network variance:**
+Optionally pre-pull the benchmark images:
+
 ```bash
-fb pull --mode lite                 # lite split image list (13 images)
-fb pull --mode fast                 # fast split image list (18 images)
-fb pull --mode full                 # full split image list (24 images)
-fb pull --mode /path/to/images.txt  # one image name per line
-
-# full list: featurebench/resources/constants/full_images.txt
-# lite list: featurebench/resources/constants/lite_images.txt
-# fast list: featurebench/resources/constants/fast_images.txt
+fb pull --mode fast
 ```
 
-**Run inference:**
+Run inference:
+
 ```bash
 fb infer \
     --config-path config.toml \
@@ -129,20 +110,52 @@ fb infer \
     --split fast
 ```
 
-**Run evaluation:**
+Evaluate the generated patches:
+
 ```bash
 fb eval \
     -p runs/<timestamp>/output.jsonl \
     --split fast
-    # use -p gold to verify the gold patches
 ```
 
-## 🧭 CLI Overview
+## 🏭 Universal Coding Data Factory
+
+The factory automatically discovers GitHub repositories, builds reproducible environments, and
+generates validated coding tasks. Adapters define the task format; FeatureBench is included by
+default. This workflow is optional for benchmark users.
+
+Put provider credentials in `.env`. From a source checkout:
+
+```bash
+cp .env.example .env
+```
+
+The default settings work out of the box and can be customized through
+`configs/default/*.yaml` or `--config`.
+
+```bash
+fb discover
+fb build outputs/discover-YYYYMMDD-HHMMSS/repositories.jsonl
+fb generate outputs/build-YYYYMMDD-HHMMSS/environments.jsonl \
+  --adapter featurebench
+```
+
+## 🧭 CLI
+
+**Benchmark:**
+
+- `fb infer` runs coding agents on FeatureBench tasks ([Documentation](docs/infer.md)).
+- `fb eval` evaluates generated patches ([Documentation](docs/eval.md)).
+- `fb pull` pre-pulls benchmark Docker images ([Documentation](docs/pull.md)).
+
+**Data factory:**
 
-`fb` provides three core commands:
-- `fb infer` runs `featurebench.infer.run_infer` (docs: [docs/infer_cli_arg.md](docs/infer_cli_arg.md))
-- `fb eval` runs `featurebench.harness.run_evaluation` (docs: [docs/harness_cli_arg.md](docs/harness_cli_arg.md))
-- `fb data` runs `featurebench.pipeline` (docs: [docs/pipeline.md](docs/pipeline.md))
+- `fb discover` finds candidate GitHub repositories ([Documentation](docs/discover.md)).
+- `fb build` creates reusable, validated environments ([Documentation](docs/build.md)).
+- `fb generate` generates tasks through an Adapter ([Documentation](docs/generate.md)).
+- `fb configure` edits an inactive run before resuming it
+  ([Documentation](docs/configure.md)).
+- `fb --resume` continues an interrupted run ([Documentation](docs/reference/resume.md)).
 
 ## ✍️ Citation
 
@@ -159,4 +172,4 @@ If you found FeatureBench useful, please cite us as:
 
 ## 📧 Contact
 
-If you have any questions, feel free to contact [zhouqixing@stu.cqu.edu.cn](mailto:zhouqixing@stu.cqu.edu.cn) or [zjcheng2022@gmail.com](mailto:zjcheng2022@gmail.com).
+If you have any questions, feel free to contact [qixing.zhou@smail.nju.edu.cn](mailto:qixing.zhou@smail.nju.edu.cn) or [zjcheng2022@gmail.com](mailto:zjcheng2022@gmail.com).

featurebench-0.3.0/codeworld/__init__.py

@@ -0,0 +1,31 @@
+"""Generic environment and task-generation engine embedded in FeatureBench."""
+
+from codeworld.adapters.base import (
+    AdapterDefinition,
+    AdapterGenerator,
+    AdapterLifecycle,
+    GeneratorContext,
+    QualityGateResult,
+    TaskQualityGate,
+)
+from codeworld.adapters.catalog import (
+    AdapterCatalog,
+    AdapterInvocation,
+    AdapterRegistration,
+    default_adapter_catalog,
+)
+from codeworld.models import TaskRecord
+
+__all__ = [
+    "AdapterCatalog",
+    "AdapterDefinition",
+    "AdapterGenerator",
+    "AdapterInvocation",
+    "AdapterLifecycle",
+    "AdapterRegistration",
+    "GeneratorContext",
+    "QualityGateResult",
+    "TaskQualityGate",
+    "TaskRecord",
+    "default_adapter_catalog",
+]

featurebench-0.3.0/codeworld/adapters/__init__.py

@@ -0,0 +1,31 @@
+"""Adapter SDK and built-in adapters."""
+
+from codeworld.adapters.base import (
+    AdapterDefinition,
+    AdapterGenerator,
+    AdapterLifecycle,
+    AdapterSettings,
+    GeneratorContext,
+    QualityGateResult,
+    TaskQualityGate,
+)
+from codeworld.adapters.catalog import (
+    AdapterCatalog,
+    AdapterInvocation,
+    AdapterRegistration,
+    default_adapter_catalog,
+)
+
+__all__ = [
+    "AdapterCatalog",
+    "AdapterDefinition",
+    "AdapterGenerator",
+    "AdapterInvocation",
+    "AdapterLifecycle",
+    "AdapterRegistration",
+    "AdapterSettings",
+    "GeneratorContext",
+    "QualityGateResult",
+    "TaskQualityGate",
+    "default_adapter_catalog",
+]

featurebench-0.3.0/codeworld/adapters/base.py

@@ -0,0 +1,144 @@
+"""Adapter data-production contracts and runtime composition."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from codeworld.models import StrictModel, TaskRecord
+from codeworld.selection import WorkSelection
+
+if TYPE_CHECKING:
+    from codeworld.environment.models import EnvironmentRecord
+    from codeworld.events import EventSink
+    from codeworld.progress import AdapterPhase, AdapterProgressReporter
+    from codeworld.runtime.base import ContainerRuntimeProtocol
+
+
+class AdapterSettings(StrictModel):
+    """Execution controls shared by every Adapter-owned YAML schema."""
+
+    environment_concurrency: int = Field(default=4, ge=1, le=32)
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratorContext:
+    """Host services and output-driven selection for one Adapter invocation."""
+
+    runtime: ContainerRuntimeProtocol
+    events: EventSink
+    progress: AdapterProgressReporter
+    work_dir: Path
+    run_id: str
+    selection: WorkSelection
+    output_dir: Path | None = None
+    completed_task_ids: frozenset[str] = frozenset()
+
+
+@runtime_checkable
+class AdapterGenerator(Protocol):
+    """Produce canonical task candidates from one validated environment."""
+
+    def generate(
+        self, environment: EnvironmentRecord, context: GeneratorContext
+    ) -> AsyncGenerator[TaskRecord, None]:
+        """Generate only Adapter work whose durable state matches ``context.selection``."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class QualityGateResult:
+    """Transient outcome consumed before a candidate may enter task JSONL."""
+
+    passed: bool
+    message: str = ""
+    metrics: Mapping[str, int | float | bool | str] = field(
+        default_factory=dict[str, int | float | bool | str]
+    )
+
+
+@runtime_checkable
+class TaskQualityGate(Protocol):
+    """Apply Adapter-owned quality semantics without prescribing a Gold representation."""
+
+    async def check(
+        self,
+        task: TaskRecord,
+        payload: BaseModel,
+        context: GeneratorContext,
+    ) -> QualityGateResult:
+        """Return an expected rejection; raise when the candidate could not be checked."""
+        ...
+
+
+@runtime_checkable
+class AdapterLifecycle(Protocol):
+    """Optional Adapter-owned durable lifecycle behind the shared Generate workflow."""
+
+    async def run_started(
+        self,
+        environment: EnvironmentRecord,
+        context: GeneratorContext,
+    ) -> None: ...
+
+    async def candidate_checked(
+        self,
+        task: TaskRecord,
+        result: QualityGateResult,
+        context: GeneratorContext,
+    ) -> None: ...
+
+    async def candidate_failed(
+        self,
+        task: TaskRecord,
+        error: BaseException,
+        context: GeneratorContext,
+    ) -> None: ...
+
+    async def run_finished(
+        self,
+        context: GeneratorContext,
+        error: BaseException | None,
+    ) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterDefinition:
+    """Runtime manifest for one registered data-producing Adapter."""
+
+    type: str
+    payload_model: type[BaseModel]
+    generator: AdapterGenerator
+    quality_gate: TaskQualityGate
+    quality_gate_concurrency: int = 1
+    maximum_tasks: int | None = None
+    display_name: str | None = None
+    progress_phases: tuple[AdapterPhase, ...] = ()
+    lifecycle: AdapterLifecycle | None = None
+
+    def __post_init__(self) -> None:
+        if not self.type or self.type != self.type.strip():
+            raise ValueError("adapter type must be non-empty without surrounding whitespace")
+        if self.maximum_tasks is not None and self.maximum_tasks < 1:
+            raise ValueError("adapter maximum tasks must be positive")
+        if self.quality_gate_concurrency < 1:
+            raise ValueError("adapter quality gate concurrency must be positive")
+        if self.display_name is not None and (
+            not self.display_name or self.display_name != self.display_name.strip()
+        ):
+            raise ValueError(
+                "adapter display name must be non-empty without surrounding whitespace"
+            )
+        phase_ids = [phase.id for phase in self.progress_phases]
+        if len(phase_ids) != len(set(phase_ids)):
+            raise ValueError("adapter progress phase IDs must be unique")
+
+    def validate_task(self, task: TaskRecord) -> BaseModel:
+        payload = self.payload_model.model_validate(task.adapter)
+        if getattr(payload, "type", None) != self.type:
+            raise ValueError(f"adapter payload type does not match definition {self.type!r}")
+        return payload