Spaces:
Running on Zero
Running on Zero
| # 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). | |