# Agent-ROI

**Agent-ROI** is a lightweight Python library for adding **guardrails, decision governance, auditability, and ROI reporting** to agentic AI workflows.

It is designed for real production environments — not just demos.

---

## Why Agent-ROI exists

AI agents are easy to demonstrate.  
They are much harder to operate responsibly at scale.

Once an agent works, the real questions begin:

- When should it act automatically vs pause for human review?
- How do we enforce cost and execution limits?
- How do we audit what happened — and why?
- How do we explain the value in plain dollars?

Agent-ROI focuses on these problems.

It does **not** replace an agent framework.  
It wraps existing agent logic with controls, decisioning, and reporting.

---

## What Agent-ROI provides

### Execution guardrails
- Step limits
- Tool call limits
- Cost ceilings
- Optional deterministic execution

### Confidence-based decision routing
- Automatic approval for high-confidence outcomes
- Human-in-the-loop escalation for uncertain or higher-risk actions
- Explicit, explainable decision outcomes

### Immutable audit logging
- Append-only audit events
- Correlation IDs per run
- Hash-chained records for traceability

### ROI-focused reporting
- Executive-readable ROI summaries
- Clear linkage between actions, savings, and risk
- Designed for leadership and governance review

---

## Included example: FinOps cost optimization

Agent-ROI ships with a simple FinOps example that:

- Scans a set of cloud resources
- Identifies cost-saving opportunities
- Categorizes recommendations by risk level
- Enforces cost limits and human approval for higher-risk actions
- Produces an executive-ready ROI report

The example is intentionally practical and deterministic.

---

## Getting started

### Install

```bash
pip install agent-roi
