Skip to content

Home

Jump to bottom
Allen Byrd edited this page Jun 2, 2026 · 2 revisions

RegRails

Codify federal regulations into machine-readable rules. Wire them into an AI advisor as a deny-by-default, risk-tiered guardrail. Keep the audit trail honest.

RegRails is an open-source, proof-of-concept policy-as-code guardrail for AI-in-the-loop governance in U.S. higher education, plus a React web platform that makes every claim inspectable. It encodes selected provisions of two federal frameworks into rules an AI advisor consults before it answers, and it ships the receipts: a verbatim-text faithfulness gate, a hash-chained decision log, a published rule-to-scenario coverage matrix, and a held-out benchmark.

  • FERPA — 34 CFR Part 99, Subpart D (education-record disclosure)
  • Title IV — a subset of 34 CFR Part 668: Satisfactory Academic Progress (§ 668.34) + student eligibility (§ 668.32)

RegRails is a proof-of-concept, not a compliance product and not legal advice. It encodes selected provisions with verbatim traceability for the rules included, and routes high-stakes determinations to a human. See Frameworks-and-Rules and the methodology/limitations notes for the exact scope boundary.

The thesis

A deterministic engine decides before any LLM speaks.

Every consultation is settled by a deterministic decision engine — no model is in the decision loop. The engine emits a typed GuardrailDecision with an outcome, a risk tier (low / medium / high), and a human_gate_required flag. Only after the decision exists does an LLM render the user-facing wording — and even then it only phrases the reply; it never makes or changes the call.

The dividing line is reversibility:

  • Reversible / low-stakes questions automate. Explaining a rule, an out-of-scope question, an aggregate de-identified release — safe for the AI to handle.
  • Irreversible / high-stakes questions route to a human. Loss of aid eligibility, loan default, a yes/no eligibility determination — the engine refuses to let the AI answer and routes to a human (the financial-aid office), with a tamper-evident record of the decision.

That boundary — what an AI may automate versus what requires human judgment — is the whole point. The engine owns the decision; the model owns the prose; the irreversible calls belong to a person. See The-Guardrail-Engine for exactly how decide() draws that line.

Install + verify in a minute

pip install regrails

regrails check faithfulness     # 37/37 rules verbatim-faithful to the bundled CFR text
regrails decide -q "I defaulted; am I eligible for aid?" --topic aid_status --aid-determination --in-default
regrails export oscal           # OSCAL 1.1.2-shaped catalog of the 37 rules
regrails decide -q "What's Jane's GPA?" --data gpa --format sarif   # SARIF 2.1.0
regrails mcp serve              # MCP server: consult_guardrail / list_rules / check_faithfulness

The engine has no LLM and no secrets, so decide, check, export, and coverage run fully offline. Running the engine with no model at all is the point you can see directly:

regrails decide --query "I defaulted on a loan; am I eligible for aid?" \
  --topic aid_status --aid-determination --in-default
# -> {"outcome": "escalate_human_review", "risk_tier": "high",
#     "human_gate_required": true, "citations_emitted": ["34-CFR-668.32(g)(1)"], ...}

The faithfulness gate is the credibility anchor: 37/37 rules are verbatim-faithful to the bundled CFR text at a token-coverage threshold of 0.85.

Links

Resource Where
Source (GitHub) github.com/Polycentric-Labs/regrails
Package (PyPI) pip install regrails — current version 0.4.0
Held-out eval dataset (HuggingFace) Polycentric-Labs/regrails-eval
Live demo regrails.polycentriclabs.com

Apache-2.0 · Python 3.12+ · uv-managed · 280 tests · ruff + mypy-strict clean.

What's in this wiki

Page What it covers
Home This page — what RegRails is, the thesis, install/verify, links.
Architecture Package modules + responsibilities, the consultation data flow, the React + serverless web platform, and the anti-drift data pipeline.
The-Guardrail-Engine How decide() works: the 7 outcomes, risk tiers, the human-gate rule, the FERPA vs Title IV dispatch, and the intercept logic.
Frameworks-and-Rules FERPA Subpart D + the Title IV subset, the rule schema, and the verbatim-text faithfulness gate.
Rules The 37 encoded rules, searchable, each expandable to its verbatim CFR span and section hash.
Coverage The rule-to-scenario traceability matrix: 31 of 37 rules exercised by 22 golden scenarios, with the 6 gaps named.
Benchmark The held-out eval: 24 independently-authored scenarios across four frontier models, judged by an independent model.
Provenance The hash-chained decision log and audit verify — how any edit, insert, or delete is detected.
Exports The OSCAL 1.1.2-shaped catalog and the SARIF 2.1.0 results document, with their honest scope notes.
MCP server The three agent tools (consult_guardrail, list_rules, check_faithfulness) and the stdio entry points.
GitHub Action The reusable composite action that fails a CI job on block / escalate_human_review and writes SARIF.
Methodology + Limitations The scope boundary, label provenance, known failure modes, and how to reproduce every number.
Roadmap Where the POC goes next (more sections, independent label review).

The four core pages — Home, Architecture, The Guardrail Engine, and Frameworks and Rules — are the authoritative narrative for how the system works. The remaining pages mirror the live web platform's routes (regrails.polycentriclabs.com) and the in-repo docs (docs/METHODOLOGY.md, docs/COVERAGE.md, docs/EVAL.md).

Built by the author of Evidentia

RegRails was built by Allen Byrd, author of Evidentia, an open-source GRC platform. RegRails reuses Evidentia's patterns directly: Pydantic models with extra="forbid", a Jaccard verbatim-faithfulness gate, a string-valued EventAction audit enum, Typer CLI sub-commands, an MCP server, and provider-agnostic, env-file secret loading that never routes a key through tool context.

The thesis in one line: regulations are code, and the primitives for representing them as machine-readable, auditable, AI-consultable artifacts already exist. RegRails is one weekend-sized worked example, extended to two frameworks.

License

Apache-2.0.

Clone this wiki locally