OBLITERATUS/CONTRIBUTING.md

Contributing to OBLITERATUS

Thanks for your interest in contributing. This document covers everything you need to get started.

Development Setup

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

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 55% 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 for linting and formatting:

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:

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:

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/                   # 41 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 for responsible disclosure of security vulnerabilities.

License

By contributing, you agree that your contributions will be licensed under the AGPL-3.0.