war851/Governed-Agent
The primitives of governance built into a simple agent. A reusable, deterministic pattern: steps, orchestration, a constrained LLM, and persistent logs. Build your own army for almost anything. Sho...
0 stars · 0 forks · HTML
README
type Readme title Governed Agent - an alternative to task-specific model training description The primitives of governance built into a simple agent. A reusable, deterministic pattern: steps, orchestration, a constrained LLM, and persistent logs. Build your own army for almost anything. Shown on an enterprise change-management example. tags governed-agent proof deterministic itil
timestamp 2026-07-22 00:00:00 UTC
Governed Agent The primitives of governance built into a simple agent. A reusable, deterministic pattern: steps, orchestration, a constrained LLM, and persistent logs. Build your own army for almost anything. Shown on an enterprise change-management example.
The orchestrator walks a fixed step sequence; the LLM holds no decision authority. At two steps it reads the free text into structured fields - some copied verbatim from the request (the claimed name, id, and any cited evidence image), some matched to a fixed table vocabulary (the system, the change standard) - and every reply is validated in code before it is trusted. A wrong extraction can change the outcome, but the model can never choose it. Every gate and every decision is pure code over the tables; every prompt, reply, gate, and decision is written to an append-only, hash-chained (tamper-evident) per-request log. A worked implementation of the Governed AI architecture This repo is a concrete, runnable example of the Governed AI architecture - the database-governed pattern where governance lives in versioned config-and-data artifacts and the LLM is stateless compute that decides nothing else. It shows the same architecture holds even in a tiny agent: config (steps, tables) separated from data (the request, the log), a stateless orchestrator building one constrained prompt, and a model confined to bounded extraction. Change management is the example case. The idea
What: an alternative to task-specific model training for well-defined cases. Just as any human can be certified, an LLM can be configured to act within a framework whose results are deterministic - the determinism lives in the framework's code, not the model. Why: training and fine-tuning are complex, costly, and slow. This relies only on the base capabilities of the model (natural-language understanding and classification), stays tiny, and because the framework holds the logic the model is swappable - even a small, agnostic model holds the result. The alternative is not to models, it is to training and retraining them. How: the same way a human passes an exam and stays compliant. We hand the well-defined constraints to the LLM and allow only compliant responses. The one human-like part is reading the request into the framework's terms; every reading is validated against the rules before it is trusted, and where the rules reserve the call for a human it routes there deterministically, by lack of authority, not because it is unsure.
What it proves One free-text request (for example "restart SYS-SHARED-01") is walked through identity, scope, authority, change type, risk, and contract, and resolves to exactly one of five terminals (final outcomes), decided by the tables and not the model: auto_approve | route_client_approval | route_provider_escalation | route_human | decline The LLM appears only at the free-text seams (S3 resolve, S5 classify): it copies identifiers verbatim from the request and matches the system and standard to the fixed table vocabulary (or none). It is never given the evidence-image table, so it cannot invent evidence, and it never chooses the outcome. Everything else is deterministic. See the architecture map. Why change management as the example Change management (ITIL) is a well-defined framework with explicit rules, roles, authorities, and a small set of outcomes - exactly the "well-defined case" the idea targets, and one where a wrong autonomous call is expensive. That makes it a clean, high-stakes showcase for governance by tables and code. The machine is not change-specific; only the tables are. Quickstart npm install npm test
npm test runs the offline gate: every fixture asserted against its expected terminal, each per-request log hash-chained, and a tampered line proven to be caught. No API key needed. To run live across two model families or the extraction fuzz, see the how-to guides below. Documentation
ARCHITECTURE.md - the one map (the S2-S8 flow and the building blocks). How-to - run the mock, run live cross-family, run the fuzz. Explanation - the pieces of the puzzle, modeling notes, simplifications and non-goals, trust boundary, hardening. Reference - generated from source (regenerate with npm run docs:reference; CI fails on drift via npm run docs:check): scenarios, terminals, tables, results. Hand-written: glossary. Evidence - the interactive dashboard.
Author's note This does not replace humans. We still author the framework and validate its sense and value. As AI amplifies impact, it amplifies any error built into the framework - that is the new place of humanity. Machine learning stays valid for many cases. This application only proves that, for most of them, we can work without it.