AGENTS.md · Human-Agent-Society/reef

Sections

1. Contribution workflow
2. Codebase and boundaries
3. Development environment
4. Python style and design
5. Naming and terminology
6. Writing style
7. Documentation review checklist
8. Tests and checks
9. Area-specific guides and documentation

First lines (shown under the repo's Apache-2.0 license)

# Agent Instructions for Reef

These instructions apply to AI-assisted work in `Human-Agent-Society/reef`.
`AGENTS.md` is the shared source of truth; `CLAUDE.md` is a relative symlink to
this file. Edit this file when updating shared instructions.

Read [CONTRIBUTING.md](CONTRIBUTING.md) for project policy. Follow any more
specific `AGENTS.md` in the area you change. Explicit user instructions take
precedence over repository guidance.

## Contribution workflow

- Inspect the working tree before editing and preserve existing user changes.
  Keep each change focused on the requested problem.
- Before opening an issue or pull request, search existing issues and PRs for
  overlapping work. Follow the RFC criteria in `CONTRIBUTING.md` for changes to
  architecture, public contracts, persistence, or project policy.
- Before drafting or updating an issue or RFC, follow
  [Issue and RFC writing](CONTRIBUTING.md#issue-and-rfc-writing). Keep the
  proposal concise; do not expand the design just to fill template sections.
- Reproduce bugs and inspect the relevant implementation before changing it.
  Avoid speculative fixes, unrelated formatting, and unnecessary abstractions.
- Before submitting a pull request, review every changed line against
  [Python style and design](#python-style-and-design),
  [Code structure and readability](#code-structure-and-readability), and
  [Naming and terminology](#naming-and-terminology), and fix any violation.
  Passing pre-commit does not replace this review; these rules are not all
  checked mechanically.
- When reviewing a pull request, check each new or changed type against
  [Define every type with mathematical rigor](CONTRIBUTING.md#define-every-type-with-mathematical-rigor).
  Report a definition that is not exact, complete, or consistent as a blocking
  finding.
- Before submitting a pull request that changes documentation, complete the
  [Documentation review checklist](#documentation-review-checklist) and fix
  any issues. Review the resulting sections in context, not only the diff.
- Use [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md).
  Explain the problem, resulting behavior, compatibility impact, and actual
  verification results. Disclose non-trivial AI assistance. The human
  contributor remains responsible for reviewing and understanding the change.
- Keep credentials and private transcripts out of logs, fixtures, and commits.
  Follow [SECURITY.md](SECURITY.md) for vulnerability reporting.

## Codebase and boundaries

Reef connects inference, feedback, learning, and versioned delivery for model
weights and agent harnesses. The distribution is `reef-infra`; imports use
`reef`. Use the [codebase map](docs/contributing/codebase-structure.rst) and the
affected package's `__init__.py` docstring to find the owner of a change.

| Location | Responsibility |
| --- | --- |
| `reef/core/` | Shared value types, wire contracts, and errors |
| `reef/dispatcher/`, `reef/scenario/` | Coordination, scenario state, commit ordering, and recovery |
| `reef/service/` | HTTP, authentication, streaming, and deployment |
| `reef/recipe/`, `reef/train/` | Recipe contracts, built-in recipes, the training pipeline, training, and backend integrations |
| `reef/evaluation/` | Candidate evaluation: running and scoring evaluation rollouts, deciding whether a candidate is published, and plugin configuration |
| `reef/runtime/` | Backend-neutral runtime contracts, scheduling, and publication coordination |
| `reef/inference/` | Concrete inference integrations, engine control, and weight reception |
| `reef/tinker/` | Tinker SDK pieces that the Tinker training component and the Tinker serving runtime share |
| `reef/surface/` | Delivery of published artifacts |
| `reef/artifact/` | Versioned artifacts and repositories |
| `reef/storage/` | Record storage contracts, persistence, and retention |
| `reef/harness/` | Harness adapters, rendering, runners, and trajectories |
| `reef/execution/` | Shared job scheduling, local process ownership, sandbox isolation, file transfer, and cleanup |
| `reef/record2record/` | The record-to-record stage: which records Reef uses and in what order (report grouping, judging, eligibility checks, selection order) |
| `reef/record2sample/` | The record-to-sample stage: one record set into samples (`Record2Sample`), and the generator service that writes, checks, and plays Harbor tasks (`generator/`) |
| `reef/sample2job/` | The sample-to-job stage: the samples of the selected record sets into one training job's data (`Sample2Job`), and the job size `job_samples` |
| `reef/pipeline_context.py` | The context that the training pipeline and its stages read for one scenario |
| `recipes/`, `tutorials/` | Method implementations, runnable examples, and tutorials |
| `tests/`, `docs/`, `docker/` | Verification, documentation, and deployment environments |

- Keep shared mechanisms in `reef/` and method-specific policy in `recipes/`.
  The core must not import cookbook methods; `recipes/` does not ship in the
  Reef wheel.
- Keep `reef-client` a separate, dependency-free protocol client. Harnesses
  consume `reef_client`; they should not need Reef's service or training stack.
- Keep the base installation usable on CPU. GPU dependencies belong to the
  supported training environment, and concrete adapters belong under their
  integration. Declare or pin third-party dependencies instead of copying them.
- Preserve provider request bodies, scenario isolation, receipt-to-feedback
  linkage, and artifact publication/recovery contracts.

## Development environment

Use `uv` and the repository virtual environment for Python work. Reuse an
existing environment; for a new checkout, the usual setup is:

```bash
git submodule update --init --recursive
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]" -e ./third_party/reef-client
pre-commit install
```

Reef requires Python 3.12 or newer, one interpreter for the service and every
child it starts; CI tests 3.12. Git LFS is required for artifact/checkpoint work.

Training-related work may also need:

```bash
uv pip install -e ".[slime]"
uv pip install --no-deps --group runtime
```

The `slime` extra supplies Python-side adapter dependencies; the `runtime`
group pins Slime itself. Preserve `--no-deps` so the installation does not
replace the container's CUDA-compatible stack. Follow
[development](docs/contributing/development.rst) and [docker/README.md](docker/README.md)
for the environment required by the selected backend.

## Python style and design

- Follow `pyproject.toml`: Black and isort format at 119 columns; Ruff checks
  code and naming; mypy checks `reef`. Match nearby code and add types to new
  or changed interfaces.
- Prefer focused functions, data classes for values, and cohesive objects for
  state and lifecycle. Use composition and explicit abstract base classes for behavior.
- Do not use `typing.Protocol`, `typing_extensions.Protocol`, or `runtime_checkable`.
  Define an `ABC` and inherit it explicitly. CI checks all first-party Python files,
  including tutorials, Docker/docs/CI scripts, and root files, without baseline exceptions.
  Third-party code, local dependency/build trees, vendored benchmarks, published result
  programs, and golden fixtures are excluded; see the paths in
  [.github/scripts/check_python_design.py](.github/scripts/check_python_design.py).
- Do not use `TYPE_CHECKING`. Fix dependency direction or move shared contracts
  so annotation imports work at runtime.
- Do not model long-lived behavior as `Callable` constructor arguments,
  callable-valued fields, or callback containers. Use an explicit interface. Keep unavoidable
  third-party dynamic behavior local to its boundary adapter.
- Do not use `assert` or `del` statements in `reef/`; use explicit validation,
  exceptions, and mutation APIs. Test assertions are allowed.
- Use descriptive domain names and short comments that explain intent or
  constraints. Follow the Google-style documentation guidance in
  `CONTRIBUTING.md`.
- Do not bypass checks by adding broad suppressions or growing
  `.github/python-design-baseline.txt` to accommodate new violations.

### Code structure and readability

Apply these rules when writing or reviewing code. The
[Code Review Style Guide](https://github.com/zhaochenyang20/sglang-diffusion-routing/issues/32)
is a reference; the rules here take precedence where it differs.

- **Avoid fragmented functions.** Inline tiny helpers used only once or twice
  when they merely split up a continuous operation. Extract functions for a
  meaningful responsibility or substantial reuse, not to meet an arbitrary
  line limit. Keep related logic readable in one place.
- **Use ordinary identifier names.** Only functions nested inside other
  functions should use a leading underscore. Start other variables, fields,
  constants, module-level functions, and methods with an English letter.
  Preserve Python-required special names such as `__init__`.
- **Handle realistic failures.** Validate types and data at entry points, then
  rely on those contracts internally. Keep `try/except` blocks narrow and catch
  specific, expected failures only when there is a meaningful recovery or error
  translation. Do not add speculative fallbacks, repeated checks, or tests for
  impossible states. Tests should be concise and cover observable behavior and
  the operation's main failure modes.
- **Keep constants with their consumer.** If a constant is defined in one
  module solely to be imported by one other module, define it in the consuming
  module instead. Share constants when they have actual shared use; avoid