Community API

Functions for saving, loading, and aggregating community research contributions from abliteration runs.

Overview

The community module lets you share anonymized abliteration results as structured JSON files that can be submitted to the OBLITERATUS community results repository. Unlike telemetry (which is automatic and remote), contributions are always explicit and local-only until you choose to share them.

from obliteratus.community import save_contribution, load_contributions, aggregate_results

Key differences from telemetry:

• Includes the public model name (for aggregation by model)
• Saved locally — nothing is sent remotely
• Filename is human-readable (llama2-7b_advanced_20260227_143052.json)
• Includes a config fingerprint for deduplication
• Always explicit opt-in — never automatic

---

save_contribution()

def save_contribution(
    pipeline,
    *,
    model_name: str,
    notes: str = "",
    output_dir: str | Path = "community_results",
    informed_report=None,
) -> Path

Save a contribution record from a completed pipeline run. The record wraps the full OBLITERATUS telemetry schema in a community envelope.

pipeline · AbliterationPipeline · required

A completed AbliterationPipeline (or InformedAbliterationPipeline) instance after run() or run_informed() has returned.

model_name · str · required

The public HuggingFace model ID used in the run (e.g., "meta-llama/Llama-2-7b-chat-hf"). Used as the aggregation key — must be the public ID, not a local path.

notes · str · default: ""

Free-text notes about the run: hardware, dataset, observations, etc.

output_dir · str | Path · default: "community_results"

Directory to write the contribution JSON file. Created automatically if it does not exist.

informed_report · InformedPipelineReport | None · default: "None"

Pass the report from run_informed() to include analysis insights (alignment detection, cone geometry, Ouroboros passes) in the contribution.

Returns Path — absolute path to the saved JSON file.

Filename format: {model_short_name}_{method}_{YYYYMMDD_HHMMSS}.json

---

load_contributions()

def load_contributions(
    contrib_dir: str | Path = "community_results",
) -> list[dict[str, Any]]

Load all contribution records from a directory.

contrib_dir · str | Path · default: "community_results"

Directory containing contribution JSON files. Non-existent directory returns an empty list.

Returns list[dict] — parsed contribution records sorted by timestamp. Each record is a dict with the structure described in Contribution Schema below. Invalid files are skipped with a warning.

---

aggregate_results()

def aggregate_results(
    records: list[dict[str, Any]],
) -> dict[str, dict[str, Any]]

Aggregate contribution records into per-model, per-method summary statistics.

records · list[dict] · required

List of contribution records, e.g., from load_contributions().

Returns nested dict:

{
    "meta-llama/Llama-3.1-8B-Instruct": {
        "advanced": {
            "n_runs": 5,
            "refusal_rate": {"mean": 0.02, "std": 0.01, "n": 5, "min": 0.0, "max": 0.03},
            "perplexity":   {"mean": 8.3,  "std": 0.4,  "n": 5, "min": 7.9, "max": 8.9},
            "coherence":    {"mean": 0.91, "std": 0.02, "n": 5, "min": 0.88, "max": 0.94},
        },
        ...
    },
    ...
}

Metrics included: refusal_rate, perplexity, coherence.

---

Contribution Schema

Each contribution JSON file follows this schema:

{
  "contribution_schema_version": 1,
  "timestamp": "2026-02-27T14:30:52Z",
  "model_name": "meta-llama/Llama-2-7b-chat-hf",
  "config_fingerprint": "a3f2c1d8",
  "notes": "Ran on A100 with default prompts",
  "telemetry": {
    "method": "advanced",
    "method_config": {
      "n_directions": 4,
      "norm_preserve": true,
      "regularization": 0.3,
      "refinement_passes": 2,
      "project_biases": true,
      "use_chat_template": true,
      "use_whitened_svd": false,
      "true_iterative_refinement": false,
      "use_jailbreak_contrast": false,
      "layer_adaptive_strength": true,
      "attention_head_surgery": false,
      "safety_neuron_masking": false,
      "per_expert_directions": false,
      "use_sae_features": false,
      "invert_refusal": false
    },
    "architecture": "llama",
    "num_layers": 32,
    "hidden_size": 4096,
    "total_params": 7000000000,
    "quality_metrics": {
      "refusal_rate": 0.03,
      "perplexity": 8.4,
      "coherence": 0.91,
      "kl_divergence": 0.12
    },
    "stage_durations": {
      "summon": 45.2,
      "probe": 120.8,
      "distill": 3.1,
      "excise": 8.4,
      "verify": 67.9,
      "rebirth": 112.3
    },
    "strong_layers": [14, 15, 16, 17, 18, 19],
    "gpu_memory_gb": 16.3
  }
}

contribution_schema_version · int

Schema version. Currently 1.

timestamp · str

ISO 8601 UTC timestamp of the run.

model_name · str

Public HuggingFace model ID.

config_fingerprint · str

8-character SHA-256 hash of the method config for deduplication.

notes · str

Free-text notes from the contributor.

telemetry · dict

Full pipeline telemetry including method config, architecture info, quality metrics, stage durations, and strong layers.

---

Code Examples

Save After Basic Run

from obliteratus.abliterate import AbliterationPipeline
from obliteratus.community import save_contribution

pipeline = AbliterationPipeline(
    model_name="meta-llama/Llama-3.1-8B-Instruct",
    output_dir="abliterated_llama",
    method="advanced",
)
pipeline.run()

path = save_contribution(
    pipeline,
    model_name="meta-llama/Llama-3.1-8B-Instruct",
    notes="Tested on A100 80GB, default 512 prompt pairs",
    output_dir="community_results",
)
print(f"Saved contribution to: {path}")

from obliteratus.informed_pipeline import InformedAbliterationPipeline
from obliteratus.community import save_contribution

pipeline = InformedAbliterationPipeline(
    model_name="Qwen/Qwen2.5-7B-Instruct",
)
output_path, report = pipeline.run_informed()

path = save_contribution(
    pipeline,
    model_name="Qwen/Qwen2.5-7B-Instruct",
    notes="Analysis-informed run, polyhedral cone detected",
    informed_report=report,  # includes analysis insights
)

from obliteratus.community import load_contributions, aggregate_results

records = load_contributions("community_results")
print(f"Loaded {len(records)} contributions")

aggregated = aggregate_results(records)

for model_name, methods in sorted(aggregated.items()):
    print(f"\n{model_name}")
    for method, stats in sorted(methods.items()):
        rr = stats.get("refusal_rate", {})
        ppl = stats.get("perplexity", {})
        print(
            f"  {method:15s}  n={stats['n_runs']:2d}  "
            f"refusal={rr.get('mean', '?'):.0%}±{rr.get('std', 0):.0%}  "
            f"ppl={ppl.get('mean', '?'):.1f}"
        )

# Save contribution via CLI flag:
obliteratus obliterate meta-llama/Llama-3.1-8B-Instruct \
    --method advanced \
    --contribute \
    --contribute-notes "RTX 4090, default prompts"

# View aggregated community results:
obliteratus aggregate --dir community_results