AGENTS.md

Project Purpose

• DEBtool-Python-Interface has two primary goals:
  • Provide Python tooling to interface with MATLAB DEBtool, including template-based generation of required species files:
    • mydata_<species>.m
    • pars_init_<species>.m
    • predict_<species>.m
    • run_<species>.m
  • Implement multitier DEB parameter estimation (individual and higher aggregation levels) based on the published multitier methodology.
• Prefer preserving compatibility with existing example workflows unless explicitly requested otherwise.
• Current status is pre-1.0; prioritize reliability and API clarity to support a near-term major release.

Environment And Command Defaults

• Always run Python commands in the debtoolpyif_dev conda environment.
• Always run tests via conda environment:
  • conda run -n debtoolpyif_dev python -m pytest ...
• If a command uses package imports, prefer:
  • conda run -n debtoolpyif_dev python ...
• If a command needs PYTHONPATH, use:
  • conda run -n debtoolpyif_dev python -m pytest ... with src layout assumptions handled by project config or explicit env var only when needed.

Testing Expectations

• For code changes, run relevant tests first, then broader tests if needed.
• Minimum validation for multitier changes:
  • conda run -n debtoolpyif_dev python -m pytest tests/integration -m integration -q
• When feasible, run:
  • conda run -n debtoolpyif_dev python -m pytest -q
• Keep unit tests fast and isolated from example folders and MATLAB.
• Keep integration tests aligned with the shared example workflow contract under examples/.
• When changing examples/ structure, load_data, create_tier_structure, or DataCollection semantics, review and update both unit and integration tests together.
• See tests/README.md for the detailed testing strategy, current example contract, and planned estimation-test scope.

Code Change Guidelines

• Keep path handling robust and cross-platform (os.path.join or pathlib).
• Avoid introducing breaking API changes without updating:
  • example scripts in examples/
  • integration tests in tests/integration/
• For changes affecting DEBtool generated files, preserve naming and expected DEBtool/add-my-pet conventions unless explicitly requested.
• When generating MATLAB numeric arrays, preserve missing and infinite values as MATLAB-compatible NaN, Inf, and -Inf tokens; do not coerce or drop them.
• Prefer small, targeted patches and keep public constructor signatures explicit.

References

• Multitier paper (canonical link): https://www.sciencedirect.com/science/article/pii/S0304380024001674
• For shared parameter-estimation documentation, prioritize:
  • docs/parameter_estimation/README.md
  • docs/parameter_estimation/MULTITIER_WORKFLOW.md
  • docs/parameter_estimation/DEBTOOL_FILES.md
  • docs/parameter_estimation/DEBTOOL_MULTITIER.md
  • docs/parameter_estimation/TEMPLATE_GENERATION.md
  • docs/parameter_estimation/MULTITIER.md

Output And Reporting

• After changes, report:
  • files modified
  • behavior change summary
  • exact test commands run and pass/fail outcome
• If tests cannot run, state the concrete blocker and next required action.