delegation-lab

Implementação de referência do framework Minimum Sufficient Oversight (MSO) do artigo de Azevedo (2026), "Minimal Oversight: Uncertainty-Aware Governance for Delegated AI Systems" (arXiv:2606.15563).

As quantidades em forma fechada do artigo são implementadas como um núcleo funcional puro e expostas por dois adaptadores independentes (um serviço HTTP em FastAPI e uma CLI em Typer). Um simulador de campo médio, usando apenas a stdlib, valida a teoria empiricamente.

Arquitetura — núcleo funcional, casca imperativa

src/delegation_lab/
  domain/            # PURE core: no I/O, no framework deps, all the math
    return_operator.py   # eq. 5, 6  + masking index M*
    allocation.py        # eq. 3, 8  Fisher metric, water-filling, threshold
    dag.py               # eq. 7, 11 effective skill, propagation O(V+E), chain
    capacity.py          # eq. 13,14,16,17 capacity, process entropy, autonomy
  simulation.py      # application layer: mean-field simulator (validates core)
  api/               # adapter: FastAPI HTTP shell (7 endpoints)
  cli.py             # adapter: Typer CLI (6 commands)

O domínio não sabe nada sobre HTTP ou terminais. Os contratos do domínio levantam um ValueError simples; cada adaptador traduz isso para o próprio vocabulário (HTTP 422, código de saída diferente de zero). Você pode adicionar uma terceira casca (worker de fila, notebook) sem tocar no núcleo.

Mapa equação → função

Artigo	Quantidade	Função
eq. 5	Ponto fixo de competência bruta	`return_operator.raw_fixed_point`
eq. 6	Qualidade corrigida	`return_operator.corrected_quality`
—	Índice de mascaramento M*	`return_operator.masking_index`
eq. 3	Métrica de Fisher	`allocation.fisher_metric`
eq. 8	Alocação water-filling	`allocation.governed_allocation`
—	Limiar do corretor K/N	`allocation.corrector_threshold`
eq. 7	Habilidade efetiva (DAG)	`dag.effective_skill`
eq. 11	Teto de cadeia recursiva	`dag.chain_ceiling`
eq. 13	Capacidade de delegação	`capacity.delegation_capacity`
eq. 14	Entropia do processo H(W)	`capacity.process_entropy`
eq. 16	Buffer de autonomia B_eff	`capacity.autonomy_buffer`
eq. 17	Tempo de autonomia T_auto	`capacity.autonomy_time`

Início rápido

uv venv
.\.venv\Scripts\Activate.ps1
uv pip install -e ".[api,cli,dev,viz]"

Rodar a API:

uvicorn delegation_lab.api.main:app --reload   # docs at http://127.0.0.1:8000/docs
# ou:
delegation-lab serve --reload

Rodar a CLI:

delegation-lab masking  --skill 0.8 --catch-rate 0.7
delegation-lab autonomy --ceiling 0.86 --p-min 0.75 --lam 0.02 --entropy 2.3
delegation-lab --help

Portão de qualidade

ruff check . ; ruff format --check .   # lint + annotations (ANN) + format
mypy                                   # strict type checking
pytest                                 # 53 tests

O CI (.github/workflows/ci.yml) roda os três no Python 3.10 / 3.11 / 3.12.

Resultados validados

O estado estacionário simulado bate com o ponto fixo em forma fechada; o tempo de autonomia escala como 1/mu, com inclinação log-log de -1.006 (artigo: -0.99); o water-filling tem pico em sigma = 0.75; a capacidade cresce com o orçamento de revisão.

Exemplos resolvidos reproduzidos

Mascaramento: sigma*_raw = 0.667, sigma*_corr = 0.90, M* = 1.35.
Limiar do corretor: K/N = 0.855 (p_min=0.80, raw=0.55, c=0.65).
Capacidade do processo: H_max = 15 bits (C=0.80, p=0.50, lambda=0.02).
Fluxo semi-real: B_eff = 0.064, T_auto = 5.33.

código — github/franciscds/delegation-lab ↗ artigo — arXiv:2606.15563 ↗