From 5abc6a31a454a2cae767fcbd78914b0d621ed75d Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 10:51:23 +0800 Subject: [PATCH 1/7] init --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..2ef228c29 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# Repository Guidelines for Agent-lightning + +## Project Structure & Module Organization + +The `agentlightning/` package holds adapters, runners, tracers, reward logic, and the `agl` CLI entry point. Docs, tutorials, and the algorithm zoo live under `docs/`, while runnable workflows and benchmarking recipes sit in `examples/`. Dashboards and UI assets live in `dashboard/`; automation scripts live in `scripts/`; regression coverage mirrors runtime modules inside `tests/`. Register new documentation in `mkdocs.yml` and keep example READMEs brief by pointing to the relevant how-to guide. + +## Build, Test, and Development Commands +Run `uv sync --group dev` to install tooling, then execute everything through `uv run --no-sync`. Core commands: +- `uv run pytest -v` — full unit suite (use `-k` or a path for targeted debugging). +- `uv run pyright` — static type validation aligned with CI. +- `uv run pre-commit run --all-files --show-diff-on-failure` — applies Black, isort, Flake8, and lint hooks. +- `uv run mkdocs build --strict` — validates docs before committing. +Record extra dependencies with `uv lock` so reviewers can replay the environment. + +## Coding Style & Naming Conventions +Python 3.12 features are allowed, but stay compatible with `requires-python = ">=3.10"`. Use 4-space indentation, 120-character lines, and Black + isort (profile `black`) formatting; do not hand-edit generated diffs. Modules, functions, and variables use `snake_case`; classes use `PascalCase`; CLI and branch names use lowercase hyphenated tokens. Keep type hints up to date (pyright enforces them) and favor dataclasses/Pydantic models already defined in `agentlightning.types`. + +## Testing Guidelines +Add or update `tests/` cases whenever touching logic. Prefer colocated modules (e.g., `tests/execution/` for trainer code) and mirror filenames. Use parametrized tests plus `pytest.mark` gates (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so hardware/API-dependent suites can be skipped locally via `-m "not gpu"`. Favor fixtures or fake spans instead of live services, and call out required environment variables (like `OPENAI_API_KEY`) near the test. + +## Commit & Pull Request Guidelines +Work from fresh `main` and branch using `feature/`, `fix/`, `docs/`, or `chore/`. Write imperative, scoped commits and reference issues with `Fixes #123` where applicable. Before pushing, rerun hooks and the relevant tests; attach logs or screenshots for UI/dashboard tweaks. PRs should summarize intent, list the commands you ran, and surface dependency or doc-navigation updates so reviewers can trace coverage quickly. From 3308f29a2c7e9300518c18cef58f6eef2037728c Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 10:57:03 +0800 Subject: [PATCH 2/7] improvements --- AGENTS.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2ef228c29..d7d292061 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,18 +5,24 @@ The `agentlightning/` package holds adapters, runners, tracers, reward logic, and the `agl` CLI entry point. Docs, tutorials, and the algorithm zoo live under `docs/`, while runnable workflows and benchmarking recipes sit in `examples/`. Dashboards and UI assets live in `dashboard/`; automation scripts live in `scripts/`; regression coverage mirrors runtime modules inside `tests/`. Register new documentation in `mkdocs.yml` and keep example READMEs brief by pointing to the relevant how-to guide. ## Build, Test, and Development Commands -Run `uv sync --group dev` to install tooling, then execute everything through `uv run --no-sync`. Core commands: -- `uv run pytest -v` — full unit suite (use `-k` or a path for targeted debugging). -- `uv run pyright` — static type validation aligned with CI. -- `uv run pre-commit run --all-files --show-diff-on-failure` — applies Black, isort, Flake8, and lint hooks. -- `uv run mkdocs build --strict` — validates docs before committing. + +Run `uv sync --group dev` to install tooling, then execute everything through `uv run --no-sync `. Core commands: + +- `uv run --no-sync pytest tests/path/to/test_file.py` — run unit-test (use `-k` for targeted debugging and `-m` for skipping tests). +- `uv run --no-sync pyright /path/to/file.py` — static type validation aligned with CI. +- `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` — applies Black, isort, Flake8, and lint hooks. +- `uv run --no-sync mkdocs build --strict` — validates docs. + Record extra dependencies with `uv lock` so reviewers can replay the environment. ## Coding Style & Naming Conventions -Python 3.12 features are allowed, but stay compatible with `requires-python = ">=3.10"`. Use 4-space indentation, 120-character lines, and Black + isort (profile `black`) formatting; do not hand-edit generated diffs. Modules, functions, and variables use `snake_case`; classes use `PascalCase`; CLI and branch names use lowercase hyphenated tokens. Keep type hints up to date (pyright enforces them) and favor dataclasses/Pydantic models already defined in `agentlightning.types`. + +Python 3.12 features are allowed, but stay compatible with `requires-python = ">=3.10"`. Use 4-space indentation, 120-character lines, and Black + isort (profile `black`) formatting; do not hand-edit generated diffs. Modules, functions, and variables use `snake_case`; classes use `PascalCase`; CLI and branch names use lowercase hyphenated tokens. Keep type hints up to date (pyright enforces them; especially for new tests) and favor dataclasses/Pydantic models already defined in `agentlightning.types`. Use Google-style docstrings for new modules, classes, and functions; use `[][]` syntax for symbol references; refrain from adding type hints to parameters in docstrings. ## Testing Guidelines -Add or update `tests/` cases whenever touching logic. Prefer colocated modules (e.g., `tests/execution/` for trainer code) and mirror filenames. Use parametrized tests plus `pytest.mark` gates (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so hardware/API-dependent suites can be skipped locally via `-m "not gpu"`. Favor fixtures or fake spans instead of live services, and call out required environment variables (like `OPENAI_API_KEY`) near the test. + +Add or update `tests/` cases whenever touching logic. Prefer colocated modules (e.g., `tests/execution/` for trainer code) and mirror filenames. Use parametrized tests plus `pytest.mark` gates (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so hardware/API-dependent suites can be skipped locally via `-m "not gpu"`. Favor fixtures or fake spans instead of live services, and call out required environment variables (like `OPENAI_API_KEY`) near the test. When testing, target specific files or units; refrain from running the entire test suite. ## Commit & Pull Request Guidelines + Work from fresh `main` and branch using `feature/`, `fix/`, `docs/`, or `chore/`. Write imperative, scoped commits and reference issues with `Fixes #123` where applicable. Before pushing, rerun hooks and the relevant tests; attach logs or screenshots for UI/dashboard tweaks. PRs should summarize intent, list the commands you ran, and surface dependency or doc-navigation updates so reviewers can trace coverage quickly. From fddaeeca599cbfaba4157310600754be8c78371b Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 11:54:44 +0800 Subject: [PATCH 3/7] remove extra new line --- AGENTS.md | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d7d292061..6da0bb4e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,28 +1,32 @@ -# Repository Guidelines for Agent-lightning +# Repository Guidelines -## Project Structure & Module Organization +## Architecture Overview +Agent Lightning loops through stages: runner and tracer emit spans, LightningStore (`agentlightning/store/`) synchronizes them, and algorithms in `agentlightning/algorithm/` learn from the traces. -The `agentlightning/` package holds adapters, runners, tracers, reward logic, and the `agl` CLI entry point. Docs, tutorials, and the algorithm zoo live under `docs/`, while runnable workflows and benchmarking recipes sit in `examples/`. Dashboards and UI assets live in `dashboard/`; automation scripts live in `scripts/`; regression coverage mirrors runtime modules inside `tests/`. Register new documentation in `mkdocs.yml` and keep example READMEs brief by pointing to the relevant how-to guide. +## Project Structure & Module Organization +- `agentlightning/`: adapters, runner/execution stack, trainer, tracer, reward logic, `agl` CLI. +- `docs/` & `examples/`: documentation (assets in `docs/assets/`, nav in `mkdocs.yml`) plus runnable workflows whose READMEs link to their how-to guides. +- `dashboard/`, `scripts/`, `tests/`: UI bundles, automation for releases/datasets/CI, and coverage mirrors of the runtime tree—document download steps instead of committing binaries. ## Build, Test, and Development Commands - -Run `uv sync --group dev` to install tooling, then execute everything through `uv run --no-sync `. Core commands: - -- `uv run --no-sync pytest tests/path/to/test_file.py` — run unit-test (use `-k` for targeted debugging and `-m` for skipping tests). -- `uv run --no-sync pyright /path/to/file.py` — static type validation aligned with CI. -- `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` — applies Black, isort, Flake8, and lint hooks. -- `uv run --no-sync mkdocs build --strict` — validates docs. - -Record extra dependencies with `uv lock` so reviewers can replay the environment. +- `uv sync --group dev` — install tooling once. +- `uv run --no-sync pytest -v` — run suites; add a path or `-k expr` for targeted loops. +- `uv run --no-sync pyright` — static analysis aligned with CI. +- `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` and `uv run --no-sync mkdocs build --strict` — formatting/lint hooks plus doc validation. +Commit the refreshed `uv.lock` whenever dependencies move and note optional groups (VERL, APO, GPU) in PRs. ## Coding Style & Naming Conventions - -Python 3.12 features are allowed, but stay compatible with `requires-python = ">=3.10"`. Use 4-space indentation, 120-character lines, and Black + isort (profile `black`) formatting; do not hand-edit generated diffs. Modules, functions, and variables use `snake_case`; classes use `PascalCase`; CLI and branch names use lowercase hyphenated tokens. Keep type hints up to date (pyright enforces them; especially for new tests) and favor dataclasses/Pydantic models already defined in `agentlightning.types`. Use Google-style docstrings for new modules, classes, and functions; use `[][]` syntax for symbol references; refrain from adding type hints to parameters in docstrings. +- Stay compatible with `requires-python >= 3.10`, use 4-space indentation, 120-character lines, and formatter-managed diffs (Black + isort, profile `black`). +- Adopt `snake_case` for modules/functions/variables, `PascalCase` for classes, and lowercase-hyphenated CLI flags or branch names. +- Keep type hints exhaustive (pyright enforced) and reuse dataclasses/Pydantic models from `agentlightning.types`. +- Use Google-style docstrings for new modules or public methods, keeping descriptions short and avoiding redundant type annotations. Use `[][]` syntax for cross-references. ## Testing Guidelines - -Add or update `tests/` cases whenever touching logic. Prefer colocated modules (e.g., `tests/execution/` for trainer code) and mirror filenames. Use parametrized tests plus `pytest.mark` gates (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so hardware/API-dependent suites can be skipped locally via `-m "not gpu"`. Favor fixtures or fake spans instead of live services, and call out required environment variables (like `OPENAI_API_KEY`) near the test. When testing, target specific files or units; refrain from running the entire test suite. +- Mirror runtime directories under `tests/` and align filenames for quick lookup. +- Parametrize pytest cases and apply markers (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so optional suites can be skipped with selectors like `-m "not mongo"` yet still run in CI. +- Favor fixtures, fake spans, and local LightningStore instances; gate unavoidable external calls with the relevant marker and mention required environment variables when present. ## Commit & Pull Request Guidelines - -Work from fresh `main` and branch using `feature/`, `fix/`, `docs/`, or `chore/`. Write imperative, scoped commits and reference issues with `Fixes #123` where applicable. Before pushing, rerun hooks and the relevant tests; attach logs or screenshots for UI/dashboard tweaks. PRs should summarize intent, list the commands you ran, and surface dependency or doc-navigation updates so reviewers can trace coverage quickly. +- Branch from fresh `main` using `feature/`, `fix/`, `docs/`, or `chore/`. +- Write imperative, scoped commits, reference issues with `Fixes #123`, and rerun pre-commit plus relevant pytest/doc builds before pushing. +- PR descriptions should summarize intent, list verification commands, highlight dependency or docs-navigation updates, and link new docs/examples via `mkdocs.yml` or `examples/README.md`; include logs for dashboard tweaks. From 5b97cf4af781cc63c48cfa94d9f5c33b10b5745d Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 12:10:09 +0800 Subject: [PATCH 4/7] update agents.md --- .github/workflows/badge-examples.yml | 2 ++ .github/workflows/badge-latest.yml | 4 ++++ .github/workflows/badge-rag.yml | 29 ++++++++++++++++++++++++++++ AGENTS.md | 12 ++++++++---- examples/README.md | 4 ++-- examples/rag/README.md | 2 ++ 6 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/badge-rag.yml diff --git a/.github/workflows/badge-examples.yml b/.github/workflows/badge-examples.yml index 9aa38e45a..fc17b7577 100644 --- a/.github/workflows/badge-examples.yml +++ b/.github/workflows/badge-examples.yml @@ -10,6 +10,7 @@ on: - Examples - Tinker - Examples - Azure - Examples - Claude Code + - Examples - RAG types: [completed] workflow_dispatch: @@ -37,5 +38,6 @@ jobs: { workflow: 'examples-tinker.yml', label: 'examples-tinker.stable', variants: ['stable'] }, { workflow: 'examples-azure.yml', label: 'examples-azure.stable', variants: ['stable'] }, { workflow: 'examples-claude-code.yml', label: 'examples-claude-code.stable', variants: ['stable'] }, + { workflow: 'examples-rag.yml', label: 'examples-rag.stable', variants: ['stable'] }, ]; await badgeAggregation({ github, context, core, dependencies }); diff --git a/.github/workflows/badge-latest.yml b/.github/workflows/badge-latest.yml index b7b2413bf..82d088c52 100644 --- a/.github/workflows/badge-latest.yml +++ b/.github/workflows/badge-latest.yml @@ -7,6 +7,8 @@ on: - Examples - Spider - Examples - APO - Examples - Unsloth + - Examples - RAG + - Examples - Claude Code - GPU Test types: [completed] @@ -32,6 +34,8 @@ jobs: { workflow: 'examples-spider.yml', label: 'spider.latest', variants: ['latest'] }, { workflow: 'examples-apo.yml', label: 'apo.latest', variants: ['latest'] }, { workflow: 'examples-unsloth.yml', label: 'unsloth.latest', variants: ['latest'] }, + { workflow: 'examples-claude-code.yml', label: 'claude-code.latest', variants: ['latest'] }, + { workflow: 'examples-rag.yml', label: 'rag.latest', variants: ['latest'] }, { workflow: 'tests-full.yml', label: 'tests-full.latest', variants: ['latest'] }, ]; await badgeAggregation({ github, context, core, dependencies }); diff --git a/.github/workflows/badge-rag.yml b/.github/workflows/badge-rag.yml new file mode 100644 index 000000000..459f0fe2f --- /dev/null +++ b/.github/workflows/badge-rag.yml @@ -0,0 +1,29 @@ +name: Badge - RAG + +on: + workflow_run: + workflows: + - Examples - RAG + types: [completed] + + workflow_dispatch: + +permissions: + actions: read + contents: read + +jobs: + badge: + if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'main') }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/github-script@v8 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const badgeAggregation = require('./scripts/badge_aggregation.js'); + const dependencies = [ + { workflow: 'examples-rag.yml', label: 'rag', variants: ['legacy', 'stable'] }, + ]; + await badgeAggregation({ github, context, core, dependencies }); diff --git a/AGENTS.md b/AGENTS.md index 6da0bb4e2..008401c23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ Agent Lightning loops through stages: runner and tracer emit spans, LightningSto ## Project Structure & Module Organization - `agentlightning/`: adapters, runner/execution stack, trainer, tracer, reward logic, `agl` CLI. -- `docs/` & `examples/`: documentation (assets in `docs/assets/`, nav in `mkdocs.yml`) plus runnable workflows whose READMEs link to their how-to guides. +- `docs/` & `examples/`: documentation (assets in `docs/assets/`, nav in `mkdocs.yml`) plus runnable workflows whose READMEs link to their how-to guides. `docs/how-to` contains step-by-step guides for accomplishing a specific task; `docs/tutorials` contains conceptual walkthroughs for components or features. - `dashboard/`, `scripts/`, `tests/`: UI bundles, automation for releases/datasets/CI, and coverage mirrors of the runtime tree—document download steps instead of committing binaries. ## Build, Test, and Development Commands @@ -16,15 +16,19 @@ Agent Lightning loops through stages: runner and tracer emit spans, LightningSto Commit the refreshed `uv.lock` whenever dependencies move and note optional groups (VERL, APO, GPU) in PRs. ## Coding Style & Naming Conventions -- Stay compatible with `requires-python >= 3.10`, use 4-space indentation, 120-character lines, and formatter-managed diffs (Black + isort, profile `black`). -- Adopt `snake_case` for modules/functions/variables, `PascalCase` for classes, and lowercase-hyphenated CLI flags or branch names. +- Stay compatible with `requires-python >= 3.10`, use 4-space indentation, 120-character lines, and formatter-managed diffs (Black + isort, profile `black`). `snake_case` for modules/functions/variables, `PascalCase` for classes and React components, and lowercase-hyphenated CLI flags, branch names and TypeScript files. - Keep type hints exhaustive (pyright enforced) and reuse dataclasses/Pydantic models from `agentlightning.types`. - Use Google-style docstrings for new modules or public methods, keeping descriptions short and avoiding redundant type annotations. Use `[][]` syntax for cross-references. ## Testing Guidelines - Mirror runtime directories under `tests/` and align filenames for quick lookup. - Parametrize pytest cases and apply markers (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so optional suites can be skipped with selectors like `-m "not mongo"` yet still run in CI. -- Favor fixtures, fake spans, and local LightningStore instances; gate unavoidable external calls with the relevant marker and mention required environment variables when present. +- Favor fixtures; prefer real stores/spans/agents over fakes. Make sure most branches are covered by tests. + +## Example Contributions +- Examples should include a README with smoke instructions so maintainers can validate them quickly. The README should contain a "Included Files" section with a list of the files in the example directory and a description of what each file does. +- The major example files that are meant to be run should be self-contained and have a module-level docstring with CLI usage instructions. Important/complex classes/functions that are meant to be read and learned for users should be documented with their own docstrings and inline comments. +- New examples should include a CI workflow that runs the example and verifies that it runs successfully. The workflow should be named `examples-.yml` and should be placed in the `.github/workflows/` directory. The workflow should be registered in `badge-.yml`, `badge-examples.yml`, and `badge-latest.yml` if necessary. ## Commit & Pull Request Guidelines - Branch from fresh `main` using `feature/`, `fix/`, `docs/`, or `chore/`. diff --git a/examples/README.md b/examples/README.md index 3cc41610a..6ac25b01b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -9,8 +9,8 @@ This catalog highlights the examples shipped with Agent-lightning. | [calc_x](./calc_x) | VERL-powered math reasoning agent training that uses AutoGen with an MCP calculator tool. | [![calc_x workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-calc-x.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-calc-x.yml) | | [claude_code](./claude_code) | Claude Code SWE-bench harness that records Agent-lightning traces across Anthropic, vLLM, and OpenAI-compatible backends. | [![claude_code workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-claude-code.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-claude-code.yml) | | [minimal](./minimal) | Bite-sized programs that demonstrate how individual Agent-lightning building blocks behave in isolation. | [![minimal workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml) | -| [rag](./rag) | Retrieval-Augmented Generation pipeline targeting the MuSiQue dataset with Wikipedia retrieval. | **Unmaintained** — last verified with Agent-lightning v0.1.1 | -| [search_r1](./search_r1) | Framework-free Search-R1 reinforcement learning training workflow with a retrieval backend. | **Unmaintained** — last verified with Agent-lightning v0.1.2 | +| [rag](./rag) | Retrieval-Augmented Generation pipeline targeting the MuSiQue dataset with Wikipedia retrieval. | [![rag workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-rag.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml) | +| [search_r1](./search_r1) | Framework-free Search-R1 reinforcement learning training workflow with a retrieval backend. | **Last verified with Agent-lightning v0.1.2** | | [spider](./spider) | Text-to-SQL reinforcement learning training on the Spider dataset using LangGraph. | [![spider workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-spider.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-spider.yml) | | [tinker](./tinker) | Reinforcement learning with Tinker as the backend training service. | [![tinker workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-tinker.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-tinker.yml) | | [unsloth](./unsloth) | Supervised fine-tuning example powered by Unsloth with 4-bit quantization and LoRA. | [![unsloth workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/badge-unsloth.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-unsloth.yml) | diff --git a/examples/rag/README.md b/examples/rag/README.md index 205b11589..fc54d120e 100644 --- a/examples/rag/README.md +++ b/examples/rag/README.md @@ -1,5 +1,7 @@ # RAG Agent Example +[![rag workflow status](https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml/badge.svg)](https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml) + This example demonstrates training a Retrieval-Augmented Generation (RAG) agent using Agent-Lightning with retrieval capabilities. The agent answers multi-hop questions from a tiny MuSiQue dataset by retrieving and reasoning over Wikipedia passages. ## Overview From c51bdfa49d4663ebd673de3690ad466c1011dc2d Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 12:13:33 +0800 Subject: [PATCH 5/7] refine AGENTS.md --- AGENTS.md | 42 +++++++++++++++++++++--------------------- CLAUDE.md | 1 + 2 files changed, 22 insertions(+), 21 deletions(-) create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 008401c23..334f6bc21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,36 +1,36 @@ # Repository Guidelines ## Architecture Overview -Agent Lightning loops through stages: runner and tracer emit spans, LightningStore (`agentlightning/store/`) synchronizes them, and algorithms in `agentlightning/algorithm/` learn from the traces. +Agent Lightning runs through a continuous loop: runners and tracers emit spans, `LightningStore` (`agentlightning/store/`) keeps them synchronized, and algorithms in `agentlightning/algorithm/` consume those traces to improve behavior. ## Project Structure & Module Organization -- `agentlightning/`: adapters, runner/execution stack, trainer, tracer, reward logic, `agl` CLI. -- `docs/` & `examples/`: documentation (assets in `docs/assets/`, nav in `mkdocs.yml`) plus runnable workflows whose READMEs link to their how-to guides. `docs/how-to` contains step-by-step guides for accomplishing a specific task; `docs/tutorials` contains conceptual walkthroughs for components or features. -- `dashboard/`, `scripts/`, `tests/`: UI bundles, automation for releases/datasets/CI, and coverage mirrors of the runtime tree—document download steps instead of committing binaries. +- `agentlightning/`: adapters, execution stack, training loop, tracer, reward logic, and the `agl` CLI. +- `docs/` & `examples/`: narrative and procedural docs (assets in `docs/assets/`, navigation in `mkdocs.yml`) plus runnable workflows whose READMEs point to their companion how-to guides. `docs/how-to` covers task-focused instructions, while `docs/tutorials` explains concepts and subsystems. +- `dashboard/`, `scripts/`, `tests/`: UI bundles, release/dataset/CI automation, and mirrored coverage of the runtime tree. Record download steps rather than committing binaries. ## Build, Test, and Development Commands -- `uv sync --group dev` — install tooling once. -- `uv run --no-sync pytest -v` — run suites; add a path or `-k expr` for targeted loops. -- `uv run --no-sync pyright` — static analysis aligned with CI. -- `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` and `uv run --no-sync mkdocs build --strict` — formatting/lint hooks plus doc validation. -Commit the refreshed `uv.lock` whenever dependencies move and note optional groups (VERL, APO, GPU) in PRs. +- `uv sync --group dev` — provision tooling once per environment. +- `uv run --no-sync pytest -v` — execute the full suite; add a path or `-k expr` to narrow the run. +- `uv run --no-sync pyright` — enforce static typing parity with CI. +- `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` and `uv run --no-sync mkdocs build --strict` — keep formatting tidy and documentation valid. +Always commit the refreshed `uv.lock` when dependencies shift, and mention optional groups (VERL, APO, GPU) in PR notes. ## Coding Style & Naming Conventions -- Stay compatible with `requires-python >= 3.10`, use 4-space indentation, 120-character lines, and formatter-managed diffs (Black + isort, profile `black`). `snake_case` for modules/functions/variables, `PascalCase` for classes and React components, and lowercase-hyphenated CLI flags, branch names and TypeScript files. -- Keep type hints exhaustive (pyright enforced) and reuse dataclasses/Pydantic models from `agentlightning.types`. -- Use Google-style docstrings for new modules or public methods, keeping descriptions short and avoiding redundant type annotations. Use `[][]` syntax for cross-references. +- Target `requires-python >= 3.10`, four-space indentation, 120-character lines, and formatter-owned diffs (Black + isort, `black` profile). Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. +- Maintain exhaustive type hints (pyright enforces them) and prefer shared dataclasses or Pydantic models from `agentlightning.types`. +- Author Google-style docstrings for new modules or public methods—succinct descriptions, no redundant type info, no redundant `Key features/components` bullet points, and `[][]` syntax for cross-references. ## Testing Guidelines -- Mirror runtime directories under `tests/` and align filenames for quick lookup. -- Parametrize pytest cases and apply markers (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so optional suites can be skipped with selectors like `-m "not mongo"` yet still run in CI. -- Favor fixtures; prefer real stores/spans/agents over fakes. Make sure most branches are covered by tests. +- Mirror runtime directories under `tests/` and match filenames for quick traceability. +- Parametrize pytest cases and apply markers (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so optional suites can be skipped via selectors like `-m "not mongo"` yet still exercised in CI. +- Lean on fixtures, favor real stores/spans/agents over mocks, and drive coverage across the majority of branches. ## Example Contributions -- Examples should include a README with smoke instructions so maintainers can validate them quickly. The README should contain a "Included Files" section with a list of the files in the example directory and a description of what each file does. -- The major example files that are meant to be run should be self-contained and have a module-level docstring with CLI usage instructions. Important/complex classes/functions that are meant to be read and learned for users should be documented with their own docstrings and inline comments. -- New examples should include a CI workflow that runs the example and verifies that it runs successfully. The workflow should be named `examples-.yml` and should be placed in the `.github/workflows/` directory. The workflow should be registered in `badge-.yml`, `badge-examples.yml`, and `badge-latest.yml` if necessary. +- Ship each example with a README that includes smoke-test instructions so maintainers can validate quickly. The README must contain an "Included Files" section summarizing every file and its role. +- Keep runnable example modules self-contained with a module-level docstring describing CLI usage. Document important or educational classes/functions with targeted docstrings and inline comments where clarity matters. +- Add a CI workflow per example named `examples-.yml` in `.github/workflows/`. Register it in `badge-.yml`, `badge-examples.yml`, and `badge-latest.yml` when applicable so badges stay accurate. ## Commit & Pull Request Guidelines -- Branch from fresh `main` using `feature/`, `fix/`, `docs/`, or `chore/`. -- Write imperative, scoped commits, reference issues with `Fixes #123`, and rerun pre-commit plus relevant pytest/doc builds before pushing. -- PR descriptions should summarize intent, list verification commands, highlight dependency or docs-navigation updates, and link new docs/examples via `mkdocs.yml` or `examples/README.md`; include logs for dashboard tweaks. +- Branch from a fresh `main` using `feature/`, `fix/`, `docs/`, or `chore/`. +- Write imperative, scoped commits, reference issues with `Fixes #123`, and rerun pre-commit plus the relevant pytest/doc builds before pushing. +- Use PR descriptions to summarize intent, list verification commands, call out dependency or docs-navigation updates, and link new docs/examples via `mkdocs.yml` or `examples/README.md`. Include logs for dashboard changes. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 2dc15783566855f8ca681d78af11fd1d45e52114 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 12:28:02 +0800 Subject: [PATCH 6/7] update contributing.md as well --- AGENTS.md | 4 +++- docs/community/contributing.md | 29 +++++++++++++++++++---------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 334f6bc21..ac42913eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,14 +16,16 @@ Agent Lightning runs through a continuous loop: runners and tracers emit spans, Always commit the refreshed `uv.lock` when dependencies shift, and mention optional groups (VERL, APO, GPU) in PR notes. ## Coding Style & Naming Conventions -- Target `requires-python >= 3.10`, four-space indentation, 120-character lines, and formatter-owned diffs (Black + isort, `black` profile). Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. +- Target `requires-python >= 3.10`, four-space indentation, 120-character lines (restriction can be relaxed for docstrings), and formatter-owned diffs (Black + isort, `black` profile). Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. - Maintain exhaustive type hints (pyright enforces them) and prefer shared dataclasses or Pydantic models from `agentlightning.types`. - Author Google-style docstrings for new modules or public methods—succinct descriptions, no redundant type info, no redundant `Key features/components` bullet points, and `[][]` syntax for cross-references. +- Writing logs is encouraged, especially for long functions with multiple steps and try-except blocks that catch all exceptions. Use `logging.getLogger(__name__)` to get loggers. Distinguish between DEBUG, INFO, WARNING, and ERROR logs. ## Testing Guidelines - Mirror runtime directories under `tests/` and match filenames for quick traceability. - Parametrize pytest cases and apply markers (`openai`, `gpu`, `agentops`, `mongo`, `llmproxy`) so optional suites can be skipped via selectors like `-m "not mongo"` yet still exercised in CI. - Lean on fixtures, favor real stores/spans/agents over mocks, and drive coverage across the majority of branches. +- If an imported module is missing from the environment, check whether `uv sync` has been run with the right groups. Do not make stubs for external dependencies unless necessary. ## Example Contributions - Ship each example with a README that includes smoke-test instructions so maintainers can validate quickly. The README must contain an "Included Files" section summarizing every file and its role. diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 651550a65..83abe06be 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -46,6 +46,7 @@ Bonus points for examples that: - Ship CI or self-test coverage so we know they still work as the core evolves. **Otherwise, we would have to mark the example as unmaintained because we won't be able to test the examples manually before each release.** - Include a [`docs/how-to/`]({{ src("docs/how-to/") }}) guide (or a detailed README if no how-to exists) without duplicating content in multiple places. - Favor simple, dependency-light code over heavy abstractions. +- Ship a README that documents smoke-test instructions and includes an "Included Files" section summarizing every file and its role; keep the runnable module self-contained with a module-level docstring explaining CLI usage, plus targeted docstrings or inline comments for educational functions/classes. !!! warning "Please discuss first" @@ -126,13 +127,13 @@ After `uv sync`, run commands via `uv run ...` (add `--no-sync` once the environ Formatting and linting are enforced through [pre-commit](https://pre-commit.com/). Install once, then run before each push: ```bash -uv run pre-commit install -uv run pre-commit run --all-files --show-diff-on-failure --color=always +uv run --no-sync pre-commit install +uv run --no-sync pre-commit run --all-files --show-diff-on-failure --color=always ``` Once installed, the hooks run automatically on every `git commit`. Running the pre-commit hooks locally keeps CI green and diffs manageable. -### 3. Branch From a Fresh `main` +### 3. Branch from Fresh `main` and Code Start all work from the latest upstream state: @@ -165,20 +166,28 @@ Use lowercase with hyphens, e.g., `feature/async-runner-hooks`. Remember to register new docs in [`mkdocs.yml`]({{ src("mkdocs.yml") }}), add examples to [examples/README]({{ src("examples/README.md") }}), and update the [Examples Catalog](../how-to/examples-catalog.md). +Before you start coding, bring the shared coding conventions with you: + +- Target `requires-python >= 3.10`, four-space indentation, ~120-character lines (docstrings may run longer), and formatter-owned diffs (Black + isort with the `black` profile). +- Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. +- Maintain exhaustive type hints (pyright enforces them), write succinct Google-style docstrings (with `[][]` cross-references). +- Prefer dataclasses or Pydantic models from `agentlightning.types`. +- Log via `logging.getLogger(__name__)` with targeted DEBUG/INFO/WARNING/ERROR calls—especially for long multi-step functions or broad `try/except` blocks. + ### 4. Test and Validate -Most contributions require automated checks. Prefix commands with `uv run` so they use the project environment. +Most contributions require automated checks. Once `uv sync` locks dependencies, prefix commands with `uv run --no-sync ...` so they share the same environment as CI. **Full test suite** ```bash -uv run pytest -v +uv run --no-sync pytest -v ``` **Targeted tests** ```bash -uv run pytest tests/path/to/test_file.py -k test_name +uv run --no-sync pytest tests/path/to/test_file.py -k test_name ``` **Optional/gated tests:** GPU-specific suites or API-dependent tests run automatically when the required hardware or environment variables (such as `OPENAI_API_KEY`) are present. @@ -186,7 +195,7 @@ uv run pytest tests/path/to/test_file.py -k test_name **Static analysis:** ```bash -uv run pyright +uv run --no-sync pyright ``` If you have touched code under `examples/`, you should run the example-specific smoke tests. Each directory includes a README with example-specific smoke tests—run those too. @@ -196,8 +205,8 @@ If you have touched code under `examples/`, you should run the example-specific Keep API references under [docs/reference]({{ src("docs/reference/") }}) up to date. Doc-only changes should still build cleanly: ```bash - uv run mkdocs serve --strict # live reload - uv run mkdocs build --strict # CI-equivalent + uv run --no-sync mkdocs serve --strict # live reload + uv run --no-sync mkdocs build --strict # CI-equivalent ``` `--strict` elevates warnings to errors so you catch issues before CI. @@ -205,7 +214,7 @@ If you have touched code under `examples/`, you should run the example-specific Before opening a PR, double-check the basics: - Run `uv lock` if you changed dependencies. -- Run `uv run pre-commit run --all-files` (hooks installed via `pre-commit install` run automatically on `git commit`, but rerun them if you amended history). +- Run `uv run --no-sync pre-commit run --all-files --show-diff-on-failure` (hooks installed via `pre-commit install` run automatically on `git commit`, but rerun them if you amended history). - Execute the relevant commands from the test list above. - Validate each affected example via its README instructions. From ba49d2796ea59fd89864f246dc9636a0bd14233d Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 6 Dec 2025 12:34:34 +0800 Subject: [PATCH 7/7] update agents.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ac42913eb..4734aab31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ Agent Lightning runs through a continuous loop: runners and tracers emit spans, Always commit the refreshed `uv.lock` when dependencies shift, and mention optional groups (VERL, APO, GPU) in PR notes. ## Coding Style & Naming Conventions -- Target `requires-python >= 3.10`, four-space indentation, 120-character lines (restriction can be relaxed for docstrings), and formatter-owned diffs (Black + isort, `black` profile). Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. +- Target `requires-python >= 3.10`, four-space indentation, 120-character lines (though docstrings may run longer), and formatter-owned diffs (Black + isort, `black` profile). Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and React components; lowercase hyphenation for CLI flags, branch names, and TypeScript filenames. - Maintain exhaustive type hints (pyright enforces them) and prefer shared dataclasses or Pydantic models from `agentlightning.types`. - Author Google-style docstrings for new modules or public methods—succinct descriptions, no redundant type info, no redundant `Key features/components` bullet points, and `[][]` syntax for cross-references. - Writing logs is encouraged, especially for long functions with multiple steps and try-except blocks that catch all exceptions. Use `logging.getLogger(__name__)` to get loggers. Distinguish between DEBUG, INFO, WARNING, and ERROR logs.