# Contributing to neuro-scan

Thank you for your interest in contributing!

## Development setup

```bash
git clone https://github.com/XXO47OXX/neuro-scan.git
cd neuro-scan
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Running tests

```bash
# Smoke tests (fast, <10s)
pytest -m smoke

# All tests except slow
pytest -m "not slow"

# Full suite including stress tests
pytest

# With coverage
pytest --cov --cov-report=term-missing
```

## Code style

We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:

```bash
ruff check .
ruff format .
```

Configuration is in `pyproject.toml` (target: Python 3.10, line length: 100).

## Pull request process

1. Fork the repo and create a feature branch
2. Write tests first (TDD encouraged)
3. Ensure `ruff check .` passes
4. Ensure `pytest -m "not slow"` passes
5. Update CHANGELOG.md under `[Unreleased]`
6. Open a PR with the provided template

## Adding a new probe

1. Create `src/neuro_scan/probes/your_probe.py`
2. Subclass `Probe` from `neuro_scan.probes.base`
3. Implement `name`, `description`, `get_samples()`, `get_score_token_ids()`
4. Register in `cli.py` `_load_probe()` builtin_probes dict
5. Add tests in `tests/`

## Adding a new backend

1. Create `src/neuro_scan/backends/your_backend.py`
2. Subclass `Backend` from `neuro_scan.backends.base`
3. Implement all abstract methods: `load()`, `get_total_layers()`, `get_tokenizer()`,
   `forward()`, `forward_with_ablation()`, `forward_with_hidden_states()`,
   `forward_with_attention()`
4. Register in `cli.py` `_load_backend()`
5. Add tests in `tests/test_backends.py`
