Skip to main content

Governed AI Blueprint — Policy. Approval. Audit.

Governed AI Agent Blueprint

Install and try · Control flow · Boundaries · PyPI · GitHub repository

A small, executable reference architecture for grounded and auditable AI agents.

CI PyPI License

This repository demonstrates the control boundaries an AI workflow should have before it reaches production. It keeps model generation separate from retrieval, policy decisions, tool approval and audit evidence.

It deliberately uses only the Python standard library. Connectors to a model, vector store, identity provider or durable audit system belong at explicit interfaces instead of being hidden inside the agent loop.

What it demonstrates

  • Answers grounded in retrieved records with machine-checkable citations
  • Tenant and role authorization before records enter model context
  • Refusal when the knowledge base has no relevant evidence
  • Tool allow, deny and human-approval decisions before execution
  • Persistent, expiring and idempotent approval state backed by SQLite
  • Structured audit events without prompts, secrets or full document content
  • Measurable evaluation thresholds independent of a model provider
  • Dependency inversion through a minimal LanguageModel protocol

Control flow

flowchart LR
    U[User request] --> R[Retriever]
    R --> Z[Record authorization]
    Z --> G{Authorized evidence?}
    G -- No --> F[Grounded refusal]
    G -- Yes --> M[Language model]
    M --> C[Citation validation]
    C --> A[Answer]
    U --> P[Tool policy]
    P --> D[Deny]
    P --> H[Persistent human approval]
    P --> T[Allowed tool request]
    R --> E[Audit sink]
    P --> E
    C --> E

The blueprint produces tool decisions; it does not execute tools. That separation prevents a model-generated request from becoming an external side effect without an application-owned authorization step.

The model must return both text and record identifiers. The agent rejects empty citations and identifiers that were not present in the retrieved context. This checks citation provenance; it does not prove that every natural-language claim is entailed by the cited text, which still requires domain-specific evaluation.

Quick start

Install the package from PyPI with Python 3.9 or later:

python3 -m pip install governed-ai-agent-blueprint

The import package is governed_agent. To run the repository's tests, evaluations and example, clone this repository and install it with python3 -m pip install -e ., then run:

python3 -m unittest discover -s tests -v
python3 evals/run.py
python3 evals/run.py --json
python3 examples/incident_assistant.py

Releases use the tag-bound publish-pypi.yml GitHub Actions workflow and the pypi environment with PyPI Trusted Publishing. The workflow tests and builds the tagged source before publishing with a short-lived identity token. GitHub release assets and checksums match the artifacts published to PyPI.

Minimal usage:

from governed_agent import GovernedAgent, InMemoryAuditSink, KnowledgeRecord, ModelOutput
from governed_agent.retrieval import KeywordRetriever


class ExampleModel:
    def complete(self, question: str, context: tuple[KnowledgeRecord, ...]) -> ModelOutput:
        return ModelOutput(
            "The documented recovery target is four hours.",
            (context[0].record_id,),
        )


records = (
    KnowledgeRecord("runbook-7", "The recovery target is four hours."),
)
audit = InMemoryAuditSink()
agent = GovernedAgent(ExampleModel(), KeywordRetriever(records), audit)

answer = agent.answer("What is the recovery target?")
print(answer.text)
print(answer.citations)

Policy model

ToolPolicy classifies tools into three outcomes:

Outcome Meaning
allow The application may continue to its normal authorization checks
approval_required A human or separate approval service must authorize it
deny The request must not execute

The default policy denies unknown tools. This is intentional: adding a tool is a security decision, not a prompt-engineering detail.

SQLiteApprovalWorkflow persists approval requests with an expiration time and idempotency key. The requester cannot approve their own action. An approved request is consumed before a separate executor performs the side effect; this repository deliberately contains no tool executor.

Repository layout

src/governed_agent/   Agent, authorization, approval, policy and audit boundaries
tests/                Deterministic unit tests
evals/                Dataset, measurable thresholds and executable evaluator
examples/             Synthetic incident-assistant workflow
docs/                 Threat model and security boundaries

Reference scenario

examples/incident_assistant.py models an operations assistant using synthetic data. An authorized operator receives a cited runbook answer, proposes a high-severity ticket and obtains approval from a different incident manager. The approval is persisted and consumed, but no external ticket is created.

Project status and provenance

The initial implementation was generated with OpenAI Codex on 25 September 2026 during a GitHub-profile improvement task. It is an AI-assisted reference implementation, not a deployed client system or evidence of a completed client engagement. The repository is public so its code, limitations and subsequent maintainer review remain inspectable.

Production integration checklist

Before adapting this blueprint to production:

  • authenticate the caller and propagate a stable actor identifier;
  • enforce tenant and record authorization inside the retrieval service itself;
  • replace keyword retrieval with a tenant-aware retrieval service;
  • validate citations against the exact context supplied to the model;
  • keep secrets and sensitive document content out of audit payloads;
  • require idempotency keys for mutating tools;
  • execute tools in a separate, least-privilege service;
  • add timeouts, rate limits, cost limits and incident telemetry;
  • evaluate refusal, grounding and authorization behavior on domain-specific cases.

Read the threat model before adapting any component.

Non-goals

This is not a general-purpose agent framework, autonomous tool runner or claim that deterministic wrappers make model output deterministic. It is a compact example of where responsibility should live in a governed system.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

MIT

Metadata

Release files for governed-ai-agent-blueprint 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for governed-ai-agent-blueprint 0.3.2
File Size Uploaded Provenance Actions
governed_ai_agent_blueprint-0.3.2.tar.gz 19.7 kB With provenance Details for governed_ai_agent_blueprint-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for governed-ai-agent-blueprint 0.3.2
File Interpreter ABI Platform Actions
governed_ai_agent_blueprint-0.3.2-py3-none-any.whl Python 3 none any Details for governed_ai_agent_blueprint-0.3.2-py3-none-any.whl

Total release size: 32.0 kB

Release files / governed_ai_agent_blueprint-0.3.2.tar.gz

Download URL governed_ai_agent_blueprint-0.3.2.tar.gz
Size 19.7 kB
Tags Source
SHA-256 checksum
How to use checksums
898323964413588e1d0815dadffe5f3b88ab5b1c77fb2555be61a42f4e32402c
BLAKE2b-256 checksum
How to use checksums
2e6416107bb04a5d2f00ddbbada8fc632349af081e58bdf80886d0375418cf3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / governed_ai_agent_blueprint-0.3.2-py3-none-any.whl

Download URL governed_ai_agent_blueprint-0.3.2-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c2be4e75baf48a3a9fd69df79755f0ae275990e6ce05fb18cf0b071472b82891
BLAKE2b-256 checksum
How to use checksums
67926f3efdaf387a6d2571c2cbb87ebd95ab7efbb3636e1a937e37b89dd493b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for governed-ai-agent-blueprint 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for governed_ai_agent_blueprint-0.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page