allocation

Optimization and policy support. Answers: "Where should I place review effort?" and "What should change?"

Paper reference: Section 1 (MSO, Eq. 2, 8); Section 4 (Algorithm 1, Demonstrations 1-2)

solve_mso

minimal_oversight.allocation.solve_mso(sigma_raw, p_min, alpha_max=1.0)

Solve the Minimum Sufficient Oversight Principle.

Finds the water-filling solution α*(x) that minimizes governance cost subject to the delivery constraint.

Parameters:

Name	Type	Description	Default
sigma_raw	ndarray	Raw competence across scope points.	required
p_min	float	Minimum quality target (delivery constraint).	required
alpha_max	float	Maximum authority at any point.	1.0

Returns:

Type	Description
AllocationResult	AllocationResult with optimal α* and supporting quantities.

Solves the Minimum Sufficient Oversight Principle (MSO): the constrained allocation problem that meets a target quality level with minimum sufficient oversight effort. Under the Bernoulli/Fisher assumptions used in the paper, the solution allocates oversight proportionally to \(\sigma \sqrt{\sigma(1-\sigma)}\), peaking at \(\sigma \approx 0.75\).

from minimal_oversight.allocation import solve_mso
import numpy as np

sigma = np.array([0.30, 0.55, 0.75, 0.90])
result = solve_mso(sigma, p_min=0.60)

for s, a in zip(sigma, result.alpha_star):
    print(f"σ = {s:.2f} → α* = {a:.3f}")
# Peak allocation at σ = 0.75 (highest marginal return of review)

solve_amo() remains available as a backward-compatible alias for older notebooks and user code.

recommend_governance_changes

minimal_oversight.allocation.recommend_governance_changes(pipeline, p_min=0.8, process_entropy=0.0, governance_gap=0.02, eta=10.0, delta=2.0, sigma_0=0.0)

High-level governance recommendations for a pipeline.

Combines capacity analysis, topology, and intervention priority into an ordered list of actionable changes.

The high-level recommendation engine. Combines capacity analysis, topology, and intervention priority into an ordered list of actions.

from minimal_oversight.allocation import recommend_governance_changes

for r in recommend_governance_changes(pipeline, p_min=0.80):
    print(f"{r.priority}. [{r.target_node}] {r.action}")
    print(f"   {r.rationale}")

select_scope

minimal_oversight.allocation.select_scope(sigma_raw, p_min, coverage_min=0.0, alpha_max=1.0)

Endogenous scope selection: which tasks should be delegated?

Without coverage constraint, the optimizer cherry-picks the easiest tasks. With coverage_min, it forces broader delegation.

Parameters:

Name	Type	Description	Default
sigma_raw	ndarray	Raw competence for each candidate task.	required
p_min	float	Quality target per delegated task.	required
coverage_min	float	Minimum fraction of tasks that must be delegated [0, 1].	0.0
alpha_max	float	Maximum authority ceiling.	1.0

Endogenous scope selection (the outer MSO problem): which tasks should be delegated at all? Without a coverage constraint, the optimizer selects the most cost-effective tasks. With coverage_min, it forces broader delegation.

prioritize_intervention

minimal_oversight.allocation.prioritize_intervention(pipeline)

Rank nodes by where additional review effort has the most impact.

Uses the SOTA proxy S(v) = DC(v) × M*(v) × κ(v) when exact sensitivities are unavailable.

Ranks nodes by the SOTA proxy \(S(v) = \text{DC}(v) \times M^*(v) \times \kappa(v)\) when exact sensitivities (\(\partial T_\text{auto}^* / \partial c(v)\)) are unavailable.

Data classes

AllocationResult

Field	Type	Description
alpha_star	np.ndarray	Optimal authority allocation
sigma_raw	np.ndarray	Input competence values
lam	float	Lagrange multiplier (water level)
total_cost	float	Governance cost \(\int \alpha^2 \sqrt{g}\, dx\)
delivery	float	Achieved delivery \(\int \alpha \sigma\, dx\)

ScopeRecommendation

Field	Type	Description
delegated_tasks	list[int]	Indices of tasks to delegate
excluded_tasks	list[int]	Indices to retain/route elsewhere
coverage	float	Fraction delegated
total_cost	float	Governance cost of delegated subset
avg_sigma_delegated	float	Mean competence of delegated tasks
explanation	str	Human-readable summary

GovernanceRecommendation

Field	Type	Description
priority	int	Rank (1 = most urgent)
action	str	What to do
target_node	str \| None	Which node (or None for pipeline-wide)
rationale	str	Why this action matters
expected_impact	str	What improvement to expect