{"owner":"NVIDIA-NeMo","repo":"Guardrails","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n`CONTRIBUTING.md` is canonical for public contribution workflow: issues,\nassignment, pull requests, refactors, changelogs, validation, commits, and DCO.\n`AI_POLICY.md` is canonical for public AI-assisted contribution policy.\n\nWhen working inside `nemoguardrails/`, also follow `nemoguardrails/AGENTS.md` for\nruntime, public-API, and provider-integration rules.\nWhen working inside `docs/`, also follow `docs/AGENTS.md` for documentation\nauthoring and AI-agent documentation rules.\n\n## Agent Skills\n\nOptional agent skills live under `.agents/skills/` for clients that support\nskill discovery.\n\n## Quick Rules\n\n- Default to drafting issue/PR text for a human to review and submit, following\n  the repo's issue/PR templates so it can be submitted as-is. The agent is not\n  the access-control boundary and does not adjudicate identity: authorization\n  rests with the directing human under `AI_POLICY.md` and with the GitHub\n  credentials in the environment.\n- Open or submit an issue directly (using `gh` or the GitHub API, not browser\n  automation) only when the operator explicitly directs it; a new issue has\n  nothing to pre-check, so no triage or assignment gate applies.\n- Push a branch, or open or submit a PR, directly (using `gh` or the GitHub API,\n  not browser automation) only when the operator explicitly directs it and a\n  read-only API check confirms the linked issue is triaged and assigned to you:\n  its `labels` mark it triaged and its `assignees` include your authenticated\n  login (compare `gh api repos/{owner}/{repo}/issues/{number}` against\n  `gh api user --jq .login`). Otherwise stop at draft text. When submitting,\n  still follow the issue/PR templates, title conventions, DCO sign-off, and\n  review-readiness rules.\n- Opportunistic refactoring in service of an assigned change is welcome: keep\n  it small, local, and within that change's scope. Standalone refactor PRs and\n  broad restructuring (module reshuffles, sweeping renames, architectural\n  overhauls) are maintainer-led; do not implement them without an approved\n  proposal and assignment. See `CONTRIBUTING.md`.\n- Never edit `CHANGELOG.md` or `CHANGELOG-Colang.md` manually.\n- Do not commit secrets, credentials, or sensitive provider data, and do not\n  fabricate results, approvals, or citations. See `AI_POLICY.md` Safety and\n  Privacy for the canonical list.\n- Do not add generated media, large generated assets, or synthetic datasets\n  without clear provenance and maintainer alignment.\n- Unit tests must not call live LLM or provider services.\n- Do not add license headers manually. Pre-commit handles license insertion.\n- Comments are welcome, not banned. When you feel the urge to comment what a\n  block does, first try to make the comment superfluous: extract a function,\n  rename for clarity, or add an assertion for a required state. Reach for a\n  comment when the code cannot carry the meaning: to explain why (rationale,\n  tradeoff, constraint), warn of a consequence, or flag where you are unsure.\n  Keep existing comments, docstrings, and license headers unless your change\n  makes them inaccurate.\n- Use uv for Python commands: `uv run --locked python ...`,\n  `uv run --locked pytest ...`, `uv run --locked pre-commit ...`.\n\n## Repository Map\n\n- Main package: `nemoguardrails/`\n- Tests: `tests/` and `benchmark/tests` (the `testpaths` in `pytest.ini`)\n- Schemas and validation snapshots: `schemas/`\n- Default development branch: `develop`\n\n## Setup\n\n- Install development dependencies:\n\n  ```bash\n  make install\n  ```\n\n- Documentation tooling requires Node.js 22. The Fern CLI version is pinned in\n  `fern/fern.config.json` and invoked through `npx`; no separate Python docs\n  dependency group is required.\n\n- Do not add dependencies to `pyproject.toml` or update `uv.lock` unless the\n  task requires it. For temporary local investigation, use:\n\n  ```bash\n  uv pip install <package-name>\n  ```\n\n- When a dependency change is required, keep it in the narrowest appropriate\n  dependency group or optional extra, add clear compatibility bounds, and avoid\n  moving optional integration dependencies into the default install path.\n\n## Validation\n\nCanonical command reference: `CONTRIBUTING.md` Validation. The table below adds\nagent-operational diagnosis commands; see `CONTRIBUTING.md` for shared rows such\nas package coverage.\n\n| Task | Command |\n| --- | --- |\n| 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) |\n| Focused test | `make test TEST=path/to/test_file.py::test_name` (extra flags via `ARGS=\"-k ... -q\"`) |\n| Serial, deterministic run | `make test WORKERS=1` (no parallelism, still unsets live keys) |\n| Coverage | `make test-coverage` |\n| Pre-commit hooks | `make pre-commit` |\n| Docs check | `make docs-fern` |\n| Ruff diagnosis | `uv run --locked ruff check path/to/file.py` |\n| Ruff formatting diagnosis | `uv run --locked ruff format path/to/file.py` |\n| ty diagnosis | `uv run --locked ty check` |\n\n| Change type | Minimum validation |\n| --- | --- |\n| Docs or repository metadata only | `uv run --locked pre-commit run --files <changed files>`; build docs when rendering, links, examples, or docs configuration may be affected |\n| Runtime bug fix | Focused regression test plus pre-commit on changed files; broaden when shared behavior is touched |\n| Public API, config, or Colang behavior | Focused tests plus related docs/examples; add broader package tests when compatibility risk is meaningful |\n| Server, streaming, tracing, actions, or generation | Targeted tests for the changed path and fallback/unsupported path |\n| Packaging, dependencies, or lockfiles | Relevant install/package checks plus pre-commit; keep dependency diffs separate from unrelated changes |\n\n- For PR-ready code changes, pre-commit is the authoritative lint, format,\n  license-header, and type-checking path.\n- Standalone Ruff, Ruff format, and ty runs are local diagnosis only; run\n  pre-commit on changed files before handoff and report if it is skipped.\n- `make test` runs every `pytest.ini` testpath, so it includes `benchmark/tests`,\n  not just `tests/`; scope with `TEST=`. The default suite needs no network:\n  `tests/conftest.py` swaps the default FastEmbed model for a deterministic\n  provider, so only `real_embeddings`-marked tests use the real model.\n- Diagnose isolation flakiness by comparing `make test` with `make test\n  WORKERS=1` (same env-safety, no parallelism); `serial`/`slow` markers in\n  `pytest.ini` are advisory and not enforced by the parallel runner.\n- `make test-serial` and bare `uv run --locked pytest` do NOT unset live-provider\n  keys; prefer `make test` / `make test WORKERS=1` so unit tests cannot reach\n  live services.\n\n## Contribution Workflow\n\n- Follow `CONTRIBUTING.md` for issue, assignment, PR title, refactor, changelog,\n  validation, commit, and DCO policy.\n- Follow `AI_POLICY.md` for disclosure, human accountability, safety, and\n  privacy requirements.\n- For non-trivial features, API changes, refactors, or behavior changes without\n  clear maintainer direction (a linked issue that is triaged, assigned to you,\n  and has an agreed approach recorded in the thread), stop at a proposal or\n  implementation plan (an issue comment, or a throwaway `PLAN.md` PR maintainers\n  can review) rather than implementing.\n- Before preparing PR-shaped work, check for duplicate or in-flight effort with\n  read-only `gh` (always allowed, independent of the submission rules above):\n  `gh issue view <issue> --comments`, `gh pr list --state open --search \"<issue>\n  in:body\"`, and `gh pr list --state open --search \"<area keywords>\"`. If an open\n  PR already covers the change, do not prepare a duplicate; if your approach\n  differs materially, surface that difference in the issue draft for a maintainer.\n- If work is exploratory, draft an issue comment with the branch and relevant\n  files instead of opening a PR.\n- Use the Conventional Commit-style titles described in `CONTRIBUTING.md`.\n- Do not prefix PR titles or commit messages with agent markers, and do not add\n  AI tools or agents as commit co-authors (no `Co-Authored-By` trailers for AI).\n\n## Review Readiness\n\n- Follow `CONTRIBUTING.md` for review-readiness policy (CodeRabbit, Greptile,\n  human comments, readiness labels): address or reply to every open review comment\n  before requesting maintainer review, do not resolve reviewers' own threads, and\n  do not self-apply the readiness label.\n\n## Code Changes\n\n- For maintainer-approved refactors, add or update characterization tests before\n  changing subtle behavior; when the existing suite does not cover the refactored\n  code, keep the equivalence check you used to prove behavior is unchanged.\n\n## Documentation And Generated Files\n\n- Update docs when changing user-visible behavior, public APIs, configuration\n  syntax, examples, or installation requirements.\n- For optional integrations, document whether the integration is optional, which\n  extras or packages are required, which API keys or environment variables are\n  expected, and whether the integration uses the default OpenAI-compatible\n  framework path or the LangChain framework.\n- When documenting model or provider examples, state the relevant model type,\n  routing mode, supported modes, and known limitations rather than assuming the\n  example generalizes to every backend.\n- Use current generally-available model IDs in docs/examples (verify against the\n  provider's docs), and do not change shipped default model parameters as a\n  documentation update.\n- Do not hand-edit generated files or lockfiles unless the task explicitly\n  requires regenerating them with project tooling.\n- Put release-note context in issue or PR draft text instead of changelog files.\n- For notebook documentation, follow `CONTRIBUTING.md`. Do not run\n  `build_notebook_docs.py` unless explicitly asked; it currently runs broad git\n  staging and pre-commit commands. Use a clean worktree if it must be run.\n\n## Review Mode\n\n- When reviewing a branch, compare against the merge base with `develop` and\n  inspect tests as well as implementation.\n- Before handing off, run pre-commit first (per Validation, so line locations are\n  stable), then a structured code review (for example `codex review` or\n  `/code-review`) with a security pass for auth, input-handling, deserialization,\n  or external-call changes. Treat findings as advisory: verify each against the\n  real code path and loop until clean.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n`CONTRIBUTING.md` is canonical for public contribution workflow: issues,\nassignment, pull requests, refactors, changelogs, validation, commits, and DCO.\n`AI_POLICY.md` is canonical for public AI-assisted contribution policy.\n\nWhen working inside `nemoguardrails/`, also follow `nemoguardrails/AGENTS.md` for\nruntime, public-API, and provider-integration rules.\nWhen working inside `docs/`, also follow `docs/AGENTS.md` for documentation\nauthoring and AI-agent documentation rules.\n\n## Agent Skills\n\nOptional agent skills live under `.agents/skills/` for clients that support\nskill discovery.\n\n## Quick Rules\n\n- Default to drafting issue/PR text for a human to review and submit, following\n  the repo's issue/PR templates so it can be submitted as-is. The agent is not\n  the access-control boundary and does not adjudicate identity: authorization\n  rests with the directing human under `AI_POLICY.md` and with the GitHub\n  credentials in the environment.\n- Open or submit an issue directly (using `gh` or the GitHub API, not browser\n  automation) only when the operator explicitly directs it; a new issue has\n  nothing to pre-check, so no triage or assignment gate applies.\n- Push a branch, or open or submit a PR, directly (using `gh` or the GitHub API,\n  not browser automation) only when the operator explicitly directs it and a\n  read-only API check confirms the linked issue is triaged and assigned to you:\n  its `labels` mark it triaged and its `assignees` include your authenticated\n  login (compare `gh api repos/{owner}/{repo}/issues/{number}` against\n  `gh api user --jq .login`). Otherwise stop at draft text. When submitting,\n  still follow the issue/PR templates, title conventions, DCO sign-off, and\n  review-readiness rules.\n- Opportunistic refactoring in service of an assigned change is welcome: keep\n  it small, local, and within that change's scope. Standalone refactor PRs and\n  broad restructuring (module reshuffles, sweeping renames, architectural\n  overhauls) are maintainer-led; do not implement them without an approved\n  proposal and assignment. See `CONTRIBUTING.md`.\n- Never edit `CHANGELOG.md` or `CHANGELOG-Colang.md` manually.\n- Do not commit secrets, credentials, or sensitive provider data, and do not\n  fabricate results, approvals, or citations. See `AI_POLICY.md` Safety and\n  Privacy for the canonical list.\n- Do not add generated media, large generated assets, or synthetic datasets\n  without clear provenance and maintainer alignment.\n- Unit tests must not call live LLM or provider services.\n- Do not add license headers manually. Pre-commit handles license insertion.\n- Comments are welcome, not banned. When you feel the urge to comment what a\n  block does, first try to make the comment superfluous: extract a function,\n  rename for clarity, or add an assertion for a required state. Reach for a\n  comment when the code cannot carry the meaning: to explain why (rationale,\n  tradeoff, constraint), warn of a consequence, or flag where you are unsure.\n  Keep existing comments, docstrings, and license headers unless your change\n  makes them inaccurate.\n- Use uv for Python commands: `uv run --locked python ...`,\n  `uv run --locked pytest ...`, `uv run --locked pre-commit ...`.\n\n## Repository Map\n\n- Main package: `nemoguardrails/`\n- Tests: `tests/` and `benchmark/tests` (the `testpaths` in `pytest.ini`)\n- Schemas and validation snapshots: `schemas/`\n- Default development branch: `develop`\n\n## Setup\n\n- Install development dependencies:\n\n  ```bash\n  make install\n  ```\n\n- Documentation tooling requires Node.js 22. The Fern CLI version is pinned in\n  `fern/fern.config.json` and invoked through `npx`; no separate Python docs\n  dependency group is required.\n\n- Do not add dependencies to `pyproject.toml` or update `uv.lock` unless the\n  task requires it. For temporary local investigation, use:\n\n  ```bash\n  uv pip install <package-name>\n  ```\n\n- When a dependency change is required, keep it in the narrowest appropriate\n  dependency group or optional extra, add clear compatibility bounds, and avoid\n  moving optional integration dependencies into the default install path.\n\n## Validation\n\nCanonical command reference: `CONTRIBUTING.md` Validation. The table below adds\nagent-operational diagnosis commands; see `CONTRIBUTING.md` for shared rows such\nas package coverage.\n\n| Task | Command |\n| --- | --- |\n| 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) |\n| Focused test | `make test TEST=path/to/test_file.py::test_name` (extra flags via `ARGS=\"-k ... -q\"`) |\n| Serial, deterministic run | `make test WORKERS=1` (no parallelism, still unsets live keys) |\n| Coverage | `make test-coverage` |\n| Pre-commit hooks | `make pre-commit` |\n| Docs check | `make docs-fern` |\n| Ruff diagnosis | `uv run --locked ruff check path/to/file.py` |\n| Ruff formatting diagnosis | `uv run --locked ruff format path/to/file.py` |\n| ty diagnosis | `uv run --locked ty check` |\n\n| Change type | Minimum validation |\n| --- | --- |\n| Docs or repository metadata only | `uv run --locked pre-commit run --files <changed files>`; build docs when rendering, links, examples, or docs configuration may be affected |\n| Runtime bug fix | Focused regression test plus pre-commit on changed files; broaden when shared behavior is touched |\n| Public API, config, or Colang behavior | Focused tests plus related docs/examples; add broader package tests when compatibility risk is meaningful |\n| Server, streaming, tracing, actions, or generation | Targeted tests for the changed path and fallback/unsupported path |\n| Packaging, dependencies, or lockfiles | Relevant install/package checks plus pre-commit; keep dependency diffs separate from unrelated changes |\n\n- For PR-ready code changes, pre-commit is the authoritative lint, format,\n  license-header, and type-checking path.\n- Standalone Ruff, Ruff format, and ty runs are local diagnosis only; run\n  pre-commit on changed files before handoff and report if it is skipped.\n- `make test` runs every `pytest.ini` testpath, so it includes `benchmark/tests`,\n  not just `tests/`; scope with `TEST=`. The default suite needs no network:\n  `tests/conftest.py` swaps the default FastEmbed model for a deterministic\n  provider, so only `real_embeddings`-marked tests use the real model.\n- Diagnose isolation flakiness by comparing `make test` with `make test\n  WORKERS=1` (same env-safety, no parallelism); `serial`/`slow` markers in\n  `pytest.ini` are advisory and not enforced by the parallel runner.\n- `make test-serial` and bare `uv run --locked pytest` do NOT unset live-provider\n  keys; prefer `make test` / `make test WORKERS=1` so unit tests cannot reach\n  live services.\n\n## Contribution Workflow\n\n- Follow `CONTRIBUTING.md` for issue, assignment, PR title, refactor, changelog,\n  validation, commit, and DCO policy.\n- Follow `AI_POLICY.md` for disclosure, human accountability, safety, and\n  privacy requirements.\n- For non-trivial features, API changes, refactors, or behavior changes without\n  clear maintainer direction (a linked issue that is triaged, assigned to you,\n  and has an agreed approach recorded in the thread), stop at a proposal or\n  implementation plan (an issue comment, or a throwaway `PLAN.md` PR maintainers\n  can review) rather than implementing.\n- Before preparing PR-shaped work, check for duplicate or in-flight effort with\n  read-only `gh` (always allowed, independent of the submission rules above):\n  `gh issue view <issue> --comments`, `gh pr list --state open --search \"<issue>\n  in:body\"`, and `gh pr list --state open --search \"<area keywords>\"`. If an open\n  PR already covers the change, do not prepare a duplicate; if your approach\n  differs materially, surface that difference in the issue draft for a maintainer.\n- If work is exploratory, draft an issue comment with the branch and relevant\n  files instead of opening a PR.\n- Use the Conventional Commit-style titles described in `CONTRIBUTING.md`.\n- Do not prefix PR titles or commit messages with agent markers, and do not add\n  AI tools or agents as commit co-authors (no `Co-Authored-By` trailers for AI).\n\n## Review Readiness\n\n- Follow `CONTRIBUTING.md` for review-readiness policy (CodeRabbit, Greptile,\n  human comments, readiness labels): address or reply to every open review comment\n  before requesting maintainer review, do not resolve reviewers' own threads, and\n  do not self-apply the readiness label.\n\n## Code Changes\n\n- For maintainer-approved refactors, add or update characterization tests before\n  changing subtle behavior; when the existing suite does not cover the refactored\n  code, keep the equivalence check you used to prove behavior is unchanged.\n\n## Documentation And Generated Files\n\n- Update docs when changing user-visible behavior, public APIs, configuration\n  syntax, examples, or installation requirements.\n- For optional integrations, document whether the integration is optional, which\n  extras or packages are required, which API keys or environment variables are\n  expected, and whether the integration uses the default OpenAI-compatible\n  framework path or the LangChain framework.\n- When documenting model or provider examples, state the relevant model type,\n  routing mode, supported modes, and known limitations rather than assuming the\n  example generalizes to every backend.\n- Use current generally-available model IDs in docs/examples (verify against the\n  provider's docs), and do not change shipped default model parameters as a\n  documentation update.\n- Do not hand-edit generated files or lockfiles unless the task explicitly\n  requires regenerating them with project tooling.\n- Put release-note context in issue or PR draft text instead of changelog files.\n- For notebook documentation, follow `CONTRIBUTING.md`. Do not run\n  `build_notebook_docs.py` unless explicitly asked; it currently runs broad git\n  staging and pre-commit commands. Use a clean worktree if it must be run.\n\n## Review Mode\n\n- When reviewing a branch, compare against the merge base with `develop` and\n  inspect tests as well as implementation.\n- Before handing off, run pre-commit first (per Validation, so line locations are\n  stable), then a structured code review (for example `codex review` or\n  `/code-review`) with a security pass for auth, input-handling, deserialization,\n  or external-call changes. Treat findings as advisory: verify each against the\n  real code path and loop until clean.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n`CONTRIBUTING.md` is canonical for public contribution workflow: issues,\nassignment, pull requests, refactors, changelogs, validation, commits, and DCO.\n`AI_POLICY.md` is canonical for public AI-assisted contribution policy.\n\nWhen working inside `nemoguardrails/`, also follow `nemoguardrails/AGENTS.md` for\nruntime, public-API, and provider-integration rules.\nWhen working inside `docs/`, also follow `docs/AGENTS.md` for documentation\nauthoring and AI-agent documentation rules.\n\n## Agent Skills\n\nOptional agent skills live under `.agents/skills/` for clients that support\nskill discovery.\n\n## Quick Rules\n\n- Default to drafting issue/PR text for a human to review and submit, following\n  the repo's issue/PR templates so it can be submitted as-is. The agent is not\n  the access-control boundary and does not adjudicate identity: authorization\n  rests with the directing human under `AI_POLICY.md` and with the GitHub\n  credentials in the environment.\n- Open or submit an issue directly (using `gh` or the GitHub API, not browser\n  automation) only when the operator explicitly directs it; a new issue has\n  nothing to pre-check, so no triage or assignment gate applies.\n- Push a branch, or open or submit a PR, directly (using `gh` or the GitHub API,\n  not browser automation) only when the operator explicitly directs it and a\n  read-only API check confirms the linked issue is triaged and assigned to you:\n  its `labels` mark it triaged and its `assignees` include your authenticated\n  login (compare `gh api repos/{owner}/{repo}/issues/{number}` against\n  `gh api user --jq .login`). Otherwise stop at draft text. When submitting,\n  still follow the issue/PR templates, title conventions, DCO sign-off, and\n  review-readiness rules.\n- Opportunistic refactoring in service of an assigned change is welcome: keep\n  it small, local, and within that change's scope. Standalone refactor PRs and\n  broad restructuring (module reshuffles, sweeping renames, architectural\n  overhauls) are maintainer-led; do not implement them without an approved\n  proposal and assignment. See `CONTRIBUTING.md`.\n- Never edit `CHANGELOG.md` or `CHANGELOG-Colang.md` manually.\n- Do not commit secrets, credentials, or sensitive provider data, and do not\n  fabricate results, approvals, or citations. See `AI_POLICY.md` Safety and\n  Privacy for the canonical list.\n- Do not add generated media, large generated assets, or synthetic datasets\n  without clear provenance and maintainer alignment.\n- Unit tests must not call live LLM or provider services.\n- Do not add license headers manually. Pre-commit handles license insertion.\n- Comments are welcome, not banned. When you feel the urge to comment what a\n  block does, first try to make the comment superfluous: extract a function,\n  rename for clarity, or add an assertion for a required state. Reach for a\n  comment when the code cannot carry the meaning: to explain why (rationale,\n  tradeoff, constraint), warn of a consequence, or flag where you are unsure.\n  Keep existing comments, docstrings, and license headers unless your change\n  makes them inaccurate.\n- Use uv for Python commands: `uv run --locked python ...`,\n  `uv run --locked pytest ...`, `uv run --locked pre-commit ...`.\n\n## Repository Map\n\n- Main package: `nemoguardrails/`\n- Tests: `tests/` and `benchmark/tests` (the `testpaths` in `pytest.ini`)\n- Schemas and validation snapshots: `schemas/`\n- Default development branch: `develop`\n\n## Setup\n\n- Install development dependencies:\n\n  ```bash\n  make install\n  ```\n\n- Documentation tooling requires Node.js 22. The Fern CLI version is pinned in\n  `fern/fern.config.json` and invoked through `npx`; no separate Python docs\n  dependency group is required.\n\n- Do not add dependencies to `pyproject.toml` or update `uv.lock` unless the\n  task requires it. For temporary local investigation, use:\n\n  ```bash\n  uv pip install <package-name>\n  ```\n\n- When a dependency change is required, keep it in the narrowest appropriate\n  dependency group or optional extra, add clear compatibility bounds, and avoid\n  moving optional integration dependencies into the default install path.\n\n## Validation\n\nCanonical command reference: `CONTRIBUTING.md` Validation. The table below adds\nagent-operational diagnosis commands; see `CONTRIBUTING.md` for shared rows such\nas package coverage.\n\n| Task | Command |\n| --- | --- |\n| 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) |\n| Focused test | `make test TEST=path/to/test_file.py::test_name` (extra flags via `ARGS=\"-k ... -q\"`) |\n| Serial, deterministic run | `make test WORKERS=1` (no parallelism, still unsets live keys) |\n| Coverage | `make test-coverage` |\n| Pre-commit hooks | `make pre-commit` |\n| Docs check | `make docs-fern` |\n| Ruff diagnosis | `uv run --locked ruff check path/to/file.py` |\n| Ruff formatting diagnosis | `uv run --locked ruff format path/to/file.py` |\n| ty diagnosis | `uv run --locked ty check` |\n\n| Change type | Minimum validation |\n| --- | --- |\n| Docs or repository metadata only | `uv run --locked pre-commit run --files <changed files>`; build docs when rendering, links, examples, or docs configuration may be affected |\n| Runtime bug fix | Focused regression test plus pre-commit on changed files; broaden when shared behavior is touched |\n| Public API, config, or Colang behavior | Focused tests plus related docs/examples; add broader package tests when compatibility risk is meaningful |\n| Server, streaming, tracing, actions, or generation | Targeted tests for the changed path and fallback/unsupported path |\n| Packaging, dependencies, or lockfiles | Relevant install/package checks plus pre-commit; keep dependency diffs separate from unrelated changes |\n\n- For PR-ready code changes, pre-commit is the authoritative lint, format,\n  license-header, and type-checking path.\n- Standalone Ruff, Ruff format, and ty runs are local diagnosis only; run\n  pre-commit on changed files before handoff and report if it is skipped.\n- `make test` runs every `pytest.ini` testpath, so it includes `benchmark/tests`,\n  not just `tests/`; scope with `TEST=`. The default suite needs no network:\n  `tests/conftest.py` swaps the default FastEmbed model for a deterministic\n  provider, so only `real_embeddings`-marked tests use the real model.\n- Diagnose isolation flakiness by comparing `make test` with `make test\n  WORKERS=1` (same env-safety, no parallelism); `serial`/`slow` markers in\n  `pytest.ini` are advisory and not enforced by the parallel runner.\n- `make test-serial` and bare `uv run --locked pytest` do NOT unset live-provider\n  keys; prefer `make test` / `make test WORKERS=1` so unit tests cannot reach\n  live services.\n\n## Contribution Workflow\n\n- Follow `CONTRIBUTING.md` for issue, assignment, PR title, refactor, changelog,\n  validation, commit, and DCO policy.\n- Follow `AI_POLICY.md` for disclosure, human accountability, safety, and\n  privacy requirements.\n- For non-trivial features, API changes, refactors, or behavior changes without\n  clear maintainer direction (a linked issue that is triaged, assigned to you,\n  and has an agreed approach recorded in the thread), stop at a proposal or\n  implementation plan (an issue comment, or a throwaway `PLAN.md` PR maintainers\n  can review) rather than implementing.\n- Before preparing PR-shaped work, check for duplicate or in-flight effort with\n  read-only `gh` (always allowed, independent of the submission rules above):\n  `gh issue view <issue> --comments`, `gh pr list --state open --search \"<issue>\n  in:body\"`, and `gh pr list --state open --search \"<area keywords>\"`. If an open\n  PR already covers the change, do not prepare a duplicate; if your approach\n  differs materially, surface that difference in the issue draft for a maintainer.\n- If work is exploratory, draft an issue comment with the branch and relevant\n  files instead of opening a PR.\n- Use the Conventional Commit-style titles described in `CONTRIBUTING.md`.\n- Do not prefix PR titles or commit messages with agent markers, and do not add\n  AI tools or agents as commit co-authors (no `Co-Authored-By` trailers for AI).\n\n## Review Readiness\n\n- Follow `CONTRIBUTING.md` for review-readiness policy (CodeRabbit, Greptile,\n  human comments, readiness labels): address or reply to every open review comment\n  before requesting maintainer review, do not resolve reviewers' own threads, and\n  do not self-apply the readiness label.\n\n## Code Changes\n\n- For maintainer-approved refactors, add or update characterization tests before\n  changing subtle behavior; when the existing suite does not cover the refactored\n  code, keep the equivalence check you used to prove behavior is unchanged.\n\n## Documentation And Generated Files\n\n- Update docs when changing user-visible behavior, public APIs, configuration\n  syntax, examples, or installation requirements.\n- For optional integrations, document whether the integration is optional, which\n  extras or packages are required, which API keys or environment variables are\n  expected, and whether the integration uses the default OpenAI-compatible\n  framework path or the LangChain framework.\n- When documenting model or provider examples, state the relevant model type,\n  routing mode, supported modes, and known limitations rather than assuming the\n  example generalizes to every backend.\n- Use current generally-available model IDs in docs/examples (verify against the\n  provider's docs), and do not change shipped default model parameters as a\n  documentation update.\n- Do not hand-edit generated files or lockfiles unless the task explicitly\n  requires regenerating them with project tooling.\n- Put release-note context in issue or PR draft text instead of changelog files.\n- For notebook documentation, follow `CONTRIBUTING.md`. Do not run\n  `build_notebook_docs.py` unless explicitly asked; it currently runs broad git\n  staging and pre-commit commands. Use a clean worktree if it must be run.\n\n## Review Mode\n\n- When reviewing a branch, compare against the merge base with `develop` and\n  inspect tests as well as implementation.\n- Before handing off, run pre-commit first (per Validation, so line locations are\n  stable), then a structured code review (for example `codex review` or\n  `/code-review`) with a security pass for auth, input-handling, deserialization,\n  or external-call changes. Treat findings as advisory: verify each against the\n  real code path and loop until clean.\n","category":"root","tokens":2627}]}