minimal-oversight

A governed-delegation analytics toolkit for delegated AI pipelines, centered on the Minimum Sufficient Oversight Principle (MSO).

Companion package to "Minimal Oversight: Uncertainty-Aware Governance for Delegated AI Systems" (Azevedo, 2026).

Documentation | Interactive widgets | Notebooks | Changelog

Current release tag: v0.1.3 / PyPI package: minimal-oversight==0.1.3

Try it on your pipeline

• Live cockpit → crbazevedo.github.io/delegation-lab/app/widgets/cockpit.html. Click ⤓ Import your pipeline and paste your traces, a LangGraph graph, or plain nodes — the cockpit renders your graph and reads masking, bottlenecks, and risk off it live.
• Colab quickstart (button above) → governance for your pipeline in 5 minutes from a trace log. The same trace JSON drives both, so the browser numbers match analyze_pipeline() in Python.

The only data you need to log, per task and per node: outcome (correct before review?) and corrected (correct after review?). That two-column contract is enough to estimate σ_raw, the masking index, and a prioritized fix list.

What it does

Delegated AI systems route uncertain work through pipelines: one model proposes, another reviews, a tool checks, and a gate decides what ships. The design problem is no longer just accuracy; it is trust calibration under uncertainty: how much autonomy to grant, where to place oversight, what quality ceiling the system can sustain, and when intervention becomes necessary.

This package turns those questions into computable quantities:

Question	What you get
Can this pipeline meet my quality target?	Feasibility check: $C_\text{op}$ vs $p_\text{min}$
Where should I place review effort?	Water-filling allocation via the Minimum Sufficient Oversight Principle
Which nodes are most dangerous?	Delegation centrality, masking index, SOTA score
How much autonomy can I safely grant?	Effective autonomy buffer $B_\text{eff}$
When should humans intervene?	Autonomy time $T^*_\text{auto}$ and intervention schedule
What should stop being delegated?	Scope recommendations with coverage constraints

In practical terms, MSO treats oversight as a constrained allocation problem: meet a target quality level with the least sufficient review effort, then place that effort where the model and pipeline state make review most informative.

Interactive companion

A dependency-free, embeddable widget suite under web/ computes the paper's quantities live in the browser — the same equations as this package. Build or load a delegated workflow in the governance cockpit (connector library, editable graph, merge gates, review loops, didactic lessons) — or import your own pipeline from traces or LangGraph — and read feasibility, masking, motifs, and risk off it; press Run to animate task tokens through the graph. Focused explainers cover the masking pathology (M*=1.83), water-filling allocation, the Return Operator run on time, a stochastic-Petri-net token simulation, and a water-filling-vs-baseline benchmark.

cd web && python -m http.server 8000   # then open http://localhost:8000

Grounding is mechanically enforced: web/mso-core.js is a faithful port of minimal_oversight._formulae pinned to the package to within 1e-6 (tests/test_parity.py), and the token simulator's empirical end-to-end success is asserted to match the analytic C_op (tests/test_sim_grounding.py). See the Interactive Companion guide.

Install

pip install minimal-oversight

For a reproducible install of the current release:

pip install minimal-oversight==0.1.3

With framework connectors and visualization:

pip install minimal-oversight[frameworks,viz]

Quick start

From scratch

from minimal_oversight import analyze_pipeline
from minimal_oversight.models import Node, PipelineGraph, AggregationType

gen = Node("generator", sigma_skill=0.55, catch_rate=0.65)
rev = Node("reviewer",  sigma_skill=0.60, catch_rate=0.70)
merge = Node("merge",   sigma_skill=0.55, aggregation=AggregationType.PRODUCT)

pipeline = PipelineGraph([gen, rev, merge])
pipeline.add_edge("generator", "reviewer")
pipeline.add_edge("reviewer", "merge")

report = analyze_pipeline(pipeline, p_min=0.80)
print(report)

From LangGraph

from langgraph.graph import StateGraph, END

graph = StateGraph(MyState)
graph.add_node("researcher", research_fn)
graph.add_node("writer", write_fn)
graph.add_edge("researcher", "writer")
graph.add_edge("writer", END)
graph.set_entry_point("researcher")

report = analyze_pipeline(graph.compile(), p_min=0.80)

From Google ADK

from google.adk import Agent

root = Agent(name="support", model="gemini-2.0-flash", sub_agents=[
    Agent(name="billing", model="gemini-2.0-flash"),
    Agent(name="tech",    model="gemini-2.0-flash"),
])

report = analyze_pipeline(root, p_min=0.80)

From production logs

from minimal_oversight.connectors.traces import from_generic_events, to_workflow_traces

events = [
    {"task_id": "t1", "node_id": "gen", "outcome": 1, "corrected": 1, "timestamp": 0},
    {"task_id": "t1", "node_id": "rev", "outcome": 0, "corrected": 1, "timestamp": 1},
]
traces = to_workflow_traces(from_generic_events(events, corrected_field="corrected"))
report = analyze_pipeline(pipeline, p_min=0.80, traces=traces)

Architecture

                     analyze_pipeline()              Practitioner interface
              ┌──────────────────────────────┐
              │  estimation  capacity        │
              │  topology    allocation      │       Decision modules
              │  intervention  viz           │
              ├──────────────────────────────┤
              │  _formulae.py                │       Paper equations (private)
              ├──────────────────────────────┤
              │  schema   connectors/        │
              │  langgraph  adk  traces      │       Framework integration
              └──────────────────────────────┘

Modules

Module	Purpose
models	Node, PipelineGraph, GovernancePolicy, WorkflowTrace
estimation	Infer $\sigma_\text{raw}$, $\sigma_\text{corr}$, $M^*$, catch rate, drift from logs
capacity	$C_\text{op}$, $B_\text{eff}$, feasibility checks, $H_\text{crit}$
topology	Motif detection, delegation centrality, conditional fragility
allocation	MSO solver, scope selection, governance recommendations
intervention	$T^*_\text{auto}$, intervention schedule, alerts, failure diagnosis
viz	Masking dashboard, autonomy buffer, risk ranking, scope frontier
connectors	LangGraph, Google ADK, LangSmith, generic trace parsers

Notebooks

#	Topic	Shows
01	SDLC pipeline	Fan-out/merge, SOTA placement, masking
02	Customer support	Chain depth, drift, diagnostic differential
03	Topology stress test	All 4 motifs compared
04	LangGraph import	Real StateGraph + conditional edges
05	ADK import	Real Agent objects + session logs
06	Paper validation	All 8 experiments from Section 3

What it is not

• Not an agent framework — it analyzes pipelines, not builds them
• Not a workflow orchestrator — it sits above LangGraph / ADK / CrewAI
• Not just the paper's reproduction code — that's one notebook

It is a governed-delegation analytics and decision-support library, backed by uncertainty-aware and information-theoretic foundations but presented through practitioner questions and one-call analysis.

Citation

@article{azevedo2026minimal,
  title={Minimal Oversight: Uncertainty-Aware Governance for Delegated AI Systems},
  author={Azevedo, Carlos R. B.},
  year={2026}
}