PS-9.1 Graduated Autonomy Engine

A risk-based autonomy governance system for AI agent actions. Every action an agent proposes is scored across four independent risk dimensions and routed to one of three autonomy levels -- autonomous execution, user confirmation, or human review -- instead of the usual all-or-nothing choice between "let the agent do anything" and "a human approves every single step."

Live deployment: https://ps91-backend.onrender.com/docs (hosted on Render's free tier -- the first request after a period of inactivity can take ~30-60s to respond while the instance cold-starts; this is expected, not a bug)

Credentials: Username: admin | Password: X3Bsgz0dFHMN9eXYwqSTqovDwPUEFH8rPe-FL8t5vc4

The problem this solves

A fully autonomous agent takes unnecessary risks on high-stakes actions. A fully gated agent requires human approval for trivial decisions and becomes a bottleneck that eliminates the value of automation. This engine scores every action's actual risk and routes it accordingly:

• A read-only query is low risk -> executes autonomously, no human in the loop.
• A single-record update is medium risk -> previewed to a human, executes only on confirmation.
• A bulk delete is high risk -> routed to a full human review queue before anything happens.

Architecture

Untrusted action proposal
        |
        v
  ActionBuilder        (validates/normalizes the proposal)
        |
        v
  RiskScorer            (4 weighted dimensions, see below)
        |
        v
  AutonomyMapper         (risk score -> autonomous | confirm | full_review)
        |
        +--> autonomous  --> ToolGateway executes immediately
        |
        +--> confirm     --> ConfirmationService holds it; a human confirms/rejects via API
        |
        +--> full_review --> ReviewService holds it; a REVIEWER/ADMIN approves/rejects via API
        |
        v
  AuditService           (every decision recorded, in full, regardless of outcome)

Risk dimensions (app/core/risk_engine/dimensions/)

Dimension	Question it answers
Reversibility	Can this action be undone? (read < create < update < delete)
Data scope	How many records/users does this affect?
Regulatory category	Is this action in a regulated domain?
Confidence	How certain is the agent/LLM's proposal?

Each dimension produces a 0-100 score with a human-readable explanation; a weighted sum produces the overall risk score, which AutonomyMapper compares against configured thresholds (backend/policies/) to pick the autonomy level.

Governance components

Component	Responsibility
app/core/actions/	Validates and normalizes untrusted action proposals
app/core/risk_engine/	The 4-dimension risk scorer
app/core/autonomy/	Risk score -> autonomy level mapping
app/core/confirmation/	Holds/resolves medium-risk actions pending user confirmation
app/core/review/	Holds/resolves high-risk actions pending human review
app/core/audit/	Immutable record of every routing decision + risk breakdown
app/core/auth/	JWT auth, Argon2id password hashing, 4-role RBAC (agent/user/reviewer/admin)
app/tools/	ToolGateway + a deterministic in-memory database_tool the engine actually executes against
app/llm/	Real LLM integration (OpenAI or Groq) for POST /agent/chat

Production readiness

This is not a script that runs once on localhost:

• Deployed to a real cloud environment (Render), not localhost -- see the live link above.
• Real persistence: PostgreSQL, not in-memory-only -- schema managed with Alembic migrations (backend/migrations/), verified with a real, disposable Postgres instance in CI (tests/test_postgres_integration.py).
• Concurrent request handling: multi-worker uvicorn (WEB_CONCURRENCY), async FastAPI.
• Real LLM provider connected: Groq (openai/gpt-oss-20b) and OpenAI are both supported through one provider abstraction (app/core/llm/provider.py) -- not mocked in production, only mocked in the test suite.
• Authentication and authorization: JWT bearer tokens, 4 roles, enforced on every protected route -- verified in Swagger with the standard Authorize flow.
• Health and readiness endpoints: GET /health (liveness + static config) and GET /ready (real DB connectivity + migration-state check).
• Structured logging and centralized error handling: every request logged as JSON with a request ID; no unhandled exception ever reaches a client as a raw stack trace.
• 1251 automated tests, including dedicated auth-security and real-Postgres integration suites.
• Docker: backend/Dockerfile + docker-compose.yml build and run the full stack (Postgres + migration + backend) reproducibly.
• AWS Terraform prepared (deploy/aws/) for ECS Fargate + RDS, not yet applied.

Known gap

The bonus "adaptive threshold calibration" (auto-adjusting risk scores based on confirm/reject history) is not implemented. Everything else in the problem statement is.

Running it yourself

Locally

cd backend
python -m venv .venv && source .venv/Scripts/activate   # Windows Git Bash
pip install -r requirements.txt
cp .env.example .env    # fill in real values -- never commit this file
alembic upgrade head
uvicorn app.main:app --reload

Without DATABASE_URL set, the app falls back to in-memory repositories automatically (useful for quick local testing without standing up Postgres).

Docker

docker compose up -d
curl http://localhost:8000/health

Tests

cd backend
pytest -q

API quick reference

Endpoint	Purpose
POST /auth/login	Exchange username/password for a JWT (public)
POST /auth/users	Create a user (ADMIN only)
POST /actions/evaluate	Submit an action proposal through the full governance pipeline
POST /agent/chat	Natural-language endpoint backed by a real LLM; any tool call it proposes goes through the identical governance pipeline
GET /confirmations, POST /confirmations/{id}/confirm | /reject	Medium-risk queue (USER/ADMIN)
GET /reviews, POST /reviews/{id}/approve | /reject	High-risk queue (REVIEWER/ADMIN)
GET /audit, GET /audit/{action_id}	Full audit trail with risk breakdowns
GET /health, GET /ready	Liveness / readiness

Full interactive documentation, with request/response schemas, at /docs.

---

Screenshots and Deployment Evidence

The following screenshots demonstrate the complete functionality of the application. All API functionality screenshots were captured using the live Render deployment, demonstrating that the system is deployed and operational.

---

1. Swagger API Overview

The Swagger /docs page provides an overview of the available API endpoint groups, including:

• Health
• Authentication
• Actions
• Confirmations
• Reviews
• Audit
• Simulation

---

2. Authentication – Authorize Modal

The Swagger Authorize modal demonstrates the configured HTTPBearer authentication mechanism and token input field.

---

3. Low-Risk Action – Autonomous Execution

Endpoint: POST /actions/evaluate

A low-risk read operation is evaluated by the system.

Request

The request demonstrates a low-risk operation submitted for evaluation.

Response

The response demonstrates that the operation was classified as autonomous and executed successfully. The response also includes the risk score and risk breakdown.

{
  "autonomy_level": "autonomous",
  "execution_status": "executed"
}

---

4. Medium-Risk Action – Confirmation Required

Endpoint: POST /actions/evaluate

A medium-risk single-record operation is evaluated by the system.

Request

The request demonstrates a medium-risk update or delete operation.

Response

The response shows that the operation requires explicit confirmation before execution.

{
  "autonomy_level": "confirm",
  "confirmation_id": "..."
}

---

5. Confirming the Action

Endpoint: POST /confirmations/{id}/confirm

The confirmation workflow demonstrates the human-in-the-loop execution process.

Confirmation Request

The request uses the confirmation_id generated during the medium-risk evaluation.

Confirmation Response

The response confirms that the action was successfully executed after explicit human confirmation.

---

6. High-Risk Action – Full Review Required

Endpoint: POST /actions/evaluate

A high-risk bulk operation is evaluated by the system.

Request

The request demonstrates a potentially destructive bulk operation, such as deleting a large number of records.

Response

The response shows that the operation has been escalated for complete human review.

{
  "autonomy_level": "full_review"
}

---

7. Audit Record and Human-Readable Risk Explanation

Endpoint: GET /audit/{action_id}

The audit endpoint provides a complete record of the evaluated action.

Audit Request

The request retrieves the audit information using the generated action_id.

Audit Response

The response includes the audit record along with a human-readable risk explanation, demonstrating why the system assigned a particular risk level and autonomy decision.

---

8. Production Readiness – Health and Readiness Checks

The health and readiness endpoints demonstrate that the deployed application is operational and correctly configured.

Health Check

The health endpoint verifies that the application and its required services are functioning correctly.

Readiness Check

The /ready endpoint confirms production readiness, including:

• Database connectivity
• Successful migrations
• Configured LLM provider

{
  "database": {
    "status": "ok"
  },
  "migrations": {
    "status": "ok"
  },
  "llm_provider": {
    "status": "configured"
  }
}

---

9. Deployment and Test Evidence

The final screenshot provides additional evidence of successful deployment or application testing.

---

Screenshot Summary

Section	Description	Screenshots
1	Swagger API Overview	1
2	HTTPBearer Authorization	1
3	Low-Risk Autonomous Execution	2
4	Medium-Risk Confirmation	2
5	Human Confirmation Workflow	2
6	High-Risk Full Review	2
7	Audit Record and Risk Explanation	2
8	Health and Readiness Checks	2
9	Deployment/Test Evidence	1
Total	Project Evidence Screenshots	15

Note: The API screenshots demonstrate the deployed application's authentication, risk evaluation, autonomous execution, confirmation workflow, full-review escalation, audit logging, health checks, and production readiness.