Skip to contents

Agent Guidelines for hestia

Source: AGENTS.md

This document provides concise instructions and rules for AI coding assistants working in the hestia repository. For full developer documentation and CI architecture, see CONTRIBUTING.md.

1. Core Architecture & Invariants

  • Package Purpose: hestia fits Bayesian compartmental infection models (such as SIR and multi-compartment hidden Markov variants) from individual-level outcome data. Models are composed from infection-process and observation-process components and fit using Stan via rstan and flexstanr.
  • Stan Backend (flexstanr / rstan):
    • Backend abstraction is provided by imported package flexstanr (>= 0.2.0).
    • Precompiled Stan models live in inst/stan/ (hmm.stan, hmm_cov.stan).
    • R/stanmodels.R and src/stanExports_* are generated by rstantools and must not be edited by hand.
  • Tracked vs. Untracked Artifacts:
    • R/globals.R and man/*.Rd are generated by roxygen2 and are untracked in git.
    • NAMESPACE is tracked in git.
    • src/RcppExports.cpp is generated by Rcpp::compileAttributes() and is tracked in git. Although generated, standard remote / GitHub installers (devtools::install_github(), pak::pak()) only download git-tracked files and do not run attribute compilers prior to R CMD INSTALL; src/RcppExports.cpp is required to register DLL entry points. Synchronization with Stan models is verified automatically by just check-rcpp (in just lint) and unit test tests/testthat/test-rcpp_exports.R.
  • Model Workflow:
    • Infection models are specified with make_infection_model(transmit(...), progress(...))
    • Observation models are specified with make_observation_model(...)
    • Model fitting is executed via run_model(inf_model, obs_model, data, ...)

2. Coding, Error Handling & Documentation Standards

  • Formatting & Linting:
    • Format code with just format (air).
    • Verify lint compliance with just lint (air and lintr).
    • Maximum line length is 100 characters.
  • Roxygen Documentation Standards:
    • Explicit @title and @description: Roxygen blocks must use explicit @title and @description tags rather than relying on automatic inference.
    • @autoglobal: Functions containing non-standard evaluation expressions should be annotated with @autoglobal so roxyglobals generates appropriate symbol declarations in R/globals.R.
    • Internal Helper Functions: Unexported internal functions should be marked with @keywords internal and @noRd to keep code documented in source without generating unused .Rd files.
    • Parameter & Return Documentation: Explicitly state input types/classes using standard roxygen conventions, and describe return structures clearly.
  • Examples:
    • For computationally heavy functions (e.g. run_model()), combine @examplesIf interactive() with \donttest{ ... } so CRAN --as-cran checks and site builds remain fast.
  • Test Suite Conventions:
    • Unit tests live in tests/testthat/.
    • Reusable test helpers and model constructors live in tests/testthat/helper-fixtures.R.
    • Use expect_shape(df, expected_nrow = ..., expected_ncol = ...) for verifying tabular shapes.

3. Common Development Commands & CI Architecture

  • justfile as Single Source of Truth:
    • The justfile serves as the single authoritative reference for all build, validation, doc, and test tasks.
    • CI workflows (.github/workflows/*.yaml) and composite actions (.github/actions/setup-hestia/action.yaml) invoke just <recipe>.

Use just recipes for development workflows:

just format        # Format R code (air)
just lint          # Lint R code (air + lintr)
just docs          # Regenerate man/*.Rd, R/globals.R
just install       # Install package into R library
just test          # Run devtools test suite
just test-fast     # Run test suite stopping on first failure
just coverage      # Check test coverage via covr
just spell         # Run spelling checks
just build         # Build package source tarball (hestia_*.tar.gz)
just check-cran    # Run R CMD check --as-cran on built tarball
just site          # Build pkgdown documentation site
just site-preview  # Preview pkgdown site locally on port 8000