Skip to main content

AI agent instructions

The developers sometimes use AI coding agents such as GitHub Copilot and Claude Code to assist in their work. To make this more effective, we supply instructions for this repository in AGENTS.md at the root of the repository. Keep the instructions short and specific to this repository; generic advice makes agents slower and more expensive without making them better.

1 Current agent instructions

2 Agent instructions

Ribasim is a water resources model. The simulation core is written in Julia, models are built with the Ribasim Python package, and there is a QGIS plugin. A model is a TOML config with a GeoPackage database (database.gpkg) of input tables; large input tables and the results are NetCDF files. See the developer docs in docs/dev and the user docs at https://ribasim.org/. Issues and PRs are on https://github.com/Deltares/Ribasim.

2.1 Repository layout

  • core/: Julia package Ribasim, with tests in core/test, core/integration_test and core/regression_test.
  • python/ribasim/: Python package for building, reading and writing models.
  • python/ribasim_api/: Python wrapper around the BMI of the shared library.
  • python/ribasim_testmodels/: test model definitions, written to generated_testmodels/.
  • ribasim_qgis/: QGIS plugin.
  • build/: build scripts for the CLI and shared library.
  • docs/: Quarto docs, published to ribasim.org.
  • utils/: development scripts.
  • models/: local working directory, ignored by git.

2.2 Commands

Use the Pixi tasks from pixi.toml rather than calling tools directly:

pixi run install              # set up all environments
pixi run test-ribasim-core    # Julia unit tests
pixi run test-ribasim-python  # Python tests
pixi run generate-testmodels  # write the test models used by the tests
pixi run codegen              # regenerate the Python schemas from the Julia schemas
pixi run check                # formatting and linting hooks (prek)
pixi run docs                 # preview the docs

The first Julia run in a fresh process spends minutes compiling; that is not a hang. When a change may affect the allocation problems, delete generated_testmodels/ and run pixi run write-allocation-problems to update the reference .lp files in core/test/data/allocation_problems.

2.3 Conventions

  • Julia tests are @testitems in *_test.jl files, run with TestItemRunner. Python tests are test_*.py; tests on models from older schema versions are marked @pytest.mark.regression.
  • Table schemas are defined in Julia. python/ribasim/ribasim/schemas.py and validation.py are generated by pixi run codegen; don’t edit them by hand.
  • A breaking schema change increments __schema_version__ in python/ribasim/ribasim/__init__.py and adds a migration to python/ribasim/ribasim/migrations.py, so older models still load.
  • The root Project.toml is the Julia development environment (--project, used by utils/ scripts); core/Project.toml is the Ribasim package (--project=core).
  • Python API docstrings are rendered in the docs by quartodoc.
  • Avoid allocations and type instabilities in the Julia simulation code; the core is compiled into a shared library.
  • Adding a node type touches Julia, Python, QGIS and the docs; follow docs/dev/addnode.qmd.
  • User-facing changes get an entry in docs/changelog.qmd.
  • Comments explain why, not what.