mirror of
https://github.com/elder-plinius/OBLITERATUS.git
synced 2026-04-28 22:26:15 +02:00
pliny
114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# 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).
|