Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (54 loc) · 2.98 KB

AGENTS.md

File metadata and controls

73 lines (54 loc) · 2.98 KB

AGENTS.md

Contribution rules and conventions for linopy, for humans and AI agents alike.

AI-assisted contributions

You're welcome to help author code, pull requests and issues. But the conversation around a change — PR and issue descriptions, comments and review discussions — is how maintainers and contributors understand each other, so it must stay human and honest. Three rules:

  1. AI-generated content must be marked, preferably with a GitHub note alert at the top of the generated section. Put verbose additional context (logs, generated analysis, long reproductions) in a collapsed <details> block so it doesn't drown the discussion.

    Don't silently mix hand-written and generated prose.

  2. The human writes their own intent. If a pull request or issue is more than a self-documenting bug report, the author must write — or at least rewrite in their own words — their personal intent and motivation by hand, with everything else placed below it. Don't submit an AI-drafted description as your own; the maintainers want the human's voice, concise and to the point.

    Thats why this is important for me (handwritten)

> [!NOTE]
> The following content was generated by AI.

What was implemented and how

<details>
<summary>Full benchmark output</summary>

...verbose content here...

</details>

  3. Conversations are not held through an agent. Posting bare information via an agent — e.g. a log, a benchmark result, a reproduction — is fine as long as it's marked (see rule 1). But discussion itself — replies, answers to questions, review back-and-forth — must be written by the human. Don't let an agent argue, agree or decide on your behalf.

Development workflow

  • Manage the environment with uv and work inside the project virtualenv.
  • Run the test suite with pytest, lint and format with ruff (ruff check --fix .), and type-check with mypy.
  • For the authoritative, detailed commands (extras, coverage, GPU and benchmark runs) see doc/contributing.rst.

Project conventions

  • Branch off master for every change and open pull requests via the GitHub CLI (gh).
  • Write tests for new features and bug fixes under test/ as test_*.py, using linopy's own assertions (assert_linequal, assert_varequal, …) where useful. Run the tests after making changes and make sure they pass.
  • Keep temporary, non-tracked scripts in dev-scripts/.

Architecture in one paragraph

linopy is a linear optimization library built on xarray: variables, constraints and expressions are dimension-labelled N-dimensional structures. Arithmetic on them broadcasts and aligns by dimension and builds expressions lazily, which are turned into the solver format only at solve time. Solvers sit behind an abstract interface with both file-based and direct-API backends. Keep new features consistent with this xarray-based, lazily-evaluated design.