How GovAI works

GovAI separates what happened (append-only evidence), what policy requires (Rust policy engine), and what operators may do (compliance summary and CI gates). This page describes the implemented flow as of the repository reference implementation.

End-to-end flow#

flowchart LR
  subgraph clients [Clients]
    PY[Python SDK / CLI]
    CI[CI / GitHub Action]
    RT[Runtime integrations]
  end
  subgraph core [Core audit service]
    E[POST /evidence]
    P[policy.rs]
    L[audit_log.jsonl]
    S[GET /compliance-summary]
    B[GET /bundle / verify]

1. Emit evidence — Clients send structured events for a run_id (training registered, evaluation completed, human approval, promotion, etc.).
2. Enforce at write — The Rust service validates schema and policy before appending to the hash-chained ledger.
3. Query decision — GET /compliance-summary projects required evidence and policy into VALID / INVALID / BLOCKED.
4. Gate or export — CI fails on non-VALID verdicts; operators export bundles for auditors and regulators.

Evidence model#

• Event — One recorded fact (typed payload, identifiers, timestamps).
• Run — A logical unit (run_id) grouping events for one model lifecycle attempt.
• Bundle — Exportable set of events plus integrity metadata (aigov.bundle.v1 contract).
• Compliance summary — Authoritative decision derived from evidence + policy_version.

Canonical contract semantics: ../strong-core-contract-note.md.

Policy and determinism#

Policy rules are implemented in Rust for a fixed policy version (policy.rs). For a given evidence set and policy version, the compliance summary is deterministic. GovAI does not use a user-editable rules language in the core path.

Integrity guarantees (core)#

• Append-only log with hash chaining
• Verification endpoints (GET /verify, GET /verify-log, bundle hash routes)
• Optional signing and trust-chain workflows (../trust/immutable-trust-chain.md)

Enterprise layer (optional)#

The same binary may expose JWT-gated /api/* routes (assessments, compliance workflow, team scope) backed by Postgres. These routes do not replace ledger appends or core policy enforcement. See open-source-vs-hosted-vs-enterprise.md and ../../ARCHITECTURE.md.

Integration surfaces#

Related reading#

• Architecture overview
• Developer onboarding flow
• Integration patterns
• Why auditability matters