# Contributing to OBLITERATUS

Thanks for your interest in contributing. This document covers everything you need to get started.

## Development Setup

```bash
git clone https://github.com/elder-plinius/OBLITERATUS.git
cd OBLITERATUS
pip install -e ".[dev]"
```

This installs the package in editable mode with test dependencies (pytest, ruff).

## Running Tests

```bash
pytest                    # full suite (823 tests)
pytest tests/test_abliterate.py  # single file
pytest -x                 # stop on first failure
pytest -k "test_name"     # run specific test
```

All tests must pass before submitting a PR. Tests are designed to run on CPU without downloading models.

## Code Style

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

```bash
ruff check obliteratus/    # lint
ruff format obliteratus/   # format
```

- Line length: 100 characters
- Target: Python 3.10+
- Follow existing patterns in the codebase

## Submitting Changes

1. Fork the repo and create a branch from `main`
2. Make your changes
3. Add or update tests as needed
4. Run `pytest` and `ruff check` -- both must pass
5. Write a clear commit message explaining *why*, not just *what*
6. Open a pull request

## Pull Request Guidelines

- Keep PRs focused -- one feature or fix per PR
- Include a test plan in the PR description
- Link related issues with `Fixes #123` or `Closes #123`
- For new analysis modules, include unit tests with synthetic data (no model downloads)

## Contributing Experiment Results

Beyond code contributions, you can contribute abliteration experiment results to the community dataset used in the research paper. After running abliteration on any model:

```bash
obliteratus obliterate <model> --method advanced --contribute \
    --contribute-notes "Hardware: A100, prompt set: default"
```

This saves a structured JSON file to `community_results/`. To submit your results:

1. Run abliteration with `--contribute` on any model/method combination
2. Open a PR adding your `community_results/*.json` file(s)
3. The aggregation pipeline will incorporate your data into the paper tables

You can preview aggregated results locally:

```bash
obliteratus aggregate --format summary
obliteratus aggregate --format latex --min-runs 3
```

## Project Structure

```
obliteratus/
  abliterate.py          # Core abliteration pipeline
  informed_pipeline.py   # Analysis-informed pipeline
  community.py           # Community contribution system
  cli.py                 # CLI entry point
  config.py              # YAML config loading
  interactive.py         # Interactive mode
  presets.py             # Model presets (47 models)
  runner.py              # Ablation study runner
  analysis/              # 15 analysis modules
  evaluation/            # Metrics and benchmarks
  models/                # Model loading utilities
  reporting/             # Report generation
  strategies/            # Ablation strategies (layer, head, FFN, embedding)
tests/                   # 28 test files
paper/                   # LaTeX paper
examples/                # YAML config examples
```

## Reporting Bugs

Open an issue with:
- What you expected to happen
- What actually happened
- Steps to reproduce
- Model name and hardware (GPU/CPU, VRAM)

## Security Issues

See [SECURITY.md](SECURITY.md) for responsible disclosure of security vulnerabilities.

## License

By contributing, you agree that your contributions will be licensed under the [AGPL-3.0](LICENSE).