governed-rank Governed Reranking for Any Domain

governed-rank implements a three-step pipeline that runs in O(N log N) time:

Base Scores + Steering Scores + Budget
         |
    [1. Orthogonalize]  →  Remove interference between steering and base
         |
    [2. Protect Edges]  →  Lock the base ranker's most confident decisions
         |
    [3. Project]        →  Constrained isotonic regression for final ranking
         |
    Reranked List + Per-Item Receipts

•Step 1: Orthogonalization

The steering signal often correlates with base scores. Orthogonalization removes this correlation by projecting the steering vector into the null space of the base score direction.

u_perp = u - (u · s / s · s) * s

After orthogonalization, the steering signal can only move items in directions that the base ranker doesn't have an opinion about. It literally cannot hurt accuracy on the dimensions where the base ranker is confident.

•Step 2: Budget-Controlled Edge Protection

The budget parameter (0.0 to 1.0) controls how much of the base ordering is protected. At budget=0.3, the 30% of adjacent-pair ordering decisions where the base ranker has the largest score gaps are locked.

These protected edges become hard constraints. No amount of steering can reverse them. This gives the base ranker team a single knob that controls risk.

•Step 3: Constrained Isotonic Projection

The final step solves a constrained optimization: maximize the policy effect (from the orthogonalized steering signal) subject to the protected ordering constraints.

This uses the Pool Adjacent Violators (PAV) algorithm — the same algorithm used in probability calibration, adapted here for ranking with constraints.

The result is Pareto-optimal: you cannot improve policy compliance without worsening accuracy. This is a mathematical guarantee, not an empirical claim.

The govern() API

from mosaic import govern

result = govern(
    base_scores={"doc1": 0.9, "doc2": 0.8, "doc3": 0.7},
    steering_scores={"doc1": -0.5, "doc2": 0.3, "doc3": 0.8},
    budget=0.3,
)

result.ranked_items   # reranked order
result.receipts       # per-item audit trail

Three arguments. One function call. Runs on any ranked list.

Tutorial Results

Each domain tutorial walks through a complete notebook with real data, showing governed-rank solving an actual steering problem.

Content Moderation

Toxic content is engaging — outrage drives clicks. Naive toxicity penalties kill engagement. The content moderation tutorial shows governed-rank demoting toxic content in the top-10 while preserving ranking quality through orthogonalization.

Fraud Detection

A fraud model ranks transactions by P(fraud), but a $50K wire transfer matters more than a $5 candy purchase. The fraud tutorial builds a tiered gating system (BLOCK / REVIEW / ALLOW) that captures 10x the fraud value in the BLOCK tier compared to the base model.

Fairness (COMPAS)

The COMPAS recidivism dataset is the canonical example of algorithmic bias. The fairness tutorial steers the risk ranking toward demographic parity, improving the adverse impact ratio from ~0.77 to ~0.92 — passing the 4/5ths rule — while preserving ranking quality.

RAG Safety

RAG pipelines retrieve documents by similarity, but adversarial prompt injections score high on similarity too. The RAG safety tutorial uses governed-rank to block all injected documents from the top-10 while retaining 65% of retrieval quality.

Objective Discovery

Before deploying any policy, you need to know which objectives actually help. The objective discovery tutorial evaluates 7 candidate policies via preference lift analysis, finding that quality_depth is the only policy with both high preference lift and diversity gain.

Key Insight

Across all tutorials, governed-rank maintains base ranker accuracy while steering toward the policy objective. The budget knob provides a single, interpretable control for trading off accuracy vs. policy compliance.

The govern() Entry Point

For any domain where you have base scores and a policy signal:

from mosaic import govern

result = govern(
    base_scores=your_base_scores,
    steering_scores=your_policy_signal,
    budget=0.3,
)

Three arguments. Returns a reranked list with per-item receipts. No configuration objects, no calibration step, no training.

Core Modules

Why O(N log N)

The entire pipeline runs in O(N log N) time:

• Sorting: O(N log N)
• Orthogonalization: O(N) — single dot product and vector subtraction
• Edge protection: O(N) — one pass over sorted gaps
• Isotonic projection: O(N) — PAV algorithm is linear
• Total: O(N log N), dominated by the initial sort

For a typical reranking of 100–1000 items, this runs in sub-millisecond time.

Install

pip install governed-rank

99 KB. Minimal dependencies — NumPy core, scikit-learn optional. Python 3.9+.

Quick Start

from mosaic import govern

result = govern(
    base_scores={"doc1": 0.9, "doc2": 0.8, "doc3": 0.7, "doc4": 0.6, "doc5": 0.5},
    steering_scores={"doc1": -0.5, "doc2": 0.3, "doc3": 0.8, "doc4": 0.1, "doc5": 0.6},
    budget=0.3,
)

print(result.ranked_items)   # reranked order
print(result.receipts)       # per-item audit trail

Tutorials

Walk through governed-rank solving real problems with real data:

• Content Moderation — demote toxicity without killing engagement
• Fraud Detection — steer review queues toward high-value fraud
• Fairness — reduce racial bias in COMPAS risk rankings
• RAG Safety — block prompt injection without breaking retrieval
• Objective Discovery — find policies that work before you deploy

Resources

• GitHub: github.com/rdoku/governed-rank
• PyPI: pypi.org/project/governed-rank/
• License: Apache 2.0
• Contact: ronald@haskelabs.com