Metadata-Version: 2.4
Name: governed-ai-agent-blueprint
Version: 0.3.1
Summary: Reference architecture for grounded and auditable AI agents
Author: Viames Marino
License-Expression: MIT
Project-URL: Homepage, https://github.com/viames/governed-ai-agent-blueprint
Project-URL: Repository, https://github.com/viames/governed-ai-agent-blueprint
Project-URL: Issues, https://github.com/viames/governed-ai-agent-blueprint/issues
Project-URL: Changelog, https://github.com/viames/governed-ai-agent-blueprint/blob/main/CHANGELOG.md
Keywords: ai,agents,governance,reference-architecture
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Governed AI Agent Blueprint

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

[![CI](https://github.com/viames/governed-ai-agent-blueprint/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/viames/governed-ai-agent-blueprint/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](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

```mermaid
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

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

Minimal usage:

```python
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

```text
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](docs/THREAT_MODEL.md) 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](SECURITY.md).

## License

MIT
