| # 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). |
|
|
