Skip to content

AGENTS.md

Latest commit

 

History

History
171 lines (142 loc) · 8.68 KB

AGENTS.md

File metadata and controls

171 lines (142 loc) · 8.68 KB

AGENTS.md

CONTRIBUTING.md is canonical for public contribution workflow: issues, assignment, pull requests, refactors, changelogs, validation, commits, and DCO. AI_POLICY.md is canonical for public AI-assisted contribution policy.

When working inside nemoguardrails/, also follow nemoguardrails/AGENTS.md for runtime, public-API, and provider-integration rules.

Quick Rules

  • Agent-specific rule: do not submit issues, PRs, or draft PRs through browser automation, the GitHub API, gh, or similar tooling. Draft text for a human to review and submit, following the repo's issue/PR templates so it can be submitted as-is.
  • Do not push branches or prepare public-submission-ready PR materials unless the linked issue is triaged and assigned to the human contributor.
  • Do not implement refactors unless a maintainer has approved the plan and assigned the work.
  • Never edit CHANGELOG.md or CHANGELOG-Colang.md manually.
  • Do not commit secrets, credentials, or sensitive provider data, and do not fabricate results, approvals, or citations. See AI_POLICY.md Safety and Privacy for the canonical list.
  • Do not add generated media, large generated assets, or synthetic datasets without clear provenance and maintainer alignment.
  • Unit tests must not call live LLM or provider services.
  • Do not add license headers manually. Pre-commit handles license insertion.
  • Do not add comments unless explicitly requested; keep existing comments, docstrings, and license headers unless your change makes them inaccurate.
  • Use Poetry for Python commands: poetry run python ..., poetry run pytest ..., poetry run pre-commit ....

Repository Map

  • Main package: nemoguardrails/
  • Tests: tests/ and benchmark/tests (the testpaths in pytest.ini)
  • Schemas and validation snapshots: schemas/
  • Default development branch: develop

Setup

  • Install development dependencies:

    poetry install --with dev

  • Install documentation dependencies when working on docs:

    poetry install --with dev,docs

  • Do not add dependencies to pyproject.toml or update poetry.lock unless the task requires it. For temporary local investigation, use:

    poetry run pip install <package-name>

  • When a dependency change is required, keep it in the narrowest appropriate dependency group or optional extra, add clear compatibility bounds, and avoid moving optional integration dependencies into the default install path.

Validation

Canonical command reference: CONTRIBUTING.md Validation. The table below adds agent-operational diagnosis commands; see CONTRIBUTING.md for shared rows such as tox and package coverage.

Task Command
Run the test suite make test (pytest-xdist parallel; unsets live-provider keys so unit tests cannot reach live services; runs all pytest.ini testpaths)
Focused test make test TEST=path/to/test_file.py::test_name (extra flags via ARGS="-k ... -q")
Serial, deterministic run make test WORKERS=1 (no parallelism, still unsets live keys)
Coverage make test-coverage
Pre-commit hooks poetry run pre-commit run --all-files
Docs check make docs-fern
Ruff diagnosis poetry run ruff check path/to/file.py
Ruff formatting diagnosis poetry run ruff format path/to/file.py
Pyright diagnosis poetry run pyright
Change type Minimum validation
Docs or repository metadata only poetry run pre-commit run --files <changed files>; build docs when rendering, links, examples, or docs configuration may be affected
Runtime bug fix Focused regression test plus pre-commit on changed files; broaden when shared behavior is touched
Public API, config, or Colang behavior Focused tests plus related docs/examples; add broader package tests when compatibility risk is meaningful
Server, streaming, tracing, actions, or generation Targeted tests for the changed path and fallback/unsupported path
Packaging, dependencies, or lockfiles Relevant install/package checks plus pre-commit; keep dependency diffs separate from unrelated changes
  • For PR-ready code changes, pre-commit is the authoritative lint, format, license-header, and type-checking path.
  • Standalone Ruff, Ruff format, and Pyright runs are local diagnosis only; run pre-commit on changed files before handoff and report if it is skipped.
  • make test runs every pytest.ini testpath, so it includes benchmark/tests, not just tests/; scope with TEST=. The default suite needs no network: tests/conftest.py swaps the default FastEmbed model for a deterministic provider, so only real_embeddings-marked tests use the real model.
  • Diagnose isolation flakiness by comparing make test with make test WORKERS=1 (same env-safety, no parallelism); serial/slow markers in pytest.ini are advisory and not enforced by the parallel runner.
  • make test-serial and bare poetry run pytest do NOT unset live-provider keys; prefer make test / make test WORKERS=1 so unit tests cannot reach live services.

Contribution Workflow

  • Follow CONTRIBUTING.md for issue, assignment, PR title, refactor, changelog, validation, commit, and DCO policy.
  • Follow AI_POLICY.md for disclosure, human accountability, safety, and privacy requirements.
  • For non-trivial features, API changes, refactors, or behavior changes without clear maintainer direction (a linked issue that is triaged, assigned to you, and has an agreed approach recorded in the thread), stop at a proposal or implementation plan (an issue comment, or a throwaway PLAN.md PR maintainers can review) rather than implementing.
  • Before preparing PR-shaped work, check for duplicate or in-flight effort with read-only gh (distinct from the no-gh-submission rule above): gh issue view <issue> --comments, gh pr list --state open --search "<issue> in:body", and gh pr list --state open --search "<area keywords>". If an open PR already covers the change, do not prepare a duplicate; if your approach differs materially, surface that difference in the issue draft for a maintainer.
  • If work is exploratory, draft an issue comment with the branch and relevant files instead of opening a PR.
  • Use the Conventional Commit-style titles described in CONTRIBUTING.md.
  • Do not prefix PR titles or commit messages with agent markers, and do not add AI tools or agents as commit co-authors (no Co-Authored-By trailers for AI).

Review Readiness

  • Follow CONTRIBUTING.md for review-readiness policy (CodeRabbit, Greptile, human comments, readiness labels): address or reply to every open review comment before requesting maintainer review, do not resolve reviewers' own threads, and do not self-apply the readiness label.

Code Changes

  • For maintainer-approved refactors, add or update characterization tests before changing subtle behavior; when the existing suite does not cover the refactored code, keep the equivalence check you used to prove behavior is unchanged.

Documentation And Generated Files

  • Update docs when changing user-visible behavior, public APIs, configuration syntax, examples, or installation requirements.
  • For optional integrations, document whether the integration is optional, which extras or packages are required, which API keys or environment variables are expected, and whether the integration uses the default OpenAI-compatible framework path or the LangChain framework.
  • When documenting model or provider examples, state the relevant model type, routing mode, supported modes, and known limitations rather than assuming the example generalizes to every backend.
  • Use current generally-available model IDs in docs/examples (verify against the provider's docs), and do not change shipped default model parameters as a documentation update.
  • Do not hand-edit generated files or lockfiles unless the task explicitly requires regenerating them with project tooling.
  • Put release-note context in issue or PR draft text instead of changelog files.
  • For notebook documentation, follow CONTRIBUTING.md. Do not run build_notebook_docs.py unless explicitly asked; it currently runs broad git staging and pre-commit commands. Use a clean worktree if it must be run.

Review Mode

  • When reviewing a branch, compare against the merge base with develop and inspect tests as well as implementation.
  • Before handing off, run pre-commit first (per Validation, so line locations are stable), then a structured code review (for example codex review or /code-review) with a security pass for auth, input-handling, deserialization, or external-call changes. Treat findings as advisory: verify each against the real code path and loop until clean.