mech_gov — Mechanical Governance for LLM Decisions

A model-agnostic Python framework for enforcing and measuring governance on LLM decisions in high-stakes settings — mechanical gates, governance metrics and a synthetic decision dataset.

Open source by Santander AI Lab. It contrasts a text-only governance regime (R1) with mechanical enforcement (R2) — hard gates, candidate freezing, argument-quality checks, an ambiguity gate, and a commit–reveal entropy step — plus an adaptive regime (R3).

Vendor-neutral by design. Nothing in the core depends on a specific cloud or model provider. Bring your own LLM backend via a small adapter; the framework never needs to know which one you use.

Installation

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
# source .venv/bin/activate

pip install -e .
# optional extras:
#   pip install -e ".[dev]"      # tests
#   pip install -e ".[viz]"      # plotting helpers
#   pip install -e ".[bedrock]"  # AWS Bedrock/SageMaker backends

Requires Python 3.10+.

Quickstart (offline, no credentials)

from mech_gov.data.banking_case import BankingCase, TransactionType
from mech_gov.governance.r2_mechanical import R2Mechanical
from mech_gov.llm.registry import create_llm

llm = create_llm({"provider": "mock"})  # deterministic, offline
case = BankingCase(
    case_id="demo-1",
    transaction_type=TransactionType.CREDIT_APPROVAL,
    risk_score=0.62, completeness=0.55, regulatory_flags=["KYC"],
)
result = R2Mechanical().process_case(case, llm)
print(result.decision.value, "|", result.gates_triggered)

Or run the bundled examples / CLI:

python examples/quickstart_mock.py
python scripts/run_governance.py --regime R2 --provider mock --n 20

Bring your own LLM

The only contract is mech_gov.llm.base.LLMInterface.invoke(...). Three dependency-free ways to supply a backend:

1. Wrap any function (callable) — the recommended way to use a proprietary or internal backend:

from mech_gov.llm.registry import create_llm

def my_backend(system_prompt, user_message, temperature=0.0, max_tokens=2048):
    # call your own SDK / gateway / local model; return the raw text
    ...

llm = create_llm({"provider": "callable", "callable": my_backend})

2. Any OpenAI-compatible HTTP endpoint (openai_compatible) — OpenAI, Azure OpenAI, vLLM, Ollama, Together, LM Studio, or an internal gateway. Uses only the standard library:

export MECH_GOV_LLM_BASE_URL=http://localhost:11434/v1
export MECH_GOV_LLM_MODEL=llama3.1
# export MECH_GOV_LLM_API_KEY=...    # if your endpoint needs one

llm = create_llm({"provider": "openai_compatible"})

3. Optional cloud backends (bedrock, sagemaker) — only available after pip install -e ".[bedrock]". The core install never imports a cloud SDK.

To add your own provider, implement LLMInterface, expose a build(config) -> LLMInterface, and register it in mech_gov.llm.registry (see CONTRIBUTING.md).

Governance regimes

Regime	Module	Behaviour
R1	mech_gov.governance.r1_text_only	Text-only: the LLM interprets the policy with no mechanical enforcement.
R2	mech_gov.governance.r2_mechanical	Mechanical pipeline: hard gates → entropy commit → candidate freezing → argument-quality (I6Q) → ambiguity gate → reveal.
R3	mech_gov.governance.r3_adaptive	Adaptive/exploratory regime.

All regimes implement process_case(case, llm, entropy_seed=None) -> DecisionResult.

Metrics

mech_gov.metrics.governance provides CDL (cosmetic-deadlock rate), DIU (deferral information utilisation), FVS, ESD, FSR, and IPI; mech_gov.metrics.task provides accuracy, macro-F1, MCC, and deferral-rate metrics.

Project layout

mech_gov_framework/
├── pyproject.toml          # packaging; boto3 is an optional [bedrock] extra
├── README.md  LICENSE  CONTRIBUTING.md
├── src/mech_gov/           # the importable package (vendor-neutral core)
│   ├── llm/                # base interface, registry, providers/
│   ├── governance/         # R1, R2, R3, primitives, policy templates
│   ├── metrics/            # governance + task metrics
│   ├── data/               # synthetic banking dataset + bundled config
│   └── experiment/         # runner, ablation, framing/FVS/seed tests
├── scripts/                # generate_dataset.py, run_governance.py
├── examples/               # quickstart_mock.py, custom_provider.py
├── configs/                # models.example.yaml
└── tests/                  # offline tests (mock provider)

CLI

# Generate the synthetic banking dataset to JSONL
python scripts/generate_dataset.py --n 100 --seed 42 --out dataset.jsonl

# Run a regime and print metrics (uses the offline mock by default)
python scripts/run_governance.py --regime R2 --provider mock --n 50

# Use a configured backend
python scripts/run_governance.py --regime R2 \
    --models-config configs/models.example.yaml --model local --n 50

Contributing

Contributions are welcome — see CONTRIBUTING.md for the issue/PR workflow and the Contributor License Agreement (CLA). Please also read our CODE_OF_CONDUCT.md. To report a vulnerability, follow SECURITY.md.

Citation

If you use mech_gov in your research, please cite it (see CITATION.cff):

@software{mech_gov_2026,
  title        = {mech\_gov: Mechanical Governance for LLM Decisions},
  author       = {{Santander AI Lab}},
  year         = {2026},
  version      = {0.1.0},
  url          = {https://github.com/SantanderAI/mech-gov-framework},
  license      = {Apache-2.0}
}

Disclaimer

This software is an open source project from the Santander AI Lab, provided "as is" under its license, without warranties or conditions of any kind. It is not an official Banco Santander product or service, carries no commitment of production support, and does not constitute financial, legal or professional advice.

"Santander" and its logo are registered trademarks of Banco Santander, S.A. The project license does not grant any right to use them beyond factual attribution.

If you believe you have found a security vulnerability, follow our security policy — do not open a public issue. You are responsible for assessing the suitability of this software for your use case and for keeping your own deployments up to date.

License

Apache License 2.0 — see LICENSE and NOTICE. Open source by Santander AI Lab.