mirror of
https://github.com/elder-plinius/OBLITERATUS.git
synced 2026-08-17 16:37:30 +02:00
131 lines
4.8 KiB
Markdown
131 lines
4.8 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
|
|
python -m pip install --index-url https://download.pytorch.org/whl/cpu "torch>=2.0"
|
|
python - <<'PY' > /tmp/torch-cpu-constraint.txt
|
|
import torch
|
|
print(f"torch=={torch.__version__}")
|
|
PY
|
|
python -m pip install -e ".[dev]" -c /tmp/torch-cpu-constraint.txt
|
|
```
|
|
|
|
This installs CPU PyTorch first, then installs the package in editable mode with pinned development tools while constraining PyTorch to the already-installed CPU build.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
python -m pytest # full suite with coverage
|
|
python -m pytest tests/test_abliterate.py # single file
|
|
python -m pytest -x # stop on first failure
|
|
python -m pytest -k "test_name" # run specific test
|
|
python - <<'PY'
|
|
import obliteratus
|
|
print(getattr(obliteratus, "__version__", "import ok"))
|
|
PY
|
|
python -m obliteratus --help
|
|
```
|
|
|
|
All tests must pass before submitting a PR. Tests are designed to run on CPU without downloading models.
|
|
The mandatory gate currently requires at least 60% repository statement coverage,
|
|
42% branch coverage, 90% coverage of changed executable lines, and 70% statement
|
|
coverage in the device, loader, architecture-profile, CLI, and simulated MLX
|
|
boundary modules. New changes should raise these floors rather than consume the
|
|
existing margin.
|
|
|
|
## Code Style
|
|
|
|
We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
|
|
|
|
```bash
|
|
python -m ruff check --select F obliteratus tests scripts/gemma4_12b_recursive_loop.py
|
|
python -m ruff check --select E501 --statistics obliteratus tests scripts/gemma4_12b_recursive_loop.py # known non-blocking line-length debt report
|
|
```
|
|
|
|
- Line length: 100 characters
|
|
- Target: Python 3.10+
|
|
- The CI Ruff gate enforces all Ruff F rules. E501 line-length findings are reported as known non-blocking legacy debt until the baseline is cleaned up.
|
|
- 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 `python -m pytest`, `python -m build --sdist --wheel`, the import/CLI smoke checks, and the CI Ruff gate
|
|
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)
|
|
- Legacy cleanup PRs may receive missing tests as a one-time maintainer courtesy when the change is already otherwise clean. New changes are expected to include relevant tests and keep the full suite passing.
|
|
|
|
## 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/ # 44 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).
|