Add AGENTS.md file#125
Open
GabyUnalaq wants to merge 3 commits into
Open
Conversation
| ## 2) Non-negotiable rules | ||
|
|
||
| - **Never break existing public API** — must keep semantic alignment with other Ankaios SDKs | ||
| - **100% test coverage is enforced** — every new or changed code path must be covered |
Contributor
There was a problem hiding this comment.
I strongly object this rule. It is stupid to setup such rules for human, as they will probably add shallow tests just to meet the goals (see Goodhart's Law). For LLM this dangerous. They will game the rules.
Write what we really want.
- Tests based on the expected behavior, not the code base
- A test for every corner cases
- A test for every error in every way this error can happen
- If multiple positive result type are possible (like for Option or other enums) at least one test for Some and None results or at least one for every enum variant which could be returned.
If you write the rules like this, while reviewing the result of the LLM, the code coverage might give you a hint, if some case has been missed.
Comment on lines
+24
to
+56
| ## 3) Development environment | ||
|
|
||
| ```sh | ||
| pip install -e ".[dev]" | ||
| ``` | ||
|
|
||
| If tests fail with protobuf errors, re-fetch proto files: | ||
|
|
||
| ```sh | ||
| pip install -e . | ||
| # or for a specific branch: | ||
| ANKAIOS_PROTO_BRANCH=my-feature-branch pip install -e . | ||
| ``` | ||
|
|
||
| ## 4) Run checks | ||
|
|
||
| All checks go through `run_checks.py` (one flag at a time): | ||
|
|
||
| ```sh | ||
| python3 run_checks.py --utest # unit tests | ||
| python3 run_checks.py --cov # coverage (enforces 100%) | ||
| python3 run_checks.py --lint # pylint (enforces 10.0/10) | ||
| python3 run_checks.py --pep8 # PEP 8 style (enforces zero violations) | ||
| ``` | ||
|
|
||
| All commands accept extra arguments that are forwarded to the underlying tool | ||
| (pytest / pylint / pycodestyle), e.g.: | ||
|
|
||
| ```sh | ||
| python3 run_checks.py --utest tests/test_ankaios.py # single file | ||
| python3 run_checks.py --utest -k test_apply_workload # by keyword | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
Why is this information in the AGENTS.md file? This is something which is also useful for humans. I would put it in some file like DEVELOPMENT.md.
Contributor
Author
There was a problem hiding this comment.
This has been moved to DEVELOPMENT.md.
Comment on lines
+57
to
+79
| ## 5) Architecture | ||
|
|
||
| The SDK communicates with the Ankaios agent via a Unix socket at | ||
| `/run/ankaios/control_interface` (two FIFOs: `input` and `output`). Messages | ||
| are length-delimited protobuf (`_control_api` wrapping `_ank_base`). | ||
|
|
||
| `ControlInterface` runs a background reader thread that deserializes incoming | ||
| messages and dispatches them to `Ankaios` via callbacks. `Ankaios` routes | ||
| responses to the correct caller using a request-ID queue. | ||
|
|
||
| `Ankaios` is the primary entry point, typically used as a context manager: | ||
|
|
||
| ```python | ||
| from ankaios_sdk import Ankaios | ||
|
|
||
| with Ankaios() as ankaios: | ||
| state = ankaios.get_state(timeout=5) | ||
| ``` | ||
|
|
||
| Use `_ank_base` (from `ankaios_sdk._protos`) for proto message construction in | ||
| tests. Never import `_pb2` files directly from outside the `_protos` package. | ||
| User-facing code must not expose proto objects. | ||
|
|
Contributor
There was a problem hiding this comment.
Same as above. Maybe ARCHITECTURE.md? Could also go to DEVELOPMENT.md.
Contributor
Author
There was a problem hiding this comment.
This part is Ankaios specific, containing information an Ankaios developer should know already. The reason why is in here is to give an overview to the agent about the basic Control Interface functionality.
Comment on lines
+80
to
+117
| ## 6) Code and test conventions | ||
|
|
||
| - Max line length: 79 chars (pycodestyle default) | ||
| - Every module, class, and public method needs a docstring (follow existing style in `_components/*.py`) | ||
| - Module-level `__all__` is required for all public modules | ||
| - Use `get_logger()` from `utils.py` — not `logging.getLogger` directly | ||
| - Apache-2.0 SPDX license header at the top of every new source file | ||
| - Tests mirror the `ankaios_sdk/_components/` structure | ||
| - Use `unittest.mock.patch` / `MagicMock` for all external dependencies | ||
| - Each test module exports a `generate_test_<thing>()` helper for fixtures | ||
| - Accessing private members in tests (e.g. `ankaios._control_interface`) is normal | ||
|
|
||
| **Typical test setup pattern:** | ||
|
|
||
| ```python | ||
| from unittest.mock import patch, PropertyMock | ||
| from ankaios_sdk import Ankaios, ControlInterfaceState | ||
|
|
||
| def generate_test_ankaios() -> Ankaios: | ||
| with patch("ankaios_sdk.ControlInterface.connect"), patch( | ||
| "ankaios_sdk.ControlInterface.connected", new_callable=PropertyMock | ||
| ) as mock_connected: | ||
| mock_connected.return_value = True | ||
| ankaios = Ankaios() | ||
| ankaios._control_interface._state = ControlInterfaceState.CONNECTED | ||
| return ankaios | ||
| ``` | ||
|
|
||
| ## 7) Exceptions | ||
|
|
||
| All exceptions derive from `AnkaiosException` (see `ankaios_sdk/exceptions.py`). | ||
|
|
||
| ## 8) Helper scripts (`tools/`, all support `--help`) | ||
|
|
||
| - `fetch_protos.sh` — download proto files from a specific Ankaios branch | ||
| - `update_version.sh` — bump SDK, Ankaios, and API versions across the project | ||
| - `generate_docs.sh` — build Sphinx HTML docs into `docs/build/` | ||
| - `install_ankaios.sh` — install Ankaios runtime (release or CI artifacts) |
Contributor
There was a problem hiding this comment.
Also DEVELOPMENT.md.
Contributor
Author
There was a problem hiding this comment.
This has been moved to DEVELOPMENT.md.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This file is intended to provide background into the Python SDK to AI agents like Copilot. It includes general information about the purpose of the SDK and general insight into its development processes.
Definition of Done
The PR shall be merged only if all items mentioned in CONTRIBUTING.md have been followed. In case an item is not applicable as described, please provide a short explanation in the description.