docs: add AGENTS.md with contribution rules for AI agents

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+ bot **closes any PR whose "Describe your change" section has no checked
+ box** (`* [x]`). Fill in the template that ships in
+ `.github/pull_request_template.md` and tick every item that applies before
+ you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+ keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+ updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+ Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+ [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+ [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+ `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+ dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+ explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.