# AGENTS.md

This file gives coding agents a practical guide for working in this repository.

## Scope
- Repository: `ruranges-py` (Python import: `ruranges_py`, Rust crate: `ruranges-py`)
- Python requirement: `>=3.12`
- Build backend: `maturin` + `PyO3`
- Python wrapper: `ruranges_py/__init__.py`
- Rust source: `src/`
- Python tests: `test/`

## Quick Start
1. Create/activate a Python env with Python 3.12+.
2. Install local dev build:
   - `maturin develop --release`
3. Run tests:
   - `pytest -q`

Python env recipe (macOS/Linux):
```bash
cd ~/code/ruranges-py
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install maturin
maturin develop --release
```

Then verify:
```bash
python -c "import ruranges_py; print(ruranges_py.__version__)"
```

Alternative install path:
- `pip install -e .` (builds via `maturin` backend)

## Project Layout
- `src/`: Rust kernels and Python bindings (`bindings/`, interval algorithms, helpers)
- `ruranges_py/__init__.py`: public Python API and dtype/dispatch logic
- `test/`: Python-level tests
- `Cargo.toml`: Rust crate metadata and dependencies
- `pyproject.toml`: Python packaging, maturin config, version metadata

## Required Checks Before Finishing
Run relevant checks after making changes:
- `cargo fmt --all`
- `cargo clippy --all-targets -- -D warnings`
- `cargo test`
- `pytest -q`

If you changed packaging/build behavior, also run:
- `maturin develop --release`

## Coding Rules
- Keep public Python API stable unless explicitly asked to change it.
- Preserve dtype behavior and coercion rules in `ruranges_py/__init__.py`.
- Prefer minimal allocations and predictable ordering in Rust kernels.
- Avoid unnecessary Python-side work inside hot paths handled in Rust.
- Add/update tests for behavior changes (including edge cases and dtype variants).
- Keep changes scoped; do not refactor unrelated modules.

## How `ruranges-py` Is Used with `pyranges1` (`~/code/pyrunges`)
- `pyranges1` depends on `ruranges-py` for performance-critical interval operations.
- For local cross-repo development, install both repos editable from the same env:
  1. In this repo: `cd ~/code/ruranges-py && maturin develop --release`
  2. In pyranges repo: `cd ~/code/pyrunges && pip install -e .`
- Quick smoke test from `~/code/pyrunges`:
  - `python -c "import pyranges1, ruranges_py; print(pyranges1.__name__, ruranges_py.__version__)"`
- When changing APIs in `ruranges-py`, validate call sites in `~/code/pyrunges/pyranges1/methods/` and run its tests.
- Suggested `pyranges1` tests to run after `ruranges-py` changes:
  1. `cd ~/code/pyrunges && pytest --doctest-modules pyranges1/ tests/unit/`
  2. `cd ~/code/pyrunges && pytest tests/`

## Release Hygiene (when applicable)
If preparing release-like changes, update consistently:
- `pyproject.toml` project version
- `Cargo.toml` crate version (if intended for Rust-side release tracking)
- `README.md` usage/docs when API behavior changes
