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
pip install -e ".[dev]"

This installs the package in editable mode with test dependencies (pytest, ruff).

Running Tests

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

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:

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

License

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