# Repository Guidelines

## Project Structure & Modules
- Source: `src/exogibbs/` with subpackages `io`, `equilibrium`, `thermo`, `optimize`, `api`, `presets`, `utils` and data files under `src/exogibbs/data/`.
- Tests: `tests/unittests/` organized by domain (e.g., `io/`, `equilibrium/`); files named `*_test.py`.
- Examples and docs: `examples/`, `documents/`.

## Build, Test, and Development
- Install (editable): `python -m pip install -e .` (requires Python >= 3.9). Uses `setuptools` + `setuptools-scm` for versioning.
- Run tests: `pytest tests/unittests` (CI runs this and exports `results/pytest.xml`).
- Optional build: `python -m pip install build && python -m build` (ensure Git tags exist for correct versioning).

## Coding Style & Naming
- Language: Python with type hints where practical.
- Indentation: 4 spaces; keep functions short and focused.
- Naming: modules/functions/variables `snake_case`, classes `CapWords`, constants `UPPER_SNAKE_CASE`.
- Docstrings: concise triple-quoted summaries; prefer argument/return descriptions on public functions.
- Imports: standard lib, third-party, then local; avoid unused imports.

## Testing Guidelines
- Framework: `pytest`.
- Location/pattern: place new tests under `tests/unittests/<area>/`, name `*_test.py` (e.g., `tests/unittests/thermo/new_feature_test.py`).
- Behavior: keep tests deterministic (no network/GPU); use small fixtures and cover edge cases (e.g., parsing, interpolation bounds).
- Goal: maintain/raise coverage of changed code and keep the suite green locally before pushing.

## Commit & Pull Request Guidelines
- Commits: concise, imperative (e.g., "thermo: fix electron parsing"), group related changes; reference issues (`#123`) when applicable.
- PRs: include a clear description, motivation, and testing notes; link issues; add/adjust tests; update data packaging (`MANIFEST.in`) when adding files under `src/exogibbs/data/`.
- CI: PRs to `develop`/`main` must pass the pytest workflow.

## Architecture Overview (Quick)
- `io.load_data`: loads molecule catalogs and JANAF-like tables.
- `thermo.stoichiometry`: builds formula matrices from species names.
- `equilibrium.gibbs`: pads tables and provides JAX-friendly interpolation of h-vectors.
- `optimize.*`: JAX-based core, VJP, and minimization routines.
- `api.chemistry` and `presets/`: typed containers and ready-to-use setups.

