Spaces:
Running on Zero
Running on Zero
File size: 3,487 Bytes
e25024e f254212 e25024e ab1b6fe e25024e ab1b6fe e25024e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 | # 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).
|